@cueplusplus/ui 0.5.0 → 0.6.0

package/dist/instruments/data-tree.js

@@ -0,0 +1,303 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { flattenTree } from "../chrome/_tree.js";
+import { ChevronRightGlyph } from "../chrome/_glyphs.js";
+import { activateRowFromClick, dataRowVariants } from "./_data-row.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/data-tree.tsx
+/**
+* The hierarchy guides, drawn as a background rather than as characters or
+* borders.
+*
+* One hairline per ancestor level, from a `repeating-linear-gradient` whose
+* period is the indent step and whose painted width is `depth × step` — so the
+* rules stop exactly where the row's own content begins. Three properties of
+* this mechanism are the reason it is not box-drawing glyphs and not a stack of
+* `border-left` spacers:
+*
+* - It is a `background-image`, so the row's hover and selection
+*   `background-color` cannot cover it, move it or switch it off. A guide drawn
+*   with borders on spacer elements has to be re-tinted for every row state.
+* - It costs no DOM. A tree of two thousand visible rows adds no elements per
+*   level, which is what makes a virtualized variant of this row viable later.
+* - It is a picture of structure, not a picture of a tree: `├` and `└` in a mono
+*   grid are characters a screen reader may read out and a proportional font
+*   destroys.
+*
+* The step is `--cue-data-tree-indent` (default `1.25rem`), a local custom
+* property so a `@container` rule can tighten the tree at the same breakpoint it
+* sheds a column — and switch the guides off entirely at the width where an
+* indent is more expensive than it is informative.
+*/
+const DATA_TREE_GUIDES = [
+	"bg-no-repeat",
+	"[background-image:repeating-linear-gradient(to_right,var(--cue-hair)_0,var(--cue-hair)_1px,transparent_1px,transparent_var(--cue-data-tree-indent,1.25rem))]",
+	"[background-size:calc(var(--depth)_*_var(--cue-data-tree-indent,1.25rem))_100%]",
+	"[background-position:var(--cue-pad-row-x)_0]"
+].join(" ");
+/**
+* `DataTreeItem` as the shape `flattenTree` walks, plus a way back.
+*
+* `flattenTree` (`src/chrome/_tree.ts`) is the outline algorithm this library
+* already has, and re-implementing "which rows are visible, at what level, in
+* what position of what set" for a second tree is how two trees start
+* disagreeing about what a collapse hides. It reads `id`, `children` and
+* `disabled`; its `TreeItem` also *declares* a `label`, which a data row does
+* not have — its content is columns. So the walk maps to that shape with a null
+* label and hands back an index from id to the caller's own item, which is what
+* the row renderer reads.
+*
+* @param items The roots, in display order.
+* @returns The outline `flattenTree` accepts, and the items keyed by id.
+*/
+function outlineOf(items) {
+	const byId = /* @__PURE__ */ new Map();
+	const walk = (nodes) => nodes.map((node) => {
+		byId.set(node.id, node);
+		const outlineNode = {
+			id: node.id,
+			label: null,
+			disabled: node.disabled
+		};
+		if (node.children !== void 0) outlineNode.children = walk(node.children);
+		return outlineNode;
+	});
+	return {
+		outline: walk(items),
+		byId
+	};
+}
+/**
+* A hierarchy of multi-column rows: the tree idiom over the `DataRow` anatomy.
+*
+* ## The ARIA pattern, chosen before the component was written
+*
+* `role="treegrid"` is **rejected** for this foundation. It is the semantically
+* exact answer — tabular *and* hierarchical — and it is the one with the worst
+* real-world assistive-technology record: Adrian Roselli's survey of expando
+* tables calls its support poor and notes that the APG's own worked example
+* carries unresolved issues; fancytree's maintainer describes treegrid support
+* as unproven ground; MUI X shipped hierarchical rows with no `aria-level` /
+* `aria-expanded` / `aria-setsize` at all and retrofitted them later. Treegrid
+* earns its cost when cells are individually interactive or editable, because
+* then a reader genuinely needs two-dimensional cell navigation. This surface is
+* read-and-navigate: you move down rows, fold a branch, and open the thing a row
+* names.
+*
+* So the pattern is `role="tree"` with `role="treeitem"` rows — VS Code's
+* choice and Carbon's, and the best-supported composite pattern in ARIA:
+*
+* - A **flat DOM** with `aria-level` / `aria-posinset` / `aria-setsize` per row
+*   rather than nested `role="group"` wrappers.
+* - **Roving tabindex**: the tree is one Tab stop and the arrows move inside it.
+* - The **APG tree keyboard map**: Up/Down between visible rows, Home/End to the
+*   ends, Right to unfold then to descend, Left to fold then to ascend,
+*   Enter/Space to select.
+* - Expansion lives on the **row**, as `aria-expanded` on the `treeitem` — that
+*   is what tree semantics mean by a parent, and it is why the chevron here is
+*   `role="presentation"` rather than a button. (The other half of this trade
+*   is `Table.GroupRow`, where the table's semantics own the grouping and a real
+*   `<button aria-expanded>` owns the disclosure. Two patterns, each internally
+*   consistent; what would be wrong is half of each.)
+*
+* **The documented trade**: columns are not independently navigable. A row's
+* multi-column content lives *inside* the treeitem, so a screen-reader user
+* hears the row as one string rather than moving cell to cell through it. For a
+* dense browse-and-open surface that is the better bargain — `tree` works today
+* on every screen reader, `treegrid` does not — but a surface whose cells are
+* genuinely editable has outgrown this component and wants a real treegrid from
+* a library that maintains one.
+*
+* ## Everything else
+*
+* Rows are the `DataRow` chassis: same padding, same hairline, same hover wash,
+* same inset focus ring, same `group/data-row`, so `DataRow.Actions` reveals in
+* a tree exactly as it does in a ledger. The row element itself is the
+* treeitem — one element owns focus, expansion, selection and the click reading
+* — and the caller's `DataRow.*` slots are its content.
+*
+* A tree whose items declare no children anywhere is a flat list: no chevrons,
+* no spacer column where a chevron would be, no guides, and `aria-expanded` on
+* nothing. A leaf row that carried `aria-expanded="false"` would tell a screen
+* reader it has children it does not have.
+*
+* @example
+* <DataTree
+*   aria-label="Patch"
+*   items={nodes}
+*   defaultExpanded={["inputs"]}
+*   selected={selected}
+*   onSelect={setSelected}
+*   className="[--cue-data-row-cols:1fr_8rem_auto]"
+* />
+*/
+const DataTree = React.forwardRef(function DataTree({ className, items, expanded: expandedProp, defaultExpanded, onExpandedChange, selected: selectedProp, defaultSelected = null, onSelect, guides = true, onKeyDown, ...elementProps }, ref) {
+	const [uncontrolledExpanded, setUncontrolledExpanded] = React.useState(defaultExpanded ?? []);
+	const expandedList = expandedProp ?? uncontrolledExpanded;
+	const expandedSet = React.useMemo(() => new Set(expandedList), [expandedList]);
+	const [uncontrolledSelected, setUncontrolledSelected] = React.useState(defaultSelected);
+	const selected = selectedProp === void 0 ? uncontrolledSelected : selectedProp;
+	const { outline, byId } = React.useMemo(() => outlineOf(items), [items]);
+	const rows = React.useMemo(() => flattenTree(outline, expandedSet), [outline, expandedSet]);
+	const hierarchical = React.useMemo(() => {
+		for (const item of byId.values()) if (item.children !== void 0) return true;
+		return false;
+	}, [byId]);
+	const [activeId, setActiveId] = React.useState(null);
+	const activeRowId = activeId !== null && rows.some((row) => row.item.id === activeId) ? activeId : rows[0]?.item.id ?? null;
+	const rowRefs = React.useRef(/* @__PURE__ */ new Map());
+	const registerRow = React.useCallback((id, element) => {
+		if (element === null) rowRefs.current.delete(id);
+		else rowRefs.current.set(id, element);
+	}, []);
+	const focusRow = React.useCallback((id) => {
+		setActiveId(id);
+		rowRefs.current.get(id)?.focus();
+	}, []);
+	const setExpanded = React.useCallback((id, next) => {
+		const current = expandedProp ?? uncontrolledExpanded;
+		const result = next ? current.includes(id) ? [...current] : [...current, id] : current.filter((entry) => entry !== id);
+		if (expandedProp === void 0) setUncontrolledExpanded(result);
+		onExpandedChange?.(result);
+	}, [
+		expandedProp,
+		onExpandedChange,
+		uncontrolledExpanded
+	]);
+	const select = React.useCallback((row) => {
+		if (byId.get(row.item.id)?.disabled === true) return;
+		if (selectedProp === void 0) setUncontrolledSelected(row.item.id);
+		onSelect?.(row.item.id);
+	}, [
+		byId,
+		onSelect,
+		selectedProp
+	]);
+	/**
+	* The APG tree keyboard map.
+	*
+	* A near-copy of `Tree`'s handler in `src/chrome/tree.tsx`, and deliberately
+	* so: the two trees paint different rows (a label with a glyph gutter there,
+	* columns with a CSS indent here) and share `flattenTree`, which is the half
+	* that is actually hard. Extracting the twenty lines below into a third module
+	* would have to thread the row registry, the expansion setter and the
+	* selection through it, and the seam would be wider than the code. If a third
+	* tree ever appears, that is the moment to hoist it.
+	*/
+	const handleKeyDown = React.useCallback((event) => {
+		onKeyDown?.(event);
+		if (event.defaultPrevented) return;
+		if (event.target.getAttribute("data-slot") !== "data-tree-row") return;
+		const index = rows.findIndex((row) => row.item.id === activeRowId);
+		const row = rows[index];
+		if (row === void 0) return;
+		const move = (target) => {
+			if (target === void 0) return;
+			event.preventDefault();
+			focusRow(target.item.id);
+		};
+		switch (event.key) {
+			case "ArrowDown":
+				move(rows[index + 1]);
+				return;
+			case "ArrowUp":
+				move(rows[index - 1]);
+				return;
+			case "Home":
+				move(rows[0]);
+				return;
+			case "End":
+				move(rows[rows.length - 1]);
+				return;
+			case "ArrowRight": {
+				event.preventDefault();
+				if (row.hasChildren && !row.expanded) {
+					setExpanded(row.item.id, true);
+					return;
+				}
+				const child = rows[index + 1];
+				if (row.expanded && child?.parentId === row.item.id) focusRow(child.item.id);
+				return;
+			}
+			case "ArrowLeft":
+				event.preventDefault();
+				if (row.expanded) setExpanded(row.item.id, false);
+				else if (row.parentId !== null) focusRow(row.parentId);
+				return;
+			case "Enter":
+			case " ":
+				event.preventDefault();
+				select(row);
+				return;
+		}
+	}, [
+		activeRowId,
+		focusRow,
+		onKeyDown,
+		rows,
+		select,
+		setExpanded
+	]);
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		...elementProps,
+		role: "tree",
+		"data-slot": "data-tree",
+		className: cn("flex flex-col font-mono text-(length:--cue-text-ui) text-fg", className),
+		onKeyDown: handleKeyDown,
+		children: rows.map((row) => {
+			const item = byId.get(row.item.id);
+			if (item === void 0) return null;
+			const isSelected = selected === item.id;
+			const state = {
+				level: row.level,
+				hasChildren: row.hasChildren,
+				expanded: row.expanded,
+				selected: isSelected
+			};
+			return /* @__PURE__ */ jsxs("div", {
+				ref: (element) => registerRow(item.id, element),
+				role: "treeitem",
+				tabIndex: activeRowId === item.id ? 0 : -1,
+				"aria-level": row.level + 1,
+				"aria-posinset": row.position,
+				"aria-setsize": row.setSize,
+				"aria-expanded": row.hasChildren ? row.expanded : void 0,
+				"aria-selected": isSelected,
+				"aria-disabled": item.disabled === true ? true : void 0,
+				"data-slot": "data-tree-row",
+				"data-selected": isSelected ? "" : void 0,
+				"data-disabled": item.disabled === true ? "" : void 0,
+				style: { "--depth": row.level },
+				onFocus: () => setActiveId(item.id),
+				onClick: (event) => activateRowFromClick(event, () => select(row)),
+				className: cn(dataRowVariants({
+					layout: "flex",
+					indent: true,
+					interactive: true
+				}), guides && row.level > 0 ? DATA_TREE_GUIDES : null),
+				children: [hierarchical ? row.hasChildren ? /* @__PURE__ */ jsx("span", {
+					role: "presentation",
+					"aria-hidden": "true",
+					"data-slot": "data-tree-toggle",
+					onClick: (event) => {
+						event.stopPropagation();
+						setExpanded(item.id, !row.expanded);
+					},
+					className: "flex size-icon-sm shrink-0 cursor-pointer items-center justify-center text-fg-subtle",
+					children: /* @__PURE__ */ jsx(ChevronRightGlyph, { className: cn("size-icon-sm transition-transform duration-150 motion-reduce:transition-none", row.expanded ? "rotate-90" : null) })
+				}) : /* @__PURE__ */ jsx("span", {
+					"aria-hidden": "true",
+					className: "size-icon-sm shrink-0"
+				}) : null, /* @__PURE__ */ jsx("span", {
+					"data-slot": "data-tree-row-content",
+					className: "grid min-w-0 flex-1 items-center gap-(--cue-space-3) [grid-template-columns:var(--cue-data-row-cols,1fr_auto)]",
+					children: typeof item.row === "function" ? item.row(state) : item.row
+				})]
+			}, item.id);
+		})
+	});
+});
+//#endregion
+export { DataTree };

