@instruments/materia-ui 0.1.0

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

@@ -0,0 +1,91 @@
+import type { BadgeTone } from "@instruments/materia-ui/components/badge";
+import type { IconProps } from "@instruments/materia-ui/components/icon";
+import type { ComponentProps, ComponentType, DOMAttributes, ReactNode } from "react";
+import type { ProductCardProduct } from "./product-card-product-types.js";
+/**
+ * Props passed to the {@link ProductCardRenderImage} slot.
+ */
+interface ProductCardImageRenderProps {
+    alt: string;
+    className?: string;
+    draggable?: boolean;
+    /** Fill mode (for next/image to fill a positioned parent). */
+    fill?: boolean;
+    priority?: boolean;
+    /** Responsive `sizes` hint (consumed by next/image wrappers). */
+    sizes?: string;
+    src: string;
+}
+/**
+ * Render slot for framework-specific image components (e.g. next/image).
+ * The default renderer is a plain `<img>` filling its positioned parent.
+ */
+type ProductCardRenderImage = (props: ProductCardImageRenderProps) => ReactNode;
+/**
+ * Drag state and wiring handed to a {@link ProductCardDragAdapter}'s
+ * children function.
+ */
+interface ProductCardDragHandle {
+    isDragging: boolean;
+    listeners?: DOMAttributes<HTMLElement> | undefined;
+    setNodeRef?: ((node: HTMLElement | null) => void) | undefined;
+}
+/**
+ * Props received by a {@link ProductCardDragAdapter} component.
+ */
+interface ProductCardDragAdapterProps {
+    children: (handle: ProductCardDragHandle) => ReactNode;
+    imageUrl: string;
+    product: ProductCardProduct;
+    variantId: string;
+    variantName: string;
+}
+/**
+ * Component slot that wires drag behaviour (e.g. dnd-kit `useDraggable`)
+ * around the card image. When absent, the image renders as a static handle.
+ */
+type ProductCardDragAdapter = ComponentType<ProductCardDragAdapterProps>;
+interface ProductCardImageProps extends ComponentProps<"div"> {
+    /** Override image URL - used for visual search to show the matched image */
+    overrideImageUrl?: string | undefined;
+    /** Prioritise loading this image (sets loading="eager" and adds preload link) */
+    priority?: boolean | undefined;
+    showSimilarityScore?: boolean | undefined;
+    similarityScore?: number | undefined;
+}
+/**
+ * Props for the "Quick view" glass pill revealed over the image on hover.
+ * Prop-driven: renders only when `onQuickView` is supplied.
+ */
+interface ProductCardQuickViewProps {
+    /**
+     * Where the pill sits along the image's bottom edge. `"start"` is the swatch
+     * tile's bottom-left.
+     * @default "center"
+     */
+    align?: "center" | "start" | undefined;
+    className?: string;
+    /** Show the pill without hover or focus, for a host that owns the reveal. */
+    forceVisible?: boolean | undefined;
+    /** Pill label. @default "Quick view" */
+    label?: string;
+    /** Render inside a shared action row rather than as an image overlay. */
+    placement?: "inline" | "overlay";
+    /** Invoked when the pill is activated. When omitted, nothing renders. */
+    onQuickView?: (() => void) | undefined;
+}
+/**
+ * Props for the optional image-overlay status badge (e.g. "New").
+ * Prop-driven: the card renders it only when supplied.
+ */
+interface ProductCardStatusBadgeProps {
+    /** Context-specific icon styling; text badges keep their owned treatment. */
+    className?: string;
+    /** Optional icon-only presentation beside the product identity. */
+    icon?: IconProps["icon"];
+    /** Badge text. When omitted, nothing renders. */
+    label?: string;
+    /** Badge tone. @default "brand" (the yellow "New" badge). */
+    tone?: BadgeTone;
+}
+export type { ProductCardDragAdapter, ProductCardDragAdapterProps, ProductCardDragHandle, ProductCardImageProps, ProductCardImageRenderProps, ProductCardQuickViewProps, ProductCardRenderImage, ProductCardStatusBadgeProps, };

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

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

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

@@ -0,0 +1,12 @@
+import type { ProductCardImageProps } from "./product-card-types.js";
+declare const ProductCardImageBase: ({ className, showSimilarityScore, similarityScore, overrideImageUrl, priority, ...props }: ProductCardImageProps) => import("react").JSX.Element;
+/**
+ * ProductCardImage - the card's image region. Default mode renders a
+ * container-query-responsive inset image with hover swap, similarity score,
+ * and unavailable badge; inspiration mode renders a full-bleed image. Images
+ * go through the context `renderImage` seam and drag wiring goes through the
+ * context `dragAdapter` seam - with no adapter, the image renders as a
+ * static handle through the same code path.
+ */
+export declare const ProductCardImage: import("react").MemoExoticComponent<typeof ProductCardImageBase>;
+export {};

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

