@instruments/materia-ui 0.1.0

package/dist/compositions/prompt-panel/prompt-panel-freeform.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { CornerDownLeft, Pencil } from "lucide-react";
+import { Flex } from "../../components/flex.js";
+import { Icon } from "../../components/icon.js";
+import { Kbd } from "../../components/kbd.js";
+import { useControllableState } from "../../hooks/use-controllable-state.js";
+const DEFAULT_PLACEHOLDER = "Type your own answer here";
+const DEFAULT_SHORTCUT = _jsx(Icon, { icon: CornerDownLeft, size: "2xs" });
+/**
+ * The "write your own" row inside a `PromptPanel` - a bordered input for
+ * freeform text (leading icon + field + trailing `Kbd`). The row keeps the
+ * same border treatment whether focused or not; the inner `<input>` is
+ * outline-free so focus never adds a second frame.
+ *
+ * @param props - The prompt panel freeform props
+ * @param props.value - Controlled value; omit for uncontrolled usage via `defaultValue`.
+ * @param props.defaultValue - Uncontrolled initial value. Defaults to "".
+ * @param props.onValueChange - Called with the next value on every keystroke.
+ * @param props.onSubmit - Called with the current value when Enter is pressed on non-empty text.
+ * @param props.icon - Leading icon. Defaults to `Pencil`.
+ * @param props.shortcut - Trailing `Kbd` content. Defaults to a `CornerDownLeft` icon.
+ * @param props.placeholder - Input placeholder. Defaults to "Type your own answer here".
+ * @param props.inputRef - Ref forwarded to the underlying `<input>`.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other standard HTML input element props.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelFreeform
+ *   onSubmit={(text) => runPrompt(text)}
+ *   onValueChange={setDraft}
+ *   value={draft}
+ * />
+ * ```
+ *
+ * @bestPractice Pair it with `usePromptPanelKeyboard` for the full digit/Enter/Escape/Backspace contract - this component alone only submits on Enter.
+ * @bestPractice Leave `placeholder` agent/consumer-supplied copy - don't hardcode "Type your own answer here" at call sites that need different phrasing.
+ */
+const PromptPanelFreeform = ({ className, placeholder = DEFAULT_PLACEHOLDER, value, defaultValue = "", onValueChange, onSubmit, onKeyDown, icon = Pencil, shortcut = DEFAULT_SHORTCUT, inputRef, disabled, "aria-label": ariaLabel, ...props }) => {
+    const [resolvedValue, setValue] = useControllableState({
+        defaultValue,
+        onChange: onValueChange,
+        value,
+    });
+    const hasText = resolvedValue.length > 0;
+    return (_jsxs(Flex, { align: "center", className: cn("border-border w-full rounded-lg border py-3 pr-3 pl-4", disabled === true && "pointer-events-none opacity-50", className), "data-component": "prompt-panel-freeform", "data-slot": "prompt-panel-freeform", gap: "xs", children: [_jsx(Icon, { className: "text-muted-foreground shrink-0", icon: icon, size: "xs" }), _jsx("input", { "aria-label": ariaLabel ?? placeholder, className: "text-foreground placeholder:text-muted-foreground text-paragraph-sm w-full min-w-0 flex-1 border-0 bg-transparent p-0 outline-none", disabled: disabled, onChange: (event) => {
+                    setValue(event.target.value);
+                }, onKeyDown: (event) => {
+                    onKeyDown?.(event);
+                    if (!event.defaultPrevented &&
+                        event.key === "Enter" &&
+                        resolvedValue.trim() !== "") {
+                        onSubmit?.(resolvedValue);
+                    }
+                }, placeholder: placeholder, ref: inputRef, type: "text", value: resolvedValue, ...props }), _jsx(Kbd, { className: cn("duration-quick transition-opacity ease-out", hasText ? "opacity-100" : "opacity-50"), size: "sm", children: shortcut })] }));
+};
+export { PromptPanelFreeform };

package/dist/compositions/prompt-panel/prompt-panel-header.d.ts

