@cueplusplus/ui 0.1.0

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,51 @@
+import * as React from "react";
+//#region src/instruments/table.d.ts
+interface TableRootProps extends React.ComponentPropsWithoutRef<"table"> {}
+interface TableSectionProps extends React.ComponentPropsWithoutRef<"tbody"> {}
+interface TableRowProps extends React.ComponentPropsWithoutRef<"tr"> {}
+interface TableHeadProps extends React.ComponentPropsWithoutRef<"th"> {
+  /** Right-align this column and set it in tabular figures. */
+  numeric?: boolean;
+}
+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.
+ *
+ * @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>>;
+  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, TableSectionProps };

package/dist/instruments/table.js

@@ -0,0 +1,92 @@
+import { cn } from "../lib/cn.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+/**
+* 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.
+*
+* @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>
+*/
+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) {
+		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
+		});
+	}),
+	Cell: React.forwardRef(function TableCell({ className, numeric = false, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("td", {
+			ref,
+			"data-slot": "table-cell",
+			"data-numeric": numeric ? "" : void 0,
+			className: cn("px-(--cue-pad-row-x) py-(--cue-pad-row-y) align-middle", className),
+			...elementProps
+		});
+	}),
+	Caption: React.forwardRef(function TableCaption({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("caption", {
+			ref,
+			"data-slot": "table-caption",
+			className: cn("caption-bottom pt-(--cue-space-3) text-left font-mono text-(length:--cue-text-label) text-fg-subtle", className),
+			...elementProps
+		});
+	})
+};
+//#endregion
+export { Table };

package/dist/instruments/terminal-frame.d.ts

@@ -0,0 +1,89 @@
+import * as React from "react";
+//#region src/instruments/terminal-frame.d.ts
+/** Ink for one transcript line, in the shared status vocabulary. */
+type TerminalLineTone = "neutral" | "accent" | "ok" | "warn" | "danger" | "info";
+/** One line of a transcript. A bare string is output; `command` makes it a prompt line. */
+interface TerminalLine {
+  /** The text of the line, verbatim. */
+  text: string;
+  /** Prefix it with the prompt glyph — this line is something the user typed. */
+  command?: boolean;
+  /** Ink for the line. Defaults to `"neutral"`. */
+  tone?: TerminalLineTone;
+}
+/** Shorthand: a bare string is an output line with no tone. */
+type TerminalFrameLine = string | TerminalLine;
+/** One beat of a simulated session: type a command, spin, print the result. */
+interface TerminalStep {
+  /** Typed one character at a time at the prompt. */
+  command?: string;
+  /** Label shown next to a spinner once the command "runs". */
+  pending?: string;
+  /** How long the spinner runs, in ms. Defaults to `900`. */
+  pendingMs?: number;
+  /** Printed all at once when the step finishes. */
+  output?: readonly TerminalFrameLine[];
+}
+/** A scripted session for {@link TerminalFrameProps.simulate}. */
+interface TerminalScript {
+  /** The beats, in order. */
+  steps: readonly TerminalStep[];
+  /** Nominal ms per keystroke, jittered 0.6×–1.6×. Defaults to `55`. */
+  keystrokeMs?: number;
+  /** Seed for the keystroke jitter. The same seed always plays the same way. Defaults to `1`. */
+  seed?: number;
+  /** Pause after a command lands and after its output prints, in ms. Defaults to `600`. */
+  holdMs?: number;
+}
+interface TerminalFrameProps extends Omit<React.ComponentPropsWithoutRef<"div">, "title" | "children"> {
+  /** Name above the transcript — a log file, a host, a task. */
+  title?: React.ReactNode;
+  /** Static transcript. Rendered as a preamble when `simulate` is also set. */
+  lines?: readonly TerminalFrameLine[];
+  /** The prompt glyph in front of a command line. Defaults to `"$"`. */
+  prompt?: string;
+  /** Show a `CopyButton` in the title bar for the commands in the transcript. */
+  copy?: boolean;
+  /** What the copy button puts on the clipboard. Defaults to the command lines, one per line. */
+  copyValue?: string;
+  /**
+   * Play the transcript out as a typed session.
+   *
+   * Pass a stable reference (a module constant, or memoised) — the player
+   * restarts whenever this prop changes identity. Under
+   * `prefers-reduced-motion` the finished transcript renders instantly and no
+   * timer is ever scheduled.
+   */
+  simulate?: TerminalScript;
+  /** Fixed body height in px at the 16px root. Leave unset to grow with the content. */
+  height?: number;
+  /** Extra content under the transcript — an input row, a hint strip. */
+  children?: React.ReactNode;
+}
+/**
+ * A recessed terminal: mono, `$`-prefixed commands, optional typed playback.
+ *
+ * Recessed rather than raised — `bg-sunken` sits the transcript *into* the page
+ * the way a real console does (the snuffle convention, where the terminal
+ * surface is the only thing darker than the background).
+ *
+ * The `simulate` player is deliberately not a GIF or a video: it is text, so it
+ * copies, it scales with the type ramp, it re-themes, and it costs nothing to
+ * load. Keystrokes are jittered from a seed so a marketing screenshot is
+ * reproducible, and the whole animation is replaced by its final frame under
+ * `prefers-reduced-motion` — with no timers scheduled at all, rather than an
+ * animation that runs invisibly.
+ *
+ * @example
+ * <TerminalFrame
+ *   title="install"
+ *   copy
+ *   lines={[{ text: "pnpm add @cueplusplus/ui", command: true }, "+ 1 package"]}
+ * />
+ * @example
+ * const SCRIPT = { steps: [{ command: "cue build", pending: "compiling", output: ["12 cues"] }] };
+ * <TerminalFrame simulate={SCRIPT} />
+ */
+declare const TerminalFrame: React.ForwardRefExoticComponent<TerminalFrameProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { TerminalFrame, TerminalFrameLine, TerminalFrameProps, TerminalLine, TerminalLineTone, TerminalScript, TerminalStep };