@@ -0,0 +1,175 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { MediaFrame } from "@instruments/materia-ui/components/media-frame";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { memo, useMemo } from "react";
+import { ProductCardAvailabilityStatus } from "./product-card-availability.js";
+import { useProductCard } from "./product-card-context.js";
+/**
+ * Handle used when no `dragAdapter` is provided: a static, non-draggable
+ * image. Module-level so its identity is stable across renders.
+ */
+const STATIC_DRAG_HANDLE = { isDragging: false };
+/**
+ * A card with no photograph still occupies the photograph's FRAME.
+ *
+ * It has to take the same `pt-4 px-4` inset, the same square, and the same
+ * corner radius the real image takes at each width - otherwise a product
+ * with no picture runs 16px taller than its neighbours and bleeds to the
+ * card's edge, and a mixed grid rows unevenly for a reason that has nothing to
+ * do with the products.
+ */
+const NoPhotographyState = ({ className, inspiration, productName, }) => {
+    if (inspiration) {
+        return (_jsx("output", { "aria-label": `Photography unavailable for ${productName}`, className: cn("bg-muted/45 absolute inset-0 overflow-hidden rounded-3xl", className), "data-component": "product-card-image-unavailable" }));
+    }
+    return (_jsx("output", { "aria-label": `Photography unavailable for ${productName}`, className: cn("block w-full @[180px]/product-card:px-4 @[180px]/product-card:pt-4", className), "data-component": "product-card-image-unavailable", children: _jsx("span", { className: "bg-muted/45 block aspect-square w-full overflow-hidden rounded-3xl @[180px]/product-card:rounded-2xl" }) }));
+};
+/**
+ * The photograph itself, filling the frame `DraggableImage` insets - the
+ * container-query padding lives there, not here - with the optional hover or
+ * pinned swap to a second image.
+ */
+const ImageContent = ({ imageSrc, hoverImageSrc, showingInstallShot, productName, priority, sizes, }) => {
+    const { renderImage } = useProductCard();
+    const hasHoverImage = hoverImageSrc !== undefined && hoverImageSrc !== "";
+    // Two ways to reveal the same second image, and only ever one of them. A card
+    // with a toggle must NOT also swap on hover: the pair would fight, and the
+    // toggle would appear not to work while the pointer sat on the card.
+    const isControlled = showingInstallShot !== undefined;
+    // Which visibility rule each layer follows, resolved once. Controlled cards
+    // pin the second image to the toggle; uncontrolled ones keep the hover swap.
+    let productImageFade = "group-hover:opacity-0";
+    let installImageFade = "opacity-0 group-hover:opacity-100";
+    if (isControlled) {
+        productImageFade = showingInstallShot ? "opacity-0" : "";
+        installImageFade = showingInstallShot ? "opacity-100" : "opacity-0";
+    }
+    return (_jsx(Box, { className: "absolute inset-0 overflow-hidden", children: _jsxs(MediaFrame, { className: "size-full rounded-3xl @[180px]/product-card:rounded-2xl", children: [renderImage({
+                    alt: `${productName} - Product image`,
+                    className: cn("object-cover", hasHoverImage && "duration-normal transition-opacity ease-out", hasHoverImage && productImageFade),
+                    draggable: false,
+                    fill: true,
+                    priority: priority ?? false,
+                    sizes,
+                    src: imageSrc,
+                }), hasHoverImage && (_jsx(Box, { className: "absolute inset-0", children: renderImage({
+                        alt: `${productName} - Installation view`,
+                        className: cn("duration-normal object-cover transition-opacity ease-out", installImageFade),
+                        draggable: false,
+                        fill: true,
+                        sizes,
+                        src: hoverImageSrc,
+                    }) }))] }) }));
+};
+/**
+ * The default-mode image region: the drag handle div (all drag presentation -
+ * `data-component` attribute, touch-action, isDragging opacity/scale, click
+ * capture nav-cancel) framing the inset image, similarity score, and
+ * availability status.
+ */
+const DraggableImage = ({ className, imageSrc, hoverImageSrc, variantName, showSimilarityScore, similarityScore, showingInstallShot, priority, sizes, dragListeners, isDragging, ref, ...props }) => {
+    const shouldShowSimilarityScore = showSimilarityScore && similarityScore !== undefined;
+    const dragging = isDragging === true;
+    return (_jsx(Box, { className: cn(
+        // The design draws the image frame as `pt-16 px-16 pb-0` around a SQUARE
+        // photograph: inset from the card's left, right and top, flush with the
+        // frame's own bottom. A square region with padding on all four sides
+        // put 24px of air between the photograph and the brand name where the
+        // design asks for 8, and that gap is most of why the card read loose.
+        "group relative w-full shrink-0 overflow-hidden bg-transparent @[180px]/product-card:px-4 @[180px]/product-card:pt-4", className), "data-component": "product-card-image", onClickCapture: (e) => {
+            // Cancel parent anchor navigation when the user is dragging this card.
+            if (dragging) {
+                e.preventDefault();
+                e.stopPropagation();
+            }
+        }, ref: ref, style: {
+            opacity: dragging ? 0 : 1,
+            scale: dragging ? 0.9 : 1,
+            touchAction: "none",
+            transition: "opacity 300ms ease-out, scale 300ms ease-out",
+        }, ...dragListeners, ...props, children: _jsxs(MediaFrame, { className: "@[180px]/product-card:bg-card relative aspect-square w-full rounded-3xl bg-gray-100 @[180px]/product-card:rounded-2xl", children: [_jsx(ImageContent, { hoverImageSrc: hoverImageSrc, imageSrc: imageSrc, showingInstallShot: showingInstallShot, priority: priority, productName: variantName, sizes: sizes }), shouldShowSimilarityScore ? (_jsx(Box, { className: "absolute right-2 bottom-2 z-10", children: _jsxs(Box, { as: "span", className: "glass-media text-micro rounded px-1.5 py-0.5 text-white/70", children: [(similarityScore * 100).toFixed(0), "%"] }) })) : null, _jsx(ProductCardAvailabilityStatus, {})] }) }));
+};
+const SwatchImage = ({ className, dragListeners, imageSizes, isDragging, mainImage, priority, ref, ...props }) => {
+    const { currentVariant, renderImage } = useProductCard();
+    return (_jsxs(Box, { className: cn("relative size-full overflow-hidden rounded-2xl bg-transparent", className), "data-component": "product-card-image", onClickCapture: (e) => {
+            if (isDragging) {
+                e.preventDefault();
+                e.stopPropagation();
+            }
+        }, ref: ref, style: {
+            opacity: isDragging ? 0 : 1,
+            touchAction: "none",
+            transition: "opacity 300ms ease-out",
+        }, ...dragListeners, ...props, children: [renderImage({
+                alt: `${currentVariant.name} - Product image`,
+                className: "object-cover",
+                draggable: false,
+                fill: true,
+                priority: priority ?? false,
+                sizes: imageSizes,
+                src: mainImage,
+            }), _jsx(ProductCardAvailabilityStatus, {})] }));
+};
+const ProductCardImageBase = ({ className, showSimilarityScore = false, similarityScore, overrideImageUrl, priority, ...props }) => {
+    const { mode, width, product, currentVariant, dragAdapter: DragAdapter, renderImage, showingInstallShot, } = useProductCard();
+    // Get images from the current variant
+    const images = useMemo(() => currentVariant.images.filter(Boolean), [currentVariant.images]);
+    // Which image the card is showing. Local to the card because it is a way of
+    // LOOKING at one product, not a selection anything else needs to know about.
+    // Resets naturally when the card unmounts, which is what a grid wants.
+    const mainImage = overrideImageUrl ?? images[0];
+    if (images.length === 0 || mainImage === undefined || mainImage === "") {
+        return (_jsx(NoPhotographyState, { className: className, inspiration: mode === "inspiration", productName: product.name }));
+    }
+    const [, hoverImage] = images;
+    // The installation view is a NAMED field, never image position. A product
+    // whose second photograph is merely another angle keeps the passive hover
+    // swap and gets no control promising a room shot.
+    const installShot = currentVariant.installationImageUrl;
+    const hasInstallShot = installShot !== undefined && installShot !== "";
+    // Image sizes hint: use explicit width if provided, otherwise responsive default
+    const imageSizes = width === undefined || width === 0
+        ? "(max-width: 480px) 50vw, 272px"
+        : `${width}px`;
+    // One render path for both drag states: with an adapter the handle comes
+    // from the adapter's children function; without one it is the static
+    // handle. The JSX below is shared between the two branches.
+    const withDragAdapter = (render) => {
+        if (DragAdapter) {
+            return (_jsx(DragAdapter, { imageUrl: mainImage, product: product, variantId: currentVariant.id, variantName: currentVariant.name, children: render }));
+        }
+        return render(STATIC_DRAG_HANDLE);
+    };
+    // Swatch mode: a full-bleed square. The tile owns its chrome (add control,
+    // Quick view, caption); this renders the photograph and its status only.
+    if (mode === "swatch") {
+        return withDragAdapter((handle) => (_jsx(SwatchImage, { className: className, dragListeners: handle.listeners, imageSizes: imageSizes, isDragging: handle.isDragging, mainImage: mainImage, priority: priority, ref: handle.setNodeRef, ...props })));
+    }
+    // Inspiration mode: use the named installation photograph when available;
+    // never infer it from the position of an image in the array.
+    if (mode === "inspiration") {
+        const shouldShowSimilarityScore = showSimilarityScore && similarityScore !== undefined;
+        return withDragAdapter((handle) => (_jsxs(Box, { className: cn("absolute inset-0 overflow-hidden rounded-3xl", className), "data-component": "product-card-image", ref: handle.setNodeRef, style: { touchAction: "none" }, children: [renderImage({
+                    alt: `${product.name} - ${product.brand?.name ?? ""}`,
+                    className: "rounded-3xl object-cover",
+                    draggable: false,
+                    fill: true,
+                    priority: priority ?? false,
+                    sizes: "(min-width: 1536px) 18vw, (min-width: 1280px) 20vw, (min-width: 1024px) 25vw, (min-width: 640px) 33vw, 50vw",
+                    src: currentVariant.inspirationImageUrl ?? installShot ?? mainImage,
+                }), _jsx(ProductCardAvailabilityStatus, {}), shouldShowSimilarityScore ? (_jsxs(Box, { className: "text-caption absolute top-3 left-3 z-10 rounded-full bg-white/85 px-2 py-0.5 font-mono text-gray-800 shadow-sm backdrop-blur-xl", children: [(similarityScore * 100).toFixed(0), "%"] })) : null] })));
+    }
+    // Unified default: @container-responsive image with optional hover swap
+    return withDragAdapter((handle) => (_jsx(DraggableImage, { className: className, dragListeners: handle.listeners, hoverImageSrc: hasInstallShot ? installShot : hoverImage, imageSrc: mainImage, isDragging: handle.isDragging, showingInstallShot: hasInstallShot ? showingInstallShot : undefined, priority: priority, ref: handle.setNodeRef, showSimilarityScore: mode === "single" && showSimilarityScore, similarityScore: similarityScore, sizes: imageSizes, variantName: currentVariant.name, ...props })));
+};
+/**
+ * ProductCardImage - the card's image region. Default mode renders a
+ * container-query-responsive inset image with hover swap, similarity score,
+ * and unavailable badge; inspiration mode renders a full-bleed image. Images
+ * go through the context `renderImage` seam and drag wiring goes through the
+ * context `dragAdapter` seam - with no adapter, the image renders as a
+ * static handle through the same code path.
+ */
+export const ProductCardImage = memo(ProductCardImageBase);

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

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+import type { useToolsActivity } from "./product-card-tools-activity.js";
+interface ProductCardInspirationContentProps {
+    className?: string | undefined;
+    inspirationControl: ReactNode;
+    interactionHandlers: ReturnType<typeof useToolsActivity>["interactionHandlers"];
+    priority?: boolean | undefined;
+    similarityScore?: number | undefined;
+    toolsActive: boolean;
+}
+/** Inspiration mode: an image-forward card with a hover overlay. */
+export declare const ProductCardInspirationContent: ({ className, inspirationControl, interactionHandlers, priority, similarityScore, toolsActive, }: ProductCardInspirationContentProps) => import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,24 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { Text } from "@instruments/materia-ui/components/text";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useProductCard } from "./product-card-context.js";
+import { ProductCardImage } from "./product-card-image.js";
+import { ProductCardQuickView } from "./product-card-quick-view.js";
+import { ProductCardTools } from "./product-card-tools.js";
+/** Brand and product name, over the image on hover. */
+const InspirationCaption = () => {
+    const { currentVariant, product, showProductBrand, showProductName } = useProductCard();
+    const brandName = product.brand?.name.trim();
+    const hasBrandName = brandName !== undefined && brandName !== "";
+    return (_jsx(Box, { className: "min-w-0", children: _jsxs(Box, { className: "min-w-0", children: [showProductBrand && hasBrandName ? (_jsx(Text, { className: "text-caption truncate text-white/75", children: brandName })) : null, showProductName ? (_jsx(Text, { className: "text-paragraph-sm truncate font-semibold text-white", children: currentVariant.name })) : null] }) }));
+};
+/** Inspiration mode: an image-forward card with a hover overlay. */
+export const ProductCardInspirationContent = ({ className, inspirationControl, interactionHandlers, priority, similarityScore, toolsActive, }) => {
+    const { availability, currentVariant, onCardClick, onQuickView, showProductBrand, showProductName, } = useProductCard();
+    const shouldShowCaption = showProductBrand || showProductName;
+    const hasInspirationControl = inspirationControl !== null && inspirationControl !== undefined;
+    return (_jsxs(Box, { className: cn("group bg-card duration-normal relative isolate h-full min-h-80 overflow-hidden rounded-3xl shadow-sm transition-shadow ease-in-out [clip-path:inset(0_round_1.5rem)] hover:shadow-md", className), "data-component": "product-card", "data-testid": "product-card", ...interactionHandlers, children: [_jsx(Box, { className: "absolute inset-0", children: _jsx(ProductCardImage, { priority: priority, showSimilarityScore: similarityScore !== undefined, similarityScore: similarityScore }) }), _jsx(ProductCardTools, { active: toolsActive }), _jsxs(Box, { className: "pointer-events-none absolute inset-0 overflow-hidden rounded-3xl", children: [_jsx(Box, { "aria-hidden": true, className: "duration-normal absolute inset-0 bg-linear-to-t from-gray-950/60 via-gray-950/20 via-40% to-transparent opacity-0 transition-opacity group-focus-within:opacity-100 group-hover:opacity-100" }), shouldShowCaption || hasInspirationControl ? (_jsx(Box, { className: "duration-normal absolute inset-x-0 bottom-0 z-20 translate-y-2 overflow-hidden opacity-0 transition group-focus-within:translate-y-0 group-focus-within:opacity-100 group-hover:translate-y-0 group-hover:opacity-100", children: _jsxs(Box, { className: "flex w-full flex-col gap-3 bg-linear-to-t from-gray-950/80 via-gray-950/55 to-transparent px-3 pt-10 pb-3 sm:px-4 sm:pt-12 sm:pb-4", children: [shouldShowCaption ? _jsx(InspirationCaption, {}) : null, onQuickView || hasInspirationControl ? (_jsxs(Box, { className: "grid w-full grid-cols-2 gap-2", children: [_jsx(ProductCardQuickView, { className: "w-full", onQuickView: onQuickView, placement: "inline" }), inspirationControl] })) : null] }) })) : null] }), _jsx("button", { "aria-label": `View ${currentVariant.name}`, className: cn(focusRing(), "absolute inset-0 z-10 cursor-pointer rounded-3xl disabled:cursor-default", "focus-visible:ring-inset"), disabled: availability === "blocked", onClick: () => onCardClick?.(), type: "button" })] }));
+};

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

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+/**
+ * The install-shot toggle - "show me this in a room".
+ *
+ * The card cross-fades to a second image on hover, which is lovely and
+ * completely undiscoverable: you cannot know an installation shot exists until
+ * you happen to point at the card, and while you are pointing at it you can no
+ * longer look at the product you came to see. This makes it a control.
+ *
+ * **It is a SIBLING of the card link, never a child of it.** A `<button>` inside
+ * an `<a>` is invalid HTML with user-agent-dependent focus behaviour, and the
+ * outer control's label swallows the inner one for assistive technology. It sits
+ * in the same overlay layer as Quick view for exactly that reason, and reads its
+ * state from context rather than taking it as a prop.
+ *
+ * **The label does not change with state.** `aria-pressed` already carries "on
+ * or off"; flipping the visible text as well makes one control read as two
+ * different buttons, and "Product, toggle button, pressed" is incoherent spoken.
+ *
+ * **It stays visible while pressed.** A control that vanishes once used leaves
+ * the card showing a room with no way back and nothing explaining why the image
+ * is not the product.
+ */
+export interface ProductCardInstallShotToggleProps {
+    className?: string | undefined;
+}
+export declare const ProductCardInstallShotToggle: ({ className, }: ProductCardInstallShotToggleProps) => ReactNode;

