@instruments/materia-ui 0.1.0

package/dist/compositions/page-toolbar/page-toolbar-root.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Flex } from "@instruments/materia-ui/components/flex";
+import { ScrollFrame } from "@instruments/materia-ui/components/scroll-frame";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useRef } from "react";
+import { useStuck } from "./use-stuck.js";
+/**
+ * A page's filter and view bar. It sits beneath the page header and holds to
+ * the top of the window, under the app's header, while the page scrolls: the
+ * filters on one side, scrolling sideways when there are more than fit, and
+ * the sort and view controls on the other. At rest it reads as part of the
+ * page; once it is holding, a hairline separates it from the content passing
+ * beneath.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ *
+ * @example
+ * <PageToolbar aria-label="Filters">
+ *   <PageToolbarFilters button={<PageToolbarFiltersButton count={applied.length} />}>
+ *     <PageToolbarApplied onClear={clear}>
+ *       <PageToolbarFilter pressed>Tile</PageToolbarFilter>
+ *     </PageToolbarApplied>
+ *     <PageToolbarFilter count={31}>Stone</PageToolbarFilter>
+ *   </PageToolbarFilters>
+ *   <PageToolbarActions>
+ *     <PageToolbarSort onValueChange={setSort} options={SORTS} value={sort} />
+ *   </PageToolbarActions>
+ * </PageToolbar>
+ *
+ * @bestPractice Place it straight after the `PageHeader`, in the column that holds the page's content; the title scrolls away and the toolbar stays.
+ * @bestPractice Order the leading side the same on every page: `PageToolbarFiltersButton` first, in the `button` slot so it holds still carrying the applied count; then `PageToolbarApplied`, the filters in force with Clear all; then the suggestions.
+ * @bestPractice Applied filters always lead, so they never scroll out of view behind suggestions. Pressing a suggestion moves it into the applied group; it is never shown twice.
+ * @bestPractice When a filter rail holds the facets, the toolbar still shows what the rail has applied, with no suggestions after it (`separator={false}`).
+ * @bestPractice Each facet appears once. A `SegmentedControl` when the facet splits the set and one part is viewed at a time (its counts sum to the total); `PageToolbarFilter` chips when several combine. Never both for the same facet.
+ * @bestPractice Keep the actions to `PageToolbarSort`, which names the current order, and a view toggle. Page actions such as export belong in the `PageHeader`.
+ * @category navigation
+ */
+export const PageToolbar = ({ "aria-label": ariaLabel, children, className, gutter = true, ...props }) => {
+    const bar = useRef(null);
+    const stuck = useStuck(bar);
+    return (_jsx(Flex, { align: "center", "aria-label": ariaLabel, as: "section", className: cn("top-app-bar md:top-header @container sticky z-20 min-w-0 flex-wrap border-b border-transparent py-3 transition-colors", "data-stuck:bg-background data-stuck:border-border", gutter && "-mx-page-gutter px-page-gutter", className), "data-component": "page-toolbar", "data-slot": "page-toolbar", "data-stuck": stuck ? "" : undefined, gap: "base", justify: "space-between", ref: bar, ...props, children: children }));
+};
+/**
+ * The toolbar's leading side: the Filters button, then the applied filters
+ * and suggestions. When those outgrow the bar they scroll sideways beside
+ * the button, with a fade at whichever edge has more to show.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export const PageToolbarFilters = ({ button, children, className, ...props }) => {
+    const strip = (_jsx(ScrollFrame, { className: "flex-1 @max-2xl:order-1 @max-2xl:basis-full", dragScroll: true, fadeMode: "mask", fadeSize: "sm", hideScrollbar: true, orientation: "horizontal", children: _jsx(Flex, { align: "center", className: className, "data-component": "page-toolbar-filters", "data-slot": "page-toolbar-filters", gap: "xs", inline: true, ...props, children: children }) }));
+    return button === undefined ? (strip) : (_jsxs(Flex, { align: "center", className: "min-w-0 flex-1 @max-2xl:contents", gap: "xs", children: [button, strip] }));
+};
+/**
+ * The toolbar's trailing side: sort and a view toggle. It never scrolls or
+ * shrinks.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export const PageToolbarActions = ({ className, ...props }) => (_jsx(Flex, { align: "center", className: cn("shrink-0 @max-2xl:ml-auto", className), "data-component": "page-toolbar-actions", "data-slot": "page-toolbar-actions", gap: "xs", ...props }));

package/dist/compositions/page-toolbar/page-toolbar-sort.d.ts

@@ -0,0 +1,31 @@
+export interface PageToolbarSortOption {
+    /** What the order is called, such as "Newest". */
+    label: string;
+    value: string;
+}
+export type PageToolbarSortDirection = "asc" | "desc";
+export interface PageToolbarSortProps {
+    /**
+     * The order's direction. Set it, with `onDirectionChange`, when the
+     * options are fields that sort either way, such as a table's columns.
+     */
+    direction?: PageToolbarSortDirection | undefined;
+    /** Names the control for assistive technology. @default "Sort" */
+    label?: string;
+    onDirectionChange?: (direction: PageToolbarSortDirection) => void;
+    onValueChange: (value: string) => void;
+    options: readonly PageToolbarSortOption[];
+    /** The current order's value; one matching no option reads as unsorted. */
+    value: string;
+}
+/**
+ * The list's order: a button naming the current order, opening a menu of
+ * the others. Naming the order keeps it visible, rather than hidden behind a
+ * bare "Sort". On a phone it narrows to its icon, leaving the width to the
+ * filters.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ *
+ * @example
+ * <PageToolbarSort onValueChange={setSort} options={SORTS} value={sort} />
+ */
+export declare const PageToolbarSort: ({ direction, label, onDirectionChange, onValueChange, options, value, }: PageToolbarSortProps) => import("react").JSX.Element;

