@workday/canvas-kit-docs 16.0.13 → 16.0.15

package/dist/es6/lib/docs.js

@@ -13367,6 +13367,26 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
           "kind": "string",
           "value": "tables"
         },
+        {
+          "kind": "string",
+          "value": "expandable-rows"
+        },
+        {
+          "kind": "string",
+          "value": "nested-rows"
+        },
+        {
+          "kind": "string",
+          "value": "selectable-rows"
+        },
+        {
+          "kind": "string",
+          "value": "filterable-column-headers"
+        },
+        {
+          "kind": "string",
+          "value": "sortable-column-headers"
+        },
         {
           "kind": "string",
           "value": "popups"
@@ -13431,6 +13451,26 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
             "kind": "string",
             "value": "tables"
           },
+          {
+            "kind": "string",
+            "value": "expandable-rows"
+          },
+          {
+            "kind": "string",
+            "value": "nested-rows"
+          },
+          {
+            "kind": "string",
+            "value": "selectable-rows"
+          },
+          {
+            "kind": "string",
+            "value": "filterable-column-headers"
+          },
+          {
+            "kind": "string",
+            "value": "sortable-column-headers"
+          },
           {
             "kind": "string",
             "value": "popups"
@@ -13459,6 +13499,23 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
       }
     }
   },
+  {
+    "name": "TABLE_PATTERN_SCENARIOS",
+    "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/mcp/lib/accessibility-enums.ts",
+    "description": "Pattern pages under Guides/Accessibility/Table Patterns, including the overview index.",
+    "declarations": [
+      {
+        "name": "TABLE_PATTERN_SCENARIOS",
+        "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/mcp/lib/accessibility-enums.ts"
+      }
+    ],
+    "tags": {},
+    "type": {
+      "kind": "unknown",
+      "value": "unknown",
+      "text": "readonly AccessibilityScenario[]"
+    }
+  },
   {
     "name": "ACCESSIBILITY_COMPONENTS",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/mcp/lib/accessibility-enums.ts",
@@ -13960,7 +14017,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
         "value": {
           "kind": "symbol",
           "name": "AccessibilityScenario",
-          "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"popups\" | \"headers\" | \"side-panel\" | \"windows-high-contrast\" | \"forms\" | \"color-contrast\""
+          "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"expandable-rows\" | \"nested-rows\" | \"selectable-rows\" | \"filterable-column-headers\" | \"sortable-column-headers\" | ... 5 more ... | \"color-contrast\""
         }
       }
     }
@@ -14009,7 +14066,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
                 "type": {
                   "kind": "symbol",
                   "name": "AccessibilityScenario",
-                  "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"popups\" | \"headers\" | \"side-panel\" | \"windows-high-contrast\" | \"forms\" | \"color-contrast\""
+                  "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"expandable-rows\" | \"nested-rows\" | \"selectable-rows\" | \"filterable-column-headers\" | \"sortable-column-headers\" | ... 5 more ... | \"color-contrast\""
                 },
                 "description": "",
                 "declarations": [
@@ -14040,7 +14097,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
         "value": {
           "kind": "symbol",
           "name": "AccessibilityScenario",
-          "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"popups\" | \"headers\" | \"side-panel\" | \"windows-high-contrast\" | \"forms\" | \"color-contrast\""
+          "value": "\"aria-live\" | \"overview\" | \"page-structure\" | \"tables\" | \"expandable-rows\" | \"nested-rows\" | \"selectable-rows\" | \"filterable-column-headers\" | \"sortable-column-headers\" | ... 5 more ... | \"color-contrast\""
         }
       }
     }
