An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 4 kind: module id: module:Table/useTableTreeData authority: current archive_reason: null superseded_by: null approved_by: humbertovirtudes approved_at: 2026-11-04 owners: [cixzhang] review_triggers: [public-api, behavior, accessibility] verified_by: [ packages/core/src/Table/plugins/tree/useTableTreeData.test.tsx, apps/storybook/stories/TableTree.stories.tsx, scripts/check-i18n-catalog.mjs, scripts/check-knowledge.mjs, ] parent_component: component:Table references: [ architecture:internationalization, architecture:public-component-api, architecture:react-component-runtime, spec:AST-009, module:Table/useTableRowExpansion,
]
useTableTreeData accessible-name contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | Optional getRowLabel?: (item: T) => string supplies tree-row identity for expansion controls. |
| Behavior | A nonblank trimmed identity gives the localized expand/collapse button a named label; omitted or blank text uses the generic name. |
| End-user impact | Top-level and nested expansion controls identify their rows. |
| Builder impact | Callers opt in with row identity text; expansion state and verbs stay separate. |
| Compatibility/readiness | Additive optional API; existing tree state, data and control semantics remain. Implementation release verification is separate. |
| Review checks | Reject index/column-derived names, new visible content or stale names after a label/locale update. |
| Governing rules | Table owns aggregate composition; internationalization and React runtime own their shared mechanisms; this module covers naming only. |
This table is a review projection; the body below is authoritative.
Intent
A tree expansion button identifies the row it controls at every depth. This record contracts only accessible names and the optional naming callback, not the complete tree plugin or tree-view anatomy.
Compatibility and migration
- Released default preserved: yes; an omitted callback keeps generic localized expansion names.
- Compatibility class: optional additive API with no tree-data, row-key, expansion-state or interaction change.
- Migration decision: DEC-1. Consumer usage belongs in
useTableTreeData.doc.mjs. - Known validation exception: body rows carry no
aria-expanded(the expansion button carries it, AR1), but they keeparia-leveloutside a treegrid. Chromium exposes it as the row's depth, leaves included. Accessibility checkers report it, and it goes away when tree tables gain treegrid semantics.
Ownership boundary
Owns: row-label input, whitespace normalization, named messages, consumption of the rendered expander's translation context, semantic label refresh and naming evidence.
Does not own: internationalization-provider scope and update semantics, aggregate Table protocol, tree flattening, row keys, expansion state, hierarchy/selection semantics, control visibility, motion, row-click behavior or the complete hook configuration. No selection-label rule changes here.
Public API and concepts
| Concept | Values | Meaning | Default | Owner | Stability |
|---|---|---|---|---|---|
| Row identity text | String returned for the row item | Human-readable name excluding action verbs | Callback absent | Caller | Additive from first release |
| Effective label | Trimmed nonempty string or absent | Named or generic control label | Generic | This module | Stable |
| Name state | Collapsed or expanded | Localized expand/collapse wording | Follows existing expansion state | This module | Stable |
Behavioral contract
| ID | Invariant | Basis | Evidence state |
|---|---|---|---|
| FR1 | UseTableTreeDataConfig<T> accepts optional getRowLabel?: (item: T) => string. It receives the existing item at any depth and never supplies row keys or expansion state. Text is not inferred from rendered columns. |
Caller-owned identity; DEC-1 | Approved; implementation verified separately |
| FR2 | Trim surrounding whitespace. A nonempty result supplies {label} to @astryx.tableTree.expandRowNamed or collapseRowNamed, according to existing expansion state. Omitted or whitespace-only results select the existing expandRow or collapseRow message. |
DEC-1; internationalization ownership | Approved; implementation verified separately |
| FR3 | Each rendered tree expander uses its own internationalization provider. Locale/override changes and changes to effective row-label text update the accessible name, including label-only changes without altering tree expansion state. | Provider and semantic snapshot contracts | Verification required |
| FR4 | Naming does not change which rows have expanders, add visible text or alter native button role, aria-expanded, tree data, selection, keyboard interaction, focus or row-click behavior. Leaves without expansion controls do not gain them. |
Additive compatibility | Verification required |
Transformation and precedence order
- ORD1: caller row text is normalized before message interpolation; existing expansion state chooses the verb and the rendered expander's provider supplies wording.
- ORD2: absent/blank identity selects generic wording. This expansion-specific fallback does not change the selection plugin's same-named callback behavior.
Performance and resources
- PR1: a row-label update participates in the existing row's semantic notification. Naming introduces no independent tree store, observer, listener or asynchronous loader; unchanged semantic snapshots retain their identity.
Accessibility contract
- AR1: expansion buttons expose the complete localized action/name and retain independent
aria-expandedstate at top-level and nested depths. - AR2: computed accessibility-tree/browser names establish role/state/name exposure, not a specific spoken phrase or new tree navigation model.
Design relationships
| Anatomy | Requirement | Owner | Contract |
|---|---|---|---|
| Existing tree expander | Names change without new visual content or control anatomy | Existing tree control; this naming slice | FR2-FR4 |
Parent and system relationships
component:Table retains aggregate composition and renderer ownership. architecture:internationalization owns ICU messages, provider updates and catalog fallback. architecture:react-component-runtime owns external-store snapshot stability. The row-expansion naming module uses the same normalization boundary but owns a separate hook lifetime.
Verification map
| Contract | Verification | States | Failure expectation |
|---|---|---|---|
| FR1-FR2 | Tree plugin tests and browser accessible-name checks | Top-level/nested, collapsed/expanded, omitted/blank/named | Removing normalization/interpolation changes the expected names |
| FR3 | Label-only and provider update tests | Same tree data and expansion state; text/locale change | Omitting effective text from semantic refresh keeps a stale accessible name |
| FR4 | Existing tree state/performance/keyboard tests | Leaves, expansion toggles and named controls | Naming must not introduce controls or change state/data/focus |
Decision log
DEC-1 — Caller identity; localized component action
Reference: module:Table/useTableTreeData/DEC-1
Decider: humbertovirtudes, 2026-11-04.
The callback supplies identity only. Blank trimmed text uses generic expansion wording, matching the detail-row expander without imposing a new selection rule. Rejected: a full-action-label callback or inference from display-column content.
Open questions
None.
Content boundary
This record leaves the rest of the tree hook uncontracted here; consumer signatures/examples, implementation plans, audit results and parent/shared rules retain their own locations.