package/dist/compositions/product-card/product-card-install-shot.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Frame } from "lucide-react";
+import { useProductCard } from "./product-card-context.js";
+export const ProductCardInstallShotToggle = ({ className, }) => {
+    const { currentVariant, hasInstallShot, showingInstallShot, toggleInstallShot, } = useProductCard();
+    // No installation photograph, no control. Same rule the primary action
+    // follows: a missing capability is an absent element, never a disabled one.
+    if (!hasInstallShot) {
+        return null;
+    }
+    return (_jsxs("button", { "aria-label": `Show ${currentVariant.name} in a room`, "aria-pressed": showingInstallShot, className: cn(
+        // A glass pill matching Quick view rather than inventing a third overlay
+        // language.
+        "pointer-events-auto absolute inline-flex h-8 items-center gap-1.5 rounded-full bg-gray-950/70 px-3 text-white backdrop-blur-sm", "text-caption font-medium", "transition-opacity-bg duration-normal ease-in-out", "hover:bg-gray-950/85", 
+        // Revealed with the card's other hover furniture - EXCEPT when pressed,
+        // where it must persist, and on touch, where `group-hover` effectively
+        // never fires and the control would be unreachable precisely where an
+        // explicit affordance mattered most.
+        showingInstallShot
+            ? "opacity-100"
+            : "opacity-0 group-hover:opacity-100 focus-visible:opacity-100 [@media(hover:none)]:opacity-100", className), onClick: (event) => {
+            // The card is a link. Changing which photograph it shows is not
+            // navigation, so this must not bubble into one.
+            event.preventDefault();
+            event.stopPropagation();
+            toggleInstallShot();
+        }, type: "button", children: [_jsx(Icon, { icon: Frame, size: "xs" }), "In a room"] }));
+};

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

