Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(a11y): TreeList adopts APG Tree View as one composite control, single caller-owned selection (#7460)

Cindy Zhang17b2fcfed5c9
diff --git a/packages/core/src/TreeList/TreeList.spec.md b/packages/core/src/TreeList/TreeList.spec.md
index 6886d38afe..90752b774c 100644
--- a/packages/core/src/TreeList/TreeList.spec.md
+++ b/packages/core/src/TreeList/TreeList.spec.md
@@ -148,6 +148,27 @@ The styling seam does not change TreeList's tree, treeitem, group, roving-focus,
expansion, selection, disabled, or activation behavior. Styling inputs MUST NOT
replace component-owned semantic or interaction props.
+- **AR1 — TreeList adopts the APG Tree View pattern** (`spec:AST-020/FR15`), as
+ one composite control: the Tree list is `role="tree"`, named by its Header
+ when one is rendered and otherwise by the caller's `aria-label` or
+ `aria-labelledby`; every row is `role="treeitem"`, named by its label and described by its
+ description, `aria-expanded` when it has children,
+ `aria-selected` when it is the selected row, and `aria-posinset`/`aria-setsize`
+ among its siblings; children sit in a `role="group"`. One row holds the Tab stop
+ (roving focus). ArrowDown/ArrowUp move between visible rows; ArrowRight expands
+ a closed row, then moves into its first child, and ArrowLeft collapses an open
+ row or moves to the parent — mirrored under RTL; Home and End move to the first
+ and last visible rows; Enter and Space activate the focused row; typing letters
+ moves to the next row whose label starts with them. Selection is caller-owned:
+ callers mark at most one row selected (`isSelected`); the tree does not
+ enforce it, claims no `aria-multiselectable`, and has no selection keyboard. Implementation gap until
+ its fix ships: a parent row's name reads "Toggle children <label>" because the
+ chevron button sits inside the `treeitem`; a plain row folds its description
+ into its name; a row with `href` or `onClick` names and describes its inner
+ control rather than the row; start and end content add their text and
+ control names to the row's name; and typeahead matches the row's whole text
+ rather than its label.
+
## Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
@@ -227,14 +248,15 @@ authorize or prohibit a future target.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection | Flat, nested, described, headed, and slotted items | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` |
-| FR2 | `TreeList.test.tsx` and `themingTargets.test.ts` | Five local targets and their documented states | Removing or moving any current local target fails focused class assertions or the global inventory. | `audit:TreeList/theming` |
-| FR3 | Source inspection plus Icon public target metadata | Expandable rows and caller-provided slots | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change. | `audit:TreeList/theming` |
-| FR4 | `TreeList.test.tsx` description rendering test and source inspection | Item with description | Removing description fails content coverage; adding a target requires an explicit map update. | `audit:TreeList/anatomy` |
-| FR5, FR6, ORD1 | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation | One input at a time; all three together; sibling rows | Dropping any mechanism, applying mechanisms to different elements, targeting the `<li>`, changing the merge order, or styling a sibling row fails. | `audit:TreeList/api` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and five current local targets | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation. | `audit:TreeList/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection | Flat, nested, described, headed, and slotted items | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` |
+| FR2 | `TreeList.test.tsx` and `themingTargets.test.ts` | Five local targets and their documented states | Removing or moving any current local target fails focused class assertions or the global inventory. | `audit:TreeList/theming` |
+| FR3 | Source inspection plus Icon public target metadata | Expandable rows and caller-provided slots | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change. | `audit:TreeList/theming` |
+| FR4 | `TreeList.test.tsx` description rendering test and source inspection | Item with description | Removing description fails content coverage; adding a target requires an explicit map update. | `audit:TreeList/anatomy` |
+| AR1 | Tree View accessibility contract (`internal/a11y-spec`, pending) bound to TreeList, in jsdom and Chromium; `TreeList.test.tsx` and `useTreeFocus.test.tsx` keyboard suites | Flat and nested trees; expanded/collapsed; selected/unselected; LTR and RTL; typeahead | A row loses its role, label name, state or position, two rows hold a Tab stop, an arrow key stops moving or stops mirroring under RTL, Home/End or typeahead stop working, or the tree claims multi-select | `audit:TreeList/accessibility` |
+| FR5, FR6, ORD1 | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation | One input at a time; all three together; sibling rows | Dropping any mechanism, applying mechanisms to different elements, targeting the `<li>`, changing the merge order, or styling a sibling row fails. | `audit:TreeList/api` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and five current local targets | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation. | `audit:TreeList/theming` |
Focused target-placement assertions cover all five local targets. Runtime support
and mutation-sensitive coverage for the item styling seam may land separately,
@@ -261,6 +283,15 @@ Rejected: applying the seam to the outer semantic `<li>`. That element owns tree
semantics and child grouping, while the row box is the stable visual and hover
boundary callers need to address.
+### DEC-2 — The tree is one composite control with single, caller-owned selection
+
+**Reference:** `component:TreeList/DEC-2`
+**Decider:** `cixzhang`, `2026-10-13`
+
+TreeList already plays the Tree View's role as one widget — one Tab stop, arrows, Home/End, activation, typeahead — so it adopts the pattern's keyboard model except the optional `*` key (AR1), not only the required parts. Callers mark at most one row selected (`isSelected`) and the tree does not enforce it, so the tree never claims `aria-multiselectable` and adds no range or toggle keyboard.
+
+Rejected: multi-select (`aria-multiselectable`, Shift/Ctrl ranges); a Tab stop per row.
+
## Open questions
None.