prime-ui-kit 0.15.0 → 0.16.0

package/dist/components/progress-circle/ProgressCircle.d.ts

@@ -4,42 +4,61 @@ import type { ControlSize, Tone } from "../../internal/states";
 export type ProgressCircleLabels = ProgressSegmentsLabels;
 type ValueModeProps = {
     /**
-     * Current value, clamped to `0…max`; `null` — under way, the share unknown: a quarter arc that
-     * always turns, no `aria-valuenow`.
+     * Value mode: the current value, clamped to `0…max`; it glides to a new value (`base`). `null` — under way, the share unknown: a quarter arc that always turns, no `aria-valuenow`.
      */
     value: number | null;
-    /** Top of the scale. Default `100`. */
+    /**
+     * Value mode: top of the scale. Segments mode: total capacity; the sum of the parts closes the ring, a larger `max` leaves the rest as track.
+     */
     max?: number;
     /**
-     * Fill color. Default `accent`. `inherit` — the arc in the host's text color over a 32% track of
-     * it, for a ring on a colored host or over media.
+     * Value mode: arc color, telling the outcome. `inherit` — the arc in the host's text color over a 32% track of it, for a ring on a colored host or over media.
      */
     tone?: Tone | "inherit";
-    /** The ring turns at any share (a sync whose share grows). Default `false`; `null` always turns. */
+    /**
+     * Value mode: the ring turns at any share (one turn = 3 × `--prime-motion-loop`; slower under reduced motion, never still) and the arc never drops under 8%: a sync whose share grows. `null` always turns.
+     */
     spin?: boolean;
+    /**
+     * Segments mode: parts in order, `{ value, label?, tone? | color? }`: `tone` names a meaning (default `accent`), `color` a category — its step of the chart palette. Each part's length is its share of `max`.
+     */
     segments?: never;
+    /**
+     * Segments mode: `none` — one continuous ring; `hairline` — every part and the rest are separate round arcs.
+     */
     segmentGap?: never;
+    /**
+     * Segments mode: built-in strings, see Labels.
+     */
     labels?: never;
+    /**
+     * Segments mode: a legend beside the ring (below it when narrow), one row per part: color · name · value · share; with `aria-label` it becomes the group's description. The root turns into the row of ring and legend.
+     */
     legend?: never;
+    /**
+     * Segments mode: display of a part's value in the legend («38 ГБ»).
+     */
     formatValue?: never;
 };
 type SegmentsModeProps = Extract<ProgressModeProps, {
     segments: ProgressSegment[];
 }> & {
+    /**
+     * Value mode: the ring turns at any share (one turn = 3 × `--prime-motion-loop`; slower under reduced motion, never still) and the arc never drops under 8%: a sync whose share grows. `null` always turns.
+     */
     spin?: never;
 };
 export type ProgressCircleProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
-    /** Default `m`. */
+    /**
+     * Diameter 24 · 32 · 48 · 64 · 80 px; the stroke is 1/12 of it. Without it the ring takes the tier of a sized host.
+     */
     size?: ControlSize;
     /**
-     * Centered content: a number, a percent or an `<Icon>`. A changed icon (another `name`) cross-
-     * fades into the new one. Not rendered on `xs`; text only from `m`. A string or number child
-     * stays available as `aria-valuetext`.
+     * Content in the center (number, percent, `Icon`): text from `m`, an icon from `s`, nothing on `xs`. A string or number also becomes `aria-valuetext`.
      */
     children?: React.ReactNode;
     /**
-     * The data is on its way: a Skeleton ring of the same size (and legend rows), which cross-fades
-     * into the data. The root is `aria-busy`.
+     * The data is on its way: a Skeleton ring of the same diameter and stroke (and legend lines) that cross-fades into the data; the inner content waits, the root is `aria-busy`.
      */
     loading?: boolean;
     ref?: React.Ref<HTMLDivElement>;
