@instruments/materia-ui 0.1.0

package/dist/compositions/sidebar.js

@@ -0,0 +1,28 @@
+export { sidebarAnatomy } from "./sidebar/sidebar-anatomy.js";
+export { CONTENT_COLUMN_CLASS, HEADER_HEIGHT, SIDEBAR_COOKIE_MAX_AGE, SIDEBAR_COOKIE_NAME, SIDEBAR_INSET_GAP, SIDEBAR_INSET_ID, SIDEBAR_KEYBOARD_SHORTCUT, SIDEBAR_MOBILE_BREAKPOINT_PX, SIDEBAR_WIDTH, SIDEBAR_WIDTH_COOKIE_NAME, SIDEBAR_WIDTH_DEFAULT_PX, SIDEBAR_WIDTH_ICON, SIDEBAR_WIDTH_MAX_PX, SIDEBAR_WIDTH_MIN_PX, SIDEBAR_WIDTH_MOBILE, } from "./sidebar/sidebar-constants.js";
+export { SidebarContent } from "./sidebar/sidebar-content.js";
+export { SidebarFooter } from "./sidebar/sidebar-footer.js";
+export { SidebarGroup } from "./sidebar/sidebar-group.js";
+export { SidebarHeader } from "./sidebar/sidebar-header.js";
+export { SidebarInput } from "./sidebar/sidebar-input.js";
+export { SidebarInset } from "./sidebar/sidebar-inset.js";
+export { SidebarLayoutHeader, SidebarLayoutHeaderActions, SidebarLayoutHeaderSearch, } from "./sidebar/sidebar-layout-header.js";
+export { SidebarMenu } from "./sidebar/sidebar-menu.js";
+export { SIDEBAR_TRANSITION } from "./sidebar/sidebar-motion-config.js";
+export { SidebarProvider, useSidebar, useSidebarResize, } from "./sidebar/sidebar-provider.js";
+export { Sidebar } from "./sidebar/sidebar-root.js";
+export { SidebarSeparator } from "./sidebar/sidebar-separator.js";
+export { SidebarTrigger } from "./sidebar/sidebar-trigger.js";
+export { SidebarGroupAction } from "./sidebar/sidebar-group.js";
+export { SidebarGroupContent } from "./sidebar/sidebar-group.js";
+export { SidebarGroupLabel } from "./sidebar/sidebar-group.js";
+export { SidebarPanel } from "./sidebar/sidebar-panel.js";
+export { SidebarSkipLink } from "./sidebar/sidebar-skip-link.js";
+export { SidebarMenuAction } from "./sidebar/sidebar-menu-action.js";
+export { SidebarMenuBadge } from "./sidebar/sidebar-menu-badge.js";
+export { SidebarMenuButton } from "./sidebar/sidebar-menu-button.js";
+export { SidebarMenuItem } from "./sidebar/sidebar-menu.js";
+export { SidebarMenuLabel } from "./sidebar/sidebar-menu-label.js";
+export { SidebarMenuSkeleton } from "./sidebar/sidebar-menu-skeleton.js";
+export { SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarMenuSubScrollArea, } from "./sidebar/sidebar-menu-sub.js";
+export { SidebarRail } from "./sidebar/sidebar-trigger.js";

package/dist/compositions/site-footer/site-footer-bar.d.ts

