Creation of documentation/implementation guide for Worklist DataGrid

packages/terra-data-grid/CHANGELOG.md

@@ -5,6 +5,9 @@
 * Added
   * Added base FlowsheetDataGrid component.
 
+* Changed
+  * Updated prop descriptions for better consistency and accuracy in the `terra-data-grid` component.
+
 ## 0.7.0 - (October 3, 2023)
 
 * Fixed

packages/terra-data-grid/src/WorklistDataGrid.jsx

@@ -40,13 +40,13 @@ const propTypes = {
 
   /**
    * Data for pinned columns. Pinned columns are the stickied leftmost columns of the grid.
-   * Columns will be presented in the order given.
+   * Columns are rendered in the order in which they are provided.
    */
   pinnedColumns: PropTypes.arrayOf(columnShape),
 
   /**
    * Data for overflow columns. Overflow columns are rendered in the Worklist Data Grid's horizontal overflow.
-   * Columns will be presented in the order given.
+   * Columns are rendered in the order in which they are provided.
    */
   overflowColumns: PropTypes.arrayOf(columnShape),
 
@@ -121,7 +121,7 @@ const propTypes = {
    */
   onEnableRowSelection: PropTypes.func,
   /**
-   * Boolean indicating whether or not the DataGrid should allow entire rows to be selectable. An additional column will be
+   * Boolean indicating whether or not the Worklist Data Grid should allow entire rows to be selectable. An additional column will be
    * rendered to allow for row selection to occur.
    */
   hasSelectableRows: PropTypes.bool,

packages/terra-data-grid/src/proptypes/cellShape.js

@@ -2,19 +2,19 @@ import PropTypes from 'prop-types';
 
 const cellShape = PropTypes.shape({
   /**
-   * Content that will be rendered within the Cell.
+   * The content to render within the cell.
    */
   content: PropTypes.node,
   /**
-   *  Boolean indicating if cell contents are masked.
+   *  A boolean indicating if the cell content is masked.
    */
   isMasked: PropTypes.bool,
   /**
-   * Boolean value indicating whether or not the column header is selectable.
+   * A boolean indicating if the cell is selectable.
    */
   isSelectable: PropTypes.bool,
   /**
-   * Boolean value indicating whether or not the cell should render as selected.
+   * A boolean indicating if the cell is selected.
    */
   isSelected: PropTypes.bool,
 });

packages/terra-data-grid/src/proptypes/rowShape.js

@@ -8,19 +8,17 @@ const rowShape = PropTypes.shape({
   id: PropTypes.string.isRequired,
 
   /**
-   * Data to be displayed in the cells of the row. Cells will be rendered in the row in the order given.
+   * An array of cell objects that define the content to be rendered in the row. Cells will be rendered in the order given and are expected to be in the same order as the columns.
    */
   cells: PropTypes.arrayOf(cellShape),
   /**
    * A boolean indicating whether or not the row should render as selected.
    */
   isSelected: PropTypes.bool,
   /**
-   * A string identifier used to describe the row contents. This value will be used to construct additional labels
-   * for internal controls (e.g. row selection cells).
+   * A string identifier used to describe the row contents. This value will be used by screen readers when announcing the row (un)selection.
    */
   ariaLabel: PropTypes.string,
-
 });
 
 export default rowShape;

packages/terra-framework-docs/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 * Added
   * Added documentation for FlowsheetDataGrid in `terra-data-grid`.
+  * Added additional documentation and implementation guide in adherence to the newly established documentation template for the examples of Worklist Data Grid in `terra-data-grid`.
 
 ## 1.39.0 - (October 3, 2023)
 

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/BasicWorklistDataGrid.1.doc.mdx

@@ -0,0 +1,9 @@
+import BasicWorklistDataGrid from './BasicWorklistDataGrid?dev-site-example';
+
+# Basic Worklist Data Grid
+
+### Description
+
+This example demonstrates a basic [Worklist Data Grid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) with basic keyboard interactions.
+
+<BasicWorklistDataGrid title='Basic Worklist Data Grid' />

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/DefaultWorklistDataGrid.jsx → packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/BasicWorklistDataGrid.jsx

@@ -51,7 +51,7 @@ const gridDataJSON = {
   ],
 };
 
-const DefaultWorklistDataGrid = () => {
+const BasicWorklistDataGrid = () => {
   const rowHeaderIndex = 0;
   const { cols, rows } = gridDataJSON;
 
@@ -66,4 +66,4 @@ const DefaultWorklistDataGrid = () => {
   );
 };
 
-export default DefaultWorklistDataGrid;
+export default BasicWorklistDataGrid;

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/CellSelection.2.doc.mdx

@@ -1,3 +1,21 @@
 import CellSelection from './CellSelection?dev-site-example';
 
-<CellSelection title='Worklist Data Grid With Cell Selection' />
+# Cell Selection
+
+### Description
+This example demonstrates a [Worklist Data Grid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) that has support for cell selection.
+A cell is selected by clicking on the cell or pressing the Spacebar on the focused
+cell. Only cells that are selectable and not masked can be selected.
+A cell is selectable by default.
+
+### Properties required
+* The **onCellSelect** callback prop: When the user selects a cell, this callback will be called with the rowId and columnId of the selected cell.
+In this example, the information is used to look up the matching cell information in the input data and disclose additional information for that cell.
+The `selected` attribute of the matching cell in the row data is toggled to be true. But an end user may choose to do nothing when the cell is already selected.
+Since only one cell may be selected, any previous cell selection is cleared before a new cell is selected.
+
+
+* The **onClearSelectedCells** callback prop: When the user presses Escape, this callback gets called. In this example, the selected attribute of any selected cell is set to false and the Worklist Data Grid is re-rendered.
+
+
+<CellSelection title='' />

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/CellSelection.jsx

@@ -29,10 +29,10 @@ const gridDataJSON = {
         { content: '' },
         { content: 'Quinzell, Harleen' },
         { content: '' },
-        { isMasked: true },
+        { isMasked: true }, // This cell's content will be masked
         { isMasked: true },
         { content: 'Admitting Physician' },
-        { content: '', isSelectable: false },
+        { content: '', isSelectable: false }, // This cell cannot be selected via click but can receive focus when navigating through keyboard
       ],
     },
     {
@@ -54,6 +54,7 @@ const gridDataJSON = {
     },
   ],
 };
