@instruments/materia-ui 0.1.0

package/dist/compositions/product-card.js

@@ -0,0 +1,23 @@
+export { ProductCardAction } from "./product-card/product-card-action.js";
+export { ProductCardAddToCart } from "./product-card/product-card-add-to-cart.js";
+export { ProductCardAvailabilityStatus } from "./product-card/product-card-availability.js";
+export { ProductCardCaption } from "./product-card/product-card-caption.js";
+export { ProductCardCategory } from "./product-card/product-card-category.js";
+export { ProductCardColorCount } from "./product-card/product-card-color-count.js";
+export { ProductCardContent } from "./product-card/product-card-content.js";
+export { useProductCard } from "./product-card/product-card-context.js";
+export { ProductCardCost } from "./product-card/product-card-cost.js";
+export { ProductCardImage } from "./product-card/product-card-image.js";
+export { ProductCardInstallShotToggle } from "./product-card/product-card-install-shot.js";
+export { ProductCardMeta } from "./product-card/product-card-meta.js";
+export { ProductCardFindSimilar, ProductCardPrimaryActionControl, } from "./product-card/product-card-primary-action.js";
+export { ProductCardProvider } from "./product-card/product-card-provider.js";
+export { ProductCardQuickView } from "./product-card/product-card-quick-view.js";
+export { ProductCard } from "./product-card/product-card-root.js";
+export { ProductCardSkeleton } from "./product-card/product-card-skeleton.js";
+export { ProductCardStatusBadge } from "./product-card/product-card-status-badge.js";
+export { ProductCardProcessing } from "./product-card/product-card-processing.js";
+export { ProductCardSwatch } from "./product-card/product-card-swatch.js";
+export { ProductCardSwatchAdd } from "./product-card/product-card-swatch-add.js";
+export { ProductCardSwatchSelector } from "./product-card/product-card-swatch-selector.js";
+export { ProductCardTools } from "./product-card/product-card-tools.js";

package/dist/compositions/product-specifications-selector/product-specifications-fields.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import type { ImageRenderProps, VariantDimension, VariantOption } from "./product-specifications-types.js";
+export interface DimensionFieldProps {
+    dimension: VariantDimension;
+    filterKey: string;
+    highlightedValues: Set<string> | undefined;
+    onAvailableSelect: (args: {
+        dimension: VariantDimension;
+        filterKey: string;
+        resolvedSelectedValue: string | null;
+        value: string;
+    }) => void;
+    onOptionHover: (dimension: VariantDimension, value: string, available: boolean) => void;
+    onOptionLeave: () => void;
+    onUnavailableSelect: (dimension: VariantDimension, value: string) => void;
+    options: VariantOption[];
+    renderImage: (props: ImageRenderProps) => ReactNode;
+    selectedValue: string | null;
+}
+/** One variant dimension: image swatches (visual) or text chips (non-visual). */
+export declare const DimensionField: ({ dimension, filterKey, highlightedValues, onAvailableSelect, onOptionHover, onOptionLeave, onUnavailableSelect, options, renderImage, selectedValue, }: DimensionFieldProps) => import("react").JSX.Element | null;
+export interface SiblingImage {
+    firstImage: string | null;
+    id: string;
+    name: string;
+}
+/** Fallback colorway selector shown when no variant attributes differ. */
+export declare const SiblingFallbackField: ({ onSiblingSelect, renderImage, selectedFallbackSiblingId, siblingsWithImages, }: {
+    onSiblingSelect?: (siblingId: string) => void;
+    renderImage: (props: ImageRenderProps) => ReactNode;
+    selectedFallbackSiblingId: string | undefined;
+    siblingsWithImages: SiblingImage[];
+}) => import("react").JSX.Element;

package/dist/compositions/product-specifications-selector/product-specifications-fields.js