package/dist/compositions/page-toolbar/page-toolbar-sort.js

@@ -0,0 +1,28 @@
+"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 { DropdownMenu, DropdownMenuContent, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuTrigger, } from "@instruments/materia-ui/components/dropdown-menu";
+import { ArrowDown, ArrowDownUp, ArrowUp, ChevronDown, } from "@instruments/materia-ui/icons";
+const DIRECTION_ICON = { asc: ArrowUp, desc: ArrowDown };
+/**
+ * The list's order: a button naming the current order, opening a menu of
+ * the others. Naming the order keeps it visible, rather than hidden behind a
+ * bare "Sort". On a phone it narrows to its icon, leaving the width to the
+ * filters.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ *
+ * @example
+ * <PageToolbarSort onValueChange={setSort} options={SORTS} value={sort} />
+ */
+export const PageToolbarSort = ({ direction, label = "Sort", onDirectionChange, onValueChange, options, value, }) => {
+    const current = options.find((option) => option.value === value);
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { render: _jsx(Button, { "aria-label": current === undefined
+                        ? label
+                        : `${label}: ${current.label}${direction === undefined ? "" : `, ${direction === "asc" ? "ascending" : "descending"}`}`, "data-component": "page-toolbar-sort", "data-slot": "page-toolbar-sort", emphasis: "outline", icon: current === undefined || direction === undefined
+                        ? ArrowDownUp
+                        : DIRECTION_ICON[direction], suffixIcon: ChevronDown, suffixIconClassName: "max-sm:hidden", tone: "neutral" }), children: _jsx("span", { className: "max-sm:sr-only", children: current?.label ?? label }) }), _jsxs(DropdownMenuContent, { align: "end", itemRadius: "full", sideOffset: 8, children: [_jsx(DropdownMenuRadioGroup, { onValueChange: onValueChange, value: value, children: options.map((option) => (_jsx(DropdownMenuRadioItem, { value: option.value, children: option.label }, option.value))) }), current === undefined ||
+                        direction === undefined ||
+                        onDirectionChange === undefined ? null : (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsxs(DropdownMenuRadioGroup, { onValueChange: (next) => {
+                                    onDirectionChange(next === "desc" ? "desc" : "asc");
+                                }, value: direction, children: [_jsx(DropdownMenuRadioItem, { value: "asc", children: "Ascending" }), _jsx(DropdownMenuRadioItem, { value: "desc", children: "Descending" })] })] }))] })] }));
+};

