@instruments/materia-ui 0.1.0

package/dist/components/swatch/swatch-tile-floating.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from "react";
+import type { SwatchTileSizeProp } from "./swatch-tile-types.js";
+/**
+ * Floating tile (shadow-md + inset white hairline + darkening overlay, `rounded-sm` inner
+ * clip). Only `StackedSwatchFan` uses it; kept pixel-identical to its baseline.
+ */
+declare const SwatchFloatingTile: ({ background, color, children, light, size, selected, unavailableClassName, className, style, }: {
+    background: string | undefined;
+    color: string | undefined;
+    children: ReactNode;
+    light: boolean | undefined;
+    size: SwatchTileSizeProp;
+    selected?: boolean | undefined;
+    unavailableClassName?: string | undefined;
+    className: string | undefined;
+    style: React.CSSProperties | undefined;
+}) => import("react").JSX.Element;
+export { SwatchFloatingTile };

package/dist/components/swatch/swatch-tile-floating.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { swatchTileSizeMap } from "../../tokens/swatch.js";
+import { cn } from "../../utils/cn.js";
+import { isNumber } from "../../utils/type-guards.js";
+import { Center } from "../center.js";
+import { composeSwatchShadow, deriveSwatchVisuals, SwatchLayers, TILE_BORDER_RADIUS, } from "./swatch-chip.js";
+import { isTileSizeScale } from "./swatch-tile-styles.js";
+/**
+ * Floating tile (shadow-md + inset white hairline + darkening overlay, `rounded-sm` inner
+ * clip). Only `StackedSwatchFan` uses it; kept pixel-identical to its baseline.
+ */
+const SwatchFloatingTile = ({ background, color, children, light, size, selected = false, unavailableClassName, className, style, }) => {
+    // Base dimension class. `StackedSwatchFan` (the only consumer) always pins
+    // exact px via inline `style`, which wins over this class - so the scale used
+    // here is visually inert and any tile-scale key is safe/pixel-identical.
+    const sizeClass = isTileSizeScale(size) ? swatchTileSizeMap[size] : undefined;
+    const { fillBackground, hasChildren, isLightComputed } = deriveSwatchVisuals({
+        background,
+        children,
+        color,
+        colors: undefined,
+        isLightOverride: light,
+    });
+    const tileStyle = {};
+    if (isNumber(size)) {
+        tileStyle.height = size;
+        tileStyle.width = size;
+    }
+    Object.assign(tileStyle, style);
+    tileStyle.boxShadow = composeSwatchShadow(selected, true, false, true);
+    return (_jsx(Center, { as: "span", className: cn("relative", TILE_BORDER_RADIUS, sizeClass, isLightComputed ? "text-gray-900" : "text-white", "duration-quick transition-shadow", unavailableClassName, size === "fluid" && "w-full", className), "data-selected": selected, "data-kind": "tile", "data-slot": "swatch", inline: true, style: tileStyle, children: _jsx(SwatchLayers, { fillBackground: fillBackground, hasChildren: hasChildren, icon: undefined, radiusClass: TILE_BORDER_RADIUS, selected: false, size: isTileSizeScale(size) ? size : "base", unavailable: false, children: children }) }));
+};
+export { SwatchFloatingTile };

package/dist/components/swatch/swatch-tile-styles.d.ts

