From d0241fc0cbad0e8ee8ddb1a327bf65af4037c175 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Wed, 17 Sep 2025 16:37:14 -0700 Subject: [PATCH 1/3] docs(table): update a11y docs --- packages/table/README.md | 476 ++++++++++++++++++--------------------- 1 file changed, 214 insertions(+), 262 deletions(-) diff --git a/packages/table/README.md b/packages/table/README.md index 3d34aaeaaa9..9d415b04e98 100644 --- a/packages/table/README.md +++ b/packages/table/README.md @@ -1,25 +1,26 @@ -## Description +## Overview -An `` is used to create a container for displaying information. It allows users to sort, compare, and take action on large amounts of data. +An `` is used to create a container for displaying information. It allows users to quickly scan, sort, compare, and take action on large amounts of data. Tables are essential for organizing and presenting structured information in a clear, accessible format. ### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/table?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/table) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/table?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/table) +[![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-2ilo6nmh) -``` +```zsh yarn add @spectrum-web-components/table ``` -Import the side effectful registration of ``, ``, ``, ``, ``, ``. and `` via: +Import the side effectful registration of ``, ``, ``, ``, ``, ``, and `` via: -``` +```js import '@spectrum-web-components/table/elements.js'; ``` Or individually via: -``` +```js import '@spectrum-web-components/table/sp-table.js'; import '@spectrum-web-components/table/sp-table-body.js'; import '@spectrum-web-components/table/sp-table-cell.js'; @@ -31,7 +32,7 @@ import '@spectrum-web-components/table/sp-table-row.js'; When looking to leverage the `Table`, `TableBody`, `TableCell`, `TableCheckboxCell`, `TableHead`, `TableHeadCell`, or `TableRow` base classes as a type and/or for extension purposes, do so via: -``` +```js import { Table, TableBody, @@ -39,205 +40,128 @@ import { TableCheckboxCell, TableHead, TableHeadCell, - TableRow + TableRow, } from '@spectrum-web-components/table'; ``` ## Example -```html +```html demo - Column Title - Column Title - Column Title + File name + Type + Size + Status - Row Item Alpha - Row Item Alpha - Row Item Alpha - - - Row Item Bravo - Row Item Bravo - Row Item Bravo + Budget + PDF + 89 KB + Reviewed - Row Item Charlie - Row Item Charlie - Row Item Charlie + Onboarding + XLS + 120 KB + Draft - Row Item Delta - Row Item Delta - Row Item Delta - - - Row Item Echo - Row Item Echo - Row Item Echo + Proposal + PDF + 139 KB + Published ``` -## Selection +### Options -To manage selection on an ``, utilise the `selects` attribute on ``. Each `` has a `value` attribute which, by default, corresponds to its index in the table, and these `value`s tell `` which ``s are selected. The selected items can be manually applied via the `selected` property on the table. + +Selection + -### `selects="single"` +The `selects` attribute enables row selection functionality. When `selects="single"`, users can select one row at a time. When `selects="multiple"`, users can select multiple rows and a checkbox column is automatically added to the table header for select all functionality. -When `selects="single"`, the `` will manage a _single_ selection in the array value of `selected`. - -```html - +```html demo + - Column Title - Column Title - Column Title + File name + Type + Size - Row Item Alpha - Row Item Alpha - Row Item Alpha + Budget + PDF + 89 KB - Row Item Bravo - Row Item Bravo - Row Item Bravo - - - Row Item Charlie - Row Item Charlie - Row Item Charlie - - - Row Item Delta - Row Item Delta - Row Item Delta - - - Row Item Echo - Row Item Echo - Row Item Echo + Onboarding + XLS + 120 KB ``` -### `selects="multiple"` - -When `selects="multiple"`, the `` manages selections via a presence toggle and adds them to the `selected` array. Additionally, an `` will be made available in the `` in order to select/deselect all items in the ``. - -```html - - - Column Title - Column Title - Column Title - - - - Row Item Alpha - Row Item Alpha - Row Item Alpha - - - Row Item Bravo - Row Item Bravo - Row Item Bravo - - - Row Item Charlie - Row Item Charlie - Row Item Charlie - - - Row Item Delta - Row Item Delta - Row Item Delta - - - Row Item Echo - Row Item Echo - Row Item Echo - - - -``` - -## Emphasized + +Emphasized + -Use the `emphasized` attribute to add priority to the information that is delivered within your `` element. In particular, this affects the appearance of selected rows, and will set the emphasized style for the checkboxes within `sp-table-checkbox-cell`. -Leaving off the `emphasized` attribute will display the non-emphasized colors. +The `emphasized` attribute adds visual priority to the table content. This affects the appearance of selected rows and checkboxes, providing a more prominent visual treatment. -```html +```html demo - Column Title - Column Title - Column Title + File name + Type + Size - Row Item Alpha - Row Item Alpha - Row Item Alpha + Budget + PDF + 89 KB - Row Item Bravo - Row Item Bravo - Row Item Bravo - - - Row Item Charlie - Row Item Charlie - Row Item Charlie + Onboarding + XLS + 120 KB ``` -## Density + +Density + -The optional `density` property changes the spacing around table cell content from the "regular" default. It accepts the values of `compact` or `spacious`. +The `density` attribute controls the spacing around table cell content. Available values are `compact` for tighter spacing and `spacious` for more generous spacing. - + Compact -```html +```html demo - Column Title - Column Title - Column Title + File name + Type + Size - - Row Item Alpha - Row Item Alpha - Row Item Alpha - - - Row Item Bravo - Row Item Bravo - Row Item Bravo + + Budget + PDF + 89 KB - - Row Item Charlie - Row Item Charlie - Row Item Charlie + + Onboarding + XLS + 120 KB @@ -247,28 +171,23 @@ The optional `density` property changes the spacing around table cell content fr Spacious -```html +```html demo - Column Title - Column Title - Column Title + File name + Type + Size - - Row Item Alpha - Row Item Alpha - Row Item Alpha - - - Row Item Bravo - Row Item Bravo - Row Item Bravo + + Budget + PDF + 89 KB - - Row Item Charlie - Row Item Charlie - Row Item Charlie + + Onboarding + XLS + 120 KB @@ -277,34 +196,33 @@ The optional `density` property changes the spacing around table cell content fr -## Sizes + +Size + + +The `size` attribute controls the overall size of the table. Available values are `s` (small), `m` (medium, default), `l` (large), and `xl` (extra large). - + Small -```html +```html demo - Column Title - Column Title - Column Title + File name + Type + Size - - Row Item Alpha - Row Item Alpha - Row Item Alpha - - - Row Item Bravo - Row Item Bravo - Row Item Bravo + + Budget + PDF + 89 KB - - Row Item Charlie - Row Item Charlie - Row Item Charlie + + Onboarding + XLS + 120 KB @@ -314,28 +232,23 @@ The optional `density` property changes the spacing around table cell content fr Medium (Default) -```html +```html demo - Column Title - Column Title - Column Title + File name + Type + Size - - Row Item Alpha - Row Item Alpha - Row Item Alpha - - - Row Item Bravo - Row Item Bravo - Row Item Bravo + + Budget + PDF + 89 KB - - Row Item Charlie - Row Item Charlie - Row Item Charlie + + Onboarding + XLS + 120 KB @@ -345,28 +258,23 @@ The optional `density` property changes the spacing around table cell content fr Large -```html +```html demo - Column Title - Column Title - Column Title + File name + Type + Size - - Row Item Alpha - Row Item Alpha - Row Item Alpha - - - Row Item Bravo - Row Item Bravo - Row Item Bravo + + Budget + PDF + 89 KB - - Row Item Charlie - Row Item Charlie - Row Item Charlie + + Onboarding + XLS + 120 KB @@ -376,28 +284,23 @@ The optional `density` property changes the spacing around table cell content fr Extra Large -```html +```html demo - Column Title - Column Title - Column Title + File name + Type + Size - - Row Item Alpha - Row Item Alpha - Row Item Alpha - - - Row Item Bravo - Row Item Bravo - Row Item Bravo + + Budget + PDF + 89 KB - - Row Item Charlie - Row Item Charlie - Row Item Charlie + + Onboarding + XLS + 120 KB @@ -406,38 +309,38 @@ The optional `density` property changes the spacing around table cell content fr -## Quiet + +Quiet + -When using the `quiet` property, the overall look of the table will change. The quiet variant of Table has a transparent background and no borders on the left and right. +The `quiet` attribute creates a more subtle table appearance with a transparent background and no side borders. This is ideal for supplementary or lightweight data display. -```html +```html demo - Column Title - Column Title - Column Title + File name + Type + Size - - Row Item Alpha - Row Item Alpha - Row Item Alpha - - - Row Item Bravo - Row Item Bravo - Row Item Bravo + + Budget + PDF + 89 KB - - Row Item Charlie - Row Item Charlie - Row Item Charlie + + Onboarding + XLS + 120 KB ``` -## Virtualized Table + + + +## Virtualized tables For large amounts of data, the `` can be virtualised to easily add table rows by using properties. @@ -507,7 +410,7 @@ For large amounts of data, the `` can be virtualised to easily add tab await table.closest('code-example')?.updateComplete; table.items = initItems(50); - table.renderItem = (item, index) => { + table.renderItem = (item, index) => { const cell1 = document.createElement('sp-table-cell'); const cell2 = document.createElement('sp-table-cell'); const cell3 = document.createElement('sp-table-cell'); @@ -559,7 +462,7 @@ const renderItem = (item: Item, index: number): TemplateResult => { Please note that there is a bug when attempting to select all virtualised elements. The items are selected programatically, it's just not reflected visually. -### Selection +### Virtualized table selection By default the `selected` property will surface an array of item indexes that are currently selected. However, when making a selection on a virtualized table, it can be useful to track selection as something other than indexes. To do so, set a custom method for the `itemValue` property. The `itemValue` method accepts an item and its index as arguments and should return the value you would like to track in the `selected` property. @@ -639,7 +542,7 @@ By default the `selected` property will surface an array of item indexes that ar table.items = initItems(50); table.itemValue = (item) => item.id; - table.renderItem = (item, index) => { + table.renderItem = (item, index) => { const cell1 = document.createElement('sp-table-cell'); const cell2 = document.createElement('sp-table-cell'); const cell3 = document.createElement('sp-table-cell'); @@ -745,8 +648,7 @@ All values in the item array are assumed to be homogenous by default. This means }); table.items = items; - - table.renderItem = (item, index) => { + table.renderItem = (item, index) => { if (item._$rowType$ === 1) { const infoCell = document.createElement('sp-table-cell'); infoCell.textContent = 'Use this row type for non-selectable content.'; @@ -865,7 +767,7 @@ For each table column you want to sort, use the `sortable` attribute in its resp table.items = items; - table.renderItem = (item, index) => { + table.renderItem = (item, index) => { const cell1 = document.createElement('sp-table-cell'); const cell2 = document.createElement('sp-table-cell'); const cell3 = document.createElement('sp-table-cell'); @@ -893,3 +795,53 @@ For each table column you want to sort, use the `sortable` attribute in its resp }); }); + +## Accessibility + +The `` component provides accessibility support for tabular data: + +### ARIA attributes + +The table automatically manages ARIA attributes for proper semantic structure: + +- `role="grid"` on the table element +- `role="row"` on each table row +- `role="columnheader"` on header cells +- `role="gridcell"` on data cells +- `role="rowgroup"` on table body +- `aria-sort` on sortable column headers +- `aria-selected` on selectable rows +- `aria-hidden` on single selection checkboxes +- `aria-rowindex` on virtualized table rows +- `aria-rowcount` on virtualized tables + +### Selection accessibility + +When using row selection: + +- `aria-selected` is applied to selectable rows +- Selection state is announced to screen readers +- Checkboxes in selection cells are properly labeled + +### Keyboard navigation + +#### Sortable column headers + +Sortable column headers support keyboard interaction: + +- **Space** - Activates the header and sorts on keyup +- **Enter** - Immediately sorts the column +- **Numpad Enter** - Immediately sorts the column +- **Tab** - Navigates to sortable headers (only sortable headers are focusable) + +#### Row selection + +Selectable rows support keyboard interaction: + +- **Click** - Toggles row selection +- **Tab** - Navigates through focusable elements + +#### Scrollable tables + +- **Tab** - Table body automatically receives `tabindex="0"` when content is scrollable +- **Mouse wheel** - Scrolls through table content when focused From b3650438e4614d1239c834e6c8549a70265c5d87 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Tue, 23 Sep 2025 08:22:41 -0700 Subject: [PATCH 2/3] chore(docs): address feedback --- packages/table/README.md | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/packages/table/README.md b/packages/table/README.md index 9d415b04e98..dd2fdc898a8 100644 --- a/packages/table/README.md +++ b/packages/table/README.md @@ -44,7 +44,15 @@ import { } from '@spectrum-web-components/table'; ``` -## Example +### Anatomy + +A table consists of the following parts: + +- a table head section (``) +- header cells (``) within the table head section +- a table body section, ie.`` +- rows (``) within the table body section +- body cells (``) within the table body rows ```html demo @@ -340,7 +348,7 @@ The `quiet` attribute creates a more subtle table appearance with a transparent -## Virtualized tables +### Behaviors For large amounts of data, the `` can be virtualised to easily add table rows by using properties. @@ -427,7 +435,7 @@ For large amounts of data, the `` can be virtualised to easily add tab }); -### How to use it +#### How to use it The virtualised table takes `items` as either a property or a JSON-encoded string, an array of type `Record`, where the key is a `string` and the value can be whatever you'd like. `items` is then fed into the `renderItem` method, which takes an `item` and its `index` as parameters and renders the `` for each item. An example is as follows: @@ -462,7 +470,7 @@ const renderItem = (item: Item, index: number): TemplateResult => { Please note that there is a bug when attempting to select all virtualised elements. The items are selected programatically, it's just not reflected visually. -### Virtualized table selection +#### Virtualized table selection By default the `selected` property will surface an array of item indexes that are currently selected. However, when making a selection on a virtualized table, it can be useful to track selection as something other than indexes. To do so, set a custom method for the `itemValue` property. The `itemValue` method accepts an item and its index as arguments and should return the value you would like to track in the `selected` property. @@ -564,7 +572,7 @@ By default the `selected` property will surface an array of item indexes that ar }); -### Row Types +#### Row Types All values in the item array are assumed to be homogenous by default. This means all of the rendered rows are either delivered as provided, or, in the case you are leveraging `selects`, rendered with an ``. However, when virtualizing a table with selection, it can sometimes be useful to surface rows with additional interactions, e.g. "Load more data" links. To support that, you can optionally include the `_$rowType$` brand in your item. The values for this are outlined by the `RowType` enum and include `ITEM` (0) and `INFORMATION` (1). When `_$rowType$: RowType.INFORMATION` is provided, it instructs the `` not to deliver an `` in that row. @@ -670,7 +678,7 @@ All values in the item array are assumed to be homogenous by default. This means }); -### The `scroller` property +#### The `scroller` property By default, the virtualized table doesn't contain a scroll bar and will display the entire length of the table body. Use the `scroller` property and specify an inline style for the height to get a `Table` of your desired height that scrolls. @@ -796,11 +804,11 @@ For each table column you want to sort, use the `sortable` attribute in its resp }); -## Accessibility +### Accessibility The `` component provides accessibility support for tabular data: -### ARIA attributes +#### ARIA attributes The table automatically manages ARIA attributes for proper semantic structure: @@ -815,7 +823,7 @@ The table automatically manages ARIA attributes for proper semantic structure: - `aria-rowindex` on virtualized table rows - `aria-rowcount` on virtualized tables -### Selection accessibility +#### Selection accessibility When using row selection: @@ -823,9 +831,7 @@ When using row selection: - Selection state is announced to screen readers - Checkboxes in selection cells are properly labeled -### Keyboard navigation - -#### Sortable column headers +#### Keyboard navigation Sortable column headers support keyboard interaction: @@ -834,14 +840,10 @@ Sortable column headers support keyboard interaction: - **Numpad Enter** - Immediately sorts the column - **Tab** - Navigates to sortable headers (only sortable headers are focusable) -#### Row selection - Selectable rows support keyboard interaction: - **Click** - Toggles row selection - **Tab** - Navigates through focusable elements -#### Scrollable tables - - **Tab** - Table body automatically receives `tabindex="0"` when content is scrollable - **Mouse wheel** - Scrolls through table content when focused From e21d5093aabcb894b1973085f2ad223aac2bd8e4 Mon Sep 17 00:00:00 2001 From: Cory Dransfeldt Date: Thu, 25 Sep 2025 08:13:12 -0700 Subject: [PATCH 3/3] Update packages/table/README.md Co-authored-by: [ Cassondra ] --- packages/table/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/table/README.md b/packages/table/README.md index dd2fdc898a8..5cbd7d4bfe5 100644 --- a/packages/table/README.md +++ b/packages/table/README.md @@ -87,7 +87,7 @@ A table consists of the following parts: ### Options - + Selection