@@ -0,0 +1,99 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Label } from "@instruments/materia-ui/components/label";
+import { RadioCard, RadioCardContent, RadioCardGroup, RadioCardTitle, } from "@instruments/materia-ui/components/radio-card";
+import { VariantSelector, VariantSelectorItem, } from "@instruments/materia-ui/compositions/variant-selector";
+import { hasText } from "../../utils/type-guards.js";
+const VISUAL_DIMENSIONS = new Set([
+    "colorName",
+    "pattern",
+    "finish",
+    "substrate",
+]);
+const isVisualDimension = (dimension) => VISUAL_DIMENSIONS.has(dimension);
+const VARIANT_LABELS = {
+    colorName: "Color",
+    finish: "Finish",
+    length: "Length",
+    pattern: "Pattern",
+    finishType: "Finish Type",
+    size: "Size",
+    substrate: "Substrate",
+    width: "Width",
+};
+const findSelectedOption = (options, selectedValue) => {
+    if (!hasText(selectedValue)) {
+        return undefined;
+    }
+    const normalized = selectedValue.trim().toLowerCase();
+    return options.find((o) => {
+        if (o.value === selectedValue || o.label === selectedValue) {
+            return true;
+        }
+        return (o.value.trim().toLowerCase() === normalized ||
+            o.label.trim().toLowerCase() === normalized);
+    });
+};
+/** Dimension caption with the formatted selected value in parentheses. */
+const DimensionLabel = ({ label, selectedLabel, }) => (_jsxs(Label, { className: "mb-2", children: [label, hasText(selectedLabel) && (_jsxs("span", { className: "text-muted-foreground", children: [" (", selectedLabel, ")"] }))] }));
+/** One variant dimension: image swatches (visual) or text chips (non-visual). */
+export const DimensionField = ({ dimension, filterKey, highlightedValues, onAvailableSelect, onOptionHover, onOptionLeave, onUnavailableSelect, options, renderImage, selectedValue, }) => {
+    if (options.length === 0) {
+        return null;
+    }
+    const selectedOption = findSelectedOption(options, selectedValue);
+    const resolvedSelectedValue = selectedOption?.value ?? null;
+    const label = VARIANT_LABELS[dimension];
+    const selectedLabel = selectedOption?.label ?? null;
+    if (isVisualDimension(dimension)) {
+        return (_jsxs("div", { children: [_jsx(DimensionLabel, { label: label, selectedLabel: selectedLabel }), _jsx(VariantSelector, { "aria-label": `${label} options`, className: "grid-cols-[repeat(auto-fill,minmax(72px,1fr))] gap-2", mode: "single", onValueChange: (value) => {
+                        const option = options.find((o) => o.value === value);
+                        if (option?.available === false) {
+                            onUnavailableSelect(dimension, value);
+                            return;
+                        }
+                        onAvailableSelect({
+                            dimension,
+                            filterKey,
+                            resolvedSelectedValue,
+                            value,
+                        });
+                    }, ...(resolvedSelectedValue === null
+                        ? {}
+                        : { value: resolvedSelectedValue }), children: options.map((option) => (_jsx(VariantSelectorItem, { highlighted: highlightedValues?.has(option.value) ?? false, image: hasText(option.image)
+                            ? renderImage({
+                                alt: option.label,
+                                className: "size-full object-cover",
+                                src: option.image,
+                            })
+                            : undefined, label: option.label, onMouseEnter: () => {
+                            onOptionHover(dimension, option.value, option.available !== false);
+                        }, onMouseLeave: onOptionLeave, unavailable: option.available === false, value: option.value }, option.value))) })] }));
+    }
+    return (_jsxs("div", { children: [_jsx(DimensionLabel, { label: label, selectedLabel: selectedLabel }), _jsx(RadioCardGroup, { layout: "inline", onValueChange: (value) => {
+                    onAvailableSelect({
+                        dimension,
+                        filterKey,
+                        resolvedSelectedValue,
+                        value,
+                    });
+                }, showIndicator: false, size: "sm", ...(resolvedSelectedValue === null
+                    ? {}
+                    : { value: resolvedSelectedValue }), children: options.map((option) => (_jsx(RadioCard, { disabled: option.available === false, value: option.value, children: _jsx(RadioCardContent, { children: _jsx(RadioCardTitle, { children: option.label }) }) }, option.value))) })] }));
+};
+/** Fallback colorway selector shown when no variant attributes differ. */
+export const SiblingFallbackField = ({ onSiblingSelect, renderImage, selectedFallbackSiblingId, siblingsWithImages, }) => (_jsxs("div", { children: [_jsx(Label, { className: "mb-2", children: siblingsWithImages.length === 1
+                ? "Colorway"
+                : `Colorways (${siblingsWithImages.length})` }), _jsx(VariantSelector, { "aria-label": "Colorway options", className: "grid-cols-[repeat(auto-fill,minmax(72px,1fr))] gap-2", mode: "single", onValueChange: (value) => {
+                if (value !== "" && onSiblingSelect) {
+                    onSiblingSelect(value);
+                }
+            }, ...(selectedFallbackSiblingId === undefined
+                ? {}
+                : { value: selectedFallbackSiblingId }), children: siblingsWithImages.map((sibling) => (_jsx(VariantSelectorItem, { image: hasText(sibling.firstImage)
+                    ? renderImage({
+                        alt: sibling.name,
+                        className: "size-full object-cover",
+                        src: sibling.firstImage,
+                    })
+                    : undefined, label: sibling.name, value: sibling.id }, sibling.id))) })] }));