package/dist/compositions/page-toolbar/page-toolbar-table.d.ts

@@ -0,0 +1,34 @@
+import type { DataGridTable as Table } from "@instruments/materia-ui/utils/data-grid-table";
+import type { ReactNode } from "react";
+export interface PageToolbarTableFiltersProps<TData extends object> {
+    /** Suggestions to follow the applied filters, if any. */
+    children?: ReactNode;
+    /** The DataGrid's table, from `useDataGridTable`. */
+    table: Table<TData>;
+}
+/**
+ * A table's filters in the page toolbar, reading and writing the same state
+ * as its column headers: the Filters button opens every filterable column's
+ * values, and each value chosen, in the toolbar or a header, shows
+ * as a chip with a cross. Columns opt in with `meta.filter`.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ *
+ * @example
+ * <PageToolbar aria-label="Filters">
+ *   <PageToolbarTableFilters table={table} />
+ *   <PageToolbarActions>
+ *     <PageToolbarTableSort table={table} />
+ *   </PageToolbarActions>
+ * </PageToolbar>
+ */
+export declare const PageToolbarTableFilters: <TData extends object>({ children, table, }: PageToolbarTableFiltersProps<TData>) => import("react").JSX.Element;
+export interface PageToolbarTableSortProps<TData extends object> {
+    /** The DataGrid's table, from `useDataGridTable`. */
+    table: Table<TData>;
+}
+/**
+ * A table's order in the page toolbar: its sortable columns and a direction,
+ * sharing state with the header arrows.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export declare const PageToolbarTableSort: <TData extends object>({ table, }: PageToolbarTableSortProps<TData>) => import("react").JSX.Element;

package/dist/compositions/page-toolbar/page-toolbar-table.js

@@ -0,0 +1,65 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, } from "@instruments/materia-ui/components/dropdown-menu";
+import { getAppliedFilters, getColumnFilterOptions, getColumnFilterValues, getColumnTitle, getFilterableColumns, getSortableColumns, setColumnFilterValues, } from "@instruments/materia-ui/compositions/data-grid";
+import { PageToolbarApplied, PageToolbarFiltersButton, } from "./page-toolbar-applied.js";
+import { PageToolbarFilter } from "./page-toolbar-filter.js";
+import { PageToolbarFilters } from "./page-toolbar-root.js";
+import { PageToolbarSort } from "./page-toolbar-sort.js";
+/** One column's values as ticks. */
+const ColumnValues = ({ column, table, }) => {
+    const chosen = getColumnFilterValues(column);
+    const ticked = new Set(chosen);
+    return getColumnFilterOptions(column, table).map((option) => (_jsx(DropdownMenuCheckboxItem, { checked: ticked.has(option.value), closeOnClick: false, onCheckedChange: (checked) => {
+            setColumnFilterValues(column, checked
+                ? [...chosen, option.value]
+                : chosen.filter((value) => value !== option.value));
+        }, children: option.label }, option.value)));
+};
+/**
+ * A table's filters in the page toolbar, reading and writing the same state
+ * as its column headers: the Filters button opens every filterable column's
+ * values, and each value chosen, in the toolbar or a header, shows
+ * as a chip with a cross. Columns opt in with `meta.filter`.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ *
+ * @example
+ * <PageToolbar aria-label="Filters">
+ *   <PageToolbarTableFilters table={table} />
+ *   <PageToolbarActions>
+ *     <PageToolbarTableSort table={table} />
+ *   </PageToolbarActions>
+ * </PageToolbar>
+ */
+export const PageToolbarTableFilters = ({ children, table, }) => {
+    const columns = getFilterableColumns(table);
+    const applied = getAppliedFilters(table);
+    return (_jsxs(PageToolbarFilters, { button: _jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { disabled: columns.length === 0, render: _jsx(PageToolbarFiltersButton, { count: applied.length }) }), _jsx(DropdownMenuContent, { align: "start", itemRadius: "full", sideOffset: 8, children: columns.map((column) => (_jsxs(DropdownMenuSub, { children: [_jsx(DropdownMenuSubTrigger, { children: getColumnTitle(column) }), _jsx(DropdownMenuSubContent, { children: _jsx(ColumnValues, { column: column, table: table }) })] }, column.id))) })] }), children: [_jsx(PageToolbarApplied, { onClear: () => {
+                    table.resetColumnFilters();
+                }, separator: children !== undefined, children: applied.map((filter) => (_jsx(PageToolbarFilter, { "aria-label": `Remove ${getColumnTitle(filter.column)}: ${filter.label}`, onPressedChange: () => {
+                        setColumnFilterValues(filter.column, getColumnFilterValues(filter.column).filter((value) => value !== filter.value));
+                    }, pressed: true, children: filter.label }, `${filter.column.id}:${filter.value}`))) }), children] }));
+};
+/** The toolbar's word for a TanStack sort's direction; undefined while unsorted. */
+const SORT_DIRECTION = { false: "asc", true: "desc" };
+const sortDirection = (desc) => desc === undefined ? undefined : SORT_DIRECTION[`${desc}`];
+/**
+ * A table's order in the page toolbar: its sortable columns and a direction,
+ * sharing state with the header arrows.
+ * Import from "@instruments/materia-ui/compositions/page-toolbar".
+ */
+export const PageToolbarTableSort = ({ table, }) => {
+    const [sort] = table.state.sorting;
+    const direction = sortDirection(sort?.desc);
+    const columns = getSortableColumns(table);
+    return (_jsx(PageToolbarSort, { direction: direction, onDirectionChange: (next) => {
+            if (sort !== undefined) {
+                table.setSorting([{ desc: next === "desc", id: sort.id }]);
+            }
+        }, onValueChange: (id) => {
+            table.setSorting([{ desc: sort?.desc ?? false, id }]);
+        }, options: columns.map((column) => ({
+            label: getColumnTitle(column),
+            value: column.id,
+        })), value: sort?.id ?? "" }));
+};

