themelia-ui 2.0.0 → 3.0.0

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

@@ -13,25 +13,45 @@ export interface TableProps extends ComponentProps<"table"> {
 /** Which way a sorted column is ordered. `null` is "sortable, but not the sort column". */
 export type TableSortDirection = "ascending" | "descending" | null;
 export interface TableCellProps extends Omit<ComponentProps<"td">, "align"> {
+    /** Column alignment. Numeric columns belong at the end. */
     align?: TableAlign;
-    /** Allows the cell to wrap. Cells are nowrap by default so columns stay readable. */
+    /**
+     * Lets the cell wrap. Cells are nowrap by default so columns stay aligned — a column that
+     * holds prose opts out here rather than the whole table losing its alignment.
+     */
     wrap?: boolean;
 }
 export interface TableHeadProps extends Omit<ComponentProps<"th">, "align"> {
+    /** Column alignment. Numeric columns belong at the end. */
     align?: TableAlign;
+    /** Lets the head cell wrap. Cells are nowrap by default so columns stay aligned. */
     wrap?: boolean;
-    /** Renders the label as a sort control. Pair with `sortDirection` and `onSort`. */
+    /**
+     * Renders the label as a sort control and puts `aria-sort` on the `<th>`. Pair with
+     * `sortDirection` and `onSort`.
+     */
     sortable?: boolean;
     /** This column's current direction, or `null` when another column is the sort. */
     sortDirection?: TableSortDirection;
+    /** Fires on activation. The table does not sort — the caller owns the data. */
     onSort?: () => void;
 }
+/**
+ * The table, inside its own scroll container. The container becomes a tab stop only while it
+ * scrolls, so a wide table can be scrolled from the keyboard.
+ */
 export declare function Table({ className, containerClassName, strings, stickyHeader, ...props }: TableProps): import("react").JSX.Element;
 export declare function TableHeader({ className, ...props }: ComponentProps<"thead">): import("react").JSX.Element;
 export declare function TableBody({ className, ...props }: ComponentProps<"tbody">): import("react").JSX.Element;
 export declare function TableFooter({ className, ...props }: ComponentProps<"tfoot">): import("react").JSX.Element;
+/**
+ * A row: a plain `<tr>`. Mark a selected row with `data-state="selected"` — a data
+ * attribute, not a prop, because rows are plain elements.
+ */
 export declare function TableRow({ className, ...props }: ComponentProps<"tr">): import("react").JSX.Element;
+/** A column's head cell, and with `sortable` its sort control. */
 export declare function TableHead({ className, children, align, wrap, sortable, sortDirection, onSort, ...props }: TableHeadProps): import("react").JSX.Element;
+/** A cell. A plain string is wrapped in `Text`; a node is left exactly as passed. */
 export declare function TableCell({ className, children, align, wrap, ...props }: TableCellProps): import("react").JSX.Element;
 export interface TableEmptyProps extends Omit<ComponentProps<"td">, "children"> {
     /** How many columns the table has, so the message spans all of them. */
@@ -39,6 +59,13 @@ export interface TableEmptyProps extends Omit<ComponentProps<"td">, "children">
     /** The message. Defaults to the table's `strings.empty`. */
     children?: ReactNode;
 }
-/** The "no rows" row, spanning every column. */
+/**
+ * The "no rows" row: it spans every column and states that there are none. A table with a
+ * header and no body reads as broken; this is what says it is empty on purpose.
+ */
 export declare function TableEmpty({ className, colSpan, children, ...props }: TableEmptyProps): import("react").JSX.Element;
+/**
+ * Names the table for assistive technology, and the scroll container with it. Rendered
+ * below the table.
+ */
 export declare function TableCaption({ className, children, id, ...props }: ComponentProps<"caption">): import("react").JSX.Element;

package/dist/components/base/text-inputs/field-shell.d.ts

@@ -19,4 +19,9 @@ export interface FieldShellProps extends Omit<React.ComponentProps<"div">, "chil
     /** A direct control, or an explicit adapter for a wrapped/custom control. */
     children?: React.ReactNode | ((controlProps: FieldShellControlProps) => React.ReactNode);
 }
+/**
+ * The field surface on its own, for composing a control the kit does not ship. The shell
+ * wears the surface and the control inside gives up its own, so an icon or a trailing
+ * action reads as part of one field rather than a box inside a box.
+ */
 export declare function FieldShell({ start, end, className, children, id, "aria-labelledby": ariaLabelledBy, "aria-invalid": ariaInvalid, "aria-describedby": ariaDescribedBy, "aria-required": ariaRequired, ...props }: FieldShellProps): React.JSX.Element;

