@instruments/materia-ui 0.4.6 → 0.4.7

package/dist/components/menu-parts-types.d.ts

@@ -0,0 +1,82 @@
+import type { Menu as MenuPrimitive } from "@base-ui/react/menu";
+import type { LucideIcon } from "lucide-react";
+import type * as React from "react";
+import type { MenuContentWidth, MenuOverflow, MenuSurface } from "../tokens/menu-content.js";
+import type { Radius } from "../tokens/radius.js";
+import type { ComponentSize } from "../tokens/size.js";
+import type { Tone } from "../tokens/tone.js";
+import type { MenuItemProps } from "./menu-item/menu-item-root.js";
+/** The props of the shared menu parts built by `menu-parts.ts`, one set for DropdownMenu, ContextMenu and Menubar. */
+/** Positioning props accepted on every menu `*Content` and forwarded to the Base UI Positioner. */
+export type MenuPositionProps = Pick<MenuPrimitive.Positioner.Props, "align" | "alignOffset" | "anchor" | "arrowPadding" | "collisionAvoidance" | "collisionBoundary" | "collisionPadding" | "disableAnchorTracking" | "side" | "sideOffset" | "sticky">;
+/** Base UI Popup props plus the positioning props, with a string `className`. */
+export type MenuPopupProps = Omit<MenuPrimitive.Popup.Props, "className"> & MenuPositionProps & {
+    className?: string;
+};
+/** Props for a menu Item. */
+export type MenuItemPartProps = Omit<MenuPrimitive.Item.Props, "children" | "className" | "render"> & {
+    className?: string;
+    /** Pads the start so a row with no leading glyph lines up with rows that have an icon, dot or avatar. */
+    inset?: boolean;
+    /** `danger` marks a destructive action with red text and a red highlight. @default "neutral" */
+    tone?: Extract<Tone, "neutral" | "danger">;
+    /** Custom leading element, such as an `Avatar`. Takes precedence over `dot` and `icon`. */
+    avatar?: React.ReactNode;
+    /** Dot indicator at the start (takes precedence over icon): `true` for a neutral dot, or a {@link Tone} to tint it. */
+    dot?: boolean | Tone;
+    /** Leading icon, passed as a component (such as a Lucide icon) rather than an element. Hidden when `avatar` or `dot` is set. */
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** Trailing icon, passed as a component. Replaces `kbd` when both are set. */
+    suffixIcon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** Keyboard shortcut keys shown as keycaps at the end, for example `["⌘", "C"]`. Ignored when `suffixIcon` is set. */
+    kbd?: string[];
+    /** Custom trailing content, rendered after `suffixIcon` or `kbd`. */
+    suffix?: React.ReactNode;
+    /** Whether the item is in an active/selected state */
+    active?: boolean;
+    /** Visual indicator for active state. "dot" shows grey dot normally, green when active. "check" shows green checkmark only when active. */
+    activeIndicator?: "dot" | "check" | "none";
+    /** Replace the default `<button>` row (e.g. with a link); glyph props render inside it, around `children`. */
+    render?: MenuItemProps["render"];
+    /** Text label. Use `icon` prop for icons, not children. */
+    children?: React.ReactElement | string | number;
+};
+/** Props shared by the CheckboxItem, RadioItem and SubTrigger rows over their Base UI part. */
+type MenuRowProps<P> = Omit<P, "children" | "className" | "render"> & {
+    className?: string;
+    /** Replace the default `<button>` row; glyph props render inside it, around `children`. */
+    render?: MenuItemProps["render"];
+    /** Text label. Use `icon` prop for icons, not children. */
+    children?: React.ReactElement | string | number;
+};
+/** Props for a menu CheckboxItem. */
+export type MenuCheckboxItemProps = MenuRowProps<MenuPrimitive.CheckboxItem.Props>;
+/** Props for a menu RadioItem. */
+export type MenuRadioItemProps = MenuRowProps<MenuPrimitive.RadioItem.Props>;
+/** Props for a menu SubTrigger. */
+export type MenuSubTriggerProps = MenuRowProps<MenuPrimitive.SubmenuTrigger.Props> & {
+    /** Pads the start so a row with no leading icon lines up with rows that have one. */
+    inset?: boolean;
+    /** Leading icon, passed as a component (such as a Lucide icon) rather than an element. The trailing chevron is added for you. */
+    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+};
+/** Props for a menu Separator. */
+export type MenuSeparatorProps = Omit<React.ComponentProps<typeof MenuPrimitive.Separator>, "className"> & {
+    className?: string;
+    /** `default` is a 1px rule with 4px margins. `compact` centres the same rule in a taller transparent band, leaving more room around it. @default "default" */
+    spacing?: "default" | "compact";
+};
+/** Props for a menu Content. */
+export type MenuContentProps = MenuPopupProps & {
+    /** Size of every item, label and shortcut inside, which read it from context. Submenus inherit it. @default "sm" */
+    size?: ComponentSize;
+    /** Border radius for menu items. When "full", items become pill-shaped. */
+    itemRadius?: Radius;
+    /** Surface density. Compact maps to the 16px-radius, 4px-padding menu surface. */
+    surface?: MenuSurface;
+    /** Named content widths from the design system. */
+    contentWidth?: MenuContentWidth;
+    /** Outer content overflow behaviour. Use hidden when a child owns scrolling. */
+    overflow?: MenuOverflow;
+};
+export {};

