@instruments/materia-ui 0.1.0

package/dist/compositions/swatch-fan/swatch-fan-engine.js

@@ -0,0 +1,154 @@
+import { getSwatchFanFrame, getSwatchFanSettle, getSwatchFanTarget, SWATCH_FAN_REST_PROGRESS, SWATCH_FAN_SETTLE_THRESHOLD, } from "./swatch-fan.motion.js";
+const INITIAL_CONFIG = {
+    fanOnHover: true,
+    itemCount: 0,
+    onFannedChange: undefined,
+    reducedMotion: false,
+};
+/** Write one computed frame straight onto the card and tile nodes. */
+const writeFrame = (card, swatches, frame, fanned) => {
+    if (card) {
+        card.dataset.state = fanned ? "fanned" : "rest";
+        card.style.transform = frame.cardTransform;
+        // No shadow on the fan's (rectangular) root box - each tile casts its own
+        // shadow-md. A root box-shadow renders as a phantom rectangle behind the
+        // fanned tiles once they splay beyond the root's bounds.
+    }
+    for (const [index, swatch] of swatches.entries()) {
+        const transform = frame.swatchTransforms[index];
+        if (swatch === null || transform === undefined) {
+            continue;
+        }
+        swatch.style.transform = transform;
+    }
+};
+/** Promote the nodes to their own layers only while a settle is in flight. */
+const writeWillChange = (card, swatches, value) => {
+    if (card) {
+        card.style.willChange = value;
+    }
+    for (const swatch of swatches) {
+        if (swatch) {
+            swatch.style.willChange = value;
+        }
+    }
+};
+/**
+ * The hover-fan's imperative motion core: a rAF settle loop that writes
+ * transforms straight to the card and tile nodes, so pointer movement never
+ * re-renders React. Created once per component instance.
+ */
+export const createSwatchFanEngine = () => {
+    let card = null;
+    const swatches = [];
+    let config = INITIAL_CONFIG;
+    let animationFrame = null;
+    let current = SWATCH_FAN_REST_PROGRESS;
+    let fanned = false;
+    let pointerX = 0;
+    let pointerY = 0;
+    let target = getSwatchFanTarget(false);
+    const applyFrame = (progress) => {
+        writeFrame(card, swatches, getSwatchFanFrame(progress, pointerX, pointerY, config.itemCount), fanned);
+    };
+    const stop = () => {
+        if (animationFrame !== null) {
+            cancelAnimationFrame(animationFrame);
+            animationFrame = null;
+            writeWillChange(card, swatches, "");
+        }
+    };
+    const runFrame = () => {
+        const delta = target - current;
+        if (Math.abs(delta) <= SWATCH_FAN_SETTLE_THRESHOLD) {
+            current = target;
+            animationFrame = null;
+            applyFrame(current);
+            writeWillChange(card, swatches, "");
+            return;
+        }
+        // Open (target above current) settles on the faster open rate;
+        // closing snaps back on the tighter exit rate.
+        current += delta * getSwatchFanSettle(delta > 0);
+        applyFrame(current);
+        animationFrame = requestAnimationFrame(runFrame);
+    };
+    const schedule = () => {
+        if (config.reducedMotion) {
+            stop();
+            current = target;
+            applyFrame(current);
+            return;
+        }
+        if (animationFrame === null) {
+            writeWillChange(card, swatches, "transform");
+            animationFrame = requestAnimationFrame(runFrame);
+        }
+    };
+    const setFanned = (nextFanned) => {
+        const didChange = fanned !== nextFanned;
+        fanned = nextFanned;
+        target = getSwatchFanTarget(nextFanned);
+        if (didChange) {
+            config.onFannedChange?.(nextFanned);
+        }
+        schedule();
+    };
+    const resetPointer = () => {
+        pointerX = 0;
+        pointerY = 0;
+    };
+    const openOnInteraction = () => {
+        if (config.fanOnHover) {
+            setFanned(true);
+        }
+    };
+    return {
+        applyCurrent: () => {
+            applyFrame(current);
+        },
+        configure: (next) => {
+            const previous = config;
+            config = next;
+            if (next.itemCount !== previous.itemCount) {
+                stop();
+                applyFrame(current);
+            }
+            if (next.reducedMotion !== previous.reducedMotion) {
+                schedule();
+            }
+        },
+        handlePointerEnter: openOnInteraction,
+        handlePointerLeave: () => {
+            resetPointer();
+            if (config.fanOnHover) {
+                setFanned(false);
+            }
+            else {
+                schedule();
+            }
+        },
+        handlePointerMove: (event) => {
+            if (!config.fanOnHover) {
+                return;
+            }
+            const rect = event.currentTarget.getBoundingClientRect();
+            pointerX = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+            pointerY = ((event.clientY - rect.top) / rect.height) * 2 - 1;
+            schedule();
+        },
+        setCard: (node) => {
+            card = node;
+        },
+        setSwatch: (index, node) => {
+            swatches[index] = node;
+        },
+        /** Adopt the controlled `fanned` value without notifying the owner. */
+        syncFanned: (nextFanned) => {
+            fanned = nextFanned;
+            target = getSwatchFanTarget(nextFanned);
+            schedule();
+        },
+        stop,
+    };
+};

