@instruments/materia-ui 0.1.0

package/dist/components/hotspot-indicator/hotspot-indicator-root.d.ts

@@ -0,0 +1,41 @@
+export interface HotspotIndicatorProps {
+    /** Horizontal position as a percentage (0-100). */
+    centerX: number;
+    /** Vertical position as a percentage (0-100). */
+    centerY: number;
+    /** Additional class names for the button element. */
+    className?: string;
+    /** Whether interaction is disabled (e.g. during processing). */
+    disabled?: boolean;
+    /** Custom focus ring classes. Defaults to grey ring for neutral, blue for blue variant. */
+    focusRingClass?: string;
+    /** Whether this hotspot is the currently selected/active one. */
+    active?: boolean;
+    /** Whether this hotspot is being hovered. */
+    hovered?: boolean;
+    /** Accessible label for the hotspot button. */
+    label?: string;
+    /** Called when the hotspot is clicked. */
+    onClick?: () => void;
+    /** Called when the mouse enters the hotspot. */
+    onMouseEnter?: () => void;
+    /** Called when the mouse leaves the hotspot. */
+    onMouseLeave?: () => void;
+    /** Show a loading spinner overlay on the dot. */
+    showSpinner?: boolean;
+    /** Colour variant: "neutral" for white/dark dots, "blue" for blue dots. */
+    variant?: "neutral" | "blue";
+}
+/**
+ * Animated hotspot dot (outer ring + inner dot) for marking locations on images.
+ *
+ * Positioned absolutely by percentage (`centerX`/`centerY`), so it needs a
+ * positioned parent. Hover and active states are controlled by the parent via
+ * `hovered`/`active` - the dot grows and the ring pulses in response.
+ *
+ * @bestPractice Place it inside a `position: relative` parent - it positions itself absolutely by `centerX`/`centerY` percentages, so it lands wrong in a static-flow container.
+ * @bestPractice State is parent-controlled: pass `hovered`/`active` (plus `onMouseEnter`/`onClick`) - the dot grows and the ring pulses only in response; it tracks nothing itself.
+ * @bestPractice Always pass `label` - it's the button's `aria-label` and the hotspot's only accessible name; also mount `ReducedMotionProvider` so the pulse honours the OS motion setting.
+ * @category motion
+ */
+export declare const HotspotIndicator: ({ centerX, centerY, active, hovered, variant, label, onClick, onMouseEnter, onMouseLeave, disabled, showSpinner, focusRingClass, className, }: HotspotIndicatorProps) => import("react").JSX.Element;

package/dist/components/hotspot-indicator/hotspot-indicator-root.js

