Skip to content

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

TypeScript
36.0 KB
Raw Blame

schema_version: 3 template_version: 1 kind: module id: module:Table/useTableColumnResize authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-09-10 owners: [cixzhang] review_triggers: [behavior, layout, visual, accessibility] verified_by: [ packages/core/src/Table/plugins/columnResize/useTableColumnResize.test.tsx, packages/core/src/Table/tests/TableColumnResizeName.a11y.chromium.spec.ts, packages/core/src/Table/tests/TableColumnResizeRange.a11y.chromium.spec.ts, scripts/check-knowledge.mjs, ] parent_component: component:Table references: [ component:Table, architecture:interaction-modality, architecture:component-theming-surface, architecture:public-component-api,

]

useTableColumnResize module contract

Intent

useTableColumnResize lets a person change a column's width from its trailing boundary. This record owns what that boundary looks like before anybody drags it: when a column boundary is drawn, how far the drawn line runs, which pointer capabilities see it, and what else on the header may change while it is shown.

Width resolution, per-column minimums, proportional-neighbor behavior, the commit callback, and the module's configuration remain uncontracted. This record is their canonical owner when they are recorded; today it states only the affordance, its extent, and its modality.

Current width behavior is on record as the starting point for that later contract, and two parts of it are already known to be wrong: a drag snapshots every column to pixel widths, so proportional columns stop being proportional, and a trailing proportional column does not absorb the delta when the column before it is resized. Both are defects to correct there, not variations this record allows.

Compatibility and migration

  • Released default preserved: no for the resting appearance of a hovered header under a hover-capable pointer, and no for boundary presence on a coarse-primary device that has another input — a keyboard-driven tablet gains a tab stop it did not have. yes for public API, DOM shape, keyboard behavior on hover-capable pointers, and every width outcome.
  • Compatibility class: presentation-only change to one transient state, plus one accessibility correction that adds a control where keyboard resize was already promised. No public API, prop, export, or target is added or changed. One accessibility correction changes the announced range: a column with no maximum width announces a stand-in maximum and its value in words (AR7), where it announced no maximum, so assistive technology fell back to a maximum of 100. A boundary's value is its column's rendered width (AR8), where it was the column's minimum until the first resize.
  • Migration decision: none. No consumer edit and no codemod.

This specification-only change carries no package Changeset. The implementation pull request owns runtime code, tests, and its Changeset.

Ownership boundary

Owns

  • Presence and placement of one resize boundary control per resizable column, and its pointer target versus its drawn indicator.
  • The disclosure contract: which boundaries are drawn at rest, on header hover, on pointer, on visible focus, and during drag, and the precedence between them.
  • The vertical extent of the drawn indicator and the requirement that it never makes the Table scroll region scroll vertically.
  • Which pointer capabilities receive the affordance at all, and which receive its hover reveal.
  • The bound on what else header hover may change.
  • Whether header disclosure responds to a pointer while the scroll region is scrolling.

Does not own / non-goals

  • Aggregate TablePlugin protocol, transform phases, plugin ordering, and header row and header cell render slots — owned by component:Table.
  • Shared modality state and focus-indicator visibility rules — owned by architecture:interaction-modality.
  • Public theme targets and token exposure — owned by architecture:component-theming-surface. No table-resize-handle target is approved by this contract.
  • Sort, selection, column-settings, or any other header control's own hover, focus, and press treatments.
  • A touch-drag resize affordance. Dragging a hairline boundary by finger is a non-goal under DEC-4; a touch-reachable resize path would be a separate affordance with its own record.
  • Width computation, clamping, commit semantics, RTL width math, and the module's configuration surface. They stay in consumer docs until this record contracts them.

Public API and concepts

This contract adds no public API. Consumer signatures, defaults, and examples remain in useTableColumnResize.doc.mjs.

Concept Closed values or states Meaning Default Owner Stability
Boundary control Present or absent per column One resizable boundary at a column's trailing inline edge. Present for every resizable column module:Table/useTableColumnResize Stable
Disclosure state hidden, hinted, emphasized How strongly one boundary is drawn right now. hidden module:Table/useTableColumnResize Stable
Pointer capability Hover-capable or coarse Whether hover reveals the affordance. Does not decide whether the control exists. Derived from the input architecture:interaction-modality Stable
Scroll activity Settling or scrolling Whether the scroll region is moving under the pointer right now. Settling module:Table/useTableColumnResize Stable

Behavioral contract

