@candor-ui/react 2.3.0 → 2.5.0

package/README.md

@@ -17,8 +17,8 @@ copy code into their app. If you want to own and edit the source, install with t
 npm install @candor-ui/react
 ```
 
-Needs React 19 and Tailwind CSS 4. Radix, lucide-react, class-variance-authority, clsx, tailwind-merge, the Inter font
-and tw-animate-css come with it.
+Needs React 19 and Tailwind CSS 4. Radix, lucide-react, class-variance-authority, clsx, tailwind-merge and the Inter
+font come with it.
 
 ## Styles (Tailwind 4)
 
@@ -30,7 +30,7 @@ The components are styled with Tailwind classes and Candor's tokens. Import the
 ```
 
 `styles.css` brings Candor's tokens (colours, type scale, radii, shadows, motion), the light, dark and high-contrast
-themes, Inter, tw-animate-css and an `@source` for the package's own files, so Tailwind generates the classes the
+themes, Inter and an `@source` for the package's own files, so Tailwind generates the classes the
 components use even though it skips `node_modules` when scanning your app. If your setup doesn't follow `@source`
 from imported CSS, add it yourself, relative to your CSS file:
 

package/dist/blocks/copy-field.js

@@ -5,7 +5,10 @@ import { cn } from "../lib/utils.js";
 import { useCopy } from "../lib/use-copy.js";
 import { useStrings } from "./locale.js";
 import { motion } from "../lib/motion.js";
