@cueplusplus/ui 0.1.0

package/dist/instruments/data-table.js

@@ -0,0 +1,212 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { SearchInput } from "../forms/search-input.js";
+import { ChevronLeftGlyph, ChevronRightGlyph, ChevronsLeftGlyph, ChevronsRightGlyph } from "./_glyphs.js";
+import { IconButton } from "../primitives/icon-button.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { columnFilteringFeature, createColumnHelper, createFilteredRowModel, createPaginatedRowModel, createSortedRowModel, filterFn_inNumberRange, filterFn_includesString, flexRender, globalFilteringFeature, rowPaginationFeature, rowSortingFeature, sortFn_alphanumeric, sortFn_basic, sortFn_datetime, sortFn_text, tableFeatures, useTable } from "@tanstack/react-table";
+//#region src/instruments/data-table.tsx
+/**
+* The console table recipe. Not a component — deliberately.
+*
+* A `<DataTable columns={…} data={…} />` monolith has to own the markup of
+* every cell, every header and every empty state, and the first column that
+* needs a `Chip` or a `TwoStepButton` in it starts a prop-drilling arms race
+* that ends with a component nobody can read. TanStack v9's whole point is that
+* the markup stays yours and only the *logic* is shared, so what this module
+* ships is the wiring:
+*
+* - {@link cueTableFeatures} — one opt-in feature set, so v9 can tree-shake
+*   everything the console does not use (grouping, faceting, pinning,
+*   virtualised column sizing).
+* - {@link useCueTable} — that feature set, pre-bound, with sensible console
+*   defaults.
+* - {@link createCueColumnHelper} — the column helper with the features
+*   already applied, so column defs infer.
+* - {@link DataTableToolbar} / {@link DataTablePagination} — the two pieces of
+*   chrome every table needs and nobody enjoys writing twice.
+*
+* The rows render through the Phase 1 `Table`. There is a fully worked example
+* in `test/instruments/data-table.test.tsx`.
+*
+* Ships from `@cueplusplus/ui/instruments/data-table`: `@tanstack/react-table`
+* is an optional peer, and the core bundle must not require it.
+*/
+/**
+* Sorting, column filtering, global filtering and pagination — and nothing
+* else.
+*
+* Named functions are registered individually rather than by spreading the
+* built-in registries, because spreading puts every sort and filter
+* implementation in the bundle whether or not a column names one.
+*/
+const cueTableFeatures = tableFeatures({
+	columnFilteringFeature,
+	globalFilteringFeature,
+	rowPaginationFeature,
+	rowSortingFeature,
+	filteredRowModel: createFilteredRowModel(),
+	paginatedRowModel: createPaginatedRowModel(),
+	sortedRowModel: createSortedRowModel(),
+	filterFns: {
+		includesString: filterFn_includesString,
+		inNumberRange: filterFn_inNumberRange
+	},
+	sortFns: {
+		alphanumeric: sortFn_alphanumeric,
+		basic: sortFn_basic,
+		datetime: sortFn_datetime,
+		text: sortFn_text
+	}
+});
+/**
+* A TanStack v9 table wired for the console.
+*
+* Adds one default on top of the feature set: `globalFilterFn: "includesString"`,
+* which is what a single search box over a console table always means. Override
+* it, or any other option, by passing it.
+*
+* @param options - Everything `useTable` takes except `features`.
+* @returns The table instance, ready to render through `Table`.
+* @example
+* const table = useCueTable({ data, columns, state: { globalFilter }, onGlobalFilterChange });
+*/
+function useCueTable(options) {
+	return useTable({
+		features: cueTableFeatures,
+		globalFilterFn: "includesString",
+		...options
+	});
+}
+/**
+* A column helper with {@link cueTableFeatures} already bound.
+*
+* @returns TanStack's `accessor` / `display` / `group` / `columns` builders.
+* @example
+* const helper = createCueColumnHelper<Fixture>();
+* const columns = [helper.accessor("name", { header: "Fixture" })];
+*/
+function createCueColumnHelper() {
+	return createColumnHelper();
+}
+/**
+* The strip above a table: one search box, a match count, your controls.
+*
+* The count is the part worth having as a component. "12/340" next to a filter
+* box is the difference between "the table is empty" and "the filter is too
+* tight", and it is the first thing left out of a hand-rolled toolbar.
+*
+* @example
+* <DataTableToolbar value={q} onValueChange={setQ} count={table.getRowCount()} total={data.length}>
+*   <Button variant="ghost" size="sm">Export</Button>
+* </DataTableToolbar>
+*/
+const DataTableToolbar = React.forwardRef(function DataTableToolbar({ className, value, onValueChange, placeholder = "Filter…", searchLabel = "Filter rows", count, total, children, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "data-table-toolbar",
+		className: cn("flex min-w-0 items-center gap-(--cue-space-3) py-(--cue-space-3)", className),
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsx(SearchInput, {
+				size: "sm",
+				"aria-label": searchLabel,
+				placeholder,
+				value,
+				onValueChange,
+				className: "max-w-[16rem] min-w-0 flex-1"
+			}),
+			count === void 0 || total === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				"data-slot": "data-table-count",
+				className: "shrink-0 font-mono text-(length:--cue-text-label) tabular-nums text-fg-subtle",
+				children: `${count}/${total}`
+			}),
+			children === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				className: "ml-auto flex shrink-0 items-center gap-(--cue-space-2)",
+				children
+			})
+		]
+	});
+});
+const DEFAULT_PAGER_LABELS = {
+	first: "First page",
+	previous: "Previous page",
+	next: "Next page",
+	last: "Last page"
+};
+/**
+* The pager: four buttons, the position, and the row count.
+*
+* First and last are present because a console table is often sorted to put the
+* interesting row at one end, and stepping there one page at a time is not a
+* navigation strategy. Every button is an `IconButton` with a real accessible
+* name — an arrow glyph alone announces as nothing.
+*
+* @example
+* <DataTablePagination table={table} />
+*/
+const DataTablePagination = React.forwardRef(function DataTablePagination({ className, table, labels, formatPosition = (page, pages) => `${page} / ${pages}`, formatRowCount = (rows) => `${rows} row${rows === 1 ? "" : "s"}`, ...elementProps }, ref) {
+	const names = {
+		...DEFAULT_PAGER_LABELS,
+		...labels
+	};
+	const pages = Math.max(1, table.getPageCount());
+	const page = (table.state.pagination?.pageIndex ?? 0) + 1;
+	const canPrevious = table.getCanPreviousPage();
+	const canNext = table.getCanNextPage();
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "data-table-pagination",
+		className: cn("flex min-w-0 items-center gap-(--cue-space-3) py-(--cue-space-3) font-mono text-(length:--cue-text-label) text-fg-subtle", className),
+		...elementProps,
+		children: [/* @__PURE__ */ jsx("span", {
+			"data-slot": "data-table-rows",
+			className: "tabular-nums",
+			children: formatRowCount(table.getRowCount())
+		}), /* @__PURE__ */ jsxs("span", {
+			className: "ml-auto flex items-center gap-(--cue-space-1)",
+			children: [
+				/* @__PURE__ */ jsx(IconButton, {
+					size: "sm",
+					variant: "ghost",
+					"aria-label": names.first,
+					icon: ChevronsLeftGlyph,
+					disabled: !canPrevious,
+					onClick: () => table.firstPage()
+				}),
+				/* @__PURE__ */ jsx(IconButton, {
+					size: "sm",
+					variant: "ghost",
+					"aria-label": names.previous,
+					icon: ChevronLeftGlyph,
+					disabled: !canPrevious,
+					onClick: () => table.previousPage()
+				}),
+				/* @__PURE__ */ jsx("span", {
+					"data-slot": "data-table-position",
+					className: "px-(--cue-space-3) tabular-nums text-fg",
+					children: formatPosition(page, pages)
+				}),
+				/* @__PURE__ */ jsx(IconButton, {
+					size: "sm",
+					variant: "ghost",
+					"aria-label": names.next,
+					icon: ChevronRightGlyph,
+					disabled: !canNext,
+					onClick: () => table.nextPage()
+				}),
+				/* @__PURE__ */ jsx(IconButton, {
+					size: "sm",
+					variant: "ghost",
+					"aria-label": names.last,
+					icon: ChevronsRightGlyph,
+					disabled: !canNext,
+					onClick: () => table.lastPage()
+				})
+			]
+		})]
+	});
+});
+//#endregion
+export { DataTablePagination, DataTableToolbar, createCueColumnHelper, cueTableFeatures, flexRender, useCueTable };

