@instruments/materia-ui 0.1.0

package/dist/compositions/thinking-trace/thinking-trace-root.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ThinkingTrace - expandable agent reasoning / tool / search timeline.
+ *
+ * Auto-expands while the agent works, settles to a summary label, and stays
+ * expandable. Four variants: steps, reasoning, search, coding.
+ *
+ * @module
+ */
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Grid } from "@instruments/materia-ui/components/grid";
+import { Text } from "@instruments/materia-ui/components/text";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ChevronDown, Search, Sparkle } from "lucide-react";
+import { useState } from "react";
+import { Icon } from "../../components/icon.js";
+import { TraceRowView } from "./thinking-trace-row.js";
+const TraceHeader = ({ expanded, working, activeLabel, doneLabel, onToggle, }) => (_jsxs("button", { "aria-expanded": expanded, className: "hover:bg-accent duration-quick -mx-1.5 flex w-fit items-center gap-2 rounded-md px-1.5 py-1 transition-colors motion-reduce:transition-none", onClick: onToggle, type: "button", children: [_jsx(Icon, { className: cn("fill-current", working ? "text-muted-foreground" : "text-muted-foreground/70"), icon: Sparkle, size: "xs" }), working ? (_jsx(Text, { as: "span", className: "shimmer-text whitespace-nowrap", size: "paragraph-sm", weight: "medium", children: activeLabel })) : (_jsx(Text, { as: "span", className: "animate-fade-in whitespace-nowrap motion-reduce:animate-none", size: "paragraph-sm", variant: "muted", weight: "medium", children: doneLabel })), _jsx(Icon, { className: cn("text-muted-foreground/70 duration-normal transition-transform motion-reduce:transition-none", expanded && "rotate-180"), icon: ChevronDown, size: "2xs" })] }));
+/**
+ * Expandable agent thinking / tool / search trace, driven by real agent state.
+ *
+ * While `streaming` is `true` the trace is open, shows every row it is given and
+ * shimmers `activeLabel`. When it turns `false` the trace collapses to
+ * `doneLabel`; rows stay mounted and the header re-expands them. A manual
+ * toggle of the header pins expansion until the component unmounts.
+ *
+ * @example
+ * ```tsx
+ * <ThinkingTrace
+ *   doneLabel={`Thought for ${elapsedSeconds} seconds`}
+ *   rows={steps.map((step) => ({ primary: step.label }))}
+ *   streaming={status === "streaming"}
+ * />
+ * ```
+ *
+ * @bestPractice Pair above streaming answers in chat. Use ThinkingLoader when you only need a one-line narrated header without an expandable timeline.
+ * @category assistant
+ */
+export const ThinkingTrace = ({ className, activeLabel = "Thinking", doneLabel = "Finished thinking", query, rows, streaming = false, variant = "steps", }) => {
+    const [manualExpanded, setManualExpanded] = useState(null);
+    const [selectedTool, setSelectedTool] = useState(null);
+    const expanded = manualExpanded ?? streaming;
+    return (_jsxs(Flex, { className: cn("w-full", className), "data-testid": "thinking-trace", direction: "column", children: [_jsx(TraceHeader, { activeLabel: activeLabel, doneLabel: doneLabel, expanded: expanded, onToggle: () => {
+                    setManualExpanded((current) => !(current ?? streaming));
+                }, working: streaming }), _jsx(Grid, { className: cn("duration-moderate transition-panel ease-out motion-reduce:transition-none", expanded ? "grid-rows-[1fr] opacity-100" : "grid-rows-[0fr] opacity-0"), columns: "none", gap: "none", inert: !expanded, children: _jsx("div", { className: "overflow-hidden", children: _jsxs("div", { className: "relative mt-1 ml-1.5 pl-4", children: [_jsx("span", { "aria-hidden": true, className: "bg-border absolute -top-2 bottom-0 left-px w-px" }), _jsxs(Flex, { className: "relative py-1", direction: "column", gap: "2xs", children: [query !== undefined && query !== "" ? (_jsxs(Flex, { align: "center", className: cn("h-6 px-1.5", expanded && "animate-fade-up motion-reduce:animate-none"), gap: "xs", children: [_jsx(Icon, { className: "text-muted-foreground/70 shrink-0", icon: Search, size: "2xs" }), _jsx(Text, { as: "span", size: "caption", variant: "muted", children: query })] })) : null, rows.map((row, index) => (_jsx(TraceRowView, { index: index, isLast: index === rows.length - 1, onSelect: () => {
+                                            setSelectedTool((current) => current === row.primary ? null : row.primary);
+                                        }, row: row, selected: selectedTool === row.primary, variant: variant, working: streaming }, row.id ?? row.primary)))] })] }) }) })] }));
+};

