@instruments/materia-ui 0.4.5 → 0.4.7

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

@@ -5,6 +5,14 @@ declare const itemMediaVariants: (props?: ({
     variant?: "default" | "icon" | "image" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface ItemMediaProps extends Omit<React.ComponentProps<"div">, keyof IconBoxProps>, Omit<Partial<IconBoxProps>, "variant">, VariantProps<typeof itemMediaVariants> {
+    /** Has no effect: the `icon` variant always renders a `neutral` icon box. */
+    tone?: IconBoxProps["tone"];
+    /** Has no effect: the `icon` variant always renders the default icon box corners. */
+    radius?: IconBoxProps["radius"];
+    /** Has no effect: the `icon` variant always renders a `sm` (32px) icon box. */
+    size?: IconBoxProps["size"];
+    /** Has no effect: the `icon` variant always renders the default solid icon box. */
+    emphasis?: IconBoxProps["emphasis"];
 }
 /**
  * Leading media slot for an item - renders an IconBox when `variant="icon"`,

package/dist/components/item/item-media.js

@@ -7,6 +7,7 @@ const itemMediaVariants = cva("flex shrink-0 items-center justify-center gap-2 g
         variant: "default",
     },
     variants: {
+        /** Media type: `icon` renders the `icon` prop in a small neutral `IconBox`, `image` crops its child `<img>` to a 40px square, `default` wraps any children as they are. @default "default" */
         variant: {
             default: "",
             icon: "",

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

@@ -18,6 +18,7 @@ declare const itemVariants: (props?: ({
     size?: "2xl" | "2xs" | "3xl" | "base" | "lg" | "sm" | "xl" | "xs" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface ItemProps extends useRender.ComponentProps<"div">, Omit<VariantProps<typeof itemVariants>, "size"> {
+    /** Padding and gap between the item's parts, `2xs` (tightest) to `3xl` (roomiest). @default "base" */
     size?: ComponentSize;
 }
 /**

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

@@ -45,6 +45,7 @@ const itemVariants = cva(cn(focusRing(), "group/item duration-quick text-paragra
         variant: "default",
     },
     variants: {
+        /** Surface: `default` is transparent, `outline` adds a border, `muted` a faint fill, `card` a bordered rounded card. Inside an `ItemGroup` the group's variant overrides most of this. @default "default" */
         variant: {
             default: "bg-transparent",
             outline: "border-border border",

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

@@ -88,11 +88,13 @@ const kbdVariants = cva("pointer-events-none inline-flex w-fit items-center just
         tone: "neutral",
     },
     variants: {
+        /** Semantic colour: `neutral` for ordinary keys, `brand` to highlight one, `danger` for a destructive shortcut. `brand` and `danger` are only styled with `emphasis="solid"`. @default "neutral" */
         tone: {
             neutral: "",
             brand: "",
             danger: "",
         },
+        /** Fill treatment: `solid` is a muted chip, `soft` a secondary-coloured fill, `outline` a bordered key on the page background, `ghost` bare text. @default "solid" */
         emphasis: {
             solid: "",
             soft: "",

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

@@ -51,6 +51,8 @@ export interface MediaFrameProps extends useRender.ComponentProps<"div"> {
  * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
  * @bestPractice Set `edge` to frame photography with an inset hairline that stays above the media; do not fake it with a border or an inset shadow on the frame, which the media hides.
  * @bestPractice Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.
+ * @bestPractice Frame a material, swatch or sample square: give the frame `aspect-square` (or wrap it in `AspectRatio`, which defaults to 1:1). Never crop a material landscape.
+ * @keywords material image, product image, photo frame, thumbnail
  * @category layout
  */
 export declare const MediaFrame: ({ as, className, children, edge, raised, ref, render, ...props }: MediaFrameProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/media-frame/media-frame-root.js

@@ -25,6 +25,8 @@ import { reportDevIssue } from "../../utils/dev-issue.js";
  * @bestPractice Use `as` to change the element (a tag); use `render` only to swap in a component (e.g. a router Link). Never `render={<Box as=…/>}` - pass `as` directly.
  * @bestPractice Set `edge` to frame photography with an inset hairline that stays above the media; do not fake it with a border or an inset shadow on the frame, which the media hides.
  * @bestPractice Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.
+ * @bestPractice Frame a material, swatch or sample square: give the frame `aspect-square` (or wrap it in `AspectRatio`, which defaults to 1:1). Never crop a material landscape.
+ * @keywords material image, product image, photo frame, thumbnail
  * @category layout
  */
 export const MediaFrame = ({ as, className, children, edge = false, raised = false, ref, render, ...props }) => {

package/dist/components/menu-item/menu-item-variants.js

@@ -128,10 +128,12 @@ const menuItemVariants = cva(`duration-quick hover:duration-instant focus:durati
         variant: "default",
     },
     variants: {
+        /** Row height, padding and text size, on the shared component scale. Match the surrounding menu's `size`. @default "sm" */
         size: MENU_ITEM_SIZE_CLASSES,
         // Surface axis (background/hover treatment). The former `destructive`
         // member split off onto the orthogonal `tone` axis below, so a
         // destructive item of any surface is now expressible.
+        /** Surface treatment: `default` tints on hover, `input` uses the input fill, `outline` adds a ring. @default "default" */
         variant: {
             default: "hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground data-[active=true]:bg-accent data-[active=true]:text-accent-foreground data-[active=true]:font-medium",
             input: "hover:bg-input hover:text-foreground focus:bg-input focus:text-foreground focus-visible:bg-input focus-visible:text-foreground data-[active=true]:bg-input data-[active=true]:text-foreground data-[active=true]:font-medium",
@@ -143,11 +145,14 @@ const menuItemVariants = cva(`duration-quick hover:duration-instant focus:durati
         // look. Active keeps the danger signal - destructive foreground on a
         // destructive tint one step stronger than hover (/20 vs /10) - instead
         // of falling through to the surface's neutral `bg-accent` active state.
+        /** `danger` marks a destructive action with red text and a red hover and active tint. @default "neutral" */
         tone: {
             neutral: "",
             danger: "text-destructive hover:bg-destructive/10 hover:text-destructive focus:bg-destructive/10 focus:text-destructive focus-visible:bg-destructive/10 focus-visible:text-destructive data-[active=true]:bg-destructive/20 data-[active=true]:text-destructive [&_svg:not([class*='text-'])]:text-destructive data-[active=true]:font-medium",
         },
+        /** Corner shape: `full` is a pill, `rounded` a soft rectangle, `square` has sharp corners. @default "full" */
         radius: RADIUS_CLASSES,
+        /** Pads the start so a row with no leading glyph lines up with rows that have an icon, dot or avatar. Switched on automatically when `indicator` is set. @default false */
         inset: {
             true: "",
             false: "",

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-root.d.ts

@@ -38,6 +38,8 @@ type SwatchProps = ChipSwatchProps | TileSwatchProps;
  * @bestPractice Feed fills through `color`/`background`/`colors`, never a hex in `className`/`style` - the props drive the contrast-aware text colour, selection ring, and darkening overlay.
  * @bestPractice Reach for `Swatch` for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is `Dot`, and a display-only status/category label is `Badge`.
  * @bestPractice For a gradient or image chip fill pass `light` - auto contrast detection (`isLightColor`) only reads solid colours, so overlaid icons/labels lose legibility without it.
+ * @bestPractice A material swatch is always square, as Swatch draws it; never stretch a tile into a landscape crop, and in a grid let the column set the size.
+ * @keywords material swatch, material sample, finish, colourway, colour chip
  * @category color
  */
 declare const Swatch: (props: SwatchProps) => import("react").JSX.Element;

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

@@ -29,6 +29,8 @@ import { SwatchTile } from "./swatch-tile.js";
  * @bestPractice Feed fills through `color`/`background`/`colors`, never a hex in `className`/`style` - the props drive the contrast-aware text colour, selection ring, and darkening overlay.
  * @bestPractice Reach for `Swatch` for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is `Dot`, and a display-only status/category label is `Badge`.
  * @bestPractice For a gradient or image chip fill pass `light` - auto contrast detection (`isLightColor`) only reads solid colours, so overlaid icons/labels lose legibility without it.
+ * @bestPractice A material swatch is always square, as Swatch draws it; never stretch a tile into a landscape crop, and in a grid let the column set the size.
+ * @keywords material swatch, material sample, finish, colourway, colour chip
  * @category color
  */
 const Swatch = (props) => {

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;