@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,107 @@
+type ProductCardMode = "single" | "group" | "compact" | "inspiration" | "swatch";
+/**
+ * Whether the product can be acted on, as the application knows it.
+ *
+ * ONE axis rather than four booleans, because the states exclude each other: a
+ * product is never both suspended and out of stock. Everything but
+ * `"available"` shows a centred status pill over the image.
+ *
+ * - `out-of-stock`, `suspended` and `blocked` mean the product cannot be
+ *   acted on, so the card offers *Find similar* in place of its primary action
+ *   when `onFindSimilar` is supplied.
+ * - `view-only` can be opened but not ordered. Its primary action is the
+ *   application's call, normally `{ kind: "view-only" }`.
+ * - `blocked` also stops the card navigating to the product page: the product
+ *   exists but this viewer may not open it.
+ *
+ * When omitted the card reads `available: false` on the current variant as
+ * `"out-of-stock"`, so callers predating this prop render as before.
+ */
+type ProductCardAvailability = "available" | "out-of-stock" | "view-only" | "suspended" | "blocked";
+/**
+ * User-visible strings the card owns, so an application can translate or
+ * rephrase them. Every key is optional and falls back to an English default.
+ */
+interface ProductCardLabels {
+    /** Collapsed swatch control that adds straight to a board. @default "Add to board" */
+    add?: string | undefined;
+    /** Status pill text per availability. Defaults: "Out of stock", "View only", "Suspended", "Unavailable". */
+    availability?: Partial<Record<Exclude<ProductCardAvailability, "available">, string>> | undefined;
+    /** Swatch control while its suggestions panel is open. @default "Close suggestions" */
+    closeSuggestions?: string | undefined;
+    /** Primary action that replaces the cart on an unavailable product. @default "Find similar" */
+    findSimilar?: string | undefined;
+    /** Collapsed swatch control that opens suggestions. @default "Suggest an action" */
+    suggest?: string | undefined;
+}
+/** A link target: a path or an absolute URL. */
+type ProductCardHref = string;
+/**
+ * Category with hierarchy information.
+ */
+interface ProductCardProductCategory {
+    id: string;
+    level: number;
+    name: string;
+    path: string;
+}
+/**
+ * Display category - Level 2 and optionally Level 3 categories for
+ * meaningful labels.
+ */
+interface ProductCardDisplayCategory {
+    level3Name?: string | null;
+    name: string;
+    path: string;
+}
+/**
+ * Minimal structural product shape the card reads. Framework- and
+ * data-layer-agnostic: apps map their own product models onto this.
+ */
+interface ProductCardProduct {
+    available?: boolean;
+    brand?: {
+        id?: string;
+        name: string;
+    };
+    /** Source-declared manufacturer model/item code, when governed upstream. */
+    brandItemCode?: string;
+    /** All categories for this product (all levels) */
+    categories?: ProductCardProductCategory[];
+    costIndicator?: string | null;
+    /** Level 2 category for display (meaningful product type) */
+    displayCategory?: ProductCardDisplayCategory | null;
+    id: string;
+    /** Array of image URLs for this product */
+    images: string[];
+    /**
+     * The product photographed in a room, when one exists.
+     *
+     * A NAMED fact rather than a position: the card does not infer an
+     * installation view from `images[1]`, since a second photograph may be merely
+     * another angle. Absent means no installation image is known.
+     */
+    installationImageUrl?: string;
+    /**
+     * A reviewed scene image known to survive the inspiration card's tall crop.
+     * This is explicit eligibility, not an alias for any installation image.
+     */
+    inspirationImageUrl?: string;
+    /**
+     * An opaque value the application attaches to a product. The card never
+     * reads it and returns the same product object to every callback, so the
+     * application can recover its own data. A variant is an entry of `variants`
+     * and carries its own `payload`.
+     */
+    payload?: unknown;
+    /** Canonical product-type display name. */
+    productType?: string;
+    name: string;
+    slug: string;
+    variantCount?: number;
+    /** Label for variant type (e.g., "Colors", "Finishes", "Patterns") */
+    variantLabel?: string | null;
+    /** Sibling variants. The card reads this but never reassigns it. */
+    variants?: ProductCardProduct[];
+}
+export type { ProductCardAvailability, ProductCardDisplayCategory, ProductCardHref, ProductCardLabels, ProductCardMode, ProductCardProduct, ProductCardProductCategory, };

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

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

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