@@ -0,0 +1,37 @@
+import type * as React from "react";
+export type PromptPanelHeaderProps = Omit<React.ComponentProps<"div">, "children"> & {
+    /** Title copy, centred regardless of whether the back button is shown. */
+    children: React.ReactNode;
+    /** Accessible label for the back button. @default "Back" */
+    backLabel?: string;
+    /** Called when the back button is pressed. */
+    onBack?: (() => void) | undefined;
+    /** Show the leading back button. @default false */
+    showBack?: boolean;
+};
+/**
+ * Header section of a `PromptPanel`: an optional leading back button and a
+ * centred title. Laid out on a three-column grid (`1fr auto 1fr`) so the
+ * title stays perfectly centred whether or not the back button is present.
+ * The leading slot always reserves `icon-sm` (`size-8`) space so header height
+ * does not shift when `showBack` toggles between steps.
+ *
+ * @param props - The prompt panel header props
+ * @param props.children - Title copy.
+ * @param props.showBack - Show the leading back button. Defaults to false.
+ * @param props.onBack - Called when the back button is pressed.
+ * @param props.backLabel - Accessible label for the back button. Defaults to "Back".
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelHeader onBack={goToPreviousStep} showBack>
+ *   How should it lean?
+ * </PromptPanelHeader>
+ * ```
+ *
+ * @bestPractice Keep the title short - it has no truncation affordance beyond `truncate`, and the panel is a fixed `w-96`.
+ */
+declare const PromptPanelHeader: ({ children, showBack, onBack, backLabel, className, ...props }: PromptPanelHeaderProps) => React.JSX.Element;
+export { PromptPanelHeader };

package/dist/compositions/prompt-panel/prompt-panel-header.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ChevronLeft } from "lucide-react";
+import { Button } from "../../components/button.js";
+import { Flex } from "../../components/flex.js";
+import { Grid } from "../../components/grid.js";
+/**
+ * Header section of a `PromptPanel`: an optional leading back button and a
+ * centred title. Laid out on a three-column grid (`1fr auto 1fr`) so the
+ * title stays perfectly centred whether or not the back button is present.
+ * The leading slot always reserves `icon-sm` (`size-8`) space so header height
+ * does not shift when `showBack` toggles between steps.
+ *
+ * @param props - The prompt panel header props
+ * @param props.children - Title copy.
+ * @param props.showBack - Show the leading back button. Defaults to false.
+ * @param props.onBack - Called when the back button is pressed.
+ * @param props.backLabel - Accessible label for the back button. Defaults to "Back".
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelHeader onBack={goToPreviousStep} showBack>
+ *   How should it lean?
+ * </PromptPanelHeader>
+ * ```
+ *
+ * @bestPractice Keep the title short - it has no truncation affordance beyond `truncate`, and the panel is a fixed `w-96`.
+ */
+const PromptPanelHeader = ({ children, showBack = false, onBack, backLabel = "Back", className, ...props }) => (_jsxs(Grid, { align: "center", className: cn("w-full grid-cols-[1fr_auto_1fr] pt-3 pr-3 pl-4", className), columns: "none", "data-component": "prompt-panel-header", "data-slot": "prompt-panel-header", gap: "xs", ...props, children: [_jsx(Flex, { align: "center", children: showBack ? (_jsx(Button, { "aria-label": backLabel, emphasis: "outline", icon: ChevronLeft, onClick: onBack, size: "icon-sm", type: "button" })) : (_jsx("div", { "aria-hidden": "true", className: "size-8" })) }), _jsx("h2", { className: "text-foreground text-paragraph truncate text-center font-semibold", children: children }), _jsx("div", { "aria-hidden": "true", className: "size-8 justify-self-end" })] }));
+export { PromptPanelHeader };

package/dist/compositions/prompt-panel/prompt-panel-option.d.ts