package/dist/compositions/product-specifications-selector/product-specifications-selector.d.ts

@@ -0,0 +1,44 @@
+import type { ReactNode } from "react";
+import type { ImageRenderProps, VariantAttributes, VariantOptions } from "./product-specifications-types.js";
+export type { ImageRenderProps, VariantAttributes, VariantDimension, VariantOption, VariantOptions, } from "./product-specifications-types.js";
+/** Sibling product data for fallback variant selection */
+interface Sibling {
+    firstImage: string | null;
+    id: string;
+    name: string;
+    slug: string;
+}
+/** Full sibling data with variant attributes for computing compatible options */
+interface SiblingWithAttributes {
+    id: string;
+    variantAttributes: VariantAttributes | null;
+}
+export interface ProductSpecificationsSelectorProps {
+    filters: Record<string, string | null>;
+    onFilterChange: (key: string, value: string | null) => void;
+    /** Callback when a sibling is selected (fallback variant selection) */
+    onSiblingSelect?: (siblingId: string) => void;
+    /** Custom image renderer (e.g., for next/image). Defaults to standard img element. */
+    renderImage?: (props: ImageRenderProps) => ReactNode;
+    /** Currently selected product ID (for highlighting in sibling selector) */
+    selectedProductId?: string;
+    /** Sibling products for fallback variant selection when variantOptions is empty */
+    siblings?: Sibling[];
+    /** Full sibling data with variant attributes for computing compatible options on hover */
+    siblingsWithAttributes?: SiblingWithAttributes[];
+    variantOptions: VariantOptions;
+}
+/**
+ * Renders the stack of variant/filter selector fields for a product so a
+ * product configuration can be refined interactively.
+ *
+ * The component renders only the field stack - no card, heading, or CTA
+ * chrome. Compose those around it (a `Card`, your own title) when a surface
+ * calls for a titled panel.
+ *
+ * @bestPractice Drive it as a controlled component: it renders from `filters` and emits `onFilterChange(key, value)` - it holds no internal filter state, so persist the value and feed it back.
+ * @bestPractice It renders nothing when there are no `variantOptions` dimensions and no `siblings` with images - supply `siblings`/`siblingsWithAttributes` so single-colourway products still show a fallback thumbnail.
+ * @bestPractice Pass `renderImage` (wrapping `next/image`) in Next.js; the default is a plain `<img>`. The component ships bare - wrap it in a `Card` with your own heading when a panel is wanted.
+ * @category catalogue
+ */
+export declare const ProductSpecificationsSelector: ({ variantOptions, filters, onFilterChange, onSiblingSelect, selectedProductId, siblings, siblingsWithAttributes, renderImage, }: ProductSpecificationsSelectorProps) => import("react").JSX.Element | null;

package/dist/compositions/product-specifications-selector/product-specifications-selector.js

