@instruments/materia-ui 0.1.0

package/dist/components/sub-navigation/sub-navigation-root.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Vertical secondary navigation for page subsections and settings-like layouts;
+ * the `<nav>` landmark wrapping a {@link SubNavigationList} of links.
+ *
+ * @bestPractice Reach for `SubNavigation` for a vertical in-page section/settings menu; horizontal router tabs are `TabNavigation`, the app-chrome shell is `Sidebar`.
+ * @bestPractice Fill it with a `SubNavigationList` of links - it already renders the `<nav>` landmark, so don't nest it inside another `<nav>`.
+ * @category navigation
+ */
+export const SubNavigation = ({ className, children, ...props }) => (_jsx(Flex, { as: "nav", className: cn("w-full", className), "data-component": "sub-navigation", "data-slot": "sub-navigation", direction: "column", gap: "xs", ...props, children: children }));

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

@@ -0,0 +1,6 @@
+export type { SubNavigationLinkProps } from "./sub-navigation/sub-navigation-link.js";
+export { SubNavigationLink } from "./sub-navigation/sub-navigation-link.js";
+export type { SubNavigationListProps } from "./sub-navigation/sub-navigation-list.js";
+export { SubNavigationList } from "./sub-navigation/sub-navigation-list.js";
+export type { SubNavigationProps } from "./sub-navigation/sub-navigation-root.js";
+export { SubNavigation } from "./sub-navigation/sub-navigation-root.js";

package/dist/components/sub-navigation.js

@@ -0,0 +1,3 @@
+export { SubNavigationLink } from "./sub-navigation/sub-navigation-link.js";
+export { SubNavigationList } from "./sub-navigation/sub-navigation-list.js";
+export { SubNavigation } from "./sub-navigation/sub-navigation-root.js";

package/dist/components/success-tick-ripple/success-tick-ripple-root.d.ts

@@ -0,0 +1,35 @@
+export interface SuccessTickRippleProps {
+    /** Pixel size of the medallion. Defaults to 64. */
+    size?: number;
+    /**
+     * Optional accessible label. When provided, the medallion is exposed
+     * to AT as an image with this label; otherwise it is decorative.
+     */
+    "aria-label"?: string;
+    /** Extra classes for the medallion element. */
+    className?: string;
+}
+/**
+ * Celebration tick - a green medallion that drops in with a spring rebound
+ * while three radial-gradient rings ripple outward from its centre and a
+ * residual mint glow settles on the upper edges of the parent container.
+ *
+ * Layout contract:
+ *  - The component renders a `position: absolute; inset: 0` ripple field
+ *    plus the medallion (in normal flow). The ripple field attaches to
+ *    the nearest positioned ancestor - wrap this component in a parent
+ *    that is `position: relative` and `overflow: hidden` to bound the
+ *    celebration. The medallion's centre is the visual impact point.
+ *
+ * Tuning:
+ *  - Override `--tick-impact-x` / `--tick-impact-y` on the parent to move
+ *    the ripple origin (defaults to 50% / 50% of the parent).
+ *
+ * Animations are CSS-only and run once on mount. `prefers-reduced-motion`
+ * collapses to the final settled state and hides the ripple.
+ *
+ * @bestPractice Wrap `SuccessTickRipple` in a `position: relative; overflow: hidden` parent - the ripple field is absolutely positioned and bleeds past an unbounded container.
+ * @bestPractice It's decorative (`aria-hidden`) unless you pass `aria-label`, which exposes it as an `img`; animations are CSS-only and already collapse under `prefers-reduced-motion`.
+ * @category feedback
+ */
+export declare const SuccessTickRipple: ({ size, className, "aria-label": ariaLabel, }: SuccessTickRippleProps) => import("react").JSX.Element;

package/dist/components/success-tick-ripple/success-tick-ripple-root.js