package/dist/instruments/index.d.ts

@@ -1,13 +1,16 @@
 import { AppWindowFrame, AppWindowFrameProps } from "./app-window-frame.js";
 import { CopyButton, CopyButtonProps } from "./copy-button.js";
+import { DataRow, DataRowDisclosure, DataRowRootProps, DataRowSlotProps } from "./data-row.js";
+import { DataTree, DataTreeItem, DataTreeProps, DataTreeRowState } from "./data-tree.js";
 import { GroupBar, GroupBarItem, GroupBarProps, GroupBarTone } from "./group-bar.js";
+import { Ledger, LedgerEmptyProps, LedgerGroupProps, LedgerRootProps, LedgerTierProps } from "./ledger.js";
 import { Meter, MeterProps, MeterProvenance, MeterTone } from "./meter.js";
 import { Progress, ProgressProps } from "./progress.js";
 import { SeamCell, SeamCellProps, SeamGrid, SeamGridProps, SeamGround } from "./seam-grid.js";
 import { Sparkline, SparklineProps } from "./sparkline.js";
 import { Stat, StatProps, StatTone } from "./stat.js";
-import { Table, TableCaptionProps, TableCellProps, TableHeadProps, TableRootProps, TableRowProps, TableScrollRegion, TableScrollRegionProps, TableSectionProps } from "./table.js";
+import { Table, TableCaptionProps, TableCellProps, TableGroupRowProps, TableHeadProps, TableRootProps, TableRowProps, TableScrollRegion, TableScrollRegionProps, TableSectionProps } from "./table.js";
 import { TerminalFrame, TerminalFrameLine, TerminalFrameProps, TerminalLine, TerminalLineTone, TerminalScript, TerminalStep } from "./terminal-frame.js";
 import { TwoStepButton, TwoStepButtonProps, TwoStepTone } from "./two-step-button.js";
 import { UsageChart, UsageChartPoint, UsageChartProps, UsageChartTone } from "./usage-chart.js";