@@ -0,0 +1,33 @@
+import type * as React from "react";
+export type PromptPanelOptionProps = Omit<React.ComponentProps<"button">, "children" | "type"> & {
+    /** Option label. */
+    children: React.ReactNode;
+    /** Keyboard-hover state - visually matches `:hover` for roving keyboard focus. @default false */
+    highlighted?: boolean;
+    /** Digit shown in the leading `Kbd` (matches `usePromptPanelKeyboard`'s 1–9 shortcuts). */
+    shortcut: string | number;
+};
+/**
+ * Selectable option row inside a `PromptPanel` - a leading `Kbd` shortcut digit
+ * and a label. Full-width, borderless until hover (muted wash), and keyboard
+ * selectable via `usePromptPanelKeyboard`'s digit contract.
+ *
+ * @param props - The prompt panel option props
+ * @param props.shortcut - Digit shown in the leading `Kbd`.
+ * @param props.highlighted - Keyboard-hover state, visually matching `:hover`. Defaults to false.
+ * @param props.children - Option label.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other standard HTML button element props.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelOption onClick={handleSelect} shortcut={2}>
+ *   Show me a sustainable option
+ * </PromptPanelOption>
+ * ```
+ *
+ * @bestPractice Number `shortcut`s 1–9 in row order - `usePromptPanelKeyboard` maps digit keys to that same index.
+ * @bestPractice Drive `highlighted` from roving keyboard focus (e.g. arrow-key navigation), not from `:hover` - hover is handled for you.
+ */
+declare const PromptPanelOption: ({ shortcut, highlighted, className, children, ...props }: PromptPanelOptionProps) => React.JSX.Element;
+export { PromptPanelOption };

package/dist/compositions/prompt-panel/prompt-panel-option.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Kbd } from "../../components/kbd.js";
+const PROMPT_PANEL_OPTION_CLASSES = cn(
+// focusRing() leads cn() so the superset transition list below survives
+// the tailwind-merge conflict (transition-trap idiom, see check-transition-order).
+focusRing(), "group flex w-full cursor-pointer items-center gap-2 rounded-lg py-3 pr-2 pl-3 text-left select-none", "duration-quick transition-colors ease-out", 
+// Fine-pointer only - touch taps must not leave a stuck :hover wash.
+"[@media(hover:hover)_and_(pointer:fine)]:hover:bg-muted", "active:scale-[0.98]", "data-[highlighted=true]:bg-muted", "disabled:pointer-events-none disabled:opacity-50");
+const PROMPT_PANEL_OPTION_KBD_CLASSES = cn("duration-quick shrink-0 transition-colors ease-out", 
+// Idle: muted chip. Hover / keyboard-highlight: invert to background on the muted row.
+"[@media(hover:hover)_and_(pointer:fine)]:group-hover:bg-background", "group-data-[highlighted=true]:bg-background");
+/**
+ * Selectable option row inside a `PromptPanel` - a leading `Kbd` shortcut digit
+ * and a label. Full-width, borderless until hover (muted wash), and keyboard
+ * selectable via `usePromptPanelKeyboard`'s digit contract.
+ *
+ * @param props - The prompt panel option props
+ * @param props.shortcut - Digit shown in the leading `Kbd`.
+ * @param props.highlighted - Keyboard-hover state, visually matching `:hover`. Defaults to false.
+ * @param props.children - Option label.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other standard HTML button element props.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelOption onClick={handleSelect} shortcut={2}>
+ *   Show me a sustainable option
+ * </PromptPanelOption>
+ * ```
+ *
+ * @bestPractice Number `shortcut`s 1–9 in row order - `usePromptPanelKeyboard` maps digit keys to that same index.
+ * @bestPractice Drive `highlighted` from roving keyboard focus (e.g. arrow-key navigation), not from `:hover` - hover is handled for you.
+ */
+const PromptPanelOption = ({ shortcut, highlighted = false, className, children, ...props }) => (_jsxs("button", { className: cn(PROMPT_PANEL_OPTION_CLASSES, className), "data-component": "prompt-panel-option", "data-highlighted": highlighted ? true : undefined, "data-slot": "prompt-panel-option", ...props, type: "button", children: [_jsx(Kbd, { className: PROMPT_PANEL_OPTION_KBD_CLASSES, size: "sm", children: shortcut }), _jsx("span", { className: "text-foreground text-paragraph-sm min-w-0 flex-1 truncate font-medium", children: children })] }));
+export { PromptPanelOption };