@@ -0,0 +1,33 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+const CHECK_PATH = "M5 13.5 9 17.5 19 6.5";
+/**
+ * Celebration tick - a green medallion that drops in with a spring rebound
+ * while three radial-gradient rings ripple outward from its centre and a
+ * residual mint glow settles on the upper edges of the parent container.
+ *
+ * Layout contract:
+ *  - The component renders a `position: absolute; inset: 0` ripple field
+ *    plus the medallion (in normal flow). The ripple field attaches to
+ *    the nearest positioned ancestor - wrap this component in a parent
+ *    that is `position: relative` and `overflow: hidden` to bound the
+ *    celebration. The medallion's centre is the visual impact point.
+ *
+ * Tuning:
+ *  - Override `--tick-impact-x` / `--tick-impact-y` on the parent to move
+ *    the ripple origin (defaults to 50% / 50% of the parent).
+ *
+ * Animations are CSS-only and run once on mount. `prefers-reduced-motion`
+ * collapses to the final settled state and hides the ripple.
+ *
+ * @bestPractice Wrap `SuccessTickRipple` in a `position: relative; overflow: hidden` parent - the ripple field is absolutely positioned and bleeds past an unbounded container.
+ * @bestPractice It's decorative (`aria-hidden`) unless you pass `aria-label`, which exposes it as an `img`; animations are CSS-only and already collapse under `prefers-reduced-motion`.
+ * @category feedback
+ */
+export const SuccessTickRipple = ({ size = 64, className, "aria-label": ariaLabel, }) => {
+    const labelProps = ariaLabel !== undefined && ariaLabel !== null && ariaLabel !== ""
+        ? { "aria-label": ariaLabel, role: "img" }
+        : { "aria-hidden": true };
+    return (_jsxs(_Fragment, { children: [_jsxs("span", { "aria-hidden": true, className: "t-success-tick-ripple-field", children: [_jsx("span", { className: "t-success-tick-ripple-glow" }), _jsx("span", { className: "t-success-tick-ripple-ring t-success-tick-ripple-ring-primary" }), _jsx("span", { className: "t-success-tick-ripple-ring t-success-tick-ripple-ring-soft" }), _jsx("span", { className: "t-success-tick-ripple-ring t-success-tick-ripple-ring-sheen" })] }), _jsx("span", { ...labelProps, className: cn("t-success-tick-medallion", className), style: { height: size, width: size }, children: _jsx("svg", { "aria-hidden": "true", fill: "none", focusable: "false", height: size, stroke: "currentColor", strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2.4, viewBox: "0 0 24 24", width: size, children: _jsx("path", { d: CHECK_PATH, pathLength: 1 }) }) })] }));
+};

package/dist/components/success-tick-ripple.d.ts

@@ -0,0 +1 @@
+export { SuccessTickRipple, type SuccessTickRippleProps, } from "./success-tick-ripple/success-tick-ripple-root.js";

package/dist/components/success-tick-ripple.js

@@ -0,0 +1 @@
+export { SuccessTickRipple, } from "./success-tick-ripple/success-tick-ripple-root.js";

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

@@ -0,0 +1,32 @@
+import type { ComponentProps } from "react";
+interface StackedSwatchFanItem {
+    background: string;
+    id: string;
+    isLight?: boolean;
+}
+interface StackedSwatchFanProps extends Omit<ComponentProps<"span">, "children" | "onAnimationStart"> {
+    /**
+     * When `true` (default), the stack owns its own fan state via hover/focus.
+     * Set `false` to drive it externally through the controlled `fanned` prop.
+     * @default true
+     */
+    fanOnHover?: boolean;
+    /** Controlled fan state - use when a sibling element (e.g. a CTA) triggers the fan. */
+    fanned?: boolean;
+    /** Swatch fills to stack; only the first few (matching the motion transforms) render. */
+    items: StackedSwatchFanItem[];
+    /** Accessible label applied as the fan's `aria-label`. @default "Material swatches" */
+    label?: string;
+    /** Fires when the fan opens or closes, with the next fanned state. */
+    onFannedChange?: (fanned: boolean) => void;
+}
+/**
+ * Four studio {@link Swatch} tiles composed into a stacked material fan that
+ * splays open on hover/focus and settles via requestAnimationFrame.
+ *
+ * Fans itself by default (`fanOnHover`); pass `fanned` to drive it from an
+ * external trigger such as a sibling CTA. Honours `prefers-reduced-motion` by
+ * snapping to the target instead of animating. Renders as a `role="img"`.
+ */
+declare const StackedSwatchFan: ({ className, fanOnHover, fanned, items, label, onBlur, onFannedChange, onFocus, onPointerEnter, onPointerLeave, onPointerMove, style, ...props }: StackedSwatchFanProps) => import("react").JSX.Element;
+export { StackedSwatchFan, type StackedSwatchFanItem, type StackedSwatchFanProps, };

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

