@instruments/materia-ui 0.4.5 → 0.4.7

package/agent-docs.md

@@ -80,6 +80,7 @@ Constrains its content to a fixed width-to-height ratio, sizing itself to the av
 
 - Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.
 - 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.
+- Show a material, swatch or sample at the default 1:1 - never landscape. A sample is cut square, and a wide crop reads as room photography; set a wide `ratio` only for a scene, an interior or video.
 
 ## AttributeCard
 
@@ -1033,6 +1034,7 @@ Extracted from the product-card and editorial-card media frames; available to an
 - 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.
 - 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.
 - Reach for `raised` only when the frame sits on the same fill as its surface; in a dense row the edge already separates it.
+- 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.
 
 ## MediaFrameEmbed
 
@@ -1244,6 +1246,7 @@ This is a presentational component that accepts handlers via props for app-speci
 
 - In Next.js apps pass `renderImage` wrapping `next/image` and `linkAs={Link}` - the defaults are a plain `<img>` and `<a>`.
 - Cart UI renders only when a `renderAddToCart` slot is provided; keep `dragAdapter` referentially stable (module-level constant).
+- Use ProductCard for a material in a grid or list; its image is square, which is how a material is always shown. Don't rebuild the card with a landscape image.
 
 ## ProductCardProvider
 
@@ -1833,6 +1836,7 @@ Chips paint the darkening overlay on every fill and draw the double-ring selecti
 - 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.
 - 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`.
 - 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.
+- 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.
 
 ## SwatchFan
 

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

@@ -9,6 +9,7 @@ export const accordionRootVariants = cva("", {
         variant: "default",
     },
     variants: {
+        /** Item styling, inherited by every item: `default` is ruled rows divided by bottom borders, `outline` bordered cards, `solid` filled cards. `outline` and `solid` space the items apart. @default "default" */
         variant: {
             default: "",
             outline: "space-y-2",

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

@@ -7,6 +7,7 @@ const alertVariants = cva("text-paragraph-sm relative grid w-full grid-cols-[0_1
     },
     variants: {
         // Lockstep: Alert's tone is the canon subset Extract<Tone, neutral|danger>.
+        /** Semantic colour: `neutral` for information, `danger` for an error or a destructive warning. @default "neutral" */
         tone: {
             neutral: "bg-card text-card-foreground",
             danger: "bg-card text-destructive *:data-[slot=alert-description]:text-destructive/90 [&>svg]:text-current",

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

@@ -16,6 +16,7 @@ const anchorVariants = cva("rounded-xs underline underline-offset-4 transition-c
         variant: "default",
     },
     variants: {
+        /** Link treatment: `default` is a medium-weight underlined link, `muted` reads as body text until hovered, `plain` has no underline until hovered. @default "default" */
         variant: {
             default: "text-foreground decoration-foreground/40 hover:decoration-foreground font-medium",
             muted: "text-muted-foreground decoration-muted-foreground/40 hover:text-foreground hover:decoration-current",

package/dist/components/aspect-ratio/aspect-ratio-root.d.ts

@@ -14,7 +14,9 @@ interface AspectRatioProps extends useRender.ComponentProps<"div"> {
     as?: LayoutElement;
     /**
      * Desired width-to-height ratio, expressed as a single number (width / height).
-     * @default 16 / 9
+     * Square unless asked: a material is shown at 1:1, and only scenes and
+     * video take a wide ratio.
+     * @default 1
      */
     ratio?: number;
 }
@@ -25,13 +27,15 @@ interface AspectRatioProps extends useRender.ComponentProps<"div"> {
  *
  * @example
  * ```tsx