@@ -0,0 +1,117 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import * as m from "motion/react-m";
+import { asMotionStyle } from "../../utils/motion-style.js";
+import { Spinner } from "../spinner.js";
+const dotSize = (active, hovered) => {
+    if (active) {
+        return 16;
+    }
+    if (hovered) {
+        return 14;
+    }
+    return 12;
+};
+const SPRING_TRANSITION = {
+    damping: 30,
+    stiffness: 500,
+    type: "spring",
+};
+const VARIANT_STYLES = {
+    blue: {
+        dot: {
+            active: {
+                backgroundColor: "#3b82f6",
+                boxShadow: "0 0 0 1.5px #fff, 0 2px 10px rgba(59, 130, 246, 0.45)",
+            },
+            inactive: {
+                backgroundColor: "#60a5fa",
+                boxShadow: "0 0 0 1px rgba(255,255,255,0.8), 0 2px 8px rgba(59, 130, 246, 0.35)",
+            },
+        },
+        focusRing: "focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2",
+        ring: {
+            active: {
+                backgroundColor: "rgba(59, 130, 246, 0.2)",
+                border: "1.5px solid rgba(59, 130, 246, 0.6)",
+            },
+            inactive: {
+                backgroundColor: "rgba(59, 130, 246, 0.1)",
+                border: "1.5px solid rgba(59, 130, 246, 0.4)",
+            },
+        },
+    },
+    neutral: {
+        dot: {
+            active: {
+                backgroundColor: "#111",
+                boxShadow: "0 0 0 1.5px #fff, 0 2px 10px rgba(0,0,0,0.35)",
+            },
+            inactive: {
+                backgroundColor: "#fff",
+                boxShadow: "0 0 0 1px rgba(0,0,0,0.25), 0 2px 8px rgba(0,0,0,0.3)",
+            },
+        },
+        focusRing: "focus:outline-none focus-visible:ring-2 focus-visible:ring-gray-900 focus-visible:ring-offset-2",
+        ring: {
+            active: {
+                backgroundColor: "rgba(0, 0, 0, 0.15)",
+                border: "1.5px solid rgba(0, 0, 0, 0.4)",
+            },
+            inactive: {
+                backgroundColor: "rgba(255, 255, 255, 0.3)",
+                border: "1.5px solid rgba(255, 255, 255, 0.6)",
+            },
+        },
+    },
+};
+const ringAnimate = (hovered, active) => {
+    if (hovered && !active) {
+        return { height: 32, opacity: 1, scale: [1, 1.25, 1], width: 32 };
+    }
+    const isHighlighted = hovered || active;
+    return {
+        height: isHighlighted ? 32 : 0,
+        opacity: isHighlighted ? 1 : 0,
+        scale: 1,
+        width: isHighlighted ? 32 : 0,
+    };
+};
+const PULSE_TRANSITION = {
+    default: SPRING_TRANSITION,
+    scale: {
+        duration: 1.2,
+        ease: "easeInOut",
+        repeat: Number.POSITIVE_INFINITY,
+    },
+};
+const ringTransition = (hovered, active) => hovered && !active ? PULSE_TRANSITION : SPRING_TRANSITION;
+/**
+ * Animated hotspot dot (outer ring + inner dot) for marking locations on images.
+ *
+ * Positioned absolutely by percentage (`centerX`/`centerY`), so it needs a
+ * positioned parent. Hover and active states are controlled by the parent via
+ * `hovered`/`active` - the dot grows and the ring pulses in response.
+ *
+ * @bestPractice Place it inside a `position: relative` parent - it positions itself absolutely by `centerX`/`centerY` percentages, so it lands wrong in a static-flow container.
+ * @bestPractice State is parent-controlled: pass `hovered`/`active` (plus `onMouseEnter`/`onClick`) - the dot grows and the ring pulses only in response; it tracks nothing itself.
+ * @bestPractice Always pass `label` - it's the button's `aria-label` and the hotspot's only accessible name; also mount `ReducedMotionProvider` so the pulse honours the OS motion setting.
+ * @category motion
+ */
+export const HotspotIndicator = ({ centerX, centerY, active = false, hovered = false, variant = "neutral", label, onClick, onMouseEnter, onMouseLeave, disabled = false, showSpinner = false, focusRingClass, className, }) => {
+    const size = dotSize(active, hovered);
+    const styles = VARIANT_STYLES[variant];
+    const stateKey = active ? "active" : "inactive";
+    return (_jsxs(_Fragment, { children: [_jsxs("button", { "aria-label": label, className: cn("pointer-events-auto absolute z-10 -translate-1/2", focusRingClass ?? styles.focusRing, disabled && "cursor-not-allowed", className), disabled: disabled, onClick: onClick
+                    ? (e) => {
+                        e.stopPropagation();
+                        onClick();
+                    }
+                    : undefined, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, style: { left: `${centerX}%`, top: `${centerY}%` }, type: "button", children: [_jsx(m.div, { animate: ringAnimate(hovered, active), className: "absolute top-1/2 left-1/2 -translate-1/2 rounded-full", initial: false, style: asMotionStyle(styles.ring[stateKey]), transition: ringTransition(hovered, active) }), _jsx(m.div, { className: "relative rounded-full", layout: true, style: asMotionStyle({
+                            ...styles.dot[stateKey],
+                            borderRadius: 9999,
+                            height: size,
+                            width: size,
+                        }), transition: SPRING_TRANSITION })] }), showSpinner && (_jsx("div", { className: "pointer-events-none absolute z-10 -translate-1/2", style: { left: `${centerX}%`, top: `${centerY}%` }, children: _jsx(Spinner, { size: "xs" }) }))] }));
+};

package/dist/components/hotspot-indicator.d.ts

@@ -0,0 +1 @@
+export { HotspotIndicator, type HotspotIndicatorProps, } from "./hotspot-indicator/hotspot-indicator-root.js";

package/dist/components/hotspot-indicator.js

@@ -0,0 +1 @@
+export { HotspotIndicator, } from "./hotspot-indicator/hotspot-indicator-root.js";

package/dist/components/hover-card/hover-card-root.d.ts