package/dist/compositions/page-toolbar/use-stuck.d.ts

@@ -0,0 +1,8 @@
+import type { RefObject } from "react";
+/**
+ * Whether a sticky element is held at its sticky offset rather than sitting
+ * in the flow: it is held exactly when its top edge rests on its own `top`.
+ * Listens to scrolls on any container, so it works whether the window or a
+ * pane scrolls.
+ */
+export declare const useStuck: (sticky: RefObject<HTMLElement | null>) => boolean;

package/dist/compositions/page-toolbar/use-stuck.js

@@ -0,0 +1,44 @@
+"use client";
+import { useEffect, useState } from "react";
+/** A computed `top` resolves to pixels for a positioned element. */
+const pixels = (value) => value.endsWith("px") ? Number(value.slice(0, -2)) : 0;
+/**
+ * Whether a sticky element is held at its sticky offset rather than sitting
+ * in the flow: it is held exactly when its top edge rests on its own `top`.
+ * Listens to scrolls on any container, so it works whether the window or a
+ * pane scrolls.
+ */
+export const useStuck = (sticky) => {
+    const [stuck, setStuck] = useState(false);
+    useEffect(() => {
+        let frame = 0;
+        const measure = () => {
+            frame = 0;
+            const element = sticky.current;
+            if (element === null) {
+                return;
+            }
+            const offset = pixels(getComputedStyle(element).top);
+            const rect = element.getBoundingClientRect();
+            // A bar with no height is not laid out, so it is not holding anywhere.
+            setStuck(rect.height > 0 && rect.top <= offset + 0.5);
+        };
+        const schedule = () => {
+            if (frame === 0) {
+                frame = requestAnimationFrame(measure);
+            }
+        };
+        measure();
+        document.addEventListener("scroll", schedule, {
+            capture: true,
+            passive: true,
+        });
+        window.addEventListener("resize", schedule, { passive: true });
+        return () => {
+            cancelAnimationFrame(frame);
+            document.removeEventListener("scroll", schedule, { capture: true });
+            window.removeEventListener("resize", schedule);
+        };
+    }, [sticky]);
+    return stuck;
+};