- * <AspectRatio ratio={16 / 9}>
- *   <img alt="" className="size-full object-cover" src="/hero.jpg" />
+ * <AspectRatio>
+ *   <img alt="" className="size-full object-cover" src="/oak-plank.jpg" />
  * </AspectRatio>
  * ```
  *
  * @bestPractice Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.
  * @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 Show a material, swatch or sample at the default 1:1 - never landscape. A sample is cut square, and a wide crop reads as room photography; set a wide `ratio` only for a scene, an interior or video.
+ * @keywords material image, swatch image, sample image, thumbnail, square, image ratio
  * @category layout
  */
 declare const AspectRatio: ({ as, className, ratio, ref, render, style, ...props }: AspectRatioProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/aspect-ratio/aspect-ratio-root.js

@@ -2,7 +2,7 @@
 import { useRender } from "@base-ui/react/use-render";
 import { cn } from "../../utils/cn.js";
 import { reportDevIssue } from "../../utils/dev-issue.js";
-const DEFAULT_RATIO = 16 / 9;
+const DEFAULT_RATIO = 1;
 /**
  * Constrains its content to a fixed width-to-height ratio, sizing itself to the
  * available width with CSS `aspect-ratio`; drop a single child (image, video,
@@ -10,13 +10,15 @@ const DEFAULT_RATIO = 16 / 9;
  *
  * @example
  * ```tsx