@@ -0,0 +1,48 @@
+"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 "../center.js";
+import { Flex } from "../flex.js";
+import { Swatch } from "../swatch/swatch-root.js";
+import { STACKED_SWATCH_FAN_CARD_WIDTH, STACKED_SWATCH_FAN_STACK_HEIGHT, STACKED_SWATCH_FAN_STACK_PADDING, STACKED_SWATCH_FAN_SWATCH_RADIUS, STACKED_SWATCH_FAN_SWATCH_SIZE, SWATCH_FAN_MAX_TILES, } from "./stacked-swatch-fan.motion.js";
+import { useStackedSwatchFan } from "./use-stacked-swatch-fan.js";
+/**
+ * Four studio {@link Swatch} tiles composed into a stacked material fan that
+ * splays open on hover/focus and settles via requestAnimationFrame.
+ *
+ * Fans itself by default (`fanOnHover`); pass `fanned` to drive it from an
+ * external trigger such as a sibling CTA. Honours `prefers-reduced-motion` by
+ * snapping to the target instead of animating. Renders as a `role="img"`.
+ */
+const StackedSwatchFan = ({ className, fanOnHover = true, fanned, items, label = "Material swatches", onBlur, onFannedChange, onFocus, onPointerEnter, onPointerLeave, onPointerMove, style, ...props }) => {
+    const visibleItems = items.slice(0, SWATCH_FAN_MAX_TILES);
+    const { cardRef, handleBlur, handleFocus, handlePointerEnter, handlePointerLeave, handlePointerMove, swatchRefs, } = useStackedSwatchFan({
+        fanOnHover,
+        fanned,
+        onBlur,
+        onFannedChange,
+        onFocus,
+        onPointerEnter,
+        onPointerLeave,
+        onPointerMove,
+        tileCount: visibleItems.length,
+    });
+    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": "stacked-swatch-fan", "data-slot": "stacked-swatch-fan", "data-state": fanned === true ? "fanned" : "rest", inline: true, onBlur: handleBlur, onFocus: handleFocus, onPointerEnter: handlePointerEnter, onPointerLeave: handlePointerLeave, onPointerMove: handlePointerMove, ref: cardRef, 
+        // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- a labelled group of decorative children, which `<img>` cannot host
+        role: "img", style: style, ...props, children: _jsx(Center, { as: "span", className: "relative [perspective:600px]", "data-slot": "stacked-swatch-fan-stack", style: {
+                height: STACKED_SWATCH_FAN_STACK_HEIGHT,
+                padding: STACKED_SWATCH_FAN_STACK_PADDING,
+                width: STACKED_SWATCH_FAN_CARD_WIDTH,
+            }, children: visibleItems.map((item, index) => (_jsx("span", { "aria-hidden": "true", className: "absolute", "data-slot": "stacked-swatch-fan-item", ref: (node) => {
+                    swatchRefs.current[index] = node;
+                }, style: { zIndex: index + 1 }, children: _jsx(Swatch, { background: item.background, ...(item.isLight === undefined ? {} : { light: item.isLight }), kind: "tile", size: "2xl", style: {
+                        borderRadius: STACKED_SWATCH_FAN_SWATCH_RADIUS,
+                        height: STACKED_SWATCH_FAN_SWATCH_SIZE,
+                        width: STACKED_SWATCH_FAN_SWATCH_SIZE,
+                    }, variant: "floating" }) }, item.id))) }) }));
+};
+export { StackedSwatchFan, };

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

@@ -0,0 +1,28 @@
+interface FanTransform {
+    hoverRotate: number;
+    hoverX: number;
+    hoverY: number;
+    restRotate: number;
+    restX: number;
+    restY: number;
+}
+interface FanFrame {
+    cardShadow: string;
+    cardTransform: string;
+    swatchTransforms: string[];
+}
+declare const STACKED_SWATCH_FAN_CARD_WIDTH = 188;
+declare const STACKED_SWATCH_FAN_STACK_PADDING = 14;
+declare const STACKED_SWATCH_FAN_STACK_HEIGHT = 110;
+declare const STACKED_SWATCH_FAN_SWATCH_SIZE = 92;
+declare const STACKED_SWATCH_FAN_SWATCH_RADIUS = 6;
+declare const STACKED_SWATCH_FAN_REST_PROGRESS = 0.15;
+declare const STACKED_SWATCH_FAN_FRAME_SETTLE: number;
+declare const STACKED_SWATCH_FAN_SETTLE_THRESHOLD = 0.001;
+declare const getStackedSwatchFanTarget: (fanned: boolean) => 0.15 | 1;
+/** Max tiles the fan renders; extra items are ignored (a fan reads cleanest at 3–4). */
+declare const SWATCH_FAN_MAX_TILES = 4;
+/** Symmetric per-tile transforms for `count` tiles at the eased open amount. */
+declare const computeSwatchFanTransforms: (count: number, eased: number) => string[];
+declare const getStackedSwatchFanFrame: (progress: number, pointerX: number, pointerY: number, count?: number) => FanFrame;
+export { computeSwatchFanTransforms, type FanFrame, type FanTransform, getStackedSwatchFanFrame, getStackedSwatchFanTarget, STACKED_SWATCH_FAN_CARD_WIDTH, STACKED_SWATCH_FAN_FRAME_SETTLE, STACKED_SWATCH_FAN_REST_PROGRESS, STACKED_SWATCH_FAN_SETTLE_THRESHOLD, STACKED_SWATCH_FAN_STACK_HEIGHT, STACKED_SWATCH_FAN_STACK_PADDING, STACKED_SWATCH_FAN_SWATCH_RADIUS, STACKED_SWATCH_FAN_SWATCH_SIZE, SWATCH_FAN_MAX_TILES, };

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