package/dist/compositions/swatch-fan/swatch-fan-hover.d.ts

@@ -0,0 +1,25 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { SwatchFanImageProps, SwatchFanItem, SwatchFanSize } from "./swatch-fan-types.js";
+interface SwatchFanHoverProps {
+    bordered: boolean;
+    className?: string | undefined;
+    /** Own the fan state via hover/focus (default) or drive it via `fanned`. */
+    fanOnHover: boolean;
+    /** Controlled fan state - use when a sibling element triggers the fan. */
+    fanned?: boolean | undefined;
+    items: SwatchFanItem[];
+    /** Accessible label applied as the fan's `aria-label`. */
+    label: string;
+    onFannedChange?: ((fanned: boolean) => void) | undefined;
+    renderImage: (props: SwatchFanImageProps) => ReactNode;
+    size: SwatchFanSize;
+    style?: CSSProperties | undefined;
+}
+/**
+ * Hover-fan engine - reproduces StackedSwatchFan's interactive splay
+ * (fan-on-hover, 3D pointer tilt, rAF settle). Settling uses separate
+ * open and close rates: faster splay-open, snappier snap-back.
+ * Only the first few items (matching the motion transforms) render.
+ */
+declare const SwatchFanHover: ({ bordered, className, fanOnHover, fanned, items, label, onFannedChange, renderImage, size, style, }: SwatchFanHoverProps) => import("react").JSX.Element;
+export { SwatchFanHover };

package/dist/compositions/swatch-fan/swatch-fan-hover.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Center } from "../../components/center.js";
+import { Flex } from "../../components/flex.js";
+import { SwatchFanTile } from "./swatch-fan-tile.js";
+import { SWATCH_FAN_CARD_WIDTH, SWATCH_FAN_STACK_HEIGHT, SWATCH_FAN_STACK_PADDING, SWATCH_FAN_MAX_TILES, SWATCH_FAN_SWATCH_RADIUS, SWATCH_FAN_SWATCH_SIZE, } from "./swatch-fan.motion.js";
+import { useSwatchFanEngine } from "./use-swatch-fan-engine.js";
+/**
+ * Hover-fan engine - reproduces StackedSwatchFan's interactive splay
+ * (fan-on-hover, 3D pointer tilt, rAF settle). Settling uses separate
+ * open and close rates: faster splay-open, snappier snap-back.
+ * Only the first few items (matching the motion transforms) render.
+ */
+const SwatchFanHover = ({ bordered, className, fanOnHover, fanned, items, label, onFannedChange, renderImage, size, style, }) => {
+    const visibleItems = items.slice(0, SWATCH_FAN_MAX_TILES);
+    const engine = useSwatchFanEngine({
+        fanOnHover,
+        fanned,
+        itemCount: visibleItems.length,
+        onFannedChange,
+    });
+    return (_jsx(Flex, { "aria-label": label, as: "span", className: cn(
+        // The fan animation is the hover/focus affordance, but reduced-motion
+        // users get no movement - a ring keeps focus visible for them (2.4.7).
+        focusRing(), "cursor-pointer", "[transform-style:preserve-3d]", !fanOnHover && "cursor-default", className), "data-component": "swatch-fan", "data-slot": "swatch-fan", "data-state": fanned === true ? "fanned" : "rest", inline: true, onPointerEnter: engine.handlePointerEnter, onPointerLeave: engine.handlePointerLeave, onPointerMove: engine.handlePointerMove, ref: (node) => {
+            engine.setCard(node);
+        }, 
+        // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- a labelled group of decorative children, which `<img>` cannot host
+        role: "img", style: style, children: _jsx(Center, { as: "span", className: "relative [perspective:600px]", "data-slot": "swatch-fan-stack", style: {
+                height: SWATCH_FAN_STACK_HEIGHT,
+                padding: SWATCH_FAN_STACK_PADDING,
+                width: SWATCH_FAN_CARD_WIDTH,
+            }, children: visibleItems.map((item, index) => (_jsx("span", { "aria-hidden": "true", className: "absolute", "data-slot": "swatch-fan-item", ref: (node) => {
+                    engine.setSwatch(index, node);
+                }, style: { zIndex: index + 1 }, children: _jsx(SwatchFanTile, { bordered: bordered, item: item, renderImage: renderImage, size: size, sizePx: SWATCH_FAN_SWATCH_SIZE, style: {
+                        borderRadius: SWATCH_FAN_SWATCH_RADIUS,
+                        height: SWATCH_FAN_SWATCH_SIZE,
+                        width: SWATCH_FAN_SWATCH_SIZE,
+                    } }) }, item.id))) }) }));
+};
+export { SwatchFanHover };