- * <AspectRatio ratio={16 / 9}>
- *   <img alt="" className="size-full object-cover" src="/hero.jpg" />
+ * <AspectRatio>
+ *   <img alt="" className="size-full object-cover" src="/oak-plank.jpg" />
  * </AspectRatio>
  * ```
  *
  * @bestPractice Give it exactly one child and let it fill - set the media to `size-full object-cover`; `AspectRatio` sizes to the available width and derives height from `ratio`.
  * @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 Show a material, swatch or sample at the default 1:1 - never landscape. A sample is cut square, and a wide crop reads as room photography; set a wide `ratio` only for a scene, an interior or video.
+ * @keywords material image, swatch image, sample image, thumbnail, square, image ratio
  * @category layout
  */
 const AspectRatio = ({ as, className, ratio = DEFAULT_RATIO, ref, render, style, ...props }) => {

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

@@ -15,7 +15,7 @@ export interface AvatarBadgeProps {
     dot?: boolean | Tone;
     /** Cap above which the count renders as `{max}+`. @default 99 */
     max?: number;
-    /** @default "top-right" */
+    /** Which corner of the avatar the badge overlaps. @default "top-right" */
     position?: "bottom-right" | "top-right" | "bottom-left" | "top-left";
     /** Component size */
     size?: ComponentSize;

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

@@ -4,7 +4,7 @@ import type { AvatarSize } from "../avatar/avatar-root.js";
 export type AvatarFallbackProps = Omit<AvatarPrimitive.Fallback.Props, "style"> & {
     /** Inline styles merged over the derived colours; a plain object only. */
     style?: React.CSSProperties | undefined;
-    /** @default "base" */
+    /** Initials text size; set it to the same `size` as the parent `AvatarRoot`, as it does not inherit it. At `2xs` and `xs` only one initial shows. @default "base" */
     size?: AvatarSize | undefined;
     /**
      * Full name or label used to:

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

@@ -19,7 +19,7 @@ export declare const AVATAR_SIZE_CLASS: Record<AvatarSize, string>;
  */
 export declare const AVATAR_SIZE_PX: Record<AvatarSize, number>;
 export type AvatarRootProps = AvatarPrimitive.Root.Props & {
-    /** @default "base" */
+    /** Avatar width and height, `2xs` (20px) to `6xl` (128px). Inside an `AvatarGroup`, the group's `size` wins. @default "base" */
     size?: AvatarSize | undefined;
     /** Border radius. Defaults to "full" (circular). */
     radius?: Radius | undefined;

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

@@ -4,10 +4,11 @@ export type AvatarStatusType = "online" | "offline" | "busy" | "away" | "dnd";
 export interface AvatarStatusProps {
     /** CSS class name */
     className?: string;
-    /** @default "bottom-right" */
+    /** Which corner of the avatar the dot sits in. @default "bottom-right" */
     position?: "bottom-right" | "top-right" | "bottom-left" | "top-left";
     /** Component size */
     size?: ComponentSize;
+    /** Presence shown by the dot colour: `online` green, `away` and `busy` amber (the same colour), `dnd` red, `offline` muted grey. */
     status: AvatarStatusType;
     /** Ring separating the dot from the avatar. @default true */
     withBorder?: boolean;

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

@@ -5,6 +5,7 @@ declare const badgeButtonVariants: (props?: ({
     variant?: "default" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface BadgeButtonProps extends useRender.ComponentProps<"button">, VariantProps<typeof badgeButtonVariants> {
+    /** Element shown when no `children` are given, an X icon unless replaced; an icon-only button needs an `aria-label`. */
     icon?: React.ReactNode;
 }
 /**

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

@@ -10,6 +10,7 @@ const badgeButtonVariants = cva("-me-0.5 inline-flex cursor-pointer items-center
         variant: "default",
     },
     variants: {
+        /** Button style; `default` is the only one, so leave it unset. @default "default" */
         variant: {
             default: "",
         },

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

@@ -18,13 +18,15 @@ export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement>, Omit<V
      * `{ base: "sm", md: "lg" }`. Forwarded to the underlying Pill. @default "base"
      */
     size?: ResponsiveValue<PillSize>;
+    /** Dims the badge to half opacity and stops it receiving pointer events. */
     disabled?: boolean;
     /** Force focus ring display (for documentation/testing) */
     focused?: boolean;
     /** Force hover state display (for documentation/testing) */
     hovered?: boolean;
+    /** Icon component (not an element) drawn beside the text, sized to match the badge. Replaced by a spinner while `loading`. */
     icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
-    /** @default "start" */
+    /** Which side of the text `icon` sits on. @default "start" */
     iconPlacement?: "start" | "end";
     /** Left segment of a split badge; renders a divider before `value`. */
     label?: string;
@@ -32,6 +34,7 @@ export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement>, Omit<V
     loading?: boolean;
     /** Label shown during loading */
     loadingLabel?: string;
+    /** Sets `data-testid` on the badge. Lower-case `testid`, unlike the `testId` prop on other components. */
     testid?: string;
     /** Right (emphasised) segment; shown alone when no `label` is set. */
     value?: string;

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

@@ -9,6 +9,7 @@ import type * as React from "react";
  * @category navigation
  */
 declare const Breadcrumb: ({ ...props }: React.ComponentProps<"nav"> & {
+    /** Not used by `Breadcrumb`: set the divider by passing children to each `BreadcrumbSeparator` instead. */
     separator?: React.ReactNode;
 }) => React.JSX.Element;
 /**

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

@@ -327,11 +327,13 @@ const buttonVariants = cva([
         // drift from ButtonTone/ButtonEmphasis (declared below).
         // Danger fades only to /95 on hover: a lighter red under the light
         // foreground and the sheen drops below 4.5:1 at /90.
+        /** Semantic colour: `brand` for the primary action, `danger` for a destructive one. @default "neutral" */
         tone: {
             neutral: "",
             brand: "border-brand-accent/40 bg-brand text-brand-foreground focus-visible:ring-brand/25 data-[focused=true]:ring-brand/25",
             danger: "border-destructive bg-destructive text-destructive-foreground hover:bg-destructive/95 data-[hovered=true]:bg-destructive/95 focus-visible:ring-red-400/50 data-[focused=true]:ring-red-400/50",
         },
+        /** Visual weight, paired with `tone`: `solid` and `soft` are filled, `outline` and `ghost` lighter, `transparent` a blurred translucent fill, `link` plain text. @default "solid" */
         emphasis: {
             solid: "",
             soft: "",
@@ -340,21 +342,26 @@ const buttonVariants = cva([
             transparent: "transform-gpu backdrop-blur-md will-change-[filter,background-color] before:hidden",
             link: "",
         },
+        /** Style the button as a form field (input background and border), for a trigger that opens a picker. @default false */
         asInput: {
             true: "border-border bg-input text-foreground hover:bg-input/90 data-[hovered=true]:bg-input/90 before:hidden",
             false: "",
         },
+        /** Corner shape: `full` is a pill (or circle when square), `rounded` a soft corner, `square` sharp. @default "full" */
         radius: RADIUS_CLASSES,
         size: BUTTON_SIZE_CLASSES,
+        /** Where the content sits along the button; `start` or `end` only shows on a button wider than its content. @default "center" */
         align: {
             center: "justify-center",
             start: "justify-start",
             end: "justify-end",
         },
+        /** Shrink slightly while held down (`:active`); `false` keeps the button still. @default true */
         pressed: {
             true: "active:scale-[0.97]",
             false: "",
         },
+        /** Lock width to height so an `icon-*` size draws a square or circle; ignored with `expandable`. @default false */
         square: {
             true: "",
             false: "",

package/dist/components/button-group/button-group-root.js

@@ -89,6 +89,7 @@ const buttonGroupVariants = cva("flex w-fit items-stretch *:focus-visible:relati
         variant: "joined",
     },
     variants: {
+        /** Group style: `joined` lets each child draw its own border and merges the shared edges; `segmented` draws one bordered, shadowed container around the children. @default "joined" */
         variant: {
             /**
              * Default "joined" behaviour - relies on each child for borders/background,
@@ -101,15 +102,18 @@ const buttonGroupVariants = cva("flex w-fit items-stretch *:focus-visible:relati
              */
             segmented: "border-border bg-card isolate overflow-hidden border shadow-xs [&>[data-slot=button-group-text]]:border-0 [&>[data-slot=button-group-text]]:shadow-none [&>[data-slot=select-trigger]]:border-0 [&>[data-slot=select-trigger]]:shadow-none",
         },
+        /** Direction the children are laid out: `horizontal` in a row, `vertical` in a column. @default "horizontal" */
         orientation: {
             horizontal: "flex-row [&>*:not(:first-child)]:rounded-l-none [&>*:not(:last-child)]:rounded-r-none",
             vertical: "flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:last-child)]:rounded-b-none",
         },
+        /** Outer corners of the group: only the first and last child are rounded, the inner edges stay square. `segmented` rounds the container too. @default "full" */
         radius: {
             rounded: "",
             square: "",
             full: "",
         },
+        /** Draw a line between children. Defaults on for the `segmented` variant and off for `joined`. */
         dividers: {
             true: "",
             false: "",

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

@@ -8,6 +8,7 @@ declare const cardVariants: (props?: ({
     variant?: "accent" | "card" | "ghost" | "muted" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface CardProps extends WithTestId<React.ComponentProps<"div">>, VariantProps<typeof cardVariants> {
+    /** Outline: `none` draws no border, `solid` a 1px border, `dashed` a faint dashed one for placeholder or drop areas. @default "none" */
     border?: BorderStyle;
     /**
      * Padding around the card's `CardHeader` and `CardContent`, and the gap

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

@@ -9,6 +9,7 @@ const cardVariants = cva("text-card-foreground flex flex-col gap-(--card-inset)
         variant: "card",
     },
     variants: {
+        /** Surface: `card` is the standard card fill, `muted` and `accent` are tinted fills, `ghost` has no fill or shadow. @default "card" */
         variant: {
             card: "bg-card shadow-sm",
             muted: "bg-muted shadow-sm",

package/dist/components/checkbox-card/checkbox-card-root.d.ts

@@ -18,7 +18,7 @@ export interface CheckboxCardGroupProps extends Omit<React.ComponentProps<"div">
     required?: boolean;
     /** Show the checkbox indicator on each item. @default true */
     showIndicator?: boolean;
-    /** @default "base" */
+    /** Padding, corner radius and icon size of every card in the group; items read it from context. @default "base" */
     size?: ComponentSize;
 }
 /**

package/dist/components/checkbox-field/checkbox-field-root.d.ts

@@ -6,10 +6,13 @@ export type CheckboxFieldProps = Omit<CheckboxProps, "size"> & {
     label: React.ReactNode;
     /** Optional helper text below the label; wired to the checkbox via `aria-describedby`. */
     description?: React.ReactNode;
-    /** @default "xs" */
+    /** Checkbox size; only `xs` and `sm` are allowed. @default "xs" */
     size?: Extract<ComponentSize, "xs" | "sm">;
+    /** Extra classes for the checkbox itself; `className` styles the outer field row. */
     checkboxClassName?: string;
+    /** Extra classes for the label text. */
     labelClassName?: string;
+    /** Extra classes for the description text; only applied when `description` is set. */
     descriptionClassName?: string;
 };
 /**

package/dist/components/context-menu/context-menu-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 ContextMenuCheckboxItem: (props: import("../menu-parts.js").MenuCheckboxItemProps) => React.JSX.Element;
+declare const ContextMenuCheckboxItem: (props: import("../menu-parts-types.js").MenuCheckboxItemProps) => React.JSX.Element;
 export { ContextMenuCheckboxItem };

package/dist/components/context-menu/context-menu-content.d.ts

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

package/dist/components/context-menu/context-menu-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 ContextMenuItem: (props: import("../menu-parts.js").MenuItemPartProps) => React.JSX.Element;
+declare const ContextMenuItem: (props: import("../menu-parts-types.js").MenuItemPartProps) => React.JSX.Element;
 export { ContextMenuItem };

package/dist/components/context-menu/context-menu-radio-item.d.ts

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

package/dist/components/context-menu/context-menu-separator.d.ts

@@ -1,3 +1,3 @@
-/** Horizontal divider between groups of menu items. `spacing="compact"` tightens the vertical gap. */
-declare const ContextMenuSeparator: (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 ContextMenuSeparator: (props: import("../menu-parts-types.js").MenuSeparatorProps) => React.JSX.Element;
 export { ContextMenuSeparator };

package/dist/components/context-menu/context-menu-separator.js

@@ -1,5 +1,5 @@
 "use client";
 import { contextMenuParts } from "./context-menu-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 ContextMenuSeparator = contextMenuParts.Separator;
 export { ContextMenuSeparator };

package/dist/components/context-menu/context-menu-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 ContextMenuSubTrigger: (props: import("../menu-parts.js").MenuSubTriggerProps) => React.JSX.Element;
+declare const ContextMenuSubTrigger: (props: import("../menu-parts-types.js").MenuSubTriggerProps) => React.JSX.Element;
 export { ContextMenuSubTrigger };

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

@@ -46,6 +46,7 @@ const dotVariants = cva("inline-block shrink-0 rounded-full", {
     },
     variants: {
         // Lockstep: Dot's tone is the full canonical Tone vocabulary.
+        /** Semantic colour: `success`, `warning`, `danger` and `info` for status, `brand` for the accent, `neutral` for a muted grey. Ignored when `color` is set. @default "neutral" */
         tone: DOT_TONE_BG_CLASSES,
     },
 });

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

@@ -20,6 +20,7 @@ export declare const DrawerContext: import("react").Context<DrawerContextValue>;
  * @category overlays
  */
 export declare const Drawer: ({ container, ...props }: ComponentProps<typeof DrawerPrimitive.Root> & {
+    /** Element the drawer and its scrim portal into, bounding them to that element instead of the page. Omit to portal to the document body. */
     container?: HTMLElement | null;
 }) => import("react").JSX.Element;
 export {};

package/dist/components/dropdown-menu/dropdown-menu-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 DropdownMenuCheckboxItem: (props: import("../menu-parts.js").MenuCheckboxItemProps) => React.JSX.Element;
+declare const DropdownMenuCheckboxItem: (props: import("../menu-parts-types.js").MenuCheckboxItemProps) => React.JSX.Element;
 export { DropdownMenuCheckboxItem };

package/dist/components/dropdown-menu/dropdown-menu-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 DropdownMenuContent: (props: import("../menu-parts.js").MenuContentProps) => React.JSX.Element;
+declare const DropdownMenuContent: (props: import("../menu-parts-types.js").MenuContentProps) => React.JSX.Element;
 export { DropdownMenuContent };

package/dist/components/dropdown-menu/dropdown-menu-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 DropdownMenuItem: (props: import("../menu-parts.js").MenuItemPartProps) => React.JSX.Element;
+declare const DropdownMenuItem: (props: import("../menu-parts-types.js").MenuItemPartProps) => React.JSX.Element;
 export { DropdownMenuItem };

package/dist/components/dropdown-menu/dropdown-menu-radio-item.d.ts

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

package/dist/components/dropdown-menu/dropdown-menu-separator.d.ts

@@ -1,3 +1,3 @@
-/** Horizontal divider between groups of menu items. `spacing="compact"` tightens the vertical gap. */
-declare const DropdownMenuSeparator: (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 DropdownMenuSeparator: (props: import("../menu-parts-types.js").MenuSeparatorProps) => React.JSX.Element;
 export { DropdownMenuSeparator };

package/dist/components/dropdown-menu/dropdown-menu-separator.js

@@ -1,5 +1,5 @@
 "use client";
 import { dropdownMenuParts } from "./dropdown-menu-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 DropdownMenuSeparator = dropdownMenuParts.Separator;
 export { DropdownMenuSeparator };

package/dist/components/dropdown-menu/dropdown-menu-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 DropdownMenuSubTrigger: (props: import("../menu-parts.js").MenuSubTriggerProps) => React.JSX.Element;
+declare const DropdownMenuSubTrigger: (props: import("../menu-parts-types.js").MenuSubTriggerProps) => React.JSX.Element;
 export { DropdownMenuSubTrigger };

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

@@ -26,6 +26,7 @@ const emptyVariants = cva("", {
         size: "base",
     },
     variants: {
+        /** Scale of the whole empty state: the title, description and icon sizes, the gaps, and the vertical padding in the `card` layouts. @default "base" */
         size: {
             sm: "",
             base: "",

package/dist/components/expand-button/expand-button-root.js

@@ -11,6 +11,7 @@ const expandButtonVariants = cva(cn(focusRing(), `group inline-flex shrink-0 ite
         size: "sm",
     },
     variants: {
+        /** Square button edge and icon size, `2xs` (14px) to `3xl` (32px). Smaller than a `Button` of the same size, so it suits dense rows. @default "sm" */
         size: SQUARE_CONTROL_SIZE_CLASSES,
     },
 });

