diff --git a/.gitignore b/.gitignore index 05dd17fe..3c15d90b 100644 --- a/.gitignore +++ b/.gitignore @@ -5,7 +5,7 @@ npm-debug.log* yarn-debug.log* yarn-error.log* lerna-debug.log* -.yarn/install-state.gz +.yarn # Diagnostic reports (https://nodejs.org/api/report.html) report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json diff --git a/packages/react-material-ui/__tests__/AppBar.spec.tsx b/packages/react-material-ui/__tests__/AppBar.spec.tsx index 94322208..9e361ae7 100644 --- a/packages/react-material-ui/__tests__/AppBar.spec.tsx +++ b/packages/react-material-ui/__tests__/AppBar.spec.tsx @@ -5,7 +5,7 @@ import '@testing-library/jest-dom'; import React from 'react'; import { render } from '@testing-library/react'; -import AppBar from '../src/components/AppBar'; +import { AppBar } from '../src/components/AppBar'; describe('AppBar Component', () => { const items = [ diff --git a/packages/react-material-ui/__tests__/AppBarDrawer.spec.tsx b/packages/react-material-ui/__tests__/AppBarDrawer.spec.tsx index 57bd7137..732716d8 100644 --- a/packages/react-material-ui/__tests__/AppBarDrawer.spec.tsx +++ b/packages/react-material-ui/__tests__/AppBarDrawer.spec.tsx @@ -5,7 +5,7 @@ import '@testing-library/jest-dom'; import React from 'react'; import { render } from '@testing-library/react'; -import AppBar from '../src/components/AppBar'; +import { AppBar } from '../src/components/AppBar'; describe('AppBarDrawer Component', () => { const items = [ diff --git a/packages/react-material-ui/__tests__/AppBarMain.spec.tsx b/packages/react-material-ui/__tests__/AppBarMain.spec.tsx index 8a6db09a..07d71336 100644 --- a/packages/react-material-ui/__tests__/AppBarMain.spec.tsx +++ b/packages/react-material-ui/__tests__/AppBarMain.spec.tsx @@ -5,7 +5,7 @@ import '@testing-library/jest-dom'; import React from 'react'; import { render } from '@testing-library/react'; -import AppBar from '../src/components/AppBar'; +import { AppBar } from '../src/components/AppBar'; describe('AppBarMain Component', () => { it('should render correctly', () => { diff --git a/packages/react-material-ui/__tests__/AppBarNav.spec.tsx b/packages/react-material-ui/__tests__/AppBarNav.spec.tsx index 1b1546eb..65cf5e82 100644 --- a/packages/react-material-ui/__tests__/AppBarNav.spec.tsx +++ b/packages/react-material-ui/__tests__/AppBarNav.spec.tsx @@ -5,7 +5,7 @@ import '@testing-library/jest-dom'; import React from 'react'; import { render, fireEvent } from '@testing-library/react'; -import AppBar from '../src/components/AppBar'; +import { AppBar } from '../src/components/AppBar'; describe('AppBar.Nav Component', () => { it('should render correctly', () => { diff --git a/packages/react-material-ui/__tests__/AppBarRoot.spec.tsx b/packages/react-material-ui/__tests__/AppBarRoot.spec.tsx index cce4f9c5..efac8092 100644 --- a/packages/react-material-ui/__tests__/AppBarRoot.spec.tsx +++ b/packages/react-material-ui/__tests__/AppBarRoot.spec.tsx @@ -5,7 +5,7 @@ import '@testing-library/jest-dom'; import React from 'react'; import { render } from '@testing-library/react'; -import AppBar from '../src/components/AppBar'; +import { AppBar } from '../src/components/AppBar'; describe('AppBarRoot Component', () => { it('should render correctly', () => { diff --git a/packages/react-material-ui/src/components/AppBar/AppBarDrawer.tsx b/packages/react-material-ui/src/components/AppBar/AppBarDrawer.tsx index a644ab70..8c03703f 100644 --- a/packages/react-material-ui/src/components/AppBar/AppBarDrawer.tsx +++ b/packages/react-material-ui/src/components/AppBar/AppBarDrawer.tsx @@ -2,7 +2,14 @@ import React from 'react'; import { Drawer, DrawerProps } from '../Drawer'; import { useAppBarRoot } from './hooks/useAppBarRoot'; -const AppBarDrawer = (props: DrawerProps) => { +/** + * The list of the app routes rendered as a vertical navigation list on the Drawer component. + * + * @see {@link AppBar} + * @see {@link Drawer} + * @param props - {@link DrawerProps} + */ +export const AppBarDrawer = (props: DrawerProps) => { const { isMobileOpen, toggleMobileOpen } = useAppBarRoot(); return ( @@ -13,5 +20,3 @@ const AppBarDrawer = (props: DrawerProps) => { /> ); }; - -export default AppBarDrawer; diff --git a/packages/react-material-ui/src/components/AppBar/AppBarMain.tsx b/packages/react-material-ui/src/components/AppBar/AppBarMain.tsx index ae3c7cfb..9b4c357e 100644 --- a/packages/react-material-ui/src/components/AppBar/AppBarMain.tsx +++ b/packages/react-material-ui/src/components/AppBar/AppBarMain.tsx @@ -1,7 +1,19 @@ import React from 'react'; import { Box, BoxProps } from '@mui/material'; -const AppBarMain = ({ sx, children, ...props }: BoxProps) => { +/** + * The AppBarMain component serves as a wrapper for the navigation bar and page content. + * + * The AppBar.Main props extend from [Material UI's Box](https://mui.com/material-ui/api/box/#props) + * component props, so every prop is interchangeable between those two. + * + * @see {@link AppBar} + * @see {@link [MUI Box Component](https://mui.com/material-ui/react-box/)} + * @param boxProps - MUI {@link [BoxProps](https://mui.com/material-ui/api/box/#props)} + */ +export const AppBarMain = (boxProps: BoxProps) => { + const { sx, children, ...props } = boxProps; + return ( { ); }; - -export default AppBarMain; diff --git a/packages/react-material-ui/src/components/AppBar/AppBarNav.tsx b/packages/react-material-ui/src/components/AppBar/AppBarNav.tsx index a60c626d..9ef1d692 100644 --- a/packages/react-material-ui/src/components/AppBar/AppBarNav.tsx +++ b/packages/react-material-ui/src/components/AppBar/AppBarNav.tsx @@ -2,10 +2,16 @@ import React from 'react'; import Navbar, { NavbarProps } from '../Navbar'; import { useAppBarRoot } from './hooks/useAppBarRoot'; -const AppBarNav = (props: NavbarProps) => { +/** + * The AppBarNav component renders the user info ({@link Avatar} and Name) and + * a list of actions related to user and auth, such as Logout. + * + * @see {@link AppBar} + * @see {@link Navbar} + * @param props - {@link NavbarProps} + */ +export const AppBarNav = (props: NavbarProps) => { const { toggleMobileOpen } = useAppBarRoot(); return ; }; - -export default AppBarNav; diff --git a/packages/react-material-ui/src/components/AppBar/AppBarRoot.tsx b/packages/react-material-ui/src/components/AppBar/AppBarRoot.tsx index f555e951..f7c58d15 100644 --- a/packages/react-material-ui/src/components/AppBar/AppBarRoot.tsx +++ b/packages/react-material-ui/src/components/AppBar/AppBarRoot.tsx @@ -2,11 +2,24 @@ import React, { ReactNode, useState } from 'react'; import Box from '@mui/material/Box'; import { AppBarContext } from './hooks/useAppBarRoot'; +/** + * AppBarRoot component props. + */ export type AppBarRootProps = { + /** Child nodes rendered inside the Main component */ children: ReactNode; }; -const AppBarRoot = ({ children }: AppBarRootProps) => { +/** + * The AppBarRoot component acts as a wrapper for the context API shared + * with the other parts of the AppBar composition. + * + * @see {@link AppBar} + * @param props - Component props. + */ +export const AppBarRoot = (props: AppBarRootProps) => { + const { children } = props; + const [isMobileOpen, setIsMobileOpen] = useState(false); const toggleMobileOpen = () => { @@ -26,5 +39,3 @@ const AppBarRoot = ({ children }: AppBarRootProps) => { ); }; - -export default AppBarRoot; diff --git a/packages/react-material-ui/src/components/AppBar/README.md b/packages/react-material-ui/src/components/AppBar/README.md deleted file mode 100644 index 78e63527..00000000 --- a/packages/react-material-ui/src/components/AppBar/README.md +++ /dev/null @@ -1,124 +0,0 @@ -# AppBar - -The AppBar component is a wrapper for the page content, that renders a lateral menu containing the list of pages rendered by the app and a top navigation bar containing information related to the current user with a dropdown menu with a list of actions. It is composed by the `ApBar.Root`, `AppBar.Drawer`, `AppBar.Main` and `AppBar.Nav` components. - -## Example - -The following example describes the full composition that mounts the AppBar component: - -```tsx -import { AppBar } from '@concepta/react-material-ui'; - - - , - text: 'Users', - onClick: () => router.push('/users'), - }, - { - id: '/profile', - icon: , - text: 'Profile', - onClick: () => router.push('/profile'), - }, - ]} - expandedWidth={120} - /> - - ( - { - handleClose(); - doLogout(); - router.replace('/login'); - }} - > - Sign Out - - )} - /> - {children} - -; -``` - -## AppBar.Root - -The Root component acts as a wrapper for the context API shared with the other parts of the AppBar composition. - -### Props - -| Name | Type | Description | Optional | -| --- | --- | --- | --- | -| key | `string` | Identifier used to enforce re-render and internal state change upon [reconciliation](https://legacy.reactjs.org/docs/reconciliation.html). | Yes -| children | `node` | Child nodes rendered inside the Main component. | No - -## AppBar.Drawer - -The list of the app routes rendered as a vertical navigation list on the Drawer component. - -### Props - -| Name | Type | Description | Optional | -| --- | --- | --- | --- | -| items | `object[]` | Array containing information about the pages listed on the drawer. | No -| currentId | `string` | Identifier for the current path, changing the menu item to active when the page selected corresponds to the path name. | Yes -| customToggle | `string` | Custom node that can be rendered on the bottom of the Drawer, serving as toggle for expanded/collapsed state. | Yes -| mobileIsOpen | `string` | Identifier for open state on mobile. | Yes -| onMobileClose | `function` | Handler for Drawer closing action on mobile. | Yes -| logo | `string` | Source for an image logo file. | Yes -| textProps | `object` | Style props for the text rendered by Drawer items. | Yes -| sx | `object` or `object[]` | Object or array containing custom styles, following the [sx](https://mui.com/system/getting-started/the-sx-prop/) pattern. | Yes -| buttonSx | `object` or `object[]` | Object or array containing custom styles for each item button, following the [sx](https://mui.com/system/getting-started/the-sx-prop/) pattern. | Yes -| horizontal | `boolean` | Flag for rendering Drawer each item with text on the bottom or on the side. | Yes -| collapsible | `boolean` | Boolean value that tells if the drawer should have a fixed width or the possibility to expand. | Yes -| collapsibleIcon | `node` | Custom icon to display on collapsed/expanded toggle button. | Yes -| collapsibleIconColor | `string` | Custom color for the collapsed toggle icon. | Yes -| collapsibleIconBgColor | `string` | Custom background color for the collapsed toggle icon. | Yes -| collapsed | `boolean` | Boolean value that tells if the drawer is collapsed. | Yes -| onCollapsedChange | `function` | Handler for collapse/expand action. | Yes -| backgroundColor | `string` | Custom background color for the Drawer component. | Yes -| iconColor | `string` | Custom color for the Drawer items. | Yes -| activeIconColor | `string` | Custom color for the Drawer items when it is in active state. | Yes -| collapsedWidth | `string` or `number` | Custom width of the Drawer when it is on collapsed state. | Yes -| expandedWidth | `string` or `number` | Custom width of the Drawer when it is on expanded state. | Yes - -## AppBar.Main - -The Main component serves as a wrapper for the navigation bar and page content. - -### Props - -| Name | Type | Description | Optional | -| --- | --- | --- | --- | -| sx | `object` or `object[]` | Object or array containing custom styles, following the [sx](https://mui.com/system/getting-started/the-sx-prop/) pattern. | Yes -| children | `node` | Content rendered by the page. | Yes - -> The AppBar.Main props extend from [Material UI's `Box`](https://mui.com/material-ui/api/box/#props) component props, so every prop is interchangeable between those two. - -## AppBar.Nav - -The Nav component renders the user info (Avatar and Name) and a list of actions related to user and auth, such as Logout. - -### Props - -| Name | Type | Description | Optional | -| --- | --- | --- | --- | -| drawerToggle | `function` | Handler for click events on the Menu button. | Yes -| showNotifications | `boolean` | Flag for showing or hiding the notifications indicator. | Yes -| notificationsNumber | `number` | Indicator for notifications counter. | Yes -| notificationsOnClick | `function` | Handler for click events on the notifications indicator. | Yes -| avatar | `string` | Source of the user profile picture. | Yes -| text | `string` | String that can contain the current user name or username. | Yes -| subText | `string` | String rendered below the _text_ content. | Yes -| headerMenuOptions | `object[]` | List of menu actions. | Yes -| sx | `object` or `object[]` | Object or array containing custom styles, following the [sx](https://mui.com/system/getting-started/the-sx-prop/) pattern. | Yes diff --git a/packages/react-material-ui/src/components/AppBar/index.ts b/packages/react-material-ui/src/components/AppBar/index.ts index be412e99..3ae8be1a 100644 --- a/packages/react-material-ui/src/components/AppBar/index.ts +++ b/packages/react-material-ui/src/components/AppBar/index.ts @@ -1,13 +1,76 @@ -import AppBarMain from './AppBarMain'; -import AppBarDrawer from './AppBarDrawer'; -import AppBarNav from './AppBarNav'; -import AppBarRoot from './AppBarRoot'; +import { AppBarMain } from './AppBarMain'; +import { AppBarDrawer } from './AppBarDrawer'; +import { AppBarNav } from './AppBarNav'; +import { AppBarRoot } from './AppBarRoot'; -const AppBar = { +/** + * The AppBar component is a wrapper for the page content, that renders a + * lateral menu containing the list of pages rendered by the app and a top + * navigation bar containing information related to the current user with a + * dropdown menu with a list of actions. + * + * It is composed by the {@link AppBarRoot}, {@link AppBarDrawer}, + * {@link AppBarMain} and {@link AppBarNav} components. + * + * A sandbox of this componet is available on our + * [AppBar Story](https://storybook.rockets.tools/?path=/docs/appbar) + * + * @example The following example describes the full composition that mounts the AppBar component: + * + * ```tsx + * import { AppBar } from '@concepta/react-material-ui'; + * + * + * , + * text: 'Users', + * onClick: () => router.push('/users'), + * }, + * { + * id: '/profile', + * icon: , + * text: 'Profile', + * onClick: () => router.push('/profile'), + * }, + * ]} + * expandedWidth={120} + * /> + * + * ( + * { + * handleClose(); + * doLogout(); + * router.replace('/login'); + * }} + * > + * Sign Out + * + * )} + * /> + * {children} + * + * ; + * ``` + * + * @see {@link AppBarMain} + * @see {@link AppBarDrawer} + * @see {@link AppBarNav} + * @see {@link AppBarRoot} + * @see [Storybook - AppBar](https://storybook.rockets.tools/?path=/docs/appbar) + */ +export const AppBar = { Main: AppBarMain, Drawer: AppBarDrawer, Nav: AppBarNav, Root: AppBarRoot, }; - -export default AppBar; diff --git a/packages/react-material-ui/src/components/Drawer/Drawer.tsx b/packages/react-material-ui/src/components/Drawer/Drawer.tsx index 06e6c13e..10ba4dbf 100644 --- a/packages/react-material-ui/src/components/Drawer/Drawer.tsx +++ b/packages/react-material-ui/src/components/Drawer/Drawer.tsx @@ -17,9 +17,9 @@ import { SxProps, Theme } from '@mui/material/styles'; export type DrawerProps = { /** Array of items to display in the drawer */ items: DrawerItemProps[]; - /** ID of the currently active item */ + /** ID of the currently active item, changing the menu item to active when the page selected corresponds to the path name. */ currentId?: string; - /** Custom toggle component for the drawer */ + /** Custom node that can be rendered on the bottom of the Drawer, serving as toggle for expanded/collapsed state. */ customToggle?: (toggleDrawer: () => void, collapsed?: boolean) => ReactNode; /** Whether the drawer is open on mobile devices */ mobileIsOpen?: boolean; @@ -29,9 +29,9 @@ export type DrawerProps = { logo?: string | ReactNode | ((collapsed?: boolean) => ReactNode); /** Props for text elements inside the drawer */ textProps?: TextProps; - /** Custom styles for the drawer */ + /** Custom styles for the drawer, following the [sx](https://mui.com/system/getting-started/the-sx-prop/) */ sx?: StyledDrawerProps['sx']; - /** Custom styles for drawer buttons */ + /** Custom styles for drawer buttons, following the [sx](https://mui.com/system/getting-started/the-sx-prop/) pattern. */ buttonSx?: SxProps; /** Whether the drawer items should be displayed horizontally */ horizontal?: boolean; diff --git a/packages/react-material-ui/src/components/Navbar/Navbar.tsx b/packages/react-material-ui/src/components/Navbar/Navbar.tsx index 092510df..710ee731 100644 --- a/packages/react-material-ui/src/components/Navbar/Navbar.tsx +++ b/packages/react-material-ui/src/components/Navbar/Navbar.tsx @@ -7,15 +7,45 @@ import Text from '../Text'; import HeaderAccount, { HeaderAccountProps } from '../HeaderAccount'; import { SxProps, Theme } from '@mui/material/styles'; +/** + * Properties for the Navbar component. + */ export type NavbarProps = { + /** + * Handler for click events on the Menu button. + */ drawerToggle?: () => void; + /** + * Flag for showing or hiding the notifications indicator. + */ showNotifications?: boolean; + /** + * Indicator for notifications counter. + */ notificationsNumber?: number; + /** + * Handler for click events on the notifications indicator. + */ notificationsOnClick?: () => void; + /** + * Source of the user profile picture. + */ avatar?: string; + /** + * String that can contain the current user name or username. + */ text?: string; + /** + * String rendered below the text content. + */ subText?: string; + /** + * List of menu actions. + */ headerMenuOptions?: HeaderAccountProps['menuOptions']; + /** + * Object or array containing custom styles, following the sx pattern. @see {@link https://mui.com/system/getting-started/the-sx-prop/} + */ sx?: SxProps; }; diff --git a/packages/react-material-ui/src/index.ts b/packages/react-material-ui/src/index.ts index 604967cd..c32bec2a 100644 --- a/packages/react-material-ui/src/index.ts +++ b/packages/react-material-ui/src/index.ts @@ -1,8 +1,11 @@ export { Avatar, AvatarProps } from './components/Avatar'; export { default as Checkbox } from './components/Checkbox'; -import AppBar from './components/AppBar'; -export { AppBar }; +export { AppBar } from './components/AppBar'; +export { AppBarRoot, AppBarRootProps } from './components/AppBar/AppBarRoot'; +export { AppBarDrawer } from './components/AppBar/AppBarDrawer'; +export { AppBarMain } from './components/AppBar/AppBarMain'; +export { AppBarNav } from './components/AppBar/AppBarNav'; export { default as Dialog } from './components/Dialog';