themelia-ui 2.0.1 → 3.0.0

package/dist/components/base/cards/card.d.ts

@@ -8,16 +8,23 @@ import * as React from "react";
 export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     /** Leading glyph on the title line. */
     icon?: React.ReactNode;
+    /** Header copy. The title truncates rather than pushing header controls off the row. */
     title?: React.ReactNode;
     /** Badges, status, or counts immediately after the title. */
     titleSuffix?: React.ReactNode;
     /**
-     * Explanatory copy behind a focusable info button on the title line — for a definition or
-     * caveat too long for the description.
+     * Explanatory copy behind an info button on the title line — for a definition or caveat
+     * too long for the description. A real focusable button, not a `title` attribute;
+     * `strings.tooltip` names it.
      */
     tooltip?: React.ReactNode;
+    /** Header copy under the title. */
     description?: React.ReactNode;
-    /** Outer chrome. */
+    /**
+     * Outer chrome. `framed`, the bezel, is the default; `card` is the plain panel. Change it
+     * for a whole product once with `UIProvider` `defaults.card.surface`.
+     * @default "framed"
+     */
     surface?: CardSurface;
     /** Full-width row above the title — an eyebrow or breadcrumb. Rare. */
     headerStart?: React.ReactNode;
@@ -25,25 +32,42 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     headerEnd?: React.ReactNode;
     /** A single control at the end of the header. Use `actions` for a list of commands. */
     headerAction?: React.ReactNode;
-    /** Overflow commands, collapsed into one menu trigger. */
+    /**
+     * Overflow commands, collapsed into one menu trigger and rendered by the shared
+     * `ActionMenu`: a destructive entry moves last and is separated.
+     */
     actions?: CardAction[];
     /**
-     * Renders the title as a heading of this level. Unset, the title is a span that heading
-     * navigation can't find; set it when the card titles a page section.
+     * Renders the title as a heading of this level, for a card that heads a page or a region.
+     * Unset, the title is a span that heading navigation can't find.
      */
     titleLevel?: 1 | 2 | 3 | 4 | 5 | 6;
-    /** A full-bleed strip above the header — a cover image, an illustration, a preview. */
+    /**
+     * A full-bleed strip above the header — a cover image, a map, a brand band — clipped to
+     * the card's top corners.
+     */
     media?: React.ReactNode;
-    /** Banner between header and content. A plain string is wrapped for you. */
+    /** Banner between header and content. A plain string is wrapped in an `Alert`. */
     alert?: React.ReactNode;
+    /** Tone of the alert band. */
     alertTone?: CardAlertTone;
+    /** Content inside the content inset, above `children`. */
     contentTop?: React.ReactNode;
+    /** Content inside the content inset, below `children`. */
     contentBottom?: React.ReactNode;
     /** Muted text in the footer band. */
     footerText?: React.ReactNode;
     /** Footer band under the content — a single primary action fits well here. */
     footerSlot?: React.ReactNode;
+    /**
+     * A rule between the header and the content. `UIProvider` defaults can change it.
+     * @default false
+     */
     headerDivider?: boolean;
+    /**
+     * A rule between the content and the footer.
+     * @default false
+     */
     footerDivider?: boolean;
     /**
      * Clips content to a collapsed height with a fade, and adds a toggle. `true` uses
@@ -52,10 +76,21 @@ export interface CardProps extends Omit<React.ComponentProps<"div">, "title"> {
     expandable?: boolean | {
         collapsedMaxHeight?: number | string;
     };
+    /** Whether an expandable card's content is expanded, for controlled expansion. */
     expanded?: boolean;
+    /** Whether an expandable card starts expanded, for uncontrolled expansion. */
     defaultExpanded?: boolean;
+    /** Called with the new state when the reader expands or collapses the content. */
     onExpandedChange?: (expanded: boolean) => void;
-    /** Overrides this card's own copy — the info glyph, the overflow trigger, the disclosure. */
+    /**
+     * Overrides this card's own copy — the info glyph, the overflow trigger, and the
+     * disclosure control's name in each state.
+     */
     strings?: Partial<CardStrings>;
 }
+/**
+ * The single surface primitive. Slot props (`title`, `description`, `actions`, `footerText`,
+ * …) cover the common shape; `CardHeader`, `CardContent` and `CardFooter` are exported for
+ * composing.
+ */
 export declare function Card({ icon, title, titleSuffix, tooltip, description, surface, titleLevel, media, headerStart, headerEnd, headerAction, actions, alert, alertTone, contentTop, contentBottom, footerText, footerSlot, headerDivider, footerDivider, expandable, expanded, defaultExpanded, onExpandedChange, strings, className, children, ...props }: CardProps): React.JSX.Element;

