@candor-ui/react 1.1.0 → 1.3.0

package/dist/chat/composer.d.ts

@@ -32,9 +32,10 @@ export type ComposerState = "ready" | "sending" | "streaming" | {
  *
  * Enter sends, Shift+Enter breaks a line. While an agent replies the send button
  * becomes Stop. A locked composer says why; an offline one says so. With
- * `onAttach`, files can also be pasted or dropped onto it.
+ * `onAttach`, files can also be pasted or dropped onto it. `tools` adds your
+ * own controls to the toolbar, such as a dictation button.
  */
-declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onScopeClick, mentions, commands, references, onReferencesChange, attachments, onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, className, }: {
+declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onScopeClick, mentions, commands, references, onReferencesChange, attachments, onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, className, }: {
     /** The text in the box. */
     value: string;
     /** Called with the new text as the person types. */
@@ -72,6 +73,8 @@ declare function Composer({ value, onChange, onSubmit, onStop, state, scope, onS
     placeholder?: string;
     /** The accessible name of the text box; "Message" by default. */
     label?: string;
+    /** Your own controls in the toolbar, after the attach button: a dictation button, a model picker. */
+    tools?: React.ReactNode;
     className?: string;
 }): React.JSX.Element;
 export { Composer };

package/dist/chat/composer.js

@@ -47,9 +47,10 @@ const hasFiles = (e) => Array.from(e.dataTransfer?.types ?? []).includes("Files"
  *
  * Enter sends, Shift+Enter breaks a line. While an agent replies the send button
  * becomes Stop. A locked composer says why; an offline one says so. With
- * `onAttach`, files can also be pasted or dropped onto it.
+ * `onAttach`, files can also be pasted or dropped onto it. `tools` adds your
+ * own controls to the toolbar, such as a dictation button.
  */
-function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, onScopeClick, mentions = [], commands = [], references = [], onReferencesChange, attachments = [], onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, className, }) {
+function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, onScopeClick, mentions = [], commands = [], references = [], onReferencesChange, attachments = [], onAttach, accept, onRemoveAttachment, placeholder: placeholderProp, label: labelProp, tools, className, }) {
     const kindOf = useEntityKinds();
     const t = useStrings("composer", composerStrings);
     const placeholder = placeholderProp ?? t("placeholder");
@@ -211,6 +212,6 @@ function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, o
                                             if (files.length)
                                                 onAttach(files);
                                             e.target.value = "";
-                                        } }), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": t("attachFiles"), disabled: Boolean(locked), onClick: () => fileInput.current?.click(), className: "flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground disabled:opacity-40", children: _jsx(Paperclip, { className: "size-4" }) }) }), _jsx(TooltipContent, { children: t("attachFiles") })] })] })), scope && (_jsxs("button", { type: "button", onClick: onScopeClick, disabled: !onScopeClick, className: cn("inline-flex min-w-0 items-center gap-1.5 rounded-lg px-2 py-1 text-xs transition-colors duration-150 enabled:hover:bg-accent", production ? "bg-warning-weak text-warning-text enabled:hover:bg-warning-weak" : "text-muted-foreground"), children: [production ? _jsx(TriangleAlert, { "aria-hidden": true, className: "size-3 shrink-0" }) : _jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-success" }), _jsxs("span", { className: "truncate", children: [scope.environment, " \u00B7 ", production ? t("production") : (scope.detail ?? t("nonProduction"))] })] })), _jsxs("span", { className: "ms-auto hidden text-2xs text-faint-foreground @lg:inline", children: [_jsx("kbd", { className: "font-sans", children: "\u21B5" }), " ", t("hintSend"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "\u21E7\u21B5" }), " ", t("hintNewLine"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "@" }), " ", t("hintMention")] }), state === "streaming" && onStop ? (_jsx("button", { type: "button", "aria-label": t("stop"), onClick: onStop, className: "ms-auto flex size-8 items-center justify-center rounded-lg bg-foreground text-background transition-transform duration-150 active:scale-95 @lg:ms-1", children: _jsx(Square, { className: "size-3 fill-current" }) })) : (_jsx("button", { type: "button", "aria-label": t("send"), onClick: submit, disabled: !canSend, "aria-busy": state === "sending", className: "ms-auto flex size-8 items-center justify-center rounded-lg bg-primary text-primary-foreground transition-[background-color,opacity,transform] duration-150 enabled:hover:bg-primary-hover active:scale-95 disabled:opacity-30 @lg:ms-1", children: state === "sending" ? _jsx(LoaderCircle, { className: "size-4 animate-spin" }) : _jsx(ArrowUp, { className: "size-4", strokeWidth: 2.5 }) }))] })] })] }));
+                                        } }), _jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": t("attachFiles"), disabled: Boolean(locked), onClick: () => fileInput.current?.click(), className: "flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors duration-150 hover:bg-accent hover:text-foreground disabled:opacity-40", children: _jsx(Paperclip, { className: "size-4" }) }) }), _jsx(TooltipContent, { children: t("attachFiles") })] })] })), tools, scope && (_jsxs("button", { type: "button", onClick: onScopeClick, disabled: !onScopeClick, className: cn("inline-flex min-w-0 items-center gap-1.5 rounded-lg px-2 py-1 text-xs transition-colors duration-150 enabled:hover:bg-accent", production ? "bg-warning-weak text-warning-text enabled:hover:bg-warning-weak" : "text-muted-foreground"), children: [production ? _jsx(TriangleAlert, { "aria-hidden": true, className: "size-3 shrink-0" }) : _jsx("span", { "aria-hidden": true, className: "size-1.5 shrink-0 rounded-full bg-success" }), _jsxs("span", { className: "truncate", children: [scope.environment, " \u00B7 ", production ? t("production") : (scope.detail ?? t("nonProduction"))] })] })), _jsxs("span", { className: "ms-auto hidden text-2xs text-faint-foreground @lg:inline", children: [_jsx("kbd", { className: "font-sans", children: "\u21B5" }), " ", t("hintSend"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "\u21E7\u21B5" }), " ", t("hintNewLine"), " \u00B7 ", _jsx("kbd", { className: "font-sans", children: "@" }), " ", t("hintMention")] }), state === "streaming" && onStop ? (_jsx("button", { type: "button", "aria-label": t("stop"), onClick: onStop, className: "ms-auto flex size-8 items-center justify-center rounded-lg bg-foreground text-background transition-transform duration-150 active:scale-95 @lg:ms-1", children: _jsx(Square, { className: "size-3 fill-current" }) })) : (_jsx("button", { type: "button", "aria-label": t("send"), onClick: submit, disabled: !canSend, "aria-busy": state === "sending", className: "ms-auto flex size-8 items-center justify-center rounded-lg bg-primary text-primary-foreground transition-[background-color,opacity,transform] duration-150 enabled:hover:bg-primary-hover active:scale-95 disabled:opacity-30 @lg:ms-1", children: state === "sending" ? _jsx(LoaderCircle, { className: "size-4 animate-spin" }) : _jsx(ArrowUp, { className: "size-4", strokeWidth: 2.5 }) }))] })] })] }));
 }
 export { Composer };

