@instruments/materia-ui 0.4.5 → 0.4.7

package/dist/components/tabs/tabs-variants.js

@@ -30,10 +30,12 @@ export const tabsListVariants = cva("inline-flex h-auto w-fit items-center justi
         variant: "pill",
     },
     variants: {
+        /** Ignored on its own: the parent `Tabs` or `TabNavigation` sets the style for every part, so set `variant` there. */
         variant: {
             pill: SEGMENTED_SHELL_BASE,
             line: "gap-6",
         },
+        /** Ignored on its own: the parent `Tabs` or `TabNavigation` sets the size for every part, so set `size` there. */
         size: {
             "2xs": "",
             xs: "",
@@ -86,7 +88,9 @@ export const tabsTriggerVariants = cva(`transition-color-shadow-border inline-fl
         variant: "pill",
     },
     variants: {
+        /** Ignored on its own: the parent `Tabs` or `TabNavigation` sets the size for every part, so set `size` there. */
         size: { ...SEGMENTED_TRIGGER_TEXT },
+        /** Ignored on its own: the parent `Tabs` or `TabNavigation` sets the style for every part, so set `variant` there. */
         variant: {
             line: cn("text-muted-foreground hover:text-foreground data-active:text-foreground dark:text-gray-500 dark:hover:text-gray-300 dark:data-active:text-gray-100", focusRing()),
             pill: "text-muted-foreground data-active:text-foreground rounded-full dark:text-gray-500 dark:data-active:text-gray-100",

package/dist/components/thinking-loader/thinking-loader-counter.d.ts

@@ -1,6 +1,8 @@
 interface ThinkingLoaderCounterProps {
     className?: string;
+    /** Number shown before the slash, counted from one (the first step is `1`). */
     current: number;
+    /** Number shown after the slash. */
     total: number;
 }
 /**

package/dist/components/thinking-loader/thinking-loader-icon.d.ts

@@ -1,6 +1,8 @@
 import type { LucideIcon } from "lucide-react";
 interface ThinkingLoaderIconProps {
+    /** Icon to show. Renders nothing when `undefined`. */
     icon: LucideIcon | undefined;
+    /** Id of the current step. A new id makes the previous icon crossfade into this one. */
     stepId: string;
 }
 /**

package/dist/components/thinking-loader/thinking-loader-step.d.ts

@@ -18,9 +18,11 @@ interface ThinkingLoaderStepProps {
     hideIcon?: boolean;
     /** Inherit font size from a containing `ThinkingLoader`. */
     inheritSize?: boolean;
+    /** Sweeps a highlight across the label; `false` renders it as plain text. @default true */
     shimmer?: boolean;
     /** Shimmer highlight direction. Defaults to `"dark"`. */
     shimmerVariant?: ShimmerVariant;
+    /** The step to show: its `label` is the text, and its `icon` leads it unless `hideIcon` is set. */
     step: ThinkingStep;
 }
 /**

package/dist/components/toggle/toggle-root.js

@@ -45,6 +45,7 @@ const toggleVariants = cva(cn(focusRing(), "border-border text-foreground bg-bac
         variant: "default",
     },
     variants: {
+        /** How a pressed toggle shows it is on: `default` greys the fill and border, `secondary` darkens the border only. Inside a `ToggleGroup` the group's value wins. @default "default" */
         variant: {
             default: "data-pressed:border-muted-foreground data-pressed:bg-muted",
             secondary: "data-pressed:border-foreground data-pressed:bg-background",
@@ -53,6 +54,7 @@ const toggleVariants = cva(cn(focusRing(), "border-border text-foreground bg-bac
         // Old `shape` values map onto the shared Radius vocabulary by their actual
         // class: old `square` was `rounded-lg` → "rounded"; old `round` was
         // `rounded-full` → "full". Appearance is preserved exactly.
+        /** Corner shape: `rounded` for soft corners, `full` for a pill. There is no sharp option. Inside a `ToggleGroup` the group's value wins. @default "rounded" */
         radius: {
             rounded: "rounded-lg",
             full: "rounded-full",

package/dist/components/voice/voice-error-popover.d.ts

@@ -6,7 +6,9 @@ export interface VoiceErrorPopoverProps {
     message: string;
     /** When set, renders an action button (e.g. `"Retry"`) that calls `onAction`. */
     actionLabel?: string;
+    /** Called when the action button is clicked. The button only appears when `actionLabel` is set. */
     onAction?: () => void;
+    /** Called when the dismiss button is clicked. The parent should then set `open` to `false`. */
     onDismiss?: () => void;
     /** Accessible label for the dismiss button. @default "Dismiss" */
     dismissLabel?: string;

package/dist/components/voice/voice-pill.d.ts

@@ -6,7 +6,9 @@ export interface VoicePillProps {
     level?: number;
     /** Elapsed capture time in ms, shown as an `mm:ss` timer while recording. @default 0 */
     elapsedMs?: number;
+    /** Called when the pill is pressed. The parent decides what the press does in each `state`, such as starting or stopping capture. */
     onClick?: () => void;
+    /** Block presses and dim the pill. @default false */
     disabled?: boolean;
     /** Accessible label. The parent chooses copy per state - never hardcoded here. */
     label: string;

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

@@ -5,6 +5,7 @@ interface AttributeCardProps {
     attributeLabel: string;
     /** CSS class name */
     className?: string;
+    /** Icon component (e.g. a Lucide icon), not a rendered element; shown small and muted at the top right. */
     icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
     /** Current value */
     valueLabel: string;

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

@@ -5,20 +5,33 @@ export interface CardGridRowMetrics {
     rowWidth: number;
 }
 export interface CardGridRowsProps<T> extends Omit<ComponentProps<"div">, "children"> {
+    /** Stable unique key for an item, such as its id; never the array index. */
     getItemKey: (item: T) => string;
+    /** Stable key for a row. Defaults to `row-<rowIndex>`; supply one when rows can reorder or be re-chunked. */
     getRowKey?: (row: T[], rowIndex: number) => string;
+    /**
+     * Pixel `cardWidth` and `gap` the rows were chunked with (e.g. from
+     * `calculateColumns`). They only size `renderAfterRow`'s `rowWidth`; they do
+     * not lay the cards out.
+     */
     metrics: Omit<CardGridRowMetrics, "rowWidth">;
+    /**
+     * Content rendered beneath a row, such as an expanded detail panel. Receives
+     * `metrics` with `rowWidth`, the row's pixel width, so the panel can align to it.
+     */
     renderAfterRow?: (props: {
         metrics: CardGridRowMetrics;
         row: T[];
         rowIndex: number;
     }) => ReactNode;
+    /** Renders one item's card; each result is wrapped in a `CardGridItem`. `index` is the position within its row. */
     renderItem: (props: {
         index: number;
         item: T;
         row: T[];
         rowIndex: number;
     }) => ReactNode;
+    /** Items already chunked into rows, e.g. with `chunkIntoRows`; one `CardGrid` is rendered per row. */
     rows: T[][];
 }
 /**

package/dist/compositions/data-grid/data-grid-checkbox.d.ts

@@ -4,18 +4,26 @@ import type { DataGridColumnDef as ColumnDef, DataGridRow as Row, DataGridCoreTa
 import type * as React from "react";
 type DataGridControlSize = Extract<ComponentSize, "xs" | "sm">;
 export type DataGridCheckboxProps = Omit<React.ComponentProps<typeof Checkbox>, "size"> & {
+    /**
+     * Checkbox size; the grid only uses the two compact steps.
+     * @default "xs"
+     */
     size?: DataGridControlSize;
 };
 /** Grid-tuned {@link Checkbox} (compact sizing, card background) for selection cells. */
 export declare const DataGridCheckbox: ({ size, className, ...props }: DataGridCheckboxProps) => React.JSX.Element;
 export interface DataGridRowSelectAllProps<TData extends object> {
+    /** Disable the checkbox, e.g. while loading or when the page has no rows. */
     disabled?: boolean;
+    /** The TanStack table whose current-page rows this checkbox selects. */
     table: Table<TData>;
 }
 /** Header checkbox that toggles selection of every row on the current page, with an indeterminate partial state. */
 export declare const DataGridRowSelectAll: <TData extends object>({ table, disabled, }: DataGridRowSelectAllProps<TData>) => React.JSX.Element;
 export interface DataGridRowSelectProps<TData extends object> {
+    /** Disable the checkbox; `createSelectionColumn` sets it when the row cannot be selected. */
     disabled?: boolean;
+    /** The TanStack row this checkbox selects. */
     row: Row<TData>;
 }
 /** Per-row selection checkbox; reflects sub-row partial selection as indeterminate when the row model supports it. */

package/dist/compositions/data-grid/data-grid-expand.d.ts

@@ -7,6 +7,7 @@ export interface DataGridExpandToggleProps<TData extends object> {
     collapsedIcon?: React.ComponentType<React.SVGProps<SVGSVGElement>>;
     /** Expanded icon */
     expandedIcon?: React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** The TanStack row to expand or collapse. The toggle renders nothing unless `row.getCanExpand()` is true. */
     row: Row<TData>;
 }
 /**

package/dist/compositions/data-grid/data-grid-filterable-header.d.ts

@@ -5,6 +5,7 @@ export type { FilterOption } from "./data-grid-types.js";
 interface DataGridFilterableHeaderProps<TData extends object, TValue> {
     children: ReactNode;
     className?: string;
+    /** The TanStack column this header sorts and filters. */
     column: Column<TData, TValue>;
     /** Filter options - enables the facets section */
     options?: FilterOption[];

package/dist/compositions/data-grid/data-grid-types.d.ts

@@ -90,7 +90,13 @@ export interface DataGridProps<TData extends object> {
         left?: string[];
         right?: string[];
     };
+    /**
+     * Set while the application fetches rows. The body shows placeholder rows or
+     * a spinner per `loadingMode`, and the select-all checkbox and
+     * `DataGridColumnHeader` buttons are disabled.
+     */
     loading?: boolean;
+    /** Text beside the spinner while loading; only shown when `loadingMode` is `"spinner"`. Defaults to "Loading...". */
     loadingMessage?: ReactNode | string;
     /**
      * How the loading state renders.

package/dist/compositions/data-grid-column-header/data-grid-column-header-root.d.ts

@@ -5,7 +5,12 @@ interface DataGridColumnHeaderProps<TData extends object, TValue> extends HTMLAt
     column: Column<TData, TValue>;
     /** Filter control rendered at the top of the header dropdown menu. */
     filter?: ReactNode;
+    /** Leading glyph shown before the title. */
     icon?: ReactNode;
+    /**
+     * Not read by the header. Pinning is controlled by `tableLayout.columnsPinnable`
+     * on `DataGrid` and the column's own `enablePinning`.
+     */
     pinnable?: boolean;
     /** Header label text. */
     title?: string;

package/dist/compositions/data-grid-table/data-grid-table-body.d.ts

@@ -16,25 +16,34 @@ declare const DataGridTableBodyRowSkeleton: ({ children, }: {
 /** Skeleton placeholder cell, sized to match the configured row height. */
 declare const DataGridTableBodyRowSkeletonCell: <TData extends object>({ children, column, }: {
     children: ReactNode;
+    /** The column this placeholder cell sits in; supplies pinning, edge and `meta.cellClassName` styling. */
     column: Column<TData>;
 }) => React.JSX.Element;
 /** Data `<tr>`; fires `props.onRowClick` and reflects selection via `data-state="selected"`. */
 declare const DataGridTableBodyRow: <TData extends object>({ children, row, dndRef, dndStyle, dataIndex, }: {
     children: ReactNode;
+    /** The TanStack row to render; its selection state sets `data-state="selected"` and its original data goes to `onRowClick`. */
     row: Row<TData>;
+    /** Ref attached to the `<tr>`; the virtualiser passes its row-measuring ref here, a drag library can pass its node ref. */
     dndRef?: React.Ref<HTMLTableRowElement>;
+    /** Inline style merged over the row height, e.g. a drag library's transform. */
     dndStyle?: CSSProperties;
+    /** Row position in the full row model, written to `data-index` so the virtualiser can find the row when measuring. */
     dataIndex?: number;
 }) => React.JSX.Element;
 /** Full-width expansion row that renders the column meta `expandedContent` for its row. */
 declare const DataGridTableBodyRowExpandded: <TData extends object>({ row, }: {
+    /** The expanded row; its `original` data is passed to the first column's `meta.expandedContent`. */
     row: Row<TData>;
 }) => React.JSX.Element;
 /** Data `<td>`; applies pinning styles and drops its bottom border while the row is expanded. */
 declare const DataGridTableBodyRowCell: <TData extends object>({ children, cell, dndRef, dndStyle, }: {
     children: ReactNode;
+    /** The TanStack cell to render; its column sets pinning, edge and `meta.cellClassName` styling. */
     cell: Cell<TData>;
+    /** Ref attached to the `<td>`, for a drag library's node ref. */
     dndRef?: React.Ref<HTMLTableCellElement>;
+    /** Inline style merged over the pinning styles, e.g. a drag library's transform. */
     dndStyle?: CSSProperties;
 }) => React.JSX.Element;
 /** Empty-state row; shows `props.emptyMessage` or "No data available". */
@@ -43,11 +52,14 @@ declare const DataGridTableEmpty: () => React.JSX.Element;
 declare const DataGridTableLoader: () => React.JSX.Element;
 /** Per-row selection checkbox with an active-row accent bar; supports the indeterminate state. */
 declare const DataGridTableRowSelect: <TData extends object>({ row, size, }: {
+    /** The TanStack row this checkbox selects. */
     row: Row<TData>;
+    /** Mirrors the table's size: `"2xs"` and `"xs"` (or omitted) give the `"xs"` checkbox, anything larger the `"sm"` one. */
     size?: ComponentSize;
 }) => React.JSX.Element;
 /** Header select-all checkbox for the current page; disabled while loading or when empty. */
-declare const DataGridTableRowSelectAll: ({ size }: {
+declare const DataGridTableRowSelectAll: ({ size, }: {
+    /** Mirrors the table's size: `"2xs"` and `"xs"` (or omitted) give the `"xs"` checkbox, anything larger the `"sm"` one. */
     size?: ComponentSize;
 }) => React.JSX.Element;
 export { flexRender } from "@tanstack/react-table";

package/dist/compositions/data-grid-table/data-grid-table-body.js

@@ -126,7 +126,7 @@ const DataGridTableRowSelect = ({ row, size, }) => {
                 }, size: dataGridSize })] }));
 };
 /** Header select-all checkbox for the current page; disabled while loading or when empty. */
-const DataGridTableRowSelectAll = ({ size }) => {
+const DataGridTableRowSelectAll = ({ size, }) => {
     const { table, recordCount, loading } = useDataGrid();
     const isSmOrLarger = size ? size !== "2xs" && size !== "xs" : false;
     const dataGridSize = isSmOrLarger ? "sm" : "xs";

package/dist/compositions/data-grid-table/data-grid-table-header.d.ts

@@ -13,17 +13,22 @@ declare const DataGridTableHead: ({ children }: {
 /** Header `<tr>` for a single header group. */
 declare const DataGridTableHeadRow: <TData extends object>({ children, headerGroup, }: {
     children: ReactNode;
+    /** The TanStack header group this row renders; it supplies the row's React key. */
     headerGroup: HeaderGroup<TData>;
 }) => React.JSX.Element;
 /** Header `<th>`; resolves column pinning position and sizing from context. */
 declare const DataGridTableHeadRowCell: <TData extends object>({ children, header, dndRef, dndStyle, }: {
     children: ReactNode;
+    /** The TanStack header this `<th>` renders; its column sets size, pinning and `meta.headerClassName`. */
     header: Header<TData>;
+    /** Ref attached to the `<th>`, for a drag library's node ref. */
     dndRef?: React.Ref<HTMLTableCellElement>;
+    /** Inline style merged over width and pinning styles, e.g. a drag library's transform. */
     dndStyle?: CSSProperties;
 }) => React.JSX.Element;
 /** Column-resize handle; drag to resize, double-click to reset the column width. */
 declare const DataGridTableHeadRowCellResize: <TData extends object>({ header, }: {
+    /** The header whose column this handle resizes. */
     header: Header<TData>;
 }) => React.JSX.Element;
 export { flexRender } from "@tanstack/react-table";

package/dist/compositions/document-list/document-list-icon.d.ts

@@ -1,6 +1,7 @@
 import type { LucideIcon } from "lucide-react";
 import type React from "react";
 export interface DocumentListIconProps extends Omit<React.ComponentProps<"div">, "children"> {
+    /** Icon component (a Lucide icon), not a rendered element; sized from the list's `size`. */
     icon: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
 }
 /**

package/dist/compositions/document-list/document-list-root.js

@@ -8,6 +8,10 @@ const documentListVariants = cva("group/document-list flex flex-col", {
         variant: "grouped",
     },
     variants: {
+        /**
+         * Container treatment: `"grouped"` is one bordered, rounded card with the rows inside, `"divided"` separates rows with hairlines and no frame, `"separated"` leaves a gap between rows so each can carry its own surface.
+         * @default "grouped"
+         */
         variant: {
             divided: "divide-border divide-y",
             separated: "gap-3",

package/dist/compositions/editorial-card/editorial-card-content.d.ts

@@ -1,6 +1,8 @@
 export interface EditorialCardContentProps {
     className?: string;
+    /** Small muted line above the title, such as a category or date. Omitted when empty. */
     subtitle?: string;
+    /** Main line, shown larger and medium weight. */
     title: string;
 }
 /**

package/dist/compositions/file-upload/file-upload-dropzone.d.ts

@@ -17,8 +17,11 @@ interface FileUploadDropzoneProps {
     onClick?: () => void;
     /** Drag event handlers from useFileUpload */
     onDragEnter?: (e: DragEvent<HTMLElement>) => void;
+    /** Fires when a drag leaves the zone; pass `handleDragLeave` to clear the drag state. */
     onDragLeave?: (e: DragEvent<HTMLElement>) => void;
+    /** Fires continuously while a drag is over the zone; pass `handleDragOver`, which cancels the default so the zone accepts a drop. */
     onDragOver?: (e: DragEvent<HTMLElement>) => void;
+    /** Fires when files are dropped; pass `handleDrop` to validate and add them. */
     onDrop?: (e: DragEvent<HTMLElement>) => void;
     /** Ref for the dropzone element */
     ref?: Ref<HTMLButtonElement>;

package/dist/compositions/folder-tile/folder-tile-types.d.ts

@@ -36,10 +36,12 @@ export interface FolderTileProps extends Omit<HTMLMotionProps<"button">, "childr
     openOnHover?: boolean;
     /** Custom image renderer for frameworks such as Next.js. */
     renderImage?: (props: FolderTileImageProps) => ReactNode;
+    /** Marks the folder as chosen: selected styling and `aria-pressed="true"`. Has no effect while `showSelectedState` is false. */
     selected?: boolean;
     /** Whether selected styling is rendered when `selected` is true. */
     showSelectedState?: boolean;
     /** Explicit visual state. When omitted, derived from material count. */
     state?: FolderTileState;
+    /** Rendered as `data-testid` on the outer wrapper (not the button), for Playwright targeting. */
     testId?: string;
 }

package/dist/compositions/mobile-navigation/mobile-navigation-header.d.ts

@@ -36,10 +36,12 @@ export declare const MobileNavigationHeaderSearchSlot: ({ className, ...props }:
  * Pass short `children` (a count, say) beside the `icon` and the pill widens
  * from its 56px minimum to fit them, keeping the same height.
  *
- * @param props.emphasis - Button emphasis. @default "soft"
  * @bestPractice Keep children to a few characters, such as a cart count, and give the action an `aria-label` that says what the number means.
  */
-export declare const MobileNavigationHeaderAction: ({ children, className, emphasis, ...props }: React.ComponentProps<typeof Button>) => React.JSX.Element;
+export declare const MobileNavigationHeaderAction: ({ children, className, emphasis, ...props }: React.ComponentProps<typeof Button> & {
+    /** Visual weight, as on Button. @default "soft" */
+    emphasis?: React.ComponentProps<typeof Button>["emphasis"];
+}) => React.JSX.Element;
 /** Header action showing the brand logo, typically used to open the navigation. */
 export declare const MobileNavigationBrandTrigger: ({ className, ...props }: Omit<React.ComponentProps<typeof Button>, "children" | "icon">) => React.JSX.Element;
 /** Brand logo plus stacked wordmark lockup for the drawer header. */
@@ -50,5 +52,6 @@ export declare const MobileNavigationBrandLockup: ({ className, ...props }: Reac
  * @param props.onClose - Invoked when the close button is pressed.
  */
 export declare const MobileNavigationHeader: ({ className, onClose, ...props }: Omit<React.ComponentProps<typeof Flex>, "children"> & {
+    /** Called when the close button is pressed; set your open state to false here. */
     onClose: () => void;
 }) => React.JSX.Element;

package/dist/compositions/mobile-navigation/mobile-navigation-header.js

@@ -38,7 +38,6 @@ export const MobileNavigationHeaderSearchSlot = ({ className, ...props }) => (_j
  * Pass short `children` (a count, say) beside the `icon` and the pill widens
  * from its 56px minimum to fit them, keeping the same height.
  *
- * @param props.emphasis - Button emphasis. @default "soft"
  * @bestPractice Keep children to a few characters, such as a cart count, and give the action an `aria-label` that says what the number means.
  */
 export const MobileNavigationHeaderAction = ({ children, className, emphasis = "soft", ...props }) => (_jsx(Button, { className: cn("dark:bg-surface-2 h-10 min-w-14 bg-white", className), emphasis: emphasis, radius: "full", size: children === undefined ? "icon-lg" : "lg", ...props, children: children }));

package/dist/compositions/mobile-navigation/mobile-navigation-item.d.ts

@@ -35,9 +35,11 @@ export interface MobileNavigationProjectItemProps {
     active?: boolean;
     /** Dim the label to indicate an archived project. */
     archived?: boolean;
+    /** Project name; truncates to one line. */
     label: React.ReactNode;
     /** Invoked when the trailing action button is pressed. */
     onAction: () => void;
+    /** Icon for the trailing action button, such as an ellipsis for project options. */
     actionIcon: NavigationIcon;
     /** Accessible label for the trailing action button. */
     actionLabel: string;

package/dist/compositions/mobile-navigation/mobile-navigation-profile.d.ts

@@ -16,6 +16,7 @@ export interface MobileNavigationProfileActionProps extends Omit<React.Component
  */
 export declare const MobileNavigationProfileAction: ({ avatarName, className, displayName, loading, userAvatarUrl, ...props }: MobileNavigationProfileActionProps) => React.JSX.Element;
 export interface MobileNavigationDrawerProfileProps {
+    /** The user's name, shown in medium weight; also the avatar image's alt text. */
     displayName: string;
     /** Secondary line under the name; hidden when absent. */
     email: string | undefined;

package/dist/compositions/mobile-navigation/mobile-navigation-root.d.ts

@@ -27,6 +27,7 @@ export type NavigationIcon = IconComponent;
  */
 export declare const MobileNavigationRoot: ({ "aria-label": ariaLabel, children, className, onClose, ...props }: Omit<HTMLMotionProps<"div">, "children"> & {
     children?: React.ReactNode;
+    /** Called when Escape is pressed. The overlay never unmounts itself, so set your open state to false here. */
     onClose?: () => void;
 }) => React.JSX.Element;
 /**

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

@@ -19,7 +19,10 @@ export interface PageToolbarAppliedProps extends ComponentProps<typeof Flex> {
     children?: ReactNode;
     /** Removes every applied filter. */
     onClear: () => void;
-    /** @default "Clear all" */
+    /**
+     * Text of the button that calls `onClear`.
+     * @default "Clear all"
+     */
     clearLabel?: string;
     /**
      * Draw a short rule after the group, before the suggestions that follow.

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

@@ -12,8 +12,11 @@ export interface PageToolbarSortProps {
     direction?: PageToolbarSortDirection | undefined;
     /** Names the control for assistive technology. @default "Sort" */
     label?: string;
+    /** Called with `"asc"` or `"desc"` when the user picks a direction. The Ascending and Descending choices only appear when both this and `direction` are set. */
     onDirectionChange?: (direction: PageToolbarSortDirection) => void;
+    /** Called with the chosen option's `value` when the user picks an order. */
     onValueChange: (value: string) => void;
+    /** The orders to offer, each a `value` and a `label`; the label of the current one shows on the button. */
     options: readonly PageToolbarSortOption[];
     /** The current order's value; one matching no option reads as unsorted. */
     value: string;

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

@@ -1,6 +1,7 @@
 import type { ProductCardProps } from "./product-card-types.js";
 type ProductCardContentProps = Omit<ProductCardProps, "product" | "variantId" | "mode" | "active" | "addGlyph" | "availability" | "dragging" | "labels" | "menuOpen" | "onAdd" | "onFindSimilar" | "price" | "processing" | "showSwatches" | "maxSwatches" | "onVariantChange" | "productUrl" | "renderTools" | "renderImage" | "renderAddToCart" | "dragAdapter">;
 declare const ProductCardContentBase: ({ className, similarityScore, overrideImageUrl, onAddToCartSuccess, priority, ...props }: ProductCardContentProps & {
+    /** Called when the `renderAddToCart` slot reports a successful add, via the `onAdded` it receives. */
     onAddToCartSuccess?: (() => void) | undefined;
 }) => import("react").JSX.Element;
 export declare const ProductCardContent: import("react").MemoExoticComponent<typeof ProductCardContentBase>;

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

@@ -46,11 +46,17 @@ interface ProductCardDragAdapterProps {
  */
 type ProductCardDragAdapter = ComponentType<ProductCardDragAdapterProps>;
 interface ProductCardImageProps extends ComponentProps<"div"> {
-    /** Override image URL - used for visual search to show the matched image */
+    /** Image URL shown in place of the variant's first image, e.g. the matched crop in a visual search. */
     overrideImageUrl?: string | undefined;
-    /** Prioritise loading this image (sets loading="eager" and adds preload link) */
+    /** Load this image eagerly (`loading="eager"`, high fetch priority in the default renderer); forwarded to `renderImage`. */
     priority?: boolean | undefined;
+    /**
+     * Show the `similarityScore` pill. Needs `similarityScore` too, and is
+     * ignored outside `"single"` and `"inspiration"` modes.
+     * @default false
+     */
     showSimilarityScore?: boolean | undefined;
+    /** Match from `0` to `1`, shown as a rounded percentage (`0.87` reads `87%`). */
     similarityScore?: number | undefined;
 }
 /**

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

@@ -92,6 +92,12 @@ interface ProductCardProviderProps {
      */
     action?: ProductCardActionProps | undefined;
     children: ReactNode;
+    /**
+     * Which parts of the card show: brand, name, line clamps, swatches, add to
+     * cart. `ProductCard` takes the same switches as flat props (`showProductBrand`
+     * and so on) and builds this for you; pass `display` only when using
+     * `ProductCardProvider` directly. Each key falls back to its own default.
+     */
     display?: ProductCardDisplayOptions | undefined;
     /**
      * Component slot that wires drag behaviour (e.g. dnd-kit `useDraggable`)
@@ -206,6 +212,12 @@ interface ProductCardProviderProps {
      * that pass `renderAddToCart` and nothing else.
      */
     primaryAction?: ProductCardPrimaryAction | undefined;
+    /**
+     * The material to show. In `"group"` mode its `variants` become the colourway
+     * swatches (the card falls back to the product itself when there are none),
+     * and `images[0]` of the selected variant is the photograph. A product whose
+     * selected variant has no images renders a "no photography" placeholder.
+     */
     product: ProductCardProduct;
     /**
      * Builds the href of a product's page. Receives the selected variant.
@@ -251,15 +263,43 @@ interface ProductCardProviderProps {
  * Props for the main ProductCard component.
  */
 type ProductCardProps = ComponentProps<"div"> & Pick<ProductCardProviderProps, "action" | "addGlyph" | "availability" | "dragAdapter" | "dragging" | "active" | "labels" | "linkAs" | "linkPrefetch" | "maxSwatches" | "menuOpen" | "mode" | "onAdd" | "onCardClick" | "onFindSimilar" | "onQuickView" | "onVariantChange" | "price" | "primaryAction" | "processing" | "product" | "productUrl" | "renderAddToCart" | "renderImage" | "renderTools" | "showActivePointer" | "statusBadge" | "variantId" | "width"> & {
-    /** Override image URL - used for visual search to show the matched image */
+    /**
+     * Image URL shown in place of the product's own first image, e.g. the
+     * matched crop in a visual search. Honoured in `"single"` and `"swatch"`
+     * modes only.
+     */
     overrideImageUrl?: string | undefined;
-    /** Prioritise loading images (sets loading="eager" and adds preload link) */
+    /**
+     * Load the main image eagerly (`loading="eager"`, high fetch priority in the
+     * default renderer, and forwarded to `renderImage`). Set it on above-the-fold
+     * cards, not the whole grid.
+     */
     priority?: boolean | undefined;
     /** How many lines the brand may take before it clamps; see `ProductCardDisplayOptions.brandLines`. */
     productBrandLines?: 1 | 2 | undefined;
+    /**
+     * How many lines the product name may take before it clamps. Choose `2`
+     * where names differ only at the end; rows stay level because the clamp is
+     * a maximum, not a reserved height.
+     * @default 1
+     */
     productNameLines?: 1 | 2 | undefined;
+    /**
+     * Show the cart control. It only ever appears when `renderAddToCart` is also
+     * supplied, and `primaryAction` can replace it with another action.
+     * @default true
+     */
     showAddToCart?: boolean | undefined;
+    /**
+     * Show the brand name above the product name. Cards without a brand name
+     * omit the line either way.
+     * @default true
+     */
     showProductBrand?: boolean | undefined;
+    /**
+     * Show the product name.
+     * @default true
+     */
     showProductName?: boolean | undefined;
     /**
      * Show the row of colourway swatches. Single-colour products and `single`
@@ -267,6 +307,11 @@ type ProductCardProps = ComponentProps<"div"> & Pick<ProductCardProviderProps, "
      * @default true
      */
     showSwatches?: boolean | undefined;
+    /**
+     * Visual-search match from `0` to `1` (not a percentage), shown as a
+     * rounded percentage pill over the image: `0.87` reads `87%`. Only
+     * `"single"` and `"inspiration"` modes show it; omit it for no pill.
+     */
     similarityScore?: number | undefined;
 };
 export type { ProductCardContextValue, ProductCardProps, ProductCardProviderProps, };

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

@@ -1,5 +1,6 @@
 import type { ProductCardProps } from "./product-card-types.js";
 declare const ProductCardBase: ({ className, product, variantId, mode, width, active, dragging, availability, labels, showActivePointer, similarityScore, overrideImageUrl, priority, showSwatches, showAddToCart, productBrandLines, productNameLines, showProductBrand, showProductName, maxSwatches, menuOpen, onAdd, addGlyph, onFindSimilar, price, processing, onCardClick, onVariantChange, linkAs, productUrl, linkPrefetch, renderTools, renderImage, renderAddToCart, dragAdapter, action, primaryAction, statusBadge, onQuickView, onAddToCartSuccess, ...props }: ProductCardProps & {
+    /** Called when the `renderAddToCart` slot reports a successful add, via the `onAdded` it receives. */
     onAddToCartSuccess?: (() => void) | undefined;
 }) => import("react").JSX.Element;
 /**
@@ -33,6 +34,8 @@ declare const ProductCardBase: ({ className, product, variantId, mode, width, ac
  * `linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.
  * @bestPractice Cart UI renders only when a `renderAddToCart` slot is
  * provided; keep `dragAdapter` referentially stable (module-level constant).
+ * @bestPractice Use ProductCard for a material in a grid or list; its image is square, which is how a material is always shown. Don't rebuild the card with a landscape image.
+ * @keywords material card, material tile, sample card, catalogue card, product tile
  * @category catalogue
  */
 export declare const ProductCard: import("react").MemoExoticComponent<typeof ProductCardBase>;

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

@@ -42,6 +42,8 @@ const ProductCardBase = ({ className, product, variantId, mode = "group", width,
  * `linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.
  * @bestPractice Cart UI renders only when a `renderAddToCart` slot is
  * provided; keep `dragAdapter` referentially stable (module-level constant).
+ * @bestPractice Use ProductCard for a material in a grid or list; its image is square, which is how a material is always shown. Don't rebuild the card with a landscape image.
+ * @keywords material card, material tile, sample card, catalogue card, product tile
  * @category catalogue
  */
 export const ProductCard = memo(ProductCardBase);

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

@@ -1,5 +1,7 @@
 interface ProductCardSwatchProps {
+    /** Image URL shown in place of the variant's first image. */
     overrideImageUrl?: string | undefined;
+    /** Load the tile's image eagerly; forwarded to `renderImage`. */
     priority?: boolean | undefined;
 }
 /**

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

@@ -1,6 +1,12 @@
 import type { ButtonProps } from "@instruments/materia-ui/components/button";
 import type { ReactNode } from "react";
 interface ProductCardToolsProps {
+    /**
+     * Whether the `renderTools` buttons are mounted. `ProductCard` sets it while
+     * the pointer or keyboard focus is inside the card, so a large grid does not
+     * render every hidden action.
+     * @default true
+     */
     active?: boolean;
     className?: string;
 }