@instruments/materia-ui 0.1.0

package/dist/compositions/product-card/product-card-root.d.ts

@@ -0,0 +1,39 @@
+import type { ProductCardProps } from "./product-card-types.js";
+declare const ProductCardBase: ({ className, product, variantId, mode, width, active, dragging, availability, labels, showActivePointer, similarityScore, overrideImageUrl, priority, showSwatches, showAddToCart, productNameLines, showProductBrand, showProductName, maxSwatches, menuOpen, onAdd, addGlyph, onFindSimilar, price, processing, onCardClick, onVariantChange, linkAs, productUrl, linkPrefetch, renderTools, renderImage, renderAddToCart, dragAdapter, action, primaryAction, statusBadge, onQuickView, onAddToCartSuccess, ...props }: ProductCardProps & {
+    onAddToCartSuccess?: (() => void) | undefined;
+}) => import("react").JSX.Element;
+/**
+ * Shared ProductCard component.
+ *
+ * This is a presentational component that accepts handlers via props
+ * for app-specific behaviour (sidepanels, stores, navigation).
+ *
+ * @example Basic usage
+ * ```tsx
+ * <ProductCard
+ *   product={product}
+ *   onCardClick={() => router.push(`/products/${product.slug}`)}
+ * />
+ * ```
+ *
+ * @example With app-specific tools
+ * ```tsx
+ * <ProductCard
+ *   product={product}
+ *   renderTools={({ productId }) => (
+ *     <>
+ *       <SaveButton productId={productId} />
+ *       <ShareButton productId={productId} />
+ *     </>
+ *   )}
+ * />
+ * ```
+ *
+ * @bestPractice In Next.js apps pass `renderImage` wrapping `next/image` and
+ * `linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.
+ * @bestPractice Cart UI renders only when a `renderAddToCart` slot is
+ * provided; keep `dragAdapter` referentially stable (module-level constant).
+ * @category catalogue
+ */
+export declare const ProductCard: import("react").MemoExoticComponent<typeof ProductCardBase>;
+export {};

package/dist/compositions/product-card/product-card-root.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { memo } from "react";
+import { ProductCardContent } from "./product-card-content.js";
+import { ProductCardProvider } from "./product-card-provider.js";
+const ProductCardBase = ({ className, product, variantId, mode = "group", width, active = false, dragging, availability, labels, showActivePointer, similarityScore, overrideImageUrl, priority, showSwatches, showAddToCart, productNameLines, showProductBrand, showProductName, maxSwatches, menuOpen, onAdd, addGlyph, onFindSimilar, price, processing, onCardClick, onVariantChange, linkAs, productUrl, linkPrefetch, renderTools, renderImage, renderAddToCart, dragAdapter, action, primaryAction, statusBadge, onQuickView, onAddToCartSuccess, ...props }) => (_jsx(ProductCardProvider, { action: action, display: {
+        addToCart: showAddToCart,
+        brand: showProductBrand,
+        name: showProductName,
+        nameLines: productNameLines,
+        swatches: showSwatches,
+    }, dragAdapter: dragAdapter, active: active, addGlyph: addGlyph, availability: availability, dragging: dragging, labels: labels, linkAs: linkAs, linkPrefetch: linkPrefetch, maxSwatches: maxSwatches, menuOpen: menuOpen, mode: mode, onAdd: onAdd, onCardClick: onCardClick, onFindSimilar: onFindSimilar, onQuickView: onQuickView, onVariantChange: onVariantChange, price: price, primaryAction: primaryAction, processing: processing, product: product, productUrl: productUrl, renderAddToCart: renderAddToCart, renderImage: renderImage, renderTools: renderTools, showActivePointer: showActivePointer, statusBadge: statusBadge, variantId: variantId, width: width, children: _jsx(ProductCardContent, { className: className, onAddToCartSuccess: onAddToCartSuccess, overrideImageUrl: overrideImageUrl, priority: priority, similarityScore: similarityScore, ...props }) }));
+/**
+ * Shared ProductCard component.
+ *
+ * This is a presentational component that accepts handlers via props
+ * for app-specific behaviour (sidepanels, stores, navigation).
+ *
+ * @example Basic usage
+ * ```tsx
+ * <ProductCard
+ *   product={product}
+ *   onCardClick={() => router.push(`/products/${product.slug}`)}
+ * />
+ * ```
+ *
+ * @example With app-specific tools
+ * ```tsx
+ * <ProductCard
+ *   product={product}
+ *   renderTools={({ productId }) => (
+ *     <>
+ *       <SaveButton productId={productId} />
+ *       <ShareButton productId={productId} />
+ *     </>
+ *   )}
+ * />
+ * ```
+ *
+ * @bestPractice In Next.js apps pass `renderImage` wrapping `next/image` and
+ * `linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.
+ * @bestPractice Cart UI renders only when a `renderAddToCart` slot is
+ * provided; keep `dragAdapter` referentially stable (module-level constant).
+ * @category catalogue
+ */
+export const ProductCard = memo(ProductCardBase);