-export { AppWindowFrame, type AppWindowFrameProps, CopyButton, type CopyButtonProps, GroupBar, type GroupBarItem, type GroupBarProps, type GroupBarTone, Meter, type MeterProps, type MeterProvenance, type MeterTone, Progress, type ProgressProps, SeamCell, type SeamCellProps, SeamGrid, type SeamGridProps, type SeamGround, Sparkline, type SparklineProps, Stat, type StatProps, type StatTone, Table, type TableCaptionProps, type TableCellProps, type TableHeadProps, type TableRootProps, type TableRowProps, TableScrollRegion, type TableScrollRegionProps, type TableSectionProps, TerminalFrame, type TerminalFrameLine, type TerminalFrameProps, type TerminalLine, type TerminalLineTone, type TerminalScript, type TerminalStep, TwoStepButton, type TwoStepButtonProps, type TwoStepTone, UsageChart, type UsageChartPoint, type UsageChartProps, type UsageChartTone };
+export { AppWindowFrame, type AppWindowFrameProps, CopyButton, type CopyButtonProps, DataRow, type DataRowDisclosure, type DataRowRootProps, type DataRowSlotProps, DataTree, type DataTreeItem, type DataTreeProps, type DataTreeRowState, GroupBar, type GroupBarItem, type GroupBarProps, type GroupBarTone, Ledger, type LedgerEmptyProps, type LedgerGroupProps, type LedgerRootProps, type LedgerTierProps, Meter, type MeterProps, type MeterProvenance, type MeterTone, Progress, type ProgressProps, SeamCell, type SeamCellProps, SeamGrid, type SeamGridProps, type SeamGround, Sparkline, type SparklineProps, Stat, type StatProps, type StatTone, Table, type TableCaptionProps, type TableCellProps, type TableGroupRowProps, type TableHeadProps, type TableRootProps, type TableRowProps, TableScrollRegion, type TableScrollRegionProps, type TableSectionProps, TerminalFrame, type TerminalFrameLine, type TerminalFrameProps, type TerminalLine, type TerminalLineTone, type TerminalScript, type TerminalStep, TwoStepButton, type TwoStepButtonProps, type TwoStepTone, UsageChart, type UsageChartPoint, type UsageChartProps, type UsageChartTone };