@@ -0,0 +1,80 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Stack } from "@instruments/materia-ui/components/stack";
+import { DimensionField, SiblingFallbackField, } from "./product-specifications-fields.js";
+import { isVariantDimension } from "./product-specifications-types.js";
+import { useVariantHighlighting } from "./use-variant-highlighting.js";
+// Map dimension keys back to URL filter keys
+const DIMENSION_TO_FILTER = {
+    colorName: "color",
+    finish: "finish",
+    length: "length",
+    pattern: "pattern",
+    finishType: "finishType",
+    size: "size",
+    substrate: "substrate",
+    width: "width",
+};
+// Priority order for dimensions - visual (colorways) first, then common attributes
+const DIMENSION_PRIORITY = [
+    "colorName",
+    "pattern",
+    "finish",
+    "size",
+    "width",
+    "length",
+    "substrate",
+    "finishType",
+];
+const defaultRenderImage = ({ src, alt, className, }) => (_jsx("img", { alt: alt, className: className, height: 200, src: src, width: 200 }));
+/**
+ * Renders the stack of variant/filter selector fields for a product so a
+ * product configuration can be refined interactively.
+ *
+ * The component renders only the field stack - no card, heading, or CTA
+ * chrome. Compose those around it (a `Card`, your own title) when a surface
+ * calls for a titled panel.
+ *
+ * @bestPractice Drive it as a controlled component: it renders from `filters` and emits `onFilterChange(key, value)` - it holds no internal filter state, so persist the value and feed it back.
+ * @bestPractice It renders nothing when there are no `variantOptions` dimensions and no `siblings` with images - supply `siblings`/`siblingsWithAttributes` so single-colourway products still show a fallback thumbnail.
+ * @bestPractice Pass `renderImage` (wrapping `next/image`) in Next.js; the default is a plain `<img>`. The component ships bare - wrap it in a `Card` with your own heading when a panel is wanted.
+ * @category catalogue
+ */
+export const ProductSpecificationsSelector = ({ variantOptions, filters, onFilterChange, onSiblingSelect, selectedProductId, siblings, siblingsWithAttributes, renderImage = defaultRenderImage, }) => {
+    const highlightingConfig = {
+        onFilterChange,
+    };
+    if (onSiblingSelect !== undefined) {
+        highlightingConfig.onSiblingSelect = onSiblingSelect;
+    }
+    if (siblingsWithAttributes !== undefined) {
+        highlightingConfig.siblingsWithAttributes = siblingsWithAttributes;
+    }
+    const { handleAvailableOptionSelect, handleOptionHover, handleOptionLeave, handleUnavailableOptionSelect, highlightedOptions, } = useVariantHighlighting(highlightingConfig);
+    // Dimensions that have options, ordered by priority (visual ones first).
+    const dimensions = Object.keys(variantOptions)
+        .filter(isVariantDimension)
+        .toSorted((a, b) => {
+        const aIndex = DIMENSION_PRIORITY.indexOf(a);
+        const bIndex = DIMENSION_PRIORITY.indexOf(b);
+        const aPriority = aIndex === -1 ? 999 : aIndex;
+        const bPriority = bIndex === -1 ? 999 : bIndex;
+        return aPriority - bPriority;
+    });
+    const siblingsWithImages = siblings?.filter((s) => s.firstImage !== null && s.firstImage !== "") ?? [];
+    const selectedFallbackSiblingId = selectedProductId ??
+        (siblingsWithImages.length === 1 ? siblingsWithImages[0]?.id : undefined);
+    // Single-colorway products still need a visible thumbnail confirmation.
+    const showSiblingFallback = dimensions.length === 0 && siblingsWithImages.length > 0;
+    if (dimensions.length === 0 && !showSiblingFallback) {
+        return null;
+    }
+    return (_jsxs(Stack, { gap: "lg", children: [dimensions.map((dimension) => {
+                const options = variantOptions[dimension];
+                if (!options || options.length === 0) {
+                    return null;
+                }
+                const filterKey = DIMENSION_TO_FILTER[dimension];
+                return (_jsx(DimensionField, { dimension: dimension, filterKey: filterKey, highlightedValues: highlightedOptions[dimension], onAvailableSelect: handleAvailableOptionSelect, onOptionHover: handleOptionHover, onOptionLeave: handleOptionLeave, onUnavailableSelect: handleUnavailableOptionSelect, options: options, renderImage: renderImage, selectedValue: filters[filterKey] ?? null }, dimension));
+            }), showSiblingFallback && (_jsx(SiblingFallbackField, { ...(onSiblingSelect === undefined ? {} : { onSiblingSelect }), renderImage: renderImage, selectedFallbackSiblingId: selectedFallbackSiblingId, siblingsWithImages: siblingsWithImages }))] }));
+};