@@ -0,0 +1,39 @@
+import type { SwatchTileSize } from "../../tokens/swatch.js";
+import type { SwatchTileSizeProp, SwatchTileVariant, TileSwatchProps } from "./swatch-tile-types.js";
+type SizeTier = "tiny" | "small" | "standard";
+declare const isTileSizeScale: (size: SwatchTileSizeProp) => size is SwatchTileSize;
+declare const ringShadowMap: Record<SizeTier, string>;
+/** Radius of the padded ring and frame ring, concentric with the border. */
+declare const getInnerRingRadius: ({ compact, isCard, tier, }: {
+    compact: boolean;
+    isCard: boolean;
+    tier: SizeTier;
+}) => string;
+interface ResolvedTileState {
+    compact: boolean;
+    disabled: boolean;
+    dotted: boolean;
+    framed: boolean;
+    hasColor: boolean;
+    hasImage: boolean;
+    isCard: boolean;
+    isPadded: boolean;
+    muted: boolean;
+    selected: boolean;
+    size: SwatchTileSizeProp;
+    tier: SizeTier;
+    variant: SwatchTileVariant;
+}
+type TileStateInput = Pick<TileSwatchProps, "children" | "color" | "compactRadius" | "disabled" | "dotted" | "framed" | "muted" | "padded" | "selected" | "size" | "src" | "variant">;
+/** Resolve content precedence (`children` > `src` > `color`) and the size tier. */
+declare const resolveTileState: (input: TileStateInput) => ResolvedTileState;
+declare const buildTileClasses: (state: ResolvedTileState, { borderColor, className, }: {
+    borderColor: string | undefined;
+    className: string | undefined;
+}) => string;
+declare const buildTileStyle: (state: ResolvedTileState, { borderColor, color, style, }: {
+    borderColor: string | undefined;
+    color: string | undefined;
+    style: React.CSSProperties | undefined;
+}) => React.CSSProperties;
+export { buildTileClasses, buildTileStyle, getInnerRingRadius, isTileSizeScale, resolveTileState, ringShadowMap, type ResolvedTileState, type SizeTier, };

package/dist/components/swatch/swatch-tile-styles.js