package/dist/compositions/page-toolbar.d.ts

@@ -0,0 +1,5 @@
+export { PageToolbarApplied, type PageToolbarAppliedProps, PageToolbarFiltersButton, type PageToolbarFiltersButtonProps, } from "./page-toolbar/page-toolbar-applied.js";
+export { PageToolbarFilter, type PageToolbarFilterProps, } from "./page-toolbar/page-toolbar-filter.js";
+export { PageToolbar, PageToolbarActions, type PageToolbarActionsProps, PageToolbarFilters, type PageToolbarFiltersProps, type PageToolbarProps, } from "./page-toolbar/page-toolbar-root.js";
+export { PageToolbarSort, type PageToolbarSortDirection, type PageToolbarSortOption, type PageToolbarSortProps, } from "./page-toolbar/page-toolbar-sort.js";
+export { PageToolbarTableFilters, type PageToolbarTableFiltersProps, PageToolbarTableSort, type PageToolbarTableSortProps, } from "./page-toolbar/page-toolbar-table.js";

package/dist/compositions/page-toolbar.js

@@ -0,0 +1,5 @@
+export { PageToolbarApplied, PageToolbarFiltersButton, } from "./page-toolbar/page-toolbar-applied.js";
+export { PageToolbarFilter, } from "./page-toolbar/page-toolbar-filter.js";
+export { PageToolbar, PageToolbarActions, PageToolbarFilters, } from "./page-toolbar/page-toolbar-root.js";
+export { PageToolbarSort, } from "./page-toolbar/page-toolbar-sort.js";
+export { PageToolbarTableFilters, PageToolbarTableSort, } from "./page-toolbar/page-toolbar-table.js";

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

@@ -0,0 +1,11 @@
+import type { ProductCardActionProps } from "./product-card-types.js";
+/**
+ * ProductCardAction - the flexible "action notice" row in Product Card 2.0
+ * (⚡ Ships overnight · 2–5 days from brand · ⌕ Find similar).
+ *
+ * Fully **prop-driven and presentational**: it never fetches data and renders
+ * `null` unless a `label` is supplied, so the card ships it off by default
+ * until a real data source (lead time, newness) exists. Pass `onClick`/`href`
+ * to make it an interactive control; otherwise it is a static line.
+ */
+export declare const ProductCardAction: ({ icon, label, tone, href, onClick, className, }: ProductCardActionProps) => import("react").JSX.Element | null;

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

@@ -0,0 +1,42 @@
+"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 { Icon } from "@instruments/materia-ui/components/icon";
+import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
+import { cn } from "@instruments/materia-ui/utils/cn";
+const TONE_CLASS = {
+    affirmative: "text-affirmative-accent",
+    muted: "text-muted-foreground",
+    warning: "text-warning-foreground",
+};
+/**
+ * ProductCardAction - the flexible "action notice" row in Product Card 2.0
+ * (⚡ Ships overnight · 2–5 days from brand · ⌕ Find similar).
+ *
+ * Fully **prop-driven and presentational**: it never fetches data and renders
+ * `null` unless a `label` is supplied, so the card ships it off by default
+ * until a real data source (lead time, newness) exists. Pass `onClick`/`href`
+ * to make it an interactive control; otherwise it is a static line.
+ */
+export const ProductCardAction = ({ icon, label, tone = "muted", href, onClick, className, }) => {
+    if (label === undefined || label === null || label === "") {
+        return null;
+    }
+    const toneClass = TONE_CLASS[tone];
+    const body = (_jsxs(_Fragment, { children: [icon ? _jsx(Icon, { icon: icon, size: "xs" }) : null, _jsx(Box, { as: "span", className: "truncate", children: label })] }));
+    // Interactive variant (e.g. "Find similar"): don't let the click bubble to
+    // the card's primary link/navigation.
+    if (onClick) {
+        const handleClick = (e) => {
+            e.stopPropagation();
+            onClick();
+        };
+        return (_jsx("button", { className: cn(focusRing(), "text-caption flex items-center gap-1 rounded-sm font-medium transition-opacity hover:opacity-80", toneClass, className), onClick: handleClick, type: "button", children: body }));
+    }
+    if (href !== undefined && href !== null && href !== "") {
+        return (_jsx("a", { className: cn(focusRing(), "text-caption flex items-center gap-1 rounded-sm font-medium transition-opacity hover:opacity-80", toneClass, className), href: href, onClick: (e) => {
+                e.stopPropagation();
+            }, children: body }));
+    }
+    return (_jsx(Box, { className: cn("text-caption flex items-center gap-1 font-medium", toneClass, className), children: body }));
+};

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