package/dist/chat/thread.d.ts

@@ -9,8 +9,12 @@ export declare const threadStrings: {
  * bottom and stops following the moment you scroll up to read, offering a
  * "Jump to latest" button instead. Pass `empty` for the first-run state and
  * the composer as `footer`.
+ *
+ * For long histories, `virtualize` renders only the messages in or near view
+ * (each child is one item, keyed by its `key`). The column stays a `log`, the
+ * message holding focus stays rendered, and Jump to latest works the same.
  */
-declare function Thread({ children, empty, footer, className, contentClassName, }: {
+declare function Thread({ children, empty, footer, className, contentClassName, virtualize, }: {
     children?: React.ReactNode;
     /** Shown before the first message. */
     empty?: React.ReactNode;
@@ -19,5 +23,7 @@ declare function Thread({ children, empty, footer, className, contentClassName,
     className?: string;
     /** Classes for the message column. */
     contentClassName?: string;
+    /** Render only the messages in or near view, for histories of hundreds of messages. Give each child a `key`. Defaults to false. */
+    virtualize?: boolean;
 }): React.JSX.Element;
 export { Thread };

package/dist/chat/thread.js

@@ -1,9 +1,10 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { ArrowDown } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { useStrings } from "../blocks/locale.js";
+import { useVirtualList } from "../lib/use-virtual-list.js";
 /** Thread's fixed words; override them under `thread` in LocaleProvider's `strings`. */
 export const threadStrings = {
     messages: "Messages",
@@ -14,8 +15,12 @@ export const threadStrings = {
  * bottom and stops following the moment you scroll up to read, offering a
  * "Jump to latest" button instead. Pass `empty` for the first-run state and
  * the composer as `footer`.
+ *
+ * For long histories, `virtualize` renders only the messages in or near view
+ * (each child is one item, keyed by its `key`). The column stays a `log`, the
+ * message holding focus stays rendered, and Jump to latest works the same.
  */
-function Thread({ children, empty, footer, className, contentClassName, }) {
+function Thread({ children, empty, footer, className, contentClassName, virtualize = false, }) {
     const t = useStrings("thread", threadStrings);
     const scroller = React.useRef(null);
     const content = React.useRef(null);
@@ -58,7 +63,23 @@ function Thread({ children, empty, footer, className, contentClassName, }) {
         lastTop.current = top;
     };
     const hasMessages = React.Children.count(children) > 0;
-    return (_jsxs("div", { "data-slot": "thread", className: cn("flex min-h-0 flex-col", className), children: [_jsxs("div", { className: "relative min-h-0 flex-1", children: [_jsx("div", { ref: scroller, onScroll: onScroll, className: "h-full overflow-y-auto overscroll-contain", children: _jsx("div", { ref: content, role: "log", "aria-label": t("messages"), className: cn("mx-auto flex w-full max-w-(--cd-thread-width) flex-col gap-7 px-4 py-6", contentClassName), children: hasMessages ? children : empty }) }), !pinned && hasMessages && (_jsxs("button", { type: "button", onClick: () => {
+    const items = virtualize ? React.Children.toArray(children) : [];
+    const keyOf = (i) => (React.isValidElement(items[i]) ? (items[i].key ?? i) : i);
+    // The message holding focus stays rendered, so focus isn't lost when it scrolls out of view.
+    const [focused, setFocused] = React.useState(null);
+    const list = useVirtualList({
+        enabled: virtualize,
+        count: items.length,
+        keyOf,
+        scroller,
+        pin: focused,
+        gap: () => (content.current ? Number.parseFloat(getComputedStyle(content.current).rowGap) || 0 : 0),
+    });
+    return (_jsxs("div", { "data-slot": "thread", className: cn("flex min-h-0 flex-col", className), children: [_jsxs("div", { className: "relative min-h-0 flex-1", children: [_jsx("div", { ref: scroller, onScroll: onScroll, onFocus: virtualize
+                            ? (e) => {
+                                setFocused(e.target.closest("[data-virtual-key]")?.getAttribute("data-virtual-key") ?? null);
+                            }
+                            : undefined, onBlur: virtualize ? (e) => !e.currentTarget.contains(e.relatedTarget) && setFocused(null) : undefined, className: "h-full overflow-y-auto overscroll-contain", children: _jsx("div", { ref: content, role: "log", "aria-label": t("messages"), className: cn("mx-auto flex w-full max-w-(--cd-thread-width) flex-col gap-7 px-4 py-6", contentClassName), children: !hasMessages ? (empty) : virtualize ? (_jsx(_Fragment, { children: list.rows.map((row) => "spacer" in row ? (_jsx("div", { "aria-hidden": true, style: { height: row.spacer } }, row.key)) : (_jsx("div", { ref: list.measure, "data-virtual-key": String(keyOf(row.index)), className: "flex flex-col", children: items[row.index] }, keyOf(row.index)))) })) : (children) }) }), !pinned && hasMessages && (_jsxs("button", { type: "button", onClick: () => {
                             pinnedRef.current = true;
                             setPinned(true);
                             toBottom("smooth");

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./lib/chat.js";
 export * from "./lib/status.js";
 export * from "./lib/use-copy.js";
 export * from "./lib/use-shortcut.js";
+export * from "./lib/use-virtual-list.js";
 export * from "./blocks/terms.js";
 export * from "./blocks/locale.js";
 export * from "./blocks/locked.js";

package/dist/index.js

@@ -2,6 +2,7 @@ export * from "./lib/chat.js";
 export * from "./lib/status.js";
 export * from "./lib/use-copy.js";
 export * from "./lib/use-shortcut.js";
+export * from "./lib/use-virtual-list.js";
 export * from "./blocks/terms.js";
 export * from "./blocks/locale.js";
 export * from "./blocks/locked.js";

package/dist/lib/use-virtual-list.d.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+/** What to render, in order: an item by its index, or a spacer standing in for the items between. */
+export type VirtualRow = {
+    index: number;
+} | {
+    spacer: number;
+    key: string;
+};
+export type VirtualList = {
+    /** The items to render and the spacers between them, in order. */
+    rows: VirtualRow[];
+    /** The ref for every rendered item, which also carries `data-virtual-key={key}`, so its real height is measured and kept. */
+    measure: (el: HTMLElement | null) => void | (() => void);
+};
+/**
+ * Render only the items of a long list that are in or near view, for Thread's and SessionList's `virtualize`.
+ * Items keep their measured heights by key, so a list that grows or reorders keeps its place; unmeasured items count
+ * as `estimate`. Spacers stand in for the rest. `pin` (an item's key) keeps that item rendered (the one holding
+ * focus), on its own if it's far from view, so focus is never lost to an item scrolling away. Until the scroller is
+ * measured (on the server, on the first render in the browser, and while it's hidden) the first or last `initial`
+ * items render, by `anchor`, so server and browser agree.
+ *
+ * Give each rendered item `ref={list.measure}` and `data-virtual-key={key}`.
+ */
+export declare function useVirtualList({ enabled, count, keyOf, scroller, estimate, overscan, initial, anchor, gap, pin, }: {
+    enabled: boolean;
+    count: number;
+    keyOf: (index: number) => React.Key;
+    scroller: React.RefObject<HTMLElement | null>;
+    estimate?: number;
+    overscan?: number;
+    initial?: number;
+    /** Which end to show before the scroller is measured: "end" for a thread (newest last), "start" for a list. Defaults to "end". */
+    anchor?: "start" | "end";
+    /** The gap between items, in pixels, read once the scroller is measured (e.g. from the list's computed `row-gap`). */
+    gap?: () => number;
+    /** The key of an item to keep rendered, such as the one holding focus. */
+    pin?: string | null;
+}): VirtualList;

package/dist/lib/use-virtual-list.js

@@ -0,0 +1,124 @@
+import * as React from "react";
+const keyAttr = "data-virtual-key";
+/**
+ * Render only the items of a long list that are in or near view, for Thread's and SessionList's `virtualize`.
+ * Items keep their measured heights by key, so a list that grows or reorders keeps its place; unmeasured items count
+ * as `estimate`. Spacers stand in for the rest. `pin` (an item's key) keeps that item rendered (the one holding
+ * focus), on its own if it's far from view, so focus is never lost to an item scrolling away. Until the scroller is
+ * measured (on the server, on the first render in the browser, and while it's hidden) the first or last `initial`
+ * items render, by `anchor`, so server and browser agree.
+ *
+ * Give each rendered item `ref={list.measure}` and `data-virtual-key={key}`.
+ */
+export function useVirtualList({ enabled, count, keyOf, scroller, estimate = 96, overscan = 800, initial = 20, anchor = "end", gap = () => 0, pin, }) {
+    const [heights, setHeights] = React.useState(() => new Map());
+    const [viewport, setViewport] = React.useState(null);
+    const gapOf = React.useRef(gap);
+    React.useLayoutEffect(() => {
+        gapOf.current = gap;
+    });
+    // One observer for the rendered items, made when the first one mounts; a changed height re-renders.
+    const observer = React.useRef(null);
+    React.useEffect(() => () => {
+        observer.current?.disconnect();
+        observer.current = null;
+    }, []);
+    const measure = React.useCallback((el) => {
+        if (!el)
+            return;
+        if (typeof ResizeObserver !== "undefined")
+            observer.current ??= new ResizeObserver((entries) => {
+                const found = entries.flatMap((e) => {
+                    const key = e.target.getAttribute(keyAttr);
+                    const h = e.target.offsetHeight;
+                    return key !== null && h > 0 ? [[key, h]] : [];
+                });
+                if (found.length)
+                    setHeights((prev) => (found.every(([k, h]) => prev.get(k) === h) ? prev : new Map([...prev, ...found])));
+            });
+        const ro = observer.current;
+        ro?.observe(el);
+        const key = el.getAttribute(keyAttr);
+        const h = el.offsetHeight;
+        if (key !== null && h > 0)
+            setHeights((prev) => (prev.get(key) === h ? prev : new Map(prev).set(key, h)));
+        // An item that unmounts stops being observed, so it can be collected.
+        return () => ro?.unobserve(el);
+    }, []);
+    React.useLayoutEffect(() => {
+        const el = scroller.current;
+        if (!enabled || !el)
+            return;
+        const pending = { frame: 0 };
+        const read = () => {
+            pending.frame = 0;
+            const g = gapOf.current();
+            setViewport((v) => (v && v.top === el.scrollTop && v.height === el.clientHeight && v.gap === g ? v : { top: el.scrollTop, height: el.clientHeight, gap: g }));
+        };
+        const later = () => {
+            if (!pending.frame)
+                pending.frame = requestAnimationFrame(read);
+        };
+        read();
+        el.addEventListener("scroll", later, { passive: true });
+        const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(later);
+        ro?.observe(el);
+        return () => {
+            el.removeEventListener("scroll", later);
+            ro?.disconnect();
+            cancelAnimationFrame(pending.frame);
+        };
+    }, [enabled, scroller]);
+    if (!enabled)
+        return { rows: Array.from({ length: count }, (_, index) => ({ index })), measure };
+    const g = viewport?.gap ?? 0;
+    const size = (i) => heights.get(String(keyOf(i))) ?? estimate;
+    const tops = [];
+    let y = 0;
+    for (let i = 0; i < count; i++) {
+        tops.push(y);
+        y += size(i) + g;
+    }
+    const total = Math.max(0, y - g);
+    let start;
+    let end;
+    if (!viewport || viewport.height === 0) {
+        start = anchor === "end" ? Math.max(0, count - initial) : 0;
+        end = anchor === "end" ? count : Math.min(count, initial);
+    }
+    else {
+        const lo = viewport.top - overscan;
+        const hi = viewport.top + viewport.height + overscan;
+        start = 0;
+        while (start < count - 1 && tops[start] + size(start) < lo)
+            start++;
+        end = start;
+        while (end < count && tops[end] <= hi)
+            end++;
+        end = Math.max(end, Math.min(count, start + 1));
+    }
+    // The pinned item and its neighbours (so Tab and Shift+Tab reach the next and previous item) render with the window,
+    // or on their own between spacers when they're far from it.
+    let ranges = [[start, end]];
+    const p = pin == null ? -1 : Array.from({ length: count }, (_, i) => i).find((i) => String(keyOf(i)) === pin) ?? -1;
+    if (p >= 0) {
+        const island = [Math.max(0, p - 1), Math.min(count, p + 2)];
+        ranges = island[1] < start ? [island, [start, end]] : island[0] > end ? [[start, end], island] : [[Math.min(start, island[0]), Math.max(end, island[1])]];
+    }
+    // A spacer stands where its items were; the gaps the layout puts beside it account for theirs.
+    const rows = [];
+    let prevEnd = 0;
+    for (const [a, b] of ranges) {
+        if (a > 0) {
+            const height = prevEnd === 0 ? tops[a] - g : tops[a] - (tops[prevEnd - 1] + size(prevEnd - 1)) - 2 * g;
+            if (a > prevEnd)
+                rows.push({ spacer: Math.max(0, height), key: `spacer-${prevEnd}` });
+        }
+        for (let i = a; i < b; i++)
+            rows.push({ index: i });
+        prevEnd = b;
+    }
+    if (prevEnd < count)
+        rows.push({ spacer: Math.max(0, total - tops[prevEnd]), key: `spacer-${prevEnd}` });
+    return { rows, measure };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@candor-ui/react",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Candor UI's free tier as an npm package: React components for agents that do real work, on shadcn/ui and Tailwind 4.",
   "license": "MIT",
   "author": "Methodic LLC",