package/dist/compositions/thinking-trace/thinking-trace-row.d.ts

@@ -0,0 +1,12 @@
+import type { ThinkingTraceRow, ThinkingTraceVariant } from "./types.js";
+interface TraceRowViewProps {
+    index: number;
+    row: ThinkingTraceRow;
+    variant: ThinkingTraceVariant;
+    working: boolean;
+    isLast: boolean;
+    selected: boolean;
+    onSelect: () => void;
+}
+export declare const TraceRowView: ({ index, row, variant, working, isLast, selected, onSelect, }: TraceRowViewProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/thinking-trace/thinking-trace-row.js

@@ -0,0 +1,47 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Center } from "@instruments/materia-ui/components/center";
+import { Text } from "@instruments/materia-ui/components/text";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Check, Globe } from "lucide-react";
+import { Icon } from "../../components/icon.js";
+/** Source-dot palettes, cycled by row index. */
+const TONES = [
+    "bg-info-accent text-primary-foreground",
+    "bg-affirmative-accent text-primary-foreground",
+    "bg-brand text-brand-foreground",
+];
+const GlobeDot = ({ tone }) => (_jsx(Center, { as: "span", className: cn("size-3.5 shrink-0 rounded-full", tone), children: _jsx(Icon, { icon: Globe, size: "3xs" }) }));
+const StepIcon = ({ done }) => {
+    if (done) {
+        return (_jsx(Icon, { className: "text-muted-foreground/70 shrink-0", icon: Check, size: "2xs" }));
+    }
+    return (_jsx("span", { className: "border-border border-t-muted-foreground size-3 shrink-0 animate-spin rounded-full border-2 motion-reduce:animate-none" }));
+};
+const ROW_CLASS = "flex min-h-7 w-full items-center gap-2 rounded-md px-1.5 py-0.5 text-left";
+const RowSecondary = ({ row }) => row.secondary !== undefined && row.secondary !== "" ? (_jsx(Text, { as: "span", className: cn("text-muted-foreground shrink-0", row.mono === true && "font-mono"), size: "caption", children: row.secondary })) : null;
+const RowDiff = ({ row }) => row.add === undefined ? null : (_jsxs(Text, { as: "span", className: "shrink-0 font-mono tabular-nums", size: "caption", children: [_jsxs("span", { className: "text-affirmative-accent", children: ["+", row.add] }), " ", _jsxs("span", { className: "text-destructive", children: ["\u2212", row.del] })] }));
+const RowLeading = ({ index, stepDone, variant, }) => {
+    if (variant === "search") {
+        return _jsx(GlobeDot, { tone: TONES[index % TONES.length] ?? TONES[0] });
+    }
+    return variant === "steps" ? _jsx(StepIcon, { done: stepDone }) : null;
+};
+const RowContent = ({ index, row, stepDone, variant, }) => {
+    const reasoning = variant === "reasoning";
+    return (_jsxs(_Fragment, { children: [_jsx(RowLeading, { index: index, stepDone: stepDone, variant: variant }), _jsx(Text, { as: "span", className: cn("min-w-0 truncate", reasoning
+                    ? "text-muted-foreground whitespace-normal"
+                    : "text-foreground font-medium", variant === "search" && "underline-grow"), size: "caption", weight: reasoning ? "normal" : "medium", children: row.primary }), _jsx(RowSecondary, { row: row }), _jsx(RowDiff, { row: row })] }));
+};
+export const TraceRowView = ({ index, row, variant, working, isLast, selected, onSelect, }) => {
+    const content = (_jsx(RowContent, { index: index, row: row, stepDone: !(isLast && working), variant: variant }));
+    const rowStyle = { animationDelay: `${index * 120}ms` };
+    const rowClass = cn(ROW_CLASS, "animate-fade-up motion-reduce:animate-none");
+    if (variant === "search" && row.href !== undefined && row.href !== "") {
+        return (_jsx("a", { className: cn(rowClass, "hover:bg-muted duration-quick transition-colors motion-reduce:transition-none"), href: row.href, rel: "noreferrer", style: rowStyle, target: "_blank", children: content }));
+    }
+    if (variant === "coding") {
+        return (_jsx("button", { "aria-pressed": selected, className: cn(rowClass, "duration-quick transition-colors motion-reduce:transition-none", selected ? "bg-muted" : "hover:bg-muted"), onClick: onSelect, style: rowStyle, type: "button", children: content }));
+    }
+    return (_jsx("div", { className: rowClass, style: rowStyle, children: content }));
+};