package/dist/compositions/product-card/product-card-skeleton.d.ts

@@ -0,0 +1,28 @@
+import type { CSSProperties } from "react";
+interface ProductCardSkeletonProps {
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Loading placeholder for `ProductCard`, at whatever size it is given.
+ *
+ * **It switches arms on its OWN width, exactly as the card does**, rather than
+ * leaving the caller to pick between a small and a large placeholder. Callers
+ * were picking from the wrong signal: `CardGridSkeletonItem` keyed off the
+ * GRID's width, but the grid's phone tier is a fluid 2-up, so a 460px container
+ * renders 222px cards - the main arm - and got the compact placeholder. There
+ * is one skeleton now, and no width for a caller to guess.
+ *
+ * It carries the arms' own classes rather than a transcription of their
+ * measured heights: the same `@container/product-card` name, the same image
+ * frame (full-bleed below 180px, `px-4 pt-4` around a square flush with the
+ * frame's bottom above it), the same padding, gaps and radius steps. Copying
+ * the classes keeps it in step as the card changes.
+ *
+ * It draws the control unconditionally. A card whose product has no capability
+ * renders none, so the placeholder overshoots that case - the reverse error, a
+ * placeholder shorter than every card that does have one, misjudged the common
+ * case instead.
+ */
+export declare const ProductCardSkeleton: ({ className, style, }: ProductCardSkeletonProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/product-card/product-card-skeleton.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Skeleton } from "@instruments/materia-ui/components/skeleton";
+import { HStack, VStack } from "@instruments/materia-ui/components/stack";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/** The fifth dot, which the card itself only shows from 240px up. */
+const SWATCH_PLACEHOLDERS = [0, 1, 2, 3, 4];
+const SwatchRow = () => (_jsx(HStack, { className: "min-h-5 gap-2.5", children: SWATCH_PLACEHOLDERS.map((index) => (_jsx(Skeleton, { className: cn("size-5 rounded-full", index === SWATCH_PLACEHOLDERS.length - 1 &&
+            "hidden @[240px]/product-card:block"), variant: "light" }, index))) }));
+/**
+ * Loading placeholder for `ProductCard`, at whatever size it is given.
+ *
+ * **It switches arms on its OWN width, exactly as the card does**, rather than
+ * leaving the caller to pick between a small and a large placeholder. Callers
+ * were picking from the wrong signal: `CardGridSkeletonItem` keyed off the
+ * GRID's width, but the grid's phone tier is a fluid 2-up, so a 460px container
+ * renders 222px cards - the main arm - and got the compact placeholder. There
+ * is one skeleton now, and no width for a caller to guess.
+ *
+ * It carries the arms' own classes rather than a transcription of their
+ * measured heights: the same `@container/product-card` name, the same image
+ * frame (full-bleed below 180px, `px-4 pt-4` around a square flush with the
+ * frame's bottom above it), the same padding, gaps and radius steps. Copying
+ * the classes keeps it in step as the card changes.
+ *
+ * It draws the control unconditionally. A card whose product has no capability
+ * renders none, so the placeholder overshoots that case - the reverse error, a
+ * placeholder shorter than every card that does have one, misjudged the common
+ * case instead.
+ */
+export const ProductCardSkeleton = ({ className, style, }) => (_jsxs(Box, { className: cn("@container/product-card w-full", className), style: style, children: [_jsxs(VStack, { className: "flex @[180px]/product-card:hidden", gap: "none", children: [_jsx(Skeleton, { className: "aspect-square w-full rounded-3xl" }), _jsxs(VStack, { className: "gap-2.5 px-1.5 py-2", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { className: "gap-0.5", gap: "none", children: [_jsx(Skeleton, { className: "h-5 w-3/5" }), _jsx(Skeleton, { className: "h-4 w-4/5" })] }), _jsx(Skeleton, { className: "h-4 w-2/3" }), _jsx(SwatchRow, {})] }), _jsx(Skeleton, { className: "h-9 w-full rounded-full" })] })] }), _jsxs(VStack, { className: "bg-card hidden overflow-hidden rounded-3xl shadow-xs @[180px]/product-card:flex @[240px]/product-card:rounded-4xl", gap: "none", children: [_jsx(Box, { className: "w-full px-4 pt-4", children: _jsx(Skeleton, { className: "aspect-square w-full rounded-2xl", variant: "light" }) }), _jsx(VStack, { className: "pt-2 pb-4", gap: "none", children: _jsxs(VStack, { className: "gap-2.5 px-4 @[240px]/product-card:gap-4", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { gap: "none", children: [_jsx(Skeleton, { className: "h-5.5 w-3/5 rounded", variant: "light" }), _jsx(Skeleton, { className: "h-5 w-4/5 rounded", variant: "light" })] }), _jsx(Skeleton, { className: "h-4 w-2/3 rounded", variant: "light" }), _jsx(Box, { className: "pt-1", children: _jsx(SwatchRow, {}) })] }), _jsx(HStack, { children: _jsx(Skeleton, { className: "h-9 w-full rounded-full @[240px]/product-card:w-32", variant: "light" }) })] }) })] })] }));