@@ -0,0 +1,132 @@
+import { swatchTileSizeMap } from "../../tokens/swatch.js";
+import { cn } from "../../utils/cn.js";
+import { isNumber, isString } from "../../utils/type-guards.js";
+import { hasValue } from "./swatch-chip.js";
+const isTileSizeScale = (size) => isString(size) && size !== "fluid";
+const getSizeTier = (size) => {
+    if (size === "fluid") {
+        return "standard";
+    }
+    if (isNumber(size)) {
+        return size <= 56 ? "small" : "standard";
+    }
+    if (size === "3xs" || size === "2xs") {
+        return "tiny";
+    }
+    if (size === "xs" || size === "sm") {
+        return "small";
+    }
+    return "standard";
+};
+const containerRadiusMap = {
+    small: { compact: "rounded-lg", normal: "rounded-xl" },
+    standard: { compact: "rounded-xl", normal: "rounded-2xl" },
+    tiny: { compact: "rounded-sm", normal: "rounded-md" },
+};
+const containerBorderMap = {
+    small: "border",
+    standard: "border-2",
+    tiny: "border",
+};
+// The white padding ring is a solid inset box-shadow drawn by an overlay that
+// paints on top of the image. It follows the image's (inner) radius, so the ring
+// is always uniform - no inner element or padding required. Thickness mirrors the
+// old padding per tier.
+const ringShadowMap = {
+    small: "shadow-[inset_0_0_0_2px_var(--color-card)]",
+    standard: "shadow-[inset_0_0_0_3px_var(--color-card)]",
+    tiny: "shadow-[inset_0_0_0_1px_var(--color-card)]",
+};
+// Radius of the image + white ring, concentric with the border (outer radius −
+// border width). The image is clipped to this inner radius by `overflow-hidden`,
+// so the ring must match it; using the container's outer radius would leave the
+// image corner poking past the ring at the diagonal. WebKit also needs the image
+// rounded directly (it clips in-flow replaced elements inconsistently), so the
+// same value is applied to the `<img>` via a descendant variant. Both maps stay
+// literal so Tailwind's scanner sees every class.
+const innerRingRadiusMap = {
+    small: { compact: "rounded-[7px]", normal: "rounded-[11px]" },
+    standard: { compact: "rounded-[10px]", normal: "rounded-[14px]" },
+    tiny: { compact: "rounded-sm", normal: "rounded-md" },
+};
+const innerImgRadiusMap = {
+    small: { compact: "[&_img]:rounded-[7px]", normal: "[&_img]:rounded-[11px]" },
+    standard: {
+        compact: "[&_img]:rounded-[10px]",
+        normal: "[&_img]:rounded-[14px]",
+    },
+    tiny: { compact: "[&_img]:rounded-sm", normal: "[&_img]:rounded-md" },
+};
+/**
+ * Pick a tiered radius: a tile is always square-cornered (circles are the chip
+ * kinds' job), bare tiles use `bare`, card tiles read the tier's compact or
+ * normal step from `map`.
+ */
+const pickRadius = (map, bare, tier, isCard, compactRadius) => {
+    if (!isCard) {
+        return bare;
+    }
+    return map[tier][compactRadius ? "compact" : "normal"];
+};
+/** Radius of the padded ring and frame ring, concentric with the border. */
+const getInnerRingRadius = ({ compact, isCard, tier, }) => pickRadius(innerRingRadiusMap, "rounded-md", tier, isCard, compact);
+/** Apply the tile's boolean, size and variant defaults. */
+const withTileDefaults = (input) => ({
+    compact: input.compactRadius ?? false,
+    disabled: input.disabled ?? false,
+    dotted: input.dotted ?? false,
+    framed: input.framed ?? false,
+    muted: input.muted ?? false,
+    selected: input.selected ?? false,
+    size: input.size ?? "base",
+    variant: input.variant ?? "card",
+});
+/** Resolve content precedence (`children` > `src` > `color`) and the size tier. */
+const resolveTileState = (input) => {
+    const defaults = withTileDefaults(input);
+    const isCard = defaults.variant === "card";
+    const hasChildren = input.children !== undefined && input.children !== null;
+    const hasSrc = hasValue(input.src);
+    return {
+        ...defaults,
+        hasColor: !hasChildren && !hasSrc && hasValue(input.color),
+        hasImage: !hasChildren && hasSrc,
+        isCard,
+        isPadded: input.padded ?? isCard,
+        tier: getSizeTier(defaults.size),
+    };
+};
+const getBorderClasses = (isCard, borderColor, selected) => {
+    if (!isCard || hasValue(borderColor)) {
+        return "";
+    }
+    return selected ? "border-primary" : "border-border/50 hover:border-border";
+};
+const buildTileClasses = (state, { borderColor, className, }) => {
+    const { tier, isCard, compact, dotted, selected, muted, disabled, size } = state;
+    return cn(
+    // Center content so icon/placeholder children sit in the middle; full-bleed
+    // `size-full` images and the absolute ring overlay are unaffected.
+    "relative flex aspect-square shrink-0 items-center justify-center overflow-hidden", pickRadius(containerRadiusMap, "rounded-md", tier, isCard, compact), 
+    // Round the image element itself (not just clip via `overflow-hidden`):
+    // WebKit clips in-flow replaced elements inconsistently, leaving square
+    // corners that poke past the radius.
+    pickRadius(innerImgRadiusMap, "[&_img]:rounded-md", tier, isCard, compact), isCard && (dotted ? "border-2" : containerBorderMap[tier]), isCard && "shadow-xs", !isCard && "bg-muted", isCard && "bg-card", isCard && (dotted ? "border-dotted" : "border-solid"), getBorderClasses(isCard, borderColor, selected), muted && "opacity-50 hover:opacity-100", isCard && "transition-border-shadow-opacity duration-quick ease-out", disabled && "cursor-not-allowed opacity-50", size === "fluid" && "w-full", isTileSizeScale(size) && swatchTileSizeMap[size], className);
+};
+const buildTileStyle = (state, { borderColor, color, style, }) => {
+    const { size } = state;
+    const tileStyle = {};
+    if (isNumber(size)) {
+        tileStyle.height = size;
+        tileStyle.width = size;
+    }
+    if (state.hasColor) {
+        tileStyle.backgroundColor = color;
+    }
+    Object.assign(tileStyle, style);
+    if (hasValue(borderColor) && state.isCard) {
+        tileStyle.borderColor = borderColor;
+    }
+    return tileStyle;
+};
+export { buildTileClasses, buildTileStyle, getInnerRingRadius, isTileSizeScale, resolveTileState, ringShadowMap, };

package/dist/components/swatch/swatch-tile-types.d.ts