package/dist/compositions/swatch-fan/swatch-fan-root.d.ts

@@ -0,0 +1,91 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { SwatchFanImageProps, SwatchFanInteraction, SwatchFanItem, SwatchFanSize, SwatchFanVariant } from "./swatch-fan-types.js";
+export type { SwatchFanImageProps, SwatchFanInteraction, SwatchFanItem, SwatchFanSize, SwatchFanVariant, } from "./swatch-fan-types.js";
+interface SwatchFanProps {
+    /** Animate cards fanning out on mount (card engine - `breathe`/`none`). */
+    animateOnMount?: boolean;
+    /**
+     * Mount as a prop. `true` (default) = white 3px card mount;
+     * `false` = 1px hairline.
+     * @default true
+     */
+    bordered?: boolean;
+    /** Border width for each material card (card engine). @default 3 */
+    cardBorderWidth?: number;
+    /** Corner radius for each material card (card engine). @default 20 */
+    cardRadius?: number;
+    /** Shadow applied to each material card (card engine). */
+    cardShadow?: string;
+    className?: string;
+    /**
+     * Own the fan state via hover/focus (default) or drive it via `fanned`
+     * (hover-fan engine). @default true
+     */
+    fanOnHover?: boolean;
+    /** Controlled fan state (hover-fan engine) - e.g. a sibling CTA triggers it. */
+    fanned?: boolean;
+    /** Controlled hover/open state for parent-driven compositions (card engine). */
+    hovered?: boolean;
+    /** Extra side-card rotation while hovered (card engine). @default 1 */
+    hoverRotate?: number;
+    /** Extra outward shift for side cards while hovered (card engine). @default 3 */
+    hoverShift?: number;
+    /**
+     * Motion/geometry engine: `breathe` (decorative micro-nudge, default),
+     * `hover-fan` (StackedSwatchFan splay + pointer tilt), or `none` (static).
+     * @default "breathe"
+     */
+    interaction?: SwatchFanInteraction;
+    /**
+     * Tiles to fan. The card engine (`breathe`/`none`) maps the first three to
+     * left/center/right; the hover-fan engine stacks the first few (matching its
+     * motion transforms).
+     */
+    items: SwatchFanItem[];
+    /** Accessible label applied as the fan's `aria-label` (hover-fan engine). */
+    label?: string;
+    /** Delay before the mount fan-out starts, in seconds (card engine). */
+    mountDelay?: number;
+    /** Fires when the hover-fan opens or closes, with the next fanned state. */
+    onFannedChange?: (fanned: boolean) => void;
+    /** Override the horizontal overlap between adjacent cards, px (card engine). */
+    overlap?: number;
+    /** Escape hatch for framework-optimized images (e.g. next/image). */
+    renderImage?: (props: SwatchFanImageProps) => ReactNode;
+    /** Side-card rotation in degrees (card engine). @default 8 */
+    rotationDeg?: number;
+    /** Tile size - a SwatchTileSize scale step or pixel number. @default "xl" */
+    size?: SwatchFanSize;
+    /** Inline styles applied to the hover-fan root. */
+    style?: CSSProperties;
+    /** Override the square wrapper size for rotated side cards, px (card engine). */
+    wrapperSize?: number;
+    /** Layout variant (card engine): `stack` (default) or `spread`. */
+    variant?: SwatchFanVariant;
+}
+/**
+ * A fanned stack of {@link Swatch} tiles: a fixed three-card editorial fan or
+ * an interactive N-tile splay.
+ *
+ * Pass 3 `items` with `interaction="breathe"` for the editorial fan (Figma
+ * geometry, `variant` spread/stack, white 3px mount via `bordered`); pass N
+ * `items` with `interaction="hover-fan"` for the interactive splay-on-hover with
+ * pointer tilt. `bordered={false}` swaps the white mount for the 1px hairline
+ * tile.
+ *
+ * @example
+ * ```tsx
+ * // Editorial trio (Figma geometry, decorative breathe)
+ * <SwatchFan items={three} variant="spread" />
+ *
+ * // Interactive fan (hairline tiles, splay on hover)
+ * <SwatchFan bordered={false} interaction="hover-fan" items={materials} />
+ * ```
+ *
+ * @bestPractice Feed 3 items for the `breathe`/`none` card engine - its Figma geometry, z-order, and `variant` morphing are built around a fixed left/center/right trio; the hover-fan engine is the N-tile path.
+ * @bestPractice Needs `ReducedMotionProvider`; it already collapses the mount fan-out, hover nudge, and splay under reduced motion (snapping to the settled frame), so don't gate the interaction yourself.
+ * @bestPractice `bordered` is the mount-as-a-prop: `true` = white 3px card mount, `false` = 1px hairline - don't hand-roll either border in a wrapper.
+ * @category catalogue
+ */
+declare const SwatchFan: ({ animateOnMount, bordered, cardBorderWidth, cardRadius, cardShadow, className, fanOnHover, fanned, hovered, hoverRotate, hoverShift, interaction, items, label, mountDelay, onFannedChange, overlap, renderImage, rotationDeg, size, style, variant, wrapperSize, }: SwatchFanProps) => import("react").JSX.Element;
+export { SwatchFan, type SwatchFanProps };