package/dist/instruments/group-bar.d.ts

@@ -0,0 +1,63 @@
+import * as React from "react";
+//#region src/instruments/group-bar.d.ts
+/** Ink for one segment, in the shared status vocabulary plus `neutral`. */
+type GroupBarTone = "neutral" | "accent" | "ok" | "busy" | "warn" | "danger" | "info";
+/** One slice of the distribution. */
+interface GroupBarItem {
+  /** Stable key. Defaults to the label, which is normally unique already. */
+  id?: string;
+  /** What this slice is. Used in the legend and in the accessible summary. */
+  label: string;
+  /** The quantity. Shares are computed against the sum; zero and below are dropped. */
+  value: number;
+  /** Ink for the slice. Defaults to `"neutral"`. */
+  tone?: GroupBarTone;
+}
+interface GroupBarProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /** The slices, in display order. */
+  items: readonly GroupBarItem[];
+  /** Strip height in px at the 16px root, emitted as `rem`. Defaults to `6`. */
+  height?: number;
+  /** What the distribution is *of*. Required in practice — it names the graphic. */
+  label?: string;
+  /** List the slices with their shares underneath the strip. */
+  legend?: boolean;
+  /** Format one share for the summary and the legend. Defaults to `"42%"`. */
+  formatShare?: (share: number, item: GroupBarItem) => string;
+  /** What to say when every slice is empty. Defaults to `"no data"`. */
+  emptyLabel?: string;
+}
+/**
+ * The distribution strip: one flex cell per group, weighted by its value.
+ *
+ * A stacked bar with no axis and no numbers — the shape *is* the reading. Three
+ * rules keep it honest:
+ *
+ * 1. **Empty groups get no cell.** A minimum width is what makes a two-pixel
+ *    sliver visible, and a minimum width on a zero would draw a group that is
+ *    not there.
+ * 2. **The percentages add to 100.** Shares are rounded by largest remainder,
+ *    so the legend never sums to 99 and never to 101.
+ * 3. **Colour is never the only channel.** The strip is a `role="img"` whose
+ *    accessible name spells the whole distribution out (WCAG 1.4.1); the legend
+ *    repeats it in text when there is room for one.
+ *
+ * The cells are divided by the same 1px seam as `SeamList`, so a distribution
+ * strip and a seam list sitting in the same panel share one hairline language.
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <GroupBar
+ *   label="Universe load"
+ *   items={[
+ *     { label: "dimmers", value: 212, tone: "accent" },
+ *     { label: "movers", value: 96, tone: "info" },
+ *     { label: "free", value: 204 },
+ *   ]}
+ *   legend
+ * />
+ */
+declare const GroupBar: React.ForwardRefExoticComponent<GroupBarProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { GroupBar, GroupBarItem, GroupBarProps, GroupBarTone };