package/dist/components/base/text-inputs/input.d.ts

@@ -6,26 +6,45 @@ export type FieldIcon = React.ComponentType<{
     className?: string;
 }> | React.ReactNode;
 export interface InputProps extends Omit<React.ComponentProps<"input">, "size"> {
-    /** Glyph before the value. */
+    /** Glyph before the value, in its own lane so the text never runs under it. */
     startIcon?: FieldIcon;
-    /** Glyph after the value. */
+    /** Glyph after the value, in its own lane so the text never runs under it. */
     endIcon?: FieldIcon;
-    /** Short text before the value — a currency symbol, a protocol, an @. */
+    /**
+     * Short text attached before the value, outside the text itself — a currency symbol, a
+     * protocol, an at sign.
+     */
     startAddon?: React.ReactNode;
-    /** Short text after the value — a unit, a domain. */
+    /** Short text attached after the value, outside the text itself — a unit, a domain. */
     endAddon?: React.ReactNode;
     /** Shows "12 / 80" in the trailing lane. Requires `maxLength`. */
     showCharacterCount?: boolean;
-    /** Shows a clear control once the field has a value. */
+    /** Character cap, and the limit the count counts against. Input past it is refused. */
+    maxLength?: number;
+    /**
+     * Shows a clear control once the field has a value. Clearing goes through the native
+     * value setter, so React's value tracker stays in sync.
+     */
     clearable?: boolean;
     /** Called after the clear control empties the field. */
     onClear?: () => void;
-    /** Replaces the trailing affordance with a spinner. */
+    /**
+     * Replaces the trailing affordance with a spinner, which outranks every other trailing
+     * affordance.
+     */
     loading?: boolean;
-    /** Applies the invalid treatment. The message stays with FormField. */
+    /**
+     * Applies the invalid treatment. Pair it with FormField's error for the message, so the
+     * border and the announcement cannot disagree.
+     */
     invalid?: boolean;
-    /** Includes string addons in the value reported by `onChange`. Off by default (addons are presentation). */
+    /**
+     * Includes string addons in the value reported by `onChange`. Off, because an addon is
+     * presentation: a caller that stores "$" and the number has to strip it again on the way
+     * out.
+     */
     returnValueWithAddons?: boolean;
+    /** Overrides this field's own copy — the clear label, the character-count format. */
     strings?: StringsProp<InputStrings>;
 }
 export declare const Input: React.ForwardRefExoticComponent<Omit<InputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/components/base/text-inputs/native-select.d.ts

@@ -3,4 +3,8 @@ export interface NativeSelectProps extends Omit<React.ComponentProps<"select">,
     /** Shown as a disabled first option when the value is empty. */
     placeholder?: string;
 }
+/**
+ * The platform `<select>` on the same field surface as `Select`, for a short list, the native
+ * picker on mobile, or a form that must post without JavaScript.
+ */
 export declare const NativeSelect: React.ForwardRefExoticComponent<Omit<NativeSelectProps, "ref"> & React.RefAttributes<HTMLSelectElement>>;

package/dist/components/base/text-inputs/password-input.d.ts

@@ -6,7 +6,15 @@ import { PasswordInputStrings } from './password-input.strings.js';
  */
 import * as React from "react";
 export interface PasswordInputProps extends Omit<InputProps, "type"> {
-    /** Overrides this field's own copy — the reveal control's name in each state. */
+    /**
+     * Overrides this field's own copy — the reveal control's name in each state, which is its
+     * state for a screen reader — and Input's own strings.
+     */
     strings?: Partial<PasswordInputStrings>;
 }
+/**
+ * A password field with a reveal control. It takes Input's props, `value` and
+ * `defaultValue` included, which behave as Input's. The reveal control's name alone carries
+ * its state — "Show password", "Hide password" — with no `aria-pressed` to contradict it.
+ */
 export declare const PasswordInput: React.ForwardRefExoticComponent<Omit<PasswordInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/components/base/text-inputs/search-input.d.ts

@@ -1,7 +1,24 @@
+import { StringsProp } from '../../../lib/strings.js';
 import { InputProps } from './input.js';
