@cueplusplus/ui 0.13.0

package/dist/instruments/ledger.d.ts

@@ -0,0 +1,204 @@
+import { LedgerHeadingLevel } from "./_ledger.js";
+import * as React from "react";
+//#region src/instruments/ledger.d.ts
+interface LedgerRootProps extends React.ComponentPropsWithoutRef<"div"> {
+  /**
+   * Make the ledger a size container, so a caller's `@container` rules shed
+   * columns against the *pane* rather than the viewport. Defaults to `true`.
+   *
+   * This is the difference between a list that sheds a column when the window
+   * narrows and one that also sheds it when a detail drawer opens beside it and
+   * takes half the pane — which is the same visual problem and, without a
+   * container, an entirely separate piece of code. Switch it off only when an
+   * ancestor is already the container the rules name; nesting containers moves
+   * which one a bare `@container` query resolves against.
+   */
+  containment?: boolean;
+}
+interface LedgerTierProps extends React.ComponentPropsWithoutRef<"section"> {
+  /**
+   * The tier's name. Omitted, the tier draws no heading and reserves no space
+   * for one — which is how a single unnamed run of rows uses the same component
+   * as a grouped one.
+   */
+  heading?: React.ReactNode;
+  /** How many rows the tier holds, printed beside its name. */
+  count?: number;
+  /**
+   * Dock the heading to the top of the scroll container while the tier's rows
+   * scroll past. Defaults to `true`.
+   */
+  sticky?: boolean;
+  /**
+   * Which heading element the tier's name is. Defaults to `2`.
+   *
+   * The outline is the navigation: a screen-reader user moves through a long
+   * ledger by heading, so the levels have to describe the real nesting of the
+   * page the ledger sits in, not the ledger's own idea of itself.
+   */
+  headingLevel?: LedgerHeadingLevel;
+  /** A qualifier printed after the name — a date, a source, a state. */
+  note?: React.ReactNode;
+  /**
+   * Put a disclosure in the tier's heading that folds its rows away. Defaults
+   * to `false`, and a tier with no `heading` has nothing to fold from, so it
+   * ignores this and renders as it always has.
+   *
+   * **This is the accordion pattern, not the tree pattern.** What folds is the
+   * heading — a *place* — and the `<h2>` stays exactly where it was with a real
+   * `<button aria-expanded aria-controls>` inside it. The rows below are hidden
+   * while it is shut, which takes them out of the accessibility tree and out of
+   * the layout but keeps whatever state they hold. If what you are folding is a
+   * *row*, and the thing under it is that row's children rather than that
+   * place's contents, you want `DataTree` and its `treeitem` semantics instead.
+   */
+  collapsible?: boolean;
+  /**
+   * Whether the tier is open, when the caller owns the state.
+   *
+   * **Persistence is the caller's.** Which places a reader has folded is a fact
+   * about the reader, not about the list, and it belongs wherever that consumer
+   * keeps the rest of them — `localStorage`, a URL, a profile. This library
+   * stores nothing. Pass this with {@link LedgerTierProps.onExpandedChange};
+   * omit both and the tier keeps its own state from
+   * {@link LedgerTierProps.defaultExpanded}. Ignored unless `collapsible`.
+   */
+  expanded?: boolean;
+  /**
+   * Whether an uncontrolled tier starts open. Defaults to `true`.
+   *
+   * Open, because a ledger whose content is folded away on first paint has
+   * hidden the thing the reader came for; the reader folds what they are done
+   * with. Ignored unless `collapsible`, and ignored entirely once
+   * {@link LedgerTierProps.expanded} is passed.
+   */
+  defaultExpanded?: boolean;
+  /**
+   * Called with the tier's next state each time the reader presses the
+   * disclosure — `true` when it is being opened, `false` when it is being shut.
+   *
+   * Fires in both the controlled and the uncontrolled form, so a consumer can
+   * record what was folded without also having to own the state.
+   */
+  onExpandedChange?: (expanded: boolean) => void;
+}
+interface LedgerGroupProps extends React.ComponentPropsWithoutRef<"div"> {
+  /**
+   * The group's slug, printed in the left gutter.
+   *
+   * Omitted, the group is a plain block: no gutter, no heading, no indent. A
+   * grouped list that has one unnamed run in it should not pay a 7rem empty
+   * column for it, and an empty gutter reads as a missing label rather than as
+   * an absent one.
+   */
+  label?: React.ReactNode;
+  /** Which heading element the slug is. Defaults to `3`. */
+  headingLevel?: 3 | 4;
+  /**
+   * Dock the slug under the tier heading while the group's rows scroll past.
+   * Defaults to `true`.
+   *
+   * The offset is a custom property, `--cue-ledger-slug-top` (default `2.5rem`):
+   * how far down the slug docks depends on how tall the tier heading above it
+   * renders, which is a function of the density and the type the *caller*
+   * configured. Set it on the ledger — `className="[--cue-ledger-slug-top:2rem]"` —
+   * rather than measuring at runtime.
+   */
+  sticky?: boolean;
+  /**
+   * Put a disclosure in the group's slug that folds its rows away. Defaults to
+   * `false`, and an unlabelled group has no slug to fold from, so it ignores
+   * this. The same accordion pattern the tier takes — see
+   * {@link LedgerTierProps.collapsible} for why it is not the tree pattern.
+   */
+  collapsible?: boolean;
+  /**
+   * Whether the group is open, when the caller owns the state. Persistence is
+   * the caller's; see {@link LedgerTierProps.expanded}.
+   */
+  expanded?: boolean;
+  /** Whether an uncontrolled group starts open. Defaults to `true`. */
+  defaultExpanded?: boolean;
+  /** Called with the group's next state each time the reader presses the slug. */
+  onExpandedChange?: (expanded: boolean) => void;
+}
+interface LedgerEmptyProps extends React.ComponentPropsWithoutRef<"p"> {}
+/**
+ * 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:
+ * headings, slugs, rows. What it owns above all 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.
+ *
+ * ## Folding: the accordion pattern, opt-in, and why it lives here
+ *
+ * This component used to refuse disclosure outright, on the grounds that *a
+ * ledger which folds is a tree with worse semantics*. That ruling was right
+ * about rows and wrong about places, and the distinction is the whole of
+ * {@link LedgerTierProps.collapsible}:
+ *
+ * - **`DataTree` folds a row.** Its `role="treeitem"` rows carry their own
+ *   `aria-expanded`, its chevron is `role="presentation"` because in tree
+ *   semantics the row owns its expansion, and a tier and a subgroup drawn
+ *   through it stop being places and become rows. A consumer who measured this
+ *   exact shape through `DataTree` counted **zero** `h2`/`h3` elements and zero
+ *   `button[aria-expanded]`, which is `DataTree` working correctly and still
+ *   not being what a grouped document needs.
+ * - **`Ledger` folds a place.** A tier is already an `<h2>`, which is already
+ *   the right element for it, so the disclosure goes *inside* the heading as a
+ *   real `<button aria-expanded aria-controls>` — the accordion pattern, and
+ *   the same one `Table.GroupRow`'s note has always pointed at for a table that
+ *   genuinely needs to fold. The outline is untouched: the heading list of a
+ *   folding ledger and a plain one are identical, which is what lets a page
+ *   offer both idioms over one dataset without the outline moving under a
+ *   reader who switches.
+ *
+ * So it is one component with two forms rather than a `DisclosureLedger` beside
+ * it: everything a folding ledger needs — the gutter track, the sticky offsets,
+ * the label recipe, the type contract — is this component, and a sibling would
+ * have been a copy of all of it wrapped around one `<button>`.
+ *
+ * Expansion is controllable and stores nothing. *Which* places a reader has
+ * folded is a fact about the reader; consumers keep that set themselves and
+ * pass it back in. A folded run of rows is hidden rather than unmounted, so a
+ * group that keeps its own fold inside a tier still keeps it after the tier has
+ * been shut and opened over it.
+ *
+ * Static markup — no `"use client"` — **until a heading is asked to fold**, at
+ * which point that heading and its rows become a small client island and the
+ * rest of the ledger keeps rendering on the server.
+ *
+ * @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>
+ *
+ * @example
+ * // Folded places are the reader's, so the reader's storage holds them.
+ * <Ledger.Tier
+ *   heading="Ours"
+ *   count={13}
+ *   collapsible
+ *   expanded={!folded.includes("ours")}
+ *   onExpandedChange={(open) => remember("ours", open)}
+ * >
+ *   <Ledger.Group label="released">…</Ledger.Group>
+ * </Ledger.Tier>
+ */
+declare const Ledger: {
+  Root: React.ForwardRefExoticComponent<LedgerRootProps & React.RefAttributes<HTMLDivElement>>;
+  Tier: React.ForwardRefExoticComponent<LedgerTierProps & React.RefAttributes<HTMLElement>>;
+  Group: React.ForwardRefExoticComponent<LedgerGroupProps & React.RefAttributes<HTMLDivElement>>;
+  Empty: React.ForwardRefExoticComponent<LedgerEmptyProps & React.RefAttributes<HTMLParagraphElement>>;
+};
+//#endregion
+export { Ledger, LedgerEmptyProps, LedgerGroupProps, LedgerRootProps, LedgerTierProps };

