themelia-ui 2.0.0 → 3.0.0

package/dist/components/base/choice-inputs/card-checkbox-group.d.ts

@@ -1,11 +1,19 @@
 import { ChoiceColumns, ChoiceGroupBaseProps, ChoiceOption } from './choice.types.js';
 export type CardCheckboxOption = ChoiceOption;
 export interface CardCheckboxGroupProps extends ChoiceGroupBaseProps {
+    /** The choices, in the shape `CardRadioGroup` takes. */
     options: CardCheckboxOption[];
     /** Controlled value. */
     value?: string[];
+    /** The initial values, for uncontrolled selection. */
     defaultValue?: string[];
+    /** Called with every chosen value. */
     onValueChange?: (values: string[]) => void;
+    /** Column count at full width, as on `CardRadioGroup`. */
     columns?: ChoiceColumns;
 }
+/**
+ * The same cards as `CardRadioGroup` for a multiple choice: takes and returns an array of
+ * values.
+ */
 export declare const CardCheckboxGroup: import('react').ForwardRefExoticComponent<CardCheckboxGroupProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/base/choice-inputs/card-radio-group.d.ts

@@ -1,12 +1,26 @@
 import { ChoiceColumns, ChoiceGroupBaseProps, ChoiceOption } from './choice.types.js';
 export type CardRadioOption = ChoiceOption;
 export interface CardRadioGroupProps extends ChoiceGroupBaseProps {
+    /**
+     * The choices, in the one shape card, list and pill groups share: value, label,
+     * description, icon, and an optional tooltip.
+     */
     options: CardRadioOption[];
     /** Controlled value. */
     value?: string;
+    /** The initial value, for uncontrolled selection. */
     defaultValue?: string;
+    /** Called with the chosen value. */
     onValueChange?: (value: string) => void;
-    /** Column count at full width. The grid steps down on narrow containers. */
+    /**
+     * Column count at full width: the track floor, not a fixed count — the grid still steps
+     * down on its own container's width. Pick it from how much each card has to say.
+     * @default 3
+     */
     columns?: ChoiceColumns;
 }
+/**
+ * Single-select as a grid of cards: a title, an optional description, an icon and a
+ * tooltip. `CardCheckboxGroup` is its multi-select twin.
+ */
 export declare const CardRadioGroup: import('react').ForwardRefExoticComponent<CardRadioGroupProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/base/choice-inputs/checkbox.d.ts

@@ -1,7 +1,17 @@
 import * as React from "react";
