Merge pull request #148 from conceptadev/feature/app-bar-docs

Feature/app bar docs

Author: MrMaz

.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

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 = [

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 = [

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', () => {

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', () => {

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', () => {

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;

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 (
     <Box
       component="main"
@@ -20,5 +32,3 @@ const AppBarMain = ({ sx, children, ...props }: BoxProps) => {
     </Box>
   );
 };
-
-export default AppBarMain;

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 <Navbar drawerToggle={toggleMobileOpen} {...props} />;
 };
-
-export default AppBarNav;

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) => {
     </AppBarContext.Provider>
   );
 };
-
-export default AppBarRoot;

packages/react-material-ui/src/components/AppBar/README.md

@@ -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';
+ *
+ * <AppBar.Root key={pathname}>
+ *   <AppBar.Drawer
+ *     currentId={pathname}
+ *     logo="/logo.svg"
+ *     collapsable
+ *     items={[
+ *       {
+ *         id: '/users',
+ *         icon: <GroupsOutlinedIcon />,
+ *         text: 'Users',
+ *         onClick: () => router.push('/users'),
+ *       },
+ *       {
+ *         id: '/profile',
+ *         icon: <PersonOutlinedIcon />,
+ *         text: 'Profile',
+ *         onClick: () => router.push('/profile'),
+ *       },
+ *     ]}
+ *     expandedWidth={120}
+ *   />
+ *   <AppBar.Main>
+ *     <AppBar.Nav
+ *       text={user.fullName}
+ *       avatar="https://source.unsplash.com/random"
+ *       headerMenuOptions={(handleClose) => (
+ *         <MenuItem
+ *           onClick={() => {
+ *             handleClose();
+ *             doLogout();
+ *             router.replace('/login');
+ *           }}
+ *         >
+ *           Sign Out
+ *         </MenuItem>
+ *       )}
+ *     />
+ *     <Container>{children}</Container>
+ *   </AppBar.Main>
+ * </AppBar.Root>;
+ * ```
+ *
+ * @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;

packages/react-material-ui/src/components/AppBar/index.ts

@@ -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<Theme>;
   /** Whether the drawer items should be displayed horizontally */
   horizontal?: boolean;