@@ -50,5 +69,5 @@ export type ProgressCircleProps = Omit<React.HTMLAttributes<HTMLDivElement>, "ch
  * clockwise from the top (`role="group"` described by the distribution), with an optional legend
  * beside the ring.
  */
-export declare function ProgressCircle(props: ProgressCircleProps): import("react/jsx-runtime").JSX.Element;
+export declare function ProgressCircle(props: ProgressCircleProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 export {};

package/dist/components/radio/Radio.d.ts

@@ -6,33 +6,71 @@ export type RadioGroupLabels = {
     /** Muted marker after the group label when `optional`. */
     optional: string;
 };
+export declare const RADIO_GROUP_LABELS: RadioGroupLabels;
 export type RadioGroupProps = Omit<FieldRootDomProps, "dir"> & {
+    /**
+     * Controlled value (the `value` of the chosen `Radio.Root`).
+     */
     value?: string;
+    /**
+     * Initial value when uncontrolled.
+     */
     defaultValue?: string;
+    /**
+     * Called with the value of the newly chosen option.
+     */
     onValueChange?: (value: string) => void;
-    /** Native `name` shared by the radios; generated when omitted. */
+    /**
+     * Native `name` shared by the radios; generated when omitted.
+     */
     name?: string;
-    /** Tier. Default: the tier of the surrounding control (a form, a panel), else `m`. */
+    /**
+     * Tier of every circle, text, the label and the hint. Without it the group takes the tier of its host (LoginForm, Popover, a panel with a size), else `m`.
+     */
     size?: ControlSize;
+    /**
+     * Disables every option.
+     */
     disabled?: boolean;
-    /** Group heading above the options; names the radiogroup (`aria-labelledby`). */
+    /**
+     * Group heading above the options; names the radiogroup through `aria-labelledby`. Without it, pass `aria-label`.
+     */
     label?: React.ReactNode;
-    /** Red `*` after the label, native `required` on the radios, `aria-required` on the group. */
+    /**
+     * Red `*` after the label, native `required` on the radios and `aria-required` on the group.
+     */
     required?: boolean;
-    /** Muted `labels.optional` marker after the label. */
+    /**
+     * Muted marker right after the label text (`labels.optional`).
+     */
     optional?: boolean;
-    /** Help text under the options. Hidden while `error` is shown. */
+    /**
+     * Help text under the options. Hidden while `error` is shown.
+     */
     hint?: React.ReactNode;
-    /** Error message under the options; implies `invalid`. */
+    /**
+     * Error message under the options; implies `invalid`.
+     */
     error?: React.ReactNode;
-    /** Invalid state for every radio (`aria-invalid` on the group and the inputs). */
+    /**
+     * Danger ring on the unchecked circles and `aria-invalid` on the group and the inputs. A non-empty `error` implies it.
+     */
     invalid?: boolean;
-    /** `vertical` stacks the options, `horizontal` lays them out in a wrapping row. */
+    /**
+     * `vertical` stacks the options; `horizontal` lays them out in a wrapping row. Sets `aria-orientation`.
+     */
     orientation?: "vertical" | "horizontal";
-    /** Id of the `role="radiogroup"` element; generated when omitted. */
+    /**
+     * Id of the `role="radiogroup"` element (generated when omitted); also the default `name`.
+     */
     id?: string;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<RadioGroupLabels>;
-    /** `Radio.Root` options. */
+    /**
+     * The `Radio.Root` options.
+     */
     children?: React.ReactNode;
 };
 /**
@@ -44,13 +82,18 @@ declare namespace RadioGroup {
     var displayName: string;
 }
 export type RadioRootProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size" | "checked" | "defaultChecked" | "onChange" | "name" | "value"> & {
-    /** Value reported to `Radio.Group` when this option is chosen. */
+    /**
+     * Value reported to the group when this option is chosen.
+     */
     value: string;
-    /** Description under the option text. */
+    /**
+     * Description under the option text, linked through `aria-describedby`.
+     */
     hint?: React.ReactNode;
-    /** `Radio.Label`; without it only the circle renders (give it an `aria-label`). */
+    /**
+     * `Radio.Label`. Without it only the circle renders — give the root an `aria-label`.
+     */
     children?: React.ReactNode;
-    /** The native radio input. */
     ref?: React.Ref<HTMLInputElement>;
 };
 declare function RadioRoot({ id, value, hint, disabled: disabledProp, className, "aria-describedby": ariaDescribedBy, children, ref, ...inputRest }: RadioRootProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/scroll-container/ScrollContainer.d.ts

@@ -8,31 +8,45 @@ export type ScrollContainerAxis = "vertical" | "horizontal" | "both";
  */
 export type ScrollContainerEdges = "fade" | "shadow" | "none";
 export type ScrollContainerProps = React.HTMLAttributes<HTMLElement> & {
-    /** Root element. Default `div`; `AppShell.Main` renders `main`. */
-    as?: "div" | "main" | "aside" | "section" | "nav" | "article";
-    /** Scroll axis. Default `vertical`. */
+    /**
+     * Root element; a landmark tag when the region is one, `pre` for preformatted text (CodeBlock).
+     */
+    as?: "div" | "main" | "aside" | "section" | "nav" | "article" | "pre";
+    /**
+     * Scroll axis; the other axis is clipped (except `both`). On `horizontal` a vertical mouse wheel scrolls the strip sideways.
+     */
     axis?: ScrollContainerAxis;
-    /** `overscroll-behavior`. Default `contain`: nested panels do not chain scroll into the page. */
+    /**
+     * CSS `overscroll-behavior`; `contain` stops scroll chaining into the page.
+     */
     overscrollBehavior?: "auto" | "contain" | "none";
-    /** The edges where more content is hidden, along every scroll axis. Default `fade`. */
+    /**
+     * Edges that hide content: `fade` dissolves them over any background; `shadow` — a soft shadow on the region's own fill (a floating panel, a code well); `none` — plain edges.
+     */
     edges?: ScrollContainerEdges;
-    /** `thin` — the kit's quiet scrollbar (default); `hidden` — no scrollbar (keep `edges`). */
+    /**
+     * `thin` — the kit's quiet scrollbar; `hidden` — no scrollbar, keep `edges` on so the overflow stays visible.
+     */
     scrollbar?: "thin" | "hidden";
-    /** The person cannot scroll the region (wheel, touch, keys, autoscroll); it keeps its place. */
+    /**
+     * The person cannot scroll the region (wheel, touch, keys, a drag's auto-scroll); code still can. Sets `data-lock`.
+     */
     lock?: boolean;
-    /** Scrolling comes to rest on the start of a child (proximity snapping): strips of tiles. */
-    snap?: boolean;
     /**
-     * `end` — a chat or a log: the region starts at the end and stays there while content arrives,
-     * as long as the person is at the end; scrolled away, what they look at stays put. Default `start`.
+     * Scrolling comes to rest on the start of a child: `true` near one (strips of tiles and cards), `"mandatory"` always on one (board columns, a carousel). A Dnd drag inside turns it off; not with `anchor="end"`.
+     */
+    snap?: boolean | "mandatory";
+    /**
+     * `end` — a chat or a log: opens at the end and follows new content while the person is at the end; scrolled away, the view holds still.
      */
     anchor?: "start" | "end";
     /**
-     * The scroll position came near the start (older messages). A returned promise is pending until
-     * it settles: no new call meanwhile, `aria-busy`. Content added above keeps the view in place.
+     * Fires within 120 px of the start, once per approach: load older content. A returned promise blocks repeats and sets `aria-busy`; content added above keeps the view.
      */
     onReachStart?: ScrollEdgeHandler;
-    /** The scroll position came near the end (the next page of a feed); a promise works the same. */
+    /**
+     * The scroll position came within 120 px of the end: load the next page. Same once-per-approach and promise rules as `onReachStart`.
+     */
     onReachEnd?: ScrollEdgeHandler;
     ref?: React.Ref<HTMLElement>;
 };

package/dist/components/scroll-container/useScrollEdges.d.ts

@@ -1,29 +1,6 @@
 import * as React from "react";
+import type { ScrollRegion } from "../../hooks/useScrollRegion";
 export type ScrollEdgeHandler = () => void | Promise<void>;
-/**
- * What a ScrollContainer lets its content ask for (`useScrollRegion`): a chat list asks to go to
- * the end after its own message, to bring a message into view, and follows whether the reader is
- * at the end. The region scrolls only itself.
- */
-export type ScrollRegion = {
-    /** The reader is at the end (`anchor="end"`, within 4 px). */
-    atEnd: () => boolean;
-    /** Follows `atEnd`; returns the unsubscribe. */
-    subscribe: (listener: () => void) => () => void;
-    /** Scrolls to the end; `smooth` glides there (instant under reduced motion). */
-    scrollToEnd: (behavior?: ScrollBehavior) => void;
-    /** Scrolls the region (only) so `element` stands in its middle. */
-    scrollToElement: (element: Element, behavior?: ScrollBehavior) => void;
-    /**
-     * Content is about to change size in place (a message opens its transcript or its reactions
-     * row): for `ms`, what the reader sees stays still — even at the end of `anchor="end"`, so the
-     * change grows past the edge instead of pushing everything up. Call it right before the change.
-     */
-    hold: (ms: number) => void;
-};
-export declare const ScrollRegionContext: React.Context<ScrollRegion | null>;
-/** The ScrollContainer around this component, or `null` outside one. */
-export declare function useScrollRegion(): ScrollRegion | null;
 type Options = {
     anchor: "start" | "end";
     horizontal: boolean;

package/dist/components/segmented-control/SegmentedControl.d.ts

@@ -5,25 +5,51 @@ export type SegmentedControlLabels = {
     /** Muted marker after the label when `optional`. */
     optional: string;
 };
-export type SegmentedControlRootProps = Omit<FieldRootDomProps, "dir"> & Omit<FieldFrameProps, "focusRing"> & {
+export declare const SEGMENTED_CONTROL_LABELS: SegmentedControlLabels;
+export type SegmentedControlRootProps = Omit<FieldRootDomProps, "dir"> & FieldFrameProps & {
+    /**
+     * Selected value (controlled).
+     */
     value?: string;
+    /**
+     * Initial value (uncontrolled); `""` — nothing selected.
+     */
     defaultValue?: string;
+    /**
+     * Called with the new value on click or arrow keys.
+     */
     onValueChange?: (value: string) => void;
+    /**
+     * Disables the whole group.
+     */
     disabled?: boolean;
+    /**
+     * Control tier; the outer height equals the control height 28 · 32 · 36 · 40 · 48. Without it the tier of its host (a toolbar, a panel with a size), else `m`.
+     */
     size?: ControlSize;
     /**
-     * Stretch to the container width. Single-line segments tend to equal widths but never get
-     * narrower than their label; when they do not fit, the row scrolls.
+     * Fills the container; single-line segments tend to equal widths but never get narrower than their label — when they do not fit, the row scrolls.
      */
     fullWidth?: boolean;
-    /** Invalid state: a danger ring on the track and `aria-invalid` on the radiogroup. */
+    /**
+     * Danger inset ring, `aria-invalid` and `data-invalid` on the `radiogroup`; the control shakes once when an error arrives.
+     */
     invalid?: boolean;
-    /** Always render the support row so an appearing error does not shift the layout. */
+    /**
+     * Always render the support row, so an appearing error does not shift the layout.
+     */
     reserveSupportRow?: boolean;
-    /** Id of the `role="radiogroup"` element; generated when omitted. */
+    /**
+     * Id of the `radiogroup` element (generated when omitted); hint id is `<id>-hint`, error id `<id>-error`.
+     */
     id?: string;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<SegmentedControlLabels>;
-    /** `SegmentedControl.Item` segments. */
+    /**
+     * `SegmentedControl.Item`s (may be wrapped, e.g. in `Tooltip.Trigger`).
+     */
     children?: React.ReactNode;
 };
 /**
@@ -35,19 +61,25 @@ declare namespace SegmentedControlRoot {
     var displayName: string;
 }
 export type SegmentedControlItemProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value" | "children" | "type" | "role"> & {
+    /**
+     * Option value compared with the root value.
+     */
     value: string;
+    /**
+     * Disables this option; arrow keys skip it.
+     */
     disabled?: boolean;
     /**
-     * Palette hue of the option (e.g. a status): a dot of that hue before the content, and while
-     * selected the sliding thumb takes a soft fill of the hue with a ring of it.
+     * Palette hue: a dot before the content; while selected the thumb takes a soft fill of the hue with a ring of it.
      */
     color?: PaletteColor;
     /**
-     * Text, `SegmentedControl.Icon`, `SegmentedControl.Label`, `SegmentedControl.Count`,
-     * `SegmentedControl.Description`. A description makes the segment two-line. Only an icon makes the
-     * segment square: give it `aria-label` (and wrap it in a Tooltip).
+     * Text, `Icon`, `Label`, `Count`, `Description`. Only an icon → square segment; give it `aria-label`.
      */
     children: React.ReactNode;
+    /**
+     * Class on the segment button.
+     */
     className?: string;
     ref?: React.Ref<HTMLButtonElement>;
 };
@@ -56,7 +88,13 @@ declare namespace SegmentedControlItem {
     var displayName: string;
 }
 export type SegmentedControlIconProps = {
+    /**
+     * The icon, e.g. `<Icon name="theme.light" />`.
+     */
     children: React.ReactNode;
+    /**
+     * Class on the icon box.
+     */
     className?: string;
     ref?: React.Ref<HTMLSpanElement>;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, "children">;
@@ -65,18 +103,33 @@ declare namespace SegmentedControlIcon {
     var displayName: string;
 }
 export type SegmentedControlLabelProps = {
+    /**
+     * Title text.
+     */
     children: React.ReactNode;
+    /**
+     * Class on the label.
+     */
     className?: string;
     ref?: React.Ref<HTMLSpanElement>;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, "children">;
-/** Segment title on one line; never truncated. Plain text children are wrapped automatically. */
+/**
+ * Segment title on one line; never truncated. Plain text children are wrapped automatically. In a
+ * row collapsed to icons the visible title leaves the row and a VisuallyHidden copy keeps naming
+ * the segment.
+ */
 declare function SegmentedControlLabel({ children, className, ...rest }: SegmentedControlLabelProps): import("react/jsx-runtime").JSX.Element;
 declare namespace SegmentedControlLabel {
     var displayName: string;
 }
 export type SegmentedControlDescriptionProps = {
-    /** Muted second line; wrap the key value in `<strong>` to emphasize it. */
+    /**
+     * Second-line text; wrap a key value in `<strong>`.
+     */
     children: React.ReactNode;
+    /**
+     * Class on the description.
+     */
     className?: string;
     ref?: React.Ref<HTMLSpanElement>;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, "children">;
@@ -86,8 +139,13 @@ declare namespace SegmentedControlDescription {
     var displayName: string;
 }
 export type SegmentedControlCountProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children" | "color"> & {
-    /** Badge hue. Default `gray`. */
+    /**
+     * Badge hue.
+     */
     color?: PaletteColor;
+    /**
+     * The number.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };

package/dist/components/select/Select.d.ts

@@ -1,77 +1,152 @@
 import * as React from "react";
-import { type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
+import { type FieldFocusRingProps, type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
 import { type MenuGroupProps } from "../../internal/MenuGroup";
 import type { ControlSize } from "../../internal/states";
 import { SelectAction, SelectItem, SelectItemDescription, SelectItemIcon, SelectItemMeta, SelectItemText } from "./SelectItem";
 import { type SelectLabels } from "./selectContext";
 export type { SelectActionProps, SelectItemDescriptionProps, SelectItemIconProps, SelectItemMetaProps, SelectItemProps, SelectItemTextProps, } from "./SelectItem";
 export type { SelectLabels } from "./selectContext";
-type SelectRootBase = FieldRootDomProps & FieldFrameProps & {
+export declare const SELECT_LABELS: SelectLabels;
+type SelectRootBase = FieldRootDomProps & FieldFrameProps & FieldFocusRingProps & {
+    /**
+     * Field tier: trigger height, padding, text; the list rows, the label and the hint follow it. Without it the tier of its host (a form, a panel with a size), else `m`.
+     */
     size?: ControlSize;
+    /**
+     * Disabled field; the list never opens.
+     */
     disabled?: boolean;
+    /**
+     * Text in the trigger while nothing is picked.
+     */
     placeholder?: string;
-    /** Danger ring and `aria-invalid`; a non-empty `error` implies it. */
+    /**
+     * Danger inset ring and `aria-invalid`.
+     */
     invalid?: boolean;
-    /** Id of the trigger; generated when omitted. */
+    /**
+     * Id of the trigger; generated when omitted.
+     */
     id?: string;
+    /**
+     * Controlled open state of the list.
+     */
     open?: boolean;
+    /**
+     * Initial open state, uncontrolled.
+     */
     defaultOpen?: boolean;
+    /**
+     * Called on every open and close: trigger, pick, Escape, an outside press.
+     */
     onOpenChange?: (open: boolean) => void;
-    /** Clear segment in the trigger (and `Delete` / `Backspace` on it) while a value is selected. */
+    /**
+     * Escape closes the list and returns focus to the trigger.
+     */
+    closeOnEscape?: boolean;
+    /**
+     * A press outside the list and its trigger closes it; focus follows the pointer.
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * A clear segment before the chevron while a value is set; `Delete` / `Backspace` on the trigger clear too.
+     */
     clearable?: boolean;
-    /** Form field name: hidden inputs submit the value (one per value with `multiple`). */
+    /**
+     * Form field name: hidden inputs submit the value (`""` while empty; one input per value with `multiple`).
+     */
     name?: string;
-    /** The search query (`Select.Content searchable`), controlled; cleared when the list closes. */
+    /**
+     * Controlled search query (`Select.Content searchable`); together with `onSearchChange`. Cleared when the list closes.
+     */
     search?: string;
-    /** The initial query, uncontrolled. Default `""`. */
+    /**
+     * Initial query, uncontrolled.
+     */
     defaultSearch?: string;
-    /** Called with the new query: typing, and `""` when the list closes. */
+    /**
+     * Called with the new query: typing, and `""` when the list closes. Load the matching options here for a server search.
+     */
     onSearchChange?: (search: string) => void;
     /**
-     * The list filters its items by the query. `false` when the results come from a server: every
-     * item shows, highlighting of the query stays.
+     * The list filters its items by the query. `false` when the options come from a server: every item shows, the query is still marked in the labels.
      */
     filter?: boolean;
     /**
-     * Options are loading: a Spinner instead of the chevron, `aria-busy`, skeleton rows in the list
-     * while no item matches (items on screen stay).
+     * Options are loading: a Spinner instead of the chevron, `aria-busy`, skeleton rows in the list while no item matches; items already on screen stay.
      */
     loading?: boolean;
-    /** More options are loading at the end: skeleton rows after the items. */
+    /**
+     * More options are loading at the end: skeleton rows after the items.
+     */
     loadingMore?: boolean;
-    /** More options exist: reaching the end of the list calls `onLoadMore`. */
+    /**
+     * More options exist: reaching the end of the list calls `onLoadMore`.
+     */
     hasMore?: boolean;
-    /** Asked once per round when the end of the list scrolls into view or the highlight reaches it. */
+    /**
+     * Called once per round with `hasMore` when the end of the list scrolls into view or the highlight reaches the last option; set `loadingMore` while it runs.
+     */
     onLoadMore?: () => void | Promise<void>;
-    /** The options failed to load: replaces the list with the message in `role="alert"`. */
+    /**
+     * The options failed to load: the message replaces the list in `role="alert"`. Not the field `error` (validation).
+     */
     loadError?: React.ReactNode;
-    /** A retry button (`labels.retry`) under `loadError`; Enter in the open list runs it too. */
+    /**
+     * A retry button (`labels.retry`) under `loadError`; Enter in the open list runs it too.
+     */
     onRetry?: () => void;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<SelectLabels>;
+    /**
+     * Class on the field frame `<div>`.
+     */
     className?: string;
+    /**
+     * Trigger and Content.
+     */
     children: React.ReactNode;
 };
 type SelectSingleProps = {
+    /**
+     * Several values: checkboxes in the list, the list stays open on a pick, labels joined in the trigger.
+     */
     multiple?: false;
+    /**
+     * Controlled value; `string[]` with `multiple`.
+     */
     value?: string;
+    /**
+     * Initial value, uncontrolled.
+     */
     defaultValue?: string;
     /**
-     * Picked value; `""` after clearing. Return the save's promise: the value shows at once with a
-     * Spinner on the trigger and picks wait; resolve keeps it, reject rolls it back and announces
-     * `labels.changeFailed`.
+     * The picked value (`""` after clearing) or, with `multiple`, the new list. A promise: the value shows at once with a trigger Spinner, picks wait; reject rolls back and announces `labels.changeFailed`.
      */
     onValueChange?: (value: string) => void | Promise<void>;
 };
 type SelectMultipleProps = {
-    /** `string[]` value, checkboxes in the list, the list stays open on a pick. */
+    /**
+     * Several values: checkboxes in the list, the list stays open on a pick, labels joined in the trigger.
+     */
     multiple: true;
+    /**
+     * Controlled value; `string[]` with `multiple`.
+     */
     value?: string[];
+    /**
+     * Initial value, uncontrolled.
+     */
     defaultValue?: string[];
-    /** The new list; a promise as in single mode. */
+    /**
+     * The picked value (`""` after clearing) or, with `multiple`, the new list. A promise: the value shows at once with a trigger Spinner, picks wait; reject rolls back and announces `labels.changeFailed`.
+     */
     onValueChange?: (value: string[]) => void | Promise<void>;
 };
 export type SelectRootProps = SelectRootBase & (SelectSingleProps | SelectMultipleProps);
-declare function SelectRoot(props: SelectRootProps): import("react/jsx-runtime").JSX.Element;
+declare function SelectRoot(props: SelectRootProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 declare namespace SelectRoot {
     var displayName: string;
 }
@@ -89,10 +164,7 @@ export type SelectValueItem = {
 };
 export type SelectValueProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
     /**
-     * Single mode: renders the selected option in the trigger with the same parts as the row —
-     * leading `Avatar.Root` / `Thumbnail.Root`, `Select.ItemText`, `Select.ItemDescription`, and a
-     * trailing `Badge.Root` / `Select.ItemMeta` at the end. Not called while empty (the placeholder
-     * shows) and not used in `multiple` mode.
+     * Single mode: draws the picked option in the trigger with the same parts as the row (Avatar, ItemText, Badge…); not called while empty.
      */
     renderValue?: (item: SelectValueItem) => React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
@@ -112,10 +184,12 @@ declare namespace SelectTriggerIcon {
 }
 export type SelectContentProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "hidden" | "onKeyDown" | "onAnimationEnd"> & {
     /**
-     * A search field on top of the list; items filter by label, description and `keywords` (or the
-     * owner loads them: `Select.Root` `search`, `filter={false}`).
+     * A search field on top; items filter by label, description and `keywords` — or the owner loads them by the query (`search`, `filter={false}` on Root).
      */
     searchable?: boolean;
+    /**
+     * Items, groups, separators; `Select.Action` children stand under the list.
+     */
     children: React.ReactNode;
     /** The floating panel. */
     ref?: React.Ref<HTMLDivElement>;