@instruments/materia-ui 0.4.0 → 0.4.2

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

@@ -7,6 +7,7 @@ import type * as React from "react";
  * @bestPractice `NativeSelect` wraps a real `<select>` - use standard `value`/`defaultValue`/`onChange` and `NativeSelectOption`/`NativeSelectOptGroup` children, not `Select` parts.
  * @bestPractice Reach for `NativeSelect` when the native mobile picker and zero-JS behaviour matter; use `Select` when you need custom-rendered option content or styling.
  * @bestPractice It has no built-in label - associate a `Label` via `htmlFor`/`id` for an accessible name.
+ * @keywords dropdown, picker
  * @category forms
  */
 declare const NativeSelect: ({ className, ...props }: React.ComponentProps<"select">) => React.JSX.Element;

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

@@ -13,6 +13,7 @@ import { Icon } from "../icon.js";
  * @bestPractice `NativeSelect` wraps a real `<select>` - use standard `value`/`defaultValue`/`onChange` and `NativeSelectOption`/`NativeSelectOptGroup` children, not `Select` parts.
  * @bestPractice Reach for `NativeSelect` when the native mobile picker and zero-JS behaviour matter; use `Select` when you need custom-rendered option content or styling.
  * @bestPractice It has no built-in label - associate a `Label` via `htmlFor`/`id` for an accessible name.
+ * @keywords dropdown, picker
  * @category forms
  */
 const NativeSelect = ({ className, ...props }) => (_jsxs("div", { className: "group/native-select relative w-fit has-[select:disabled]:opacity-50", "data-component": "native-select-wrapper", "data-slot": "native-select-wrapper", children: [_jsx("select", { className: cn(focusInput(), `h-12 w-full min-w-0 appearance-none ${INPUT_SHELL} selection:bg-primary selection:text-primary-foreground placeholder:text-muted-foreground transition-color-shadow text-paragraph-sm px-4 py-3 pr-9 shadow-xs disabled:pointer-events-none disabled:cursor-not-allowed`, hasErrorInput, className), "data-component": "native-select", "data-slot": "native-select", ...props }), _jsx(Icon, { "aria-hidden": "true", className: "pointer-events-none absolute top-1/2 right-3 -translate-y-1/2 opacity-50 select-none", "data-component": "native-select-icon", "data-slot": "native-select-icon", icon: ChevronDown, size: "xs" })] }));

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

@@ -26,6 +26,7 @@ export interface PillProps extends React.HTMLAttributes<HTMLElement>, Omit<Varia
  *
  * @bestPractice Don't reach for `Pill` in app code - it's the shared styling base; use `Badge` for display-only labels/counts and `Tag` for interactive (clickable/dismissible) chips.
  * @bestPractice `Pill` is presentation-only and has no button semantics or dismiss/click handling - those live on `Tag`; adding `onClick` here yields a non-accessible pseudo-button.
+ * @keywords chip
  * @category data
  */
 export declare const Pill: ({ as, className, tone, size, emphasis, radius, disabled, asInput, children, ref, render, ...props }: PillProps) => React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;

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

@@ -11,6 +11,7 @@ import { DEFAULT_PILL_SIZE, PILL_SIZE_CLASSES, pillVariants, } from "../pill/pil
  *
  * @bestPractice Don't reach for `Pill` in app code - it's the shared styling base; use `Badge` for display-only labels/counts and `Tag` for interactive (clickable/dismissible) chips.
  * @bestPractice `Pill` is presentation-only and has no button semantics or dismiss/click handling - those live on `Tag`; adding `onClick` here yields a non-accessible pseudo-button.
+ * @keywords chip
  * @category data
  */
 export const Pill = ({ as = "span", className, tone, size, emphasis, radius, disabled, asInput, children, ref, render, ...props }) => {

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

@@ -21,6 +21,7 @@ import type { ComponentSize } from "../../tokens/size.js";
  * @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
  */
 declare const Popover: <Payload>({ ...props }: PopoverPrimitive.Root.Props<Payload>) => import("react").JSX.Element;

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/segmented-control/segmented-control-root.js

@@ -6,7 +6,7 @@ import { ScrollFade } from "@instruments/materia-ui/components/scroll-fade";
 import { cn } from "@instruments/materia-ui/utils/cn";
 import { useEffect, useId, useMemo, useRef, useState } from "react";
 import { getResponsiveSizeOverrides, resolveResponsiveBase, } from "../../tokens/responsive.js";
-import { SEGMENTED_GAP, SEGMENTED_SHELL_BASE, SEGMENTED_SHELL_PADDING, } from "../../tokens/segmented.js";
+import { SEGMENTED_GAP, SEGMENTED_SHELL_BASE, SEGMENTED_SHELL_PADDING_X, SEGMENTED_SHELL_PADDING_Y, } from "../../tokens/segmented.js";
 import { Flex } from "../flex.js";
 import { SegmentedControlContext } from "./segmented-control-context.js";
 import { useSingleSelection } from "./use-single-selection.js";
@@ -65,10 +65,13 @@ const SegmentedControl = ({ className, size = "sm", fullWidth = false, value, de
             viewport?.removeEventListener("scroll", checkScroll);
         };
     }, []);
