@cueplusplus/ui 0.13.0

package/dist/elements/live-region-announcer.js

@@ -0,0 +1,230 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/elements/live-region-announcer.tsx
+/**
+* The mounted announcers, and everyone who wants to know about them.
+*
+* This exists because two elements in this family are live regions and a
+* console that mounts both — the obvious composition — had every state spoken
+* twice: once by `TailStatus`, whose row is a `role="status"`, and once by the
+* queue below, whose {@link ANNOUNCEMENTS} table covers the same transitions.
+* Two polite regions saying the same sentence is not redundancy a reader can
+* ignore; it is the transcript read out twice, out of step, because the two
+* regions update at different moments.
+*
+* The contract is that **the announcer is the speech channel and the tail row
+* is a picture of the run**, so the row is what goes quiet. Not the other way
+* round, for three reasons: this region covers nine transitions the row can
+* never show (an error, a permission request, a finished answer); it is mounted
+* empty and stays mounted, which is the only way a live region is reliably
+* announced at all, while a tail row comes and goes with the run; and its whole
+* mechanism — spacing, depth, the pause rules — exists because narration that
+* changes several times a second is unusable when it is spoken. A row that
+* narrates at that rate is exactly what this was built to stand in front of.
+*
+* Module state rather than React context, deliberately. Context would need a
+* provider above both elements, and the composition that has the bug — an
+* announcer and a tail row as siblings, neither knowing about the other — is
+* the one that would not have it. The cost is that this is per *module
+* instance*, not per React root: two independent consoles on one page share the
+* count, and the second one's row would go quiet because the first one's
+* announcer is mounted. That is what {@link TailStatusProps.announce} is for —
+* an explicit answer always wins over this one.
+*/
+const speakers = { announcers: 0 };
+/** Everyone rendering against {@link speakers}. */
+const listeners = /* @__PURE__ */ new Set();
+/** Subscribe to mounts and unmounts, for `useSyncExternalStore`. */
+function subscribeToAnnouncers(onChange) {
+	listeners.add(onChange);
+	return () => {
+		listeners.delete(onChange);
+	};
+}
+const countAnnouncers = () => speakers.announcers;
+/**
+* On the server there is nobody to announce anything and no effect has run, so
+* the answer is zero — which is also what the client's first render sees, since
+* registration happens in an effect. Hydration matches, and the row flips to
+* quiet in the same commit that mounts the announcer.
+*/
+const noAnnouncers = () => 0;
+/** Take a place among the speakers, and give it back. */
+function claimAnnouncer() {
+	speakers.announcers += 1;
+	for (const listener of listeners) listener();
+	return () => {
+		speakers.announcers -= 1;
+		for (const listener of listeners) listener();
+	};
+}
+/**
+* Whether the page is out of sight, asked of the document rather than
+* remembered from an effect.
+*
+* The difference is the whole of the pause rule. A mount effect that reads
+* `visibilityState` into state cannot be read back until the render after it,
+* so every other effect in that same flush — including the one that pumps the
+* queue — runs against `false` and the announcer spends a message before it has
+* learned where it is. A session restored into a background tab would read its
+* backlog out over whatever the reader is doing in the foreground, which is the
+* one moment this rule exists for.
+*/
+const pageHidden = () => typeof document !== "undefined" && document.visibilityState === "hidden";
+/**
+* On the server nothing is on anybody's screen, so the answer is `false` — and
+* it is the answer a hydrating client has to give too, or the markup it renders
+* and the markup it was handed disagree. The gate below does not wait for that
+* to settle; it asks {@link pageHidden} itself.
+*/
+const pageShown = () => false;
+/** Subscribe to the tab going out of sight and coming back. */
+function subscribeToVisibility(onChange) {
+	if (typeof document === "undefined") return () => {};
+	document.addEventListener("visibilitychange", onChange);
+	return () => document.removeEventListener("visibilitychange", onChange);
+}
+/**
+* Whether a {@link LiveRegionAnnouncer} is mounted and will do the speaking.
+*
+* The hook behind this family's one-speaker rule: an announcer and a
+* `TailStatus` in the same console would otherwise narrate the same run twice,
+* so the row asks this and goes quiet. Exported because a console with a status
+* row of its own owes a reader the same courtesy — ask before becoming a second
+* live region.
+*
+* @returns `true` while at least one announcer is mounted anywhere in the page.
+* @example
+* const spokenFor = useAnnouncerPresent();
+* <div role={spokenFor ? undefined : "status"}>{action}</div>
+*/
+function useAnnouncerPresent() {
+	return React.useSyncExternalStore(subscribeToAnnouncers, countAnnouncers, noAnnouncers) > 0;
+}
+/**
+* One polite region, and a queue that makes it audible.
+*
+* The element in this family with no visual design at all, and the one that
+* decides whether the rest of it can be used without a screen. An agent
+* transcript is a stream of state changes, and the naive wiring — an
+* `aria-live` region bound to the current status — announces almost none of
+* them: polite announcements replace each other, so a region updated four times
+* a second speaks once and swallows the rest.
+*
+* So this is a queue with four rules, all of them the reference's:
+*
+* - **Spacing.** One announcement every `spacing` milliseconds, so each is
+*   spoken instead of overwritten.
+* - **Depth, oldest dropped.** A backlog behind a busy run is history; the
+*   newest five are what a reader needs.
+* - **Paused while the page is hidden**, so a background tab does not read a
+*   run out over whatever the reader is actually doing, and paused on demand
+*   through `paused` while a modal has their attention. Both are in force from
+*   the first render rather than the first effect, so an announcer mounted into
+*   a hidden tab with a backlog does not spend a line of it learning where it
+*   is.
+* - **The trailing space.** A screen reader ignores a live region set to the
+*   text it already holds; the same message twice is announced twice by
+*   appending a space to the second, which changes the string without changing
+*   a word of it.
+*
+* The region itself is mounted empty and stays mounted. A live region added to
+* the document at the same moment as its text is a region most assistive
+* technologies never announce, which is the most common way this fails in
+* practice.
+*
+* What to say is the caller's: {@link ANNOUNCEMENTS} carries the nine
+* transitions the study found announced, as templates a console can extend or
+* translate.
+*
+* **It is the surface's one speaker.** `TailStatus` is a `role="status"` too,
+* and a console that mounts both — which is the ordinary shape of an agent
+* console — would have every state read out twice. So mounting this hands the
+* speaking to it: a `TailStatus` anywhere on the page notices (through
+* {@link useAnnouncerPresent}) and renders as an ordinary row, keeping its words
+* on the screen and taking them out of the accessibility tree. Feed this the
+* transitions that row would have narrated, or set `announce` on the row to
+* decide the other way.
+*
+* @example
+* import { ANNOUNCEMENTS, LiveRegionAnnouncer } from "@cueplusplus/ui/elements";
+*
+* // One per surface, mounted for the life of the transcript.
+* <LiveRegionAnnouncer messages={log} paused={dialogOpen} />
+* @example
+* // Composed with the transcript's live row: the row draws, this one speaks.
+* <>
+*   <TailStatus action={TAIL_ACTIONS.searchingCode} detail="composer.tsx" />
+*   <LiveRegionAnnouncer messages={log} />
+* </>
+* @example
+* // The log is a caller's append-only list of what happened.
+* setLog((was) => [...was, ANNOUNCEMENTS.working]);
+*/
+const LiveRegionAnnouncer = React.forwardRef(function LiveRegionAnnouncer({ messages, spacing = 400, depth = 5, paused = false, announceOnMount = false, className, ...elementProps }, ref) {
+	const [spoken, setSpoken] = React.useState("");
+	const hidden = React.useSyncExternalStore(subscribeToVisibility, pageHidden, pageShown);
+	const queue = React.useRef([]);
+	const seen = React.useRef(announceOnMount ? 0 : messages.length);
+	const timer = React.useRef(null);
+	const held = React.useRef(paused || pageHidden());
+	const halted = paused || hidden;
+	/**
+	* Speak the head of the queue, then hold the region for `spacing` before
+	* looking again. A pump that is already inside its gap does nothing: the
+	* timeout's own tail is what drains the rest.
+	*/
+	const pump = React.useCallback(() => {
+		if (timer.current !== null || held.current) return;
+		const next = queue.current.shift();
+		if (next === void 0) return;
+		setSpoken((was) => was === next ? `${next} ` : next);
+		timer.current = setTimeout(() => {
+			timer.current = null;
+			pump();
+		}, Math.max(0, spacing));
+	}, [spacing]);
+	React.useEffect(() => claimAnnouncer(), []);
+	React.useEffect(() => {
+		held.current = paused || pageHidden();
+		if (!held.current) pump();
+	}, [
+		hidden,
+		paused,
+		pump
+	]);
+	React.useEffect(() => {
+		if (messages.length < seen.current) {
+			seen.current = messages.length;
+			return;
+		}
+		if (messages.length === seen.current) return;
+		const arrived = messages.slice(seen.current);
+		seen.current = messages.length;
+		queue.current = [...queue.current, ...arrived].slice(-Math.max(1, depth));
+		pump();
+	}, [
+		depth,
+		messages,
+		pump
+	]);
+	React.useEffect(() => () => {
+		if (timer.current !== null) clearTimeout(timer.current);
+		timer.current = null;
+	}, []);
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "live-region-announcer",
+		"data-paused": String(halted),
+		role: "status",
+		"aria-live": "polite",
+		"aria-atomic": "true",
+		className: cn("sr-only", className),
+		...elementProps,
+		children: spoken
+	});
+});
+//#endregion
+export { LiveRegionAnnouncer, useAnnouncerPresent };