package/dist/compositions/swatch-fan/swatch-fan-root.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { fanCardShadow } from "@instruments/materia-ui/tokens/shadows";
+import { HOVER_ROTATE, HOVER_SHIFT, ROTATION_DEG, SwatchFanCards, } from "./swatch-fan-cards.js";
+import { SwatchFanHover } from "./swatch-fan-hover.js";
+import { defaultRenderFanImage } from "./swatch-fan-types.js";
+/** Pick the hover-fan or card engine for already-defaulted props. */
+const SwatchFanEngineSwitch = ({ animateOnMount, bordered, cardBorderWidth, cardRadius, cardShadow, className, fanOnHover, fanned, hovered, hoverRotate, hoverShift, interaction, items, label, mountDelay, onFannedChange, overlap, renderImage, rotationDeg, size, style, variant, wrapperSize, }) => {
+    if (interaction === "hover-fan") {
+        return (_jsx(SwatchFanHover, { bordered: bordered, className: className, fanned: fanned, fanOnHover: fanOnHover, items: items, label: label, onFannedChange: onFannedChange, renderImage: renderImage, size: size, style: style }));
+    }
+    return (_jsx(SwatchFanCards, { animateOnMount: animateOnMount, bordered: bordered, breathe: interaction === "breathe", cardBorderWidth: cardBorderWidth, cardRadius: cardRadius, cardShadow: cardShadow, className: className, hovered: hovered, hoverRotate: hoverRotate, hoverShift: hoverShift, items: items, mountDelay: mountDelay, overlap: overlap, renderImage: renderImage, rotationDeg: rotationDeg, size: size, style: style, variant: variant, wrapperSize: wrapperSize }));
+};
+/**
+ * A fanned stack of {@link Swatch} tiles: a fixed three-card editorial fan or
+ * an interactive N-tile splay.
+ *
+ * Pass 3 `items` with `interaction="breathe"` for the editorial fan (Figma
+ * geometry, `variant` spread/stack, white 3px mount via `bordered`); pass N
+ * `items` with `interaction="hover-fan"` for the interactive splay-on-hover with
+ * pointer tilt. `bordered={false}` swaps the white mount for the 1px hairline
+ * tile.
+ *
+ * @example
+ * ```tsx
+ * // Editorial trio (Figma geometry, decorative breathe)
+ * <SwatchFan items={three} variant="spread" />
+ *
+ * // Interactive fan (hairline tiles, splay on hover)
+ * <SwatchFan bordered={false} interaction="hover-fan" items={materials} />
+ * ```
+ *
+ * @bestPractice Feed 3 items for the `breathe`/`none` card engine - its Figma geometry, z-order, and `variant` morphing are built around a fixed left/center/right trio; the hover-fan engine is the N-tile path.
+ * @bestPractice Needs `ReducedMotionProvider`; it already collapses the mount fan-out, hover nudge, and splay under reduced motion (snapping to the settled frame), so don't gate the interaction yourself.
+ * @bestPractice `bordered` is the mount-as-a-prop: `true` = white 3px card mount, `false` = 1px hairline - don't hand-roll either border in a wrapper.
+ * @category catalogue
+ */
+const SwatchFan = ({ animateOnMount = false, bordered = true, cardBorderWidth = 3, cardRadius = 20, cardShadow = fanCardShadow, className, fanOnHover = true, fanned, hovered, hoverRotate = HOVER_ROTATE, hoverShift = HOVER_SHIFT, interaction = "breathe", items, label = "Material swatches", mountDelay, onFannedChange, overlap, renderImage = defaultRenderFanImage, rotationDeg = ROTATION_DEG, size = "xl", style, variant = "stack", wrapperSize, }) => (_jsx(SwatchFanEngineSwitch, { animateOnMount: animateOnMount, bordered: bordered, cardBorderWidth: cardBorderWidth, cardRadius: cardRadius, cardShadow: cardShadow, className: className, fanOnHover: fanOnHover, fanned: fanned, hovered: hovered, hoverRotate: hoverRotate, hoverShift: hoverShift, interaction: interaction, items: items, label: label, mountDelay: mountDelay, onFannedChange: onFannedChange, overlap: overlap, renderImage: renderImage, rotationDeg: rotationDeg, size: size, style: style, variant: variant, wrapperSize: wrapperSize }));
+export { SwatchFan };