+import { InputStrings } from './input.strings.js';
 import * as React from "react";
 export interface SearchInputProps extends Omit<InputProps, "type" | "startIcon"> {
-    /** Called when the reader clears the field. The clear control is always offered. */
+    /**
+     * Called when the reader clears the field — a notification only, because Input does the
+     * clearing itself. The clear control is always present once there is a value.
+     */
     onClear?: () => void;
+    /**
+     * Overrides this field's own copy. It is Input's strings object with one default
+     * narrowed: a search field's only copy is one word of Input's.
+     * @default { clear: "Clear search" }
+     */
+    strings?: StringsProp<InputStrings>;
+    /** Say what is being searched, not just "Search". */
+    placeholder?: string;
 }
+/**
+ * Input with a leading magnifier and a clear control, and the native search clear
+ * suppressed. It only pre-wires those two; everything else is Input's API.
+ */
 export declare const SearchInput: React.ForwardRefExoticComponent<Omit<SearchInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/components/base/text-inputs/slug-field.d.ts

@@ -6,11 +6,21 @@ import { SlugifyOptions } from './slugify.js';
  */
 import * as React from "react";
 export interface SlugFieldProps extends Omit<InputProps, "value" | "defaultValue" | "onChange" | "readOnly" | "type" | "prefix">, SlugifyOptions {
-    /** The source value. Controlled — the slug is derived, never held. */
+    /**
+     * The source text; the field shows its slugified form. Controlled — the slug is derived,
+     * never held.
+     */
     value: string | number | null | undefined;
-    /** Replaces the built-in derivation entirely. */
+    /**
+     * Replaces the built-in derivation entirely. The default lower-cases, strips accents,
+     * keeps letters and numbers in any script, and collapses every other run to a single
+     * separator.
+     */
     transform?: (value: string | number | null | undefined) => string;
-    /** Rendered before the slug, inside the field — a domain or a path prefix. */
+    /**
+     * Rendered before the slug, inside the field — a domain or a path prefix. Not part of the
+     * value.
+     */
     prefix?: React.ReactNode;
 }
 export declare const SlugField: React.ForwardRefExoticComponent<Omit<SlugFieldProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/components/base/text-inputs/slugify.d.ts