@@ -0,0 +1,86 @@
+import type { ReactNode, Ref } from "react";
+import type { SwatchTileSize } from "../../tokens/swatch.js";
+/**
+ * Tile size can be a {@link SwatchTileSize} scale value, a pixel number, or
+ * "fluid".
+ * - SwatchTileSize: predefined scale ("3xs"…"2xl", 16–112px)
+ * - number: exact pixel value via inline style
+ * - "fluid": fills the parent width while preserving a square aspect ratio
+ */
+type SwatchTileSizeProp = SwatchTileSize | number | "fluid";
+/**
+ * Tile appearance:
+ * - "card": border, shadow, and optional padding ring (selectable items)
+ * - "bare": simple container with muted background (dense data grids)
+ * - "floating": floating shadow-md + inset white hairline over the fill, with the
+ *   darkening overlay - the floating tile `StackedSwatchFan` uses. Used
+ *   only by `StackedSwatchFan`; not part of the card/bare framing model.
+ */
+type SwatchTileVariant = "card" | "bare" | "floating";
+interface TileSwatchProps {
+    /** Alt text for the image (used when `src` is provided) */
+    alt?: string | undefined;
+    /** Border colour override (e.g., "white" for decorative use) */
+    borderColor?: string | undefined;
+    /** Custom content - takes precedence over `src` and `color` */
+    children?: ReactNode | undefined;
+    /** Additional className for the outer container */
+    className?: string | undefined;
+    /** Background colour (solid fill, no image) */
+    color?: string | undefined;
+    /** Background CSS value (gradient/image) - only the legacy `floating` variant paints it */
+    background?: string | undefined;
+    /** Use a slightly lighter corner radius profile (useful for dense selectors) */
+    compactRadius?: boolean | undefined;
+    /** Disabled state - blocks interaction, reduced opacity */
+    disabled?: boolean | undefined;
+    /** Dotted border style (e.g., for pending/preview states) */
+    dotted?: boolean | undefined;
+    /**
+     * Show a subtle inset hairline ring (`ring-1 ring-inset ring-black/5`) that
+     * frames the image/color - a faint depth-defining edge, independent of
+     * `padded`'s thicker card-colored separator ring. Follows the same corner
+     * radius as the container.
+     * @default false
+     */
+    framed?: boolean | undefined;
+    /**
+     * Contrast override for overlaid content on the legacy `floating` variant -
+     * `isLightColor` only reads solid colours, so gradient/image fills need it.
+     */
+    light?: boolean | undefined;
+    /** Muted state - reduced opacity, restores on hover */
+    muted?: boolean | undefined;
+    /**
+     * Show the white inset ring - card style with a solid inner border that frames
+     * the image/color. Drawn as an inset box-shadow overlay (follows the container
+     * radius, so it is always uniform). When false: image fills edge-to-edge.
+     * @default true (for card variant), false (for bare variant)
+     */
+    padded?: boolean | undefined;
+    /** Prioritise image loading for above-the-fold or interactive CTAs */
+    priority?: boolean | undefined;
+    /** Forwarded ref to the root element. */
+    ref?: Ref<HTMLDivElement> | undefined;
+    /** Selection state - shows primary border + elevated shadow (card variant only) */
+    selected?: boolean | undefined;
+    /**
+     * Tile geometry discriminant. Always "tile" - chip kinds live on the
+     * `ChipSwatchProps` union member.
+     */
+    kind: "tile";
+    /** Size - SwatchTileSize scale ("xs", "base", "2xl"), pixel number, or "fluid" */
+    size?: SwatchTileSizeProp | undefined;
+    /** Responsive size hint forwarded to the underlying `<img>` element */
+    sizes?: string | undefined;
+    /** Image source URL - renders a native `<img>` with `object-cover` */
+    src?: string | undefined;
+    /** Inline styles (useful for motion animations) */
+    style?: React.CSSProperties | undefined;
+    /**
+     * Visual style variant.
+     * @default "card"
+     */
+    variant?: SwatchTileVariant | undefined;
+}
+export type { SwatchTileSizeProp, SwatchTileVariant, TileSwatchProps };

package/dist/components/swatch/swatch-tile-types.js

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

package/dist/components/swatch/swatch-tile.d.ts

