Skip to content

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

TypeScript

docs(Table): define row-status contract (#5830)

Cindy Zhang83873b32d303
diff --git a/packages/core/src/Table/Table.spec.md b/packages/core/src/Table/Table.spec.md
index ad730786a3..11785af910 100644
--- a/packages/core/src/Table/Table.spec.md
+++ b/packages/core/src/Table/Table.spec.md
@@ -3,16 +3,17 @@ schema_version: 3
template_version: 3
kind: component
id: component:Table
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-09-01
owners: [cixzhang]
review_triggers: [public-api, behavior, layout, theming, accessibility]
verified_by:
[
packages/core/src/Table/Table.test.tsx,
+ packages/core/src/Table/Table.perf.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,
@@ -21,7 +22,7 @@ verified_by:
packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
-modules: []
+modules: [module:Table/useTableRowStatus]
families: []
design_specs: []
architecture:
@@ -40,9 +41,11 @@ system_specs: []
## 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.
+contract records its current aggregate anatomy, parent-owned target inventory,
+stable sorting, selection, expansion, and empty-state parts, and the shared
+`TablePlugin` protocol through which public modules compose. Module-local API,
+generated anatomy, accessibility, migration, and evidence belong to each listed
+`module:*` record.
## Compatibility and migration
@@ -66,6 +69,9 @@ Consumer migration instructions belong in consumer docs and release notes.
useTableRowExpansion.
- Placement of selection-plugin CheckboxInput controls in generated header and
body cells.
+- The shared `TablePlugin` transform surface, phase order, sequential composition,
+ named-plugin ordering, slot protocol, failure isolation, and stable plugin-array
+ identity used by every Table module.
**Does not own / non-goals**
@@ -75,28 +81,42 @@ Consumer migration instructions belong in consumer docs and release notes.
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.
+- The public API, generated columns or other anatomy, internal precedence,
+ accessibility, migration, performance evidence, or theming decisions of an
+ independently contractible module. `module:Table/useTableRowStatus` owns those
+ concerns for `useTableRowStatus`.
- New targets for current untargeted plugin parts, or correction of current
target-reachability gaps.
-- New runtime behavior, DOM, API, target, alias, or plugin contract.
+- New runtime behavior, DOM, API, target, or alias.
## 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.
+Table records two aggregate public concepts without duplicating module-local APIs:
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------- | -------------------------- | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
+| Plugin collection | Named `Record<string, TablePlugin<T>>` or absent | Adds ordered transformations to the data-driven Table pipeline. | Data-driven Table | Absent | `component:Table` | Stable | Development warns for unknown transform keys, non-functions, and empty plugins; unsupported keys are ignored. |
+| Plugin transform | Column, element-render-prop, scroll-wrapper, or context transform | Changes one owned pipeline phase while preserving the common `TablePlugin` protocol. | According to the transform method | Omitted methods are no-ops | `component:Table` | Stable | A throwing transform is isolated and the prior accumulated value continues. |
+
+Consumer data, columns, props, module signatures, defaults, and usage remain
+documented in `Table.doc.mjs` and the member and module 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 |
+| ID | Invariant | Basis | Evidence 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 |
+| FR9 | Table converts the caller's named plugin record into one ordered array after its built-in styling plugin. Known names use the current canonical sequence `columnSettings → sort → tree → selection → pagination`; every other name follows that known set while preserving its record insertion order. | Current source and docs | Current shared ordering; canonical-name coverage is source-inspected |
+| FR10 | Every applicable non-context transform runs sequentially in the resolved plugin-array order, so a later plugin receives the value returned by every earlier successful plugin. A throwing transform reports a development error and leaves the prior accumulated value in the pipeline. | Current source and tests | Sequential composition is tested; failure isolation is source-inspected |
+| FR11 | `transformColumns` completes before element transforms. Table then applies table, header-cell/header-row, body-cell/body-row, scroll-wrapper, and context phases at their render points. Header-cell contributions use `before`, `content`, `after`, `overlay`, and `below` slots. Context transforms run in reverse so the first plugin becomes the outermost provider. | Current source, types, and tests | Transform application is tested; complete cross-phase order is source-inspected |
+| FR12 | When built-in and named plugin references are unchanged, Table reuses the resolved plugin array; unknown/custom plugin value identity and insertion order remain stable inputs to memoization. | Current source and performance tests | Current performance contract; focused named-order coverage is partial |
### Current evidence and gaps
@@ -116,8 +136,8 @@ and hook docs.
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.
+ where expansion captures the final column set. This contract records both gaps
+ and does not correct them.
### Allowed variation
@@ -131,6 +151,9 @@ and hook docs.
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.
+- **AV5 - Module participation.** Any named module may omit transform phases it does
+ not need. Unknown/custom plugin names remain valid and follow the shared fallback
+ ordering without acquiring module-local semantics here.
### Representative states
@@ -142,22 +165,39 @@ and hook docs.
| 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. |
+| Multiple plugins | Built-in styling runs first, then named plugins compose in the resolved order; later transforms receive earlier results. | Supported transform subset, custom names, and omitted phases. |
### Transformation and precedence order
-- No new plugin ordering, column transformation, slot placement, wrapping,
- sizing, or styling precedence rule is introduced.
+- **ORD1 - Plugin array.** Built-in plugins precede named consumer plugins. Known
+ names sort by the canonical list; unknown/custom names retain record insertion
+ order after the known set.
+- **ORD2 - Sequential transforms.** Each non-context phase reduces over that array
+ from first to last. A later plugin receives the earlier accumulated value.
+- **ORD3 - Render phases.** Column transforms complete before element transforms;
+ element transforms run at the table, header, body, and scroll-wrapper render
+ points. Context transforms run from last to first so array priority and provider
+ nesting agree: the first plugin is outermost.
+- **ORD4 - Module boundary.** Module records may rely on this protocol and state the
+ transforms they contribute, but they do not redefine aggregate phase or
+ named-plugin ordering.
### Performance and resources
-- No new performance or resource rule is introduced. Existing memoization and
- plugin-specific render behavior remain outside this documentation change.
+- **PR1 - Stable plugin array.** Table reuses the resolved plugin array while the
+ built-in array and named plugin values are referentially unchanged, including
+ when the caller recreates the containing record.
+- **PR2 - Module ownership.** Each module owns any stronger render, allocation,
+ listener, observer, or initialization constraint created by its transforms.
+ Table owns only the common array and transform pipeline cost.
## Accessibility contract
-This draft does not change or extend the current native table semantics,
+This contract 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.
+Each public module owns accessibility introduced by its transforms; the shared
+pipeline does not confer correctness on module output.
## Design relationships
@@ -247,40 +287,39 @@ aggregate ownership.
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.
+- `module:Table/useTableRowStatus` owns the row-status module's API, generated
+ anatomy, resolution and warning precedence, accessibility, performance,
+ migration, and evidence. Table owns only the shared plugin protocol and its
+ aggregate composition order.
## 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` |
+| 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` |
+| FR9-FR11 | `Table.test.tsx`, `types.ts`, `BaseTable.tsx`, and `useBaseTablePlugins.ts` | Built-in plus known and custom named plugins; every transform phase | Sequential composition, base-before-user behavior, transform application, and slot output have focused coverage; complete known-name sorting, phase order, exception continuation, and context nesting remain source-inspected. | `audit:Table/plugins` |
+| FR12, PR1 | `Table.perf.test.tsx` plus `useBaseTablePlugins.ts` source inspection | Same plugin references, recreated record, and changed plugin value | Unchanged plugin values must preserve the resolved array and representative no-op row-update budgets; focused named-record identity coverage remains partial. | `audit:Table/performance` |
+| Module backlink | `scripts/check-knowledge.mjs` | Active parent and colocated module record | A missing, duplicate, mis-parented, wrong-kind, misnamed, or undiscovered module record fails knowledge validation. | `audit:Table/modules` |
+| 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.
+None. This current contract records existing Table facts, approved canonical parent
+ownership, and the shared plugin protocol without introducing a component-local
+visual or runtime change.
## 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.
+None.
## 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.
+This file does not duplicate consumer prop tables or examples, module-local API or
+generated anatomy, plugin usage recipes, container-padding mechanics, shared
+modality rules, current audit results, or implementation steps. It links to their
+owners.
diff --git a/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.md b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.md
new file mode 100644
index 0000000000..8600530a7d
--- /dev/null
+++ b/packages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.md
@@ -0,0 +1,354 @@
+---
+schema_version: 3
+template_version: 1
+kind: module
+id: module:Table/useTableRowStatus
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-01
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/Table/plugins/rowStatus/useTableRowStatus.test.tsx,
+ scripts/check-knowledge.mjs,
+ ]
+parent_component: component:Table
+references:
+ [
+ component:Icon,
+ architecture:component-theming-surface,
+ architecture:icon-resolution-and-component-slots,
+ architecture:public-component-api,
+ spec:AST-002/DEC-6,
+ ]
+---
+
+# useTableRowStatus module contract
+
+## Intent
+
+`useTableRowStatus` adds an optional generated status gutter that communicates one
+outcome or caller-defined marker for each Table row. The module owns its public status
+vocabulary, generated column and indicator anatomy, accessible naming, internal
+signifier resolution, invalid-input fallback, performance obligations, and
+implementation evidence.
+
+This current contract is authoritative for the module's intended behavior. Runtime,
+public types, consumer docs, and release implementation remain explicitly pending
+and MUST follow this contract when implemented.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; every stable `0.5.2` custom marker keeps the
+ same source shape and rendered dot or caller-selected glyph.
+- Compatibility class: additive semantic interface at the `getStatus` callback
+ boundary plus restoration of stable behavior before the next stable release.
+- Migration decision: no stable-consumer codemod and no required stable-consumer
+ edit. Canary consumers that intentionally adopted the implicit semantic glyph
+ from [#5671](https://github.com/facebook/astryx/pull/5671) migrate manually from
+ `{color: 'error', label}` to `{status: 'error', label}`.
+
+Stable `0.5.2` already defines `{color, label}` as a caller-painted dot and
+`{color, icon, label}` as a caller-selected glyph with caller-selected paint. The
+exported `TableRowStatus` interface remains byte-for-byte unchanged so existing
+annotations, interface extensions, and declaration merging remain valid.
+
+A value-based codemod would be unsafe because stable `{color: 'error', label}` may
+intentionally mean an error-colored dot. If the semantic implementation is not
+ready before a stable cut, restore the custom-marker behavior first and defer the
+new semantic interface; the overloaded canary behavior MUST NOT become stable.
+
+This specification-only change carries no package Changeset. The implementation
+pull request owns public exports, consumer docs, tests, release notes, and its
+package-version Changeset.
+
+## Ownership boundary
+
+**Owns**
+
+- The public `useTableRowStatus` hook, `UseTableRowStatusConfig`, unchanged
+ `TableRowStatus` custom-marker interface, and proposed
+ `TableSemanticRowStatus` interface.
+- The exclusive result boundary of `getStatus`, including `null` for no marker.
+- The generated fixed-width column, visually hidden header name, empty-cell
+ behavior, indicator DOM, and internal `icon | dot` variant resolution.
+- Mapping semantic row status to a shared semantic Icon name and tone before
+ delegating glyph rendering.
+- Runtime precedence and warning behavior for untyped semantic/custom conflicts.
+- Row-status accessibility, performance constraints, migration, and evidence.
+
+**Does not own / non-goals**
+
+- Aggregate `TablePlugin` protocol, transform phases, named-plugin ordering, slot
+ composition, failure isolation, or plugin-array identity — owned by
+ `component:Table`.
+- Icon artwork, Icon's target, or shared icon resolution — owned by
+ `component:Icon` and `architecture:icon-resolution-and-component-slots`.
+- The active theme's semantic token values or concrete semantic artwork. The theme
+ supplies those through existing contracts; it does not select this module's
+ internal variant.
+- Product-specific meaning for custom colors or custom icons. The caller owns that
+ meaning and supplies the required label.
+- Shared design-feedback vocabulary. A Table row outcome is not authority for
+ feedback components.
+- A public `variant` or `presentation` prop, extensible variant map, reflected
+ variant data attribute, or row-status theme selector axis.
+- No `table-row-status` target is approved by this contract.
+ [#5754](https://github.com/facebook/astryx/pull/5754) remains outside this
+ contract and is held for a separate AST-002 proposal proving a theme-author
+ need, painter placement, and exact guarantees.
+
+## Public API and concepts
+
+The proposed public interfaces and callback boundary are additive:
+
+```ts
+export interface TableRowStatus {
+ color: TableRowStatusColor | (string & {});
+ icon?: IconName;
+ label: string;
+}
+
+export interface TableSemanticRowStatus {
+ status: 'success' | 'warning' | 'error';
+ color?: never;
+ icon?: never;
+ label: string;
+}
+
+export interface UseTableRowStatusConfig<T extends Record<string, unknown>> {
+ getStatus: (
+ item: T,
+ ) => (TableRowStatus & {status?: never}) | TableSemanticRowStatus | null;
+}
+```
+
+`TableRowStatus` remains byte-for-byte the existing exported interface. The
+exclusive union exists only at the callback boundary, where its custom member is
+intersected with `{status?: never}`. This preserves the existing interface for
+annotations, extension, and declaration merging without allowing a supported
+semantic status to mix with custom marker inputs. `TableRowStatusColor` and the
+existing `string & {}` CSS-color escape hatch remain unchanged; this contract does
+not newly export the color type.
+
+| Concept | Closed values or states | Meaning | Default | Owner | Stability |
+| ------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------- | -------------------------------- | --------------------------------------- |
+| Row-status presence | Either public interface or `null` | Adds one indicator for the row or leaves the generated cell empty. | `null` means absent | `module:Table/useTableRowStatus` | Stable presence; additive semantic form |
+| Semantic outcome | `success`, `warning`, `error` | Selects one cohesive system-owned outcome whose glyph and tone are derived together. | No implicit outcome | `module:Table/useTableRowStatus` | Additive proposal |
+| Custom marker paint | Existing Table row-status colors or a CSS color | Selects paint only; no color value implies a semantic outcome or representation. | Required on `TableRowStatus` | Caller through this module | Stable `0.5.2` |
+| Custom marker glyph | `IconName` or absent | Selects the caller-owned glyph; absence selects a dot. | Absent means dot | Caller through this module | Stable `0.5.2` |
+| Label | Required string | Names the indicator and supplies supplemental tooltip text. | Required | Caller through this module | Stable |
+| Resolved variant | Internal `icon` or `dot` | Names the signifier anatomy derived from the accepted result, not a caller choice. | Derived | `module:Table/useTableRowStatus` | Internal |
+
+Consumer docs own final import syntax, reference tables, and examples when the
+implementation lands.
+
+## Behavioral contract
+
+| ID | Invariant | Basis | Implementation/evidence state |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------- |
+| FR1 | Given a referentially stable `getStatus`, `useTableRowStatus` returns one stable `TablePlugin` that contributes a `transformColumns` function to the parent pipeline. | Current source and stable behavior | Verified baseline; semantic branch pending. |
+| FR2 | At its parent-owned transform position, the module prepends one fixed 28 CSS-pixel, non-resizable generated column. The visually blank header has a localized accessible name; `null` leaves that row's generated cell empty. | Stable `0.5.2` behavior | Owner-directed module contract; composition evidence pending. |
+| FR3 | `TableRowStatus` remains byte-for-byte the exported stable `{color, icon?, label}` interface. `color` always controls paint only. An absent `icon` resolves to the existing dot; a present `icon` resolves to the caller-selected glyph with caller-selected paint, including when the color string is `success`, `warning`, or `error`. | Stable `0.5.2` compatibility and owner direction | Owner-directed; current canary overload must be reverted. |
+| FR4 | `TableSemanticRowStatus` accepts only `success`, `warning`, or `error` plus required `label`. Each status resolves to the matching shared semantic Icon name and semantic tone from the active theme. Caller `color` and `icon` are forbidden. | Owner direction, 2026-09-01; Icon resolution contract | Owner-directed; implementation and theme substitution pending. |
+| FR5 | Internal variant resolves to `icon` for every semantic status, `dot` for custom color without icon, and `icon` for custom color with icon. Variant is internal/anatomy terminology only. | Owner direction, 2026-09-01 | Owner-directed; no public or theme exposure approved. |
+| FR6 | Only `getStatus` forms the exclusive callback union shown above, intersecting the custom interface with `status?: never`. Typed callers cannot provide a supported `status` together with `color` or `icon`; the standalone stable interface is not narrowed. | Owner direction and AST-002 FR15-FR16 | Type shape verified independently; repository fixtures pending. |
+| FR7 | For an untyped object with a supported `status` plus `color` and/or `icon`, semantic status wins, custom fields are ignored, and development emits at most one warning for the loaded row-status module instance. Production emits no warning and renders the same semantic result. | Owner direction, 2026-09-01 | Owner-directed; runtime coverage pending. |
+| FR8 | `label` remains required on both interfaces. The outer indicator exposes one accessible image name; a nested Icon is decorative. Tooltip text is supplemental and not the sole communication path. | Stable behavior and owner direction | Naming is owner-directed; browser and AT evidence pending. |
+| FR9 | The semantic interface supplies a non-color cue through distinguishable themed glyphs. The custom dot makes no promise that caller-selected paint is a shared semantic outcome or an independently non-color cue. | Owner direction and accessibility boundary | Owner-directed; theme and forced-colors evidence pending. |
+| FR10 | The module composes through the parent `TablePlugin` protocol and does not redefine or depend on a private second transform order. It prepends to the columns received at its resolved position and remains valid with supported selection, expansion, grouping, empty-data, and custom-plugin combinations. | Parent protocol and owner direction | Composition matrix pending. |
+
+### Transformation and precedence order
+
+- **ORD1 — Result presence.** `null` produces no indicator. A non-null result moves
+ to branch resolution.
+- **ORD2 — Semantic branch.** A supported `status` selects semantic outcome before
+ custom-marker resolution, deriving matching tone and shared glyph together.
+- **ORD3 — Invalid semantic/custom mixture.** When untyped input also carries
+ `color` or `icon`, ignore those fields. In development, a module-level dedupe
+ emits only the first warning for the loaded module instance; repeated rows and
+ renders do not spam the console. Production renders the semantic result without
+ warning.
+- **ORD4 — Custom branch.** Without supported semantic status, custom `color`
+ selects paint; `icon` presence selects caller glyph versus dot.
+- **ORD5 — Icon delegation.** The module selects a shared semantic Icon name, then
+ the active theme's existing shared registry selects artwork. The theme does not
+ select internal variant.
+- **ORD6 — Parent pipeline.** The module prepends its column at the transform
+ position supplied by `component:Table`; the parent owns all relative ordering
+ and later render phases.
+
+### Performance and resources
+
+- **PR1 — Constant row work.** Result and variant resolution perform constant work
+ per rendered row and add no layout measurement, listener, observer, timer, or
+ asynchronous resource.
+- **PR2 — Stable identity.** A referentially stable `getStatus` preserves the
+ module's `TablePlugin` identity. Adding semantic resolution MUST NOT make
+ unchanged rows rerender solely because the branch moved from `color` to
+ `status`.
+- **PR3 — Existing theme path.** Semantic glyph and tone resolution use existing
+ synchronous Icon/theme paths rather than a parallel registry or per-row theme
+ subscription.
+- **PR4 — Warning bound.** Invalid-input diagnostics retain only one module-level
+ boolean-equivalent dedupe state and emit at most once per loaded module instance.
+
+Current measurements belong in audit evidence. Implementation verification must
+add semantic/custom cases to representative Table render and no-op update budgets.
+
+## Accessibility contract
+
+- **AR1 — Named gutter.** The visually blank generated column header MUST keep one
+ localized accessible name identifying the row-status column.
+- **AR2 — One indicator name.** Every non-null result MUST expose exactly one
+ accessible image name from required `label`; any nested Icon remains decorative.
+- **AR3 — Semantic non-color cue.** Semantic outcomes MUST use distinguishable
+ shared glyphs as well as semantic tone across supported themes and forced-colors
+ behavior.
+- **AR4 — Honest custom contract.** A custom dot remains a caller-selected
+ paint-only marker. Required `label` supplies its programmatic name, but the module
+ MUST NOT claim that the dot itself communicates custom meaning without color.
+- **AR5 — Supplemental tooltip.** Tooltip may repeat `label` as pointer help, but
+ the indicator's accessible name MUST remain sufficient without opening it. The
+ current indicator is not focusable, so tooltip presence is not keyboard evidence.
+- **AR6 — Row context.** Assistive-technology verification MUST confirm the named
+ status is encountered in its row context without duplicate announcements.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Module contract |
+| ----------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | -------------------- |
+| Row-status column | Keeps optional row outcomes aligned in one narrow generated gutter. | This module; relative column order belongs to `component:Table`. | FR1, FR2, FR10, AR1 |
+| Row-status indicator | Owns the row's accessible status name and contains one resolved signifier. | `module:Table/useTableRowStatus` | FR3-FR9, AR2-AR6 |
+| `icon` signifier | Uses a semantic or caller-selected glyph through Icon. | This module selects meaning; `component:Icon` renders. | FR3-FR5, AR2, AR3 |
+| `dot` signifier | Uses the stable custom paint-only dot. | This module with caller-selected paint. | FR3, FR5, AR4 |
+| Invalid untyped mixture | Preserves cohesive semantic outcome without combining custom axes or flooding diagnostics. | `module:Table/useTableRowStatus` | FR6, FR7, ORD2, ORD3 |
+
+No direct row-status target or variant selector is approved. Semantic icon rendering
+delegates to the existing `icon` target. The custom dot has no direct public target.
+Because this specification PR does not change consumer anatomy metadata, it does
+not add an `anatomy-theming:v1` block. A later direct target proposal requires its
+own AST-002 review and synchronized consumer anatomy.
+
+## Parent and system relationships
+
+- `component:Table` owns the aggregate `TablePlugin` transform protocol,
+ base-before-user ordering, canonical named-plugin order, slot composition,
+ failure isolation, context nesting, and plugin-array identity. This module owns
+ only the row-status contribution and MUST NOT duplicate or override that order.
+- `component:Icon` owns glyph presentation, size, color, target, and decorative
+ versus labelled Icon semantics. The row-status indicator keeps the outer name.
+- `architecture:icon-resolution-and-component-slots` owns shared semantic-key
+ resolution. This module selects `success`, `warning`, or `error`; it creates no
+ Table-specific component-icon slot.
+- `architecture:component-theming-surface` owns target qualification and requires a
+ separate decision before any `table-row-status`, `variant`, or `presentation`
+ selector is public.
+- `architecture:public-component-api` and `spec:AST-002/DEC-6` require the stable
+ custom interface, additive semantic interface, and callback-only exclusive
+ boundary to keep each public input's responsibility coherent.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| FR1, FR2, FR10 | Extend `useTableRowStatus.test.tsx` with fixed column metadata, `null`, empty data, grouped rows, selection/expansion combinations, and parent-order permutations. | Module alone and with supported first-party/custom plugins. | The column drops, duplicates, resizes, loses its header name, or assumes a second/private plugin order. |
+| FR3, FR4, FR6 | Add public-subpath compile fixtures for the unchanged interface, declaration merging and extension, semantic interface, callback union, missing labels, unknown statuses, and forbidden mixtures. | Stable custom annotations/extensions; all semantic statuses. | `TableRowStatus` changes or stops merging, semantic usage is inaccessible, or supported status mixes with custom fields. |
+| FR3-FR5 | Extend row-status runtime tests with semantic-looking custom colors, raw/palette dots, explicit custom icons, all semantic statuses, and active-theme substitution. | Custom dot, custom icon, and three semantic outcomes. | Custom color selects an implicit glyph, semantic status bypasses shared resolution, or variant becomes caller/theme input. |
+| FR7, ORD2-ORD4, PR4 | Runtime tests under development and production modes with repeated mixed objects, rows, and renders. | `status + color`, `status + icon`, and all three fields. | Custom input overrides supported status, forbidden fields affect output, production warns, or development warns more than once per loaded module instance. |
+| AR1-AR6 | Existing role/name tests plus browser axe, forced-colors, tooltip modality, and VoiceOver table-navigation evidence. | Semantic glyphs, custom icon, custom dot, `null`, light/dark, and every shipped theme. | Header or indicator loses its name, nested glyph is announced twice, glyph distinctions disappear, tooltip becomes sole meaning, or row context duplicates status. |
+| PR1-PR3 | Extend `Table.perf.test.tsx` with semantic/custom initial render and no-op update cases. | Stable rerender, mixed rows, and theme substitution. | Resolution adds measurement/resources, creates a parallel registry, or exceeds existing representative Table budgets. |
+| Structural ownership | `scripts/check-knowledge.mjs`. | Colocated module, canonical filename/id, and parent backlink. | A missing, duplicate, orphaned, mis-parented, misnamed, or undiscovered record passes validation. |
+| Public hygiene and scope | Prettier, `check:knowledge`, checker tests, `check:repo`, changed-file scan, and public-content scan. | Parent backlink plus one module specification; no Changeset. | Runtime/docs files, private context, invalid record shape, or unrelated changes enter this contract proposal. |
+
+Implementation and browser/assistive-technology evidence are pending. Passing this
+specification PR's checks proves record integrity only, not future runtime behavior.
+
+## Decision log
+
+These entries record the approved owner direction. Runtime implementation and its
+evidence remain pending.
+
+### DEC-1 — Preserve the custom interface; union only at the callback boundary
+
+**Reference:** `module:Table/useTableRowStatus/DEC-1`
+**Direction owner:** cixzhang, 2026-09-01
+
+The exported `TableRowStatus` interface remains byte-for-byte the stable custom
+marker contract so existing annotations, extensions, and declaration merging keep
+working. A separate exported `TableSemanticRowStatus` interface owns semantic
+outcomes. Only `getStatus` forms their exclusive union by intersecting the custom
+interface with `{status?: never}`.
+
+Rejected: replacing `TableRowStatus` with a union alias or adding semantic fields to
+it. Either choice changes the extension surface stable consumers already use.
+
+### DEC-2 — Derive variant and delegate semantic artwork
+
+**Reference:** `module:Table/useTableRowStatus/DEC-2`
+**Direction owner:** cixzhang, 2026-09-01
+
+The module derives internal `icon | dot` variant from semantic versus custom intent.
+Semantic status selects the matching shared Icon name and tone; the active theme
+supplies concrete artwork and token values. Custom color keeps caller-owned paint
+and optional glyph.
+
+Rejected: public `variant` or `presentation`, semantic caller overrides, a
+Table-specific semantic icon registry, and exposing the derived branch as a theme
+axis or data-attribute guarantee.
+
+### DEC-3 — Stable behavior wins over the canary overload
+
+**Reference:** `module:Table/useTableRowStatus/DEC-3`
+**Direction owner:** cixzhang, 2026-09-01
+
+Stable `0.5.2` custom-marker behavior is preserved without a codemod. The canary
+behavior introduced by [#5671](https://github.com/facebook/astryx/pull/5671), where
+semantic-looking `color` values choose icons, must be reverted before stable.
+Canary adopters of that implicit glyph migrate manually to `status`.
+
+Rejected: changing stable custom colors, guessing semantic intent with a codemod,
+or allowing the overload to reach stable while semantic implementation is
+unfinished.
+
+### DEC-4 — Direct row-status theming is not approved
+
+**Reference:** `module:Table/useTableRowStatus/DEC-4`
+**Direction owner:** cixzhang, 2026-09-01
+
+The semantic interface uses Icon's existing target, registry, and theme-owned
+artwork and tone. This contract records generated anatomy but does not add
+`table-row-status`, `presentation`, `variant`, or an equivalent selector surface.
+
+Owner direction holds [#5754](https://github.com/facebook/astryx/pull/5754)
+as written. A future direct target requires separate AST-002 review after painter
+placement, theme-author need, and exact property guarantees are settled.
+
+### DEC-5 — Supported semantic status wins invalid untyped mixtures
+
+**Reference:** `module:Table/useTableRowStatus/DEC-5`
+**Direction owner:** cixzhang, 2026-09-01
+
+For untyped input containing a supported `status` plus `color` and/or `icon`, resolve
+the semantic branch, ignore custom fields, and emit one development warning
+deduplicated for the loaded row-status module instance. Production renders the same
+semantic result without warning.
+
+Rejected: allowing custom fields to override semantic intent, combining axes, or
+warning once per row or render and flooding the console.
+
+## Open questions
+
+None. The owner approved every module-local judgment in this contract.
+Implementation and its evidence remain pending.
+
+## Content boundary
+
+This record does not duplicate consumer import/reference docs, the parent Table
+plugin protocol or ordering, shared Icon/theme algorithms, shared feedback
+language, current audit results, or implementation steps. Runtime code, consumer
+docs, release notes, Changeset, and final browser/assistive-technology evidence
+land separately as implementation of this approved contract.