@cueplusplus/ui 0.3.0 → 0.6.0

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

package/dist/instruments/table.js

@@ -1,6 +1,6 @@
 import { cn } from "../lib/cn.js";
 import * as React from "react";
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/instruments/table.tsx
 /**
 * A named horizontal viewport for a table wider than its container.
@@ -20,6 +20,108 @@ const TableScrollRegion = React.forwardRef(function TableScrollRegion({ classNam
 	});
 });
 /**
+* The table frame. Owns the type, the collapse and the numeric alignment rule.
+*
+* `data-numeric` is the contract, not a prop: the alignment and
+* `tabular-nums` live in one descendant selector here, so a hand-written
+* `<td data-numeric>` inside a data-driven body lines up exactly like a
+* `<Table.Cell numeric>`. Figures that do not share a column width are
+* unreadable as a column, which is the whole point of a table.
+*/
+const TableRoot = React.forwardRef(function TableRoot({ className, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("table", {
+		ref,
+		"data-slot": "table",
+		className: cn("w-full border-collapse font-mono text-(length:--cue-text-ui) text-fg", "[&_[data-numeric]]:text-right [&_[data-numeric]]:tabular-nums", className),
+		...elementProps
+	});
+});
+/** The header band. Sticky-able by the caller; sized by the row padding tokens. */
+const TableHeader = React.forwardRef(function TableHeader({ className, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("thead", {
+		ref,
+		"data-slot": "table-header",
+		className,
+		...elementProps
+	});
+});
+/** The data band. */
+const TableBody = React.forwardRef(function TableBody({ className, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("tbody", {
+		ref,
+		"data-slot": "table-body",
+		className,
+		...elementProps
+	});
+});
+/**
+* One row, separated by a hairline underneath — dropped on the last row so the
+* table never draws a rule against the panel rim it sits in. In a `<thead>` the
+* "last row" is the header row itself, so the header's own bottom border (on
+* the cells) is the only rule there and the two can never stack into 2px.
+*
+* Every row carries the `group/data-row` name unconditionally. It paints
+* nothing by itself, and it is what lets a `DataRow.Actions` cluster inside a
+* `Table.Cell` reveal on hover, on focus and on selection with no second
+* implementation of that idiom for the table — the whole point of the three
+* idioms sharing one row anatomy.
+*
+* **The focus half of that reveal is the caller's to supply here.** A `<tr>` is
+* not focusable and this component does not make it one — a tab stop on every
+* row of a long table is a tab stop a keyboard user has to walk past hundreds
+* of times, which is the reason `Ledger` rows opt in individually. So the
+* reveal-on-focus only happens if the row *contains* something focusable
+* outside the hidden track: a link on the row's name, a checkbox in the leading
+* cell, any real control. Without one, `:focus-within` can never fire — content
+* inside a `visibility: hidden` subtree cannot be focused, so the track cannot
+* bootstrap its own reveal — and a hidden action cluster is then reachable by
+* pointer only, which is a WCAG 2.1.1 failure the screen gives no sign of. A
+* table whose only per-row controls live in a hidden track wants either a
+* focusable cell beside it or an always-visible cluster.
+*
+* The selected tint is the row's, not the cell's: a `background` on the `<tr>`
+* shows through every cell in it, so the fill cannot end up ragged where one
+* cell sets a ground of its own.
+*/
+const TableRow = React.forwardRef(function TableRow({ className, interactive = false, selected = false, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("tr", {
+		ref,
+		"data-slot": "table-row",
+		"data-selected": selected ? "" : void 0,
+		className: cn("group/data-row border-b border-border last:border-b-0 data-[selected]:bg-accent-soft", interactive ? "cursor-pointer hover:bg-(--cue-row-hover)" : null, className),
+		...elementProps
+	});
+});
+/**
+* A column heading: the same mono uppercase label as `SectionHeader` and
+* `Eyebrow`, on the raised surface so the band reads as chrome rather than as
+* the first row of data.
+*
+* **Sticky swaps the bottom border for an inset shadow.** `Table.Root` collapses
+* its borders, and a collapsed border belongs to the table's shared grid rather
+* than to the cell — so when a cell detaches to stay at the top of the scroll
+* container, its rule stays behind with the rows and the stuck band appears to
+* lose its edge. An inset `box-shadow` is a paint effect on the cell itself, so
+* it travels with it. The alternative — putting the whole table on
+* `border-separate` — would change the geometry of every table in the library
+* to fix one that scrolls.
+*
+* The opaque `bg-surface-1` is not decoration either: a transparent sticky cell
+* is a sticky cell you read the rows through. A caller who wants the header on
+* the page's own ground can pass `className="bg-bg"` — what it must not pass is
+* nothing.
+*/
+const TableHead = React.forwardRef(function TableHead({ className, numeric = false, sticky = false, scope = "col", ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("th", {
+		ref,
+		scope,
+		"data-slot": "table-head",
+		"data-numeric": numeric ? "" : void 0,
+		className: cn("border-b border-border bg-surface-1 px-(--cue-pad-row-x) py-(--cue-pad-row-y) text-left font-mono text-(length:--cue-text-label) font-normal tracking-[0.15em] whitespace-nowrap text-fg-subtle uppercase", sticky ? "sticky top-0 z-3 border-b-0 shadow-[inset_0_-1px_0_var(--cue-hair-strong)]" : null, className),
+		...elementProps
+	});
+});
+/**
 * The canonical console table: hairlines, mono figures, no zebra striping.
 *
 * Semantic `<table>` markup throughout — a grid of divs loses row/column
@@ -30,6 +132,14 @@ const TableScrollRegion = React.forwardRef(function TableScrollRegion({ classNam
 * 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>
@@ -47,48 +157,32 @@ const TableScrollRegion = React.forwardRef(function TableScrollRegion({ classNam
 * </Table.Root>
 */
 const Table = {
-	Root: React.forwardRef(function TableRoot({ className, ...elementProps }, ref) {
-		return /* @__PURE__ */ jsx("table", {
-			ref,
-			"data-slot": "table",
-			className: cn("w-full border-collapse font-mono text-(length:--cue-text-ui) text-fg", "[&_[data-numeric]]:text-right [&_[data-numeric]]:tabular-nums", className),
-			...elementProps
-		});
-	}),
-	Header: React.forwardRef(function TableHeader({ className, ...elementProps }, ref) {
-		return /* @__PURE__ */ jsx("thead", {
-			ref,
-			"data-slot": "table-header",
-			className,
-			...elementProps
-		});
-	}),
-	Body: React.forwardRef(function TableBody({ className, ...elementProps }, ref) {
-		return /* @__PURE__ */ jsx("tbody", {
-			ref,
-			"data-slot": "table-body",
-			className,
-			...elementProps
-		});
-	}),
-	Row: React.forwardRef(function TableRow({ className, ...elementProps }, ref) {
+	Root: TableRoot,
+	Header: TableHeader,
+	Body: TableBody,
+	Row: TableRow,
+	GroupRow: React.forwardRef(function TableGroupRow({ className, span, label, count, sticky = false, ...elementProps }, ref) {
 		return /* @__PURE__ */ jsx("tr", {
 			ref,
-			"data-slot": "table-row",
-			className: cn("border-b border-border last:border-b-0", className),
-			...elementProps
-		});
-	}),
-	Head: React.forwardRef(function TableHead({ className, numeric = false, scope = "col", ...elementProps }, ref) {
-		return /* @__PURE__ */ jsx("th", {
-			ref,
-			scope,
-			"data-slot": "table-head",
-			"data-numeric": numeric ? "" : void 0,
-			className: cn("border-b border-border bg-surface-1 px-(--cue-pad-row-x) py-(--cue-pad-row-y) text-left font-mono text-(length:--cue-text-label) font-normal tracking-[0.15em] whitespace-nowrap text-fg-subtle uppercase", className),
-			...elementProps
+			"data-slot": "table-group-row",
+			...elementProps,
+			children: /* @__PURE__ */ jsxs("th", {
+				colSpan: span,
+				scope: "rowgroup",
+				"data-slot": "table-group-cell",
+				className: cn("bg-bg px-(--cue-pad-row-x) py-(--cue-pad-row-y) text-left font-mono text-(length:--cue-text-label) font-normal tracking-[0.15em] whitespace-nowrap text-fg-subtle uppercase", sticky ? "sticky z-2 [top:var(--cue-table-group-top,0px)]" : null, className),
+				children: [/* @__PURE__ */ jsx("span", {
+					"data-slot": "table-group-label",
+					children: label
+				}), count === void 0 ? null : /* @__PURE__ */ jsx("span", {
+					"data-slot": "table-group-count",
+					className: "ml-(--cue-space-2) tabular-nums",
+					children: count
+				})]
+			})
 		});
 	}),
+	Head: TableHead,
 	Cell: React.forwardRef(function TableCell({ className, numeric = false, ...elementProps }, ref) {
 		return /* @__PURE__ */ jsx("td", {
 			ref,

package/dist/instruments/two-step-button.js

@@ -7,14 +7,33 @@ import { jsx, jsxs } from "react/jsx-runtime";
 /**
 * The armed confirm button's fill.
 *
-* The ink is a literal rather than a token because there is no `--cue-warn-fg`
-* or `--cue-danger-fg` in the palette — the same pragmatism as `Button`'s
-* `danger` variant, which is also `text-white`. Every theme's `warn` is an
-* amber and every theme's `danger` is a red, so the two literals hold.
+* Both tones now take the ink their own theme authors against them —
+* `danger-fg` on the red, `warn-fg` on the amber — which is the same shape
+* `Button`'s `danger` variant and `RevertDock`'s confirm paint on the red, and
+* the only place in the package the amber's ink is spent.
+*
+* Both replaced literals, and both literals were wrong in the same way. The
+* red's `text-white` measured 2.99:1 on cue's dark block, which is the default
+* theme. The amber's `text-black` was the better guess of the two — an amber is
+* usually light — but "usually" is not a measurement: it fell to 3.58:1 on
+* requestport's light amber, 3.74:1 on dusk's and 4.22:1 on cue's own, because
+* a light theme darkens its amber to clear the paper and a darkened amber wants
+* paper back. Neither pairing could be fixed by choosing a better literal:
+* which ink a tone can carry is a property of that tone, so each theme derives
+* one. Both tokens clear 4.5:1 on all twenty shipped blocks, and
+* `test/destructive-ink.test.ts` measures this string rather than trusting it.
+*
+* Both tokens are spelled without their prefix on purpose. `tokensUsed` in the
+* package manifest is scanned out of the source text, *comments included*, so a
+* `--cue-…` written in prose is published as a token this component resolves
+* whether or not any class string resolves one. Spelling the amber's ink that
+* way while the palette still had none would have published a token that did
+* not exist; spelling it that way now would still put the claim in the wrong
+* place. The class strings below are where this component names its tokens.
 */
 const CONFIRM_TONES = {
-	danger: "border-transparent bg-danger text-white hover:opacity-90",
-	warn: "border-transparent bg-warn text-black hover:opacity-90"
+	danger: "border-transparent bg-danger text-danger-fg hover:opacity-90",
+	warn: "border-transparent bg-warn text-warn-fg hover:opacity-90"
 };
 /** The idle trigger: outline only, so a destructive action is never the loudest thing on screen. */
 const IDLE_TONES = {

package/dist/layout/sidebar.d.ts

@@ -5,7 +5,25 @@ interface SidebarContextValue {
   collapsed: boolean;
   toggle: () => void;
 }
-/** Read the collapse state of the nearest {@link SidebarRoot}. */
+/**
+ * Read the collapse state of the nearest {@link SidebarRoot}.
+ *
+ * Hands back `{ collapsed, toggle }`: whether the column is at its narrow
+ * width, and the same valve `Sidebar.Rail` pulls. It is for the part the kit
+ * does not ship — a footer that drops its labels when the column narrows, a
+ * keyboard shortcut, a collapse control somewhere other than the rail.
+ *
+ * Outside a `Sidebar.Root` it reports `collapsed: false` and a `toggle` that
+ * does nothing, rather than throwing. A row rendered on its own — in a test, on
+ * a docs page, in a menu that reuses the same markup — is a legitimate thing,
+ * and the honest answer for it is that nothing is collapsed.
+ *
+ * @example
+ * const { collapsed } = useSidebar();
+ * <Button variant="ghost" icon={Plus} aria-label="New scene">
+ *   {collapsed ? null : "New scene"}
+ * </Button>
+ */
 declare function useSidebar(): SidebarContextValue;
 /**
  * Which landmark a navigation column announces as.

package/dist/layout/sidebar.js

@@ -15,7 +15,25 @@ const SidebarContext = React.createContext({
 	collapsed: false,
 	toggle: () => {}
 });
-/** Read the collapse state of the nearest {@link SidebarRoot}. */
+/**
+* Read the collapse state of the nearest {@link SidebarRoot}.
+*
+* Hands back `{ collapsed, toggle }`: whether the column is at its narrow
+* width, and the same valve `Sidebar.Rail` pulls. It is for the part the kit
+* does not ship — a footer that drops its labels when the column narrows, a
+* keyboard shortcut, a collapse control somewhere other than the rail.
+*
+* Outside a `Sidebar.Root` it reports `collapsed: false` and a `toggle` that
+* does nothing, rather than throwing. A row rendered on its own — in a test, on
+* a docs page, in a menu that reuses the same markup — is a legitimate thing,
+* and the honest answer for it is that nothing is collapsed.
+*
+* @example
+* const { collapsed } = useSidebar();
+* <Button variant="ghost" icon={Plus} aria-label="New scene">
+*   {collapsed ? null : "New scene"}
+* </Button>
+*/
 function useSidebar() {
 	return React.useContext(SidebarContext);
 }

package/dist/primitives/button.js

@@ -26,6 +26,16 @@ const buttonChassis = "inline-flex select-none items-center justify-center gap-[
 * reads as white-on-black in `cue` and cyan-on-near-black in `terminal` with no
 * per-theme branching here.
 *
+* `danger` is one of the two tones this system fills a control with — the other
+* is the amber on `TwoStepButton`'s confirm — and they are the two the palette
+* gives an ink of their own. It used to be painted `text-white`, a
+* literal chosen when there was nothing else to choose: white measures 2.99:1
+* on cue's own red in dark mode — the default theme, under AA and under the 3:1
+* floor a non-text control gets — and under AA on eight of the ten dark blocks
+* this system ships. `--cue-danger-fg` is authored against each theme's red and
+* clears 4.5:1 on all twenty. `test/destructive-ink.test.ts` measures it here,
+* at the call site, rather than measuring the token pair on its own.
+*
 * @internal Not part of the public API; imported by `icon-button.tsx`.
 */
 const buttonTones = {
@@ -33,7 +43,7 @@ const buttonTones = {
 	secondary: "border border-border text-fg-muted hover:border-border-strong hover:text-fg bg-surface-2",
 	ghost: "text-fg-muted hover:text-fg hover:bg-surface-2 border border-transparent",
 	outline: "border border-border text-fg hover:border-accent hover:text-accent bg-transparent",
-	danger: "bg-danger text-white hover:opacity-90 border border-transparent",
+	danger: "bg-danger text-danger-fg hover:opacity-90 border border-transparent",
 	"danger-outline": "border text-danger bg-transparent hover:bg-danger/10 border-danger/40"
 };
 /**