@@ -0,0 +1,27 @@
+import type { TileSwatchProps } from "./swatch-tile-types.js";
+/**
+ * Standalone inset hairline ring (`ring-1 ring-inset ring-black/5`) that frames
+ * an image/color container - a faint depth-defining edge. `Swatch kind="tile"`
+ * renders this internally via the `framed` prop; it is also exported directly
+ * for hand-rolled image containers elsewhere that need the exact same treatment
+ * without adopting the full tile container (e.g. bespoke shadow/sizing).
+ *
+ * @example
+ * ```tsx
+ * <div className="relative h-50 w-50 overflow-hidden rounded-xl">
+ *   <SwatchFrameRing radius="rounded-xl" />
+ *   <Image alt="" fill src={url} />
+ * </div>
+ * ```
+ */
+declare const SwatchFrameRing: ({ radius }: {
+    radius: string;
+}) => import("react").JSX.Element;
+/**
+ * Tile renderer for `Swatch` - the square material/image tile. `card`/`bare`
+ * use tiered radius, border, ring and shadow, `children` > `src` > `color`
+ * precedence, and no darkening overlay; `floating`
+ * reproduces the legacy floating Swatch tile for `StackedSwatchFan`.
+ */
+declare const SwatchTile: (props: TileSwatchProps) => import("react").JSX.Element;
+export { SwatchFrameRing, SwatchTile };

package/dist/components/swatch/swatch-tile.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../../utils/cn.js";
+import { isNumber } from "../../utils/type-guards.js";
+import { SwatchFloatingTile } from "./swatch-tile-floating.js";
+import { buildTileClasses, buildTileStyle, getInnerRingRadius, resolveTileState, ringShadowMap, } from "./swatch-tile-styles.js";
+/**
+ * Standalone inset hairline ring (`ring-1 ring-inset ring-black/5`) that frames
+ * an image/color container - a faint depth-defining edge. `Swatch kind="tile"`
+ * renders this internally via the `framed` prop; it is also exported directly
+ * for hand-rolled image containers elsewhere that need the exact same treatment
+ * without adopting the full tile container (e.g. bespoke shadow/sizing).
+ *
+ * @example
+ * ```tsx
+ * <div className="relative h-50 w-50 overflow-hidden rounded-xl">
+ *   <SwatchFrameRing radius="rounded-xl" />
+ *   <Image alt="" fill src={url} />
+ * </div>
+ * ```
+ */
+const SwatchFrameRing = ({ radius }) => (_jsx("span", { "aria-hidden": "true", className: cn("pointer-events-none absolute inset-0 ring-1 ring-black/5 ring-inset", radius) }));
+/**
+ * Card/bare renderer: the tiered radius/border/ring/shadow tile.
+ */
+const SwatchBoxTile = ({ alt = "", borderColor, children, className, color, priority = false, ref, sizes, src, style, ...flags }) => {
+    const state = resolveTileState({ children, color, src, ...flags });
+    const { size } = state;
+    const innerRadius = getInnerRingRadius(state);
+    return (_jsxs("div", { className: buildTileClasses(state, { borderColor, className }), "data-component": "swatch", "data-muted": state.muted, "data-selected": state.selected, "data-kind": "tile", "data-variant": state.variant, ref: ref, style: buildTileStyle(state, { borderColor, color, style }), children: [children, state.hasImage && (_jsx("img", { alt: alt, className: "size-full object-cover", fetchPriority: priority ? "high" : "auto", height: isNumber(size) ? size : 200, loading: priority ? "eager" : "lazy", sizes: sizes, src: src, width: isNumber(size) ? size : 200 })), state.isPadded && state.isCard && (_jsx("span", { "aria-hidden": "true", className: cn("pointer-events-none absolute inset-0", innerRadius, ringShadowMap[state.tier]) })), state.framed && _jsx(SwatchFrameRing, { radius: innerRadius })] }));
+};
+/**
+ * Tile renderer for `Swatch` - the square material/image tile. `card`/`bare`
+ * use tiered radius, border, ring and shadow, `children` > `src` > `color`
+ * precedence, and no darkening overlay; `floating`
+ * reproduces the legacy floating Swatch tile for `StackedSwatchFan`.
+ */
+const SwatchTile = (props) => {
+    if (props.variant === "floating") {
+        return (_jsx(SwatchFloatingTile, { background: props.background, className: props.className, color: props.color, light: props.light, selected: props.selected, size: props.size ?? "base", style: props.style, unavailableClassName: props.disabled === true || props.muted === true
+                ? "opacity-50"
+                : undefined, children: props.children }));
+    }
+    return _jsx(SwatchBoxTile, { ...props });
+};
+export { SwatchFrameRing, SwatchTile };