package/dist/compositions/prompt-panel/prompt-panel-root.d.ts

@@ -0,0 +1,39 @@
+import type * as React from "react";
+import type { WithTestId } from "../../utils/with-test-id.js";
+export type PromptPanelProps = WithTestId<React.ComponentProps<"div">> & {
+    /**
+     * Panel title, used to derive `aria-label` when one isn't explicitly
+     * provided. Pass the same copy given to `PromptPanelHeader`.
+     */
+    title?: string;
+};
+/**
+ * Floating panel root - a shadowed card that prompts the user to pick an action
+ * or describe one. Compose it with `PromptPanelHeader` and
+ * `PromptPanelBody` (which stacks `PromptPanelOption`/`PromptPanelFreeform`
+ * rows); use `PromptPanelStage` around the body to animate between steps.
+ *
+ * @param props - The prompt panel props
+ * @param props.title - Panel title; used to derive `aria-label` when one isn't explicitly passed.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.testId - Test ID for testing purposes.
+ * @param props.children - Panel content - typically `PromptPanelHeader` + `PromptPanelBody`.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanel title="What would you like to do?">
+ *   <PromptPanelHeader>What would you like to do?</PromptPanelHeader>
+ *   <PromptPanelBody>
+ *     <PromptPanelOption shortcut={1}>Find similar</PromptPanelOption>
+ *     <PromptPanelFreeform onSubmit={handleSubmit} />
+ *   </PromptPanelBody>
+ * </PromptPanel>
+ * ```
+ *
+ * @bestPractice Pass `title` (or an explicit `aria-label`) - the panel is a `role="dialog"` surface floating over other content, so it needs an accessible name of its own.
+ * @bestPractice Wrap step transitions in `PromptPanelStage`, not a hand-rolled page swap - it owns the page-slide choreography and the reduced-motion fallback.
+ * @category assistant
+ */
+declare const PromptPanel: ({ className, title, role, testId, "aria-label": ariaLabel, ...props }: PromptPanelProps) => React.JSX.Element;
+export { PromptPanel };

