@flikk/ui 1.0.0-beta.30 → 1.0.0-beta.32

package/dist/components/ai/AgentRequest/AgentRequest.animations.js

@@ -0,0 +1,81 @@
+"use client";
+/**
+ * Motion for the agent-request panel.
+ *
+ * One question is on screen at a time and the panel resizes to fit it, so the
+ * motion is a two-part gesture: the question SLIDES in the direction of travel
+ * (forward = in from the right, back = in from the left, so the arrows have a
+ * physical meaning), while the panel HEIGHT tweens to the incoming question's
+ * measured height. `AnimatePresence mode="wait"` keeps them from crossing over
+ * — the outgoing question is gone before the incoming one starts, which is what
+ * makes a taller or shorter next question read as a resize rather than a jump.
+ *
+ * These are motion/react values (seconds, JS numbers) and therefore do NOT
+ * track `--motion-duration-*` — per §12 that token family covers CSS
+ * transitions only. They are tuned to sit alongside those tiers, so if a theme
+ * retunes the CSS durations these want adjusting to match.
+ */
+/** Expo-out. Weighted settle — fast departure, long soft landing. */
+const EXPO = [0.32, 0.72, 0, 1];
+/** How far a question travels on the way in/out. */
+const SLIDE = 14;
+const INSTANT = { duration: 0 };
+const panelAnimations = {
+    hidden: { opacity: 0, y: 14, scale: 0.97 },
+    visible: {
+        opacity: 1,
+        y: 0,
+        scale: 1,
+        transition: { duration: 0.4, ease: EXPO, when: "beforeChildren" },
+    },
+    exit: {
+        opacity: 0,
+        y: 10,
+        scale: 0.98,
+        transition: { duration: 0.3, ease: EXPO },
+    },
+};
+/**
+ * The question swap. `custom` is the direction of travel: 1 when advancing,
+ * -1 when the user arrows back. Exit is deliberately quicker than enter — the
+ * outgoing question should clear out of the way, not perform.
+ */
+const questionAnimations = {
+    enter: (direction = 1) => ({ opacity: 0, x: direction * SLIDE }),
+    center: {
+        opacity: 1,
+        x: 0,
+        transition: { duration: 0.28, ease: EXPO },
+    },
+    exit: (direction = 1) => ({
+        opacity: 0,
+        x: direction * -SLIDE,
+        transition: { duration: 0.14, ease: "easeOut" },
+    }),
+};
+/**
+ * Reduced-motion twins of the two variant sets above.
+ *
+ * 🔴 They exist because a variant's OWN `transition` overrides the element's
+ * `transition` prop in motion — so passing `INSTANT` down alongside variants
+ * that each carry a transition does nothing, and the opt-out silently animates
+ * anyway. §12's rule ("motion props apply only when both allow") therefore has
+ * to be honoured by swapping the VARIANTS, not the transition. The states are
+ * kept identical so `initial`/`animate`/`exit` don't have to branch: only the
+ * travel (y/x/scale) and the duration are dropped, and the opacity states stay
+ * so `AnimatePresence` still has something to resolve against.
+ */
+const panelAnimationsInstant = {
+    hidden: { opacity: 0, y: 0, scale: 1 },
+    visible: { opacity: 1, y: 0, scale: 1, transition: INSTANT },
+    exit: { opacity: 0, y: 0, scale: 1, transition: INSTANT },
+};
+const questionAnimationsInstant = {
+    enter: { opacity: 0, x: 0 },
+    center: { opacity: 1, x: 0, transition: INSTANT },
+    exit: { opacity: 0, x: 0, transition: INSTANT },
+};
+/** The panel growing/shrinking to the measured height of the new question. */
+const HEIGHT_TRANSITION = { duration: 0.32, ease: EXPO };
+
+export { HEIGHT_TRANSITION, INSTANT, panelAnimations, panelAnimationsInstant, questionAnimations, questionAnimationsInstant };

package/dist/components/ai/AgentRequest/AgentRequest.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { AgentRequestProps } from "./AgentRequest.types";
+export declare const AgentRequest: React.ForwardRefExoticComponent<AgentRequestProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/ai/AgentRequest/AgentRequest.js

