@instruments/materia-ui 0.1.0

package/dist/components/voice/voice-pill.js

@@ -0,0 +1,75 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { durations, easings, shakeKeyframes, } from "@instruments/materia-ui/tokens/motion";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { ArrowUp, Mic } from "lucide-react";
+import { AnimatePresence, useReducedMotion } from "motion/react";
+import * as m from "motion/react-m";
+import { Icon } from "../icon.js";
+import { LiveWaveform } from "./live-waveform.js";
+/** Blur applied during the glyph↔recording crossfade to mask the overlap. */
+const CROSSFADE_BLUR = "blur(2px)";
+/** Fully faded-in, unblurred content. */
+const CROSSFADE_IN = { filter: "blur(0px)", opacity: 1 };
+/** The hidden edge of the crossfade - a soft blur under reduced-off, else plain fade. */
+const crossfadeEdge = (reduced) => reduced ? { opacity: 0 } : { filter: CROSSFADE_BLUR, opacity: 0 };
+/** A slow, looping opacity pulse (idle "arming"/reduced-recording heartbeat). */
+const pulseTransition = (duration) => ({
+    duration,
+    ease: easings.inOut,
+    repeat: Number.POSITIVE_INFINITY,
+    repeatType: "mirror",
+});
+const crossfadeTransition = (reduced) => ({
+    duration: reduced ? durations.quick : durations.normal,
+    ease: easings.out,
+});
+const formatElapsed = (elapsedMs) => {
+    const totalSeconds = Math.max(0, Math.floor(elapsedMs / 1000));
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+};
+/** The recording cluster: live/frozen waveform + elapsed timer. */
+const RecordingContent = ({ state, level, elapsedMs, reduced, }) => (_jsxs(m.span, { animate: reduced ? { opacity: [1, 0.55, 1] } : CROSSFADE_IN, className: "relative flex items-center gap-2", exit: crossfadeEdge(reduced), initial: crossfadeEdge(reduced), transition: reduced ? pulseTransition(2) : crossfadeTransition(reduced), children: [_jsx(LiveWaveform, { active: state === "listening", level: level }), _jsx("span", { className: "text-caption font-medium tabular-nums", children: formatElapsed(elapsedMs) })] }));
+/** The idle/typing glyph: Mic, or ArrowUp once there is text. */
+const GlyphContent = ({ showArrow, arming, reduced, }) => {
+    const pulsing = arming && !reduced;
+    return (_jsx(m.span, { animate: pulsing ? { opacity: [1, 0.55, 1] } : CROSSFADE_IN, className: "relative flex items-center justify-center", exit: crossfadeEdge(reduced), initial: crossfadeEdge(reduced), transition: pulsing ? pulseTransition(1) : crossfadeTransition(reduced), children: showArrow ? (_jsx(Icon, { className: "relative", icon: ArrowUp, size: "xs" })) : (_jsx(Icon, { className: "relative", icon: Mic, size: "xs" })) }));
+};
+/**
+ * The composer's send/voice control, morphing across a single `<button>`. A
+ * dumb, fully props-driven atom: it owns no timers, audio, or permissions - a
+ * parent drives every transition through `state`, `level`, and `elapsedMs`.
+ *
+ * States: `idle` shows the `Mic` (empty-composer control); `typing` swaps
+ * instantly to `ArrowUp`; `arming` gives a brief pre-listen pulse; `listening`
+ * widens the pill and crossfades (with a masking blur) to a live waveform plus
+ * a `tabular-nums` timer; `finalizing` freezes the bars and contracts faster
+ * than it expanded; `error` shakes once (or, under reduced motion, pulses a
+ * destructive tint). Carries a glass sheen so `idle` reads as a plain primary pill.
+ *
+ * @bestPractice Keep this dumb - drive every transition from the parent through `state`/`level`/`elapsedMs`; it owns no timers, audio, or permissions.
+ * @bestPractice Pass `label` per state (the parent decides the copy, e.g. "Voice input" vs "Stop dictation") so screen readers announce the current action; never hardcode it here.
+ * @bestPractice Feed `level` from a real RMS meter while `listening` - a dead-flat waveform reads as a crashed mic; the atom floors and undulates the bars, but only live level makes it look alive.
+ * @category motion
+ */
+export const VoicePill = ({ state, level = 0, elapsedMs = 0, onClick, disabled = false, label, pressed, className, }) => {
+    const reduced = useReducedMotion() ?? false;
+    const isRecording = state === "listening" || state === "finalizing";
+    return (_jsxs(m.button
+    // A single horizontal shake cycle acknowledges an error (skipped under
+    // reduced motion, which uses the tint pulse below instead).
+    , { 
+        // A single horizontal shake cycle acknowledges an error (skipped under
+        // reduced motion, which uses the tint pulse below instead).
+        animate: { x: state === "error" && !reduced ? shakeKeyframes : 0 }, "aria-label": label, "aria-pressed": pressed, className: cn("border-primary bg-primary text-primary-foreground transition-width relative flex h-9 shrink-0 items-center justify-center overflow-hidden rounded-full border px-4 shadow-xs drop-shadow-xs ease-out disabled:opacity-60 motion-reduce:transition-none", 
+        // Width is a class, not an animated value: expanding is slower than
+        // contracting, so the pill snaps back quickly once capture ends.
+        isRecording ? "duration-normal w-24" : "duration-normal w-12", className), disabled: disabled, onClick: onClick, transition: {
+            x: { duration: durations.normal, ease: easings.out },
+        }, type: "button", children: [_jsx("span", { "aria-hidden": true, className: "from-alpha-20 to-alpha-5 inset-shadow-alpha-20 pointer-events-none absolute inset-0 rounded-full bg-gradient-to-b inset-shadow-2xs" }), state === "error" && reduced ? (_jsx(m.span, { animate: { opacity: [0, 1, 0] }, "aria-hidden": true, className: "ring-destructive pointer-events-none absolute inset-0 rounded-full ring-2 ring-inset", initial: { opacity: 0 }, transition: {
+                    duration: durations.moderate,
+                    ease: easings.out,
+                } })) : null, _jsx(AnimatePresence, { initial: false, mode: "popLayout", children: isRecording ? (_jsx(RecordingContent, { elapsedMs: elapsedMs, level: level, reduced: reduced, state: state }, "recording")) : (_jsx(GlyphContent, { arming: state === "arming", reduced: reduced, showArrow: state === "typing" }, "glyph")) })] }));
+};