package/dist/compositions/prompt-panel/prompt-panel-root.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Floating panel root - a shadowed card that prompts the user to pick an action
+ * or describe one. Compose it with `PromptPanelHeader` and
+ * `PromptPanelBody` (which stacks `PromptPanelOption`/`PromptPanelFreeform`
+ * rows); use `PromptPanelStage` around the body to animate between steps.
+ *
+ * @param props - The prompt panel props
+ * @param props.title - Panel title; used to derive `aria-label` when one isn't explicitly passed.
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.testId - Test ID for testing purposes.
+ * @param props.children - Panel content - typically `PromptPanelHeader` + `PromptPanelBody`.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanel title="What would you like to do?">
+ *   <PromptPanelHeader>What would you like to do?</PromptPanelHeader>
+ *   <PromptPanelBody>
+ *     <PromptPanelOption shortcut={1}>Find similar</PromptPanelOption>
+ *     <PromptPanelFreeform onSubmit={handleSubmit} />
+ *   </PromptPanelBody>
+ * </PromptPanel>
+ * ```
+ *
+ * @bestPractice Pass `title` (or an explicit `aria-label`) - the panel is a `role="dialog"` surface floating over other content, so it needs an accessible name of its own.
+ * @bestPractice Wrap step transitions in `PromptPanelStage`, not a hand-rolled page swap - it owns the page-slide choreography and the reduced-motion fallback.
+ * @category assistant
+ */
+const PromptPanel = ({ className, title, role = "dialog", testId, "aria-label": ariaLabel, ...props }) => (_jsx("div", { "aria-label": ariaLabel ?? title, className: cn("bg-popover text-popover-foreground w-96 overflow-hidden rounded-2xl shadow-lg", className), "data-component": "prompt-panel", "data-slot": "prompt-panel", "data-testid": testId, role: role, ...props }));
+export { PromptPanel };

package/dist/compositions/prompt-panel/prompt-panel-stage.d.ts

@@ -0,0 +1,47 @@
+import * as React from "react";
+export interface PromptPanelStageProps {
+    /** The current step's content - swap it whenever `stepKey` changes. */
+    children: React.ReactNode;
+    className?: string;
+    /**
+     * Which way the transition travels: `1` (deeper - enters from the right /
+     * page 2), `-1` (back - enters from the left / page 1), or `0` (snap, no
+     * directional bias; used on first mount). @default 0
+     */
+    direction?: -1 | 0 | 1;
+    /** Identifies the current step; changing it triggers the transition. */
+    stepKey: string;
+}
+/**
+ * Page-slide stage for `PromptPanel` step transitions. Two stacked pages crossfade with an 8px horizontal
+ * slide and 3px blur; `data-page` on the container picks the active page.
+ * Forward (`direction={1}`) lands on page 2 (enter from the right, exit left);
+ * back (`direction={-1}`) lands on page 1 (enter from the left, exit right).
+ * Height snaps to the active page - no layout/height morph. Under
+ * `prefers-reduced-motion`, CSS disables the transition so the flip is instant.
+ * Each page stacks its children with `gap="xs"` (8px).
+ *
+ * @param props - The prompt panel stage props
+ * @param props.stepKey - Identifies the current step; changing it triggers the transition.
+ * @param props.direction - Which way the transition travels: 1 (deeper), -1 (back), 0 (snap). Defaults to 0.
+ * @param props.children - The current step's content - a full step page (header + body with options and freeform), or sibling option rows.
+ * @param props.className - Additional CSS classes to apply.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelStage direction={direction} stepKey={step}>
+ *   <div className="w-full">
+ *     <PromptPanelHeader>{title}</PromptPanelHeader>
+ *     <PromptPanelBody>
+ *       {options}
+ *       <PromptPanelFreeform placeholder={freeformPlaceholder} />
+ *     </PromptPanelBody>
+ *   </div>
+ * </PromptPanelStage>
+ * ```
+ *
+ * @bestPractice Track `direction` alongside `stepKey` in the parent's step state - going deeper is `1`, going back is `-1`; the stage can't infer it from the key alone.
+ * @bestPractice Put freeform (and header) inside the stage page for multi-step flows so they participate in the page-slide; a freeform sibling outside Stage stays static and flashes when stage height snaps.
+ */
+declare const PromptPanelStage: ({ stepKey, direction, children, className, }: PromptPanelStageProps) => React.JSX.Element;
+export { PromptPanelStage };

package/dist/compositions/prompt-panel/prompt-panel-stage.js