@@ -0,0 +1,82 @@
+import { easings } from "@instruments/materia-ui/tokens/motion";
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const mix = (from, to, progress) => from + (to - from) * progress;
+const sampleCurve = (time, point1, point2) => {
+    const inverse = 1 - time;
+    return (3 * inverse * inverse * time * point1 +
+        3 * inverse * time * time * point2 +
+        time * time * time);
+};
+const cubicBezier = (progress, x1, y1, x2, y2) => {
+    const epsilon = 0.00001;
+    let lower = 0;
+    let upper = 1;
+    let percent = progress;
+    for (let i = 0; i < 12; i += 1) {
+        const x = sampleCurve(percent, x1, x2);
+        if (Math.abs(x - progress) < epsilon) {
+            break;
+        }
+        if (x < progress) {
+            lower = percent;
+        }
+        else {
+            upper = percent;
+        }
+        percent = (upper + lower) / 2;
+    }
+    return sampleCurve(percent, y1, y2);
+};
+const STACKED_SWATCH_FAN_CARD_WIDTH = 188;
+const STACKED_SWATCH_FAN_STACK_PADDING = 14;
+const STACKED_SWATCH_FAN_STACK_HEIGHT = 110;
+const STACKED_SWATCH_FAN_SWATCH_SIZE = 92;
+const STACKED_SWATCH_FAN_SWATCH_RADIUS = 6;
+const STACKED_SWATCH_FAN_CARD_LIFT = 2;
+const STACKED_SWATCH_FAN_POINTER_TILT = 3;
+const STACKED_SWATCH_FAN_REST_PROGRESS = 0.15;
+const STACKED_SWATCH_FAN_FRAME_SETTLE = clamp((0.21 * 320) / 300, 0.015, 0.6);
+const STACKED_SWATCH_FAN_SETTLE_THRESHOLD = 0.001;
+const getStackedSwatchFanTarget = (fanned) => fanned ? 1 : STACKED_SWATCH_FAN_REST_PROGRESS;
+// Symmetric fan geometry, computed per tile count so any N (2–6) splays evenly
+// around the centre instead of drawing from a fixed 4-slot table (which skewed
+// a 3-tile fan lopsided). Per-step deltas widen from rest → hover.
+const SWATCH_FAN_REST_ANGLE_STEP = 7;
+const SWATCH_FAN_HOVER_ANGLE_STEP = 11;
+const SWATCH_FAN_REST_X_STEP = 22;
+const SWATCH_FAN_HOVER_X_STEP = 34;
+const SWATCH_FAN_END_DIP = 4;
+/** Max tiles the fan renders; extra items are ignored (a fan reads cleanest at 3–4). */
+const SWATCH_FAN_MAX_TILES = 4;
+/** Symmetric per-tile transforms for `count` tiles at the eased open amount. */
+const computeSwatchFanTransforms = (count, eased) => {
+    const centre = (count - 1) / 2;
+    const angleStep = mix(SWATCH_FAN_REST_ANGLE_STEP, SWATCH_FAN_HOVER_ANGLE_STEP, eased);
+    const xStep = mix(SWATCH_FAN_REST_X_STEP, SWATCH_FAN_HOVER_X_STEP, eased);
+    return Array.from({ length: count }, (_unused, index) => {
+        // Symmetric offset: −centre … +centre.
+        const offset = index - centre;
+        const rotate = offset * angleStep;
+        const x = offset * xStep;
+        // End tiles dip slightly as the fan opens - a real fan's outer cards fall.
+        const y = Math.abs(offset) * SWATCH_FAN_END_DIP * eased;
+        return `rotate(${rotate}deg) translate3d(${x}px, ${y}px, 0)`;
+    });
+};
+const getStackedSwatchFanFrame = (progress, pointerX, pointerY, count = 4) => {
+    const eased = cubicBezier(progress, ...easings.out);
+    const shadowY = mix(4, 8, eased);
+    const shadowBlur = mix(20, 28, eased);
+    const shadowOpacity = mix(0.05, 0.08, eased);
+    return {
+        cardShadow: `0 ${shadowY}px ${shadowBlur}px rgba(0, 0, 0, ${shadowOpacity})`,
+        cardTransform: [
+            `translate3d(0, ${-STACKED_SWATCH_FAN_CARD_LIFT * eased}px, 0)`,
+            "scale(1)",
+            `rotateX(${-pointerY * STACKED_SWATCH_FAN_POINTER_TILT * eased}deg)`,
+            `rotateY(${pointerX * STACKED_SWATCH_FAN_POINTER_TILT * eased}deg)`,
+        ].join(" "),
+        swatchTransforms: computeSwatchFanTransforms(count, eased),
+    };
+};
+export { computeSwatchFanTransforms, getStackedSwatchFanFrame, getStackedSwatchFanTarget, STACKED_SWATCH_FAN_CARD_WIDTH, STACKED_SWATCH_FAN_FRAME_SETTLE, STACKED_SWATCH_FAN_REST_PROGRESS, STACKED_SWATCH_FAN_SETTLE_THRESHOLD, STACKED_SWATCH_FAN_STACK_HEIGHT, STACKED_SWATCH_FAN_STACK_PADDING, STACKED_SWATCH_FAN_SWATCH_RADIUS, STACKED_SWATCH_FAN_SWATCH_SIZE, SWATCH_FAN_MAX_TILES, };

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