package/dist/compositions/swatch-fan/swatch-fan-tile.d.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { SwatchFanImageProps, SwatchFanItem, SwatchFanSize } from "./swatch-fan-types.js";
+interface SwatchFanTileProps {
+    /** White 3px card mount when `true`; 1px hairline (floating) when `false`. */
+    bordered: boolean;
+    className?: string | undefined;
+    item: SwatchFanItem;
+    renderImage: (props: SwatchFanImageProps) => ReactNode;
+    size: SwatchFanSize;
+    /** Border-box px of the tile - forwarded to the image `sizes` hint. */
+    sizePx: number;
+    style?: CSSProperties | undefined;
+}
+/**
+ * One `SwatchFan` tile, built on the unified `Swatch kind="tile"`.
+ *
+ * - `bordered` → `variant="card"` + `borderColor="white"` + `padded={false}`,
+ *   the white 3px card mount (the geometry engine pins
+ *   radius/border-width/shadow via `style`).
+ * - hairline → `variant="floating"`, reproducing the retired StackedSwatchFan tile
+ *   (shadow-md + inset white hairline) exactly.
+ */
+declare const SwatchFanTile: ({ bordered, className, item, renderImage, size, sizePx, style, }: SwatchFanTileProps) => import("react").JSX.Element;
+export { SwatchFanTile };

package/dist/compositions/swatch-fan/swatch-fan-tile.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Swatch } from "../../components/swatch/swatch-root.js";
+import { hasText } from "../../utils/type-guards.js";
+/**
+ * One `SwatchFan` tile, built on the unified `Swatch kind="tile"`.
+ *
+ * - `bordered` → `variant="card"` + `borderColor="white"` + `padded={false}`,
+ *   the white 3px card mount (the geometry engine pins
+ *   radius/border-width/shadow via `style`).
+ * - hairline → `variant="floating"`, reproducing the retired StackedSwatchFan tile
+ *   (shadow-md + inset white hairline) exactly.
+ */
+const SwatchFanTile = ({ bordered, className, item, renderImage, size, sizePx, style, }) => {
+    const RenderImage = renderImage;
+    // Render as an element (not an inline call) so React preserves the image's
+    // identity/state across renders (no-render-in-render).
+    const image = hasText(item.src) ? (_jsx(RenderImage, { alt: item.alt ?? "", className: "object-cover", draggable: false, fill: true, sizes: `${sizePx}px`, src: item.src })) : null;
+    // A background gradient/image string becomes a fill child so bordered card
+    // tiles (which don't paint `background`) still show it.
+    const fillChild = image ??
+        (hasText(item.background) ? (_jsx("span", { "aria-hidden": true, className: "absolute inset-0", style: { background: item.background } })) : null);
+    if (bordered) {
+        return (_jsx(Swatch, { alt: item.alt ?? "", borderColor: "white", className: className, color: fillChild ? undefined : item.color, padded: false, kind: "tile", size: size, style: style, variant: "card", children: fillChild }));
+    }
+    // Hairline - reproduces the retired StackedSwatchFan floating tile pixel-exactly.
+    return (_jsx(Swatch, { alt: item.alt ?? "", background: item.background, className: className, color: item.color, ...(item.isLight === undefined ? {} : { light: item.isLight }), kind: "tile", size: size, style: style, variant: "floating", children: image }));
+};
+export { SwatchFanTile };