package/dist/elements/loading-state.d.ts

@@ -0,0 +1,27 @@
+import { ComponentProps } from "react";
+//#region src/elements/loading-state.d.ts
+/**
+ * The shape the nine cells take: dots, hard squares, or softened ones.
+ *
+ * @example
+ * import { GenerationLoader } from "@cueplusplus/ui/elements";
+ *
+ * <GenerationLoader label="Generating" tick={24} />
+ */
+type GenerationLoaderVariant = "dots" | "squares" | "rounded";
+interface GenerationLoaderProps extends Omit<ComponentProps<"div">, "children"> {
+  /** Status copy shown under the pixel grid while the model has nothing else to show. */
+  label: string;
+  /** Animation clock that advances the pixel pattern and the elapsed seconds counter. */
+  tick: number;
+  /** Cell shape of the pixel matrix. */
+  variant?: GenerationLoaderVariant;
+}
+/**
+ * The wait before there is anything to show. A nine-cell matrix keeps time under a
+ * shimmering label, driven by a `tick` the caller advances — so a paused replay pauses
+ * the loader too.
+ */
+declare function GenerationLoader({ label, tick, variant, className, ...props }: GenerationLoaderProps): import("react").JSX.Element;
+//#endregion
+export { GenerationLoader, GenerationLoaderProps, GenerationLoaderVariant };