ID Invariant Basis Implementation/evidence state
FR1 Each resizable column receives one boundary control at its trailing inline edge, with a pointer target wider than the drawn indicator so the line stays hairline while the grab area stays usable. A column that opts out of resizing, and a generated plugin column, receive none. Current source and docs Verified current behavior; sizes are source-inspected.
FR2 The drawn indicator runs from the top of the header through the body rows so a drag reads against the rows it moves. It MUST end at or above the table's bottom edge and MUST NOT make the Table scroll region scroll vertically; that region exists for horizontal overflow only. Owner direction, 2026-09-10 Current release overhangs the last row; correction pending.
FR3 With no hover-capable pointer in the header row, no visible focus on a boundary, and no drag in progress, every boundary is hidden. Current source and docs Verified current behavior.
FR4 While a hover-capable pointer is anywhere inside a header row, every boundary in that row is hinted at border weight at the same time. The boundaries return to hidden when the pointer leaves the row. Owner direction, 2026-09-10 (DEC-1) Owner-directed; implementation and focused coverage pending.
FR5 A boundary under the pointer, a boundary with a visible focus indicator, and the boundary being dragged are emphasized at accent weight, over any hinted state. Current source plus DEC-1 Pointer and focus states verified; hint interaction pending.
FR6 Pointer capability gates the hover reveal, not the control. Where no pointer can hover, entering a header row reveals nothing and every boundary stays hidden. The boundary control itself, with its tab stop and accessible name and values, exists wherever any available input can operate it, so a coarse-primary device with a keyboard keeps keyboard resize. DEC-3 plus architecture:interaction-modality Coarse-primary suppression is current behavior and is the defect DEC-3 corrects.
FR7 Header hover changes only these indicators. It MUST NOT change header background, label, cursor, layout, column width, or any body-row treatment, and MUST NOT alter another header control's own states. Owner direction, 2026-09-10 Owner-directed; focused coverage pending.
FR8 Resizing stays available without hover. A boundary remains in tab order with its accessible name and values, keyboard resize is unchanged, and the reveal adds discovery only — it is never a precondition for use. This holds on every device whose input can operate the control, including a coarse-primary device with a keyboard. Current source, WAI-ARIA splitter pattern, DEC-3 Keyboard path verified on hover-capable pointers; coarse-primary parity pending.
FR9 A boundary with a visible focus indicator is emphasized alone. Focus MUST NOT raise the row-level hint, so focusing one boundary never draws its neighbors. Only a hover-capable pointer inside the header row does that. Owner direction, 2026-09-21 (DEC-5) Owner-directed; focused coverage pending.
FR10 While the Table's scroll region is scrolling, header hover resolves no new disclosure: a boundary the pointer reaches only because content moved under it stays hidden, and boundaries already hinted when the scroll began settle back to hidden. Disclosure resumes when scrolling stops. A drag in progress and a visible focus indicator are unaffected. Owner direction, 2026-09-21 (DEC-6) Owner-directed; implementation and coverage pending.

Transformation and precedence order

  • ORD0 — Scroll gate. Scroll activity is evaluated before ORD1's hover branch. While the scroll region scrolls, the hinted branch is unreachable; drag and visible focus still resolve to emphasized (FR10).
  • ORD1 — Disclosure precedence. Drag, visible focus, and pointer-on-boundary resolve to emphasized; otherwise header-row hover resolves to hinted; otherwise hidden. A boundary's own state always outranks the row-level hint, so the boundary under the pointer reaches accent while its neighbors stay at border weight. Precedence runs one way only: a boundary's own state never raises the row-level hint, which is why focus alone emphasizes one boundary and draws no neighbors (FR9).
  • ORD2 — Reveal scope. The reveal is published once at header-row scope, not per cell, so entering the header anywhere reveals every boundary in that row together rather than the one under the pointer.
  • ORD3 — Parent pipeline. The module contributes its header row and header cell transforms at the position component:Table gives it and does not redefine plugin order.

Performance and resources

  • PR1 — Disclosure costs no render. Entering or leaving the header MUST NOT set React state or rerender the Table. Disclosure is a declarative style state. FR10's scroll gate is the one permitted exception to the no-listener rule: the module MAY attach a single passive scroll listener on the scroll region, plus the settle signal that tells it when to reopen — scrollend where the browser has it, otherwise one debounced timer. It MUST write its scroll state straight to the DOM, as an attribute or an inline custom property that CSS reads, and MUST NOT set React state or rerender the Table. No other listener or timer may be added for disclosure.
  • PR2 — One measurement path. Indicator extent reuses the module's existing shared resize observation of the table. Disclosure adds no observer, and extent measurement MUST NOT observe anything whose size the indicator itself changes.