@@ -0,0 +1,259 @@
+import type { ComponentProps, ElementType, ReactNode } from "react";
+import type { ProductCardPrimaryAction, ProductCardRenderAddToCart, ProductCardSwatchAddGlyph } from "./product-card-actions-types.js";
+import type { ProductCardActionProps, ProductCardDisplayOptions, ProductCardProcessingProps } from "./product-card-content-types.js";
+import type { ProductCardDragAdapter, ProductCardRenderImage, ProductCardStatusBadgeProps } from "./product-card-image-types.js";
+import type { ProductCardAvailability, ProductCardHref, ProductCardLabels, ProductCardMode, ProductCardProduct } from "./product-card-product-types.js";
+import type { ProductCardRenderTools } from "./product-card-tools-types.js";
+/**
+ * Context value provided to ProductCard children via the useProductCard hook.
+ */
+interface ProductCardContextValue {
+    /** Optional flexible action notice (e.g. "Ships overnight"). Off when absent. */
+    action?: ProductCardActionProps | undefined;
+    currentVariant: ProductCardProduct;
+    /**
+     * Component slot wiring drag behaviour around the card image.
+     * Absent means a static (non-draggable) image.
+     */
+    dragAdapter?: ProductCardDragAdapter | undefined;
+    /** Whether this card is active (highlighted) */
+    active: boolean;
+    /** Swatch mode: the host is mid-drag; chrome is suppressed. */
+    dragging: boolean;
+    /** Resolved availability, including the `available: false` fallback. */
+    availability: ProductCardAvailability;
+    labels?: ProductCardLabels | undefined;
+    /** Component used to render navigation links. Defaults to `"a"`. */
+    linkComponent: ElementType;
+    /** Controls `<Link prefetch>` on all internal links */
+    linkPrefetch?: boolean | undefined;
+    maxSwatches: number;
+    /** Swatch mode: the suggestions panel is open. */
+    menuOpen?: boolean | undefined;
+    mode: ProductCardMode;
+    /** Swatch mode: the add / suggest control's handler. */
+    onAdd?: (() => void) | undefined;
+    addGlyph?: ProductCardSwatchAddGlyph | undefined;
+    onCardClick?: (() => void) | undefined;
+    /** Offers *Find similar* in place of the primary action when unavailable. */
+    onFindSimilar?: (() => void) | undefined;
+    /** When set, reveals a "Quick view" glass pill over the image on hover. */
+    onQuickView?: (() => void) | undefined;
+    onVariantChange: (variantId: string) => void;
+    /** Application-supplied price, shown on the meta line. */
+    price?: ReactNode;
+    /** Swatch mode processing footer. Off when absent. */
+    processing?: ProductCardProcessingProps | undefined;
+    /**
+     * What this card's one labelled control offers. Absent falls back to the
+     * legacy cart-only behaviour, so callers predating this render unchanged.
+     */
+    primaryAction?: ProductCardPrimaryAction | undefined;
+    product: ProductCardProduct;
+    /** URL to the product page */
+    productUrl: ProductCardHref;
+    /** Render slot for the add-to-cart control. Absent means no cart UI. */
+    renderAddToCart?: ProductCardRenderAddToCart | undefined;
+    /** Render slot for images. Always defined (defaults to a plain `<img>`). */
+    renderImage: ProductCardRenderImage;
+    /** Render slot for app-specific tools (saves, visual search, etc.) */
+    renderTools?: ProductCardRenderTools | undefined;
+    selectedVariantId: string;
+    /** Whether to show the active row pointer under the card. */
+    showActivePointer: boolean;
+    /**
+     * True when this variant has an installation photograph to offer.
+     *
+     * Read from the NAMED `installationImageUrl`, never from image position - see
+     * {@link ProductCardProduct.installationImageUrl}.
+     */
+    hasInstallShot: boolean;
+    /** Whether the installation view is currently pinned. */
+    showingInstallShot: boolean;
+    toggleInstallShot: () => void;
+    showAddToCart: boolean;
+    productNameLines: 1 | 2;
+    showProductBrand: boolean;
+    showProductName: boolean;
+    showSwatches: boolean;
+    /** Optional image-overlay status badge (e.g. "New"). Off when absent. */
+    statusBadge?: ProductCardStatusBadgeProps | undefined;
+    /** Fixed width in pixels. Undefined = fluid width */
+    width?: number | undefined;
+}
+/**
+ * Props for ProductCardProvider - the context provider for ProductCard.
+ */
+interface ProductCardProviderProps {
+    /**
+     * Optional flexible "action notice" shown under the meta row
+     * (e.g. ⚡ Ships overnight, ⌕ Find similar). Prop-driven; omit to hide.
+     */
+    action?: ProductCardActionProps | undefined;
+    children: ReactNode;
+    display?: ProductCardDisplayOptions | undefined;
+    /**
+     * Component slot that wires drag behaviour (e.g. dnd-kit `useDraggable`)
+     * around the card image. Omit for a static, non-draggable image.
+     *
+     * @bestPractice Pass a referentially stable component - a module-level
+     * constant, never an inline factory (`dragAdapter={(p) => …}`). A
+     * `ComponentType` prop remounts its subtree whenever its identity changes,
+     * which drops the underlying drag node ref mid-drag.
+     */
+    dragAdapter?: ProductCardDragAdapter | undefined;
+    /**
+     * Whether this card is active (highlighted).
+     * Apps should compute this based on their own state (e.g., sidepanel open,
+     * recommendations anchor).
+     */
+    active?: boolean | undefined;
+    /**
+     * Swatch mode: set while the host is dragging the tile. Hides Quick view, the
+     * caption and the add control and keeps the elevated shell. Distinct from
+     * {@link dragAdapter}, which wires a drag handle around the image.
+     */
+    dragging?: boolean | undefined;
+    /**
+     * Whether the product can be acted on - see {@link ProductCardAvailability}.
+     * @default "available"
+     */
+    availability?: ProductCardAvailability | undefined;
+    /** Override the card's own strings. */
+    labels?: ProductCardLabels | undefined;
+    /**
+     * Component to render internal navigation links.
+     * Defaults to `"a"`. Pass `Link` from `next/link` in Next.js apps
+     * to enable client-side navigation and prefetching.
+     */
+    linkAs?: ElementType | undefined;
+    /**
+     * Controls `<Link prefetch>` on all internal links.
+     * `true` forces full route prefetch (including data) on viewport entry.
+     * Default (undefined) uses Next.js auto behaviour (partial prefetch for
+     * dynamic routes).
+     */
+    linkPrefetch?: boolean | undefined;
+    maxSwatches?: number | undefined;
+    /**
+     * Mode determines the card behavior:
+     * - "single": Shows a single product (no carousel, swatches)
+     * - "group": Shows a product group with carousel, swatches, etc.
+     * - "inspiration": Image-forward card with hover overlay (for
+     *   explore/masonry feeds)
+     * - "swatch": Compact image-first tile for boards and canvases. Brand/name,
+     *   Quick view and the add control appear on hover or keyboard focus.
+     */
+    mode?: ProductCardMode | undefined;
+    /**
+     * Swatch mode: handler for the circular add / suggest control. Omit it for a
+     * presentational, inert control that leaves clicks to the tile.
+     */
+    onAdd?: (() => void) | undefined;
+    /** Swatch mode: collapsed glyph of the control. @default "spark" */
+    addGlyph?: ProductCardSwatchAddGlyph | undefined;
+    /**
+     * Swatch mode: while true the control reads as Minus and stays visible, so
+     * closing the suggestions panel remains reachable. Pair with `onAdd`.
+     */
+    menuOpen?: boolean | undefined;
+    /**
+     * Called from the *Find similar* control that replaces the primary action
+     * when `availability` is `"out-of-stock"`, `"suspended"` or `"blocked"`.
+     * Omit it and the primary action renders as it would for any product.
+     */
+    onFindSimilar?: (() => void) | undefined;
+    /**
+     * Price, supplied by the application as already-formatted content. Replaces
+     * `costIndicator` on the meta line. The card does no currency or tax logic.
+     * Shipping and delivery flags go through {@link action}, whose `label` is
+     * also a ReactNode.
+     */
+    price?: ReactNode;
+    /**
+     * Swatch mode: processing footer ("Matching materials" and elapsed time).
+     * Replaces the caption and hides Quick view.
+     */
+    processing?: ProductCardProcessingProps | undefined;
+    /**
+     * Override the default card click behaviour.
+     * Apps should provide this to handle navigation/sidepanel opening.
+     */
+    onCardClick?: (() => void) | undefined;
+    /**
+     * When provided, a "Quick view" glass pill appears over the image on hover
+     * and invokes this handler (e.g. open a quick-view sidepanel). Prop-driven;
+     * omit to hide.
+     */
+    onQuickView?: (() => void) | undefined;
+    /**
+     * Callback when variant selection changes.
+     */
+    onVariantChange?: ((variantId: string) => void) | undefined;
+    /**
+     * What this card's one labelled control offers - see
+     * {@link ProductCardPrimaryAction}.
+     *
+     * Omit entirely for a card with no control at all, which is the correct
+     * rendering for a product that can do nothing rather than a disabled button.
+     * Omitting also preserves the pre-existing cart-only behaviour for callers
+     * that pass `renderAddToCart` and nothing else.
+     */
+    primaryAction?: ProductCardPrimaryAction | undefined;
+    product: ProductCardProduct;
+    /**
+     * Builds the href of a product's page. Receives the selected variant.
+     * Defaults to `/products/` followed by the slug.
+     */
+    productUrl?: ((product: ProductCardProduct) => string) | undefined;
+    /**
+     * Render slot for the add-to-cart control, placement-discriminated
+     * ("cta" | "inspiration"). Omit to render no cart UI at all.
+     */
+    renderAddToCart?: ProductCardRenderAddToCart | undefined;
+    /**
+     * Render slot for framework-specific image components.
+     *
+     * @bestPractice In Next.js apps pass a renderer wrapping `next/image` -
+     * the default is a plain `<img>` and skips Next's optimisation pipeline.
+     */
+    renderImage?: ProductCardRenderImage | undefined;
+    /**
+     * Render slot for app-specific tools (saves, visual search, etc.)
+     * Rendered in the image overlay area.
+     */
+    renderTools?: ProductCardRenderTools | undefined;
+    /** Show the active row pointer under the card when active. */
+    showActivePointer?: boolean | undefined;
+    /**
+     * Optional status badge overlaid on the image (e.g. "New"). Prop-driven;
+     * omit to hide.
+     */
+    statusBadge?: ProductCardStatusBadgeProps | undefined;
+    /**
+     * For "single" mode: the specific variant ID to display
+     * For "group" mode: the initially selected variant ID
+     */
+    variantId?: string | undefined;
+    /**
+     * Fixed width in pixels for image sizing hints.
+     * When omitted, card fills its container (fluid width).
+     */
+    width?: number | undefined;
+}
+/**
+ * Props for the main ProductCard component.
+ */
+type ProductCardProps = ComponentProps<"div"> & Pick<ProductCardProviderProps, "action" | "addGlyph" | "availability" | "dragAdapter" | "dragging" | "active" | "labels" | "linkAs" | "linkPrefetch" | "maxSwatches" | "menuOpen" | "mode" | "onAdd" | "onCardClick" | "onFindSimilar" | "onQuickView" | "onVariantChange" | "price" | "primaryAction" | "processing" | "product" | "productUrl" | "renderAddToCart" | "renderImage" | "renderTools" | "showActivePointer" | "statusBadge" | "variantId" | "width"> & {
+    /** Override image URL - used for visual search to show the matched image */
+    overrideImageUrl?: string | undefined;
+    /** Prioritise loading images (sets loading="eager" and adds preload link) */
+    priority?: boolean | undefined;
+    productNameLines?: 1 | 2 | undefined;
+    showAddToCart?: boolean | undefined;
+    showProductBrand?: boolean | undefined;
+    showProductName?: boolean | undefined;
+    showSwatches?: boolean | undefined;
+    similarityScore?: number | undefined;
+};
+export type { ProductCardContextValue, ProductCardProps, ProductCardProviderProps, };

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

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

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