package/dist/components/voice.d.ts

@@ -0,0 +1,3 @@
+export { LiveWaveform, type LiveWaveformProps } from "./voice/live-waveform.js";
+export { VoiceErrorPopover, type VoiceErrorPopoverProps, } from "./voice/voice-error-popover.js";
+export { VoicePill, type VoicePillProps, type VoicePillState, } from "./voice/voice-pill.js";

package/dist/components/voice.js

@@ -0,0 +1,3 @@
+export { LiveWaveform } from "./voice/live-waveform.js";
+export { VoiceErrorPopover, } from "./voice/voice-error-popover.js";
+export { VoicePill, } from "./voice/voice-pill.js";

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

@@ -0,0 +1,25 @@
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+interface AttributeCardProps {
+    /** Attribute label */
+    attributeLabel: string;
+    /** CSS class name */
+    className?: string;
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** Current value */
+    valueLabel: string;
+    /** Current value */
+    valueSubLabel?: string;
+}
+/**
+ * AttributeCard UI component.
+ * Import from "@instruments/materia-ui/compositions/attribute-card".
+ *
+ * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.
+ * @bestPractice Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.
+ * @bestPractice This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.
+ * @category catalogue
+ */
+declare const AttributeCard: ({ attributeLabel, valueLabel, valueSubLabel, icon, className, }: AttributeCardProps) => React.JSX.Element;
+export type { AttributeCardProps };
+export { AttributeCard };

package/dist/compositions/attribute-card.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { Card, CardContent, CardDescription, CardTitle, } from "../components/card.js";
+import { Flex } from "../components/flex.js";
+import { Icon } from "../components/icon.js";
+/**
+ * AttributeCard UI component.
+ * Import from "@instruments/materia-ui/compositions/attribute-card".
+ *
+ * @bestPractice Use `AttributeCard` for a single label + prominent value stat tile (a KPI/metric); for many key/value pairs about one entity reach for `DescriptionList` instead.
+ * @bestPractice Pass a Lucide component to `icon` (e.g. `RulerIcon`), not a rendered `<Icon/>` - it is handed to the internal `Icon` at a fixed `sm` size.
+ * @bestPractice This is a preset composition of `Card`; restyle via the surrounding layout rather than reaching inside - for a bespoke layout compose `Card`/`CardContent` directly.
+ * @category catalogue
+ */
+const AttributeCard = ({ attributeLabel, valueLabel, valueSubLabel, icon, className, }) => (_jsx(Card, { className: cn(className), "data-component": "attribute-card", variant: "card", children: _jsx(CardContent, { children: _jsxs(Flex, { className: "gap-2.5", direction: "column", children: [_jsxs(Flex, { align: "flex-start", justify: "space-between", children: [_jsx(CardTitle, { className: "text-paragraph-sm font-normal", children: attributeLabel }), icon && (_jsx(Icon, { className: "text-muted-foreground", icon: icon, size: "sm" }))] }), _jsxs(Flex, { direction: "column", gap: "2xs", children: [_jsx("div", { className: "text-subheading-lg line-clamp-2 font-semibold", children: valueLabel }), valueSubLabel !== undefined &&
+                            valueSubLabel !== null &&
+                            valueSubLabel !== "" && (_jsx(CardDescription, { className: "text-caption", children: valueSubLabel }))] })] }) }) }));
+export { AttributeCard };