Accessibility contract

  • AR1 — Unchanged semantics. Each boundary keeps its separator role, vertical orientation, accessible name naming its column, and value bounds (AR7). Its resize handle sits in the overlay slot, so it doesn't join the header's name (component:Table FR11).
  • AR2 — Decorative disclosure. hinted is presentation only. It changes no ARIA state, announces nothing, and does not enter or reorder tab order.
  • AR3 — Parity without hover. Keyboard focus draws the same boundary at accent, so a person who never hovers gets an equal cue at the moment it is useful. Focus draws that one boundary and no others (FR9).
  • AR4 — Honest strength claim. The hinted weight is a discovery aid, not a state indicator. This contract makes no non-text contrast promise for it and MUST NOT let it become the only signal that a control is available; emphasized and the focus indicator carry that signal.
  • AR5 — Motion restraint. Any transition on disclosure MUST remain a short color change and MUST NOT move layout or the indicator's position.
  • AR6 — Parity across inputs. The tab stop does not depend on primary pointer capability. A device whose primary pointer is coarse but which has a keyboard keeps the boundary control, its name, and its values (FR6, DEC-3).
  • AR7 — A range that holds the value. A boundary's announced maximum is never below its value or its minimum, and its announced minimum is never above its value (spec:AST-020 FR1). A column with a maximum width announces that maximum, or its value when the layout renders it wider; a column rendered narrower than its minimum announces its value as the minimum. A column with no maximum width announces the window's inline extent, floored at its value and minimum, as an unbounded Resizable region does, from the same shared measurement; the column is never clamped to it. Because that maximum stands in for a missing limit, such a boundary also announces its value in words ("133 pixels"). The server render, which has no window, carries no maximum until hydration reads it.
  • AR8 — The value is the rendered width. A boundary's value is its column's rendered width in whole pixels, from the first measurement after layout, and follows the column as it is resized. The width is read from the shared resize observer, never during render. Until the first measurement, the value is the width the table asked for, else the column's minimum.

Design relationships

Anatomy or state Design requirement Representation authority Module contract
Boundary control Offers a grabbable column edge without drawing a permanent divider, on every input that can operate it. module:Table/useTableColumnResize FR1, FR6, AR6
hidden boundary Keeps a resting header free of controls the person is not using. module:Table/useTableColumnResize FR3
hinted boundary Answers "can these columns move?" at the moment attention enters the header. module:Table/useTableColumnResize FR4, FR7, AR4
emphasized boundary Names the one boundary that pointer, focus, or drag is acting on, and only that one. module:Table/useTableColumnResize FR5, FR9, ORD1
Disclosure at rest during scroll Keeps content moving under a still pointer from reading as intent. module:Table/useTableColumnResize FR10, ORD0
Indicator extent Reads the drag against the rows it resizes, without changing what the table scrolls. module:Table/useTableColumnResize FR2

Theming

No public target is approved for the boundary control or its indicator, and the module's consumer doc records no anatomy of its own. This contract therefore adds no anatomy-theming:v1 block; a direct target requires its own review under architecture:component-theming-surface with synchronized consumer anatomy.

DEC-7 settles this as a decision rather than an open question: the hint and accent weights already resolve from theme tokens, so a theme change moves the boundary without a target of its own.

Parent and system relationships

  • component:Table owns the plugin protocol, ordering, header row and header cell slots, and the scroll region this contract's FR2 protects. Table's aggregate record does not own column-resize anatomy, which is why this boundary is separate.
  • The sticky-columns plugin (useTableStickyColumns, no record of its own yet) composes with this module on the same header cell. Both contribute position — this module appends relative so its absolute boundary control anchors, sticky needs sticky to pin — and while both went through the cell's xstyle, the later plugin's value won and composition order decided whether a pinned column actually pinned. Ordering is not the fix: component:Table owns plugin order and treats it as a layout decision, never a correctness one, so a pair that works in one order and breaks in the other is a defect in the pair. Sticky therefore writes position inline alongside the offsets it already wrote there, which outranks either plugin's classes and makes the composition order-independent. A second coupling stays open: sticky computes its cumulative pin offsets from declared column widths while a drag writes rendered pixel widths to the DOM, so pin offsets go stale after a resize. Neither record contracts that reconciliation yet.
  • architecture:interaction-modality owns hover capability versus modality history and the visibility rules for the shared focus indicator. FR6 and AR3 apply those rules; they do not restate them.
  • architecture:component-theming-surface owns target qualification. Structural custom properties used to carry extent and hint values are implementation, not theme surface.
  • architecture:public-component-api owns the public boundary. This record adds no export, prop, or type.

