Creation of documentation/implementation guide for Worklist DataGrid #1826
Conversation
| * [Properties](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#properties) | ||
|
|
||
| ## Overview | ||
| The WorklistDataGrid is an [accessible grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) component that allows the user to display data in a table like structure with rows and columns. The grid provides core functionality that a consumer would need while allowing flexibility for the consumers to control specific behavior of the grid based on their requirements. |
There was a problem hiding this comment.
Since this is markdown, consecutive lines are still rendered as a paragraph. Can we have 1 sentence per line for better readability.
| The WorklistDataGrid is an [accessible grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) component that allows the user to display data in a table like structure with rows and columns. The grid provides core functionality that a consumer would need while allowing flexibility for the consumers to control specific behavior of the grid based on their requirements. | |
| The WorklistDataGrid is an [accessible grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) component that allows the user to display data in a table like structure with rows and columns. | |
| The grid provides core functionality that a consumer would need while allowing flexibility for the consumers to control specific behavior of the grid based on their requirements. |
| * [Properties](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#properties) | ||
|
|
||
| ## Overview | ||
| The WorklistDataGrid is an [accessible grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) component that allows the user to display data in a table like structure with rows and columns. The grid provides core functionality that a consumer would need while allowing flexibility for the consumers to control specific behavior of the grid based on their requirements. |
There was a problem hiding this comment.
Update WorklistDataGrid to be Worklist Data Grid throughout the document.
There was a problem hiding this comment.
Adding on to this, if you're a generic name instead of the Terra name of the component, then you can use worklist data grid.
| The WorklistDataGrid is an [accessible grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) component that allows the user to display data in a table like structure with rows and columns. The grid provides core functionality that a consumer would need while allowing flexibility for the consumers to control specific behavior of the grid based on their requirements. | ||
|
|
||
| The WorklistData has a header row and one or more data rows. The columns may allow sorting based on the consumers specification. | ||
| At any given point, only one cell will be focusable and tabbing into the Worklist DataGrid will focus that cell. The arrow keys are used for navigation. See [keyboard interactions](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#keyboard-interactions) for all supported keys. |
There was a problem hiding this comment.
In the overview section, I would maybe reword it to something like the below:
The Worklist Data Grid is an accessible grid component that allows the user to display data in a table like structure of rows and columns. Worklist Data Grids are ideal when you want to layout data in a way that allows for the user to navigate and interact with it while minimizing the need to navigate the user away from the grid.
The Worklist Data Grid displays a header row and one or more rows of data. The component contains only one tab stop with the arrow keys used for primary navigation. See keyboard interactions for all supported keys. Other key features of the component are listed out in the Features section.
|
|
||
| ## Getting Started | ||
| ## Design Decisions | ||
| For the most part, the Worklist DataGrid supports the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) as documented by the ARIA Authoring Practices Guide. |
There was a problem hiding this comment.
| For the most part, the Worklist DataGrid supports the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) as documented by the ARIA Authoring Practices Guide. | |
| The Worklist Data Grid supports the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) as documented by the ARIA Authoring Practices Guide. |
There was a problem hiding this comment.
Accepted and Updated
| * supports only one tab stop. Tabbing into the Worklist DataGrid will either go to the last visited cell, or the first cell upon initial entry. While on the Worklist DataGrid, Tab or Shift+Tab will exit the Worklist DataGrid. | ||
| * does not maintain consumer data state. The states must be maintained by the Consumer. | ||
| * uses callbacks to communicate the actions taken by the user. The callbacks are provided by the Consumer and therefore the implementation is Consumer specific. It is up to the Consumer to determine if and what actions should be taken. For example, the user may click on a selectable cell in the Worklist DataGrid which calls the _onCellSelect_ callback. For Business reasons, the Consumer may decide not to honor that cell selection and instead does nothing resulting in the the cell not getting selected in the WorklistDataGrid. | ||
| * supports specifying multiple columns as sortable. However, at any given instance, sorting is by a single column. |
There was a problem hiding this comment.
| * supports specifying multiple columns as sortable. However, at any given instance, sorting is by a single column. | |
| supports single column sorting with the ability to specify multiple columns as sortable. |
There was a problem hiding this comment.
Accepted and Updated
| |Left Arrow | Moves focus one cell to the left. If focus is on the left-most cell in the row, focus does not move.| | ||
| |Home | Moves focus to the first cell in the row that contains focus.| | ||
| |End | Moves focus to the last cell in the row that contains focus.| | ||
| |Control + Home <br/> or <br/> Ctrl + Command + Left Arrow | Moves focus to the first cell in the first non header row.| |
There was a problem hiding this comment.
| |Control + Home <br/> or <br/> Ctrl + Command + Left Arrow | Moves focus to the first cell in the first non header row.| | |
| |Control + Home <br/> or <br/> Ctrl + Command + Left Arrow (Mac) | Moves focus to the first cell in the first non header row.| |
For the keyboard interactions that are specific to Mac's add a (Mac) after it. To avoid confusion since PC's do not have a Command button.
|
|
||
| ## Component Features | ||
| ## Terra Standards |
There was a problem hiding this comment.
Move the Terra Standards section to the bottom of the page after Properties
|
|
||
| ### Description | ||
|
|
||
| The content of a cell in the [Worklist DataGrid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) may be empty, text, or any combination of widgets. Since the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) mandates only one tab stop and arrow keys for navigation, these keys are not available by default to navigate focusable elements inside a cell. To make these keys available for cell navigation, as part of its basic functionality, the Worklist DataGrid supports single cell navigation (dive-in mode). Enabling single cell navigation will disable grid navigation and disabling single cell navigation will restore grid navigation. |
There was a problem hiding this comment.
| The content of a cell in the [Worklist DataGrid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) may be empty, text, or any combination of widgets. Since the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) mandates only one tab stop and arrow keys for navigation, these keys are not available by default to navigate focusable elements inside a cell. To make these keys available for cell navigation, as part of its basic functionality, the Worklist DataGrid supports single cell navigation (dive-in mode). Enabling single cell navigation will disable grid navigation and disabling single cell navigation will restore grid navigation. | |
| The content of a cell in the [Worklist DataGrid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) may be empty, text, numerical, or any combination of widgets. Since the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) mandates only one tab stop and arrow keys for navigation, these keys are not available by default to navigate focusable elements inside a cell. To make these keys available for cell navigation, as part of its basic functionality, the Worklist DataGrid supports single cell navigation (dive-in mode). Enabling single cell navigation will disable grid navigation and disabling single cell navigation will restore grid navigation. |
|
I removed the Tech Review Required label as this time we do not have a process to engage the Tech Writer team. Those conversations are ongoing but nothing will be finalized by the time you'll need to merge this PR. |
|
@chrismichalewicz We can still keep the label for the designated tech reviewers on the team to utilize. Once we get the process finalized, we can revisit the labels. |
@sdadn Sounds good, I readded it. I just was afraid it would prevent merging or something. |
|
|
||
| ## Getting Started | ||
| ## Design Decisions | ||
| For the most part, the Worklist DataGrid supports the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) as documented by the ARIA Authoring Practices Guide. |
There was a problem hiding this comment.
"For the most part" isn't the best phrasing for a technical document. We can phrase this to:
| For the most part, the Worklist DataGrid supports the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) as documented by the ARIA Authoring Practices Guide. | |
| WorklistDataGrid supports the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) as documented by the ARIA Authoring Practices Guide. |
There was a problem hiding this comment.
Removed in previous commit.
| @@ -14,14 +12,102 @@ import WorklistDataGridColumnStates from './Examples.3/WorklistDataGridColumnSta | |||
| Terra Data Grid is currently under alpha release. There may be breaking changes between releases until it is stable with the 1.0 release. | |||
There was a problem hiding this comment.
| Terra Data Grid is currently under alpha release. There may be breaking changes between releases until it is stable with the 1.0 release. | |
| Terra WorklistDataGrid is currently under alpha release. There may be breaking changes between releases until it is stable with the 1.0 release. |
| * [Properties](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#properties) | ||
|
|
||
| ## Overview | ||
| The WorklistDataGrid is an [accessible grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) component that allows the user to display data in a table like structure with rows and columns. The grid provides core functionality that a consumer would need while allowing flexibility for the consumers to control specific behavior of the grid based on their requirements. |
There was a problem hiding this comment.
Adding on to this, if you're a generic name instead of the Terra name of the component, then you can use worklist data grid.
| The Worklist DataGrid: | ||
| * supports only one tab stop. Tabbing into the Worklist DataGrid will either go to the last visited cell, or the first cell upon initial entry. While on the Worklist DataGrid, Tab or Shift+Tab will exit the Worklist DataGrid. | ||
| * does not maintain consumer data state. The states must be maintained by the Consumer. | ||
| * uses callbacks to communicate the actions taken by the user. The callbacks are provided by the Consumer and therefore the implementation is Consumer specific. It is up to the Consumer to determine if and what actions should be taken. For example, the user may click on a selectable cell in the Worklist DataGrid which calls the _onCellSelect_ callback. For Business reasons, the Consumer may decide not to honor that cell selection and instead does nothing resulting in the the cell not getting selected in the WorklistDataGrid. |
There was a problem hiding this comment.
"Consumer" should be lowercase.
There was a problem hiding this comment.
Changed in previous commit
...ges/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/About.2.doc.mdx
Show resolved
Hide resolved
|
|
||
| ### Description | ||
|
|
||
| The [Worklist DataGrid](/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 DataGrid 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 DataGrid that supports both pinned and overflow columns. |
There was a problem hiding this comment.
| The [Worklist DataGrid](/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 DataGrid 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 DataGrid that supports both pinned and overflow columns. | |
| The [Worklist DataGrid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) defines two types of columns: Pinned and Overflow columns. | |
| Pinned columns will stay stickied to the left of the WorklistDataGrid when scrolling horizontally. | |
| The overflow column section can be scrolled horizontally. | |
| This example demonstrates a WorklistDataGrid that supports both pinned and overflow columns. |
There was a problem hiding this comment.
Changed in previous commit
| * Cell Selection (_default_) | ||
| * **Row Selection** | ||
|
|
||
| Row Selection Mode is controlled via a prop and is off by default. When creating a Worklist DataGrid that supports Row Selection, the prop has to be explicitly set by the Consumer. This example demonstrates a Worklist DataGrid with full support for row selection and can be referenced for [row centric functionalities](http://localhost:8080/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/examples/row-selection#implemented-functionality). |
There was a problem hiding this comment.
| Row Selection Mode is controlled via a prop and is off by default. When creating a Worklist DataGrid that supports Row Selection, the prop has to be explicitly set by the Consumer. This example demonstrates a Worklist DataGrid with full support for row selection and can be referenced for [row centric functionalities](http://localhost:8080/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/examples/row-selection#implemented-functionality). | |
| Row Selection Mode is controlled via a prop and is `false` by default. | |
| When creating a Worklist DataGrid that supports Row Selection, the prop has to be explicitly set. | |
| This example demonstrates a WorklistDataGrid with full support for row selection and can be referenced for [row centric functionalities](http://localhost:8080/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/examples/row-selection#implemented-functionality). |
There was a problem hiding this comment.
Changed sentences in the paragraph to new line in previous commit. I did not take the false keyword suggestion as describing a feature as on/off makes more sense compared to true/false.
| * Cell Selection (_default_) | ||
| * **Row Selection** | ||
|
|
||
| Row Selection Mode is controlled via a prop and is off by default. When creating a Worklist DataGrid that supports Row Selection, the prop has to be explicitly set by the Consumer. This example demonstrates a Worklist DataGrid with full support for row selection and can be referenced for [row centric functionalities](http://localhost:8080/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/examples/row-selection#implemented-functionality). |
There was a problem hiding this comment.
Why is the localhost url referenced here?
There was a problem hiding this comment.
It was by mistake. Removed.
| The content of a cell in the [Worklist DataGrid](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about) may be empty, text, or any combination of widgets. Since the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) mandates only one tab stop and arrow keys for navigation, these keys are not available by default to navigate focusable elements inside a cell. To make these keys available for cell navigation, as part of its basic functionality, the Worklist DataGrid supports single cell navigation (dive-in mode). Enabling single cell navigation will disable grid navigation and disabling single cell navigation will restore grid navigation. | ||
|
|
||
| <span style={{color: 'blue'}}> | ||
| <em>The consumer does not have to implement any callbacks or specify any properties to take advantage of the single cell navigation as it is part of the core functionality of the Worklist DataGrid.</em> |
There was a problem hiding this comment.
| <em>The consumer does not have to implement any callbacks or specify any properties to take advantage of the single cell navigation as it is part of the core functionality of the Worklist DataGrid.</em> | |
| <em>Single Cell navigation is built-in and do not require any additional setup or implementation.</em> |
There was a problem hiding this comment.
Accepted and updated.
There was a problem hiding this comment.
Sorry, made a typo. It should be does not require.
|
From an older PR I know but since we're trying to update the documentation to be ready for consumers, we should fix this: We're using the wrong component for the version badge. |
| @@ -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 DataGrid in `terra-data-grid`. | |||
There was a problem hiding this comment.
| * Added additional documentation and implementation guide in adherence to the newly established documentation template for the examples of Worklist DataGrid 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`. |
| The Worklist Data Grid displays a header row and one or more rows of data. | ||
| The component contains only one tab stop with the arrow keys used for primary navigation. | ||
| See [keyboard interactions](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#keyboard-interactions) for all supported keys. | ||
| Other key features of the component are listed out in the [Features](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#features) section. |
There was a problem hiding this comment.
Tiny nit on wording:
| Other key features of the component are listed out in the [Features](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#features) section. | |
| Other key features of the component are listed in the [Features](/components/cerner-terra-framework-docs/data-grid/worklist-data-grid/about#features) section. |
| The Worklist Data Grid supports the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) as documented by the ARIA Authoring Practices Guide. | ||
|
|
||
| The Worklist Data Grid: | ||
| * supports only one tab stop. Tabbing into the Worklist Data Grid will either go to the last visited cell, or the first cell upon initial entry. |
There was a problem hiding this comment.
I'm wondering if we should be capitalizing the first word of each of these bullet points. I know they are sentence fragments, but IMO capitalization makes bulleted lists look cleaner and easier to scan quickly. I like the style detailed in this article for example.
...ges/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/About.2.doc.mdx
Outdated
Show resolved
Hide resolved
...-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/CellSelection.2.doc.mdx
Outdated
Show resolved
Hide resolved
...mework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/CellSelection.jsx
Outdated
Show resolved
Hide resolved
...terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/PinnedColumnsWithRowSelection.jsx
Outdated
Show resolved
Hide resolved
...k-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/RowSelection.3.doc.mdx
Outdated
Show resolved
Hide resolved
...k-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/RowSelection.3.doc.mdx
Outdated
Show resolved
Hide resolved
...ges/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/About.2.doc.mdx
Outdated
Show resolved
Hide resolved
...ges/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/About.2.doc.mdx
Outdated
Show resolved
Hide resolved
|
|
||
| ## Overview | ||
| The Worklist Data Grid is an [accessible grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) component that allows the user to display data in a table like structure of rows and columns. | ||
| Worklist Data Grids are ideal when you want to layout data in a way that allows for the user to navigate and interact with it while minimizing the need to navigate the user away from the grid. |
There was a problem hiding this comment.
I understand and agree with the intent of this line, but this feels overly generic and confusing. I don't know what "minimizing the need to navigate the user away" means here.
Since we want to merge this soon, I would remove this for now to avoid confusion and then work with @mjpalazzo / @eawww on constructing more specific guidance on WDG's usage.
There was a problem hiding this comment.
Chris provided this line. @chrismichalewicz, can you advise on how to proceed?
There was a problem hiding this comment.
@sdadn That was added based on a conversation we had during one of our review meetings about wanting to provide general guidance on when a consumer would select the Worklist Data Grid over another form of Grid. Thus is intended to be generic. I had reached out to Clayton Beese in UX and he provided this wiki so I did my best to try and summerize it into 1 or 2 sentences and this is the result. It was also posted to UXPLATFORM-9322 with Clatyon and Eric tagged for their thoughts.
"Minimizing the need to navigate the user away" is my attempt at trying to summarize that actionable items that in a more traditional workflow the clinician would have to open a specific part of the patients chart are now within a cell and they can document them without navigating away from the grid.
If this is holding up getting this approved then I am fine if we want to remove it.
...mework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/PinnedColumns.jsx
Outdated
Show resolved
Hide resolved
...mework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/PinnedColumns.jsx
Outdated
Show resolved
Hide resolved
...a-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/WorklistDataGridFocusableCell.doc.mdx
Outdated
Show resolved
Hide resolved
| onCellSelect={onCellSelect} | ||
| onClearSelectedCells={onClearSelectedCells} | ||
| onCellSelect={onCellSelect} // For cell selection, consumer must provide a callback that the Worklist DataGrid will call when the user selects a cell. | ||
| onClearSelectedCells={onClearSelectedCells} // To clear selection of a cell, consumer must provide a callback that the Worklist DataGrid will call to clear the selection. |
There was a problem hiding this comment.
| onClearSelectedCells={onClearSelectedCells} // To clear selection of a cell, consumer must provide a callback that the Worklist DataGrid will call to clear the selection. | |
| onClearSelectedCells={onClearSelectedCells} // To clear the selection of a cell, a callback function must be provided so that the WorklistDataGrid can execute it to clear the selection. |
...ges/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/About.2.doc.mdx
Outdated
Show resolved
Hide resolved
| The Worklist Data Grid supports the [grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) as documented by the ARIA Authoring Practices Guide. | ||
|
|
||
| The Worklist Data Grid: | ||
| * supports only one tab stop. Tabbing into the Worklist Data Grid will either go to the last visited cell, or the first cell upon initial entry. |
| ### Cells | ||
| Cells define the content rendered in a given row, and column. Cells will be rendered in the order given and are expected to be in the same order as the column. | ||
| ### Cell | ||
| Cell defines the content rendered at the intersection of a row and a column. |
There was a problem hiding this comment.
The original usage of Cells was grammatically correct.
| Cell defines the content rendered at the intersection of a row and a column. | |
| Cells defines the content rendered at the intersection of a row and a column. |
There was a problem hiding this comment.
In the rowShape where the array of cells is defined, we use Cells. In this case, we are defining a cell. So, we kept the singular but tweaked the sentence slightly.
...ges/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/About.2.doc.mdx
Outdated
Show resolved
Hide resolved
...ges/terra-framework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/About.2.doc.mdx
Outdated
Show resolved
Hide resolved
|
"Default" looks weird here, I think we should rename the example to
|
Updated to terra-data-grid |
Updated |
...amework-docs/src/terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/RowSelection.jsx
Outdated
Show resolved
Hide resolved
.../terra-dev-site/doc/data-grid/WorklistDataGrid.1/Examples.3/WorklistDataGridColumnStates.jsx
Outdated
Show resolved
Hide resolved
Co-authored-by: Sydney Combs <[email protected]>
Co-authored-by: Sydney Combs <[email protected]>
There was a problem hiding this comment.
Great job on applying the new template! There may be more refinement we can do such as applying the OHAI documentation guide. But this conveys all the necessary information and is usable for consumers. Any additional work can be done in the future as part of the documentation update project.
Summary
Create implementation guide and required documentation for Worklist DataGrid.
Testing
This change was tested using:
Reviews
In addition to engineering reviews, this PR needs:
This PR resolves:
UXPLATFORM-9322