@@ -0,0 +1,21 @@
+import type { ElementType, ReactNode } from "react";
+import type { ProductCardHref } from "./product-card-types.js";
+interface ProductCardLinkProps {
+    /** The product cannot be opened by this viewer: render no link at all. */
+    blocked?: boolean | undefined;
+    children: ReactNode;
+    className?: string | undefined;
+    href: ProductCardHref;
+    label: string;
+    linkComponent: ElementType;
+    onActivate?: (() => void) | undefined;
+    prefetch?: boolean | undefined;
+}
+/**
+ * The card's one navigation target: a button when the application handles the
+ * click, an `<a>` for external URLs, otherwise the injected `linkAs`
+ * component. A `blocked` product gets a plain wrapper, because a link to a page
+ * the viewer may not open is a broken promise.
+ */
+export declare const ProductCardLink: ({ blocked, children, className, href, label, linkComponent: LinkComp, onActivate, prefetch, }: ProductCardLinkProps) => import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createElement } from "react";
+/**
+ * The card's one navigation target: a button when the application handles the
+ * click, an `<a>` for external URLs, otherwise the injected `linkAs`
+ * component. A `blocked` product gets a plain wrapper, because a link to a page
+ * the viewer may not open is a broken promise.
+ */
+export const ProductCardLink = ({ blocked = false, children, className, href, label, linkComponent: LinkComp, onActivate, prefetch, }) => {
+    if (blocked) {
+        return _jsx("div", { className: className, children: children });
+    }
+    if (onActivate) {
+        return (_jsx("button", { "aria-label": label, className: className, onClick: onActivate, type: "button", children: children }));
+    }
+    // External URLs always use a plain <a> - no client-side routing needed.
+    if (href.startsWith("http")) {
+        return (_jsx("a", { "aria-label": label, className: className, href: href, children: children }));
+    }
+    // `linkComponent` is a polymorphic ElementType; createElement renders it
+    // without JSX's children-typing narrowing to `never` on the ComponentType arm.
+    return createElement(LinkComp, {
+        "aria-label": label,
+        className,
+        href,
+        prefetch,
+    }, children);
+};

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