@@ -0,0 +1,15 @@
+import type { ProductCardProviderProps } from "./product-card-types.js";
+/**
+ * Context provider for ProductCard.
+ * Manages variant selection and provides product data + render seams to
+ * children. App-specific behaviour (navigation, cart, drag) is injected via
+ * props.
+ *
+ * @bestPractice Pass `renderImage` wrapping `next/image` in Next.js apps -
+ * the default renderer is a plain `<img>` and skips Next's optimisation.
+ * @bestPractice Keep `dragAdapter` referentially stable (a module-level
+ * constant) - an inline factory remounts the image subtree and drops the
+ * drag ref mid-drag.
+ * @category catalogue
+ */
+export declare const ProductCardProvider: ({ product, children, mode, width, active, dragging, labels, showActivePointer, linkAs, linkPrefetch, maxSwatches, renderTools, renderImage, renderAddToCart, dragAdapter, action, primaryAction, statusBadge, onQuickView, onAdd, onCardClick, addGlyph, menuOpen, onFindSimilar, price, processing, ...resolveInputs }: ProductCardProviderProps) => import("react").JSX.Element;

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

@@ -0,0 +1,204 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useCallback, useMemo, useState } from "react";
+import { ProductCardContext } from "./product-card-context.js";
+const defaultProductUrl = (product) => `/products/${product.slug}`;
+/**
+ * Default image renderer: a plain `<img>` that fills its positioned parent.
+ *
+ * @bestPractice In Next.js apps pass `renderImage` wrapping `next/image` -
+ * this default skips Next's image optimisation and responsive srcset.
+ *
+ * @example
+ * ```tsx
+ * // Using Next.js Image
+ * import Image from "next/image";
+ *
+ * <ProductCardProvider
+ *   renderImage={({ src, alt, className, sizes, priority }) => (
+ *     <Image
+ *       alt={alt}
+ *       className={className}
+ *       fill
+ *       priority={priority}
+ *       sizes={sizes}
+ *       src={src}
+ *     />
+ *   )}
+ * />
+ * ```
+ */
+const defaultRenderImage = ({ alt, className, draggable = false, priority = false, src, }) => (_jsx("img", { alt: alt, className: cn("absolute inset-0 size-full object-cover", className), decoding: "async", draggable: draggable, loading: priority ? "eager" : "lazy", src: src, ...(priority ? { fetchPriority: "high" } : {}) }));
+const useVariantSelection = ({ mode, onVariantChange, product, variantId, }) => {
+    const variants = useMemo(() => product.variants ?? [product], [product]);
+    const defaultVariantId = variants[0]?.id ?? "";
+    const [userSelectedVariantId, setUserSelectedVariantId] = useState(null);
+    const preferredVariantId = variantId ?? userSelectedVariantId ?? defaultVariantId;
+    const currentVariant = useMemo(() => {
+        const matchingVariant = variants.find((v) => v.id === preferredVariantId);
+        if (matchingVariant) {
+            return matchingVariant;
+        }
+        const [fallbackVariant] = variants;
+        if (fallbackVariant) {
+            return fallbackVariant;
+        }
+        throw new Error("Product must contain at least one variant");
+    }, [variants, preferredVariantId]);
+    const selectedVariantId = currentVariant.id;
+    const handleVariantChange = useCallback((newVariantId) => {
+        // In single/inspiration/swatch mode, variant selection is fixed
+        if (mode === "single" || mode === "inspiration" || mode === "swatch") {
+            return;
+        }
+        setUserSelectedVariantId(newVariantId);
+        onVariantChange?.(newVariantId);
+    }, [mode, onVariantChange]);
+    return { currentVariant, handleVariantChange, selectedVariantId };
+};
+/**
+ * Resolves the card's display flags. The add-to-cart flag only matters when a
+ * renderer exists: no renderAddToCart slot means no cart UI at all.
+ */
+const resolveDisplay = (display, hasRenderAddToCart) => ({
+    productNameLines: display?.nameLines ?? 1,
+    showAddToCart: (display?.addToCart ?? true) && hasRenderAddToCart,
+    showProductBrand: display?.brand ?? true,
+    showProductName: display?.name ?? true,
+    showSwatches: display?.swatches ?? false,
+});
+/**
+ * Which image the card is showing. Card-local because it is a way of LOOKING
+ * at one product, not a selection anything outside the card needs. Lives in the
+ * provider rather than the image so the toggle can render as a SIBLING of the
+ * card link instead of a button nested inside one.
+ */
+const useInstallShot = (installationImageUrl) => {
+    const [showingInstallShot, setShowingInstallShot] = useState(false);
+    const toggleInstallShot = useCallback(() => {
+        setShowingInstallShot((shown) => !shown);
+    }, []);
+    const hasInstallShot = Boolean(installationImageUrl);
+    return { hasInstallShot, showingInstallShot, toggleInstallShot };
+};
+/**
+ * Everything the provider derives rather than forwards: the selected variant,
+ * the install-shot toggle, availability, the product URL and the display flags.
+ */
+const useResolvedCard = ({ availability: availabilityProp, display, mode, onVariantChange, product, productUrl: buildProductUrl = defaultProductUrl, renderAddToCart, variantId, }) => {
+    const { currentVariant, handleVariantChange, selectedVariantId } = useVariantSelection({ mode, onVariantChange, product, variantId });
+    const { hasInstallShot, showingInstallShot, toggleInstallShot } = useInstallShot(currentVariant.installationImageUrl);
+    // An explicit availability wins; otherwise a variant the data marks
+    // unavailable reads as out of stock, as it did before the prop existed.
+    const availability = availabilityProp ??
+        (currentVariant.available === false ? "out-of-stock" : "available");
+    const productUrl = buildProductUrl(currentVariant);
+    const { productNameLines, showAddToCart, showProductBrand, showProductName, showSwatches, } = resolveDisplay(display, renderAddToCart !== undefined);
+    return useMemo(() => ({
+        availability,
+        currentVariant,
+        hasInstallShot,
+        onVariantChange: handleVariantChange,
+        productNameLines,
+        productUrl,
+        selectedVariantId,
+        showAddToCart,
+        showProductBrand,
+        showProductName,
+        showSwatches,
+        showingInstallShot,
+        toggleInstallShot,
+    }), [
+        availability,
+        currentVariant,
+        handleVariantChange,
+        hasInstallShot,
+        productNameLines,
+        productUrl,
+        selectedVariantId,
+        showAddToCart,
+        showProductBrand,
+        showProductName,
+        showSwatches,
+        showingInstallShot,
+        toggleInstallShot,
+    ]);
+};
+/**
+ * Context provider for ProductCard.
+ * Manages variant selection and provides product data + render seams to
+ * children. App-specific behaviour (navigation, cart, drag) is injected via
+ * props.
+ *
+ * @bestPractice Pass `renderImage` wrapping `next/image` in Next.js apps -
+ * the default renderer is a plain `<img>` and skips Next's optimisation.
+ * @bestPractice Keep `dragAdapter` referentially stable (a module-level
+ * constant) - an inline factory remounts the image subtree and drops the
+ * drag ref mid-drag.
+ * @category catalogue
+ */
+export const ProductCardProvider = ({ product, children, mode = "group", width, active = false, dragging = false, labels, showActivePointer = true, linkAs = "a", linkPrefetch, maxSwatches = 5, renderTools, renderImage = defaultRenderImage, renderAddToCart, dragAdapter, action, primaryAction, statusBadge, onQuickView, onAdd, onCardClick, addGlyph, menuOpen, onFindSimilar, price, processing, ...resolveInputs }) => {
+    const resolved = useResolvedCard({
+        ...resolveInputs,
+        mode,
+        product,
+        renderAddToCart,
+    });
+    const contextValue = useMemo(() => ({
+        ...resolved,
+        action,
+        active,
+        addGlyph,
+        dragAdapter,
+        dragging,
+        labels,
+        linkComponent: linkAs,
+        linkPrefetch,
+        maxSwatches,
+        menuOpen,
+        mode,
+        onAdd,
+        onCardClick,
+        onFindSimilar,
+        onQuickView,
+        price,
+        primaryAction,
+        processing,
+        product,
+        renderAddToCart,
+        renderImage,
+        renderTools,
+        showActivePointer,
+        statusBadge,
+        width,
+    }), [
+        resolved,
+        action,
+        active,
+        addGlyph,
+        dragAdapter,
+        dragging,
+        labels,
+        linkAs,
+        linkPrefetch,
+        maxSwatches,
+        menuOpen,
+        mode,
+        onAdd,
+        onCardClick,
+        onFindSimilar,
+        onQuickView,
+        price,
+        primaryAction,
+        processing,
+        product,
+        renderAddToCart,
+        renderImage,
+        renderTools,
+        showActivePointer,
+        statusBadge,
+        width,
+    ]);
+    return (_jsx(ProductCardContext.Provider, { value: contextValue, children: children }));
+};

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

