@cueplusplus/ui 0.5.0 → 0.7.0

package/dist/instruments/data-tree.d.ts

@@ -0,0 +1,126 @@
+import * as React from "react";
+//#region src/instruments/data-tree.d.ts
+/** What a row knows about itself when its content is a function. */
+interface DataTreeRowState {
+  /** Depth from the roots; `0` for a root. */
+  level: number;
+  /** Whether the node declares children at all. */
+  hasChildren: boolean;
+  /** Whether those children are currently shown. */
+  expanded: boolean;
+  /** Whether this row is the selected one. */
+  selected: boolean;
+}
+/** One node of the tree: an identity, a row's worth of content, and children. */
+interface DataTreeItem {
+  /** Stable identity: what selection, expansion and focus are keyed on. */
+  id: string;
+  /**
+   * The row's content — normally `DataRow` slots, in the same order and with
+   * the same tracks as the other idioms drawing this dataset.
+   *
+   * A function receives the row's own state, for the cases where the content
+   * differs by it: a count that only shows while a node is folded, a different
+   * marker for an expanded parent.
+   */
+  row: React.ReactNode | ((state: DataTreeRowState) => React.ReactNode);
+  /**
+   * Nested nodes. An empty array still makes the row a parent — an empty folder
+   * is a folder, and `aria-expanded` on it is the truth.
+   */
+  children?: readonly DataTreeItem[];
+  /** Grey the row out; it stays reachable by keyboard but cannot be selected. */
+  disabled?: boolean;
+}
+interface DataTreeProps extends Omit<React.ComponentPropsWithoutRef<"div">, "onSelect"> {
+  /** The roots, in display order. */
+  items: readonly DataTreeItem[];
+  /** Expanded ids when controlled. Pass with `onExpandedChange`. */
+  expanded?: readonly string[];
+  /** Initially expanded ids when uncontrolled. */
+  defaultExpanded?: readonly string[];
+  /** Called with the whole next expanded set whenever a row is folded or unfolded. */
+  onExpandedChange?: (expanded: string[]) => void;
+  /** Selected id when controlled. Pass with `onSelect`. */
+  selected?: string | null;
+  /** Initially selected id when uncontrolled. */
+  defaultSelected?: string | null;
+  /** Called with the id of the row the user selected. */
+  onSelect?: (id: string) => void;
+  /**
+   * Draw the depth guides. Defaults to `true`.
+   *
+   * Roots never draw one — there is no ancestor to draw — so a flat tree draws
+   * none at all whatever this is set to.
+   */
+  guides?: boolean;
+  /** Accessible name for the tree. Required in practice — name what it lists. */
+  "aria-label"?: string;
+}
+/**
+ * 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]"
+ * />
+ */
+declare const DataTree: React.ForwardRefExoticComponent<DataTreeProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { DataTree, DataTreeItem, DataTreeProps, DataTreeRowState };

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,17 @@
+import { activateRowFromClick, activateRowFromKeyDown } from "./_data-row.js";
 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, activateRowFromClick, activateRowFromKeyDown };

package/dist/instruments/index.js

@@ -1,6 +1,10 @@
+import { activateRowFromClick, activateRowFromKeyDown } from "./_data-row.js";
 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 +14,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, activateRowFromClick, activateRowFromKeyDown };

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 };