useTableColumnsVirtualization module contract¶
Contract at a glance¶
| Area | Contract |
|---|---|
| Public contract | useTableColumnsVirtualization({initialViewportWidth}) returns an opaque TableVirtualizationCapability; Table.virtualization takes it alone or in a list beside the rows capability. Table retains data, columns, identity, widths and plugins. |
| Behavior | Inline-axis windowing of the unpinned columns between the pinned start and end runs, with two internal overscan columns per side, at most one retained focused column, native table semantics and parent-owned pre-cell planning. |
| End-user impact | Mounted cells keep their controls, focus and full-table column positions; unmounted columns are not promised virtual-cursor discovery. |
| Builder impact | Callers keep their column definitions and widths and accept single-line content; a columns-only Table keeps its block sizing, and unsupported content or structure falls back to rendering every column. |
| Compatibility/readiness | Additive capability; output without it is unchanged. Implementation and numerical verification remain separate release requirements. |
| Review checks | Reject render-then-hide, a second scroll owner, header/body column drift, lost focus, unbounded retention, window-relative column positions and unmeasured budget claims. |
| Governing rules | component:Table owns columns, widths, pinned runs, admission, render planning and the viewport. module:Table/useTableRowsVirtualization owns the block axis. architecture:list-windowing owns the shared window computation. spec:AST-025 FR18/FR19 constrain scrolling. |
This table is a review projection; the body below is authoritative.
Intent¶
useTableColumnsVirtualization bounds mounted cells for a Table with many
columns. Its capability carries only a seed width; the widths come from the
Table's own column layout, and Table owns the semantic rendering pipeline.
Compatibility and migration¶
- Released default preserved:
yes; without the capability, Table output is unchanged. - Compatibility class: additive hook and capability.
Table.virtualizationwidens from one capability to one capability or a list, which keeps every existing call valid. - Migration decision:
module:Table/useTableColumnsVirtualization/DEC-1andcomponent:TableFR18.
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary¶
Owns
- The inline seed, the windowed run between the pinned runs and Table's admission into the shared list window.
- Table's retained-focus participation, the column anchor policy and column-windowed accessibility outcomes.
- Column-windowing admission and its performance targets.
Does not own / non-goals
- Columns, widths, pinned runs, resizing, column settings, identity, rendering mode and the viewport:
component:Tableand their plugin modules. - Block-axis windowing:
module:Table/useTableRowsVirtualization. - The visible range, internal overscan, inline gap geometry, the first-visible-key anchor math, the focus-column retention and the offset helpers: the shared windowing module,
architecture:list-windowing. This module supplies Table's column pitches, pinned runs and admission to it. - Grouped or multi-row headers, cells that span columns, detail or custom rows, vertical writing modes, page-level horizontal scrolling, an overscan setting or a
scrollToColumnAPI.
Public API and concepts¶
The hook returns an opaque TableVirtualizationCapability from
initialViewportWidth, never columns or widths. The initial width only seeds the
first window; it sizes no element. After mount, the measured inline viewport sets
the window.
| Concept | Values or states | Meaning | Default | Owner | Stability |
|---|---|---|---|---|---|
| Seed | Positive finite CSS-pixel initialViewportWidth |
The inline viewport width the first window plans for | Required | This module | Stable |
| Capability | Opaque Table-compatible value | Carries inline intent, not sliced columns or an engine handle | Absent without opt-in | This module; parent consumption | Stable |
| Column pitch | The width Table layout gives each column at the table's minimum width | One width per column, the same widths pinned offsets use | Derived | component:Table |
Parent dependency |
| Windowed run | The unpinned columns between the pinned start and end runs | The only columns that can unmount | Derived | This module | Stable |
| Range | Half-open contiguous interval of the windowed run | Viewport-intersecting columns before overscan | Derived | architecture:list-windowing |
Stable |
| Focus column | Absent or one retained column | Keeps the focused cell's column mounted outside the range | Absent | architecture:list-windowing; existing focus owner |
Stable |
| Metadata | Logical column index and column count | One source for aria-colindex and aria-colcount |
Derived | component:Table |
Parent dependency |
Behavioral contract¶
These requirements define the complete normative contract. Implementation, browser, accessibility and performance verification remain release requirements.
| ID | Invariant | Basis | Verification state |
|---|---|---|---|
| FR1 | Unchanged seed preserves capability identity. Unchanged columns, widths, pinned runs, data and mounted range preserve output identities and do not invoke product renderers again. | Parent memoization | Required for release |
| FR2 | Pinned start and end runs always mount. In the windowed run, mounted columns are one contiguous range with two overscan columns per side plus at most one discontiguous focused column. With no unpinned column, column windowing changes nothing. | DEC-2; bounded DOM | Required for release |
| FR3 | Each column's pitch is the width Table layout gives it at the table's minimum width, the same width pinned offsets use, including a widened row-number column. When the inline viewport is at least the table's minimum width, every column mounts. | Parent FR13/FR19; DEC-3 | Required for release |
| FR4 | The header row and every body row render the same column structure: the pinned start cells, at most three inaccessible native spacer cells around the mounted range and focused column, the mounted cells and the pinned end cells. A spacer has the summed width of the columns it stands for and no content, padding, border, state, focus stop or product transform. | Native HTML; header association | Required for release |
| FR5 | While columns are windowed, Table exposes aria-colcount equal to the full column count, and every mounted header and body cell carries aria-colindex for its full-table position. Without column windowing, neither attribute is added. |
Parent FR23; full-table semantics | Required for release |
| FR6 | Server and first client use the same seed: the windowed columns whose start lies within initialViewportWidth less the widths of both pinned runs, plus overscan. There is no full-render-then-collapse or empty-then-repair. |
SSR; runtime architecture | Required for release |
| FR7 | A focused cell whose column leaves the range keeps that column mounted with its original subtree. Real focus departure, removal or return releases it; focus transfer replaces it. Scrolling alone never moves focus. | Existing focus owner; DEC-4 | Required for release |
| FR8 | Column order, width, visibility and pinning changes preserve the first visible column's key and its fractional offset; a removed anchor resolves to the next surviving column, then the previous one, then the start. | Column settings and resize; DEC-4 | Required for release |
| FR9 | Inline geometry uses the parent's shared viewport measurement and pooled resize path; column windowing adds no subscription, observer or frame of its own. The pinned runs' widths are subtracted from the inline viewport once. | Parent FR19; spec:AST-025 | Required for release |
| FR10 | With useTableRowsVirtualization, rows and columns window together: a row gap spans the mounted column structure, and a retained focused cell keeps both its row and its column. |
Rows module FR2/FR7 | Required for release |
| FR11 | Before rendering, admission requires data mode, explicit valid identity (parent FR18), the Table-owned scroll wrapper, a single header row, flat rows and a declared Table minimum width no wider than the columns' sum; a spanning cell found after mount latches the same fallback. Any unsupported case renders every column with a development warning. | Parent FR18; DEC-2 | Required for release |
| FR12 | A list passed to Table.virtualization holds at most one rows capability and one columns capability; any other list renders without windowing and warns once in development. |
Parent FR18; DEC-1 | Required for release |
| FR13 | Mounting or unmounting a column changes no row's height: unspecified textOverflow defaults to single-line truncation, and explicit wrap or a custom cell renderer without fixed-height admission renders every column. |
Rows module FR14; DEC-2 | Required for release |
| FR14 | A columns-only Table keeps the block sizing and block scrolling it has without windowing; only a rows capability gives the Table a parent-sized block viewport (component:Table FR19). |
Parent FR1/FR19 | Required for release |
Performance and resources¶
- PR1 — Structural bound. With an unobscured inline viewport
Wand the narrowest windowed column widthw, mounted windowed columns are at mostceil(W/w)+1+4+1; the last is the optional focused column. Cells scale with mounted rows times mounted columns, never with the total column count. - PR2 — Stable work. A scroll within the current range invokes zero product renderers; a range change mounts and unmounts only the columns that enter or leave.
- PR3 — Timing targets. At 1,000 columns, the p95 range-plus-commit for an inline scroll is at most 4 ms with 20 mounted rows; a no-op scroll is at most 2 ms.
- PR4 — Evidence. Targets are release requirements, not measured results; verification records environment, browser, column count, widths and p50/p95/max.
Accessibility contract¶
- AR1 — Native semantics. Header association stays positional and native; spacers have no accessible name, role as data, control or state.
- AR2 — Positions.
aria-colindexandaria-colcountreport full-table positions (FR5); claims cover mounted cells only. - AR3 — Keyboard access. The parent's named viewport keeps native arrow scrolling on both axes and Tab through mounted controls; Tab does not claim to reach unmounted columns.
- AR4 — Focus retention. FR7 keeps the focused cell's column; focus never jumps because a column unmounted.
Design relationships¶
| Anatomy/state | Design requirement | Representation authority | Module contract |
|---|---|---|---|
| Product cell | Same appearance and controls as without windowing | Existing Table targets and state owners | FR4; FR11 |
| Spacer cells | Geometry only; inaccessible and unpainted | This module; no theme target | FR4 |
| Pinned runs | Always mounted, offsets unchanged | useTableStickyColumns |
FR2; FR3 |
| Viewport | One coordinated Table-owned scroll region | Parent FR19 | FR9 |
The module adds no theme target.
Parent and system relationships¶
component:TableFR13 owns column widths and floors; FR18 owns admission and theTable.virtualizationprop; FR19 owns the both-axis viewport and shared geometry.useTableStickyColumnsowns pinned runs and their offsets, which this module reads and never moves.useTableColumnResizeand column settings own width, order and visibility changes; FR8 keeps the inline anchor across them.module:Table/useTableRowsVirtualizationowns the block axis; FR10 governs the combination.architecture:list-windowingowns the shared windowing module. It computes the column range, the retained focus column and the anchor from the pitches, pinned runs and inline geometry that Table supplies, as it does for rows.
Verification map¶
| Contract | Verification | Representative states | Mutation/failure expectation |
|---|---|---|---|
| FR1-FR6; PR1-PR2 | Actual Table renderer-count, native DOM and geometry tests | No unpinned column, start/middle/end, pinned start and end, widened row number, wide viewport mounting every column | Header/body drift, a spacer with content, window-relative aria-colindex or an unbounded range fails |
| FR7-FR10; AR3-AR4 | Real-browser focus and anchor integration | Focused input scrolled out and back, resize, reorder, hide, pin, rows and columns together | Lost focus, a jump in the first visible column or a row gap that misspans fails |
| FR11-FR14 | Admission tests | Grouped header, spanning cell, wrapped content, duplicate capabilities | Windowing an unsupported case, or a fallback without its warning, fails |
| PR3-PR4 | Browser frame traces | 1,000 columns, 20 rows, inline scroll and no-op | Budget overrun without a recorded decision fails |
Decision log¶
DEC-1 — A sibling capability in the same prop¶
Reference: module:Table/useTableColumnsVirtualization/DEC-1
Decider: humbertovirtudes, 2026-11-10
Column windowing is its own hook beside useTableRowsVirtualization, and
Table.virtualization takes one capability or a list of them.
Rejected: a second Table prop, and one combined hook that makes rows expressible two ways.
DEC-2 — Unpinned columns window; pinned runs stay¶
Reference: module:Table/useTableColumnsVirtualization/DEC-2
Decider: humbertovirtudes, 2026-11-10
Pinned start and end runs always mount, so their offsets and paint stay with the sticky-columns owner. Only the run between them windows. Rejected: windowing pinned columns.
DEC-3 — Layout widths, not a declared width¶
Reference: module:Table/useTableColumnsVirtualization/DEC-3
Decider: humbertovirtudes, 2026-11-10
Columns already declare pixel() or proportional() widths with floors, and an
overflowing Table renders at its minimum width. The window uses the widths
layout gives each column there, so callers add no width.
Rejected: a uniform columnWidth, and measuring offscreen columns.
DEC-4 — One focus column and a first-visible-key anchor¶
Reference: module:Table/useTableColumnsVirtualization/DEC-4
Decider: humbertovirtudes, 2026-11-10
One retained column keeps focus; the first visible column's key and fractional offset anchor inline scrolling across column changes. Rejected: stretching the range to a remote focused column.
Open questions¶
None. The normative contract is complete. Implementation and release verification remain separate from contract approval.
Content boundary¶
This record does not duplicate consumer signatures/examples, parent protocol, research, measured results, implementation steps or general virtualizer algorithms.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx