@cueplusplus/ui 0.13.0

package/dist/index.js

@@ -0,0 +1,124 @@
+import { CueLogotype } from "./brand/cue-logotype.js";
+import { CueMark } from "./brand/cue-mark.js";
+import { Plussie } from "./brand/plussie.js";
+import { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, agentColor, agentColorStyle } from "./chat/agent-color.js";
+import { AgentPile } from "./chat/agent-pile.js";
+import { Checkbox, CheckboxGroup } from "./forms/checkbox.js";
+import { bareControlClasses, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants } from "./forms/_chassis.js";
+import { InputGroup } from "./forms/input-group.js";
+import { Input } from "./forms/input.js";
+import { NumberField } from "./forms/number-field.js";
+import { Radio, RadioGroup } from "./forms/radio-group.js";
+import { Button, buttonVariants } from "./primitives/button.js";
+import { Chip, chipVariants } from "./primitives/chip.js";
+import { AskBox } from "./chat/ask-box.js";
+import { Composer } from "./chat/composer.js";
+import { Spinner } from "./primitives/spinner.js";
+import { DelegationCard } from "./chat/delegation-card.js";
+import { Message } from "./chat/message.js";
+import { MessageList } from "./chat/message-list.js";
+import { TAB_FADE_PX, computeScrollEdges, edgeFadeMask } from "./chrome/_tabs-scroll.js";
+import { TREE_GUIDE_GLYPHS, flattenTree } from "./chrome/_tree.js";
+import { Link, linkVariants } from "./layout/link.js";
+import { Separator } from "./primitives/separator.js";
+import { AppBar } from "./chrome/app-bar.js";
+import { Sidebar, useSidebar } from "./layout/sidebar.js";
+import { Density } from "./system/density.js";
+import { isSafeTokenValue } from "./system/overrides.js";
+import { DEFAULT_STORAGE_KEY, prepaintScript } from "./system/prepaint.js";
+import { useDensities, useFonts, useThemes } from "./system/theme-registry.js";
+import { ThemeProvider } from "./system/theme-provider.js";
+import { CuePortalFrame, useCuePortalProps } from "./system/portal.js";
+import { OVERLAY_SIDE_OFFSET, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, scrimClasses } from "./overlays/_surface.js";
+import { Drawer } from "./overlays/drawer.js";
+import { IconButton } from "./primitives/icon-button.js";
+import { AppShell } from "./chrome/app-shell.js";
+import { Container } from "./layout/container.js";
+import { Band } from "./chrome/band.js";
+import { EmptyState } from "./chrome/empty-state.js";
+import { Eyebrow } from "./chrome/eyebrow.js";
+import { Footer } from "./chrome/footer.js";
+import { SectionHeader } from "./chrome/section-header.js";
+import { Inspector } from "./chrome/inspector.js";
+import { NavigationMenu } from "./chrome/navigation-menu.js";
+import { PageShell } from "./chrome/page-shell.js";
+import { Panel, PanelHeader } from "./chrome/panel.js";
+import { Row, SeamList, rowVariants } from "./chrome/row.js";
+import { ScrollArea } from "./chrome/scroll-area.js";
+import { SegmentedControl } from "./chrome/segmented-control.js";
+import { StatusBar } from "./chrome/status-bar.js";
+import { ScrollableTabsList, Tabs } from "./chrome/tabs.js";
+import { TitleBar } from "./chrome/title-bar.js";
+import { Tree, TreeVisibilityToggle } from "./chrome/tree.js";
+import { Toolbar } from "./chrome/toolbar.js";
+import { Autocomplete } from "./forms/autocomplete.js";
+import { ButtonGroup } from "./forms/button-group.js";
+import { Combobox } from "./forms/combobox.js";
+import { PasswordInput } from "./forms/password-input.js";
+import { EnvVarInput, envReference, parseEnvReference } from "./forms/env-var-input.js";
+import { Field, FieldDescription, FieldError, FieldLabel } from "./forms/field.js";
+import { FileUpload, partitionFiles } from "./forms/file-upload.js";
+import { MultiSelect } from "./forms/multi-select.js";
+import { OTPField } from "./forms/otp-field.js";
+import { Rating } from "./forms/rating.js";
+import { ScrubInput } from "./forms/scrub-input.js";
+import { SearchInput } from "./forms/search-input.js";
+import { Select } from "./forms/select.js";
+import { Slider } from "./forms/slider.js";
+import { Switch } from "./forms/switch.js";
+import { TagsInput } from "./forms/tags-input.js";
+import { Textarea } from "./forms/textarea.js";
+import { ToggleGroup } from "./forms/toggle-group.js";
+import { Toggle } from "./forms/toggle.js";
+import { AudienceIcon, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, CliToolIcon, FolderIcon, McpServerIcon, SkillIcon, StackIcon, StacksMatrixIcon } from "./icons/containers.js";
+import { activateRowFromClick, activateRowFromKeyDown } from "./instruments/_data-row.js";
+import { AppWindowFrame } from "./instruments/app-window-frame.js";
+import { CopyButton } from "./instruments/copy-button.js";
+import { CodeBlock } from "./instruments/code-block.js";
+import { DataRow } from "./instruments/data-row.js";
+import { DataTree } from "./instruments/data-tree.js";
+import { GroupBar } from "./instruments/group-bar.js";
+import { Ledger } from "./instruments/ledger.js";
+import { Meter } from "./instruments/meter.js";
+import { Progress } from "./instruments/progress.js";
+import { SeamCell, SeamGrid } from "./instruments/seam-grid.js";
+import { Sparkline } from "./instruments/sparkline.js";
+import { Stat } from "./instruments/stat.js";
+import { Table, TableScrollRegion } from "./instruments/table.js";
+import { TerminalFrame } from "./instruments/terminal-frame.js";
+import { TwoStepButton } from "./instruments/two-step-button.js";
+import { UsageChart } from "./instruments/usage-chart.js";
+import { Accordion } from "./layout/accordion.js";
+import { Stack } from "./layout/stack.js";
+import { Bento } from "./layout/bento.js";
+import { Breadcrumb } from "./layout/breadcrumb.js";
+import { Card } from "./layout/card.js";
+import { Collapsible, Disclosure } from "./layout/collapsible.js";
+import { DescriptionList } from "./layout/description-list.js";
+import { Frames } from "./layout/frames.js";
+import { Grid } from "./layout/grid.js";
+import { Item, itemVariants } from "./layout/item.js";
+import { Pagination, paginationRange } from "./layout/pagination.js";
+import { Preview } from "./layout/preview.js";
+import { Stepper } from "./layout/stepper.js";
+import { StatusDot } from "./primitives/status-dot.js";
+import { Timeline } from "./layout/timeline.js";
+import { AlertDialog } from "./overlays/alert-dialog.js";
+import { CommandPalette } from "./overlays/command-palette.js";
+import { DropdownMenu } from "./overlays/dropdown-menu.js";
+import { ContextMenu } from "./overlays/context-menu.js";
+import { Dialog } from "./overlays/dialog.js";
+import { HoverCard } from "./overlays/hover-card.js";
+import { Tooltip } from "./overlays/tooltip.js";
+import { InfoTip } from "./overlays/info-tip.js";
+import { Menubar } from "./overlays/menubar.js";
+import { Popover } from "./overlays/popover.js";
+import { Sheet } from "./overlays/sheet.js";
+import { Toast, useToast } from "./overlays/toast.js";
+import { Avatar, AvatarGroup } from "./primitives/avatar.js";
+import { Kbd } from "./primitives/kbd.js";
+import { Skeleton } from "./primitives/skeleton.js";
+import { useControlHeight, useDensity } from "./system/use-density.js";
+import { useTheme } from "./system/use-theme.js";
+import { DEFAULT_STYLE_SET, STYLE_SETS } from "./system/index.js";
+export { AGENT_COLOR_PROPERTY, AGENT_HUES, AGENT_ROOT_COLOR, Accordion, AgentPile, AlertDialog, AppBar, AppShell, AppWindowFrame, AskBox, AudienceIcon, Autocomplete, Avatar, AvatarGroup, Band, Bento, Breadcrumb, Button, ButtonGroup, Card, CatalogueIcon, ChannelBetaIcon, ChannelReleasedIcon, Checkbox, CheckboxGroup, Chip, CliToolIcon, CodeBlock, Collapsible, Combobox, CommandPalette, Composer, Container, ContextMenu, CopyButton, CueLogotype, CueMark, CuePortalFrame, DEFAULT_STORAGE_KEY, DEFAULT_STYLE_SET, DataRow, DataTree, DelegationCard, Density, DescriptionList, Dialog, Disclosure, Drawer, DropdownMenu, EmptyState, EnvVarInput, Eyebrow, Field, FieldDescription, FieldError, FieldLabel, FileUpload, FolderIcon, Footer, Frames, Grid, GroupBar, HoverCard, IconButton, InfoTip, Input, InputGroup, Inspector, Item, Kbd, Ledger, Link, McpServerIcon, Menubar, Message, MessageList, Meter, MultiSelect, NavigationMenu, NumberField, OTPField, OVERLAY_SIDE_OFFSET, PageShell, Pagination, Panel, PanelHeader, PasswordInput, Plussie, Popover, Preview, Progress, Radio, RadioGroup, Rating, Row, STYLE_SETS, ScrollArea, ScrollableTabsList, ScrubInput, SeamCell, SeamGrid, SeamList, SearchInput, SectionHeader, SegmentedControl, Select, Separator, Sheet, Sidebar, Skeleton, SkillIcon, Slider, Sparkline, Spinner, Stack, StackIcon, StacksMatrixIcon, Stat, StatusBar, StatusDot, Stepper, Switch, TAB_FADE_PX, TREE_GUIDE_GLYPHS, Table, TableScrollRegion, Tabs, TagsInput, TerminalFrame, Textarea, ThemeProvider, Timeline, TitleBar, Toast, Toggle, ToggleGroup, Toolbar, Tooltip, Tree, TreeVisibilityToggle, TwoStepButton, UsageChart, activateRowFromClick, activateRowFromKeyDown, agentColor, agentColorStyle, bareControlClasses, buttonVariants, chipVariants, computeScrollEdges, controlClasses, controlGroupFocusClasses, controlSurface, controlVariants, edgeFadeMask, envReference, flattenTree, isSafeTokenValue, itemVariants, linkVariants, menuItemClasses, menuLabelClasses, menuPopupClasses, menuSeparatorClasses, overlayDescriptionClasses, overlayFooterClasses, overlayModalTransitionClasses, overlayPopupTransitionClasses, overlayPositionerClasses, overlaySurfaceClasses, overlayTextClasses, overlayTitleClasses, paginationRange, parseEnvReference, partitionFiles, prepaintScript, rowVariants, scrimClasses, useControlHeight, useCuePortalProps, useDensities, useDensity, useFonts, useSidebar, useTheme, useThemes, useToast };

package/dist/instruments/_ansi.js

@@ -0,0 +1,116 @@
+import Anser from "anser";
+//#region src/instruments/_ansi.ts
+/**
+* The eight ANSI hues on the system's tokens.
+*
+* `blue` and `cyan` share `info`, and `magenta` borrows `accent`: the palette
+* has one cool status colour and no sixth hue, and inventing two more would put
+* colours on screen that no theme controls. Bright variants resolve to the same
+* token — brightness in a terminal is an intensity, and intensity here is the
+* `bold` flag.
+*/
+const NAMED_COLORS = {
+	black: "var(--cue-fg-subtle)",
+	red: "var(--cue-danger)",
+	green: "var(--cue-ok)",
+	yellow: "var(--cue-warn)",
+	blue: "var(--cue-info)",
+	magenta: "var(--cue-accent)",
+	cyan: "var(--cue-info)",
+	white: "var(--cue-fg)",
+	"bright-black": "var(--cue-fg-muted)",
+	"bright-red": "var(--cue-danger)",
+	"bright-green": "var(--cue-ok)",
+	"bright-yellow": "var(--cue-warn)",
+	"bright-blue": "var(--cue-info)",
+	"bright-magenta": "var(--cue-accent)",
+	"bright-cyan": "var(--cue-info)",
+	"bright-white": "var(--cue-fg)"
+};
+/** The 256-colour palette's first sixteen slots, in index order. */
+const PALETTE_NAMES = [
+	"black",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"magenta",
+	"cyan",
+	"white",
+	"bright-black",
+	"bright-red",
+	"bright-green",
+	"bright-yellow",
+	"bright-blue",
+	"bright-magenta",
+	"bright-cyan",
+	"bright-white"
+];
+/** The six levels each channel of the 6×6×6 cube can take. */
+const CUBE_LEVELS = [
+	0,
+	95,
+	135,
+	175,
+	215,
+	255
+];
+/** Resolve one of anser's class names into a CSS colour. */
+function resolveColor(name, truecolor) {
+	if (name === null) return void 0;
+	if (name === "ansi-truecolor") return truecolor === null ? void 0 : `rgb(${truecolor})`;
+	const palette = /^ansi-palette-(\d+)$/.exec(name);
+	if (palette !== null) {
+		const index = Number(palette[1]);
+		if (index < 16) return NAMED_COLORS[PALETTE_NAMES[index]];
+		if (index > 255) return void 0;
+		if (index >= 232) {
+			const level = 8 + (index - 232) * 10;
+			return `rgb(${level}, ${level}, ${level})`;
+		}
+		const offset = index - 16;
+		return `rgb(${CUBE_LEVELS[Math.floor(offset / 36)]}, ${CUBE_LEVELS[Math.floor(offset / 6) % 6]}, ${CUBE_LEVELS[offset % 6]})`;
+	}
+	return NAMED_COLORS[name.replace(/^ansi-/, "")];
+}
+/**
+* Parse one line of terminal output into styled spans.
+*
+* Always returns at least one span — an empty line still needs a row of the
+* right height — and never returns markup.
+*
+* @param text - One line, escape sequences and all.
+* @returns The runs, in order.
+* @example
+* ansiSpans("failed").map((span) => span.color); // ["var(--cue-danger)"]
+*/
+function ansiSpans(text) {
+	const spans = Anser.ansiToJson(text, {
+		use_classes: true,
+		remove_empty: true
+	}).map((entry) => {
+		const decorations = new Set(entry.decorations);
+		return {
+			text: entry.content,
+			color: resolveColor(entry.fg, entry.fg_truecolor),
+			background: resolveColor(entry.bg, entry.bg_truecolor),
+			bold: decorations.has("bold"),
+			dim: decorations.has("dim"),
+			italic: decorations.has("italic"),
+			underline: decorations.has("underline"),
+			strikethrough: decorations.has("strikethrough")
+		};
+	});
+	return spans.length > 0 ? spans : [{
+		text: "",
+		color: void 0,
+		background: void 0,
+		bold: false,
+		dim: false,
+		italic: false,
+		underline: false,
+		strikethrough: false
+	}];
+}
+//#endregion
+export { ansiSpans };

package/dist/instruments/_data-row.d.ts

@@ -0,0 +1,68 @@
+import "../lib/cva.js";
+import * as React from "react";
+//#region src/instruments/_data-row.d.ts
+/**
+ * Whether a click on a row means "open this row", and act on it if it does.
+ *
+ * Exported because more surfaces need this reading than ship a `DataRow.Root`:
+ * `Table.Row` documents activation as the caller's job, and a console that draws
+ * its list as a `<tr>` in one view and a `DataRow.Root` in another would
+ * otherwise run two implementations of one decision — which is how the table
+ * view quietly loses modifier-click on the row's link while the ledger view
+ * keeps it. `DataRow.Root` calls this exact function; so should you.
+ *
+ * Four cases a naive `onClick={open}` gets wrong, and this is the whole reason
+ * the row is not simply a `<button>`:
+ *
+ * - **A control inside the row.** The action cluster, a menu trigger, a
+ *   checkbox — pressing one is not the same gesture as picking the row. Anything
+ *   under a `[data-stop]` ancestor is left entirely alone, which is why
+ *   `DataRow.Actions` stamps that attribute on itself.
+ * - **A link inside the row.** A plain click on it should open the row's own
+ *   surface (the drawer, the detail pane), so the anchor's navigation is
+ *   suppressed — but ⌘/Ctrl/Shift/Alt-click must still open a tab, which is the
+ *   whole value of having shipped a real `<a href>` in the first place.
+ * - **A secondary button.** Only the primary button activates; the middle
+ *   button belongs to the browser.
+ * - **An already-handled event.** A caller's own `onClick` that called
+ *   `preventDefault()` has said no.
+ *
+ * @param event The row's own click event.
+ * @param activate What "open this row" means to the surface.
+ * @example
+ * onClick={(event) => activateRowFromClick(event, () => open(row))}
+ * @example
+ * // The same decision on a table row, which owns its activation itself.
+ * <Table.Row
+ *   interactive
+ *   tabIndex={0}
+ *   onClick={(event) => activateRowFromClick(event, () => open(device))}
+ *   onKeyDown={(event) => activateRowFromKeyDown(event, () => open(device))}
+ * >
+ */
+declare function activateRowFromClick(event: React.MouseEvent<HTMLElement>, activate: () => void): void;
+/**
+ * Whether a key press on a row means "open this row", and act on it if it does.
+ *
+ * The other half of {@link activateRowFromClick}, and not optional: a row that
+ * opens on click and not on Enter is reachable by pointer only. It fires only
+ * when the row itself has focus, so the element it is attached to needs a
+ * `tabIndex` — a `<div>` and a `<tr>` are both unfocusable by default, and this
+ * handler on an unfocusable row is dead code.
+ *
+ * Guarded on `event.target === event.currentTarget` so a control inside the row
+ * keeps its own keys: without it a rename field on a row could never contain a
+ * space, and every action button's Enter would also open the row behind it.
+ *
+ * Space is prevented rather than merely handled, because the browser's default
+ * for Space on a focused non-control is to scroll the page — a row that opened
+ * a drawer *and* jumped the list a screenful would read as a bug.
+ *
+ * @param event The row's own keydown event.
+ * @param activate What "open this row" means to the surface.
+ * @example
+ * onKeyDown={(event) => activateRowFromKeyDown(event, () => open(row))}
+ */
+declare function activateRowFromKeyDown(event: React.KeyboardEvent<HTMLElement>, activate: () => void): void;
+//#endregion
+export { activateRowFromClick, activateRowFromKeyDown };

package/dist/instruments/_data-row.js

@@ -0,0 +1,139 @@
+import { cva } from "../lib/cva.js";
+//#region src/instruments/_data-row.ts
+/**
+* The row recipe, in the three shapes the surfaces need.
+*
+* `layout` — `grid` is the row proper, whose children are its columns; `flex`
+* is the tree row, which puts a disclosure chevron outside the grid so the
+* chevron is not a column the caller has to count (see the column-count rule in
+* {@link DATA_ROW_COLUMNS}).
+*
+* `indent` — the tree's depth step, folded into the row's own left padding
+* rather than applied to an inner wrapper, because the guides
+* ({@link DataTreeProps.guides}) are painted on the row's background box and
+* have to start where the padding does.
+*
+* `interactive` — the row responds to a pointer and to the keyboard. The focus
+* ring is *inset* (`-outline-offset-2`), the same ruling as `Row`: these rows
+* live in clipped panes, where an outset ring on the first or last row is cut
+* off by the pane's own rim. `outline-solid` rides along with every
+* `outline-<n>` in this file because Tailwind v4 leaves `--tw-outline-style`
+* unset otherwise and the ring never paints — `test/focus-ring.test.ts` is what
+* keeps the pair together.
+*
+* The selected tint is in the base rather than in `interactive`: a static row in
+* a selected group still reads as selected, and the attribute is the contract
+* either way. It is declared after the hover wash on purpose — Tailwind emits
+* `data-*` variants after `hover:`, so a selected row keeps its accent tint
+* while the pointer is over it instead of flickering back to the hover grey.
+*
+* @example
+* cn(dataRowVariants({ interactive: true }), className)
+*/
+const dataRowVariants = cva([
+	"group/data-row w-full items-center gap-(--cue-space-3) py-(--cue-pad-row-y)",
+	"font-mono text-(length:--cue-text-ui) text-fg",
+	"border-t border-t-(--cue-hair) first:border-t-0",
+	"data-[selected]:bg-accent-soft data-[disabled]:pointer-events-none data-[disabled]:opacity-40"
+].join(" "), {
+	variants: {
+		layout: {
+			grid: "grid [grid-template-columns:var(--cue-data-row-cols,1fr_auto)]",
+			flex: "flex"
+		},
+		indent: {
+			true: "pr-(--cue-pad-row-x) pl-[calc(var(--cue-pad-row-x)_+_var(--depth)_*_var(--cue-data-tree-indent,1.25rem))]",
+			false: "px-(--cue-pad-row-x)"
+		},
+		interactive: {
+			true: "cursor-pointer outline-none hover:bg-(--cue-row-hover) focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent",
+			false: ""
+		}
+	},
+	defaultVariants: {
+		layout: "grid",
+		indent: false,
+		interactive: false
+	}
+});
+/**
+* Whether a click on a row means "open this row", and act on it if it does.
+*
+* Exported because more surfaces need this reading than ship a `DataRow.Root`:
+* `Table.Row` documents activation as the caller's job, and a console that draws
+* its list as a `<tr>` in one view and a `DataRow.Root` in another would
+* otherwise run two implementations of one decision — which is how the table
+* view quietly loses modifier-click on the row's link while the ledger view
+* keeps it. `DataRow.Root` calls this exact function; so should you.
+*
+* Four cases a naive `onClick={open}` gets wrong, and this is the whole reason
+* the row is not simply a `<button>`:
+*
+* - **A control inside the row.** The action cluster, a menu trigger, a
+*   checkbox — pressing one is not the same gesture as picking the row. Anything
+*   under a `[data-stop]` ancestor is left entirely alone, which is why
+*   `DataRow.Actions` stamps that attribute on itself.
+* - **A link inside the row.** A plain click on it should open the row's own
+*   surface (the drawer, the detail pane), so the anchor's navigation is
+*   suppressed — but ⌘/Ctrl/Shift/Alt-click must still open a tab, which is the
+*   whole value of having shipped a real `<a href>` in the first place.
+* - **A secondary button.** Only the primary button activates; the middle
+*   button belongs to the browser.
+* - **An already-handled event.** A caller's own `onClick` that called
+*   `preventDefault()` has said no.
+*
+* @param event The row's own click event.
+* @param activate What "open this row" means to the surface.
+* @example
+* onClick={(event) => activateRowFromClick(event, () => open(row))}
+* @example
+* // The same decision on a table row, which owns its activation itself.
+* <Table.Row
+*   interactive
+*   tabIndex={0}
+*   onClick={(event) => activateRowFromClick(event, () => open(device))}
+*   onKeyDown={(event) => activateRowFromKeyDown(event, () => open(device))}
+* >
+*/
+function activateRowFromClick(event, activate) {
+	if (event.defaultPrevented || event.button !== 0) return;
+	const target = event.target;
+	if (target === null) return;
+	if (target.closest("[data-stop]") !== null) return;
+	if (target.closest("a[href]") !== null) {
+		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+		event.preventDefault();
+	}
+	activate();
+}
+/**
+* Whether a key press on a row means "open this row", and act on it if it does.
+*
+* The other half of {@link activateRowFromClick}, and not optional: a row that
+* opens on click and not on Enter is reachable by pointer only. It fires only
+* when the row itself has focus, so the element it is attached to needs a
+* `tabIndex` — a `<div>` and a `<tr>` are both unfocusable by default, and this
+* handler on an unfocusable row is dead code.
+*
+* Guarded on `event.target === event.currentTarget` so a control inside the row
+* keeps its own keys: without it a rename field on a row could never contain a
+* space, and every action button's Enter would also open the row behind it.
+*
+* Space is prevented rather than merely handled, because the browser's default
+* for Space on a focused non-control is to scroll the page — a row that opened
+* a drawer *and* jumped the list a screenful would read as a bug.
+*
+* @param event The row's own keydown event.
+* @param activate What "open this row" means to the surface.
+* @example
+* onKeyDown={(event) => activateRowFromKeyDown(event, () => open(row))}
+*/
+function activateRowFromKeyDown(event, activate) {
+	if (event.defaultPrevented) return;
+	if (event.target !== event.currentTarget) return;
+	if (event.key !== "Enter" && event.key !== " ") return;
+	event.preventDefault();
+	activate();
+}
+//#endregion
+export { activateRowFromClick, activateRowFromKeyDown, dataRowVariants };

package/dist/instruments/_glyphs.js

@@ -0,0 +1,90 @@
+import "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/_glyphs.tsx
+/**
+* Shared instrument glyphs.
+*
+* Drawn inline for the same reason as `overlays/_glyphs.tsx`: a copy
+* affordance should not put an icon dependency on the render path, and
+* hand-set strokes stay hairline-thin at the 10–12px sizes console density
+* asks for. `currentColor` everywhere — the tone comes from the button.
+*
+* @internal Not part of the public API.
+*/
+/** Two offset sheets: the universal "copy to clipboard" mark. */
+function CopyGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.5",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [/* @__PURE__ */ jsx("rect", {
+			x: "5.5",
+			y: "5.5",
+			width: "8",
+			height: "8",
+			rx: "1.5"
+		}), /* @__PURE__ */ jsx("path", { d: "M10.5 3.5a1.5 1.5 0 0 0-1.5-1.5H4a1.5 1.5 0 0 0-1.5 1.5V9A1.5 1.5 0 0 0 4 10.5" })]
+	});
+}
+/** The tick that confirms the copy landed. */
+function CheckGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "m3 8.5 3.5 3.5L13 4.5" })
+	});
+}
+/** Shared stroke settings for the four pager chevrons. */
+const CHEVRON = {
+	viewBox: "0 0 16 16",
+	fill: "none",
+	stroke: "currentColor",
+	strokeWidth: "2",
+	strokeLinecap: "round",
+	strokeLinejoin: "round",
+	"aria-hidden": "true"
+};
+/** Previous page. */
+function ChevronLeftGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		...CHEVRON,
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "m10 3-5 5 5 5" })
+	});
+}
+/** Next page. */
+function ChevronRightGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		...CHEVRON,
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "m6 3 5 5-5 5" })
+	});
+}
+/** First page. */
+function ChevronsLeftGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		...CHEVRON,
+		...props,
+		children: [/* @__PURE__ */ jsx("path", { d: "m8 3-5 5 5 5" }), /* @__PURE__ */ jsx("path", { d: "m13 3-5 5 5 5" })]
+	});
+}
+/** Last page. */
+function ChevronsRightGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		...CHEVRON,
+		...props,
+		children: [/* @__PURE__ */ jsx("path", { d: "m3 3 5 5-5 5" }), /* @__PURE__ */ jsx("path", { d: "m8 3 5 5-5 5" })]
+	});
+}
+//#endregion
+export { CheckGlyph, ChevronLeftGlyph, ChevronRightGlyph, ChevronsLeftGlyph, ChevronsRightGlyph, CopyGlyph };