@@ -47918,7 +47975,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
     "type": {
       "kind": "enhancedComponent",
       "componentType": "subcomponent",
-      "elemPropsHook": "useMultiSelectInput",
+      "elemPropsHook": "useMultiSelectSearchInput",
       "props": [
         {
           "kind": "property",

package/dist/es6/lib/specs.js

@@ -2719,6 +2719,48 @@ module.exports = {specifications: [
       }
     ]
   },
+  {
+    "type": "file",
+    "name": "MultiSelect",
+    "children": [
+      {
+        "type": "describe",
+        "name": "MultiSelect",
+        "children": [
+          {
+            "type": "describe",
+            "name": "given the Searching story is rendered",
+            "children": [
+              {
+                "type": "describe",
+                "name": "when Enter is pressed before typing",
+                "children": [
+                  {
+                    "type": "it",
+                    "name": "should keep the listbox hidden"
+                  }
+                ]
+              },
+              {
+                "type": "describe",
+                "name": "when search text is entered using the keyboard",
+                "children": [
+                  {
+                    "type": "it",
+                    "name": "should not have any axe errors"
+                  },
+                  {
+                    "type": "it",
+                    "name": "should open the listbox with the filtered result"
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
   {
     "type": "file",
     "name": "Pagination",

package/dist/es6/lib/stackblitzFiles/packageJSONFile.js

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "16.0.13",
-    "@workday/canvas-kit-preview-react": "16.0.13",
-    "@workday/canvas-kit-react": "16.0.13",
-    "@workday/canvas-kit-react-fonts": "^16.0.13",
-    "@workday/canvas-kit-styling": "16.0.13",
+    "@workday/canvas-kit-labs-react": "16.0.15",
+    "@workday/canvas-kit-preview-react": "16.0.15",
+    "@workday/canvas-kit-react": "16.0.15",
+    "@workday/canvas-kit-react-fonts": "^16.0.15",
+    "@workday/canvas-kit-styling": "16.0.15",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts

@@ -19,11 +19,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "16.0.13",
-    "@workday/canvas-kit-preview-react": "16.0.13",
-    "@workday/canvas-kit-react": "16.0.13",
-    "@workday/canvas-kit-react-fonts": "^16.0.13",
-    "@workday/canvas-kit-styling": "16.0.13",
+    "@workday/canvas-kit-labs-react": "16.0.15",
+    "@workday/canvas-kit-preview-react": "16.0.15",
+    "@workday/canvas-kit-react": "16.0.15",
+    "@workday/canvas-kit-react-fonts": "^16.0.15",
+    "@workday/canvas-kit-styling": "16.0.15",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/mdx/accessibility/Popups.mdx

@@ -44,10 +44,6 @@ hooks. **Tradeoff:** the popup is constrained by ancestor `overflow` and positio
 
 <ExampleCodeBlock code={InlinePopupNoPortal} />
 
-For the same reading-order goal using a **portaled** popup mounted into a sentinel next to the
-trigger (with `PopupStack.pushStackContext`), see
-[**Testing > Inline Portals**](?path=/docs/guides-accessibility-testing-inline-portals--docs).
-
 ## 2. Reading order with `aria-owns`
 
 You can keep the default portal (content at the bottom of `body`) and still try to **re-parent** the
@@ -67,6 +63,6 @@ that card as “owned” by the trigger for browsing and announcements.
 The Canvas Kit [**Dialog**](?path=/docs/components-popups-dialog--docs) builds this pattern in.
 
 Another `aria-owns` example:
-[Advanced Tables > Table With Filterable Column Headers](?path=/docs/guides-accessibility-examples-advanced-tables--docs#filterable-column-headers).
+[Table Patterns > Filterable Column Headers](?path=/docs/guides-accessibility-table-patterns-filterable-column-headers--docs).
 
 <ExampleCodeBlock code={PopupAriaOwns} />

package/dist/mdx/accessibility/tables/ExpandableRows.mdx

@@ -0,0 +1,27 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {ExpandableRows} from '../examples/Table/WithExpandableRows';
+
+
+## Expandable Rows
+
+Expandable Rows combines the likes of an accordion with tabular data tables. Column 1 renders icon
+buttons with 2 states, a collapsed and expanded state. A new row that spans the entire width of the
+table is added to the table just after the expanded row.
+
+- The `aria-expanded` property is added to the chevron button to communicate this state to screen
+  reader users.
+- A Canvas accessible `Tooltip` component is used to assign names to each icon button based on the
+  most useful value in the row. In this example, we combined the car make (in column 1) and model
+  (in column 2) together. This allows everyone to view the name of the icon buttons by hovering the
+  mouse or focusing with the keyboard.
+- The expanded row uses `colspan` to span the entire width of the table and support screen readers.
+  This space provides flexibility to show headings, lists, and other structured content for the
+  table row above.
+- There is no explicit relationship between a row of cells and the spanned content below it. The
+  spanned content is assumed to belong to the row of cells above it, based on established accordion
+  patterns and logical reading order of content rendered to the screen.
+- Outlining hierarchy with additional nested rows in the table is not supported for screen readers
+  in this example.
+
+<ExampleCodeBlock code={ExpandableRows} />

package/dist/mdx/accessibility/tables/FilterableColumnHeaders.mdx

@@ -0,0 +1,37 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {FilterableColumnHeaders} from '../examples/Table/WithColumnHeaderFilters';
+
+
+## Filterable Column Headers
+
+In this example, we demonstrate using the `Popup` component in each column header allowing users to
+search and filter the data on the table. The `Popup` component relies on React Portals to render the
+popup elements at the bottom of the browser's DOM presenting 2 key challenges for accessibility:
+
+1. Keyboard focus order of the elements in the popup,
+2. Screen readers' reading order of the content rendered in the browser.
+
+Here's what we did about it:
+
+- Canvas Kit includes a `usePopupModel` hook, with quite a few additional hooks developers can add
+  to their models. In particular, the `useFocusRedirect` hook manages keyboard focus between the
+  `<Popup.Target>` button and the popup content.
+- The `useInitialFocus` hook allows developers to specify which element receives keyboard focus when
+  the popup appears. In this example, we auto-focused the search input field.
+- To address the reading order of content, we set the `aria-owns` property onto the parent
+  `<Table.Header>` component (`<th>` DOM element) with 2 unique `id` values. The first `id` refers
+  to the `<Popup.Target>` button and the second refers to the `<Popup.Card>` container element. This
+  manually reassigns the column header's `<Popup.Target>` button and the `Popup` contents as
+  siblings in the browser's accessibility tree hierarchy. Screen readers **should** read the column
+  header buttons and the popup content in sequential order even though they are not siblings in the
+  DOM.
+- The `type='description'` variant of the Canvas `Tooltip` is used to communicate the filtered state
+  of the column header, and assigned to the accessible description of the column header
+  `<TertiaryButton>` component.
+- The `AriaLiveRegion` component is used to render the "X of Y items" status inside the table
+  caption. This enables screen readers to automatically describe the filter state changes of the
+  table content to users in real time. We recommend validating whether this use of a live region is
+  well supported for your screen reader and browser combinations first.
+
+<ExampleCodeBlock code={FilterableColumnHeaders} />

package/dist/mdx/accessibility/tables/NestedRows.mdx

@@ -0,0 +1,38 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {NestedRows} from '../examples/Table/WithNestedRows';
+
+
+## Nested Rows
+
+Nested Rows shows a hierarchy of related records in **one table**, using additional `<tr>` elements
+for child rows. Expanding a project reveals its phases; expanding a phase reveals its tasks. The
+chevron and name share the Name cell so they indent together. Collapsing a parent hides its
+descendants even if a child was previously expanded.
+
+This is a different pattern from
+[Expandable Rows](?path=/docs/guides-accessibility-table-patterns-expandable-rows--docs). That
+example inserts a `colspan` panel with extra content for a single parent row. It does **not** add
+nested table rows. Use Nested Rows when the children are themselves tabular records (same columns at
+every level). Use Expandable Rows when the extra content is not a row of the same table.
+
+- Child rows are siblings in the same `<tbody>`, not a nested `<table>` and not extra `<tbody>`
+  elements used to fake a tree.
+- The Name cell is the tree column: it holds the chevron `TertiaryButton` and the row name together
+  so the control stays next to the label it expands. Leaf rows keep an empty slot the same width as
+  the button so names line up with their siblings.
+- The `aria-expanded` property is added to the chevron button to communicate this state to screen
+  reader users.
+- A Canvas Kit `Tooltip` names each chevron **Project**, **Phase**, or **Task** based on the row's
+  depth. The visible name stays in the row header, so the button name describes the _kind_ of row
+  rather than repeating the label.
+- Since those button names are not unique, we added `aria-describedby` to each chevron, referencing
+  the unique `id` on the name text in the same cell. That gives screen readers the specific project
+  or phase the control belongs to, similar to the
+  [Selectable Rows](?path=/docs/guides-accessibility-table-patterns-selectable-rows--docs)
+  checkboxes.
+- `aria-level` is set on each `Table.Row` (`1` = project, `2` = phase, `3` = task) to describe
+  depth. Support for `aria-level` on HTML table rows is uneven across screen readers and browsers.
+  Validate the combinations you support. This is a research example, not a Canvas Kit primitive.
+
+<ExampleCodeBlock code={NestedRows} />

package/dist/mdx/accessibility/tables/Overview.mdx

@@ -0,0 +1,28 @@
+## Advanced Table Examples
+
+Tables should only be used to organize data that has a clear relationship between rows and columns,
+like a calendar or a schedule. Never use a table just for page layout.
+
+When you use the proper HTML table markup, a screen reader can help a user navigate the table. It
+will automatically read the column and row headers as they move through the data, so they always
+know what information they're looking at.
+
+- All tables should have a clear header and a descriptive title.
+- Keep your tables simple. If a table is too complex, it might be better to break it up into several
+  smaller tables or use a different format.
+
+Out of the box, `Table` is a lightweight compound component with a high degree of flexibility, but
+not much functionality outside of providing a basic table layout. This flexibility lets developers
+implement common features, such as selecting rows and sorting columns, on top of `Table` to meet
+their specific application needs.
+
+The Workday Accessibility Team has researched and developed the following examples to demonstrate
+how to build these accessible table patterns. We've listed the specific considerations and decisions
+we've made for each of the examples.
+
+- [Expandable Rows](?path=/docs/guides-accessibility-table-patterns-expandable-rows--docs)
+- [Nested Rows](?path=/docs/guides-accessibility-table-patterns-nested-rows--docs)
+- [Selectable Rows](?path=/docs/guides-accessibility-table-patterns-selectable-rows--docs)
+- [Filterable Column Headers](?path=/docs/guides-accessibility-table-patterns-filterable-column-headers--docs)
+- [Sortable Column Headers](?path=/docs/guides-accessibility-table-patterns-sortable-column-headers--docs)
+- [With Form Fields](?path=/docs/guides-accessibility-table-patterns-with-form-fields--docs)

package/dist/mdx/accessibility/tables/SelectableRows.mdx

@@ -0,0 +1,27 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {SelectableRows} from '../examples/Table/WithSelectableRows';
+
+
+## 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} />

package/dist/mdx/accessibility/tables/SortableColumnHeaders.mdx

@@ -0,0 +1,23 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+
+import {SortableColumnHeaders} from '../examples/Table/WithSortableColumnHeaders';
+
+
+## Sortable Column Headers
+
+The challenge in this example is to provide all of the necessary information about the interactive
+column headers, the sort state of the column, and instructions about how the table will be sorted
+without giving too much information to users while reading the data cells below.
+
+- The `aria-sort` property has been added to each of the `<Table.Header>` components (`<th>` DOM
+  element) and updated to `ascending` or `descending` to reflect the current sort state. We
+  recommend validating whether this property is well supported for your screen reader and browser
+  combinations first.
+- A `<TertiaryButton>` describing the column name is used inside of the `<Table.Header>` component.
+- The `description` variant of the Canvas `Tooltip` component is applied to the button in the column
+  header and applied to the accessible description of the button with the `aria-description`
+  property. This is used to describe how the column will be sorted when pressed and screen readers
+  will only read this description while focusing on the column headers, not while reading the data
+  cells below.
+
+<ExampleCodeBlock code={SortableColumnHeaders} />

package/dist/mdx/accessibility/{TestingTableWithFormFields.mdx → tables/WithFormFields.mdx}

@@ -1,5 +1,6 @@
 import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
-import WithFormFields from './examples/Table/WithFormFields';
+
+import {WithFormFields} from '../examples/Table/WithFormFields';
 
 
 ## Table with form field components

package/dist/mdx/react/table/Table.mdx

@@ -1,9 +1,10 @@
 import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
+import BaseHtmlTable from './examples/BaseHtmlTable';
 import Basic from './examples/Basic';
 import BasicWithHeading from './examples/BasicWithHeading';
 import FixedColumn from './examples/FixedColumn';
 import RightToLeft from './examples/RightToLeft';
-import BaseHtmlTable from './examples/BaseHtmlTable';
+
 
 # Canvas Kit Table
 
@@ -77,12 +78,16 @@ use the `BaseTable` component.
 
 ### Advanced
 
-You can also find several advanced Table examples in our Storybook Examples section.
+You can also find several advanced Table examples in our
+[Guides > Accessibility > Table Patterns](?path=/docs/guides-accessibility-table-patterns--docs)
+section.
 
-- [Expandable Rows](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-advanced-tables--docs#expandable-rows)
-- [Selectable Rows ](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-advanced-tables--docs#selectable-rows)
-- [Filterable Column Headers](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-advanced-tables--docs#filterable-column-headers)
-- [Sortable Column Headers](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-advanced-tables--docs#sortable-column-headers)
+- [Expandable Rows](?path=/docs/guides-accessibility-table-patterns-expandable-rows--docs)
+- [Nested Rows](?path=/docs/guides-accessibility-table-patterns-nested-rows--docs)
+- [Selectable Rows](?path=/docs/guides-accessibility-table-patterns-selectable-rows--docs)
+- [Filterable Column Headers](?path=/docs/guides-accessibility-table-patterns-filterable-column-headers--docs)
+- [Sortable Column Headers](?path=/docs/guides-accessibility-table-patterns-sortable-column-headers--docs)
+- [With Form Fields](?path=/docs/guides-accessibility-table-patterns-with-form-fields--docs)
 
 ### Custom Styles
 
@@ -90,6 +95,176 @@ Table and its subcomponents support custom styling via the `cs` prop. For more i
 our
 ["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-guides-customizing-styles--docs).
 
+## Accessibility
+
+`Table` is a styled compound wrapper around native HTML table elements (`<table>`, `<caption>`,
+`<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>`, `<td>`). Assistive technology can announce column
+and row headers as users move through cells **only when** the markup is a real data table with
+correct headers and an accessible name. `Table` does **not** include a model, roving tabindex, or
+built-in sort, filter, selection, or expand behavior.
+
+Use `Table` for tabular data with a relationship between rows and columns—not for page layout.
+Prefer **`Table`** (CSS Grid) unless the design needs a standard HTML table layout without Grid;
+then use **`BaseTable`**. The same accessibility requirements apply to both. For interactive table
+patterns, follow
+[Guides > Accessibility > Table Patterns](?path=/docs/guides-accessibility-table-patterns--docs)
+instead of inventing ARIA. See also
+[Table Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/table/).
+
+### Minimum accessible structure
+
+The following matches the [Example with Caption](#example-with-caption) (`Basic` story): native
+table markup with **`Table.Caption`** as the accessible name and **`scope="col"`** on column
+headers. The [Basic Example](#basic-example) uses a visible **`Heading`** and **`aria-labelledby`**
+instead of a caption; that is an equally valid naming pattern (see **Accessibility Requirements**).
+
+```tsx
+import {Table} from '@workday/canvas-kit-react/table';
+
+<Table>
+  <Table.Caption>Coffee Drinks and Sizes</Table.Caption>
+  <Table.Head>
+    <Table.Row>
+      <Table.Header scope="col">Drink</Table.Header>
+      <Table.Header scope="col">Size</Table.Header>
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Espresso</Table.Cell>
+      <Table.Cell>1 oz</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>Macchiato</Table.Cell>
+      <Table.Cell>2 oz Espresso</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>;
+```
+
+Put **`Table.Caption`** first when you use it (HTML requires `<caption>` as the first child of
+`<table>`). Pair every column header with **`scope="col"`**. Do not render empty **`Table.Row`**
+elements.
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically when you compose `Table` (or `BaseTable`) with its
+subcomponents. **Do not duplicate them** in consuming code.
+
+**Native table semantics** (_applied by `createComponent` element mapping_):
+
+- `Table`: `<table>`
+- `Table.Caption`: `<caption>`
+- `Table.Head`: `<thead>`
+- `Table.Body`: `<tbody>`
+- `Table.Footer`: `<tfoot>`
+- `Table.Row`: `<tr>` (`Table.Row` also sets CSS Grid column tracks from the count of valid child
+  cells; this is layout only)
+- `Table.Header`: `<th>`
+- `Table.Cell`: `<td>`
+
+**Keyboard** (_standard `Table` behavior_):
+
+`Table` uses native `<table>` keyboard behavior. Do not add custom key handlers or grid-widget keys
+on a data table.
+
+When **`Table`** overflows (the root stencil uses `overflow: auto`), add **`tabIndex={0}`** so
+keyboard users can focus and scroll it, as in the [Fixed Column](#fixed-column) example. Omit
+**`tabIndex`** when the table does not scroll.
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- The table is announced as a table, with its accessible name from **`Table.Caption`** or
+  **`aria-labelledby`** / **`aria-label`** on **`Table`**
+- Moving across a row announces the **column** header (`scope="col"`)
+- Moving down a column announces the **row** header when body cells use **`Table.Header`** with
+  **`scope="row"`**
+- Interactive controls inside cells are announced with their own name and role when focused
+
+### Accessibility Requirements
+
+Required in application code for an accessible `Table`. There is **no** `useTableModel`. Canvas Kit
+does **not** set `scope`, an accessible name, `tabIndex`, or `id` / `headers` cell associations —
+supply those in application code when the table below requires them. Rows marked _(conditional)_
+apply only when the situation matches—otherwise omit.
+
+**If no design spec is provided:** generate a simple data table with **`Table.Caption`**,
+**`Table.Head`** / **`Table.Body`**, **`scope="col"`** on column headers, and **`Table.Cell`** for
+body data. Omit **`Table.Footer`**, row headers, **`tabIndex`**, `id` / `headers` associations,
+**`aria-sort`**, **`aria-expanded`**, **`aria-level`**, selection checkboxes, and filter/sort popups
+unless the spec calls for those patterns.
+
+**Heading instead of caption** _(conditional)_:
+
+When the design uses a visible heading (or other text) instead of **`Table.Caption`**, give that
+heading a unique `id` and set **`aria-labelledby`** on **`Table`**. Do not also render
+**`Table.Caption`** unless the design needs both a caption and extra labelling. See
+[Basic Example](#basic-example).
+
+```tsx
+<Heading as="h3" id={headingId}>
+  Pizza Toppings
+</Heading>
+<Table aria-labelledby={headingId}>{/* … */}</Table>
+```
+
+**Interactive and advanced patterns** _(conditional)_:
+
+Do not invent table ARIA. Copy the matching Canvas Kit guide when the spec includes that behavior:
+
+- [Expandable Rows](?path=/docs/guides-accessibility-table-patterns-expandable-rows--docs)
+- [Nested Rows](?path=/docs/guides-accessibility-table-patterns-nested-rows--docs)
+- [Selectable Rows](?path=/docs/guides-accessibility-table-patterns-selectable-rows--docs)
+- [Filterable Column Headers](?path=/docs/guides-accessibility-table-patterns-filterable-column-headers--docs)
+- [Sortable Column Headers](?path=/docs/guides-accessibility-table-patterns-sortable-column-headers--docs)
+- [With Form Fields](?path=/docs/guides-accessibility-table-patterns-with-form-fields--docs)
+
+| Requirement                                           | How to satisfy                                                                                                                                                                                                                                                             |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Data table, not layout                                | Compose **`Table`** (or **`BaseTable`**) with **`Head`**, **`Body`**, **`Row`**, **`Header`**, and **`Cell`**. Do not use a table to position non-tabular UI.                                                                                                              |
+| Accessible name                                       | **`Table.Caption`** with a descriptive title, **or** **`aria-labelledby`** on **`Table`** pointing at a visible heading `id` (see **Heading instead of caption**). Canvas Kit does not set **`aria-labelledby`**.                                                          |
+| Column headers                                        | Set **`scope="col"`** on every **`Table.Header`** in **`Table.Head`**. **`Table.Header`** renders `<th>` but does not set `scope`. Do not use **`Table.Cell`** (`<td>`) for column headers.                                                                                |
+| Row headers _(conditional)_                           | When the first (or identifying) column names each row, set **`scope="row"`** on **`Table.Header`** in the body, as in [Fixed Column](#fixed-column). Do not rely on `<th>` alone.                                                                                          |
+| Keyboard access to overflow _(conditional)_           | If the table scrolls, set **`tabIndex={0}`** on **`Table`**. Omit it when content does not overflow.                                                                                                                                                                       |
+| Footer _(conditional)_                                | **`Table.Footer`** only when the design includes summary or footer rows.                                                                                                                                                                                                   |
+| Form controls in cells _(conditional)_                | Label every control (prefer **`FormField`**). See [With Form Fields](?path=/docs/guides-accessibility-table-patterns-with-form-fields--docs) and [Form Field](?path=/docs/components-inputs-form-field--docs).                                                             |
+| Sort, filter, select, expand, or nest _(conditional)_ | Follow the matching [Table Patterns](?path=/docs/guides-accessibility-table-patterns--docs) guide. **Ask the developer** which pattern the spec requires before generating `aria-sort`, `aria-expanded`, `aria-level`, `aria-owns`, live regions, or selection checkboxes. |
+
+**Summary for code generation:**
+
+- **REQUIRED:** semantic `Table` composition, accessible name (caption or `aria-labelledby`),
+  `scope="col"` on column headers
+- **CONDITIONAL:** heading + `aria-labelledby`, `scope="row"`, `tabIndex={0}` for overflow,
+  `Table.Footer`, form-field labelling in cells, advanced table patterns from the guides
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Manually set `role="table"`, `role="row"`, `role="columnheader"`, `role="rowheader"`, or
+  `role="cell"` on **`Table`** subcomponents — they already render native table elements
+- Omit **`scope`** on **`Table.Header`**, or use **`Table.Cell`** for column or row headers
+- Generate `id` / `headers` associations on cells for a simple data table — use **`scope`** instead
+  (see **Accessibility Requirements**)
+- Leave the table unnamed (no **`Table.Caption`**, **`aria-labelledby`**, or **`aria-label`**), or
+  set **`aria-labelledby`** when **`Table.Caption`** already names the table
+- Use a table for page layout
+- Add **`tabIndex={0}`** on a table that does not scroll, or omit it on a horizontally/vertically
+  scrollable table
+- Set **`aria-sort`**, **`aria-expanded`**, **`aria-level`**, **`aria-owns`**, or selection
+  checkboxes by default — those belong to specific
+  [Table Patterns](?path=/docs/guides-accessibility-table-patterns--docs) and need a matching design
+  spec
+- Nest a `<table>` inside a cell to fake hierarchy, or add extra **`Table.Body`** elements to fake a
+  tree — see [Nested Rows](?path=/docs/guides-accessibility-table-patterns-nested-rows--docs)
+- Put a "Select All" checkbox in a column header **`Table.Header`** without following
+  [Selectable Rows](?path=/docs/guides-accessibility-table-patterns-selectable-rows--docs)
+- Place unlabeled inputs in cells, or rely on the column header alone without checking
+  [With Form Fields](?path=/docs/guides-accessibility-table-patterns-with-form-fields--docs)
+- Generate **`role="grid"`** / grid-widget keyboard behavior on **`Table`** — CSS Grid on
+  **`Table.Row`** is visual layout, not an ARIA grid
+
 ## Component API
 
 <SymbolDoc name="Table" fileName="/react/" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "16.0.13",
+  "version": "16.0.15",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -47,10 +47,10 @@
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
     "@workday/canvas-expressive-icons-web": "1.0.2",
-    "@workday/canvas-kit-labs-react": "^16.0.13",
-    "@workday/canvas-kit-preview-react": "^16.0.13",
-    "@workday/canvas-kit-react": "^16.0.13",
-    "@workday/canvas-kit-styling": "^16.0.13",
+    "@workday/canvas-kit-labs-react": "^16.0.15",
+    "@workday/canvas-kit-preview-react": "^16.0.15",
+    "@workday/canvas-kit-react": "^16.0.15",
+    "@workday/canvas-kit-styling": "^16.0.15",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-tokens-web": "^4.4.0",
     "markdown-to-jsx": "^7.2.0",
@@ -63,5 +63,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "e9dd2a5816799426ed59d7b4a3c8b6b56300aa68"
+  "gitHead": "f4ae86b34eec3edc8e580c9384d4919da5ae2a76"
 }

package/dist/mdx/accessibility/InlinePortals.mdx

@@ -1,21 +0,0 @@
-import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
-
-import InlinePortalPopup from './examples/Popups/InlinePortalPopup';
-
-
-## Inline portal with `PopupStack`
-
-This example builds on the patterns described in
-[Guides > Accessibility > Inline Popups](?path=/docs/guides-accessibility-inline-popups--docs). It
-does **not** use a focus trap. For modal dialogs with overlay and focus trap, use the
-[**Modal**](?path=/docs/components-popups-modal--docs) component instead.
-
-Keep using a portal (default stacking and positioning) but mount the portal **into a sentinel
-element** placed right after the trigger. Call `PopupStack.pushStackContext(sentinelElement)` while
-the popup is open so new stack items append to that sentinel instead of `body`. **Tradeoff:** You
-still get **ancestor overflow** clipping—the portaled content is a descendant of the sentinel, not
-`document.body`. You must also handle **`PopupStack` context** (push/pop on open/close), which is
-more moving parts than `portal={false}` alone. Use **`useInitialFocus`** so opening the popup is
-announced when focus enters the dialog.
-
-<ExampleCodeBlock code={InlinePortalPopup} />

package/dist/mdx/accessibility/TablesAdvanced.mdx

@@ -1,126 +0,0 @@
-import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
-
-import SelectableRows from './examples/Table/WithSelectableRows';
-import ExpandableRows from './examples/Table/WithExpandableRows';
-import SortableColumnHeaders from './examples/Table/WithSortableColumnHeaders';
-import FilterableColumnHeaders from './examples/Table/WithColumnHeaderFilters';
-
-
-## Advanced Table Examples
-
-Tables should only be used to organize data that has a clear relationship between rows and columns,
-like a calendar or a schedule. Never use a table just for page layout.
-
-When you use the proper HTML table markup, a screen reader can help a user navigate the table. It
-will automatically read the column and row headers as they move through the data, so they always
-know what information they're looking at.
-
-- All tables should have a clear header and a descriptive title.
-- Keep your tables simple. If a table is too complex, it might be better to break it up into several
-  smaller tables or use a different format.
-
-Out of the box, `Table` is a lightweight compound component with a high degree of flexibility, but
-not much functionality outside of providing a basic table layout. This flexibility lets developers
-implement common features, such as selecting rows and sorting columns, on top of `Table` to meet
-their specific application needs.
-
-The Workday Accessibility Team has researched and developed the following examples below to
-demonstrate how to build these accessible table patterns. We've listed the specific considerations
-and decisions we've made for each of the examples.
-
-### Expandable Rows
-
-Expandable Rows combines the likes of an accordion with tabular data tables. Column 1 renders icon
-buttons with 2 states, a collapsed and expanded state. A new row that spans the entire width of the
-table is added to the table just after the expanded row.
-
-- The `aria-expanded` property is added to the chevron button to communicate this state to screen
-  reader users.
-- A Canvas accessible `Tooltip` component is used to assign names to each icon button based on the
-  most useful value in the row. In this example, we combined the car make (in column 1) and model
-  (in column 2) together. This allows everyone to view the name of the icon buttons by hovering the
-  mouse or focusing with the keyboard.
-- The expanded row uses `colspan` to span the entire width of the table and support screen readers.
-  This space provides flexibility to show headings, lists, and other structured content for the
-  table row above.
-- There is no explicit relationship between a row of cells and the spanned content below it. The
-  spanned content is assumed to belong to the row of cells above it, based on established accordion
-  patterns and logical reading order of content rendered to the screen.
-- Outlining hierarchy with additional nested rows in the table is not supported for screen readers
-  in this example.
-
-<ExampleCodeBlock code={ExpandableRows} />
-
-### 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' accessible `Tooltip` component to assign names to each Checkbox based on the most
-  useful value in the row, the topping name. This allows everyone to view the name of the checkboxes
-  by hovering the mouse or focusing with the keyboard.
-- 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. When we
-  rendered column 1 as row headers, then reading down column 2 (Topping Name) sounded redundant
-  because the `Checkbox` names in column 1 are identical to the Topping Name in column 2.
-
-<ExampleCodeBlock code={SelectableRows} />
-
-### Filterable Column Headers
-
-In this example, we demonstrate using the `Popup` component in each column header allowing users to
-search and filter the data on the table. The `Popup` component relies on React Portals to render the
-popup elements at the bottom of the browser's DOM presenting 2 key challenges for accessibility:
-
-1. Keyboard focus order of the elements in the popup,
-2. Screen readers' reading order of the content rendered in the browser.
-
-Here's what we did about it:
-
-- Canvas Kit includes a `usePopupModel` hook, with quite a few additional hooks developers can add
-  to their models. In particular, the `useFocusRedirect` hook manages keyboard focus between the
-  `<Popup.Target>` button and the popup content.
-- The `useInitialFocus` hook allows developers to specify which element receives keyboard focus when
-  the popup appears. In this example, we auto-focused the search input field.
-- To address the reading order of content, we set the `aria-owns` property onto the parent
-  `<Table.Header>` component (`<th>` DOM element) with 2 unique `id` values. The first `id` refers
-  to the `<Popup.Target>` button and the second refers to the `<Popup.Card>` container element. This
-  manually reassigns the column header's `<Popup.Target>` button and the `Popup` contents as
-  siblings in the browser's accessibility tree hierarchy. Screen readers **should** read the column
-  header buttons and the popup content in sequential order even though they are not siblings in the
-  DOM.
-- The `type='description'` variant of the Canvas `Tooltip` is used to communicate the filtered state
-  of the column header, and assigned to the accessible description of the column header
-  `<TertiaryButton>` component.
-- The Canvas `AriaLiveRegion` component is used to render the "X of Y items" status inside the table
-  caption. This enables screen readers to automatically describe the filter state changes of the
-  table content to users in real time. We recommend validating whether this use of a live region is
-  well supported for your screen reader and browser combinations first.
-
-<ExampleCodeBlock code={FilterableColumnHeaders} />
-
-### Sortable Column Headers
-
-The challenge in this example is to provide all of the necessary information about the interactive
-column headers, the sort state of the column, and instructions about how the table will be sorted
-without giving too much information to users while reading the data cells below.
-
-- The `aria-sort` property has been added to each of the `<Table.Header>` components (`<th>` DOM
-  element) and updated to `ascending` or `descending` to reflect the current sort state. We
-  recommend validating whether this property is well supported for your screen reader and browser
-  combinations first.
-- A `<TertiaryButton>` describing the column name is used inside of the `<Table.Header>` component.
-- The `description` variant of the Canvas `Tooltip` component is applied to the button in the column
-  header and applied to the accessible description of the button with the `aria-description`
-  property. This is used to describe how the column will be sorted when pressed and screen readers
-  will only read this description while focusing on the column headers, not while reading the data
-  cells below.
-
-<ExampleCodeBlock code={SortableColumnHeaders} />