@@ -0,0 +1 @@
+export declare const ProductCardMeta: () => import("react").JSX.Element | null;

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

@@ -0,0 +1,26 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box } from "@instruments/materia-ui/components/box";
+import { HStack } from "@instruments/materia-ui/components/stack";
+import { Text } from "@instruments/materia-ui/components/text";
+import { ProductCardCategory } from "./product-card-category.js";
+import { useProductCard } from "./product-card-context.js";
+import { ProductCardCost, hasProductCardPrice } from "./product-card-cost.js";
+// The design separates the badge row with a BULLET on a 4px rhythm, the same
+// glyph the category tooltip already uses for its level-3 suffix.
+const Dot = ({ show }) => show ? (_jsx(Box, { as: "span", className: "mx-1 shrink-0", children: "\u2022" })) : null;
+export const ProductCardMeta = () => {
+    const { price, product } = useProductCard();
+    const showCategory = (product.displayCategory?.name ?? "") !== "";
+    const showProductType = !showCategory && (product.productType ?? "") !== "";
+    const showCost = hasProductCardPrice(price) || (product.costIndicator ?? "") !== "";
+    // The colourway circles are their own ROW beneath this line (badge row at
+    // y=48, swatches at y=72), not a dot-separated segment after the price. Swatches are pictures; a bullet between a price and a picture
+    // reads as punctuation between two unlike things.
+    const hasAnyMeta = showCategory || showProductType || showCost;
+    if (!hasAnyMeta) {
+        return null;
+    }
+    const showCostSeparator = showCategory || showProductType;
+    return (_jsxs(HStack, { className: "text-muted-foreground text-caption w-full items-center", gap: "none", children: [showCategory ? _jsx(ProductCardCategory, {}) : null, showProductType ? (_jsx(Text, { size: "caption", variant: "muted", render: _jsx("span", { className: "min-w-0 truncate" }), children: product.productType })) : null, showCost ? (_jsxs(_Fragment, { children: [_jsx(Dot, { show: showCostSeparator }), _jsx(Box, { as: "span", className: "shrink-0", children: _jsx(ProductCardCost, {}) })] })) : null] }));
+};

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

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+/**
+ * The card's one labelled control, resolved from
+ * {@link ProductCardPrimaryAction}. It spans the card until the card is wide
+ * enough to let it hug - see `PRODUCT_CARD_CTA_WIDTH`.
+ *
+ * A grid can mix fabrics, chairs, taps and catalogue products, and this control
+ * is the only thing that tells them apart. It is implemented here rather than
+ * as a badge: the card does not label what a product is, it offers what the
+ * product can actually do.
+ *
+ * **There is no disabled arm, deliberately.** A product that can do nothing
+ * gets no `primaryAction` and therefore no control - an absent element, never a
+ * greyed one. A greyed *Add to cart* tells a designer a sample exists and is
+ * merely unavailable, which for a chair is a lie.
+ */
+interface ProductCardPrimaryActionControlProps {
+    className?: string | undefined;
+    /** Callback after a successful add, forwarded to the cart slot. */
+    onAdded?: (() => void) | undefined;
+}
+/**
+ * *Find similar*, standing in for the primary action when the product cannot
+ * be acted on and the application supplied `onFindSimilar`. A real button: it
+ * acts, it does not navigate, and its click never reaches the card's link.
+ */
+export declare const ProductCardFindSimilar: ({ onImage, }: {
+    /** The control sits over a photograph, so it takes the glass treatment. */
+    onImage?: boolean | undefined;
+}) => ReactNode;
+export declare const ProductCardPrimaryActionControl: ({ className, onAdded, }: ProductCardPrimaryActionControlProps) => ReactNode;
+export {};