package/dist/compositions/product-card/product-card-standard-content.d.ts

@@ -0,0 +1,17 @@
+import { Box } from "@instruments/materia-ui/components/box";
+import type { ComponentProps, ReactNode } from "react";
+import type { useToolsActivity } from "./product-card-tools-activity.js";
+interface ProductCardStandardContentProps {
+    cardProps: ComponentProps<typeof Box>;
+    className?: string | undefined;
+    compactFooterControl: ReactNode;
+    footerControl: ReactNode;
+    interactionHandlers: ReturnType<typeof useToolsActivity>["interactionHandlers"];
+    overrideImageUrl?: string | undefined;
+    priority?: boolean | undefined;
+    similarityScore?: number | undefined;
+    toolsActive: boolean;
+}
+/** The group, single, compact and swatch-less layouts: compact arm plus full arm. */
+export declare const ProductCardStandardContent: ({ cardProps, className, compactFooterControl, footerControl, interactionHandlers, overrideImageUrl, priority, similarityScore, toolsActive, }: ProductCardStandardContentProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/product-card/product-card-standard-content.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ProductCardCompactArm } from "./product-card-compact-arm.js";
+import { useProductCard } from "./product-card-context.js";
+import { ProductCardFullArm } from "./product-card-full-arm.js";
+/** The pointer that ties an active card to the panel it opens. */
+const ActivePointer = () => (_jsx(Box, { className: "-mt-px hidden justify-center @[180px]/product-card:flex", children: _jsx("svg", { "aria-hidden": "true", className: "text-card", fill: "none", height: "13", viewBox: "-2 -2 32 17", width: "28", children: _jsx("path", { d: "M0 0 L28 0 L14 13 Z", fill: "currentColor", stroke: "currentColor", strokeLinejoin: "round", strokeWidth: "4" }) }) }));
+/** The group, single, compact and swatch-less layouts: compact arm plus full arm. */
+export const ProductCardStandardContent = ({ cardProps, className, compactFooterControl, footerControl, interactionHandlers, overrideImageUrl, priority, similarityScore, toolsActive, }) => {
+    const { active, showActivePointer, width } = useProductCard();
+    const hasFixedWidth = width !== undefined && width !== 0;
+    return (_jsxs(Box, { className: cn(
+        // A column so the active pointer stays in flow BELOW the card rather
+        // than overflowing the cell: the card grows into the row's height and
+        // the pointer keeps its own.
+        "@container/product-card flex h-full flex-col", hasFixedWidth ? "shrink-0" : "w-full", className), style: hasFixedWidth ? { width: `${width}px` } : undefined, children: [_jsxs(Box, { className: "group min-h-0 w-full flex-1", "data-component": "product-card", "data-testid": "product-card", ...cardProps, ...interactionHandlers, children: [_jsx(ProductCardCompactArm, { compactFooterControl: compactFooterControl, overrideImageUrl: overrideImageUrl, priority: priority, similarityScore: similarityScore, toolsActive: toolsActive }), _jsx(ProductCardFullArm, { footerControl: footerControl, overrideImageUrl: overrideImageUrl, priority: priority, similarityScore: similarityScore, toolsActive: toolsActive })] }), active && showActivePointer ? _jsx(ActivePointer, {}) : null] }));
+};

package/dist/compositions/product-card/product-card-status-badge.d.ts

@@ -0,0 +1,10 @@
+import type { ProductCardStatusBadgeProps } from "./product-card-types.js";
+/**
+ * ProductCardStatusBadge - optional overlay badge on the image (e.g. "New").
+ *
+ * Prop-driven and off by default: rendered by the card only when a
+ * `statusBadge` prop is supplied. Positioned 22px from the card corner (Figma
+ * `36.08 ÷ 1.64`), i.e. 6px inside the 16px-inset photo. Non-interactive so
+ * it never blocks the card's primary link.
+ */
+export declare const ProductCardStatusBadge: ({ className, icon, label, tone, }: ProductCardStatusBadgeProps) => import("react").JSX.Element | null;

