@instruments/materia-ui 0.4.0 → 0.4.2

package/README.md

@@ -127,10 +127,8 @@ Point your agent at the guidance from your own `AGENTS.md` or `CLAUDE.md`:
 
 ```md
 ## UI
-Build UI with @instruments/materia-ui. Before writing any UI, read
-node_modules/@instruments/materia-ui/agent-docs.md and follow its rules.
-Never invent a prop; if a component can't do what you need, say so.
-Run `materia-ui-lint --all <dirs>` on what you changed.
+
+Build UI with @instruments/materia-ui. Before writing any UI, read node_modules/@instruments/materia-ui/agent-docs.md and follow its rules. Never invent a prop; if a component can't do what you need, say so. Run `materia-ui-lint --all <dirs>` on what you changed.
 ```
 
 ## Build an app

package/agent-docs.md

@@ -1,6 +1,6 @@
 # @instruments/materia-ui - agent guidance
 
-<!-- GENERATED by scripts/generate-agent-docs.mjs - DO NOT EDIT.
+<!-- GENERATED by scripts/generate-agent-docs.ts - DO NOT EDIT.
      Author `@bestPractice` JSDoc tags on public exports; regenerate with
      `pnpm generate:agent-docs`. -->
 
@@ -133,7 +133,7 @@ Honours `prefers-reduced-motion` (renders nothing - a static ring would be loude
 
 `@instruments/materia-ui/components/box`
 
-The escape hatch: a raw host element with a `className`, still checked for tokens-only classes. Box renders the chosen {@link LayoutElement} with no layout opinions of its own (no margin, width, or padding, unlike Container), so it suits decorative wrappers that a styled primitive would visually break. Reach for it only when no styled primitive fits; the `className` you pass is governed by the same tokens-only scan as everything else. RSC-safe.
+The escape hatch: a raw host element with a `className`, still checked for tokens-only classes. Box renders the chosen `LayoutElement` with no layout opinions of its own (no margin, width, or padding, unlike Container), so it suits decorative wrappers that a styled primitive would visually break. Reach for it only when no styled primitive fits; the `className` you pass is governed by the same tokens-only scan as everything else. RSC-safe.
 
 - `Box` renders the chosen element with no layout opinions (no margin/width/padding, unlike `Container`); use it as a neutral wrapper when a styled primitive would interfere.
 - Use `as="span"` for a decorative inline wrapper; reach for `Box` only when no styled primitive fits - its `className` is still checked for tokens-only classes.
@@ -1514,7 +1514,7 @@ A generic section header: an optional eyebrow label, a `Heading` title, an optio
 
 A single-select, always-one-selected control that switches between a small set of visible options - a view or mode switcher rendered as a pill of segments. Built on Base UI ToggleGroup (single-select) but kept permanently selected: re-clicking the active segment never clears it.
 
-Compose it from {@link SegmentedControlItem}s; shared `size` / `fullWidth` / active state flow to them through context. Controlled via `value`, or uncontrolled via `defaultValue`. Items scroll horizontally with a trailing fade hint when they overflow.
+Compose it from `SegmentedControlItem`s; shared `size` / `fullWidth` / active state flow to them through context. Controlled via `value`, or uncontrolled via `defaultValue`. Items scroll horizontally with a trailing fade hint when they overflow.
 
 - One value is always selected - the active segment cannot be deselected; for deselectable or multi-select sets reach for ToggleGroup.
 - Switching visible content panels is Tabs; navigating URLs is TabNavigation - SegmentedControl is an input that selects a value or mode.
@@ -1606,7 +1606,7 @@ Honours `prefers-reduced-motion` - renders nothing when motion is reduced (a sta
 
 `@instruments/materia-ui/compositions/sidebar`
 
-The sidebar shell. Reads open/collapsed state from {@link useSidebar}, so it must render inside a {@link SidebarProvider}.
+The sidebar shell. Reads open/collapsed state from `useSidebar`, so it must render inside a `SidebarProvider`.
 
 Adapts by viewport and `collapsible`: an animated docked shell on desktop, a slide-in `Sheet` on mobile, or a static column when `collapsible="none"`.
 
@@ -1641,7 +1641,7 @@ The desktop (md+) top header beside the sidebar. Fixed by default, its left offs
 
 The primary interactive row of a sidebar menu - a leading icon plus label, optional suffix icon and keyboard-shortcut hint.
 
-Collapses to icon-only when the sidebar collapses (swapping in `collapsedIcon` /`collapsedContent` and revealing the `tooltip`), unless `forceExpanded`. Reads collapsed state from {@link useSidebar}; pass `render` to render a `<Link>` or other element as the button.
+Collapses to icon-only when the sidebar collapses (swapping in `collapsedIcon` /`collapsedContent` and revealing the `tooltip`), unless `forceExpanded`. Reads collapsed state from `useSidebar`; pass `render` to render a `<Link>` or other element as the button.
 
 - In an icon-collapsible sidebar use `size="xl"`: the icon rail is sized for an `xl` row, so its collapsed square centres on the rail and the icon stays put as the sidebar folds.
 
@@ -1798,7 +1798,7 @@ Progressive streaming answer with settle-gated chrome.
 
 `@instruments/materia-ui/components/sub-navigation`
 
-Vertical secondary navigation for page subsections and settings-like layouts; the `<nav>` landmark wrapping a {@link SubNavigationList} of links.
+Vertical secondary navigation for page subsections and settings-like layouts; the `<nav>` landmark wrapping a `SubNavigationList` of links.
 
 - Reach for `SubNavigation` for a vertical in-page section/settings menu; horizontal router tabs are `TabNavigation`, the app-chrome shell is `Sidebar`.
 - Fill it with a `SubNavigationList` of links - it already renders the `<nav>` landmark, so don't nest it inside another `<nav>`.
@@ -1838,7 +1838,7 @@ Chips paint the darkening overlay on every fill and draw the double-ring selecti
 
 `@instruments/materia-ui/compositions/swatch-fan`
 
-A fanned stack of {@link Swatch} tiles: a fixed three-card editorial fan or an interactive N-tile splay.
+A fanned stack of `Swatch` tiles: a fixed three-card editorial fan or an interactive N-tile splay.
 
 Pass 3 `items` with `interaction="breathe"` for the editorial fan (Figma geometry, `variant` spread/stack, white 3px mount via `bordered`); pass N `items` with `interaction="hover-fan"` for the interactive splay-on-hover with pointer tilt. `bordered={false}` swaps the white mount for the 1px hairline tile.
 
@@ -1862,7 +1862,7 @@ Row of selectable circular color/image swatches with single-select behaviour, bu
 
 Row of selectable color/image swatches with controlled single selection, built on Base UI ToggleGroup: the row is one tab stop and the arrow keys move between swatches.
 
-Shares the selected `value`, `onValueChange`, and `size` with its {@link SwatchSelectorItem} children through context.
+Shares the selected `value`, `onValueChange`, and `size` with its `SwatchSelectorItem` children through context.
 
 - Pair `SwatchSelector` with `SwatchSelectorItem` children - it shares `value`/`onValueChange`/`size` through context, so items need no individual wiring.
 - Prefer `SwatchGroup` when the row is a single-choice form control needing radio roles and form submission; `SwatchSelector` is a row of pressed-state toggle buttons.
@@ -2030,7 +2030,7 @@ Inside a `ToggleGroup` it is the group's item, as in Base UI: give it a `value`,
 
 `@instruments/materia-ui/components/toggle-group`
 
-A literal group of {@link Toggle}s: several two-state pressable buttons that share one selection, laid out `joined` (a seamless segmented row), `separated`, or `wrap`ped. Built on Base UI ToggleGroup - by default one item is pressed at a time (radio-like), `multiple` makes it checkbox-like; `value` is always an array. The `Toggle`s inside take `size` / `radius` / `variant` from the group through context.
+A literal group of `Toggle`s: several two-state pressable buttons that share one selection, laid out `joined` (a seamless segmented row), `separated`, or `wrap`ped. Built on Base UI ToggleGroup - by default one item is pressed at a time (radio-like), `multiple` makes it checkbox-like; `value` is always an array. The `Toggle`s inside take `size` / `radius` / `variant` from the group through context.
 
 - An always-one-selected mode switcher is `SegmentedControl`, not `ToggleGroup` - reach here for multi-select toolbars and deselectable choice chips.
 - `layout="wrap"` + `required` (without `multiple`) is the wizard choice-chip recipe.

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

@@ -10,6 +10,7 @@ import { accordionRootVariants } from "../accordion/accordion-variants.js";
  * @bestPractice Leave `multiple` off for one-at-a-time panels or set it to allow several open at once; `value`/`defaultValue` are arrays either way, and an open item can always be closed again.
  * @bestPractice Reach for `Collapsible` instead when there is a single expandable region - `Accordion` is for a set of grouped items keyed by `value`.
  * @bestPractice Children must be `AccordionItem`s (each with `AccordionTrigger`/`AccordionContent`); the item's `value` is what `value`/`defaultValue` match against.
+ * @keywords disclosure, faq, expander
  * @category data
  */
 declare const AccordionRoot: <Value = string>({ className, variant, indicator, children, ...rest }: Omit<AccordionPrimitive.Root.Props<Value>, "className"> & VariantProps<typeof accordionRootVariants> & {

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

@@ -14,6 +14,7 @@ import { accordionRootVariants } from "../accordion/accordion-variants.js";
  * @bestPractice Leave `multiple` off for one-at-a-time panels or set it to allow several open at once; `value`/`defaultValue` are arrays either way, and an open item can always be closed again.
  * @bestPractice Reach for `Collapsible` instead when there is a single expandable region - `Accordion` is for a set of grouped items keyed by `value`.
  * @bestPractice Children must be `AccordionItem`s (each with `AccordionTrigger`/`AccordionContent`); the item's `value` is what `value`/`defaultValue` match against.
+ * @keywords disclosure, faq, expander
  * @category data
  */
 const AccordionRoot = ({ className, variant = "default", indicator = "arrow", children, ...rest }) => {

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

@@ -15,6 +15,7 @@ declare const alertVariants: (props?: ({
  * @bestPractice Use `Alert` for a persistent inline message block; a transient, auto-dismissing notification is a toast (`Toaster` and `toast()` from `components/toast`).
  * @bestPractice Compose `AlertTitle` / `AlertDescription` as children and render a direct-child `<svg>` for the auto-detected icon column; `tone="danger"` recolours for errors.
  * @bestPractice It renders `role="alert"`, so AT announces it on mount - keep it a notice, not a container for heavy interactive UI.
+ * @keywords callout, notice, banner, message
  * @category feedback
  */
 declare const Alert: ({ className, tone, ...props }: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) => React.JSX.Element;

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

@@ -25,6 +25,7 @@ const alertVariants = cva("text-paragraph-sm relative grid w-full grid-cols-[0_1
  * @bestPractice Use `Alert` for a persistent inline message block; a transient, auto-dismissing notification is a toast (`Toaster` and `toast()` from `components/toast`).
  * @bestPractice Compose `AlertTitle` / `AlertDescription` as children and render a direct-child `<svg>` for the auto-detected icon column; `tone="danger"` recolours for errors.
  * @bestPractice It renders `role="alert"`, so AT announces it on mount - keep it a notice, not a container for heavy interactive UI.
+ * @keywords callout, notice, banner, message
  * @category feedback
  */
 const Alert = ({ className, tone, ...props }) => (_jsx("div", { className: cn(alertVariants({ tone }), className), "data-component": "alert", "data-slot": "alert", role: "alert", ...props }));

package/dist/components/alert-dialog/alert-dialog-root.d.ts

@@ -9,6 +9,7 @@ import type * as React from "react";
  * @bestPractice Use `AlertDialog` only for a confirm / warn / destructive decision (Cancel + Action); a general modal form or details view is a `Dialog`.
  * @bestPractice Route every destructive confirmation here, never a plain `Dialog` - unlike `Dialog` it won't dismiss on outside-click / Esc, so the choice stays deliberate.
  * @bestPractice Give the destructive `AlertDialogAction` `tone="danger"` and keep the safe escape as `AlertDialogCancel`.
+ * @keywords confirm, confirmation, modal
  * @category overlays
  */
 declare const AlertDialog: ({ ...props }: React.ComponentProps<typeof AlertDialogPrimitive.Root>) => React.JSX.Element;

package/dist/components/alert-dialog/alert-dialog-root.js

@@ -10,6 +10,7 @@ import { AlertDialog as AlertDialogPrimitive } from "@base-ui/react/alert-dialog
  * @bestPractice Use `AlertDialog` only for a confirm / warn / destructive decision (Cancel + Action); a general modal form or details view is a `Dialog`.
  * @bestPractice Route every destructive confirmation here, never a plain `Dialog` - unlike `Dialog` it won't dismiss on outside-click / Esc, so the choice stays deliberate.
  * @bestPractice Give the destructive `AlertDialogAction` `tone="danger"` and keep the safe escape as `AlertDialogCancel`.
+ * @keywords confirm, confirmation, modal
  * @category overlays
  */
 const AlertDialog = ({ ...props }) => (_jsx(AlertDialogPrimitive.Root, { "data-component": "alert-dialog", "data-slot": "alert-dialog", ...props }));

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

@@ -34,6 +34,7 @@ export type AvatarRootProps = AvatarPrimitive.Root.Props & {
  * @bestPractice Always render an `AvatarFallback` child - it is what shows while the image loads and when `src` is missing or errors; an image-only avatar renders empty on failure.
  * @bestPractice Give `AvatarImage` a meaningful `alt`; the visual is decorative only when the fallback initials already convey the identity.
  * @bestPractice Keep the default `radius="full"` for people; use a squared `radius` for brand/entity logos so they read as objects, not users.
+ * @keywords profile picture, user, initials
  * @category data
  */
 export declare const AvatarRoot: ({ className, size: sizeProp, radius, withRing, ringColor, ...props }: AvatarRootProps) => import("react").JSX.Element;

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

@@ -46,6 +46,7 @@ const RADIUS_CLASS = {
  * @bestPractice Always render an `AvatarFallback` child - it is what shows while the image loads and when `src` is missing or errors; an image-only avatar renders empty on failure.
  * @bestPractice Give `AvatarImage` a meaningful `alt`; the visual is decorative only when the fallback initials already convey the identity.
  * @bestPractice Keep the default `radius="full"` for people; use a squared `radius` for brand/entity logos so they read as objects, not users.
+ * @keywords profile picture, user, initials
  * @category data
  */
 export const AvatarRoot = ({ className, size: sizeProp = "base", radius = "full", withRing = false, ringColor, ...props }) => {

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

@@ -65,6 +65,7 @@ export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement>, Omit<V
  * @bestPractice For a notification count use `mode="count"` (circular, tabular figures), not `radius="full"` + manual classes.
  * @bestPractice A standalone count needs an `accessibleLabel` ("3 unread"); inside an icon-only trigger, mark the badge `aria-hidden` and fold the count into the trigger's `aria-label`.
  * @bestPractice A badge overlapping a corner of another surface takes `ring` so a 2px `background`-coloured ring separates it from what's beneath; set it only where the badge truly overlaps, and the page surface should be `background`.
+ * @keywords chip, status, label
  * @category feedback
  */
 export declare const Badge: ({ className, tone, size, emphasis, radius, asInput, render, disabled, testid, label, value, icon, iconPlacement, focused, hovered, loading, loadingLabel, mode, accessibleLabel, ring, children, ...props }: BadgeProps) => React.JSX.Element;

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

@@ -69,6 +69,7 @@ const getOptionalPillProps = ({ asInput, disabled, emphasis, tone, }) => {
  * @bestPractice For a notification count use `mode="count"` (circular, tabular figures), not `radius="full"` + manual classes.
  * @bestPractice A standalone count needs an `accessibleLabel` ("3 unread"); inside an icon-only trigger, mark the badge `aria-hidden` and fold the count into the trigger's `aria-label`.
  * @bestPractice A badge overlapping a corner of another surface takes `ring` so a 2px `background`-coloured ring separates it from what's beneath; set it only where the badge truly overlaps, and the page surface should be `background`.
+ * @keywords chip, status, label
  * @category feedback
  */
 export const Badge = ({ className, tone, size, emphasis, radius = "rounded", asInput, render, disabled, testid, label, value, icon, iconPlacement = "start", focused, hovered, loading = false, loadingLabel, mode = "default", accessibleLabel, ring = false, children, ...props }) => {

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

@@ -46,6 +46,7 @@ const CalendarDayButton = ({ modifiers, ...props }) => {
  * @bestPractice Set `mode` explicitly (`single` | `multiple` | `range`) - the selection value shape and `onSelect` signature change with it; a `range` handler never fires in `single` mode.
  * @bestPractice Restrict selectable dates with react-day-picker matchers (`disabled`/`hidden`/`startMonth`/`endMonth`), not by filtering after the user clicks.
  * @bestPractice Use `Calendar` for an inline date grid; for a compact click-to-open date field, wrap it in a `Popover` behind a `Button`/`Input` trigger.
+ * @keywords date picker, datepicker, date
  * @category forms
  */
 const Calendar = ({ className, classNames, showOutsideDays = true, ...props }) => (_jsx(DayPicker, { className: cn("w-fit p-3", className), classNames: {

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

@@ -50,6 +50,7 @@ interface CarouselProps {
  * @bestPractice Set `slidesToShow` to show multiple items at once (it drives each item's `flex-basis`); don't fake a multi-item view with CSS widths on `CarouselItem`.
  * @bestPractice Tune scroll behaviour via `opts` (Embla options like `loop`/`align`) and enable `wheelScroll`/`freeScroll` deliberately - free-scroll drops snap points, so pass `slideCount` if the dots miscount.
  * @bestPractice Give a descriptive `aria-label` when the region isn't self-evidently "Carousel" (e.g. `"Product images"`).
+ * @keywords slideshow, gallery, swiper
  * @category data
  */
 declare const Carousel: ({ "aria-label": ariaLabel, opts, plugins, orientation, slidesToShow, slideCount, freeScroll, wheelScroll, className, children, }: CarouselProps) => import("react").JSX.Element;

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

@@ -29,6 +29,7 @@ const useCarousel = () => {
  * @bestPractice Set `slidesToShow` to show multiple items at once (it drives each item's `flex-basis`); don't fake a multi-item view with CSS widths on `CarouselItem`.
  * @bestPractice Tune scroll behaviour via `opts` (Embla options like `loop`/`align`) and enable `wheelScroll`/`freeScroll` deliberately - free-scroll drops snap points, so pass `slideCount` if the dots miscount.
  * @bestPractice Give a descriptive `aria-label` when the region isn't self-evidently "Carousel" (e.g. `"Product images"`).
+ * @keywords slideshow, gallery, swiper
  * @category data
  */
 const Carousel = ({ "aria-label": ariaLabel = "Carousel", opts, plugins, orientation = "horizontal", slidesToShow = 1, slideCount, freeScroll = false, wheelScroll = false, className, children, }) => {

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

@@ -12,6 +12,7 @@ import type { ChartConfig } from "./chart-context.js";
  *
  * @bestPractice Colour every series through `config` (`{ desktop: { label, color } }`) and reference `var(--color-<key>)` on the marks - never hardcode a hex on a `Bar` / `Line`; that keeps light/dark theming and the legend/tooltip swatches in sync.
  * @bestPractice Reach for `Chart` only to render a recharts data visualization; for a static value + delta use `Stat`, and for a progress bar use `Progress`.
+ * @keywords graph, plot, visualisation, visualization
  * @category data
  */
 export declare const Chart: ({ id, className, children, config, initialDimension, ...props }: React.ComponentProps<"div"> & {

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

@@ -19,6 +19,7 @@ const INITIAL_DIMENSION = { width: 320, height: 200 };
  *
  * @bestPractice Colour every series through `config` (`{ desktop: { label, color } }`) and reference `var(--color-<key>)` on the marks - never hardcode a hex on a `Bar` / `Line`; that keeps light/dark theming and the legend/tooltip swatches in sync.
  * @bestPractice Reach for `Chart` only to render a recharts data visualization; for a static value + delta use `Stat`, and for a progress bar use `Progress`.
+ * @keywords graph, plot, visualisation, visualization
  * @category data
  */
 export const Chart = ({ id, className, children, config, initialDimension = INITIAL_DIMENSION, ...props }) => {

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

@@ -6,6 +6,7 @@ import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible"
  * @bestPractice Use `Collapsible` for a single expand/collapse region; reach for `Accordion` when you have a set of grouped items where selecting one can close the others.
  * @bestPractice Compose `CollapsibleTrigger` + `CollapsibleContent` inside it - a bare child won't expand.
  * @bestPractice Drive it uncontrolled with `defaultOpen`; only lift to `open`/`onOpenChange` when external state must sync (e.g. persisting the open panel).
+ * @keywords disclosure, show more, expander
  * @category data
  */
 export declare const Collapsible: ({ ...props }: CollapsiblePrimitive.Root.Props) => import("react").JSX.Element;

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

@@ -8,6 +8,7 @@ import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible"
  * @bestPractice Use `Collapsible` for a single expand/collapse region; reach for `Accordion` when you have a set of grouped items where selecting one can close the others.
  * @bestPractice Compose `CollapsibleTrigger` + `CollapsibleContent` inside it - a bare child won't expand.
  * @bestPractice Drive it uncontrolled with `defaultOpen`; only lift to `open`/`onOpenChange` when external state must sync (e.g. persisting the open panel).
+ * @keywords disclosure, show more, expander
  * @category data
  */
 export const Collapsible = ({ ...props }) => (_jsx(CollapsiblePrimitive.Root, { "data-component": "collapsible", "data-slot": "collapsible", ...props }));

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

@@ -48,6 +48,7 @@ export interface ComboboxProps {
  * @bestPractice `onValueChange` fires with `""` when the current selection is toggled off - treat empty string as "cleared", not as a real value.
  * @bestPractice For lists in the hundreds+, pass `virtualization={{ enabled: true }}` so only visible rows mount instead of every option.
  * @bestPractice Provide `items` as `{ label, value }[]` - the visible text comes from `label` while selection is tracked by `value`.
+ * @keywords autocomplete, typeahead, searchable select
  * @category forms
  */
 export declare const Combobox: ({ items, value, onValueChange, placeholder, buttonClassName, contentClassName, disabled, size, virtualization, "data-testid": dataTestId, }: ComboboxProps) => React.JSX.Element;

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

@@ -80,6 +80,7 @@ const scrollHighlightIntoView = (virtualizer, item, { reason, index }) => {
  * @bestPractice `onValueChange` fires with `""` when the current selection is toggled off - treat empty string as "cleared", not as a real value.
  * @bestPractice For lists in the hundreds+, pass `virtualization={{ enabled: true }}` so only visible rows mount instead of every option.
  * @bestPractice Provide `items` as `{ label, value }[]` - the visible text comes from `label` while selection is tracked by `value`.
+ * @keywords autocomplete, typeahead, searchable select
  * @category forms
  */
 export const Combobox = ({ items, value, onValueChange, placeholder = "Select…", buttonClassName, contentClassName, disabled, size = "xl", virtualization, "data-testid": dataTestId, }) => {

package/dist/components/command/command-dialog.d.ts

@@ -10,7 +10,11 @@ export type CommandDialogProps<Item> = Omit<React.ComponentProps<typeof Dialog>,
     description?: string;
     /** Extra class names applied to the `DialogContent` wrapper. */
     className?: string;
-    /** Whether to show the dialog close button. */
+    /**
+     * Whether to show the dialog close button. Off by default: the button sits
+     * over the search field, and Escape or a click outside closes the palette.
+     * @default false
+     */
     showCloseButton?: boolean;
     /** Extra props applied to the rendered dialog content element. */
     contentProps?: Omit<React.ComponentProps<typeof DialogContent>, "children"> & React.HTMLAttributes<HTMLDivElement> & {

package/dist/components/command/command-dialog.js

@@ -14,7 +14,7 @@ import { Command } from "../command/command-root.js";
  * @bestPractice Pass `filter={null}` to list the entries unfiltered, for example when the application filters them itself.
  */
 export const CommandDialog = (props) => {
-    const { title = "Command Palette", description = "Search for a command to run…", children, className, showCloseButton = true, contentProps, filter, groups: _groups, items: _items, limit, mode, ...dialogProps } = props;
+    const { title = "Command Palette", description = "Search for a command to run…", children, className, showCloseButton = false, contentProps, filter, groups: _groups, items: _items, limit, mode, ...dialogProps } = props;
     // Narrow on `props` so the palette receives exactly one of items or groups.
     const source = props.groups === undefined
         ? { items: props.items }

package/dist/components/command/command-input.js

@@ -1,7 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Autocomplete as AutocompletePrimitive } from "@base-ui/react/autocomplete";
-import { focusRing } from "@instruments/materia-ui/tokens/focus-ring";
 import { cn } from "@instruments/materia-ui/utils/cn";
 import { Search } from "lucide-react";
 import { Icon } from "../icon.js";
@@ -9,4 +8,8 @@ import { Icon } from "../icon.js";
  * CommandInput renders the search field for a Command; typing filters the list.
  * Import from "@instruments/materia-ui/components/command".
  */
-export const CommandInput = ({ className, ...props }) => (_jsxs(AutocompletePrimitive.InputGroup, { className: "flex h-9 items-center gap-2 border-b px-3", "data-component": "command-input-wrapper", "data-slot": "command-input-wrapper", children: [_jsx(Icon, { className: "shrink-0 opacity-50", icon: Search, size: "xs" }), _jsx(AutocompletePrimitive.Input, { className: cn(focusRing(), "placeholder:text-muted-foreground text-paragraph-sm flex h-10 w-full rounded-lg bg-transparent py-3 disabled:cursor-not-allowed disabled:opacity-50", "focus-visible:ring-inset", className), "data-component": "command-input", "data-slot": "command-input", ...props })] }));
+export const CommandInput = ({ className, ...props }) => (_jsxs(AutocompletePrimitive.InputGroup, { className: "flex h-9 items-center gap-2 border-b px-3", "data-component": "command-input-wrapper", "data-slot": "command-input-wrapper", children: [_jsx(Icon, { className: "shrink-0 opacity-50", icon: Search, size: "xs" }), _jsx(AutocompletePrimitive.Input, { className: cn(
+            // No ring: the field is the palette's only input and always holds
+            // focus, so the caret marks it; a ring would collide with the
+            // dialog's rounded top edge.
+            "placeholder:text-muted-foreground text-paragraph-sm flex h-full w-full bg-transparent outline-none disabled:cursor-not-allowed disabled:opacity-50", className), "data-component": "command-input", "data-slot": "command-input", ...props })] }));

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

@@ -35,6 +35,7 @@ export type CommandProps<Item> = Omit<AutocompletePrimitive.Root.Props<Item>, "c
  * @bestPractice Pass the entries as `items`, or as titled `groups`, and render them with a function child of `CommandList`; filtering only sees those entries, so items written as static JSX are not filtered.
  * @bestPractice Act on a choice with `CommandItem`'s `onClick`, which fires for a pointer click and for `Enter` on the highlighted item.
  * @bestPractice A plain click-triggered action menu is `DropdownMenu`; a remembered selection is `Combobox`.
+ * @keywords command palette, spotlight, cmd+k, quick search
  * @category navigation
  */
 export declare const Command: <Item>(props: CommandProps<Item>) => React.JSX.Element;

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

@@ -14,6 +14,7 @@ import { cn } from "@instruments/materia-ui/utils/cn";
  * @bestPractice Pass the entries as `items`, or as titled `groups`, and render them with a function child of `CommandList`; filtering only sees those entries, so items written as static JSX are not filtered.
  * @bestPractice Act on a choice with `CommandItem`'s `onClick`, which fires for a pointer click and for `Enter` on the highlighted item.
  * @bestPractice A plain click-triggered action menu is `DropdownMenu`; a remembered selection is `Combobox`.
+ * @keywords command palette, spotlight, cmd+k, quick search
  * @category navigation
  */
 export const Command = (props) => {

package/dist/components/dialog/dialog-content.d.ts

@@ -10,6 +10,8 @@ type DialogContentProps = Omit<React.ComponentProps<typeof DialogPrimitive.Popup
  * such as a product's quick view.
  */
 export type DialogContentSize = "default" | "viewport";
+/** Panel geometry per size. Exported for the Figma generator in `figma/`. */
+export declare const DIALOG_SIZE_CLASSES: Record<DialogContentSize, string | undefined>;
 export interface DialogContentExtras {
     /** Extra classes for the overlay behind the dialog. */
     overlayClassName?: string;

package/dist/components/dialog/dialog-content.js

@@ -6,7 +6,8 @@ import { OVERLAY_PANEL_ANIMATION, OVERLAY_PANEL_CENTERED, } from "../../tokens/o
 import { Button } from "../button.js";
 import { DialogOverlay } from "../dialog/dialog-overlay.js";
 import { DialogPortal } from "../dialog/dialog-portal.js";
-const SIZE_CLASSES = {
+/** Panel geometry per size. Exported for the Figma generator in `figma/`. */
+export const DIALOG_SIZE_CLASSES = {
     default: undefined,
     viewport: "h-dialog-viewport w-dialog-viewport max-w-dialog-viewport sm:max-w-dialog-viewport md:h-dialog-viewport-md md:max-h-dialog-viewport md:w-dialog-viewport-md",
 };
@@ -20,4 +21,4 @@ const SIZE_CLASSES = {
  *
  * @bestPractice Use `size="viewport"` for a dialog that holds a whole view (a product quick view, a large preview); it sets only the geometry, so lay the panel out as a column with a scrolling body yourself or compose `QuickView`.
  */
-export const DialogContent = ({ className, children, showCloseButton = true, overlayClassName, size = "default", ...props }) => (_jsxs(DialogPortal, { "data-component": "dialog-portal", "data-slot": "dialog-portal", children: [_jsx(DialogOverlay, { className: overlayClassName }), _jsxs(DialogPrimitive.Popup, { className: cn(OVERLAY_PANEL_ANIMATION, OVERLAY_PANEL_CENTERED, SIZE_CLASSES[size], className), "data-component": "dialog-content", "data-size": size, "data-slot": "dialog-content", ...props, children: [children, showCloseButton ? (_jsx(DialogPrimitive.Close, { render: _jsx(Button, { "aria-label": "Close", className: "absolute top-5 right-5", "data-component": "dialog-close", "data-slot": "dialog-close", emphasis: "soft", icon: XIcon, size: "icon-sm", tone: "neutral" }) })) : null] })] }));
+export const DialogContent = ({ className, children, showCloseButton = true, overlayClassName, size = "default", ...props }) => (_jsxs(DialogPortal, { "data-component": "dialog-portal", "data-slot": "dialog-portal", children: [_jsx(DialogOverlay, { className: overlayClassName }), _jsxs(DialogPrimitive.Popup, { className: cn(OVERLAY_PANEL_ANIMATION, OVERLAY_PANEL_CENTERED, DIALOG_SIZE_CLASSES[size], className), "data-component": "dialog-content", "data-size": size, "data-slot": "dialog-content", ...props, children: [children, showCloseButton ? (_jsx(DialogPrimitive.Close, { render: _jsx(Button, { "aria-label": "Close", className: "absolute top-5 right-5", "data-component": "dialog-close", "data-slot": "dialog-close", emphasis: "soft", icon: XIcon, size: "icon-sm", tone: "neutral" }) })) : null] })] }));

package/dist/components/dialog/dialog-footer.d.ts

@@ -3,6 +3,8 @@ interface DialogFooterProps extends React.ComponentProps<"div"> {
     /** Button alignment within the footer. @default "end" */
     justify?: "end" | "between";
 }
+/** Footer classes for a `justify`. Exported for the Figma generator in `figma/`. */
+export declare const dialogFooterClasses: (justify: NonNullable<DialogFooterProps["justify"]>) => string;
 /**
  * Action row at the bottom of the panel; stacks buttons vertically on mobile and
  * lays them out horizontally from `sm` up. Render inside `<DialogContent>`.

package/dist/components/dialog/dialog-footer.js

@@ -1,16 +1,16 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "@instruments/materia-ui/utils/cn";
 import { Flex } from "../flex.js";
+/** Footer classes for a `justify`. Exported for the Figma generator in `figma/`. */
+export const dialogFooterClasses = (justify) => cn("mt-2 flex-col-reverse gap-2 sm:flex-row", justify === "between" ? "sm:-ml-1.5 sm:justify-between" : "sm:justify-end", 
+// Concentric nesting: pull the actions 6px onto the trailing edges so a
+// default pill button (h-9, r 18px) sits 18px from the rounded-modal (36px)
+// corner - 36−18 - its curve parallel to the boundary.
+// `between` also pulls the leading edge so the left action nestles too.
+"sm:-mr-1.5 sm:-mb-1.5");
 /**
  * Action row at the bottom of the panel; stacks buttons vertically on mobile and
  * lays them out horizontally from `sm` up. Render inside `<DialogContent>`.
  * Import from "@instruments/materia-ui/components/dialog".
  */
-export const DialogFooter = ({ className, justify = "end", ...props }) => (_jsx(Flex, { className: cn("mt-2 flex-col-reverse gap-2 sm:flex-row", justify === "between"
-        ? "sm:-ml-1.5 sm:justify-between"
-        : "sm:justify-end", 
-    // Concentric nesting: pull the actions 6px onto the trailing edges so a
-    // default pill button (h-9, r 18px) sits 18px from the rounded-modal (36px)
-    // corner - 36−18 - its curve parallel to the boundary.
-    // `between` also pulls the leading edge so the left action nestles too.
-    "sm:-mr-1.5 sm:-mb-1.5", className), "data-component": "dialog-footer", "data-slot": "dialog-footer", ...props }));
+export const DialogFooter = ({ className, justify = "end", ...props }) => (_jsx(Flex, { className: cn(dialogFooterClasses(justify), className), "data-component": "dialog-footer", "data-slot": "dialog-footer", ...props }));

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

@@ -6,6 +6,7 @@ import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
  * @bestPractice Use `Dialog` for a centred blocking modal (form, details, footer actions); a destructive confirm is `AlertDialog`, an anchored non-blocking panel is `Popover`.
  * @bestPractice A panel that slides in from a screen edge is a `Sheet` (or `Drawer` for a drag-to-dismiss bottom sheet), not a `Dialog`.
  * @bestPractice Always render a `DialogTitle` (wrap in `sr-only` if visually hidden) so the modal is announced; `DialogContent` uses the 36px `--radius-modal` corner.
+ * @keywords modal, popup, lightbox
  * @category overlays
  */
 export declare const Dialog: (props: DialogPrimitive.Root.Props<unknown>) => import("react").ReactElement;

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

@@ -7,6 +7,7 @@ import { makeOverlayRoot } from "../overlay-primitives.js";
  * @bestPractice Use `Dialog` for a centred blocking modal (form, details, footer actions); a destructive confirm is `AlertDialog`, an anchored non-blocking panel is `Popover`.
  * @bestPractice A panel that slides in from a screen edge is a `Sheet` (or `Drawer` for a drag-to-dismiss bottom sheet), not a `Dialog`.
  * @bestPractice Always render a `DialogTitle` (wrap in `sr-only` if visually hidden) so the modal is announced; `DialogContent` uses the 36px `--radius-modal` corner.
+ * @keywords modal, popup, lightbox
  * @category overlays
  */
 export const Dialog = makeOverlayRoot(DialogPrimitive.Root, {

package/dist/components/dialog/dialog-title.d.ts

@@ -1,5 +1,7 @@
 import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
 import type * as React from "react";
+/** Title classes. Exported for the Figma generator in `figma/`. */
+export declare const DIALOG_TITLE_CLASSES = "text-subheading font-semibold text-balance";
 /**
  * Accessible heading that labels the dialog (wired to the panel's
  * `aria-labelledby`). Render inside `<DialogHeader>`.

package/dist/components/dialog/dialog-title.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
 import { cn } from "@instruments/materia-ui/utils/cn";
+/** Title classes. Exported for the Figma generator in `figma/`. */
+export const DIALOG_TITLE_CLASSES = "text-subheading font-semibold text-balance";
 /**
  * Accessible heading that labels the dialog (wired to the panel's
  * `aria-labelledby`). Render inside `<DialogHeader>`.
  * Import from "@instruments/materia-ui/components/dialog".
  */
-export const DialogTitle = ({ className, ...props }) => (_jsx(DialogPrimitive.Title, { className: cn("text-subheading font-semibold text-balance", className), "data-component": "dialog-title", "data-slot": "dialog-title", ...props }));
+export const DialogTitle = ({ className, ...props }) => (_jsx(DialogPrimitive.Title, { className: cn(DIALOG_TITLE_CLASSES, className), "data-component": "dialog-title", "data-slot": "dialog-title", ...props }));

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

@@ -16,6 +16,7 @@ export declare const DrawerContext: import("react").Context<DrawerContextValue>;
  * @bestPractice Drawer is the touch-first slide-up panel - reach for `Sheet` for desktop side panels and `Dialog` for centred modals.
  * @bestPractice Always render a `DrawerTitle` inside `DrawerContent` (sr-only if visually hidden) - the underlying primitive uses it for `aria-labelledby`.
  * @bestPractice Pass `container` to scope the drawer and its scrim to a bounded element instead of the viewport (the mobile-nav overlay pattern).
+ * @keywords bottom sheet
  * @category overlays
  */
 export declare const Drawer: ({ container, ...props }: ComponentProps<typeof DrawerPrimitive.Root> & {

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

@@ -15,6 +15,7 @@ export const DrawerContext = createContext({});
  * @bestPractice Drawer is the touch-first slide-up panel - reach for `Sheet` for desktop side panels and `Dialog` for centred modals.
  * @bestPractice Always render a `DrawerTitle` inside `DrawerContent` (sr-only if visually hidden) - the underlying primitive uses it for `aria-labelledby`.
  * @bestPractice Pass `container` to scope the drawer and its scrim to a bounded element instead of the viewport (the mobile-nav overlay pattern).
+ * @keywords bottom sheet
  * @category overlays
  */
 export const Drawer = ({ container, ...props }) => {

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

@@ -30,6 +30,7 @@ type HeadingProps = Omit<React.ComponentProps<"h1">, "size"> & {
  *
  * @bestPractice Set `level` (`h1`–`h6`) for the document outline and `size` for visual scale independently - don't pick a tag just to get a size; a small-looking heading can still be an `h2`.
  * @bestPractice Keep one `h1` per page and don't skip levels for styling; use `size` (responsive-capable) to make a lower-level heading look larger.
+ * @keywords title, headline
  * @category typography
  */
 declare const Heading: ({ level, size, className, ...props }: HeadingProps) => React.JSX.Element;

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

@@ -41,6 +41,7 @@ const SIZE_CLASSES = {
  *
  * @bestPractice Set `level` (`h1`–`h6`) for the document outline and `size` for visual scale independently - don't pick a tag just to get a size; a small-looking heading can still be an `h2`.
  * @bestPractice Keep one `h1` per page and don't skip levels for styling; use `size` (responsive-capable) to make a lower-level heading look larger.
+ * @keywords title, headline
  * @category typography
  */
 const Heading = ({ level = "2", size, className, ...props }) => {

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

@@ -32,6 +32,7 @@ export type InputProps = WithTestId<Omit<React.ComponentProps<"input">, "size">>
  * @bestPractice Inside a `Field`, let invalid state cascade - omit `hasError`; pass `hasError` only to force error styling on a standalone `Input`. An invalid `Field` keeps `aria-invalid` on its control even with `hasError={false}`.
  * @bestPractice Give every `Input` an associated 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.
  * @bestPractice `size` defaults to `"xl"` (48px); pass a responsive object like `{ base: "sm", md: "xl" }` rather than swapping components per breakpoint.
+ * @keywords text field, textbox, text input
  * @category forms
  */
 export declare const Input: ({ className, testId, size, radius, hasError, focused, ...props }: InputProps) => React.JSX.Element;

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

@@ -25,6 +25,7 @@ import { DEFAULT_INPUT_SIZE, INPUT_SIZE_CLASSES, standaloneInputVariants, } from
  * @bestPractice Inside a `Field`, let invalid state cascade - omit `hasError`; pass `hasError` only to force error styling on a standalone `Input`. An invalid `Field` keeps `aria-invalid` on its control even with `hasError={false}`.
  * @bestPractice Give every `Input` an associated 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.
  * @bestPractice `size` defaults to `"xl"` (48px); pass a responsive object like `{ base: "sm", md: "xl" }` rather than swapping components per breakpoint.
+ * @keywords text field, textbox, text input
  * @category forms
  */
 export const Input = ({ className, testId, size, radius, hasError, focused, ...props }) => {

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

@@ -65,6 +65,7 @@ type KbdProps = Omit<React.ComponentProps<"kbd">, "size"> & VariantProps<typeof
  *
  * @bestPractice Wrap multi-key chords in `KbdGroup` and set `size` on the group - children inherit it via context, so you size the combo once.
  * @bestPractice It renders a semantic `<kbd>`; reserve it for keyboard keys/shortcuts, not as a generic small-label chip (that's `Badge`).
+ * @keywords keyboard shortcut, hotkey
  * @category typography
  */
 declare const Kbd: ({ className, size, tone, emphasis, ...props }: KbdProps) => import("react").JSX.Element;

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

@@ -124,6 +124,7 @@ const kbdVariants = cva("pointer-events-none inline-flex w-fit items-center just
  *
  * @bestPractice Wrap multi-key chords in `KbdGroup` and set `size` on the group - children inherit it via context, so you size the combo once.
  * @bestPractice It renders a semantic `<kbd>`; reserve it for keyboard keys/shortcuts, not as a generic small-label chip (that's `Badge`).
+ * @keywords keyboard shortcut, hotkey
  * @category typography
  */
 const Kbd = ({ className, size, tone, emphasis, ...props }) => {

package/dist/components/logo/logo-mark.d.ts

@@ -1,6 +1,6 @@
 /**
  * The Material Bank mark's geometry, in one place: `Logo` draws it and
- * `scripts/generate-brand-assets.mjs` writes the shipped SVG files from it.
+ * `scripts/generate-brand-assets.ts` writes the shipped SVG files from it.
  * Plain constants with no imports, so a Node script can load this file
  * directly.
  */

package/dist/components/logo/logo-mark.js

@@ -1,6 +1,6 @@
 /**
  * The Material Bank mark's geometry, in one place: `Logo` draws it and
- * `scripts/generate-brand-assets.mjs` writes the shipped SVG files from it.
+ * `scripts/generate-brand-assets.ts` writes the shipped SVG files from it.
  * Plain constants with no imports, so a Node script can load this file
  * directly.
  */

package/dist/components/logotype/logotype-paths.d.ts

@@ -1,6 +1,6 @@
 /**
  * The Material Bank logotype geometry, in one place: the `Logotype` component
- * draws it and `scripts/generate-brand-assets.mjs` writes the shipped SVG files
+ * draws it and `scripts/generate-brand-assets.ts` writes the shipped SVG files
  * from it. Plain constants with no imports, so a Node script can load this file
  * directly.
  *

package/dist/components/logotype/logotype-paths.js

@@ -1,6 +1,6 @@
 /**
  * The Material Bank logotype geometry, in one place: the `Logotype` component
- * draws it and `scripts/generate-brand-assets.mjs` writes the shipped SVG files
+ * draws it and `scripts/generate-brand-assets.ts` writes the shipped SVG files
  * from it. Plain constants with no imports, so a Node script can load this file
  * directly.
  *

package/dist/components/month-year-picker/month-year-picker-root.d.ts

@@ -41,6 +41,7 @@ export interface MonthYearPickerProps {
  * @bestPractice `value` is a union - a `Date`, `"beyond"`, or `"unsure"` - so branch on the string sentinels in `onChange` before treating it as a date.
  * @bestPractice Enable the "I'm not sure" escape hatch with `showUnsure` (off by default); `"unsure"`/`"beyond"` only ever arrive when their toggles are shown.
  * @bestPractice Bound the range with `yearsAhead` (from the current year); it auto-advances and commits once both month and year are chosen, so don't add your own "next" control.
+ * @keywords date picker, date, month, year
  * @category forms
  */
 export declare const MonthYearPicker: ({ value, onChange, yearsAhead, beyondLabel, showUnsure, unsureLabel, size, variant, monthLabel, yearLabel, className, }: MonthYearPickerProps) => import("react").JSX.Element;

package/dist/components/month-year-picker/month-year-picker-root.js

@@ -60,6 +60,7 @@ const SpecialOptions = ({ isBeyond, isUnsure, onBeyondSelect, onUnsureSelect, re
  * @bestPractice `value` is a union - a `Date`, `"beyond"`, or `"unsure"` - so branch on the string sentinels in `onChange` before treating it as a date.
  * @bestPractice Enable the "I'm not sure" escape hatch with `showUnsure` (off by default); `"unsure"`/`"beyond"` only ever arrive when their toggles are shown.
  * @bestPractice Bound the range with `yearsAhead` (from the current year); it auto-advances and commits once both month and year are chosen, so don't add your own "next" control.
+ * @keywords date picker, date, month, year
  * @category forms
  */
 export const MonthYearPicker = ({ value, onChange, yearsAhead = 10, beyondLabel, showUnsure = false, unsureLabel = "I'm not sure", size = "lg", variant = "default", monthLabel = "Choose month", yearLabel = "Choose year", className, }) => {