package/dist/compositions/swatch-fan/swatch-fan-types.d.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from "react";
+import type { SwatchTileSize } from "../../tokens/swatch.js";
+/**
+ * A single tile in a {@link SwatchFan}. Provide exactly one fill -
+ * `src` (image), `background` (CSS gradient/image string), or `color` (solid).
+ */
+export interface SwatchFanItem {
+    /** Alt text for image fills. */
+    alt?: string;
+    /** CSS `background` value (gradient or `url(...)` image). */
+    background?: string;
+    /** Solid colour fill (hex/rgb/hsl). */
+    color?: string;
+    /** Stable key for the tile. */
+    id: string;
+    /**
+     * Contrast override for overlaid content - `isLightColor` only reads solid
+     * colours, so gradient/image fills need it.
+     */
+    isLight?: boolean;
+    /** Image source URL. Takes precedence over `background`/`color`. */
+    src?: string;
+}
+/** Props handed to the `renderImage` escape hatch. */
+export interface SwatchFanImageProps {
+    alt: string;
+    className: string;
+    draggable: boolean;
+    fill?: boolean;
+    height?: number;
+    sizes?: string;
+    src: string;
+    width?: number;
+}
+/** Layout of the 3-item card engine. */
+export type SwatchFanVariant = "spread" | "stack";
+/**
+ * Motion/geometry engine selector.
+ * - `breathe` - decorative hover micro-nudge + optional mount fan-out
+ *   (3-item fixed geometry). Default.
+ * - `hover-fan` - StackedSwatchFan's interactive splay-open + pointer tilt
+ *   (N-item stacked geometry).
+ * - `none` - static card-engine geometry, no motion.
+ */
+export type SwatchFanInteraction = "breathe" | "hover-fan" | "none";
+/** Tile size - a {@link SwatchTileSize} scale step or an exact pixel number. */
+export type SwatchFanSize = SwatchTileSize | number;
+/** Default renderImage - a plain `<img>`. */
+export declare const defaultRenderFanImage: ({ src, alt, className, draggable, width, height, fill, }: SwatchFanImageProps) => ReactNode;

package/dist/compositions/swatch-fan/swatch-fan-types.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "../../utils/cn.js";
+/** Default renderImage - a plain `<img>`. */
+export const defaultRenderFanImage = ({ src, alt, className, draggable, width, height, fill, }) => (_jsx("img", { alt: alt, className: cn(fill === true ? "absolute inset-0 size-full" : "", className), draggable: draggable, height: height ?? 1, src: src, width: width ?? 1 }));

package/dist/compositions/swatch-fan/swatch-fan.motion.d.ts

@@ -0,0 +1,6 @@
+export { getStackedSwatchFanFrame as getSwatchFanFrame, getStackedSwatchFanTarget as getSwatchFanTarget, STACKED_SWATCH_FAN_CARD_WIDTH as SWATCH_FAN_CARD_WIDTH, STACKED_SWATCH_FAN_REST_PROGRESS as SWATCH_FAN_REST_PROGRESS, STACKED_SWATCH_FAN_SETTLE_THRESHOLD as SWATCH_FAN_SETTLE_THRESHOLD, STACKED_SWATCH_FAN_STACK_HEIGHT as SWATCH_FAN_STACK_HEIGHT, STACKED_SWATCH_FAN_STACK_PADDING as SWATCH_FAN_STACK_PADDING, STACKED_SWATCH_FAN_SWATCH_RADIUS as SWATCH_FAN_SWATCH_RADIUS, STACKED_SWATCH_FAN_SWATCH_SIZE as SWATCH_FAN_SWATCH_SIZE, SWATCH_FAN_MAX_TILES, } from "../../components/swatch/stacked-swatch-fan.motion.js";
+declare const SWATCH_FAN_OPEN_SETTLE: number;
+declare const SWATCH_FAN_CLOSE_SETTLE: number;
+/** Pick the settle rate for the current direction of travel. */
+declare const getSwatchFanSettle: (opening: boolean) => number;
+export { getSwatchFanSettle, SWATCH_FAN_OPEN_SETTLE, SWATCH_FAN_CLOSE_SETTLE };

