@instruments/materia-ui 0.1.0

package/dist/components/menubar/menubar-separator.d.ts

@@ -0,0 +1,3 @@
+/** Horizontal divider between groups of menu items. `spacing="compact"` tightens the vertical gap. */
+declare const MenubarSeparator: (props: import("../menu-parts.js").MenuSeparatorProps) => React.JSX.Element;
+export { MenubarSeparator };

package/dist/components/menubar/menubar-separator.js

@@ -0,0 +1,5 @@
+"use client";
+import { menubarParts } from "./menubar-parts.js";
+/** Horizontal divider between groups of menu items. `spacing="compact"` tightens the vertical gap. */
+const MenubarSeparator = menubarParts.Separator;
+export { MenubarSeparator };

package/dist/components/menubar/menubar-shortcut.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Right-aligned keyboard-hint text for a menu item (e.g. "⌘K"). Purely
+ * presentational - it does not bind the shortcut. Sizing follows content context.
+ */
+declare const MenubarShortcut: (props: import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>) => React.JSX.Element;
+export { MenubarShortcut };

package/dist/components/menubar/menubar-shortcut.js

@@ -0,0 +1,8 @@
+"use client";
+import { menubarParts } from "./menubar-parts.js";
+/**
+ * Right-aligned keyboard-hint text for a menu item (e.g. "⌘K"). Purely
+ * presentational - it does not bind the shortcut. Sizing follows content context.
+ */
+const MenubarShortcut = menubarParts.Shortcut;
+export { MenubarShortcut };

package/dist/components/menubar/menubar-sub-content.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Popover surface for a submenu's items. Inherits item size and radius from the
+ * parent menu unless `size` is overridden here. Accepts the same positioning
+ * props as MenubarContent.
+ */
+declare const MenubarSubContent: (props: import("../menu-parts.js").MenuSubContentProps) => React.JSX.Element;
+export { MenubarSubContent };

package/dist/components/menubar/menubar-sub-content.js

@@ -0,0 +1,9 @@
+"use client";
+import { menubarParts } from "./menubar-parts.js";
+/**
+ * Popover surface for a submenu's items. Inherits item size and radius from the
+ * parent menu unless `size` is overridden here. Accepts the same positioning
+ * props as MenubarContent.
+ */
+const MenubarSubContent = menubarParts.SubContent;
+export { MenubarSubContent };

package/dist/components/menubar/menubar-sub-trigger.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Menu item that opens its parent MenubarSub on hover (after a short delay) or
+ * arrow key, with a trailing chevron. Pass label text via `children` and a
+ * leading icon via `icon`.
+ */
+declare const MenubarSubTrigger: (props: import("../menu-parts.js").MenuSubTriggerProps) => React.JSX.Element;
+export { MenubarSubTrigger };

package/dist/components/menubar/menubar-sub-trigger.js

@@ -0,0 +1,9 @@
+"use client";
+import { menubarParts } from "./menubar-parts.js";
+/**
+ * Menu item that opens its parent MenubarSub on hover (after a short delay) or
+ * arrow key, with a trailing chevron. Pass label text via `children` and a
+ * leading icon via `icon`.
+ */
+const MenubarSubTrigger = menubarParts.SubTrigger;
+export { MenubarSubTrigger };

package/dist/components/menubar/menubar-sub.d.ts

@@ -0,0 +1,3 @@
+/** Wraps a nested submenu, pairing a MenubarSubTrigger with a MenubarSubContent. */
+declare const MenubarSub: (props: import("@base-ui/react").MenuSubmenuRootProps) => React.JSX.Element;
+export { MenubarSub };

package/dist/components/menubar/menubar-sub.js

@@ -0,0 +1,5 @@
+"use client";
+import { menubarParts } from "./menubar-parts.js";
+/** Wraps a nested submenu, pairing a MenubarSubTrigger with a MenubarSubContent. */
+const MenubarSub = menubarParts.Sub;
+export { MenubarSub };

package/dist/components/menubar/menubar-trigger.d.ts

@@ -0,0 +1,9 @@
+import { Menu as MenuPrimitive } from "@base-ui/react/menu";
+/**
+ * Top-level bar button that opens its MenubarMenu on click or arrow key. Unlike
+ * a dropdown trigger, focus moves between sibling triggers with the arrow keys.
+ */
+declare const MenubarTrigger: ({ className, ...props }: Omit<MenuPrimitive.Trigger.Props, "className"> & {
+    className?: string;
+}) => import("react").JSX.Element;
+export { MenubarTrigger };