@@ -0,0 +1,37 @@
+import { Anchor } from "@instruments/materia-ui/components/anchor";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import type { SocialNetwork } from "@instruments/materia-ui/components/social-icon";
+import { Text } from "@instruments/materia-ui/components/text";
+import type { ComponentProps } from "react";
+export type SiteFooterBarProps = ComponentProps<typeof Flex>;
+/**
+ * The footer's last row, beneath a rule: the legal line on one side, the
+ * social links on the other. It stacks on a phone.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export declare const SiteFooterBar: ({ className, ...props }: SiteFooterBarProps) => import("react").JSX.Element;
+export type SiteFooterLegalProps = ComponentProps<typeof Text>;
+/**
+ * The copyright line, small and quiet.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export declare const SiteFooterLegal: (props: SiteFooterLegalProps) => import("react").JSX.Element;
+export type SiteFooterSocialProps = ComponentProps<typeof Box>;
+/**
+ * The row of social links.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export declare const SiteFooterSocial: ({ className, ...props }: SiteFooterSocialProps) => import("react").JSX.Element;
+export interface SiteFooterSocialLinkProps extends Omit<ComponentProps<typeof Anchor>, "children" | "icon" | "suffixIcon" | "variant"> {
+    /** The network's name, which names the link. */
+    label: string;
+    /** Which network's mark to draw. */
+    network: SocialNetwork;
+}
+/**
+ * A social profile, drawn as its network's mark in a round target. It opens
+ * in a new tab.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export declare const SiteFooterSocialLink: ({ className, label, network, ...props }: SiteFooterSocialLinkProps) => import("react").JSX.Element;

package/dist/compositions/site-footer/site-footer-bar.js

@@ -0,0 +1,30 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Anchor } from "@instruments/materia-ui/components/anchor";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { SocialIcon } from "@instruments/materia-ui/components/social-icon";
+import { Text } from "@instruments/materia-ui/components/text";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * The footer's last row, beneath a rule: the legal line on one side, the
+ * social links on the other. It stacks on a phone.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export const SiteFooterBar = ({ className, ...props }) => (_jsx(Flex, { className: cn("border-border col-span-full flex-col gap-4 border-t pt-6 sm:flex-row sm:items-center sm:justify-between", className), "data-component": "site-footer-bar", "data-slot": "site-footer-bar", ...props }));
+/**
+ * The copyright line, small and quiet.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export const SiteFooterLegal = (props) => (_jsx(Text, { "data-component": "site-footer-legal", "data-slot": "site-footer-legal", size: "paragraph-sm", variant: "muted", ...props }));
+/**
+ * The row of social links.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export const SiteFooterSocial = ({ className, ...props }) => (_jsx(Box, { as: "ul", className: cn("-mx-3 flex items-center", className), "data-component": "site-footer-social", "data-slot": "site-footer-social", ...props }));
+/**
+ * A social profile, drawn as its network's mark in a round target. It opens
+ * in a new tab.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export const SiteFooterSocialLink = ({ className, label, network, ...props }) => (_jsx(Box, { as: "li", children: _jsx(Anchor, { "aria-label": label, className: cn("text-muted-foreground hover:bg-surface-inset hover:text-foreground inline-flex size-11 items-center justify-center rounded-full transition-colors", className), "data-component": "site-footer-social-link", "data-slot": "site-footer-social-link", rel: "noopener noreferrer", target: "_blank", variant: "plain", ...props, children: _jsx(SocialIcon, { network: network, size: "sm" }) }) }));

package/dist/compositions/site-footer/site-footer-context.d.ts

@@ -0,0 +1,3 @@
+/** True inside a column's list, where each link is a list item. */
+export declare const SiteFooterListContext: import("react").Context<boolean>;
+export declare const useInSiteFooterList: () => boolean;

package/dist/compositions/site-footer/site-footer-context.js

@@ -0,0 +1,5 @@
+"use client";
+import { createContext, useContext } from "react";
+/** True inside a column's list, where each link is a list item. */
+export const SiteFooterListContext = createContext(false);
+export const useInSiteFooterList = () => useContext(SiteFooterListContext);

package/dist/compositions/site-footer/site-footer-root.d.ts