package/dist/components/base/cards/index.d.ts

@@ -4,3 +4,4 @@ export type { CardSurface, CardAction, CardAlertTone } from './card.types.js';
 export { CardActionStrip, CardPrimaryAction, type CardActionStripProps, type CardPrimaryActionProps, } from './card-actions.js';
 export { CardSkeleton, type CardSkeletonProps } from './card-skeleton.js';
 export { defaultCardStrings, type CardStrings } from './card.strings.js';
+export type { LinkRenderer, LinkRenderProps } from '../../../lib/navigation.js';

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

@@ -7,6 +7,10 @@ export declare const CarouselContext: import('react').Context<{
     scrollToSlide: (index: number) => void;
     strings: CarouselStrings;
 } | null>;
+/**
+ * The track's position, its slide count, and the scroll helpers, for a fully custom control
+ * surface. Must be called inside a `Carousel`.
+ */
 export declare function useCarousel(): {
     index: number;
     count: number;

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

@@ -4,30 +4,62 @@ export type CarouselOrientation = "horizontal" | "vertical";
 /** Where the previous/next controls sit. `overlay` floats them over the track's edges. */
 export type CarouselControlPlacement = "outside" | "overlay" | "none";
 export interface CarouselProps extends Omit<ComponentProps<"div">, "children"> {
+    /** The slides, usually `CarouselSlide`s. */
     children: ReactNode;
+    /** Which axis snaps. */
     orientation?: CarouselOrientation;
+    /**
+     * Where the previous/next buttons sit: `outside` the track, `overlay` on its edges, or
+     * `none` when you compose your own with `CarouselControl`.
+     */
     controls?: CarouselControlPlacement;
     /** Shows the position indicators, and lets them be clicked. */
     showDots?: boolean;
+    /** `pill` stretches the active indicator instead of only recolouring it. */
     dotStyle?: "dot" | "pill";
-    /** Overrides this carousel's own copy — the region name and the two controls. */
+    /**
+     * Overrides this carousel's own copy — the region name, the two icon-only controls, and
+     * each pagination dot. It travels through the context, so a control placed with
+     * `CarouselControl` is named by the same override as one the root rendered.
+     */
     strings?: Partial<CarouselStrings>;
+    /**
+     * Names the region for assistive technology; unset, `strings.label` does. A carousel with
+     * no name is an unexplained scroll box, and a page with two needs two names.
+     */
     label?: string;
+    /**
+     * Styles the scroll container rather than the outer frame — for a carousel that needs its
+     * own padding inside the clip.
+     */
     viewportClassName?: string;
 }
+/**
+ * A native scroll-snap track with controls. Script only reports the current slide and
+ * scrolls to a chosen one.
+ */
 export declare function Carousel({ children, orientation, controls, showDots, dotStyle, strings, label, className, viewportClassName, ...props }: CarouselProps): import("react").JSX.Element;
 export interface CarouselControlProps extends ComponentProps<"button"> {
+    /** Which way the control moves the track. */
     direction: "previous" | "next";
 }
-/** A previous/next control placed by the caller rather than by the root. */
+/**
+ * A single previous/next control placed by the caller rather than by the root, for composing
+ * your own layout with `controls="none"`. Must sit inside a `Carousel`.
+ */
 export declare function CarouselControl({ direction, className, children, ...props }: CarouselControlProps): import("react").JSX.Element;
 export interface CarouselDotsProps extends ComponentProps<"div"> {
+    /** `pill` stretches the active indicator instead of only recolouring it. */
     dotStyle?: "dot" | "pill";
 }
-/** The position indicators, placed by the caller. */
+/**
+ * The position indicators on their own, placed by the caller outside the track. Must sit
+ * inside a `Carousel`.
+ */
 export declare function CarouselDots({ dotStyle, className, ...props }: CarouselDotsProps): import("react").JSX.Element;
 export interface CarouselSlideProps extends ComponentProps<"div"> {
     /** Track width this slide occupies — "100%", "50%", "18rem". */
     size?: string;
 }
+/** One slide of the track, announced as a slide. */
 export declare function CarouselSlide({ size, className, style, ...props }: CarouselSlideProps): import("react").JSX.Element;

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

@@ -24,7 +24,15 @@ export interface ChartPayloadItem {
     payload?: Record<string, unknown>;
 }
 export interface ChartContainerProps extends Omit<React.ComponentProps<"div">, "children"> {
+    /**
+     * Maps each data key to a label, a colour, and an icon. Each colour becomes
+     * `--color-{key}` on the container.
+     */
     config: ChartConfig;
+    /**
+     * One Recharts chart. `label` and `description` become its `<title>` and `<desc>` unless
+     * it sets its own.
+     */
     children: React.ComponentProps<typeof Recharts.ResponsiveContainer>["children"];
     /**
      * What the chart shows, as a sentence a screen reader can speak ("Monthly revenue against
@@ -34,29 +42,57 @@ export interface ChartContainerProps extends Omit<React.ComponentProps<"div">, "
     /** A longer summary of the data or its takeaway, read after the label. */
     description?: string;
 }
+/**
+ * Recharts on the kit's tokens: Recharts owns geometry, this owns chrome. Each series key
+ * maps to `--color-<key>`, so colours are set once in the config; prefer `var(--chart-1)` …
+ * `var(--chart-5)`, which follow the theme.
+ */
 export declare function ChartContainer({ config, label, description, className, children, style, ...props }: ChartContainerProps): React.JSX.Element;
 export declare const ChartTooltip: typeof Recharts.Tooltip;
 export declare function ChartLegend({ itemSorter, ...props }: React.ComponentProps<typeof Recharts.Legend>): React.JSX.Element;
 export interface ChartTooltipContentProps extends Omit<React.ComponentProps<"div">, "color"> {
-    /** Supplied by Recharts. */
+    /**
+     * Supplied by Recharts. A content component is cloned with it; it never receives it from
+     * you.
+     */
     active?: boolean;
+    /**
+     * The entries under the cursor. Supplied by Recharts, which clones a content component with
+     * them; it never receives them from you.
+     */
     payload?: ChartPayloadItem[];
+    /** The hovered category, supplied by Recharts. `labelKey` and `labelFormatter` change what shows. */
     label?: React.ReactNode;
+    /** Drops the label row. */
     hideLabel?: boolean;
+    /** Drops the swatches. */
     hideIndicator?: boolean;
+    /** Shape of the swatch beside each value. */
     indicator?: "dot" | "line" | "dashed";
-    /** Key in the payload holding each series name. */
+    /** Key in the payload holding each series name, when it is not the data key. */
     nameKey?: string;
-    /** Key in the payload holding the tooltip label. */
+    /** Key in the payload holding the tooltip label, when it is not the data key. */
     labelKey?: string;
+    /** Formats the tooltip's heading — a date key into a readable date. */
     labelFormatter?: (label: React.ReactNode, payload: ChartPayloadItem[]) => React.ReactNode;
+    /** Formats each value. Without it, numbers get locale grouping. */
     formatter?: (value: NonNullable<ChartPayloadItem["value"]>, name: NonNullable<ChartPayloadItem["name"]>, item: ChartPayloadItem, index: number) => React.ReactNode;
 }
+/**
+ * The tooltip body, passed to `ChartTooltip` as its `content`. Names, colours and icons come
+ * from the container's config.
+ */
 export declare function ChartTooltipContent({ active, payload, label, hideLabel, hideIndicator, indicator, nameKey, labelKey, labelFormatter, formatter, className, ...props }: ChartTooltipContentProps): React.JSX.Element | null;
 export interface ChartLegendContentProps extends React.ComponentProps<"div"> {
     /** Supplied by Recharts. */
     payload?: ChartPayloadItem[];
+    /** Drops the swatch, for a legend beside a chart whose colours are already named. */
     hideIcon?: boolean;
+    /** Key in the payload holding each series name, when it is not the data key. */
     nameKey?: string;
 }
+/**
+ * The legend body, passed to `ChartLegend` as its `content`. Names, colours and icons come
+ * from the container's config.
+ */
 export declare function ChartLegendContent({ payload, hideIcon, nameKey, className, ...props }: ChartLegendContentProps): React.JSX.Element | null;

package/dist/components/base/chart/sparkline.d.ts

@@ -9,4 +9,9 @@ export interface SparklineProps extends Omit<React.ComponentProps<"div">, "child
     /** What the shape says. Without it the chart is decorative and hidden from readers. */
     label?: string;
 }
+/**
+ * A trend line with no axes, no grid and no tooltip — the shape of a series beside the figure
+ * it belongs to. Not a small `ChartContainer`: it draws no chrome, so it can sit inside a table
+ * cell or a metric tile.
+ */
 export declare function Sparkline({ data, tone, animated, label, className, ...props }: SparklineProps): import("react").JSX.Element;

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;