docs(Table): define row-status contract

[cixzhang]

User impact

People scanning dense tables get consistent non-color glyphs for semantic success, warning, and error. Existing stable consumers keep every 0.5.2 custom marker unchanged: color remains paint-only, an omitted icon renders the dot, and an explicit icon renders the caller-selected glyph.

Infrastructure

Module-contract infrastructure landed on main in #5833. This PR now targets current main directly.

Semantic before → after

Before: current canaries overload TableRowStatus.color: success, warning, and error select both tone and a default icon, while other colors select paint only.

After: the exported, declaration-mergeable TableRowStatus interface remains byte-for-byte the stable {color, icon?, label} custom-marker contract. A separate exported TableSemanticRowStatus interface adds {status, label}. Only UseTableRowStatusConfig.getStatus forms their exclusive union by intersecting the custom branch with {status?: never}.

Ownership split

• component:Table retains aggregate Table anatomy and the shared TablePlugin protocol: transform phases, base-before-user ordering, known/custom named ordering, sequential composition, slots, failure isolation, context nesting, and plugin-array identity.
• module:Table/useTableRowStatus owns its API and exact interfaces, callback boundary, generated column, internal icon | dot variant, semantic/custom resolution, invalid-input fallback, accessibility, performance/evidence, migration, and theming boundary.

Compatibility and release strategy

• Contract-only change; no runtime, consumer-doc change, or Changeset.
• Stable TableRowStatus annotations, subtypes, extensions, and declaration merging remain valid. Stable 0.5.2 callers require no edit or codemod.
• The implementation follow-up must revert the canary-only overload from #5671 before stable; only canary adopters relying on implicit glyphs migrate manually from color to status.
• Owner direction continues to hold #5754 as written. Direct row-status theming needs separate AST-002 review after the target, painter, and guarantees are justified.

Runtime fallback

For untyped input containing a supported status plus forbidden color and/or icon, semantic status wins. Custom fields are ignored. Development emits one warning deduplicated for the loaded row-status module instance; production renders the same semantic result without warning.

• component:Table and module:Table/useTableRowStatus are both authority: current, approved by cixzhang on 2026-09-01. Runtime implementation remains explicitly pending.

Test plan

• Prettier checks for both changed specifications
• pnpm check:knowledge -- --base origin/main
• focused knowledge/change-scope/path/spec-owner suites (169+ tests)
• strict TypeScript probe for unchanged interface extension/merging, callback-only union, valid branches, and invalid mixtures
• pnpm check:repo
• Markdown table-integrity and public-hygiene scans

No Changeset: specifications only; no published package behavior changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 1, 2026 9:13pm UTC

[cixzhang]

/approve-spec d8511ed

[cixzhang]

/approve-spec 1515367