package/dist/compositions/product-specifications-selector/product-specifications-types.d.ts

@@ -0,0 +1,22 @@
+/** All variant dimension keys */
+export declare const VARIANT_DIMENSIONS: readonly ["colorName", "pattern", "finish", "substrate", "size", "width", "finishType", "length"];
+export type VariantDimension = (typeof VARIANT_DIMENSIONS)[number];
+export declare const isVariantDimension: (value: string) => value is VariantDimension;
+/** A single option within a variant dimension */
+export interface VariantOption {
+    available?: boolean;
+    count?: number;
+    image?: string;
+    label: string;
+    value: string;
+}
+/** All variant options for a product group, keyed by dimension */
+export type VariantOptions = Partial<Record<VariantDimension, VariantOption[]>>;
+/** Variant attributes extracted from a product's attributes */
+export type VariantAttributes = Partial<Record<VariantDimension, string | null>>;
+/** Props for custom image renderer */
+export interface ImageRenderProps {
+    alt: string;
+    className: string;
+    src: string;
+}

package/dist/compositions/product-specifications-selector/product-specifications-types.js

@@ -0,0 +1,12 @@
+/** All variant dimension keys */
+export const VARIANT_DIMENSIONS = [
+    "colorName",
+    "pattern",
+    "finish",
+    "substrate",
+    "size",
+    "width",
+    "finishType",
+    "length",
+];
+export const isVariantDimension = (value) => VARIANT_DIMENSIONS.some((dimension) => dimension === value);

package/dist/compositions/product-specifications-selector/use-variant-highlighting.d.ts

@@ -0,0 +1,26 @@
+import type { VariantAttributes, VariantDimension } from "./product-specifications-types.js";
+interface SiblingWithAttributes {
+    id: string;
+    variantAttributes: VariantAttributes | null;
+}
+/**
+ * Tracks the hovered unavailable option and derives, for each other dimension,
+ * the option values that remain compatible - plus the selection handlers.
+ */
+export declare const useVariantHighlighting: ({ siblingsWithAttributes, onSiblingSelect, onFilterChange, }: {
+    onFilterChange: (key: string, value: string | null) => void;
+    onSiblingSelect?: (siblingId: string) => void;
+    siblingsWithAttributes?: SiblingWithAttributes[];
+}) => {
+    handleAvailableOptionSelect: ({ dimension, filterKey, resolvedSelectedValue, value, }: {
+        dimension: VariantDimension;
+        filterKey: string;
+        resolvedSelectedValue: string | null;
+        value: string;
+    }) => void;
+    handleOptionHover: (dimension: VariantDimension, value: string, available: boolean) => void;
+    handleOptionLeave: () => void;
+    handleUnavailableOptionSelect: (dimension: VariantDimension, value: string) => void;
+    highlightedOptions: Partial<Record<"colorName" | "finish" | "finishType" | "length" | "pattern" | "size" | "substrate" | "width", Set<string>>>;
+};
+export {};

package/dist/compositions/product-specifications-selector/use-variant-highlighting.js