package/dist/compositions/product-card/product-card-status-badge.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge } from "@instruments/materia-ui/components/badge";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { Tooltip, TooltipContent, TooltipTrigger, } from "@instruments/materia-ui/components/tooltip";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * ProductCardStatusBadge - optional overlay badge on the image (e.g. "New").
+ *
+ * Prop-driven and off by default: rendered by the card only when a
+ * `statusBadge` prop is supplied. Positioned 22px from the card corner (Figma
+ * `36.08 ÷ 1.64`), i.e. 6px inside the 16px-inset photo. Non-interactive so
+ * it never blocks the card's primary link.
+ */
+export const ProductCardStatusBadge = ({ className, icon, label, tone = "brand", }) => {
+    if (label === undefined || label === null || label === "") {
+        return null;
+    }
+    if (icon) {
+        return (_jsxs(Tooltip, { children: [_jsx(TooltipTrigger, { render: _jsx(Box, { "aria-label": label, as: "span", className: cn(focusRing(), "text-muted-foreground duration-fast hover:text-foreground mt-0.5 flex size-7 shrink-0 cursor-default items-center justify-center rounded-full border border-gray-200 bg-white/80 shadow-xs backdrop-blur-md transition-colors", className), 
+                        // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- a labelled group of decorative children, which `<img>` cannot host
+                        role: "img", tabIndex: 0 }), children: _jsx(Icon, { icon: icon, size: "2xs" }) }), _jsx(TooltipContent, { side: "top", sideOffset: 4, children: label })] }));
+    }
+    return (_jsx(Box, { className: "pointer-events-none absolute top-5.5 left-5.5 z-20", children: _jsx(Badge, { tone: tone, children: label }) }));
+};

package/dist/compositions/product-card/product-card-swatch-add.d.ts

@@ -0,0 +1,14 @@
+import type { ProductCardSwatchAddProps } from "./product-card-types.js";
+/**
+ * The swatch tile's circular add / suggest control, pinned to the image's
+ * top-right. It shows on tile hover or keyboard focus, and stays visible while
+ * `menuOpen` so the close affordance survives the pointer leaving. Selection
+ * alone does not reveal it, but turns it brand-toned once it is visible.
+ *
+ * Reveal follows an ancestor named `group`; outside a tile, pass
+ * `className="opacity-100"`. It anchors to the nearest positioned ancestor.
+ *
+ * Without `onAdd` it is presentational: inert and hidden from assistive
+ * technology, so the tile's own click still selects.
+ */
+export declare const ProductCardSwatchAdd: ({ active, className, glyph, labels, menuOpen, onAdd, }: ProductCardSwatchAddProps) => import("react").JSX.Element;

package/dist/compositions/product-card/product-card-swatch-add.js

@@ -0,0 +1,51 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Button } from "@instruments/materia-ui/components/button";
+import { Minus, Plus, Sparkle } from "@instruments/materia-ui/icons";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { createContext, useContext, useMemo } from "react";
+const COLLAPSED_GLYPHS = { plus: Plus, spark: Sparkle };
+/**
+ * Button's icon-only sizes need a STABLE icon component, and swapping the
+ * glyph component itself would replay Button's vertical icon slide. The glyph
+ * therefore travels through context and this one component renders it.
+ */
+const SwatchAddGlyphContext = createContext({ glyph: "spark", menuOpen: false });
+const SwatchAddGlyph = (props) => {
+    const { glyph, menuOpen } = useContext(SwatchAddGlyphContext);
+    const Glyph = menuOpen ? Minus : COLLAPSED_GLYPHS[glyph];
+    return _jsx(Glyph, { ...props });
+};
+SwatchAddGlyph.displayName = "SwatchAddGlyph";
+const swatchAddLabel = ({ glyph, labels, menuOpen, }) => {
+    if (menuOpen) {
+        return labels?.closeSuggestions ?? "Close suggestions";
+    }
+    return glyph === "plus"
+        ? (labels?.add ?? "Add to board")
+        : (labels?.suggest ?? "Suggest an action");
+};
+/**
+ * The swatch tile's circular add / suggest control, pinned to the image's
+ * top-right. It shows on tile hover or keyboard focus, and stays visible while
+ * `menuOpen` so the close affordance survives the pointer leaving. Selection
+ * alone does not reveal it, but turns it brand-toned once it is visible.
+ *
+ * Reveal follows an ancestor named `group`; outside a tile, pass
+ * `className="opacity-100"`. It anchors to the nearest positioned ancestor.
+ *
+ * Without `onAdd` it is presentational: inert and hidden from assistive
+ * technology, so the tile's own click still selects.
+ */
+export const ProductCardSwatchAdd = ({ active = false, className, glyph = "spark", labels, menuOpen = false, onAdd, }) => {
+    const interactive = onAdd !== undefined;
+    const brand = active || menuOpen;
+    const glyphValue = useMemo(() => ({ glyph, menuOpen }), [glyph, menuOpen]);
+    const handleClick = (e) => {
+        // The tile may select on click; this control only adds.
+        e.stopPropagation();
+        onAdd?.();
+    };
+    return (_jsx(Box, { "aria-hidden": interactive ? undefined : true, className: cn("absolute top-1 right-1 z-20 flex size-8 items-center justify-center", !interactive && "pointer-events-none"), inert: interactive ? undefined : true, children: _jsx(SwatchAddGlyphContext.Provider, { value: glyphValue, children: _jsx(Button, { "aria-expanded": interactive ? menuOpen : undefined, "aria-label": swatchAddLabel({ glyph, labels, menuOpen }), className: cn("group-hover:opacity-100 group-has-focus-visible:opacity-100", menuOpen ? "opacity-100" : "opacity-0", className), emphasis: brand ? "solid" : "outline", icon: SwatchAddGlyph, onClick: handleClick, radius: "full", size: "icon-sm", square: true, tone: brand ? "brand" : "neutral" }) }) }));
+};