@@ -0,0 +1,24 @@
+import { PreviewCard as HoverCardPrimitive } from "@base-ui/react/preview-card";
+/**
+ * Hover-triggered popover for supplementary content (previews, profile cards).
+ * Controlled via `open`/`onOpenChange`, or uncontrolled via `defaultOpen`;
+ * `HoverCardTrigger`'s `delay`/`closeDelay` (ms) tune the hover-in / hover-out timing.
+ *
+ * @bestPractice Use `HoverCard` for rich hover content (preview, profile card); a one-line hint is a `Tooltip`, a click-opened panel is a `Popover`.
+ * @bestPractice It opens on hover / focus only - never hide essential actions or content a touch / keyboard-only user can't otherwise reach behind it.
+ * @bestPractice Tune the trigger's `delay`/`closeDelay` (ms) instead of adding your own timers; `HoverCardContent` portals to the body.
+ * @category overlays
+ */
+declare const HoverCard: <Payload>({ ...props }: HoverCardPrimitive.Root.Props<Payload>) => import("react").JSX.Element;
+/** Element that reveals the card on hover/focus; pass `render` to project the behaviour onto your own element. Hover timing is set here with `delay` and `closeDelay` (ms). */
+declare const HoverCardTrigger: ({ ...props }: HoverCardPrimitive.Trigger.Props) => import("react").JSX.Element;
+type HoverCardPositionerProps = Pick<HoverCardPrimitive.Positioner.Props, "align" | "alignOffset" | "anchor" | "arrowPadding" | "collisionAvoidance" | "collisionBoundary" | "collisionPadding" | "positionMethod" | "side" | "sideOffset" | "sticky">;
+/**
+ * Floating panel, rendered in a portal and positioned by `side`/`align` with a
+ * `sideOffset` gap (px) from the trigger.
+ * @default align `"center"`, sideOffset `4`
+ */
+declare const HoverCardContent: ({ className, align, sideOffset, side, alignOffset, anchor, arrowPadding, collisionAvoidance, collisionBoundary, collisionPadding, positionMethod, sticky, ...props }: Omit<HoverCardPrimitive.Popup.Props, "className"> & HoverCardPositionerProps & {
+    className?: string;
+}) => import("react").JSX.Element;
+export { HoverCard, HoverCardContent, HoverCardTrigger };

package/dist/components/hover-card/hover-card-root.js

@@ -0,0 +1,25 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PreviewCard as HoverCardPrimitive } from "@base-ui/react/preview-card";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { POPOVER_CONTENT_ANIMATION, POPOVER_SURFACE, } from "../../tokens/overlay-styles.js";
+/**
+ * Hover-triggered popover for supplementary content (previews, profile cards).
+ * Controlled via `open`/`onOpenChange`, or uncontrolled via `defaultOpen`;
+ * `HoverCardTrigger`'s `delay`/`closeDelay` (ms) tune the hover-in / hover-out timing.
+ *
+ * @bestPractice Use `HoverCard` for rich hover content (preview, profile card); a one-line hint is a `Tooltip`, a click-opened panel is a `Popover`.
+ * @bestPractice It opens on hover / focus only - never hide essential actions or content a touch / keyboard-only user can't otherwise reach behind it.
+ * @bestPractice Tune the trigger's `delay`/`closeDelay` (ms) instead of adding your own timers; `HoverCardContent` portals to the body.
+ * @category overlays
+ */
+const HoverCard = ({ ...props }) => (_jsx(HoverCardPrimitive.Root, { "data-component": "hover-card", "data-slot": "hover-card", ...props }));
+/** Element that reveals the card on hover/focus; pass `render` to project the behaviour onto your own element. Hover timing is set here with `delay` and `closeDelay` (ms). */
+const HoverCardTrigger = ({ ...props }) => (_jsx(HoverCardPrimitive.Trigger, { "data-component": "hover-card-trigger", "data-slot": "hover-card-trigger", ...props }));
+/**
+ * Floating panel, rendered in a portal and positioned by `side`/`align` with a
+ * `sideOffset` gap (px) from the trigger.
+ * @default align `"center"`, sideOffset `4`
+ */
+const HoverCardContent = ({ className, align = "center", sideOffset = 4, side, alignOffset, anchor, arrowPadding, collisionAvoidance, collisionBoundary, collisionPadding, positionMethod, sticky, ...props }) => (_jsx(HoverCardPrimitive.Portal, { "data-component": "hover-card-portal", "data-slot": "hover-card-portal", children: _jsx(HoverCardPrimitive.Positioner, { align: align, alignOffset: alignOffset, anchor: anchor, arrowPadding: arrowPadding, className: "z-50", collisionAvoidance: collisionAvoidance, collisionBoundary: collisionBoundary, collisionPadding: collisionPadding, positionMethod: positionMethod, side: side, sideOffset: sideOffset, sticky: sticky, children: _jsx(HoverCardPrimitive.Popup, { className: cn(`${POPOVER_CONTENT_ANIMATION} ${POPOVER_SURFACE} w-64 origin-(--transform-origin) rounded-2xl border p-4 dark:shadow-none`, className), "data-component": "hover-card-content", "data-slot": "hover-card-content", ...props }) }) }));
+export { HoverCard, HoverCardContent, HoverCardTrigger };