@@ -0,0 +1,161 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import * as React from "react";
+import { flushSync } from "react-dom";
+import { Stack } from "../../components/stack.js";
+const slotsForDirection = (goForward, outgoing, incoming) => goForward
+    ? { "1": outgoing, "2": incoming }
+    : { "1": incoming, "2": outgoing };
+const PromptPanelStagePane = ({ active, onHeightChange, pageId, children, }) => {
+    const innerRef = React.useRef(null);
+    React.useLayoutEffect(() => {
+        const inner = innerRef.current;
+        if (inner === null) {
+            return () => {
+                // not mounted
+            };
+        }
+        const update = () => {
+            onHeightChange(pageId, inner.offsetHeight);
+        };
+        update();
+        const observer = new ResizeObserver(update);
+        observer.observe(inner);
+        return () => {
+            observer.disconnect();
+        };
+    }, [onHeightChange, pageId]);
+    return (_jsx("div", { "aria-hidden": !active, className: "page-slide-pane", "data-page-id": pageId, inert: active ? undefined : true, children: _jsx("div", { ref: innerRef, children: _jsx(Stack, { className: "w-full", gap: "xs", children: children }) }) }));
+};
+const useStageStepTransition = (stepKey, direction, children, rootRef) => {
+    const pendingFlipRef = React.useRef(null);
+    const [state, setState] = React.useState(() => ({
+        activePage: "1",
+        slots: { "1": { key: stepKey, node: children }, "2": null },
+    }));
+    const stateRef = React.useRef(state);
+    const stepKeyRef = React.useRef(stepKey);
+    React.useLayoutEffect(() => {
+        stateRef.current = state;
+    }, [state]);
+    React.useLayoutEffect(() => {
+        if (stepKeyRef.current === stepKey) {
+            setState((previous) => {
+                const existing = previous.slots[previous.activePage];
+                if (existing !== null && existing.node === children) {
+                    return previous;
+                }
+                return {
+                    ...previous,
+                    slots: {
+                        ...previous.slots,
+                        [previous.activePage]: { key: stepKey, node: children },
+                    },
+                };
+            });
+            return;
+        }
+        const fromPage = stateRef.current.activePage;
+        const outgoing = stateRef.current.slots[fromPage] ?? {
+            key: stepKeyRef.current,
+            node: children,
+        };
+        const incoming = { key: stepKey, node: children };
+        stepKeyRef.current = stepKey;
+        if (direction === 0) {
+            const root = rootRef.current;
+            if (root !== null) {
+                root.style.setProperty("--page-slide-dur", "0ms");
+                root.style.setProperty("--page-fade-dur", "0ms");
+            }
+            flushSync(() => {
+                setState({
+                    activePage: "1",
+                    slots: { "1": incoming, "2": null },
+                });
+            });
+            if (root !== null) {
+                root.style.removeProperty("--page-slide-dur");
+                root.style.removeProperty("--page-fade-dur");
+            }
+            return;
+        }
+        const goForward = direction === 1;
+        const targetPage = goForward ? "2" : "1";
+        const nextSlots = slotsForDirection(goForward, outgoing, incoming);
+        if (fromPage !== targetPage) {
+            setState({ activePage: targetPage, slots: nextSlots });
+            return;
+        }
+        const prepPage = goForward ? "1" : "2";
+        const root = rootRef.current;
+        if (root !== null) {
+            root.style.setProperty("--page-slide-dur", "0ms");
+            root.style.setProperty("--page-fade-dur", "0ms");
+        }
+        pendingFlipRef.current = { slots: nextSlots, targetPage };
+        setState({ activePage: prepPage, slots: nextSlots });
+    }, [stepKey, direction, children, rootRef]);
+    React.useLayoutEffect(() => {
+        const pending = pendingFlipRef.current;
+        if (pending === null || state.activePage === pending.targetPage) {
+            return;
+        }
+        pendingFlipRef.current = null;
+        const root = rootRef.current;
+        void root?.offsetWidth;
+        if (root !== null) {
+            root.style.removeProperty("--page-slide-dur");
+            root.style.removeProperty("--page-fade-dur");
+        }
+        setState({ activePage: pending.targetPage, slots: pending.slots });
+    }, [state.activePage, rootRef]);
+    return state;
+};
+/**
+ * Page-slide stage for `PromptPanel` step transitions. Two stacked pages crossfade with an 8px horizontal
+ * slide and 3px blur; `data-page` on the container picks the active page.
+ * Forward (`direction={1}`) lands on page 2 (enter from the right, exit left);
+ * back (`direction={-1}`) lands on page 1 (enter from the left, exit right).
+ * Height snaps to the active page - no layout/height morph. Under
+ * `prefers-reduced-motion`, CSS disables the transition so the flip is instant.
+ * Each page stacks its children with `gap="xs"` (8px).
+ *
+ * @param props - The prompt panel stage props
+ * @param props.stepKey - Identifies the current step; changing it triggers the transition.
+ * @param props.direction - Which way the transition travels: 1 (deeper), -1 (back), 0 (snap). Defaults to 0.
+ * @param props.children - The current step's content - a full step page (header + body with options and freeform), or sibling option rows.
+ * @param props.className - Additional CSS classes to apply.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelStage direction={direction} stepKey={step}>
+ *   <div className="w-full">
+ *     <PromptPanelHeader>{title}</PromptPanelHeader>
+ *     <PromptPanelBody>
+ *       {options}
+ *       <PromptPanelFreeform placeholder={freeformPlaceholder} />
+ *     </PromptPanelBody>
+ *   </div>
+ * </PromptPanelStage>
+ * ```
+ *
+ * @bestPractice Track `direction` alongside `stepKey` in the parent's step state - going deeper is `1`, going back is `-1`; the stage can't infer it from the key alone.
+ * @bestPractice Put freeform (and header) inside the stage page for multi-step flows so they participate in the page-slide; a freeform sibling outside Stage stays static and flashes when stage height snaps.
+ */
+const PromptPanelStage = ({ stepKey, direction = 0, children, className, }) => {
+    const rootRef = React.useRef(null);
+    const { activePage, slots } = useStageStepTransition(stepKey, direction, children, rootRef);
+    const [heights, setHeights] = React.useState({
+        "1": undefined,
+        "2": undefined,
+    });
+    const handleHeightChange = React.useCallback((pageId, height) => {
+        setHeights((previous) => previous[pageId] === height
+            ? previous
+            : { ...previous, [pageId]: height });
+    }, []);
+    return (_jsxs("div", { className: cn("page-slide w-full overflow-hidden", className), "data-component": "prompt-panel-stage", "data-page": activePage, "data-slot": "prompt-panel-stage", ref: rootRef, style: { height: heights[activePage] }, children: [_jsx(PromptPanelStagePane, { active: activePage === "1", onHeightChange: handleHeightChange, pageId: "1", children: slots["1"]?.node }), _jsx(PromptPanelStagePane, { active: activePage === "2", onHeightChange: handleHeightChange, pageId: "2", children: slots["2"]?.node })] }));
+};
+export { PromptPanelStage };