package/dist/compositions/product-card/product-card-swatch-selector.d.ts

@@ -0,0 +1,2 @@
+import type { ProductCardSwatchSelectorProps } from "./product-card-types.js";
+export declare const ProductCardSwatchSelector: ({ className, ...props }: ProductCardSwatchSelectorProps) => import("react").JSX.Element | null;

package/dist/compositions/product-card/product-card-swatch-selector.js

@@ -0,0 +1,23 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Swatch, SwatchMore, SwatchSelector, } from "@instruments/materia-ui/components/swatch-selector";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useProductCard } from "./product-card-context.js";
+export const ProductCardSwatchSelector = ({ className, ...props }) => {
+    const { selectedVariantId, onVariantChange, product, showSwatches, maxSwatches, renderImage, } = useProductCard();
+    if (!showSwatches) {
+        return null;
+    }
+    const variants = product.variants ?? [product];
+    const visibleVariants = variants.slice(0, maxSwatches);
+    // Use variantCount (total in DB) for overflow, not just loaded variants
+    const overflowCount = (product.variantCount ?? 1) - maxSwatches;
+    return (_jsxs(SwatchSelector, { className: cn("px-6", className), onValueChange: onVariantChange, value: selectedVariantId, ...props, children: [visibleVariants.map((variant) => (_jsx(Swatch, { unavailable: variant.available === false, value: variant.id, children: renderImage({
+                    alt: `${variant.name} variant`,
+                    className: "object-cover",
+                    draggable: false,
+                    fill: true,
+                    sizes: "32px",
+                    src: variant.images[0] ?? "",
+                }) }, variant.id))), overflowCount > 0 && _jsx(SwatchMore, { count: overflowCount })] }));
+};

package/dist/compositions/product-card/product-card-swatch.d.ts

@@ -0,0 +1,22 @@
+interface ProductCardSwatchProps {
+    overrideImageUrl?: string | undefined;
+    priority?: boolean | undefined;
+}
+/**
+ * ProductCardSwatch - the image-first tile for boards and canvases.
+ *
+ * - Idle: the image alone.
+ * - Hover or keyboard focus: the card surface, Quick view, the add control and
+ *   the brand and category lines.
+ * - Selected (`active`), not hovered: the elevated surface only. Selection
+ *   alone does not reveal the add control.
+ * - `menuOpen`: the add control stays visible so it can close the panel.
+ * - `dragging`: the elevated surface and nothing else.
+ * - `processing`: the caption becomes a process chip with elapsed time.
+ *
+ * Reveals are pure CSS (`hover`, `has-focus-visible`), never `focus-within`: a
+ * click focuses the tile's link, and `focus-within` would pin the chrome open
+ * once the pointer leaves.
+ */
+export declare const ProductCardSwatch: (props: ProductCardSwatchProps) => import("react").JSX.Element;
+export {};