package/dist/instruments/_ledger-disclosure.js

@@ -0,0 +1,103 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { ChevronRightGlyph } from "../chrome/_glyphs.js";
+import { headingTag } from "./_ledger.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/_ledger-disclosure.tsx
+/**
+* A heading that folds the rows beneath it: the accordion pattern, once, for
+* both of the ledger's headings.
+*
+* ## Why the button is inside the heading rather than instead of it
+*
+* This is the disclosure shape the APG calls an accordion, and the one
+* `Table.GroupRow`'s own note already points at — *"a real
+* `<button aria-expanded aria-controls>` inside this cell, never the row
+* itself"*. The heading element survives, so the page's `h2`/`h3` outline is
+* unchanged whether a tier folds or not, and a screen-reader user who navigates
+* a two-hundred-row ledger by heading — which is what the outline is *for* —
+* finds the same places in the same order either way. Making the heading the
+* button, or replacing it with one, would trade that outline for a control, and
+* the outline is the more valuable of the two.
+*
+* The glyph is `aria-hidden`, so the button's accessible name is the heading's
+* own words. A reader hears "Ours, 13, collapsed button", not "button".
+*
+* ## Why the folded rows are hidden rather than unmounted
+*
+* A folded run of rows stays mounted inside a panel that carries `hidden`. The
+* obvious alternative — dropping the children while the run is shut, so that
+* folding something away costs nothing to have folded — is wrong here, and the
+* reason is that **the rows are not always inert**. A `Ledger.Group` inside a
+* tier is itself a disclosure holding its own uncontrolled state: unmount it
+* and that state goes with it, so a reader who folds three groups, folds the
+* tier over them and opens it again finds all three sprung back open. A control
+* that says nothing about touching them had quietly undone their work. React
+* state below a fold is the caller's too, and this component is not entitled to
+* throw it away.
+*
+* Nothing is given up in exchange. A `hidden` subtree is out of the
+* accessibility tree exactly as an absent one is — no heading in it reaches the
+* outline, no row in it answers `getByRole`, and a screen reader walks past all
+* of it — so the two forms are indistinguishable to the reader this component
+* is built for. What differs is only that the caller's state survives.
+*
+* The panel element itself would have to stay in any case: `aria-controls` must
+* name an element that exists, and pointed at a node that leaves with its
+* contents it becomes a dangling reference and an `aria-valid-attr-value`
+* failure — the very trap `DataRowDisclosure.controls` documents.
+*
+* ## Why the folded panel wears no classes at all
+*
+* `hidden` is a UA rule, `[hidden] { display: none }`, and **any author
+* `display` beats it**: a panel that keeps `flex` while it is `hidden` is a
+* panel that is not hidden. Rather than fight that with a `display` utility
+* whose win depends on Tailwind's emission order, the folded panel is given no
+* class list at all, and the layout classes come back when it opens.
+*
+* Keeping the rows mounted is what makes this load-bearing rather than tidy.
+* When the panel was emptied on folding there was nothing inside to leak; now
+* the panel's own `display: none` is the only thing standing between a folded
+* run of rows and a visible one. It is enough — a `display: none` element
+* generates no boxes for any of its descendants, whatever `display` each of
+* them asks for — but it has to actually apply, and jsdom cannot see whether it
+* does, which is why `tests/browser/data-surfaces.spec.ts` reads the computed
+* `display` on both real engines.
+*/
+function LedgerDisclosure({ headingLevel, headingSlot, headingClassName, toggleSlot, toggleClassName, panelSlot, panelClassName, label, expanded: expandedProp, defaultExpanded = true, onExpandedChange, children }) {
+	const [selfExpanded, setSelfExpanded] = React.useState(defaultExpanded);
+	const expanded = expandedProp ?? selfExpanded;
+	const panelId = React.useId();
+	const Heading = headingTag(headingLevel);
+	const toggle = () => {
+		const next = !expanded;
+		if (expandedProp === void 0) setSelfExpanded(next);
+		onExpandedChange?.(next);
+	};
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
+		"data-slot": headingSlot,
+		className: headingClassName,
+		children: /* @__PURE__ */ jsxs("button", {
+			type: "button",
+			"data-slot": toggleSlot,
+			"aria-expanded": expanded,
+			"aria-controls": panelId,
+			onClick: toggle,
+			className: toggleClassName,
+			children: [/* @__PURE__ */ jsx(ChevronRightGlyph, {
+				"aria-hidden": "true",
+				"data-slot": `${toggleSlot}-glyph`,
+				className: cn("size-icon-sm shrink-0 self-center transition-transform duration-150 motion-reduce:transition-none", expanded ? "rotate-90" : null)
+			}), label]
+		})
+	}), /* @__PURE__ */ jsx("div", {
+		id: panelId,
+		"data-slot": panelSlot,
+		hidden: !expanded,
+		className: expanded ? panelClassName : void 0,
+		children
+	})] });
+}
+//#endregion
+export { LedgerDisclosure };

package/dist/instruments/_ledger.d.ts

@@ -0,0 +1,21 @@
+//#region src/instruments/_ledger.d.ts
+/**
+ * The outline half of the ledger, in a module carrying no runtime directive.
+ *
+ * `ledger.tsx` renders on the server and has to keep doing so — a document of
+ * two hundred rows that ships its own JavaScript in order to be *read* is
+ * exactly what the static form exists to avoid — while the disclosure in
+ * `_ledger-disclosure.tsx` holds React state and is therefore `"use client"`.
+ *
+ * A server module may **render** a client one, but it may not **call into** it:
+ * every value imported from a `"use client"` file is a client reference, and
+ * invoking one during a server render throws rather than returning a tag name.
+ * So the two symbols both halves need — what a heading level is, and which
+ * element it names — live here, in a plain module either graph can compile,
+ * instead of being copied into both and drifting the day one of them learns
+ * about `h5`.
+ */
+/** The heading elements a tier or a group may be given. */
+type LedgerHeadingLevel = 2 | 3 | 4;
+//#endregion
+export { LedgerHeadingLevel };