@instruments/materia-ui 0.4.6 → 0.4.8

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 }: Omit<React.ComponentProps<typeof Button>, "emphasis"> & {
+    /** 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;
 /**

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;
 }

package/dist/compositions/product-specifications-selector/product-specifications-selector.d.ts

@@ -14,7 +14,16 @@ interface SiblingWithAttributes {
     variantAttributes: VariantAttributes | null;
 }
 export interface ProductSpecificationsSelectorProps {
+    /**
+     * The current selection, keyed by filter key (`"color"` for `colorName`, otherwise the
+     * dimension name such as `"finish"`) to the selected option's `value`, or `null` for none.
+     */
     filters: Record<string, string | null>;
+    /**
+     * Called when an option is picked, with the filter key and the option's `value`;
+     * picking the selected option again sends `null` to clear it. When `onSiblingSelect` and
+     * `siblingsWithAttributes` find a matching sibling, that fires instead.
+     */
     onFilterChange: (key: string, value: string | null) => void;
     /** Callback when a sibling is selected (fallback variant selection) */
     onSiblingSelect?: (siblingId: string) => void;
@@ -26,6 +35,11 @@ export interface ProductSpecificationsSelectorProps {
     siblings?: Sibling[];
     /** Full sibling data with variant attributes for computing compatible options on hover */
     siblingsWithAttributes?: SiblingWithAttributes[];
+    /**
+     * The options on offer per dimension (`colorName`, `pattern`, `finish`, `size`, `width`,
+     * `length`, `substrate`, `finishType`). Each present dimension becomes one field, ordered
+     * with colourways first; an option with `available: false` is shown as unavailable.
+     */
     variantOptions: VariantOptions;
 }
 /**

package/dist/compositions/quick-view/quick-view-body.d.ts

@@ -1,6 +1,6 @@
 import { ScrollArea } from "@instruments/materia-ui/components/scroll-area";
 import type { ComponentProps } from "react";
-export type QuickViewBodyProps = Omit<ComponentProps<typeof ScrollArea>, "as" | "orientation" | "render"> & {
+export type QuickViewBodyProps = Omit<ComponentProps<typeof ScrollArea>, "aria-label" | "as" | "orientation" | "render"> & {
     /** Names the scrolling region for assistive tech, e.g. "Product details". */
     "aria-label": string;
 };

package/dist/compositions/sidebar/sidebar-group.d.ts