package/dist/compositions/thinking-trace/types.d.ts

@@ -0,0 +1,32 @@
+/** Trace presentation variants. */
+export type ThinkingTraceVariant = "steps" | "reasoning" | "search" | "coding";
+/** One row in the expandable trace. */
+export interface ThinkingTraceRow {
+    /** Stable identity for list rendering. Defaults to `primary`. */
+    id?: string;
+    primary: string;
+    secondary?: string;
+    mono?: boolean;
+    add?: number;
+    del?: number;
+    href?: string;
+}
+export interface ThinkingTraceProps {
+    className?: string;
+    /** Header label while streaming. Defaults to `"Thinking"`. */
+    activeLabel?: string;
+    /** Settled header label. Defaults to `"Finished thinking"`. */
+    doneLabel?: string;
+    /** Search query shown above the rows. */
+    query?: string;
+    /** Trace rows, in order. */
+    rows: ThinkingTraceRow[];
+    /**
+     * Whether the agent is still working. `true` shows the shimmering
+     * `activeLabel` with the trace open; `false` collapses it to `doneLabel`.
+     * Defaults to `false`.
+     */
+    streaming?: boolean;
+    /** Presentation variant. Defaults to `"steps"`. */
+    variant?: ThinkingTraceVariant;
+}

package/dist/compositions/thinking-trace/types.js

@@ -0,0 +1 @@
+export {};

package/dist/compositions/thinking-trace.d.ts

@@ -0,0 +1 @@
+export { ThinkingTrace, type ThinkingTraceProps, type ThinkingTraceRow, type ThinkingTraceVariant, } from "./thinking-trace/thinking-trace-root.js";

package/dist/compositions/thinking-trace.js

@@ -0,0 +1 @@
+export { ThinkingTrace, } from "./thinking-trace/thinking-trace-root.js";

package/dist/compositions/variant-selector/variant-selector-context.d.ts

@@ -0,0 +1,17 @@
+/** Variant selector context value type definition */
+export interface VariantSelectorContextValue {
+    /** Component mode: single items are radios, multiple items are toggles. */
+    mode: "single" | "multiple";
+    /** Selected values */
+    selectedValues: Set<string>;
+}
+/**
+ * VariantSelectorContext UI component.
+ * Import from "@instruments/materia-ui/compositions/variant-selector".
+ */
+export declare const VariantSelectorContext: import("react").Context<VariantSelectorContextValue | null>;
+/**
+ * useVariantSelector React hook.
+ * Import from "@instruments/materia-ui/compositions/variant-selector".
+ */
+export declare const useVariantSelector: () => VariantSelectorContextValue;

package/dist/compositions/variant-selector/variant-selector-context.js

@@ -0,0 +1,18 @@
+"use client";
+import { createContext, use } from "react";
+/**
+ * VariantSelectorContext UI component.
+ * Import from "@instruments/materia-ui/compositions/variant-selector".
+ */
+export const VariantSelectorContext = createContext(null);
+/**
+ * useVariantSelector React hook.
+ * Import from "@instruments/materia-ui/compositions/variant-selector".
+ */
+export const useVariantSelector = () => {
+    const context = use(VariantSelectorContext);
+    if (!context) {
+        throw new Error("useVariantSelector must be used within a VariantSelector");
+    }
+    return context;
+};

package/dist/compositions/variant-selector/variant-selector-item-label.d.ts