package/dist/components/menubar/menubar-trigger.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Menu as MenuPrimitive } from "@base-ui/react/menu";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Top-level bar button that opens its MenubarMenu on click or arrow key. Unlike
+ * a dropdown trigger, focus moves between sibling triggers with the arrow keys.
+ */
+const MenubarTrigger = ({ className, ...props }) => (_jsx(MenuPrimitive.Trigger, { className: cn("focus:bg-accent focus:text-accent-foreground data-popup-open:bg-accent data-popup-open:text-accent-foreground text-paragraph-sm flex items-center rounded-xs px-3 py-1 font-normal outline-hidden select-none", className), "data-component": "menubar-trigger", "data-slot": "menubar-trigger", ...props }));
+export { MenubarTrigger };

package/dist/components/menubar.d.ts

@@ -0,0 +1,17 @@
+export { menubarAnatomy } from "./menubar/menubar-anatomy.js";
+export { MenubarCheckboxItem } from "./menubar/menubar-checkbox-item.js";
+export { MenubarContent } from "./menubar/menubar-content.js";
+export { MenubarGroup } from "./menubar/menubar-group.js";
+export { MenubarItem } from "./menubar/menubar-item.js";
+export { MenubarLabel } from "./menubar/menubar-label.js";
+export { MenubarMenu } from "./menubar/menubar-menu.js";
+export { MenubarPortal } from "./menubar/menubar-portal.js";
+export { MenubarRadioGroup } from "./menubar/menubar-radio-group.js";
+export { MenubarRadioItem } from "./menubar/menubar-radio-item.js";
+export { Menubar } from "./menubar/menubar-root.js";
+export { MenubarSeparator } from "./menubar/menubar-separator.js";
+export { MenubarShortcut } from "./menubar/menubar-shortcut.js";
+export { MenubarSub } from "./menubar/menubar-sub.js";
+export { MenubarSubContent } from "./menubar/menubar-sub-content.js";
+export { MenubarSubTrigger } from "./menubar/menubar-sub-trigger.js";
+export { MenubarTrigger } from "./menubar/menubar-trigger.js";

package/dist/components/menubar.js

@@ -0,0 +1,17 @@
+export { menubarAnatomy } from "./menubar/menubar-anatomy.js";
+export { MenubarCheckboxItem } from "./menubar/menubar-checkbox-item.js";
+export { MenubarContent } from "./menubar/menubar-content.js";
+export { MenubarGroup } from "./menubar/menubar-group.js";
+export { MenubarItem } from "./menubar/menubar-item.js";
+export { MenubarLabel } from "./menubar/menubar-label.js";
+export { MenubarMenu } from "./menubar/menubar-menu.js";
+export { MenubarPortal } from "./menubar/menubar-portal.js";
+export { MenubarRadioGroup } from "./menubar/menubar-radio-group.js";
+export { MenubarRadioItem } from "./menubar/menubar-radio-item.js";
+export { Menubar } from "./menubar/menubar-root.js";
+export { MenubarSeparator } from "./menubar/menubar-separator.js";
+export { MenubarShortcut } from "./menubar/menubar-shortcut.js";
+export { MenubarSub } from "./menubar/menubar-sub.js";
+export { MenubarSubContent } from "./menubar/menubar-sub-content.js";
+export { MenubarSubTrigger } from "./menubar/menubar-sub-trigger.js";
+export { MenubarTrigger } from "./menubar/menubar-trigger.js";

package/dist/components/month-year-picker/month-year-picker-root.d.ts