package/dist/compositions/prompt-panel/prompt-panel-view.d.ts

@@ -0,0 +1,67 @@
+export interface PromptPanelViewOption {
+    /** Stable identifier, passed to `onSelectOption`. */
+    id: string;
+    /** Option label. */
+    label: string;
+    /** Digit shown in the leading `Kbd`; defaults to the option's 1-based position. */
+    shortcut?: number | string;
+}
+export interface PromptPanelViewProps {
+    /** Placeholder for the freeform row. */
+    freeformPlaceholder?: string;
+    /** Controlled value for the freeform row; omit for uncontrolled usage. */
+    freeformValue?: string;
+    /** Option `id` currently highlighted by keyboard navigation, if any. */
+    highlightedOptionId?: null | string;
+    /** Called when the back button is pressed, or Backspace on an empty freeform. */
+    onBack?: () => void;
+    /** Called when Escape is pressed in the freeform input. */
+    onEscape?: () => void;
+    /** Called with the next value on every freeform keystroke. */
+    onFreeformChange?: (value: string) => void;
+    /** Called with the option's `id` when a row is selected. */
+    onSelectOption: (id: string) => void;
+    /** Called with the freeform text when it's submitted. */
+    onSubmitFreeform: (text: string) => void;
+    /** Selectable option rows, in display order. */
+    options: PromptPanelViewOption[];
+    /** Show the leading back button. @default false */
+    showBack?: boolean;
+    /** Panel/step title. */
+    title: string;
+}
+/**
+ * Thin data-driven composition over `PromptPanel` - pass a `title` and an
+ * `options` array and it renders the full header/body/freeform structure.
+ * Reach for the individual parts (`PromptPanel`, `PromptPanelHeader`, …)
+ * directly when a step needs bespoke content the `options` array can't
+ * express; this composition is a convenience, not the only supported shape.
+ *
+ * @param props - The prompt panel view props
+ * @param props.title - Panel/step title.
+ * @param props.showBack - Show the leading back button. Defaults to false.
+ * @param props.onBack - Called when the back button is pressed, or Backspace on an empty freeform.
+ * @param props.onEscape - Called when Escape is pressed in the freeform input.
+ * @param props.options - Selectable option rows, in display order.
+ * @param props.onSelectOption - Called with the option's `id` when a row is selected.
+ * @param props.highlightedOptionId - Option `id` currently highlighted by keyboard navigation.
+ * @param props.freeformPlaceholder - Placeholder for the freeform row.
+ * @param props.freeformValue - Controlled value for the freeform row.
+ * @param props.onFreeformChange - Called with the next value on every freeform keystroke.
+ * @param props.onSubmitFreeform - Called with the freeform text when it's submitted.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelView
+ *   onSelectOption={(id) => runOption(id)}
+ *   onSubmitFreeform={(text) => runPrompt(text)}
+ *   options={[
+ *     { id: "find-similar", label: "Find similar" },
+ *     { id: "sustainable", label: "Show me a sustainable option" },
+ *   ]}
+ *   title="What would you like to do?"
+ * />
+ * ```
+ */
+declare const PromptPanelView: ({ title, showBack, onBack, onEscape, options, onSelectOption, highlightedOptionId, freeformPlaceholder, freeformValue, onFreeformChange, onSubmitFreeform, }: PromptPanelViewProps) => import("react").JSX.Element;
+export { PromptPanelView };