package/dist/components/hover-card.d.ts

@@ -0,0 +1 @@
+export { HoverCard, HoverCardContent, HoverCardTrigger, } from "./hover-card/hover-card-root.js";

package/dist/components/hover-card.js

@@ -0,0 +1 @@
+export { HoverCard, HoverCardContent, HoverCardTrigger, } from "./hover-card/hover-card-root.js";

package/dist/components/icon/icon-root.d.ts

@@ -0,0 +1,38 @@
+import type * as React from "react";
+import type { IconComponent } from "../../tokens/icon-component.js";
+import type { ComponentSize } from "../../tokens/size.js";
+/** Icon supports an additional "3xs" size for tiny icons in small containers */
+export type IconSize = ComponentSize | "3xs";
+/** Tailwind size classes for each icon size */
+export declare const ICON_SIZE_CLASS: Record<IconSize, string>;
+/**
+ * Renders a Lucide or custom SVG icon with consistent sizing and stroke width.
+ *
+ * @param props - The icon props
+ * @param props.icon - Icon component from lucide-react or any SVG React component (required).
+ * @param props.size - Icon size. Options: "3xs" (10px), "2xs" (12px), "xs" (16px), "sm" (18px), "base" (default, 20px), "lg" (24px), "xl" (28px), "2xl" (32px), "3xl" (40px).
+ * @param props.className - Additional CSS classes to apply.
+ * @param props... - All other standard SVG element props.
+ *
+ * @example
+ * ```tsx
+ * <Icon icon={ArrowRight} />
+ * <Icon icon={ArrowRight} size="lg" className="text-muted-foreground" />
+ * ```
+ */
+export interface IconProps extends Omit<React.SVGProps<SVGSVGElement>, "strokeWidth"> {
+    /** Icon component from lucide-react or any SVG React component. */
+    icon: IconComponent;
+    /** Size scale for icons. Supports ComponentSize plus "3xs" for tiny icons. Defaults to `base` (20px). */
+    size?: IconSize;
+}
+/**
+ * Renders the given icon as a decorative SVG - always `aria-hidden` and
+ * non-focusable, with a fixed 1.5 stroke width.
+ *
+ * @bestPractice Route every lucide/SVG glyph through `Icon` (`<Icon icon={ArrowRight} />`), never the raw component - it fixes the `1.5` stroke and size scale so icons stay consistent.
+ * @bestPractice `Icon` is always `aria-hidden` + non-focusable - pair it with visible text or give the interactive parent an `aria-label`; never rely on it to name a control.
+ * @bestPractice Size with the `size` token (`"sm"`,`"lg"`…), not `className="size-6"` - the scale maps to the shared `ComponentSize` steps other components align to.
+ * @category color
+ */
+export declare const Icon: ({ icon: IconComp, size, className, ...props }: IconProps) => React.JSX.Element;

package/dist/components/icon/icon-root.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** Tailwind size classes for each icon size */
+export const ICON_SIZE_CLASS = {
+    // 32px
+    "2xl": "size-8",
+    // 12px
+    "2xs": "size-3",
+    // 40px
+    "3xl": "size-10",
+    // 10px
+    "3xs": "size-2.5",
+    // 20px
+    base: "size-5",
+    // 24px
+    lg: "size-6",
+    // 18px
+    sm: "size-4.5",
+    // 28px
+    xl: "size-7",
+    // 16px
+    xs: "size-4",
+};
+const sizeToIconClass = (size) => ICON_SIZE_CLASS[size ?? "base"];
+/**
+ * Renders the given icon as a decorative SVG - always `aria-hidden` and
+ * non-focusable, with a fixed 1.5 stroke width.
+ *
+ * @bestPractice Route every lucide/SVG glyph through `Icon` (`<Icon icon={ArrowRight} />`), never the raw component - it fixes the `1.5` stroke and size scale so icons stay consistent.
+ * @bestPractice `Icon` is always `aria-hidden` + non-focusable - pair it with visible text or give the interactive parent an `aria-label`; never rely on it to name a control.
+ * @bestPractice Size with the `size` token (`"sm"`,`"lg"`…), not `className="size-6"` - the scale maps to the shared `ComponentSize` steps other components align to.
+ * @category color
+ */
+export const Icon = ({ icon: IconComp, size = "base", className, ...props }) => (_jsx(IconComp, { "aria-hidden": true, className: cn("stroke-medium", sizeToIconClass(size), className), "data-component": "icon", focusable: false, ...props }));