@@ -0,0 +1,47 @@
+import type { ToggleSize } from "../toggle.js";
+/** Value returned by MonthYearPicker */
+export type MonthYearPickerValue = Date | "beyond" | "unsure";
+type ToggleVariant = "default" | "secondary";
+export interface MonthYearPickerProps {
+    /** Label for "beyond" option. Default: "Beyond {lastYear}" */
+    beyondLabel?: string;
+    className?: string;
+    /** Month section label. Default: "Choose month" */
+    monthLabel?: string;
+    /** Called when selection is committed (auto-advances when both month and year selected) */
+    onChange?: (value: MonthYearPickerValue) => void;
+    /** Show "I'm not sure" option. Default: false */
+    showUnsure?: boolean;
+    /** Toggle size. Default: "lg" */
+    size?: ToggleSize;
+    /** Label for "unsure" option. Default: "I'm not sure" */
+    unsureLabel?: string;
+    /** Current value */
+    value?: MonthYearPickerValue | null;
+    /** Toggle variant. Default: "default" */
+    variant?: ToggleVariant;
+    /** Year section label. Default: "Choose year" */
+    yearLabel?: string;
+    /** Number of years to show from current year. Default: 10 */
+    yearsAhead?: number;
+}
+/**
+ * MonthYearPicker allows selecting a month and year, or choosing "Beyond" / "I'm not sure".
+ * Auto-advances to the next step when both month and year are selected.
+ *
+ * @example
+ * ```tsx
+ * <MonthYearPicker
+ *   value={selectedDate}
+ *   onChange={(value) => setSelectedDate(value)}
+ *   yearsAhead={10}
+ * />
+ * ```
+ *
+ * @bestPractice `value` is a union - a `Date`, `"beyond"`, or `"unsure"` - so branch on the string sentinels in `onChange` before treating it as a date.
+ * @bestPractice Enable the "I'm not sure" escape hatch with `showUnsure` (off by default); `"unsure"`/`"beyond"` only ever arrive when their toggles are shown.
+ * @bestPractice Bound the range with `yearsAhead` (from the current year); it auto-advances and commits once both month and year are chosen, so don't add your own "next" control.
+ * @category forms
+ */
+export declare const MonthYearPicker: ({ value, onChange, yearsAhead, beyondLabel, showUnsure, unsureLabel, size, variant, monthLabel, yearLabel, className, }: MonthYearPickerProps) => import("react").JSX.Element;
+export {};

package/dist/components/month-year-picker/month-year-picker-root.js