package/dist/compositions/card-grid/card-grid-context.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The enclosing CardGrid's layout, so `CardGridItem` drops its fixed widths
+ * inside a `fill` grid, where the column track sizes the card.
+ */
+export declare const CardGridLayoutContext: import("react").Context<"fill" | "wrap">;

package/dist/compositions/card-grid/card-grid-context.js

@@ -0,0 +1,7 @@
+"use client";
+import { createContext } from "react";
+/**
+ * The enclosing CardGrid's layout, so `CardGridItem` drops its fixed widths
+ * inside a `fill` grid, where the column track sizes the card.
+ */
+export const CardGridLayoutContext = createContext("wrap");

package/dist/compositions/card-grid/card-grid-item.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentProps, Ref } from "react";
+export interface CardGridItemProps extends ComponentProps<"li"> {
+    ref?: Ref<HTMLLIElement>;
+}
+/**
+ * A single cell within `CardGrid`, rendered as a list item. In the default
+ * `wrap` layout it carries the responsive widths: a fluid 2-up
+ * (`w-[calc((100%-1rem)/2)]`) below a 500px container, then fixed `w-44` /
+ * `@[800px]/card-grid:w-52` / `@[1200px]/card-grid:w-68`, tuned to the
+ * ProductCard small/medium/full breakpoints. In a `fill` grid the column
+ * track sizes it instead.
+ *
+ * @bestPractice Keep this as the direct child of `CardGrid` so the list semantics stay intact; put the actual card inside it.
+ * @category catalogue
+ */
+export declare const CardGridItem: ({ className, ref, ...props }: CardGridItemProps) => import("react").JSX.Element;

package/dist/compositions/card-grid/card-grid-item.js

@@ -0,0 +1,21 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { use } from "react";
+import { CardGridLayoutContext } from "./card-grid-context.js";
+import { CARD_GRID_RESPONSIVE } from "./card-grid-metrics.js";
+/**
+ * A single cell within `CardGrid`, rendered as a list item. In the default
+ * `wrap` layout it carries the responsive widths: a fluid 2-up
+ * (`w-[calc((100%-1rem)/2)]`) below a 500px container, then fixed `w-44` /
+ * `@[800px]/card-grid:w-52` / `@[1200px]/card-grid:w-68`, tuned to the
+ * ProductCard small/medium/full breakpoints. In a `fill` grid the column
+ * track sizes it instead.
+ *
+ * @bestPractice Keep this as the direct child of `CardGrid` so the list semantics stay intact; put the actual card inside it.
+ * @category catalogue
+ */
+export const CardGridItem = ({ className, ref, ...props }) => {
+    const layout = use(CardGridLayoutContext);
+    return (_jsx("li", { className: cn(layout === "fill" ? "min-w-0" : CARD_GRID_RESPONSIVE.ITEM_CLASSNAME, className), ref: ref, ...props }));
+};