package/dist/components/field/field-error.d.ts

@@ -18,6 +18,7 @@
  * ```
  */
 export declare const FieldError: ({ className, children, errors, id, ...props }: React.ComponentProps<"div"> & {
+    /** Validation errors to show: one renders as plain text, several as a bulleted list. Duplicate messages collapse; ignored when `children` is set. */
     errors?: ({
         message?: string;
     } | undefined)[];

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

@@ -9,6 +9,7 @@ export const fieldVariants = cva("group/field data-[invalid=true]:text-destructi
         orientation: "vertical",
     },
     variants: {
+        /** How label and control are arranged: `vertical` stacks them, `horizontal` puts them in a row, `responsive` stacks until the enclosing `FieldGroup` reaches its `md` container width, then switches to a row (needs a `FieldGroup` ancestor). @default "vertical" */
         orientation: {
             vertical: ["flex-col *:w-full [&>.sr-only]:w-auto"],
             horizontal: [

package/dist/components/icon-box/icon-box-root.js

@@ -35,6 +35,7 @@ const iconBoxVariants = cva("flex shrink-0 items-center justify-center border bo
         tone: "neutral",
     },
     variants: {
+        /** Box width and height, `2xs` (16px) to `3xl` (96px); the icon and corner radius scale with it. @default "base" */
         size: {
             "2xs": "size-4",
             xs: "size-6",
@@ -52,6 +53,7 @@ const iconBoxVariants = cva("flex shrink-0 items-center justify-center border bo
         // former `primary` dark look is retired. `muted`/`secondary` collapsed
         // onto `neutral` (muted → neutral+soft compound above; secondary →
         // neutral).
+        /** Semantic colour of the icon and its tinted surface: `brand` for the accent, `danger`, `warning`, `success` and `info` for status, `neutral` for everything else. @default "neutral" */
         tone: {
             neutral: "bg-accent text-foreground",
             brand: "bg-brand text-brand-foreground",
@@ -60,12 +62,14 @@ const iconBoxVariants = cva("flex shrink-0 items-center justify-center border bo
             success: "bg-affirmative-soft text-affirmative-foreground dark:bg-affirmative-soft/20 dark:text-affirmative-accent",
             info: "bg-info-soft text-info-foreground dark:bg-info-soft/20 dark:text-info-accent",
         },
+        /** Surface fill: `solid` is the tinted fill, `soft` the same except `neutral` takes the muted fill, `outline` a border with no fill, `ghost` neither. The icon keeps the tone's colour in every case. @default "solid" */
         emphasis: {
             solid: "",
             soft: "",
             outline: "border-border bg-transparent",
             ghost: "border-transparent bg-transparent",
         },
+        /** Corner shape: `rounded` scales with `size`, `square` has sharp corners, `full` is a circle. @default "rounded" */
         radius: RADIUS_CLASSES,
     },
 });

package/dist/components/identified-surface.d.ts

@@ -4,12 +4,17 @@ export interface IdentifiedSurfaceFrameProps {
     className?: string;
     /** Reveals the complete frame while a related control is hovered or focused. */
     highlighted?: boolean;
+    /** Name of the identified object, shown in the label pill. The label appears only while `highlighted` or `active`. */
     label: string;
+    /** Which edge of the frame the label lines up with: `start` the left, `end` the right, `center` centred. @default "center" */
     labelAlign?: "center" | "end" | "start";
+    /** Whether the label sits above or below the frame. @default "above" */
     labelPlacement?: "above" | "below";
     /** Keeps the complete evidence boundary visible before interaction. */
     persistentFrame?: boolean;
+    /** Smaller grey text after `label`, such as a code or category; truncated to a short width. */
     secondaryLabel?: string | undefined;
+    /** Image URL for a small round thumbnail at the start of the label. Decorative, so it carries empty alt text. */
     thumbnailUrl?: string | null | undefined;
 }
 /**

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

@@ -35,6 +35,7 @@ export const standaloneInputVariants = cva("border-border bg-input selection:bg-
     },
     variants: {
         // Input radius is 8px (Figma rounded-md), not the shared 10px `rounded-lg`.
+        /** Corner shape: `rounded` is the standard 8px radius, `square` has sharp corners, `full` is a pill. @default "rounded" */
         radius: {
             full: "rounded-full",
             rounded: "rounded-md",

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

@@ -15,8 +15,11 @@ declare const INPUT_CARD_ICON_SIZE: Record<ComponentSize, ComponentSize>;
 declare const getInputCardIconSize: (cardSize: ComponentSize) => ComponentSize;
 interface InputCardIconProps {
     className?: string;
+    /** Icon component (not an element) to draw. */
     icon: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
+    /** Tints the icon with the primary colour instead of muted. */
     selected?: boolean;
+    /** Size of the parent card, not of the icon: the icon renders smaller than the card (`xs` at `base`). */
     size: ComponentSize;
 }
 /** Renders an icon for InputCard with proper sizing and selection state styling */

package/dist/components/input-group/input-group-button.d.ts

@@ -1,14 +1,18 @@
 import type { LucideIcon } from "lucide-react";
 import type * as React from "react";
-import type { ButtonEmphasis, ButtonTone } from "../button.js";
+import type { ButtonEmphasis, ButtonProps, ButtonTone } from "../button.js";
 import { Button } from "../button.js";
 export type InputGroupButtonProps = Omit<React.ComponentProps<typeof Button>, "size"> & {
     /** Icon to display. */
     icon?: LucideIcon | React.ComponentType<React.SVGProps<SVGSVGElement>>;
-    /** Button tone. */
+    /** Semantic colour, as on Button. @default "neutral" */
     tone?: ButtonTone;
-    /** Button emphasis. */
+    /** Visual weight, as on Button; ghost keeps the button quiet inside the field. @default "ghost" */
     emphasis?: ButtonEmphasis;
+    /** Corner shape; leave unset - the corners follow the InputGroup's `radius`, tighter inside the field. */
+    radius?: ButtonProps["radius"];
+    /** Square by default, as an icon button sized from the InputGroup. @default true */
+    square?: ButtonProps["square"];
 };
 /**
  * Button element for use inside InputGroup.

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

@@ -12,6 +12,7 @@ const itemGroupVariants = cva("group/item-group flex flex-col", {
         variant: "divided",
     },
     variants: {
+        /** List style: `divided` is plain rows with lines between, `separated` makes each item its own card with a gap, `grouped` joins the items inside one bordered card. @default "divided" */
         variant: {
             divided: "divide-border divide-y",
             separated: "gap-3",