@cueplusplus/ui 0.1.0

package/dist/instruments/terminal-frame.js

@@ -0,0 +1,256 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { CopyButton } from "./copy-button.js";
+import { toRem } from "./_rem.js";
+import { mulberry32, usePrefersReducedMotion } from "./_motion.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/terminal-frame.tsx
+const LINE_TONES = {
+	neutral: "text-fg-muted",
+	accent: "text-accent",
+	ok: "text-ok",
+	warn: "text-warn",
+	danger: "text-danger",
+	info: "text-info"
+};
+/** The braille spinner every CLI in the portfolio uses. */
+const SPINNER_GLYPHS = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+const SPINNER_MS = 80;
+const DEFAULT_KEYSTROKE_MS = 55;
+const DEFAULT_HOLD_MS = 600;
+const DEFAULT_PENDING_MS = 900;
+const DEFAULT_SEED = 1;
+const IDLE = {
+	lines: [],
+	typing: null,
+	spinner: null,
+	done: true
+};
+/** Normalise the shorthand so the renderer only ever sees one shape. */
+function toLine(line) {
+	return typeof line === "string" ? { text: line } : line;
+}
+/** Every line a script ends on — what reduced motion renders straight away. */
+function finalLines(script) {
+	return script.steps.flatMap((step) => [...step.command === void 0 ? [] : [{
+		text: step.command,
+		command: true
+	}], ...(step.output ?? []).map(toLine)]);
+}
+/**
+* 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} />
+*/
+const TerminalFrame = React.forwardRef(function TerminalFrame({ className, title, lines, prompt = "$", copy = false, copyValue, simulate, height, children, ...elementProps }, ref) {
+	const reduced = usePrefersReducedMotion();
+	const [transcript, setTranscript] = React.useState(IDLE);
+	React.useEffect(() => {
+		if (simulate === void 0) {
+			setTranscript(IDLE);
+			return;
+		}
+		if (reduced) {
+			setTranscript({
+				lines: finalLines(simulate),
+				typing: null,
+				spinner: null,
+				done: true
+			});
+			return;
+		}
+		let cancelled = false;
+		let timer;
+		const sleep = (ms) => new Promise((resolve) => {
+			timer = setTimeout(resolve, ms);
+		});
+		const random = mulberry32(simulate.seed ?? DEFAULT_SEED);
+		const keystrokeMs = simulate.keystrokeMs ?? DEFAULT_KEYSTROKE_MS;
+		const holdMs = simulate.holdMs ?? DEFAULT_HOLD_MS;
+		const printed = [];
+		setTranscript({
+			lines: [],
+			typing: null,
+			spinner: null,
+			done: false
+		});
+		(async () => {
+			for (const step of simulate.steps) {
+				if (step.command !== void 0) {
+					for (let index = 1; index <= step.command.length; index += 1) {
+						await sleep(keystrokeMs * (.6 + random()));
+						if (cancelled) return;
+						setTranscript({
+							lines: [...printed],
+							typing: step.command.slice(0, index),
+							spinner: null,
+							done: false
+						});
+					}
+					await sleep(holdMs);
+					if (cancelled) return;
+					printed.push({
+						text: step.command,
+						command: true
+					});
+					setTranscript({
+						lines: [...printed],
+						typing: null,
+						spinner: null,
+						done: false
+					});
+				}
+				if (step.pending !== void 0) {
+					const frames = Math.max(1, Math.round((step.pendingMs ?? DEFAULT_PENDING_MS) / SPINNER_MS));
+					for (let index = 0; index < frames; index += 1) {
+						setTranscript({
+							lines: [...printed],
+							typing: null,
+							spinner: {
+								label: step.pending,
+								index
+							},
+							done: false
+						});
+						await sleep(SPINNER_MS);
+						if (cancelled) return;
+					}
+				}
+				for (const line of step.output ?? []) printed.push(toLine(line));
+				setTranscript({
+					lines: [...printed],
+					typing: null,
+					spinner: null,
+					done: false
+				});
+				await sleep(holdMs);
+				if (cancelled) return;
+			}
+			setTranscript({
+				lines: [...printed],
+				typing: null,
+				spinner: null,
+				done: true
+			});
+		})();
+		return () => {
+			cancelled = true;
+			if (timer !== void 0) clearTimeout(timer);
+		};
+	}, [reduced, simulate]);
+	const preamble = (lines ?? []).map(toLine);
+	const rendered = [...preamble, ...transcript.lines];
+	const commands = [...preamble, ...simulate === void 0 ? [] : finalLines(simulate)].filter((line) => line.command === true);
+	const clipboard = copyValue ?? commands.map((line) => line.text).join("\n");
+	const simulating = simulate !== void 0 && !transcript.done;
+	const promptGlyph = /* @__PURE__ */ jsx("span", {
+		"aria-hidden": "true",
+		"data-slot": "terminal-frame-prompt",
+		className: "mr-(--cue-space-3) shrink-0 text-accent select-none",
+		children: prompt
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "terminal-frame",
+		"data-simulating": simulate === void 0 ? void 0 : String(simulating),
+		className: cn("flex min-w-0 flex-col overflow-hidden rounded-(--radius-surface) border border-border bg-sunken font-mono text-(length:--cue-text-ui) text-fg-muted", className),
+		...elementProps,
+		children: [title === void 0 && !copy ? null : /* @__PURE__ */ jsxs("div", {
+			"data-slot": "terminal-frame-bar",
+			className: "flex h-control-md shrink-0 items-center justify-between gap-(--cue-space-3) border-b border-border px-(--cue-pad-row-x)",
+			children: [/* @__PURE__ */ jsx("span", {
+				"data-slot": "terminal-frame-title",
+				className: "min-w-0 truncate text-(length:--cue-text-label) tracking-[0.15em] text-fg-subtle uppercase",
+				children: title
+			}), copy ? /* @__PURE__ */ jsx("span", {
+				"data-slot": "terminal-frame-copy",
+				"data-value": clipboard,
+				className: "shrink-0",
+				children: /* @__PURE__ */ jsx(CopyButton, {
+					value: clipboard,
+					variant: "ghost",
+					size: "sm"
+				})
+			}) : null]
+		}), /* @__PURE__ */ jsxs("div", {
+			"data-slot": "terminal-frame-body",
+			className: "min-w-0 flex-1 overflow-auto p-(--cue-space-5) leading-relaxed whitespace-pre-wrap",
+			style: height === void 0 ? void 0 : { height: toRem(height) },
+			children: [
+				rendered.map((line, index) => /* @__PURE__ */ jsxs("div", {
+					"data-slot": "terminal-frame-line",
+					"data-command": line.command === true ? "" : void 0,
+					className: cn("flex min-w-0", LINE_TONES[line.tone ?? "neutral"]),
+					children: [line.command === true ? promptGlyph : null, /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 break-all",
+						children: line.text
+					})]
+				}, index)),
+				transcript.typing === null ? null : /* @__PURE__ */ jsxs("div", {
+					"data-slot": "terminal-frame-line",
+					"data-typing": "",
+					className: "flex min-w-0 text-fg",
+					children: [
+						promptGlyph,
+						/* @__PURE__ */ jsx("span", {
+							className: "min-w-0 break-all",
+							children: transcript.typing
+						}),
+						/* @__PURE__ */ jsx("span", {
+							"aria-hidden": "true",
+							className: "animate-pulse motion-reduce:animate-none",
+							children: "▍"
+						})
+					]
+				}),
+				transcript.spinner === null ? null : /* @__PURE__ */ jsxs("div", {
+					"data-slot": "terminal-frame-line",
+					"data-pending": "",
+					className: "flex min-w-0 text-fg-subtle",
+					children: [/* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						className: "mr-(--cue-space-3) shrink-0 text-accent",
+						children: SPINNER_GLYPHS[transcript.spinner.index % SPINNER_GLYPHS.length]
+					}), /* @__PURE__ */ jsx("span", {
+						className: "min-w-0 break-all",
+						children: transcript.spinner.label
+					})]
+				}),
+				children
+			]
+		})]
+	});
+});
+//#endregion
+export { TerminalFrame };