package/dist/compositions/card-grid/card-grid-metrics.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared card grid layout constants for consistent sizing across grids.
+ * Used by product grid, brand grid, and other card-based layouts.
+ */
+export declare const CARD_GRID: {
+    /** Standard card width in pixels */
+    readonly CARD_WIDTH: 272;
+    /** Gap between cards in pixels */
+    readonly GAP: 24;
+};
+export declare const CARD_GRID_RESPONSIVE: {
+    readonly CONTAINER_CLASSNAME: "@container/card-grid";
+    readonly ROW_CLASSNAME: "flex flex-wrap gap-4";
+    readonly ITEM_CLASSNAME: "w-[calc((100%-1rem)/2)] @[500px]/card-grid:w-44 @[800px]/card-grid:w-52 @[1200px]/card-grid:w-68";
+    /** Below this container width the grid is fluid 2-up (see ITEM_CLASSNAME). */
+    readonly PHONE_GRID_MAX_WIDTH: 500;
+    readonly COMPACT_CARD_WIDTH: 176;
+    readonly COMPACT_GAP: 16;
+    readonly MEDIUM_CARD_WIDTH: 208;
+    readonly MEDIUM_GAP: 16;
+    readonly MEDIUM_CARD_MIN_WIDTH: 800;
+    readonly FULL_CARD_WIDTH: 272;
+    readonly FULL_GAP: 16;
+    readonly FULL_CARD_MIN_WIDTH: 1200;
+};
+/**
+ * Minimum card width per `minItemSize` in a `layout="fill"` CardGrid, matching
+ * the compact, medium and full fixed widths of the default `wrap` layout.
+ */
+export declare const CARD_GRID_FILL_MIN_WIDTH: {
+    readonly base: 208;
+    readonly lg: 272;
+    readonly sm: 176;
+};
+/**
+ * The `grid-template-columns` of a `layout="fill"` CardGrid: as many columns
+ * as fit at `minWidth`, stretched to share the row so the right edge lines up.
+ * The `min()` keeps the phone tier at two columns (each half the row less half
+ * the 1rem gap) when two `minWidth` cards would not fit.
+ */
+export declare const cardGridFillColumns: (minWidth: number) => string;
+export declare const getCardGridMetrics: (containerWidth: number) => {
+    CARD_WIDTH: 272;
+    GAP: 16;
+} | {
+    CARD_WIDTH: 208;
+    GAP: 16;
+} | {
+    CARD_WIDTH: 176;
+    GAP: 16;
+};
+/**
+ * Calculate number of columns for a given container width.
+ */
+export declare const calculateColumns: (containerWidth: number, cardWidth?: number, gap?: number) => number;
+/**
+ * Chunk items into rows based on column count.
+ */
+export declare const chunkIntoRows: <T>(items: T[], columns: number) => T[][];

package/dist/compositions/card-grid/card-grid-metrics.js

@@ -0,0 +1,92 @@
+/**
+ * Shared card grid layout constants for consistent sizing across grids.
+ * Used by product grid, brand grid, and other card-based layouts.
+ */
+export const CARD_GRID = {
+    /** Standard card width in pixels */
+    CARD_WIDTH: 272,
+    /** Gap between cards in pixels */
+    GAP: 24,
+};
+export const CARD_GRID_RESPONSIVE = {
+    CONTAINER_CLASSNAME: "@container/card-grid",
+    ROW_CLASSNAME: "flex flex-wrap gap-4",
+    // Below the phone threshold cards are fluid - exactly two per row filling the
+    // container (minus the 1rem gap) - because a single fixed-width card strands
+    // the right half of a phone screen. From 500px up, fixed widths tuned to the
+    // ProductCard small/medium/full breakpoints take over.
+    ITEM_CLASSNAME: "w-[calc((100%-1rem)/2)] @[500px]/card-grid:w-44 @[800px]/card-grid:w-52 @[1200px]/card-grid:w-68",
+    /** Below this container width the grid is fluid 2-up (see ITEM_CLASSNAME). */
+    PHONE_GRID_MAX_WIDTH: 500,
+    COMPACT_CARD_WIDTH: 176,
+    COMPACT_GAP: 16,
+    MEDIUM_CARD_WIDTH: 208,
+    MEDIUM_GAP: 16,
+    MEDIUM_CARD_MIN_WIDTH: 800,
+    FULL_CARD_WIDTH: CARD_GRID.CARD_WIDTH,
+    FULL_GAP: 16,
+    FULL_CARD_MIN_WIDTH: 1200,
+};
+/**
+ * Minimum card width per `minItemSize` in a `layout="fill"` CardGrid, matching
+ * the compact, medium and full fixed widths of the default `wrap` layout.
+ */
+export const CARD_GRID_FILL_MIN_WIDTH = {
+    base: CARD_GRID_RESPONSIVE.MEDIUM_CARD_WIDTH,
+    lg: CARD_GRID_RESPONSIVE.FULL_CARD_WIDTH,
+    sm: CARD_GRID_RESPONSIVE.COMPACT_CARD_WIDTH,
+};
+/**
+ * The `grid-template-columns` of a `layout="fill"` CardGrid: as many columns
+ * as fit at `minWidth`, stretched to share the row so the right edge lines up.
+ * The `min()` keeps the phone tier at two columns (each half the row less half
+ * the 1rem gap) when two `minWidth` cards would not fit.
+ */
+export const cardGridFillColumns = (minWidth) => `repeat(auto-fill, minmax(min(${minWidth}px, calc(50% - 0.5rem)), 1fr))`;
+export const getCardGridMetrics = (containerWidth) => {
+    if (containerWidth >= CARD_GRID_RESPONSIVE.FULL_CARD_MIN_WIDTH) {
+        return {
+            CARD_WIDTH: CARD_GRID_RESPONSIVE.FULL_CARD_WIDTH,
+            GAP: CARD_GRID_RESPONSIVE.FULL_GAP,
+        };
+    }
+    if (containerWidth >= CARD_GRID_RESPONSIVE.MEDIUM_CARD_MIN_WIDTH) {
+        return {
+            CARD_WIDTH: CARD_GRID_RESPONSIVE.MEDIUM_CARD_WIDTH,
+            GAP: CARD_GRID_RESPONSIVE.MEDIUM_GAP,
+        };
+    }
+    return {
+        CARD_WIDTH: CARD_GRID_RESPONSIVE.COMPACT_CARD_WIDTH,
+        GAP: CARD_GRID_RESPONSIVE.COMPACT_GAP,
+    };
+};
+/**
+ * Calculate number of columns for a given container width.
+ */
+export const calculateColumns = (containerWidth, cardWidth = CARD_GRID.CARD_WIDTH, gap = CARD_GRID.GAP) => {
+    if (containerWidth === 0) {
+        return 1;
+    }
+    // Mirror ITEM_CLASSNAME's fluid 2-up phone tier so JS row chunking stays in
+    // lockstep with what CSS renders - but ONLY for the fluid CardGridItem scale
+    // (compact cards). Callers rendering fixed-width cards (e.g. the default
+    // 272px `CARD_WIDTH`, as VirtualizedCardGrid does) must fall through to the
+    // real fit calculation, or they'd force two oversized cards into a phone
+    // container and overflow.
+    if (containerWidth < CARD_GRID_RESPONSIVE.PHONE_GRID_MAX_WIDTH &&
+        cardWidth <= CARD_GRID_RESPONSIVE.COMPACT_CARD_WIDTH) {
+        return 2;
+    }
+    return Math.max(1, Math.floor((containerWidth + gap) / (cardWidth + gap)));
+};
+/**
+ * Chunk items into rows based on column count.
+ */
+export const chunkIntoRows = (items, columns) => {
+    const rows = [];
+    for (let i = 0; i < items.length; i += columns) {
+        rows.push(items.slice(i, i + columns));
+    }
+    return rows;
+};

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

