@hitachivantara/uikit-react-core 3.74.0 → 4.0.1-next.2

package/dist/modern/Table/stories/TableHooks.stories.mdx

@@ -0,0 +1,278 @@
+import { Meta, Story, Preview } from "@storybook/addon-docs";
+
+import LinkTo from "@storybook/addon-links/react";
+
+import { Usage } from "storybook-root/blocks/Usage";
+
+import { HvTable } from "../..";
+
+import * as stories from "./TableHooks.stories.js";
+
+<Meta title="Display/Table Hooks" />
+
+# Table hooks
+
+The UI Kit library provides a collection of **custom hooks** that ease the integration with the <LinkTo kind="Display/Table" story="Main" className="sbdocs sbdocs-a">HvTable elements</LinkTo> and allows more advanced use cases and better data handling.
+
+Our custom hooks are built on top of [React Table](https://react-table.tanstack.com) which is an "headless" UI utility library to build data tables while retaining control over markup and styles. It consists of a collection of, lightweight, composable and extensible custom React hooks.
+
+## `useHv*` hooks
+
+For further ease, you can use the provided `useHvData` hook that wraps the [React Table's `useTable` hook](https://react-table.tanstack.com/docs/api/useTable) and
+provides the following functionality:
+
+- Ensures the use of the needed core and layout plugins when using any of the UI Kit custom hooks (e.g. adding `useHvPagination` implies the instalation of React Table's `usePagination` hook).
+- Automatically installs the `useHvTableStyles` hook.
+- Generates default column metadata from the data fields, if the `columns` option is missing.
+- Defaults to an empty array if no `data` is provided.
+
+<Usage>{'import { useHvData } from "@hitachivantara/uikit-react-lab";'}</Usage>
+
+<Preview withToolbar>
+  <Story inline story={stories.UseHvData} />
+</Preview>
+
+The following plugin hooks are available:
+
+- `useHvTableStyles`: ensures the correct styling of the table by injecting the column's `variant` and `align` options into the `HvTableHeader` and `HvTableCell` components (via `getHeaderProps` and `getCellProps`, respectively).
+  Also adds support for injecting the `styles`, `className` and `classes` into the `HvTable`, `HvTableHeader` and `HvTableCell` components.
+- `useHvPagination`: eases the wiring of the `HvPagination` component when using pagination. See <a href="#pagination" className="sbdocs-a">Pagination</a>.
+- `useHvRowSelection`: creates and manages the UI for selecting rows. See <a href="#selection" className="sbdocs-a">Selection</a>.
+- `useHvBulkActions`: eases the wiring of the `HvBulkActions` component. See <a href="#bulk-selection-and-actions" className="sbdocs-a">Bulk selection and actions</a>.
+- `useHvSortBy`: manages the table's header sorting functionality. See <a href="#sorting" className="sbdocs-a">Sorting</a>.
+- `useHvRowExpand`: manages the row expanding functionality. See <a href="#row-expanding" className="sbdocs-a">Row expanding</a>.
+- `useHvTableSticky`: allows defining sticky headers and columns. See <a href="#sticky-headers-and-columns" className="sbdocs-a">Sticky Headers And Columns</a>.
+- `useHvHeaderGroups`: allows defining grouped headers. See <a href="#grouped-headers" className="sbdocs-a">Grouped Headers</a>.
+
+## KitchenSink
+
+Complete sample table that uses most of the features provided.
+
+<Preview withToolbar>
+  <Story inline story={stories.KitchenSink} />
+</Preview>
+
+# Hooks usage
+
+## useHvPagination
+
+Data can be paginated. Optionally, empty lines can be added to the last page to avoid changes in height.
+
+Check [React Table's `usePagination` documentation](https://react-table.tanstack.com/docs/api/usePagination) for configuration details.
+
+The `useHvPagination` hook makes the `getHvPaginationProps` function available on the table instance returned that can be used to setup a `HvPagination` component.
+
+_Note: This hook depends on the `usePagination` hook from `react-table`, but when using `useHvData` only `useHvPagination` needs to be installed._
+
+<Preview withToolbar>
+  <Story inline story={stories.Pagination} />
+</Preview>
+
+## useHvRowSelection
+
+Rows can be selected individually.
+
+Check [React Table's `useRowSelect` documentation](https://react-table.tanstack.com/docs/api/useRowSelect) for configuration details.
+
+The `useHvRowSelecion` hook injects a new column with a `HvCheckBox` to select each row. It also manages the `HvTableRow`'s `isSelected` property via the `getRowProps`.
+
+This hook is originally based on the code `useRowSelect` hook from `react-table` and implements its API, but extends it with support for locking the selection state of individual rows.
+
+<Preview withToolbar>
+  <Story inline story={stories.Selection} />
+</Preview>
+
+## useHvRowSelection controlled
+
+A selection state can also be included in the data and toggled externally.
+
+<Preview withToolbar>
+  <Story inline story={stories.ControlledSelection} />
+</Preview>
+
+## useHvBulkActions
+
+Rows can also be selected in bulk and actions can be performed on the current selection.
+
+The `useHvBulkActions` hook makes the `getHvBulkActionsProps` function available on the table instance returned that can be used to setup a `HvBulkActions` component.
+
+_Note: This hook depends on the `useRowSelect` hook from `react-table`, but when using `useHvData` only `useHvBulkActions` needs to be installed._
+
+<Preview withToolbar>
+  <Story inline story={stories.BulkActions} />
+</Preview>
+
+## useHvSortBy
+
+Tables can have the capability of sorting the data by column.
+Clicking a sortable column header toggles between ascending or descending. Multiple sorting criteria is enabled through holding shift while clicking.
+
+Check [React Table's `useSortBy` documentation](https://react-table.tanstack.com/docs/api/useSortBy) for configuration details.
+
+The `useHvSortBy` hook ensures that the proper properties are injected in the `HvTableHeader` (including the on click sorting trigger) and `HvTableCell` (for styling).
+
+_Note: This hook depends on the `useSortBy` hook from `react-table`, but when using `useHvData` only `useHvSortBy` needs to be installed._
+
+<Preview withToolbar>
+  <Story inline story={stories.Sortable} />
+</Preview>
+
+## useHvRowExpand
+
+Tables rows can have the capability of being expanded to show more details.
+
+Check [React Table's `useExpanded` documentation](https://react-table.tanstack.com/docs/api/useExpanded) for configuration details.
+
+The `useHvRowExpand` hook injects a `HvButton` into the first data column that toggles each row expansion. If the column has a custom renderer, an extra column is created instead.
+
+_Note: This hook depends on the `useExpanded` hook from `react-table`, but when using `useHvData` only `useHvRowExpand` needs to be installed._
+
+<Preview withToolbar>
+  <Story inline story={stories.Expandable} />
+</Preview>
+
+## useGroupBy
+
+Tables rows can have the capability of being expanded to show more details.
+
+Check [React Table's `useGroupBy` documentation](https://react-table.tanstack.com/docs/api/useGroupBy) for configuration details.
+
+This example requires useHvRowExpand to show the grouped rows.
+
+<Preview withToolbar>
+  <Story inline story={stories.GroupBy} />
+</Preview>
+
+## useHvTableSticky
+
+The table headers can be fixed at the top, allowing it to keep always visible when table has vertical scrolling enabled.
+
+It is also possible to stick columns, either on the left or on the right, making them always visible when scrolling horizontally.
+
+This is implemented using the `useHvTableSticky` custom React Table hook provided by the UI Kit library.
+
+When using sticky columns, all column widths will be fixed and a non-table-element layout is applied.
+
+### Configuration
+
+The following options are supported via the main options object passed to `useTable(options)`:
+
+- `stickyHeader: Bool`
+  - Enables the sticky header
+
+The following options are supported on any `Column` object passed to the `columns` options in `useTable()`:
+
+- `sticky: "left" | "right"`
+  - Sticks this column to the defined side. Columns will be re-orderer if needed.
+- `width: Int`
+  - Defaults to 150
+  - Specifies the width for the column
+- `minWidth: Int`
+  - Defaults to 0
+  - Specifies the minimum width for the column
+
+### Usage
+
+The `getTableProps`, `getTableHeadProps`, `getHeaderGroupProps`, `getHeaderProps`, `getTableBodyProps`, `getRowProps` and `getCellProps` prop getters must be called and the properties injected into the corresponding elements.
+
+<Preview withToolbar>
+  <Story inline story={stories.StickyHeadersAndColumns} />
+</Preview>
+
+## useHvHeaderGroups
+
+The table columns can be grouped, allowing it to have header groups.
+
+Check [React Table's `useTable#column-options` documentation](https://react-table.tanstack.com/docs/api/useTable#column-options) for configuration details.
+
+This is implemented using the `useHvHeaderGroups` custom React Table hook provided by the UI Kit library.
+
+When using grouped columns, all header group columns text will be centered.
+
+### Configuration
+
+The following options are supported on any `Column` object passed to the `columns` options in `useTable()`:
+
+- `columns: Array<Column>`
+  - A nested array of columns. If defined, the column will act as a header group. Columns can be recursively nested as much as needed.
+
+### Usage
+
+The `getTableProps`, `getHeaderGroupProps`, `getHeaderProps`, `getTableBodyProps`, `getRowProps` and `getCellProps` prop getters must be called and the properties injected into the corresponding elements.
+
+<Preview withToolbar>
+  <Story inline story={stories.GroupedHeaders} />
+</Preview>
+
+# Other use cases
+
+## Empty Cells
+
+The absence of data within an individual cell in the table should be displayed as a `—` (_em dash_), according to Design System guidelines.
+
+This must be handled by the developer in the respective cell renderer, as it is an guideline and not a strict rule.
+Different use cases may require different solutions, like `N/A` or `0`. Empty cells should be avoided.
+
+<Preview withToolbar>
+  <Story inline story={stories.EmptyCells} />
+</Preview>
+
+## Locked Selection
+
+Individual rows can have its selection state locked (becoming either not selectable or not unselectable), disabling the selection checkbox and also preventing the bulk actions to change the row state.
+
+<Preview withToolbar>
+  <Story inline story={stories.LockedSelection} />
+</Preview>
+
+## Alternative Layout
+
+react-table provides some layout plugin hooks useful for instance when needing to virtualize rows and cells for performance or enabling user resizable tables/columns.
+They rely on the core column options `width`, `minWidth` and `maxWidth`, that are used to calculate column and cell widths.
+
+- `useBlockLayout` renders headers and cells as inline-block elements with explicit width.
+- `useAbsoluteLayout` renders headers and cells as absolutely positioned elements with explicit width.
+- `useFlexLayout` renders headers and cells as inline-block elements, with the `width` being used as the `flex-basis` and `flex-grow`.
+
+Note that not all built-in styles will apply when using any of the alternative layouts, so aditional styling might be needed to acomplish the same look.
+Also, styles affecting element's widths (`width`, `min-width`, `max-width` and flex properties) must be avoided and the core column options used instead.
+
+Most layouts work well with the default html table elements, keeping the semantics while loosing the table layout rules.
+Elements can be changed (to `div` or any other apropriate html element) by using the `component` property.
+
+`useGridLayout` implies a totally diferent dom structure and is currently not supported by the HvTable components.
+
+<Preview withToolbar>
+  <Story inline story={stories.AlternativeLayout} />
+</Preview>
+
+## Server Side
+
+<Preview withToolbar>
+  <Story inline story={stories.ServerSide} />
+</Preview>
+
+## Drag and Drop
+
+react-table has an example which integrates the react-dnd / react-beautiful-dnd libraries to provide drag and drop capability on lines.
+Please check the documentation of [react-beautiful-dnd](https://github.com/atlassian/react-beautiful-dnd) in case you want to extend this example.
+
+This sample is not a clean react-beautiful-dnd implementation because it is applied to a table and requires some custom work to maintain the
+layout of the table line (and its cell contents) while dragging. Please check https://github.com/atlassian/react-beautiful-dnd/blob/master/docs/patterns/tables.md
+for more information.
+
+This behavior does not match 100% the Design System guidelines, although it offers a solution which implements the behavior and adds an accessible way for
+doing the drag/drop operation via `SPACE + ARROW` Keys.
+
+<Preview withToolbar>
+  <Story inline story={stories.DragAndDrop} />
+</Preview>
+
+## Column Resize
+
+Columns can be resized using the useHvResizeColumn hook, which leverages the react-table capabilities.
+Resize, although not an accessible functionality, it allows columns to be resizable via dragging column right border.
+
+<Preview withToolbar>
+  <Story inline story={stories.ColumnResize} />
+</Preview>