package/dist/compositions/product-card/product-card-primary-action.js

@@ -0,0 +1,91 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Button } from "@instruments/materia-ui/components/button";
+import { BookOpen, ScanSearch } from "@instruments/materia-ui/icons";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { createElement } from "react";
+import { PRODUCT_CARD_CTA_WIDTH, ProductCardAddToCart, } from "./product-card-add-to-cart.js";
+import { useProductCard } from "./product-card-context.js";
+/**
+ * A control that navigates, or calls back, without knowing which it is.
+ *
+ * It takes the SAME width rule the cart takes. A mixed grid puts *Add to
+ * cart*, *Show 47 finishes* and *View in catalogue* in one row, and a hug-width
+ * button beside full-width ones reads as a broken row rather than a different
+ * state - so the rule has to be shared, not per-kind.
+ */
+const ActionControl = ({ children, className, href, icon, linkComponent, onActivate, prefetch, }) => {
+    if (onActivate) {
+        return (_jsx(Button, { className: className, onClick: onActivate, emphasis: "outline", icon: icon, size: "base", children: children }));
+    }
+    if (href === undefined) {
+        return null;
+    }
+    // External URLs take a plain anchor - no client-side routing to do.
+    if (href.startsWith("http")) {
+        return (_jsx(Button, { className: className, emphasis: "outline", icon: icon, size: "base", render: (anchorProps) => (_jsx("a", { ...anchorProps, href: href, children: anchorProps.children })), children: children }));
+    }
+    return (_jsx(Button, { className: className, emphasis: "outline", icon: icon, render: createElement(linkComponent, { href, prefetch }), size: "base", children: children }));
+};
+/**
+ * *Find similar*, standing in for the primary action when the product cannot
+ * be acted on and the application supplied `onFindSimilar`. A real button: it
+ * acts, it does not navigate, and its click never reaches the card's link.
+ */
+export const ProductCardFindSimilar = ({ onImage = false, }) => {
+    const { labels, onFindSimilar } = useProductCard();
+    if (onFindSimilar === undefined) {
+        return null;
+    }
+    const handleClick = (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        onFindSimilar();
+    };
+    return (_jsx(Button, { className: onImage
+            ? "pointer-events-auto relative z-30 w-full border-white/50 bg-white/10 text-white hover:bg-white/20 @[240px]/product-card:w-auto"
+            : "w-full @[240px]/product-card:w-auto", emphasis: "outline", icon: ScanSearch, onClick: handleClick, size: "base", children: labels?.findSimilar ?? "Find similar" }));
+};
+const unsupportedPrimaryAction = (action) => {
+    throw new Error(`Unsupported product card primary action: ${JSON.stringify(action)}`);
+};
+export const ProductCardPrimaryActionControl = ({ className, onAdded, }) => {
+    const { linkComponent, linkPrefetch, primaryAction, productUrl } = useProductCard();
+    if (primaryAction === undefined) {
+        return null;
+    }
+    const shared = {
+        className: cn(PRODUCT_CARD_CTA_WIDTH, className),
+        linkComponent,
+        prefetch: linkPrefetch,
+    };
+    switch (primaryAction.kind) {
+        case "add-to-cart": {
+            // No width class here: `ProductCardAddToCart` applies
+            // `PRODUCT_CARD_CTA_WIDTH` itself, and so does every arm below, so a
+            // mixed row breaks and hugs as one.
+            return _jsx(ProductCardAddToCart, { className: className, onAdd: onAdded });
+        }
+        case "show-finishes": {
+            // The count is the total for this product, not the length of one page of
+            // finishes, which would understate the manufacturer's range.
+            const handleActivate = primaryAction.onActivate;
+            return (_jsx(ActionControl, { ...shared, href: primaryAction.href ?? productUrl, onActivate: handleActivate, children: primaryAction.label ??
+                    (primaryAction.count === undefined
+                        ? "Show finishes"
+                        : `Show ${primaryAction.count} ${primaryAction.count === 1 ? "finish" : "finishes"}`) }));
+        }
+        case "view-only": {
+            // Live, not disabled. It goes to the detail page, which is where the
+            // sentence explaining the state belongs.
+            return (_jsx(ActionControl, { ...shared, href: productUrl, children: primaryAction.label ?? "View only" }));
+        }
+        case "view-in-catalogue": {
+            const handleActivate = primaryAction.onActivate;
+            return (_jsx(ActionControl, { ...shared, href: primaryAction.href ?? productUrl, icon: BookOpen, onActivate: handleActivate, children: primaryAction.label ?? "View in catalog" }));
+        }
+        default: {
+            return unsupportedPrimaryAction(primaryAction);
+        }
+    }
+};

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

