@tensor_1/react 2.5.0 → 2.7.0

package/dist/index.js

@@ -1,5 +1,8 @@
 import { cx } from "./cx.js";
 import { useDialog } from "./hooks/useDialog.js";
+import { useTable } from "./hooks/useTable.js";
+import { useAnchoredPosition } from "./hooks/useAnchoredPosition.js";
+import { computePosition } from "./overlay-position.js";
 import { Button, ButtonGroup } from "./components/Button.js";
 import { Input, InputGroup } from "./components/Input.js";
 import { Textarea } from "./components/Textarea.js";
@@ -24,7 +27,22 @@ import { NavFavourites } from "./components/NavFavourites.js";
 import { Alert } from "./components/Alert.js";
 import { Spinner } from "./components/Spinner.js";
 import { Toast, Toaster } from "./components/Toast.js";
-import { TableWrap, Table, Th, Td, Tr } from "./components/Table.js";
+import {
+  TableWrap,
+  Table,
+  Th,
+  Td,
+  Tr,
+  BulkBar,
+  RowActions,
+  RowAction,
+  ExpandToggle,
+  CellStrong,
+  CellSub,
+  Mark,
+  Highlighted
+} from "./components/Table.js";
+export * from "./table-engine.js";
 import { Pagination } from "./components/Pagination.js";
 import { StatusPill } from "./components/StatusPill.js";
 import { Progress } from "./components/Progress.js";
@@ -35,6 +53,8 @@ import { EmptyState, ErrorState, Skeleton, LoadingState } from "./components/Sta
 import { Label } from "./components/Label.js";
 import { Avatar, AvatarGroup, UserChip } from "./components/Avatar.js";
 import { Comments, Comment } from "./components/Comments.js";
+import { Composer, ComposerBar } from "./components/Composer.js";
+import { Segmented, SegmentedOption } from "./components/Segmented.js";
 import { Timeline, TimelineItem } from "./components/Timeline.js";
 import { Prose, Note } from "./components/Prose.js";
 import { Popover } from "./components/Popover.js";
@@ -42,27 +62,35 @@ import { CommandPalette, CommandGroup, CommandItem } from "./components/CommandP
 import { Inbox, InboxList, InboxItem, InboxDetail } from "./components/Inbox.js";
 import { Kanban, KanbanColumn, KanbanCard } from "./components/Kanban.js";
 import { Tree } from "./components/Tree.js";