package/dist/compositions/product-card/product-card-swatch.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { VStack } from "@instruments/materia-ui/components/stack";
+import { Text } from "@instruments/materia-ui/components/text";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useProductCard } from "./product-card-context.js";
+import { ProductCardImage } from "./product-card-image.js";
+import { ProductCardLink } from "./product-card-link.js";
+import { ProductCardProcessing } from "./product-card-processing.js";
+import { ProductCardQuickView } from "./product-card-quick-view.js";
+import { ProductCardSwatchAdd } from "./product-card-swatch-add.js";
+const SwatchShell = ({ active, children, dragging, processing, }) => (_jsx(Box, { className: cn(
+    // Bare at rest, so the tile reads as its image alone; the card surface
+    // and elevation arrive on hover or focus (`shadow-md`) and while
+    // selected or dragged (`shadow-lg`).
+    "group relative flex w-full flex-col rounded-3xl p-1", processing ? "gap-1" : "gap-0 hover:gap-1 has-focus-visible:gap-1", processing && !(active || dragging) && "bg-card shadow-sm", (active || dragging) && "bg-card shadow-lg", !(processing || active || dragging) &&
+        "hover:bg-card has-focus-visible:bg-card bg-transparent hover:shadow-md has-focus-visible:shadow-md"), "data-component": "product-card", "data-dragging": dragging ? "true" : undefined, "data-mode": "swatch", "data-testid": "product-card", children: children }));
+/**
+ * Brand and category, collapsed until the tile is hovered or focused. Empty
+ * strings drop their line.
+ */
+const SwatchCaption = () => {
+    const { currentVariant, product, showProductBrand, showProductName } = useProductCard();
+    const brandName = product.brand?.name.trim() ?? "";
+    // The category answers "what is this?" faster than a marketing name, so it
+    // leads; the product name is the fallback and lives in the Quick view.
+    const categoryName = product.displayCategory?.name.trim() ?? "";
+    const secondLine = categoryName === "" ? currentVariant.name : categoryName;
+    return (_jsxs(VStack, { className: "max-h-0 w-full overflow-hidden px-2 py-0 opacity-0 group-hover:max-h-16 group-hover:py-1 group-hover:opacity-100 group-has-focus-visible:max-h-16 group-has-focus-visible:py-1 group-has-focus-visible:opacity-100", gap: "none", children: [showProductBrand && brandName !== "" ? (_jsx(Text, { className: "truncate", size: "caption", weight: "semibold", children: brandName })) : null, showProductName ? (_jsx(Text, { className: "truncate", size: "caption", children: secondLine })) : null] }));
+};
+/** The square photograph with the add control and Quick view over it. */
+const SwatchMedia = ({ overrideImageUrl, priority, }) => {
+    const { active, addGlyph, availability, currentVariant, dragging, labels, linkComponent, linkPrefetch, menuOpen, onAdd, onCardClick, onQuickView, processing, productUrl, } = useProductCard();
+    return (_jsxs(Box, { className: "relative aspect-square w-full overflow-hidden rounded-2xl", children: [_jsx(ProductCardLink, { blocked: availability === "blocked", className: "block size-full", href: productUrl, label: `View ${currentVariant.name}`, linkComponent: linkComponent, onActivate: onCardClick, prefetch: linkPrefetch, children: _jsx(ProductCardImage, { overrideImageUrl: overrideImageUrl, priority: priority }) }), dragging ? null : (_jsx(ProductCardSwatchAdd, { active: active, glyph: addGlyph, labels: labels, menuOpen: menuOpen, onAdd: onAdd })), dragging || processing !== undefined ? null : (_jsx(ProductCardQuickView, { align: "start", onQuickView: onQuickView }))] }));
+};
+/**
+ * ProductCardSwatch - the image-first tile for boards and canvases.
+ *
+ * - Idle: the image alone.
+ * - Hover or keyboard focus: the card surface, Quick view, the add control and
+ *   the brand and category lines.
+ * - Selected (`active`), not hovered: the elevated surface only. Selection
+ *   alone does not reveal the add control.
+ * - `menuOpen`: the add control stays visible so it can close the panel.
+ * - `dragging`: the elevated surface and nothing else.
+ * - `processing`: the caption becomes a process chip with elapsed time.
+ *
+ * Reveals are pure CSS (`hover`, `has-focus-visible`), never `focus-within`: a
+ * click focuses the tile's link, and `focus-within` would pin the chrome open
+ * once the pointer leaves.
+ */
+export const ProductCardSwatch = (props) => {
+    const { active, dragging, processing, showProductBrand, showProductName } = useProductCard();
+    const showCaption = !(dragging || processing !== undefined) &&
+        (showProductBrand || showProductName);
+    return (_jsxs(SwatchShell, { active: active, dragging: dragging, processing: processing !== undefined, children: [_jsx(SwatchMedia, { ...props }), processing === undefined ? null : (_jsx(ProductCardProcessing, { ...processing })), showCaption ? _jsx(SwatchCaption, {}) : null] }));
+};

package/dist/compositions/product-card/product-card-tools-activity.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentProps, FocusEvent, PointerEvent } from "react";
+type ToolsActivityHandlers = Pick<ComponentProps<"div">, "onBlurCapture" | "onFocusCapture" | "onPointerEnter" | "onPointerLeave">;
+/**
+ * Tracks whether the card's tools should be mounted: hover or focus anywhere
+ * inside the card turns them on, leaving both turns them off. The returned
+ * handlers wrap the caller's own so a consumer's listeners still fire.
+ */
+export declare const useToolsActivity: ({ onBlurCapture, onFocusCapture, onPointerEnter, onPointerLeave, }: ToolsActivityHandlers) => {
+    interactionHandlers: {
+        onBlurCapture: (e: FocusEvent<HTMLDivElement>) => void;
+        onFocusCapture: (e: FocusEvent<HTMLDivElement>) => void;
+        onPointerEnter: (e: PointerEvent<HTMLDivElement>) => void;
+        onPointerLeave: (e: PointerEvent<HTMLDivElement>) => void;
+    };
+    toolsActive: boolean;
+};
+export {};

package/dist/compositions/product-card/product-card-tools-activity.js