@@ -0,0 +1,7 @@
+/** The caption under a swatch; dims with the swatch and fades back on hover. */
+export declare const VariantSelectorItemLabel: ({ disabled, isDimmed, isSelected, label, }: {
+    disabled: boolean | undefined;
+    isDimmed: boolean;
+    isSelected: boolean;
+    label: string;
+}) => import("react").JSX.Element;

package/dist/compositions/variant-selector/variant-selector-item-label.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** The caption under a swatch; dims with the swatch and fades back on hover. */
+export const VariantSelectorItemLabel = ({ disabled, isDimmed, isSelected, label, }) => (_jsx("span", { className: cn("block w-full truncate text-center", "text-caption", "mt-1", "duration-quick transition-opacity ease-out", isSelected ? "text-foreground" : "text-muted-foreground", isDimmed && "opacity-50 group-hover:opacity-100", disabled === true && "opacity-50"), title: label, children: label }));

package/dist/compositions/variant-selector/variant-selector-item.d.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+export interface VariantSelectorItemProps {
+    /** CSS class name */
+    className?: string;
+    /** Colour value */
+    color?: string;
+    /** Whether disabled (blocks interaction) */
+    disabled?: boolean;
+    /** Whether this option is highlighted (compatible with a hovered unavailable option) */
+    highlighted?: boolean;
+    image?: ReactNode;
+    /** Label text */
+    label: string;
+    /** Called when mouse enters this item */
+    onMouseEnter?: () => void;
+    /** Called when mouse leaves this item */
+    onMouseLeave?: () => void;
+    /** Whether unavailable (visual styling only, still clickable) */
+    unavailable?: boolean;
+    /** Current value */
+    value: string;
+}
+/**
+ * Individual variant item that can display a colour swatch or image.
+ * Automatically adapts to the parent VariantSelector's mode: a Base UI Radio in
+ * single mode, a Base UI Toggle in multiple mode.
+ */
+export declare const VariantSelectorItem: ({ value, label, color, image, disabled, unavailable, highlighted, onMouseEnter, onMouseLeave, className, }: VariantSelectorItemProps) => import("react").JSX.Element;

package/dist/compositions/variant-selector/variant-selector-item.js

@@ -0,0 +1,28 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Radio as RadioPrimitive } from "@base-ui/react/radio";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { Swatch } from "@instruments/materia-ui/components/swatch";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useVariantSelector } from "./variant-selector-context.js";
+import { VariantSelectorItemLabel } from "./variant-selector-item-label.js";
+/**
+ * Individual variant item that can display a colour swatch or image.
+ * Automatically adapts to the parent VariantSelector's mode: a Base UI Radio in
+ * single mode, a Base UI Toggle in multiple mode.
+ */
+export const VariantSelectorItem = ({ value, label, color, image, disabled, unavailable, highlighted, onMouseEnter, onMouseLeave, className, }) => {
+    const { mode, selectedValues } = useVariantSelector();
+    const isSelected = selectedValues.has(value);
+    const isDimmed = unavailable === true || highlighted === true;
+    const labelElement = (_jsx(VariantSelectorItemLabel, { disabled: disabled, isDimmed: isDimmed, isSelected: isSelected, label: label }));
+    // Focus ring and cursor for multiple-mode toggle buttons
+    const interactiveStyles = cn("w-full cursor-pointer", focusRing(), disabled === true && "cursor-not-allowed");
+    const tile = (_jsx(Swatch, { className: "h-auto w-full shadow-none", ...(color === undefined ? {} : { color }), compactRadius: true, ...(disabled === undefined ? {} : { disabled }), dotted: isDimmed, kind: "tile", muted: isDimmed, selected: isSelected, children: image }));
+    if (mode === "single") {
+        return (_jsxs(Flex, { align: "center", className: cn("group", className), direction: "column", "data-component": "variant-selector-item", "data-slot": "variant-selector-item", "data-testid": "variant-option", children: [_jsx(RadioPrimitive.Root, { "aria-label": label, className: cn("relative block w-full cursor-pointer outline-hidden transition-shadow focus-visible:ring-3 focus-visible:ring-gray-500/80", disabled === true && "cursor-not-allowed"), disabled: disabled, nativeButton: true, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, render: (buttonProps) => _jsx("button", { type: "button", ...buttonProps }), value: value, children: tile }), labelElement] }));
+    }
+    return (_jsxs(Flex, { align: "center", className: cn("group", className), direction: "column", "data-component": "variant-selector-item", "data-slot": "variant-selector-item", "data-testid": "variant-option", children: [_jsx(TogglePrimitive, { "aria-label": label, className: interactiveStyles, disabled: disabled, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, value: value, children: tile }), labelElement] }));
+};