+import { flattenTree, treeNav } from "./tree-model.js";
 export {
   Alert,
   AppShell,
   Avatar,
   AvatarGroup,
+  BulkBar,
   Button,
   ButtonGroup,
   Card,
+  CellStrong,
+  CellSub,
   Checkbox,
   CommandGroup,
   CommandItem,
   CommandPalette,
   Comment,
   Comments,
+  Composer,
+  ComposerBar,
   DescriptionItem,
   DescriptionList,
   DetailLayout,
   Drawer,
   EmptyState,
   ErrorState,
+  ExpandToggle,
   Field,
+  Highlighted,
   Inbox,
   InboxDetail,
   InboxItem,
@@ -76,6 +104,7 @@ export {
   List,
   ListItem,
   LoadingState,
+  Mark,
   Meter,
   Modal,
   NavFavourites,
@@ -90,6 +119,10 @@ export {
   Prose,
   Radio,
   RadioGroup,
+  RowAction,
+  RowActions,
+  Segmented,
+  SegmentedOption,
   Select,
   Sidebar,
   SidebarSection,
@@ -115,6 +148,11 @@ export {
   Tr,
   Tree,
   UserChip,
+  computePosition,
   cx,
-  useDialog
+  flattenTree,
+  treeNav,
+  useAnchoredPosition,
+  useDialog,
+  useTable
 };

package/dist/overlay-position.d.ts

@@ -0,0 +1,59 @@
+/**
+ * uix overlay positioning — framework-agnostic, dependency-free anchored placement.
+ *
+ * Pure geometry (no DOM): given the anchor's rect, the floating element's size, and
+ * the viewport, compute where to put the floating element with two behaviours:
+ *   • flip  — if the preferred side doesn't fit, use the opposite side (or whichever
+ *             side has more room);
+ *   • shift — slide along the cross axis so the element stays within the viewport.
+ *
+ * The React hook (useAnchoredPosition) and the vanilla styleguide both feed this
+ * getBoundingClientRect() values, so anchored overlays land in the same place in every
+ * browser — instead of relying on CSS anchor() positioning, which is Chromium-only and
+ * silently detaches the overlay from its trigger everywhere else (UIX-FIX-02).
+ *
+ * Everything here is deterministic and unit-tested (see overlay-position.test.mjs).
+ */
+type Side = 'top' | 'bottom' | 'left' | 'right';
+type Align = 'start' | 'center' | 'end';
+type Placement = Side | `${Side}-${Align}`;
+/** A viewport-space rectangle, as returned by getBoundingClientRect(). */
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+interface PositionOptions {
+    /** Preferred placement. Default `'bottom-start'`; a bare side (e.g. `'top'`) centers on the cross axis. */
+    placement?: Placement;
+    /** Gap between the anchor and the floating element, in px. Default 6. */
+    offset?: number;
+    /** Minimum gap kept from each viewport edge when shifting, in px. Default 8. */
+    padding?: number;
+    /** Flip to the opposite side when the preferred one doesn't fit. Default true. */
+    flip?: boolean;
+    /** Slide along the cross axis to stay on-screen. Default true. */
+    shift?: boolean;
+}
+interface PositionResult {
+    /** Viewport-space left, for `position: fixed`. */
+    x: number;
+    /** Viewport-space top, for `position: fixed`. */
+    y: number;
+    /** The placement actually used (after any flip). */
+    placement: Placement;
+    side: Side;
+    align: Align;
+}
+/**
+ * Compute the floating element's viewport-space position anchored to `anchor`.
+ * Coordinates are for `position: fixed` (same space as getBoundingClientRect).
+ */
+declare function computePosition(anchor: Rect, floating: Size, viewport: Size, options?: PositionOptions): PositionResult;
+
+export { type Align, type Placement, type PositionOptions, type PositionResult, type Rect, type Side, type Size, computePosition };

package/dist/overlay-position.js

@@ -0,0 +1,62 @@
+const OPPOSITE = { top: "bottom", bottom: "top", left: "right", right: "left" };
+function parsePlacement(p) {
+  const [side, align] = p.split("-");
+  return { side, align: align ?? "center" };
+}
+const clamp = (v, min, max) => Math.max(min, Math.min(max, v));
+function spaceOn(side, a, vp, offset) {
+  switch (side) {
+    case "top":
+      return a.y - offset;
+    case "bottom":
+      return vp.height - (a.y + a.height) - offset;
+    case "left":
+      return a.x - offset;
+    case "right":
+      return vp.width - (a.x + a.width) - offset;
+  }
+}
+function fitsOn(side, a, f, vp, offset, padding) {
+  const need = side === "top" || side === "bottom" ? f.height : f.width;
+  return spaceOn(side, a, vp, offset) >= need + padding;
+}
+function computePosition(anchor, floating, viewport, options = {}) {
+  const { placement = "bottom-start", offset = 6, padding = 8, flip = true, shift = true } = options;
+  const { side: preferred, align } = parsePlacement(placement);
+  let side = preferred;
+  if (flip && !fitsOn(side, anchor, floating, viewport, offset, padding)) {
+    const opp = OPPOSITE[side];
+    if (fitsOn(opp, anchor, floating, viewport, offset, padding) || spaceOn(opp, anchor, viewport, offset) > spaceOn(side, anchor, viewport, offset)) {
+      side = opp;
+    }
+  }
+  let x, y;
+  const horizontal = side === "top" || side === "bottom";
+  if (side === "top") y = anchor.y - floating.height - offset;
+  else if (side === "bottom") y = anchor.y + anchor.height + offset;
+  else if (side === "left") x = anchor.x - floating.width - offset;
+  else x = anchor.x + anchor.width + offset;
+  if (horizontal) {
+    const start = anchor.x;
+    const end = anchor.x + anchor.width - floating.width;
+    const center = anchor.x + (anchor.width - floating.width) / 2;
+    x = align === "start" ? start : align === "end" ? end : center;
+    if (shift) x = clamp(x, padding, Math.max(padding, viewport.width - floating.width - padding));
+  } else {
+    const start = anchor.y;
+    const end = anchor.y + anchor.height - floating.height;
+    const center = anchor.y + (anchor.height - floating.height) / 2;
+    y = align === "start" ? start : align === "end" ? end : center;
+    if (shift) y = clamp(y, padding, Math.max(padding, viewport.height - floating.height - padding));
+  }
+  return {
+    x,
+    y,
+    placement: align === "center" ? side : `${side}-${align}`,
+    side,
+    align
+  };
+}
+export {
+  computePosition
+};

package/dist/table-engine.d.ts

@@ -0,0 +1,89 @@
+/**
+ * uix table engine — framework-agnostic, dependency-free logic for data grids.
+ *
+ * Pure functions only (no DOM, no React), so the same core drives the React
+ * wrappers, the vanilla styleguide, and any consumer. Everything here is
+ * deterministic and unit-tested (see table-engine.test.mjs). The React layer
+ * (useTable / Table subcomponents) composes these; products may also call them
+ * directly. Presentation stays in table.css via the --uix-* contract.
+ */
+type SortDir = 'ascending' | 'descending';
+interface SortKey {
+    /** row field to sort on */
+    field: string;
+    dir: SortDir;
+}
+type Primitive = string | number | boolean | null | undefined;
+type Row = Record<string, unknown>;
+/**
+ * Stable multi-column sort. `keys` are applied in priority order (first is
+ * primary). Returns a new array; the input is not mutated.
+ */
+declare function multiSort<T extends Row>(rows: readonly T[], keys: readonly SortKey[]): T[];
+/** Cycle a header's sort state: none → ascending → descending → none. */
+declare function nextSortDir(current: SortDir | 'none' | undefined): SortDir | 'none';
+/**
+ * Toggle a field within a multi-sort key list. Without shift, it replaces the
+ * list with just this field (cycling its direction); with shift, it adds/updates
+ * the field as a secondary key (removing it when it cycles back to none).
+ */
+declare function toggleSort(keys: readonly SortKey[], field: string, additive?: boolean): SortKey[];
+type FilterKind = 'enum' | 'text' | 'number' | 'date' | 'boolean';
+type FilterOp = 'isAnyOf' | 'isNoneOf' | 'contains' | 'equals' | 'startsWith' | 'eq' | 'lt' | 'gt' | 'between' | 'is';
+interface ColumnFilter {
+    field: string;
+    kind: FilterKind;
+    op: FilterOp;
+    /** value(s): a scalar, an array (enum / between), or [min,max] for between */
+    value: Primitive | Primitive[];
+}
+declare function matchFilter(row: Row, f: ColumnFilter): boolean;
+/** Keep rows that satisfy EVERY active filter (AND across columns). */
+declare function applyFilters<T extends Row>(rows: readonly T[], filters: readonly ColumnFilter[]): T[];
+/** Rows where any of `fields` (default: all string/number values) contains `query`. */
+declare function searchRows<T extends Row>(rows: readonly T[], query: string, fields?: readonly string[]): T[];
+interface Segment {
+    text: string;
+    match: boolean;
+}
+/** Split `text` into matched / unmatched segments for <mark> rendering (case-insensitive). */
+declare function highlightSegments(text: string, query: string): Segment[];
+interface ViewState {
+    sort?: SortKey[];
+    filters?: ColumnFilter[];
+    columns?: string[];
+    density?: 'compact' | 'standard' | 'comfortable';
+    q?: string;
+}
+/** Serialize a view to a compact, linkable query string (no leading '?'). */
+declare function serializeView(v: ViewState): string;
+/** Parse a query string (with or without leading '?') back into a ViewState. */
+declare function parseView(qs: string): ViewState;
+interface VirtualWindow {
+    start: number;
+    end: number;
+    padTop: number;
+    padBottom: number;
+    total: number;
+}
+/**
+ * Compute the visible row window for a fixed row height. Renders only
+ * [start, end) plus `overscan` rows on each side; padTop/padBottom are spacer
+ * heights (px) so the scrollbar stays correct. Below `threshold` rows, callers
+ * should skip virtualization (render all) — see shouldVirtualize.
+ */
+declare function virtualWindow(scrollTop: number, viewportH: number, rowH: number, count: number, overscan?: number): VirtualWindow;
+declare function shouldVirtualize(count: number, threshold?: number): boolean;
+/** Clamp a dragged column width to a sane minimum (and optional maximum). */
+declare function clampWidth(width: number, min?: number, max?: number): number;
+/** Move an item from index `from` to index `to`, returning a new array. */
+declare function reorder<T>(arr: readonly T[], from: number, to: number): T[];
+declare function toggleId(set: ReadonlySet<string>, id: string): Set<string>;
+type SelectAllState = 'none' | 'some' | 'all';
+declare function selectAllState(selected: ReadonlySet<string>, pageIds: readonly string[]): SelectAllState;
+/** Toggle every id on the current page on/off based on the header checkbox. */
+declare function togglePage(selected: ReadonlySet<string>, pageIds: readonly string[]): Set<string>;
+/** Pinned rows (kept present regardless of filter/sort) hoisted above the rest. */
+declare function mergePinned<T extends Row>(all: readonly T[], visible: readonly T[], pinnedIds: ReadonlySet<string>, idField?: string): T[];
+
+export { type ColumnFilter, type FilterKind, type FilterOp, type Primitive, type Row, type Segment, type SelectAllState, type SortDir, type SortKey, type ViewState, type VirtualWindow, applyFilters, clampWidth, highlightSegments, matchFilter, mergePinned, multiSort, nextSortDir, parseView, reorder, searchRows, selectAllState, serializeView, shouldVirtualize, toggleId, togglePage, toggleSort, virtualWindow };

package/dist/table-engine.js

@@ -0,0 +1,251 @@
+function compare(a, b) {
+  if (a == null && b == null) return 0;
+  if (a == null) return -1;
+  if (b == null) return 1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return String(a).localeCompare(String(b), void 0, { numeric: true, sensitivity: "base" });
+}
+function multiSort(rows, keys) {
+  if (!keys.length) return rows.slice();
+  return rows.map((row, i) => ({ row, i })).sort((x, y) => {
+    for (const k of keys) {
+      const c = compare(x.row[k.field], y.row[k.field]);
+      if (c !== 0) return k.dir === "ascending" ? c : -c;
+    }
+    return x.i - y.i;
+  }).map((w) => w.row);
+}
+function nextSortDir(current) {
+  if (current === "ascending") return "descending";
+  if (current === "descending") return "none";
+  return "ascending";
+}
+function toggleSort(keys, field, additive = false) {
+  const existing = keys.find((k) => k.field === field);
+  const dir = nextSortDir(existing?.dir);
+  if (!additive) return dir === "none" ? [] : [{ field, dir }];
+  const rest = keys.filter((k) => k.field !== field);
+  return dir === "none" ? rest : [...rest, { field, dir }];
+}
+function asNum(v) {
+  return typeof v === "number" ? v : Number(v);
+}
+function asTime(v) {
+  if (v == null) return NaN;
+  if (v instanceof Date) return v.getTime();
+  if (typeof v === "number") return v;
+  const s = String(v).trim();
+  if (s === "") return NaN;
+  const parsed = Date.parse(s);
+  return Number.isNaN(parsed) ? Number(s) : parsed;
+}
+function matchDate(cell, f) {
+  const c = asTime(cell);
+  if (Number.isNaN(c)) return false;
+  switch (f.op) {
+    case "eq":
+      return c === asTime(f.value);
+    case "lt":
+      return c < asTime(f.value);
+    case "gt":
+      return c > asTime(f.value);
+    case "between": {
+      const [lo, hi] = f.value.map(asTime);
+      return c >= lo && c <= hi;
+    }
+    default:
+      return true;
+  }
+}
+function matchFilter(row, f) {
+  const cell = row[f.field];
+  if (f.kind === "date") return matchDate(cell, f);
+  switch (f.op) {
+    case "isAnyOf":
+      return Array.isArray(f.value) && f.value.includes(cell);
+    case "isNoneOf":
+      return Array.isArray(f.value) && !f.value.includes(cell);
+    case "contains":
+      return String(cell ?? "").toLowerCase().includes(String(f.value ?? "").toLowerCase());
+    case "equals":
+      return String(cell ?? "") === String(f.value ?? "");
+    case "startsWith":
+      return String(cell ?? "").toLowerCase().startsWith(String(f.value ?? "").toLowerCase());
+    case "eq":
+      return asNum(cell) === asNum(f.value);
+    case "lt":
+      return asNum(cell) < asNum(f.value);
+    case "gt":
+      return asNum(cell) > asNum(f.value);
+    case "between": {
+      const [lo, hi] = f.value.map(asNum);
+      return asNum(cell) >= lo && asNum(cell) <= hi;
+    }
+    case "is":
+      return Boolean(cell) === Boolean(f.value);
+    default:
+      return true;
+  }
+}
+function applyFilters(rows, filters) {
+  if (!filters.length) return rows.slice();
+  return rows.filter((r) => filters.every((f) => matchFilter(r, f)));
+}
+function searchRows(rows, query, fields) {
+  const q = query.trim().toLowerCase();
+  if (!q) return rows.slice();
+  return rows.filter((r) => {
+    const vals = fields ? fields.map((f) => r[f]) : Object.values(r);
+    return vals.some((v) => v != null && String(v).toLowerCase().includes(q));
+  });
+}
+function highlightSegments(text, query) {
+  const q = query.trim();
+  if (!q) return [{ text, match: false }];
+  const out = [];
+  const lower = text.toLowerCase();
+  const ql = q.toLowerCase();
+  let i = 0;
+  for (; ; ) {
+    const hit = lower.indexOf(ql, i);
+    if (hit === -1) {
+      if (i < text.length) out.push({ text: text.slice(i), match: false });
+      break;
+    }
+    if (hit > i) out.push({ text: text.slice(i, hit), match: false });
+    out.push({ text: text.slice(hit, hit + q.length), match: true });
+    i = hit + q.length;
+  }
+  return out;
+}
+const ARRAY_OPS = /* @__PURE__ */ new Set(["isAnyOf", "isNoneOf", "between"]);
+const escapePart = (s) => encodeURIComponent(s).replace(/~/g, "%7E");
+const unescapePart = (s) => decodeURIComponent(s);
+const scalarToStr = (v) => v == null ? "" : String(v);
+function parseScalar(s, kind) {
+  switch (kind) {
+    case "number":
+      return Number(s);
+    case "boolean":
+      return s === "true";
+    case "date":
+      return /^-?\d+$/.test(s) ? Number(s) : s;
+    // epoch-ms number, else the ISO/date string
+    default:
+      return s;
+  }
+}
+function kindFromOp(op) {
+  if (op === "isAnyOf" || op === "isNoneOf") return "enum";
+  if (op === "is") return "boolean";
+  if (op === "contains" || op === "equals" || op === "startsWith") return "text";
+  return "number";
+}
+function serializeFilter(f) {
+  const value = Array.isArray(f.value) ? f.value.map((x) => escapePart(scalarToStr(x))).join("|") : escapePart(scalarToStr(f.value));
+  return `${escapePart(f.field)}~${f.kind}~${f.op}~${value}`;
+}
+function parseFilter(tok) {
+  const parts = tok.split("~");
+  let field, kind, op, raw;
+  if (parts.length >= 4) {
+    [field, kind, op, raw] = [unescapePart(parts[0]), parts[1], parts[2], parts[3] ?? ""];
+  } else {
+    [field, op, raw] = [unescapePart(parts[0]), parts[1], parts[2] ?? ""];
+    kind = kindFromOp(op);
+  }
+  if (!field || !op) return null;
+  const value = ARRAY_OPS.has(op) ? raw.split("|").filter((s) => s !== "").map((s) => parseScalar(unescapePart(s), kind)) : parseScalar(unescapePart(raw), kind);
+  return { field, kind, op, value };
+}
+function serializeView(v) {
+  const p = new URLSearchParams();
+  if (v.sort?.length) p.set("sort", v.sort.map((s) => `${s.field}:${s.dir === "descending" ? "d" : "a"}`).join(","));
+  if (v.columns?.length) p.set("cols", v.columns.join(","));
+  if (v.density && v.density !== "standard") p.set("density", v.density);
+  if (v.q) p.set("q", v.q);
+  if (v.filters?.length) p.set("filter", v.filters.map(serializeFilter).join(","));
+  return p.toString();
+}
+function parseView(qs) {
+  const p = new URLSearchParams(qs.replace(/^\?/, ""));
+  const v = {};
+  const sort = p.get("sort");
+  if (sort) v.sort = sort.split(",").filter(Boolean).map((tok) => {
+    const [field, d] = tok.split(":");
+    return { field, dir: d === "d" ? "descending" : "ascending" };
+  });
+  const cols = p.get("cols");
+  if (cols) v.columns = cols.split(",").filter(Boolean);
+  const density = p.get("density");
+  if (density === "compact" || density === "comfortable" || density === "standard") v.density = density;
+  const q = p.get("q");
+  if (q) v.q = q;
+  const filter = p.get("filter");
+  if (filter) {
+    v.filters = filter.split(",").filter(Boolean).map(parseFilter).filter((f) => f !== null);
+  }
+  return v;
+}
+function virtualWindow(scrollTop, viewportH, rowH, count, overscan = 6) {
+  if (rowH <= 0 || count <= 0) return { start: 0, end: count, padTop: 0, padBottom: 0, total: 0 };
+  const first = Math.max(0, Math.floor(scrollTop / rowH) - overscan);
+  const visible = Math.ceil(viewportH / rowH) + overscan * 2;
+  const end = Math.min(count, first + visible);
+  return { start: first, end, padTop: first * rowH, padBottom: (count - end) * rowH, total: count * rowH };
+}
+function shouldVirtualize(count, threshold = 100) {
+  return count > threshold;
+}
+function clampWidth(width, min = 64, max = Infinity) {
+  return Math.max(min, Math.min(max, Math.round(width)));
+}
+function reorder(arr, from, to) {
+  const next = arr.slice();
+  if (from < 0 || from >= next.length || to < 0 || to >= next.length) return next;
+  const [moved] = next.splice(from, 1);
+  next.splice(to, 0, moved);
+  return next;
+}
+function toggleId(set, id) {
+  const next = new Set(set);
+  next.has(id) ? next.delete(id) : next.add(id);
+  return next;
+}
+function selectAllState(selected, pageIds) {
+  const on = pageIds.filter((id) => selected.has(id)).length;
+  if (on === 0) return "none";
+  return on === pageIds.length ? "all" : "some";
+}
+function togglePage(selected, pageIds) {
+  const next = new Set(selected);
+  const all = pageIds.every((id) => next.has(id));
+  for (const id of pageIds) all ? next.delete(id) : next.add(id);
+  return next;
+}
+function mergePinned(all, visible, pinnedIds, idField = "id") {
+  if (!pinnedIds.size) return visible.slice();
+  const pinned = all.filter((r) => pinnedIds.has(String(r[idField])));
+  const pinnedSet = new Set(pinned.map((r) => String(r[idField])));
+  const rest = visible.filter((r) => !pinnedSet.has(String(r[idField])));
+  return [...pinned, ...rest];
+}
+export {
+  applyFilters,
+  clampWidth,
+  highlightSegments,
+  matchFilter,
+  mergePinned,
+  multiSort,
+  nextSortDir,
+  parseView,
+  reorder,
+  searchRows,
+  selectAllState,
+  serializeView,
+  shouldVirtualize,
+  toggleId,
+  togglePage,
+  toggleSort,
+  virtualWindow
+};

package/dist/tree-model.d.ts

@@ -0,0 +1,48 @@
+/**
+ * uix tree model — framework-agnostic, dependency-free tree flattening + keyboard nav.
+ *
+ * Pure functions (no DOM, no React): flatten a nested tree into the linear list of *visible*
+ * rows (respecting expansion) so it can be virtualized with the table engine's virtualWindow,
+ * and resolve a keyboard key into a navigation decision. Both the plain and the virtualized
+ * <Tree> render paths use these, so the two behave identically and keyboard nav works even for
+ * rows that are scrolled out of the virtual window (UIX-FIX-05). Unit-tested (tree-model.test.mjs).
+ */
+/** Minimal shape a node must have; the concrete node (label, icon, …) rides along as `T`. */
+interface TreeLike<T> {
+    id: string;
+    children?: T[];
+}
+interface FlatNode<T> {
+    node: T;
+    /** 1-based depth, for aria-level. */
+    level: number;
+    /** number of siblings at this level (this node's parent's child count), for aria-setsize. */
+    setsize: number;
+    /** 1-based index among those siblings, for aria-posinset. */
+    posinset: number;
+    hasChildren: boolean;
+    isExpanded: boolean;
+}
+/**
+ * Flatten a nested tree into the visible rows, in DOM/reading order. A node's children follow
+ * it immediately and are included only when the node is in `expanded`.
+ */
+declare function flattenTree<T extends TreeLike<T>>(nodes: readonly T[], expanded: ReadonlySet<string>, level?: number): FlatNode<T>[];
+/** A decision produced by a key press — any subset may be set. */
+interface TreeNavAction {
+    /** move focus (roving tabindex) to this node id. */
+    focusId?: string;
+    /** toggle this node's expansion. */
+    toggleId?: string;
+    /** select this node id. */
+    selectId?: string;
+}
+/**
+ * Resolve a key press against the flattened, visible node list — the single source of truth for
+ * both render paths. Mirrors the WAI-ARIA tree pattern: Up/Down move by row, Right expands then
+ * descends, Left collapses then ascends to the parent, Home/End jump, Enter/Space select (and
+ * toggle a parent). Returns an empty action for unhandled keys or an unknown current id.
+ */
+declare function treeNav<T extends TreeLike<T>>(flat: readonly FlatNode<T>[], currentId: string | undefined, key: string): TreeNavAction;
+
+export { type FlatNode, type TreeLike, type TreeNavAction, flattenTree, treeNav };

package/dist/tree-model.js

@@ -0,0 +1,49 @@
+function flattenTree(nodes, expanded, level = 1) {
+  const out = [];
+  const setsize = nodes.length;
+  nodes.forEach((node, i) => {
+    const hasChildren = Array.isArray(node.children) && node.children.length > 0;
+    const isExpanded = hasChildren && expanded.has(node.id);
+    out.push({ node, level, setsize, posinset: i + 1, hasChildren, isExpanded });
+    if (isExpanded) out.push(...flattenTree(node.children, expanded, level + 1));
+  });
+  return out;
+}
+function treeNav(flat, currentId, key) {
+  const idx = flat.findIndex((f) => f.node.id === currentId);
+  if (idx < 0) return {};
+  const cur = flat[idx];
+  const focusAt = (i) => {
+    const clamped = Math.max(0, Math.min(flat.length - 1, i));
+    return { focusId: flat[clamped]?.node.id };
+  };
+  switch (key) {
+    case "ArrowDown":
+      return focusAt(idx + 1);
+    case "ArrowUp":
+      return focusAt(idx - 1);
+    case "Home":
+      return focusAt(0);
+    case "End":
+      return focusAt(flat.length - 1);
+    case "ArrowRight":
+      if (cur.hasChildren && !cur.isExpanded) return { toggleId: cur.node.id };
+      if (cur.hasChildren && cur.isExpanded) return focusAt(idx + 1);
+      return {};
+    case "ArrowLeft":
+      if (cur.hasChildren && cur.isExpanded) return { toggleId: cur.node.id };
+      for (let i = idx - 1; i >= 0; i--) {
+        if (flat[i].level === cur.level - 1) return { focusId: flat[i].node.id };
+      }
+      return {};
+    case "Enter":
+    case " ":
+      return cur.hasChildren ? { toggleId: cur.node.id, selectId: cur.node.id } : { selectId: cur.node.id };
+    default:
+      return {};
+  }
+}
+export {
+  flattenTree,
+  treeNav
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tensor_1/react",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Thin React wrappers over the UIx v2 CSS component library.",
   "license": "UNLICENSED",
   "type": "module",
@@ -31,7 +31,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --test"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",