@@ -0,0 +1,20 @@
+import type { ProductCardQuickViewProps } from "./product-card-types.js";
+/**
+ * ProductCardQuickView - a "Quick view" glass pill revealed at the
+ * bottom-center of the image on card hover/focus, 6px inside the photograph's
+ * bottom edge - the same inset the status badge and tool cluster take from the
+ * top corners. Prop-driven: renders
+ * nothing unless `onQuickView` is supplied. Reveal is pure CSS `group-hover`
+ * (a single element, so no per-card motion runtime), and the click never
+ * falls through to the card's primary link.
+ *
+ * `align="start"` anchors the pill bottom-left for the swatch tile, and
+ * `forceVisible` shows it without hover for a host that owns the reveal.
+ *
+ * Built on the canonical `Button`: `tone="neutral" emphasis="transparent"` is
+ * the DS media-glass treatment (`bg-primary/50 backdrop-blur-md` +
+ * `text-primary-foreground`) - the exact Figma `alpha-dark/50` glass with a
+ * light label. The only card-specific tweak is `text-caption` (Figma's 12px pill
+ * label).
+ */
+export declare const ProductCardQuickView: ({ onQuickView, label, align, className, forceVisible, placement, }: ProductCardQuickViewProps) => import("react").JSX.Element | null;