package/dist/compositions/swatch-fan/swatch-fan.motion.js

@@ -0,0 +1,21 @@
+export { getStackedSwatchFanFrame as getSwatchFanFrame, getStackedSwatchFanTarget as getSwatchFanTarget, STACKED_SWATCH_FAN_CARD_WIDTH as SWATCH_FAN_CARD_WIDTH, STACKED_SWATCH_FAN_REST_PROGRESS as SWATCH_FAN_REST_PROGRESS, STACKED_SWATCH_FAN_SETTLE_THRESHOLD as SWATCH_FAN_SETTLE_THRESHOLD, STACKED_SWATCH_FAN_STACK_HEIGHT as SWATCH_FAN_STACK_HEIGHT, STACKED_SWATCH_FAN_STACK_PADDING as SWATCH_FAN_STACK_PADDING, STACKED_SWATCH_FAN_SWATCH_RADIUS as SWATCH_FAN_SWATCH_RADIUS, STACKED_SWATCH_FAN_SWATCH_SIZE as SWATCH_FAN_SWATCH_SIZE, SWATCH_FAN_MAX_TILES, } from "../../components/swatch/stacked-swatch-fan.motion.js";
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+/**
+ * Convert a target open/close duration (ms) into the per-frame lerp fraction the
+ * rAF settle loop uses. Same shape as the retired StackedSwatchFan constant
+ * (`(0.21 * 320) / 300 ≈ 0.224` at 300ms), so a duration of 300ms reproduces the
+ * old single-speed feel exactly; shorter durations settle faster.
+ */
+const settleFromDuration = (ms) => clamp((0.21 * 320) / ms, 0.015, 0.6);
+/**
+ * The hover-fan settles at separate open and close rates: it opens faster
+ * (220ms, on the `out` curve) and snaps closed faster (160ms). These are this
+ * component's own tuned values, not shared motion tokens.
+ */
+const SWATCH_FAN_OPEN_MS = 220;
+const SWATCH_FAN_EXIT_MS = 160;
+const SWATCH_FAN_OPEN_SETTLE = settleFromDuration(SWATCH_FAN_OPEN_MS);
+const SWATCH_FAN_CLOSE_SETTLE = settleFromDuration(SWATCH_FAN_EXIT_MS);
+/** Pick the settle rate for the current direction of travel. */
+const getSwatchFanSettle = (opening) => opening ? SWATCH_FAN_OPEN_SETTLE : SWATCH_FAN_CLOSE_SETTLE;
+export { getSwatchFanSettle, SWATCH_FAN_OPEN_SETTLE, SWATCH_FAN_CLOSE_SETTLE };

package/dist/compositions/swatch-fan/use-swatch-fan-engine.d.ts

@@ -0,0 +1,19 @@
+interface UseSwatchFanEngineOptions {
+    fanOnHover: boolean;
+    fanned: boolean | undefined;
+    itemCount: number;
+    onFannedChange: ((fanned: boolean) => void) | undefined;
+}
+/** Create the hover-fan engine and keep it in step with the component's props. */
+export declare const useSwatchFanEngine: ({ fanOnHover, fanned, itemCount, onFannedChange, }: UseSwatchFanEngineOptions) => {
+    applyCurrent: () => void;
+    configure: (next: import("./swatch-fan-engine.js").SwatchFanEngineConfig) => void;
+    handlePointerEnter: () => void;
+    handlePointerLeave: () => void;
+    handlePointerMove: (event: import("react").PointerEvent<HTMLSpanElement>) => void;
+    setCard: (node: HTMLSpanElement | null) => void;
+    setSwatch: (index: number, node: HTMLSpanElement | null) => void;
+    syncFanned: (nextFanned: boolean) => void;
+    stop: () => void;
+};
+export {};

package/dist/compositions/swatch-fan/use-swatch-fan-engine.js