@@ -0,0 +1,111 @@
+import type { ReactNode, Ref } from "react";
+import type { IconComponent } from "../../tokens/icon-component.js";
+import type { SwatchChipSize, SwatchTileSize } from "../../tokens/swatch.js";
+/** Chip geometry - the round/pill kinds (tiles are handled by `SwatchTile`). */
+type SwatchChipForm = "circle" | "pill";
+type SwatchColorStop = string | {
+    color: string;
+    ratio?: number;
+};
+/** Tile corner radius - used by the legacy `variant="raised"` tile path. */
+declare const TILE_BORDER_RADIUS = "rounded-sm";
+/** A non-empty string fill value (filters out undefined/null/empty). */
+declare const hasValue: (value: string | null | undefined) => value is string;
+/** Compose the ringless control shadow with optional selection/media edges. */
+declare const composeSwatchShadow: (selected: boolean, showRing: boolean, raised: boolean, isTile: boolean) => string;
+/** Resolve the fill value + contrast colour for a swatch from its fill props. */
+declare const deriveSwatchVisuals: ({ background, children, color, colors, isLightOverride, }: {
+    background: string | undefined;
+    children: ReactNode;
+    color: string | undefined;
+    colors: SwatchColorStop[] | undefined;
+    isLightOverride: boolean | undefined;
+}) => {
+    fillBackground: string | undefined;
+    hasChildren: boolean;
+    isLightComputed: boolean;
+};
+/** The stacked visual layers inside a Swatch (fill, content, overlay, icon, unavailable). */
+declare const SwatchLayers: ({ fillBackground, hasChildren, children, radiusClass, selected, icon, size, unavailable, }: {
+    fillBackground: string | undefined;
+    hasChildren: boolean;
+    children: ReactNode;
+    radiusClass: string;
+    selected: boolean;
+    icon: IconComponent | undefined;
+    size: SwatchTileSize;
+    unavailable: boolean;
+}) => import("react").JSX.Element;
+/** Hover-reveal remove control. Uses <span role="button"> to avoid nesting a
+ * <button> when the Swatch itself sits inside a button (e.g. PaletteSlot). */
+declare const SwatchRemoveButton: ({ onRemove }: {
+    onRemove: () => void;
+}) => import("react").JSX.Element;
+interface ChipSwatchProps {
+    /**
+     * CSS background value for the swatch fill. Accepts any valid CSS
+     * `background` - gradients, images, or solid colours. Takes precedence over
+     * `color` when both are provided. Use this for gradient or image fills.
+     */
+    background?: string;
+    /** Image or custom content rendered on top of the colour */
+    children?: ReactNode;
+    /** Additional className */
+    className?: string;
+    /** CSS colour value (hex, rgb, hsl, etc.) - convenience prop for solid fills. */
+    color?: string;
+    /**
+     * One or more colours rendered as a single swatch fill. Object entries can
+     * include `ratio` values to represent colour density or extracted palette
+     * proportions. `background` takes precedence when both are provided.
+     */
+    colors?: SwatchColorStop[];
+    /** Icon to display when selected (e.g., Check, X). Contrast-aware coloring is automatic. */
+    icon?: IconComponent;
+    /** Alt text for the image (used when `src` is provided). */
+    alt?: string;
+    /**
+     * Override light colour detection for contrast handling. Required when using
+     * `background` for a gradient - `isLightColor` only works for solid colours.
+     */
+    light?: boolean;
+    /**
+     * When provided, renders a hover-reveal X button at the top-right corner.
+     * Clicking the X calls this handler (e.g. to remove the swatch from a list).
+     */
+    onRemove?: () => void;
+    /** White border ring for embedding swatches in input fields */
+    raised?: boolean;
+    /** Forwarded ref to the root span. Needed for m.create(Swatch). */
+    ref?: Ref<HTMLSpanElement>;
+    /** Whether this swatch appears selected */
+    selected?: boolean;
+    /**
+     * Chip kind: "circle" (default) or "pill" (wide rounded rectangle).
+     * Pill form is 144×48 with rounded-3xl corners - used for colour name pills
+     * and back-navigation targets.
+     * @default "circle"
+     */
+    kind?: SwatchChipForm;
+    /** Show selection ring when selected (default: true) */
+    showRing?: boolean;
+    /** Size from the chip swatch size system. Ignored when kind="pill". */
+    size?: SwatchChipSize;
+    /**
+     * Image source URL - rendered as a native `<img>` fill (object-cover) on top
+     * of any color/gradient fill. Ignored when `children` is provided.
+     */
+    src?: string;
+    /** Inline styles (useful for pixel-based sizing) */
+    style?: React.CSSProperties;
+    /** Whether this option is unavailable (out of stock) */
+    unavailable?: boolean;
+}
+/**
+ * Chip renderer for `Swatch` - the circular/pill colour, gradient, and image
+ * chip. Sets contrast-aware text colour (light/dark) so children and icons
+ * inherit the correct colour, paints the darkening overlay on every fill, and
+ * draws the double-ring selection pattern.
+ */
+declare const SwatchChip: ({ background, color, colors, children, src, alt, size, kind, raised, selected, showRing, icon, onRemove, unavailable, light: isLightOverride, className, style, ref, }: ChipSwatchProps) => import("react").JSX.Element;
+export { composeSwatchShadow, deriveSwatchVisuals, hasValue, SwatchChip, type ChipSwatchProps, SwatchLayers, SwatchRemoveButton, type SwatchColorStop, TILE_BORDER_RADIUS, };

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