Verification map

Contract Verification Representative states Mutation or failure expectation
FR1, FR6 useTableColumnResize.test.tsx boundary-presence cases plus hover-capability and coarse-primary cases Resizable, opted-out, and generated columns; hover-capable, coarse-primary with keyboard, and coarse-only inputs A boundary appears on a non-resizable column, disappears from a resizable one, the hover reveal fires where no pointer can hover, or the control is absent where an input can operate it.
FR2 Browser measurement of scroll-region vertical overflow with the plugin enabled Short and tall tables, wrapped and single-line headers, dense and default The indicator ends below the last row or the scroll region gains vertical scroll that the same table lacks without resize.
FR3-FR5, FR9, ORD1 New focused tests for resting, header-hovered, pointer-on-boundary, focused, and dragging states Rest, header hover, hover plus pointer on one boundary, keyboard focus with no pointer in the row, drag A resting header draws boundaries, header hover misses a boundary, the pointed/focused boundary fails to outrank the hint, or focus alone draws a neighbor.
FR10, ORD0 Scroll-gate test driving the scroll region with a stationary pointer over the header Pointer resting over a header while the region scrolls and after it settles Boundaries reveal mid-scroll, an existing hint survives the scroll, or disclosure fails to resume once scrolling stops.
FR7 Snapshot or assertion that header hover changes no other header or row treatment Header hover over a sortable and a selectable header Header hover changes background, label, cursor, width, or another control's state.
FR8, AR1-AR3, AR6 Existing keyboard and ARIA suites and a coarse-primary keyboard case; useTableColumnResize.test.tsx "the handle never adds to its column header's name (AR1)" and TableColumnResizeName.a11y.chromium.spec.ts "a resize handle never adds to its column header name"; an assistive-technology spot check is recommended follow-up Tab to boundary, arrow resize, screen-reader navigation of the header, coarse-primary device with a keyboard The boundary leaves tab order on any input that can operate it, loses its name or values, or the hint reaches the accessibility tree.
AR7 useTableColumnResize.test.tsx "an unbounded column announces a finite maximum, never below its value, and its width in words" and "handle has aria-valuemax when finite"; TableColumnResizeRange.a11y.chromium.spec.ts in Chromium's accessibility tree A column with no maximum width; one with maxWidth A missing or non-finite maximum, a maximum below the value or the minimum, missing value text on an unbounded column, or value text on a bounded one fails.
AR8 useTableColumnResize.test.tsx "announces its column's rendered width before any resize, not the minimum"; TableColumnResizeRange.a11y.chromium.spec.ts "a handle announces its column's rendered width before any resize" in Chromium's accessibility tree, before any resize and after two ArrowRight presses; useTableColumnResize.test.tsx "keeps the announced range holding a column rendered past its limits" Before any resize; after keyboard resizes A value that differs from the column's rendered width once it has been measured, or a layout read during render, fails.
PR1, PR2 Render-count assertion around header pointer enter/leave and during a scroll; listener and observer inspection Pointer enters and leaves the header repeatedly; the region scrolls under a resting pointer Disclosure rerenders the Table, the scroll gate sets React state, more than one scroll listener or any timer is added, or the extent measurement observes what it resizes.
Plugin composition Test mounting the resize and sticky-columns plugins together in both insertion orders Pinned start column with resize enabled, before and after a drag A pinned column loses position: sticky in either order, or the composition depends on caller insertion order.
Record shape scripts/check-knowledge.mjs Colocated module record, canonical id and filename, parent backlink A missing, misnamed, mis-parented, or unlinked record passes validation.

Browser, render-count, and assistive-technology evidence are pending. Passing this specification pull request proves record integrity only.

Decision log

DEC-1 — The header discloses every resizable boundary on hover

Reference: module:Table/useTableColumnResize/DEC-1 Decider: cixzhang, 2026-09-10

A boundary drawn only once the pointer is already inside its grab area asks the person to suspect the column is resizable before they can find out. Entering the header now reveals every boundary at border weight, and the boundary under the pointer still takes accent, so discovery and targeting stay distinguishable. The reveal is bounded by FR7 and is pointer-only by FR6.

Rejected: revealing only the boundary under the pointer, which keeps the discovery problem; drawing permanent dividers, which adds a resting visual the columns do not earn; relying on the resize cursor alone, which requires the same prior suspicion; and a public prop to opt out, which makes a discovery affordance a caller decision.

DEC-2 — The indicator is bounded by the table it belongs to