@@ -0,0 +1,39 @@
+import type { ComponentSize } from "@instruments/materia-ui/tokens/size";
+import type { ComponentProps, Ref } from "react";
+/** The card widths a `layout="fill"` CardGrid can use as its column minimum. */
+export type CardGridItemSize = Extract<ComponentSize, "sm" | "base" | "lg">;
+type CardGridLayoutProps = {
+    /**
+     * `"wrap"` (default): a wrapping flex row of fixed-width cards that step
+     * through the ProductCard breakpoints, leaving any leftover width at the
+     * row's end. `"fill"`: a grid whose columns stretch to share the row, so
+     * the right edge always lines up with the content column.
+     * @default "wrap"
+     */
+    layout?: "wrap";
+    minItemSize?: never;
+} | {
+    layout: "fill";
+    /**
+     * Narrowest a card may get before the row drops a column: `sm` 176px,
+     * `base` 208px, `lg` 272px. Phones keep two cards a row regardless.
+     * @default "base"
+     */
+    minItemSize?: CardGridItemSize;
+};
+export type CardGridProps = Omit<ComponentProps<"ul">, "ref"> & CardGridLayoutProps & {
+    ref?: Ref<HTMLUListElement>;
+};
+/**
+ * Responsive `@container` list that lays cards out in rows. The default
+ * `wrap` layout is a wrapping flex row whose items resize at the ProductCard
+ * small/medium/full breakpoints via the `@container/card-grid` query name;
+ * `layout="fill"` is a grid whose columns stretch to fill each row.
+ *
+ * @bestPractice Render `CardGridItem` children so each card is a list item under this `<ul>` - wrapping arbitrary elements loses the list semantics.
+ * @bestPractice Use `layout="fill"` wherever the grid's width changes with the page (a docked panel, a collapsing sidebar): fixed widths leave a ragged gap at the right edge, fill columns don't. Keep `CardGridRows` on the default, as its row widths come from the fixed metrics.
+ * @bestPractice Give the loading grid the same `layout` and `minItemSize` as the loaded one, so skeletons and cards share columns and nothing reflows when data lands.
+ * @category catalogue
+ */
+export declare const CardGrid: ({ className, layout, minItemSize, ref, style, ...props }: CardGridProps) => import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { cssVariables } from "../../utils/css-variables.js";
+import { CardGridLayoutContext } from "./card-grid-context.js";
+import { CARD_GRID_FILL_MIN_WIDTH, CARD_GRID_RESPONSIVE, cardGridFillColumns, } from "./card-grid-metrics.js";
+/**
+ * Responsive `@container` list that lays cards out in rows. The default
+ * `wrap` layout is a wrapping flex row whose items resize at the ProductCard
+ * small/medium/full breakpoints via the `@container/card-grid` query name;
+ * `layout="fill"` is a grid whose columns stretch to fill each row.
+ *
+ * @bestPractice Render `CardGridItem` children so each card is a list item under this `<ul>` - wrapping arbitrary elements loses the list semantics.
+ * @bestPractice Use `layout="fill"` wherever the grid's width changes with the page (a docked panel, a collapsing sidebar): fixed widths leave a ragged gap at the right edge, fill columns don't. Keep `CardGridRows` on the default, as its row widths come from the fixed metrics.
+ * @bestPractice Give the loading grid the same `layout` and `minItemSize` as the loaded one, so skeletons and cards share columns and nothing reflows when data lands.
+ * @category catalogue
+ */
+export const CardGrid = ({ className, layout = "wrap", minItemSize = "base", ref, style, ...props }) => {
+    const fill = layout === "fill";
+    return (_jsx(CardGridLayoutContext, { value: layout, children: _jsx("ul", { className: cn(CARD_GRID_RESPONSIVE.CONTAINER_CLASSNAME, fill
+                ? "grid grid-cols-(--card-grid-columns) gap-4"
+                : CARD_GRID_RESPONSIVE.ROW_CLASSNAME, className), "data-component": "card-grid", "data-layout": layout, ref: ref, style: fill
+                ? cssVariables({
+                    "--card-grid-columns": cardGridFillColumns(CARD_GRID_FILL_MIN_WIDTH[minItemSize]),
+                }, style)
+                : style, ...props }) }));
+};