package/dist/compositions/variant-selector/variant-selector-root.d.ts

@@ -0,0 +1,53 @@
+import type { ReactNode } from "react";
+/** Variant selector props single type definition */
+interface VariantSelectorPropsSingleBase {
+    /** Child elements */
+    children?: ReactNode;
+    /** CSS class name */
+    className?: string;
+    /** Initial value */
+    defaultValue?: string;
+    /** Component mode */
+    mode: "single";
+    /** Value change handler */
+    onValueChange?: (value: string) => void;
+    /** Current value */
+    value?: string;
+}
+type VariantSelectorPropsSingle = VariantSelectorPropsSingleBase & ({
+    "aria-label": string;
+    "aria-labelledby"?: never;
+} | {
+    "aria-label"?: never;
+    "aria-labelledby": string;
+});
+/** Variant selector props multiple type definition */
+interface VariantSelectorPropsMultiple {
+    /** Child elements */
+    children?: ReactNode;
+    /** CSS class name */
+    className?: string;
+    /** Initial value */
+    defaultValue?: string[];
+    /** Component mode */
+    mode: "multiple";
+    /** Value change handler */
+    onValueChange?: (value: string[]) => void;
+    /** Current value */
+    value?: string[];
+}
+export type VariantSelectorProps = VariantSelectorPropsSingle | VariantSelectorPropsMultiple;
+/**
+ * A flexible variant selector that supports both single and multiple selection modes.
+ * Renders card-style items that can display images or colours. Single mode is a
+ * Base UI RadioGroup and multiple mode a Base UI ToggleGroup, so either way the
+ * set is one tab stop and the arrow keys move between items.
+ *
+ * @bestPractice Fill it with `VariantSelectorItem` children - they read selection from context; `value`/`defaultValue` matches each item's `value`.
+ * @bestPractice `mode` is a discriminated prop: `"single"` renders a `role="radiogroup"` and gives `onValueChange` a `string`, `"multiple"` renders a `<fieldset>` of pressed-state toggles and a `string[]` - keep `value`/`defaultValue` types matching the mode.
+ * @bestPractice `defaultValue` is uncontrolled: the selector tracks later picks itself. Pass `value` with `onValueChange` to control it.
+ * @bestPractice Use `VariantSelector` for image/colour swatch pickers; for a labelled icon-over-text option grid use `IconCard`, and for plain radio/checkbox lists use `RadioGroup`/`Checkbox`.
+ * @category catalogue
+ */
+export declare const VariantSelector: (props: VariantSelectorProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/variant-selector/variant-selector-root.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group";
+import { ToggleGroup as ToggleGroupPrimitive } from "@base-ui/react/toggle-group";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useMemo, useState } from "react";
+import { VariantSelectorContext } from "./variant-selector-context.js";
+import { toSelectedValues } from "./variant-selector-state.js";
+const GRID = "grid grid-cols-[repeat(auto-fit,minmax(100px,1fr))] gap-4";
+/**
+ * A flexible variant selector that supports both single and multiple selection modes.
+ * Renders card-style items that can display images or colours. Single mode is a
+ * Base UI RadioGroup and multiple mode a Base UI ToggleGroup, so either way the
+ * set is one tab stop and the arrow keys move between items.
+ *
+ * @bestPractice Fill it with `VariantSelectorItem` children - they read selection from context; `value`/`defaultValue` matches each item's `value`.
+ * @bestPractice `mode` is a discriminated prop: `"single"` renders a `role="radiogroup"` and gives `onValueChange` a `string`, `"multiple"` renders a `<fieldset>` of pressed-state toggles and a `string[]` - keep `value`/`defaultValue` types matching the mode.
+ * @bestPractice `defaultValue` is uncontrolled: the selector tracks later picks itself. Pass `value` with `onValueChange` to control it.
+ * @bestPractice Use `VariantSelector` for image/colour swatch pickers; for a labelled icon-over-text option grid use `IconCard`, and for plain radio/checkbox lists use `RadioGroup`/`Checkbox`.
+ * @category catalogue
+ */
+export const VariantSelector = (props) => {
+    const { mode, value, defaultValue, className, children } = props;
+    const [uncontrolled, setUncontrolled] = useState(defaultValue);
+    const current = value ?? uncontrolled;
+    const selectedValues = useMemo(() => toSelectedValues(current), [current]);
+    const contextValue = useMemo(() => ({ mode, selectedValues }), [mode, selectedValues]);
+    // Narrow on `props` (not the destructured fields) so the discriminated
+    // union correlates `mode` with `onValueChange`'s signature - no casts.
+    if (props.mode === "single") {
+        const { onValueChange } = props;
+        return (_jsx(VariantSelectorContext.Provider, { value: contextValue, children: _jsx(RadioGroupPrimitive, { "aria-label": props["aria-label"], "aria-labelledby": props["aria-labelledby"], className: cn(GRID, className), "data-component": "variant-selector", "data-slot": "variant-selector", onValueChange: (next) => {
+                    setUncontrolled(next);
+                    onValueChange?.(next);
+                }, 
+                // "" is no selection; RadioGroup has no empty value of its own.
+                value: Array.isArray(current) ? "" : (current ?? ""), children: children }) }));
+    }
+    const { onValueChange } = props;
+    return (_jsx(VariantSelectorContext.Provider, { value: contextValue, children: _jsx(ToggleGroupPrimitive, { className: cn(GRID, className), "data-component": "variant-selector", "data-slot": "variant-selector", multiple: true, onValueChange: (next) => {
+                setUncontrolled(next);
+                onValueChange?.(next);
+            }, render: _jsx("fieldset", {}), value: [...selectedValues], children: children }) }));
+};