package/dist/elements/loading-state.js

@@ -0,0 +1,36 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { ShimmerLabel } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/elements/loading-state.tsx
+const CELL_SHAPES = {
+	dots: "rounded-full",
+	squares: "rounded-none",
+	rounded: "rounded-(--radius-control)"
+};
+/**
+* The wait before there is anything to show. A nine-cell matrix keeps time under a
+* shimmering label, driven by a `tick` the caller advances — so a paused replay pauses
+* the loader too.
+*/
+function GenerationLoader({ label, tick, variant = "dots", className, ...props }) {
+	const pixelOffset = Math.floor(tick / 3);
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "generation-loader",
+		className: cn("flex flex-col items-center gap-4", className),
+		...props,
+		children: [/* @__PURE__ */ jsx("div", {
+			"aria-hidden": true,
+			className: "grid grid-cols-3 gap-1",
+			children: Array.from({ length: 9 }, (_, index) => {
+				const active = (index * 2 + pixelOffset) % 9 < 3;
+				return /* @__PURE__ */ jsx("span", { className: cn("bg-accent size-2 transition-opacity duration-300 motion-reduce:transition-none", CELL_SHAPES[variant], active ? "opacity-90" : "opacity-15") }, index);
+			})
+		}), /* @__PURE__ */ jsx(ShimmerLabel, {
+			className: "text-fg-muted relative inline-block text-(length:--cue-text-body)",
+			children: label
+		})]
+	});
+}
+//#endregion
+export { GenerationLoader };