@@ -0,0 +1,42 @@
+"use client";
+import { useCallback, useState } from "react";
+/**
+ * Tracks whether the card's tools should be mounted: hover or focus anywhere
+ * inside the card turns them on, leaving both turns them off. The returned
+ * handlers wrap the caller's own so a consumer's listeners still fire.
+ */
+export const useToolsActivity = ({ onBlurCapture, onFocusCapture, onPointerEnter, onPointerLeave, }) => {
+    const [toolsActive, setToolsActive] = useState(false);
+    const handlePointerEnter = useCallback((e) => {
+        onPointerEnter?.(e);
+        setToolsActive(true);
+    }, [onPointerEnter]);
+    const handlePointerLeave = useCallback((e) => {
+        onPointerLeave?.(e);
+        const { activeElement } = document;
+        if (activeElement && e.currentTarget.contains(activeElement)) {
+            return;
+        }
+        setToolsActive(false);
+    }, [onPointerLeave]);
+    const handleFocusCapture = useCallback((e) => {
+        onFocusCapture?.(e);
+        setToolsActive(true);
+    }, [onFocusCapture]);
+    const handleBlurCapture = useCallback((e) => {
+        onBlurCapture?.(e);
+        const nextTarget = e.relatedTarget;
+        if ((nextTarget instanceof Node && e.currentTarget.contains(nextTarget)) ||
+            e.currentTarget.matches(":hover")) {
+            return;
+        }
+        setToolsActive(false);
+    }, [onBlurCapture]);
+    const interactionHandlers = {
+        onBlurCapture: handleBlurCapture,
+        onFocusCapture: handleFocusCapture,
+        onPointerEnter: handlePointerEnter,
+        onPointerLeave: handlePointerLeave,
+    };
+    return { interactionHandlers, toolsActive };
+};

package/dist/compositions/product-card/product-card-tools-types.d.ts

@@ -0,0 +1,16 @@
+import type { ButtonProps } from "@instruments/materia-ui/components/button";
+import type { ReactNode } from "react";
+interface ProductCardToolsProps {
+    active?: boolean;
+    className?: string;
+}
+/**
+ * Render slot for app-specific tools (saves, visual search, etc.), shared by
+ * the provider props and the context value.
+ */
+type ProductCardRenderTools = (props: {
+    actionButtonSize: ButtonProps["size"];
+    productId: string;
+    variantId: string;
+}) => ReactNode;
+export type { ProductCardRenderTools, ProductCardToolsProps };

package/dist/compositions/product-card/product-card-tools-types.js

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

package/dist/compositions/product-card/product-card-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ProductCardToolsProps } from "./product-card-types.js";
+declare const ProductCardToolsBase: ({ active, className, }: ProductCardToolsProps) => import("react").JSX.Element | null;
+/**
+ * ProductCardTools - Renders app-specific tools via the renderTools slot.
+ * Tools mount only while the card is hovered or focus is inside the card,
+ * keeping large search grids from rendering every hidden action button.
+ */
+export declare const ProductCardTools: import("react").MemoExoticComponent<typeof ProductCardToolsBase>;
+export {};

package/dist/compositions/product-card/product-card-tools.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { durations, easings } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { AnimatePresence, useReducedMotion } from "motion/react";
+import * as m from "motion/react-m";
+import { memo } from "react";
+import { useProductCard } from "./product-card-context.js";
+import { ProductCardStatusBadge } from "./product-card-status-badge.js";
+const PRODUCT_CARD_TOOL_BUTTON_SIZE = {
+    // Figma hover: 40×32 pill → 32px tall = icon-sm (icon-lg was 40px, too large).
+    "@[240px]/product-card": "icon-sm",
+    base: "icon-xs",
+};
+const ProductCardToolSlot = ({ actionButtonSize, productId, renderTools, variantId, }) => renderTools({
+    actionButtonSize,
+    productId,
+    variantId,
+});
+const ProductCardToolsBase = ({ active = true, className, }) => {
+    const { currentVariant, mode, renderTools, statusBadge } = useProductCard();
+    const shouldReduceMotion = useReducedMotion();
+    // If no renderTools provided, render nothing
+    if (!renderTools) {
+        return null;
+    }
+    const isInspiration = mode === "inspiration";
+    const actionButtonSize = isInspiration
+        ? "icon-base"
+        : PRODUCT_CARD_TOOL_BUTTON_SIZE;
+    return (_jsx(Box, { className: cn("pointer-events-none absolute z-20", isInspiration
+            ? "top-5 right-5"
+            : "top-3 right-3 @[240px]/product-card:top-5.5 @[240px]/product-card:right-5.5", className), children: _jsx(AnimatePresence, { initial: false, children: active && (_jsxs(m.div, { animate: {
+                    "--product-card-tool-presence": 1,
+                }, className: cn("pointer-events-auto flex", 
+                // Column stays right-anchored (items-end) so an expandable tool
+                // grows its label leftward into the image - the cluster's right
+                // edge is pinned, so the card never reflows or overflows.
+                isInspiration
+                    ? "items-center gap-1.5"
+                    : "flex-col items-end gap-1"), exit: {
+                    "--product-card-tool-presence": 0,
+                }, initial: {
+                    "--product-card-tool-presence": 0,
+                }, transition: shouldReduceMotion === true
+                    ? { duration: 0 }
+                    : {
+                        duration: durations.moderate,
+                        ease: easings.inOut,
+                    }, children: [isInspiration && statusBadge?.icon ? (_jsx(ProductCardStatusBadge, { ...statusBadge, className: "!bg-tool-scrim hover:!bg-tool-scrim-hover size-10 border-transparent text-white backdrop-blur-xl [&_svg]:size-4" })) : null, _jsx(ProductCardToolSlot, { actionButtonSize: actionButtonSize, productId: currentVariant.id, renderTools: renderTools, variantId: currentVariant.id })] })) }) }));
+};
+/**
+ * ProductCardTools - Renders app-specific tools via the renderTools slot.
+ * Tools mount only while the card is hovered or focus is inside the card,
+ * keeping large search grids from rendering every hidden action button.
+ */
+export const ProductCardTools = memo(ProductCardToolsBase);