@@ -1,6 +1,7 @@
 export interface SlugifyOptions {
     /** Character joining words. */
     separator?: string;
+    /** Lower-cases the slug. */
     lowercase?: boolean;
     /** Strips leading and trailing separators. */
     trim?: boolean;

package/dist/components/base/text-inputs/textarea.d.ts

@@ -8,16 +8,28 @@ export interface TextareaProps extends Omit<React.ComponentProps<"textarea">, "o
     maxLength?: number;
     /** Shows the current and maximum character count. */
     showCharacterCount?: boolean;
-    /** Shows an inline clear action once the field has a value. */
+    /**
+     * Shows a clear control in the trailing lane once the field has a value. `strings.clear`
+     * is its accessible name.
+     */
     clearable?: boolean;
+    /** Called after the clear control empties the field. */
     onClear?: () => void;
     /** Replaces the trailing affordance with a loading indicator. */
     loading?: boolean;
-    /** Applies the invalid styling. Validation copy stays with FormField. */
+    /** Applies the invalid styling, the same as Input. Validation copy stays with FormField. */
     invalid?: boolean;
-    /** Smallest height, in rows. */
+    /**
+     * Visible lines. Without `minRows` it is the floor the field grows from; `maxRows` sets
+     * where it stops growing and scrolls.
+     */
+    rows?: number;
+    /** The floor when the field grows with its content: its smallest height, in rows. */
     minRows?: number;
-    /** Height at which the field stops growing and starts scrolling. */
+    /**
+     * Height at which the field stops growing and starts scrolling. Without a ceiling a long
+     * note pushes the submit button off the screen.
+     */
     maxRows?: number;
     onChange?: (event: React.ChangeEvent<HTMLTextAreaElement>) => void;
     value?: string;

package/dist/components/base/text-inputs/use-field-value.d.ts

@@ -23,7 +23,8 @@ export interface UseFieldValueResult {
     wouldExceedLimit: (next: string) => boolean;
 }
 /**
- * Value bookkeeping shared by the text controls (Input, Textarea): controlled or not, a
- * generated id, the character count and the limit — one branch, so fields agree.
+ * Value bookkeeping shared by Input and Textarea (SearchInput wraps Input): the controlled or
+ * uncontrolled value, a generated id, and the character count with its limit — one branch,
+ * so both fields behave the same under a form library.
  */
 export declare function useFieldValue({ controlledValue, defaultValue, maxLength, showCharacterCount, providedId, idPrefix, }: UseFieldValueOptions): UseFieldValueResult;

package/dist/components/base/timeline/stepper.d.ts

@@ -11,29 +11,49 @@ export type StepperStatus = "completed" | "complete" | "current" | "upcoming";
  * markers show.
  */
 export type StepperVariant = "bar" | "trail";
+/** One step of a `Stepper`. */
 export interface StepperStep {
     /** Stable identity for the step, handed back to `onStepClick`. */
     id: string;
+    /** What the step is called. */
     label: ReactNode;
     /** A second, quieter line under the label. */
     hint?: ReactNode;
-    /** Where the step stands. Defaults to `upcoming`. */
+    /**
+     * Where the step stands. `completed` is the canonical spelling; `complete` is accepted as
+     * the same state and normalised, so the DOM only ever says `completed`.
+     * @default "upcoming"
+     */
     status?: StepperStatus;
     /**
-     * The step's whole accessible name, replacing its announced position, label, hint and
-     * state. `aria-current` still marks the current step.
+     * The step's whole accessible name, worded by the caller. It replaces the announced
+     * position, label, hint and state rather than joining them; `aria-current` still marks
+     * the current step.
      */
     accessibleName?: string;
 }
 export interface StepperProps extends Omit<ComponentProps<"ol">, "children"> {
+    /** The steps, in order. Rendered as an `<ol>`, because the order is the meaning. */
     steps: StepperStep[];
-    /** Which drawing. Defaults to `bar`. */
+    /**
+     * Which drawing. `bar`: labels under ringed markers in equal columns, with the connector
+     * through the marker row. `trail`: labels beside filled markers and a rule taking the
+     * rest of the row; below `lg` the labels are visually hidden and only the markers show.
+     */
     variant?: StepperVariant;
     /**
      * Makes each step a button: completed steps and the current one are reachable, upcoming
      * ones disabled. Without it the steps are plain list items.
      */
     onStepClick?: (id: string, index: number) => void;
+    /**
+     * Overrides this stepper's own copy: `position(index, total)` names what the numeral
+     * counts, and `completed` and `current` are said with those steps.
+     */
     strings?: Partial<StepperStrings>;
 }
+/**
+ * A numbered sequence the reader is partway through: a marker per step — a numeral that
+ * becomes a tick — connectors, and a label with an optional hint.
+ */
 export declare function Stepper({ steps, variant, onStepClick, strings, className, ...props }: StepperProps): import("react").JSX.Element;

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

@@ -6,23 +6,42 @@ import { ComponentProps, ReactNode } from 'react';
  * `pending` is the only unfilled dot.
  */
 export type TimelineStatus = "progress" | "completed" | "current" | "pending" | "success" | "warning" | "destructive" | "neutral";
+/** One entry of a `Timeline`. Everything an entry needs travels in the item. */
 export interface TimelineItem {
     /** Stable identity for the row. */
     id: string;
+    /** What happened. */
     title: ReactNode;
     /** Supporting copy under the title. */
     description?: ReactNode;
-    /** Already formatted — the kit's date primitives decide the format, not this. */
+    /** Already formatted — the kit's date primitives decide the format, not this component. */
     timestamp?: ReactNode;
-    /** The title row's trailing lane when it holds something other than a time; replaces `timestamp`. */
+    /**
+     * The title row's trailing lane when what belongs there is not a time — an amount, a
+     * count. It replaces `timestamp` rather than joining it: there is one lane.
+     */
     trailing?: ReactNode;
     /** Decorative glyph inside the dot. */
     icon?: LucideIcon;
+    /**
+     * Colours the dot, and the connector that runs from it to the next entry. `progress` and
+     * `completed` are not the same thing: a step you walked past is a position, so it takes
+     * the same primary tone as the step you are on and a sequence reads as one journey in one
+     * colour; `completed` is an outcome, a milestone that landed. A bare `progress` dot is
+     * hollow where `current` is solid, because on a rail with no glyphs the card still has to
+     * say where the thing is.
+     * @default "neutral"
+     */
     status?: TimelineStatus;
     /** Anything the entry carries below its description — a card, a diff, an action row. */
     children?: ReactNode;
 }
 export interface TimelineProps extends Omit<ComponentProps<"ol">, "children"> {
+    /**
+     * The entries, in the order they should be read. Rendered as an `<ol>`, because these
+     * have an order and a screen reader should say so.
+     */
     items: TimelineItem[];
 }
+/** An ordered run of events on one rail — changelogs, milestones, an order's progress. */
 export declare function Timeline({ items, className, ...props }: TimelineProps): import("react").JSX.Element;

package/dist/components/base/toaster/toast-store.d.ts

@@ -2,18 +2,32 @@ import { ReactNode } from 'react';
 /** Status: the surface is the same for all; only the glyph and announcement politeness change. */
 export type ToastStatus = "neutral" | "success" | "info" | "warning" | "error" | "loading";
 export type ToastPosition = "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end";
+/** A button on a toast's pill. */
 export interface ToastAction {
+    /** The button's text. */
     label: string;
+    /** Runs on press, before the toast is dismissed. */
     onClick: () => void;
 }
+/** What a toast carries beyond its title, passed as `toast(title, options)`. */
 export interface ToastOptions {
+    /** Reusing an on-screen id updates that toast in place rather than stacking a second one. */
     id?: string;
+    /** A second line under the title. */
     description?: ReactNode;
     /** Replaces the status glyph. */
     icon?: ReactNode;
-    /** Milliseconds before auto-dismissal. `Infinity` pins it open. */
+    /**
+     * Lifetime in milliseconds before auto-dismissal. `Infinity` pins it open. Falls back to
+     * the Toaster's `duration`.
+     */
     duration?: number;
+    /**
+     * A button on the pill — the undo for something that already happened. It dismisses the
+     * toast after running.
+     */
     action?: ToastAction;
+    /** A second, quieter button on the pill. Dismisses the toast after running. */
     cancel?: ToastAction;
     /** Called after the toast leaves, whichever way it left. */
     onDismiss?: (id: string) => void;
@@ -57,13 +71,19 @@ export interface ToastStore {
     applyDefaultDuration(defaultDuration: number): void;
 }
 /**
- * A store with its own queue and timers, for a second, isolated Toaster (a host app and an
- * embedded widget). Most apps use the default `toastStore`.
+ * An independent queue with its own timers and its own bound `toast()`, for a second,
+ * isolated Toaster — a host application and an embedded widget. With only the module-level
+ * queue, one for the whole realm, two Toasters on a page would render the same toasts, and
+ * `pauseAll` would walk a timer map neither owned. The singleton stays the default, because
+ * `toast("Saved")` working with no wiring is the point of it.
  */
 export declare function createToastStore(): ToastStore;
 /** The default store, which `toast("Saved")` writes to from anywhere (no hook or context). */
 export declare const toastStore: ToastStore;
-/** `toast()` bound to the default store. */
+/**
+ * Raises a toast on the default store and returns its id. Also `.success`, `.info`,
+ * `.warning`, `.error`, `.loading`, `.promise` and `.dismiss`.
+ */
 export declare const toast: ToastFn;
 export declare const dismiss: (id?: string) => void;
 export declare const pauseAll: () => void;

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

@@ -2,23 +2,43 @@ import { UIPortalContainer } from '../../../lib/ui-provider/index.js';
 import { ToastPosition, ToastStore } from './toast-store.js';
 import { ToasterStrings } from './toaster.strings.js';
 export interface ToasterProps {
+    /**
+     * One of six: top or bottom, crossed with start, center, or end. Bottom stacks grow
+     * upward so the newest is nearest the edge. `UIProvider` defaults can change it.
+     * @default "bottom-end"
+     */
     position?: ToastPosition;
-    /** Default lifetime in ms. A toast with its own `duration` still wins. */
+    /**
+     * Default lifetime in ms. A toast with its own `duration` still wins. `UIProvider`
+     * defaults can change it.
+     * @default 4000
+     */
     duration?: number;
-    /** Maximum toasts on screen. Older ones are dropped from the render, not the store. */
+    /**
+     * Maximum toasts on screen — a cap on the render, not the store: older ones are dropped
+     * from the render, and a capped toast still runs its timer and `onDismiss`. `UIProvider`
+     * defaults can change it.
+     * @default 3
+     */
     visibleToasts?: number;
+    /**
+     * Shows each toast's dismiss control. `UIProvider` defaults can change it.
+     * @default true
+     */
     closeButton?: boolean;
     /** Overrides this region's own copy — its name, and each toast's dismiss. */
     strings?: Partial<ToasterStrings>;
     className?: string;
     /**
-     * The queue this Toaster renders. Defaults to the singleton `toast()` writes to; pass a
-     * `createToastStore()` instance for independent Toasters (a host app and an embedded widget).
+     * The queue this Toaster renders, dismisses and pauses. Defaults to the singleton
+     * `toast()` writes to; pass a `createToastStore()` instance to isolate it — a host app and
+     * an embedded widget.
      */
     store?: ToastStore;
     /**
      * Where the toast region renders. Defaults to the nearest `UIPortalHost`, else
-     * `document.body`, so scoped density and theme apply.
+     * `document.body` — so toasts raised inside a scoped region are drawn with that region's
+     * density and theme.
      */
     container?: UIPortalContainer;
 }

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

@@ -1,16 +1,30 @@
 import { Toggle as TogglePrimitive } from '@base-ui/react/toggle';
 import { ToggleGroup as ToggleGroupPrimitive } from '@base-ui/react/toggle-group';
-export interface ToggleProps extends TogglePrimitive.Props {
-    /** Sunk when engaged, or outlined. Match whatever sits beside it in the row. */
+export interface ToggleProps extends TogglePrimitive.Props, Pick<TogglePrimitive.Props, "pressed" | "defaultPressed" | "onPressedChange" | "value"> {
+    /**
+     * Sunk when engaged, or outlined. Match whatever sits beside it in the row — `outline`
+     * for a lone control, `ghost` inside a group.
+     */
     variant?: "ghost" | "outline";
 }
+/**
+ * A control that stays engaged, reported with `aria-pressed`: `pressed` and
+ * `defaultPressed` hold its state, controlled and uncontrolled, and `onPressedChange` fires
+ * with the next one. Inside a `ToggleGroup`, `value` names the toggle, and the group reads it
+ * into its own value; outside a group it is unused.
+ */
 export declare function Toggle({ variant, className, ...props }: ToggleProps): import("react").JSX.Element;
-export interface ToggleGroupProps extends ToggleGroupPrimitive.Props {
-    /** Joins the toggles into one framed control. Defaults to true. */
+export interface ToggleGroupProps extends ToggleGroupPrimitive.Props, Pick<ToggleGroupPrimitive.Props, "multiple" | "value" | "onValueChange"> {
+    /**
+     * Joins the toggles into one framed control with internal rules. Off leaves them as
+     * separate buttons in a row.
+     */
     attached?: boolean;
 }
 /**
- * A set of `Toggle`s (each given a `value`) sharing one value. `multiple` makes it a
- * checkbox set rather than one-at-a-time.
+ * A set of `Toggle`s (each given a `value`) sharing one value. `multiple` allows several at
+ * once rather than one: a view switch is one, text styles are several. The value is always
+ * an array, even when only one may be pressed, so switching `multiple` does not change its
+ * shape.
  */
 export declare function ToggleGroup({ attached, className, ...props }: ToggleGroupProps): import("react").JSX.Element;

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

@@ -1,28 +1,37 @@
 import { Toolbar as ToolbarPrimitive } from '@base-ui/react/toolbar';
 import { ButtonProps } from '../buttons/index.js';
 import * as React from "react";
-export interface ToolbarProps extends ToolbarPrimitive.Root.Props {
+export interface ToolbarProps extends ToolbarPrimitive.Root.Props, Pick<ToolbarPrimitive.Root.Props, "orientation" | "disabled" | "loopFocus"> {
 }
 /**
- * A named set of related controls with one tab stop and orientation-aware arrow
- * navigation. Supply `aria-label` or `aria-labelledby` whenever no visible label names
- * the set.
+ * A named set of related controls: `role="toolbar"`, with one roving tab stop and
+ * orientation-aware arrow navigation. `orientation`, `disabled` and `loopFocus` come from
+ * Base UI's toolbar root. Supply `aria-label` or `aria-labelledby` whenever no visible label
+ * names the set.
  */
 export declare function Toolbar({ className, ...props }: ToolbarProps): React.JSX.Element;
-export interface ToolbarGroupProps extends ToolbarPrimitive.Group.Props {
+export interface ToolbarGroupProps extends ToolbarPrimitive.Group.Props, Pick<ToolbarPrimitive.Group.Props, "disabled"> {
 }
+/** Groups related items, and can disable the group as one unit. */
 export declare function ToolbarGroup({ className, ...props }: ToolbarGroupProps): React.JSX.Element;
 export interface ToolbarButtonProps extends Omit<ToolbarPrimitive.Button.Props, "render">, Pick<ButtonProps, "tone" | "buttonStyle" | "iconOnly" | "loading" | "fullWidth"> {
     /** Replaces the kit Button while retaining toolbar navigation behavior. */
     render?: React.ReactElement;
 }
+/**
+ * A toolbar item rendered through the kit Button: Base UI owns the navigation behaviour, the
+ * Button its look. It takes `tone`, `buttonStyle`, `iconOnly`, `loading` and `render`.
+ */
 export declare function ToolbarButton({ render, tone, buttonStyle, iconOnly, loading, fullWidth, className, ...props }: ToolbarButtonProps): React.JSX.Element;
 export interface ToolbarLinkProps extends ToolbarPrimitive.Link.Props {
 }
+/** An anchor item that joins the same roving-focus order. */
 export declare function ToolbarLink({ className, ...props }: ToolbarLinkProps): React.JSX.Element;
 export interface ToolbarInputProps extends ToolbarPrimitive.Input.Props {
 }
+/** A native input item that joins the same roving-focus order. */
 export declare function ToolbarInput({ className, ...props }: ToolbarInputProps): React.JSX.Element;
 export interface ToolbarSeparatorProps extends ToolbarPrimitive.Separator.Props {
 }
+/** A rule between items. It takes the orientation opposite to the toolbar's. */
 export declare function ToolbarSeparator({ className, ...props }: ToolbarSeparatorProps): React.JSX.Element;

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

@@ -1,10 +1,20 @@
 import { Tooltip as TooltipPrimitive } from '@base-ui/react/tooltip';
 import { UIPortalContainer } from '../../../lib/ui-provider/index.js';
-declare function TooltipProvider({ delay, delayDuration, ...props }: TooltipPrimitive.Provider.Props & {
+/**
+ * Shares one open delay, `delay`, across every tooltip inside it. Wrap the app once rather
+ * than each tooltip.
+ */
+declare function TooltipProvider({ delay, delayDuration, ...props }: TooltipPrimitive.Provider.Props & Pick<TooltipPrimitive.Provider.Props, "delay"> & {
+    /** `delay` under another name, in milliseconds. It wins when both are given. */
     delayDuration?: number;
 }): import("react").JSX.Element;
 declare function Tooltip({ open, defaultOpen, onOpenChange, ...props }: TooltipPrimitive.Root.Props): import("react").JSX.Element;
-declare function TooltipTrigger({ render, children, ...props }: TooltipPrimitive.Trigger.Props): import("react").JSX.Element;
+/**
+ * What the tip anchors to, passed as `render`. It must be a real focusable element, so the
+ * tip opens on keyboard focus and not only on hover.
+ */
+declare function TooltipTrigger({ render, children, ...props }: TooltipPrimitive.Trigger.Props & Pick<TooltipPrimitive.Trigger.Props, "render">): import("react").JSX.Element;
+/** The tip. Short — a sentence, not a paragraph. */
 declare function TooltipContent({ container, className, side, sideOffset, align, alignOffset, children, ...props }: TooltipPrimitive.Popup.Props & Pick<TooltipPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset"> & {
     /** Where the popup renders. Defaults to the nearest `UIPortalHost`, else the primitive's own. */
     container?: UIPortalContainer;

package/dist/components/base/typography/rich-text/rich-text.d.ts

@@ -9,7 +9,13 @@ export interface RichTextProps extends Omit<ComponentProps<"div">, "children" |
     type?: TextProps["type"];
     align?: TextProps["align"];
     weight?: TextProps["weight"];
+    /** Defaults to `relaxed`, the editor's prose leading, so a body does not reflow once posted. */
     lineHeight?: TextProps["lineHeight"];
     tag?: "div" | "p";
 }
+/**
+ * Renders stored rich text — the READ half of the rich-text editor — in `Text`'s styles. It
+ * sanitises on the way in, with no opt-out, so content from a database or an API cannot carry
+ * script or event handlers into the page.
+ */
 export declare function RichText({ html, children, size, type, align, weight, lineHeight, tag, className, ...props }: RichTextProps): import("react").JSX.Element | null;