@@ -0,0 +1,136 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { X as XIcon } from "lucide-react";
+import { isLightColor } from "../../data/material-colors.js";
+import { shadows } from "../../tokens/shadows.js";
+import { swatchIconSizeMap, swatchSizeMap } from "../../tokens/swatch.js";
+import { cn } from "../../utils/cn.js";
+import { isString } from "../../utils/type-guards.js";
+import { Center } from "../center.js";
+import { Icon } from "../icon.js";
+/** Pill dimensions: 144×48 (w-36 h-12), for colour name pills. */
+const PILL_SIZE_CLASS = "h-12 w-36";
+const PILL_BORDER_RADIUS = "rounded-3xl";
+const CIRCLE_BORDER_RADIUS = "rounded-full";
+/** Tile corner radius - used by the legacy `variant="raised"` tile path. */
+const TILE_BORDER_RADIUS = "rounded-sm";
+/** A non-empty string fill value (filters out undefined/null/empty). */
+const hasValue = (value) => value !== undefined && value !== null && value !== "";
+/** Compose the ringless control shadow with optional selection/media edges. */
+const composeSwatchShadow = (selected, showRing, raised, isTile) => {
+    const parts = isTile
+        ? [
+            shadows.xs,
+            // Keep light photo swatch edges legible without changing elevation.
+            "inset 0 0 0 1px rgba(255, 255, 255, 0.6)",
+        ]
+        : [shadows.xs];
+    if (selected && showRing) {
+        parts.push("0 0 0 2px var(--color-input)", "0 0 0 4px var(--color-primary)");
+    }
+    else if (raised) {
+        parts.push("0 0 0 2px white");
+    }
+    return parts.join(", ");
+};
+const getSwatchColorsBackground = (colors) => {
+    if (!colors || colors.length === 0) {
+        return null;
+    }
+    const stops = [];
+    for (const stop of colors) {
+        const normalized = isString(stop)
+            ? { color: stop, ratio: null }
+            : { color: stop.color, ratio: stop.ratio ?? null };
+        if (normalized.color.trim().length > 0) {
+            stops.push(normalized);
+        }
+    }
+    if (stops.length === 0) {
+        return null;
+    }
+    if (stops.length === 1) {
+        return stops[0]?.color ?? null;
+    }
+    const ratioSum = stops.reduce((sum, stop) => sum + Math.max(0, stop.ratio ?? 0), 0);
+    const fallbackRatio = 100 / stops.length;
+    let cursor = 0;
+    const colorStops = stops.map((stop, index) => {
+        const rawRatio = ratioSum > 0
+            ? (Math.max(0, stop.ratio ?? 0) / ratioSum) * 100
+            : fallbackRatio;
+        const position = cursor + rawRatio / 2;
+        const end = index === stops.length - 1 ? 100 : cursor + rawRatio;
+        cursor = end;
+        return `${stop.color} ${position}%`;
+    });
+    return `linear-gradient(135deg, ${colorStops.join(", ")})`;
+};
+/** Resolve the fill value + contrast colour for a swatch from its fill props. */
+const deriveSwatchVisuals = ({ background, children, color, colors, isLightOverride, }) => {
+    const colorStopsBackground = getSwatchColorsBackground(colors);
+    // `background` shorthand accepts both colours and gradients.
+    const fillBackground = background ?? colorStopsBackground ?? color;
+    const hasGradientFill = hasValue(background) || hasValue(colorStopsBackground);
+    // `isLightColor` only works on solid colours - skip it for gradient/image fills.
+    const isLightComputed = isLightOverride ??
+        (hasValue(color) && !hasGradientFill ? isLightColor(color) : false);
+    return {
+        fillBackground,
+        hasChildren: children !== undefined && children !== null,
+        isLightComputed,
+    };
+};
+/** The stacked visual layers inside a Swatch (fill, content, overlay, icon, unavailable). */
+const SwatchLayers = ({ fillBackground, hasChildren, children, radiusClass, selected, icon, size, unavailable, }) => {
+    const hasFill = hasValue(fillBackground);
+    return (_jsxs(_Fragment, { children: [hasFill ? (_jsx("span", { "aria-hidden": true, className: cn("absolute inset-0 overflow-hidden", radiusClass), style: { background: fillBackground } })) : null, hasChildren ? (_jsx("span", { "aria-hidden": true, className: cn("absolute inset-0 overflow-hidden", radiusClass), children: children })) : null, selected && icon ? (_jsx(Center, { as: "span", className: "absolute inset-0", "data-slot": "swatch-icon", children: _jsx(Icon, { className: "stroke-bold", icon: icon, size: swatchIconSizeMap[size] }) })) : null, unavailable ? (_jsx(Center, { "aria-hidden": true, as: "span", className: "absolute inset-0", children: _jsx("span", { className: "h-0.5 w-full -rotate-45 bg-white shadow-xs" }) })) : null] }));
+};
+/** Hover-reveal remove control. Uses <span role="button"> to avoid nesting a
+ * <button> when the Swatch itself sits inside a button (e.g. PaletteSlot). */
+const SwatchRemoveButton = ({ onRemove }) => (_jsx(Center, { "aria-label": "Remove", as: "span", className: "bg-primary hover:bg-primary/90 absolute -top-1 -right-1 size-5 cursor-pointer rounded-full opacity-0 shadow-xs transition-opacity group-focus-within:opacity-100 group-hover:opacity-100 focus-visible:opacity-100", onClick: (e) => {
+        e.stopPropagation();
+        onRemove();
+    }, onKeyDown: (e) => {
+        if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            e.stopPropagation();
+            onRemove();
+        }
+    }, 
+    // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role, react-doctor/prefer-tag-over-role -- intentional <span role="button"> to avoid nesting a <button> inside a parent button (Swatch sits inside button surfaces e.g. PaletteSlot); a native <button> would be invalid HTML
+    role: "button", tabIndex: 0, children: _jsx(Icon, { className: "text-primary-foreground", icon: XIcon, size: "2xs" }) }));
+/**
+ * Chip renderer for `Swatch` - the circular/pill colour, gradient, and image
+ * chip. Sets contrast-aware text colour (light/dark) so children and icons
+ * inherit the correct colour, paints the darkening overlay on every fill, and
+ * draws the double-ring selection pattern.
+ */
+const SwatchChip = ({ background, color, colors, children, src, alt = "", size = "base", kind = "circle", raised = false, selected = false, showRing = true, icon, onRemove, unavailable = false, light: isLightOverride, className, style, ref, }) => {
+    const isPill = kind === "pill";
+    const radiusClass = isPill ? PILL_BORDER_RADIUS : CIRCLE_BORDER_RADIUS;
+    const sizeClass = isPill ? PILL_SIZE_CLASS : swatchSizeMap[size];
+    // `src` is a convenience for the (previously children-only) image-chip path;
+    // an explicit `children` still wins so custom next/image wrappers pass through.
+    const content = children ??
+        (hasValue(src) ? (_jsx("img", { alt: alt, className: "size-full object-cover", src: src })) : undefined);
+    const { fillBackground, hasChildren, isLightComputed } = deriveSwatchVisuals({
+        background,
+        children: content,
+        color,
+        colors,
+        isLightOverride,
+    });
+    return (_jsxs(Center, { as: "span", className: cn(
+        // Base styles - container for rings and colour
+        "relative", radiusClass, sizeClass, 
+        // Contrast-aware text colour - inherited by all children (icons, labels, etc.)
+        isLightComputed ? "text-gray-900" : "text-white", 
+        // Transition for smooth selection
+        "duration-quick transition-shadow", 
+        // Unavailable state
+        unavailable && "opacity-50", className), "data-selected": selected, "data-kind": kind, "data-slot": "swatch", inline: true, ref: ref, style: {
+            ...style,
+            boxShadow: composeSwatchShadow(selected, showRing, raised, false),
+        }, children: [_jsx(SwatchLayers, { fillBackground: fillBackground, hasChildren: hasChildren, icon: icon, radiusClass: radiusClass, selected: selected, size: size, unavailable: unavailable, children: content }), onRemove ? _jsx(SwatchRemoveButton, { onRemove: onRemove }) : null] }));
+};
+export { composeSwatchShadow, deriveSwatchVisuals, hasValue, SwatchChip, SwatchLayers, SwatchRemoveButton, TILE_BORDER_RADIUS, };

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

