--- name: data-table-usage description: > Use after component-usage-ux when an app needs the @techsio/ui-kit DataTable — a headless, data-driven grid built on @tanstack/react-table v9 that renders into the presentational Table organism. Covers column defs, sorting, conditional column filters, global search, row selection, column visibility/pinning/reorder, row reorder, tree/expanding rows, inline edit, colSpan/rowSpan, virtualization / infinite scroll and pagination — every feature behind a flag with a callback. metadata: component_version: "2.0.1" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux app-token-overrides table-usage ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "" contributor_sources: "libs/ui/src/organisms/data-table.tsx libs/ui/src/organisms/data-table.helpers.ts libs/ui/stories/organisms/data-table.stories.tsx" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit DataTable Usage `DataTable` is the data-driven grid. It owns the TanStack table instance and renders into the presentational `Table` organism, so it inherits every `--color-table-*` / `--padding-table-cell-*` token. Reach for the plain `Table` when you only need static markup; reach for `DataTable` when you need sorting/filtering/selection/pagination and friends. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `DataTable`. **Use it when** - Collections users search, sort, filter, select, edit inline and page through — the default for admin lists. - Any list that is the main content of a page (orders, products, customers, pages). **Use something else when** | Need | Use instead | | --- | --- | | A small static table (spec sheet, invoice lines) | Table | | Browsing products visually | a ProductCard grid | | Showing a trend | Chart | | Editing a whole record with validation across fields | the drawer/full form, not inline edit | **Do** - Align numeric columns (money, counts, percentages) with `meta: { align: "end" }` and render them with `tabular-nums`; text and dates stay start-aligned (ux-guidelines/formatting#alignment-in-tables). - Format cells with the app's `Intl` formatters; render missing values as `—`. - Row click = read (detail drawer); edit and delete live in `rowActions`, delete last with `severity: "danger"`. - Show bulk actions only while rows are selected; confirm destructive bulk actions with the count. - Design all three empty states (first use, no results, load error). `translations.emptyTitle` / `emptyDescription` hold one message, so pick it from the app's state on each render, or use `renderEmpty` to render a different state (with `Clear filters` / `Try again`) per case — never let a failed load read as `No records`. **Don't** - Build a separate filter bar when column filters (`enableColumnFilters` + `meta.type`) fit. - Blank the table while refreshing — keep rows and show progress in the toolbar. - Put more than one primary action in the toolbar (the page's primary lives in the page header) or more than three own actions (the rest go into a `Menu`). **Copy and states** - Column headers are short nouns in sentence case, with units when shared (`Price (€)`). - Inline edit success → toast ` saved`; errors stay on the cell editor. Search placeholder `Search …`. **Behaviour (from the UX spec)** - Inline edit: Cancel restores the last saved value, and moving focus never silently commits another row's edit. - If a sort, filter or page request fails, revert the indicator and keep the previous rows; `sort=none` means sortable but unsorted. - Expand toggles use a chevron (never ×) and expanding never selects the row. The page-size select needs an accessible name; cell links and buttons don't make it an ARIA grid (no `role="grid"`). **Figma → code** | Figma | Code | | --- | --- | | toolbar / filter row / pagination `size=md` | `size="sm" \| "md" \| "lg"` (shared by nested controls; `sm` for scanning, `md` when rows are edited inline) | | `Table.IconButton` | `ActionIcon` with `aria-label` (no Table.IconButton exists) | | `state=loading` | `loading` / `loadingMore` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Organisms/DataTable → UX guidelines*. ## Setup ```tsx import { DataTable } from "@techsio/ui-kit/organisms/data-table" import type { ColumnDef } from "@techsio/ui-kit/organisms/data-table" type Order = { id: string; customer: string; total: number; status: string } const STATUS_OPTIONS = [ { label: "Paid", value: "paid" }, { label: "Pending", value: "pending" }, ] const columns: ColumnDef[] = [ { accessorKey: "customer", header: "Customer" }, { accessorKey: "total", header: "Total", meta: { align: "end", type: "number" }, cell: (info) => `${info.getValue()} €`, }, { accessorKey: "status", header: "Status", meta: { type: "enum", options: STATUS_OPTIONS }, }, ] open(row.original)} /> ``` ## Column types drive the filter and the editor Declare `meta.type` and DataTable renders the matching ui-kit control in both the header filter row and the inline row editor, at the table's `size`: | `meta.type` | filter control | editor control | |---|---|---| | `string` | Input + condition menu (icon) | Input | | `int` / `number` | Input + condition menu (`between` adds a second Input) | NumericInput | | `boolean` | tri-state Select (All/Yes/No) | Switch | | `enum` | Select (+ "All") | Select | | `multiEnum` | Combobox `multiple` | Combobox `multiple` | | `date` / `datetime` | Input `date` / `datetime-local` | same | | `time` | from/to time Inputs (window may cross midnight) | Input `time` | | `dateRange` | from/to date Inputs | from/to date Inputs | | `custom` | nothing — supply `meta.renderFilter` | supply `meta.renderEditor` | Filter values are objects — `{ operator, value, to? }` for text/number, `{ values: [...] }` for the enum types, `{ value }` for boolean, `{ from, to }` for date/time ranges. A bare value from the plain TanStack API (`column.setFilterValue("Ada")`, or a controlled `columnFilters` entry) is coerced to the right shape for every type: an array becomes `{ values }`, a lone date/time becomes a closed range on itself (a whole day for `date`, that exact minute for `time`), and `"true"` / `"false"` strings are parsed rather than coerced. Give `enum`/`multiEnum` their choices via `meta.options`. Register `filterFn: "typed"` on the column so filtering matches the declared type (`time` compares minutes-since-midnight; a `dateRange` cell compares interval overlap). There is no date-picker component yet, so date/time fields use the native `Input` types. The filter row puts the value control first and the operator behind a compact icon button (a Menu of conditions), so the input gets the width and the header stays on one line. The active condition is in the button's `aria-label`, and for `Is empty` / `Is not empty` the input is disabled and shows the condition as its placeholder. Row actions use the `Button` atom icon-only at `size="sm"`, `appearance="ghost"`, with `severity` carrying the semantics (`danger` for destructive actions). Escape hatches, in precedence order: `meta.renderFilter` / `meta.renderEditor` per column → the table-wide `renderHeaderFilter` slot → `filterRenderers` / `editorRenderers` maps → the type default. All receive a context with `{ column, type, value, setValue, disabled, size, options }` (editors also get `row`, `error`, `commit`, `cancel`). ## Column widths and alignment ```tsx { accessorKey: "age", meta: { width: 80, align: "end" } } { accessorKey: "email", meta: { width: "var(--dimension-200)", minWidth: 120 } } { accessorKey: "active", meta: { width: "15%", align: "center" } } ``` `meta.width` / `meta.minWidth` / `meta.maxWidth` take a number (px) or any CSS length, so tokens, `%` and `ch` all work. Pair them with `tableLayout="fixed"` — under the default `"auto"` a width is only a hint and long content can still stretch the column. Use `meta.width`, not TanStack's `columnDef.size`: TanStack merges `size: 150` into every column def, so `size` cannot express "no width declared". Numeric widths are mirrored into `size`/`minSize`/`maxSize` internally, which keeps the rendered width and the sticky offsets of pinned columns in agreement. While resizing is on the live dragged width wins. Give **pinned (frozen) columns a numeric width**. Sticky offsets are summed from the numeric sizes, so a `%` or token width on a frozen column cannot be resolved to pixels and the frozen block can misalign. Unpinned columns take any unit. `meta.align` (`start | center | end`, default `start`) is forwarded to the `Table` cell as `data-align`, which is where the alignment is actually styled — so a hand-written `Table` gets the same three options. Nothing is inferred from the column type: center an icon/boolean column or right-align a number only if you say so. `Table`'s older `numeric` prop still right-aligns, but it means "this value is a number"; set one or the other, not both. ## Inline editing and interaction locking The table renders read-only until the user opts in: the right-hand actions cell holds an edit icon, and clicking it swaps that row's editable cells (`meta.editable`) to type-driven editors with save and cancel beside them. `enableInlineEdit` is what wires this up. One row is editable at a time; Enter commits, Escape cancels. Apply the committed `draft` to your own state in `onEditCommit` — DataTable does not mutate `data`. For a column that should always be an editor instead, skip `enableInlineEdit` and render your own control in `columnDef.cell`, pushing values through `table.options.meta.updateData` (see "Inline edit" below). Validation runs on commit from `meta.required` and `meta.validate(value, draft)`; failures block the commit and surface through `onEditValidationError`. While a row is being edited, `lockInteractionsWhileEditing` (default `true`) disables sorting, column filters, global search, pagination, selection, row and column reorder, and row click — anything that could move the row out from under the user. Blocked attempts report through `onInteractionBlocked({ action, reason: "editing", rowId })`, but only for `globalFilter`, `paginate`, `columnVisibility` and `rowClick`. Every other locked control — sort, column filters, selection, both reorder flavours — is natively `disabled` or non-draggable during an edit, so the interaction never reaches a handler and there is nothing to report; `globalFilter` is the one exception, reachable through `SearchForm`'s clear button even while its input is disabled. Filtering and sorting still compose freely with each other when no edit is active. Edit callbacks: `onEditStart`, `onEditChange`, `onEditCommit`, `onEditCancel` (with `dirty`), `onEditValidationError`, plus controlled `editingRowId` / `onEditingRowIdChange`. Slot return contract: `renderRowActions` and `renderHeaderFilter` treat `undefined` as "not handling this one" (falls through to the built-in edit button / the type-driven filter) and `null` as "render nothing here". ## Toolbar The toolbar is one row: the global search stretches to fill the free width, and custom actions sit at the trailing edge in a flex group. ```tsx ``` Each entry takes the full `Button` API (minus `size`, which follows the table); `label` is a convenience alias for `children`. Keep to `DATA_TABLE_MAX_TOOLBAR_ACTIONS` (3) — more still render, but DataTable `console.warn`s, because a crowded toolbar usually means the extras belong in a menu. It is a recommendation, not an error. The search is the `SearchForm` molecule: a clear button appears inside the field once there is a value, and a submit button is joined to its trailing edge with the touching corners squared off (`gapped={false}`). Filtering is live on every keystroke, so the submit button is a confirm affordance rather than the trigger. `translations.searchLabel`, `searchPlaceholder`, `clearSearchLabel` and `searchButtonLabel` cover its text. ## Loading states - `loading` replaces the body with `loadingRowCount` skeleton rows (default 5) while keeping the header, so the layout does not jump when data arrives. - `loadingMore` appends a single skeleton row — pair it with `onReachEnd` for infinite scroll so the user sees the next page being fetched. ## Drag affordances Reorder handles are always rendered but stay fully transparent until the row or header is hovered or receives focus, so the table stays calm while still being discoverable. They also reveal while their row/header is being dragged, so the handle does not vanish when the pointer leaves the source. During a drag the source is dimmed and lifted (`data-dragging`), and the drop target shows an insertion edge — a border on the leading or trailing side for columns, top or bottom for rows — so it is clear where the item will land. ## Accessibility Sortable headers carry `aria-sort`; the expander carries `aria-expanded`; the table carries `aria-busy` while loading and skeleton rows are hidden from assistive tech. Rows with `onRowClick` are focusable and activate on Enter or Space (the handler ignores keys bubbling from controls inside the row). Both drag handles receive dnd-kit's keyboard attributes, so reordering works without a mouse. Pass `getRowLabel` so selection checkboxes and the edit action are labelled by row content instead of an opaque row id. Inline-edit validation messages render next to the field with `role="alert"` and are linked through `aria-describedby`; focus moves into the edited row on start and returns to the control that opened it on commit or cancel. ## Sizing `size` (`sm | md | lg`) is forwarded to the underlying `Table` **and** to every nested control — filter inputs, inline editors, page-size select, pagination, action icons and the column menu — so the whole table scales as one. `paginationProps` exposes the full `Pagination` molecule API (variant, compact, siblingCount, translations, …) except the table-owned count/page/pageSize. The footer splits: the record range sits on the left, the pager and page-size select on the right. It shares the header's background so the two frame the table consistently. `translations.rangeLabel({ start, end, total })` builds the range text; `translations.pageSizeLabel` is the page-size select's accessible name (the design shows no visible label beside it). ## Feature flags (all opt-in unless noted) - `enableSorting` (default `true`) — click header to sort; `meta.align: "end"` right-aligns numeric columns. - `enableGlobalFilter` — renders the toolbar search (`DataTable.GlobalSearch`). - `enableColumnFilters` — renders a per-column filter row. Pick the control with `meta.type` (`"string" | "int" | "number" | "boolean" | "enum" | "multiEnum" | "date" | "datetime" | "dateRange" | "time" | "custom"`), plus `meta.options` for the enum types. Columns get `filterFn: "typed"` by default, which dispatches on that same `meta.type`; set `filterFn: "conditional"` for the operator-based ("with conditions") comparator instead, or override the whole UI with `meta.renderFilter` / `renderHeaderFilter`. `meta.filterVariant` and `meta.filterOptions` are deprecated aliases kept for older columns: both still work — `filterVariant` is resolved to a `meta.type` (`text`→`string`, `number`/`range`→`number`, `select`→`enum`) and selects that type's control and matcher, and `filterOptions` is used when `options` is absent. Prefer `meta.type` / `meta.options` in new code. - `enableRowSelection` — injects a leading checkbox column; header checkbox toggles eligible loaded records (all client pages, but only the loaded response in manual server paging). Always supply stable `getRowId`. Constrain it with `selectionMode: "single" | "multiple"` (single replaces the selection), `maxSelectedRows: N` (a hard cap — unselected rows disable once it is reached, selected ones stay deselectable, and `onSelectionLimitReached` fires) and/or `canSelectRow(row, { selectedCount, isSelected })` for rules those two can't express. All three compose; the select-all header checkbox is hidden unless selection is unbounded multiple. - `enableColumnVisibility` — an icon-only cog button (tooltipped with `translations.columnsLabel`) opening a checkbox list of hideable columns. The list stays open while toggling, so several columns can be hidden without reopening it. - `enableColumnPinning` + controlled `columnPinning` — freeze columns to either edge (sticky, with an edge shadow). TanStack Table v9 names the two sides logically, so the state is `{ start: string[], end: string[] }` (v8's `left`/`right`) and pinned cells carry `data-pinned="start" | "end"`. The sticky offsets use `insetInlineStart`/`insetInlineEnd`, so a start-pinned column freezes against the right edge in RTL. - `enableRowSelection` shift-click range selection is **off**. TanStack v9 enables it by default, but it applies a whole range in one update and would sail past `maxSelectedRows`; DataTable sets `enableRowRangeSelection: false` until it can offer a cap-aware version. - Column `filterFn` accepts `"conditional"`, `"typed"` and `"includesString"` by name. Other built-in comparators are not registered on the table's feature set (registering them all would pull every built-in into the bundle) — pass the function itself instead, which needs no registration. `sortFn: "auto"` works: `alphanumeric`, `datetime` and `text` are registered. - `enableColumnReorder` — drag column headers (dnd-kit); fires `onColumnReorder`. - `enableRowReorder` — injects a drag handle column; fires `onRowReorder`. - `enableExpanding` — the expand toggle lives in the trailing actions cell, so it never collides with the selection checkbox. Pair with `getSubRows` for tree rows, or with `renderExpandedRow` alone for master-detail (every row becomes expandable; narrow it with `getRowCanExpand`). The detail renders as one full-width cell spanning every column, containing a plain `div` — put any layout inside, no nested table cells. - `enablePagination` — renders `DataTable.Pagination` ("start–end of total" + page-size select + pager). Configure `pageSizeOptions`. - `enableVirtualization` + `maxHeight` — windowed rendering for large datasets (keeps native column alignment). Set `estimateRowHeight`. - `enableColumnResizing` — draggable column widths (`columnResizeMode: "onChange"`); the leaf colgroup carries inline widths, and only leaf headers offer resize/reset handles. Pointer/touch drags start from the rendered leaf width, including CSS-string widths such as `"20rem"`, and follow the table's RTL direction. - `enableInlineEdit` — type-driven row editing with an edit/save/cancel actions cell (see above). - `stickyActions` (default `true`) — pin the row-actions cell to the right edge. - `hideHeader` — render without the column header row(s). - `onReachEnd` + `maxHeight` — infinite scroll; called once when scrolled near the bottom. Server-driven data: set `manualSorting` / `manualFiltering` / `manualPagination` and supply `rowCount` (or `pageCount`) so pagination totals stay correct. Prefer `rowCount` — it makes the "start–end of total" label exact. With only `pageCount`, capacity is derived as `pageCount * pageSize` to keep every page reachable, but user-facing copy reports pages rather than an invented exact record total. Use `pageCount=-1` for unknown-total Previous/Next navigation. A settled `pageCount=0` response reports the exact empty range (`0–0 of 0`) through `rangeLabel`, not “Page 1 of 0”. During loading/refetch, pager destinations stay mounted and unavailable for activation; transient empty totals do not remove keyboard focus. If the settled response removes the focused page, focus moves to the new current page (or the remaining page-size control when no pages remain), unless the user has moved it elsewhere. ## Callbacks (for interaction tests + app wiring) Every stateful feature is controllable via a `state` + `onXChange` pair and also exposes a plain callback: `onRowClick`, `onSortingChange`, `onColumnFiltersChange`, `onGlobalFilterChange`, `onRowSelectionChange`, `onColumnVisibilityChange`, `onColumnOrderChange`, `onColumnPinningChange`, `onExpandedChange`, `onPaginationChange`, `onColumnReorder`, `onRowReorder`, `onCellEditCommit`, and `onReady(table)`. `onColumnReorder`'s `from`/`to`/`order` are relative to your own `columns` array — the injected selection and drag-handle columns are stripped out — so `arrayMove(myColumns, from, to)` reproduces the new order directly. `onReady` fires once on mount. Its methods stay live, but read `table.state` and `table.options` off it with care: `useTable` hands back a spread copy, so those two fields are a mount-time snapshot. Use `renderToolbar` for live state. ## Slots (open DOM paths) `renderToolbar(table)`, `renderEmpty()`, `renderRowActions(row)`, `renderHeaderFilter(column)`, `renderExpandedRow(row)`, and `slotProps.{root,header,body,row}` for className/data-attr/ref passthrough. Compose the toolbar/pagination yourself with `DataTable.Toolbar`, `DataTable.GlobalSearch`, `DataTable.ColumnVisibility`, `DataTable.Pagination`. ## colSpan / rowSpan TanStack has no body-cell spanning model. Pass `getCellSpan(cell, ctx)` returning `{ colSpan?, rowSpan?, hidden? }`; mark cells swallowed by a span with `hidden: true`. ## Inline edit Set `meta.editable` on a column and render an editable control in `columnDef.cell` that calls `table.options.meta.updateData(rowId, columnId, value)`; DataTable forwards it to `onCellEditCommit`. ## Presentation `appearance` (`line | outline | striped`), `size` (`sm | md | lg`), `stickyHeader`, `showColumnBorder`, `hideHeader`, `caption` — all forwarded to the underlying `Table`. Use `stickyHeader` with `maxHeight` for a scrolling body and `hideHeader` for headerless layouts. The whole grid is one rounded card: the wrapper carries `rounded-table` and clips its children, so the corners are correct with a toolbar, a pagination footer, both, or neither — including the empty state. `appearance="outline"` draws its border on that wrapper rather than on the ``, so the toolbar and footer sit inside the outline instead of beside it. The wrapper always draws a border in `--color-table-border`, the same colour as the row separators, so the grid reads as one bounded block. `appearance="outline"` adds the outline shadow on top of it. `striped` is a standalone boolean, so zebra rows compose with any variant — prefer it over `appearance="striped"`, which cannot be combined with `outline`. A striped row drops its own bottom border (the alternating background is already a separator; drawing both looked doubled-up), so an unstriped table still has the row-divider border and a striped one doesn't. `tintNestedRows` shades rows by `row.depth` — a tree (`getSubRows`) or expanded-detail child reads as "inside" its parent instead of just being the next row. Layered as an inset shadow rather than a background, so it composes with `striped` instead of losing the conflict against its zebra background. Setting `onRowClick` automatically makes rows interactive (pointer cursor + hover background); the affordance is dropped while an inline edit locks row clicks, so rows never look clickable when they are not. ## Don'ts - Do not hardcode colors/padding — the grid is fully tokenised via `Table`. - Do not reach for a canvas grid (VTable/S2): they cannot use our Tailwind tokens. - Do not mutate `data` in place for row reorder — apply the `onRowReorder` `data` result to your state. ## Wave 2 contracts With enableColumnResizing, focus a Resize edge and press Left/Right to change its width by 10px (Shift: 50px), clamped to column minSize/maxSize. Enter or Home resets its width; pointer double-click also resets. Keep destructive bulk actions behind an alertdialog naming the affected records, or provide a real undo path. Skeleton fill uses a table-specific token so it remains distinct in dark mode. Canonical sizes are sm/md/lg (default md). The bounded scroll surface is a keyboard-focusable named region. Its caption supplies the name; without a caption, localize `translations.scrollLabel` (default “Scrollable records”). Virtual padding rows are hidden from the accessibility tree while real rows retain absolute `aria-rowindex` and the table reports the full `aria-rowcount`. Default inline editors render sized StatusText errors with icons, aria-invalid and aria-errormessage on the actual control. Choice editors own their feedback through the widget API; custom editors receive error/errorId and must associate their focus target. Built-in editors reserve a size-dependent minimum value width so numeric values remain readable beside steppers; constrained fixed-layout cells scroll locally instead of covering adjacent fields. Sticky actions pin only when the table scroll container is at least 48rem wide. In narrower containers they scroll with the row, so Save/Cancel cannot cover a focused value editor. This is container-responsive, including narrow panels on desktop. ## Record identity and selection scope Always provide a stable `getRowId={(record) => record.id}` for selection, editing and server paging. Never key identity by the returned page index. Select-all affects all eligible **loaded records** in the client row model, not only the current client-side page. In manual server paging it affects only the loaded response, not unseen server records. Cross-page selected IDs may be retained by a controlled owner. Already-selected records remain deselectable when `canSelectRow` changes; new ineligible selections are refused. Revalidate all bulk-action permissions on the server before execution, including unloaded IDs. ## Widths, direction and windowing The leaf colgroup is the sizing authority, including grouped fixed layouts. Only leaf headers expose resize handles: resize/reset each leaf rather than a group. Pointer and keyboard resizing both follow the table's effective inherited direction. Frozen offsets use measured rendered widths, including CSS-string widths, and end-pinned leaves reserve the actual sticky actions width. Virtualization uses stable record/detail keys and measures every mounted row, including expanded detail rows; `estimateRowHeight` is an initial estimate only. Detail rows and footers are included in the accessible sequence. Client-paginated detail tables count expanded details on preceding pages. Manual-paginated detail tables use page-local structural indexes because prior pages' detail counts are unknown; flat paginated tables use absolute record indexes. Manual pages without `rowCount` report unknown `aria-rowcount=-1`. ## Persistence and validation `onEditCommit` may return `void` or `Promise`. Return/await persistence before applying local rows. The editor stays mounted while saving, duplicate submissions are blocked, and rejection keeps the draft with an error and retry. Localize `savePendingLabel` and `saveErrorLabel`; custom row actions receive `pending` and `error` alongside `commitEdit`. Do not close a controlled editor before its promise succeeds. Required date ranges need at least one endpoint (open-ended ranges are supported); completely empty optional ranges are valid. Populated bounds must be valid dates and the start must not follow the end. Both Save and Enter perform these checks. Localize `invalidRangeLabel`. ## Server pagination ownership `rowCount` is an exact total; `pageCount` alone is capacity, never an exact record count. Without `rowCount`, default copy uses localized `pageLabel({page,pageCount})` rather than the exact `rangeLabel` contract. With `pageCount=-1`, the pager shows Previous/Next without fabricated last-page links; optionally set `hasNextPage` from the response. Localize `previousPageLabel` and `nextPageLabel`. Settled totals that invalidate a page request the last valid page once through `onPaginationChange` (or update uncontrolled state); page-size changes atomically reset to page zero. The parent owns fetching: mark transient responses `loading` and cancel/ignore stale requests so rowCount belongs to the current request. An invalid response shows a correction message, not a false empty-success state. `loadingMore` announces loading even when the first response has no rows. `renderEmpty` owns its own accessible feedback; the default empty live announcement is suppressed when custom content is supplied. If the combined frozen bands cannot fit their scroll container, pinning temporarily yields to horizontal scrolling so every column stays reachable; the requested pins resume when there is room. On narrow screens, pinned columns that fit stay frozen (start-side identity columns first); pins that would leave no scrollable room scroll with the data and freeze again when space permits. Resized widths are kept under auto table layout, and virtualized measurement is frame-batched so resizing never triggers ResizeObserver loops. The toolbar wraps search and actions on narrow screens, fixed-layout cells clip their content to the column, and empty or loading feedback centers in the visible scrollport. When start and end pins would leave no room for middle columns, end pins scroll with the data. Rendering without `ResizeObserver` (jsdom tests, older embeds) no longer throws; the initial measurement still runs. Omit interactive sort controls from grouped-header alignment placeholders. Fixed-layout column filters scroll within their cell instead of overlapping neighbouring filters; auto layout keeps the full control width.