package/dist/compositions/variant-selector/variant-selector-state.d.ts

@@ -0,0 +1,4 @@
+/** True when the selection holds several values (multiple mode). */
+export declare const isMultipleSelection: (current: string | readonly string[]) => current is readonly string[];
+/** The current selection (one value, several, or none) as a set. */
+export declare const toSelectedValues: (current: string | readonly string[] | undefined) => Set<string>;

package/dist/compositions/variant-selector/variant-selector-state.js

@@ -0,0 +1,9 @@
+/** True when the selection holds several values (multiple mode). */
+export const isMultipleSelection = (current) => Array.isArray(current);
+/** The current selection (one value, several, or none) as a set. */
+export const toSelectedValues = (current) => {
+    if (current === undefined) {
+        return new Set();
+    }
+    return new Set(isMultipleSelection(current) ? current : [current]);
+};

package/dist/compositions/variant-selector.d.ts

@@ -0,0 +1,2 @@
+export { VariantSelectorItem } from "./variant-selector/variant-selector-item.js";
+export { VariantSelector } from "./variant-selector/variant-selector-root.js";

package/dist/compositions/variant-selector.js

@@ -0,0 +1,2 @@
+export { VariantSelectorItem } from "./variant-selector/variant-selector-item.js";
+export { VariantSelector } from "./variant-selector/variant-selector-root.js";