package/dist/compositions/card-grid/card-grid-rows.d.ts

@@ -0,0 +1,32 @@
+import type { ComponentProps, ReactNode } from "react";
+export interface CardGridRowMetrics {
+    cardWidth: number;
+    gap: number;
+    rowWidth: number;
+}
+export interface CardGridRowsProps<T> extends Omit<ComponentProps<"div">, "children"> {
+    getItemKey: (item: T) => string;
+    getRowKey?: (row: T[], rowIndex: number) => string;
+    metrics: Omit<CardGridRowMetrics, "rowWidth">;
+    renderAfterRow?: (props: {
+        metrics: CardGridRowMetrics;
+        row: T[];
+        rowIndex: number;
+    }) => ReactNode;
+    renderItem: (props: {
+        index: number;
+        item: T;
+        row: T[];
+        rowIndex: number;
+    }) => ReactNode;
+    rows: T[][];
+}
+/**
+ * Renders a list of pre-chunked rows, each as its own `CardGrid`, with an
+ * optional `renderAfterRow` slot (e.g. an expanded detail panel) beneath each
+ * row. Row widths are derived from `metrics` so callers can align that slot.
+ *
+ * @bestPractice Chunk items with `chunkIntoRows` (using `calculateColumns`) before passing `rows`; provide a stable `getItemKey` (and `getRowKey` where rows reorder) so React reconciliation stays correct.
+ * @category catalogue
+ */
+export declare const CardGridRows: <T>({ className, getItemKey, getRowKey, metrics, renderAfterRow, renderItem, rows, ...props }: CardGridRowsProps<T>) => import("react").JSX.Element;

package/dist/compositions/card-grid/card-grid-rows.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@instruments/materia-ui/utils/cn";
+import { CardGridItem } from "./card-grid-item.js";
+import { CardGrid } from "./card-grid-root.js";
+const CardGridRow = ({ getItemKey, metrics, renderAfterRow, renderItem, row, rowIndex, }) => {
+    const cardsInRow = row.length;
+    const rowWidth = cardsInRow * metrics.cardWidth + (cardsInRow - 1) * metrics.gap;
+    return (_jsxs("div", { children: [_jsx(CardGrid, { className: "pb-4 sm:pb-6", children: row.map((item, index) => (_jsx(CardGridItem, { children: renderItem({ item, index, row, rowIndex }) }, getItemKey(item)))) }), renderAfterRow?.({
+                row,
+                rowIndex,
+                metrics: {
+                    ...metrics,
+                    rowWidth,
+                },
+            })] }));
+};
+/**
+ * Renders a list of pre-chunked rows, each as its own `CardGrid`, with an
+ * optional `renderAfterRow` slot (e.g. an expanded detail panel) beneath each
+ * row. Row widths are derived from `metrics` so callers can align that slot.
+ *
+ * @bestPractice Chunk items with `chunkIntoRows` (using `calculateColumns`) before passing `rows`; provide a stable `getItemKey` (and `getRowKey` where rows reorder) so React reconciliation stays correct.
+ * @category catalogue
+ */
+export const CardGridRows = ({ className, getItemKey, getRowKey, metrics, renderAfterRow, renderItem, rows, ...props }) => (_jsx("div", { className: cn("[clip-path:inset(0_-200px_-200px_-200px)]", className), ...props, children: rows.map((row, rowIndex) => {
+        const rowKey = getRowKey?.(row, rowIndex) ?? `row-${rowIndex}`;
+        return (_jsx(CardGridRow, { getItemKey: getItemKey, metrics: metrics, ...(renderAfterRow === undefined ? {} : { renderAfterRow }), renderItem: renderItem, row: row, rowIndex: rowIndex }, rowKey));
+    }) }));

