@cueplusplus/ui 0.13.0

package/dist/elements/compaction-row.js

@@ -0,0 +1,110 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { mono } from "./surfaces.js";
+import { COMPACTION_LABELS } from "./vocabulary.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CircleAlertIcon, FoldVerticalIcon, Loader2Icon, MinusIcon, XIcon } from "lucide-react";
+//#region src/elements/compaction-row.tsx
+/**
+* A count as a compaction rule says it: `214`, `1.5k`, `128k`.
+*
+* Thousands from four figures up, one decimal below ten thousand and none above
+* it — `128000` is `128k` and `1500` is `1.5k`, because the first number is
+* about a budget and the second is about a change. Anything that is not a
+* finite, positive number is `0`.
+*/
+function formatCount(value) {
+	if (!Number.isFinite(value) || value <= 0) return "0";
+	if (value < 1e3) return String(Math.round(value));
+	const thousands = value / 1e3;
+	return thousands < 10 ? `${Math.round(thousands * 10) / 10}k` : `${Math.round(thousands)}k`;
+}
+/** `128k → 24k tokens`, or `128k tokens` when there is no after yet. */
+function figures(before, after, unit) {
+	if (before === void 0) return null;
+	if (after === void 0) return `${formatCount(before)} ${unit}`;
+	return `${formatCount(before)} → ${formatCount(after)} ${unit}`;
+}
+/**
+* The rule that says the conversation was compacted, and by how much.
+*
+* A `role="separator"` like {@link TimeBoundary}, because that is what it is:
+* the transcript above it is not the transcript below it any more. What makes
+* it worth a component rather than a line of prose is the pair of numbers —
+* before and after, on both axes — since "compacted" alone tells a reader
+* nothing they can act on, while `128k → 24k tokens · 214 → 31 messages` tells
+* them why the model stopped remembering the thing they mentioned an hour ago.
+*
+* Five states, which is two more than most implementations have and exactly the
+* two that matter: a compaction that **failed** leaves the window full, and one
+* that was **skipped** leaves it full on purpose. Both are the states a reader
+* meets when something is about to go wrong, and both are the states a UI that
+* only draws the happy path renders as nothing at all.
+*
+* The numbers render as far as they are known. While `started`, pass the before
+* figures and no after ones and the row reads `128k tokens · 214 messages`; the
+* arrows arrive with the answer.
+*
+* @example
+* import { CompactionRow } from "@cueplusplus/ui/elements";
+*
+* <CompactionRow
+*   state="completed"
+*   tokensBefore={128_000}
+*   tokensAfter={24_000}
+*   messagesBefore={214}
+*   messagesAfter={31}
+* />
+* @example
+* <CompactionRow state="skipped" reason="context window still under 60%" />
+*/
+const CompactionRow = React.forwardRef(function CompactionRow({ state, tokensBefore, tokensAfter, messagesBefore, messagesAfter, label, reason, className, ...elementProps }, ref) {
+	const said = label ?? COMPACTION_LABELS[state];
+	const counts = [figures(tokensBefore, tokensAfter, "tokens"), figures(messagesBefore, messagesAfter, "messages")].filter((part) => part !== null);
+	const spoken = [
+		said,
+		...counts,
+		reason
+	].filter(Boolean).join(" · ");
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		role: "separator",
+		"aria-label": spoken,
+		"data-slot": "compaction-row",
+		"data-state": state,
+		className: cn("flex w-full items-center gap-2.5 py-1", className),
+		...elementProps,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				className: "bg-border h-px flex-1"
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				"aria-hidden": true,
+				className: "flex min-w-0 shrink items-center gap-2",
+				children: [
+					state === "started" ? /* @__PURE__ */ jsx(Loader2Icon, { className: "size-3 shrink-0 animate-spin text-stream motion-reduce:animate-none" }) : state === "failed" ? /* @__PURE__ */ jsx(CircleAlertIcon, { className: "size-3 shrink-0 text-danger" }) : state === "cancelled" ? /* @__PURE__ */ jsx(XIcon, { className: "text-fg-subtle size-3 shrink-0" }) : state === "skipped" ? /* @__PURE__ */ jsx(MinusIcon, { className: "text-fg-subtle size-3 shrink-0" }) : /* @__PURE__ */ jsx(FoldVerticalIcon, { className: "text-fg-subtle size-3 shrink-0" }),
+					/* @__PURE__ */ jsx("span", {
+						className: cn(mono, "shrink-0", state === "failed" ? "text-danger" : "text-fg-subtle"),
+						children: said
+					}),
+					counts.length === 0 ? null : /* @__PURE__ */ jsx("span", {
+						className: cn(mono, "text-fg-subtle min-w-0 truncate tabular-nums"),
+						children: counts.join(" · ")
+					}),
+					reason === void 0 ? null : /* @__PURE__ */ jsx("span", {
+						className: cn(mono, "text-fg-subtle min-w-0 truncate"),
+						children: reason
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				className: "bg-border h-px flex-1"
+			})
+		]
+	});
+});
+//#endregion
+export { CompactionRow };

