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.mdindex 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: 3template_version: 3kind: componentid: component:Table-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-09-01owners: [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: []## IntentTable 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 andbody 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, orcontext-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 currenttarget-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 theexpansion plugin runs `transformColumns`; a later custom plugin can add or removecolumns 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 changeinternal 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.mdnew file mode 100644index 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.