package/dist/instruments/two-step-button.d.ts

@@ -0,0 +1,47 @@
+import { ButtonProps } from "../primitives/button.js";
+import * as React from "react";
+//#region src/instruments/two-step-button.d.ts
+/** Which end of the warning scale this action sits at. */
+type TwoStepTone = "danger" | "warn";
+interface TwoStepButtonProps extends Omit<ButtonProps, "onClick" | "variant" | "onConfirm" | "children"> {
+  /** Fired once, when the *second* press lands. */
+  onConfirm: () => void;
+  /** The idle label — name the action, not the button ("Delete rig", not "Delete"). */
+  children: React.ReactNode;
+  /** Label on the armed half. Defaults to `"Confirm"`. */
+  confirmLabel?: React.ReactNode;
+  /** Label on the escape hatch. Defaults to `"Cancel"`. */
+  cancelLabel?: React.ReactNode;
+  /** How severe this is. Defaults to `"danger"`. */
+  tone?: TwoStepTone;
+  /** ms before an untouched armed state disarms itself. `0` disables. Defaults to `4000`. */
+  timeout?: number;
+  /** Called with the new armed state on every arm and disarm. */
+  onArmedChange?: (armed: boolean) => void;
+}
+/**
+ * Arm, then confirm: a destructive action that takes two deliberate presses.
+ *
+ * The most-reused interaction in the portfolio (fifteen call sites, three
+ * hand-rolled implementations) and the right shape for a destructive action
+ * that is *routine* — deleting a cue, clearing a patch. A modal
+ * `AlertDialog` is the right shape for a rare and expensive one; putting a
+ * dialog in front of an action people take twenty times an hour just teaches
+ * them to dismiss dialogs.
+ *
+ * Four ways out, because an armed button left lying around is a trap: Cancel,
+ * Escape, moving focus away, and a timeout. Focus lands on **Cancel** when the
+ * pair arms, never on the destructive half — the same ruling as a destructive
+ * dialog's default button, and it means a stuck Enter key cannot walk through
+ * both steps.
+ *
+ * @example
+ * <TwoStepButton onConfirm={() => deleteRig(id)}>Delete rig</TwoStepButton>
+ * @example
+ * <TwoStepButton tone="warn" timeout={0} confirmLabel="Reset it" onConfirm={reset}>
+ *   Reset patch
+ * </TwoStepButton>
+ */
+declare const TwoStepButton: React.ForwardRefExoticComponent<TwoStepButtonProps & React.RefAttributes<HTMLButtonElement>>;
+//#endregion
+export { TwoStepButton, TwoStepButtonProps, TwoStepTone };

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