package/dist/elements/map-answer.d.ts

@@ -0,0 +1,38 @@
+import { ComponentProps } from "react";
+//#region src/elements/map-answer.d.ts
+/**
+ * One place in a location answer: what it is called, where it sits, and its one line
+ * of detail.
+ */
+interface MapPin {
+  /** Stable identity for the list key and for the callbacks that report a selection. */
+  id: string;
+  /** Place name, shown on the pin and in the list below it. */
+  label: string;
+  /** Secondary fact: a distance, a duration, a rating. */
+  detail: string;
+  /** Horizontal position as a percentage. */
+  x: number;
+  /** Vertical position as a percentage. */
+  y: number;
+}
+/**
+ * A location answer: pins, a route between them, and the list they came from.
+ *
+ * @example
+ * import { MapAnswer } from "@cueplusplus/ui/elements";
+ *
+ * <MapAnswer pins={pins} activeId="b" route onSelect={setActive} />
+ */
+declare function MapAnswer({ pins, activeId, route, onSelect, className, ...props }: Omit<ComponentProps<"div">, "children" | "pins" | "activeId" | "route" | "onSelect"> & {
+  /** Places in the answer, positioned as percentages so the element needs no tiles. */
+  pins: readonly MapPin[];
+  /** Which pin is selected, in both the plot and the list. */
+  activeId: string;
+  /** Draws a dashed path through the pins in order. */
+  route?: boolean;
+  /** Called when a pin or its list row is chosen. Both surfaces report the same id. */
+  onSelect?: (id: string) => void;
+}): import("react").JSX.Element;
+//#endregion
+export { MapAnswer, MapPin };

package/dist/elements/map-answer.js

@@ -0,0 +1,93 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { field, mono, paper } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/elements/map-answer.tsx
+/**
+* A location answer: pins, a route between them, and the list they came from.
+*
+* @example
+* import { MapAnswer } from "@cueplusplus/ui/elements";
+*
+* <MapAnswer pins={pins} activeId="b" route onSelect={setActive} />
+*/
+function MapAnswer({ pins, activeId, route, onSelect, className, ...props }) {
+	const path = pins.map((pin) => `${pin.x},${pin.y}`).join(" ");
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "map-answer",
+		className: cn(paper, "flex w-full max-w-sm flex-col overflow-hidden rounded-(--radius-overlay)", className),
+		...props,
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: cn(field, "relative h-40"),
+			children: [/* @__PURE__ */ jsxs("svg", {
+				viewBox: "0 0 100 100",
+				preserveAspectRatio: "none",
+				"aria-hidden": true,
+				className: "absolute inset-0 size-full",
+				children: [
+					[
+						18,
+						42,
+						66,
+						88
+					].map((y) => /* @__PURE__ */ jsx("line", {
+						x1: "0",
+						x2: "100",
+						y1: y,
+						y2: y,
+						className: "stroke-fg-subtle",
+						strokeWidth: "0.6"
+					}, `h${y}`)),
+					[
+						22,
+						50,
+						74
+					].map((x) => /* @__PURE__ */ jsx("line", {
+						x1: x,
+						x2: x,
+						y1: "0",
+						y2: "100",
+						className: "stroke-fg-subtle",
+						strokeWidth: "0.6"
+					}, `v${x}`)),
+					route && pins.length > 1 && /* @__PURE__ */ jsx("polyline", {
+						points: path,
+						fill: "none",
+						strokeWidth: "1.2",
+						strokeDasharray: "3 2",
+						strokeLinecap: "round",
+						className: "stroke-stream/60"
+					})
+				]
+			}), pins.map((pin) => /* @__PURE__ */ jsx("button", {
+				type: "button",
+				"aria-label": pin.label,
+				"aria-current": pin.id === activeId || void 0,
+				onClick: () => onSelect?.(pin.id),
+				className: "focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent absolute flex size-6 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full outline-none",
+				style: {
+					left: `${pin.x}%`,
+					top: `${pin.y}%`
+				},
+				children: /* @__PURE__ */ jsx("span", { className: cn("block rounded-full border-2 transition-all duration-200 motion-reduce:transition-none", pin.id === activeId ? "border-bg size-3.5 bg-stream" : "border-bg bg-surface-3 size-2.5") })
+			}, pin.id))]
+		}), /* @__PURE__ */ jsx("div", {
+			className: "flex flex-col",
+			children: pins.map((pin) => /* @__PURE__ */ jsxs("button", {
+				type: "button",
+				"aria-current": pin.id === activeId || void 0,
+				onClick: () => onSelect?.(pin.id),
+				className: cn("border-border flex items-baseline gap-2 border-t px-3.5 py-2 text-start transition-colors", pin.id === activeId ? "bg-surface-1" : "hover:bg-surface-1"),
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "text-fg-muted min-w-0 flex-1 truncate text-(length:--cue-text-body)",
+					children: pin.label
+				}), /* @__PURE__ */ jsx("span", {
+					className: cn(mono, "text-fg-subtle shrink-0"),
+					children: pin.detail
+				})]
+			}, pin.id))
+		})]
+	});
+}
+//#endregion
+export { MapAnswer };