package/dist/data/component-categories.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Canonical family taxonomy for the Materia design system.
+ *
+ * Every component and every composition in `@instruments/materia-ui` is tagged
+ * with exactly one family via a `@category` JSDoc tag on its primary
+ * declaration. The tree (components or compositions) says what kind of unit it
+ * is; the family says what it is for. Each tree has its own list: components
+ * take a {@link COMPONENT_CATEGORIES} family, compositions a
+ * {@link COMPOSITION_CATEGORIES} one. The generated docs manifest reads those
+ * tags to group each tree for browsing, and fails the build on any missing or
+ * unrecognised category - so these lists are the single source of truth. Add a
+ * family here before using it in a tag.
+ *
+ * @module
+ */
+/**
+ * The eleven canonical component families. Ordered roughly from structural
+ * primitives (layout, typography) through interactive controls (actions,
+ * forms, navigation, overlays) to presentational and higher-order groupings
+ * (feedback, data, colour, motion, composites).
+ */
+export declare const COMPONENT_CATEGORIES: readonly ["layout", "typography", "actions", "forms", "navigation", "overlays", "feedback", "data", "color", "motion", "composites"];
+/**
+ * A single component family - the value carried by a component's `@category`
+ * JSDoc tag and the key the docs manifest groups by.
+ */
+export type ComponentCategory = (typeof COMPONENT_CATEGORIES)[number];
+/**
+ * The seven composition families, named for what the compositions are:
+ * navigation and headers, then what a catalogue shows (catalogue, data), what
+ * it takes (inputs), what stands in for it (states) and the assistant.
+ */
+export declare const COMPOSITION_CATEGORIES: readonly ["navigation", "headers", "catalogue", "data", "inputs", "states", "assistant"];
+/**
+ * A single composition family - the value carried by a composition's
+ * `@category` JSDoc tag.
+ */
+export type CompositionCategory = (typeof COMPOSITION_CATEGORIES)[number];
+/** Display labels for the component families. */
+export declare const COMPONENT_CATEGORY_LABELS: Record<ComponentCategory, string>;
+/** Display labels for the composition families. */
+export declare const COMPOSITION_CATEGORY_LABELS: Record<CompositionCategory, string>;

package/dist/data/component-categories.js

@@ -0,0 +1,72 @@
+/**
+ * Canonical family taxonomy for the Materia design system.
+ *
+ * Every component and every composition in `@instruments/materia-ui` is tagged
+ * with exactly one family via a `@category` JSDoc tag on its primary
+ * declaration. The tree (components or compositions) says what kind of unit it
+ * is; the family says what it is for. Each tree has its own list: components
+ * take a {@link COMPONENT_CATEGORIES} family, compositions a
+ * {@link COMPOSITION_CATEGORIES} one. The generated docs manifest reads those
+ * tags to group each tree for browsing, and fails the build on any missing or
+ * unrecognised category - so these lists are the single source of truth. Add a
+ * family here before using it in a tag.
+ *
+ * @module
+ */
+/**
+ * The eleven canonical component families. Ordered roughly from structural
+ * primitives (layout, typography) through interactive controls (actions,
+ * forms, navigation, overlays) to presentational and higher-order groupings
+ * (feedback, data, colour, motion, composites).
+ */
+export const COMPONENT_CATEGORIES = [
+    "layout",
+    "typography",
+    "actions",
+    "forms",
+    "navigation",
+    "overlays",
+    "feedback",
+    "data",
+    "color",
+    "motion",
+    "composites",
+];
+/**
+ * The seven composition families, named for what the compositions are:
+ * navigation and headers, then what a catalogue shows (catalogue, data), what
+ * it takes (inputs), what stands in for it (states) and the assistant.
+ */
+export const COMPOSITION_CATEGORIES = [
+    "navigation",
+    "headers",
+    "catalogue",
+    "data",
+    "inputs",
+    "states",
+    "assistant",
+];
+/** Display labels for the component families. */
+export const COMPONENT_CATEGORY_LABELS = {
+    actions: "Actions",
+    color: "Color",
+    composites: "Composites",
+    data: "Data",
+    feedback: "Feedback",
+    forms: "Forms",
+    layout: "Layout",
+    motion: "Motion",
+    navigation: "Navigation",
+    overlays: "Overlays",
+    typography: "Typography",
+};
+/** Display labels for the composition families. */
+export const COMPOSITION_CATEGORY_LABELS = {
+    assistant: "Assistant",
+    catalogue: "Catalogue",
+    data: "Data",
+    headers: "Headers",
+    inputs: "Inputs",
+    navigation: "Navigation",
+    states: "States",
+};

package/dist/data/countries.d.ts