@@ -6,7 +6,11 @@ export declare const SidebarGroup: ({ className, ...props }: React.ComponentProp
 /** Heading for a {@link SidebarGroup}; fades out (keeping layout) when collapsed to an icon rail. Pass `render` to use a custom element. */
 export declare const SidebarGroupLabel: ({ className, render, ...props }: useRender.ComponentProps<"div">) => React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 /** Icon button pinned to a group's top-right corner (defaults to a `+`); hidden when collapsed unless `showWhenCollapsed`. */
-export declare const SidebarGroupAction: ({ className, icon, size, radius, emphasis, showWhenCollapsed, ...props }: React.ComponentProps<typeof Button> & {
+export declare const SidebarGroupAction: ({ className, icon, size, radius, emphasis, showWhenCollapsed, ...props }: Omit<React.ComponentProps<typeof Button>, "emphasis" | "size"> & {
+    /** Size token, as on Button. @default "icon-sm" */
+    size?: React.ComponentProps<typeof Button>["size"];
+    /** Visual weight, as on Button. @default "ghost" */
+    emphasis?: React.ComponentProps<typeof Button>["emphasis"];
     /** Show the action button even when sidebar is collapsed */
     showWhenCollapsed?: boolean;
 }) => React.JSX.Element;

package/dist/compositions/sidebar/sidebar-menu-button.d.ts

@@ -10,16 +10,27 @@ type SidebarMenuButtonProps = Omit<useRender.ComponentProps<"button">, "children
     tooltip?: string | React.ComponentProps<typeof TooltipContent>;
     /** Control tooltip visibility. Use `false` to hide tooltip (e.g., when a dropdown is open). */
     tooltipOpen?: boolean;
+    /**
+     * Row height and text size. Use `"xl"` in an icon-collapsible sidebar so the collapsed square centres on the rail.
+     * @default "base"
+     */
     size?: ComponentSize;
+    /**
+     * Surface treatment: `"input"` uses the sidebar's accent fill on hover and when active, `"default"` the standard accent tint, `"outline"` adds a ring.
+     * @default "input"
+     */
     variant?: "default" | "input" | "outline";
+    /** Leading icon component. When the sidebar collapses to the rail it is the only thing shown, unless `collapsedIcon` or `collapsedContent` replaces it. */
     icon?: IconComponent;
     /** Icon to show when sidebar is collapsed (overrides icon) */
     collapsedIcon?: IconComponent;
     /** Custom content to show when sidebar is collapsed (e.g., Avatar). Takes precedence over collapsedIcon. */
     collapsedContent?: React.ReactNode;
+    /** Trailing icon component, such as a chevron for a submenu. Replaces the `kbd` hint when both are set, and hides when the sidebar collapses. */
     suffixIcon?: IconComponent;
     /** Keep label/suffix visible even when the sidebar provider is collapsed. */
     forceExpanded?: boolean;
+    /** Keyboard shortcut keys shown as keycaps at the end of the row, one string per key (e.g. `["⌘", "K"]`). Hidden when collapsed or when `suffixIcon` is set. */
     kbd?: string[];
     children?: React.ReactNode;
 };

package/dist/compositions/sidebar/sidebar-menu-sub.d.ts

@@ -19,13 +19,17 @@ export declare const SidebarMenuSubScrollArea: ({ children, className, fade, max
 type SidebarMenuSubItemProps = React.ComponentProps<"li">;
 /** The `<li>` wrapper for a single submenu row. */
 export declare const SidebarMenuSubItem: ({ className, ...props }: SidebarMenuSubItemProps) => React.JSX.Element;
-type SidebarMenuSubButtonProps = Omit<MenuItemProps, "icon" | "dot"> & {
+type SidebarMenuSubButtonProps = Omit<MenuItemProps, "dot" | "icon" | "iconClassName" | "size" | "variant"> & {
     /** Dot indicator in the left column (takes precedence over icon): `true` for a neutral dot, or a {@link Tone} to tint it. */
     dot?: boolean | Tone;
     /** Icon to display in the left icon column */
     icon?: IconComponent;
     /** Additional className for the icon */
     iconClassName?: string;
+    /** Row size, as on MenuItem. @default "xl" */
+    size?: MenuItemProps["size"];
+    /** Row style, as on MenuItem. @default "input" */
+    variant?: MenuItemProps["variant"];
 };
 /**
  * SidebarMenuSubButton UI component.

package/dist/compositions/sidebar/sidebar-trigger.d.ts

@@ -1,9 +1,11 @@
 import { Button } from "@instruments/materia-ui/components/button";
 import type React from "react";
 import type { IconComponent } from "../../tokens/icon-component.js";
-type SidebarTriggerProps = Omit<React.ComponentProps<typeof Button>, "icon"> & {
+type SidebarTriggerProps = Omit<React.ComponentProps<typeof Button>, "emphasis" | "icon"> & {
     /** Icon to display. Defaults to PanelLeftCloseIcon. */
     icon?: IconComponent;
+    /** Visual weight, as on Button. @default "ghost" */
+    emphasis?: React.ComponentProps<typeof Button>["emphasis"];
 };
 /** Icon button that toggles the sidebar open/collapsed via {@link useSidebar}; must render inside a {@link SidebarProvider}. Any `onClick` runs before the toggle. */
 export declare const SidebarTrigger: ({ className, emphasis, onClick, icon, ...props }: SidebarTriggerProps) => React.JSX.Element;

package/dist/compositions/variant-selector/variant-selector-item.d.ts

@@ -8,6 +8,7 @@ export interface VariantSelectorItemProps {
     disabled?: boolean;
     /** Whether this option is highlighted (compatible with a hovered unavailable option) */
     highlighted?: boolean;
+    /** Picture shown inside the tile, such as an `<img>` of the variant; omit it for a plain `color` tile. */
     image?: ReactNode;
     /** Label text */
     label: string;