Reference: module:Table/useTableColumnResize/DEC-2 Decider: cixzhang, 2026-09-10

A full-height indicator is the intended design because a drag has to read against the rows it moves. An indicator that ends past the last row is a defect, not an allowed variation: the scroll region promotes vertical overflow as soon as it scrolls horizontally, so an invisible overhang becomes visible stray scrolling. Ending a fraction short of the last row is within FR2; hanging past it is not.

Rejected: leaving the overhang and suppressing vertical scroll on the region, which would hide real overflow from other content.

DEC-3 — Pointer capability gates the reveal, not the control

Reference: module:Table/useTableColumnResize/DEC-3 Decider: cixzhang, 2026-09-21

Suppressing the whole boundary control on a coarse primary pointer also removes its tab stop, so a keyboard-driven tablet loses resize entirely while FR8 and AR3 promise it. Capability decides disclosure only: hover reveals where a pointer can hover, and the control exists wherever any available input can operate it. The current coarse suppression is a defect against this decision, not the behavior it records.

Rejected: keeping existence gated on pointer capability and weakening FR8 to hover-capable devices, which trades an accessibility guarantee for an implementation convenience; and gating on a touch-capability test, which still misreads devices carrying both inputs.

DEC-4 — Touch-drag resize is a non-goal

Reference: module:Table/useTableColumnResize/DEC-4 Decider: cixzhang, 2026-09-21

A hairline boundary cannot be dragged reliably by finger, and widening the grab area enough for touch would either swallow header presses or draw a resting affordance the columns have not earned. Touch users are not given a degraded version of the pointer path. This closes OQ3.

Rejected: enlarging the grab area under coarse pointers, which conflicts with FR7's bound on header changes; and a long-press drag mode, which collides with text selection and scrolling without solving the target size.

A touch-reachable resize path remains wanted as separate work — a drag pill or resize inside a column-settings sheet — with its own affordance and record.

DEC-5 — Focus emphasizes one boundary and never hints the row

Reference: module:Table/useTableColumnResize/DEC-5 Decider: cixzhang, 2026-09-21

Keyboard focus is already aimed at one boundary, so drawing every boundary in the row adds noise rather than discovery. The row-level hint answers "can these columns move?" for a pointer arriving without a target; focus has one. Focus therefore resolves emphasized on its own boundary and leaves its neighbors hidden.

Rejected: firing the row hint on focus for symmetry with hover, which repeats a discovery cue to a modality that does not need it and makes the focused boundary harder to pick out of eight drawn lines.

DEC-6 — Disclosure is suppressed while the scroll region scrolls

Reference: module:Table/useTableColumnResize/DEC-6 Decider: cixzhang, 2026-09-21

A pointer that ends up over a header because the content moved under it has not expressed intent, so boundaries appearing mid-scroll read as flicker. Disclosure holds while the region scrolls and resumes when it settles. A drag in progress and a visible focus indicator are unaffected, since both are deliberate.

Rejected: revealing on scroll-triggered hover as the browser reports it, which is the flicker; and a debounce on pointer entry, which delays the deliberate case to fix the accidental one.

DEC-7 — The boundary gets no public theme target

Reference: module:Table/useTableColumnResize/DEC-7 Decider: cixzhang, 2026-09-21

The hint and accent weights already resolve from theme tokens, so a theme change moves the boundary correctly without a direct target. Publishing one would freeze boundary and indicator anatomy into the theming surface before the width model is contracted, and architecture:component-theming-surface requires synchronized consumer anatomy this module's doc does not have. This closes OQ2.

Rejected: publishing a target now and revising it when the width contract lands, which puts a stable public surface in front of an undecided one.

Revisit if a consumer needs the hint weight to differ from their own border token.

Open questions

  • OQ1 — Forced colors. How do hinted and emphasized resolve under forced-colors and high-contrast modes? (checkable)
  • OQ4 — Draft design record. design:user-states is draft. When it is promoted, its conditional-hover requirement should be cited here instead of restated.
  • OQ5 — Sticky offset reconciliation. After a drag writes rendered pixel widths, sticky pin offsets computed from declared widths are stale. Which record owns the reconciliation, and does it belong to the width contract or to sticky columns? (checkable)

OQ2 (theme selection) is closed by DEC-7 and OQ3 (coarse pointers) by DEC-3 and DEC-4. Their numbers are retained rather than reused.

Content boundary

This record does not duplicate consumer signatures or examples, the parent Table plugin protocol, shared modality mechanics, theme target policy, width computation, current audit results, or implementation steps. It links to their owners.