import {Meta} from '@storybook/blocks';

import {ExampleCodeBlock} from '@workday/canvas-kit-docs';

import {SelectableRows} from '../examples/Table/WithSelectableRows';

<Meta title="Guides/Accessibility/Table Patterns/Selectable Rows" />

## Selectable Rows

Using a `Checkbox` labeled "Select All" inside of a column header can be a confusing experience for
screen reader users. Screen readers will automatically announce the "Select All" label in the column
header each time users are reading any of the Check boxes in the first column. For instance, the
`Checkbox` in row 4 is definitely not going to select all of the rows. Here is what we did about it:

- We intentionally rendered row 1, column 1 as a standard `<td>` element so screen readers won't
  automatically announce the "Select All" label while reading cells in column 1.
- Our research found that VoiceOver (MacOS v12.7, Safari v17.1) persistently announce "Select All"
  despite using the `<td>` element because of the optional `<thead>` element in the table. We
  omitted the optional `<thead>` and `<tbody>` elements from this example for that reason.
- We used Canvas Kit's `Tooltip` component to assign concise names to each Checkbox, describing
  their purpose of selecting rows. This allows everyone to view the name of the checkboxes by
  hovering the mouse or focusing with the keyboard.
- Since each checkbox is not uniquely labeled, we added `aria-describedby` to the checkbox,
  referencing the unique `id` of the row header cell. This practice gives screen readers more
  context about which value each checkbox is refering to.
- We rendered the cells in column 2 as the row headers for the table, enabling screen readers to
  automatically announce the topping name even while reading down the Amounts in column 3.

<ExampleCodeBlock code={SelectableRows} />