@@ -0,0 +1,147 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/button.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/two-step-button.tsx
+/**
+* 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.
+*/
+const CONFIRM_TONES = {
+	danger: "border-transparent bg-danger text-white hover:opacity-90",
+	warn: "border-transparent bg-warn text-black hover:opacity-90"
+};
+/** The idle trigger: outline only, so a destructive action is never the loudest thing on screen. */
+const IDLE_TONES = {
+	danger: "border-danger/40 text-danger hover:border-danger hover:bg-danger/10",
+	warn: "border-warn/40 text-warn hover:border-warn hover:bg-warn/10"
+};
+/** ms the armed state survives without input before it gives up. */
+const DEFAULT_TIMEOUT_MS = 4e3;
+/**
+* Arm, then confirm: a destructive action that takes two deliberate presses.
+*
+* The most-reused interaction in the portfolio (fifteen call sites, three
+* hand-rolled implementations) and the right shape for a destructive action
+* that is *routine* — deleting a cue, clearing a patch. A modal
+* `AlertDialog` is the right shape for a rare and expensive one; putting a
+* dialog in front of an action people take twenty times an hour just teaches
+* them to dismiss dialogs.
+*
+* Four ways out, because an armed button left lying around is a trap: Cancel,
+* Escape, moving focus away, and a timeout. Focus lands on **Cancel** when the
+* pair arms, never on the destructive half — the same ruling as a destructive
+* dialog's default button, and it means a stuck Enter key cannot walk through
+* both steps.
+*
+* @example
+* <TwoStepButton onConfirm={() => deleteRig(id)}>Delete rig</TwoStepButton>
+* @example
+* <TwoStepButton tone="warn" timeout={0} confirmLabel="Reset it" onConfirm={reset}>
+*   Reset patch
+* </TwoStepButton>
+*/
+const TwoStepButton = React.forwardRef(function TwoStepButton({ className, onConfirm, children, confirmLabel = "Confirm", cancelLabel = "Cancel", tone = "danger", timeout = DEFAULT_TIMEOUT_MS, onArmedChange, size, disabled, ...buttonProps }, ref) {
+	const [armed, setArmed] = React.useState(false);
+	const triggerRef = React.useRef(null);
+	const cancelRef = React.useRef(null);
+	const groupRef = React.useRef(null);
+	const timerRef = React.useRef(void 0);
+	const restoreFocusRef = React.useRef(false);
+	const setTriggerRef = React.useCallback((element) => {
+		triggerRef.current = element;
+		if (typeof ref === "function") ref(element);
+		else if (ref !== null) ref.current = element;
+	}, [ref]);
+	const clearTimer = React.useCallback(() => {
+		if (timerRef.current !== void 0) clearTimeout(timerRef.current);
+		timerRef.current = void 0;
+	}, []);
+	React.useEffect(() => clearTimer, [clearTimer]);
+	const disarm = React.useCallback((restoreFocus) => {
+		clearTimer();
+		restoreFocusRef.current = restoreFocus;
+		setArmed(false);
+		onArmedChange?.(false);
+	}, [clearTimer, onArmedChange]);
+	const arm = React.useCallback(() => {
+		setArmed(true);
+		onArmedChange?.(true);
+		if (timeout > 0) {
+			clearTimer();
+			timerRef.current = setTimeout(() => {
+				timerRef.current = void 0;
+				disarm(true);
+			}, timeout);
+		}
+	}, [
+		clearTimer,
+		disarm,
+		onArmedChange,
+		timeout
+	]);
+	React.useEffect(() => {
+		if (armed) {
+			cancelRef.current?.focus();
+			return;
+		}
+		if (!restoreFocusRef.current) return;
+		restoreFocusRef.current = false;
+		triggerRef.current?.focus();
+	}, [armed]);
+	if (!armed) return /* @__PURE__ */ jsx(Button, {
+		ref: setTriggerRef,
+		variant: "outline",
+		size,
+		disabled,
+		"data-slot": "two-step-button",
+		"data-tone": tone,
+		"data-armed": "false",
+		className: cn(IDLE_TONES[tone], className),
+		onClick: arm,
+		...buttonProps,
+		children
+	});
+	return /* @__PURE__ */ jsxs("span", {
+		ref: groupRef,
+		"data-slot": "two-step-button-armed",
+		"data-tone": tone,
+		className: "inline-flex items-center gap-(--cue-space-2)",
+		onKeyDown: (event) => {
+			if (event.key !== "Escape") return;
+			event.stopPropagation();
+			disarm(true);
+		},
+		onBlur: (event) => {
+			const next = event.relatedTarget;
+			if (next !== null && groupRef.current?.contains(next) === true) return;
+			disarm(false);
+		},
+		children: [/* @__PURE__ */ jsx(Button, {
+			ref: cancelRef,
+			variant: "ghost",
+			size,
+			"data-slot": "two-step-button-cancel",
+			onClick: () => disarm(true),
+			children: cancelLabel
+		}), /* @__PURE__ */ jsx(Button, {
+			variant: "outline",
+			size,
+			"data-slot": "two-step-button-confirm",
+			className: cn(CONFIRM_TONES[tone], className),
+			onClick: () => {
+				disarm(true);
+				onConfirm();
+			},
+			...buttonProps,
+			children: confirmLabel
+		})]
+	});
+});
+//#endregion
+export { TwoStepButton };

