@cueplusplus/ui 0.13.0

package/dist/instruments/seam-grid.js

@@ -0,0 +1,78 @@
+import { cn } from "../lib/cn.js";
+import { toRem } from "./_rem.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/instruments/seam-grid.tsx
+const GROUNDS = {
+	bg: "bg-bg",
+	sunken: "bg-sunken",
+	"surface-1": "bg-surface-1",
+	"surface-2": "bg-surface-2",
+	"surface-3": "bg-surface-3"
+};
+/**
+* The seam recipe itself: a 1px gap over the border colour.
+*
+* No borders anywhere. Two adjacent bordered cells stack into a 2px rule and
+* the grid's outer edge gets a rim nobody asked for; a gap over a coloured
+* ground gives exactly one hairline between every pair of neighbours and
+* nothing at all around the outside.
+*/
+const SEAM_CONTAINER = "gap-px bg-border";
+/**
+* The seam idiom as a component: cells separated by hairlines, no borders.
+*
+* A grid whose `gap` is 1px over the border colour. Every cell paints its own
+* ground, so the only place the container shows through is the gap — which
+* reads as a hairline between neighbours, aligns perfectly at every corner, and
+* never doubles up. This is snuffle's signature primitive; it was inlined at
+* eighteen call sites before it was a component.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <SeamGrid columns={3}>
+*   <SeamCell>001</SeamCell>
+*   <SeamCell>002</SeamCell>
+*   <SeamCell>003</SeamCell>
+* </SeamGrid>
+* @example
+* // Reflowing, no media query:
+* <SeamGrid min={180} bordered>{cells}</SeamGrid>
+*/
+const SeamGrid = React.forwardRef(function SeamGrid({ className, columns, min, bordered = false, style, ...elementProps }, ref) {
+	const gridTemplateColumns = min !== void 0 ? `repeat(auto-fit, minmax(${toRem(min)}, 1fr))` : columns === void 0 ? void 0 : `repeat(${columns}, minmax(0, 1fr))`;
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "seam-grid",
+		className: cn("grid", SEAM_CONTAINER, bordered ? "overflow-hidden rounded-(--radius-surface) border border-border" : null, className),
+		style: {
+			...gridTemplateColumns === void 0 ? null : { gridTemplateColumns },
+			...style
+		},
+		...elementProps
+	});
+});
+/**
+* One filled cell of a {@link SeamGrid} — or of the Phase 1 `SeamList`.
+*
+* The fill is the load-bearing part: an unfilled cell lets the container's
+* border colour through everywhere, not just at the gap, and the seam
+* disappears into a solid block.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <SeamCell ground="sunken" flush><Sparkline values={series} /></SeamCell>
+*/
+const SeamCell = React.forwardRef(function SeamCell({ className, ground = "surface-1", interactive = false, flush = false, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "seam-cell",
+		"data-ground": ground,
+		className: cn("min-w-0", GROUNDS[ground], flush ? null : "p-(--cue-space-5)", interactive ? "cursor-pointer transition-colors duration-150 hover:bg-surface-2 motion-reduce:transition-none" : null, className),
+		...elementProps
+	});
+});
+//#endregion
+export { SeamCell, SeamGrid };

package/dist/instruments/sparkline.d.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+//#region src/instruments/sparkline.d.ts
+interface SparklineProps extends Omit<React.SVGProps<SVGSVGElement>, "values" | "width" | "height" | "children" | "ref"> {
+  /** The series, as percentages. Clamped to 0–100; never rescaled. */
+  values: readonly number[];
+  /** Box width in px at the 16px root, emitted as `rem`. Defaults to `72`. */
+  width?: number;
+  /** Box height in px at the 16px root, emitted as `rem`. Defaults to `14`. */
+  height?: number;
+  /**
+   * The accessible name. Defaults to a sentence naming the latest value, which
+   * is the only number a trace this small can honestly report.
+   */
+  label?: string;
+}
+/**
+ * A tiny unlabelled trace: "is this climbing, or did it just reset?".
+ *
+ * Deliberately answers nothing else — the numbers belong to the `Stat` or the
+ * row above it. Two rules make it trustworthy at 72×14:
+ *
+ * 1. **The scale is always 0–100.** A trace auto-scaled to its own range makes
+ *    a flat 3% look identical to a flat 95%, which is the exact misreading a
+ *    sparkline is supposed to prevent.
+ * 2. **The stroke tone comes from the last value**, not from the shape, so the
+ *    colour agrees with the `Chip` or `Meter` sitting next to it.
+ *
+ * Under two points there is no line to draw, so it renders an empty box of the
+ * same size rather than nothing: a row of sparklines keeps its column even
+ * while some series are still filling up.
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <Sparkline values={[12, 18, 30, 44, 61, 58, 72]} />
+ */
+declare const Sparkline: React.ForwardRefExoticComponent<SparklineProps & React.RefAttributes<SVGSVGElement>>;
+//#endregion
+export { Sparkline, SparklineProps };