package/dist/components/menu-parts-types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/menu-parts.d.ts

@@ -1,11 +1,7 @@
 import { Menu as MenuPrimitive } from "@base-ui/react/menu";
-import type { LucideIcon } from "lucide-react";
 import type * as React from "react";
-import type { MenuContentWidth, MenuOverflow, MenuSurface } from "../tokens/menu-content.js";
-import type { Radius } from "../tokens/radius.js";
 import type { ComponentSize } from "../tokens/size.js";
-import type { Tone } from "../tokens/tone.js";
-import type { MenuItemProps } from "./menu-item/menu-item-root.js";
+import type { MenuCheckboxItemProps, MenuContentProps, MenuItemPartProps, MenuPopupProps, MenuPositionProps, MenuRadioItemProps, MenuSeparatorProps, MenuSubTriggerProps } from "./menu-parts-types.js";
 /**
  * Internal factory for the menu families (DropdownMenu / ContextMenu /
  * Menubar). The three compose the same Base UI Menu parts (ContextMenu's and
@@ -18,12 +14,6 @@ import type { MenuItemProps } from "./menu-item/menu-item-root.js";
  * menu part files. Unlike that module the parts read React context, so it
  * carries a `"use client"` directive.
  */
-/** Positioning props accepted on every menu `*Content` and forwarded to the Base UI Positioner. */
-type MenuPositionProps = Pick<MenuPrimitive.Positioner.Props, "align" | "alignOffset" | "anchor" | "arrowPadding" | "collisionAvoidance" | "collisionBoundary" | "collisionPadding" | "disableAnchorTracking" | "side" | "sideOffset" | "sticky">;
-/** Base UI Popup props plus the positioning props, with a string `className`. */
-export type MenuPopupProps = Omit<MenuPrimitive.Popup.Props, "className"> & MenuPositionProps & {
-    className?: string;
-};
 /** Default Positioner offsets/alignment a family applies when the caller omits them. */
 interface MenuPositionDefaults {
     align?: MenuPositionProps["align"];
@@ -37,67 +27,13 @@ interface MenuContextValue {
 }
 /** Props for a menu SubContent: the Content's popup props plus a `size` override. */
 export type MenuSubContentProps = MenuPopupProps & {
+    /** Item size for this submenu only. Omit to inherit the parent menu's `size`. */
     size?: ComponentSize;
 };
 /** Props for a menu Label: Base UI `GroupLabel` props with a string `className`. */
 export type MenuLabelProps = Omit<MenuPrimitive.GroupLabel.Props, "className"> & {
     className?: string;
 };
-/** Props for a menu Item. */
-export type MenuItemPartProps = Omit<MenuPrimitive.Item.Props, "children" | "className" | "render"> & {
-    className?: string;
-    inset?: boolean;
-    tone?: Extract<Tone, "neutral" | "danger">;
-    avatar?: React.ReactNode;
-    /** Dot indicator at the start (takes precedence over icon): `true` for a neutral dot, or a {@link Tone} to tint it. */
-    dot?: boolean | Tone;
-    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
-    suffixIcon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
-    kbd?: string[];
-    suffix?: React.ReactNode;
-    /** Whether the item is in an active/selected state */
-    active?: boolean;
-    /** Visual indicator for active state. "dot" shows grey dot normally, green when active. "check" shows green checkmark only when active. */
-    activeIndicator?: "dot" | "check" | "none";
-    /** Replace the default `<button>` row (e.g. with a link); glyph props render inside it, around `children`. */
-    render?: MenuItemProps["render"];
-    /** Text label. Use `icon` prop for icons, not children. */
-    children?: React.ReactElement | string | number;
-};
-/** Props shared by the CheckboxItem, RadioItem and SubTrigger rows over their Base UI part. */
-type MenuRowProps<P> = Omit<P, "children" | "className" | "render"> & {
-    className?: string;
-    /** Replace the default `<button>` row; glyph props render inside it, around `children`. */
-    render?: MenuItemProps["render"];
-    /** Text label. Use `icon` prop for icons, not children. */
-    children?: React.ReactElement | string | number;
-};
-/** Props for a menu CheckboxItem. */
-export type MenuCheckboxItemProps = MenuRowProps<MenuPrimitive.CheckboxItem.Props>;
-/** Props for a menu RadioItem. */
-export type MenuRadioItemProps = MenuRowProps<MenuPrimitive.RadioItem.Props>;
-/** Props for a menu SubTrigger. */
-export type MenuSubTriggerProps = MenuRowProps<MenuPrimitive.SubmenuTrigger.Props> & {
-    inset?: boolean;
-    icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
-};
-/** Props for a menu Separator. */
-export type MenuSeparatorProps = Omit<React.ComponentProps<typeof MenuPrimitive.Separator>, "className"> & {
-    className?: string;
-    spacing?: "default" | "compact";
-};
-/** Props for a menu Content. */
-export type MenuContentProps = MenuPopupProps & {
-    size?: ComponentSize;
-    /** Border radius for menu items. When "full", items become pill-shaped. */
-    itemRadius?: Radius;
-    /** Surface density. Compact maps to the 16px-radius, 4px-padding menu surface. */
-    surface?: MenuSurface;
-    /** Named content widths from the design system. */
-    contentWidth?: MenuContentWidth;
-    /** Outer content overflow behaviour. Use hidden when a child owns scrolling. */
-    overflow?: MenuOverflow;
-};
 /** The Content defaults that differ between families. */
 interface MenuContentConfig {
     /** Positioner defaults applied when the caller omits them. */
@@ -129,6 +65,7 @@ export interface MenuFamilyParts {
     Group: MenuPart<React.ComponentProps<typeof MenuPrimitive.Group>>;
     Item: MenuPart<MenuItemPartProps>;
     Label: MenuPart<MenuLabelProps & {
+        /** Pads the start so the label lines up with items that have a leading icon. */
         inset?: boolean;
     }>;
     Portal: MenuPart<React.ComponentProps<typeof MenuPrimitive.Portal>>;

package/dist/components/menubar/menubar-checkbox-item.d.ts

@@ -2,5 +2,5 @@
  * Menu item with a toggleable checkmark. Controlled via `checked`/`onCheckedChange`;
  * the menu stays open on select unless you set `closeOnClick`.
  */
-declare const MenubarCheckboxItem: (props: import("../menu-parts.js").MenuCheckboxItemProps) => React.JSX.Element;
+declare const MenubarCheckboxItem: (props: import("../menu-parts-types.js").MenuCheckboxItemProps) => React.JSX.Element;
 export { MenubarCheckboxItem };

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

@@ -3,5 +3,5 @@
  * open/close. Provides item size and radius to descendants via context, so
  * `size`/`itemRadius` set here flow to every item, label, and shortcut inside.
  */
-declare const MenubarContent: (props: import("../menu-parts.js").MenuContentProps) => React.JSX.Element;
+declare const MenubarContent: (props: import("../menu-parts-types.js").MenuContentProps) => React.JSX.Element;
 export { MenubarContent };

package/dist/components/menubar/menubar-item.d.ts

@@ -4,5 +4,5 @@
  * for a leading icon rather than nesting icon elements in `children`. Handle
  * selection with `onClick`; set `closeOnClick={false}` to keep the menu open.
  */
-declare const MenubarItem: (props: import("../menu-parts.js").MenuItemPartProps) => React.JSX.Element;
+declare const MenubarItem: (props: import("../menu-parts-types.js").MenuItemPartProps) => React.JSX.Element;
 export { MenubarItem };

package/dist/components/menubar/menubar-radio-item.d.ts

@@ -2,5 +2,5 @@
  * Single-select menu item showing a trailing checkmark when active. Must be
  * rendered inside a MenubarRadioGroup, which supplies its `value`.
  */
-declare const MenubarRadioItem: (props: import("../menu-parts.js").MenuRadioItemProps) => React.JSX.Element;
+declare const MenubarRadioItem: (props: import("../menu-parts-types.js").MenuRadioItemProps) => React.JSX.Element;
 export { MenubarRadioItem };

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

@@ -1,3 +1,3 @@
-/** Horizontal divider between groups of menu items. `spacing="compact"` tightens the vertical gap. */
-declare const MenubarSeparator: (props: import("../menu-parts.js").MenuSeparatorProps) => React.JSX.Element;
+/** Horizontal divider between groups of menu items. `spacing="compact"` leaves more room around the rule. */
+declare const MenubarSeparator: (props: import("../menu-parts-types.js").MenuSeparatorProps) => React.JSX.Element;
 export { MenubarSeparator };

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

@@ -1,5 +1,5 @@
 "use client";
 import { menubarParts } from "./menubar-parts.js";
-/** Horizontal divider between groups of menu items. `spacing="compact"` tightens the vertical gap. */
+/** Horizontal divider between groups of menu items. `spacing="compact"` leaves more room around the rule. */
 const MenubarSeparator = menubarParts.Separator;
 export { MenubarSeparator };

package/dist/components/menubar/menubar-sub-trigger.d.ts

@@ -3,5 +3,5 @@
  * arrow key, with a trailing chevron. Pass label text via `children` and a
  * leading icon via `icon`.
  */
-declare const MenubarSubTrigger: (props: import("../menu-parts.js").MenuSubTriggerProps) => React.JSX.Element;
+declare const MenubarSubTrigger: (props: import("../menu-parts-types.js").MenuSubTriggerProps) => React.JSX.Element;
 export { MenubarSubTrigger };

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

@@ -17,6 +17,7 @@ const phoneInputVariants = cva("border-border bg-input relative flex w-full item
     },
     variants: {
         // Heights from shared CONTROL_HEIGHT_CLASSES (aligns with Button/Input).
+        /** Control height and text size, matching Button and Input at the same size. Also sizes the country selector. @default "xl" */
         size: withControlHeights({
             "2xs": "text-xs",
             xs: "text-xs",
@@ -27,6 +28,7 @@ const phoneInputVariants = cva("border-border bg-input relative flex w-full item
             "2xl": "text-base",
             "3xl": "text-base",
         }),
+        /** Corner shape: `rounded` for a soft rectangle, `full` for a capsule. @default "rounded" */
         radius: {
             rounded: "rounded-md",
             full: "rounded-full",

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

@@ -6,6 +6,7 @@ import { pillVariants } from "../pill/pill-variants.js";
 export interface PillProps extends React.HTMLAttributes<HTMLElement>, Omit<VariantProps<typeof pillVariants>, "size"> {
     /** Host tag rendered when `render` is not given. @default "span" */
     as?: keyof React.JSX.IntrinsicElements;
+    /** Dims the pill and blocks pointer events. Styling only: no `disabled` attribute reaches the element. */
     disabled?: boolean;
     /** Replace the rendered element with another element or component. */
     render?: useRender.RenderProp | undefined;

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

@@ -233,6 +233,7 @@ export const pillVariants = cva(cn("inline-flex items-center justify-center bord
         // `satisfies Record<Tone|Emphasis, string>` fails to compile if a canon
         // member is missing or a stray key creeps in, keeping PillTone=Tone and
         // PillEmphasis=Emphasis (declared below) honest.
+        /** Semantic colour: `neutral` for plain labels, `brand` for the house yellow, `success` / `warning` / `info` / `danger` for status. @default "neutral" */
         tone: {
             neutral: "bg-primary text-primary-foreground",
             brand: "bg-brand text-brand-foreground",
@@ -241,6 +242,7 @@ export const pillVariants = cva(cn("inline-flex items-center justify-center bord
             info: "bg-info-accent text-info-foreground",
             danger: "bg-destructive text-destructive-foreground",
         },
+        /** Visual weight: `solid` is a filled pill, `soft` a pale tint, `outline` a border, `ghost` text only, `transparent` frosted glass for use over images only. @default "solid" */
         emphasis: {
             solid: "",
             soft: "",
@@ -252,6 +254,7 @@ export const pillVariants = cva(cn("inline-flex items-center justify-center bord
             true: "pointer-events-none opacity-50",
         },
         size: PILL_SIZE_CLASSES,
+        /** Corner shape: `full` is a capsule, `rounded` a soft rectangle, `square` has sharp corners. Overrides the size's own corner radius. @default "full" */
         radius: {
             rounded: "rounded-md!",
             square: "rounded-none!",

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

@@ -57,7 +57,9 @@ type PopoverPositionerProps = Pick<PopoverPrimitive.Positioner.Props, "align" |
  */
 declare const PopoverContent: ({ className, align, sideOffset, size, side, alignOffset, anchor, arrowPadding, collisionAvoidance, collisionBoundary, collisionPadding, positionMethod, positionerClassName, sticky, ...props }: Omit<PopoverPrimitive.Popup.Props, "className"> & PopoverPositionerProps & {
     className?: string;
+    /** Classes for the positioning layer around the content, such as a lower `z-*` for a panel that sits beneath fixed chrome. Defaults to `z-50`. */
     positionerClassName?: string;
+    /** Padding and corner radius: `sm` is compact (8px), `base` is 16px, `lg` is roomy (24px). @default "lg" */
     size?: PopoverSize;
 }) => import("react").JSX.Element;
 /**

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

@@ -5,6 +5,7 @@ interface ProgressCircleProps {
     /** Optional content rendered centred over the ring (e.g. a percentage). */
     children?: React.ReactNode;
     className?: string;
+    /** Classes for the filled arc, for example a stroke colour such as `stroke-brand`. Defaults to `stroke-primary`. */
     indicatorClassName?: string;
     /** Accessible label announced by screen readers (required). */
     label: string;
@@ -14,6 +15,7 @@ interface ProgressCircleProps {
     size?: number;
     /** Ring stroke width in pixels. @default 3 */
     strokeWidth?: number;
+    /** Classes for the unfilled ring behind the arc, for example a stroke colour such as `stroke-border`. Defaults to `stroke-muted`. */
     trackClassName?: string;
     /** Current progress; clamped to `0..max`. */
     value: number;

package/dist/components/scroll-frame/scroll-frame-root.d.ts

@@ -30,7 +30,10 @@ export interface ScrollFrameProps {
      * @default false
      */
     dragScroll?: boolean | undefined;
-    /** @default "color" */
+    /**
+     * How the fades are drawn: `color` blends a gradient of `fadeTheme` into a solid surface, `mask` fades the content itself to transparent, for use over images or blurs.
+     * @default "color"
+     */
     fadeMode?: ScrollFrameFadeMode | undefined;
     /**
      * Which edges fade. An edge fades only while there is more beyond it.
@@ -52,7 +55,10 @@ export interface ScrollFrameProps {
      * @default false
      */
     hideScrollbar?: boolean | undefined;
-    /** @default "vertical" */
+    /**
+     * Scroll axis: `vertical` scrolls up and down, `horizontal` left and right, as for a row of chips.
+     * @default "vertical"
+     */
     orientation?: Orientation | undefined;
     /** Classes for the scrolling element. */
     viewportClassName?: string | undefined;

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

@@ -10,9 +10,15 @@ export type SegmentedControlProps<T extends string = string> = Omit<ToggleGroup.
     defaultValue?: T;
     /** Fires with the newly selected value - never with "". */
     onValueChange?: (value: T) => void;
-    /** @default "sm" */
+    /**
+     * Size of every segment (text and padding), or an object per breakpoint like `{ base: "sm", md: "lg" }`.
+     * @default "sm"
+     */
     size?: ResponsiveValue<ComponentSize>;
-    /** @default false */
+    /**
+     * Stretches the control to its container's width, with the segments sharing the space equally; otherwise it hugs its content.
+     * @default false
+     */
     fullWidth?: boolean;
 };
 /**

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

@@ -10,6 +10,7 @@ type SelectPositionerProps = Pick<SelectPrimitive.Positioner.Props, "align" | "a
  */
 declare const SelectContent: ({ className, children, align, alignItemWithTrigger, side, sideOffset, alignOffset, anchor, arrowPadding, collisionAvoidance, collisionBoundary, collisionPadding, positionMethod, sticky, size, testId, ...props }: WithTestId<Omit<SelectPrimitive.Popup.Props, "className"> & SelectPositionerProps & {
     className?: string;
+    /** Size of every SelectItem, label and group inside, which read it from context. Match the trigger's `size`. @default "sm" */
     size?: ComponentSize;
 }>) => import("react").JSX.Element;
 export { SelectContent };

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

@@ -5,10 +5,18 @@ import type { ButtonProps } from "../button.js";
 /**
  * Button that opens the listbox and displays the selected value (or the
  * SelectValue placeholder), with a trailing chevron; forwards Button styling
- * props - defaults to `size="lg"`, `emphasis="outline"`, `tone="neutral"`.
+ * props - defaults to `size="xl"`, `emphasis="outline"`, `radius="rounded"`.
  */
 declare const SelectTrigger: ({ className, children, testId, tone, size, emphasis, radius, pressed, ...props }: WithTestId<Omit<SelectPrimitive.Trigger.Props, "className" | "render"> & Pick<ButtonProps, "emphasis" | "pressed" | "radius" | "tone"> & {
     className?: string;
+    /** Semantic colour of the trigger, as on Button. @default "neutral" */
+    tone?: ButtonProps["tone"];
+    /** Visual weight, as on Button; the outline reads as a form field. @default "outline" */
+    emphasis?: ButtonProps["emphasis"];
+    /** Corner shape, as on Button. @default "rounded" */
+    radius?: ButtonProps["radius"];
+    /** Shrink while held down, as on Button, but off by default here. @default false */
+    pressed?: ButtonProps["pressed"];
     /**
      * Trigger size - a single token or a per-breakpoint object like
      * `{ base: "sm", md: "xl" }`. Forwarded to the underlying Button. @default "xl"

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

@@ -8,7 +8,7 @@ import { Icon } from "../icon.js";
 /**
  * Button that opens the listbox and displays the selected value (or the
  * SelectValue placeholder), with a trailing chevron; forwards Button styling
- * props - defaults to `size="lg"`, `emphasis="outline"`, `tone="neutral"`.
+ * props - defaults to `size="xl"`, `emphasis="outline"`, `radius="rounded"`.
  */
 const SelectTrigger = ({ className, children, testId, tone = "neutral", size = "xl", emphasis = "outline", radius = "rounded", pressed = false, ...props }) => (_jsxs(SelectPrimitive.Trigger, { render: _jsx(Button, { emphasis: emphasis, className: cn("bg-input data-placeholder:text-muted-foreground text-paragraph-sm justify-between rounded-md *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2", className), pressed: pressed, radius: radius, size: size, tone: tone }), "data-component": "select-trigger", "data-slot": "select-trigger", "data-testid": testId, ...props, children: [children, _jsx(SelectPrimitive.Icon, { className: "flex", children: _jsx(Icon, { className: "opacity-50", icon: ChevronDown, size: "xs" }) })] }));
 export { SelectTrigger };

package/dist/components/sidepanel/sidepanel-header.d.ts

@@ -11,6 +11,10 @@ import type { ComponentProps } from "react";
  */
 type SidepanelHeaderVariant = "bar" | "default";
 type SidepanelHeaderProps = ComponentProps<"div"> & {
+    /**
+     * `default` is a stacked title and description with a bottom border. `bar` is a transparent toolbar pinned over the top of the panel, for two `SidepanelControls` groups.
+     * @default "default"
+     */
     variant?: SidepanelHeaderVariant;
 };
 /**

package/dist/components/sub-navigation/sub-navigation-link.d.ts

@@ -5,6 +5,7 @@ export interface SubNavigationLinkProps extends Omit<React.ComponentProps<"a">,
     active?: boolean;
     /** Link label, matching what `MenuItem` renders. */
     children?: React.ReactElement | string | number | undefined;
+    /** Destination of the default `<a>`. Not used when `render` supplies its own element. */
     href?: string;
     /** Leading icon shown before the label. */
     icon?: LucideIcon;

package/dist/components/swatch/swatch-tile.d.ts

@@ -14,7 +14,8 @@ import type { TileSwatchProps } from "./swatch-tile-types.js";
  * </div>
  * ```
  */
-declare const SwatchFrameRing: ({ radius }: {
+declare const SwatchFrameRing: ({ radius, }: {
+    /** Tailwind rounding class (such as `rounded-xl`) matching the framed container's corners, so the ring follows them. */
     radius: string;
 }) => import("react").JSX.Element;
 /**

package/dist/components/swatch/swatch-tile.js

@@ -18,7 +18,7 @@ import { buildTileClasses, buildTileStyle, getInnerRingRadius, resolveTileState,
  * </div>
  * ```
  */
-const SwatchFrameRing = ({ radius }) => (_jsx("span", { "aria-hidden": "true", className: cn("pointer-events-none absolute inset-0 ring-1 ring-black/5 ring-inset", radius) }));
+const SwatchFrameRing = ({ radius, }) => (_jsx("span", { "aria-hidden": "true", className: cn("pointer-events-none absolute inset-0 ring-1 ring-black/5 ring-inset", radius) }));
 /**
  * Card/bare renderer: the tiered radius/border/ring/shadow tile.
  */

package/dist/components/tab-navigation/tab-navigation-link.d.ts

@@ -8,6 +8,7 @@ export interface TabNavigationLinkProps extends Omit<useRender.ComponentProps<"a
      * @default false
      */
     active?: boolean;
+    /** Destination of the link. Also forwarded to the element given in `render`, such as a router `Link`. */
     href: string;
     /** Optional icon rendered alongside the label. */
     icon?: IconComponent;

package/dist/components/tabs/tabs-panel.d.ts

@@ -8,5 +8,9 @@
 export declare const TabsPanel: ({ children, className, layout, }: {
     children: React.ReactNode;
     className?: string;
+    /**
+     * Motion `layout` value for the height animation when the active tab's content changes size: `false` switches it off, `"size"` or `"position"` animates only that, `"preserve-aspect"` keeps the aspect ratio.
+     * @default true
+     */
     layout?: boolean | "position" | "size" | "preserve-aspect";
 }) => import("react").JSX.Element;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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