@@ -0,0 +1,47 @@
+import type { ChipSwatchProps } from "./swatch-chip.js";
+import type { TileSwatchProps } from "./swatch-tile-types.js";
+/**
+ * Discriminated `Swatch` props, keyed on `kind`.
+ * - `kind="circle" | "pill"` (or omitted) → chip renderer ({@link ChipSwatchProps})
+ * - `kind="tile"` → tile renderer ({@link TileSwatchProps})
+ *
+ * The union makes misused props a compile error: a chip cannot take a
+ * tile-only step (`<Swatch kind="circle" size="3xs">`), and a tile cannot take
+ * a chip-only prop (`<Swatch kind="tile" icon={…}>`).
+ */
+type SwatchProps = ChipSwatchProps | TileSwatchProps;
+/**
+ * Low-level visual swatch primitive for colours, gradients, and images -
+ * shaped as a **chip** (`circle`/`pill`) or a **tile** (square material/image
+ * card). A thin façade dispatching on `kind` to the internal chip and tile
+ * renderers, which share fill resolution and contrast handling.
+ *
+ * Chips paint the darkening overlay on every fill and draw the double-ring
+ * selection pattern; tiles use tiered radius, border, ring and shadow, `children` > `src` > `color`
+ * precedence, and no darkening overlay.
+ *
+ * @example
+ * ```tsx
+ * // Colour chip with selection ring
+ * <Swatch color="#ff0000" selected size="base" />
+ *
+ * // Pill form (colour name pills)
+ * <Swatch color="#8B4513" kind="pill" />
+ *
+ * // Image tile (card variant)
+ * <Swatch kind="tile" src="/lace.jpg" alt="Lace" size="lg" />
+ *
+ * // Solid-colour tile
+ * <Swatch kind="tile" color="#a2b09f" size={58} />
+ * ```
+ *
+ * @bestPractice Feed fills through `color`/`background`/`colors`, never a hex in `className`/`style` - the props drive the contrast-aware text colour, selection ring, and darkening overlay.
+ * @bestPractice Reach for `Swatch` for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is `Dot`, and a display-only status/category label is `Badge`.
+ * @bestPractice For a gradient or image chip fill pass `light` - auto contrast detection (`isLightColor`) only reads solid colours, so overlaid icons/labels lose legibility without it.
+ * @category color
+ */
+declare const Swatch: (props: SwatchProps) => import("react").JSX.Element;
+export { Swatch, type SwatchProps };
+export type { ChipSwatchProps, SwatchColorStop } from "./swatch-chip.js";
+export { SwatchFrameRing } from "./swatch-tile.js";
+export type { TileSwatchProps } from "./swatch-tile-types.js";

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

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SwatchChip } from "./swatch-chip.js";
+import { SwatchTile } from "./swatch-tile.js";
+/**
+ * Low-level visual swatch primitive for colours, gradients, and images -
+ * shaped as a **chip** (`circle`/`pill`) or a **tile** (square material/image
+ * card). A thin façade dispatching on `kind` to the internal chip and tile
+ * renderers, which share fill resolution and contrast handling.
+ *
+ * Chips paint the darkening overlay on every fill and draw the double-ring
+ * selection pattern; tiles use tiered radius, border, ring and shadow, `children` > `src` > `color`
+ * precedence, and no darkening overlay.
+ *
+ * @example
+ * ```tsx
+ * // Colour chip with selection ring
+ * <Swatch color="#ff0000" selected size="base" />
+ *
+ * // Pill form (colour name pills)
+ * <Swatch color="#8B4513" kind="pill" />
+ *
+ * // Image tile (card variant)
+ * <Swatch kind="tile" src="/lace.jpg" alt="Lace" size="lg" />
+ *
+ * // Solid-colour tile
+ * <Swatch kind="tile" color="#a2b09f" size={58} />
+ * ```
+ *
+ * @bestPractice Feed fills through `color`/`background`/`colors`, never a hex in `className`/`style` - the props drive the contrast-aware text colour, selection ring, and darkening overlay.
+ * @bestPractice Reach for `Swatch` for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is `Dot`, and a display-only status/category label is `Badge`.
+ * @bestPractice For a gradient or image chip fill pass `light` - auto contrast detection (`isLightColor`) only reads solid colours, so overlaid icons/labels lose legibility without it.
+ * @category color
+ */
+const Swatch = (props) => {
+    if (props.kind === "tile") {
+        return _jsx(SwatchTile, { ...props });
+    }
+    return _jsx(SwatchChip, { ...props });
+};
+export { Swatch };
+export { SwatchFrameRing } from "./swatch-tile.js";