@cueplusplus/ui 0.5.0 → 0.7.0

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,107 @@ 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 and to focus: the row-hover wash, a pointer
+   * cursor across the whole row, and an inset focus ring. 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.
+   *
+   * **The focus ring ships with it, because the caller's half is what makes the
+   * row focusable.** A `<tr>` cannot take focus on its own, so the moment a
+   * caller gives one a `tabIndex` to run
+   * {@link activateRowFromKeyDown} against, a keyboard user can reach and
+   * activate a row that shows nothing — a WCAG 2.4.7 failure the pointer user
+   * never sees. The ring is *inset* (`-outline-offset-2`), the same ruling as
+   * `Row` and `DataRow.Root`: these tables live in clipped panes and scroll
+   * regions, 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>` here
+   * 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.
+   */
+  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;
+}
+/** The heading elements a group divider's label may be asked to be. */
+type TableGroupHeadingLevel = 2 | 3 | 4 | 5 | 6;
+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;
+  /**
+   * Make the label slot a real heading element. Defaults to `undefined` — no
+   * heading, and the label stays the `<span>` it has always been.
+   *
+   * **Set this rather than passing a heading as `label`.** The label slot wraps
+   * whatever it is given, so an `<h2>` handed in as `label` lands *inside* a
+   * `<span>` — which renders, and exposes the heading, and does not validate: a
+   * `<span>` is phrasing content and may not contain a heading. With this prop
+   * the wrapper *is* the heading (`<h2 data-slot="table-group-label">`), so
+   * there is nothing to nest.
+   *
+   * A heading inside a `<th>` is valid — `<th>` takes flow content — and it is
+   * useful: a screen-reader user navigates a long grouped table by heading, and
+   * without one the group names are reachable only by walking the rows. The
+   * `scope="rowgroup"` association is untouched either way; this adds the
+   * divider to the document outline, it does not change what the cell heads.
+   *
+   * Levels run `2`–`6` because the outline has to describe the real nesting of
+   * the page the table sits in, not the table's own idea of itself — the same
+   * ruling as {@link LedgerTierProps.headingLevel}. There is no `1`: a group
+   * divider is never the title of the document.
+   */
+  headingLevel?: TableGroupHeadingLevel;
+  /** 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 +132,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 +161,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,138 @@ 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.
+*
+* A caller who instead makes the *row* focusable — a `tabIndex` plus
+* {@link activateRowFromClick} and {@link activateRowFromKeyDown}, which is the
+* shape a row that opens a drawer takes — gets the focus ring from
+* {@link TableRowProps.interactive} and needs to draw nothing of its own.
+*
+* 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 outline-none hover:bg-(--cue-row-hover) focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent" : 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
+	});
+});
+/** `headingLevel` as a tag name, so the outline is real elements, not roles. */
+const headingTag = (level) => `h${level}`;
+/**
+* The label slot's own treatment, worn by the `<span>` and by every heading
+* level alike — which is the point: the two forms have to be indistinguishable.
+*
+* Everything here is a no-op on a `<span>` and a correction on a heading, and
+* each of the four exists because a UA stylesheet sets it on `<h2>`–`<h6>`:
+*
+* - `inline` — headings are `display: block`, and a block label would push the
+*   count onto a second line. This is the one that breaks the layout outright.
+* - `text-[length:inherit]` — `<h2>` is `1.5em` and `<h6>` is `0.67em`, so
+*   without this the divider's type would change with the level it was given,
+*   which is a heading level leaking into the visual design.
+* - `font-normal` — headings come bold, and a bold micro-label in a dense list
+*   reads as a second kind of emphasis (the same ruling as `Ledger`'s heading).
+* - `m-0` — headings carry a block margin that would thicken the divider row.
+*
+* Preflight already does the middle two for consumers who import it, but the
+* library does not assume the consumer's reset: the divider has to look the
+* same either way. Tracking, case and colour are *not* restated — no UA rule
+* touches them, so they inherit from the `<th>` that owns the recipe, and a
+* second copy of a treatment is exactly how two surfaces drift apart.
+*/
+const TABLE_GROUP_LABEL = "m-0 inline text-[length:inherit] font-normal";
+/**
 * The canonical console table: hairlines, mono figures, no zebra striping.
 *
 * Semantic `<table>` markup throughout — a grid of divs loses row/column
@@ -30,6 +162,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 +187,34 @@ 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, headingLevel, sticky = false, ...elementProps }, ref) {
+		const Label = headingLevel === void 0 ? "span" : headingTag(headingLevel);
 		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(Label, {
+					"data-slot": "table-group-label",
+					className: 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/theming/_presets.js

@@ -263,7 +263,7 @@ const THEME_PRESETS = {
 			"info": "#1a75d2",
 			"stream": "hsl(212 78% 42%)",
 			"selection": "#cce0ff",
-			"focus": "#e06510",
+			"focus": "#c75600",
 			"data-ground": "#000000",
 			"scrim": "rgba(0,0,0,0.35)"
 		},
@@ -322,7 +322,7 @@ const THEME_PRESETS = {
 			"info": "#2f6fd0",
 			"stream": "hsl(221 78% 45%)",
 			"selection": "rgba(224,101,16,0.15)",
-			"focus": "#e06510",
+			"focus": "#c75600",
 			"data-ground": "#000000",
 			"scrim": "rgba(15,23,42,0.45)"
 		},
@@ -440,7 +440,7 @@ const THEME_PRESETS = {
 			"info": "#1a75d2",
 			"stream": "#0f6ac4",
 			"selection": "rgba(184,134,47,0.20)",
-			"focus": "#b8862f",
+			"focus": "#9f6e08",
 			"data-ground": "#000000",
 			"scrim": "rgba(0,0,0,0.55)"
 		},

package/manifest/components/app-shell.json

@@ -88,7 +88,7 @@
     {
       "name": "Bar",
       "usage": "AppShell.Bar",
-      "description": "The bar across the top of the frame, divided by the navigation column: a\nheader cell exactly the column's width, and the rest of the bar beside it.\n\n`TitleBar` and `AppBar` span the whole frame and know nothing about the\ncolumn under them, which is right for a document and wrong for a console\nthat has an app mark over its navigation: two boxes that are meant to read\nas one column have to be measured from one length, or they drift the first\ntime the column changes width. This is the bar that is measured that way. It\nreads `--cue-nav-width` from {@link AppShellRoot}, so railing the console\nmoves the cell and the column together with nothing to keep in sync.\n\nBelow `md` the cell takes its content's width instead. That is the same\ndecision the column and the drawer trigger already make and not a third one:\nbelow the breakpoint the column is not in the layout, and a cell aligned to\na column that is not there is 14rem of a 390px bar walled off for nothing.\n\nA `<div>` rather than a `<header>`, like `TitleBar` beside it: a console\nframe that also carries an `AppBar` would otherwise have two `banner`\nlandmarks, and a page that wants one can say `role=\"banner\"` here.",
+      "description": "The bar across the top of the frame, divided by the navigation column: a\nheader cell exactly the column's width, and the rest of the bar beside it.\n\n`TitleBar` and `AppBar` span the whole frame and know nothing about the\ncolumn under them, which is right for a document and wrong for a console\nthat has an app mark over its navigation: two boxes that are meant to read\nas one column have to be measured from one length, or they drift the first\ntime the column changes width. This is the bar that is measured that way. It\nreads `--cue-nav-width` from {@link AppShellRoot}, so railing the console\nmoves the cell and the column together with nothing to keep in sync.\n\nBelow `md` the cell takes its content's width instead. That is the same\ndecision the column and the drawer trigger already make and not a third one:\nbelow the breakpoint the column is not in the layout, and a cell aligned to\na column that is not there is 14rem of a 390px bar walled off for nothing.\n\nA `<div>` rather than a `<header>`, like `TitleBar` beside it: a console\nframe that also carries an `AppBar` would otherwise have two `banner`\nlandmarks, and a page that wants one can say `role=\"banner\"` here.\n\n**It is also the desktop app's one chrome row.** `platformDrag` gives it the\ndrag contract `TitleBar` has always had, and `center` and `actions` give it\nthe two slots that made a second stacked bar necessary — so a Tauri or\nElectron window spends one `--cue-chrome-titlebar` on furniture instead of\ntwo. See {@link AppShellBarProps.platformDrag} for why the attribute lands on\nthree surfaces rather than one.\n\nThe bar is always three nested clusters — brand content, leading children,\ntrailing actions — whether or not it is draggable. One shape, not two: the\ndrag mode is then a class on a box that already exists rather than a\ndifferent tree, and a caller's own CSS cannot be right in a browser and wrong\nin a shell. In an ordinary web shell each cluster grows into the space its\ncell gives it, so an `ms-auto` on a brand control still reaches the cell's\ntrailing edge exactly as it did before the clusters existed; under\n`platformDrag` the clusters shrink to their content instead, so that the\nslack stays on the attributed cell and the window can be dragged by it.",
       "props": [
         {
           "name": "brand",
@@ -102,7 +102,28 @@
           "type": "string",
           "required": false,
           "defaultValue": null,
-          "description": "Extra classes for the header cell."
+          "description": "Extra classes for the header cell — the bordered box that spans the\nnavigation column, not the row of brand content inside it. Anything about\nthe cell's width, rim or gutter belongs here; anything about how the mark\nand its controls sit belongs on the nodes passed as `brand`."
+        },
+        {
+          "name": "platformDrag",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Make the bar's dead space a window drag handle. Defaults to `false`.\n\nThis is the same contract {@link TitleBar } has always offered, on the bar\na console with a navigation column actually uses — a desktop app should\nnot need a `TitleBar` *and* an `AppShell.Bar` stacked on top of each other\nto get one draggable row, which is two chrome rungs of a small window\nspent on furniture.\n\nEvery structural surface is attributed and every interactive cluster is\ncarved back out, because the two shells this ships into fail in opposite\ndirections. Tauri matches the *exact* element under the cursor, so the\nbrand cell and the rest cell carry the attribute themselves — a click on\nthe cell's own dead space targets the cell, never the root beneath it, and\na bar that only attributed its root would be draggable nowhere. Electron\nbuilds a geometric mask from painted boxes instead and excludes nothing on\nits own, so the brand content, the leading children and `actions` each sit\nin a cluster marked `app-region: no-drag` — without it a button that merely\noverlaps the bar stops receiving clicks at all. See `./_drag.ts`.\n\n**It changes how the clusters are sized, and that is a trade.** Off, each\ncluster grows into its cell, so a caller's own `ms-auto` reaches the cell's\ntrailing rim. On, the clusters take their content's width and `actions` is\npushed over with `ms-auto` instead, because a cluster that fills its cell\nis a `no-drag` rectangle painted over every dead pixel the cell just\nattributed — the bar would be draggable nowhere but its paddings and its\none gap. The dead area belongs to the window in drag mode, and a caller who\nneeds content to reach the rim there should say so on a box of their own\ninside the cluster.\n\n`select-none` comes with it: dragging a window and selecting the text you\nstarted the drag on are the same gesture, and the shell wins.\n\nNot wired here: double-click-to-maximise. Tauri's injected script already\ndoes it for any drag region, macOS's cancel-by-dragging-away included.\nElectron does not, and an Electron app has to listen for `dblclick` and\ntoggle the window itself. Which of those an app is, is not something a\nlayout component can know."
+        },
+        {
+          "name": "center",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "A title centred on the **bar**, not between the cells beside it.\n\nAbsolutely positioned against the bar's own box, so it stays put when a\nbutton appears in `actions` or the column rails — the whole reason a\ndocument name in desktop chrome is not just another flex child.\n`pointer-events-none` so the dead space around a short title still drags,\nwhich is also what makes it click through to the drag surface underneath\nin Tauri, whose hit-testing is the browser's own.\n\nInert by construction. Anything the reader has to click belongs in\n`actions` or in `children`, where it can be carved out of the drag region."
+        },
+        {
+          "name": "actions",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The trailing cluster: connection state, a run indicator, an overflow menu.\n\nPinned to the bar's trailing edge and never squeezed, so it reads as window\nfurniture rather than the end of a sentence. `children` keeps flowing into\nthe same cell ahead of it, which is what lets an existing web-shell caller\npass free-form content and gain a cluster without rearranging anything."
         }
       ],
       "typeReferences": [
@@ -289,13 +310,16 @@
     "--cue-chrome-titlebar",
     "--cue-control-md",
     "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
     "--cue-icon-md",
     "--cue-nav-width",
     "--cue-pad-row-x",
     "--cue-space-3",
     "--cue-space-4",
     "--cue-space-5",
-    "--cue-surface-1"
+    "--cue-surface-1",
+    "--cue-text-label"
   ],
   "summary": "The console frame: title bar, navigation, work area and status bar, one viewport tall with exactly one thing scrolling.",
   "examples": [
@@ -329,6 +353,11 @@
       "code": "<span className=\"group-data-[rail]/app-shell:hidden\">CUE++</span>",
       "language": "tsx"
     },