@@ -0,0 +1,102 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+import { isVariantDimension } from "./product-specifications-types.js";
+const collectCompatibleValues = (attrs, excludeDimension, result) => {
+    for (const [dim, value] of Object.entries(attrs)) {
+        if (dim === excludeDimension ||
+            value === undefined ||
+            value === null ||
+            value === "") {
+            continue;
+        }
+        if (!isVariantDimension(dim)) {
+            continue;
+        }
+        result[dim] ??= new Set();
+        result[dim]?.add(value);
+    }
+};
+/**
+ * Tracks the hovered unavailable option and derives, for each other dimension,
+ * the option values that remain compatible - plus the selection handlers.
+ */
+export const useVariantHighlighting = ({ siblingsWithAttributes, onSiblingSelect, onFilterChange, }) => {
+    const [hoveredOption, setHoveredOption] = useState(null);
+    const highlightedOptions = useMemo(() => {
+        if (hoveredOption === null ||
+            siblingsWithAttributes === undefined ||
+            siblingsWithAttributes.length === 0) {
+            const empty = {};
+            return empty;
+        }
+        const result = {};
+        const compatibleSiblings = siblingsWithAttributes.filter((s) => {
+            const attrs = s.variantAttributes;
+            if (!attrs) {
+                return false;
+            }
+            return attrs[hoveredOption.dimension] === hoveredOption.value;
+        });
+        for (const sibling of compatibleSiblings) {
+            if (sibling.variantAttributes) {
+                collectCompatibleValues(sibling.variantAttributes, hoveredOption.dimension, result);
+            }
+        }
+        return result;
+    }, [hoveredOption, siblingsWithAttributes]);
+    const handleOptionHover = useCallback((dimension, value, available) => {
+        if (!available) {
+            setHoveredOption({ dimension, value });
+        }
+    }, []);
+    const handleOptionLeave = useCallback(() => {
+        setHoveredOption(null);
+    }, []);
+    const handleUnavailableOptionSelect = useCallback((dimension, value) => {
+        if (siblingsWithAttributes === undefined ||
+            siblingsWithAttributes.length === 0 ||
+            onSiblingSelect === undefined) {
+            return;
+        }
+        const compatibleSibling = siblingsWithAttributes.find((s) => {
+            const attrs = s.variantAttributes;
+            if (!attrs) {
+                return false;
+            }
+            return attrs[dimension] === value;
+        });
+        if (compatibleSibling) {
+            setHoveredOption(null);
+            onSiblingSelect(compatibleSibling.id);
+        }
+    }, [siblingsWithAttributes, onSiblingSelect]);
+    const handleAvailableOptionSelect = useCallback(({ dimension, filterKey, resolvedSelectedValue, value, }) => {
+        const nextValue = value === resolvedSelectedValue ? null : value;
+        if (nextValue !== undefined &&
+            nextValue !== null &&
+            nextValue !== "" &&
+            siblingsWithAttributes !== undefined &&
+            siblingsWithAttributes.length > 0 &&
+            onSiblingSelect !== undefined) {
+            const compatibleSibling = siblingsWithAttributes.find((s) => {
+                const attrs = s.variantAttributes;
+                if (!attrs) {
+                    return false;
+                }
+                return attrs[dimension] === nextValue;
+            });
+            if (compatibleSibling) {
+                onSiblingSelect(compatibleSibling.id);
+                return;
+            }
+        }
+        onFilterChange(filterKey, nextValue);
+    }, [onFilterChange, onSiblingSelect, siblingsWithAttributes]);
+    return {
+        handleAvailableOptionSelect,
+        handleOptionHover,
+        handleOptionLeave,
+        handleUnavailableOptionSelect,
+        highlightedOptions,
+    };
+};

package/dist/compositions/product-specifications-selector.d.ts

@@ -0,0 +1 @@
+export { type ImageRenderProps, ProductSpecificationsSelector, type ProductSpecificationsSelectorProps, } from "./product-specifications-selector/product-specifications-selector.js";

package/dist/compositions/product-specifications-selector.js

@@ -0,0 +1 @@
+export { ProductSpecificationsSelector, } from "./product-specifications-selector/product-specifications-selector.js";

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

@@ -0,0 +1,5 @@
+/**
+ * promptPanelAnatomy helper for PromptPanel.
+ * Import from "@instruments/materia-ui/compositions/prompt-panel".
+ */
+export declare const promptPanelAnatomy: import("../../tokens/anatomy.js").ComponentAnatomy;

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

@@ -0,0 +1,34 @@
+import { defineAnatomy } from "../../tokens/anatomy.js";
+/**
+ * promptPanelAnatomy helper for PromptPanel.
+ * Import from "@instruments/materia-ui/compositions/prompt-panel".
+ */
+export const promptPanelAnatomy = defineAnatomy({
+    children: [
+        {
+            description: "Centered title with an optional leading back button",
+            label: "PromptPanelHeader",
+            slot: "prompt-panel-header",
+        },
+        {
+            children: [
+                {
+                    description: "Selectable row: icon, label, trailing Kbd digit",
+                    label: "PromptPanelOption",
+                    slot: "prompt-panel-option",
+                },
+                {
+                    description: "Borderless freeform text row with a submit Kbd",
+                    label: "PromptPanelFreeform",
+                    slot: "prompt-panel-freeform",
+                },
+            ],
+            description: "Stacked option/freeform rows",
+            label: "PromptPanelBody",
+            slot: "prompt-panel-body",
+        },
+    ],
+    description: "Floating panel prompting the user to pick an action or describe one",
+    label: "PromptPanel",
+    slot: "prompt-panel",
+});

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