package/dist/components/swatch/use-stacked-swatch-fan.d.ts

@@ -0,0 +1,27 @@
+import type { FocusEvent, PointerEvent } from "react";
+interface UseStackedSwatchFanOptions {
+    fanOnHover: boolean;
+    fanned: boolean | undefined;
+    onBlur: ((event: FocusEvent<HTMLSpanElement>) => void) | undefined;
+    onFannedChange: ((fanned: boolean) => void) | undefined;
+    onFocus: ((event: FocusEvent<HTMLSpanElement>) => void) | undefined;
+    onPointerEnter: ((event: PointerEvent<HTMLSpanElement>) => void) | undefined;
+    onPointerLeave: ((event: PointerEvent<HTMLSpanElement>) => void) | undefined;
+    onPointerMove: ((event: PointerEvent<HTMLSpanElement>) => void) | undefined;
+    tileCount: number;
+}
+/**
+ * Hover/focus wiring for {@link StackedSwatchFan}: returns the refs to attach
+ * and the event handlers, each of which forwards to the consumer's own
+ * handler before driving the fan.
+ */
+declare const useStackedSwatchFan: ({ fanOnHover, fanned, onBlur, onFannedChange, onFocus, onPointerEnter, onPointerLeave, onPointerMove, tileCount, }: UseStackedSwatchFanOptions) => {
+    cardRef: import("react").RefObject<HTMLSpanElement | null>;
+    handleBlur: (event: FocusEvent<HTMLSpanElement>) => void;
+    handleFocus: (event: FocusEvent<HTMLSpanElement>) => void;
+    handlePointerEnter: (event: PointerEvent<HTMLSpanElement>) => void;
+    handlePointerLeave: (event: PointerEvent<HTMLSpanElement>) => void;
+    handlePointerMove: (event: PointerEvent<HTMLSpanElement>) => void;
+    swatchRefs: import("react").RefObject<(HTMLSpanElement | null)[]>;
+};
+export { useStackedSwatchFan };

package/dist/components/swatch/use-stacked-swatch-fan.js

