@tensor_1/react 2.53.0 → 2.54.0

package/README.md

@@ -205,7 +205,7 @@ Radial mode still shortens long labels to fit its ring, but every node carries i
 - **`Comment variant="system"`** marks a product event, such as a status change, apart from people. It has no speech bubble and a `systemLabel` byline (default "System").
 - **`Comment avatar={false}`** drops the avatar column (`.uix-comment--bare`), for a comment on a rail that already marks each row, such as a system event in a timeline.
 - **`Comment replyTo`** quotes the answered message above the body. Its label comes from `replyToLabel` (default "In reply to"). Mentions in a body use the `.uix-mention` class.
-- **`SaveStatus`** shows `idle`, `saving`, `saved` or `failed` for inline edits and autosave. It offers `onRetry` when a save fails, and every string comes from `labels`. The status text sits in a polite live region that stays mounted while idle, so keep one `SaveStatus` mounted and change its `state`. Mounting it only when a save starts means the first announcement is lost.
+- **`SaveStatus`** shows `idle`, `saving`, `saved` or `failed` for inline edits and autosave. It offers `onRetry` when a save fails, and every string comes from `labels`. The status text sits in a polite live region that stays mounted while idle, so keep one `SaveStatus` mounted and change its `state`. Mounting it only when a save starts means the first announcement is lost. A failed save's sentence wraps inside its container, with the retry beside or under it, so a long refusal stays readable in a narrow footer.
 - **`TabPanel keepMounted`** keeps an inactive panel in the DOM, `hidden` and out of the tab order, so switching back keeps its state and data. It is off by default.
 
 ```tsx
@@ -732,6 +732,52 @@ enumerateDateKeys({ start: '2026-10-11', end: '2026-10-12' });            // { d
 - **Deprecated:** `zonedDateSpan` (end-inclusive, swaps inverted ends) and `enumerateDateSpan` (stops silently at
   370) are unchanged in 2.x. Use `zonedDaySpan` and `enumerateDateKeys`.
 
+### Two-axis grids: MatrixInput and MatrixHeatmap
+
+`MatrixInput` fills a grid of choices, one per row and column, from the keyboard alone. `MatrixHeatmap` shows how many items sit in each cell, each cell's named band, and a way to the items behind it. Neither has words of its own: `labels`, the axes, the options and the bands come from you.
+
+Both are a `role="grid"` table with one tab stop. Arrow keys move between cells, Home and End along a row, and Ctrl+Home and Ctrl+End to the corners. A wide grid scrolls inside its own container with the row headers sticky, so it never widens the page. Set `--uix-matrix-max-height` to keep the column headers in view down a long grid too; without it the page scrolls the grid and they scroll away with it.
+
+```tsx
+<MatrixInput
+  aria-label={t('impact')}
+  rows={criteria}             // { id, label, description? }
+  columns={horizons}
+  options={[
+    { value: 'na', label: t('notRated'), unrated: true },
+    { value: 'low', label: t('low'), tone: 'success' },
+    { value: 'high', label: t('high'), tone: 'danger' },
+  ]}
+  value={value}               // value[rowId][columnId]
+  onChange={(next, change) => setValue(next)}
+  rowAxisLabel={t('criterion')}
+  labels={{ empty: t('choose') }}
+  getCell={(rowId, columnId) => ({ help, error, disabled, readOnly })}
+/>
+```
+
+- Each cell is a `Select`: Enter, Space or a typed letter opens the choice, and focus returns to the cell. Keep `options` stable, because a new array redraws every cell.
+- A cell with no value shows `labels.empty`, and so does one naming an option no longer in `options`: keep a retired option in the list, `disabled`, while stored data can hold it. An `unrated` option is a value, drawn apart from both a level and an empty cell.
+- `help` shows under the grid while the cell has focus or the pointer, and a corner mark says a cell has some. `error` shows in the cell.
+- `disabled` and `readOnly`, on the grid or one cell, keep the cell reachable and readable: the keys still move through it.
+
+```tsx
+<MatrixHeatmap
+  aria-label={t('risks')}
+  rows={impact}
+  columns={likelihood}
+  cells={[{ rowId: 'severe', columnId: 'likely', count: 12, band: { label: t('critical'), tone: 'danger' } }]}
+  onOpenCell={(cell) => openPeek(cell)}
+  rowAxisLabel={t('impact')}
+  columnAxisLabel={t('likelihood')}
+  labels={{ empty: t('noData') }}
+/>
+```
+
+- Each cell shows its count and its band, and is named by its two axes, band and count. Give a cell `href`, with `renderLink` for your router, to make it a link: it navigates and does not call `onOpenCell`.
+- `count: 0` shows a zero. `hideCount` shows the band alone, for a zero you would rather not print. A row and column left out of `cells` is drawn empty (dashed, `labels.empty`), and can still be opened: `onOpenCell` gets only its `rowId` and `columnId`.
+- Tones are `neutral`, `info`, `success`, `warning`, `attention` and `danger`, always beside their words.
+
 ### FilterEditor (typed column filters)
 
 `FilterEditor` is the content of one column-filter popover with a typed value (HAR-1365; TENSOR's

package/dist/components/MatrixHeatmap.d.ts

@@ -0,0 +1,63 @@
+import * as react from 'react';
+import { HTMLAttributes } from 'react';
+import { UixRenderLink } from '../link.js';
+import { MatrixTone, MatrixAxisItem } from './MatrixParts.js';
+
+/** A cell's named band. The name is always shown: colour is never the only cue. */
+interface MatrixBand {
+    label: string;
+    tone?: MatrixTone;
+}
+/** What one cell of a heatmap holds. */
+interface MatrixHeatmapCell {
+    rowId: string;
+    columnId: string;
+    /** How many items sit in the cell. `0` is shown as a zero unless `hideCount` is set. */
+    count?: number;
+    band?: MatrixBand;
+    /**
+     * Show the band without its figure, for a zero the caller would rather not print. Still a cell
+     * with data, drawn apart from a cell the caller left out.
+     */
+    hideCount?: boolean;
+    /** Opens as a link rather than a button, through `renderLink`. */
+    href?: string;
+}
+/** MatrixHeatmap's words. There are no defaults: the kit carries no language of its own here. */
+interface MatrixHeatmapLabels {
+    /** Shown in a cell the caller left out of `cells`. */
+    empty: string;
+}
+interface MatrixHeatmapProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'aria-label' | 'aria-labelledby'> {
+    /** Names the grid. Give this or `aria-labelledby`. */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    rows: readonly MatrixAxisItem[];
+    columns: readonly MatrixAxisItem[];
+    /** The cells with data. A row and column left out is drawn as empty, and can still be opened. */
+    cells: readonly MatrixHeatmapCell[];
+    /**
+     * The drill-through, for every cell without an `href`. An empty cell comes with only its `rowId`
+     * and `columnId`. Without it, a cell with no `href` opens nothing and is marked `aria-disabled`.
+     */
+    onOpenCell?: (cell: MatrixHeatmapCell) => void;
+    /** Draws a cell's `href` with the app's router link. */
+    renderLink?: UixRenderLink;
+    /** Names the row headers, in the corner. */
+    rowAxisLabel: string;
+    /** Names the column headers, in the corner. */
+    columnAxisLabel?: string;
+    labels: MatrixHeatmapLabels;
+}
+/**
+ * How many items sit in each cell of a two-axis grid, each cell's named band, and a way to the
+ * items behind it (HAR-2753). Every cell is one control. The grid is one tab stop: arrow keys
+ * move between cells, Home and End along a row, Ctrl+Home and Ctrl+End to its corners, and Enter
+ * opens the cell.
+ *
+ * Without words of its own: `labels`, the axes and the bands come from the caller. A wide grid
+ * scrolls inside its own container with both headers sticky.
+ */
+declare function MatrixHeatmap({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, rows, columns, cells, onOpenCell, renderLink, rowAxisLabel, columnAxisLabel, labels, className, ...props }: MatrixHeatmapProps): react.JSX.Element;
+
+export { type MatrixBand, MatrixHeatmap, type MatrixHeatmapCell, type MatrixHeatmapLabels, type MatrixHeatmapProps };

package/dist/components/MatrixHeatmap.js

@@ -0,0 +1,67 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { useMatrixGrid } from "../hooks/useMatrixGrid.js";
+import { renderUixLink } from "../link.js";
+import { MatrixFrame, matrixClass } from "./MatrixParts.js";
+const cellKey = (rowId, columnId) => JSON.stringify([rowId, columnId]);
+function MatrixHeatmap({
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  rows,
+  columns,
+  cells,
+  onOpenCell,
+  renderLink,
+  rowAxisLabel,
+  columnAxisLabel,
+  labels,
+  className,
+  ...props
+}) {
+  const { gridRef, onCellKeyDown, onGridFocus } = useMatrixGrid(rows.length, columns.length);
+  const byCell = useMemo(() => new Map(cells.map((cell) => [cellKey(cell.rowId, cell.columnId), cell])), [cells]);
+  return /* @__PURE__ */ jsx("div", { ...props, className: matrixClass(className, "heatmap"), children: /* @__PURE__ */ jsx(
+    MatrixFrame,
+    {
+      gridRef,
+      rows,
+      columns,
+      rowAxisLabel,
+      columnAxisLabel,
+      ariaLabel,
+      ariaLabelledBy,
+      readOnly: true,
+      onFocus: onGridFocus,
+      renderCell: (row, column, rowIndex, columnIndex) => {
+        const cell = byCell.get(cellKey(row.id, column.id));
+        const figure = cell && !cell.hideCount && cell.count != null ? String(cell.count) : null;
+        const empty = figure == null && !cell?.band;
+        const detail = empty ? labels.empty : [cell?.band?.label, figure].filter(Boolean).join(", ");
+        const name = `${row.label}, ${column.label}${detail ? `: ${detail}` : ""}`;
+        const opened = cell ?? { rowId: row.id, columnId: column.id };
+        const control = {
+          className: "uix-matrix__tile",
+          "aria-label": name,
+          tabIndex: rowIndex === 0 && columnIndex === 0 ? 0 : -1,
+          "data-uix-matrix-cell": "",
+          "data-row": rowIndex,
+          "data-column": columnIndex,
+          "data-tone": cell?.band?.tone,
+          "data-empty": empty || void 0,
+          "aria-disabled": cell?.href == null && !onOpenCell || void 0,
+          onKeyDown: onCellKeyDown,
+          onClick: cell?.href != null ? void 0 : () => onOpenCell?.(opened)
+        };
+        const content = /* @__PURE__ */ jsxs(Fragment, { children: [
+          figure != null && /* @__PURE__ */ jsx("span", { className: "uix-matrix__count", children: figure }),
+          /* @__PURE__ */ jsx("span", { className: "uix-matrix__band", children: empty ? labels.empty : cell?.band?.label })
+        ] });
+        return /* @__PURE__ */ jsx("td", { role: "gridcell", className: "uix-matrix__cell", children: cell?.href != null ? renderUixLink(renderLink, { ...control, href: cell.href, children: content }) : /* @__PURE__ */ jsx("button", { type: "button", ...control, children: content }) }, column.id);
+      }
+    }
+  ) });
+}
+export {
+  MatrixHeatmap
+};

package/dist/components/MatrixInput.d.ts

@@ -0,0 +1,83 @@
+import * as react from 'react';
+import { HTMLAttributes } from 'react';
+import { MatrixAxisItem, MatrixTone } from './MatrixParts.js';
+
+/** One choice a cell offers. */
+interface MatrixOption {
+    /** Not empty: an empty value is a cell with none. */
+    value: string;
+    /** Shown in the cell and the list: a level is always readable without its colour. */
+    label: string;
+    tone?: MatrixTone;
+    /** A second, muted line in the list. */
+    description?: string;
+    /**
+     * The value that says "looked at, and not rated". It is drawn apart from the levels, and apart
+     * from a cell with no value at all, which shows `labels.empty`.
+     */
+    unrated?: boolean;
+    disabled?: boolean;
+}
+/**
+ * The choices so far: `value[rowId][columnId]`. A cell without an entry shows `labels.empty`, and
+ * so does one naming an option no longer in `options`: keep retired values among the options, marked
+ * `disabled`, for as long as stored data can hold them.
+ */
+type MatrixValue = Readonly<Record<string, Readonly<Record<string, string | undefined>> | undefined>>;
+/** What one cell changed to. */
+interface MatrixChange {
+    rowId: string;
+    columnId: string;
+    value: string;
+}
+/** What is particular to one cell. */
+interface MatrixCellState {
+    /** Shown under the grid while the cell has focus or the pointer. */
+    help?: string;
+    /** Shown in the cell. */
+    error?: string;
+    /** Can be reached and read, but not changed, and is drawn dimmed. */
+    disabled?: boolean;
+    /** Can be reached and read, but not changed. */
+    readOnly?: boolean;
+}
+/** MatrixInput's words. There are no defaults: the kit carries no language of its own here. */
+interface MatrixInputLabels {
+    /** Shown in a cell with no value. */
+    empty: string;
+}
+interface MatrixInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue' | 'children' | 'aria-label' | 'aria-labelledby'> {
+    /** Names the grid. Give this or `aria-labelledby`. */
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    rows: readonly MatrixAxisItem[];
+    columns: readonly MatrixAxisItem[];
+    /** What each cell can hold. Keep this array stable: a new one redraws every cell. */
+    options: readonly MatrixOption[];
+    value: MatrixValue;
+    /** Called with the whole next value, and with the one cell that changed. */
+    onChange: (value: MatrixValue, change: MatrixChange) => void;
+    /** Names the row headers, in the corner. */
+    rowAxisLabel: string;
+    /** Names the column headers, in the corner. */
+    columnAxisLabel?: string;
+    labels: MatrixInputLabels;
+    /** Help, an error or a lock for one cell. */
+    getCell?: (rowId: string, columnId: string) => MatrixCellState | undefined;
+    /** Every cell can be reached and read, but none changed, and all are drawn dimmed. */
+    disabled?: boolean;
+    /** Every cell can be reached and read, but none changed. */
+    readOnly?: boolean;
+}
+/**
+ * A grid of choices: one value per row and column, filled from the keyboard alone (HAR-2752).
+ * Each cell is a `Select`. The grid is one tab stop: arrow keys move between cells, Home and End
+ * along a row, Ctrl+Home and Ctrl+End to its corners; Enter, Space or a typed letter opens the
+ * choice, and focus comes back to the cell afterwards.
+ *
+ * Controlled, and without words of its own: `labels`, the axes and the options come from the
+ * caller. A wide grid scrolls inside its own container with both headers sticky.
+ */
+declare function MatrixInput({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, rows, columns, options, value, onChange, rowAxisLabel, columnAxisLabel, labels, getCell, disabled, readOnly, className, ...props }: MatrixInputProps): react.JSX.Element;
+
+export { type MatrixCellState, type MatrixChange, MatrixInput, type MatrixInputLabels, type MatrixInputProps, type MatrixOption, type MatrixValue };

package/dist/components/MatrixInput.js

@@ -0,0 +1,162 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { memo, useCallback, useEffect, useId, useMemo, useRef } from "react";
+import { useMatrixGrid } from "../hooks/useMatrixGrid.js";
+import { MatrixFrame, matrixClass } from "./MatrixParts.js";
+import { Select } from "./Select.js";
+const Cell = memo(function Cell2({
+  rowId,
+  columnId,
+  rowIndex,
+  columnIndex,
+  name,
+  value,
+  options,
+  option,
+  empty,
+  help,
+  error,
+  disabled,
+  readOnly,
+  id,
+  onKeyDown,
+  onPick
+}) {
+  const locked = disabled || readOnly;
+  const helpId = help ? `${id}-help` : void 0;
+  const errorId = error ? `${id}-error` : void 0;
+  const describedBy = [errorId, helpId].filter(Boolean).join(" ") || void 0;
+  return /* @__PURE__ */ jsxs("td", { role: "gridcell", className: "uix-matrix__cell", "aria-readonly": locked || void 0, "aria-invalid": error ? true : void 0, children: [
+    /* @__PURE__ */ jsx(
+      Select,
+      {
+        size: "sm",
+        "aria-label": name,
+        "aria-describedby": describedBy,
+        "aria-disabled": disabled || void 0,
+        tabIndex: rowIndex === 0 && columnIndex === 0 ? 0 : -1,
+        options,
+        value,
+        placeholder: empty,
+        readOnly: locked,
+        invalid: !!error,
+        "data-uix-matrix-cell": "",
+        "data-row": rowIndex,
+        "data-column": columnIndex,
+        "data-tone": option?.tone,
+        "data-unrated": option?.unrated || void 0,
+        "data-locked": disabled || void 0,
+        "data-help": help,
+        onKeyDown,
+        onValueChange: (next) => onPick(rowId, columnId, next)
+      }
+    ),
+    help && /* @__PURE__ */ jsx("span", { id: helpId, className: "uix-visually-hidden", children: help }),
+    error && /* @__PURE__ */ jsx("span", { id: errorId, className: "uix-matrix__error", children: error })
+  ] });
+});
+function MatrixInput({
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  rows,
+  columns,
+  options,
+  value,
+  onChange,
+  rowAxisLabel,
+  columnAxisLabel,
+  labels,
+  getCell,
+  disabled = false,
+  readOnly = false,
+  className,
+  ...props
+}) {
+  const uid = useId();
+  const { gridRef, onCellKeyDown, onGridFocus } = useMatrixGrid(rows.length, columns.length);
+  const helpRef = useRef(null);
+  const latest = useRef({ value, onChange });
+  latest.current = { value, onChange };
+  const onPick = useCallback((rowId, columnId, next) => {
+    const current = latest.current;
+    current.onChange(
+      { ...current.value, [rowId]: { ...current.value[rowId], [columnId]: next } },
+      { rowId, columnId, value: next }
+    );
+  }, []);
+  const choices = useMemo(() => options.map(({ value: v, label, description, disabled: off }) => ({
+    value: v,
+    label,
+    ...description ? { description } : {},
+    ...off ? { disabled: true } : {}
+  })), [options]);
+  const byValue = useMemo(() => new Map(options.map((o) => [o.value, o])), [options]);
+  const showHelp = (cell) => {
+    if (helpRef.current) helpRef.current.textContent = cell?.getAttribute("data-help") ?? "";
+  };
+  const cellOf = (target) => target?.closest?.("[data-uix-matrix-cell]") ?? null;
+  const onFocus = (event) => {
+    onGridFocus(event);
+    showHelp(cellOf(event.target));
+  };
+  const onPointerOver = (event) => {
+    const cell = cellOf(event.target);
+    if (cell && event.pointerType === "mouse") showHelp(cell);
+  };
+  const onPointerLeave = () => showHelp(cellOf(document.activeElement));
+  const onBlur = (event) => {
+    if (!event.currentTarget.contains(event.relatedTarget)) showHelp(null);
+  };
+  useEffect(() => {
+    const focused = cellOf(document.activeElement);
+    if (focused && gridRef.current?.contains(focused)) showHelp(focused);
+  });
+  const anyHelp = !!getCell && rows.some((row) => columns.some((column) => getCell(row.id, column.id)?.help));
+  return /* @__PURE__ */ jsxs("div", { ...props, className: matrixClass(className, "input"), children: [
+    /* @__PURE__ */ jsx(
+      MatrixFrame,
+      {
+        gridRef,
+        rows,
+        columns,
+        rowAxisLabel,
+        columnAxisLabel,
+        ariaLabel,
+        ariaLabelledBy,
+        readOnly,
+        onFocus,
+        gridProps: { onPointerOver, onPointerLeave, onBlur },
+        renderCell: (row, column, rowIndex, columnIndex) => {
+          const state = getCell?.(row.id, column.id);
+          const current = value[row.id]?.[column.id] ?? "";
+          return /* @__PURE__ */ jsx(
+            Cell,
+            {
+              rowId: row.id,
+              columnId: column.id,
+              rowIndex,
+              columnIndex,
+              name: `${row.label}, ${column.label}`,
+              value: current,
+              options: choices,
+              option: byValue.get(current),
+              empty: labels.empty,
+              help: state?.help,
+              error: state?.error,
+              disabled: disabled || !!state?.disabled,
+              readOnly: readOnly || !!state?.readOnly,
+              id: `${uid}-${rowIndex}-${columnIndex}`,
+              onKeyDown: onCellKeyDown,
+              onPick
+            },
+            column.id
+          );
+        }
+      }
+    ),
+    anyHelp && /* @__PURE__ */ jsx("p", { ref: helpRef, className: "uix-matrix__help", "aria-hidden": "true" })
+  ] });
+}
+export {
+  MatrixInput
+};

package/dist/components/MatrixParts.d.ts

@@ -0,0 +1,39 @@
+import * as react from 'react';
+import { ReactNode, RefObject, FocusEventHandler } from 'react';
+
+/** A level's or a band's colour. It always comes with words: colour is never the only cue. */
+type MatrixTone = 'neutral' | 'info' | 'success' | 'warning' | 'attention' | 'danger';
+/** One row or column of a matrix. */
+interface MatrixAxisItem {
+    id: string;
+    /** Names the header, and the cells under it to a screen reader. */
+    label: string;
+    /** A second, muted line in the header. */
+    description?: ReactNode;
+}
+interface MatrixFrameProps {
+    gridRef: RefObject<HTMLTableElement>;
+    rows: readonly MatrixAxisItem[];
+    columns: readonly MatrixAxisItem[];
+    /** Names the row headers, in the corner. */
+    rowAxisLabel: string;
+    /** Names the column headers, in the corner. */
+    columnAxisLabel?: string;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+    readOnly: boolean;
+    onFocus: FocusEventHandler<HTMLElement>;
+    gridProps?: Record<string, unknown>;
+    /** The cell at a row and a column, as `<td>`. */
+    renderCell: (row: MatrixAxisItem, column: MatrixAxisItem, rowIndex: number, columnIndex: number) => ReactNode;
+}
+/**
+ * The table both matrices share: a `role="grid"` table with sticky row and column headers, in
+ * its own scroller so a wide grid never widens the page. The layout is fixed, so a cell does not
+ * change width when its words do.
+ */
+declare function MatrixFrame({ gridRef, rows, columns, rowAxisLabel, columnAxisLabel, ariaLabel, ariaLabelledBy, readOnly, onFocus, gridProps, renderCell, }: MatrixFrameProps): react.JSX.Element;
+/** The class of a matrix's outer element. */
+declare const matrixClass: (className: string | undefined, modifier?: string) => string;
+
+export { type MatrixAxisItem, MatrixFrame, type MatrixTone, matrixClass };

package/dist/components/MatrixParts.js

@@ -0,0 +1,54 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cx } from "../cx.js";
+function MatrixFrame({
+  gridRef,
+  rows,
+  columns,
+  rowAxisLabel,
+  columnAxisLabel,
+  ariaLabel,
+  ariaLabelledBy,
+  readOnly,
+  onFocus,
+  gridProps,
+  renderCell
+}) {
+  return /* @__PURE__ */ jsx("div", { className: "uix-matrix__scroll", children: /* @__PURE__ */ jsxs(
+    "table",
+    {
+      ...gridProps,
+      ref: gridRef,
+      role: "grid",
+      className: "uix-matrix__grid",
+      style: { "--uix-matrix-columns": columns.length },
+      "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabelledBy,
+      "aria-readonly": readOnly || void 0,
+      onFocus,
+      children: [
+        /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+          /* @__PURE__ */ jsxs("th", { scope: "col", className: "uix-matrix__corner", children: [
+            columnAxisLabel && /* @__PURE__ */ jsx("span", { className: "uix-matrix__axis uix-matrix__axis--column", children: columnAxisLabel }),
+            /* @__PURE__ */ jsx("span", { className: "uix-matrix__axis", children: rowAxisLabel })
+          ] }),
+          columns.map((column) => /* @__PURE__ */ jsxs("th", { scope: "col", className: "uix-matrix__column", children: [
+            column.label,
+            column.description != null && /* @__PURE__ */ jsx("span", { className: "uix-matrix__note", children: column.description })
+          ] }, column.id))
+        ] }) }),
+        /* @__PURE__ */ jsx("tbody", { children: rows.map((row, rowIndex) => /* @__PURE__ */ jsxs("tr", { children: [
+          /* @__PURE__ */ jsxs("th", { scope: "row", className: "uix-matrix__row", children: [
+            row.label,
+            row.description != null && /* @__PURE__ */ jsx("span", { className: "uix-matrix__note", children: row.description })
+          ] }),
+          columns.map((column, columnIndex) => renderCell(row, column, rowIndex, columnIndex))
+        ] }, row.id)) })
+      ]
+    }
+  ) });
+}
+const matrixClass = (className, modifier) => cx("uix-matrix", modifier && `uix-matrix--${modifier}`, className);
+export {
+  MatrixFrame,
+  matrixClass
+};

package/dist/hooks/useMatrixGrid.d.ts

@@ -0,0 +1,17 @@
+import { RefObject, KeyboardEvent, FocusEvent } from 'react';
+
+interface MatrixGrid {
+    gridRef: RefObject<HTMLTableElement>;
+    /** On each cell's control. A control with an open list (`aria-expanded`) keeps its own keys. */
+    onCellKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    /** On the grid: the focused cell becomes the tab stop. */
+    onGridFocus: (event: FocusEvent<HTMLElement>) => void;
+}
+/**
+ * One tab stop and arrow-key movement over a grid's cells, written straight to the DOM: moving
+ * through a grid of 50 Selects re-renders none of them. The stop survives a re-render, and falls
+ * to the cell now in its place when its own cell has gone.
+ */
+declare function useMatrixGrid(rows: number, columns: number): MatrixGrid;
+
+export { type MatrixGrid, useMatrixGrid };

package/dist/hooks/useMatrixGrid.js

@@ -0,0 +1,49 @@
+"use client";
+import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
+import { matrixStep } from "../matrix-model.js";
+import { syncRovingStop } from "../roving.js";
+const useIsomorphicLayoutEffect = typeof document !== "undefined" ? useLayoutEffect : useEffect;
+const CELL = "[data-uix-matrix-cell]";
+function useMatrixGrid(rows, columns) {
+  const gridRef = useRef(null);
+  const stop = useRef({ node: null, index: 0 });
+  const size = useRef({ rows, columns });
+  size.current = { rows, columns };
+  const cells = () => Array.from(gridRef.current?.querySelectorAll(CELL) ?? []);
+  useIsomorphicLayoutEffect(() => {
+    stop.current = syncRovingStop(cells(), stop.current);
+  });
+  const onGridFocus = useCallback((event) => {
+    const cell = event.target.closest(CELL);
+    if (cell) stop.current = syncRovingStop(cells(), stop.current, cell);
+  }, []);
+  const onCellKeyDown = useCallback((event) => {
+    const cell = event.currentTarget;
+    if (cell.getAttribute("aria-expanded") === "true") return;
+    const { key, altKey, shiftKey } = event;
+    const corner = event.ctrlKey || event.metaKey;
+    if (altKey || shiftKey || corner && key !== "Home" && key !== "End") return;
+    const to = matrixStep(
+      { row: Number(cell.dataset.row), column: Number(cell.dataset.column) },
+      size.current,
+      key,
+      { corner, rtl: getComputedStyle(cell).direction === "rtl" }
+    );
+    if (!to) return;
+    event.preventDefault();
+    const next = gridRef.current?.querySelector(`${CELL}[data-row="${to.row}"][data-column="${to.column}"]`);
+    if (!next || next === cell) return;
+    next.focus({ preventScroll: true });
+    next.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+    const grid = gridRef.current;
+    const header = grid?.tHead?.rows[0]?.cells[0];
+    const scroller = grid?.parentElement;
+    if (!header || !scroller) return;
+    const under = header.getBoundingClientRect().bottom - next.getBoundingClientRect().top;
+    if (under > 0) scroller.scrollTop -= under;
+  }, []);
+  return { gridRef, onCellKeyDown, onGridFocus };
+}
+export {
+  useMatrixGrid
+};