package/dist/compositions/product-card/product-card-types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The ProductCard type surface, re-exported from one file per arm so existing
+ * import paths keep working.
+ */
+export type { ProductCardAvailability, ProductCardDisplayCategory, ProductCardHref, ProductCardLabels, ProductCardMode, ProductCardProduct, ProductCardProductCategory, } from "./product-card-product-types.js";
+export type { ProductCardDragAdapter, ProductCardDragAdapterProps, ProductCardDragHandle, ProductCardImageProps, ProductCardImageRenderProps, ProductCardQuickViewProps, ProductCardRenderImage, ProductCardStatusBadgeProps, } from "./product-card-image-types.js";
+export type { ProductCardActionProps, ProductCardActionTone, ProductCardDisplayOptions, ProductCardProcessingProps, ProductCardSwatchSelectorProps, } from "./product-card-content-types.js";
+export type { ProductCardAddToCartAction, ProductCardAddToCartPlacement, ProductCardAddToCartRenderProps, ProductCardPrimaryAction, ProductCardRenderAddToCart, ProductCardShowFinishesAction, ProductCardSwatchAddGlyph, ProductCardSwatchAddProps, ProductCardViewInCatalogueAction, ProductCardViewOnlyAction, } from "./product-card-actions-types.js";
+export type { ProductCardToolsProps } from "./product-card-tools-types.js";
+export type { ProductCardContextValue, ProductCardProps, ProductCardProviderProps, } from "./product-card-provider-types.js";

package/dist/compositions/product-card/product-card-types.js

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

package/dist/compositions/product-card.d.ts

@@ -0,0 +1,24 @@
+export { ProductCardAction } from "./product-card/product-card-action.js";
+export { ProductCardAddToCart } from "./product-card/product-card-add-to-cart.js";
+export { ProductCardAvailabilityStatus } from "./product-card/product-card-availability.js";
+export { ProductCardCaption } from "./product-card/product-card-caption.js";
+export { ProductCardCategory } from "./product-card/product-card-category.js";
+export { ProductCardColorCount } from "./product-card/product-card-color-count.js";
+export { ProductCardContent } from "./product-card/product-card-content.js";
+export { useProductCard } from "./product-card/product-card-context.js";
+export { ProductCardCost } from "./product-card/product-card-cost.js";
+export { ProductCardImage } from "./product-card/product-card-image.js";
+export { ProductCardInstallShotToggle } from "./product-card/product-card-install-shot.js";
+export { ProductCardMeta } from "./product-card/product-card-meta.js";
+export { ProductCardFindSimilar, ProductCardPrimaryActionControl, } from "./product-card/product-card-primary-action.js";
+export { ProductCardProvider } from "./product-card/product-card-provider.js";
+export { ProductCardQuickView } from "./product-card/product-card-quick-view.js";
+export { ProductCard } from "./product-card/product-card-root.js";
+export { ProductCardSkeleton } from "./product-card/product-card-skeleton.js";
+export { ProductCardStatusBadge } from "./product-card/product-card-status-badge.js";
+export { ProductCardProcessing } from "./product-card/product-card-processing.js";
+export { ProductCardSwatch } from "./product-card/product-card-swatch.js";
+export { ProductCardSwatchAdd } from "./product-card/product-card-swatch-add.js";
+export { ProductCardSwatchSelector } from "./product-card/product-card-swatch-selector.js";
+export { ProductCardTools } from "./product-card/product-card-tools.js";
+export type { ProductCardActionProps, ProductCardActionTone, ProductCardAddToCartAction, ProductCardAddToCartPlacement, ProductCardAddToCartRenderProps, ProductCardAvailability, ProductCardContextValue, ProductCardDisplayCategory, ProductCardDisplayOptions, ProductCardDragAdapter, ProductCardDragAdapterProps, ProductCardDragHandle, ProductCardHref, ProductCardImageProps, ProductCardImageRenderProps, ProductCardLabels, ProductCardMode, ProductCardPrimaryAction, ProductCardProduct, ProductCardProcessingProps, ProductCardProductCategory, ProductCardProps, ProductCardProviderProps, ProductCardQuickViewProps, ProductCardRenderAddToCart, ProductCardRenderImage, ProductCardShowFinishesAction, ProductCardStatusBadgeProps, ProductCardSwatchAddGlyph, ProductCardSwatchAddProps, ProductCardSwatchSelectorProps, ProductCardToolsProps, ProductCardViewInCatalogueAction, ProductCardViewOnlyAction, } from "./product-card/product-card-types.js";