package/dist/instruments/usage-chart.d.ts

@@ -0,0 +1,55 @@
+import * as React from "react";
+//#region src/instruments/usage-chart.d.ts
+/** One sample: a timestamp in ms, and a percentage. */
+interface UsageChartPoint {
+  /** Epoch ms. Non-finite and non-positive timestamps are dropped. */
+  t: number;
+  /** Percentage of the ceiling. Clamped to 0–100 on the way in. */
+  v: number;
+}
+/** Stroke colour, in the shared status vocabulary. */
+type UsageChartTone = "accent" | "ok" | "busy" | "warn" | "danger" | "info";
+interface UsageChartProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The series. Sorted and cleaned internally; order in is not order out. */
+  points: readonly UsageChartPoint[];
+  /** Stroke tone. Defaults to `"accent"`. */
+  tone?: UsageChartTone;
+  /** Plot height in px at the 16px root. Defaults to `120`. */
+  height?: number;
+  /** Break the line when consecutive samples are further apart than this, in ms. */
+  gapMs?: number;
+  /** Draw a dashed rule at this percentage — where throttling starts, say. */
+  threshold?: number;
+  /** The accessible name. Name the series; the shape is not self-describing. */
+  label?: string;
+  /** What to say when there is nothing to plot. Defaults to `"No data yet"`. */
+  emptyLabel?: string;
+  /** Format a sample's timestamp for the tooltip. Defaults to a short local date-time. */
+  formatTimestamp?: (t: number) => string;
+  /** Format a sample's value for the tooltip. Defaults to `"87%"`. */
+  formatValue?: (v: number) => string;
+}
+/**
+ * A quota trace: where you sit against the ceiling, over time.
+ *
+ * Dependency-free inline SVG — a charting library is a large price for one
+ * line and five gridlines, and none of them draws the three things that make
+ * this chart honest:
+ *
+ * 1. **The y axis is always 0–100.** A quota chart auto-scaled to its own range
+ *    makes a flat 3% look identical to a flat 95%. The ceiling is the reading,
+ *    so the ceiling is always drawn.
+ * 2. **Gaps are gaps.** When the sweep does not run, the line breaks. Joining
+ *    across a hole invents data — and worse, invents a *smooth* trend across
+ *    exactly the window nothing is known about. The area fill stops at the
+ *    break for the same reason.
+ * 3. **Out-of-range values are clamped, not plotted.** Upstream numbers are
+ *    reverse-engineered and can be anything; 140% should read as a flat line on
+ *    the ceiling, not as a path drawn over the axis labels.
+ *
+ * @example
+ * <UsageChart label="API requests" points={series} threshold={80} tone="warn" />
+ */
+declare const UsageChart: React.ForwardRefExoticComponent<UsageChartProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { UsageChart, UsageChartPoint, UsageChartProps, UsageChartTone };