@candor-ui/react 2.2.0 → 2.4.0

package/dist/chat/thread.js

@@ -5,6 +5,23 @@ 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";
+import { motion, useMotionAllowed } from "../lib/motion.js";
+/** The smooth scroll to the latest message. */
+const scrollMotion = motion("thread", "scroll", "move");
+/** Jump to latest appearing while the reader is scrolled up: 2.2's 150 ms and 4 px rise. */
+/** How long the animations running on `el` take in all, in milliseconds (the longest of duration × iteration count, capped at 6 s); undefined when it can't be read. */
+function animationMs(el) {
+    if (!el || typeof getComputedStyle === "undefined")
+        return undefined;
+    const style = getComputedStyle(el);
+    const durations = style.animationDuration.split(",").map((t) => (t.trim().endsWith("ms") ? Number.parseFloat(t) : Number.parseFloat(t) * 1000));
+    const counts = style.animationIterationCount.split(",").map((c) => (c.trim() === "infinite" ? Number.POSITIVE_INFINITY : Number.parseFloat(c)));
+    const totals = durations.map((d, i) => d * (counts[i % counts.length] || 1)).filter((n) => Number.isFinite(n) || n === Number.POSITIVE_INFINITY);
+    return totals.length ? Math.min(6000, Math.max(...totals)) : undefined;
+}
+const jumpMotion = motion("thread", "jump", "arrive", { dur: 150 });
+/** Its ring when a message arrives while the reader is scrolled up. */
+const arrivalMotion = motion("thread", "arrival", "attention");
 /** Thread's fixed words; override them under `thread` in LocaleProvider's `strings`. */
 export const threadStrings = {
     messages: "Messages",
@@ -37,19 +54,21 @@ function Thread({ children, empty, footer, className, contentClassName, virtuali
     const pinnedRef = React.useRef(!anchoring);
     const [pinned, setPinned] = React.useState(!anchoring);
     React.useImperativeHandle(scrollerRef, () => scroller.current, []);
+    // A smooth jump only when nothing asks for stillness: the OS setting (the calm level), data-motion="calm" or "none"
+    // around the thread, or a brand that turned the scroll off.
+    const smooth = useMotionAllowed(scroller, scrollMotion);
     const toBottom = React.useCallback((behavior = "auto") => {
         const el = scroller.current;
         if (!el)
             return;
-        // A smooth jump only when nothing asks for stillness: the OS setting, or data-motion="none" around the thread.
-        const still = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches || el.closest('[data-motion="none"]') !== null;
-        el.scrollTo({ top: el.scrollHeight, behavior: still ? "auto" : behavior });
-    }, []);
+        el.scrollTo({ top: el.scrollHeight, behavior: smooth() ? behavior : "auto" });
+    }, [smooth]);
     // A new message while the reader is scrolled up: the Jump to latest control pulses once for each arrival, even when
     // the messages sit inside a wrapper component or a fragment. A second arrival while it still pulses restarts it.
     const [arrived, setArrived] = React.useState(false);
     const arrivedRef = React.useRef(false);
     const frame = React.useRef(0);
+    const jump = React.useRef(null);
     React.useEffect(() => {
         arrivedRef.current = arrived;
     }, [arrived]);
@@ -98,8 +117,11 @@ function Thread({ children, empty, footer, className, contentClassName, virtuali
             const had = new Set(before);
             const survivors = before.filter((node) => node.isConnected);
             const added = known.filter((node) => !had.has(node));
-            const atTheEnd = added.some((node) => survivors.every((old) => old.compareDocumentPosition(node) & Node.DOCUMENT_POSITION_FOLLOWING));
-            if (atTheEnd)
+            const arrivals = added.filter((node) => survivors.every((old) => old.compareDocumentPosition(node) & Node.DOCUMENT_POSITION_FOLLOWING));
+            // A message that arrived after the thread first drew rises in (Message reads data-arrived); loaded history is still.
+            for (const node of arrivals)
+                node.setAttribute("data-arrived", "");
+            if (arrivals.length)
                 arrive();
         });
         observer.observe(el, { childList: true, subtree: true });
@@ -108,7 +130,10 @@ function Thread({ children, empty, footer, className, contentClassName, virtuali
     React.useEffect(() => {
         if (!arrived)
             return;
-        const timer = window.setTimeout(() => setArrived(false), 1000);
+        // The ring ends when its animation does (onAnimationEnd on the button). This timer is only the fallback for when
+        // no animation runs (motion off, or no Candor CSS), set from the duration and count the page resolved, so a brand's
+        // longer ring isn't cut short.
+        const timer = window.setTimeout(() => setArrived(false), (animationMs(jump.current) ?? 1200) + 100);
         return () => window.clearTimeout(timer);
     }, [arrived]);
     // Open at the anchor once, when it first appears.
@@ -177,10 +202,13 @@ function Thread({ children, empty, footer, className, contentClassName, virtuali
                             }
                             : undefined, onBlur: virtualize ? (e) => !e.currentTarget.contains(e.relatedTarget) && setFocused(null) : undefined, className: "h-full scroll-pb-14 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 && (
                     // The entrance is the wrapper's, so the pulse on the button never replays it.
-                    _jsx("span", { className: "absolute bottom-3 left-1/2 z-10 -translate-x-1/2 animate-in fade-in-0 slide-in-from-bottom-1", children: _jsxs("button", { type: "button", "data-slot": "thread-jump", "data-arrived": arrived ? "" : undefined, onClick: () => {
+                    _jsx("span", { style: jumpMotion, className: "absolute bottom-3 left-1/2 z-10 -translate-x-1/2 cd-arrive", children: _jsxs("button", { type: "button", ref: jump, "data-slot": "thread-jump", onAnimationEnd: (e) => {
+                                if (e.target === e.currentTarget && e.animationName.startsWith("cd-"))
+                                    setArrived(false);
+                            }, "data-arrived": arrived ? "" : undefined, onClick: () => {
                                 pinnedRef.current = true;
                                 setPinned(true);
                                 toBottom("smooth");
-                            }, className: cn("inline-flex items-center gap-1.5 rounded-full border bg-popover px-3 py-1.5 text-xs font-medium shadow-float [--cd-attention-color:var(--primary)]", arrived && "animate-attention"), children: [_jsx(ArrowDown, { "aria-hidden": true, className: "size-3" }), " ", t("jumpToLatest")] }) })), fade && _jsx("div", { "aria-hidden": true, "data-slot": "thread-fade", className: "pointer-events-none absolute inset-x-0 bottom-0 h-6 bg-gradient-to-t from-background to-transparent" })] }), footer && _jsx("div", { className: "mx-auto w-full max-w-(--cd-thread-width) px-4 pb-4", children: footer })] }));
+                            }, style: arrivalMotion, className: cn("inline-flex items-center gap-1.5 rounded-full border bg-popover px-3 py-1.5 text-xs font-medium shadow-float [--cd-attention-color:var(--primary)]", arrived && "cd-attention"), children: [_jsx(ArrowDown, { "aria-hidden": true, className: "size-3" }), " ", t("jumpToLatest")] }) })), fade && _jsx("div", { "aria-hidden": true, "data-slot": "thread-fade", className: "pointer-events-none absolute inset-x-0 bottom-0 h-6 bg-gradient-to-t from-background to-transparent" })] }), footer && _jsx("div", { className: "mx-auto w-full max-w-(--cd-thread-width) px-4 pb-4", children: footer })] }));
 }
 export { Thread };