@@ -0,0 +1,128 @@
+import type { ReactNode } from "react";
+import type { ProductCardHref, ProductCardLabels, ProductCardProduct } from "./product-card-product-types.js";
+/**
+ * Collapsed glyph of the swatch control. `"spark"` suggests an action;
+ * `"plus"` adds straight to a board.
+ */
+type ProductCardSwatchAddGlyph = "spark" | "plus";
+/** Props for the swatch tile's circular add / suggest control. */
+interface ProductCardSwatchAddProps {
+    /** Selected: the control takes the brand tone once it is visible. */
+    active?: boolean | undefined;
+    className?: string | undefined;
+    /** Collapsed glyph. @default "spark" */
+    glyph?: ProductCardSwatchAddGlyph | undefined;
+    /** Strings, overridable; see {@link ProductCardLabels}. */
+    labels?: Pick<ProductCardLabels, "add" | "closeSuggestions" | "suggest"> | undefined;
+    /**
+     * While true the glyph reads as Minus, the control is brand-toned and stays
+     * visible without hover, so the close affordance remains reachable.
+     */
+    menuOpen?: boolean | undefined;
+    /** Click handler. Omit for an inert, presentational control. */
+    onAdd?: (() => void) | undefined;
+}
+type ProductCardAddToCartPlacement = "compact" | "cta" | "inspiration";
+/**
+ * Props passed to the {@link ProductCardRenderAddToCart} slot.
+ */
+interface ProductCardAddToCartRenderProps {
+    available?: boolean | undefined;
+    className?: string | undefined;
+    /** Invoked after a successful add (e.g. to flash a confirmation). */
+    onAdded?: (() => void) | undefined;
+    /** Where in the card the control is being rendered. */
+    placement: ProductCardAddToCartPlacement;
+    product: ProductCardProduct;
+    variant: ProductCardProduct;
+}
+/**
+ * Render slot for the add-to-cart control. When absent, the card renders no
+ * cart UI at all.
+ */
+type ProductCardRenderAddToCart = (props: ProductCardAddToCartRenderProps) => ReactNode;
+/**
+ * What a card's one labelled control actually offers.
+ *
+ * A grid mixes fabrics, chairs, taps and catalogue products, and the only thing
+ * that distinguishes them is this control. Naming the four cases avoids every caller expressing "Show 47 finishes"
+ * through a slot called `renderAddToCart`, where the type says cart and the
+ * pixels say something else.
+ *
+ * **A missing capability is an absent control, never a disabled one.** There is
+ * deliberately no `disabled` case and no greyed arm - a card offers what its
+ * product can actually do, and if it can do nothing, `primaryAction` is omitted
+ * and no control renders at all.
+ *
+ * **Driven by facts, never by brand.** Which case applies is decided by sample
+ * availability and declared-finish count, not by where a product came from. A
+ * catalogue product that later becomes sampleable changes case here and nothing
+ * else about the card moves.
+ */
+type ProductCardPrimaryAction = ProductCardAddToCartAction | ProductCardShowFinishesAction | ProductCardViewOnlyAction | ProductCardViewInCatalogueAction;
+/**
+ * The sampleable-material case: the existing cart control, unchanged.
+ *
+ * Delegates to the {@link ProductCardRenderAddToCart} slot rather than
+ * reimplementing it, so every caller already passing `renderAddToCart` keeps
+ * exactly the control it has today.
+ */
+interface ProductCardAddToCartAction {
+    kind: "add-to-cart";
+}
+/**
+ * A product with manufacturer-declared finishes: *Show 47 finishes*.
+ *
+ * `count` must be the total number of finishes for this product, never the
+ * length of one page of them. A paged list is not the whole set; printing a
+ * page length here states a number about the manufacturer's range that is
+ * false.
+ *
+ * Counting follows the design's own rule: a textile in 8 colourways contributes
+ * 8 finishes, not 1.
+ */
+interface ProductCardShowFinishesAction {
+    /**
+     * The total number of finishes for this product. Never a page length.
+     *
+     * **Optional, and absent means unknown rather than zero.** Counting finishes
+     * can cost a read per product, which a grid of many cards may not afford. A
+     * card without one reads *Show finishes*; it does not print a number it has
+     * not been told, and it does not print 0.
+     */
+    count?: number | undefined;
+    /** Short action label for surfaces that do not show the count. */
+    label?: string | undefined;
+    /** Where the control goes. Omit when `onActivate` handles it. */
+    href?: ProductCardHref;
+    kind: "show-finishes";
+    onActivate?: (() => void) | undefined;
+}
+/**
+ * In the catalogue, but neither sampleable nor carrying declared finishes yet.
+ *
+ * A live, bordered control that navigates to the detail page - NOT a disabled
+ * *Add to cart*. The detail page carries the full explanation; the card carries
+ * an accurate affordance.
+ */
+interface ProductCardViewOnlyAction {
+    kind: "view-only";
+    /** @default "View only" */
+    label?: string;
+}
+/**
+ * A catalogue-only product: *View in catalogue*.
+ *
+ * It can be neither sampled nor necessarily finished, so the one capability it
+ * has is the page of the brand's own catalogue it is printed on.
+ * Everything else on offer, such as requesting a sample or contacting a rep, is
+ * a promise about someone else's process; the page is a fact the card holds.
+ */
+interface ProductCardViewInCatalogueAction {
+    href?: ProductCardHref;
+    kind: "view-in-catalogue";
+    /** @default "View in catalog" */
+    label?: string;
+    onActivate?: (() => void) | undefined;
+}
+export type { ProductCardAddToCartAction, ProductCardAddToCartPlacement, ProductCardAddToCartRenderProps, ProductCardPrimaryAction, ProductCardRenderAddToCart, ProductCardShowFinishesAction, ProductCardSwatchAddGlyph, ProductCardSwatchAddProps, ProductCardViewInCatalogueAction, ProductCardViewOnlyAction, };

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

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