+    {
+      "title": "The desktop shape: one chrome row",
+      "code": "<AppShell.Bar\n  platformDrag\n  center=\"main-stage.cue\"\n  brand={<><AppShell.NavTrigger /><Eyebrow>cue++</Eyebrow></>}\n  actions={<><Chip tone=\"ok\">live</Chip><IconButton aria-label=\"Preview\" icon={Monitor} size=\"sm\" /></>}\n>\n  <Toolbar.Button icon={Play}>Go</Toolbar.Button>\n</AppShell.Bar>",
+      "language": "tsx"
+    },
     {
       "title": "Where the footer goes",
       "code": "<AppShell.Content>\n  <AppShell.Scroller className=\"flex flex-col\">\n    <div className=\"flex-1\">{children}</div>\n    <Footer meta={…}>…</Footer>\n  </AppShell.Scroller>\n</AppShell.Content>",
@@ -366,7 +395,9 @@
     "Reaching for a viewport variant of your own because the shell has one. The `md` switch is licensed for navigation shape and nothing else; everything else in this system is intrinsically responsive.",
     "Hard-coding the navigation column's width somewhere else in the frame — a header cell, a toolbar offset, a sticky rule. Read `--cue-nav-width` instead, or the two drift the first time the column rails.",
     "Railing a column of items with no icons. At 3.5rem the label goes `sr-only` and the icon is all that is left; without one the reader gets an empty strip. `AppShell.Sidebar` takes `collapsible={false}` for exactly that column.",
-    "Ending the page with a `Footer` after `AppShell.Body`. A footer belongs to the content column — the last child of `AppShell.Scroller` — or it stretches under the navigation and pretends to be part of the frame."
+    "Ending the page with a `Footer` after `AppShell.Body`. A footer belongs to the content column — the last child of `AppShell.Scroller` — or it stretches under the navigation and pretends to be part of the frame.",
+    "Stacking a `TitleBar` above an `AppShell.Bar` in a desktop app to get a drag region. `AppShell.Bar platformDrag` is the same contract on the bar you already have, and two chrome rungs of a small window is a lot to spend on furniture.",
+    "Putting something clickable in `AppShell.Bar`'s `center`. It is `pointer-events-none` so the dead space around a short title still drags — an interactive centre belongs in `actions` or in `children`, where it is carved out of the drag region."
   ],
   "specimens": [
     {
@@ -378,6 +409,16 @@
       "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  {/* `h-[26rem]` overrides the shell's own `h-dvh`, and `main={false}`\n   * keeps it from emitting a second `<main>` inside the page already\n   * wrapping this corpus. Both are what embedding a whole-screen\n   * component in a bench costs. */}\n  <AppShell.Root className=\"h-[26rem]\" rail={rail} onRailChange={setRail}>\n    {/* The toggle is rendered here rather than by the shell: where the\n     * control lives is a decision about this bar, and persisting what\n     * it sets is a decision about hydration. Both are the caller's. */}\n    <AppShell.Bar\n      brand={\n        <>\n          <AppShell.NavTrigger />\n          <Eyebrow className=\"group-data-[rail]/app-shell:hidden\">CUE++</Eyebrow>\n          <IconButton\n            icon={PanelLeft}\n            size=\"sm\"\n            aria-label={rail ? \"Expand the sidebar\" : \"Collapse the sidebar\"}\n            aria-pressed={rail}\n            className=\"ms-auto\"\n            onClick={() => setRail(!rail)}\n          />\n        </>\n      }\n    >\n      <span className=\"font-mono text-(length:--cue-text-label) text-fg-muted\">\n        main-stage.cue\n      </span>\n      <Chip tone=\"ok\" className=\"ms-auto\">\n        live\n      </Chip>\n    </AppShell.Bar>\n\n    <AppShell.Body>\n      <AppShell.Sidebar aria-label=\"Console\" drawerTitle=\"Console\">\n        <Sidebar.Section label=\"Show\">\n          <Sidebar.Item icon={List} active>\n            Cues\n          </Sidebar.Item>\n          <Sidebar.Item icon={Lightbulb} badge={<Chip>48</Chip>}>\n            Fixtures\n          </Sidebar.Item>\n        </Sidebar.Section>\n      </AppShell.Sidebar>\n\n      <AppShell.Content main={false}>\n        <Toolbar.Root aria-label=\"Cue list\">\n          <Toolbar.Button icon={Plus}>Add cue</Toolbar.Button>\n          <Toolbar.Separator />\n          <Toolbar.Button icon={Monitor}>Live</Toolbar.Button>\n        </Toolbar.Root>\n\n        <AppShell.Scroller>\n          <Panel>\n            <PanelHeader title=\"Cue stack\" actions={<Chip tone=\"ok\">live</Chip>} />\n            {CUES.map((cue) => (\n              <Row key={cue.id}>\n                <span className=\"w-[2rem] shrink-0 font-mono tabular-nums\">{cue.id}</span>\n                <span className=\"flex-1 truncate\">{cue.label}</span>\n                <span className=\"font-mono tabular-nums text-fg-muted\">{cue.time}</span>\n              </Row>\n            ))}\n          </Panel>\n        </AppShell.Scroller>\n      </AppShell.Content>\n\n      <AppShell.Aside aria-label=\"Inspector\" width=\"11rem\">\n        <SectionHeader label=\"Selected\" />\n        <p className=\"font-mono text-(length:--cue-text-ui) text-fg-muted\">\n          Its own scroller, so reading it never moves the work area.\n        </p>\n      </AppShell.Aside>\n    </AppShell.Body>\n\n    <StatusBar>\n      <StatusBar.Item tone=\"ok\">Art-Net</StatusBar.Item>\n      <StatusBar.Item push>Cue 4</StatusBar.Item>\n    </StatusBar>\n  </AppShell.Root>\n</div>",
       "note": "The console frame, and the arithmetic that holds it up: one viewport tall, an unbroken min-h-0 chain, and exactly one thing scrolling. AppShell.Bar divides the bar at the navigation column, so the mark over the column and the column itself are one box measured from one length. Boxed to 26rem here — a bench has no viewport to give it.",
       "interaction": "the button beside the mark rails the column to 3.5rem of icons, and the header cell over it narrows with it — one --cue-nav-width, rewritten once. The 4px strip on the column's edge does the same. Below 48rem the column is not rendered at all and the trigger opens the same navigation as a drawer."
+    },
+    {
+      "title": "AppShell.Bar",
+      "group": "chrome",
+      "components": [
+        "AppShell"
+      ],
+      "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  <AppShell.Root className=\"h-auto\">\n    <AppShell.Bar\n      platformDrag\n      center=\"main-stage.cue\"\n      brand={\n        <>\n          <AppShell.NavTrigger />\n          <Eyebrow>cue++</Eyebrow>\n        </>\n      }\n      actions={\n        <>\n          <Chip tone=\"ok\">live</Chip>\n          <IconButton aria-label=\"Preview\" icon={Monitor} size=\"sm\" />\n        </>\n      }\n    >\n      <Toolbar.Root aria-label=\"Playback\" className=\"border-0 bg-transparent px-0\">\n        <Toolbar.Button icon={Play}>Go</Toolbar.Button>\n        <Toolbar.Button icon={Eye}>Blind</Toolbar.Button>\n      </Toolbar.Root>\n    </AppShell.Bar>\n  </AppShell.Root>\n</div>",
+      "note": "The same bar a console uses, given the desktop app's three extra slots: platformDrag hands every dead pixel to the window manager, center pins the document name to the middle of the bar rather than the middle of the space left over, and actions holds the trailing cluster. One chrome row instead of a TitleBar with a Toolbar stacked under it.",
+      "interaction": "the drag region is inert in a browser — there is no window to move — and live in Tauri and Electron, where it is also carved back out around the mark, the leading controls and the actions, so every one of them still takes its click. Double-click-to-maximise is Tauri's for free and the app's own work in Electron."
     }
   ]
 }

package/manifest/components/autocomplete.json

@@ -144,6 +144,7 @@
     "--cue-accent-soft",
     "--cue-border",
     "--cue-border-overlay",
+    "--cue-border-strong",
     "--cue-chip-h",
     "--cue-control-lg",
     "--cue-control-md",
@@ -152,6 +153,7 @@
     "--cue-fg",
     "--cue-fg-muted",
     "--cue-fg-subtle",
+    "--cue-focus",
     "--cue-font-mono",
     "--cue-icon-sm",
     "--cue-radius-control",