@@ -0,0 +1,9 @@
+import type { ProductCardProcessingProps } from "./product-card-types.js";
+/**
+ * Swatch-mode processing footer: a process chip on the left, the elapsed time
+ * on the right. Replaces the brand/name caption while a job runs. The chip is
+ * a button only when `onClick` is supplied.
+ */
+export declare const ProductCardProcessing: ({ className, elapsed, label, onClick, }: ProductCardProcessingProps & {
+    className?: string | undefined;
+}) => import("react").JSX.Element;

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

@@ -0,0 +1,22 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from "@instruments/materia-ui/components/button";
+import { Icon } from "@instruments/materia-ui/components/icon";
+import { HStack } from "@instruments/materia-ui/components/stack";
+import { Text } from "@instruments/materia-ui/components/text";
+import { ChartNoAxesColumn, ChevronDown } from "@instruments/materia-ui/icons";
+import { cn } from "@instruments/materia-ui/utils/cn";
+/**
+ * Swatch-mode processing footer: a process chip on the left, the elapsed time
+ * on the right. Replaces the brand/name caption while a job runs. The chip is
+ * a button only when `onClick` is supplied.
+ */
+export const ProductCardProcessing = ({ className, elapsed, label = "Matching materials", onClick, }) => {
+    const handleClick = (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        onClick?.();
+    };
+    const chip = (_jsxs(_Fragment, { children: [_jsx(Icon, { icon: ChartNoAxesColumn, size: "xs" }), _jsx(Text, { as: "span", className: "min-w-0 truncate", size: "caption", weight: "medium", children: label }), _jsx(Icon, { icon: ChevronDown, size: "xs" })] }));
+    return (_jsxs(HStack, { className: cn("h-10 w-full items-center justify-between p-1", className), "data-component": "product-card-processing", children: [onClick ? (_jsx(Button, { className: "text-muted-foreground min-w-0 gap-1", emphasis: "ghost", onClick: handleClick, size: "sm", tone: "neutral", children: chip })) : (_jsx(HStack, { className: "bg-background text-muted-foreground min-w-0 items-center gap-1 rounded-sm px-1.5 py-1", children: chip })), elapsed !== undefined && elapsed !== "" ? (_jsx(Text, { className: "text-muted-foreground shrink-0 px-1 whitespace-nowrap", size: "caption", weight: "medium", children: elapsed })) : null] }));
+};