package/dist/elements/comparison-card.d.ts

@@ -0,0 +1,47 @@
+import { ComponentProps } from "react";
+//#region src/elements/comparison-card.d.ts
+/** One of the options being weighed, and how it answers each trait. */
+interface ComparisonOption {
+  /** Stable identity, compared against recommendedId. */
+  id: string;
+  /** Option name. */
+  name: string;
+  /** One-line summary under the name. */
+  headline: string;
+  /**
+   * Positional against traitLabels. A string is what the option does; false means it
+   * lacks the trait and shows the label struck back.
+   */
+  traits: readonly (string | false)[];
+}
+/**
+ * Two options weighed side by side, with the pick named and argued.
+ *
+ * @example
+ * import { ComparisonCard } from "@cueplusplus/ui/elements";
+ *
+ * <ComparisonCard
+ *   traitLabels={traits}
+ *   options={options}
+ *   recommendedId="local"
+ *   reason="You already hold messages in your own store."
+ * />
+ */
+declare function ComparisonCard({ traitLabels, options, recommendedId, reason, className, ...props }: Omit<ComponentProps<"div">, "children" | "traitLabels" | "options" | "recommendedId" | "reason"> & {
+  /**
+   * The dimensions compared, in order. Used as the fallback label when an option lacks
+   * a trait.
+   */
+  traitLabels: readonly string[];
+  /** Two or three options. More than that wants a table, not a comparison. */
+  options: readonly ComparisonOption[];
+  /** Which option is the pick. It is tinted and labelled rather than merely ordered first. */
+  recommendedId: string;
+  /**
+   * Why that one, in the user's terms. A comparison without a recommendation is an
+   * unanswered question.
+   */
+  reason: string;
+}): import("react").JSX.Element;
+//#endregion
+export { ComparisonCard, ComparisonOption };

package/dist/elements/comparison-card.js

@@ -0,0 +1,69 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { field, paper } from "./surfaces.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, MinusIcon } from "lucide-react";
+//#region src/elements/comparison-card.tsx
+/**
+* Two options weighed side by side, with the pick named and argued.
+*
+* @example
+* import { ComparisonCard } from "@cueplusplus/ui/elements";
+*
+* <ComparisonCard
+*   traitLabels={traits}
+*   options={options}
+*   recommendedId="local"
+*   reason="You already hold messages in your own store."
+* />
+*/
+function ComparisonCard({ traitLabels, options, recommendedId, reason, className, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "comparison-card",
+		className: cn(paper, "flex w-full max-w-md flex-col gap-3 rounded-(--radius-overlay) p-4", className),
+		...props,
+		children: [/* @__PURE__ */ jsx("div", {
+			className: "flex gap-2",
+			children: options.map((option) => {
+				const recommended = option.id === recommendedId;
+				return /* @__PURE__ */ jsxs("div", {
+					className: cn("flex min-w-0 flex-1 flex-col gap-2 rounded-(--radius-surface) p-3 transition-colors", recommended ? "bg-stream/10" : field),
+					children: [/* @__PURE__ */ jsxs("div", {
+						className: "flex flex-col gap-0.5",
+						children: [/* @__PURE__ */ jsxs("span", {
+							className: "flex items-baseline gap-1.5",
+							children: [/* @__PURE__ */ jsx("span", {
+								className: "truncate text-(length:--cue-text-body) font-medium",
+								children: option.name
+							}), recommended && /* @__PURE__ */ jsx("span", {
+								className: cn("font-mono text-(length:--cue-text-label) tracking-tight", "shrink-0 text-stream"),
+								children: "pick"
+							})]
+						}), /* @__PURE__ */ jsx("span", {
+							className: "text-fg-muted truncate text-(length:--cue-text-ui)",
+							children: option.headline
+						})]
+					}), /* @__PURE__ */ jsx("div", {
+						className: "flex flex-col gap-1",
+						children: traitLabels.map((label, i) => {
+							const trait = option.traits[i];
+							const absent = !trait;
+							return /* @__PURE__ */ jsxs("span", {
+								className: "flex items-center gap-1.5 text-(length:--cue-text-ui)",
+								children: [absent ? /* @__PURE__ */ jsx(MinusIcon, { className: "text-fg-subtle size-3 shrink-0" }) : /* @__PURE__ */ jsx(CheckIcon, { className: "size-3 shrink-0 text-ok" }), /* @__PURE__ */ jsx("span", {
+									className: cn("min-w-0 truncate", absent ? "text-fg-subtle" : "text-fg-muted"),
+									children: absent ? label : trait
+								})]
+							}, `${i}-${label}`);
+						})
+					})]
+				}, option.id);
+			})
+		}), /* @__PURE__ */ jsx("p", {
+			className: "text-fg-muted text-(length:--cue-text-ui) leading-(--cue-leading-ui)",
+			children: reason
+		})]
+	});
+}
+//#endregion
+export { ComparisonCard };

