Skip to content

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

TypeScript

docs(specs): windowed Table row-number columns fit their last logical position (#10666)

Humberto Virtudes289e7cf22bb7
diff --git a/docs/specs/components/Table/Table.spec.md b/docs/specs/components/Table/Table.spec.md
index 2800a08e76..be077a52a4 100644
--- a/docs/specs/components/Table/Table.spec.md
+++ b/docs/specs/components/Table/Table.spec.md
@@ -95,7 +95,9 @@ public behavior and evidence, without privately replacing the Table renderer.
- Retained width compatibility (DEC-2): the compact floor for an explicit column
with omitted width is 60px rather than a zero-width flexible share. Per-column
`proportional(value, {minWidth})` overrides that floor; explicit widths remain
- unchanged and insufficient room uses the existing inline Scroll region. This
+ unchanged, except that a windowed table's recognized row-index cell consumer
+ widens to fit its last position (FR13), and insufficient room uses the existing
+ inline Scroll region. This
existing default correction is not described as preservation of its former
floor merely because the new capabilities are opt-in.
- Retained scroll/target compatibility (DEC-1): shared viewport behavior follows
@@ -219,7 +221,7 @@ Consumer data, columns, props, module signatures and usage remain documented in
| 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. Content in a header cell's `overlay` slot never joins the header's accessible name. 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 |
-| FR13 | In data-driven mode, each explicit column whose `width` is omitted keeps one equal flexible share and a 60px readability floor. A column sets its own floor with `proportional(value, {minWidth})`, which replaces the 60px floor for that column; Table has no table-wide floor setting. Resolution is a pure function of the final column definitions: row values, rendered header/body measurement, locale, sorting, filtering, virtualization, and loading state do not change any floor. Explicit pixel and proportional widths retain their authored floors. When the resolved floors exceed available inline space, the existing Scroll region provides horizontal overflow. | `component:Table/DEC-2`; current source and tests | Verified by width-resolution unit coverage and the ResponsiveScroll real-browser geometry fixture |
+| FR13 | In data-driven mode, each explicit column whose `width` is omitted keeps one equal flexible share and a 60px readability floor. A column sets its own floor with `proportional(value, {minWidth})`, which replaces the 60px floor for that column; Table has no table-wide floor setting. Resolution is a pure function of the final column definitions: row values, rendered header/body measurement, locale, sorting, filtering, virtualization, and loading state do not change any floor. Explicit pixel and proportional widths retain their authored floors. One exception: in a windowed table, a recognized row-index cell consumer, such as the `useTableRowIndex` column, widens to fit the last position in its own font and padding. Table measures this in its first client layout pass and again whenever the logical row count or the column's font or padding changes, before a wider position paints, so windowing never clips a mounted position or falls back mid-scroll; unwindowed tables keep the authored width. When the resolved floors exceed available inline space, the existing Scroll region provides horizontal overflow. | `component:Table/DEC-2`; current source and tests | Verified by width-resolution unit coverage and the ResponsiveScroll real-browser geometry fixture; the windowed row-position floor awaits implementation evidence |
| FR14 | Wherever Table shows a row divider, including while rows glide and in pinned columns, the divider has the width, style and colour the row's border would have: the theme's tokens and any app override on `tr`, `tbody` or `td` borders, so customizations still show. | `component:Table/DEC-3` | Verified by row-expansion glide unit coverage and real-browser divider checks, pinned cells and an open panel included; a transient 1 px WebKit pinned-cell step is a recorded gap |
| FR15 | `useTableRowExpansion` takes an `animatedLayout` option, the handle `spec:AST-105` FR1 defines: when an Expanded detail row opens, the panel plays in and the rows after it glide to their new places; when one closes, it hides at once and the rows after it glide up into its space (`spec:AST-105` Coverage). The Expansion glyph turns on the same motion; under reduced motion the rows move without travel (`spec:AST-105` FR4). Without the option, rows change at once. A table that draws column lines (`dividers="grid"` or `"columns"`) does not glide yet: with the option its panel and rows change at once, as without it, and the glyph keeps its own turn. A `panelVariant="muted"` panel paints its wash on its cell, so the wash slides in with the panel's content (`spec:AST-105` FR9). | `spec:AST-105` FR1, FR4, FR9; owner decision, 2026-10-26 | Opening and closing glides, the case without a handle, the glyph's turn, reduced motion and column lines are tested; the panel's entrance and its hide on close are source-inspected |
| FR16 | Activation and windowing use one explicit canonical `idKey`. Property keys resolve valid strings/finite numbers through the existing string projection; function keys retain string/finite-number type. Missing, null, nonprimitive, nonfinite and duplicate values are invalid for these opt-ins. Table validates the complete logical dataset on data/key changes and supplies status; activation is inert on invalid rows and windowing falls back to full rendering. Internal type-tagged reconciliation keys distinguish numeric `0` from string `"0"` without changing callback equality. Invalid fallback keys are deterministic per record but promise no preserved state under invalid identity. Legacy keys without these opt-ins remain unchanged. | DEC-4; identity and compatibility boundary | Specified; release verification required |
@@ -326,7 +328,11 @@ Consumer data, columns, props, module signatures and usage remain documented in
- **PR3 - Static width resolution.** Explicit-column floors resolve in the existing
O(column count) pass without DOM measurement, observers, extra render passes, or
dependence on row values. The server and client therefore derive the same inline
- width styles from the same column definitions.
+ width styles from the same column definitions. FR13's windowed row-position floor
+ is the one exception: server output and the first client render use the authored
+ width, and Table measures the floor in its first client layout pass and again
+ whenever the logical row count or the column's font or padding changes, before a
+ wider position paints.
## Accessibility contract
@@ -451,7 +457,7 @@ for this aggregate ownership.
| 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`; `useTableColumnResize.test.tsx` "the handle never adds to its column header\'s name (AR1)" and `TableColumnResizeName.a11y.chromium.spec.ts` for the `overlay` slot\'s name | 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` |
-| FR13, PR3 | `Table.test.tsx`, `plugins/columnResize/useTableColumnResize.test.tsx`, `plugins/stickyColumns/useTableStickyColumns.test.tsx`, and `Table.stories.tsx` ResponsiveScroll play assertions | Width-less columns with empty, short, and long-token rows; mixed explicit widths; pinned columns; narrow and fitting containers | Removing the 60px floor, deriving it from row content, changing explicit width semantics, desynchronizing resize bounds or sticky offsets, or preventing the existing Scroll region from activating fails focused unit or real-browser geometry assertions. | `audit:Table/layout` |
+| FR13, PR3 | `Table.test.tsx`, `plugins/columnResize/useTableColumnResize.test.tsx`, `plugins/stickyColumns/useTableStickyColumns.test.tsx`, and `Table.stories.tsx` ResponsiveScroll play assertions; for the windowed row-position floor, `plugins/rowIndex/useTableRowIndex.test.tsx` and a real-browser windowing check, including an append from 999 to 1,000 rows while scrolled to the end, re-measurement after a font, theme, density or host-inset change, and a pinned column after a widened row-number column keeping its inline start at the end of the columns before it (an overlap fails) | Width-less columns with empty, short, and long-token rows; mixed explicit widths; pinned columns; narrow and fitting containers; windowed numbering at each density's first 48px overflow: compact row 10,000, balanced row 1,000, spacious row 100 | Removing the 60px floor, deriving it from row content, changing explicit width semantics, desynchronizing resize bounds or sticky offsets, or preventing the existing Scroll region from activating fails focused unit or real-browser geometry assertions. A windowed number column that clips a number, falls back when a longer number mounts or its font or padding changes (host inset included), or narrows below its authored width, or an unwindowed one that widens, fails. | `audit:Table/layout` |
| FR14 | `__tests__/TableRowGlide.a11y.browser.spec.ts` screenshot checks of the divider mid-glide, in pinned columns, and under an open detail panel; `plugins/rowExpansion/useTableRowExpansion.glide.test.tsx` for the divider an open panel carries | a theme with a custom divider colour; an app override of a row's border; both mid-glide and on a pinned cell; an open detail panel's divider under the same theme and override | a divider whose width, style or colour differs from the row's border, or that drops a theme or app override, fails | `audit:Table/theming` |
| FR15 | `plugins/rowExpansion/useTableRowExpansion.glide.test.tsx` and `__tests__/TableRowGlide.a11y.browser.spec.ts`: row expansion with and without `animatedLayout`, plus source inspection of the panel's entrance and its hide on close | open and close with the handle; without it; reduced motion under a coarse and a fine pointer; a glyph turn beside the glide; a `dividers="grid"` and a `dividers="columns"` table with the option; a muted panel mid-open | rows that jump with the handle in a table without column lines, a closing panel that animates or leaves its space empty before the rows arrive, a panel and rows on different motion, a glyph on its own timing beside the glide, travel under reduced motion, or any motion without the handle a table with column lines that glides or animates its panel, or one whose glyph does not keep its own turn, fails | `audit:Table/plugins` |
| Accessibility contract | `__tests__/Table.a11y.test.tsx` and `__tests__/Table.a11y.chromium.spec.ts` bind Table to the base Table contract (`internal/a11y-spec`), composing each module's contract only for the states rendered with that module: the sort module contract (`plugins/sortable/__tests__/useTableSortable.a11y.ts`) for the sorted state; `__tests__/TableScroll.a11y.chromium.spec.ts` keeps the Scroll region evidence | Labelled data-driven, sorted descending, composed RTL with row headers, and empty data | Losing the table role or declared name, row, header, or cell roles, or a part leaving its row or the table, fails the base binding; a missing or stale `aria-sort` fails the composed sort module contract. | `audit:Table/accessibility` |
@@ -483,8 +489,16 @@ A data-driven column with omitted `width` resolves as one flexible share with a
{minWidth})` sets that column's floor, and `proportional()` without `minWidth`
keeps its 120px default. Resolution uses only column definitions, so pagination,
sorting, filtering, virtualization, empty and loading states, SSR, and hydration
-cannot change any floor. Rejected: deriving the floor from rendered or sampled
-content, because it shifts with data and view state.
+cannot change any floor. One exception applies while `Table.virtualization`
+windows a table: a recognized row-index cell consumer, such as the
+`useTableRowIndex` column, keeps at least its authored width and widens to fit the
+last position, the logical row count, in the column's own font and padding at the
+active density. Table measures that width in its first client layout pass and
+again whenever the logical row count or the column's font or padding changes,
+before a wider position paints, because windowing must never clip a mounted
+position or fall back to full rendering mid-scroll; unwindowed tables keep the
+authored width. Rejected: deriving the floor from rendered or sampled content,
+because it shifts with data and view state.
### DEC-3 — A drawn divider keeps the row border's source