@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Table/plugins/infiniteScroll/useTableInfiniteScroll.spec.md

@@ -1,244 +0,0 @@
----
-schema_version: 3
-template_version: 3
-kind: module
-id: module:Table/useTableInfiniteScroll
-authority: draft
-archive_reason: null
-superseded_by: null
-approved_by: null
-approved_at: null
-owners: [cixzhang]
-review_triggers:
-  [public-api, behavior, layout, theming, accessibility, interaction]
-verified_by:
-  [
-    packages/core/src/Table/plugins/infiniteScroll/useTableInfiniteScroll.test.tsx,
-    packages/core/src/Table/__tests__/TableInfiniteScroll.a11y.chromium.spec.ts,
-    packages/core/src/Table/Table.perf.test.tsx,
-    scripts/check-knowledge.mjs,
-  ]
-parent_component: component:Table
-references:
-  [
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-    architecture:react-component-runtime,
-    spec:AST-002,
-    spec:AST-009,
-    spec:AST-020,
-  ]
----
-
-# useTableInfiniteScroll module contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                             |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | Candidate `useTableInfiniteScroll` hook returning one `TablePlugin` from controlled `hasMore`, controlled `isLoading`, and `onLoadMore`; root, reset, fallback, and look-ahead inputs remain unadmitted until their owner decisions pass.                                            |
-| Behavior                | One end sentinel requests the next batch as it approaches the relevant block-scroll viewport, never overlaps requests, and rearms when loading completes while more data remains.                                                                                                    |
-| End-user impact         | People can continue through incrementally loaded rows without duplicate requests, focus disruption, inaccessible progress, or a dead end when automatic observation is unavailable.                                                                                                  |
-| Builder impact          | Builders own data, request state, errors, and appended rows. The plugin owns observation, duplicate suppression, progress/fallback presentation, and cleanup.                                                                                                                        |
-| Compatibility/readiness | Additive, unreleased module. This draft is not implementation authority. Scroll-root ownership, request completion/reset, parent rendering-mode seam, fallback policy, loading/error composition, customization, and announcement evidence require owner decisions before promotion. |
-| Review checks           | Reject viewport assumptions, overlapping loads, stale callbacks, a permanently visible sentinel loop, unexplained focusable sentinels, progress announced on every observer tick, a mouse-only fallback, invalid table DOM, retained observers, or router/data-client dependencies.  |
-| Governing rules         | `component:Table` FR9-FR12 and ORD1-ORD4 own plugin composition; `architecture:react-component-runtime` owns observer lifetime; `architecture:public-component-api` and `spec:AST-002` own public caller burden.                                                                     |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-`useTableInfiniteScroll` connects incremental data loading to a data-driven Table
-without making Table own a router, cache, query client, cursor format, or product data.
-It owns an end sentinel, observation lifecycle, one-request-at-a-time behavior,
-rearming, accessible progress, and a keyboard-operable fallback.
-
-Infinite scroll is distinct from client pagination and virtualization. It appends data;
-it does not choose the caller's page/cursor protocol or bound the number of rendered rows.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`; Table behavior remains unchanged unless the new plugin is supplied.
-- Compatibility class: additive public hook, types, documentation, and examples.
-- Migration decision: `module:Table/useTableInfiniteScroll/DEC-1` after the open ownership decisions are approved.
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The public hook, configuration, sentinel, observer lifecycle, and loading trigger boundary.
-- Duplicate-request suppression, rearming after completion, and short-batch behavior.
-- Default progress and manual fallback behavior, accessibility, performance, and evidence.
-- Composition with Table's scroll wrapper, empty state, loading state, appended rows, other plugins, and the candidate children-mode warning/no-op, blocked on OQ8's parent contract decision.
-
-**Does not own / non-goals**
-
-- Aggregate `TablePlugin` protocol, transform order, or scroll-wrapper implementation — owned by `component:Table`.
-- Product data, request/cursor/page state, cache policy, retry policy, or error content — owned by the caller or another module.
-- Client pagination, server pagination, Relay integration, row virtualization, or column virtualization.
-- Scroll restoration, URL state, routing, or prefetching.
-- A new public Table theme target unless a separate approved decision establishes a distinct theme-author need.
-- Caller-composed children-mode semantics or the parent rendering-mode contract. The candidate warning/no-op depends on OQ8; the module never interprets caller children or infers mode from DOM to append loading UI.
-
-## Public API and concepts
-
-The candidate minimum shape is:
-
-```ts
-export interface UseTableInfiniteScrollConfig {
-  hasMore: boolean;
-  isLoading: boolean;
-  onLoadMore: () => void | Promise<void>;
-}
-
-export function useTableInfiniteScroll<T extends Record<string, unknown>>(
-  config: UseTableInfiniteScrollConfig,
-): TablePlugin<T>;
-```
-
-The final shape is blocked on OQ1-OQ8. Consumer docs own final signatures,
-defaults, imports, and examples after promotion.
-
-| Concept         | Closed values or states                     | Meaning                                                                                          | Default                  | Owner                                 | Stability |
-| --------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------ | ------------------------------------- | --------- |
-| More-data state | `hasMore` true or false                     | Whether another load may be requested.                                                           | Controlled               | Caller through this module            | Candidate |
-| Loading state   | `isLoading` true or false                   | Whether a request is already in flight.                                                          | Controlled               | Caller through this module            | Candidate |
-| Load request    | `void` or promise-returning callback        | Starts one caller-owned append operation without prescribing its data protocol.                  | No request while blocked | Caller through this module            | Unsettled |
-| Look-ahead      | Optional non-negative distance, if admitted | Starts loading before the sentinel reaches the visible block-end edge.                           | Not yet admitted         | Caller/module boundary                | Unsettled |
-| Sentinel        | Observed, loading, exhausted, unavailable   | Coordinates automatic loading without becoming unexplained table data or an accidental tab stop. | Derived                  | `module:Table/useTableInfiniteScroll` | Candidate |
-| Manual fallback | Available or hidden                         | Provides an explicit load command when automatic observation is unavailable or unsuitable.       | Unsettled                | `module:Table/useTableInfiniteScroll` | Unsettled |
-
-## Behavioral contract
-
-| ID   | Candidate invariant                                                                                                                                                                                                                                                                                                                                        | Basis                                            | Draft review state                      |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------- |
-| FR1  | Stable configuration callbacks and unchanged primitive inputs preserve one stable `TablePlugin`.                                                                                                                                                                                                                                                           | Parent plugin identity and runtime architecture  | Settled candidate                       |
-| FR2  | The plugin contributes one end sentinel after the semantic `<table>`, inside the Table scroll-wrapper content. It never inserts non-row content inside `<table>`, `<thead>`, `<tbody>`, or `<tr>`.                                                                                                                                                         | Valid HTML and parent wrapper contract           | Settled candidate                       |
-| FR3  | Automatic loading is armed only when `hasMore` is true and `isLoading` is false. One visibility episode produces at most one active request.                                                                                                                                                                                                               | Duplicate suppression                            | Settled candidate                       |
-| FR4  | While a load is in flight, the module does not call `onLoadMore` again, including through repeated observation, manual activation, or rerender. Completion can make another call eligible only for the current configuration, subject to the controlled inputs and FR14. The caller remains solely responsible for suppressing stale product-data commits. | Controlled state and async ownership             | Callback completion contract unsettled  |
-| FR5  | When a short append leaves the sentinel visible and `hasMore` remains true, completing the prior load can request the next batch without requiring the user to scroll away and back.                                                                                                                                                                       | Continuous loading behavior                      | Settled outcome; mechanism free         |
-| FR6  | `hasMore=false` disconnects observation, removes the manual command, and presents no loading state. Changing back to true can arm a new request.                                                                                                                                                                                                           | Exhausted-state boundary                         | Settled candidate                       |
-| FR7  | An observer-unavailable environment preserves server rendering/hydration and exposes the approved manual fallback rather than throwing or silently dead-ending the user.                                                                                                                                                                                   | Progressive enhancement                          | Fallback policy unsettled               |
-| FR8  | Loading progress is shown and announced at most once per state transition, not once per observer callback. Error and retry UI remain caller-owned and do not render duplicate progress chrome.                                                                                                                                                             | Accessibility and module boundary                | Composition surface unsettled           |
-| FR9  | The module does not call another plugin's callbacks, mutate selection/activation/expansion/sort/filter state, replace product rows, or reset scroll position. Preservation of caller-controlled state follows from that non-interference; caller data updates remain caller-owned.                                                                         | Plugin independence                              | Settled candidate                       |
-| FR10 | Empty data may still load when `hasMore=true`; default EmptyState and load affordance do not obscure each other or communicate contradictory states.                                                                                                                                                                                                       | Empty/loading composition                        | Human layout decision                   |
-| FR11 | Approved scroll-root or look-ahead changes reconnect observation without leaking the old observer or triggering from a detached sentinel. Unmount and node replacement release every observer and retained node.                                                                                                                                           | `architecture:react-component-runtime`           | Settled candidate                       |
-| FR12 | The plugin remains data-protocol agnostic. `onLoadMore` receives no Table-owned page, cursor, Relay, router, cache, or request-client object.                                                                                                                                                                                                              | Public ownership boundary                        | Settled candidate                       |
-| FR13 | In children mode the module is a no-op and emits at most one deduplicated development warning. This candidate outcome depends on OQ8's missing parent contract; it does not establish a rendering-mode signal on the current Table wrapper transform or permit mode inference from DOM.                                                                    | Missing `component:Table` dependency, OQ8        | Hold: parent contract decision required |
-| FR14 | Reconfiguration during a load follows one approved caller-visible reset or React remount boundary. Settlement from a load started before that boundary neither calls `onLoadMore`, makes a call eligible, nor changes loading presentation for the current configuration. Caller response ownership remains unchanged.                                     | Caller-visible reset and stale-completion safety | Human API decision                      |
-
-### Transformation and precedence order
-
-- **ORD1 — Exhausted/loading gate.** Resolve `hasMore` and `isLoading` before observing or exposing a manual command.
-- **ORD2 — Current configuration.** Calls use the current `onLoadMore` and respect the approved reset/remount boundary; changing callback identity alone does not end an in-flight load or silently redefine product-data ownership.
-- **ORD3 — One load at a time.** From invocation of `onLoadMore` until the approved completion condition, no observation or manual activation invokes it again, including reentrant activation from caller code. Synchronous throws and asynchronous settlement follow OQ2's completion rule.
-- **ORD4 — Completion after reset.** FR14 excludes settlement from before a reset/remount from invoking or enabling a call or changing current loading presentation. Completion of a current-configuration load follows OQ2/OQ5 and the controlled inputs; the plugin never commits or rejects caller data.
-- **ORD5 — Rearm.** Controlled completion and continued `hasMore` rearm the current sentinel, including when it remains visible.
-- **ORD6 — Presentation.** Exhausted, loading, automatic, fallback, and error-adjacent states render one coherent after-table surface.
-- **ORD7 — Parent pipeline.** In data mode the module appends to accumulated `afterTable` content and preserves prior wrapper props, styles, refs, and chrome; children mode returns prior props unchanged, subject to OQ8's parent contract dependency.
-
-### Performance and resources
-
-- **PR1 — One observer.** At most one `IntersectionObserver` and one observed sentinel exist per mounted plugin instance.
-- **PR2 — No scroll listener.** Native observation, not a per-frame or per-scroll JavaScript listener, drives automatic loading.
-- **PR3 — Stable resources.** Callback updates do not recreate observation when the approved root/look-ahead geometry and sentinel are unchanged.
-- **PR4 — Complete cleanup.** Unmount, sentinel replacement, root replacement, exhaustion, and loading transitions release obsolete observation.
-- **PR5 — Constant callback work.** An observer entry performs constant coordination work and never scans rows or columns.
-
-## Accessibility contract
-
-- **AR1 — Valid structure.** Sentinel, progress, and fallback UI stay outside the semantic table and do not appear as data rows or cells (WCAG 2.2 SC 1.3.1; DOM/accessibility-tree and browser evidence).
-- **AR2 — Progress announcement.** Loading transitions use a non-interruptive status that does not repeat for observer churn or every appended row (WCAG 2.2 SC 4.1.3). Deterministic transition tests prove event count/order, and the approved implementation requires NVDA + Chrome on Windows and VoiceOver + Safari on macOS to prove spoken announcement timing under `spec:AST-009` FR4 and FR12.
-- **AR3 — Operable fallback.** The approved fallback is a real keyboard-operable control with a localized name and visible focus; the sentinel itself is not an unexplained tab stop (WCAG 2.2 SC 2.1.1, 2.4.7, and 4.1.2; DOM/axe/real-browser evidence).
-- **AR4 — Focus stability.** Appending rows does not move focus, reset focused descendants, or make the fallback disappear while it owns focus without a deterministic successor (WCAG 2.2 SC 2.4.3 and 2.4.7; real-browser keyboard evidence).
-- **AR5 — Reduced motion.** Progress presentation does not require motion to communicate loading state and respects platform motion settings; real-browser visual evidence proves the supported states.
-- **AR6 — Touch and zoom.** Automatic loading and fallback remain available without hover, precision pointing, or a fixed viewport size (WCAG 2.2 SC 1.4.10 and 2.1.1; responsive/touch real-browser evidence).
-- **AR7 — Evidence boundaries.** Real AT evidence is limited to AR2's announcement claim or any later approved AT-dependent outcome; it supplements rather than replaces deterministic state, DOM, keyboard, and browser coverage.
-
-## Design relationships
-
-| Anatomy or state    | Design requirement                                                                    | Representation authority  | Module contract   |
-| ------------------- | ------------------------------------------------------------------------------------- | ------------------------- | ----------------- |
-| End sentinel        | Supplies observation geometry without masquerading as table data or a control.        | This module               | FR2-FR7, AR1      |
-| Loading progress    | Communicates one active append operation without duplicating caller-owned chrome.     | Unsettled pending OQ4     | FR3-FR8, AR2, AR5 |
-| Manual load command | Provides an explicit fallback with normal control semantics and focus treatment.      | Unsettled pending OQ3/OQ4 | FR7-FR10, AR3-AR4 |
-| Exhausted state     | Stops requesting and removes load affordances without adding an unsolicited message.  | This module               | FR6, ORD1, ORD5   |
-| Error/retry         | Remains outside the module unless a later loading/error composition contract owns it. | Caller or another module  | FR8, non-goal     |
-
-The module adds no direct theme target. OQ3/OQ4 must select any progress/fallback component and then name its exact existing target or record a classified `none`; no delegation is promised yet. Sentinel geometry is implementation detail rather than theme API.
-
-## Parent and system relationships
-
-- `component:Table` owns the scroll-wrapper phase and accumulated `afterTable` slot. **Missing parent dependency (OQ8):** its current contract does not establish a data/children mode signal at that phase. The module remains on hold until the parent contract records the approved mode distinction or makes the invalid combination unrepresentable; FR13 then cites that owning claim. This draft neither supplies a field nor approves a parent API change.
-- `architecture:react-component-runtime` owns observer acquisition, current-value synchronization, node replacement, StrictMode replay, and cleanup boundaries.
-- `architecture:public-component-api` and `spec:AST-002` require a protocol-agnostic API whose inputs express caller-owned state rather than implementation clients.
-- `spec:AST-009` and `spec:AST-020` own announcement evidence and the WCAG/evidence-layer boundary; AR2 is the only current real-AT-dependent claim.
-- Pagination and virtualization remain separate modules. Infinite loading can compose with them only where their current contracts explicitly permit it.
-
-## Verification map
-
-| Contract                            | Verification                                                                                                    | Representative states                                                                                     | Mutation or failure expectation                                                                                                                                                         |
-| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1, FR3-FR7, FR14, ORD1-ORD5       | Deterministic observer events, callback count/order assertions, and controlled rerenders                        | Visible/hidden, loading, exhausted, short batch, reentrant activation, throw, async settle, reset/remount | Calls overlap, pre-reset completion invokes or enables a call or changes current loading presentation, short batches dead-end, observation throws, or rearm fails.                      |
-| FR2, FR8-FR10, FR12-FR13, ORD6-ORD7 | Table render and plugin-composition tests against the parent rendering-mode contract once OQ8 is resolved       | Data/children mode, empty/non-empty, wrapper chrome, loading, exhausted, caller error UI                  | Invalid DOM appears, children mode renders a sentinel, warning repeats, prior chrome is lost, caller state is mutated, or states contradict; absent parent authority keeps OQ8 on hold. |
-| FR11, PR1-PR5                       | Observer lifecycle tests under StrictMode, root/sentinel/look-ahead change, unmount, and no-op rerender         | Every approved acquisition, replacement, and release path                                                 | More than one observer survives, detached nodes remain observed, or stable inputs churn resources.                                                                                      |
-| AR1, AR3-AR7                        | DOM/accessibility-tree assertions, axe, and real-browser keyboard/touch/zoom/reduced-motion/focus flows         | Automatic, fallback, loading, append, exhaustion, observer unavailable                                    | Sentinel becomes a row/tab stop, focus is lost, fallback is inoperable, or responsive/motion behavior carries required meaning.                                                         |
-| AR2                                 | Deterministic status-transition count/order tests plus NVDA + Chrome on Windows and VoiceOver + Safari on macOS | Initial load, repeated observer entries, short batches, completion, exhaustion                            | Status repeats, arrives out of order, is skipped, or announces observer churn/appended rows instead of loading transitions.                                                             |
-| Public API and docs                 | Public-subpath compile fixture, `.doc.mjs`, generated inventory, Storybook, and one generic async-cache recipe  | Controlled state, promise/void callback, approved reset/root/fallback/look-ahead inputs                   | API leaks a client, exposes look-ahead without admission, cannot express the approved reset boundary, promises unsettled behavior, or permits contradictions.                           |
-| Performance                         | Extend Table performance coverage with stable no-op, observer callback, and repeated append budgets             | Large representative data and repeated batches                                                            | Stable rerenders recreate resources, callbacks scan rows, or appends exceed recorded budgets.                                                                                           |
-| Structural ownership                | `pnpm check:knowledge`                                                                                          | Draft module and parent backlink                                                                          | A missing, orphaned, misnamed, wrong-kind, or duplicate module record passes validation.                                                                                                |
-
-## Decision log
-
-### DEC-1 — Infinite scroll owns loading coordination, not data
-
-**Reference:** `module:Table/useTableInfiniteScroll/DEC-1`
-**Decider:** pending owner approval
-
-The module observes the end of rendered Table content and asks the caller for another batch. It owns at-most-one-in-flight loading, callback eligibility after completion/reset, rearming, and presentation under FR4/FR14 and ORD2-ORD5, not an internal coordination mechanism. The caller remains the sole owner of rows, request protocol, cache, cursor/page, stale-response suppression, errors, and retry policy.
-
-Rejected: importing a router/query client, mutating Table data, or combining cursor,
-server-pagination, Relay, and infinite-loading contracts.
-
-### DEC-2 — The sentinel is after the table
-
-**Reference:** `module:Table/useTableInfiniteScroll/DEC-2`
-**Decider:** pending owner approval
-
-Observation and progress UI use the parent scroll wrapper's `afterTable` slot. They never
-insert non-row elements into semantic table structure or synthesize a fake data row.
-
-Rejected: a `<div>` inside `<tbody>`, a sentinel `<tr>` announced as data, and a focusable
-sentinel with no user command.
-
-### DEC-3 — Automatic loading requires an operable fallback
-
-**Reference:** `module:Table/useTableInfiniteScroll/DEC-3`
-**Decider:** pending owner approval
-
-Automatic observation is progressive enhancement. An approved fallback prevents a dead
-end when observation is unsupported, disabled, or unsuitable and gives keyboard users an
-explicit command without making the sentinel itself interactive.
-
-Rejected: silently doing nothing without IntersectionObserver and making automatic loading
-the only path.
-
-## Open questions
-
-- **OQ1 — Who owns the block-scroll root?** (`human-api`) Decide viewport default versus an explicit caller root/ref, and how Table nested in a vertical `ScrollableArea` identifies the correct root without brittle ancestor discovery.
-- **OQ2 — What observable event completes a load?** (`human-api`) Decide whether controlled `isLoading`, a returned promise, or both permit another `onLoadMore` call after synchronous throw and asynchronous settlement.
-- **OQ3 — When is manual fallback shown?** (`human-design`) Decide always-visible, observer-unavailable-only, user-selected, or another policy; define focus behavior when loading/exhaustion removes it.
-- **OQ4 — What loading customization is public?** (`human-api`) Decide whether the module renders one fixed default, accepts `renderLoadingIndicator`, composes an existing loading-state module, or stays behavior-only while still meeting progress requirements.
-- **OQ5 — How do error and retry compose?** (`human-api`) Keep error content caller-owned, but define how a failed request rearms automatic loading and avoids immediate retry loops or duplicate loading/error chrome.
-- **OQ6 — Is caller-configurable look-ahead admitted?** (`human-api`) First prove a non-derivable caller distinction under `spec:AST-002`; if admitted, choose an intent-named distance API with explicit units/default rather than reusing browser `threshold` terminology, which conventionally means an intersection ratio. Keep it out of the candidate interface until then.
-- **OQ7 — What is the caller-visible reset boundary?** (`human-api`) Decide an explicit caller-owned reset identity versus a documented React remount/key boundary when dataset/query configuration changes during a load. Pre-reset settlement neither invokes nor enables a call nor changes loading presentation for the current configuration; stale product-data suppression remains the caller's job.
-- **OQ8 — Which parent contract distinguishes data from children mode?** (`human-api`) Decide a parent-owned rendering-mode signal at the wrapper transform versus making the invalid combination unrepresentable, preserving FR13's warning/no-op outcome for children mode. The chosen behavior belongs in `component:Table`, and FR13 must cite its approved owning claim before this module is promoted. This missing dependency remains on hold; no parent field or approval is assumed.
-
-## Content boundary
-
-This record does not duplicate consumer signatures/examples, the parent Table wrapper
-protocol, general observer mechanics, current usage audits, implementation steps, or
-pagination/virtualization/data-client contracts. It links to their canonical owners.

package/src/Table/plugins/rowStatus/useTableRowStatus.spec.md

@@ -1,355 +0,0 @@
----
-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/meta/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/meta/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.** The named status is exposed in its row context without a
-  duplicate name, proved at the accessibility tree. Assistive-technology
-  observation of the announcement is recommended follow-up under `spec:AST-009`.
-
-## 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 accessibility-tree row-context evidence; VoiceOver table navigation is recommended follow-up.                     | 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/meta/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/meta/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.