@@ -0,0 +1,130 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useRef, useState } from "react";
+import { Flex } from "../flex.js";
+import { Grid } from "../grid.js";
+import { Text } from "../text.js";
+import { Toggle } from "../toggle.js";
+/** Short month labels */
+const MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+/** The calendar year the year list starts from. */
+const getCurrentYear = () => new Date().getFullYear();
+/**
+ * A committed (authoritative) value has arrived: a concrete date, a special
+ * choice, or an explicit clear. `undefined` means "no opinion" and is left
+ * untouched so a mid-selection draft survives re-renders.
+ */
+const isCommittedValue = (value) => value instanceof Date ||
+    value === "beyond" ||
+    value === "unsure" ||
+    value === null;
+const MonthSection = ({ isBeyond, isUnsure, monthLabel, onMonthSelect, selectedMonth, size, variant, }) => (_jsxs(Flex, { direction: "column", gap: "xs", children: [_jsx(Text, { className: "text-muted-foreground", size: "caption", weight: "medium", children: monthLabel }), _jsx(Grid, { columns: 4, gap: "xs", children: MONTHS.map((month, index) => {
+                const isSelected = selectedMonth === index && !isBeyond && !isUnsure;
+                return (_jsx(Toggle, { defaultPressed: false, onPressedChange: (pressed) => {
+                        onMonthSelect(index, pressed);
+                    }, pressed: isSelected, size: size, variant: variant, children: month }, month));
+            }) })] }));
+const YearSection = ({ isBeyond, isUnsure, onYearSelect, selectedYear, size, variant, yearLabel, years, }) => (_jsxs(Flex, { direction: "column", gap: "xs", children: [_jsx(Text, { className: "text-muted-foreground", size: "caption", weight: "medium", children: yearLabel }), _jsx(Grid, { columns: 5, gap: "xs", children: years.map((year) => {
+                const isSelected = selectedYear === year && !isBeyond && !isUnsure;
+                return (_jsx(Toggle, { defaultPressed: false, onPressedChange: (pressed) => {
+                        onYearSelect(year, pressed);
+                    }, pressed: isSelected, size: size, variant: variant, children: year }, year));
+            }) })] }));
+const SpecialOptions = ({ isBeyond, isUnsure, onBeyondSelect, onUnsureSelect, resolvedBeyondLabel, showUnsure, size, unsureLabel, variant, }) => (_jsxs(Flex, { gap: "xs", wrap: "wrap", children: [_jsx(Toggle, { defaultPressed: false, onPressedChange: onBeyondSelect, pressed: isBeyond, size: size, variant: variant, children: resolvedBeyondLabel }), showUnsure && (_jsx(Toggle, { defaultPressed: false, onPressedChange: onUnsureSelect, pressed: isUnsure, size: size, variant: variant, children: unsureLabel }))] }));
+/**
+ * MonthYearPicker allows selecting a month and year, or choosing "Beyond" / "I'm not sure".
+ * Auto-advances to the next step when both month and year are selected.
+ *
+ * @example
+ * ```tsx
+ * <MonthYearPicker
+ *   value={selectedDate}
+ *   onChange={(value) => setSelectedDate(value)}
+ *   yearsAhead={10}
+ * />
+ * ```
+ *
+ * @bestPractice `value` is a union - a `Date`, `"beyond"`, or `"unsure"` - so branch on the string sentinels in `onChange` before treating it as a date.
+ * @bestPractice Enable the "I'm not sure" escape hatch with `showUnsure` (off by default); `"unsure"`/`"beyond"` only ever arrive when their toggles are shown.
+ * @bestPractice Bound the range with `yearsAhead` (from the current year); it auto-advances and commits once both month and year are chosen, so don't add your own "next" control.
+ * @category forms
+ */
+export const MonthYearPicker = ({ value, onChange, yearsAhead = 10, beyondLabel, showUnsure = false, unsureLabel = "I'm not sure", size = "lg", variant = "default", monthLabel = "Choose month", yearLabel = "Choose year", className, }) => {
+    const currentYear = getCurrentYear();
+    const years = Array.from({ length: yearsAhead }, (_, i) => currentYear + i);
+    const lastYear = years.at(-1);
+    const resolvedBeyondLabel = beyondLabel ?? `Beyond ${lastYear}`;
+    // Track if user has interacted in this session (prevents auto-advance on mount)
+    const hasInteracted = useRef(false);
+    // Local selection state for partial selections (before both are complete)
+    const [pendingMonth, setPendingMonth] = useState(null);
+    const [pendingYear, setPendingYear] = useState(null);
+    // Derive selected state from value prop or pending state
+    const savedMonth = value instanceof Date ? value.getMonth() : null;
+    const savedYear = value instanceof Date ? value.getFullYear() : null;
+    // Use pending state while selecting, saved state when complete
+    const selectedMonth = pendingMonth ?? savedMonth;
+    const selectedYear = pendingYear ?? savedYear;
+    const isBeyond = value === "beyond";
+    const isUnsure = value === "unsure";
+    // Reset the mid-selection draft (pendingMonth/pendingYear) when an
+    // authoritative value arrives externally, so a stale partial selection
+    // never shadows the committed value via `pendingMonth ?? savedMonth`.
+    // The draft cannot be derived from props (a half-picked month has no
+    // committed value yet), so it is cleared while rendering the new prop.
+    // `undefined` is intentionally left untouched.
+    const [previousValue, setPreviousValue] = useState(value);
+    if (value !== previousValue) {
+        setPreviousValue(value);
+        if (isCommittedValue(value)) {
+            setPendingMonth(null);
+            setPendingYear(null);
+        }
+    }
+    // Check if both selections are complete and auto-advance
+    const maybeAutoAdvance = useCallback((month, year) => {
+        if (hasInteracted.current && month !== null && year !== null) {
+            const date = new Date(year, month, 1);
+            onChange?.(date);
+        }
+    }, [onChange]);
+    const handleMonthSelect = useCallback((monthIndex, pressed) => {
+        if (!pressed) {
+            return;
+        }
+        hasInteracted.current = true;
+        setPendingMonth(monthIndex);
+        maybeAutoAdvance(monthIndex, selectedYear);
+    }, [selectedYear, maybeAutoAdvance]);
+    const handleYearSelect = useCallback((year, pressed) => {
+        if (!pressed) {
+            return;
+        }
+        hasInteracted.current = true;
+        setPendingYear(year);
+        maybeAutoAdvance(selectedMonth, year);
+    }, [selectedMonth, maybeAutoAdvance]);
+    // Beyond/unsure share identical reset-then-commit behaviour
+    const handleSpecialSelect = useCallback((kind) => (pressed) => {
+        if (!pressed) {
+            return;
+        }
+        setPendingMonth(null);
+        setPendingYear(null);
+        onChange?.(kind);
+    }, [onChange]);
+    return (_jsxs(Flex, { className: className, "data-component": "month-year-picker", direction: "column", gap: "lg", children: [_jsx(MonthSection, { isBeyond: isBeyond, isUnsure: isUnsure, monthLabel: monthLabel, onMonthSelect: handleMonthSelect, selectedMonth: selectedMonth, size: size, variant: variant }), _jsx(YearSection, { isBeyond: isBeyond, isUnsure: isUnsure, onYearSelect: handleYearSelect, selectedYear: selectedYear, size: size, variant: variant, yearLabel: yearLabel, years: years }), _jsx(SpecialOptions, { isBeyond: isBeyond, isUnsure: isUnsure, onBeyondSelect: handleSpecialSelect("beyond"), onUnsureSelect: handleSpecialSelect("unsure"), resolvedBeyondLabel: resolvedBeyondLabel, showUnsure: showUnsure, size: size, unsureLabel: unsureLabel, variant: variant })] }));
+};