package/dist/instruments/ledger.js

@@ -0,0 +1,204 @@
+import { cn } from "../lib/cn.js";
+import { headingTag } from "./_ledger.js";
+import { LedgerDisclosure } from "./_ledger-disclosure.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";
+/**
+* The disclosure button a collapsible heading holds.
+*
+* Worn *with* {@link LEDGER_LABEL}, which the heading around it is already
+* wearing. The repetition is deliberate: a `<button>` carries the UA's own font
+* rather than its parent's, and while Tailwind's preflight resets that to
+* `font: inherit`, a component whose micro-label silently becomes 13px Arial if
+* a consumer drops preflight is a component with a very confusing bug report.
+* One constant applied twice cannot drift; two recipes can.
+*
+* `w-full` so the whole width of the heading is the hit area rather than the
+* word itself, and the focus ring is inset (`-outline-offset-2`) for the same
+* reason `_data-row.ts` gives: these headings dock at the top of clipped panes,
+* where an outset ring on the first one is cut off by the pane's own rim.
+*/
+const LEDGER_TOGGLE = "flex w-full min-w-0 cursor-pointer items-baseline gap-(--cue-space-2) text-left outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent";
+/**
+* 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:
+* headings, slugs, rows. What it owns above all 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.
+*
+* ## Folding: the accordion pattern, opt-in, and why it lives here
+*
+* This component used to refuse disclosure outright, on the grounds that *a
+* ledger which folds is a tree with worse semantics*. That ruling was right
+* about rows and wrong about places, and the distinction is the whole of
+* {@link LedgerTierProps.collapsible}:
+*
+* - **`DataTree` folds a row.** Its `role="treeitem"` rows carry their own
+*   `aria-expanded`, its chevron is `role="presentation"` because in tree
+*   semantics the row owns its expansion, and a tier and a subgroup drawn
+*   through it stop being places and become rows. A consumer who measured this
+*   exact shape through `DataTree` counted **zero** `h2`/`h3` elements and zero
+*   `button[aria-expanded]`, which is `DataTree` working correctly and still
+*   not being what a grouped document needs.
+* - **`Ledger` folds a place.** A tier is already an `<h2>`, which is already
+*   the right element for it, so the disclosure goes *inside* the heading as a
+*   real `<button aria-expanded aria-controls>` — the accordion pattern, and
+*   the same one `Table.GroupRow`'s note has always pointed at for a table that
+*   genuinely needs to fold. The outline is untouched: the heading list of a
+*   folding ledger and a plain one are identical, which is what lets a page
+*   offer both idioms over one dataset without the outline moving under a
+*   reader who switches.
+*
+* So it is one component with two forms rather than a `DisclosureLedger` beside
+* it: everything a folding ledger needs — the gutter track, the sticky offsets,
+* the label recipe, the type contract — is this component, and a sibling would
+* have been a copy of all of it wrapped around one `<button>`.
+*
+* Expansion is controllable and stores nothing. *Which* places a reader has
+* folded is a fact about the reader; consumers keep that set themselves and
+* pass it back in. A folded run of rows is hidden rather than unmounted, so a
+* group that keeps its own fold inside a tier still keeps it after the tier has
+* been shut and opened over it.
+*
+* Static markup — no `"use client"` — **until a heading is asked to fold**, at
+* which point that heading and its rows become a small client island and the
+* rest of the ledger keeps rendering on the server.
+*
+* @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>
+*
+* @example
+* // Folded places are the reader's, so the reader's storage holds them.
+* <Ledger.Tier
+*   heading="Ours"
+*   count={13}
+*   collapsible
+*   expanded={!folded.includes("ours")}
+*   onExpandedChange={(open) => remember("ours", open)}
+* >
+*   <Ledger.Group label="released">…</Ledger.Group>
+* </Ledger.Tier>
+*/
+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, collapsible = false, expanded, defaultExpanded = true, onExpandedChange, children, ...elementProps }, ref) {
+		const Heading = headingTag(headingLevel);
+		const words = /* @__PURE__ */ jsxs(Fragment, { 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
+			})
+		] });
+		const ground = sticky ? "sticky top-0 z-2 bg-bg" : null;
+		return /* @__PURE__ */ jsx("section", {
+			ref,
+			"data-slot": "ledger-tier",
+			className: cn("flex flex-col", className),
+			...elementProps,
+			children: heading === void 0 ? children : collapsible ? /* @__PURE__ */ jsx(LedgerDisclosure, {
+				headingLevel,
+				headingSlot: "ledger-tier-heading",
+				headingClassName: cn(LEDGER_LABEL, "py-(--cue-pad-row-y)", ground),
+				toggleSlot: "ledger-tier-toggle",
+				toggleClassName: cn(LEDGER_LABEL, LEDGER_TOGGLE),
+				panelSlot: "ledger-tier-rows",
+				panelClassName: "flex flex-col",
+				label: words,
+				expanded,
+				defaultExpanded,
+				onExpandedChange,
+				children
+			}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
+				"data-slot": "ledger-tier-heading",
+				className: cn(LEDGER_LABEL, "flex items-baseline gap-(--cue-space-2) py-(--cue-pad-row-y)", ground),
+				children: words
+			}), children] })
+		});
+	}),
+	Group: React.forwardRef(function LedgerGroup({ className, label, headingLevel = 3, sticky = true, collapsible = false, expanded, defaultExpanded = true, onExpandedChange, children, ...elementProps }, ref) {
+		const Heading = headingTag(headingLevel);
+		const labelled = label !== void 0;
+		const ground = sticky ? "sticky self-start [top:var(--cue-ledger-slug-top,2.5rem)] bg-bg" : null;
+		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 ? children : collapsible ? /* @__PURE__ */ jsx(LedgerDisclosure, {
+				headingLevel,
+				headingSlot: "ledger-group-label",
+				headingClassName: cn(LEDGER_LABEL, "min-w-0 py-(--cue-pad-row-y) pr-(--cue-space-3)", ground),
+				toggleSlot: "ledger-group-toggle",
+				toggleClassName: cn(LEDGER_LABEL, LEDGER_TOGGLE),
+				panelSlot: "ledger-group-rows",
+				panelClassName: "flex min-w-0 flex-col",
+				label: /* @__PURE__ */ jsx("span", {
+					className: "min-w-0 truncate",
+					children: label
+				}),
+				expanded,
+				defaultExpanded,
+				onExpandedChange,
+				children
+			}) : /* @__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)", ground),
+				children: label
+			}), /* @__PURE__ */ jsx("div", {
+				"data-slot": "ledger-group-rows",
+				className: "flex min-w-0 flex-col",
+				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/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 };