package/dist/compositions/product-card/product-card-quick-view.js

@@ -0,0 +1,44 @@
+"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 { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * ProductCardQuickView - a "Quick view" glass pill revealed at the
+ * bottom-center of the image on card hover/focus, 6px inside the photograph's
+ * bottom edge - the same inset the status badge and tool cluster take from the
+ * top corners. Prop-driven: renders
+ * nothing unless `onQuickView` is supplied. Reveal is pure CSS `group-hover`
+ * (a single element, so no per-card motion runtime), and the click never
+ * falls through to the card's primary link.
+ *
+ * `align="start"` anchors the pill bottom-left for the swatch tile, and
+ * `forceVisible` shows it without hover for a host that owns the reveal.
+ *
+ * Built on the canonical `Button`: `tone="neutral" emphasis="transparent"` is
+ * the DS media-glass treatment (`bg-primary/50 backdrop-blur-md` +
+ * `text-primary-foreground`) - the exact Figma `alpha-dark/50` glass with a
+ * light label. The only card-specific tweak is `text-caption` (Figma's 12px pill
+ * label).
+ */
+export const ProductCardQuickView = ({ onQuickView, label = "Quick view", align = "center", className, forceVisible = false, placement = "overlay", }) => {
+    if (!onQuickView) {
+        return null;
+    }
+    const handleClick = (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        onQuickView();
+    };
+    const control = (_jsx(Button, { className: cn("text-caption pointer-events-auto", className), emphasis: "transparent", onClick: handleClick, radius: "full", size: placement === "inline" ? "base" : "sm", tone: "neutral", children: label }));
+    return placement === "inline" ? (control) : (_jsx(Box, { className: cn("transition-opacity-transform duration-normal pointer-events-none absolute z-20 flex ease-in-out motion-reduce:transition-none", align === "start"
+            ? "bottom-1 left-1 justify-start"
+            : "inset-x-0 bottom-1.5 justify-center", 
+        // The swatch tile reveals on keyboard focus only: a click focuses its
+        // primary link, and `focus-within` would pin the pill open after the
+        // pointer leaves.
+        forceVisible && "translate-y-0 opacity-100", !forceVisible &&
+            (align === "start"
+                ? "translate-y-1 opacity-0 group-hover:translate-y-0 group-hover:opacity-100 group-has-focus-visible:translate-y-0 group-has-focus-visible:opacity-100"
+                : "translate-y-1 opacity-0 group-focus-within:translate-y-0 group-focus-within:opacity-100 group-hover:translate-y-0 group-hover:opacity-100")), children: control }));
+};