package/dist/instruments/sparkline.js

@@ -0,0 +1,85 @@
+import { cn } from "../lib/cn.js";
+import { toRem } from "./_rem.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/instruments/sparkline.tsx
+const TONE_CLASSES = {
+	accent: "text-accent",
+	warn: "text-warn",
+	danger: "text-danger"
+};
+/** Thresholds on the *last* value — the only point a glance actually lands on. */
+function toneFor(last) {
+	if (last >= 80) return "danger";
+	if (last >= 50) return "warn";
+	return "accent";
+}
+/** Default box in px at the 16px root: wide enough for a week, short enough to inline. */
+const DEFAULT_WIDTH_PX = 72;
+const DEFAULT_HEIGHT_PX = 14;
+/**
+* A tiny unlabelled trace: "is this climbing, or did it just reset?".
+*
+* Deliberately answers nothing else — the numbers belong to the `Stat` or the
+* row above it. Two rules make it trustworthy at 72×14:
+*
+* 1. **The scale is always 0–100.** A trace auto-scaled to its own range makes
+*    a flat 3% look identical to a flat 95%, which is the exact misreading a
+*    sparkline is supposed to prevent.
+* 2. **The stroke tone comes from the last value**, not from the shape, so the
+*    colour agrees with the `Chip` or `Meter` sitting next to it.
+*
+* Under two points there is no line to draw, so it renders an empty box of the
+* same size rather than nothing: a row of sparklines keeps its column even
+* while some series are still filling up.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <Sparkline values={[12, 18, 30, 44, 61, 58, 72]} />
+*/
+const Sparkline = React.forwardRef(function Sparkline({ className, values, width = DEFAULT_WIDTH_PX, height = DEFAULT_HEIGHT_PX, label, style, ...elementProps }, ref) {
+	const box = {
+		width: toRem(width),
+		height: toRem(height),
+		overflow: "visible",
+		...style
+	};
+	if (values.length < 2) return /* @__PURE__ */ jsx("svg", {
+		ref,
+		viewBox: `0 0 ${width} ${height}`,
+		"aria-hidden": "true",
+		"data-slot": "sparkline",
+		"data-empty": "true",
+		className: cn("block shrink-0", className),
+		style: box,
+		...elementProps
+	});
+	const step = width / (values.length - 1);
+	const y = (value) => height - Math.min(100, Math.max(0, value)) / 100 * height;
+	const d = values.map((value, index) => `${index === 0 ? "M" : "L"}${(index * step).toFixed(1)},${y(value).toFixed(1)}`).join(" ");
+	const last = values[values.length - 1] ?? 0;
+	const tone = toneFor(last);
+	return /* @__PURE__ */ jsx("svg", {
+		ref,
+		viewBox: `0 0 ${width} ${height}`,
+		role: "img",
+		"aria-label": label ?? `Trend, currently ${Math.round(last)} percent`,
+		"data-slot": "sparkline",
+		"data-tone": tone,
+		className: cn("block shrink-0", TONE_CLASSES[tone], className),
+		style: box,
+		...elementProps,
+		children: /* @__PURE__ */ jsx("path", {
+			d,
+			fill: "none",
+			stroke: "currentColor",
+			strokeWidth: "1",
+			strokeLinecap: "round",
+			strokeLinejoin: "round",
+			vectorEffect: "non-scaling-stroke"
+		})
+	});
+});
+//#endregion
+export { Sparkline };

package/dist/instruments/stat.d.ts

@@ -0,0 +1,35 @@
+import * as React from "react";
+//#region src/instruments/stat.d.ts
+/** The shared status vocabulary, plus the two non-status readings. */
+type StatTone = "neutral" | "accent" | "ok" | "busy" | "warn" | "danger" | "info";
+interface StatProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** What is being measured. Rendered as a micro uppercase caption. */
+  label: React.ReactNode;
+  /** The reading itself — the one thing the eye should land on. */
+  value: React.ReactNode;
+  /** Optional second line: a delta, a window, a unit. */
+  detail?: React.ReactNode;
+  /** Tints the value only. Defaults to `"neutral"`. */
+  tone?: StatTone;
+}
+/**
+ * One number, named: the console's KPI tile.
+ *
+ * Reads label-first (micro, uppercase, tracked) so a row of tiles scans as a
+ * list of captions with the readings underneath, and the value is set in
+ * `tabular-nums` mono so a changing number does not shuffle the layout under
+ * the reader.
+ *
+ * Only the value takes the tone. Tinting the caption too would make a red tile
+ * where the intent is a red *number* — the label is not the alarm.
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <Stat label="Universes" value="512" />
+ * @example
+ * <Stat label="Dropped frames" value="12" detail="last hour" tone="danger" />
+ */
+declare const Stat: React.ForwardRefExoticComponent<StatProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { Stat, StatProps, StatTone };