@@ -0,0 +1,80 @@
+import { Anchor } from "@instruments/materia-ui/components/anchor";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Stack } from "@instruments/materia-ui/components/stack";
+import type { ComponentProps, ReactNode } from "react";
+export type SiteFooterProps = ComponentProps<"footer">;
+/**
+ * The page's closing panel: a pitch on one side, the site's links in columns
+ * on the other, and a bar beneath for the legal line and social links. It
+ * sits on the page gutter as one rounded, sunk surface, so it reads as the
+ * end of the page rather than another section of it.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ *
+ * @example
+ * <SiteFooter>
+ *   <SiteFooterLead action={<Button>Join us</Button>} brand={<Logo />} title="Are you a brand?">
+ *     Put your products in front of designers sourcing for their projects.
+ *   </SiteFooterLead>
+ *   <SiteFooterNav>
+ *     <SiteFooterColumn title="Explore">
+ *       <SiteFooterLink href="/products">Products</SiteFooterLink>
+ *     </SiteFooterColumn>
+ *   </SiteFooterNav>
+ *   <SiteFooterBar>
+ *     <SiteFooterLegal>© 2026 Material Bank</SiteFooterLegal>
+ *     <SiteFooterSocial>
+ *       <SiteFooterSocialLink href="https://instagram.com/materialbank" label="Instagram" network="instagram" />
+ *     </SiteFooterSocial>
+ *   </SiteFooterBar>
+ * </SiteFooter>
+ *
+ * @bestPractice Render it after the page's `<main>`, not inside it, so it stays the page's own footer landmark.
+ * @bestPractice Keep it to a lead, one nav and one bar. Four columns of a few links each is the shape it is set for.
+ * @category navigation
+ */
+export declare const SiteFooter: ({ children, className, ...props }: SiteFooterProps) => import("react").JSX.Element;
+export interface SiteFooterLeadProps extends Omit<ComponentProps<typeof Stack>, "children" | "title"> {
+    /** A call to action beneath the description, such as a `Button`. */
+    action?: ReactNode;
+    /** The brand mark above the title, such as a `Logo`. */
+    brand?: ReactNode;
+    /** The pitch's heading. */
+    title: string;
+    /** The pitch's description: one or two sentences. */
+    children?: ReactNode;
+}
+/**
+ * The footer's leading column: the brand, a short pitch and its action.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export declare const SiteFooterLead: ({ action, brand, children, className, title, ...props }: SiteFooterLeadProps) => import("react").JSX.Element;
+export interface SiteFooterNavProps extends ComponentProps<typeof Box> {
+    /** Names the footer's navigation landmark. @default "Footer" */
+    "aria-label"?: string;
+}
+/**
+ * The footer's links, one `SiteFooterColumn` per group: two across on a
+ * phone, four on a tablet, two again beside the lead on a laptop, and four
+ * from a wide screen up.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export declare const SiteFooterNav: ({ "aria-label": ariaLabel, children, className, ...props }: SiteFooterNavProps) => import("react").JSX.Element;
+export interface SiteFooterColumnProps extends Omit<ComponentProps<typeof Stack>, "as" | "children" | "title"> {
+    /** The group's name, shown above its links. */
+    title: string;
+    /** Its `SiteFooterLink`s. */
+    children: ReactNode;
+}
+/**
+ * One group of links under a quiet heading.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export declare const SiteFooterColumn: ({ children, className, title, ...props }: SiteFooterColumnProps) => import("react").JSX.Element;
+export type SiteFooterLinkProps = Omit<ComponentProps<typeof Anchor>, "variant">;
+/**
+ * A link in a footer column, or in the bar beside the legal line. Pass
+ * `render` for a router link. Without an `href` it is a button that looks
+ * like its neighbours, for an action such as opening privacy choices.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export declare const SiteFooterLink: ({ className, href, render, ...props }: SiteFooterLinkProps) => import("react").JSX.Element;

package/dist/compositions/site-footer/site-footer-root.js

@@ -0,0 +1,75 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Anchor } from "@instruments/materia-ui/components/anchor";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Grid } from "@instruments/materia-ui/components/grid";
+import { Heading } from "@instruments/materia-ui/components/heading";
+import { Stack } from "@instruments/materia-ui/components/stack";
+import { Text } from "@instruments/materia-ui/components/text";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useId } from "react";
+import { SiteFooterListContext, useInSiteFooterList, } from "./site-footer-context.js";
+/**
+ * The page's closing panel: a pitch on one side, the site's links in columns
+ * on the other, and a bar beneath for the legal line and social links. It
+ * sits on the page gutter as one rounded, sunk surface, so it reads as the
+ * end of the page rather than another section of it.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ *
+ * @example
+ * <SiteFooter>
+ *   <SiteFooterLead action={<Button>Join us</Button>} brand={<Logo />} title="Are you a brand?">
+ *     Put your products in front of designers sourcing for their projects.
+ *   </SiteFooterLead>
+ *   <SiteFooterNav>
+ *     <SiteFooterColumn title="Explore">
+ *       <SiteFooterLink href="/products">Products</SiteFooterLink>
+ *     </SiteFooterColumn>
+ *   </SiteFooterNav>
+ *   <SiteFooterBar>
+ *     <SiteFooterLegal>© 2026 Material Bank</SiteFooterLegal>
+ *     <SiteFooterSocial>
+ *       <SiteFooterSocialLink href="https://instagram.com/materialbank" label="Instagram" network="instagram" />
+ *     </SiteFooterSocial>
+ *   </SiteFooterBar>
+ * </SiteFooter>
+ *
+ * @bestPractice Render it after the page's `<main>`, not inside it, so it stays the page's own footer landmark.
+ * @bestPractice Keep it to a lead, one nav and one bar. Four columns of a few links each is the shape it is set for.
+ * @category navigation
+ */
+export const SiteFooter = ({ children, className, ...props }) => (_jsx("footer", { className: cn("px-page-gutter pb-page-gutter pt-16", className), "data-component": "site-footer", "data-slot": "site-footer", ...props, children: _jsx(Grid, { className: "bg-surface-sunk rounded-4xl px-8 py-10 md:px-12 md:py-14", columns: { base: 1, lg: 12 }, xGap: "xl", yGap: "2xl", children: children }) }));
+/**
+ * The footer's leading column: the brand, a short pitch and its action.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export const SiteFooterLead = ({ action, brand, children, className, title, ...props }) => (_jsxs(Stack, { align: "flex-start", className: cn("lg:col-span-4", className), "data-component": "site-footer-lead", "data-slot": "site-footer-lead", gap: "lg", ...props, children: [brand, _jsxs(Stack, { className: "max-w-sm", gap: "xs", children: [_jsx(Heading, { level: "2", size: "subheading", children: title }), children === undefined ? null : (_jsx(Text, { size: "paragraph-sm", variant: "muted", children: children }))] }), action] }));
+/**
+ * The footer's links, one `SiteFooterColumn` per group: two across on a
+ * phone, four on a tablet, two again beside the lead on a laptop, and four
+ * from a wide screen up.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export const SiteFooterNav = ({ "aria-label": ariaLabel = "Footer", children, className, ...props }) => (_jsx(Box, { "aria-label": ariaLabel, as: "nav", className: cn("lg:col-span-8 lg:col-start-5", className), "data-component": "site-footer-nav", "data-slot": "site-footer-nav", ...props, children: _jsx(Grid, { align: "flex-start", columns: { base: 2, lg: 2, sm: 4, xl: 4 }, xGap: "lg", yGap: "xl", children: children }) }));
+/**
+ * One group of links under a quiet heading.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export const SiteFooterColumn = ({ children, className, title, ...props }) => {
+    const headingId = useId();
+    return (_jsxs(Stack, { "aria-labelledby": headingId, as: "section", className: cn("min-w-0", className), "data-component": "site-footer-column", "data-slot": "site-footer-column", gap: "xs", ...props, children: [_jsx(Heading, { className: "text-paragraph-sm text-muted-foreground font-normal", id: headingId, level: "2", size: "paragraph-lg", children: title }), _jsx(Stack, { as: "ul", gap: "none", children: _jsx(SiteFooterListContext, { value: true, children: children }) })] }));
+};
+// The host for a footer link with no destination: Anchor renders through it
+// and passes its label and styles along.
+const ActionButton = (props) => (_jsx("button", { type: "button", ...props }));
+/**
+ * A link in a footer column, or in the bar beside the legal line. Pass
+ * `render` for a router link. Without an `href` it is a button that looks
+ * like its neighbours, for an action such as opening privacy choices.
+ * Import from "@instruments/materia-ui/compositions/site-footer".
+ */
+export const SiteFooterLink = ({ className, href, render, ...props }) => {
+    const inList = useInSiteFooterList();
+    const link = (_jsx(Anchor, { href: href, render: render ?? (href === undefined ? _jsx(ActionButton, {}) : undefined), className: cn("text-paragraph-sm inline-flex min-h-11 items-center text-start text-nowrap", className), "data-component": "site-footer-link", "data-slot": "site-footer-link", variant: "plain", ...props }));
+    return inList ? _jsx(Box, { as: "li", children: link }) : link;
+};