package/dist/compositions/card-grid/card-grid-skeleton-item.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Loading placeholder for a single `CardGrid` cell.
+ *
+ * It renders ONE skeleton and lets the skeleton read the cell it lands in.
+ * Choosing here on `@container/card-grid` was choosing on the wrong signal: the
+ * grid's phone tier is a fluid 2-up, so a 460px container renders 222px cards -
+ * the card's main arm - while the grid query still read "small".
+ *
+ * @bestPractice Render one `CardGridSkeletonItem` per expected card while data loads, inside the same `CardGrid` - this keeps list semantics and column widths stable across the loading→loaded transition.
+ * @category catalogue
+ */
+export declare const CardGridSkeletonItem: ({ className }: {
+    className?: string;
+}) => import("react").JSX.Element;

package/dist/compositions/card-grid/card-grid-skeleton-item.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ProductCardSkeleton } from "../product-card/product-card-skeleton.js";
+import { CardGridItem } from "./card-grid-item.js";
+/**
+ * Loading placeholder for a single `CardGrid` cell.
+ *
+ * It renders ONE skeleton and lets the skeleton read the cell it lands in.
+ * Choosing here on `@container/card-grid` was choosing on the wrong signal: the
+ * grid's phone tier is a fluid 2-up, so a 460px container renders 222px cards -
+ * the card's main arm - while the grid query still read "small".
+ *
+ * @bestPractice Render one `CardGridSkeletonItem` per expected card while data loads, inside the same `CardGrid` - this keeps list semantics and column widths stable across the loading→loaded transition.
+ * @category catalogue
+ */
+export const CardGridSkeletonItem = ({ className }) => (_jsx(CardGridItem, { className: className, children: _jsx(ProductCardSkeleton, {}) }));

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

@@ -0,0 +1,5 @@
+export { CardGridItem, type CardGridItemProps, } from "./card-grid/card-grid-item.js";
+export { CARD_GRID, CARD_GRID_FILL_MIN_WIDTH, CARD_GRID_RESPONSIVE, calculateColumns, cardGridFillColumns, chunkIntoRows, getCardGridMetrics, } from "./card-grid/card-grid-metrics.js";
+export { CardGrid, type CardGridItemSize, type CardGridProps, } from "./card-grid/card-grid-root.js";
+export { CardGridRows, type CardGridRowMetrics, type CardGridRowsProps, } from "./card-grid/card-grid-rows.js";
+export { CardGridSkeletonItem } from "./card-grid/card-grid-skeleton-item.js";

package/dist/compositions/card-grid.js

@@ -0,0 +1,5 @@
+export { CardGridItem, } from "./card-grid/card-grid-item.js";
+export { CARD_GRID, CARD_GRID_FILL_MIN_WIDTH, CARD_GRID_RESPONSIVE, calculateColumns, cardGridFillColumns, chunkIntoRows, getCardGridMetrics, } from "./card-grid/card-grid-metrics.js";
+export { CardGrid, } from "./card-grid/card-grid-root.js";
+export { CardGridRows, } from "./card-grid/card-grid-rows.js";
+export { CardGridSkeletonItem } from "./card-grid/card-grid-skeleton-item.js";

package/dist/compositions/color-palette/color-palette-parts.d.ts

@@ -0,0 +1,2 @@
+export { type ColorPaletteLinkProps, defaultRenderLink, } from "./palette-helpers.js";
+export { PaletteRow } from "./palette-row.js";

package/dist/compositions/color-palette/color-palette-parts.js

@@ -0,0 +1,2 @@
+export { defaultRenderLink, } from "./palette-helpers.js";
+export { PaletteRow } from "./palette-row.js";

package/dist/compositions/color-palette/color-palette-root.d.ts