package/dist/instruments/index.js

@@ -1,6 +1,9 @@
 import { AppWindowFrame } from "./app-window-frame.js";
 import { CopyButton } from "./copy-button.js";
+import { DataRow } from "./data-row.js";
+import { DataTree } from "./data-tree.js";
 import { GroupBar } from "./group-bar.js";
+import { Ledger } from "./ledger.js";
 import { Meter } from "./meter.js";
 import { Progress } from "./progress.js";
 import { SeamCell, SeamGrid } from "./seam-grid.js";
@@ -10,4 +13,4 @@ import { Table, TableScrollRegion } from "./table.js";
 import { TerminalFrame } from "./terminal-frame.js";
 import { TwoStepButton } from "./two-step-button.js";
 import { UsageChart } from "./usage-chart.js";
-export { AppWindowFrame, CopyButton, GroupBar, Meter, Progress, SeamCell, SeamGrid, Sparkline, Stat, Table, TableScrollRegion, TerminalFrame, TwoStepButton, UsageChart };
+export { AppWindowFrame, CopyButton, DataRow, DataTree, GroupBar, Ledger, Meter, Progress, SeamCell, SeamGrid, Sparkline, Stat, Table, TableScrollRegion, TerminalFrame, TwoStepButton, UsageChart };

package/dist/instruments/ledger.d.ts

