Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(Datagrid): add missing hook documentation, part 1 (v2) #2921

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 220 additions & 0 deletions packages/cloud-cognitive/src/components/Datagrid/Datagrid.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -221,6 +221,12 @@ for center and right aligned as well. See
[design guidance](https://pages.github.ibm.com/cdai-design/pal/components/data-table/column-alignment/usage)
for details around when to change default column alignment.

To utilize center or right aligned columns refer to the steps below:

1. Include `useColumnCenterAlign` or `useColumnRightAlign` hook/s.
2. Add `rightAlignedColumn` or `centerAlignedColumn` to the column object in
which you which to change the default column alignment.

```jsx
import {
Datagrid,
Expand Down Expand Up @@ -794,6 +800,220 @@ width will be set to the default column width (150px) or the value passed to the
...
```

## Actions column

This will add row actions (if more than two actions are provided an OverflowMenu
component will be used) to the cells on the column marked with `isAction: true`.
Each action button callback will include the actionId and the row object.

1. Include `useActionsColumn` hook
2. Add `isAction = true` to the column object in which you which to add the
overflow menu actions
3. Add `rowActions = []` array to the props

- `rowActions[].id` for callback to identify the action is called
- `rowActions[].onClick(actionId: string, row: Row, event: ClickEvent)` callback
on menuitem clicked.
[Row properties](https://react-table.tanstack.com/docs/api/useTable#row-properties)
- `rowActions[].shouldHideMenuItem(row: Row)` callback to hide this menuitem.
[Row properties](https://react-table.tanstack.com/docs/api/useTable#row-properties)
- `rowActions[].shouldDisableMenuItem(row: Row)` callback to disable this
menuitem.
[Row properties](https://react-table.tanstack.com/docs/api/useTable#row-properties)
- This will override `rowActions[].disabled` (from Carbon) because
`shouldDisableMenuItem` is more specific to the row.
- each action object can take all the props from `OverflowMenuItem` props, see
[carbon docs](https://react.carbondesignsystem.com/?path=/docs/components-overflowmenu--default#overflowmenu)

```jsx
const columns = [
// other columns
{
Header: '',
accessor: 'actions',
isAction: true,
},
];
const onActionClick = (actionId, row, event) => {};
const datagridState = useDatagrid(
{
columns,
data,
rowActions: [
{
id: 'edit',
itemText: 'Edit',
onClick: onActionClick,
},
{
id: 'hidden',
itemText: 'Hidden item',
onClick: onActionClick,
shouldHideMenuItem: () => true,
},
{
id: 'delete',
itemText: 'Delete',
hasDivider: true,
isDelete: true,
onClick: onActionClick,
},
],
},
useActionsColumn
);

return <Datagrid datagridState={datagridState} />;
```

## Customizing columns

Customizing columns allows user to reorder and hide certain columns of the
datagrid. Consuming component can use the provided callback to save/update
according to their persistent strategy.

1. Include `useCustomizeColumns` and `useColumnOrder` hooks (required)

- `useColumnOrder` comes from `react-table` but is exported by
`@carbon/ibm-products` to be used alongside `useCustomizeColumns`.

2. Implement `options.DatagridActions` component

- this component will have props: `datagridState`
- render `datagridState.CustomizeColumnsButton` component wherever makes sense.

3. Options available to set:

- `options.initialState.hiddenColumns: Array<ColumnId: String>`
- Array of column ids that will be hidden after initial render
- [react-table doc](https://react-table.tanstack.com/docs/api/useTable#table-options)
- `options.initialState.columnOrder: Array<ColumnId: String>`
- Order of the columns. Any column ids not in this array will be ordered by
their position in the `options.columns`
- [react-table doc](https://react-table.tanstack.com/docs/api/useColumnOrder#table-options)
- `options.customizeColumnsProps.onSaveColumnPrefs`
- type:
`Function(Columns: Array<{ColumnId: String, isVisible: Boolean}>) => void`
- Callback function when 'Save' button clicked on the narrow tearsheet. It
allows consumer to preserve the updated column preference. This output can
also be used to compute the `hiddenColumns` and `columnOrder`
- Reset to default (optional)
- There is a reset to default button on the modal. It will use the
`options.columns` as the default. If there are columns should be hidden by
default, denote them with property: `isVisible: false` (undefined will be
treated as `true`)

```jsx
const columns = React.useMemo(() => defaultHeader, []);
const [data] = useState(makeData(10));
const DatagridActions = (datagridState) => (
<TableToolbarContent>
<TableToolbarSearch ... />
<Button ... />
<datagridState.CustomizeColumnsButton />
</TableToolbarContent>
)
const datagridState = useDatagrid(
{
columns,
data,
initialState: {
hiddenColumns: ['age'],
columnOrder: [],
},
customizeColumnsProps: {
onSaveColumnPrefs: (newColDefs) => {
console.log(newColDefs);
},
},
DatagridActions,
},
useCustomizeColumns,
useColumnOrder,
);

return (
<Datagrid datagridState={datagridState} />
);
```

## Disabling select rows

Disabling select rows allows you to choose which rows will be disabled in the
table.

1. Include the `useDisableSelectRows` hook in the `endPlugins` property of
`useDatagrid`.
2. Add the `shouldDisableSelectRow` to the `useDatagrid` hook, this will be a
function that returns the row indexes that will be disabled.

```jsx
const [data] = useState(makeData(10));
const columns = React.useMemo(() => getColumns(data), []);
const datagridState = useDatagrid(
{
columns,
data,
DatagridActions,
DatagridBatchActions,
endPlugins: [useDisableSelectRows],
shouldDisableSelectRow: (row) => row.id % 2 === 0,
disableSelectAll: true,
},
useSelectRows
);

return <Datagrid datagridState={datagridState} />;
```

## Infinite scroll

Infinite scroll is supported via the `useInfiniteScroll` hook. This hook will
allow you to fetch more data to display to the user after a certain scroll
threshold. The `useInfiniteScroll` hook can also be used to support virtualized
data, this is required when working with large amounts of data, only rendering
the rows that need to be visible in the component at a point in time.

Infinite scroll:

1. Include `useInfiniteScroll` hook
2. Add `fetchMoreData` property to `useDatagrid`, this will be a function that
is called when the scroll threshold is met. Optionally change the height of
the grid with the `virtualHeight` property.

```jsx
const datagridState = useDatagrid(
{
columns,
data,
isFetching,
fetchMoreData: fetchData,
virtualHeight: 540,
emptyStateTitle: 'Empty state title',
emptyStateDescription: 'Description explaining why the table is empty',
},
useInfiniteScroll
);
```

Virtualized data:

1. Include `useInfiniteScroll` hook
2. The Datagrid will know to use virtualized data just by providing the
`useInfiniteScroll` hook

```jsx
const [data] = useState(makeData(10000));
const columns = React.useMemo(() => getColumns(data), []);
const datagridState = useDatagrid(
{
columns,
data,
},
useInfiniteScroll
);
```

## Code sample

<CodesandboxLink exampleDirectory="Datagrid" />
Expand Down