-/** The tick or cross after the clipboard write settles. */
+/**
+ * @motion pop:tick After the person copies, a tick (or a cross, if the browser refused the clipboard) pops in on the
+ * button once the browser has answered. Nothing shows before the answer, and under reduced motion it fades in.
+ */
 const tickMotion = motion("copy-field", "tick", "pop");
 /** CopyField's fixed words; override them under `copyField` in LocaleProvider's `strings`. */
 export const copyFieldStrings = {

package/dist/blocks/degraded-panel.js

@@ -5,6 +5,10 @@ import { cn } from "../lib/utils.js";
 import { Button } from "../ui/button.js";
 import { useStrings } from "./locale.js";
 import { motion } from "../lib/motion.js";
+/**
+ * @motion live:busy While a retry is under way, the retry icon turns in place and the button says it is retrying. It
+ * stops when the app ends the retry, and under reduced motion the icon is still.
+ */
 const spinMotion = motion("degraded-panel", "busy", "live", { dur: 1000 });
 /** DegradedPanel's fixed words; override them under `degradedPanel` in LocaleProvider's `strings`. */
 export const degradedPanelStrings = {

package/dist/blocks/locked.js

@@ -5,8 +5,27 @@ import { LockKeyhole } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { Tooltip, TooltipContent, TooltipTrigger } from "../ui/tooltip.js";
 import { motion } from "../lib/motion.js";
-/** A press on the locked control: the reason is emphasised, and under expressive the control shakes. */
+/** The running animation's duration on `el`, in milliseconds (its longest, if there are several); undefined when it can't be read. */
+function animationMs(el) {
+    if (!el || typeof getComputedStyle === "undefined")
+        return undefined;
+    const times = getComputedStyle(el)
+        .animationDuration.split(",")
+        .map((t) => (t.trim().endsWith("ms") ? Number.parseFloat(t) : Number.parseFloat(t) * 1000))
+        .filter((n) => Number.isFinite(n));
+    return times.length ? Math.max(...times) : undefined;
+}
+/**
+ * @motion refuse:refuse A press on a locked control shows the reason it is locked; under the expressive setting the
+ * control also shakes once. The control stays locked and does nothing it would have done unlocked. Nothing plays
+ * until the person presses it.
+ */
 const refuseMotion = motion("locked", "refuse", "refuse");
+/**
+ * @motion tint:reason When the person presses a locked control, its reason changes from muted to full-strength text
+ * so it can be read, and goes back to muted for a moment after the press. Screen readers always have the reason,
+ * whether or not it is shown.
+ */
 const reasonMotion = motion("locked", "reason", "tint", { dur: 200 });
 /**
  * The honest-state rule: a control that cannot be used says why.
@@ -28,10 +47,14 @@ function Locked({ reason, inline = false, children, className, }) {
     const [press, setPress] = React.useState(0);
     const [shaking, setShaking] = React.useState(false);
     const [held, setHeld] = React.useState(false);
+    const box = React.useRef(null);
     React.useEffect(() => {
         if (press === 0)
             return;
-        const shake = window.setTimeout(() => setShaking(false), 400);
+        // The shake ends when its animation does (onAnimationEnd below). This timer is only the fallback for when no
+        // animation runs (motion off, or no Candor CSS), set from the duration the page resolved: a brand's longer shake,
+        // or the speed token, isn't cut short.
+        const shake = window.setTimeout(() => setShaking(false), (animationMs(box.current) ?? 400) + 100);
         const hold = window.setTimeout(() => setHeld(false), 1800);
         return () => {
             window.clearTimeout(shake);
@@ -57,6 +80,9 @@ function Locked({ reason, inline = false, children, className, }) {
                 block(e);
         },
     });
-    return (_jsxs("span", { "data-slot": "locked", "data-pressed": held ? "" : undefined, style: refuseMotion, className: cn("relative inline-flex flex-col items-start gap-1.5", shaking && "cd-refuse", className), children: [inline ? (control) : (_jsxs(Tooltip, { open: shown || held, onOpenChange: setShown, children: [_jsx(TooltipTrigger, { asChild: true, children: control }), _jsx(TooltipContent, { children: reason })] })), _jsxs("span", { id: id, "data-slot": "locked-reason", style: reasonMotion, className: cn("items-center gap-1 text-xs text-muted-foreground cd-tint", inline ? "inline-flex" : "sr-only", held && "text-foreground"), children: [_jsx(LockKeyhole, { "aria-hidden": true, className: "size-3" }), reason] })] }));
+    return (_jsxs("span", { ref: box, "data-slot": "locked", onAnimationEnd: (e) => {
+            if (e.target === e.currentTarget)
+                setShaking(false);
+        }, "data-pressed": held ? "" : undefined, style: refuseMotion, className: cn("relative inline-flex flex-col items-start gap-1.5", shaking && "cd-refuse", className), children: [inline ? (control) : (_jsxs(Tooltip, { open: shown || held, onOpenChange: setShown, children: [_jsx(TooltipTrigger, { asChild: true, children: control }), _jsx(TooltipContent, { children: reason })] })), _jsxs("span", { id: id, "data-slot": "locked-reason", style: reasonMotion, className: cn("items-center gap-1 text-xs text-muted-foreground cd-tint", inline ? "inline-flex" : "sr-only", held && "text-foreground"), children: [_jsx(LockKeyhole, { "aria-hidden": true, className: "size-3" }), reason] })] }));
 }
 export { Locked };

package/dist/blocks/relative-time.js

@@ -80,6 +80,6 @@ function RelativeTime({ date, bare = false, format = "relative", className, }) {
     // A bare time ("2 days") is read aloud without its direction, so a screen reader hears the whole phrase ("2 days ago")
     // while the page keeps the short one. "always" keeps the number ("1 day ago", not "yesterday"), so the spoken words match the shown ones.
     const spoken = bare && format === "relative" && current !== null ? formatRelative(d, new Date(current), { locale: fmt.tag, justNow: t("justNow"), numeric: "always" }) : text;
-    return (_jsx("time", { dateTime: d.toISOString(), title: current === null ? undefined : fmt.date(d, "datetime"), className: className, children: spoken === text ? (text) : (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, children: text }), _jsx("span", { className: "sr-only", children: spoken })] })) }));
+    return (_jsx("time", { "data-slot": "relative-time", dateTime: d.toISOString(), title: current === null ? undefined : fmt.date(d, "datetime"), className: className, children: spoken === text ? (text) : (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, children: text }), _jsx("span", { className: "sr-only", children: spoken })] })) }));
 }
 export { RelativeTime };

package/dist/blocks/status-dot.js

@@ -4,9 +4,16 @@ import { cn } from "../lib/utils.js";
 import { useNow } from "./relative-time.js";
 import { motion, useSettled } from "../lib/motion.js";
 import { runLiveness, STALE_AFTER, useStatusLabel } from "../lib/status.js";
-/** The pulse while a run is heard from. */
+/**
+ * @motion live:live A running or waiting dot pulses only while the run has been heard from within the allowed
+ * silence. Past it, or when the time can't be read, the dot is still rather than claiming the run is alive, and under
+ * reduced motion it is still.
+ */
 const liveMotion = motion("status-dot", "live", "live");
-/** The dot popping into its final colour when the run settles on screen. */
+/**
+ * @motion pop:settle The dot pops into its final colour when a run it was showing as unfinished settles while it is
+ * on screen. A dot that is already settled when it appears is drawn in its colour at once.
+ */
 const settleMotion = motion("status-dot", "settle", "pop");
 const dotColor = {
     idle: "bg-faint-foreground/60",

package/dist/blocks/step-list.js

@@ -5,12 +5,25 @@ import { CircleSlash, Hand, LoaderCircle } from "lucide-react";
 import { cn } from "../lib/utils.js";
 import { motion, useArrived, useSettled } from "../lib/motion.js";
 import { useStatusLabel } from "../lib/status.js";
-/** A step's tick or cross, drawn when its status settles on screen. */
+/**
+ * @motion mark:mark A step's tick or cross is drawn along its path when the step settles while the list is on screen.
+ * Steps that were already settled when the list appeared show their mark at once.
+ */
 const markMotion = motion("step-list", "mark", "mark");
-/** The rail growing to a step that finished on screen. */
+/**
+ * @motion fill:rail The line leading to a step fills in when that step finishes while the list is on screen, never
+ * ahead of it. Lines for steps that were already finished when the list appeared are full at once.
+ */
 const railMotion = motion("step-list", "rail", "fill");
-/** A step added after the list first drew. */
+/**
+ * @motion arrive:arrive A step rises in when the app adds it after the list first drew. The steps the list was drawn
+ * with appear still.
+ */
 const arriveMotion = motion("step-list", "arrive", "arrive");
+/**
+ * @motion live:working A step that is running shows a spinner that turns until the app reports it finished or failed.
+ * Under reduced motion the spinner is still, and the step's status is still written in words.
+ */
 const workingMotion = motion("step-list", "working", "live", { dur: 1000 });
 /** A tick, drawn along its path when `draw` is above zero (and again each time it changes). */
 function Tick({ draw }) {

package/dist/blocks/streaming-text.js

@@ -1,6 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../lib/utils.js";
 import { motion } from "../lib/motion.js";
+/**
+ * @motion live:caret While the text is still streaming in, a caret blinks at its end. It goes when streaming stops,
+ * and under reduced motion it is a still bar.
+ */
 const caretMotion = motion("streaming-text", "caret", "live", { dur: 1000 });
 /**
  * Text that is still arriving. Shows a caret while `streaming`, and announces

package/dist/chat/attachment-preview.d.ts

@@ -22,13 +22,18 @@ export declare function fileIcon(a: Pick<Attachment, "name" | "mediaType">): Luc
 /**
  * A file waiting to be sent, as a chip in the composer: its name, then upload progress, an error, or its size, and a
  * remove button. Images show their preview when the app gives one.
+ *
+ * @motion fill:progress The upload bar under the chip moves from the old reported fraction to the new one as the service
+ * reports it. It is drawn at its first value in place, never grown from empty, and a file with no progress draws no bar.
  */
-declare function AttachmentChip({ attachment: a, onRemove, className, }: {
+declare function AttachmentChip({ attachment: a, onRemove, className, style, }: {
     /** The file, with progress (0–1) while uploading or an error if it failed. */
     attachment: Attachment;
     /** Shows a remove button. */
     onRemove?: ((id: string) => void) | undefined;
     className?: string | undefined;
+    /** Inline style for the chip's outer element, such as a motion chain from `motion()`. */
+    style?: React.CSSProperties | undefined;
 }): React.JSX.Element;
 /**
  * A sent file, as a tile in a message: an image preview when the app supplied one, else an icon for its type, with

package/dist/chat/attachment-preview.js

@@ -56,12 +56,15 @@ const thumbnail = (a) => (a.previewUrl && (a.mediaType ?? "").startsWith("image/
 /**
  * A file waiting to be sent, as a chip in the composer: its name, then upload progress, an error, or its size, and a
  * remove button. Images show their preview when the app gives one.
+ *
+ * @motion fill:progress The upload bar under the chip moves from the old reported fraction to the new one as the service
+ * reports it. It is drawn at its first value in place, never grown from empty, and a file with no progress draws no bar.
  */
-function AttachmentChip({ attachment: a, onRemove, className, }) {
+function AttachmentChip({ attachment: a, onRemove, className, style, }) {
     const t = useStrings("attachmentPreview", attachmentPreviewStrings);
     const fmt = useFormat();
     const thumb = thumbnail(a);
-    return (_jsxs("span", { "data-slot": "attachment-chip", className: cn("relative inline-flex max-w-56 items-center gap-1.5 overflow-hidden rounded-md border bg-card py-1 pe-1 ps-2 text-xs", a.error && "border-destructive/50", className), children: [thumb ? _jsx("img", { src: thumb, alt: "", className: "size-4 shrink-0 rounded-xs object-cover" }) : _jsx(Paperclip, { "aria-hidden": true, className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: a.name }), _jsx("span", { className: cn("shrink-0 tabular-nums", a.error ? "text-destructive-text" : "text-faint-foreground"), children: a.error ? a.error : a.progress !== undefined ? fmt.number(Math.round(a.progress * 100) / 100, { style: "percent" }) : formatFileSize(a.size, fmt.number, t) }), onRemove && (_jsx("button", { type: "button", "aria-label": t("remove", { name: a.name }), onClick: () => onRemove(a.id), className: "relative after:absolute after:-inset-1 rounded-sm p-0.5 text-faint-foreground hover:bg-accent hover:text-foreground", children: _jsx(X, { className: "size-3" }) })), a.progress !== undefined && !a.error && _jsx("span", { "aria-hidden": true, className: "absolute bottom-0 start-0 h-0.5 bg-primary cd-fill", style: { ...progressMotion, width: `${a.progress * 100}%` } })] }));
+    return (_jsxs("span", { "data-slot": "attachment-chip", style: style, className: cn("relative inline-flex max-w-56 items-center gap-1.5 overflow-hidden rounded-md border bg-card py-1 pe-1 ps-2 text-xs", a.error && "border-destructive/50", className), children: [thumb ? _jsx("img", { src: thumb, alt: "", className: "size-4 shrink-0 rounded-xs object-cover" }) : _jsx(Paperclip, { "aria-hidden": true, className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: a.name }), _jsx("span", { className: cn("shrink-0 tabular-nums", a.error ? "text-destructive-text" : "text-faint-foreground"), children: a.error ? a.error : a.progress !== undefined ? fmt.number(Math.round(a.progress * 100) / 100, { style: "percent" }) : formatFileSize(a.size, fmt.number, t) }), onRemove && (_jsx("button", { type: "button", "aria-label": t("remove", { name: a.name }), onClick: () => onRemove(a.id), className: "relative after:absolute after:-inset-1 rounded-sm p-0.5 text-faint-foreground hover:bg-accent hover:text-foreground", children: _jsx(X, { className: "size-3" }) })), a.progress !== undefined && !a.error && _jsx("span", { "aria-hidden": true, className: "absolute bottom-0 start-0 h-0.5 bg-primary cd-fill", style: { ...progressMotion, width: `${a.progress * 100}%` } })] }));
 }
 /**
  * A sent file, as a tile in a message: an image preview when the app supplied one, else an icon for its type, with

package/dist/chat/card-registry.js

@@ -6,6 +6,10 @@ import { DegradedPanel } from "../blocks/degraded-panel.js";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible.js";
 import { useStrings } from "../blocks/locale.js";
 import { motion } from "../lib/motion.js";
+/**
+ * @motion reveal:open The text view opens to its full height when the person asks to see the card as text, and the
+ * chevron turns with it; closing reverses both. Under reduced motion it snaps open or shut.
+ */
 const turnMotion = motion("card-registry", "open", "reveal");
 /** CardRegistry's fixed words; override them under `cardRegistry` in LocaleProvider's `strings`. */
 export const cardRegistryStrings = {
@@ -46,13 +50,13 @@ function Card({ name, props, summary, }) {
     const cards = React.useContext(Registry);
     const def = cards[name];
     if (!def) {
-        return (_jsxs("div", { "data-slot": "card", "data-card": name, "data-state": "unknown", className: "flex flex-col gap-1.5 rounded-lg border border-dashed px-3 py-2.5", children: [_jsxs("p", { className: "flex items-center gap-1.5 text-sm text-muted-foreground", children: [_jsx(LayoutTemplate, { "aria-hidden": true, className: "size-3.5" }), " ", t("unknown", { name })] }), _jsx(Summary, { text: summary })] }));
+        return (_jsxs("div", { "data-slot": "card-registry", "data-card": name, "data-state": "unknown", className: "flex flex-col gap-1.5 rounded-lg border border-dashed px-3 py-2.5", children: [_jsxs("p", { className: "flex items-center gap-1.5 text-sm text-muted-foreground", children: [_jsx(LayoutTemplate, { "aria-hidden": true, className: "size-3.5" }), " ", t("unknown", { name })] }), _jsx(Summary, { text: summary })] }));
     }
     const problem = def.check(props);
     if (problem) {
-        return (_jsxs("div", { "data-slot": "card", "data-card": name, "data-state": "invalid", className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: t("invalid", { label: def.label.toLowerCase(), problem }) }), _jsx(Summary, { text: summary })] }));
+        return (_jsxs("div", { "data-slot": "card-registry", "data-card": name, "data-state": "invalid", className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: t("invalid", { label: def.label.toLowerCase(), problem }) }), _jsx(Summary, { text: summary })] }));
     }
-    return (_jsx("div", { "data-slot": "card", "data-card": name, "data-state": "ready", children: _jsx(CardBoundary, { fallback: _jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: t("failed", { label: def.label.toLowerCase() }) }), _jsx(Summary, { text: summary })] }), children: def.render(props) }) }));
+    return (_jsx("div", { "data-slot": "card-registry", "data-card": name, "data-state": "ready", children: _jsx(CardBoundary, { fallback: _jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(DegradedPanel, { reason: t("failed", { label: def.label.toLowerCase() }) }), _jsx(Summary, { text: summary })] }), children: def.render(props) }) }));
 }
 /* ---------------------------------------------------------------- small checking helpers */
 export const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);