@@ -0,0 +1,105 @@
+import * as React from "react";
+//#region src/instruments/ledger.d.ts
+/** The heading elements a tier or a group may be given. */
+type LedgerHeadingLevel = 2 | 3 | 4;
+interface LedgerRootProps extends React.ComponentPropsWithoutRef<"div"> {
+  /**
+   * Make the ledger a size container, so a caller's `@container` rules shed
+   * columns against the *pane* rather than the viewport. Defaults to `true`.
+   *
+   * This is the difference between a list that sheds a column when the window
+   * narrows and one that also sheds it when a detail drawer opens beside it and
+   * takes half the pane — which is the same visual problem and, without a
+   * container, an entirely separate piece of code. Switch it off only when an
+   * ancestor is already the container the rules name; nesting containers moves
+   * which one a bare `@container` query resolves against.
+   */
+  containment?: boolean;
+}
+interface LedgerTierProps extends React.ComponentPropsWithoutRef<"section"> {
+  /**
+   * The tier's name. Omitted, the tier draws no heading and reserves no space
+   * for one — which is how a single unnamed run of rows uses the same component
+   * as a grouped one.
+   */
+  heading?: React.ReactNode;
+  /** How many rows the tier holds, printed beside its name. */
+  count?: number;
+  /**
+   * Dock the heading to the top of the scroll container while the tier's rows
+   * scroll past. Defaults to `true`.
+   */
+  sticky?: boolean;
+  /**
+   * Which heading element the tier's name is. Defaults to `2`.
+   *
+   * The outline is the navigation: a screen-reader user moves through a long
+   * ledger by heading, so the levels have to describe the real nesting of the
+   * page the ledger sits in, not the ledger's own idea of itself.
+   */
+  headingLevel?: LedgerHeadingLevel;
+  /** A qualifier printed after the name — a date, a source, a state. */
+  note?: React.ReactNode;
+}
+interface LedgerGroupProps extends React.ComponentPropsWithoutRef<"div"> {
+  /**
+   * The group's slug, printed in the left gutter.
+   *
+   * Omitted, the group is a plain block: no gutter, no heading, no indent. A
+   * grouped list that has one unnamed run in it should not pay a 7rem empty
+   * column for it, and an empty gutter reads as a missing label rather than as
+   * an absent one.
+   */
+  label?: React.ReactNode;
+  /** Which heading element the slug is. Defaults to `3`. */
+  headingLevel?: 3 | 4;
+  /**
+   * Dock the slug under the tier heading while the group's rows scroll past.
+   * Defaults to `true`.
+   *
+   * The offset is a custom property, `--cue-ledger-slug-top` (default `2.5rem`):
+   * how far down the slug docks depends on how tall the tier heading above it
+   * renders, which is a function of the density and the type the *caller*
+   * configured. Set it on the ledger — `className="[--cue-ledger-slug-top:2rem]"` —
+   * rather than measuring at runtime.
+   */
+  sticky?: boolean;
+}
+interface LedgerEmptyProps extends React.ComponentPropsWithoutRef<"p"> {}
+/**
+ * A grouped run of dense rows under sticky headings: the ledger idiom.
+ *
+ * The flattest of the three surfaces this package ships over one row model, and
+ * the one that does the least: headings, slugs, rows. **Nothing here collapses.**
+ * A ledger with a disclosure on it would be a tree with worse semantics, so the
+ * component emits no `aria-expanded` anywhere, and a test holds it to that —
+ * collapse belongs to `DataTree`, and grouping-with-columns belongs to a
+ * grouped `Table`.
+ *
+ * What it does own is the document outline. Tiers and groups are real `<h2>` /
+ * `<h3>` elements at caller-chosen levels, because in a list of two hundred
+ * rows the heading list *is* how a screen-reader user navigates.
+ *
+ * Static markup — no `"use client"`. The rows inside it may be anything;
+ * `DataRow` is the intended tenant.
+ *
+ * @example
+ * <Ledger.Root className="[--cue-data-row-cols:1fr_8rem_auto]">
+ *   <Ledger.Tier heading="Ours" count={12}>
+ *     <Ledger.Group label="released">
+ *       <DataRow.Root interactive onActivate={open}>…</DataRow.Root>
+ *     </Ledger.Group>
+ *     <Ledger.Group label="lab">
+ *       <Ledger.Empty>Nothing yet.</Ledger.Empty>
+ *     </Ledger.Group>
+ *   </Ledger.Tier>
+ * </Ledger.Root>
+ */
+declare const Ledger: {
+  Root: React.ForwardRefExoticComponent<LedgerRootProps & React.RefAttributes<HTMLDivElement>>;
+  Tier: React.ForwardRefExoticComponent<LedgerTierProps & React.RefAttributes<HTMLElement>>;
+  Group: React.ForwardRefExoticComponent<LedgerGroupProps & React.RefAttributes<HTMLDivElement>>;
+  Empty: React.ForwardRefExoticComponent<LedgerEmptyProps & React.RefAttributes<HTMLParagraphElement>>;
+};
+//#endregion
+export { Ledger, LedgerEmptyProps, LedgerGroupProps, LedgerRootProps, LedgerTierProps };