package/dist/chat/tool-call.js

@@ -9,6 +9,10 @@ import { useStatusLabel } from "../lib/status.js";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible.js";
 import { Payload } from "./payload.js";
 import { useStrings } from "../blocks/locale.js";
+import { motion } from "../lib/motion.js";
+/** A call's detail opening, and a group of calls. */
+const openMotion = motion("tool-call", "open", "reveal");
+const groupMotion = motion("tool-call", "group-open", "reveal");
 /** ToolCall's fixed words; override them under `toolCall` in LocaleProvider's `strings`. */
 export const toolCallStrings = {
     input: "Input",
@@ -35,7 +39,7 @@ function ToolCall({ call, className, }) {
     const failed = call.status === "failed";
     const [open, setOpen] = React.useState(failed);
     const hasDetail = Boolean(call.input || call.output || call.error || call.approval?.note || call.approval?.originalInput);
-    return (_jsxs(Collapsible, { open: open, onOpenChange: setOpen, "data-slot": "tool-call", "data-status": call.status, className: cn("group/tool", className), children: [_jsxs(CollapsibleTrigger, { disabled: !hasDetail, className: "flex w-full items-center gap-2.5 rounded-md px-1.5 py-1 text-start outline-none transition-colors duration-150 enabled:hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80", children: [_jsx(StepMark, { status: call.status }), _jsxs("span", { className: "min-w-0 flex-1 truncate text-sm", children: [call.status === "running" ? _jsx(ShimmerLabel, { className: "font-normal", children: call.title }) : call.title, _jsxs("span", { className: "sr-only", children: [" \u2014 ", statusLabel(call.status)] })] }), call.approval?.originalInput !== undefined && (_jsx("span", { "data-slot": "tool-call-edited", className: "shrink-0 rounded-xs bg-warning-weak px-1 text-2xs text-warning-text", children: t("editedBeforeRun") })), call.approval?.by === "automatic" && (_jsx("span", { "data-slot": "tool-call-approval", className: "shrink-0 rounded-xs bg-muted px-1 text-2xs text-muted-foreground", children: t("approvedAutomatically") })), _jsx("code", { className: "hidden shrink-0 font-mono text-2xs text-faint-foreground sm:inline", children: call.tool }), call.duration && _jsx("span", { className: "shrink-0 text-xs tabular-nums text-faint-foreground", children: call.duration }), hasDetail && (_jsx(ChevronRight, { "aria-hidden": true, className: "rtl:-scale-x-100 size-3.5 shrink-0 text-faint-foreground transition-transform duration-200 ease-standard group-data-[state=open]/tool:[transform:rotate(90deg)]" }))] }), _jsx(CollapsibleContent, { children: _jsxs("div", { className: "mt-1 mb-2 ms-[1.375rem] flex flex-col gap-2 border-s ps-3.5", children: [call.error && (_jsx("p", { className: "rounded-md bg-destructive-weak px-2.5 py-1.5 text-xs text-destructive-text", children: call.error })), call.approval?.note && (_jsxs("p", { className: "text-xs text-muted-foreground", children: [call.approval.by === "automatic" ? t("approvedAutomatically") : t("approvedByPerson"), ": ", call.approval.note] })), call.approval?.originalInput !== undefined && _jsx("p", { className: "text-xs text-muted-foreground", children: t("editedNote") }), call.input && _jsx(Payload, { language: "json", title: t("input"), text: call.input }), call.approval?.originalInput !== undefined && _jsx(Payload, { language: "json", title: t("proposed"), text: call.approval.originalInput }), call.output && _jsx(Payload, { language: call.outputLanguage ?? "text", title: t("output"), text: call.output })] }) })] }));
+    return (_jsxs(Collapsible, { open: open, onOpenChange: setOpen, "data-slot": "tool-call", "data-status": call.status, className: cn("group/tool", className), children: [_jsxs(CollapsibleTrigger, { disabled: !hasDetail, className: "flex w-full items-center gap-2.5 rounded-md px-1.5 py-1 text-start outline-none cd-tint enabled:hover:bg-accent focus-visible:ring-[3px] focus-visible:ring-ring/80", children: [_jsx(StepMark, { status: call.status }), _jsxs("span", { className: "min-w-0 flex-1 truncate text-sm", children: [call.status === "running" ? _jsx(ShimmerLabel, { className: "font-normal", children: call.title }) : call.title, _jsxs("span", { className: "sr-only", children: [" \u2014 ", statusLabel(call.status)] })] }), call.approval?.originalInput !== undefined && (_jsx("span", { "data-slot": "tool-call-edited", className: "shrink-0 rounded-xs bg-warning-weak px-1 text-2xs text-warning-text", children: t("editedBeforeRun") })), call.approval?.by === "automatic" && (_jsx("span", { "data-slot": "tool-call-approval", className: "shrink-0 rounded-xs bg-muted px-1 text-2xs text-muted-foreground", children: t("approvedAutomatically") })), _jsx("code", { className: "hidden shrink-0 font-mono text-2xs text-faint-foreground sm:inline", children: call.tool }), call.duration && _jsx("span", { className: "shrink-0 text-xs tabular-nums text-faint-foreground", children: call.duration }), hasDetail && (_jsx(ChevronRight, { "aria-hidden": true, style: openMotion, className: "rtl:-scale-x-100 size-3.5 shrink-0 text-faint-foreground cd-reveal-turn group-data-[state=open]/tool:[transform:rotate(90deg)]" }))] }), _jsx(CollapsibleContent, { style: openMotion, children: _jsxs("div", { className: "mt-1 mb-2 ms-[1.375rem] flex flex-col gap-2 border-s ps-3.5", children: [call.error && (_jsx("p", { className: "rounded-md bg-destructive-weak px-2.5 py-1.5 text-xs text-destructive-text", children: call.error })), call.approval?.note && (_jsxs("p", { className: "text-xs text-muted-foreground", children: [call.approval.by === "automatic" ? t("approvedAutomatically") : t("approvedByPerson"), ": ", call.approval.note] })), call.approval?.originalInput !== undefined && _jsx("p", { className: "text-xs text-muted-foreground", children: t("editedNote") }), call.input && _jsx(Payload, { language: "json", title: t("input"), text: call.input }), call.approval?.originalInput !== undefined && _jsx(Payload, { language: "json", title: t("proposed"), text: call.approval.originalInput }), call.output && _jsx(Payload, { language: call.outputLanguage ?? "text", title: t("output"), text: call.output })] }) })] }));
 }
 /** A run of tool calls, with a count when it's long enough to fold. */
 function ToolCallGroup({ calls, className, }) {
@@ -47,6 +51,6 @@ function ToolCallGroup({ calls, className, }) {
     if (calls.length <= 2) {
         return (_jsx("div", { "data-slot": "tool-call-group", className: cn("flex flex-col", className), children: calls.map((c) => (_jsx(ToolCall, { call: c }, c.id))) }));
     }
-    return (_jsxs(Collapsible, { open: open, onOpenChange: setOpen, "data-slot": "tool-call-group", className: cn("group/tools rounded-lg border bg-card", className), children: [_jsxs(CollapsibleTrigger, { className: "flex w-full items-center gap-2 px-3 py-2 text-start text-xs text-muted-foreground outline-none hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/80 rounded-lg", children: [_jsx(Wrench, { "aria-hidden": true, className: "size-3.5" }), _jsxs("span", { className: "flex-1", children: [t("calls", { count: calls.length }), done > 0 && ` · ${t("done", { count: done })}`, failed > 0 && _jsxs("span", { className: "text-destructive-text", children: [" \u00B7 ", t("failed", { count: failed })] }), running && ` · ${t("working")}`] }), _jsx(ChevronRight, { "aria-hidden": true, className: "rtl:-scale-x-100 size-3.5 transition-transform duration-200 ease-standard group-data-[state=open]/tools:[transform:rotate(90deg)]" })] }), _jsx(CollapsibleContent, { children: _jsx("div", { className: "flex flex-col border-t px-1.5 py-1.5", children: calls.map((c) => (_jsx(ToolCall, { call: c }, c.id))) }) })] }));
+    return (_jsxs(Collapsible, { open: open, onOpenChange: setOpen, "data-slot": "tool-call-group", className: cn("group/tools rounded-lg border bg-card", className), children: [_jsxs(CollapsibleTrigger, { className: "flex w-full items-center gap-2 px-3 py-2 text-start text-xs text-muted-foreground outline-none hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/80 rounded-lg", children: [_jsx(Wrench, { "aria-hidden": true, className: "size-3.5" }), _jsxs("span", { className: "flex-1", children: [t("calls", { count: calls.length }), done > 0 && ` · ${t("done", { count: done })}`, failed > 0 && _jsxs("span", { className: "text-destructive-text", children: [" \u00B7 ", t("failed", { count: failed })] }), running && ` · ${t("working")}`] }), _jsx(ChevronRight, { "aria-hidden": true, style: groupMotion, className: "rtl:-scale-x-100 size-3.5 cd-reveal-turn group-data-[state=open]/tools:[transform:rotate(90deg)]" })] }), _jsx(CollapsibleContent, { style: groupMotion, children: _jsx("div", { className: "flex flex-col border-t px-1.5 py-1.5", children: calls.map((c) => (_jsx(ToolCall, { call: c }, c.id))) }) })] }));
 }
 export { ToolCall, ToolCallGroup };

package/dist/index.d.ts

@@ -43,6 +43,15 @@ export * from "./lib/render-prop.js";
 export * from "./chat/ai-disclosure.js";
 export * from "./chat/permission-prompt.js";
 export * from "./lib/mcp-input.js";
+export * from "./lib/motion.js";
+export * from "./ui/label.js";
+export * from "./ui/checkbox.js";
+export * from "./ui/switch.js";
+export * from "./ui/slider.js";
+export * from "./ui/progress.js";
+export * from "./ui/alert.js";
+export * from "./ui/accordion.js";
+export * from "./lib/sound.js";
 export * from "./lib/utils.js";
 export { ToolCall } from "./chat/tool-call.js";
 export type { ToolCall as ToolCallData } from "./lib/chat.js";

package/dist/index.js

@@ -43,6 +43,15 @@ export * from "./lib/render-prop.js";
 export * from "./chat/ai-disclosure.js";
 export * from "./chat/permission-prompt.js";
 export * from "./lib/mcp-input.js";
+export * from "./lib/motion.js";
+export * from "./ui/label.js";
+export * from "./ui/checkbox.js";
+export * from "./ui/switch.js";
+export * from "./ui/slider.js";
+export * from "./ui/progress.js";
+export * from "./ui/alert.js";
+export * from "./ui/accordion.js";
+export * from "./lib/sound.js";
 export * from "./lib/utils.js";
 export { ToolCall } from "./chat/tool-call.js";
 export { Message } from "./chat/message.js";

package/dist/lib/motion.d.ts

@@ -0,0 +1,466 @@
+import * as React from "react";
+import type { RunStatus } from "./status.js";
+/**
+ * Candor's motion layer, the part that runs in components. Motion is organised by fourteen families, one per kind of
+ * change; each component moment (copy-field's tick, the dialog opening) belongs to one family and can be tuned on its
+ * own by a brand file. The rule the layer keeps: **a theme tunes how a change looks, never when it happens**. The
+ * trigger stays in the component (a class added at an honest moment); this file only builds the chain of CSS
+ * variables the family utility in `candor.css` reads, and the two hooks that decide "seen settling" and "arrived after
+ * the first draw".
+ *
+ * Precedence, highest first: the OS's reduced-motion setting (the calm level), then the app's `data-motion`
+ * (`none`, `calm`, `subtle`, `expressive`), then the brand file's `--cd-motion-*` values, then the defaults below.
+ *
+ * `motion()` is pure and safe to call at module level, so server components can use it; the hooks need a client
+ * component.
+ */
+/** The fourteen families: one per kind of change a person can see. */
+export type MotionFamily = "reveal" | "arrive" | "pop" | "mark" | "fill" | "value" | "move" | "overlay" | "press" | "tint" | "refuse" | "attention" | "live" | "clock";
+/** A motion level: 0 off (the end state appears, events still fire), 1 subtle, 2 expressive. */
+export type MotionLevel = 0 | 1 | 2;
+/** The easings a family may allow. Spring overshoots, so only spatial families accept it. */
+export type MotionEase = "standard" | "inout" | "spring" | "linear";
+/** The CSS each easing name stands for, as a brand file writes it. */
+export declare const motionEases: Readonly<Record<MotionEase, string>>;
+/** A family's amplitude: what its expressive level moves by. */
+export type MotionAmplitude = {
+    /** The token suffix: `--cd-motion-<family>-<name>`. */
+    readonly name: "distance" | "scale" | "count";
+    /** The value at the expressive level, as CSS. */
+    readonly default: string;
+    /** The lowest value `theme check` accepts. */
+    readonly min: number;
+    /** The highest value `theme check` accepts. */
+    readonly max: number;
+    /** The unit `min` and `max` are in ("" for a plain number). */
+    readonly unit: "px" | "" | "%";
+    /** How much of the amplitude the subtle level uses: 0 none, 1 all of it. */
+    readonly subtle: number;
+};
+/** A duration with the range `theme check` accepts, in milliseconds. */
+export type MotionDuration = {
+    readonly default: number;
+    readonly min: number;
+    readonly max: number;
+};
+/** Everything Candor knows about one family. `check:motion` checks `candor.css` against these. */
+export type MotionFamilySpec = {
+    /** What the family reports, in words, for the docs and the theme builder. */
+    readonly reports: string;
+    /** Moves things in space (scale, translate, size). Spring easing is accepted only here. */
+    readonly spatial: boolean;
+    /** The information itself (a hold, a deadline): a brand can't turn it below subtle. */
+    readonly essential: boolean;
+    /** How long one play takes; `null` when the clock decides. */
+    readonly dur: MotionDuration | null;
+    /** How long leaving takes, for families with an out moment (`-out-dur`). */
+    readonly outDur: MotionDuration | null;
+    /** The easing used when nothing sets one. */
+    readonly ease: MotionEase;
+    /** The easings a brand may choose. */
+    readonly eases: readonly MotionEase[];
+    /** The amplitude token, when the family has one. */
+    readonly amp: MotionAmplitude | null;
+    /** The closed set of variants: how the change is drawn, never when. The first is the default. */
+    readonly variants: readonly [string, ...string[]];
+    /** What the calm level (reduced motion) does with it, in words. */
+    readonly calm: string;
+};
+/** The family defaults. Durations, easings and amplitudes are 2.2's, so an app with no brand file looks the same. */
+export declare const motionFamilies: {
+    readonly reveal: {
+        readonly reports: "Content opened or closed to its measured size; a chevron turns.";
+        readonly spatial: true;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 200;
+            readonly min: 150;
+            readonly max: 300;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard", "inout"];
+        readonly amp: null;
+        readonly variants: readonly ["size", "fade"];
+        readonly calm: "Snaps to its measured size.";
+    };
+    readonly arrive: {
+        readonly reports: "Something new, added after the first draw.";
+        readonly spatial: true;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 240;
+            readonly min: 150;
+            readonly max: 300;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard", "spring"];
+        readonly amp: {
+            readonly name: "distance";
+            readonly default: "8px";
+            readonly min: 0;
+            readonly max: 16;
+            readonly unit: "px";
+            readonly subtle: 0.5;
+        };
+        readonly variants: readonly ["rise", "fade", "pop"];
+        readonly calm: "Fades in, up to 150 ms.";
+    };
+    readonly pop: {
+        readonly reports: "Added, removed, or a small mark appearing.";
+        readonly spatial: true;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 200;
+            readonly min: 100;
+            readonly max: 300;
+        };
+        readonly outDur: {
+            readonly default: 120;
+            readonly min: 80;
+            readonly max: 300;
+        };
+        readonly ease: "standard";
+        readonly eases: readonly ["standard", "spring"];
+        readonly amp: {
+            readonly name: "scale";
+            readonly default: "0.85";
+            readonly min: 0.8;
+            readonly max: 1;
+            readonly unit: "";
+            readonly subtle: 0;
+        };
+        readonly variants: readonly ["scale", "fade"];
+        readonly calm: "Fades, up to 150 ms.";
+    };
+    readonly mark: {
+        readonly reports: "A tick or cross drawn when a result settles.";
+        readonly spatial: true;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 360;
+            readonly min: 200;
+            readonly max: 500;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard"];
+        readonly amp: null;
+        readonly variants: readonly ["draw", "pop", "drop"];
+        readonly calm: "The finished mark fades in, up to 150 ms.";
+    };
+    readonly fill: {
+        readonly reports: "A bar or ring moving between measured values.";
+        readonly spatial: true;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 360;
+            readonly min: 200;
+            readonly max: 600;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard", "inout"];
+        readonly amp: null;
+        readonly variants: readonly ["grow"];
+        readonly calm: "Snaps to the new value; its colour may fade.";
+    };
+    readonly value: {
+        readonly reports: "A number or word changed in place.";
+        readonly spatial: false;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 120;
+            readonly min: 80;
+            readonly max: 200;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard"];
+        readonly amp: {
+            readonly name: "distance";
+            readonly default: "2px";
+            readonly min: 0;
+            readonly max: 4;
+            readonly unit: "px";
+            readonly subtle: 0;
+        };
+        readonly variants: readonly ["fade", "slide"];
+        readonly calm: "Crossfades, up to 150 ms.";
+    };
+    readonly move: {
+        readonly reports: "A thing changed place: a reorder, a tab indicator, a toast restacking, a scroll.";
+        readonly spatial: true;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 200;
+            readonly min: 150;
+            readonly max: 300;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard", "spring"];
+        readonly amp: null;
+        readonly variants: readonly ["slide"];
+        readonly calm: "Jumps to its new place.";
+    };
+    readonly overlay: {
+        readonly reports: "A dialog, sheet, popover, menu or tooltip opened or closed.";
+        readonly spatial: true;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 150;
+            readonly min: 100;
+            readonly max: 500;
+        };
+        readonly outDur: {
+            readonly default: 150;
+            readonly min: 80;
+            readonly max: 300;
+        };
+        readonly ease: "standard";
+        readonly eases: readonly ["standard", "inout", "spring"];
+        readonly amp: {
+            readonly name: "scale";
+            readonly default: "0.95";
+            readonly min: 0.9;
+            readonly max: 1;
+            readonly unit: "";
+            readonly subtle: 1;
+        };
+        readonly variants: readonly ["scale", "slide", "fade"];
+        readonly calm: "Fades, up to 150 ms.";
+    };
+    readonly press: {
+        readonly reports: "A press registered.";
+        readonly spatial: true;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 150;
+            readonly min: 80;
+            readonly max: 200;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard"];
+        readonly amp: {
+            readonly name: "scale";
+            readonly default: "0.96";
+            readonly min: 0.9;
+            readonly max: 1;
+            readonly unit: "";
+            readonly subtle: 0.5;
+        };
+        readonly variants: readonly ["scale"];
+        readonly calm: "Doesn't scale; the colour still answers.";
+    };
+    readonly tint: {
+        readonly reports: "Hover, focus, selected, a drop target: a colour or opacity change.";
+        readonly spatial: false;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 150;
+            readonly min: 0;
+            readonly max: 200;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard", "inout"];
+        readonly amp: null;
+        readonly variants: readonly ["fade"];
+        readonly calm: "Colour and opacity only, up to 150 ms.";
+    };
+    readonly refuse: {
+        readonly reports: "A locked control was pressed: the reason is shown, and under expressive it shakes.";
+        readonly spatial: true;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 360;
+            readonly min: 200;
+            readonly max: 500;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard"];
+        readonly amp: {
+            readonly name: "distance";
+            readonly default: "3px";
+            readonly min: 0;
+            readonly max: 6;
+            readonly unit: "px";
+            readonly subtle: 0;
+        };
+        readonly variants: readonly ["shake"];
+        readonly calm: "No shake; the reason's colour still changes.";
+    };
+    readonly attention: {
+        readonly reports: "Something new waits on the person: a ring that grows and fades.";
+        readonly spatial: false;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 900;
+            readonly min: 600;
+            readonly max: 1600;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard"];
+        readonly amp: {
+            readonly name: "count";
+            readonly default: "1";
+            readonly min: 1;
+            readonly max: 3;
+            readonly unit: "";
+            readonly subtle: 1;
+        };
+        readonly variants: readonly ["ring"];
+        readonly calm: "One ring that fades without growing, up to 150 ms.";
+    };
+    readonly live: {
+        readonly reports: "Work that is being heard from: a dot's pulse, a caret, a spinner, a shimmer, a skeleton.";
+        readonly spatial: false;
+        readonly essential: false;
+        readonly dur: {
+            readonly default: 1600;
+            readonly min: 1000;
+            readonly max: 3000;
+        };
+        readonly outDur: null;
+        readonly ease: "standard";
+        readonly eases: readonly ["standard", "inout", "linear"];
+        readonly amp: null;
+        readonly variants: readonly ["pulse"];
+        readonly calm: "Still, with its word.";
+    };
+    readonly clock: {
+        readonly reports: "Real time passing: a hold, a deadline, a replay. Painted from the clock.";
+        readonly spatial: true;
+        readonly essential: true;
+        readonly dur: null;
+        readonly outDur: null;
+        readonly ease: "linear";
+        readonly eases: readonly ["linear"];
+        readonly amp: null;
+        readonly variants: readonly ["glide"];
+        readonly calm: "Steps instead of gliding; never off.";
+    };
+};
+/** The family names, in the order the docs and the theme builder list them. */
+export declare const motionFamilyNames: MotionFamily[];
+/** A family's variants, by name: `MotionVariant<"mark">` is `"draw" | "pop" | "drop"`. */
+export type MotionVariant<F extends MotionFamily> = (typeof motionFamilies)[F]["variants"][number];
+/**
+ * True when a family has one way of drawing its change (fill, move, press, tint, refuse, attention, live and clock).
+ * Its single variant is fixed: there is no `-variant` token to set, and `motion()` writes none, because the family's
+ * utility has nothing to choose between. The docs mark such a family "(fixed)" instead of listing a value that does
+ * nothing. A later release that adds a second word turns the token on without a new name.
+ */
+export declare const motionVariantIsFixed: (family: MotionFamily) => boolean;
+/**
+ * The CSS value a variant is written as. CSS can only choose a drawing by keyframe name, so a variant's value is its
+ * keyframe's: the word with Candor's prefix, which keeps an app's own `@keyframes rise` from taking over.
+ */
+export declare const motionVariantValue: (variant: string) => string;
+/** What a moment may set as its own default, where it differs from its family's. */
+export type MomentDefaults<F extends MotionFamily> = {
+    /** The moment's duration, in milliseconds, within its family's range. */
+    dur?: number | undefined;
+    /** How long leaving takes, for families with an out moment. */
+    outDur?: number | undefined;
+    /** The moment's easing, from its family's allowed set. */
+    ease?: (typeof motionFamilies)[F]["eases"][number] | undefined;
+    /** The amplitude at the expressive level, as CSS (`"0.9"`, `"0.25rem"`, `"3"`). */
+    amp?: string | undefined;
+    /** The moment's variant, from its family's set. */
+    variant?: MotionVariant<F> | undefined;
+};
+/** The moment a chain belongs to, kept on the style object (not enumerable, so it never reaches the DOM). */
+export type MotionMoment = {
+    readonly item: string;
+    readonly moment: string;
+    readonly family: MotionFamily;
+};
+declare const momentKey: unique symbol;
+/**
+ * A moment's chain: CSS variables to spread into the moving element's `style`. Each resolves the moment's own token,
+ * then its family's, then the default, on that element, so a `data-motion` container anywhere above it still applies.
+ */
+export type MotionStyle = React.CSSProperties & {
+    readonly [momentKey]?: MotionMoment | undefined;
+};
+/**
+ * Builds a moment's chain. Call it once at module level and spread the result into the element's `style`, beside the
+ * family utility that the component adds at the honest moment:
+ *
+ * ```tsx
+ * const tick = motion("copy-field", "tick", "pop")
+ * <Check style={tick} className={cn(copied && "cd-pop")} />
+ * ```
+ *
+ * The brand reaches the moment with `--cd-motion-copy-field-tick` (its level), `-dur`, `-ease`, the family's amplitude
+ * suffix and `-variant`; anything it doesn't set falls back to the family (`--cd-motion-pop-*`), then to `defaults`,
+ * then to Candor's. Two families on one element compose: `style={{ ...press, ...tint }}`.
+ */
+export declare function motion<F extends MotionFamily>(item: string, moment: string, family: F, defaults?: MomentDefaults<F>): MotionStyle;
+/** The moment a chain was built for, or `undefined` for a plain style object. */
+export declare const motionMomentOf: (style: MotionStyle | undefined) => MotionMoment | undefined;
+/** How `useSettled` tells a finished value from an unfinished one; Candor's run statuses when left out. */
+export type SettledTest<T> = {
+    /** Reached an outcome worth showing settling (done or failed). */
+    settled: (value: T) => boolean;
+    /** Over in any way, including ones that don't animate (cancelled, skipped); `settled` when left out. */
+    over?: ((value: T) => boolean) | undefined;
+};
+/**
+ * How many times `value` reached a settled outcome from an unfinished one while the component was on screen. Zero
+ * for something that mounted already settled, so its mark is drawn still: motion reports a change that was seen,
+ * never one that happened before the reader arrived. Key the moving element on the count to replay it.
+ */
+export declare function useSettled(value: RunStatus): number;
+export declare function useSettled<T>(value: T, test: SettledTest<T>): number;
+/**
+ * Which keys were added after the component first drew. Keys present at the first render answer false, so a list
+ * that loads with fifty entries draws them still; a key added later answers true until it leaves (and true again if
+ * it comes back).
+ */
+export declare function useArrived(keys: readonly string[]): (key: string) => boolean;
+/**
+ * Items that just left, kept as inert ghosts for the length of their out moment. Each ghost goes when `left(item)` is
+ * called (from its `onAnimationEnd`), or after `fallbackMs` when nothing animated. The default, 600 ms, is longer than
+ * the longest out moment a brand can set (pop's 300 ms at the slowest speed, 1.5×, is 450 ms). An item that comes back while its
+ * ghost is still leaving takes the ghost's place.
+ */
+export declare function useLeaving<T>(items: readonly T[], keyOf: (item: T) => string, fallbackMs?: number): {
+    leaving: readonly T[];
+    left: (item: T) => void;
+};
+/** What the person allows here: everything, the calm level (reduced motion), or nothing. */
+export type MotionMode = "full" | "calm" | "none";
+/**
+ * The person's setting where `el` is: `none` under `data-motion="none"`, `calm` under the OS's reduced-motion setting
+ * or `data-motion="calm"`, else `full`. `none` or `calm` anywhere above wins (the same reach as the CSS variants), the
+ * OS setting can't be raised by the app, and values that aren't Candor's (Radix writes its own `data-motion` on menu
+ * panels) are ignored.
+ */
+export declare function motionMode(el: Element | null | undefined): MotionMode;
+/**
+ * `motionMode` for a component that has to react to it: the person's setting where `ref`'s element is, read after
+ * mount and again whenever the app changes `data-motion` or the OS setting changes. It starts as `full` for the first
+ * render, since there is nothing to read until the element exists. Use it for behaviour (a timer that must stop),
+ * not for styling, which the CSS variants already answer.
+ */
+export declare function useMotionMode(ref: React.RefObject<Element | null>): MotionMode;
+/**
+ * The level a moment resolves to on `el`, read from its computed style: the moment's token, its family's, the preset,
+ * then capped by `data-motion`. A page without Candor's CSS reads as subtle.
+ */
+export declare function motionLevel(el: Element | null | undefined, moment: MotionMoment | MotionFamily): MotionLevel;
+/**
+ * For motion that CSS can't stop (smooth scrolling, the Web Animations API, a bar painted from the clock): a stable
+ * function that answers, at the moment of the motion, whether it may play on `ref`'s element. False under
+ * `data-motion="none"`, under the calm level (reduced motion), and when the moment's resolved level is 0. Pass the
+ * moment's chain from `motion()`, or a family name for the family's level.
+ */
+export declare function useMotionAllowed(ref: React.RefObject<Element | null>, moment: MotionStyle | MotionFamily): () => boolean;
+export {};