package/dist/compositions/prompt-panel/prompt-panel-view.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PromptPanelBody } from "./prompt-panel-body.js";
+import { PromptPanelFreeform } from "./prompt-panel-freeform.js";
+import { PromptPanelHeader } from "./prompt-panel-header.js";
+import { PromptPanelOption } from "./prompt-panel-option.js";
+import { PromptPanel } from "./prompt-panel-root.js";
+import { usePromptPanelKeyboard } from "./use-prompt-panel-keyboard.js";
+/**
+ * Thin data-driven composition over `PromptPanel` - pass a `title` and an
+ * `options` array and it renders the full header/body/freeform structure.
+ * Reach for the individual parts (`PromptPanel`, `PromptPanelHeader`, …)
+ * directly when a step needs bespoke content the `options` array can't
+ * express; this composition is a convenience, not the only supported shape.
+ *
+ * @param props - The prompt panel view props
+ * @param props.title - Panel/step title.
+ * @param props.showBack - Show the leading back button. Defaults to false.
+ * @param props.onBack - Called when the back button is pressed, or Backspace on an empty freeform.
+ * @param props.onEscape - Called when Escape is pressed in the freeform input.
+ * @param props.options - Selectable option rows, in display order.
+ * @param props.onSelectOption - Called with the option's `id` when a row is selected.
+ * @param props.highlightedOptionId - Option `id` currently highlighted by keyboard navigation.
+ * @param props.freeformPlaceholder - Placeholder for the freeform row.
+ * @param props.freeformValue - Controlled value for the freeform row.
+ * @param props.onFreeformChange - Called with the next value on every freeform keystroke.
+ * @param props.onSubmitFreeform - Called with the freeform text when it's submitted.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelView
+ *   onSelectOption={(id) => runOption(id)}
+ *   onSubmitFreeform={(text) => runPrompt(text)}
+ *   options={[
+ *     { id: "find-similar", label: "Find similar" },
+ *     { id: "sustainable", label: "Show me a sustainable option" },
+ *   ]}
+ *   title="What would you like to do?"
+ * />
+ * ```
+ */
+const PromptPanelView = ({ title, showBack = false, onBack, onEscape, options, onSelectOption, highlightedOptionId, freeformPlaceholder, freeformValue, onFreeformChange, onSubmitFreeform, }) => {
+    const { onKeyDown } = usePromptPanelKeyboard({
+        onSelectOption: (index) => {
+            const option = options[index];
+            if (option !== undefined) {
+                onSelectOption(option.id);
+            }
+        },
+        onSubmit: onSubmitFreeform,
+        optionCount: options.length,
+        onBack,
+        onEscape,
+    });
+    return (_jsxs(PromptPanel, { title: title, children: [_jsx(PromptPanelHeader, { onBack: onBack, showBack: showBack, children: title }), _jsxs(PromptPanelBody, { children: [options.map((option, index) => (_jsx(PromptPanelOption, { highlighted: highlightedOptionId === option.id, onClick: () => {
+                            onSelectOption(option.id);
+                        }, shortcut: option.shortcut ?? index + 1, children: option.label }, option.id))), _jsx(PromptPanelFreeform, { onKeyDown: onKeyDown, onSubmit: onSubmitFreeform, onValueChange: onFreeformChange, placeholder: freeformPlaceholder, value: freeformValue })] })] }));
+};
+export { PromptPanelView };