package/dist/instruments/ledger.js

@@ -0,0 +1,114 @@
+import { cn } from "../lib/cn.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/ledger.tsx
+/**
+* The one type treatment every heading in the ledger wears: the mono uppercase
+* label of `SectionHeader`, `Eyebrow` and `Table.Head`.
+*
+* Declared once here rather than per heading level so a tier and a group slug
+* can never drift into two label styles; `font-normal` is the part that has to
+* be said out loud, because `<h2>` and `<h3>` come bold by default and a bold
+* micro-label in a dense list reads as a second kind of emphasis.
+*/
+const LEDGER_LABEL = "font-mono text-(length:--cue-text-label) font-normal tracking-[0.15em] text-fg-subtle uppercase";
+/** `headingLevel` as a tag name, so the outline is real elements, not roles. */
+const headingTag = (level) => level === 2 ? "h2" : level === 3 ? "h3" : "h4";
+/**
+* A grouped run of dense rows under sticky headings: the ledger idiom.
+*
+* The flattest of the three surfaces this package ships over one row model, and
+* the one that does the least: headings, slugs, rows. **Nothing here collapses.**
+* A ledger with a disclosure on it would be a tree with worse semantics, so the
+* component emits no `aria-expanded` anywhere, and a test holds it to that —
+* collapse belongs to `DataTree`, and grouping-with-columns belongs to a
+* grouped `Table`.
+*
+* What it does own is the document outline. Tiers and groups are real `<h2>` /
+* `<h3>` elements at caller-chosen levels, because in a list of two hundred
+* rows the heading list *is* how a screen-reader user navigates.
+*
+* Static markup — no `"use client"`. The rows inside it may be anything;
+* `DataRow` is the intended tenant.
+*
+* @example
+* <Ledger.Root className="[--cue-data-row-cols:1fr_8rem_auto]">
+*   <Ledger.Tier heading="Ours" count={12}>
+*     <Ledger.Group label="released">
+*       <DataRow.Root interactive onActivate={open}>…</DataRow.Root>
+*     </Ledger.Group>
+*     <Ledger.Group label="lab">
+*       <Ledger.Empty>Nothing yet.</Ledger.Empty>
+*     </Ledger.Group>
+*   </Ledger.Tier>
+* </Ledger.Root>
+*/
+const Ledger = {
+	Root: React.forwardRef(function LedgerRoot({ className, containment = true, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("div", {
+			ref,
+			"data-slot": "ledger",
+			className: cn("flex flex-col font-mono text-(length:--cue-text-ui) text-fg", containment ? "[container-type:inline-size]" : null, className),
+			...elementProps
+		});
+	}),
+	Tier: React.forwardRef(function LedgerTier({ className, heading, count, sticky = true, headingLevel = 2, note, children, ...elementProps }, ref) {
+		const Heading = headingTag(headingLevel);
+		return /* @__PURE__ */ jsxs("section", {
+			ref,
+			"data-slot": "ledger-tier",
+			className: cn("flex flex-col", className),
+			...elementProps,
+			children: [heading === void 0 ? null : /* @__PURE__ */ jsxs(Heading, {
+				"data-slot": "ledger-tier-heading",
+				className: cn(LEDGER_LABEL, "flex items-baseline gap-(--cue-space-2) py-(--cue-pad-row-y)", sticky ? "sticky top-0 z-2 bg-bg" : null),
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						"data-slot": "ledger-tier-label",
+						children: heading
+					}),
+					count === void 0 ? null : /* @__PURE__ */ jsx("span", {
+						"data-slot": "ledger-tier-count",
+						className: "tabular-nums",
+						children: count
+					}),
+					note === void 0 ? null : /* @__PURE__ */ jsx("span", {
+						"data-slot": "ledger-tier-note",
+						className: "tracking-normal normal-case",
+						children: note
+					})
+				]
+			}), children]
+		});
+	}),
+	Group: React.forwardRef(function LedgerGroup({ className, label, headingLevel = 3, sticky = true, children, ...elementProps }, ref) {
+		const Heading = headingTag(headingLevel);
+		const labelled = label !== void 0;
+		return /* @__PURE__ */ jsx("div", {
+			ref,
+			"data-slot": "ledger-group",
+			"data-labelled": labelled ? "" : void 0,
+			className: cn(labelled ? "grid [grid-template-columns:var(--cue-ledger-gutter,7rem)_minmax(0,1fr)]" : "flex flex-col", className),
+			...elementProps,
+			children: labelled ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
+				"data-slot": "ledger-group-label",
+				className: cn(LEDGER_LABEL, "min-w-0 truncate py-(--cue-pad-row-y) pr-(--cue-space-3)", sticky ? "sticky self-start [top:var(--cue-ledger-slug-top,2.5rem)] bg-bg" : null),
+				children: label
+			}), /* @__PURE__ */ jsx("div", {
+				"data-slot": "ledger-group-rows",
+				className: "flex min-w-0 flex-col",
+				children
+			})] }) : children
+		});
+	}),
+	Empty: React.forwardRef(function LedgerEmpty({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("p", {
+			ref,
+			"data-slot": "ledger-empty",
+			className: cn("px-(--cue-pad-row-x) py-(--cue-pad-row-y) font-mono text-(length:--cue-text-ui) text-fg-subtle", className),
+			...elementProps
+		});
+	})
+};
+//#endregion
+export { Ledger };