@@ -0,0 +1,85 @@
+import type { ReactNode } from "react";
+import type { ColorPaletteLinkProps } from "./color-palette-parts.js";
+import type { ColorPaletteItem, PaletteDirection, PaletteSort } from "./palette-sort.js";
+interface ColorPaletteProps {
+    /** Cards to render - flat colours, gradients, or images (see ColorPaletteItem). */
+    items: ColorPaletteItem[];
+    /** Controlled sort order */
+    sort?: PaletteSort;
+    /** Initial sort order when uncontrolled (default "original") */
+    defaultSort?: PaletteSort;
+    /** Fired when the sort changes; pair with `sort` for controlled mode. */
+    onSortChange?: (sort: PaletteSort) => void;
+    /** Controlled stacking direction */
+    direction?: PaletteDirection;
+    /** Initial stacking direction when uncontrolled (default "left-first") */
+    defaultDirection?: PaletteDirection;
+    /** Fired when the direction changes; pair with `direction` for controlled mode. */
+    onDirectionChange?: (direction: PaletteDirection) => void;
+    /** Show the sort/direction settings popover button (default false) */
+    showSettings?: boolean;
+    /**
+     * Let users build a selection by clicking cards - the whole card becomes
+     * a toggle instead of a search link. Selected cards keep a check visible
+     * at rest; read the selection through `onSelectedIdsChange` and drive any
+     * sampling CTA yourself (default false).
+     */
+    selectable?: boolean;
+    /**
+     * Controlled selected ids. Ids come from `item.id`, falling back to
+     * `kind-index` for items without one - provide stable ids when selection
+     * must survive item reordering.
+     */
+    selectedIds?: string[];
+    /** Initial selected ids when uncontrolled */
+    defaultSelectedIds?: string[];
+    /** Fired when the selection changes; pair with `selectedIds` for controlled mode. */
+    onSelectedIdsChange?: (selectedIds: string[]) => void;
+    /** Base path for the built-in search links (default "/colors") */
+    searchBasePath?: string;
+    /** Hover label for unnamed searchable cards (default "Search this color") */
+    searchLabel?: string;
+    /**
+     * Escape hatch to render links with a router-aware component
+     * (e.g. next/link). Must render a single anchor element.
+     * Defaults to a plain anchor.
+     */
+    renderLink?: (props: ColorPaletteLinkProps) => ReactNode;
+    className?: string;
+}
+/**
+ * Stacked colour palette in the style of the Dropbox brand site: a row of
+ * overlapping, bottom-anchored square cards cropped to 16:9. Hovering
+ * or focusing a card smoothly raises it and reveals a search action that
+ * deep-links into the colours search page.
+ *
+ * The component renders only the swatch row - no card, heading, or CTA
+ * chrome. Compose those around it (a `<section>`, a title, a sample button
+ * wired to `onSelectedIdsChange`) when a surface calls for them.
+ *
+ * Cards can be flat colours, gradients, or images (see ColorPaletteItem).
+ * Image cards need a `searchHex` to be clickable.
+ *
+ * With `selectable`, clicking anywhere on a card toggles it in and out of
+ * the selection instead of linking out; selected cards keep a check
+ * visible at rest, and the selection surfaces through `onSelectedIdsChange`.
+ *
+ * @example
+ * ```tsx
+ * <ColorPalette
+ *   items={[
+ *     { kind: "color", hex: "#7B2D26", name: "Rust" },
+ *     { kind: "gradient", from: "#C97B43", to: "#F2C879" },
+ *     { kind: "image", src: "/oak.jpg", searchHex: "#8C5A3C" },
+ *   ]}
+ * />
+ * ```
+ *
+ * @bestPractice Describe cards as `items` (`kind: "color" | "gradient" | "image"`), not hand-built markup - the component owns the overlap, hover-raise, and deep-link-to-search behaviour.
+ * @bestPractice Give every `image` card a `searchHex`, otherwise it can't be searched or selected - flat colours and gradients derive theirs automatically.
+ * @bestPractice Pass `renderLink` (e.g. wrapping `next/link`) for client-side nav - the built-in links are plain `<a>`; the callback must return a single anchor element.
+ * @category catalogue
+ */
+declare const ColorPalette: ({ items, sort: sortProp, defaultSort, onSortChange, direction: directionProp, defaultDirection, onDirectionChange, showSettings, selectable, selectedIds: selectedIdsProp, defaultSelectedIds, onSelectedIdsChange, searchBasePath, searchLabel, renderLink, className, }: ColorPaletteProps) => import("react").JSX.Element;
+export { ColorPalette, type ColorPaletteProps };
+export type { ColorPaletteLinkProps } from "./color-palette-parts.js";