[terra-table] Custom message for masked cells (#1858)

packages/terra-framework-docs/CHANGELOG.md

@@ -9,14 +9,14 @@
 
 * Fixed
   * Fixed the `terra-tabs` icon-only examples keyboard navigation issue.
+  * Fixed broken links in the Worklist Data Grid documentation in `terra-data-grid` component.
 
 * Added
   * Added test for data grid column resizing.
   * Added example for Flowsheet Data Grid containing "No Result" cells.
 
-* Fixed
-  * Fixed the `terra-tabs` icon-only examples keyboard navigation issue.
-  * Fixed broken links in the Worklist Data Grid documentation in `terra-data-grid` component.
+* Updated
+  * Updated `terra-table` example to show providing custom masked cell message label.
 
 ## 1.42.0 - (October 20, 2023)
 

packages/terra-framework-docs/src/terra-dev-site/doc/table/About.1.doc.mdx

@@ -48,3 +48,37 @@ import Table from "terra-table";
 ## Table Props
 
 <TablePropsTable />
+
+### Column
+A column specifies the data to render a cell in the header row of the Worklist Data Grid.
+
+|Name|Type|Is Required|Default Value|Description|
+|---|---|---|---|---|
+|**id**|string|<span style={{color:'#d53040'}}>required</span>|none|An identifier to uniquely identify the column within the grid.|
+|**displayName**|string|optional|none|String of text to render within the column header cell.|
+|**hasError**|bool|optional|none|Boolean value indicating whether or not the column has an error in the data.|
+|**isResizable**|bool|optional|none|Boolean value indicating whether or not the column header is resizable.|
+|**isSelectable**|bool|optional|none|Boolean value indicating whether or not the column header is selectable.|
+|**minimumWidth**|number|optional|none|Number that specifies the minimum column width in pixels.|
+|**maximumWidth**|number|optional|none|Number that specifies the maximum column width in pixels.|
+|**width**|number|optional|none|A number (in px) specifying the width of the column. If not provided, the Data Grid's default column width will be used.|
+|**sortIndicator**|custom|optional|none|A string indicating which sorting indicator should be rendered. If not provided, no sorting indicator will be rendered. One of `ascending`, `descending`.
+
+### Row
+A row defines the cells rendered within the row.
+
+|Name|Type|Is Required|Default Value|Description|
+|---|---|---|---|---|
+|**id**|string|<span style={{color:'#d53040'}}>required</span>|none|An identifier to uniquely identify the row within the grid.|
+|**cells**|array|optional|[]|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.|
+|**isSelected**|bool|optional|none|A boolean indicating whether or not the row should render as selected.|
+|**ariaLabel**|string|optional|none|A string identifier used to describe the row contents. This value will be used for accessibility when announcing the row (un)selection.|
+
+### Cell
+A cell defines the content rendered at the intersection of a row and a column.
+
+|Name|Type|Is Required|Default Value|Description|
+|---|---|---|---|---|
+|**content**|content|optional|none|The content to render within the cell.|
+|**isMasked**|bool|optional|none|A boolean indicating if the cell content is masked.|
+|**maskedLabel**|bool|optional|none|Provides a custom string for masked cells to be read by screen readers. This value is only applied if the cell is masked.|

packages/terra-framework-docs/src/terra-dev-site/doc/table/Examples/DefaultTable.jsx

@@ -25,7 +25,7 @@ const tableData = {
         { content: '' },
         { content: 'Quinzell, Harleen' },
         { content: '' },
-        { isMasked: true },
+        { isMasked: true, maskedLabel: 'Age Hidden' },
         { isMasked: true },
         { content: 'Admitting Physician' },
       ],

packages/terra-table/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+* Added
+  * Added ability for consumers to specify a custom screen reader message for masked cells.
+
 ## 5.1.1-alpha.0 - (October 25, 2023)
 
 * Changed

packages/terra-table/src/proptypes/cellShape.js

@@ -5,15 +5,23 @@ const cellShape = PropTypes.shape({
    * Content that will be rendered within the Cell.
    */
   content: PropTypes.node,
+
   /**
    * Boolean indicating if cell contents are masked.
    */
   isMasked: PropTypes.bool,
+
+  /**
+   * Provides a custom string for masked cells to be read by screen readers. This value is only applied if the cell is masked.
+   */
+  maskedLabel: PropTypes.string,
+
   /**
    * @private
    * Boolean value indicating whether or not the column header is selectable.
    */
   isSelectable: PropTypes.bool,
+
   /**
    * @private
    * Boolean value indicating whether or not the cell should render as selected.

packages/terra-table/src/subcomponents/Cell.jsx

@@ -56,6 +56,11 @@ const propTypes = {
    */
   isMasked: PropTypes.bool,
 
+  /**
+   * Provides a custom string for masked cells to be read by screen readers. This value is only applied if the cell is masked.
+   */
+  maskedLabel: PropTypes.string,
+
   /**
    * Boolean value indicating whether or not the column header is selectable.
    */
@@ -106,6 +111,7 @@ function Cell(props) {
     columnIndex,
     ariaLabel,
     isMasked,
+    maskedLabel,
     isRowHeader,
     isSelectable,
     isSelected,
@@ -205,7 +211,7 @@ function Cell(props) {
   if (isMasked) {
     cellContent = (
       <span className={cx('no-data-cell', theme.className)}>
-        {intl.formatMessage({ id: 'Terra.table.maskedCell' })}
+        {maskedLabel || intl.formatMessage({ id: 'Terra.table.maskedCell' })}
       </span>
     );
   } else if (!children) {

packages/terra-table/src/subcomponents/Row.jsx

@@ -134,6 +134,7 @@ function Row(props) {
           key={`${id}_${displayedColumns[cellColumnIndex].id}`}
           isSelected={!hasRowSelection && cellData.isSelected}
           isMasked={cellData.isMasked}
+          maskedLabel={cellData.maskedLabel}
           isSelectable={cellData.isSelectable}
           isRowHeader={cellColumnIndex === rowHeaderIndex}
           isHighlighted={isHovered || isSelected}

packages/terra-table/tests/jest/Cell.test.jsx

@@ -252,6 +252,35 @@ describe('Cell', () => {
     expect(wrapper).toMatchSnapshot();
   });
 
+  it('verifies that a cell has renders that masked label text, when provided', () => {
+    const wrapper = shallowWithIntl(
+      <IntlProvider locale="en">
+        <Cell
+          rowId="RowID"
+          columnId="ColumnId"
+          ariaLabel="Some Label Here"
+          rowIndex={1}
+          columnIndex={2}
+          key="key"
+          isMasked
+          maskedLabel="MaskedLabel"
+          onCellSelect={jest.fn}
+        >
+          Data in cell
+        </Cell>
+      </IntlProvider>,
+    ).dive().dive();
+
+    const maskedCell = wrapper.find('td.masked');
+    expect(maskedCell).toHaveLength(1);
+
+    const cellContent = maskedCell.find('div');
+    expect(cellContent.text()).toBe('MaskedLabel');
+    expect(cellContent).toHaveLength(1);
+
+    expect(wrapper).toMatchSnapshot();
+  });
+
   it('verifies mask takes precedence when cell is masked, selectable and selected', () => {
     const wrapper = shallowWithIntl(
       <IntlProvider locale="en">

packages/terra-table/tests/jest/__snapshots__/Cell.test.jsx.snap

@@ -105,6 +105,33 @@ exports[`Cell verifies mask takes precedence when cell is masked, selectable and
 </td>
 `;
 
+exports[`Cell verifies that a cell has renders that masked label text, when provided 1`] = `
+<td
+  aria-label="Some Label Here"
+  className="cell masked"
+  style={
+    Object {
+      "left": null,
+    }
+  }
+>
+  <div
+    className="cell-content"
+    style={
+      Object {
+        "height": undefined,
+      }
+    }
+  >
+    <span
+      className="no-data-cell"
+    >
+      MaskedLabel
+    </span>
+  </div>
+</td>
+`;
+
 exports[`Cell verifies that a cell has the correct styles and no content when isMasked prop is true 1`] = `
 <td
   aria-label="Some Label Here"