-export interface CheckboxProps extends Omit<React.ComponentProps<"input">, "type" | "size"> {
+export interface CheckboxProps extends Omit<React.ComponentProps<"input">, "type" | "size">, Pick<React.ComponentProps<"input">, "checked" | "defaultChecked" | "onChange"> {
+    /** Rendered beside the box and wired to it, so the text is part of the target. */
     label?: React.ReactNode;
-    /** Partially-selected: neither on nor off. Outranks `checked` visually. */
+    /**
+     * The dash state, for a parent whose children are partly checked: neither on nor off.
+     * Independent of `checked`, which it outranks visually.
+     */
     indeterminate?: boolean;
 }
+/**
+ * A native checkbox under the kit's styling, so form, keyboard and label behaviour are the
+ * platform's. `checked` and `defaultChecked` are its controlled and uncontrolled state, and
+ * `onChange` receives the native change event: read `event.target.checked` for the next
+ * state.
+ */
 export declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/components/base/choice-inputs/list-radio-group.d.ts

@@ -1,10 +1,20 @@
 import { ChoiceGroupBaseProps, ChoiceOption } from './choice.types.js';
 export type ListRadioOption = ChoiceOption;
 export interface ListRadioGroupProps extends ChoiceGroupBaseProps {
+    /**
+     * The choices, in the one shape card, list and pill groups share: value, label,
+     * description, icon, and an optional tooltip.
+     */
     options: ListRadioOption[];
     /** Controlled value. */
     value?: string;
+    /** The initial value, for uncontrolled selection. */
     defaultValue?: string;
+    /** Called with the chosen value. */
     onValueChange?: (value: string) => void;
 }
+/**
+ * Single-select as a divided vertical list, for options with a descriptive second line —
+ * plan tiers, roles. The same component as `CardRadioGroup`, laid out another way.
+ */
 export declare const ListRadioGroup: import('react').ForwardRefExoticComponent<ListRadioGroupProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/base/choice-inputs/pill-radio-group.d.ts

@@ -1,13 +1,25 @@
 import { ChoiceGroupBaseProps, ChoiceOption } from './choice.types.js';
 export type PillRadioOption = ChoiceOption;
 export interface PillRadioGroupProps extends ChoiceGroupBaseProps {
+    /**
+     * The choices, in the one shape card, list and pill groups share. A pill shows no
+     * description — it has no room for one.
+     */
     options: PillRadioOption[];
     /** Controlled value. `null` is the cleared state. */
     value: string | null | undefined;
+    /** Called with the chosen value, or `null` when the selection is cleared. */
     onValueChange: (value: string | null) => void;
-    /** Lets the active pill be clicked again to clear the selection. */
+    /**
+     * Lets the active pill be clicked again to clear the selection, for a filter whose empty
+     * state is "all".
+     */
     allowClear?: boolean;
-    /** Stretches the pills to fill the container. */
+    /** Stretches the pills to fill the container, for a segmented control that owns its row. */
     fullWidth?: boolean;
 }
+/**
+ * A compact single-select of connected pills, for two to four short options — a timeframe,
+ * a view mode. A hidden input submits the value.
+ */
 export declare const PillRadioGroup: import('react').ForwardRefExoticComponent<PillRadioGroupProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/base/choice-inputs/radio.d.ts

@@ -1,11 +1,23 @@
 import * as React from "react";
-export interface RadioProps extends Omit<React.ComponentProps<"input">, "type" | "size"> {
+export interface RadioProps extends Omit<React.ComponentProps<"input">, "type" | "size">, Pick<React.ComponentProps<"input">, "value" | "checked" | "defaultChecked" | "onChange"> {
+    /** Rendered beside the circle and wired to it, so the text is part of the target. */
     label?: React.ReactNode;
 }
+/**
+ * One option: a native radio under the kit's styling. `checked` and `defaultChecked` are
+ * its controlled and uncontrolled selection, and the group supplies the shared `name`.
+ * `onChange` receives the native input event: read `event.target.value` for the selected
+ * value.
+ */
 export declare const Radio: React.ForwardRefExoticComponent<Omit<RadioProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
 export interface RadioGroupProps extends Omit<React.ComponentProps<"div">, "onChange"> {
-    /** Shared across every radio inside, which is what makes them exclusive. */
+    /**
+     * Groups the options: shared across every radio inside, which is what makes them
+     * exclusive. A native radio group needs it to behave as one.
+     */
     name: string;
+    /** The direction the options run in. */
     orientation?: "vertical" | "horizontal";
 }
+/** Radios that exclude each other. The group supplies the shared `name` that does it. */
 export declare function RadioGroup({ name, orientation, className, children, ...props }: RadioGroupProps): React.JSX.Element;

package/dist/components/base/choice-inputs/select-popup.d.ts

@@ -7,13 +7,31 @@ export type SelectPopupContentProps = SelectPrimitive.Popup.Props & Pick<SelectP
      */
     container?: UIPortalContainer;
 };
+/**
+ * The popup behind `Select`, public so every finite-option control — a phone country, a unit
+ * picker — renders the same popup and rows.
+ */
 export declare function SelectPopupContent({ container, className, children, side, sideOffset, align, alignOffset, alignItemWithTrigger, ...props }: SelectPopupContentProps): import("react").JSX.Element;
+/** A division of the popup's options. */
 export declare function SelectPopupGroup({ className, ...props }: SelectPrimitive.Group.Props): import("react").JSX.Element;
+/** One option row, with the mark that shows it is chosen. */
 export declare function SelectPopupItem({ className, children, ...props }: SelectPrimitive.Item.Props): import("react").JSX.Element;
+/**
+ * A group's caption. A label is not an item: it is not focusable and the arrow keys skip it,
+ * which a styled item would get wrong.
+ */
 export declare function SelectPopupLabel({ className, children, ...props }: SelectPrimitive.GroupLabel.Props): import("react").JSX.Element;
+/** A rule between groups of options. */
 export declare function SelectPopupSeparator({ className, ...props }: SelectPrimitive.Separator.Props): import("react").JSX.Element;
-/** The primitives, for a control that needs the state engine but not this presentation. */
+/**
+ * The unassembled root behind `Select`. Reach for these parts when the trigger has to be
+ * something `Select` cannot express — an avatar and a name, a swatch, two lines — and keep
+ * the popup and the keyboard behaviour rather than rebuilding them.
+ */
 export declare const SelectRoot: typeof SelectPrimitive.Root;
+/** The unassembled trigger behind `Select`, for a trigger `Select` cannot express. */
 export declare const SelectTriggerPrimitive: import('react').ForwardRefExoticComponent<Omit<import('@base-ui/react').SelectTriggerProps, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;
+/** The unassembled value behind `Select`: what the trigger shows for the current choice. */
 export declare const SelectValuePrimitive: import('react').ForwardRefExoticComponent<Omit<import('@base-ui/react').SelectValueProps, "ref"> & import('react').RefAttributes<HTMLSpanElement>>;
+/** The unassembled icon behind `Select`: the trigger's chevron. */
 export declare const SelectIconPrimitive: import('react').ForwardRefExoticComponent<Omit<import('@base-ui/react').SelectIconProps, "ref"> & import('react').RefAttributes<HTMLSpanElement>>;

package/dist/components/base/choice-inputs/select.d.ts

@@ -10,54 +10,95 @@ export interface SelectOption {
     disabled?: boolean;
 }
 export interface SelectProps {
+    /** The choices. Each carries a value, a label, and an optional description and icon. */
     options: SelectOption[];
-    /** Shorthand for `strings.placeholder`. */
+    /** Shown while nothing is selected. Shorthand for `strings.placeholder`, and wins over it. */
     placeholder?: string;
     /** Overrides this select's own copy — the placeholder and the clear row. */
     strings?: Partial<SelectStrings>;
-    /** Prepends an option that clears the selection. */
+    /**
+     * Prepends an option that clears the selection, for a field whose empty state is a real
+     * answer.
+     */
     allowClear?: boolean;
-    /** Applies the invalid treatment. Pair it with a message on the FormField. */
+    /**
+     * Applies the invalid treatment; the trigger only carries it. Pair it with a message on the
+     * `FormField`.
+     */
     invalid?: boolean;
     /** Controlled value. Passing `undefined` explicitly keeps it controlled and clear. */
     value?: string | null;
+    /** The initial value, for an uncontrolled select. */
     defaultValue?: string | null;
     /** Fires with `undefined` when the selection is cleared. */
     onValueChange?: (value: string | undefined) => void;
     disabled?: boolean;
+    /** Shows the value but prevents choosing another. */
     readOnly?: boolean;
+    /** Requires a value before the owning form submits. */
     required?: boolean;
     /** Field name for the hidden native input. */
     name?: string;
-    /** The owning form's id, when the select renders outside it. */
+    /**
+     * The owning form's id, when the select renders outside it. Like `name`, `autoComplete` and
+     * `inputRef`, it is for the hidden native input that carries the value into a form submit.
+     */
     form?: string;
+    /** Autofill hint for the hidden native input that carries the value into a form submit. */
     autoComplete?: string;
     /** Ref to the hidden native input used for submission. */
     inputRef?: Ref<HTMLInputElement>;
     id?: string;
+    /**
+     * Whether the popup is open, for a select driven from outside — a tour, a keyboard
+     * shortcut.
+     */
     open?: boolean;
+    /** Whether the popup starts open, uncontrolled. */
     defaultOpen?: boolean;
+    /** Called when the popup opens or closes. */
     onOpenChange?: (open: boolean) => void;
-    /** Isolates interaction with the rest of the page while open. */
+    /**
+     * Isolates interaction with the rest of the page while open. Turn it off for a select
+     * inside a surface that is already modal.
+     * @default true
+     */
     modal?: boolean;
-    /** Pointer movement highlights options. */
+    /**
+     * Pointer movement highlights options. Off, the highlight belongs to the keyboard alone.
+     * @default true
+     */
     highlightItemOnHover?: boolean;
-    /** Where the popup opens relative to the trigger. */
+    /**
+     * Where the popup opens relative to the trigger.
+     * @default "bottom"
+     */
     side?: SelectPopupContentProps["side"];
+    /**
+     * How the popup lines up with the trigger along that side.
+     * @default "start"
+     */
     align?: SelectPopupContentProps["align"];
     /**
-     * Positions the selected option over the trigger, macOS-style. Off by default: inside
-     * a form it covers the field's own label.
+     * Positions the chosen option over the trigger, the native macOS behaviour. Off, the list
+     * opens under the field: inside a form, a popup over the trigger covers the field's own
+     * label.
+     * @default false
      */
     alignItemWithTrigger?: boolean;
     /** Replaces the default icon/label/description row. */
     renderOption?: (option: SelectOption) => ReactNode;
-    /** Replaces the trigger's value. Receives `undefined` in the placeholder state. */
+    /**
+     * Replaces what the trigger shows — what a select of avatars needs. Receives `undefined` in
+     * the placeholder state.
+     */
     renderValue?: (option: SelectOption | undefined) => ReactNode;
     className?: string;
-    /** Class for the popup surface. */
+    /** Class for the popup surface. `className` stays on the trigger. */
     contentClassName?: string;
+    /** Called on the trigger, so a form library can track touched state. */
     onFocus?: FocusEventHandler<HTMLButtonElement>;
+    /** Called on the trigger, so a form library can track touched state. */
     onBlur?: FocusEventHandler<HTMLButtonElement>;
     "aria-label"?: string;
     "aria-labelledby"?: string;

package/dist/components/base/choice-inputs/switch-card.d.ts

@@ -3,4 +3,9 @@ export interface SwitchCardProps extends Omit<ToggleFieldProps, "kind" | "surfac
     /** Card title, and the switch's accessible name. */
     label: string;
 }
+/**
+ * The top-of-list feature switch: a bordered card with an icon, a title, an optional
+ * description and hint, and a trailing switch; the whole card toggles. A `ToggleField`
+ * preset with `surface="card"`, a switch, and an off value that still submits: `"0"`.
+ */
 export declare const SwitchCard: import('react').ForwardRefExoticComponent<SwitchCardProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/base/choice-inputs/switch.d.ts

@@ -3,7 +3,14 @@
  * native checkbox as Checkbox, refined with `role="switch"`.
  */
 import * as React from "react";
-export interface SwitchProps extends Omit<React.ComponentProps<"input">, "type" | "size"> {
+export interface SwitchProps extends Omit<React.ComponentProps<"input">, "type" | "size">, Pick<React.ComponentProps<"input">, "checked" | "defaultChecked" | "onChange"> {
+    /** Rendered beside the track and wired to it. */
     label?: React.ReactNode;
 }
+/**
+ * An immediate on/off; a checkbox means "include when I submit". The same hidden native
+ * checkbox as `Checkbox`, announced as a switch. `checked` and `defaultChecked` are its
+ * controlled and uncontrolled state, and `onChange` receives the native change event: read
+ * `event.target.checked` for the next state.
+ */
 export declare const Switch: React.ForwardRefExoticComponent<Omit<SwitchProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/components/base/choice-inputs/toggle-field.d.ts

@@ -2,13 +2,18 @@ import { ReactNode } from 'react';
 import { ChoiceOption } from './choice.types.js';
 export type ToggleFieldKind = "switch" | "checkbox";
 export interface ToggleFieldProps {
+    /** The row's label. */
     label: ReactNode;
+    /** The row's supporting sentence. */
     description?: ReactNode;
-    /** Short guidance under the description. */
+    /** Quieter, short guidance under the description. */
     hint?: ReactNode;
     /** Leading glyph, drawn in a medallion. Most at home on `surface="card"`. */
     icon?: ChoiceOption["icon"];
-    /** Which control renders. */
+    /**
+     * Which control renders: a checkbox for a preference that is saved with the form, a switch
+     * for state that applies immediately.
+     */
     kind?: ToggleFieldKind;
     /**
      * `row` is a plain settings row; `card` is a bordered card that takes the checked
@@ -17,9 +22,12 @@ export interface ToggleFieldProps {
     surface?: "row" | "card";
     /** Controlled state. */
     value?: boolean;
+    /** The initial state, uncontrolled. */
     defaultValue?: boolean;
+    /** Called with the next state. */
     onValueChange?: (checked: boolean) => void;
     disabled?: boolean;
+    /** The error surface. The message stays on the `FormField`. */
     invalid?: boolean;
     name?: string;
     /**
@@ -32,4 +40,9 @@ export interface ToggleFieldProps {
     controlPosition?: "leading" | "trailing";
     className?: string;
 }
+/**
+ * A clickable label-and-control row for a switch or a checkbox: a plain settings row, or with
+ * `surface="card"` a bordered card with an optional icon and hint. The whole row is the
+ * target.
+ */
 export declare const ToggleField: import('react').ForwardRefExoticComponent<ToggleFieldProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/base/combobox/combobox-filter.d.ts

@@ -1,2 +1,6 @@
 import { Combobox as ComboboxPrimitive } from '@base-ui/react/combobox';
+/**
+ * Locale-aware matchers from Base UI — `contains`, `startsWith` and the rest — for a caller
+ * filtering a list themselves who still wants the popup's rules about what counts as a match.
+ */
 export declare const useComboboxFilter: typeof ComboboxPrimitive.useFilter;

package/dist/components/base/combobox/combobox.d.ts

@@ -2,52 +2,86 @@ import { Combobox as ComboboxPrimitive } from '@base-ui/react/combobox';
 import { ReactNode } from 'react';
 import { ComboboxStrings } from './combobox.strings.js';
 /**
- * The Base UI combobox anatomy with the kit's surface applied — parts, not a recipe; the
- * searchable, single- and multi-select recipes compose them. Field parts carry
- * `data-field-control` / `data-field-shell`, matching Input, Textarea and Select.
+ * The state: Base UI's combobox root, holding `value` and `onValueChange`, `inputValue` and
+ * `onInputValueChange`, `items` and `multiple`. The parts around it are the Base UI anatomy
+ * with the kit's surface applied — parts, not a recipe; the searchable, single- and
+ * multi-select recipes compose them. Field parts carry `data-field-control` /
+ * `data-field-shell`, matching Input, Textarea and Select.
  */
 export declare const ComboboxRoot: typeof ComboboxPrimitive.Root;
-/** The popup's portal, routed through the nearest `UIPortalHost` like every kit popup. */
+/**
+ * The popup's portal, which escapes an ancestor that clips or transforms. Routed through the
+ * nearest `UIPortalHost` like every kit popup.
+ */
 export declare function ComboboxPortal({ container, ...props }: ComboboxPrimitive.Portal.Props): import("react").JSX.Element;
+/** The renderer that maps a list to items. */
 export declare const ComboboxCollection: typeof ComboboxPrimitive.Collection;
+/** The query field. */
 export declare function ComboboxInput({ className, ...props }: ComboboxPrimitive.Input.Props): import("react").JSX.Element;
 /**
- * The input with its trailing chevron and optional clear button, padded so text never
- * runs under them. `strings` names the two trailing controls.
+ * The input with its trailing chevron and optional clear button. Its trailing padding is
+ * computed from the same variables that size the controls, so text never runs under them.
  */
 export declare function ComboboxInputTrigger({ className, showClear, invalid, strings, ...props }: ComboboxPrimitive.Input.Props & {
+    /** Shows the clear button beside the chevron. */
     showClear?: boolean;
+    /** Applies the invalid treatment. */
     invalid?: boolean;
+    /** Names the two trailing controls: the clear button and the chevron. */
     strings?: Partial<Pick<ComboboxStrings, "clear" | "toggle">>;
 }): import("react").JSX.Element;
 /**
- * The whole field as one trigger — a select-like combobox with no free text. Pair it with
- * `ComboboxPopupInput`: Base UI drives the list's keyboard cursor from an input. For a
- * short list with no search, use `Select`.
+ * The whole field as one trigger, for a value that can only come from the list — a
+ * select-like combobox with no free text. Pair it with `ComboboxPopupInput`: Base UI drives
+ * the list's keyboard cursor from an input. For a short list with no search, use `Select`.
  */
 export declare function ComboboxTrigger({ className, children, ...props }: ComboboxPrimitive.Trigger.Props): import("react").JSX.Element;
 /**
- * The search band inside the popup, for the `ComboboxTrigger` shape: focus lands here when
- * the popup opens, typing filters the list, and the arrow keys and Enter drive it. Give it
- * an `aria-label` — its placeholder is not a name.
+ * The search band inside the popup, for a combobox opened from a button (`ComboboxTrigger`)
+ * rather than typed into: focus lands here when the popup opens, typing filters the list,
+ * and the arrow keys and Enter still move through the list below it. Give it an
+ * `aria-label` — its placeholder is not a name.
  */
 export declare function ComboboxPopupInput({ className, ...props }: ComboboxPrimitive.Input.Props): import("react").JSX.Element;
+/** The current selection, shown in a `ComboboxTrigger`. */
 export declare function ComboboxValue({ placeholder, ...props }: ComboboxPrimitive.Value.Props & {
     placeholder?: ReactNode;
 }): import("react").JSX.Element;
+/** The control that empties the field. */
 export declare function ComboboxClear({ className, children, ...props }: ComboboxPrimitive.Clear.Props): import("react").JSX.Element;
+/** Anchors the popup to the trigger, and flips it when there is no room below. */
 export declare function ComboboxPositioner({ className, sideOffset, ...props }: ComboboxPrimitive.Positioner.Props): import("react").JSX.Element;
+/**
+ * The list's surface, anchored to the field's width — unlike a dropdown menu, a listbox that
+ * does not line up with its field reads as a different control.
+ */
 export declare function ComboboxPopup({ className, ...props }: ComboboxPrimitive.Popup.Props): import("react").JSX.Element;
+/** The results. */
 export declare function ComboboxList({ className, ...props }: ComboboxPrimitive.List.Props): import("react").JSX.Element;
+/**
+ * A result row with a trailing selection check. Children go in the label slot. The same row
+ * the pickers render.
+ */
 export declare function ComboboxItem({ className, children, ...props }: ComboboxPrimitive.Item.Props): import("react").JSX.Element;
-/** The indicator on its own, for a row that lays its parts out differently. */
+/** The tick on a chosen item, on its own, for a row that lays its parts out differently. */
 export declare function ComboboxItemIndicator({ className, children, ...props }: ComboboxPrimitive.ItemIndicator.Props): import("react").JSX.Element;
+/**
+ * Renders only when a search returns nothing, so "no matches" never flashes before the first
+ * keystroke.
+ */
 export declare function ComboboxEmpty({ className, ...props }: ComboboxPrimitive.Empty.Props): import("react").JSX.Element;
 /** Async status — "Searching…", "12 of 340". Hidden while empty. */
 export declare function ComboboxStatus({ className, ...props }: ComboboxPrimitive.Status.Props): import("react").JSX.Element;
+/** A division of the results. */
 export declare function ComboboxGroup({ className, ...props }: ComboboxPrimitive.Group.Props): import("react").JSX.Element;
+/** A group's caption. */
 export declare function ComboboxGroupLabel({ className, ...props }: ComboboxPrimitive.GroupLabel.Props): import("react").JSX.Element;
+/** A rule between groups of results. */
 export declare function ComboboxSeparator({ className, ...props }: ComboboxPrimitive.Separator.Props): import("react").JSX.Element;
+/**
+ * The multi-select field: the container is the field, and the input sits among the chips so
+ * typing continues where the last selection ended.
+ */
 export declare function ComboboxChips({ className, invalid, ...props }: ComboboxPrimitive.Chips.Props & {
     invalid?: boolean;
 }): import("react").JSX.Element;
@@ -60,6 +94,9 @@ export declare function ComboboxChips({ className, invalid, ...props }: Combobox
 export declare function ComboboxChip({ className, children, strings, ...props }: ComboboxPrimitive.Chip.Props & {
     strings?: Partial<Pick<ComboboxStrings, "removeChip">>;
 }): import("react").JSX.Element;
+/** The query input among the chips, so typing continues where the last selection ended. */
 export declare function ComboboxChipsInput({ className, ...props }: ComboboxPrimitive.Input.Props): import("react").JSX.Element;
+/** A layer behind the open popup, part of its placement machinery. */
 export declare function ComboboxBackdrop({ className, ...props }: ComboboxPrimitive.Backdrop.Props): import("react").JSX.Element;
+/** An arrow pointing from the popup to its anchor, part of its placement machinery. */
 export declare function ComboboxArrow({ className, ...props }: ComboboxPrimitive.Arrow.Props): import("react").JSX.Element;

package/dist/components/base/command/command.d.ts

@@ -3,25 +3,44 @@ import { OverlayRootProps } from '../overlay/index.js';
 import { CommandStrings } from './command.strings.js';
 import * as React from "react";
 export type CommandProps = React.ComponentProps<typeof CommandPrimitive>;
+/** The command palette's root: filtering, keyboard navigation and the rows' shared state. */
 declare function Command({ className, ...props }: CommandProps): React.JSX.Element;
 export type CommandDialogProps = Omit<OverlayRootProps, "children"> & {
-    /** Shorthands for the matching `strings` key. */
+    /** Shorthand for `strings.title`: the palette's accessible name. */
     title?: string;
+    /** Shorthand for `strings.description`. */
     description?: string;
     /** Overrides this palette's own copy. All of it is hidden from view. */
     strings?: Partial<CommandStrings>;
-    /** Filtering, keyboard loop, and other cmdk root behavior. */
+    /**
+     * Configures the cmdk root the dialog owns: custom filtering, looping, labels, and other
+     * command behaviour.
+     */
     commandProps?: CommandProps;
     className?: string;
     showCloseButton?: boolean;
     children: React.ReactNode;
 };
+/**
+ * The palette as an overlay, opened and closed through `open` and `onOpenChange`. The
+ * caller binds the shortcut that opens it.
+ */
 declare function CommandDialog({ title, description, strings, commandProps, children, className, showCloseButton, ...props }: CommandDialogProps): React.JSX.Element;
+/** The filter. Owns focus when the palette opens. */
 declare function CommandInput({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Input>): React.JSX.Element;
+/** The scrolling list of results. */
 declare function CommandList({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.List>): React.JSX.Element;
+/** Shown when nothing matches. Not optional — a silent empty list reads as broken. */
 declare function CommandEmpty({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Empty>): React.JSX.Element;
-declare function CommandGroup({ className, ref, ...props }: React.ComponentProps<typeof CommandPrimitive.Group>): React.JSX.Element;
+/** A captioned block of rows. */
+declare function CommandGroup({ className, ref, ...props }: React.ComponentProps<typeof CommandPrimitive.Group> & Pick<React.ComponentProps<typeof CommandPrimitive.Group>, "heading">): React.JSX.Element;
+/**
+ * The rule between groups. Presentational and skipped by the keyboard, so arrowing through
+ * results never lands on it.
+ */
 declare function CommandSeparator({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Separator>): React.JSX.Element;
-declare function CommandItem({ className, children, ref, ...props }: React.ComponentProps<typeof CommandPrimitive.Item>): React.JSX.Element;
+/** A row. Its `value` is what the filter matches; its label is what is read. */
+declare function CommandItem({ className, children, ref, ...props }: React.ComponentProps<typeof CommandPrimitive.Item> & Pick<React.ComponentProps<typeof CommandPrimitive.Item>, "value" | "onSelect">): React.JSX.Element;
+/** The key hint at the end of a row. */
 declare function CommandShortcut({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
 export { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandShortcut, CommandSeparator, };

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

@@ -3,11 +3,21 @@ import { Menu as MenuPrimitive } from '@base-ui/react/menu';
 import { DropdownMenuCheckboxItem, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger } from '../dropdown-menu/index.js';
 import { UIPortalContainer } from '../../../lib/ui-provider/index.js';
 import type * as React from "react";
+/**
+ * The dropdown's menu opened by right-click over a region, reusing its rows. The trigger is
+ * not a button — the whole area is the target. Every entry must also be reachable another
+ * way (a toolbar, an `ActionMenu`): right-click is undiscoverable, absent on touch and
+ * awkward from a keyboard.
+ */
 declare function ContextMenu({ ...props }: ContextMenuPrimitive.Root.Props): React.JSX.Element;
 /** The region a right-click opens the menu over. */
 declare function ContextMenuTrigger({ ...props }: ContextMenuPrimitive.Trigger.Props): React.JSX.Element;
 /** The portal, for a caller placing the surface itself. The content portals already. */
 declare const ContextMenuPortal: React.ForwardRefExoticComponent<Omit<import('@base-ui/react').ContextMenuPortalProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * The menu's surface. It portals already, escaping an ancestor that clips or transforms — a
+ * card with overflow hidden, a scrolling pane.
+ */
 declare function ContextMenuContent({ container, className, ...props }: MenuPrimitive.Popup.Props & {
     className?: string;
     /**
@@ -16,16 +26,39 @@ declare function ContextMenuContent({ container, className, ...props }: MenuPrim
      */
     container?: UIPortalContainer;
 }): React.JSX.Element;
+/**
+ * The dropdown's row, unchanged: `icon`, `description`, `shortcut`, `trailing` and
+ * `variant="destructive"` all apply.
+ */
 declare const ContextMenuItem: typeof DropdownMenuItem;
+/** A row that toggles rather than closing. */
 declare const ContextMenuCheckboxItem: typeof DropdownMenuCheckboxItem;
+/** A set of rows that behaves as one choice. */
 declare const ContextMenuRadioGroup: typeof DropdownMenuRadioGroup;
+/** One choice inside a `ContextMenuRadioGroup`; it toggles rather than closing. */
 declare const ContextMenuRadioItem: typeof DropdownMenuRadioItem;
+/**
+ * A group's caption. It must sit inside a group — Base UI throws otherwise — and is not an
+ * item: arrow keys skip it.
+ */
 declare const ContextMenuLabel: typeof DropdownMenuLabel;
+/** A titled run of items. */
 declare const ContextMenuGroup: typeof DropdownMenuGroup;
+/** The rule between runs of items. */
 declare const ContextMenuSeparator: typeof DropdownMenuSeparator;
+/**
+ * The key hint on an item's trailing edge. Presentational: the item already carries the
+ * accessible name.
+ */
 declare const ContextMenuShortcut: typeof DropdownMenuShortcut;
+/**
+ * A nested menu, opening sideways. It holds the open state, so trigger and panel cannot
+ * disagree.
+ */
 declare const ContextMenuSub: typeof DropdownMenuSub;
+/** The row that opens a nested menu. */
 declare const ContextMenuSubTrigger: typeof DropdownMenuSubTrigger;
+/** The panel a nested menu opens, sideways. */
 declare const ContextMenuSubContent: typeof DropdownMenuSubContent;
 export type ContextMenuProps = React.ComponentProps<typeof ContextMenu>;
 export { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuPortal, ContextMenuItem, ContextMenuCheckboxItem, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuLabel, ContextMenuGroup, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent, };