package/dist/compositions/site-footer.d.ts

@@ -0,0 +1,2 @@
+export { SiteFooterBar, type SiteFooterBarProps, SiteFooterLegal, type SiteFooterLegalProps, SiteFooterSocial, SiteFooterSocialLink, type SiteFooterSocialLinkProps, type SiteFooterSocialProps, } from "./site-footer/site-footer-bar.js";
+export { SiteFooter, SiteFooterColumn, type SiteFooterColumnProps, SiteFooterLead, type SiteFooterLeadProps, SiteFooterLink, type SiteFooterLinkProps, SiteFooterNav, type SiteFooterNavProps, type SiteFooterProps, } from "./site-footer/site-footer-root.js";

package/dist/compositions/site-footer.js

@@ -0,0 +1,2 @@
+export { SiteFooterBar, SiteFooterLegal, SiteFooterSocial, SiteFooterSocialLink, } from "./site-footer/site-footer-bar.js";
+export { SiteFooter, SiteFooterColumn, SiteFooterLead, SiteFooterLink, SiteFooterNav, } from "./site-footer/site-footer-root.js";

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

@@ -0,0 +1,33 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { SwatchFanImageProps, SwatchFanItem, SwatchFanSize, SwatchFanVariant } from "./swatch-fan-types.js";
+declare const ROTATION_DEG = 8;
+declare const HOVER_SHIFT = 3;
+declare const HOVER_ROTATE = 1;
+interface SwatchFanCardsProps {
+    animateOnMount: boolean;
+    /** `breathe` enables the hover nudge; `none` is fully static. */
+    breathe: boolean;
+    bordered: boolean;
+    cardBorderWidth: number;
+    cardRadius: number;
+    cardShadow: string;
+    className?: string | undefined;
+    hovered?: boolean | undefined;
+    hoverRotate: number;
+    hoverShift: number;
+    items: SwatchFanItem[];
+    mountDelay?: number | undefined;
+    overlap?: number | undefined;
+    renderImage: (props: SwatchFanImageProps) => ReactNode;
+    rotationDeg: number;
+    size: SwatchFanSize;
+    style?: CSSProperties | undefined;
+    variant: SwatchFanVariant;
+    wrapperSize?: number | undefined;
+}
+/**
+ * Card engine - the fixed 3-tile fan: Figma geometry, z-order, variant
+ * morphing, and mount/breathe motion. Maps `items[0..2]` → left/center/right.
+ */
+declare const SwatchFanCards: ({ animateOnMount, breathe, bordered, cardBorderWidth, cardRadius, cardShadow, className, hovered, hoverRotate, hoverShift, items, mountDelay, overlap, renderImage, rotationDeg, size, style, variant, wrapperSize, }: SwatchFanCardsProps) => import("react").JSX.Element;
+export { HOVER_ROTATE, HOVER_SHIFT, ROTATION_DEG, SwatchFanCards };

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