package/dist/chat/citation.d.ts

@@ -28,6 +28,9 @@ declare function SourceDetail({ source, }: {
  * An inline [n]. Opens the source in a popover on click or Enter, so evidence is
  * one step away without leaving the thread. A source the message doesn't list
  * renders as a plain bracket rather than a guess.
+ *
+ * @motion tint:tint A source chip's border and text colour change when the pointer is over it, and a ring fades in
+ * when a citation number or chip takes keyboard focus.
  */
 declare function Citation({ source, marker, }: {
     /** The source this marker points to; without it the marker says it's unknown. */

package/dist/chat/citation.js

@@ -48,13 +48,16 @@ function SourceDetail({ source, }) {
  * An inline [n]. Opens the source in a popover on click or Enter, so evidence is
  * one step away without leaving the thread. A source the message doesn't list
  * renders as a plain bracket rather than a guess.
+ *
+ * @motion tint:tint A source chip's border and text colour change when the pointer is over it, and a ring fades in
+ * when a citation number or chip takes keyboard focus.
  */
 function Citation({ source, marker, }) {
     const t = useStrings("citation", citationStrings);
     if (!source) {
-        return _jsxs("sup", { className: "text-faint-foreground", children: ["[", marker ?? "?", "]"] });
+        return _jsxs("sup", { "data-slot": "citation", className: "text-faint-foreground", children: ["[", marker ?? "?", "]"] });
     }
-    return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx("button", { type: "button", "aria-label": t("sourceLabel", { marker: source.marker, label: source.label }), className: cn("mx-0.5 inline-flex h-4 min-w-4 -translate-y-px items-center justify-center rounded-sm px-1 align-middle text-2xs font-semibold tabular-nums cd-tint outline-none focus-visible:ring-[3px] focus-visible:ring-ring/80", source.provisional
+    return (_jsxs(Popover, { children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx("button", { type: "button", "data-slot": "citation", "aria-label": t("sourceLabel", { marker: source.marker, label: source.label }), className: cn("mx-0.5 inline-flex h-4 min-w-4 -translate-y-px items-center justify-center rounded-sm px-1 align-middle text-2xs font-semibold tabular-nums cd-tint outline-none focus-visible:ring-[3px] focus-visible:ring-ring/80", source.provisional
                         ? "border border-dashed border-provisional/60 text-provisional hover:bg-muted"
                         : "bg-accent-weak text-accent-text hover:bg-primary hover:text-primary-foreground"), children: source.marker }) }), _jsx(PopoverContent, { align: "start", className: "w-80 max-w-[calc(100vw-2rem)] p-3", children: _jsx(SourceDetail, { source: source }) })] }));
 }

package/dist/chat/composer.js

@@ -8,12 +8,25 @@ import { EntityChip, useEntityKinds } from "./entity-chip.js";
 import { AttachmentChip } from "./attachment-preview.js";
 import { useStrings } from "../blocks/locale.js";
 import { motion, useArrived, useLeaving } from "../lib/motion.js";
-/** A chip added after the first draw pops in; a removed one pops out as a ghost. */
+/**
+ * @motion pop:chip A mention or attachment chip pops in when the person adds one while writing, and a chip they
+ * remove pops out. Chips that were there when the composer first drew, such as a restored draft, appear still.
+ */
 const chipMotion = motion("composer", "chip", "pop");
-/** The mention and command menu: 2.2's fade and 4 px rise. */
+/**
+ * @motion overlay:menu The mention and command menu rises a little and fades in above the field when the person types
+ * the character that opens it, and goes at once when it closes. Under reduced motion it is a short fade.
+ */
 const menuMotion = motion("composer", "menu", "overlay", { variant: "slide" });
-/** Send and Stop acknowledge the press: 2.2's scale of 0.95. */
+/**
+ * @motion press:send Send and Stop shrink a little while they are held down and return when let go. A Send that is
+ * disabled never moves, and under reduced motion neither changes size.
+ */
 const sendMotion = motion("composer", "send", "press", { amp: "0.9" });
+/**
+ * @motion live:sending While the app reports that the message is being sent, a spinner turns in place of Send's
+ * arrow. It stops when the app says sending is over, and under reduced motion the spinner is still.
+ */
 const sendingMotion = motion("composer", "sending", "live", { dur: 1000 });
 /** Composer's fixed words; override them under `composer` in LocaleProvider's `strings`. */
 export const composerStrings = {
@@ -218,7 +231,7 @@ function Composer({ value, onChange, onSubmit, onStop, state = "ready", scope, o
                                     e.preventDefault();
                                     choose(item);
                                 }, onMouseMove: () => setActive(i), className: "flex cursor-pointer items-center gap-2.5 rounded-md px-2 py-1.5 text-sm aria-selected:bg-accent", children: item.type === "command" ? (_jsxs(_Fragment, { children: [_jsxs("span", { className: "font-mono text-xs text-accent-text", children: ["/", item.command.name] }), item.command.args && _jsx("span", { className: "font-mono text-xs text-faint-foreground", children: item.command.args }), _jsx("span", { className: "ms-auto truncate text-xs text-muted-foreground", children: item.command.description })] })) : (_jsxs(_Fragment, { children: [_jsx("span", { className: "flex size-6 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground", children: Icon ? _jsx(Icon, { className: "size-3.5" }) : _jsx("span", { className: "text-xs", children: "@" }) }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate", children: item.option.label }), (item.option.description ?? item.option.entity?.name) !== item.option.label && (item.option.description ?? item.option.entity?.name) && (_jsx("span", { className: "block truncate font-mono text-2xs text-faint-foreground", children: item.option.description ?? item.option.entity?.name }))] })] })) })] }, item.type === "command" ? item.command.id : item.option.id));
-                }) })), _jsxs("div", { className: cn("rounded-2xl border bg-card shadow-raised cd-tint focus-within:border-border-strong focus-within:shadow-float", locked && "bg-muted shadow-none"), children: [(references.length > 0 || attachments.length > 0 || referenceMotion.leaving.length > 0 || attachmentMotion.leaving.length > 0) && (_jsxs("div", { className: "flex flex-wrap gap-1.5 px-3 pt-3", children: [references.map((r) => (_jsx("span", { "data-slot": "composer-chip", style: chipMotion, className: cn("inline-flex max-w-full min-w-0", referenceArrived(referenceKey(r)) && "cd-pop"), children: _jsx(EntityChip, { entity: r, onRemove: (e) => onReferencesChange?.(references.filter((x) => x !== e)) }) }, referenceKey(r)))), referenceMotion.leaving.map((r) => (_jsx(LeavingChip, { onDone: () => referenceMotion.left(r), children: _jsx(EntityChip, { entity: r }) }, `leaving:${referenceKey(r)}`))), attachments.map((a) => (_jsx("span", { "data-slot": "composer-chip", style: chipMotion, className: cn("inline-flex max-w-full min-w-0", attachmentArrived(a.id) && "cd-pop"), children: _jsx(AttachmentChip, { attachment: a, onRemove: onRemoveAttachment }) }, a.id))), attachmentMotion.leaving.map((a) => (_jsx(LeavingChip, { onDone: () => attachmentMotion.left(a), children: _jsx(AttachmentChip, { attachment: a }) }, `leaving:${a.id}`)))] })), _jsx("label", { htmlFor: id, className: "sr-only", children: label }), _jsx("textarea", { ref: textarea, id: id, rows: 1, value: value, disabled: Boolean(locked), placeholder: locked ? undefined : placeholder, onChange: (e) => {
+                }) })), _jsxs("div", { className: cn("rounded-2xl border bg-card shadow-raised cd-tint focus-within:border-border-strong focus-within:shadow-float", locked && "bg-muted shadow-none"), children: [(references.length > 0 || attachments.length > 0 || referenceMotion.leaving.length > 0 || attachmentMotion.leaving.length > 0) && (_jsxs("div", { className: "flex flex-wrap gap-1.5 px-3 pt-3", children: [references.map((r) => (_jsx(EntityChip, { entity: r, onRemove: (e) => onReferencesChange?.(references.filter((x) => x !== e)), style: chipMotion, className: cn(referenceArrived(referenceKey(r)) && "cd-pop") }, referenceKey(r)))), referenceMotion.leaving.map((r) => (_jsx(LeavingChip, { onDone: () => referenceMotion.left(r), children: _jsx(EntityChip, { entity: r }) }, `leaving:${referenceKey(r)}`))), attachments.map((a) => (_jsx(AttachmentChip, { attachment: a, onRemove: onRemoveAttachment, style: chipMotion, className: cn(attachmentArrived(a.id) && "cd-pop") }, a.id))), attachmentMotion.leaving.map((a) => (_jsx(LeavingChip, { onDone: () => attachmentMotion.left(a), children: _jsx(AttachmentChip, { attachment: a }) }, `leaving:${a.id}`)))] })), _jsx("label", { htmlFor: id, className: "sr-only", children: label }), _jsx("textarea", { ref: textarea, id: id, rows: 1, value: value, disabled: Boolean(locked), placeholder: locked ? undefined : placeholder, onChange: (e) => {
                             onChange(e.target.value);
                             requestAnimationFrame(syncTrigger);
                         }, onKeyDown: onKeyDown, onKeyUp: (e) => {

package/dist/chat/context-meter.d.ts

@@ -15,6 +15,11 @@ export declare const contextMeterStrings: {
  * Counts are the service's own token counts; the ring warns past 80%. When a
  * new count arrives the ring sweeps to it and changes colour at the warning
  * line; it draws its first value in place, with no sweep from zero.
+ *
+ * @motion fill:fill The ring moves from the old measured value to the new one when the count changes while the meter is
+ * on screen, and changes colour at the warning line. The first value is drawn in place, never swept from empty.
+ * @motion value:value The percentage beside the ring crossfades to the new figure in the quick duration when the count
+ * changes while the meter is on screen; it never counts through values that were not measured.
  */
 declare function ContextMeter({ segments, limit, className, }: {
     /** What fills the context window, by kind, in tokens. */

package/dist/chat/context-meter.js

@@ -4,9 +4,13 @@ import * as React from "react";
 import { cn } from "../lib/utils.js";
 import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover.js";
 import { useFormat, useStrings } from "../blocks/locale.js";
-import { motion } from "../lib/motion.js";
+import { motion, useSettled } from "../lib/motion.js";
 /** The ring moving to a new measured value, after the first one was drawn in place. */
 const fillMotion = motion("context-meter", "fill", "fill");
+/** The percentage changing in place. */
+const valueMotion = motion("context-meter", "value", "value");
+/** Every new figure counts as a change worth showing. */
+const changed = { settled: () => true, over: () => false };
 /** ContextMeter's fixed words; override them under `contextMeter` in LocaleProvider's `strings`. */
 export const contextMeterStrings = {
     /** A token count in thousands; `{n}` is already formatted. */
@@ -36,6 +40,11 @@ function k(n, format, thousands) {
  * Counts are the service's own token counts; the ring warns past 80%. When a
  * new count arrives the ring sweeps to it and changes colour at the warning
  * line; it draws its first value in place, with no sweep from zero.
+ *
+ * @motion fill:fill The ring moves from the old measured value to the new one when the count changes while the meter is
+ * on screen, and changes colour at the warning line. The first value is drawn in place, never swept from empty.
+ * @motion value:value The percentage beside the ring crossfades to the new figure in the quick duration when the count
+ * changes while the meter is on screen; it never counts through values that were not measured.
  */
 function ContextMeter({ segments, limit, className, }) {
     const t = useStrings("contextMeter", contextMeterStrings);
@@ -49,7 +58,9 @@ function ContextMeter({ segments, limit, className, }) {
     // The sweep is a transition, so it runs only for a value that changed after the first one was drawn.
     const [drawn, setDrawn] = React.useState(false);
     React.useEffect(() => setDrawn(true), []);
-    return (_jsxs(Popover, { children: [_jsxs(PopoverTrigger, { "aria-label": t("label", { used: tokens(used), limit: tokens(limit) }), "data-warn": warn ? "" : undefined, className: cn("inline-flex items-center gap-1.5 rounded-md px-1.5 py-1 text-2xs tabular-nums outline-none hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80", warn ? "text-warning-text" : "text-muted-foreground", className), children: [_jsxs("svg", { viewBox: "0 0 18 18", className: "size-4 -rotate-90", "aria-hidden": true, children: [_jsx("circle", { cx: "9", cy: "9", r: r, fill: "none", stroke: "var(--muted)", strokeWidth: "2.5" }), _jsx("circle", { "data-slot": "context-meter-ring", cx: "9", cy: "9", r: r, fill: "none", stroke: warn ? "var(--warning)" : "var(--primary)", strokeWidth: "2.5", strokeDasharray: `${pct * c} ${c}`, strokeLinecap: "round", style: fillMotion, className: cn(drawn && "cd-fill") })] }), fmt.number(Math.round(pct * 100) / 100, { style: "percent" })] }), _jsxs(PopoverContent, { align: "start", className: "w-72 p-3", children: [_jsxs("p", { className: "flex items-baseline justify-between text-sm font-medium", children: [t("context"), " ", _jsx("span", { className: "text-xs font-normal text-muted-foreground tabular-nums", children: t("usage", { used: tokens(used), limit: tokens(limit) }) })] }), _jsx("div", { "aria-hidden": true, className: "mt-2 flex h-2 overflow-hidden rounded-full bg-muted", children: segments.map((s) => (_jsx("span", { style: { width: `${(s.tokens / limit) * 100}%`, background: kindColor[s.kind] } }, s.label))) }), _jsx("ul", { className: "mt-3 flex flex-col gap-1.5", children: [...segments]
+    const percent = fmt.number(Math.round(pct * 100) / 100, { style: "percent" });
+    const percentChanges = useSettled(percent, changed);
+    return (_jsxs(Popover, { children: [_jsxs(PopoverTrigger, { "data-slot": "context-meter", "aria-label": t("label", { used: tokens(used), limit: tokens(limit) }), "data-warn": warn ? "" : undefined, className: cn("inline-flex items-center gap-1.5 rounded-md px-1.5 py-1 text-2xs tabular-nums outline-none hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80", warn ? "text-warning-text" : "text-muted-foreground", className), children: [_jsxs("svg", { viewBox: "0 0 18 18", className: "size-4 -rotate-90", "aria-hidden": true, children: [_jsx("circle", { cx: "9", cy: "9", r: r, fill: "none", stroke: "var(--muted)", strokeWidth: "2.5" }), _jsx("circle", { "data-slot": "context-meter-ring", cx: "9", cy: "9", r: r, fill: "none", stroke: warn ? "var(--warning)" : "var(--primary)", strokeWidth: "2.5", strokeDasharray: `${pct * c} ${c}`, strokeLinecap: "round", style: fillMotion, className: cn(drawn && "cd-fill") })] }), percentChanges > 0 ? (_jsx("span", { style: valueMotion, className: "cd-value", children: percent }, percentChanges)) : (percent)] }), _jsxs(PopoverContent, { align: "start", className: "w-72 p-3", children: [_jsxs("p", { className: "flex items-baseline justify-between text-sm font-medium", children: [t("context"), " ", _jsx("span", { className: "text-xs font-normal text-muted-foreground tabular-nums", children: t("usage", { used: tokens(used), limit: tokens(limit) }) })] }), _jsx("div", { "aria-hidden": true, className: "mt-2 flex h-2 overflow-hidden rounded-full bg-muted", children: segments.map((s) => (_jsx("span", { style: { width: `${(s.tokens / limit) * 100}%`, background: kindColor[s.kind] } }, s.label))) }), _jsx("ul", { className: "mt-3 flex flex-col gap-1.5", children: [...segments]
                             .sort((a, b) => b.tokens - a.tokens)
                             .map((s) => (_jsxs("li", { className: "flex items-center gap-2 text-xs", children: [_jsx("span", { "aria-hidden": true, className: "size-2 rounded-xs", style: { background: kindColor[s.kind] } }), _jsx("span", { className: "flex-1", children: s.label }), _jsx("span", { className: "text-muted-foreground tabular-nums", children: tokens(s.tokens) })] }, s.label))) }), warn && _jsx("p", { className: "mt-3 text-xs text-warning-text", children: t("nearlyFull") })] })] }));
 }

package/dist/chat/entity-chip.d.ts

@@ -43,8 +43,11 @@ declare function useEntityKinds(): (kind: string) => EntityKindInfo;
  * so "Account" the table and "Account" the report never read alike. The
  * identifier is the label unless a friendlier one is given; then the
  * identifier is on hover and for screen readers.
+ *
+ * @motion tint:tint A chip that can be pressed changes its border and background when the pointer is over it, and a
+ * ring fades in on keyboard focus. A chip that can't be pressed does not change.
  */
-declare function EntityChip({ entity, onOpen, onRemove, className, }: {
+declare function EntityChip({ entity, onOpen, onRemove, className, style, }: {
     /** The thing to show: its kind, identifier and optional label. */
     entity: EntityRef;
     /** Makes the chip a button that opens the thing. */
@@ -52,5 +55,7 @@ declare function EntityChip({ entity, onOpen, onRemove, className, }: {
     /** Adds a remove button, e.g. in the composer. */
     onRemove?: ((entity: EntityRef) => void) | undefined;
     className?: string | undefined;
+    /** Inline style for the chip's outer element, such as a motion chain from `motion()`. */
+    style?: React.CSSProperties | undefined;
 }): React.JSX.Element;
 export { EntityChip, EntityKindsProvider, useEntityKinds };

package/dist/chat/entity-chip.js

@@ -71,8 +71,11 @@ function useEntityKinds() {
  * so "Account" the table and "Account" the report never read alike. The
  * identifier is the label unless a friendlier one is given; then the
  * identifier is on hover and for screen readers.
+ *
+ * @motion tint:tint A chip that can be pressed changes its border and background when the pointer is over it, and a
+ * ring fades in on keyboard focus. A chip that can't be pressed does not change.
  */
-function EntityChip({ entity, onOpen, onRemove, className, }) {
+function EntityChip({ entity, onOpen, onRemove, className, style, }) {
     const { Icon, noun } = useEntityKinds()(entity.kind);
     const t = useStrings("entityChip", entityChipStrings);
     const shown = entity.label ?? entity.name;
@@ -81,6 +84,6 @@ function EntityChip({ entity, onOpen, onRemove, className, }) {
         : t("title", { noun, name: entity.name });
     const body = (_jsxs(_Fragment, { children: [_jsx(Icon, { "aria-hidden": true, className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: shown }), _jsxs("span", { className: "sr-only", children: [" (", title, ")"] })] }));
     const base = "inline-flex max-w-full items-center gap-1 rounded-sm border bg-card px-1.5 py-px align-baseline font-mono text-[0.92em] leading-[1.35] text-foreground";
-    return (_jsxs("span", { "data-slot": "entity-chip", "data-kind": entity.kind, title: title, className: cn("inline-flex max-w-full min-w-0 items-center sm:max-w-64", className), children: [onOpen ? (_jsx("button", { type: "button", onClick: () => onOpen(entity), className: cn(base, "cursor-pointer cd-tint hover:border-border-strong hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80 outline-none"), children: body })) : (_jsx("span", { className: base, children: body })), onRemove && (_jsx("button", { type: "button", "aria-label": t("remove", { name: shown }), onClick: () => onRemove(entity), className: "relative after:absolute after:-inset-1 -ms-px rounded-e-sm border border-s-0 bg-card px-1 py-px text-faint-foreground hover:text-foreground", children: "\u00D7" }))] }));
+    return (_jsxs("span", { "data-slot": "entity-chip", "data-kind": entity.kind, title: title, style: style, className: cn("inline-flex max-w-full min-w-0 items-center sm:max-w-64", className), children: [onOpen ? (_jsx("button", { type: "button", onClick: () => onOpen(entity), className: cn(base, "cursor-pointer cd-tint hover:border-border-strong hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80 outline-none"), children: body })) : (_jsx("span", { className: base, children: body })), onRemove && (_jsx("button", { type: "button", "aria-label": t("remove", { name: shown }), onClick: () => onRemove(entity), className: "relative after:absolute after:-inset-1 -ms-px rounded-e-sm border border-s-0 bg-card px-1 py-px text-faint-foreground hover:text-foreground", children: "\u00D7" }))] }));
 }
 export { EntityChip, EntityKindsProvider, useEntityKinds };

package/dist/chat/folded-turns.js

@@ -6,6 +6,10 @@ import { cn } from "../lib/utils.js";
 import { useStrings } from "../blocks/locale.js";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible.js";
 import { motion } from "../lib/motion.js";
+/**
+ * @motion reveal:open The folded turns open to their full height when the person presses the summary, with its
+ * chevron turning, and close the same way. Under reduced motion they snap open or shut.
+ */
 const turnMotion = motion("folded-turns", "open", "reveal");
 /** FoldedTurns' fixed words; override them under `foldedTurns` in LocaleProvider's `strings`. */
 export const foldedTurnsStrings = {

package/dist/chat/message-actions.js

@@ -7,7 +7,10 @@ import { useCopy } from "../lib/use-copy.js";
 import { Tooltip, TooltipContent, TooltipTrigger } from "../ui/tooltip.js";
 import { useStrings } from "../blocks/locale.js";
 import { motion } from "../lib/motion.js";
-/** The tick or cross after the clipboard write settles. */
+/**
+ * @motion pop:tick After the person copies, a tick (or a cross, if the browser refused the clipboard) pops in on the
+ * button once the browser has answered. Nothing shows before the answer, and under reduced motion it fades in.
+ */
 const tickMotion = motion("message-actions", "tick", "pop");
 /** MessageActions' fixed words; override them under `messageActions` in LocaleProvider's `strings`. */
 export const messageActionsStrings = {

package/dist/chat/message.js

@@ -12,8 +12,15 @@ import { Reasoning } from "./reasoning.js";
 import { ThreadEvent } from "./thread-event.js";
 import { useStrings } from "../blocks/locale.js";
 import { motion } from "../lib/motion.js";
-/** A message that arrived after the thread first drew rises in (Thread marks it `data-arrived`); loaded history is still. */
+/**
+ * @motion arrive:arrive A message rises in when it is added to a Thread after the thread first drew, whether it is
+ * the person's or the agent's. Messages loaded with the thread, and a Message outside a Thread, are drawn still.
+ */
 const arriveMotion = motion("message", "arrive", "arrive");
+/**
+ * @motion live:caret While a reply is still streaming, a caret blinks at the end of its text. It goes when the reply
+ * finishes or is interrupted, and under reduced motion it is a still bar.
+ */
 const caretMotion = motion("message", "caret", "live", { dur: 1000 });
 /** Message's fixed words; override them under `message` in LocaleProvider's `strings`. */
 export const messageStrings = {

package/dist/chat/payload.d.ts

@@ -16,6 +16,9 @@ export declare const payloadStrings: {
  *
  * Code is split into tokens (keywords, strings, comments…) rendered as spans of text, never as HTML. They're coloured
  * when `highlight` is set, or anywhere under `data-syntax="highlight"` (set it on `<html>` for the whole app).
+ *
+ * @motion tint:tint The copy button's background and text colour change when the pointer is over it, and a ring fades
+ * in when it takes keyboard focus.
  */
 declare function Payload({ language, text, title, bare, highlight, className, }: {
     /** Shown as the label, e.g. json, sql, python. Never executed or highlighted as HTML. */

package/dist/chat/payload.js

@@ -32,6 +32,9 @@ const languageLabel = (lang, t) => {
  *
  * Code is split into tokens (keywords, strings, comments…) rendered as spans of text, never as HTML. They're coloured
  * when `highlight` is set, or anywhere under `data-syntax="highlight"` (set it on `<html>` for the whole app).
+ *
+ * @motion tint:tint The copy button's background and text colour change when the pointer is over it, and a ring fades
+ * in when it takes keyboard focus.
  */
 function Payload({ language, text, title, bare = false, highlight, className, }) {
     const { state, copy } = useCopy();

package/dist/chat/permission-prompt.d.ts

@@ -113,6 +113,11 @@ export type PermissionAnswer = {
  * nothing else is ever counted as a denial. While the decision waits, its shield pulses slowly; a press on inert
  * space outside it (the gesture that would dismiss a dialog) nudges it instead, so the person sees it is still
  * waiting. Both stop once the answer is being sent.
+ *
+ * @motion attention:waiting While the decision waits, a ring pulses out from the shield three times and then is still.
+ * It stops once the answer is being sent, and under calm it is one ring that fades.
+ * @motion attention:nudge A press on inert space outside the prompt rings it once, so the person sees it is still waiting.
+ * @motion refuse:nudge Under expressive the same press also shakes the prompt a little; nothing is dismissed.
  */
 declare function PermissionPrompt({ request, mode, suggestions, editable, onAllow, onDeny, busy, className, }: {
     /** The waiting request. */