@@ -0,0 +1,25 @@
+import type * as React from "react";
+export type PromptPanelBodyProps = React.ComponentProps<"div">;
+/**
+ * Body section of a `PromptPanel` - a vertical stack with `gap="xs"` (8px)
+ * between its direct children (`PromptPanelOption`, `PromptPanelFreeform`).
+ *
+ * For multi-step flows, compose Body *inside* each `PromptPanelStage` page
+ * (with Header) so options and freeform slide together. A Body that wraps
+ * Stage + a freeform sibling leaves freeform outside the page-slide.
+ *
+ * @param props - The prompt panel body props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - `PromptPanelOption`/`PromptPanelFreeform` rows.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelBody>
+ *   <PromptPanelOption shortcut={1}>Find similar</PromptPanelOption>
+ *   <PromptPanelFreeform onSubmit={handleSubmit} />
+ * </PromptPanelBody>
+ * ```
+ */
+declare const PromptPanelBody: ({ className, ...props }: PromptPanelBodyProps) => React.JSX.Element;
+export { PromptPanelBody };

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

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Stack } from "../../components/stack.js";
+/**
+ * Body section of a `PromptPanel` - a vertical stack with `gap="xs"` (8px)
+ * between its direct children (`PromptPanelOption`, `PromptPanelFreeform`).
+ *
+ * For multi-step flows, compose Body *inside* each `PromptPanelStage` page
+ * (with Header) so options and freeform slide together. A Body that wraps
+ * Stage + a freeform sibling leaves freeform outside the page-slide.
+ *
+ * @param props - The prompt panel body props
+ * @param props.className - Additional CSS classes to apply.
+ * @param props.children - `PromptPanelOption`/`PromptPanelFreeform` rows.
+ * @param props... - All other standard HTML div element props.
+ *
+ * @example
+ * ```tsx
+ * <PromptPanelBody>
+ *   <PromptPanelOption shortcut={1}>Find similar</PromptPanelOption>
+ *   <PromptPanelFreeform onSubmit={handleSubmit} />
+ * </PromptPanelBody>
+ * ```
+ */
+const PromptPanelBody = ({ className, ...props }) => (_jsx(Stack, { className: cn("w-full px-4 pt-3 pb-4", className), "data-component": "prompt-panel-body", "data-slot": "prompt-panel-body", gap: "xs", ...props }));
+export { PromptPanelBody };

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

@@ -0,0 +1,50 @@
+import type * as React from "react";
+import type { IconComponent } from "../../tokens/icon-component.js";
+export type PromptPanelFreeformProps = Omit<React.ComponentPropsWithoutRef<"input">, "defaultValue" | "onChange" | "onSubmit" | "size" | "value"> & {
+    /** Uncontrolled initial value. @default "" */
+    defaultValue?: string;
+    /** Leading icon. @default Pencil */
+    icon?: IconComponent;
+    /** Ref forwarded to the underlying `<input>` (object or callback). */
+    inputRef?: React.Ref<HTMLInputElement | null>;
+    /** Called with the current value when Enter is pressed on non-empty text. */
+    onSubmit?: ((value: string) => void) | undefined;
+    /** Called with the next value on every keystroke (controlled or uncontrolled). */
+    onValueChange?: ((value: string) => void) | undefined;
+    /** Trailing `Kbd` content. @default a CornerDownLeft icon */
+    shortcut?: React.ReactNode;
+    /** Controlled value; omit for uncontrolled usage via `defaultValue`. */
+    value?: string | undefined;
+};
+/**
+ * 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.
+ */
+declare const PromptPanelFreeform: ({ className, placeholder, value, defaultValue, onValueChange, onSubmit, onKeyDown, icon, shortcut, inputRef, disabled, "aria-label": ariaLabel, ...props }: PromptPanelFreeformProps) => React.JSX.Element;
+export { PromptPanelFreeform };