@instruments/materia-ui 0.4.1 → 0.4.3

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

@@ -24,6 +24,7 @@ import { OVERLAY_SCRIM_DARK, POPOVER_CONTENT_ANIMATION, POPOVER_SURFACE, } from
  * @bestPractice Use `Popover` for an anchored non-blocking panel dismissed on outside-click / Esc; a page-blocking modal is a `Dialog`, a menu of actions is a `DropdownMenu`.
  * @bestPractice It's non-modal by default (`modal={false}`) so the page stays interactive - pass `modal` only when you must trap focus and block the background.
  * @bestPractice `PopoverContent` portals to the body; anchor to a non-trigger element with its `anchor` prop.
+ * @keywords popup, flyout, popout
  * @category overlays
  */
 const Popover = ({ ...props }) => (_jsx(PopoverPrimitive.Root, { "data-component": "popover", "data-slot": "popover", ...props }));

package/dist/components/quantity-control/quantity-control-root.d.ts

@@ -44,6 +44,7 @@ interface QuantityControlProps {
  * @bestPractice Pass `onRemove` when hitting the minimum should delete the item - the decrement button then swaps to a trash icon; without it, decrement just stops at `min`.
  * @bestPractice It's controlled - pass the current `value` and update it in `onIncrement`/`onDecrement`, which fire once per step for clicks, arrow keys and each repeat of a held button. Typing a number is not supported.
  * @bestPractice Tab focuses the quantity itself (the stepper buttons are skipped, as in any number field), announced by its `label`. In a list of lines, pass a `label` naming the item so each field is told apart.
+ * @keywords counter, number input, increment, spinbutton
  * @category actions
  */
 export declare const QuantityControl: ({ value, label, onIncrement, onDecrement, onRemove, min, max, disabled, radius, testId, }: QuantityControlProps) => React.JSX.Element;

package/dist/components/quantity-control/quantity-control-root.js

@@ -47,6 +47,7 @@ const stepperProps = {
  * @bestPractice Pass `onRemove` when hitting the minimum should delete the item - the decrement button then swaps to a trash icon; without it, decrement just stops at `min`.
  * @bestPractice It's controlled - pass the current `value` and update it in `onIncrement`/`onDecrement`, which fire once per step for clicks, arrow keys and each repeat of a held button. Typing a number is not supported.
  * @bestPractice Tab focuses the quantity itself (the stepper buttons are skipped, as in any number field), announced by its `label`. In a list of lines, pass a `label` naming the item so each field is told apart.
+ * @keywords counter, number input, increment, spinbutton
  * @category actions
  */
 export const QuantityControl = ({ value, label = "Quantity", onIncrement, onDecrement, onRemove, min = 1, max = 99, disabled = false, radius = "rounded", testId, }) => {

package/dist/components/select/select-root.d.ts

@@ -9,6 +9,7 @@ import type { WithTestId } from "../../utils/with-test-id.js";
  * @bestPractice Use `Select` to pick one option from a short closed list; when users need type-to-filter, use `Combobox` instead.
  * @bestPractice Drive it with `value` + `onValueChange` (controlled) or `defaultValue` (uncontrolled), and give it an accessible name via the trigger (`Field`/`Label`).
  * @bestPractice Pass `items` (a value-to-label map or `{ value, label }[]`) so the trigger shows the selected label even before the popup has mounted.
+ * @keywords dropdown, picker
  * @category forms
  */
 declare const Select: <Value, Multiple extends boolean | undefined = false>({ testId, ...props }: WithTestId<SelectPrimitive.Root.Props<Value, Multiple>>) => import("react").JSX.Element;

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

@@ -10,6 +10,7 @@ import { Select as SelectPrimitive } from "@base-ui/react/select";
  * @bestPractice Use `Select` to pick one option from a short closed list; when users need type-to-filter, use `Combobox` instead.
  * @bestPractice Drive it with `value` + `onValueChange` (controlled) or `defaultValue` (uncontrolled), and give it an accessible name via the trigger (`Field`/`Label`).
  * @bestPractice Pass `items` (a value-to-label map or `{ value, label }[]`) so the trigger shows the selected label even before the popup has mounted.
+ * @keywords dropdown, picker
  * @category forms
  */
 const Select = ({ testId, ...props }) => (_jsx(SelectPrimitive.Root, { "data-component": "select", "data-slot": "select", "data-testid": testId, ...props }));

package/dist/components/separator/separator-root.d.ts

@@ -24,6 +24,7 @@ interface SeparatorProps extends SeparatorPrimitive.Props {
  *
  * @bestPractice It is announced as a separator by default - pass `aria-hidden` when the rule is purely decorative.
  * @bestPractice For an inline rule set `orientation="vertical"` and give it an explicit height (e.g. `className="h-6"`) - a vertical separator has no intrinsic length.
+ * @keywords divider, rule, hr
  * @category layout
  */
 declare const Separator: ({ className, orientation, variant, ...props }: SeparatorProps) => import("react").JSX.Element;

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

@@ -22,6 +22,7 @@ const VARIANT_CLASSES = {
  *
  * @bestPractice It is announced as a separator by default - pass `aria-hidden` when the rule is purely decorative.
  * @bestPractice For an inline rule set `orientation="vertical"` and give it an explicit height (e.g. `className="h-6"`) - a vertical separator has no intrinsic length.
+ * @keywords divider, rule, hr
  * @category layout
  */
 const Separator = ({ className, orientation = "horizontal", variant = "default", ...props }) => (_jsx(SeparatorPrimitive, { className: cn("shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px", VARIANT_CLASSES[variant], className), "data-component": "separator", "data-slot": "separator", orientation: orientation, ...props }));

package/dist/components/sheet/sheet-root.d.ts

@@ -5,6 +5,7 @@ import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
  *
  * @bestPractice Use `Sheet` for a simple edge panel holding a focused form / settings; a drag-to-dismiss bottom sheet is a `Drawer`, and nested panels are a `Sidepanel`.
  * @bestPractice Set the entry edge via `SheetContent` `side`; always render a `SheetTitle` (wrap in `sr-only` if hidden) so the panel is announced.
+ * @keywords drawer, side sheet, slide-over
  * @category overlays
  */
 export declare const Sheet: (props: DialogPrimitive.Root.Props<unknown>) => import("react").ReactElement;

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

@@ -6,6 +6,7 @@ import { makeOverlayRoot } from "../overlay-primitives.js";
  *
  * @bestPractice Use `Sheet` for a simple edge panel holding a focused form / settings; a drag-to-dismiss bottom sheet is a `Drawer`, and nested panels are a `Sidepanel`.
  * @bestPractice Set the entry edge via `SheetContent` `side`; always render a `SheetTitle` (wrap in `sr-only` if hidden) so the panel is announced.
+ * @keywords drawer, side sheet, slide-over
  * @category overlays
  */
 export const Sheet = makeOverlayRoot(DialogPrimitive.Root, {

package/dist/components/spinner/spinner-root.d.ts

@@ -20,6 +20,7 @@ export type SpinnerProps = LucideProps & {
  *
  * @bestPractice Use `Spinner` for small inline / action loading (inside a `Button`, next to text); a blocking full region is `LoadingState`, a layout placeholder is `Skeleton`.
  * @bestPractice A bare `Spinner` carries no accessible name - wrap it in a labelled live region (e.g. `LoadingState`) when it's the sole loading signal.
+ * @keywords loader, loading, activity indicator
  * @category feedback
  */
 export declare const Spinner: ({ size, className, ...props }: SpinnerProps) => import("react").JSX.Element;

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

@@ -41,6 +41,7 @@ const SPINNER_STROKE = {
  *
  * @bestPractice Use `Spinner` for small inline / action loading (inside a `Button`, next to text); a blocking full region is `LoadingState`, a layout placeholder is `Skeleton`.
  * @bestPractice A bare `Spinner` carries no accessible name - wrap it in a labelled live region (e.g. `LoadingState`) when it's the sole loading signal.
+ * @keywords loader, loading, activity indicator
  * @category feedback
  */
 export const Spinner = ({ size = "base", className, ...props }) => {

package/dist/components/stepper/stepper-root.d.ts

@@ -26,6 +26,7 @@ export type StepperProps = {
  *
  * @bestPractice Give each step a `StepperItem` child in order - progress is derived from child index, so conditionally rendering steps shifts the fill.
  * @bestPractice Control completion via `value`/`onValueChange` (or uncontrolled `defaultValue`); the fill reaches only the last *completed* step, not the current one.
+ * @keywords wizard, steps, multi-step
  * @category navigation
  */
 export declare const Stepper: ({ value, defaultValue, onValueChange, size, className, children, ...rest }: StepperProps) => React.JSX.Element;

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

@@ -13,6 +13,7 @@ import { DEFAULT_STEPPER_SIZE, STEPPER_TRACK_SIZE_CLASSES, stepperRootVariants,
  *
  * @bestPractice Give each step a `StepperItem` child in order - progress is derived from child index, so conditionally rendering steps shifts the fill.
  * @bestPractice Control completion via `value`/`onValueChange` (or uncontrolled `defaultValue`); the fill reaches only the last *completed* step, not the current one.
+ * @keywords wizard, steps, multi-step
  * @category navigation
  */
 export const Stepper = ({ value, defaultValue = 0, onValueChange, size = "base", className, children, ...rest }) => {

package/dist/components/success-tick-ripple/success-tick-ripple-root.d.ts

@@ -30,6 +30,7 @@ export interface SuccessTickRippleProps {
  *
  * @bestPractice Wrap `SuccessTickRipple` in a `position: relative; overflow: hidden` parent - the ripple field is absolutely positioned and bleeds past an unbounded container.
  * @bestPractice It's decorative (`aria-hidden`) unless you pass `aria-label`, which exposes it as an `img`; animations are CSS-only and already collapse under `prefers-reduced-motion`.
+ * @keywords celebrate, success, confirmation
  * @category feedback
  */
 export declare const SuccessTickRipple: ({ size, className, "aria-label": ariaLabel, }: SuccessTickRippleProps) => import("react").JSX.Element;

package/dist/components/success-tick-ripple/success-tick-ripple-root.js

@@ -23,6 +23,7 @@ const CHECK_PATH = "M5 13.5 9 17.5 19 6.5";
  *
  * @bestPractice Wrap `SuccessTickRipple` in a `position: relative; overflow: hidden` parent - the ripple field is absolutely positioned and bleeds past an unbounded container.
  * @bestPractice It's decorative (`aria-hidden`) unless you pass `aria-label`, which exposes it as an `img`; animations are CSS-only and already collapse under `prefers-reduced-motion`.
+ * @keywords celebrate, success, confirmation
  * @category feedback
  */
 export const SuccessTickRipple = ({ size = 64, className, "aria-label": ariaLabel, }) => {

package/dist/components/switch/switch-root.d.ts

@@ -42,6 +42,7 @@ type SwitchProps = Omit<React.ComponentProps<typeof SwitchPrimitive.Root>, "size
  * @bestPractice Use `Switch` for an instantly-applied on/off setting; use `Checkbox` for opt-ins confirmed by a submit, and `RadioGroup` for mutually-exclusive choices.
  * @bestPractice Controlled use needs `checked` + `onCheckedChange`; with only `checked` the switch won't move - use `defaultChecked` for uncontrolled.
  * @bestPractice `Switch` has no built-in label - associate a `Label` via `htmlFor`/`id` so the toggle has an accessible name.
+ * @keywords toggle, on off
  * @category forms
  */
 declare const Switch: ({ className, size, ...props }: SwitchProps) => React.JSX.Element;

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

@@ -57,6 +57,7 @@ export const SWITCH_THUMB_CLASSES = {
  * @bestPractice Use `Switch` for an instantly-applied on/off setting; use `Checkbox` for opt-ins confirmed by a submit, and `RadioGroup` for mutually-exclusive choices.
  * @bestPractice Controlled use needs `checked` + `onCheckedChange`; with only `checked` the switch won't move - use `defaultChecked` for uncontrolled.
  * @bestPractice `Switch` has no built-in label - associate a `Label` via `htmlFor`/`id` so the toggle has an accessible name.
+ * @keywords toggle, on off
  * @category forms
  */
 const Switch = ({ className, size, ...props }) => (_jsx(SwitchPrimitive.Root, { nativeButton: true, render: (buttonProps) => _jsx("button", { type: "button", ...buttonProps }), className: cn("peer data-checked:bg-primary data-unchecked:bg-muted dark:data-checked:bg-muted-foreground dark:data-unchecked:bg-secondary inline-flex shrink-0 items-center rounded-full border-transparent outline-none disabled:cursor-not-allowed disabled:opacity-50 data-checked:shadow-xs", getResponsiveSizeClasses(size, SWITCH_TRACK_CLASSES, DEFAULT_SWITCH_SIZE), focusInput(), hasErrorInput, 

package/dist/components/tag/tag-root.d.ts

@@ -53,6 +53,7 @@ export interface TagProps extends Omit<React.HTMLAttributes<HTMLElement>, "child
  * @bestPractice With both actions, HTML attributes (including the accessible name and selected state) apply to the selection button; `className` and `style` style the outer chip.
  * @bestPractice Set at most one leading visual - `loading` > `imageUrl` > `dot` > `icon` (in that precedence); pass a Lucide component to `icon` (not `<Icon/>`), and `imageUrl` renders a circular `<img alt="">`, so keep it decorative.
  * @bestPractice When `onDismiss` is set, Backspace/Delete also removes the tag while it's focused - don't bind your own conflicting key handler.
+ * @keywords chip, token
  * @category data
  */
 export declare const Tag: ({ className, style, tone, size, emphasis, asInput, radius, disabled, children, icon, dot, imageUrl, loading, onClick, onDismiss, dismissIcon, hideDismiss, ...props }: TagProps) => React.JSX.Element;

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

@@ -161,6 +161,7 @@ const getTagAppearanceProps = ({ emphasis, asInput, disabled, radius, }) => {
  * @bestPractice With both actions, HTML attributes (including the accessible name and selected state) apply to the selection button; `className` and `style` style the outer chip.
  * @bestPractice Set at most one leading visual - `loading` > `imageUrl` > `dot` > `icon` (in that precedence); pass a Lucide component to `icon` (not `<Icon/>`), and `imageUrl` renders a circular `<img alt="">`, so keep it decorative.
  * @bestPractice When `onDismiss` is set, Backspace/Delete also removes the tag while it's focused - don't bind your own conflicting key handler.
+ * @keywords chip, token
  * @category data
  */
 export const Tag = ({ className, style, tone, size = "base", emphasis, asInput, radius, disabled, children, icon, dot, imageUrl, loading = false, onClick, onDismiss, dismissIcon, hideDismiss = false, ...props }) => {

package/dist/components/textarea/textarea-root.d.ts

@@ -26,6 +26,7 @@ interface TextareaProps extends WithTestId<React.ComponentProps<"textarea">> {
  * @bestPractice Inside a `Field`, let invalid state cascade like `Input` - omit `hasError`; pass it only to force error styling on a standalone `Textarea`.
  * @bestPractice It auto-grows with content (`field-sizing-content`); set `rows` for a minimum height in lines rather than pinning height via CSS.
  * @bestPractice Give it a label - inside a `Field` a `FieldLabel` targets it with no ids to wire; standalone, point a `Label`'s `htmlFor` at its `id`. A placeholder is not an accessible name.
+ * @keywords multiline, text area
  * @category forms
  */
 declare const Textarea: ({ className, testId, hasError, id, name, disabled, rows, style, ...props }: TextareaProps) => React.JSX.Element;

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

@@ -29,6 +29,7 @@ import { useTextareaRows } from "./use-textarea-rows.js";
  * @bestPractice Inside a `Field`, let invalid state cascade like `Input` - omit `hasError`; pass it only to force error styling on a standalone `Textarea`.
  * @bestPractice It auto-grows with content (`field-sizing-content`); set `rows` for a minimum height in lines rather than pinning height via CSS.
  * @bestPractice Give it a label - inside a `Field` a `FieldLabel` targets it with no ids to wire; standalone, point a `Label`'s `htmlFor` at its `id`. A placeholder is not an accessible name.
+ * @keywords multiline, text area
  * @category forms
  */
 const Textarea = ({ className, testId, hasError, id, name, disabled, rows, style, ...props }) => {

package/dist/components/time-slot-picker/time-slot-picker-root.d.ts

@@ -34,6 +34,7 @@ export interface TimeSlotPickerProps extends Omit<React.ComponentProps<"div">, "
  * @bestPractice Pass slot values already formatted for display, or give each slot a `label` - the picker does no time parsing or 12/24-hour formatting.
  * @bestPractice Name the group with `aria-label` or `aria-labelledby`; screen readers announce it before the first slot.
  * @bestPractice Use `TimeSlotPicker` for a fixed set of offered times; for any time the user types, use `Input type="time"`.
+ * @keywords date, appointment, booking, schedule
  * @category forms
  */
 export declare const TimeSlotPicker: ({ className, defaultValue, disabled, name, onValueChange, slots, value, ...props }: TimeSlotPickerProps) => React.JSX.Element;

package/dist/components/time-slot-picker/time-slot-picker-root.js

@@ -19,6 +19,7 @@ focusRing(), "inline-flex h-9 cursor-pointer items-center justify-center px-4 se
  * @bestPractice Pass slot values already formatted for display, or give each slot a `label` - the picker does no time parsing or 12/24-hour formatting.
  * @bestPractice Name the group with `aria-label` or `aria-labelledby`; screen readers announce it before the first slot.
  * @bestPractice Use `TimeSlotPicker` for a fixed set of offered times; for any time the user types, use `Input type="time"`.
+ * @keywords date, appointment, booking, schedule
  * @category forms
  */
 export const TimeSlotPicker = ({ className, defaultValue, disabled, name, onValueChange, slots, value, ...props }) => {

package/dist/components/toast/toast-root.d.ts

@@ -34,6 +34,7 @@ export interface ToasterProps {
  * @bestPractice Use toasts for transient, auto-dismissing notifications; a persistent inline message is an `Alert`.
  * @bestPractice Mount `<Toaster />` exactly once near the app root, then fire toasts with `toast()` from `@instruments/materia-ui/components/toast` - don't render a `Toaster` per view.
  * @bestPractice Press F6 to move focus into the toasts; hovering or focusing the stack pauses dismissal and fans it open.
+ * @keywords notification, snackbar, flash message
  * @category feedback
  */
 export declare const Toaster: ({ position, duration, limit, className, }: ToasterProps) => React.JSX.Element;

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

@@ -101,6 +101,7 @@ const ToastList = ({ edge }) => {
  * @bestPractice Use toasts for transient, auto-dismissing notifications; a persistent inline message is an `Alert`.
  * @bestPractice Mount `<Toaster />` exactly once near the app root, then fire toasts with `toast()` from `@instruments/materia-ui/components/toast` - don't render a `Toaster` per view.
  * @bestPractice Press F6 to move focus into the toasts; hovering or focusing the stack pauses dismissal and fans it open.
+ * @keywords notification, snackbar, flash message
  * @category feedback
  */
 export const Toaster = ({ position = "bottom-center", duration = 4000, limit = 3, className, }) => {

package/dist/components/tooltip/tooltip-root.d.ts

@@ -28,6 +28,7 @@ declare const TooltipProvider: ({ delay, ...props }: TooltipPrimitive.Provider.P
  * @bestPractice Keep `TooltipContent` a short, non-interactive label - no buttons or links inside; for rich or actionable hover content use `HoverCard`.
  * @bestPractice The trigger must be focusable (a button / link, or `render` onto one) or keyboard and AT users never see the tip.
  * @bestPractice Share one `TooltipProvider` to tune `delay` / skip-delay for a group; `Tooltip` wraps its own provider, so you only need it for grouping.
+ * @keywords hint, title
  * @category overlays
  */
 declare const Tooltip: <Payload>({ delay, ...props }: TooltipPrimitive.Root.Props<Payload> & {

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

@@ -32,6 +32,7 @@ const TooltipProvider = ({ delay = 0, ...props }) => (_jsx(TooltipPrimitive.Prov
  * @bestPractice Keep `TooltipContent` a short, non-interactive label - no buttons or links inside; for rich or actionable hover content use `HoverCard`.
  * @bestPractice The trigger must be focusable (a button / link, or `render` onto one) or keyboard and AT users never see the tip.
  * @bestPractice Share one `TooltipProvider` to tune `delay` / skip-delay for a group; `Tooltip` wraps its own provider, so you only need it for grouping.
+ * @keywords hint, title
  * @category overlays
  */
 const Tooltip = ({ delay, ...props }) => (_jsx(TooltipProvider, { ...(delay === undefined ? {} : { delay }), children: _jsx(TooltipPrimitive.Root, { "data-component": "tooltip", "data-slot": "tooltip", ...props }) }));

package/dist/compositions/empty-state/empty-state-root.d.ts

@@ -41,6 +41,7 @@ export interface EmptyStateProps extends Omit<EmptyProps, "children" | "title">
  *
  * @bestPractice Use `EmptyState` for "no data / nothing here"; a failure the user can retry is an `ErrorState` (which also composes `Empty`), so don't hand-roll a retry empty.
  * @bestPractice Set `level` to keep the document outline gapless where you place it - a full-page empty near an `h2` wants `level="3"`, but a nested one may need `"4"`.
+ * @keywords no results, zero state, blank slate
  * @category states
  */
 export declare const EmptyState: ({ actions, description, icon, iconPlain, iconTone, level, media, title, ...emptyProps }: EmptyStateProps) => React.JSX.Element;

package/dist/compositions/empty-state/empty-state-root.js

@@ -23,6 +23,7 @@ import { EmptyTitle } from "../../components/empty/empty-title.js";
  *
  * @bestPractice Use `EmptyState` for "no data / nothing here"; a failure the user can retry is an `ErrorState` (which also composes `Empty`), so don't hand-roll a retry empty.
  * @bestPractice Set `level` to keep the document outline gapless where you place it - a full-page empty near an `h2` wants `level="3"`, but a nested one may need `"4"`.
+ * @keywords no results, zero state, blank slate
  * @category states
  */
 export const EmptyState = ({ actions, description, icon, iconPlain, iconTone, level = "3", media, title, ...emptyProps }) => {

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

@@ -46,6 +46,7 @@ interface FileUploadDropzoneProps {
  * @bestPractice `FileUploadDropzone` is presentational - wire it to the `useFileUpload` hook for the actual file input, drag state, and file list; it stores nothing itself.
  * @bestPractice Forward the hook's `handleDragEnter/Leave/Over/Drop` and drag state into `dragging` so the drag styling matches the real drop-target state.
  * @bestPractice Keep `title`/`description` (accepted types, size limit) accurate - they are the zone's only affordance copy; override the whole body via `children` when needed.
+ * @keywords dropzone, attachment, file input
  * @category inputs
  */
 export declare const FileUploadDropzone: ({ ref, dragging, disabled, icon, title, description, onDragEnter, onDragLeave, onDragOver, onDrop, onClick, className, children, }: FileUploadDropzoneProps) => import("react").JSX.Element;

package/dist/compositions/file-upload/file-upload-dropzone.js

@@ -28,6 +28,7 @@ import { Text } from "../../components/text.js";
  * @bestPractice `FileUploadDropzone` is presentational - wire it to the `useFileUpload` hook for the actual file input, drag state, and file list; it stores nothing itself.
  * @bestPractice Forward the hook's `handleDragEnter/Leave/Over/Drop` and drag state into `dragging` so the drag styling matches the real drop-target state.
  * @bestPractice Keep `title`/`description` (accepted types, size limit) accurate - they are the zone's only affordance copy; override the whole body via `children` when needed.
+ * @keywords dropzone, attachment, file input
  * @category inputs
  */
 export const FileUploadDropzone = ({ ref, dragging = false, disabled = false, icon, title = "Drop files here or click to upload", description = "PNG, JPG, GIF up to 10MB", onDragEnter, onDragLeave, onDragOver, onDrop, onClick, className, children, }) => {

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

@@ -5,7 +5,7 @@ import { cn } from "@instruments/materia-ui/utils/cn";
 import { createElement, useCallback } from "react";
 import { useProductCard } from "./product-card-context.js";
 export const ProductCardCaption = ({ scale = "default", }) => {
-    const { availability, currentVariant, linkComponent, linkPrefetch, onCardClick, product, productNameLines, productUrl, showProductBrand, showProductName, } = useProductCard();
+    const { availability, currentVariant, linkComponent, linkPrefetch, onCardClick, product, productBrandLines, productNameLines, productUrl, showProductBrand, showProductName, } = useProductCard();
     const handleLinkClick = useCallback((event) => {
         if (onCardClick) {
             event.preventDefault();
@@ -33,7 +33,9 @@ export const ProductCardCaption = ({ scale = "default", }) => {
             prefetch: isExternalUrl ? undefined : linkPrefetch,
         };
     return (_jsxs(_Fragment, { children: [showProductBrand && hasBrandName
-                ? createElement(LinkComp, linkProps, _jsx(Text, { className: cn("line-clamp-1 truncate", brandSize), weight: "semibold", children: brandName }))
+                ? createElement(LinkComp, linkProps, _jsx(Text, { className: cn(productBrandLines === 2
+                        ? "line-clamp-2 text-pretty"
+                        : "line-clamp-1 truncate", brandSize), weight: "semibold", children: brandName }))
                 : null, showProductName
                 ? createElement(LinkComp, linkProps, _jsx(Text, { className: cn("text-foreground", 
                     // `truncate` and `line-clamp-2` cannot both apply: truncate

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

@@ -16,6 +16,14 @@ interface ProductCardProcessingProps {
 interface ProductCardDisplayOptions {
     addToCart?: boolean | undefined;
     brand?: boolean | undefined;
+    /**
+     * How many lines the brand may occupy before it clamps. One by default.
+     * Raise it to two where brands run long - *Scuffmaster Wolf-Gordon* clamps
+     * to *Scuffmaster Wolf-...* on one line of a 208px card - and the brand is
+     * how people tell the cards apart. Like `nameLines`, the clamp is a maximum,
+     * not a reserved height.
+     */
+    brandLines?: 1 | 2 | undefined;
     name?: boolean | undefined;
     /**
      * How many lines the product name may occupy before it clamps. One by

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

@@ -1,8 +1,8 @@
 "use client";
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box } from "@instruments/materia-ui/components/box";
+import { MarqueeText } from "@instruments/materia-ui/components/marquee-text";
 import { HStack } from "@instruments/materia-ui/components/stack";
-import { Text } from "@instruments/materia-ui/components/text";
 import { ProductCardCategory } from "./product-card-category.js";
 import { useProductCard } from "./product-card-context.js";
 import { ProductCardCost, hasProductCardPrice } from "./product-card-cost.js";
@@ -22,5 +22,5 @@ export const ProductCardMeta = () => {
         return null;
     }
     const showCostSeparator = showCategory || showProductType;
-    return (_jsxs(HStack, { className: "text-muted-foreground text-caption w-full items-center", gap: "none", children: [showCategory ? _jsx(ProductCardCategory, {}) : null, showProductType ? (_jsx(Text, { size: "caption", variant: "muted", render: _jsx("span", { className: "min-w-0 truncate" }), children: product.productType })) : null, showCost ? (_jsxs(_Fragment, { children: [_jsx(Dot, { show: showCostSeparator }), _jsx(Box, { as: "span", className: "shrink-0", children: _jsx(ProductCardCost, {}) })] })) : null] }));
+    return (_jsxs(HStack, { className: "text-muted-foreground text-caption w-full items-center", gap: "none", children: [showCategory ? _jsx(ProductCardCategory, {}) : null, showProductType ? (_jsx(MarqueeText, { children: product.productType ?? "" })) : null, showCost ? (_jsxs(_Fragment, { children: [_jsx(Dot, { show: showCostSeparator }), _jsx(Box, { as: "span", className: "shrink-0", children: _jsx(ProductCardCost, {}) })] })) : null] }));
 };

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

@@ -72,6 +72,7 @@ interface ProductCardContextValue {
     showingInstallShot: boolean;
     toggleInstallShot: () => void;
     showAddToCart: boolean;
+    productBrandLines: 1 | 2;
     productNameLines: 1 | 2;
     showProductBrand: boolean;
     showProductName: boolean;
@@ -254,6 +255,8 @@ type ProductCardProps = ComponentProps<"div"> & Pick<ProductCardProviderProps, "
     overrideImageUrl?: string | undefined;
     /** Prioritise loading images (sets loading="eager" and adds preload link) */
     priority?: boolean | undefined;
+    /** How many lines the brand may take before it clamps; see `ProductCardDisplayOptions.brandLines`. */
+    productBrandLines?: 1 | 2 | undefined;
     productNameLines?: 1 | 2 | undefined;
     showAddToCart?: boolean | undefined;
     showProductBrand?: boolean | undefined;

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

@@ -62,6 +62,7 @@ const useVariantSelection = ({ mode, onVariantChange, product, variantId, }) =>
  * renderer exists: no renderAddToCart slot means no cart UI at all.
  */
 const resolveDisplay = (display, hasRenderAddToCart) => ({
+    productBrandLines: display?.brandLines ?? 1,
     productNameLines: display?.nameLines ?? 1,
     showAddToCart: (display?.addToCart ?? true) && hasRenderAddToCart,
     showProductBrand: display?.brand ?? true,
@@ -94,12 +95,13 @@ const useResolvedCard = ({ availability: availabilityProp, display, mode, onVari
     const availability = availabilityProp ??
         (currentVariant.available === false ? "out-of-stock" : "available");
     const productUrl = buildProductUrl(currentVariant);
-    const { productNameLines, showAddToCart, showProductBrand, showProductName, showSwatches, } = resolveDisplay(display, renderAddToCart !== undefined);
+    const { productBrandLines, productNameLines, showAddToCart, showProductBrand, showProductName, showSwatches, } = resolveDisplay(display, renderAddToCart !== undefined);
     return useMemo(() => ({
         availability,
         currentVariant,
         hasInstallShot,
         onVariantChange: handleVariantChange,
+        productBrandLines,
         productNameLines,
         productUrl,
         selectedVariantId,
@@ -114,6 +116,7 @@ const useResolvedCard = ({ availability: availabilityProp, display, mode, onVari
         currentVariant,
         handleVariantChange,
         hasInstallShot,
+        productBrandLines,
         productNameLines,
         productUrl,
         selectedVariantId,

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

@@ -1,5 +1,5 @@
 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, 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 & {
+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 & {
     onAddToCartSuccess?: (() => void) | undefined;
 }) => import("react").JSX.Element;
 /**

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

@@ -3,9 +3,10 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { memo } from "react";
 import { ProductCardContent } from "./product-card-content.js";
 import { ProductCardProvider } from "./product-card-provider.js";
-const ProductCardBase = ({ className, product, variantId, mode = "group", width, active = false, dragging, availability, labels, showActivePointer, similarityScore, overrideImageUrl, priority, showSwatches, showAddToCart, 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 }) => (_jsx(ProductCardProvider, { action: action, display: {
+const ProductCardBase = ({ className, product, variantId, mode = "group", width, active = false, 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 }) => (_jsx(ProductCardProvider, { action: action, display: {
         addToCart: showAddToCart,
         brand: showProductBrand,
+        brandLines: productBrandLines,
         name: showProductName,
         nameLines: productNameLines,
         swatches: showSwatches,

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

@@ -2,6 +2,14 @@ import type { CSSProperties } from "react";
 interface ProductCardSkeletonProps {
     className?: string;
     style?: CSSProperties;
+    /**
+     * Draw the add-to-cart control. True by default; pass the same value as the
+     * card's `showAddToCart` so a grid without a cart keeps its height when the
+     * products arrive.
+     */
+    showAddToCart?: boolean;
+    /** Draw the row of colourway dots. True by default; pass the card's `showSwatches`. */
+    showSwatches?: boolean;
 }
 /**
  * Loading placeholder for `ProductCard`, at whatever size it is given.
@@ -19,10 +27,11 @@ interface ProductCardSkeletonProps {
  * frame's bottom above it), the same padding, gaps and radius steps. Copying
  * the classes keeps it in step as the card changes.
  *
- * It draws the control unconditionally. A card whose product has no capability
- * renders none, so the placeholder overshoots that case - the reverse error, a
- * placeholder shorter than every card that does have one, misjudged the common
- * case instead.
+ * It draws the control and the swatch row by default. A card whose product has
+ * no capability renders no control, so the placeholder overshoots that case -
+ * the reverse error, a placeholder shorter than every card that does have one,
+ * misjudged the common case instead. A grid that turns either off on every
+ * card passes the same flags here.
  */
-export declare const ProductCardSkeleton: ({ className, style, }: ProductCardSkeletonProps) => import("react").JSX.Element;
+export declare const ProductCardSkeleton: ({ className, showAddToCart, showSwatches, style, }: ProductCardSkeletonProps) => import("react").JSX.Element;
 export {};

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

@@ -23,9 +23,10 @@ const SwatchRow = () => (_jsx(HStack, { className: "min-h-5 gap-2.5", children:
  * frame's bottom above it), the same padding, gaps and radius steps. Copying
  * the classes keeps it in step as the card changes.
  *
- * It draws the control unconditionally. A card whose product has no capability
- * renders none, so the placeholder overshoots that case - the reverse error, a
- * placeholder shorter than every card that does have one, misjudged the common
- * case instead.
+ * It draws the control and the swatch row by default. A card whose product has
+ * no capability renders no control, so the placeholder overshoots that case -
+ * the reverse error, a placeholder shorter than every card that does have one,
+ * misjudged the common case instead. A grid that turns either off on every
+ * card passes the same flags here.
  */
-export const ProductCardSkeleton = ({ className, style, }) => (_jsxs(Box, { className: cn("@container/product-card w-full", className), style: style, children: [_jsxs(VStack, { className: "flex @[180px]/product-card:hidden", gap: "none", children: [_jsx(Skeleton, { className: "aspect-square w-full rounded-3xl" }), _jsxs(VStack, { className: "gap-2.5 px-1.5 py-2", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { className: "gap-0.5", gap: "none", children: [_jsx(Skeleton, { className: "h-5 w-3/5" }), _jsx(Skeleton, { className: "h-4 w-4/5" })] }), _jsx(Skeleton, { className: "h-4 w-2/3" }), _jsx(SwatchRow, {})] }), _jsx(Skeleton, { className: "h-9 w-full rounded-full" })] })] }), _jsxs(VStack, { className: "bg-card hidden overflow-hidden rounded-3xl shadow-xs @[180px]/product-card:flex @[240px]/product-card:rounded-4xl", gap: "none", children: [_jsx(Box, { className: "w-full px-4 pt-4", children: _jsx(Skeleton, { className: "aspect-square w-full rounded-2xl", variant: "light" }) }), _jsx(VStack, { className: "pt-2 pb-4", gap: "none", children: _jsxs(VStack, { className: "gap-2.5 px-4 @[240px]/product-card:gap-4", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { gap: "none", children: [_jsx(Skeleton, { className: "h-5.5 w-3/5 rounded", variant: "light" }), _jsx(Skeleton, { className: "h-5 w-4/5 rounded", variant: "light" })] }), _jsx(Skeleton, { className: "h-4 w-2/3 rounded", variant: "light" }), _jsx(Box, { className: "pt-1", children: _jsx(SwatchRow, {}) })] }), _jsx(HStack, { children: _jsx(Skeleton, { className: "h-9 w-full rounded-full @[240px]/product-card:w-32", variant: "light" }) })] }) })] })] }));
+export const ProductCardSkeleton = ({ className, showAddToCart = true, showSwatches = true, style, }) => (_jsxs(Box, { className: cn("@container/product-card w-full", className), style: style, children: [_jsxs(VStack, { className: "flex @[180px]/product-card:hidden", gap: "none", children: [_jsx(Skeleton, { className: "aspect-square w-full rounded-3xl" }), _jsxs(VStack, { className: "gap-2.5 px-1.5 py-2", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { className: "gap-0.5", gap: "none", children: [_jsx(Skeleton, { className: "h-5 w-3/5" }), _jsx(Skeleton, { className: "h-4 w-4/5" })] }), _jsx(Skeleton, { className: "h-4 w-2/3" }), showSwatches ? _jsx(SwatchRow, {}) : null] }), showAddToCart ? (_jsx(Skeleton, { className: "h-9 w-full rounded-full" })) : null] })] }), _jsxs(VStack, { className: "bg-card hidden overflow-hidden rounded-3xl shadow-xs @[180px]/product-card:flex @[240px]/product-card:rounded-4xl", gap: "none", children: [_jsx(Box, { className: "w-full px-4 pt-4", children: _jsx(Skeleton, { className: "aspect-square w-full rounded-2xl", variant: "light" }) }), _jsx(VStack, { className: "pt-2 pb-4", gap: "none", children: _jsxs(VStack, { className: "gap-2.5 px-4 @[240px]/product-card:gap-4", gap: "none", children: [_jsxs(VStack, { className: "gap-1 px-0.5", gap: "none", children: [_jsxs(VStack, { gap: "none", children: [_jsx(Skeleton, { className: "h-5.5 w-3/5 rounded", variant: "light" }), _jsx(Skeleton, { className: "h-5 w-4/5 rounded", variant: "light" })] }), _jsx(Skeleton, { className: "h-4 w-2/3 rounded", variant: "light" }), showSwatches ? (_jsx(Box, { className: "pt-1", children: _jsx(SwatchRow, {}) })) : null] }), showAddToCart ? (_jsx(HStack, { children: _jsx(Skeleton, { className: "h-9 w-full rounded-full @[240px]/product-card:w-32", variant: "light" }) })) : null] }) })] })] }));

package/dist/data/decision-trees.d.ts

@@ -10,7 +10,7 @@
  * unit's page (`/components/<slug>` or `/compositions/<slug>`).
  *
  * Every leaf slug is validated against the generated docs manifest at
- * generation time (`scripts/generate-docs-manifest.mjs`), so a component rename
+ * generation time (`scripts/generate-docs-manifest.ts`), so a component rename
  * fails the manifest freshness test until the tree is updated - the drift gate. Family `id`s
  * are validated against `COMPONENT_CATEGORIES`; a family renders on the shelf of
  * its `id`, and several families may share a shelf (three feedback families

package/dist/data/decision-trees.js

@@ -10,7 +10,7 @@
  * unit's page (`/components/<slug>` or `/compositions/<slug>`).
  *
  * Every leaf slug is validated against the generated docs manifest at
- * generation time (`scripts/generate-docs-manifest.mjs`), so a component rename
+ * generation time (`scripts/generate-docs-manifest.ts`), so a component rename
  * fails the manifest freshness test until the tree is updated - the drift gate. Family `id`s
  * are validated against `COMPONENT_CATEGORIES`; a family renders on the shelf of
  * its `id`, and several families may share a shelf (three feedback families

package/dist/data/docs-manifest.d.ts

@@ -26,6 +26,8 @@ export interface DocsComponentEntry {
     description: string;
     exports: DocsExportEntry[];
     bestPractices: string[];
+    /** Words an agent might search for that the title and description don't use, from `@keywords`. */
+    keywords: string[];
     /** Same-layer component/composition slugs this unit's implementation imports. */
     uses: string[];
     /** Same-layer component/composition slugs that import this unit. */