@@ -0,0 +1,251 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { durations, springs } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useReducedMotion } from "motion/react";
+import * as m from "motion/react-m";
+import { useEffect, useState } from "react";
+import { swatchTileSizePx } from "../../tokens/swatch.js";
+import { asMotionStyle } from "../../utils/motion-style.js";
+import { SwatchFanTile } from "./swatch-fan-tile.js";
+// =============================================================================
+// LAYOUT CALCULATIONS - Figma-canon geometry.
+// =============================================================================
+const ROTATION_DEG = 8;
+const getWrapperRatio = (rotationDeg) => {
+    const rotRad = (rotationDeg * Math.PI) / 180;
+    return Math.cos(rotRad) + Math.sin(rotRad);
+};
+/**
+ * Spread variant - cards overlap heavily with tight gaps, right card on top.
+ * Overlap ratio 0.856 (Figma: 83px overlap / 97px card).
+ */
+const getSpreadLayout = (cardSize, rotationDeg, overrides = {}) => {
+    const wrapperSize = overrides.wrapperSize ?? Math.ceil(cardSize * getWrapperRatio(rotationDeg));
+    const overlap = overrides.overlap ?? Math.ceil(cardSize * 0.856);
+    const centerTop = Math.round((wrapperSize - cardSize) / 2);
+    const centerLeft = wrapperSize - overlap;
+    const rightLeft = centerLeft + cardSize - overlap;
+    return {
+        outerHeight: wrapperSize,
+        outerWidth: rightLeft + wrapperSize,
+        positions: {
+            center: { left: centerLeft, rotation: 0, top: centerTop, zIndex: 2 },
+            left: { left: 0, rotation: -rotationDeg, top: 0, zIndex: 1 },
+            right: { left: rightLeft, rotation: rotationDeg, top: 0, zIndex: 3 },
+        },
+        wrapperSize,
+    };
+};
+/**
+ * Stack variant - center prominent, two cards peeking from sides. Overlap ratio
+ * 0.65.
+ */
+const getStackLayout = (cardSize, rotationDeg, overrides = {}) => {
+    const wrapperSize = overrides.wrapperSize ?? Math.ceil(cardSize * getWrapperRatio(rotationDeg));
+    const overlap = overrides.overlap ?? Math.ceil(cardSize * 0.65);
+    const centerTop = Math.round((wrapperSize - cardSize) / 2);
+    const centerLeft = wrapperSize - overlap;
+    const rightLeft = centerLeft + cardSize - overlap;
+    return {
+        outerHeight: wrapperSize,
+        outerWidth: rightLeft + wrapperSize,
+        positions: {
+            center: { left: centerLeft, rotation: 0, top: centerTop, zIndex: 3 },
+            left: { left: 0, rotation: -rotationDeg, top: 0, zIndex: 2 },
+            right: { left: rightLeft, rotation: rotationDeg, top: 0, zIndex: 1 },
+        },
+        wrapperSize,
+    };
+};
+const FanCard = ({ animate, bordered, cardBorderWidth, cardRadius, cardShadow, initialPosition, item, position, renderImage, size, sizePx, transition, wrapperSize, }) => {
+    const startFrom = animate ? initialPosition : undefined;
+    const needsWrapper = position.rotation !== 0 || (initialPosition?.rotation ?? 0) !== 0;
+    const cardElement = (_jsx(SwatchFanTile, { bordered: bordered, item: item, renderImage: renderImage, size: size, sizePx: sizePx, style: {
+            borderRadius: cardRadius,
+            // Only the white card mount carries a border. Hairline tiles must not
+            // inherit Tailwind preflight's default (grey, solid) border via a
+            // forced width - that renders an unwanted 3px frame on `bordered={false}`.
+            borderWidth: bordered ? cardBorderWidth : 0,
+            boxShadow: cardShadow,
+        } }));
+    if (needsWrapper) {
+        return (_jsx(m.div, { animate: {
+                x: position.left,
+                y: position.top,
+                zIndex: position.zIndex,
+            }, className: "absolute top-0 left-0 flex items-center justify-center", "data-slot": "swatch-fan-card", initial: startFrom
+                ? {
+                    x: startFrom.left,
+                    y: startFrom.top,
+                    zIndex: startFrom.zIndex,
+                }
+                : false, style: { height: wrapperSize, width: wrapperSize }, transition: transition, children: _jsx(m.div, { animate: { rotate: position.rotation, scale: position.scale ?? 1 }, initial: startFrom
+                    ? {
+                        rotate: startFrom.rotation,
+                        scale: startFrom.scale ?? 1,
+                    }
+                    : false, transition: transition, children: cardElement }) }));
+    }
+    return (_jsx(m.div, { animate: {
+            scale: position.scale ?? 1,
+            x: position.left,
+            y: position.top,
+            zIndex: position.zIndex,
+        }, className: "absolute top-0 left-0", "data-slot": "swatch-fan-card", initial: startFrom
+            ? {
+                scale: startFrom.scale ?? 1,
+                x: startFrom.left,
+                y: startFrom.top,
+                zIndex: startFrom.zIndex,
+            }
+            : false, transition: transition, children: cardElement }));
+};
+// Hover nudge: side cards shift outward and rotate slightly more.
+const HOVER_SHIFT = 3;
+const HOVER_ROTATE = 1;
+const HOVER_LIFT = 1;
+const isNamedTileSize = (size) => Object.hasOwn(swatchTileSizePx, size);
+const getCardSizePx = (size) => isNamedTileSize(size) ? swatchTileSizePx[size] : size;
+const getNudgedPositions = (positions, hoverShift = HOVER_SHIFT, hoverRotate = HOVER_ROTATE) => ({
+    center: {
+        ...positions.center,
+        top: positions.center.top - HOVER_LIFT,
+    },
+    left: {
+        ...positions.left,
+        left: positions.left.left - hoverShift,
+        rotation: positions.left.rotation - hoverRotate,
+    },
+    right: {
+        ...positions.right,
+        left: positions.right.left + hoverShift,
+        rotation: positions.right.rotation + hoverRotate,
+    },
+});
+const getStackedInitialPositions = (layout) => {
+    const { left: centerLeft, top: centerTop } = layout.positions.center;
+    return {
+        center: {
+            left: centerLeft,
+            rotation: 0,
+            top: centerTop,
+            zIndex: layout.positions.center.zIndex,
+        },
+        left: {
+            left: centerLeft,
+            rotation: 0,
+            scale: 0.98,
+            top: centerTop,
+            zIndex: layout.positions.left.zIndex,
+        },
+        right: {
+            left: centerLeft,
+            rotation: 0,
+            scale: 0.98,
+            top: centerTop,
+            zIndex: layout.positions.right.zIndex,
+        },
+    };
+};
+/** Cards always render in the same left → center → right DOM order. */
+const SIDES = ["left", "center", "right"];
+/** Defer the mount flag by `mountDelay` seconds (0/undefined = mounted). */
+const useMountDelay = (mountDelay) => {
+    const [hasMounted, setHasMounted] = useState((mountDelay ?? 0) === 0);
+    useEffect(() => {
+        if (mountDelay === undefined || mountDelay === 0) {
+            return () => {
+                // no delay; nothing to clean up
+            };
+        }
+        const id = setTimeout(() => {
+            setHasMounted(true);
+        }, mountDelay * 1000);
+        return () => {
+            clearTimeout(id);
+        };
+    }, [mountDelay]);
+    return hasMounted;
+};
+const getFanLayout = (variant, cardSize, rotationDeg, overrides = {}) => variant === "spread"
+    ? getSpreadLayout(cardSize, rotationDeg, overrides)
+    : getStackLayout(cardSize, rotationDeg, overrides);
+const resolveFanPositions = ({ animateOnHover, animateOnMount, hasMounted, hoverRotate, hoverShift, hovered, isHovered, layout, }) => {
+    const fanned = layout.positions;
+    const stacked = animateOnMount ? getStackedInitialPositions(layout) : fanned;
+    const isEffectivelyHovered = hovered ?? isHovered;
+    const hoveredPositions = animateOnHover && isEffectivelyHovered
+        ? getNudgedPositions(fanned, hoverShift, hoverRotate)
+        : fanned;
+    const positions = animateOnMount && !hasMounted ? stacked : hoveredPositions;
+    return { positions, stacked };
+};
+/**
+ * Collapse the mount fan-out and hover nudge, and snap card springs to an
+ * instant transition, when the user prefers reduced motion (WCAG 2.3.3).
+ */
+const resolveFanMotion = (shouldReduceMotion, animateOnMount, animateOnHover) => {
+    const reduceMotion = shouldReduceMotion === true;
+    return {
+        cardTransition: reduceMotion
+            ? { duration: durations.instant }
+            : springs.swift,
+        shouldAnimateOnHover: animateOnHover && !reduceMotion,
+        shouldAnimateOnMount: animateOnMount && !reduceMotion,
+    };
+};
+/**
+ * Card engine - the fixed 3-tile fan: Figma geometry, z-order, variant
+ * morphing, and mount/breathe motion. Maps `items[0..2]` → left/center/right.
+ */
+const SwatchFanCards = ({ animateOnMount, breathe, bordered, cardBorderWidth, cardRadius, cardShadow, className, hovered, hoverRotate, hoverShift, items, mountDelay, overlap, renderImage, rotationDeg, size, style, variant, wrapperSize, }) => {
+    const [isHovered, setIsHovered] = useState(false);
+    const hasMounted = useMountDelay(mountDelay);
+    const shouldReduceMotion = useReducedMotion();
+    const { cardTransition, shouldAnimateOnHover, shouldAnimateOnMount } = resolveFanMotion(shouldReduceMotion, animateOnMount, breathe);
+    const cardSizePx = getCardSizePx(size);
+    const layout = getFanLayout(variant, cardSizePx, rotationDeg, {
+        overlap,
+        wrapperSize,
+    });
+    const { positions, stacked } = resolveFanPositions({
+        animateOnHover: shouldAnimateOnHover,
+        animateOnMount: shouldAnimateOnMount,
+        hasMounted,
+        hoverRotate,
+        hoverShift,
+        hovered,
+        isHovered,
+        layout,
+    });
+    const animate = shouldAnimateOnMount || shouldAnimateOnHover;
+    // The consumer `style` merges over the computed layout box (height/width);
+    // asMotionStyle bridges the plain CSSProperties to motion's MotionStyle.
+    const outerStyle = {
+        height: layout.outerHeight,
+        width: layout.outerWidth,
+        ...style,
+    };
+    const trio = {
+        center: items[1],
+        left: items[0],
+        right: items[2],
+    };
+    return (_jsx(m.div, { className: cn("relative", className), "data-slot": "swatch-fan", "data-variant": variant, onMouseEnter: shouldAnimateOnHover
+            ? () => {
+                setIsHovered(true);
+            }
+            : undefined, onMouseLeave: shouldAnimateOnHover
+            ? () => {
+                setIsHovered(false);
+            }
+            : undefined, style: asMotionStyle(outerStyle), children: SIDES.map((side) => {
+            const item = trio[side];
+            if (item === undefined) {
+                return null;
+            }
+            return (_jsx(FanCard, { animate: animate, bordered: bordered, cardBorderWidth: cardBorderWidth, cardRadius: cardRadius, cardShadow: cardShadow, initialPosition: shouldAnimateOnMount ? stacked[side] : undefined, item: item, position: positions[side], renderImage: renderImage, size: size, sizePx: cardSizePx, transition: cardTransition, wrapperSize: layout.wrapperSize }, side));
+        }) }));
+};
+export { HOVER_ROTATE, HOVER_SHIFT, ROTATION_DEG, SwatchFanCards };

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