package/dist/compositions/product-card/product-card-add-to-cart.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+interface ProductCardAddToCartProps {
+    className?: string | undefined;
+    /** Callback after item is successfully added to cart */
+    onAdd?: (() => void) | undefined;
+}
+/**
+ * The card's one control spans the card until the card is wide enough to let it
+ * hug: the design draws it full width on the small frame and hug-width on the
+ * large one. Exported so the primary-action control resolves to the same rule.
+ */
+export declare const PRODUCT_CARD_CTA_WIDTH = "w-full @[240px]/product-card:w-auto";
+/**
+ * ProductCardAddToCart - the card's CTA slot. A thin part that forwards to the
+ * context `renderAddToCart` seam with `placement: "cta"`. Renders nothing when
+ * no renderer is provided or the display flag is off.
+ */
+export declare const ProductCardAddToCart: ({ className, onAdd, }: ProductCardAddToCartProps) => ReactNode;
+export {};

package/dist/compositions/product-card/product-card-add-to-cart.js

@@ -0,0 +1,28 @@
+"use client";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { useProductCard } from "./product-card-context.js";
+/**
+ * The card's one control spans the card until the card is wide enough to let it
+ * hug: the design draws it full width on the small frame and hug-width on the
+ * large one. Exported so the primary-action control resolves to the same rule.
+ */
+export const PRODUCT_CARD_CTA_WIDTH = "w-full @[240px]/product-card:w-auto";
+/**
+ * ProductCardAddToCart - the card's CTA slot. A thin part that forwards to the
+ * context `renderAddToCart` seam with `placement: "cta"`. Renders nothing when
+ * no renderer is provided or the display flag is off.
+ */
+export const ProductCardAddToCart = ({ className, onAdd, }) => {
+    const { availability, currentVariant, product, renderAddToCart, showAddToCart, } = useProductCard();
+    if (!showAddToCart || renderAddToCart === undefined) {
+        return null;
+    }
+    return renderAddToCart({
+        available: availability === "available",
+        className: cn(PRODUCT_CARD_CTA_WIDTH, className),
+        onAdded: onAdd,
+        placement: "cta",
+        product,
+        variant: currentVariant,
+    });
+};

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