package/dist/elements/markdown.d.ts

@@ -0,0 +1,131 @@
+import * as React from "react";
+//#region src/elements/markdown.d.ts
+/** A fenced block, handed to a highlighter that was opted into. */
+interface MarkdownCodeBlock {
+  /**
+   * The info string's first word — `ts` from ` ```ts ` — or `undefined` when
+   * the fence carried none. Matched against `language-[\w+#.-]+`; anything
+   * else was dropped by the sanitizer before it got here.
+   */
+  language?: string;
+  /** The block's text, exactly as the model wrote it. Never markup. */
+  code: string;
+}
+interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">, "children"> {
+  /**
+   * The markdown source. Untrusted model output is precisely what this prop is
+   * for — see the component's own documentation for what is and is not
+   * rendered.
+   */
+  children: string;
+  /**
+   * The turn is still arriving, so hide the token being typed.
+   *
+   * Off by default, because sealing is a small edit to the source and a
+   * settled document should be rendered as written. Turn it on for the tail of
+   * a stream and off again when the turn completes; the rendered output is
+   * identical once nothing is half-written.
+   */
+  streaming?: boolean;
+  /**
+   * Where a link opens. `_blank` by default: a transcript that navigates away
+   * loses the run. `rel` is not configurable — every link gets
+   * `noopener noreferrer nofollow` whatever this says.
+   */
+  target?: "_blank" | "_self";
+  /**
+   * The heading level `#` renders at; `##` and below follow it, clamped at
+   * `h6`. Defaults to `2`, because model output is a passage inside a page
+   * that already owns its `h1`.
+   */
+  headingLevel?: 2 | 3 | 4;
+  /**
+   * Render fenced code blocks with something other than plain text — a
+   * highlighter, a copy button, a diff view.
+   *
+   * Unset, a block is a `<pre><code>` containing the model's characters and
+   * nothing else. That is the default on purpose: a highlighter is a second
+   * parser over the same untrusted string, usually one that emits HTML, and
+   * opting into it should be a line of code somebody wrote rather than a
+   * behaviour they inherited.
+   */
+  renderCodeBlock?: (block: MarkdownCodeBlock) => React.ReactNode;
+}
+/**
+ * Model output, rendered.
+ *
+ * The one component in this library that turns a string into markup, and the
+ * only one that has to be argued for rather than described. Everywhere else —
+ * `Message`, `AskBox`, every element in this group — text is text: a string
+ * arrives from a model and is placed in the DOM as characters, because a
+ * component that quietly parsed it would put every consumer of this library one
+ * prompt away from an injection. This one parses, so it states in full what it
+ * will and will not do with what it is given.
+ *
+ * **Threat model.** The input is hostile. Assume the string was written by a
+ * model that was told to write it by a web page it fetched, a file it read, or
+ * a tool result it did not verify — the practical shape of prompt injection is
+ * not "the model turned evil", it is "the model faithfully relayed an
+ * attacker's bytes". Three things follow.
+ *
+ * - **No raw HTML, ever, and not by filtering it.** Markup in the source has no
+ *   path to the DOM, and the first reason is an absence rather than a setting.
+ *   `react-markdown` hands `remark-rehype` its own `allowDangerousHtml: true`
+ *   and spreads it *over* whatever `remarkRehypeOptions` says, so the option
+ *   cannot be turned off from here and `<img onerror=…>` does become a `raw`
+ *   node. A `raw` node is a span of source text rather than an element, and the
+ *   one thing that turns it into markup is `rehype-raw`. Nothing in this package
+ *   depends on that plugin, and a test asserts it never will — so the string has
+ *   no parser to reach. `rehype-sanitize` then drops the `raw` type outright,
+ *   and react-markdown's own `skipHtml` removes whatever is left. Three gates,
+ *   none of which is a deny-list of dangerous tags. A `<script>`, an
+ *   `<iframe>`, an `<svg>` and an `onclick=` are all the same non-event: there
+ *   is nothing in the tree for them to be.
+ * - **Attributes are enumerated, not filtered.** An element that is not in the
+ *   schema renders nothing; an element that is renders only the attributes
+ *   named beside it — `href`/`title` on a link, `src`/`alt`/`title` on an
+ *   image, `language-…` on a `code`. No element in the subset accepts `id`,
+ *   `style`, `srcset`, `formaction` or any `on*` handler, so none of them has
+ *   an attribute to arrive on.
+ * - **URLs are allow-listed twice.** `http`, `https` and `mailto` on both
+ *   `href` and `src`; a relative URL stays relative; everything else — a
+ *   `javascript:` link, a `data:text/html` image, `vbscript:`, `blob:`,
+ *   `file:`, `//host` — loses the attribute and leaves an inert element
+ *   behind. Every link also carries `rel="noopener noreferrer nofollow"`,
+ *   which is not a prop: reverse tabnabbing, referrer leakage of a private
+ *   console URL, and SEO laundering through a transcript are all things a
+ *   caller should not be able to turn off by accident.
+ *
+ * **The subset.** Paragraphs, ATX and setext headings, bullet and ordered
+ * lists, block quotes, thematic breaks, fenced and indented code, inline code,
+ * emphasis, strong, strikethrough, links, images, and hard breaks. No GFM
+ * plugin is enabled, so no tables, task lists, footnotes or autolink literals —
+ * an explicit `<https://…>` autolink still works. Fenced blocks are plain text
+ * unless {@link MarkdownTextProps.renderCodeBlock} is given.
+ *
+ * **Streaming.** Pass `streaming` while the turn is arriving and the token the
+ * model is halfway through typing is hidden rather than rendered as
+ * punctuation: no asterisks flickering through every bold run, no half-written
+ * URL, no fence that opens a code block one frame and closes it the next. The
+ * words appear as they arrive; only their formatting waits for the closing
+ * token.
+ *
+ * `react-markdown` and `rehype-sanitize` are optional peers of this subpath
+ * alone, which is why this component is not re-exported from
+ * `@cueplusplus/ui/elements`: a console that renders a transcript without
+ * markdown should install neither.
+ *
+ * @example
+ * <Message agent="researcher">
+ *   <MarkdownText>{turn.text}</MarkdownText>
+ * </Message>
+ * @example
+ * <MarkdownText streaming={turn.status === "running"}>{turn.text}</MarkdownText>
+ * @example
+ * <MarkdownText renderCodeBlock={({ language, code }) => <Highlight lang={language} code={code} />}>
+ *   {answer}
+ * </MarkdownText>
+ */
+declare const MarkdownText: React.ForwardRefExoticComponent<MarkdownTextProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { MarkdownCodeBlock, MarkdownText, MarkdownTextProps };