@@ -0,0 +1,29 @@
+import type { PointerEvent } from "react";
+/** Inputs the engine reads on every frame; refreshed by the owning hook. */
+export interface SwatchFanEngineConfig {
+    /** Own the fan state via hover/focus; otherwise only `fanned` drives it. */
+    fanOnHover: boolean;
+    /** Number of tiles the frame math lays out. */
+    itemCount: number;
+    onFannedChange: ((fanned: boolean) => void) | undefined;
+    /** Snap straight to the settled frame instead of easing. */
+    reducedMotion: boolean;
+}
+/**
+ * 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 declare const createSwatchFanEngine: () => {
+    applyCurrent: () => void;
+    configure: (next: SwatchFanEngineConfig) => void;
+    handlePointerEnter: () => void;
+    handlePointerLeave: () => void;
+    handlePointerMove: (event: PointerEvent<HTMLSpanElement>) => void;
+    setCard: (node: HTMLSpanElement | null) => void;
+    setSwatch: (index: number, node: HTMLSpanElement | null) => void;
+    /** Adopt the controlled `fanned` value without notifying the owner. */
+    syncFanned: (nextFanned: boolean) => void;
+    stop: () => void;
+};
+export type SwatchFanEngine = ReturnType<typeof createSwatchFanEngine>;