-    return (_jsx(ToggleGroup, { className: cn(SEGMENTED_SHELL_BASE, "group/segmented-control inline-flex h-auto max-w-full items-center overflow-hidden", SEGMENTED_SHELL_PADDING[resolvedSize], getResponsiveSizeOverrides(size, SEGMENTED_SHELL_PADDING), fullWidth && "flex w-full", className), "data-component": "segmented-control", "data-size": resolvedSize, "data-slot": "segmented-control", onValueChange: (groupValue) => {
+    return (_jsx(ToggleGroup, { className: cn(SEGMENTED_SHELL_BASE, "group/segmented-control inline-flex h-auto max-w-full items-center overflow-hidden", SEGMENTED_SHELL_PADDING_X[resolvedSize], getResponsiveSizeOverrides(size, SEGMENTED_SHELL_PADDING_X), fullWidth && "flex w-full", className), "data-component": "segmented-control", "data-size": resolvedSize, "data-slot": "segmented-control", onValueChange: (groupValue) => {
             // Single-select group: Base UI sends `[]` when the active item is
             // re-clicked; the selection hook swallows that deselect.
             selection.onValueChange(groupValue[0] ?? "");
-        }, value: [selection.value], ...props, children: _jsx(SegmentedControlContext.Provider, { value: contextValue, children: _jsxs("div", { className: "relative min-w-0 flex-1", ref: containerRef, children: [_jsx(ScrollArea, { hideScrollbar: true, orientation: "horizontal", children: _jsx(Flex, { align: "center", className: cn(SEGMENTED_GAP[resolvedSize], getResponsiveSizeOverrides(size, SEGMENTED_GAP), fullWidth && "w-full"), inline: true, children: children }) }), showEndFade && (_jsx(ScrollFade, { className: "rounded-r-full", orientation: "horizontal", position: "end", size: "sm", theme: "gray" }))] }) }) }));
+        }, value: [selection.value], ...props, children: _jsx(SegmentedControlContext.Provider, { value: contextValue, children: _jsxs("div", { className: "relative min-w-0 flex-1", ref: containerRef, children: [_jsx(ScrollArea, { hideScrollbar: true, orientation: "horizontal", children: _jsx(Flex, { align: "center", className: cn(
+                            // Vertical padding sits inside the scroll area, which clips,
+                            // so each item's hit area reaches the shell's full height.
+                            SEGMENTED_SHELL_PADDING_Y[resolvedSize], getResponsiveSizeOverrides(size, SEGMENTED_SHELL_PADDING_Y), SEGMENTED_GAP[resolvedSize], getResponsiveSizeOverrides(size, SEGMENTED_GAP), fullWidth && "w-full"), inline: true, children: children }) }), showEndFade && (_jsx(ScrollFade, { className: "rounded-r-full", orientation: "horizontal", position: "end", size: "sm", theme: "gray" }))] }) }) }));
 };
 export { SegmentedControl };

package/dist/components/segmented-control/segmented-control-variants.js

@@ -20,7 +20,10 @@ const triggerPaddingCompoundVariants = typedEntries(SEGMENTED_TRIGGER_PADDING).m
  * Structure mirrors `tabsTriggerVariants` (pill): the `size` variant only sets
  * text size; ALL padding is applied through size-keyed compound variants.
  */
-export const segmentedControlItemVariants = cva(cn(focusRing(), "text-muted-foreground relative inline-flex shrink-0 cursor-pointer items-center justify-center rounded-full font-medium whitespace-nowrap", `transition-color-shadow-border ${DISABLED}`, "data-pressed:text-foreground dark:text-gray-500 dark:data-pressed:text-gray-100", "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"), {
+export const segmentedControlItemVariants = cva(cn(focusRing(), "text-muted-foreground relative inline-flex shrink-0 cursor-pointer items-center justify-center rounded-full font-medium whitespace-nowrap", 
+// An invisible hit area overhanging the segment; the root's scroll area
+// trims it to the track, so a tap anywhere in the track's height lands.
+"after:absolute after:inset-x-0 after:-inset-y-3", `transition-color-shadow-border ${DISABLED}`, "data-pressed:text-foreground dark:text-gray-500 dark:data-pressed:text-gray-100", "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"), {
     compoundVariants: triggerPaddingCompoundVariants,
     defaultVariants: {
         size: "sm",

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/swatch-selector/swatch-selector-item.js

@@ -24,7 +24,10 @@ export const SwatchSelectorItem = ({ value, color, children, size: sizeOverride,
     const isSelected = selectedValue === value;
     const button = (_jsx(TogglePrimitive, { "aria-label": props["aria-label"] ?? `Select ${value}`, className: cn(
         // Focus styles only - visual handled by Swatch
-        "inline-flex shrink-0 cursor-pointer items-center justify-center rounded-full", focusRing(), "disabled:cursor-not-allowed disabled:opacity-50", className), "data-component": "swatch-selector-item", "data-slot": "swatch-selector-item", onClick: (event) => {
+        "relative inline-flex shrink-0 cursor-pointer items-center justify-center rounded-full", 
+        // An invisible hit area at least 44px tall and 5px wider each side, so
+        // a small swatch fills its slot in a 10px-gapped row.
+        "after:absolute after:-inset-x-[5px] after:top-1/2 after:h-full after:min-h-11 after:-translate-y-1/2", focusRing(), "disabled:cursor-not-allowed disabled:opacity-50", className), "data-component": "swatch-selector-item", "data-slot": "swatch-selector-item", onClick: (event) => {
             event.stopPropagation();
         }, value: value, ...props, children: _jsx(Swatch, { ...(color === undefined ? {} : { color }), selected: isSelected, size: resolvedSize, unavailable: unavailable, children: children }) }));
     if (unavailable) {

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/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. */