+
 const CellSelection = () => {
   const rowHeaderIndex = 0;
   const { cols, rows } = gridDataJSON;
@@ -66,7 +67,7 @@ const CellSelection = () => {
       const rowIndex = rowData.findIndex(e => e.id === rowId);
       const columnIndex = cols.findIndex(e => e.id === columnId);
 
-      // Remove current selections
+      // Remove current selections as the Worklist Data Grid can have only one selected cell at any instance.
       const newRowData = [...rowData];
       for (let row = 0; row < rowData.length; row += 1) {
         for (let cell = 0; cell < rowData[row].cells.length; cell += 1) {
@@ -81,6 +82,7 @@ const CellSelection = () => {
       newRowData[rowIndex].cells[columnIndex].isSelected = !rowData[rowIndex].cells[columnIndex].isSelected;
       setRowData(newRowData);
 
+      // Example illustrates implementation of a Disclosure Manager on selection of a cell.
       disclosureManager.disclose({
         preferredType: 'panel',
         size: 'tiny',
@@ -113,15 +115,15 @@ const CellSelection = () => {
   return (
     <WorklistDataGrid
       id="worklist-data-grid-row-selection"
-      overflowColumns={cols}
-      rows={rowData}
+      overflowColumns={cols} // Column Headers
+      rows={rowData} // Rows with cell data
       rowHeaderIndex={rowHeaderIndex}
       rowHeight="50px"
       defaultColumnWidth={100}
       columnHeaderHeight="100px"
       ariaLabel="Worklist Data Grid With Cell Selection"
-      onCellSelect={onCellSelect}
-      onClearSelectedCells={onClearSelectedCells}
+      onCellSelect={onCellSelect} // For cell selection, a callback function must be provided so that the Worklist Data Grid can invoke it when a cell is selective.
+      onClearSelectedCells={onClearSelectedCells} // To clear the selection of a cell, a callback function must be provided so that the Worklist Data Grid can execute it to clear the selection.
     />
   );
 };

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/PinnedColumns.5.doc.mdx

@@ -1,3 +1,20 @@
 import PinnedColumns from './PinnedColumns?dev-site-example';
 
+# Pinned Columns
+
+### Description
+
+The [Worklist Data Grid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) defines two types of columns: Pinned and Overflow.
+The pinned columns are aligned to the left of the Worklist Data Grid and cannot be scrolled.
+The overflow section is aligned to the right of pinned columns and scrolls horizontally to reveal each overflow column.
+This example demonstrates a Worklist Data Grid that supports both pinned and overflow columns.
+
+
+### Properties required
+* The **pinnedColumns** prop is used to specify columns that need to be aligned left of the grid and stickied.
+
+* The **overflowColumns** prop is used to specify columns that do not need to be stickied and can scroll horizontally.
+
+Columns specified in both these props will rendered in the order in which they are provided.
+
 <PinnedColumns title='Worklist Data Grid with Pinned Columns' />

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/PinnedColumns.jsx

@@ -93,9 +93,9 @@ const PinnedColumns = () => {
 
   return (
     <WorklistDataGrid
-      id="default-terra-worklist-data-grid"
-      pinnedColumns={cols.slice(0, 3)}
-      overflowColumns={cols.slice(3)}
+      id="terra-worklist-data-grid-pinned-columns"
+      pinnedColumns={cols.slice(0, 3)} // This prop must be specified to display columns that need to pinned (stickied).
+      overflowColumns={cols.slice(3)} // This prop must be specified to display columns that do not need to be stickied and can be scrolled horizontally.
       rows={rowData}
       rowHeaderIndex={rowHeaderIndex}
       ariaLabel="Worklist Data Grid"

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/PinnedColumnsWithRowSelection.6.doc.mdx

@@ -1,3 +1,13 @@
-import PinnedColumnsWithRowSelection from './PinnedColumnsWithRowSelection?dev-site-example';
+import PinnedColumnsWithRowSelection from './PinnedColumnsWithRowSelection?dev-site-exaWorklist DataGridmple';
+
+# Pinned Columns with Row Selection
+
+### Description
+
+This example demonstrates a [Worklist Data Grid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) that supports both [Pinned Columns](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/examples/cell-selection) and [Row Selection](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/examples/row-selection) features.
+It is important to note that when Row Selection mode is turned on, the Worklist Data Grid treats row selection cell column as a pinned column.
+
+### Properties required
+Refer to the properties specified in [Pinned Columns](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/examples/cell-selection) and [Row Selection](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/examples/row-selection) examples for details.
 
 <PinnedColumnsWithRowSelection title='Worklist Data Grid with Pinned Columns and Row Selection' />

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/PinnedColumnsWithRowSelection.jsx

@@ -119,18 +119,18 @@ const RowSelection = () => {
       </div>
       <WorklistDataGrid
         id="pinned-columns-with-row-selection"
-        pinnedColumns={cols.slice(0, 3)}
-        overflowColumns={cols.slice(3)}
+        pinnedColumns={cols.slice(0, 3)} // Consumer must specify pinnedColumns prop to display columns that need to pinned (stickied).
+        overflowColumns={cols.slice(3)} // Consumer must specify overflowColumns prop to display columns that do not need to be stickied and can scroll horizontally.
         rows={rowData}
         rowHeaderIndex={rowHeaderIndex}
         defaultColumnWidth={180}
         ariaLabel="Worklist Data Grid with Pinned Columns and Row Selection"
-        hasSelectableRows={hasSelectableRows}
-        onRowSelect={onRowSelect}
-        onRowSelectAll={onRowSelectAll}
-        onClearSelectedRows={clearRowSelection}
-        onDisableSelectableRows={disableSelectableRows}
-        onEnableRowSelection={enableRowSelection}
+        hasSelectableRows={hasSelectableRows} // Prop to turn row selection mode on/off
+        onRowSelect={onRowSelect} // For row selection, consumer must provide a callback that the Worklist Data Grid will call when the user selects one or more rows.
+        onRowSelectAll={onRowSelectAll} // For row selection, consumer must provide a callback that the Worklist Data Grid will call when the user selects all rows.
+        onClearSelectedRows={clearRowSelection} // To clear selected rows, consumer must provide a callback that the Worklist Data Grid will call to clear the selection.
+        onDisableSelectableRows={disableSelectableRows} // Consumer must provide a callback that the Worklist Data Grid will call to turn off the row selection mode.
+        onEnableRowSelection={enableRowSelection} // Consumer must provide a callback that the Worklist Data Grid will call to turn on the row selection mode.
       />
     </React.Fragment>
   );

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/RowSelection.3.doc.mdx

@@ -1,3 +1,39 @@
 import RowSelection from './RowSelection?dev-site-example';
 
-<RowSelection title='Worklist Data Grid With Row Selection' />
+# Row Selection
+
+### Description
+The [Worklist Data Grid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) is built to operate in either of two selection modes:
+* Cell Selection (_default_)
+* **Row Selection**
+
+Row Selection Mode is controlled via a prop and is off by default.
+When creating a Worklist Data Grid that supports Row Selection, the prop has to be explicitly set by the consumer.
+This example demonstrates a Worklist Data Grid with full support for row selection and can be referenced for [row centric functionalities](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/examples/row-selection#implemented-functionality).
+
+### Properties required
+This example demonstrates a Worklist Data Grid with full support for row selection by utilizing the following [Worklist Data Grid properties](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#properties):
+* hasSelectableRows
+* onRowSelect
+* onRowSelectAll
+* onClearSelectedRows
+* onDisableSelectableRows
+* onEnableRowSelection
+
+## Row Selection Interactions
+When using this example, the following row centric outcomes may be achieved by using the respective actions.
+
+|Outcome|Action|
+|---|---|
+|Select a row|When Row Selection is on, click or press Spacebar anywhere on an _unselected_ row.<br/> Shift+Click or press Shift+Spacebar anywhere on an _unselected_ row.|
+|Unselect a row|Click or press Spacebar anywhere on an _selected_ row.|
+|Select all rows|Press Control+A from anywhere on the grid.|
+|Unselect all selected rows|Press Escape from anywhere on the grid.|
+|Select a range of rows|From any row, hold Shift key and press up arrow or down arrow. Continue to press Up and Down arrow to expand or contract the range of rows.<br/>Select any unselected row then Shift+Click or Shift+Space on another row.|
+|Turn Row Selection mode On|In addition to their default grid behavior, Shift+Click, Shift+Space, Shift+Up and Shift+Down will turn Row Selection Mode on if Row Selection Mode is off.|
+|Turn Row Selection mode Off|Press Escape when no rows are selected.|
+
+[All Worklist Data Grid Keyboard Interactions](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#keyboard-interactions)
+
+
+<RowSelection title='Worklist Data Grid With Row Selectionxx' />

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/RowSelection.jsx

@@ -254,13 +254,13 @@ const RowSelection = () => {
         rowHeaderIndex={rowHeaderIndex}
         columnWidth="180px"
         ariaLabel="Worklist Data Grid"
-        hasSelectableRows={hasSelectableRows}
-        onRowSelect={onRowSelect}
-        onRowSelectAll={onRowSelectAll}
-        onClearSelectedRows={clearRowSelection}
-        onDisableSelectableRows={disableSelectableRows}
         onColumnSelect={onColumnSelect}
-        onEnableRowSelection={enableRowSelection}
+        hasSelectableRows={hasSelectableRows} // Prop to turn row selection mode on/off
+        onRowSelect={onRowSelect} // For row selection, consumer must provide a callback that the Worklist DataGrid will call when the user selects one or more rows.
+        onRowSelectAll={onRowSelectAll} // For row selection, consumer must provide a callback that the Worklist DataGrid will call when the user selects all rows.
+        onClearSelectedRows={clearRowSelection} // To clear selected rows, consumer must provide a callback that the Worklist DataGrid will call to clear the selection.
+        onDisableSelectableRows={disableSelectableRows} // Consumer must provide a callback that the Worklist DataGrid will call to turn off the row selection mode.
+        onEnableRowSelection={enableRowSelection} // Consumer must provide a callback that the Worklist DataGrid will call to turn on the row selection mode.
       />
     </React.Fragment>
   );

packages/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/WorklistDataGridColumnStates.4.doc.mdx

@@ -1,3 +1,17 @@
 import WorklistDataGridColumnStates from './WorklistDataGridColumnStates?dev-site-example';
 
+# Column States and Selection
+
+### Description
+This example demonstrates a [Worklist Data Grid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) that supports column states and selection.
+A column can be selected by clicking on the column or pressing the Spacebar on the focused column.
+Only columns that are selectable can be selected. A column is selectable by default.
+
+The Column can display icons representing its current state such as sort indicator and error.
+
+### Properties required
+* The **_onColumnSelect_** callback prop: When the user selects a column, this callback will be called with the columnId of the selected column.
+
+The below example also demonstrates how properties such as _isSelectable_, _hasError_ and _sortIndicator_ can be provided by the consumer to prevent selection, display error and show sort indicator icons respectively.
+
 <WorklistDataGridColumnStates title='Worklist Data Grid Column States' />