package/dist/instruments/group-bar.js

@@ -0,0 +1,122 @@
+import { cn } from "../lib/cn.js";
+import { toRem } from "./_rem.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/instruments/group-bar.tsx
+const CELL_TONES = {
+	neutral: "bg-fg-subtle",
+	accent: "bg-accent",
+	ok: "bg-ok",
+	busy: "bg-busy",
+	warn: "bg-warn",
+	danger: "bg-danger",
+	info: "bg-info"
+};
+const LEGEND_TONES = {
+	neutral: "text-fg-subtle",
+	accent: "text-accent",
+	ok: "text-ok",
+	busy: "text-busy",
+	warn: "text-warn",
+	danger: "text-danger",
+	info: "text-info"
+};
+/** Default strip height in px at the 16px root — thin enough to sit under a `Stat`. */
+const DEFAULT_HEIGHT_PX = 6;
+/** Percentages that add up: largest-remainder, so the row never reads 99%. */
+function shares(values) {
+	const total = values.reduce((sum, value) => sum + value, 0);
+	if (total <= 0) return values.map(() => 0);
+	const exact = values.map((value) => value / total * 100);
+	const floors = exact.map((value) => Math.floor(value));
+	let remainder = 100 - floors.reduce((sum, value) => sum + value, 0);
+	const order = exact.map((value, index) => ({
+		index,
+		fraction: value - Math.floor(value)
+	})).sort((a, b) => b.fraction - a.fraction);
+	const result = [...floors];
+	for (const { index } of order) {
+		if (remainder <= 0) break;
+		result[index] = result[index] + 1;
+		remainder -= 1;
+	}
+	return result;
+}
+/**
+* The distribution strip: one flex cell per group, weighted by its value.
+*
+* A stacked bar with no axis and no numbers — the shape *is* the reading. Three
+* rules keep it honest:
+*
+* 1. **Empty groups get no cell.** A minimum width is what makes a two-pixel
+*    sliver visible, and a minimum width on a zero would draw a group that is
+*    not there.
+* 2. **The percentages add to 100.** Shares are rounded by largest remainder,
+*    so the legend never sums to 99 and never to 101.
+* 3. **Colour is never the only channel.** The strip is a `role="img"` whose
+*    accessible name spells the whole distribution out (WCAG 1.4.1); the legend
+*    repeats it in text when there is room for one.
+*
+* The cells are divided by the same 1px seam as `SeamList`, so a distribution
+* strip and a seam list sitting in the same panel share one hairline language.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <GroupBar
+*   label="Universe load"
+*   items={[
+*     { label: "dimmers", value: 212, tone: "accent" },
+*     { label: "movers", value: 96, tone: "info" },
+*     { label: "free", value: 204 },
+*   ]}
+*   legend
+* />
+*/
+const GroupBar = React.forwardRef(function GroupBar({ className, items, height = DEFAULT_HEIGHT_PX, label, legend = false, formatShare = (share) => `${share}%`, emptyLabel = "no data", ...elementProps }, ref) {
+	const present = items.filter((item) => item.value > 0);
+	const percentages = shares(present.map((item) => item.value));
+	const empty = present.length === 0;
+	const summary = empty ? emptyLabel : present.map((item, index) => `${item.label} ${formatShare(percentages[index], item)}`).join(", ");
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		"data-slot": "group-bar",
+		"data-empty": empty ? "true" : void 0,
+		className: cn("flex min-w-0 flex-col gap-(--cue-space-3)", className),
+		...elementProps,
+		children: [/* @__PURE__ */ jsx("div", {
+			role: "img",
+			"aria-label": label === void 0 ? summary : `${label}: ${summary}`,
+			"data-slot": "group-bar-track",
+			className: "flex w-full gap-px overflow-hidden rounded-(--radius-control) bg-border",
+			style: { height: toRem(height) },
+			children: present.map((item) => /* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				"data-slot": "group-bar-cell",
+				"data-tone": item.tone ?? "neutral",
+				className: cn("min-w-[2px] shrink-0", CELL_TONES[item.tone ?? "neutral"]),
+				style: {
+					flexGrow: item.value,
+					flexBasis: 0
+				}
+			}, item.id ?? item.label))
+		}), legend && !empty ? /* @__PURE__ */ jsx("div", {
+			"aria-hidden": "true",
+			"data-slot": "group-bar-legend",
+			className: "flex flex-wrap items-center gap-x-(--cue-space-5) gap-y-(--cue-space-2) font-mono text-(length:--cue-text-label) text-fg-muted",
+			children: present.map((item, index) => /* @__PURE__ */ jsxs("span", {
+				className: "inline-flex items-center gap-(--cue-space-2)",
+				children: [
+					/* @__PURE__ */ jsx("span", { className: cn("size-[0.375rem] shrink-0 rounded-full", CELL_TONES[item.tone ?? "neutral"]) }),
+					/* @__PURE__ */ jsx("span", { children: item.label }),
+					/* @__PURE__ */ jsx("span", {
+						className: cn("tabular-nums", LEGEND_TONES[item.tone ?? "neutral"]),
+						children: formatShare(percentages[index], item)
+					})
+				]
+			}, item.id ?? item.label))
+		}) : null]
+	});
+});
+//#endregion
+export { GroupBar };

package/dist/instruments/index.d.ts

@@ -0,0 +1,13 @@
+import { AppWindowFrame, AppWindowFrameProps } from "./app-window-frame.js";
+import { CopyButton, CopyButtonProps } from "./copy-button.js";
+import { GroupBar, GroupBarItem, GroupBarProps, GroupBarTone } from "./group-bar.js";
+import { Meter, MeterProps, MeterProvenance, MeterTone } from "./meter.js";
+import { Progress, ProgressProps } from "./progress.js";
+import { SeamCell, SeamCellProps, SeamGrid, SeamGridProps, SeamGround } from "./seam-grid.js";
+import { Sparkline, SparklineProps } from "./sparkline.js";
+import { Stat, StatProps, StatTone } from "./stat.js";
+import { Table, TableCaptionProps, TableCellProps, TableHeadProps, TableRootProps, TableRowProps, TableSectionProps } from "./table.js";
+import { TerminalFrame, TerminalFrameLine, TerminalFrameProps, TerminalLine, TerminalLineTone, TerminalScript, TerminalStep } from "./terminal-frame.js";
+import { TwoStepButton, TwoStepButtonProps, TwoStepTone } from "./two-step-button.js";
+import { UsageChart, UsageChartPoint, UsageChartProps, UsageChartTone } from "./usage-chart.js";
+export { AppWindowFrame, type AppWindowFrameProps, CopyButton, type CopyButtonProps, GroupBar, type GroupBarItem, type GroupBarProps, type GroupBarTone, Meter, type MeterProps, type MeterProvenance, type MeterTone, Progress, type ProgressProps, SeamCell, type SeamCellProps, SeamGrid, type SeamGridProps, type SeamGround, Sparkline, type SparklineProps, Stat, type StatProps, type StatTone, Table, type TableCaptionProps, type TableCellProps, type TableHeadProps, type TableRootProps, type TableRowProps, type TableSectionProps, TerminalFrame, type TerminalFrameLine, type TerminalFrameProps, type TerminalLine, type TerminalLineTone, type TerminalScript, type TerminalStep, TwoStepButton, type TwoStepButtonProps, type TwoStepTone, UsageChart, type UsageChartPoint, type UsageChartProps, type UsageChartTone };

package/dist/instruments/index.js

@@ -0,0 +1,13 @@
+import { AppWindowFrame } from "./app-window-frame.js";
+import { CopyButton } from "./copy-button.js";
+import { GroupBar } from "./group-bar.js";
+import { Meter } from "./meter.js";
+import { Progress } from "./progress.js";
+import { SeamCell, SeamGrid } from "./seam-grid.js";
+import { Sparkline } from "./sparkline.js";
+import { Stat } from "./stat.js";
+import { Table } from "./table.js";
+import { TerminalFrame } from "./terminal-frame.js";
+import { TwoStepButton } from "./two-step-button.js";
+import { UsageChart } from "./usage-chart.js";
+export { AppWindowFrame, CopyButton, GroupBar, Meter, Progress, SeamCell, SeamGrid, Sparkline, Stat, Table, TerminalFrame, TwoStepButton, UsageChart };

package/dist/instruments/log-viewer.d.ts

@@ -0,0 +1,74 @@
+import * as React from "react";
+//#region src/instruments/log-viewer.d.ts
+/** The four levels a process actually emits. */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/** One line of output. */
+interface LogLine {
+  /** Stable identity. Used as the virtualiser's key, so it must not repeat. */
+  id: string;
+  /** Epoch ms. Rendered through `formatTimestamp` when present. */
+  ts?: number;
+  /** Severity. Drives the row's ink and the filter strip. */
+  level?: LogLevel;
+  /** The line, verbatim — escape sequences and all. */
+  text: string;
+  /** Parse `text` as ANSI. Off by default: most streams are plain. */
+  ansi?: boolean;
+}
+interface LogViewerProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children" | "onScroll"> {
+  /** The buffer, oldest first. */
+  lines: readonly LogLine[];
+  /** Stick to the bottom as lines arrive. Defaults to `true`. */
+  follow?: boolean;
+  /**
+   * Which levels get a filter chip. Defaults to the levels present in `lines`;
+   * `false` hides the strip entirely. Levels with no chip are always shown.
+   */
+  filters?: readonly LogLevel[] | false;
+  /** Viewer height in px at the 16px root. */
+  height: number;
+  /** Row height in px. Defaults to the short control rung at the ambient density. */
+  rowHeight?: number;
+  /** Cap on retained lines; the oldest are dropped. Defaults to `5000`. */
+  maxLines?: number;
+  /** Render a line's timestamp. Defaults to a local `HH:MM:SS`. */
+  formatTimestamp?: (ts: number) => string;
+  /** What to say when there is nothing to show. Defaults to `"No output"`. */
+  emptyLabel?: string;
+  /** Label for the catch-up pill. Defaults to `"3 new lines"`. */
+  newLinesLabel?: (count: number) => string;
+  /** Accessible name for the log region. Required in practice — name the stream. */
+  "aria-label"?: string;
+}
+/**
+ * A virtualised log tail: ANSI colour, level filters, and stick-to-bottom.
+ *
+ * The four things a log pane has to get right, and the reasons each one is not
+ * optional:
+ *
+ * - **Virtualised.** Five thousand DOM rows is a frozen tab. Rows are fixed at
+ *   the short control rung so the virtualiser never has to measure, which is
+ *   also what keeps the scrollbar honest while lines stream in.
+ * - **ANSI as data, never as HTML.** `anser` will happily hand back a markup
+ *   string, and the moment that reaches `dangerouslySetInnerHTML` any process
+ *   that prints a `<script>` owns the console watching it. Colour arrives here
+ *   as spans of *text* with resolved token colours (see `_ansi.ts`).
+ * - **Following is a mode, not a scroll.** While pinned to the bottom the view
+ *   follows; scroll up and it stops and starts counting, so reading something
+ *   is never fought by the stream. The count comes back as a pill, not as a
+ *   jump.
+ * - **A cap.** An unbounded buffer is a memory leak with a progress bar. The
+ *   head is dropped past `maxLines`.
+ *
+ * Ships from `@cueplusplus/ui/instruments/log-viewer`: it needs
+ * `@tanstack/react-virtual` and `anser`, both optional peers, and neither
+ * belongs in the bundle of an app that renders no logs.
+ *
+ * @example
+ * <LogViewer aria-label="Build output" height={320} lines={lines} />
+ * @example
+ * <LogViewer aria-label="Worker" height={200} follow={false} filters={["warn", "error"]} lines={lines} />
+ */
+declare const LogViewer: React.ForwardRefExoticComponent<LogViewerProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { LogLevel, LogLine, LogViewer, LogViewerProps };