terra-clinical-data-grid
Version:
An organizational component that renders a collection of data in a grid-like format.
121 lines (79 loc) • 9.5 kB
text/mdx
import { Notice } from "@cerner/terra-docs";
import { Badge } from 'terra-clinical-data-grid/package.json?dev-site-package';
import DataGridPropsTable from 'terra-clinical-data-grid/src/DataGrid?dev-site-props-table';
<Badge />
[](https://github.com/cerner/terra-clinical/packages/terra-clinical-data-grid#readme)
# Terra Clinical DataGrid
<Notice variant="deprecation">
`terra-clinical-data-grid` does not comply with accessibility guidelines and is no longer supported. If you are using `terra-clinical-data-grid`, consider replacing it with `terra-flowsheet-data-grid`.
</Notice>
The DataGrid is an organizational component that renders a collection of data in a grid-like format.
## Getting Started
- Install with [npmjs](https://www.npmjs.com):
- `npm install terra-clinical-data-grid`
## Usage
The DataGrid is a fully-controlled component that utilizes no internal state. Any desired changes to the DataGrid after its initial render can and should be communicated through its props.
Content is provided to the DataGrid as one of four distinct data structures: columns, sections, rows, and cells. These strutures are simple JS objects, not React components. Immutable objects should be used where possible to avoid unnecessary rendering costs.
### Columns
Columns define what is rendered in the column header as well as what interactions are available.
Columns are provided to the DataGrid through two props: `pinnedColumns` and `overflowColumns`. The order in which the columns are provided will be the order in which they are rendered, with the `pinnedColumns` preceeding the `overflowColumns`.
|Name|Type|Is Required|Default Value|Description|
|---|---|---|---|---|
|**id**|string|required|none|An identifier for the column. This identifier should be unique across the set of columns provided to the DataGrid.|
|**width**|number|optional|none|A number (in px) specifying the width of the column. If not provided, the DataGrid's default column width will be used.|
|**isSelectable**|bool|optional|none|A boolean indicating whether or not the column header is selectable. If true, the DataGrid's `onColumnSelect` prop will be called upon column header selection.|
|**isResizable**|bool|optional|none|A boolean indicating whether or not the column header is resizable. If true, a resize indicator will be rendered over the column header's contents, and the DataGrid's `onRequestColumnResize` function will be called upon interaction with the resize indicator. The new width will be provided with the function call so that the column's width property can be updated as needed.|
|**text**|string|optional|none|A string of text to render within the column header. This text will follow standard truncation rules as necessary. If a `component` value is specified, `text` will be ignored.|
|**sortIndicator**|One of: **ascending**, **descending**|optional|none|A string indicating which sorting indicator should be rendered. If not provided, no sorting indicator will be rendered. If a `component` value is specified, `sortIndicator` will be ignored.
|**component**|component|optional|none|A custom component to render within the column header. If provided, the `text` and `sortIndicator` values will be ignored.|
### Sections
Sections define the rendering style of the section header as well as the rows inside the section.
Sections are provided to the DataGrid through the `sections` prop. The order in which the sections are provided will be the order in which they are rendered.
|Name|Type|Is Required|Default Value|Description|
|---|---|---|---|---|
|**id**|string|required|none|An identifier for the section. This identifier should be unique across the set of sections provided to the DataGrid.|
|**isCollapsible**|bool|optional|none|A boolean indicating whether or not the the section is collapsible. If true, the DataGrid's `onRequestSectionCollapse` function will be called upon selection of the section header, and an icon indicating collapsibility will be rendered within the seaction header.|
|**isCollapsed**|bool|optional|none|A boolean indicating whether or not the section is collapsed. If true, the DataGrid will not render the contents of the section.|
|**text**|string|optional|none|A text string to render within the section header.|
|**startAccessory**|component|optional|none|A component to render within the section header's start accessory position. This will be rendered ahead of `text`.|
|**endAccessory**|component|optional|none|A component to render within the section header's end accessory position. This will be rendered behind `text`.|
|**component**|component|optional|none|A custom component to render within the section header. If provided, the `text`, `startAccessory`, and `endAccessory` values will be ignored.|
|**rows**|array|optional|[]|An array of row objects to be rendered within the section.|
> Note: if `text`, `startAccessory`, `endAccessory`, and `component` are not provided, and if `isCollapsible` is false, no section header will be rendered. However, the `rows` of the section will continue to be rendered.
Section headers will be provided the attribute `data-terra-clinical-data-grid-section-header-id="${sectionId}` for interested consumers.
### Rows
Rows define the cells rendered within the row as well as the row's selection properties.
Rows are provided to sections to be rendered by the DataGrid. The order in which the rows are provided will be the order in which they are rendered.
|Name|Type|Is Required|Default Value|Description|
|---|---|---|---|---|
|**id**|string|required|none|An identifier for the row. This identifier should be unique across the set of rows provided to a given section.|
|**ariaLabel**|string|optional|none|A string identifier used to describe the row contents. This value will be used to contruct additional labels for internal controls (e.g. row selection cells).|
|**isDecorative**|bool|optional|none|A boolean to prevent the row from being interactive (selectable + selected), hides the column highlighting style in the row when `columnHighlightId` is valued, and applies role="presentation" and aria-hidden="true" to hide from screen readers. Used for inserted decorative rows like custom dividers.|
|**isSelectable**|bool|optional|none|A boolean indicating whether or not the row is selectable.|
|**isSelected**|bool|optional|none|A boolean indicating whether or not the row should render as selected.|
|**cells**|array|optional|[]|An array of cell objects that define the content to be rendered in the row. The order in which the cells are rendered is determined by the order of the `pinnedColumns` and `overflowColumns` props.|
|**height**|string|optional|none|The height for this row. This overrides the `DataGrid` `rowHeight` property. Values are suggested to be in `rem`s (ex `'5rem'`), but any valid CSS height value is accepted.|
### Cells
Cells define the content rendered in a given section, row, and column.
|Name|Type|Is Required|Default Value|Description|
|---|---|---|---|---|
|**columnId**|string|required|none|A column identifier for the cell. This identifier should be unique across the set of cells provided to a given row.|
|**isSelectable**|bool|optional|none|A boolean indicating whether or not the cell is selectable.|
|**isSelected**|bool|optional|none|A boolean indicating whether or not the cell should render as selected.|
|**component**|component|optional|none|A component to render within the cell.|
#### Creating components for Cells
The DataGrid will provide a explicitly sized container within which the Cell `component` will be rendered. A height and width of `100%` should be set on the component to ensure it fills the available area.
## Creating Custom Content
The various DataGrid containers (column header, section header, cell) support the presentation of custom components. However, there are a few rules that a component must adhere to.
The DataGrid provides a number of styles for mouse/keyboard interaction states (click, hover, selection). Custom components should generally render with a transparent background to ensure those default styles bleed through the component.
The DataGrid will provide a explicitly sized container within which the component will rendered. A height and width of `100%` should be set on the component to ensure it fills the area provided to it.
If there are any mouse/keyboard interactive elements within the component, and the component is rendered inside a selectable DataGrid container (column header, section header, cell), events may propagate in ways that the component is not expecting. Events triggered by those interactive elements should not be propagated to prevent undesired DataGrid interactions.
Additionally, these interactive elements must include a special data attribute called `data-accessible-data-grid-content`. The DataGrid utilizes a custom tabbing implementation to ensure a propper tabbing order, and including that attribute on all interactive elements of custom components will ensure that they are still sensibly keyboard accessible.
``` jsx
import DataGrid from 'terra-clinical-data-grid';
```
## Component Features
* [Cross-Browser Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#cross-browser-support)
* [Responsive Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#responsive-support)
## Data Grid Props Table
<DataGridPropsTable />