Skip to content

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

TypeScript

docs(Table): record canonical anatomy (#5770)

Cindy Zhangbc39db431684
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 98ec208d04..aef706ba9d 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -1,5 +1,104 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Table',
+ required: true,
+ description:
+ 'Semantic table element that groups the table sections, rows, and cells.',
+ },
+ {
+ name: 'Scroll region',
+ required: true,
+ description:
+ 'Keyboard-focusable outer region that scrolls horizontally when the columns overflow.',
+ },
+ {
+ name: 'Header section',
+ required: false,
+ description:
+ 'Column-heading section generated when data-driven columns are present or supplied with TableHeader in children mode.',
+ },
+ {
+ name: 'Column header cell',
+ required: false,
+ description:
+ 'Cell that identifies one column and may contain sorting or bulk-selection controls.',
+ },
+ {
+ name: 'Sort control',
+ required: false,
+ description:
+ "Button that wraps a sortable column label and changes that column's sort direction.",
+ },
+ {
+ name: 'Sort indicator glyph',
+ required: false,
+ description: 'Directional symbol rendered by Icon inside a Sort control.',
+ },
+ {
+ name: 'Sort priority',
+ required: false,
+ description:
+ 'Number shown for a sorted column when multi-column sorting is active.',
+ },
+ {
+ name: 'Selection control',
+ required: false,
+ description:
+ 'CheckboxInput rendered in the header and selectable body rows by the selection plugin.',
+ },
+ {
+ name: 'Body section',
+ required: true,
+ description:
+ 'Section containing data rows or the current empty state; data-driven mode renders it automatically.',
+ },
+ {
+ name: 'Row',
+ required: false,
+ description:
+ 'Repeated TableRow that groups cells in a standard header, body, or footer row.',
+ },
+ {
+ name: 'Cell',
+ required: false,
+ description:
+ 'TableCell containing one value or caller-provided content in a standard body or footer row.',
+ },
+ {
+ name: 'Default empty state',
+ required: false,
+ description:
+ 'Compact EmptyState shown for an empty data array unless it is replaced or disabled.',
+ },
+ {
+ name: 'Expansion control',
+ required: false,
+ description:
+ 'Button in a leading cell that expands or collapses one expandable row.',
+ },
+ {
+ name: 'Expansion glyph',
+ required: false,
+ description:
+ 'Directional symbol rendered by Icon inside an Expansion control.',
+ },
+ {
+ name: 'Expanded detail panel',
+ required: false,
+ description:
+ 'Detail row and spanning cell rendered below an expanded row around caller-provided content.',
+ },
+ {
+ name: 'Footer section',
+ required: false,
+ description:
+ 'Optional summary or totals section supplied with TableFooter in children mode.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -147,14 +246,7 @@ export const docs = {
{ guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
{ guidance: false, description: 'Omit width on text-heavy columns; without an explicit proportional() width they have no minimum and can squish to near-zero on mobile.' },
],
- anatomy: [
- {name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
- {name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},
- {name: 'Footer', required: false, description: 'Displays summary or totals.'},
- {name: 'Top Bar', required: false, description: 'Contains title, toolbar, and filters.'},
- {name: 'Bottom Bar', required: false, description: 'Contains pagination controls.'},
- {name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
- ],
+ anatomy,
},
};
@@ -169,14 +261,7 @@ export const docsZh = {
{ guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
{ guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
],
- anatomy: [
- {name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
- {name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},
- {name: 'Footer', required: false, description: 'Displays summary or totals.'},
- {name: 'Top Bar', required: false, description: 'Contains title, toolbar, and filters.'},
- {name: 'Bottom Bar', required: false, description: 'Contains pagination controls.'},
- {name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
- ],
+ anatomy,
},
};
@@ -196,13 +281,6 @@ export const docsDense = {
{ guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
{ guidance: false, description: 'Omit width on text-heavy columns; w/o explicit proportional() width they have no minimum and can squish to near-zero on mobile.' },
],
- anatomy: [
- {name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
- {name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},
- {name: 'Footer', required: false, description: 'Displays summary or totals.'},
- {name: 'Top Bar', required: false, description: 'Contains title, toolbar, and filters.'},
- {name: 'Bottom Bar', required: false, description: 'Contains pagination controls.'},
- {name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
- ],
+ anatomy,
},
};
\ No newline at end of file
diff --git a/packages/core/src/Table/Table.spec.md b/packages/core/src/Table/Table.spec.md
new file mode 100644
index 0000000000..5dc74e9525
--- /dev/null
+++ b/packages/core/src/Table/Table.spec.md
@@ -0,0 +1,283 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Table
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/Table/Table.test.tsx,
+ packages/core/src/Table/plugins/selection/useTableSelection.test.tsx,
+ packages/core/src/Table/plugins/sortable/useTableSortable.test.tsx,
+ packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.test.tsx,
+ packages/cli/foundation/discovery/theming-targets.test.mjs,
+ packages/cli/api/theme/targets/targets.test.mjs,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:container-padding,
+ architecture:interaction-modality,
+ architecture:public-component-api,
+ ]
+contributing: []
+system_specs: []
+---
+
+# Table component contract
+
+## Intent
+
+Table presents consistently structured data in semantic rows and columns. This
+draft records its current aggregate anatomy, parent-owned target inventory, and
+stable sorting, selection, expansion, and empty-state parts without changing
+runtime behavior, DOM, styling, targets, aliases, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+ targets, aliases, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The Table and Scroll region, the aggregate Header section, Body section,
+ conditional Footer section, Row, Column header cell, and Cell anatomy, and the
+ eight current `table*` targets mapped below.
+- The stable Sort control and Sort priority rendered by useTableSortable.
+- The stable Expansion control and Expanded detail panel rendered by
+ useTableRowExpansion.
+- Placement of selection-plugin CheckboxInput controls in generated header and
+ body cells.
+
+**Does not own / non-goals**
+
+- CheckboxInput visuals, Icon glyphs, or the default EmptyState surface; those
+ remain owned by their respective components.
+- Cell values, custom cell renderers, custom empty states, footer content, or
+ expanded detail content supplied by the caller.
+- Pagination, filtering, column-management, tree, grouping, sticky-column, or
+ context-menu anatomy beyond the stable parts explicitly recorded here.
+- New targets for current untargeted plugin parts, or correction of current
+ target-reachability gaps.
+- New runtime behavior, DOM, API, target, alias, or plugin contract.
+
+## Public concepts
+
+No new public concept is introduced. Consumer data, columns, props, composition,
+plugins, defaults, and usage remain documented in `Table.doc.mjs` and the member
+and hook docs.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | Styled Table renders one keyboard-focusable Scroll region around one semantic Table. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | Data-driven mode renders a Body section and a Header section with Column header cells when columns are present. Each data item renders a standard Row and Cells; an empty data array instead renders the configured empty-state row when enabled. It never creates a Footer section. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR3 | Children mode passes caller composition through to the Table. TableHeader, TableBody, and TableFooter provide the respective sections, and TableRow, TableHeaderCell, and TableCell provide standard rows and cells. | Current source, docs, and tests | Verified current composition; no new API or DOM rule |
+| FR4 | `Table.doc.mjs` is the canonical aggregate consumer owner for the eight current targets: `table`, `table-scroll-wrapper`, `table-header`, `table-body`, `table-footer`, `table-row`, `table-cell`, and `table-header-cell`. Member docs retain direct lookup metadata through `subComponentOf: 'Table'`. | Current docs and CLI target tests | Verified parent ownership; focused placement coverage is partial |
+| FR5 | For a sortable column, useTableSortable renders a Sort control around the column label, an Icon-owned Sort indicator glyph, and a numeric Sort priority only while multi-sort has more than one active entry. | Current source, docs, and tests | Control and priority are tested; glyph presence is source-inspected only |
+| FR6 | useTableSelection renders CheckboxInput-owned Selection controls in the generated selection Column header cell and each selectable body Cell; selection remains row state rather than separate anatomy. | Current source, docs, and tests | Verified stable delegated controls; no target or state change |
+| FR7 | For an expandable row, useTableRowExpansion renders an Expansion control with an Icon-owned Expansion glyph and conditionally appends an Expanded detail panel whose cell spans the column count captured by that plugin's `transformColumns` step. | Current source, docs, and tests | Verified stable plugin parts; current target gaps remain |
+| FR8 | Empty data renders the default compact EmptyState unless the caller supplies replacement content or disables it. | Current source, docs, and tests | Verified conditional delegation; caller content remains outside ownership |
+
+### Current evidence and gaps
+
+- The `table`, `table-scroll-wrapper`, `table-row`, `table-cell`, and
+ `table-header-cell` placements have focused runtime assertions. The
+ `table-header`, `table-body`, and `table-footer` placements are source-inspected;
+ existing section tests assert element structure and prop forwarding but not the
+ target classes.
+- Sort tests assert the Sort control, labels, state, and conditional priority, but
+ the test named `renders sort icon for sortable columns` checks only the buttons.
+ Sort indicator glyph presence is source-inspected and lacks focused regression
+ evidence. Selection and expansion suites assert their stable controls, states,
+ and panel structure; delegated Icon and CheckboxInput target classes also remain
+ source-inspected.
+- The Expanded detail panel uses raw `tr` and `td` elements rather than TableRow
+ and TableCell, so the existing `table-row` and `table-cell` targets do not reach
+ that panel wrapper. Its `colSpan` comes from the column count captured when the
+ expansion plugin runs `transformColumns`; a later custom plugin can add or remove
+ columns and leave the span stale. The current full-span test covers only the case
+ where expansion captures the final column set. This draft records both gaps and
+ does not correct them.
+
+### Allowed variation
+
+- **AV1 - Rendering mode.** Data-driven mode generates sections, rows, and cells;
+ children mode uses the caller-supplied composition without changing aggregate
+ ownership.
+- **AV2 - Repetition and content.** Column, Row, and Cell counts and caller-owned
+ content may vary without creating new anatomy parts.
+- **AV3 - Optional parts.** Header section, Footer section, default EmptyState,
+ Sort, Selection, and Expansion parts may be absent according to columns,
+ rendering mode, plugin configuration, data, and row eligibility.
+- **AV4 - Delegated rendering.** CheckboxInput, Icon, and EmptyState may change
+ internal element shape while preserving their own public contracts.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Data-driven rows | Scroll region contains Table, Header section when columns exist, Body section, and one standard Row with Cells per data item. | Counts, values, density, dividers, and cell content. |
+| Empty data | Body section contains default EmptyState unless replaced or disabled. | Caller replacement content or no empty state. |
+| Children mode | Caller-supplied sections are passed directly to Table. | Header, Body, and Footer section presence and content. |
+| Sortable column | Column header cell contains Sort control and Sort indicator glyph. | Direction and conditional multi-sort priority. |
+| Selectable rows | Selection controls occupy generated header and body cells. | Checked, indeterminate, disabled, or absent per row. |
+| Expandable row | Expansion control occupies a generated Cell; open state adds the detail panel after its row using the expansion plugin's captured column count. | Expanded state, caller detail content, and later plugin column transforms. |
+
+### Transformation and precedence order
+
+- No new plugin ordering, column transformation, slot placement, wrapping,
+ sizing, or styling precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced. Existing memoization and
+ plugin-specific render behavior remain outside this documentation change.
+
+## Accessibility contract
+
+This draft does not change or extend the current native table semantics,
+focusable Scroll region, column-header scope, sort `aria-sort`, selection
+`aria-selected`, CheckboxInput labels, or expansion `aria-expanded` behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| --------------------- | --------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Table | Groups the semantic table structure. | Current source and public docs | Supporting | FR1-FR4 |
+| Scroll region | Provides keyboard-reachable horizontal overflow around Table. | Current source and public docs | Supporting | FR1, FR4 |
+| Header section | Groups Column header cells separately from body data. | Current source and public docs | Supporting | FR2-FR4 |
+| Column header cell | Identifies one column and hosts optional header controls. | Current source and public docs | Prominent | FR2-FR6 |
+| Sort control | Activates sorting for one sortable column. | Current source and public docs | Prominent | FR5 |
+| Sort indicator glyph | Shows the current sort direction through Icon. | `component:Icon` | Supporting | FR5 |
+| Sort priority | Shows a column's position in active multi-sort order. | Current source and public docs | Supporting | FR5 |
+| Selection control | Selects all eligible rows or one eligible row through CheckboxInput. | `component:CheckboxInput` | Prominent | FR6 |
+| Body section | Groups data, empty-state, and expanded-detail rows. | Current source and public docs | Supporting | FR2-FR4, FR7, FR8 |
+| Row | Groups standard header, body, or footer cells. | Current source and public docs | Supporting | FR2-FR4, FR6 |
+| Cell | Contains one value or caller-provided content in a standard body or footer row. | Current source and public docs | Prominent | FR2-FR4, FR6, FR7 |
+| Default empty state | Communicates that the current data array has no rows through EmptyState. | `component:EmptyState` | Prominent | FR8 |
+| Expansion control | Expands or collapses one eligible row. | Current source and public docs | Prominent | FR7 |
+| Expansion glyph | Shows the current expansion direction through Icon. | `component:Icon` | Supporting | FR7 |
+| Expanded detail panel | Presents caller-provided detail content in a spanning row below the expanded row. | Current source and public docs | Prominent | FR7 |
+| Footer section | Groups caller-supplied summary or total rows below the body. | Current source and public docs | Supporting | FR3, FR4 |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Table": {"target": "table"},
+ "Scroll region": {"target": "table-scroll-wrapper"},
+ "Header section": {"target": "table-header"},
+ "Column header cell": {"target": "table-header-cell"},
+ "Sort control": {"inherits": "table-header-cell"},
+ "Sort indicator glyph": {
+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+ },
+ "Sort priority": {
+ "none": {
+ "reason": "unsettled: The multi-sort rank has no direct public target and uses a component-owned accent style; future exposure still needs an owner decision"
+ }
+ },
+ "Selection control": {
+ "delegatesTo": {
+ "owner": "component:CheckboxInput",
+ "target": "checkbox-input"
+ }
+ },
+ "Body section": {"target": "table-body"},
+ "Row": {"target": "table-row"},
+ "Cell": {"target": "table-cell"},
+ "Default empty state": {
+ "delegatesTo": {"owner": "component:EmptyState", "target": "empty-state"}
+ },
+ "Expansion control": {
+ "none": {
+ "reason": "unsettled: The expansion button has no direct public target and uses component-owned styles; future exposure still needs an owner decision"
+ }
+ },
+ "Expansion glyph": {
+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+ },
+ "Expanded detail panel": {
+ "none": {
+ "reason": "reachability-gap: The plugin renders its detail row and cell as raw elements, so the current table-row and table-cell targets do not reach the panel wrapper"
+ }
+ },
+ "Footer section": {"target": "table-footer"}
+}
+```
+
+The exact map records all eight current non-deprecated Table targets once. The
+legacy `base-table` alias is compatibility, not anatomy. TableHeader, TableBody,
+TableFooter, TableRow, TableCell, and TableHeaderCell retain direct docs linked by
+`subComponentOf: 'Table'`; they do not need independent component specs for this
+aggregate ownership.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, exact
+ target mapping, delegation, inheritance, factual `none` classifications, and
+ the rule that deprecated aliases do not count as anatomy.
+- `architecture:container-padding` owns the inherited inset protocol consumed by
+ the Scroll region and Cell edge compensation.
+- `architecture:interaction-modality` owns shared keyboard and pointer modality;
+ Table and its plugins retain their current local interactions.
+- `architecture:public-component-api` owns the stable props, components, hooks,
+ exports, and compatibility boundary; this documentation adds no API.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| FR1-FR3 | `Table.test.tsx` render, structure, children-mode, section, and target assertions | Data-driven rows, empty data, and children composition | Removing Table, Scroll region, or configured structure fails existing role, structure, class, or prop-forwarding assertions; Row and Cell are conditional on rendered data or caller composition. | `audit:Table/anatomy` |
+| FR4 | CLI discovery and API target tests plus source inspection | Direct member docs and unfiltered/scoped target output | Duplicating a parent/member target or changing the canonical owner fails parent-aware discovery assertions; section target placement remains source-inspected. | `audit:Table/theming` |
+| FR5 | `plugins/sortable/useTableSortable.test.tsx` plus source inspection | Unsorted, ascending, descending, and multi-sort | Removing the Sort control, conditional priority, or ARIA state fails existing assertions. Removing the Sort indicator glyph does not currently fail a focused test; glyph presence and delegated Icon target placement remain source-inspected. | `audit:Table/anatomy` |
+| FR6 | `plugins/selection/useTableSelection.test.tsx` | Select all, individual, disabled, and non-selectable | Removing header/body Selection controls or row selection state fails existing structure, label, interaction, and ARIA assertions; delegated CheckboxInput target placement remains source-inspected. | `audit:Table/anatomy` |
+| FR7 | `plugins/rowExpansion/useTableRowExpansion.test.tsx` plus source inspection | Collapsed, expanded, and non-expandable rows | Removing the Expansion control, conditional detail panel, captured-count `colSpan`, or ARIA state fails existing assertions in the covered plugin order; later column transforms, delegated Icon target placement, and untargeted panel wrappers remain source-inspected. | `audit:Table/anatomy` |
+| FR8 | `Table.test.tsx` empty-state suite plus EmptyState public target metadata | Default, custom, disabled, and non-empty | Removing conditional empty behavior fails existing assertions; default EmptyState delegation remains source-inspected. | `audit:Table/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`, and CLI parent-aware target discovery tests | Canonical anatomy, eight current targets, legacy alias | Missing, extra, duplicated, prefixed, stale, alias-backed, or independently owned member mappings fail repository validation or discovery coverage. | `audit:Table/theming` |
+
+## Decision log
+
+None. This draft records current facts and the user-directed canonical parent
+ownership without introducing a component-local design, API, behavior, layout,
+or theming decision.
+
+## Open questions
+
+- **OQ1 - Should the current untargeted Sort priority, Expansion control, or
+ Expanded detail panel gain direct public theming targets?** (`human-api`) This
+ factual map does not decide future exposure.
+- **OQ2 - Should focused runtime tests pin the Sort indicator glyph, the
+ `table-header`, `table-body`, and `table-footer` target classes, and delegated
+ component target placement?** (`checkable`) Current evidence is source
+ inspection plus structural and global inventory tests.
+- **OQ3 - Should row expansion derive its panel span after all column transforms?**
+ (`checkable`) A later custom `transformColumns` plugin can currently make the
+ captured count stale.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples, plugin usage,
+container-padding mechanics, shared modality rules, current audit results, or
+implementation steps. It links to their owners.