package/dist/instruments/stat.js

@@ -0,0 +1,59 @@
+import { cn } from "../lib/cn.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/stat.tsx
+const VALUE_TONE_CLASSES = {
+	neutral: "text-fg",
+	accent: "text-accent",
+	ok: "text-ok",
+	busy: "text-busy",
+	warn: "text-warn",
+	danger: "text-danger",
+	info: "text-info"
+};
+/**
+* One number, named: the console's KPI tile.
+*
+* Reads label-first (micro, uppercase, tracked) so a row of tiles scans as a
+* list of captions with the readings underneath, and the value is set in
+* `tabular-nums` mono so a changing number does not shuffle the layout under
+* the reader.
+*
+* Only the value takes the tone. Tinting the caption too would make a red tile
+* where the intent is a red *number* — the label is not the alarm.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <Stat label="Universes" value="512" />
+* @example
+* <Stat label="Dropped frames" value="12" detail="last hour" tone="danger" />
+*/
+const Stat = React.forwardRef(function Stat({ className, label, value, detail, tone = "neutral", ...elementProps }, ref) {
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "stat",
+		"data-tone": tone,
+		className: cn("flex min-w-0 flex-col gap-(--cue-space-2)", className),
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"data-slot": "stat-label",
+				className: "truncate font-mono text-(length:--cue-text-micro) tracking-[0.15em] text-fg-subtle uppercase",
+				children: label
+			}),
+			/* @__PURE__ */ jsx("span", {
+				"data-slot": "stat-value",
+				className: cn("truncate font-mono text-(length:--cue-text-title) leading-none tabular-nums", VALUE_TONE_CLASSES[tone]),
+				children: value
+			}),
+			detail === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "stat-detail",
+				className: "truncate font-mono text-(length:--cue-text-label) text-fg-muted",
+				children: detail
+			})
+		]
+	});
+});
+//#endregion
+export { Stat };

package/dist/instruments/table.d.ts

@@ -0,0 +1,170 @@
+import * as React from "react";
+//#region src/instruments/table.d.ts
+interface TableScrollRegionProps extends Omit<React.ComponentPropsWithoutRef<"div">, "aria-label" | "role" | "tabIndex"> {
+  /** Accessible name announced for the keyboard-focusable scrolling region. */
+  "aria-label": string;
+}
+/**
+ * A named horizontal viewport for a table wider than its container.
+ *
+ * The region is independently keyboard-focusable so keyboard users can reach
+ * native horizontal scrolling. It adds no table semantics of its own; place a
+ * compound {@link Table} inside it and keep the table's caption.
+ */
+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"> {
+  /**
+   * 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. */
+  numeric?: boolean;
+}
+interface TableCaptionProps extends React.ComponentPropsWithoutRef<"caption"> {}
+/**
+ * The canonical console table: hairlines, mono figures, no zebra striping.
+ *
+ * Semantic `<table>` markup throughout — a grid of divs loses row/column
+ * announcement, and a console table is exactly the place a screen reader user
+ * needs it. Zebra rows are deliberately absent: at console density the stripes
+ * are thicker than the data.
+ *
+ * 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>
+ *     <Table.Row>
+ *       <Table.Head>Fixture</Table.Head>
+ *       <Table.Head numeric>Address</Table.Head>
+ *     </Table.Row>
+ *   </Table.Header>
+ *   <Table.Body>
+ *     <Table.Row>
+ *       <Table.Cell>Par 64</Table.Cell>
+ *       <Table.Cell numeric>001</Table.Cell>
+ *     </Table.Row>
+ *   </Table.Body>
+ * </Table.Root>
+ */
+declare const Table: {
+  Root: React.ForwardRefExoticComponent<TableRootProps & React.RefAttributes<HTMLTableElement>>;
+  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, TableGroupRowProps, TableHeadProps, TableRootProps, TableRowProps, TableScrollRegion, TableScrollRegionProps, TableSectionProps };