package/dist/components/icon-box/icon-box-root.d.ts

@@ -0,0 +1,29 @@
+import type { VariantProps } from "class-variance-authority";
+import type * as React from "react";
+import type { IconProps } from "../icon.js";
+declare const iconBoxVariants: (props?: ({
+    size?: "2xl" | "2xs" | "3xl" | "base" | "lg" | "sm" | "xl" | "xs" | null | undefined;
+    tone?: "brand" | "danger" | "info" | "neutral" | "success" | "warning" | null | undefined;
+    emphasis?: "ghost" | "outline" | "soft" | "solid" | null | undefined;
+    radius?: "full" | "rounded" | "square" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface IconBoxProps extends Omit<React.ComponentProps<"div">, "children">, VariantProps<typeof iconBoxVariants> {
+    /** Icon component from lucide-react or any SVG React component. */
+    icon: IconProps["icon"];
+    /** Additional className for the icon itself. */
+    iconClassName?: string;
+    /** Size of the icon inside the box. Defaults based on box size. */
+    iconSize?: IconProps["size"];
+}
+/**
+ * Renders an icon inside a styled surface box - for empty states, feature
+ * highlights, and status indicators. Icon size defaults to the box size.
+ * Import from "@instruments/materia-ui/components/icon-box".
+ *
+ * @bestPractice Reach for `IconBox` for a framed-icon surface (empty states, feature highlights) instead of wrapping `Icon` in a hand-styled `div` - it owns the size→radius and box→icon-size pairings.
+ * @bestPractice Set colour via `tone`, not a hex/`bg-*` className - `tone` carries the paired surface+foreground tokens, including the dark-mode variants.
+ * @bestPractice Let `iconSize` default from the box `size`; override only when the glyph must break the built-in `BOX_TO_ICON_SIZE` ratio.
+ * @category color
+ */
+export declare const IconBox: ({ icon, size, tone, emphasis, radius, iconSize, className, iconClassName, ...props }: IconBoxProps) => React.JSX.Element;
+export {};

package/dist/components/icon-box/icon-box-root.js

@@ -0,0 +1,86 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cva } from "class-variance-authority";
+import { RADIUS_CLASSES } from "../../tokens/radius.js";
+import { Icon } from "../icon.js";
+const BOX_TO_ICON_SIZE = {
+    "2xl": "base",
+    "2xs": "3xs",
+    "3xl": "lg",
+    base: "sm",
+    lg: "sm",
+    sm: "xs",
+    xl: "base",
+    xs: "2xs",
+};
+const iconBoxVariants = cva("flex shrink-0 items-center justify-center border border-transparent", {
+    compoundVariants: [
+        { class: "rounded", radius: "rounded", size: ["2xs", "xs"] },
+        { class: "rounded-md", radius: "rounded", size: ["sm", "base"] },
+        { class: "rounded-lg", radius: "rounded", size: ["lg", "xl"] },
+        { class: "rounded-xl", radius: "rounded", size: "2xl" },
+        { class: "rounded-2xl", radius: "rounded", size: "3xl" },
+        // `neutral` + `soft` reproduces the former `muted` tone verbatim (muted
+        // surface + dim foreground) - its home after `muted` left the tone axis.
+        {
+            class: "bg-muted text-muted-foreground",
+            emphasis: "soft",
+            tone: "neutral",
+        },
+    ],
+    defaultVariants: {
+        emphasis: "solid",
+        radius: "rounded",
+        size: "base",
+        tone: "neutral",
+    },
+    variants: {
+        size: {
+            "2xs": "size-4",
+            xs: "size-6",
+            sm: "size-8",
+            base: "size-10",
+            lg: "size-12",
+            xl: "size-16",
+            "2xl": "size-20",
+            "3xl": "size-24",
+        },
+        // Lockstep: these keys ARE the canonical `Tone` vocabulary, enforced by
+        // `satisfies Record<Tone, string>`. `brand` is the system-wide brand
+        // yellow - same surface/foreground pairing as Pill/Badge solid brand
+        // (dark readable foreground on the brand surface, both themes); the
+        // former `primary` dark look is retired. `muted`/`secondary` collapsed
+        // onto `neutral` (muted → neutral+soft compound above; secondary →
+        // neutral).
+        tone: {
+            neutral: "bg-accent text-foreground",
+            brand: "bg-brand text-brand-foreground",
+            danger: "bg-error-soft text-error-foreground dark:bg-error-soft/20 dark:text-error-accent",
+            warning: "bg-warning-soft text-warning-foreground dark:bg-warning-soft/20 dark:text-warning-accent",
+            success: "bg-affirmative-soft text-affirmative-foreground dark:bg-affirmative-soft/20 dark:text-affirmative-accent",
+            info: "bg-info-soft text-info-foreground dark:bg-info-soft/20 dark:text-info-accent",
+        },
+        emphasis: {
+            solid: "",
+            soft: "",
+            outline: "border-border bg-transparent",
+            ghost: "border-transparent bg-transparent",
+        },
+        radius: RADIUS_CLASSES,
+    },
+});
+/**
+ * Renders an icon inside a styled surface box - for empty states, feature
+ * highlights, and status indicators. Icon size defaults to the box size.
+ * Import from "@instruments/materia-ui/components/icon-box".
+ *
+ * @bestPractice Reach for `IconBox` for a framed-icon surface (empty states, feature highlights) instead of wrapping `Icon` in a hand-styled `div` - it owns the size→radius and box→icon-size pairings.
+ * @bestPractice Set colour via `tone`, not a hex/`bg-*` className - `tone` carries the paired surface+foreground tokens, including the dark-mode variants.
+ * @bestPractice Let `iconSize` default from the box `size`; override only when the glyph must break the built-in `BOX_TO_ICON_SIZE` ratio.
+ * @category color
+ */
+export const IconBox = ({ icon, size, tone, emphasis, radius, iconSize, className, iconClassName, ...props }) => {
+    const resolvedSize = size ?? "base";
+    const resolvedIconSize = iconSize ?? BOX_TO_ICON_SIZE[resolvedSize] ?? "sm";
+    return (_jsx("div", { className: cn(iconBoxVariants({ emphasis, radius, size, tone }), className), "data-component": "icon-box", ...props, children: _jsx(Icon, { className: iconClassName, icon: icon, size: resolvedIconSize }) }));
+};

package/dist/components/icon-box.d.ts

@@ -0,0 +1 @@
+export { IconBox, type IconBoxProps } from "./icon-box/icon-box-root.js";

package/dist/components/icon-box.js

@@ -0,0 +1 @@
+export { IconBox } from "./icon-box/icon-box-root.js";

package/dist/components/icon-card/icon-card-root.d.ts

@@ -0,0 +1,32 @@
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+import type { WithTestId } from "../../utils/with-test-id.js";
+interface IconCardProps extends WithTestId<Omit<React.ComponentProps<"button">, "children">> {
+    /** The icon to display */
+    icon: LucideIcon;
+    /** Label text below the icon */
+    label: string;
+    /** Whether the card is currently selected */
+    selected?: boolean;
+}
+/**
+ * A selectable card pairing an icon over a label, for option pickers such as
+ * property-type or category choices; renders a native button and forwards its props.
+ *
+ * @example
+ * ```tsx
+ * <IconCard
+ *   icon={HomeIcon}
+ *   label="Residential"
+ *   selected={selectedValue === "residential"}
+ *   onClick={() => setSelectedValue("residential")}
+ * />
+ * ```
+ *
+ * @bestPractice `IconCard` is itself a native `<button>` - wire `selected`/`onClick` and drive a single-select group in state; don't nest it in another button or anchor.
+ * @bestPractice Pass a Lucide component to `icon` (e.g. `HomeIcon`), not a rendered element `<HomeIcon />` - it is handed to the internal `Icon` for consistent sizing/stroke.
+ * @bestPractice Use `IconCard` for compact icon-over-label option pickers (property type, category); for a content container with header/body reach for `Card`, and for a settings row use `SettingsCard`.
+ * @category data
+ */
+declare const IconCard: ({ icon, label, selected, className, testId, ...props }: IconCardProps) => React.JSX.Element;
+export { IconCard, type IconCardProps };

package/dist/components/icon-card/icon-card-root.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Center } from "../center.js";
+import { Icon } from "../icon.js";
+/**
+ * A selectable card pairing an icon over a label, for option pickers such as
+ * property-type or category choices; renders a native button and forwards its props.
+ *
+ * @example
+ * ```tsx
+ * <IconCard
+ *   icon={HomeIcon}
+ *   label="Residential"
+ *   selected={selectedValue === "residential"}
+ *   onClick={() => setSelectedValue("residential")}
+ * />
+ * ```
+ *
+ * @bestPractice `IconCard` is itself a native `<button>` - wire `selected`/`onClick` and drive a single-select group in state; don't nest it in another button or anchor.
+ * @bestPractice Pass a Lucide component to `icon` (e.g. `HomeIcon`), not a rendered element `<HomeIcon />` - it is handed to the internal `Icon` for consistent sizing/stroke.
+ * @bestPractice Use `IconCard` for compact icon-over-label option pickers (property type, category); for a content container with header/body reach for `Card`, and for a settings row use `SettingsCard`.
+ * @category data
+ */
+const IconCard = ({ icon, label, selected = false, className, testId, ...props }) => (_jsxs("button", { className: cn("group text-paragraph-sm flex flex-col items-center gap-3 disabled:pointer-events-none disabled:opacity-50", className), "data-component": "icon-card", "data-selected": selected, "data-testid": testId, type: "button", ...props, children: [_jsx(Center, { className: cn("aspect-square w-full rounded-lg border shadow-xs transition-colors", selected
+                ? "border-foreground bg-accent"
+                : "border-input bg-input group-hover:border-foreground/30"), "data-slot": "icon-card-content", children: _jsx(Icon, { className: "stroke-fine", icon: icon, size: "3xl" }) }), _jsx("span", { className: "font-medium", "data-slot": "icon-card-label", children: label })] }));
+export { IconCard };

package/dist/components/icon-card.d.ts

@@ -0,0 +1 @@
+export { IconCard, type IconCardProps } from "./icon-card/icon-card-root.js";

package/dist/components/icon-card.js

@@ -0,0 +1 @@
+export { IconCard } from "./icon-card/icon-card-root.js";

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

@@ -0,0 +1,69 @@
+import type { Easing, EasingTuple } from "@instruments/materia-ui/tokens/motion";
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+import type { IconSize } from "../icon.js";
+/** Easing value: named preset from @instruments/materia-ui/tokens/motion or a custom bezier tuple */
+type EasingValue = Easing | EasingTuple;
+export interface IconMorphProps extends Omit<React.SVGProps<SVGSVGElement>, "strokeWidth"> {
+    /** Duration for enter animation in seconds. Defaults to `durations.normal`. */
+    enterDuration?: number;
+    /** Easing for enter animation. Accepts named preset or bezier tuple. Defaults to `easings.out`. */
+    enterEasing?: EasingValue;
+    /** Duration for exit animation in seconds. Defaults to `durations.quick`. */
+    exitDuration?: number;
+    /** Easing for exit animation. Accepts named preset or bezier tuple. Defaults to `easings.out`. */
+    exitEasing?: EasingValue;
+    /** Icon component from lucide-react or any SVG React component. */
+    icon: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** Unique key to trigger morph animation when icon changes. */
+    morphKey: string;
+    /** Size scale for icons. Defaults to `base` (20px). */
+    size?: IconSize;
+}
+/**
+ * Icon with blur-crossfade morph animation between icon changes.
+ *
+ * Drop-in replacement for Icon when you need animated transitions.
+ * The icon stays in place while crossfading with a blur effect.
+ *
+ * @example
+ * ```tsx
+ * // Morph between icons based on state
+ * <IconMorph
+ *   icon={isPlaying ? Pause : Play}
+ *   morphKey={isPlaying ? "pause" : "play"}
+ * />
+ *
+ * // With size and color
+ * <IconMorph
+ *   icon={currentIcon}
+ *   morphKey={currentStep}
+ *   size="lg"
+ *   className="text-muted-foreground"
+ * />
+ *
+ * // With custom timing (named presets from @instruments/materia-ui/tokens/motion)
+ * <IconMorph
+ *   icon={icon}
+ *   morphKey={key}
+ *   enterDuration={0.3}
+ *   exitDuration={0.15}
+ *   enterEasing="inOut"
+ *   exitEasing="out"
+ * />
+ *
+ * // With custom bezier tuple
+ * <IconMorph
+ *   icon={icon}
+ *   morphKey={key}
+ *   enterEasing={[0.25, 0.1, 0.25, 1]}
+ * />
+ * ```
+ *
+ * @bestPractice Change `morphKey` whenever `icon` changes (e.g. play↔pause) - the crossfade is keyed off it, so a stale key swaps the new glyph in with no morph.
+ * @bestPractice Use it as the animated drop-in for `Icon`; for a plain static glyph stay on `Icon` and skip the extra `AnimatePresence`/motion cost.
+ * @bestPractice Needs `ReducedMotionProvider` for the blur-crossfade to run and honour reduced motion; like `Icon` it renders `aria-hidden`, so name the control elsewhere.
+ * @category motion
+ */
+export declare const IconMorph: ({ icon: IconComp, morphKey, size, enterDuration, exitDuration, enterEasing, exitEasing, className, ...props }: IconMorphProps) => React.JSX.Element;
+export {};

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

@@ -0,0 +1,84 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { durations, easings } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence } from "motion/react";
+import * as m from "motion/react-m";
+import { ICON_SIZE_CLASS } from "../icon.js";
+/** Default animation timing for morph transitions */
+const DEFAULT_TIMING = {
+    enter: durations.normal,
+    exit: durations.quick,
+};
+/** Default easing for morph transitions */
+const DEFAULT_EASING = {
+    enter: easings.out,
+    exit: easings.out,
+};
+/** Resolve named easing to tuple, or pass through if already a tuple */
+const resolveEasing = (value) => Array.isArray(value) ? value : easings[value];
+/**
+ * Icon with blur-crossfade morph animation between icon changes.
+ *
+ * Drop-in replacement for Icon when you need animated transitions.
+ * The icon stays in place while crossfading with a blur effect.
+ *
+ * @example
+ * ```tsx
+ * // Morph between icons based on state
+ * <IconMorph
+ *   icon={isPlaying ? Pause : Play}
+ *   morphKey={isPlaying ? "pause" : "play"}
+ * />
+ *
+ * // With size and color
+ * <IconMorph
+ *   icon={currentIcon}
+ *   morphKey={currentStep}
+ *   size="lg"
+ *   className="text-muted-foreground"
+ * />
+ *
+ * // With custom timing (named presets from @instruments/materia-ui/tokens/motion)
+ * <IconMorph
+ *   icon={icon}
+ *   morphKey={key}
+ *   enterDuration={0.3}
+ *   exitDuration={0.15}
+ *   enterEasing="inOut"
+ *   exitEasing="out"
+ * />
+ *
+ * // With custom bezier tuple
+ * <IconMorph
+ *   icon={icon}
+ *   morphKey={key}
+ *   enterEasing={[0.25, 0.1, 0.25, 1]}
+ * />
+ * ```
+ *
+ * @bestPractice Change `morphKey` whenever `icon` changes (e.g. play↔pause) - the crossfade is keyed off it, so a stale key swaps the new glyph in with no morph.
+ * @bestPractice Use it as the animated drop-in for `Icon`; for a plain static glyph stay on `Icon` and skip the extra `AnimatePresence`/motion cost.
+ * @bestPractice Needs `ReducedMotionProvider` for the blur-crossfade to run and honour reduced motion; like `Icon` it renders `aria-hidden`, so name the control elsewhere.
+ * @category motion
+ */
+export const IconMorph = ({ icon: IconComp, morphKey, size = "base", enterDuration = DEFAULT_TIMING.enter, exitDuration = DEFAULT_TIMING.exit, enterEasing = DEFAULT_EASING.enter, exitEasing = DEFAULT_EASING.exit, className, ...props }) => {
+    const sizeClass = ICON_SIZE_CLASS[size];
+    return (_jsx("div", { className: cn("relative shrink-0", sizeClass), children: _jsx(AnimatePresence, { mode: "sync", children: _jsx(m.div, { animate: {
+                    filter: "blur(0px)",
+                    scale: 1,
+                }, className: "absolute inset-0", exit: {
+                    filter: "blur(4px)",
+                    scale: 0.9,
+                    transition: {
+                        duration: exitDuration,
+                        ease: resolveEasing(exitEasing),
+                    },
+                }, initial: {
+                    filter: "blur(4px)",
+                    scale: 1.1,
+                }, transition: {
+                    duration: enterDuration,
+                    ease: resolveEasing(enterEasing),
+                }, children: _jsx(IconComp, { "aria-hidden": true, className: cn("stroke-medium", sizeClass, className), "data-component": "icon-morph", focusable: false, ...props }) }, morphKey) }) }));
+};