@@ -0,0 +1,19 @@
+/** Structural mirror of ComboboxItem, kept local to avoid a shared → component import. */
+export interface CountryOption {
+    label: string;
+    value: string;
+}
+/**
+ * Get all countries formatted for Combobox
+ * Uses ISO 3166-1 alpha-2 country codes from countries-list package
+ * Sorted alphabetically by country name
+ */
+export declare const getCountries: () => CountryOption[];
+/**
+ * Get country name by ISO code
+ */
+export declare const getCountryName: (code: string) => string | undefined;
+/**
+ * Get country code by name (case-insensitive)
+ */
+export declare const getCountryCode: (name: string) => string | undefined;

package/dist/data/countries.js

@@ -0,0 +1,26 @@
+import { countries } from "countries-list";
+/**
+ * Get all countries formatted for Combobox
+ * Uses ISO 3166-1 alpha-2 country codes from countries-list package
+ * Sorted alphabetically by country name
+ */
+export const getCountries = () => Object.entries(countries)
+    .map(([code, data]) => ({
+    label: data.name,
+    value: code,
+}))
+    .toSorted((a, b) => a.label.localeCompare(b.label));
+/**
+ * Get country name by ISO code
+ */
+export const getCountryName = (code) => {
+    const lookup = countries;
+    return lookup[code]?.name;
+};
+/**
+ * Get country code by name (case-insensitive)
+ */
+export const getCountryCode = (name) => {
+    const entry = Object.entries(countries).find(([, data]) => data.name.toLowerCase() === name.toLowerCase());
+    return entry?.[0];
+};

package/dist/data/decision-trees.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Component decision trees - the "which one do I reach for?" logic from
+ * `AGENTS.md`, converted from prose ASCII trees into validated structured data.
+ *
+ * Each {@link DecisionFamily} answers one user intent (float content over the
+ * page, show state, enter/choose a value, arrange things, load, empty/error,
+ * render a table). Its `tree` is a {@link DecisionNode}: interior nodes ask a
+ * `question` and branch; leaves name a component by its **manifest slug**
+ * (kebab-case, e.g. `alert-dialog`) so the docs site can link straight to the
+ * unit's page (`/components/<slug>` or `/compositions/<slug>`).
+ *
+ * Every leaf slug is validated against the generated docs manifest at
+ * generation time (`scripts/generate-docs-manifest.mjs`), so a component rename
+ * fails the manifest freshness test until the tree is updated - the drift gate. Family `id`s
+ * are validated against `COMPONENT_CATEGORIES`; a family renders on the shelf of
+ * its `id`, and several families may share a shelf (three feedback families
+ * live on `feedback`).
+ *
+ * This is a data-layer module: it imports nothing (the src layer matrix). The docs
+ * site imports it directly via `@instruments/materia-ui/data/decision-trees`.
+ *
+ * @module
+ */
+/** A terminal recommendation: the component to reach for, by manifest slug. */
+export interface DecisionLeaf {
+    /** Manifest slug of the component to reach for (kebab-case). */
+    slug: string;
+    /** Optional aside - a caveat, a fallback, or where to look next. */
+    note?: string;
+}
+/** One labelled path out of a question node. */
+export interface DecisionBranch {
+    label: string;
+    next: DecisionNode;
+}
+/** Either a branching question or a terminal leaf. */
+export type DecisionNode = {
+    question: string;
+    branches: DecisionBranch[];
+} | DecisionLeaf;
+/** A flat comparison of the family's components, rendered as a table. */
+export interface DecisionComparisonTable {
+    columns: string[];
+    rows: string[][];
+}
+/** One "which component?" decision family for a single user intent. */
+export interface DecisionFamily {
+    /**
+     * A `COMPONENT_CATEGORIES` value - the shelf this family renders on. Not
+     * unique: families whose components span into a shelf share its id (loading
+     * and empty/error both render on `feedback`).
+     */
+    id: string;
+    title: string;
+    /** The user intent this family answers, e.g. "I need to float content above the page". */
+    intent: string;
+    tree: DecisionNode;
+    comparison?: DecisionComparisonTable;
+    /** Short disambiguating rules - the blockquote tie-breakers from AGENTS.md. */
+    tieBreakers: string[];
+}
+/**
+ * A type guard used by both the generator's validator and the renderer to tell
+ * a branching node from a terminal leaf.
+ */
+export declare const isDecisionLeaf: (node: DecisionNode) => node is DecisionLeaf;
+export declare const DECISION_FAMILIES: readonly DecisionFamily[];