package/dist/instruments/table.d.ts

@@ -14,10 +14,69 @@ interface TableScrollRegionProps extends Omit<React.ComponentPropsWithoutRef<"di
 declare const TableScrollRegion: React.ForwardRefExoticComponent<TableScrollRegionProps & React.RefAttributes<HTMLDivElement>>;
 interface TableRootProps extends React.ComponentPropsWithoutRef<"table"> {}
 interface TableSectionProps extends React.ComponentPropsWithoutRef<"tbody"> {}
-interface TableRowProps extends React.ComponentPropsWithoutRef<"tr"> {}
+interface TableRowProps extends React.ComponentPropsWithoutRef<"tr"> {
+  /**
+   * The row responds to a pointer: the row-hover wash and a pointer cursor
+   * across the whole row. Defaults to `false`.
+   *
+   * Opt-in rather than automatic, because a table of figures nobody can click
+   * that lit up under the pointer would be promising an interaction it does not
+   * have. Wiring the row up to actually do something — a click handler, a
+   * keyboard path to the same thing — stays the caller's job; this is the paint.
+   */
+  interactive?: boolean;
+  /**
+   * Draw the row as picked out of the table. Defaults to `false`.
+   *
+   * Sets `data-selected`, which is what the tint and the hover-revealed
+   * `DataRow.Actions` inside the row both key off — so a hand-written
+   * `<tr data-selected>` in a data-driven body gets exactly the same treatment.
+   */
+  selected?: boolean;
+}
 interface TableHeadProps extends React.ComponentPropsWithoutRef<"th"> {
   /** Right-align this column and set it in tabular figures. */
   numeric?: boolean;
+  /**
+   * Dock the header band to the top of the scroll container while the rows
+   * scroll under it. Defaults to `false`.
+   *
+   * Set it on the cells, not on the `<tr>`: sticky on a table row is honoured
+   * inconsistently across engines, and the cell is the reliable baseline
+   * everywhere.
+   */
+  sticky?: boolean;
+}
+interface TableGroupRowProps extends Omit<React.ComponentPropsWithoutRef<"tr">, "children"> {
+  /**
+   * How many columns the divider spans. Required: it must equal the table's
+   * column count, or the group's cell stops covering the row and the columns
+   * below it shift by one.
+   */
+  span: number;
+  /** What the group is called. */
+  label: React.ReactNode;
+  /** How many rows the group holds, printed beside its name. */
+  count?: number;
+  /**
+   * Dock the divider under the header band while the group's rows scroll past.
+   * Defaults to `false`.
+   *
+   * The offset is the custom property `--cue-table-group-top` (default `0`):
+   * how far down the divider docks is the rendered height of the sticky header
+   * above it, which depends on the density and type the caller configured. Set
+   * it on the table — `className="[--cue-table-group-top:2rem]"` — rather than
+   * measuring at runtime.
+   */
+  sticky?: boolean;
+  /**
+   * Classes for the divider's *cell*, not its row.
+   *
+   * The `<tr>` paints nothing — the ground, the type and the sticky offset all
+   * live on the `<th>` that spans it, and a background on the row would sit
+   * behind the cell's own. Every other prop, and the ref, go to the row.
+   */
+  className?: string;
 }
 interface TableCellProps extends React.ComponentPropsWithoutRef<"td"> {
   /** Right-align this cell and set it in tabular figures. */
@@ -35,6 +94,14 @@ interface TableCaptionProps extends React.ComponentPropsWithoutRef<"caption"> {}
  * Static markup — no `"use client"`. Compose it with `Panel` for the rim.
  * Use {@link TableScrollRegion} only when the table can exceed its container.
  *
+ * For a grouped list, the table stays *one* table: `Table.Head sticky` docks the
+ * column names, and one `Table.Body` per group opens with a `Table.GroupRow`
+ * divider — so the columns are named once and scan straight through every group
+ * boundary. Rows may hold `DataRow` slots, and `DataRow.Actions` reveals inside
+ * a cell on hover and on selection exactly as it does in a `Ledger` row — on
+ * focus too, once the row holds something focusable outside the track, which a
+ * `<tr>` never is by itself. See {@link TableRowProps.interactive}.
+ *
  * @example
  * <Table.Root>
  *   <Table.Header>
@@ -56,9 +123,10 @@ declare const Table: {
   Header: React.ForwardRefExoticComponent<TableSectionProps & React.RefAttributes<HTMLTableSectionElement>>;
   Body: React.ForwardRefExoticComponent<TableSectionProps & React.RefAttributes<HTMLTableSectionElement>>;
   Row: React.ForwardRefExoticComponent<TableRowProps & React.RefAttributes<HTMLTableRowElement>>;
+  GroupRow: React.ForwardRefExoticComponent<TableGroupRowProps & React.RefAttributes<HTMLTableRowElement>>;
   Head: React.ForwardRefExoticComponent<TableHeadProps & React.RefAttributes<HTMLTableCellElement>>;
   Cell: React.ForwardRefExoticComponent<TableCellProps & React.RefAttributes<HTMLTableCellElement>>;
   Caption: React.ForwardRefExoticComponent<TableCaptionProps & React.RefAttributes<HTMLTableCaptionElement>>;
 };
 //#endregion
-export { Table, TableCaptionProps, TableCellProps, TableHeadProps, TableRootProps, TableRowProps, TableScrollRegion, TableScrollRegionProps, TableSectionProps };
+export { Table, TableCaptionProps, TableCellProps, TableGroupRowProps, TableHeadProps, TableRootProps, TableRowProps, TableScrollRegion, TableScrollRegionProps, TableSectionProps };