package/dist/components/month-year-picker.d.ts

@@ -0,0 +1 @@
+export { MonthYearPicker, type MonthYearPickerProps, type MonthYearPickerValue, } from "./month-year-picker/month-year-picker-root.js";

package/dist/components/month-year-picker.js

@@ -0,0 +1 @@
+export { MonthYearPicker, } from "./month-year-picker/month-year-picker-root.js";

package/dist/components/morph-dialog/morph-dialog-root.d.ts

@@ -0,0 +1,87 @@
+interface MorphDialogContextValue {
+    layoutId: string;
+    open: boolean;
+    setOpen: (open: boolean) => void;
+}
+declare const useMorphDialog: () => MorphDialogContextValue;
+interface MorphDialogProps {
+    children: React.ReactNode;
+    /** Callback when open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** Controlled open state. Omit to let the dialog manage its own open state. */
+    open?: boolean;
+}
+/**
+ * Root of a dialog that morphs open from its trigger via a shared-element
+ * layout animation - the trigger and the dialog card share a `layoutId`, so
+ * Motion tweens position, size, radius, and shadow between them.
+ *
+ * Controlled when `open` is passed, otherwise uncontrolled. Provides context
+ * to the trigger, content, title, and description parts.
+ *
+ * @bestPractice Reach for `MorphDialog` only when the modal should animate out of its trigger element (shared-layout); a plain centred modal is a `Dialog`.
+ * @bestPractice Pass the trigger's `borderRadius` / `boxShadow` via `style` (not `className`) on `MorphDialogTrigger` so Motion can correct their distortion during the morph.
+ * @bestPractice Render a `MorphDialogTitle` (use `visuallyHidden` if needed) for the accessible name; mount `ReducedMotionProvider` at the app root since it animates via `m.*`.
+ * @category overlays
+ */
+declare const MorphDialog: ({ children, open: controlledOpen, onOpenChange, }: MorphDialogProps) => import("react").JSX.Element;
+interface MorphDialogTriggerProps {
+    children: React.ReactNode;
+    className?: string;
+    /**
+     * Style props for the layoutId element (the one that morphs).
+     * Motion can only auto-correct borderRadius and boxShadow distortion
+     * if they're set via style prop, not className.
+     * Pass matching values from your trigger children here.
+     * @example style={{ borderRadius: radii["2xl"], boxShadow: shadows.none }}
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * The element the dialog morphs out of. Hidden (`invisible`) while the dialog
+ * is open so the shared-element card appears to be the same surface.
+ *
+ * Pass the trigger's `borderRadius`/`boxShadow` via `style` (not `className`)
+ * so Motion can correct their distortion during the morph.
+ */
+declare const MorphDialogTrigger: ({ children, className, style, }: MorphDialogTriggerProps) => import("react").JSX.Element;
+interface MorphDialogContentProps {
+    children: React.ReactNode;
+    className?: string;
+    /** Test ID for E2E testing */
+    "data-testid"?: string;
+    /** Position of the dialog. "center" (default) centres in viewport, "bottom" anchors near bottom for thumb reach */
+    position?: "center" | "bottom";
+}
+/**
+ * The morphed dialog card, portalled to the body over a fading scrim. Shares
+ * the trigger's `layoutId` so it animates out of the trigger's position, then
+ * fades its children in.
+ *
+ * Only mounts while open; dismisses on scrim/outside click or Escape (handled
+ * by the underlying Base UI dialog).
+ */
+declare const MorphDialogContent: ({ children, className, position, "data-testid": testId, }: MorphDialogContentProps) => import("react").JSX.Element;
+interface MorphDialogTitleProps {
+    children: React.ReactNode;
+    className?: string;
+    /** Visually hide but keep accessible to screen readers */
+    visuallyHidden?: boolean;
+}
+/**
+ * Title for the dialog. Required for accessibility.
+ * Use visuallyHidden prop to hide visually while keeping accessible.
+ */
+declare const MorphDialogTitle: ({ children, className, visuallyHidden, }: MorphDialogTitleProps) => import("react").JSX.Element;
+interface MorphDialogDescriptionProps {
+    children: React.ReactNode;
+    className?: string;
+    /** Visually hide but keep accessible to screen readers */
+    visuallyHidden?: boolean;
+}
+/**
+ * Description for the dialog. Provides accessible description.
+ * Use visuallyHidden prop to hide visually while keeping accessible.
+ */
+declare const MorphDialogDescription: ({ children, className, visuallyHidden, }: MorphDialogDescriptionProps) => import("react").JSX.Element;
+export { MorphDialog, MorphDialogContent, MorphDialogDescription, MorphDialogTitle, MorphDialogTrigger, useMorphDialog, };

package/dist/components/morph-dialog/morph-dialog-root.js

@@ -0,0 +1,106 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import { durations, springs } from "@instruments/materia-ui/tokens/motion";
+import { radii } from "@instruments/materia-ui/tokens/radius-tokens";
+import { shadows } from "@instruments/materia-ui/tokens/shadows";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { createContext, use, useId, useMemo } from "react";
+import { useControllableState } from "../../hooks/use-controllable-state.js";
+import { asMotionStyle } from "../../utils/motion-style.js";
+/**
+ * Shared spring config for layout animations.
+ * Swift spring - zero overshoot, instant settle. No bounce.
+ */
+const LAYOUT_SPRING = springs.swift;
+const MorphDialogContext = createContext(null);
+const useMorphDialog = () => {
+    const ctx = use(MorphDialogContext);
+    if (!ctx) {
+        throw new Error("useMorphDialog must be used within MorphDialog");
+    }
+    return ctx;
+};
+/**
+ * Root of a dialog that morphs open from its trigger via a shared-element
+ * layout animation - the trigger and the dialog card share a `layoutId`, so
+ * Motion tweens position, size, radius, and shadow between them.
+ *
+ * Controlled when `open` is passed, otherwise uncontrolled. Provides context
+ * to the trigger, content, title, and description parts.
+ *
+ * @bestPractice Reach for `MorphDialog` only when the modal should animate out of its trigger element (shared-layout); a plain centred modal is a `Dialog`.
+ * @bestPractice Pass the trigger's `borderRadius` / `boxShadow` via `style` (not `className`) on `MorphDialogTrigger` so Motion can correct their distortion during the morph.
+ * @bestPractice Render a `MorphDialogTitle` (use `visuallyHidden` if needed) for the accessible name; mount `ReducedMotionProvider` at the app root since it animates via `m.*`.
+ * @category overlays
+ */
+const MorphDialog = ({ children, open: controlledOpen, onOpenChange, }) => {
+    const [open, setOpen] = useControllableState({
+        defaultValue: false,
+        onChange: onOpenChange,
+        value: controlledOpen,
+    });
+    const layoutId = useId();
+    const contextValue = useMemo(() => ({ layoutId, open, setOpen }), [layoutId, open, setOpen]);
+    return (_jsx(MorphDialogContext.Provider, { value: contextValue, children: _jsx(DialogPrimitive.Root, { onOpenChange: setOpen, open: open, children: children }) }));
+};
+/**
+ * The element the dialog morphs out of. Hidden (`invisible`) while the dialog
+ * is open so the shared-element card appears to be the same surface.
+ *
+ * Pass the trigger's `borderRadius`/`boxShadow` via `style` (not `className`)
+ * so Motion can correct their distortion during the morph.
+ */
+const MorphDialogTrigger = ({ children, className, style, }) => {
+    const { layoutId, open } = useMorphDialog();
+    return (_jsx(DialogPrimitive.Trigger, { disabled: open, nativeButton: false, render: _jsx(m.div, { className: cn(className, open && "invisible"), layoutId: layoutId, style: asMotionStyle(style), transition: { layout: LAYOUT_SPRING } }), children: children }));
+};
+/**
+ * The morphed dialog card, portalled to the body over a fading scrim. Shares
+ * the trigger's `layoutId` so it animates out of the trigger's position, then
+ * fades its children in.
+ *
+ * Only mounts while open; dismisses on scrim/outside click or Escape (handled
+ * by the underlying Base UI dialog).
+ */
+const MorphDialogContent = ({ children, className, position = "center", "data-testid": testId, }) => {
+    const { layoutId, open, setOpen } = useMorphDialog();
+    // Centring wrapper classes - uses flexbox so layoutId element doesn't need CSS transforms
+    const wrapperClasses = position === "bottom"
+        ? "fixed inset-0 z-50 flex items-end justify-center pb-6"
+        : "fixed inset-0 z-50 flex items-end justify-center pb-dialog-lift";
+    return (_jsx(AnimatePresence, { children: open && (_jsxs(DialogPrimitive.Portal, { keepMounted: true, children: [_jsx(DialogPrimitive.Backdrop, { hidden: false, render: _jsx(m.div, { animate: { opacity: 1 }, className: "glass-scrim fixed inset-0 z-40", exit: { opacity: 0 }, initial: { opacity: 0 }, transition: { duration: durations.quick } }) }), _jsx(DialogPrimitive.Popup, { className: wrapperClasses, hidden: false, onClick: (e) => {
+                        // Close when clicking the wrapper area (outside the card)
+                        if (e.target === e.currentTarget) {
+                            setOpen(false);
+                        }
+                    }, children: _jsx(m.div, { className: cn("w-[calc(100%-3rem)] max-w-sm overflow-hidden bg-white", position === "bottom" && "max-h-[calc(100vh-3rem)]", className), "data-testid": testId, layoutId: layoutId, style: {
+                            borderRadius: radii["4xl"],
+                            boxShadow: shadows["2xl"],
+                        }, transition: { layout: LAYOUT_SPRING }, children: _jsx(m.div, { animate: { opacity: 1 }, exit: { opacity: 0 }, initial: { opacity: 0 }, transition: {
+                                opacity: { duration: 0.15 },
+                            }, children: children }) }) })] })) }));
+};
+/**
+ * Title for the dialog. Required for accessibility.
+ * Use visuallyHidden prop to hide visually while keeping accessible.
+ */
+const MorphDialogTitle = ({ children, className, visuallyHidden, }) => {
+    if (visuallyHidden === true) {
+        return (_jsx(DialogPrimitive.Title, { className: "sr-only", children: children }));
+    }
+    return (_jsx(DialogPrimitive.Title, { render: _jsx("span", { className: className }), children: children }));
+};
+/**
+ * Description for the dialog. Provides accessible description.
+ * Use visuallyHidden prop to hide visually while keeping accessible.
+ */
+const MorphDialogDescription = ({ children, className, visuallyHidden, }) => {
+    if (visuallyHidden === true) {
+        return (_jsx(DialogPrimitive.Description, { className: "sr-only", children: children }));
+    }
+    return (_jsx(DialogPrimitive.Description, { className: className, children: children }));
+};
+export { MorphDialog, MorphDialogContent, MorphDialogDescription, MorphDialogTitle, MorphDialogTrigger, useMorphDialog, };

package/dist/components/morph-dialog.d.ts

@@ -0,0 +1 @@
+export { MorphDialog, MorphDialogContent, MorphDialogDescription, MorphDialogTitle, MorphDialogTrigger, useMorphDialog, } from "./morph-dialog/morph-dialog-root.js";

package/dist/components/morph-dialog.js

@@ -0,0 +1,2 @@
+"use client";
+export { MorphDialog, MorphDialogContent, MorphDialogDescription, MorphDialogTitle, MorphDialogTrigger, useMorphDialog, } from "./morph-dialog/morph-dialog-root.js";

package/dist/components/motion-config/motion-config-root.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+/**
+ * App-level motion provider. Place once in each app's root layout to cover all
+ * animated descendants. It does two things:
+ *
+ * 1. `MotionConfig` respects the user's `prefers-reduced-motion` OS setting.
+ * 2. `LazyMotion` loads the animation feature bundle (`domMax`) as one shared,
+ *    code-split chunk, so @instruments/materia-ui components render the lightweight `m.*`
+ *    primitives instead of pulling the full motion engine into every consumer's
+ *    initial bundle. Non-strict so apps that render `motion.*` directly still
+ *    work; @instruments/materia-ui itself uses only `m.*` (enforced by howells/no-raw-motion-namespace).
+ *
+ * @bestPractice Mount `ReducedMotionProvider` once in each app's root layout, wrapping everything - every @instruments/materia-ui `m.*` component needs the `LazyMotion` feature bundle it provides or it renders static and never animates.
+ * @bestPractice It's required app-side, not inside @instruments/materia-ui - the library ships only lightweight `m.*` primitives, so without this provider the `domMax` features never load.
+ * @bestPractice Rely on it (not per-component code) for reduced motion: its `MotionConfig reducedMotion="user"` honours the OS setting for all descendants.
+ * @category motion
+ */
+export declare const ReducedMotionProvider: ({ children, }: {
+    children: ReactNode;
+}) => import("react").JSX.Element;

package/dist/components/motion-config/motion-config-root.js

@@ -0,0 +1,20 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { domMax, LazyMotion, MotionConfig } from "motion/react";
+/**
+ * App-level motion provider. Place once in each app's root layout to cover all
+ * animated descendants. It does two things:
+ *
+ * 1. `MotionConfig` respects the user's `prefers-reduced-motion` OS setting.
+ * 2. `LazyMotion` loads the animation feature bundle (`domMax`) as one shared,
+ *    code-split chunk, so @instruments/materia-ui components render the lightweight `m.*`
+ *    primitives instead of pulling the full motion engine into every consumer's
+ *    initial bundle. Non-strict so apps that render `motion.*` directly still
+ *    work; @instruments/materia-ui itself uses only `m.*` (enforced by howells/no-raw-motion-namespace).
+ *
+ * @bestPractice Mount `ReducedMotionProvider` once in each app's root layout, wrapping everything - every @instruments/materia-ui `m.*` component needs the `LazyMotion` feature bundle it provides or it renders static and never animates.
+ * @bestPractice It's required app-side, not inside @instruments/materia-ui - the library ships only lightweight `m.*` primitives, so without this provider the `domMax` features never load.
+ * @bestPractice Rely on it (not per-component code) for reduced motion: its `MotionConfig reducedMotion="user"` honours the OS setting for all descendants.
+ * @category motion
+ */
+export const ReducedMotionProvider = ({ children, }) => (_jsx(MotionConfig, { reducedMotion: "user", children: _jsx(LazyMotion, { features: domMax, children: children }) }));

package/dist/components/motion-config.d.ts

@@ -0,0 +1 @@
+export { ReducedMotionProvider } from "./motion-config/motion-config-root.js";

package/dist/components/motion-config.js

@@ -0,0 +1 @@
+export { ReducedMotionProvider } from "./motion-config/motion-config-root.js";

package/dist/components/native-select/native-select-optgroup.d.ts

@@ -0,0 +1,3 @@
+import type * as React from "react";
+/** A native `<optgroup>` that labels a set of options inside {@link NativeSelect}. */
+export declare const NativeSelectOptGroup: ({ className, ...props }: React.ComponentProps<"optgroup">) => React.JSX.Element;

package/dist/components/native-select/native-select-optgroup.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** A native `<optgroup>` that labels a set of options inside {@link NativeSelect}. */
+export const NativeSelectOptGroup = ({ className, ...props }) => (_jsx("optgroup", { className: cn(className), "data-component": "native-select-optgroup", "data-slot": "native-select-optgroup", ...props }));

package/dist/components/native-select/native-select-option.d.ts

@@ -0,0 +1,3 @@
+import type * as React from "react";
+/** A native `<option>` for use inside {@link NativeSelect}. */
+export declare const NativeSelectOption: ({ ...props }: React.ComponentProps<"option">) => React.JSX.Element;

package/dist/components/native-select/native-select-option.js

@@ -0,0 +1,3 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** A native `<option>` for use inside {@link NativeSelect}. */
+export const NativeSelectOption = ({ ...props }) => (_jsx("option", { "data-component": "native-select-option", "data-slot": "native-select-option", ...props }));

package/dist/components/native-select/native-select-root.d.ts

@@ -0,0 +1,15 @@
+import type * as React from "react";
+/**
+ * Styled wrapper around a real native `<select>`, so it stays controlled and
+ * accessible through standard select props (`value`/`defaultValue`/`onChange`)
+ * and keeps the platform's keyboard and mobile picker behaviour.
+ *
+ * @bestPractice `NativeSelect` wraps a real `<select>` - use standard `value`/`defaultValue`/`onChange` and `NativeSelectOption`/`NativeSelectOptGroup` children, not `Select` parts.
+ * @bestPractice Reach for `NativeSelect` when the native mobile picker and zero-JS behaviour matter; use `Select` when you need custom-rendered option content or styling.
+ * @bestPractice It has no built-in label - associate a `Label` via `htmlFor`/`id` for an accessible name.
+ * @category forms
+ */
+declare const NativeSelect: ({ className, ...props }: React.ComponentProps<"select">) => React.JSX.Element;
+export { NativeSelectOptGroup } from "./native-select-optgroup.js";
+export { NativeSelectOption } from "./native-select-option.js";
+export { NativeSelect };