@@ -0,0 +1,20 @@
+"use client";
+import { useReducedMotion } from "motion/react";
+import { useEffect, useMemo } from "react";
+import { createSwatchFanEngine } from "./swatch-fan-engine.js";
+/** Create the hover-fan engine and keep it in step with the component's props. */
+export const useSwatchFanEngine = ({ fanOnHover, fanned, itemCount, onFannedChange, }) => {
+    const engine = useMemo(() => createSwatchFanEngine(), []);
+    const reducedMotion = useReducedMotion() === true;
+    useEffect(() => {
+        engine.configure({ fanOnHover, itemCount, onFannedChange, reducedMotion });
+    }, [engine, fanOnHover, itemCount, onFannedChange, reducedMotion]);
+    useEffect(() => {
+        engine.syncFanned(Boolean(fanned));
+    }, [engine, fanned]);
+    useEffect(() => {
+        engine.applyCurrent();
+        return engine.stop;
+    }, [engine]);
+    return engine;
+};

package/dist/compositions/swatch-fan.d.ts

@@ -0,0 +1 @@
+export { SwatchFan, type SwatchFanImageProps, type SwatchFanInteraction, type SwatchFanItem, type SwatchFanProps, type SwatchFanSize, type SwatchFanVariant, } from "./swatch-fan/swatch-fan-root.js";

package/dist/compositions/swatch-fan.js

@@ -0,0 +1 @@
+export { SwatchFan, } from "./swatch-fan/swatch-fan-root.js";

package/dist/compositions/tag-selector/tag-selector-color-swatches.d.ts

@@ -0,0 +1,10 @@
+import type { TagColor } from "../tag-selector/tag-selector-context.js";
+/**
+ * A row of colour dots for picking a tag colour. Pressing the selected colour
+ * again clears it. Shared by the inline tag editor and the "Create" option.
+ */
+export declare const TagSelectorColorSwatches: ({ onSelect, palette, selected, }: {
+    onSelect: (color: TagColor | undefined) => void;
+    palette: TagColor[];
+    selected: TagColor | undefined;
+}) => import("react").JSX.Element;

package/dist/compositions/tag-selector/tag-selector-color-swatches.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Button } from "../../components/button.js";
+import { Dot } from "../../components/dot.js";
+import { Flex } from "../../components/flex.js";
+import { tagColorToDotTone } from "../tag-selector/tag-selector-context.js";
+/**
+ * A row of colour dots for picking a tag colour. Pressing the selected colour
+ * again clears it. Shared by the inline tag editor and the "Create" option.
+ */
+export const TagSelectorColorSwatches = ({ onSelect, palette, selected, }) => (_jsx(Flex, { align: "center", className: "-ml-2", children: palette.map((color) => (_jsx(Button, { "aria-label": `${color} colour`, "aria-pressed": selected === color, className: cn("aspect-square px-0", selected === color && "ring-foreground ring-2 ring-inset"), emphasis: "ghost", onClick: () => {
+            onSelect(selected === color ? undefined : color);
+        }, size: "2xs", tone: "neutral", type: "button", children: _jsx(Dot, { size: "xs", tone: tagColorToDotTone(color) }) }, color))) }));

package/dist/compositions/tag-selector/tag-selector-content.d.ts

@@ -0,0 +1,12 @@
+import type * as React from "react";
+interface TagSelectorContentProps {
+    children: React.ReactNode;
+    className?: string;
+}
+/**
+ * TagSelectorContent - Popover content wrapper for the tag selector dropdown.
+ * When `coverTrigger` is enabled, the popover overlaps the trigger so the
+ * selected tags aren't visually doubled.
+ */
+export declare const TagSelectorContent: ({ children, className, }: TagSelectorContentProps) => React.JSX.Element;
+export {};

package/dist/compositions/tag-selector/tag-selector-content.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { PopoverContent } from "../../components/popover.js";
+import { useTagSelectorContext } from "../tag-selector/tag-selector-context.js";
+/**
+ * TagSelectorContent - Popover content wrapper for the tag selector dropdown.
+ * When `coverTrigger` is enabled, the popover overlaps the trigger so the
+ * selected tags aren't visually doubled.
+ */
+export const TagSelectorContent = ({ children, className, }) => {
+    const { coverTrigger } = useTagSelectorContext();
+    return (_jsx(PopoverContent, { align: "start", className: cn("w-(--anchor-width) min-w-60 rounded-3xl p-0", className), "data-component": "tag-selector-content", "data-slot": "tag-selector-content", sideOffset: coverTrigger ? 0 : 4, style: coverTrigger
+            ? {
+                marginTop: "calc(-1 * var(--anchor-height))",
+            }
+            : undefined, children: children }));
+};