@@ -0,0 +1,14 @@
+import type { ProductCardAvailability } from "./product-card-types.js";
+/**
+ * True when the product cannot be acted on, so *Find similar* may stand in for
+ * the primary action. `view-only` is excluded: it can still be opened.
+ */
+export declare const cannotAct: (availability: ProductCardAvailability) => boolean;
+/**
+ * ProductCardAvailabilityStatus - the centred status pill over the image for
+ * every availability but `"available"`. The label is real text inside an
+ * `<output>` (an implicit status live region), so the state is announced
+ * rather than carried by the pill's look alone. Non-interactive: it never
+ * blocks the card's primary link.
+ */
+export declare const ProductCardAvailabilityStatus: () => import("react").JSX.Element | null;

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

@@ -0,0 +1,33 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Badge } from "@instruments/materia-ui/components/badge";
+import { Center } from "@instruments/materia-ui/components/center";
+import { useProductCard } from "./product-card-context.js";
+const DEFAULT_AVAILABILITY_LABELS = {
+    blocked: "Unavailable",
+    "out-of-stock": "Out of stock",
+    suspended: "Suspended",
+    "view-only": "View only",
+};
+/**
+ * True when the product cannot be acted on, so *Find similar* may stand in for
+ * the primary action. `view-only` is excluded: it can still be opened.
+ */
+export const cannotAct = (availability) => availability === "out-of-stock" ||
+    availability === "suspended" ||
+    availability === "blocked";
+/**
+ * ProductCardAvailabilityStatus - the centred status pill over the image for
+ * every availability but `"available"`. The label is real text inside an
+ * `<output>` (an implicit status live region), so the state is announced
+ * rather than carried by the pill's look alone. Non-interactive: it never
+ * blocks the card's primary link.
+ */
+export const ProductCardAvailabilityStatus = () => {
+    const { availability, labels } = useProductCard();
+    if (availability === "available") {
+        return null;
+    }
+    return (_jsx(Center, { className: "pointer-events-none absolute inset-0 z-10", children: _jsx("output", { children: _jsx(Badge, { emphasis: "transparent", size: "lg", tone: "neutral", children: labels?.availability?.[availability] ??
+                    DEFAULT_AVAILABILITY_LABELS[availability] }) }) }));
+};

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

@@ -0,0 +1,22 @@
+import type { ReactNode } from "react";
+/**
+ * Brand and product name, each linking to the product.
+ *
+ * Extracted because it was pasted three times - once per container-query arm -
+ * differing in nothing but the padding of the stack around it. Three copies of
+ * the same link wiring is three places for a prefetch flag or a click handler to
+ * drift out of step.
+ *
+ * The click handler is the card's own rule: when a surface supplies
+ * `onCardClick` the caption opens that surface rather than navigating, because a
+ * sidepanel and a page are the same destination reached two ways.
+ */
+export interface ProductCardCaptionProps {
+    /**
+     * Text scale. The compact tile steps both lines down - a genuine divergence
+     * between the arms, unlike the link wiring, which is identical and was the
+     * reason this component exists.
+     */
+    scale?: "compact" | "default";
+}
+export declare const ProductCardCaption: ({ scale, }: ProductCardCaptionProps) => ReactNode;