package/dist/elements/composer.d.ts

@@ -0,0 +1,274 @@
+import { ComponentProps } from "react";
+import { LucideIcon } from "lucide-react";
+//#region src/elements/composer.d.ts
+/** One file on its way into a message: what it is, how big, and how far it got. */
+interface ComposerAttachment {
+  /** The file name, which is also what the remove button is labelled with. */
+  name: string;
+  /** The line under the name — a size, a page count, or the reason it failed. */
+  meta: string;
+  /**
+   * `uploading` draws the progress hairline, `done` offers remove, `error` reddens the
+   * meta line.
+   */
+  state: "uploading" | "done" | "error";
+  /** How far the upload got, 0 to 100. Only read while `state` is `uploading`. */
+  progress?: number;
+  /** Which icon the tile shows. Defaults to the text one. */
+  kind?: "image" | "text" | "archive";
+}
+/** One slash command the composer offers, as `/name` plus the line beside it. */
+interface ComposerCommand {
+  /** The word after the slash. Matching is a prefix test against what has been typed. */
+  name: string;
+  /** What the command does, in a few words, beside the name. */
+  description: string;
+  /** The lucide icon drawn at the start of the row. */
+  icon: LucideIcon;
+}
+/** One @-mentionable participant: a person or another agent in the thread. */
+interface ComposerPerson {
+  /** Their name, matched as a prefix and written back into the value by `applyMention`. */
+  name: string;
+  /** Whether this is a person or another agent, shown in mono at the end of the row. */
+  role: "agent" | "human";
+}
+/** One row of the model menu — the name, and the line of metadata under it. */
+interface ComposerModel {
+  /** The model's name, as it appears in the menu and on the trigger. */
+  name: string;
+  /** The mono line beside it — a context size, a price, a latency. */
+  meta: string;
+}
+/**
+ * How the context window is spent, in thousands of tokens. The three parts and the
+ * size of the window; the element does the division.
+ */
+interface ComposerUsage {
+  /** Thousands of tokens held by the system prompt. */
+  system: number;
+  /** Thousands of tokens held by the tool definitions. */
+  tools: number;
+  /** Thousands of tokens held by the conversation so far. */
+  messages: number;
+  /**
+   * The size of the window, in the same thousands. Zero means unknown, and the dial
+   * reads empty.
+   */
+  total: number;
+}
+/**
+ * Commands whose name starts with the slash query, or none when not typing one.
+ *
+ * @example
+ * import { ComposerCommandItem, ComposerMenu, useSlashMatches } from "@cueplusplus/ui/elements";
+ *
+ * const matches = useSlashMatches(value, commands);
+ *
+ * <ComposerMenu open={matches.length > 0}>
+ *   {matches.map((command, index) => (
+ *     <ComposerCommandItem
+ *       key={command.name}
+ *       command={command}
+ *       active={index === active}
+ *       onClick={() => setValue(`/${command.name} `)}
+ *     />
+ *   ))}
+ * </ComposerMenu>
+ */
+declare function useSlashMatches(
+/** What is in the input. Only a value starting with `/` matches anything. */
+value: string,
+/** The commands on offer, or nothing when the composer has none. */
+commands: readonly ComposerCommand[] | undefined): ComposerCommand[];
+/**
+ * People matching a trailing @mention, or none when the caret is not in one.
+ *
+ * @example
+ * import { ComposerMenu, ComposerPersonItem, applyMention, useMentionMatches } from "@cueplusplus/ui/elements";
+ *
+ * const matches = useMentionMatches(value, people);
+ *
+ * <ComposerMenu open={matches.length > 0} align="end">
+ *   {matches.map((person, index) => (
+ *     <ComposerPersonItem
+ *       key={person.name}
+ *       person={person}
+ *       active={index === active}
+ *       onClick={() => setValue(applyMention(value, person.name))}
+ *     />
+ *   ))}
+ * </ComposerMenu>
+ */
+declare function useMentionMatches(
+/** What is in the input. Only a trailing `@word` matches anything. */
+value: string,
+/** Who can be mentioned, or nothing when the composer mentions nobody. */
+people: readonly ComposerPerson[] | undefined): ComposerPerson[];
+/** Replaces the trailing @mention with the chosen name. */
+declare function applyMention(value: string, name: string): string;
+/**
+ * The unified input: attachments, commands, mentions, models, voice, and context in
+ * one surface.
+ *
+ * @example
+ * import {
+ *   Composer,
+ *   ComposerActions,
+ *   ComposerAttachButton,
+ *   ComposerBar,
+ *   ComposerInput,
+ *   ComposerSend,
+ *   ComposerToolbar,
+ * } from "@cueplusplus/ui/elements";
+ *
+ * <Composer>
+ *   <ComposerBar>
+ *     <ComposerInput value={value} placeholder="Ask anything" onChange={onChange} onSubmit={send} />
+ *     <ComposerToolbar>
+ *       <ComposerActions><ComposerAttachButton onClick={pick} /></ComposerActions>
+ *       <ComposerActions><ComposerSend streaming={false} idle={!value} onClick={send} /></ComposerActions>
+ *     </ComposerToolbar>
+ *   </ComposerBar>
+ * </Composer>
+ */
+declare function ElementsComposer({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/**
+ * The bar itself: the paper the input, the attachments and the toolbar sit on.
+ * `dragActive` tints it while a file is over it, which is the only feedback a drop
+ * target gets before the drop.
+ */
+declare function ComposerBar({ dragActive, className, ...props }: ComponentProps<"div"> & {
+  /** Whether a file is being dragged over the bar. */
+  dragActive?: boolean;
+}): import("react").JSX.Element;
+/**
+ * The popover the slash and mention menus are drawn in, anchored above the bar. It
+ * animates open rather than mounting, so the caret never moves under it.
+ */
+declare function ComposerMenu({ open, align, className, ...props }: ComponentProps<"div"> & {
+  /** Whether the menu is showing. Closed is animated out, not unmounted. */
+  open: boolean;
+  /** Which edge of the composer the menu hangs from. */
+  align?: "start" | "end";
+}): import("react").JSX.Element;
+/**
+ * One row of a `ComposerMenu`, and the chassis the command, person and model rows are
+ * built on.
+ */
+declare function ComposerMenuItem({ active, className, ...props }: ComponentProps<"button"> & {
+  /** Whether this is the row the keyboard is on. */
+  active?: boolean;
+}): import("react").JSX.Element;
+/**
+ * A slash command in the menu: its icon, `/name`, what it does, and the return key on
+ * the active row.
+ */
+declare function ComposerCommandItem({ command, active, ...props }: Omit<ComponentProps<"button">, "children"> & {
+  /** The command this row offers. */
+  command: ComposerCommand;
+  /** Whether this is the row Enter would run. */
+  active: boolean;
+}): import("react").JSX.Element;
+/**
+ * A mentionable person in the menu: their initial, their name, and whether they are an
+ * agent or a human.
+ */
+declare function ComposerPersonItem({ person, active, ...props }: Omit<ComponentProps<"button">, "children"> & {
+  /** The person this row would mention. */
+  person: ComposerPerson;
+  /** Whether this is the row Enter would pick. */
+  active: boolean;
+}): import("react").JSX.Element;
+/** The rail the attachment chips wrap in, above the input. */
+declare function ComposerAttachments({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/**
+ * One attached file as a chip: an icon for its kind, its name and size, and — while it
+ * uploads — a progress hairline along the bottom edge. A finished one offers remove, a
+ * failed one says so in its meta line.
+ */
+declare function ComposerAttachmentChip({ attachment, onRemove, className, ...props }: Omit<ComponentProps<"div">, "children"> & {
+  /** The file this chip stands for. */
+  attachment: ComposerAttachment;
+  /**
+   * Called with the attachment's name. Omit it and a finished chip shows a tick
+   * instead of a remove button.
+   */
+  onRemove?: (name: string) => void;
+}): import("react").JSX.Element;
+/**
+ * The text field. Enter submits, guarded against IME composition so accepting a
+ * candidate does not send the message.
+ */
+declare function ComposerInput({ onSubmit, onKeyDown, className, ...props }: Omit<ComponentProps<"input">, "onSubmit"> & {
+  /**
+   * Called on Enter, guarded against IME composition so accepting a candidate does not
+   * send.
+   */
+  onSubmit?: () => void;
+}): import("react").JSX.Element;
+/**
+ * What replaces the input while the microphone is open: a level meter, a running clock
+ * while recording, and a shimmering `Transcribing` once it stops.
+ */
+declare function ComposerVoice({ recording, seconds, className, ...props }: Omit<ComponentProps<"div">, "children"> & {
+  /** Whether the microphone is open. False is the transcribing state, not the resting one. */
+  recording: boolean;
+  /**
+   * How long it has been recording. Drives both the clock and the meter, so the caller
+   * owns the tick.
+   */
+  seconds: number;
+}): import("react").JSX.Element;
+/** The row under the input, which holds the two `ComposerActions` clusters. */
+declare function ComposerToolbar({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/** One cluster of controls in the toolbar. Two of them, one at each end. */
+declare function ComposerActions({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/**
+ * The paperclip, as a plus. Disabled when no handler is given, rather than rendering a
+ * control that does nothing.
+ */
+declare function ComposerAttachButton({ className, ...props }: Omit<ComponentProps<"button">, "children">): import("react").JSX.Element;
+/**
+ * The model name in the toolbar, which opens the model menu. Carries `aria-expanded`
+ * for it.
+ */
+declare function ComposerModelTrigger({ model, open, className, ...props }: Omit<ComponentProps<"button">, "children"> & {
+  /** The name to show, which is the selected model. */
+  model: string;
+  /** Whether the menu it opens is showing. Announced as `aria-expanded`. */
+  open: boolean;
+}): import("react").JSX.Element;
+/** One model in the menu, with its metadata and a tick on the chosen one. */
+declare function ComposerModelItem({ entry, selected, ...props }: Omit<ComponentProps<"button">, "children"> & {
+  /** The model this row offers. */
+  entry: ComposerModel;
+  /** Whether this is the model in use. Draws the tick. */
+  selected: boolean;
+}): import("react").JSX.Element;
+/**
+ * The context-window dial in the toolbar, with the breakdown on hover or focus. It
+ * turns danger-coloured past 85%, which is the point where the next long tool result
+ * starts costing the conversation its own history.
+ */
+declare function ComposerContext({ usage, className, ...props }: Omit<ComponentProps<"div">, "children"> & {
+  /** Where the window has gone, and how big it is. */
+  usage: ComposerUsage;
+}): import("react").JSX.Element;
+/** The microphone, which becomes a filled stop while recording. */
+declare function ComposerVoiceButton({ active, className, ...props }: Omit<ComponentProps<"button">, "children"> & {
+  /** Whether the microphone is open. */
+  active: boolean;
+}): import("react").JSX.Element;
+/**
+ * Send, which becomes stop while the model is streaming. Dim when the input is empty
+ * and there is nothing to send; the arrow and the square cross-fade rather than swap.
+ */
+declare function ComposerSend({ streaming, idle, className, ...props }: Omit<ComponentProps<"button">, "children"> & {
+  /** Swaps the arrow for a stop square. */
+  streaming: boolean;
+  /** Whether the input is empty. Dims the button when there is nothing to send. */
+  idle: boolean;
+}): import("react").JSX.Element;
+//#endregion
+export { ComposerActions, ComposerAttachButton, ComposerAttachment, ComposerAttachmentChip, ComposerAttachments, ComposerBar, ComposerCommand, ComposerCommandItem, ComposerContext, ComposerInput, ComposerMenu, ComposerMenuItem, ComposerModel, ComposerModelItem, ComposerModelTrigger, ComposerPerson, ComposerPersonItem, ComposerSend, ComposerToolbar, ComposerUsage, ComposerVoice, ComposerVoiceButton, ElementsComposer, applyMention, useMentionMatches, useSlashMatches };