@@ -0,0 +1,162 @@
+"use client";
+import { useReducedMotion } from "motion/react";
+import { useCallback, useEffect, useRef } from "react";
+import { getStackedSwatchFanFrame, getStackedSwatchFanTarget, STACKED_SWATCH_FAN_FRAME_SETTLE, STACKED_SWATCH_FAN_REST_PROGRESS, STACKED_SWATCH_FAN_SETTLE_THRESHOLD, } from "./stacked-swatch-fan.motion.js";
+/**
+ * Owns the requestAnimationFrame loop: eases `state.current` towards
+ * `state.target` and writes each frame straight onto the card and tiles, so
+ * hover never re-renders React.
+ */
+const useFanAnimation = (fanned, tileCount) => {
+    const cardRef = useRef(null);
+    const swatchRefs = useRef([]);
+    const initialFanned = Boolean(fanned);
+    const stateRef = useRef({
+        animationFrame: null,
+        current: STACKED_SWATCH_FAN_REST_PROGRESS,
+        fanned: initialFanned,
+        pointerX: 0,
+        pointerY: 0,
+        target: getStackedSwatchFanTarget(initialFanned),
+    });
+    const reducedMotion = useReducedMotion();
+    const applyFrame = useCallback((progress, settling = false) => {
+        // Layer promotion only while a settle is in flight, never at rest.
+        const willChange = settling ? "transform" : "";
+        const card = cardRef.current;
+        const state = stateRef.current;
+        const frame = getStackedSwatchFanFrame(progress, state.pointerX, state.pointerY, tileCount);
+        if (card) {
+            card.dataset.state = state.fanned ? "fanned" : "rest";
+            card.style.transform = frame.cardTransform;
+            card.style.willChange = willChange;
+            // No shadow on the (rectangular) root box - each tile casts its own; a
+            // root box-shadow shows as a phantom rectangle behind the splayed tiles.
+        }
+        for (const [index, swatch] of swatchRefs.current.entries()) {
+            const transform = frame.swatchTransforms[index];
+            if (swatch === null || transform === undefined) {
+                continue;
+            }
+            swatch.style.transform = transform;
+            swatch.style.willChange = willChange;
+        }
+    }, [tileCount]);
+    const stopAnimation = useCallback(() => {
+        const state = stateRef.current;
+        if (state.animationFrame !== null) {
+            cancelAnimationFrame(state.animationFrame);
+            state.animationFrame = null;
+        }
+    }, []);
+    const runFrame = useCallback(function runFrame() {
+        const state = stateRef.current;
+        const delta = state.target - state.current;
+        if (Math.abs(delta) <= STACKED_SWATCH_FAN_SETTLE_THRESHOLD) {
+            state.current = state.target;
+            state.animationFrame = null;
+            applyFrame(state.current);
+            return;
+        }
+        state.current += delta * STACKED_SWATCH_FAN_FRAME_SETTLE;
+        applyFrame(state.current, true);
+        state.animationFrame = requestAnimationFrame(runFrame);
+    }, [applyFrame]);
+    const scheduleAnimation = useCallback(() => {
+        const state = stateRef.current;
+        if (reducedMotion === true) {
+            stopAnimation();
+            state.current = state.target;
+            applyFrame(state.current);
+            return;
+        }
+        if (state.animationFrame !== null) {
+            return;
+        }
+        state.animationFrame = requestAnimationFrame(runFrame);
+    }, [applyFrame, reducedMotion, runFrame, stopAnimation]);
+    useEffect(() => {
+        const nextFanned = Boolean(fanned);
+        stateRef.current.fanned = nextFanned;
+        stateRef.current.target = getStackedSwatchFanTarget(nextFanned);
+        scheduleAnimation();
+    }, [fanned, scheduleAnimation]);
+    useEffect(() => {
+        applyFrame(stateRef.current.current);
+        return stopAnimation;
+    }, [applyFrame, stopAnimation]);
+    return { cardRef, scheduleAnimation, stateRef, swatchRefs };
+};
+/**
+ * Hover/focus wiring for {@link StackedSwatchFan}: returns the refs to attach
+ * and the event handlers, each of which forwards to the consumer's own
+ * handler before driving the fan.
+ */
+const useStackedSwatchFan = ({ fanOnHover, fanned, onBlur, onFannedChange, onFocus, onPointerEnter, onPointerLeave, onPointerMove, tileCount, }) => {
+    const { cardRef, scheduleAnimation, stateRef, swatchRefs } = useFanAnimation(fanned, tileCount);
+    const setFanState = useCallback((nextFanned) => {
+        const state = stateRef.current;
+        const didChange = state.fanned !== nextFanned;
+        state.fanned = nextFanned;
+        state.target = getStackedSwatchFanTarget(nextFanned);
+        if (didChange) {
+            onFannedChange?.(nextFanned);
+        }
+        scheduleAnimation();
+    }, [onFannedChange, scheduleAnimation, stateRef]);
+    const resetPointer = useCallback(() => {
+        stateRef.current.pointerX = 0;
+        stateRef.current.pointerY = 0;
+    }, [stateRef]);
+    const handlePointerEnter = useCallback((event) => {
+        onPointerEnter?.(event);
+        if (fanOnHover) {
+            setFanState(true);
+        }
+    }, [fanOnHover, onPointerEnter, setFanState]);
+    const handlePointerLeave = useCallback((event) => {
+        onPointerLeave?.(event);
+        resetPointer();
+        if (fanOnHover) {
+            setFanState(false);
+        }
+        else {
+            scheduleAnimation();
+        }
+    }, [fanOnHover, onPointerLeave, resetPointer, scheduleAnimation, setFanState]);
+    const handlePointerMove = useCallback((event) => {
+        onPointerMove?.(event);
+        if (!fanOnHover) {
+            return;
+        }
+        const rect = event.currentTarget.getBoundingClientRect();
+        stateRef.current.pointerX =
+            ((event.clientX - rect.left) / rect.width) * 2 - 1;
+        stateRef.current.pointerY =
+            ((event.clientY - rect.top) / rect.height) * 2 - 1;
+        scheduleAnimation();
+    }, [fanOnHover, onPointerMove, scheduleAnimation, stateRef]);
+    const handleFocus = useCallback((event) => {
+        onFocus?.(event);
+        if (fanOnHover) {
+            setFanState(true);
+        }
+    }, [fanOnHover, onFocus, setFanState]);
+    const handleBlur = useCallback((event) => {
+        onBlur?.(event);
+        resetPointer();
+        if (fanOnHover) {
+            setFanState(false);
+        }
+    }, [fanOnHover, onBlur, resetPointer, setFanState]);
+    return {
+        cardRef,
+        handleBlur,
+        handleFocus,
+        handlePointerEnter,
+        handlePointerLeave,
+        handlePointerMove,
+        swatchRefs,
+    };
+};
+export { useStackedSwatchFan };