@@ -0,0 +1,435 @@
+"use client";
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+import React__default, { useMemo, useId, useRef, useState, useCallback, useEffect } from 'react';
+import { CaretLeft, CaretRight, X, Check } from '@phosphor-icons/react';
+import { motion, useReducedMotion, AnimatePresence } from 'motion/react';
+import { cn } from '../../../utils/cn.js';
+import { Button } from '../../core/Button/Button.js';
+import { Card } from '../../core/Card/Card.js';
+import { Input } from '../../forms/Input/Input.js';
+import '../../forms/Input/Input.theme.js';
+import { Radio } from '../../forms/Radio/Radio.js';
+import { Checkbox } from '../../forms/Checkbox/Checkbox.js';
+import { agentRequestTheme } from './AgentRequest.theme.js';
+import { panelAnimationsInstant, panelAnimations, INSTANT, HEIGHT_TRANSITION, questionAnimationsInstant, questionAnimations } from './AgentRequest.animations.js';
+
+/**
+ * The panel IS a `Card` — it takes the surface, the elevation shadow and the
+ * `--field-fill` its controls need from the relative-elevation engine instead
+ * of hand-painting them (§3). `motion.create` because it also has to animate
+ * in and out of the composer slot; Card forwards its ref and spreads the rest
+ * of its props onto its root element, which is everything motion needs.
+ *
+ * 🔴 The SURFACE only — no `Card.Body`. Card's slots pad by `--card-px/py`
+ * (24px) and this panel's inset is 16px; stacking the two put the heading at
+ * 40px while its own options and actions sat at 24px.
+ */
+const MotionCard = motion.create(Card);
+/**
+ * Display text for an option. `label` is a ReactNode, but an answer's `label`
+ * has to be a plain string (it lands in the answer payload and in the answered
+ * chip), so fall back to the value when the label isn't stringy.
+ */
+const optionText = (option) => option === undefined
+    ? ""
+    : typeof option.label === "string"
+        ? option.label
+        : option.value;
+const defaultProgressLabel = (current, total) => `${current} of ${total}`;
+/**
+ * The free-text entry inside a recorded answer, if it has one.
+ *
+ * A value that is not on the option list can only have come from `allowOther`,
+ * so on revisit it belongs back in that row. Without this it sat inside
+ * `selection` with no checkbox to render it — invisible, uneditable, and still
+ * silently attached to the answer on every re-confirm.
+ */
+const offListAnswer = (question, answer) => {
+    var _a;
+    if (question.kind !== "choice" || !question.allowOther)
+        return "";
+    if ((answer === null || answer === void 0 ? void 0 : answer.outcome) !== "resolved")
+        return "";
+    const values = Array.isArray(answer.value) ? answer.value : [answer.value];
+    return (_a = values.find((v) => !question.options.some((o) => o.value === v))) !== null && _a !== void 0 ? _a : "";
+};
+/**
+ * One question's body.
+ *
+ * A component rather than a render function so that its drafts (typed text,
+ * ticked boxes) are OWNED BY THE MOUNT: it is keyed by question id inside the
+ * `AnimatePresence`, so moving to another question remounts it and the drafts
+ * reset, and arrowing back re-seeds them from the recorded answer. Doing that
+ * with effects in the parent meant a controlled consumer handing back a fresh
+ * `answers` array on every render could wipe half-typed text.
+ */
+const QuestionBody = ({ question, answer, theme, fieldId, questionTextId, navReserve, scroll, onAnswer, }) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    const [draft, setDraft] = useState(() => question.kind === "input" &&
+        (answer === null || answer === void 0 ? void 0 : answer.outcome) === "resolved" &&
+        typeof answer.value === "string"
+        ? answer.value
+        : "");
+    // The off-list value is pulled OUT of the ticked set and back into the
+    // free-text row it came from, so the two drafts never both hold it.
+    const [selection, setSelection] = useState(() => {
+        if (!answer || !Array.isArray(answer.value))
+            return [];
+        const off = offListAnswer(question, answer);
+        return off ? answer.value.filter((v) => v !== off) : answer.value;
+    });
+    /** The free-text draft for the "something else" row. */
+    const [other, setOther] = useState(() => offListAnswer(question, answer));
+    const toggleSelection = useCallback((value, checked) => {
+        setSelection((current) => checked
+            ? current.includes(value)
+                ? current
+                : [...current, value]
+            : current.filter((v) => v !== value));
+    }, []);
+    // Discriminate on `question.kind` directly at each branch — hoisting it into
+    // a `kind` variable does NOT narrow the union, so `question.options` would
+    // not type-check inside the choice branch.
+    const isMulti = question.kind === "choice" && question.multiple === true;
+    const minSelected = isMulti ? ((_a = question.minSelected) !== null && _a !== void 0 ? _a : 0) : 0;
+    const maxSelected = isMulti ? question.maxSelected : undefined;
+    /**
+     * 🔴 The multi-choice bounds, checked in the COMMIT path and not only in the
+     * Confirm button's disabled state. The free-text row commits straight from
+     * its Enter key, which walked past both `minSelected` and `maxSelected`
+     * however the button was rendered.
+     */
+    const withinBounds = (count) => count > 0 &&
+        count >= minSelected &&
+        (maxSelected === undefined || count <= maxSelected);
+    /**
+     * Human-readable label for a set of selected values. The `|| v` fallback is
+     * load-bearing: a value that isn't on the option list came from `allowOther`,
+     * and without it the join left an empty segment behind ("#a, , #b").
+     */
+    const labelFor = (values) => question.kind === "choice"
+        ? values
+            .map((v) => optionText(question.options.find((o) => o.value === v)) || v)
+            .join(", ")
+        : values.join(", ");
+    /**
+     * Commit the "something else" text. On a multi-choice question it joins the
+     * ticked options rather than replacing them, so the answer keeps the array
+     * shape the question's type promises.
+     */
+    const submitOther = () => {
+        if (question.kind !== "choice")
+            return;
+        const text = other.trim();
+        if (!text)
+            return;
+        if (question.multiple) {
+            const values = [...selection, text];
+            if (!withinBounds(values.length))
+                return;
+            onAnswer(values, labelFor(values));
+            return;
+        }
+        onAnswer(text, text);
+    };
+    /** Clears the nav, which is absolutely positioned on this same line. */
+    const actionsInset = navReserve ? { paddingLeft: navReserve } : undefined;
+    /**
+     * Skip — the same control on every kind, so it is built once. `approval`
+     * carries `optional` too: it has no free-text row to fall back on, so this is
+     * the only way out of a permission gate the user can neither approve nor deny.
+     */
+    const skipAction = question.optional ? (jsx("div", { className: theme.actionsStartStyle, children: jsx(Button, { size: "sm", color: "mono", variant: "outline", onClick: () => { var _a; return onAnswer("__skipped__", (_a = question.skipLabel) !== null && _a !== void 0 ? _a : "Skipped", "deferred"); }, children: (_b = question.skipLabel) !== null && _b !== void 0 ? _b : "Skip" }) })) : null;
+    // 🔴 Split into CONTENT and ACTIONS rather than one per-kind block: only the
+    // content goes inside the height cap, and the actions row is the footer the
+    // nav is absolutely positioned onto. Fold them back together and a capped
+    // question scrolls its own Confirm button out of reach, with the nav painted
+    // on top of whatever ends up at the bottom edge.
+    const content = (jsxs(Fragment, { children: [(question.kind === undefined || question.kind === "approval") &&
+                question.payload && (jsx("div", { className: theme.bodyInnerStyle, children: jsx("div", { className: theme.payloadStyle, children: question.payload }) })), question.kind === "choice" && (jsxs("div", { className: theme.bodyInnerStyle, children: [jsx("div", { className: theme.optionListStyle, role: isMulti ? "group" : "radiogroup", "aria-labelledby": questionTextId, children: question.options.map((option) => {
+                            // Pre-selected when revisiting: the recorded answer is what the
+                            // controls show, so going back reads as "here is what you said"
+                            // rather than as a blank question.
+                            const checked = isMulti
+                                ? selection.includes(option.value)
+                                : (answer === null || answer === void 0 ? void 0 : answer.value) === option.value;
+                            const atMax = isMulti &&
+                                !checked &&
+                                question.maxSelected !== undefined &&
+                                selection.length >= question.maxSelected;
+                            const shared = {
+                                value: option.value,
+                                label: option.label,
+                                description: option.description,
+                                size: "sm",
+                                className: theme.optionStyle,
+                            };
+                            return isMulti ? (jsx(Checkbox, { ...shared, checked: checked, state: atMax ? "disabled" : "default", onChange: (next) => toggleSelection(option.value, next) }, option.value)) : (jsx(Radio, { ...shared, name: fieldId, checked: checked, onChange: () => onAnswer(option.value, optionText(option)) }, option.value));
+                        }) }), question.allowOther && (jsx(Input, { size: "sm", "aria-label": (_c = question.otherPlaceholder) !== null && _c !== void 0 ? _c : "Something else", placeholder: (_d = question.otherPlaceholder) !== null && _d !== void 0 ? _d : "Something else", wrapperClassName: theme.otherInputStyle, value: other, onChange: (event) => setOther(event.target.value), onKeyDown: (event) => {
+                            if (event.key === "Enter" && other.trim()) {
+                                event.preventDefault();
+                                submitOther();
+                            }
+                        } }))] })), question.kind === "input" && (
+            /* The real Input, not a hand-rolled <input>: it owns the form-control
+               geometry tokens (--form-px/min-h/radius) and the inset box-shadow
+               border system from §9. Rolling our own here bypassed all of it and
+               mis-rendered under a large --radius-base. */
+            jsx("div", { className: theme.bodyInnerStyle, children: jsx(Input, { size: "sm", "aria-labelledby": questionTextId, wrapperClassName: theme.inputStyle, placeholder: question.placeholder, value: draft, onChange: (event) => setDraft(event.target.value), onKeyDown: (event) => {
+                        if (event.key === "Enter" && draft.trim()) {
+                            event.preventDefault();
+                            onAnswer(draft.trim(), draft.trim());
+                        }
+                    } }) }))] }));
+    const actions = (jsxs(Fragment, { children: [(question.kind === undefined || question.kind === "approval") && (
+            /* Primary action rightmost — the row is right-anchored, so "Approve"
+               is the last thing before the panel edge. */
+            jsxs("div", { className: theme.actionsStyle, style: actionsInset, children: [skipAction, question.allowAlways && (jsx(Button, { size: "sm", color: "mono", variant: "outline", onClick: () => { var _a; return onAnswer("always", (_a = question.alwaysAllowLabel) !== null && _a !== void 0 ? _a : "Always allowed"); }, children: (_e = question.alwaysAllowLabel) !== null && _e !== void 0 ? _e : "Always allow" })), jsx(Button, { size: "sm", color: "danger", variant: "outline", onClick: () => { var _a; return onAnswer("denied", (_a = question.denyLabel) !== null && _a !== void 0 ? _a : "Denied", "rejected"); }, children: (_f = question.denyLabel) !== null && _f !== void 0 ? _f : "Deny" }), jsx(Button, { size: "sm", color: "primary", variant: "filled", onClick: () => { var _a; return onAnswer("approved", (_a = question.approveLabel) !== null && _a !== void 0 ? _a : "Approved"); }, children: (_g = question.approveLabel) !== null && _g !== void 0 ? _g : "Approve" })] })), question.kind === "choice" &&
+                (isMulti || question.optional || other.trim() || navReserve > 0) && (jsxs("div", { className: theme.actionsStyle, style: actionsInset, children: [skipAction, isMulti ? (jsx(Button, { size: "sm", color: "primary", variant: "filled", state: withinBounds(selection.length + (other.trim() ? 1 : 0))
+                            ? "default"
+                            : "disabled", onClick: () => {
+                            if (other.trim()) {
+                                submitOther();
+                                return;
+                            }
+                            onAnswer(selection, labelFor(selection));
+                        }, children: (_h = question.confirmLabel) !== null && _h !== void 0 ? _h : "Confirm" })) : (other.trim() && (jsx(Button, { size: "sm", color: "primary", variant: "filled", onClick: submitOther, children: (_j = question.otherSubmitLabel) !== null && _j !== void 0 ? _j : "Send" })))] })), question.kind === "input" && (jsxs("div", { className: theme.actionsStyle, style: actionsInset, children: [skipAction, jsx(Button, { size: "sm", color: "primary", variant: "filled", state: draft.trim() ? "default" : "disabled", onClick: () => onAnswer(draft.trim(), draft.trim()), children: (_k = question.submitLabel) !== null && _k !== void 0 ? _k : "Submit" })] }))] }));
+    return (jsxs(Fragment, { children: [jsxs("div", { className: "relative", children: [scroll.maxHeight && (jsx("div", { className: cn(theme.fadeStyle, theme.fadeTopStyle, scroll.edges.top ? "opacity-100" : "opacity-0"), "aria-hidden": "true" })), jsx("div", { ref: scroll.ref, className: cn(scroll.maxHeight && theme.scrollAreaStyle), style: scroll.maxHeight ? { maxHeight: scroll.maxHeight } : undefined, onScroll: scroll.onScroll, children: content }), scroll.maxHeight && (jsx("div", { className: cn(theme.fadeStyle, theme.fadeBottomStyle, scroll.edges.bottom ? "opacity-100" : "opacity-0"), "aria-hidden": "true" }))] }), actions] }));
+};
+const AgentRequest = React__default.forwardRef(({ questions, children, title, value, defaultValue, onValueChange, onAnswer, onComplete, maxHeight, previousLabel = "Previous question", nextLabel = "Next question", progressLabel = defaultProgressLabel, className, theme: themeOverrides, ...rest }, ref) => {
+    var _a;
+    const theme = useMemo(() => ({
+        ...agentRequestTheme,
+        ...themeOverrides,
+        badgeStates: {
+            ...agentRequestTheme.badgeStates,
+            ...themeOverrides === null || themeOverrides === void 0 ? void 0 : themeOverrides.badgeStates,
+        },
+    }), [themeOverrides]);
+    const reactId = useId();
+    const shouldReduceMotion = useReducedMotion();
+    const panelRef = useRef(null);
+    const scrollerRef = useRef(null);
+    const contentRef = useRef(null);
+    const navRef = useRef(null);
+    /**
+     * Set when an ANSWER moved the cursor — see the focus-recovery effect for
+     * why the effect can't just look at `document.activeElement`.
+     */
+    const recoverFocus = useRef(false);
+    const [edges, setEdges] = useState({ top: false, bottom: false });
+    const [bodyHeight, setBodyHeight] = useState(null);
+    const [navWidth, setNavWidth] = useState(0);
+    const isControlled = value !== undefined;
+    const [uncontrolled, setUncontrolled] = useState(defaultValue !== null && defaultValue !== void 0 ? defaultValue : []);
+    const answers = isControlled ? value : uncontrolled;
+    const list = useMemo(() => questions !== null && questions !== void 0 ? questions : [], [questions]);
+    /**
+     * The one-at-a-time cursor. Answers are looked up BY ID, never by index —
+     * the cursor moves independently of how many questions are answered, which
+     * is the whole point of being able to arrow back into one and change it.
+     */
+    const nextOpenIn = useCallback((against) => list.findIndex((q) => !against.some((a) => a.id === q.id)), [list]);
+    const [cursor, setCursor] = useState(() => {
+        const seed = (questions !== null && questions !== void 0 ? questions : []).findIndex((q) => { var _a; return !((_a = value !== null && value !== void 0 ? value : defaultValue) !== null && _a !== void 0 ? _a : []).some((a) => a.id === q.id); });
+        return seed === -1 ? 0 : seed;
+    });
+    /** Travel direction, so the swap slides the way the arrows point. */
+    const [direction, setDirection] = useState(1);
+    const total = list.length;
+    // Clamped rather than corrected in an effect: `questions` can shrink at any
+    // time and a render must never index off the end.
+    const safeCursor = Math.min(cursor, Math.max(0, total - 1));
+    const current = list[safeCursor];
+    const currentAnswer = current
+        ? answers.find((a) => a.id === current.id)
+        : undefined;
+    const isComplete = total > 0 && nextOpenIn(answers) === -1;
+    const hasQuestions = questions !== undefined && questions.length > 0;
+    const hasChildren = children !== undefined;
+    const showNav = total > 1;
+    useEffect(() => {
+        if (process.env.NODE_ENV === "production")
+            return;
+        /* eslint-disable no-console */
+        if (hasQuestions && hasChildren) {
+            console.warn("[AgentRequest]: both `questions` and `children` were provided — `questions` takes precedence.");
+        }
+        if (isControlled && defaultValue !== undefined) {
+            console.warn("[AgentRequest]: both `value` and `defaultValue` were provided — `value` (controlled) wins.");
+        }
+        if (isControlled && onValueChange === undefined) {
+            console.warn("[AgentRequest]: `value` was provided without `onValueChange`, so answers can never be recorded. Pass `defaultValue` for uncontrolled usage.");
+        }
+        if (hasQuestions) {
+            const ids = new Set();
+            for (const q of questions) {
+                if (ids.has(q.id)) {
+                    console.warn(`[AgentRequest]: duplicate question id "${q.id}" — answers are keyed by id and will collide.`);
+                }
+                ids.add(q.id);
+            }
+        }
+        /* eslint-enable no-console */
+    }, [
+        hasQuestions,
+        hasChildren,
+        isControlled,
+        defaultValue,
+        onValueChange,
+        questions,
+    ]);
+    const recomputeEdges = useCallback(() => {
+        const el = scrollerRef.current;
+        if (!el)
+            return;
+        const overflowing = el.scrollHeight > el.clientHeight + 2;
+        setEdges({
+            top: overflowing && el.scrollTop > 4,
+            bottom: overflowing && el.scrollTop + el.clientHeight < el.scrollHeight - 4,
+        });
+    }, []);
+    /**
+     * Measure the question so the panel can tween its own height to it. The
+     * measured node wraps the `AnimatePresence`, not the question itself, so
+     * with `mode="wait"` it always reports exactly one question's height.
+     * `safeCursor` is a dependency so the fade edges are recomputed for the
+     * incoming question even when it happens to be exactly as tall as the one
+     * it replaced (no resize, so no observer callback).
+     */
+    useEffect(() => {
+        const el = contentRef.current;
+        if (!el)
+            return;
+        const measure = () => {
+            setBodyHeight(el.offsetHeight);
+            recomputeEdges();
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [isComplete, safeCursor, recomputeEdges]);
+    /**
+     * Measure the nav so the heading's floated spacer reserves exactly its
+     * lane. It can't be a literal width: `progressLabel` is a consumer-supplied
+     * i18n string, and a fixed one fitted the built-in "1 of 3" and let a
+     * longer label run underneath the arrows.
+     */
+    useEffect(() => {
+        const el = navRef.current;
+        if (!el) {
+            setNavWidth(0);
+            return;
+        }
+        const measure = () => setNavWidth(el.offsetWidth);
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, [isComplete, showNav]);
+    /**
+     * Answering unmounts the control that had focus, which drops the keyboard
+     * on the floor — tab order restarts at the top of the page. Move focus to
+     * the panel instead, but ONLY when an answer is what moved the cursor: the
+     * arrows stay mounted and keep their own focus, so a second press still
+     * lands on them.
+     *
+     * 🔴 Do NOT go back to deciding this from `document.activeElement === body`.
+     * `AnimatePresence mode="wait"` keeps the outgoing question — and the button
+     * that was just clicked — mounted for its exit, so at the moment this effect
+     * runs focus has not been lost YET. It is lost a frame later, when nothing
+     * is listening, and the panel silently stopped recovering it.
+     */
+    useEffect(() => {
+        var _a, _b;
+        if (!recoverFocus.current)
+            return;
+        recoverFocus.current = false;
+        const active = document.activeElement;
+        // Never yank focus out of something the user moved to themselves.
+        if (active && active !== document.body && !((_a = panelRef.current) === null || _a === void 0 ? void 0 : _a.contains(active)))
+            return;
+        (_b = panelRef.current) === null || _b === void 0 ? void 0 : _b.focus({ preventScroll: true });
+    }, [safeCursor]);
+    const commit = useCallback((question, next) => {
+        // Replace by id, not push: arrowing back and answering again OVERWRITES
+        // that question's answer and leaves every other answer alone.
+        const existing = answers.some((a) => a.id === question.id);
+        const updated = existing
+            ? answers.map((a) => (a.id === question.id ? next : a))
+            : [...answers, next];
+        if (!isControlled)
+            setUncontrolled(updated);
+        onValueChange === null || onValueChange === void 0 ? void 0 : onValueChange(updated);
+        onAnswer === null || onAnswer === void 0 ? void 0 : onAnswer(next);
+        // Land on the first question that is still open — so editing an early
+        // answer returns the user to where they were, not back through
+        // questions they have already dealt with.
+        const open = nextOpenIn(updated);
+        if (open === -1) {
+            onComplete === null || onComplete === void 0 ? void 0 : onComplete(updated);
+            return;
+        }
+        // The control that was just used is about to unmount with the question.
+        if (open !== safeCursor)
+            recoverFocus.current = true;
+        setDirection(open >= safeCursor ? 1 : -1);
+        setCursor(open);
+    }, [
+        answers,
+        isControlled,
+        onValueChange,
+        onAnswer,
+        onComplete,
+        nextOpenIn,
+        safeCursor,
+    ]);
+    const answerCurrent = useCallback((value_, label, outcome = "resolved") => {
+        if (!current)
+            return;
+        commit(current, { id: current.id, value: value_, label, outcome });
+    }, [commit, current]);
+    const goTo = useCallback((index, travel) => {
+        setDirection(travel);
+        setCursor(index);
+    }, []);
+    if (total === 0 && !hasChildren)
+        return null;
+    const canGoBack = safeCursor > 0;
+    // Forward only over ground already covered — an unanswered question is not
+    // something to skip past, it is the thing being asked.
+    const canGoForward = safeCursor < total - 1 && currentAnswer !== undefined;
+    // 🔴 Reduced motion swaps the VARIANTS, not the transition — a variant's own
+    // transition overrides the element's `transition` prop, so passing INSTANT
+    // alongside these would animate anyway. See AgentRequest.animations.ts.
+    const panelVariants = shouldReduceMotion
+        ? panelAnimationsInstant
+        : panelAnimations;
+    const questionVariants = shouldReduceMotion
+        ? questionAnimationsInstant
+        : questionAnimations;
+    const labelId = `${reactId}-title`;
+    const questionTextId = current ? `${reactId}-${current.id}-q` : undefined;
+    const defaultTitle = `Agent needs ${total} decision${total === 1 ? "" : "s"}`;
+    return (jsx("div", { ref: ref, className: cn(theme.baseStyle, className), ...rest, children: jsx(AnimatePresence, { initial: false, children: !isComplete && (jsx(MotionCard, { ref: panelRef, elevation: "overlay", className: theme.panelStyle, role: "region", "aria-labelledby": labelId, 
+                // Not a tab stop — a focus target. See the focus-recovery effect.
+                tabIndex: -1, variants: panelVariants, initial: "hidden", animate: "visible", exit: "exit", children: jsxs(Fragment, { children: [jsx("span", { id: labelId, className: "sr-only", children: title !== null && title !== void 0 ? title : defaultTitle }), showNav && (jsxs("div", { ref: navRef, className: theme.navStyle, children: [jsx(Button, { size: "sm", color: "mono", variant: "ghost", iconOnly: true, className: theme.navButtonStyle, "aria-label": previousLabel, state: canGoBack ? "default" : "disabled", onClick: () => goTo(safeCursor - 1, -1), children: jsx(CaretLeft, { className: "size-3.5", weight: "bold" }) }), jsx("span", { className: theme.navCountStyle, "aria-live": "polite", children: progressLabel(safeCursor + 1, total) }), jsx(Button, { size: "sm", color: "mono", variant: "ghost", iconOnly: true, className: theme.navButtonStyle, "aria-label": nextLabel, state: canGoForward ? "default" : "disabled", onClick: () => goTo(safeCursor + 1, 1), children: jsx(CaretRight, { className: "size-3.5", weight: "bold" }) })] })), jsx(motion.div, { className: theme.bodyStyle, 
+                            // `auto` until the first measurement lands (and in jsdom,
+                            // where offsetHeight is always 0) so the panel can never
+                            // collapse the question it is meant to be showing.
+                            animate: { height: bodyHeight ? bodyHeight : "auto" }, initial: false, transition: shouldReduceMotion ? INSTANT : HEIGHT_TRANSITION, children: jsx("div", { ref: contentRef, className: theme.contentStyle, children: jsx(AnimatePresence, { mode: "wait", initial: false, custom: direction, children: current ? (jsxs(motion.div, { custom: direction, variants: questionVariants, initial: "enter", animate: "center", exit: "exit", "data-risk": current.risk === "destructive"
+                                            ? "destructive"
+                                            : undefined, children: [jsxs("div", { className: theme.headerStyle, children: [currentAnswer && (jsxs("span", { className: theme.answeredChipStyle, children: [jsx("span", { className: cn(theme.badgeStyle, theme.badgeStates[currentAnswer.outcome]), "aria-hidden": "true", children: currentAnswer.outcome === "rejected" ? (jsx(X, { className: "size-2.5", weight: "bold" })) : (jsx(Check, { className: "size-2.5", weight: "bold" })) }), jsx("span", { className: theme.answerStyle, children: currentAnswer.label })] })), jsx("div", { id: questionTextId, className: theme.questionStyle, children: (_a = current.question) !== null && _a !== void 0 ? _a : current.label }), current.meta && (jsx("div", { className: theme.metaStyle, children: current.meta }))] }), jsx(QuestionBody, { question: current, answer: currentAnswer, theme: theme, fieldId: `${reactId}-${current.id}`, questionTextId: questionTextId, 
+                                                // The +4 is the 4px the nav is pulled out by,
+                                                // plus the gutter between it and the actions.
+                                                navReserve: showNav && navWidth ? navWidth + 4 : 0, scroll: {
+                                                    maxHeight,
+                                                    ref: scrollerRef,
+                                                    onScroll: recomputeEdges,
+                                                    edges,
+                                                }, onAnswer: answerCurrent })] }, current.id)) : (hasChildren && (jsx(motion.div, { variants: questionVariants, initial: "enter", animate: "center", exit: "exit", children: jsx("div", { className: cn(theme.bodyInnerStyle, "pt-4"), children: children }) }, "children"))) }) }) })] }) })) }) }));
+});
+AgentRequest.displayName = "AgentRequest";
+
+export { AgentRequest };

package/dist/components/ai/AgentRequest/AgentRequest.theme.d.ts

@@ -0,0 +1,2 @@
+import type { AgentRequestTheme } from "./AgentRequest.types";
+export declare const agentRequestTheme: AgentRequestTheme;

package/dist/components/ai/AgentRequest/AgentRequest.theme.js

@@ -0,0 +1,106 @@
+const agentRequestTheme = {
+    baseStyle: "w-full min-w-0",
+    // GEOMETRY ONLY — no bg, no shadow. The panel is a `Card` pinned to the
+    // overlay rung, so the elevation engine paints the surface, the shadow and
+    // `--field-fill` (which is what makes the Input/Radio/Checkbox inside fill
+    // correctly against a lifted panel). It used to hand-paint
+    // `bg-[var(--color-surface)] shadow-surface-5` — a rung-3 background under a
+    // rung-5 shadow, and hardcoded, so it never lifted when nested.
+    // The radius stays ours: the panel sits where the composer was and takes the
+    // sm cap tier, NOT `--card-radius` (lg). See docs/THEMING.md.
+    panelStyle: "relative w-full min-w-0 overflow-hidden rounded-[var(--agent-request-radius)]",
+    // Bottom-LEFT, sharing the footer line with the question's own actions: the
+    // arrows are navigation, the right-hand button is the answer, and putting
+    // them on one line separates "where am I" from "what do I do".
+    // 🔴 Still ABSOLUTE, and that is deliberate: the question swaps inside an
+    // AnimatePresence, and a nav rendered inside that swap would unmount on every
+    // step — taking keyboard focus with it, so a second press of the back arrow
+    // would land on nothing. Which is also why the actions row reserves its lane
+    // by padding rather than by holding it as a flex child.
+    // Pulled 4px out of the panel's 16px inset so the caret GLYPHS line up with
+    // the content edge — the ghost button boxes are wider than the marks in them.
+    // `bottom-5` centres the 24px nav against the 32px `size="sm"` button sitting
+    // on the panel's 16px bottom inset.
+    navStyle: "absolute bottom-5 left-3 z-[2] flex shrink-0 items-center gap-0.5",
+    // Overrides Button's `iconOnly` sizing (--button-icon-size-sm is the FORM
+    // control height — too heavy for a quiet header affordance). Plain utilities,
+    // not `!important`: Button puts `className` last in its own `cn(...)`, so
+    // twMerge already resolves these against the size/padding it set.
+    navButtonStyle: "size-6 p-0 text-[var(--color-text-muted)]",
+    navCountStyle: "px-0.5 text-xs tabular-nums text-[var(--color-text-muted)] select-none",
+    // 🔴 The panel's own inset, and it lives HERE rather than on a `Card.Body`.
+    // Card's body/header slots pad by `--card-px/py` (24px); this panel sits in
+    // the composer slot at 16px, which is also what earns it the sm radius cap
+    // instead of Card's lg (docs/THEMING.md). Wrapping the question in
+    // `Card.Body` stacked the two — the heading sat at 40px while its own
+    // options and actions sat at 24px, a 16px stagger down the left edge — so
+    // only Card's SURFACE is taken and the padding is ours.
+    contentStyle: "px-4 pb-4",
+    // The question IS the heading — there is no separate title row, and with the
+    // nav moved down to the footer the heading gets the full width.
+    headerStyle: "flex flex-col gap-1 pt-3.5 pb-3",
+    questionStyle: "min-w-0 text-base font-semibold leading-snug text-[var(--color-text-primary)]",
+    metaStyle: "text-sm text-[var(--color-text-secondary)]",
+    // Shown above the question when the user has arrowed BACK to one they already
+    // answered. The controls below are pre-selected too, but an approval has no
+    // control that can hold a selection, so this is the only record of it.
+    answeredChipStyle: "flex items-center gap-1.5",
+    badgeStyle: "grid size-4 shrink-0 place-items-center rounded-full",
+    badgeStates: {
+        resolved: "bg-[var(--color-success)] text-[var(--color-success-contrast)]",
+        rejected: "bg-[var(--color-danger)] text-[var(--color-danger-contrast)]",
+        deferred: "bg-[var(--color-mono)] text-[var(--color-mono-contrast)]",
+    },
+    // A rem cap, not a percentage — Tailwind v4 emits no rule for a percentage
+    // arbitrary max-width, so `max-w-[52%]` would silently never truncate.
+    answerStyle: "max-w-[14rem] truncate text-[11px] font-medium text-[var(--color-text-muted)]",
+    // The height-animated shell. `overflow-hidden` is load-bearing — it clips the
+    // outgoing question while the panel resizes to the incoming one.
+    bodyStyle: "relative w-full min-w-0 overflow-hidden",
+    // Applied only when `maxHeight` is set, and only to the ANSWERING controls —
+    // the question heading sits above the scroller. Capping the whole question
+    // let the user scroll the question itself out of sight while picking from its
+    // own option list. overscroll-contain stops a flick inside the body from
+    // scrolling the transcript behind it.
+    scrollAreaStyle: "overflow-y-auto overscroll-contain",
+    fadeStyle: "pointer-events-none absolute inset-x-0 z-[2] h-6 transition-opacity duration-[var(--motion-duration-base)] ease-out",
+    // `--surface-5`, not `--color-surface`: the panel paints the overlay rung, so
+    // a rung-3 gradient would band against it in dark mode.
+    fadeTopStyle: "top-0 bg-gradient-to-b from-[var(--surface-5)] to-transparent",
+    fadeBottomStyle: "bottom-0 bg-gradient-to-t from-[var(--surface-5)] to-transparent",
+    bodyInnerStyle: "min-w-0",
+    // Tight inner well — takes the xs-capped token, one tier below the panel it
+    // sits in. A bare `--radius-base` put a 24px curve on 10px of padding.
+    payloadStyle: "whitespace-pre-wrap break-words rounded-[var(--agent-request-well-radius)] bg-[var(--color-surface-sunken)] px-2.5 py-2 font-mono text-[11px] leading-relaxed text-[var(--color-text-secondary)]",
+    // ── option rows ────────────────────────────────────────────────────────────
+    // One connected group: a single perimeter on the list, hairline dividers
+    // between items, and only the first/last corners rounded. `overflow-hidden`
+    // is what rounds the children's outer corners — which is also why the option
+    // focus ring below MUST be `ring-inset`, or it gets clipped on the first and
+    // last rows. Takes the well radius (xs cap) so a large `--radius-base` theme
+    // can't round a 10px-padded row past its own padding.
+    optionListStyle: "flex flex-col overflow-hidden rounded-[var(--agent-request-well-radius)] shadow-[inset_0_0_0_1px_var(--color-border)]",
+    // The rows are the real `Radio`/`Checkbox` — this styles the row they sit in,
+    // nothing more. `first-of-type` (not `first`) is exact here because every
+    // child is one of those controls.
+    optionStyle: "flex w-full cursor-pointer items-center gap-2.5 border-t border-[var(--color-border)] px-2.5 py-2 text-left text-sm transition-[background-color] duration-[var(--motion-duration-fast)] ease-out first-of-type:border-t-0 hover:bg-[var(--color-surface-hover)] focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--color-primary)]",
+    // No optionRadioStyle / optionDescriptionStyle — the real `Radio` and
+    // `Checkbox` own the control mark and the per-option `description`
+    // (§9: `description` is the per-option slot, distinct from `helperText`).
+    // The escape hatch: a plain `Input` under the options, nothing bespoke.
+    otherInputStyle: "mt-2",
+    // The footer line. Right-anchored: the primary action is the rightmost thing
+    // in the panel. `actionsStartStyle`'s `mr-auto` is what pushes it there, and
+    // it also holds the row open when the escape hatches are the only things
+    // present. `min-h-8` keeps the line tall enough for the absolutely-positioned
+    // nav even on a question whose only content is the nav itself; the left inset
+    // that clears the nav is applied inline, since its width is measured.
+    actionsStyle: "flex min-h-8 flex-wrap items-center justify-end gap-2 pt-3",
+    actionsStartStyle: "mr-auto flex items-center gap-2",
+    // Spacing ONLY — the box (height, padding, radius, border, focus ring) comes
+    // from the real `Input` component and its --form-* tokens. This used to be a
+    // hand-rolled <input> that reimplemented all of that and got it wrong.
+    inputStyle: "",
+};
+
+export { agentRequestTheme };