Merge pull request #169 from brunomous/docs/table-hooks

Documentation for hooks/context

package.json

@@ -53,6 +53,7 @@
     "tsconfig-paths": "^3.10.1",
     "typedoc": "^0.25.0",
     "typedoc-plugin-coverage": "^3.2.0",
+    "typedoc-plugin-rename-defaults": "^0.7.1",
     "typescript": "^4.3.5"
   },
   "scripts": {

packages/react-auth-provider/src/index.tsx

@@ -18,6 +18,9 @@ import {
 
 const AuthContext = createContext<AuthProviderTypes | null>(null);
 
+/**
+ * Custom hook that wraps the implementation of the Auth context.
+ */
 const useAuth = () => useContext<AuthProviderTypes>(AuthContext);
 
 const AuthProvider = ({
@@ -67,8 +70,6 @@ const AuthProvider = ({
   const doLogout = async () => {
     localStorage.removeItem('accessToken');
     localStorage.removeItem('refreshToken');
-    localStorage.removeItem('filterSettings');
-    localStorage.removeItem('tableSettings');
   };
 
   return (
@@ -88,4 +89,10 @@ const AuthProvider = ({
   );
 };
 
-export { LoginParams, useAuth, AuthProvider };
+export {
+  LoginParams,
+  useAuth,
+  AuthProvider,
+  AuthProviderTypes,
+  AuthProviderProps,
+};

packages/react-auth-provider/src/interfaces/index.ts

@@ -1,12 +1,34 @@
 export interface LoginParams {
+  /**
+   * API path where the login request will be sent to.
+   */
   loginPath?: string;
+  /**
+   * Parameter username that belongs to user credentials.
+   */
   username?: string;
+  /**
+   * Parameter password that belongs to user credentials.
+   */
   password?: string;
+  /**
+   * Custom credentials passed to the login request.
+   */
   [key: string]: string | number | boolean;
 }
 
 export type AuthProviderProps = {
+  /**
+   * Callback for when the login request performs successfully.
+   *
+   * @param accessToken - The JWT token of the signed user.
+   */
   onSuccess?: (accessToken?: string) => void;
+  /**
+   * Callback for when there's an error on the login request.
+   *
+   * @param accessToken - The error returned from the API.
+   */
   onError?: (error?: Error) => void;
 };
 
@@ -15,16 +37,43 @@ export type DoLogin = <TLoginParams>(
 ) => void;
 
 export type AuthProviderTypes = {
+  /**
+   * User data returned from a successfully performed login request.
+   */
   user: unknown;
+  /**
+   * Callback for management of the login user data.
+   */
   setUser: React.Dispatch<unknown>;
+  /**
+   * Callback for performing a login request.
+   */
   doLogin: DoLogin;
+  /**
+   * Callback for performing a logout request.
+   */
   doLogout: () => void;
+  /**
+   * Login request loading state indicator.
+   */
   isPending: unknown;
+  /**
+   * JWT token assigned to the logged user.
+   */
   accessToken: string;
+  /**
+   * JWT token used for refreshing an user token.
+   */
   refreshToken: string;
 };
 
 export interface AuthReponse {
+  /**
+   * JWT token assigned to the logged user.
+   */
   accessToken: string;
+  /**
+   * JWT token used for refreshing an user token.
+   */
   refreshToken: string;
 }

packages/react-material-ui/src/components/AppBar/AppBarDrawer.tsx

@@ -4,7 +4,7 @@ import { useAppBarRoot } from './hooks/useAppBarRoot';
 
 /**
  * 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}

packages/react-material-ui/src/components/AppBar/AppBarNav.tsx

@@ -5,7 +5,7 @@ import { useAppBarRoot } from './hooks/useAppBarRoot';
 /**
  * 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}

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

@@ -0,0 +1,3 @@
+import { useAppBarRoot, AppBarContextProps } from './useAppBarRoot';
+
+export { useAppBarRoot, AppBarContextProps };

packages/react-material-ui/src/components/AppBar/hooks/useAppBarRoot.tsx

@@ -2,15 +2,24 @@
 
 import { createContext, useContext } from 'react';
 
-type AppBarContextProps = {
+export type AppBarContextProps = {
+  /**
+   * Boolean that indicates if the AppBar Drawer is open on a mobile screen.
+   */
   isMobileOpen: boolean;
+  /**
+   * Callback for changing the open state of the AppBar Drawer dinamically.
+   */
   toggleMobileOpen: () => void;
 };
 
 export const AppBarContext = createContext<AppBarContextProps>(
   {} as AppBarContextProps,
 );
 
+/**
+ * Custom hook that wraps the implementation of the App Bar Root context.
+ */
 export const useAppBarRoot = () => {
   const appBarContext = useContext(AppBarContext);
 

packages/react-material-ui/src/components/Table/hooks/index.ts

@@ -0,0 +1,9 @@
+import { useTableQueryState, getTableQueryState } from './useTableQueryState';
+import { useTableRoot, TableContextProps } from './useTableRoot';
+
+export {
+  useTableQueryState,
+  getTableQueryState,
+  useTableRoot,
+  TableContextProps,
+};

packages/react-material-ui/src/components/Table/hooks/useTableRoot.tsx

@@ -3,22 +3,80 @@
 import React, { createContext, useContext } from 'react';
 import { HeaderProps, RowProps, TableQueryStateProps } from '../types';
 
-type TableContextProps = {
+export type TableContextProps = {
+  /**
+   * Array of objects, where each contain the data displayed in Table rows.
+   */
   rows: RowProps[];
+  /**
+   * Array of objects that represent the Table columns.
+   */
   headers: HeaderProps[];
+  /**
+   * Total of items displayed in the Table.
+   */
   total: number;
+  /**
+   * Boolean value that indicates if the Table state can be controlled by external sources.
+   */
   isControlled: boolean;
+  /**
+   * Total of pages rendered by the Table.
+   */
   pageCount: number;
+  /**
+   * Table state containing page, order and search properties.
+   */
   tableQuery: TableQueryStateProps;
+  /**
+   * Array of selected rows when checkboxes are available.
+   */
   selected: RowProps[];
+  /**
+   * Callback for changing Table columns dinamically.
+   */
   setHeaders: React.Dispatch<React.SetStateAction<HeaderProps[]>>;
+  /**
+   * Cllback for checking whether a row with the given ID is selected.
+   *
+   * @param id - The ID of the row to check.
+   * @returns `true` if the row is selected, `false` otherwise.
+   */
   isSelected: (id: string) => boolean;
+  /**
+   * Callback for changing the current page in the Table pagination.
+   *
+   * @param event - The event representing the page change.
+   * @param newPage - The new page number.
+   */
   handleChangePage: (event: unknown, newPage: number) => void;
+  /**
+   * Callback for changing the quantity of rows per page in the Table pagination.
+   *
+   * @param event - The event representing the value change.
+   */
   handleChangeRowsPerPage: (event: React.ChangeEvent<HTMLInputElement>) => void;
+  /**
+   * Callback for changing the current Table sort by a specific column.
+   *
+   * @param event - The mouse event triggering the sorting request.
+   * @param property - The property by which to sort the table.
+   */
   handleSort: (event: React.MouseEvent<unknown>, property: string) => void;
+  /**
+   * Callback for selecting all checkboxes for rows in the Table.
+   *
+   * @param event - The event representing the checkbox selection change.
+   */
   handleSelectAllCheckboxes: (
     event: React.ChangeEvent<HTMLInputElement>,
   ) => void;
+  /**
+   * Callback for selecting a checkbox for a specific row in the table.
+   *
+   * @param event - The mouse event triggering the checkbox selection.
+   * @param row - The row for which the checkbox is being selected.
+   */
   handleSelectCheckboxItem: (
     event: React.MouseEvent<unknown>,
     row: RowProps,
@@ -29,6 +87,9 @@ export const TableContext = createContext<TableContextProps>(
   {} as TableContextProps,
 );
 
+/**
+ * Custom hook that wraps the implementation of the Table Root context.
+ */
 export const useTableRoot = () => {
   const tableRootContext = useContext(TableContext);
 

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

@@ -17,6 +17,13 @@ import { TableRowSkeleton } from './TableRowSkeleton';
 import { TableCellSkeleton } from './TableCellSkeleton';
 import { TableColumnOrderable } from './TableColumnOrderable';
 
+import useTable, {
+  UseTableProps,
+  UseTableResult,
+  UseTableOptions,
+  UpdateSearch,
+} from './useTable';
+
 const TableComponent = {
   Table,
   BodyCell: TableBodyCells,
@@ -36,4 +43,12 @@ const TableComponent = {
   ColumnOrderable: TableColumnOrderable,
 };
 
+export {
+  useTable,
+  UseTableProps,
+  UseTableResult,
+  UseTableOptions,
+  UpdateSearch,
+};
+
 export default TableComponent;