package/dist/components/swatch-group/swatch-group-context.d.ts

@@ -0,0 +1,17 @@
+import type { LucideIcon } from "lucide-react";
+import type { SwatchSize } from "../../tokens/swatch.js";
+interface SwatchGroupContextValue {
+    /** Icon to display on selected swatch (e.g., Check). When set, replaces the selection ring. */
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>> | undefined;
+    /** Swatch size from shared size system */
+    size: SwatchSize;
+}
+/**
+ * Context for SwatchGroup to pass size and display options to children.
+ */
+export declare const SwatchGroupContext: import("react").Context<SwatchGroupContextValue>;
+/**
+ * Hook to access SwatchGroup context.
+ */
+export declare const useSwatchGroupContext: () => SwatchGroupContextValue;
+export {};

package/dist/components/swatch-group/swatch-group-context.js

@@ -0,0 +1,12 @@
+"use client";
+import { createContext, use } from "react";
+/**
+ * Context for SwatchGroup to pass size and display options to children.
+ */
+export const SwatchGroupContext = createContext({
+    size: "base",
+});
+/**
+ * Hook to access SwatchGroup context.
+ */
+export const useSwatchGroupContext = () => use(SwatchGroupContext);

package/dist/components/swatch-group/swatch-group-item.d.ts

@@ -0,0 +1,37 @@
+import { Radio as RadioPrimitive } from "@base-ui/react/radio";
+import type React from "react";
+import type { SwatchSize } from "../../tokens/swatch.js";
+type SwatchGroupItemProps = Omit<RadioPrimitive.Root.Props<string>, "children"> & {
+    /**
+     * CSS colour value (hex, rgb, hsl, etc.).
+     * If provided along with children, children render on top.
+     */
+    color?: string;
+    /**
+     * Accessible label for screen readers.
+     */
+    "aria-label"?: string;
+    /**
+     * Custom content rendered inside the swatch (e.g., images).
+     */
+    children?: React.ReactNode;
+    /**
+     * Override size for this specific swatch.
+     */
+    size?: SwatchSize;
+};
+/**
+ * Individual swatch item within a SwatchGroup.
+ * Composes the visual `Swatch` primitive with Base UI Radio.Root
+ * for accessible single-select behaviour.
+ *
+ * @example
+ * ```tsx
+ * <SwatchGroup defaultValue="c1" icon={Check}>
+ *   <SwatchGroupItem color="#ff0000" value="c1" aria-label="Red" />
+ *   <SwatchGroupItem color="#00ff00" value="c2" aria-label="Green" />
+ * </SwatchGroup>
+ * ```
+ */
+export declare const SwatchGroupItem: ({ className, color, children, size: sizeOverride, ...props }: SwatchGroupItemProps) => React.JSX.Element;
+export {};