prime-ui-kit 0.7.13 → 0.9.1

package/src/components/select/COMPONENT.md

@@ -1,291 +1,231 @@
 # Select
 
-**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
-
-## About
-
-A field for choosing from a closed set of options. By default (**`native`** `false`) it is a combobox — a trigger shows the current choice or a placeholder, and a portaled listbox lets the user pick. Set **`multiple`** to **`true`** on **`Select.Root`** for multiselect: **`value`** / **`defaultValue`** / **`onChange`** use **`string[]`**; picking toggles options; the list stays open until blur, outside click, or **Escape**; **`Select.Value`** shows selected labels joined with **`, `**; the listbox sets **`aria-multiselectable`**.
-
-With **`native`** `true`, **`Select.Root`** renders a native **`<select>`** (single) or **`<select multiple>`** (when **`multiple`** is **`true`**) with **`<option>`** / **`<optgroup>`** built from the same **`Select.Item`** (and optional **`Select.Group`**) tree.
-
-**When to use**
-
-- Forms, settings, and filters where one or many options must be chosen from a predefined list (role, country, departments, themes, intervals).
-- Flows where a compact trigger is enough and the full list should open on demand with keyboard support.
-- Long option lists structured with **`Select.Group`**, **`Select.GroupLabel`**, and **`Select.Separator`**.
-- Multiselect from the same list without chips or free-text creation — **`multiple`** on the combobox, or **`native`** + **`multiple`** for a platform **`<select multiple>`**.
-
-**When not to use**
-
-- Free text or ad-hoc tags with a chip row and optional “create” — prefer [Tag select](../tag-select/COMPONENT.md).
-- Async search-as-you-type or virtualized remote lists — this primitive expects static **`Select.Item`** children (extend at the app layer if needed).
-- Command or action menus — use [Dropdown](../dropdown/COMPONENT.md) when choices are actions, not form values.
-
-## Composition
-
-- **`Select.Root`** — owns **`native`**, **`multiple`**, value (string or **`string[]`** depending on **`multiple`**), **`size`**, **`hasError`**, **`disabled`**, **`placeholder`**. When **`native`** is `false`, the combobox also owns open state and highlight. Wrap everything else.
-- **`Select.Trigger`** — (non-**`native`** only) the combobox **`button`**. Put **`Select.Value`** inside; optionally **`Select.TriggerIcon`** before **`Select.Value`**. The implementation sets the trigger **`id`**; associate an external [Label](../label/COMPONENT.md) with **`aria-labelledby`** pointing at the label’s **`id`**.
-- **`Select.Value`** — (non-**`native`** only) displays the selected label(s): one label in single mode, or comma-separated labels in **`multiple`** mode, otherwise **`placeholder`** when empty.
-- **`Select.Content`** — when **`native`** is `false`: portaled **`role="listbox"`** with **`display: none`** and **`aria-hidden`** while closed (items stay mounted so **`Select.Item`** can register labels for **`Select.Value`** — do not unmount the list when closed). Closed panel uses **`pointer-events: none`** so fixed layers in **`body`** do not block navigation. With **`multiple`**, the listbox gets **`aria-multiselectable="true"`**. When **`native`** is `true`, **`Select.Content`** is optional; items build the **`<select>`** DOM.
-- **`Select.Item`** — one option per row; optional **`Select.ItemIcon`** children are split into a leading icon slot vs label text (stable marker on **`Select.ItemIcon`**, not only `===` type — duplicate module chunks in the bundle still work). Row spacing tokens are applied on the item (**`data-size`** from root). Use **`label`** when the trigger should show different text than the row content.
-- **`Select.Group`** / **`Select.GroupLabel`** / **`Select.Separator`** — optional structure inside **`Select.Content`** (or under **`native`** root for optgroups).
-
-### Canonical example (single)
-
-```tsx
-import * as React from "react";
-import { Label, Select, Typography } from "prime-ui-kit";
-
-export function Example() {
-  const labelId = React.useId();
-
-  return (
-    <div>
-      <Label.Root id={labelId}>
-        Department
-      </Label.Root>
-      <Select.Root placeholder="Choose">
-        <Select.Trigger aria-labelledby={labelId}>
-          <Select.Value />
-        </Select.Trigger>
-        <Select.Content>
-          <Select.Item value="eng">Engineering</Select.Item>
-          <Select.Item value="design">Design</Select.Item>
-          <Select.Item value="sales">Sales</Select.Item>
-        </Select.Content>
-      </Select.Root>
-      <Typography.Root as="p" variant="caption" tone="muted">
-        Used for routing internal requests only.
-      </Typography.Root>
-    </div>
-  );
-}
-```
-
-### Multiselect (combobox)
-
+**Category:** selection
+**Kind:** field
+
+> A field for choosing one value (or several with `multiple`) from a closed list.
+
+## When to use
+- One value from a closed list of 5+ options in forms, filters and settings: country, role, time zone.
+- A long list where search helps (`Select.Content searchable`, `keywords`).
+- A few values from a short list shown as comma-separated text (`multiple`).
+- Options that need a picture, a second line or a trailing value (rich options).
+
+## When not to use
+- 2–5 options that should all be visible → use [Radio](../radio/COMPONENT.md) or [SegmentedControl](../segmented-control/COMPONENT.md).
+- The OS picker on a mobile-first form → use [NativeSelect](../native-select/COMPONENT.md).
+- Many values shown as removable tags, or creating new values → use [TagSelect](../tag-select/COMPONENT.md).
+- Free text → use [Input](../input/COMPONENT.md).
+- A menu of actions (not a value) → use [Dropdown](../dropdown/COMPONENT.md).
+- Global search / command palette → use [CommandMenu](../command-menu/COMPONENT.md).
+- Dates → use [Datepicker](../datepicker/COMPONENT.md).
+
+## Import
 ```tsx
-import * as React from "react";
 import { Select } from "prime-ui-kit";
-
-export function MultiExample() {
-  const [value, setValue] = React.useState<string[]>(["eng"]);
-
-  return (
-    <Select.Root multiple value={value} onChange={setValue} placeholder="Choose departments">
-      <Select.Trigger aria-label="Departments">
-        <Select.Value />
-      </Select.Trigger>
-      <Select.Content>
-        <Select.Item value="eng">Engineering</Select.Item>
-        <Select.Item value="design">Design</Select.Item>
-        <Select.Item value="sales">Sales</Select.Item>
-      </Select.Content>
-    </Select.Root>
-  );
-}
 ```
 
-### Native `<select>` (`native`)
-
-```tsx
-import { Select } from "prime-ui-kit";
-
-export function NativeExample() {
-  return (
-    <Select.Root native placeholder="Choose">
-      <Select.Item value="a">Option A</Select.Item>
-      <Select.Item value="b">Option B</Select.Item>
-    </Select.Root>
-  );
-}
+## Anatomy
 ```
-
-### Native `<select multiple>` (`native` + `multiple`)
-
-```tsx
-import * as React from "react";
-import { Select } from "prime-ui-kit";
-
-export function NativeMultiExample() {
-  const [value, setValue] = React.useState<string[]>(["a"]);
-
-  return (
-    <Select.Root native multiple value={value} onChange={setValue}>
-      <Select.Item value="a">Option A</Select.Item>
-      <Select.Item value="b">Option B</Select.Item>
-    </Select.Root>
-  );
-}
+Select.Root                       field frame: label · control · hint/error; value, open, search
+├── Select.Trigger                <button role="combobox">: [icon] [value] [clear] [chevron]
+│   ├── Select.TriggerIcon        optional leading glyph
+│   └── Select.Value              picked label or placeholder (renderValue for a rich trigger)
+└── Select.Content                portaled panel, mounted while open
+    ├── search row                with `searchable`
+    ├── role="listbox"
+    │   ├── Select.Group          role="group", named by `label`
+    │   │   └── Select.Item       role="option": [checkbox] [icon / Thumbnail] [text] [meta] [check]
+    │   │       ├── Select.ItemIcon
+    │   │       ├── Select.ItemText · Select.ItemDescription
+    │   │       └── Select.ItemMeta
+    │   └── Select.Separator      full-bleed Divider
+    └── empty state               compact EmptyPage
 ```
 
-You can wrap items in **`Select.Content`** for parity with the composable tree; behavior is the same.
-
-### Playground snippets (live demos)
-
-These files power **`playground/sections/SelectSection.tsx`** (Russian copy in the playground UI). Order matches the section.
-
-| File | Intent |
-|------|--------|
-| `playground/snippets/select/sizes.tsx` | Four **`size`** values **`s`–`xl`** in one column |
-| `playground/snippets/select/states.tsx` | Placeholder only, **`defaultValue`**, root **`disabled`**, **`hasError`** |
-| `playground/snippets/select/controlled.tsx` | **`value`** / **`onChange`** with caption showing parent state |
-| `playground/snippets/select/composition.tsx` | **`Select.TriggerIcon`**, **`Select.ItemIcon`**, item **`label`** vs short row text |
-| `playground/snippets/select/full-width.tsx` | Trigger fills a narrow shell (**`width: 100%`** from kit styles) |
-| `playground/snippets/select/native.tsx` | **`Select.Root`** **`native`** with optional **`Select.Content`** wrapper |
-| `playground/snippets/select/multiple.tsx` | **`Select.Root`** **`multiple`**: **`string[]`** value, list stays open on pick |
-| `playground/snippets/select/features.tsx` | **`Group`** / **`GroupLabel`** / **`Separator`**, disabled item, long list + scroll |
-
-### Examples next to this file
-
-Runnable examples use **`@/`** in the workspace; published consumers import **`prime-ui-kit`**. **`pattern-*`** files mirror the playground snippets above in English (same APIs).
-
-| File | Intent |
-|------|--------|
-| `examples/pattern-sizes.tsx` | **`sizes.tsx`** snippet |
-| `examples/pattern-states.tsx` | **`states.tsx`** snippet |
-| `examples/pattern-controlled.tsx` | **`controlled.tsx`** snippet |
-| `examples/pattern-multiple.tsx` | **`multiple.tsx`** snippet |
-| `examples/pattern-composition.tsx` | **`composition.tsx`** snippet |
-| `examples/pattern-full-width.tsx` | **`full-width.tsx`** snippet |
-| `examples/pattern-native.tsx` | **`native.tsx`** snippet |
-| `examples/pattern-features.tsx` | **`features.tsx`** snippet |
-
-### Additional scenarios
-
-| File | Intent |
-|------|--------|
-| [`./examples/01-country.tsx`](./examples/01-country.tsx) | Visible **`Label.Root`** + **`aria-labelledby`** on **`Select.Trigger`** and helper copy |
-| [`./examples/02-controlled.tsx`](./examples/02-controlled.tsx) | Controlled **`value`** / **`onChange`** with **`Label.Root`** (same tier options as **`pattern-controlled.tsx`**) |
-| [`./examples/03-groups.tsx`](./examples/03-groups.tsx) | Time zones with **`Select.Group`**, **`Select.GroupLabel`**, **`Select.Separator`** |
-| [`./examples/04-full-width-form.tsx`](./examples/04-full-width-form.tsx) | Multi-field form column; triggers span the track |
-
-**LLM note:** Prefer **`pattern-*`** and `playground/snippets/select/*.tsx` for parity with live demos; use **`01`–`04`** for labeled forms and richer scenarios. This page keeps the contract (rules + API tables) authoritative.
-
-## Rules
-
-- **`native`** — default **`false`**. **`true`**: **`<select>`** (or **`<select multiple>`** when **`multiple`** is **`true`**) with kit styling; combobox trigger, portaled listbox, and listbox keyboard model are not used for the single-select native path. Options are collected by walking **`children`** for **`Select.Item`** (and **`Select.Group`** / **`Select.GroupLabel`** → **`<optgroup>`**; **`Select.Separator`** is skipped). **`placeholder`** adds a first **`<option value="">`** for single native select; do not use **`value=""`** on an **`Select.Item`** if you rely on that placeholder. **`Select.ItemIcon`** / **`Select.TriggerIcon`** are not represented in the native control.
-- **`multiple`** — default **`false`**. **`true`**: use **`string[]`** for **`value`**, **`defaultValue`**, and **`onChange`**. Combobox: toggling an option does not close the list; **`Select.Value`** joins labels in selection order. Native: platform rules for **`<select multiple>`** (e.g. modifier keys for multi-select on desktop).
-- **Controlled:** set **`value`** and **`onChange`** together (types follow **`multiple`**). **Uncontrolled:** use **`defaultValue`** or neither; initial empty selection is **`undefined`** / **`[]`** as appropriate.
-- **`onChange`** fires when the controlled value changes (string or **`string[]`**).
-- **`disabled`** on **`Select.Root`** prevents opening the list and selecting; the trigger is inactive (combobox) or the **`<select>`** is disabled (native).
-- **`disabled`** on **`Select.Item`** skips that option for pointer selection and for arrow-key navigation among enabled options only.
-- **`hasError`** on **`Select.Root`** applies error styling to the trigger (combobox) or native select.
-- **Width:** there is no **`fullWidth`** prop on **`Select.Root`**. The combobox trigger uses **`width: 100%`** — constrain with the parent layout.
-- **`Select.Content`** uses **`Portal`**; **`Select.Item`** effects call **`onInitLabel`** so **`Select.Value`** stays aligned with item labels. While open, the listbox **repositions** like **Dropdown** / **Popover**: **`resize`** on **`window`** and **`visualViewport`**, **`scroll`** on the trigger’s scroll ancestors, and **`ResizeObserver`** on the panel when the runtime supports it — the panel stays anchored to the trigger when the page or a scroll container moves.
-- **`Select.Content`** (combobox): on open the listbox receives focus; **Escape** and outside click close. **Enter** / **Space** on a highlighted option applies selection (toggle in **`multiple`** mode). With **`multiple`**, the listbox is **`aria-multiselectable`**.
-- **`Select.Trigger`** is **`role="combobox"`** with **`aria-expanded`**, **`aria-haspopup="listbox"`**, **`aria-controls`**. Items use **`role="option"`**, **`aria-selected`**, **`aria-disabled`** when disabled.
-- If there is no visible label on the trigger, set **`aria-label`** on **`Select.Trigger`**, or **`aria-labelledby`** with an external [Label](../label/COMPONENT.md).
-- List position is resolved internally; there are no public **`side`** / **`align`** props on **`Select.Content`**.
-
 ## API
 
-### Select.Root
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-Discriminated by **`multiple`** and **`native`**:
-
-| Mode | `value` / `defaultValue` | `onChange` |
-|------|--------------------------|------------|
-| Default (combobox, single) | `string` | `(value: string) => void` |
-| Combobox **`multiple`** | `string[]` | `(value: string[]) => void` |
-| **`native`** (single) | `string` | `(value: string) => void` |
-| **`native`** + **`multiple`** | `string[]` | `(value: string[]) => void` |
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Token tier: trigger height, type scale, padding, icon sizes |
-| multiple | `boolean` | `false` | No | **`true`**: multiselect; value types are **`string[]`** |
-| value | `string` or `string[]` | — | No | Controlled selected value(s) |
-| defaultValue | `string` or `string[]` | — | No | Initial value when uncontrolled |
-| onChange | `(value: string) => void` or `(value: string[]) => void` | — | No | Fires after selection changes |
-| disabled | `boolean` | — | No | Disables the control |
-| placeholder | `string` | — | No | Shown in the trigger when empty (combobox); native single: empty **`<option>`** |
-| hasError | `boolean` | `false` | No | Error styling |
-| native | `boolean` | `false` | No | **`true`**: native **`<select>`** (single or **`multiple`**) |
-| children | `React.ReactNode` | — | Yes | **`Select.Trigger`** + **`Select.Content`** (combobox) or **`Select.Item`** tree (**`native`**) |
+### Select.Root
+`ref` → `HTMLDivElement`. The field frame (label row · control · support row) holding the value, the open state and the search query.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| string[]` | — | Controlled value; `string[]` with `multiple`. |
+| `defaultValue` | `string \| string[]` | — | Initial value, uncontrolled. |
+| `onValueChange` | `(value: string) => void \| (value: string[]) => void` | — | Called with the picked value (`""` after clearing), or the new list with `multiple`. |
+| `multiple` | `boolean` | `false` | Several values: checkboxes in the list, the list stays open on a pick, labels joined in the trigger. |
+| `open` | `boolean` | — | Controlled open state of the list. |
+| `defaultOpen` | `boolean` | `false` | Initial open state, uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, pick, Escape, an outside press. |
+| `label` | `ReactNode` | — | Field label above; names the trigger. |
+| `hint` | `ReactNode` | — | Support text under the field; linked by `aria-describedby`. |
+| `error` | `ReactNode` | — | Error message; replaces the hint and implies `invalid`. |
+| `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the trigger. |
+| `optional` | `boolean` | — | Muted `labels.optional` after the label. |
+| `invalid` | `boolean` | `false` | Danger inset ring and `aria-invalid`. |
+| `disabled` | `boolean` | `false` | Disabled field; the list never opens. |
+| `loading` | `boolean` | `false` | Spinner instead of the chevron, `aria-busy`, a status row in the list. |
+| `clearable` | `boolean` | `false` | A clear segment before the chevron while a value is set; `Delete` / `Backspace` on the trigger clear too. |
+| `placeholder` | `string` | — | Text in the trigger while nothing is picked. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Field tier: trigger height, padding, text; the list rows, the label and the hint follow it. |
+| `focusRing` | `boolean` | `true` | `false` hides the visual focus ring (`data-focus-ring="false"`), never focus or the error ring. |
+| `id` | `string` | — | Id of the trigger; generated when omitted. |
+| `labels` | `Partial<SelectLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — (required) | Trigger and Content. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
 
 ### Select.Trigger
+`ref` → `HTMLButtonElement`. `<button role="combobox">` with the value, the clear segment and the chevron (a Spinner while `loading`). + native button props.
 
-`forwardRef` to the underlying **`button`**. Props omit **`id`**, **`type`**, and **`role`** (set by the implementation).
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | No | Usually **`Select.Value`** and optionally **`Select.TriggerIcon`** |
-| className | `string` | — | No | Additional class on the button |
-| disabled | `boolean` | — | No | Native disabled; final state also respects **`Select.Root`** **`disabled`** |
-| ref | `React.Ref<HTMLButtonElement>` | — | No | Ref to the button element |
-| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "id" \| "type" \| "role">` | — | No | e.g. **`aria-label`**, **`aria-labelledby`**, event handlers |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | `Select.TriggerIcon`, `Select.Value`, optionally a Badge after it. |
 
 ### Select.Value
+`ref` → `HTMLSpanElement`. The picked label (labels joined with `multiple`) with an ellipsis, or the placeholder.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the value / placeholder span |
-
-### Select.TriggerIcon
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `renderValue` | `(item: { value: string; label: string }) => ReactNode` | — | Single mode: draws the picked option in the trigger with the row parts (Thumbnail, ItemText, ItemDescription); not called while empty. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | No | Icon or other content to the left of the value |
-| className | `string` | — | No | Wrapper class |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other **`span`** attributes |
+### Select.TriggerIcon · Select.ItemIcon
+`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` with a leading glyph at the tier icon size: before the value / before the option label. + native `<span>` props.
 
 ### Select.Content
+`ref` → `HTMLDivElement` (the panel). Portal + the floating list panel, mounted while open and during its exit animation (closed, the items render hidden in place so the trigger knows their labels), shown with the overlay motion. Holds the search row, the `role="listbox"` and the empty state.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the portaled listbox container |
-| children | `React.ReactNode` | — | Yes | Items, groups, and separators (listbox portal stays mounted; hidden while closed) |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `searchable` | `boolean` | `false` | A search field on top; items filter by label, description and `keywords`. |
+| `children` | `ReactNode` | — (required) | Items, groups, separators. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "hidden" \| "onKeyDown" \| "onAnimationEnd">` | — | `className` and the other attributes of the panel. |
 
 ### Select.Item
+`ref` → `HTMLDivElement`. `role="option"` with `aria-selected`; a check on the end (single) or a Checkbox.Indicator in front (`multiple`).
 
-`forwardRef` to the option root **`div`**.
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `string` | — | Yes | Submitted / controlled string value |
-| label | `string` | — | No | Text shown in the trigger; otherwise derived from non-icon children or **`value`** |
-| disabled | `boolean` | — | No | Option not selectable |
-| className | `string` | — | No | Class on the option row |
-| children | `React.ReactNode` | — | Yes | Label content and optional **`Select.ItemIcon`** |
-| ref | `React.Ref<HTMLDivElement>` | — | No | Ref on the option root |
-
-### Select.ItemIcon
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — (required) | Value of the option. |
+| `label` | `string` | — | Text in the trigger and for typeahead; defaults to `Select.ItemText`, then the plain text. |
+| `keywords` | `string` | — | Extra words for the search. |
+| `disabled` | `boolean` | `false` | Muted, skipped by the keyboard, not selectable. |
+| `children` | `ReactNode` | — (required) | Text, or `Select.ItemIcon`, `Thumbnail.Root`, `Select.ItemText`, `Select.ItemDescription`, `Select.ItemMeta` as direct children. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | No | Icon before the item text |
-| className | `string` | — | No | Wrapper class |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other **`span`** attributes |
+### Select.ItemText · Select.ItemDescription · Select.ItemMeta
+`ref` → `HTMLSpanElement`. Rich option parts: the title (its text is the label) / a muted second line (searchable; makes the row two-line) / a trailing muted value before the check. A `Thumbnail.Root` child is the leading media, sized to the tier unless it sets `size`. + native `<span>` props.
 
 ### Select.Group
+`ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while the search leaves none of its options. + native `<div>` props.
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the **`role="group"`** container |
-| children | `React.ReactNode` | — | No | Group label and items |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other **`div`** attributes |
-
-### Select.GroupLabel
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the label |
-| children | `React.ReactNode` | — | No | Group heading text |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other **`div`** attributes |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
 
 ### Select.Separator
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the **`hr`** |
-| …rest | `React.HTMLAttributes<HTMLHRElement>` | — | No | Other **`hr`** attributes |
+`ref` → `HTMLDivElement`. A full-bleed Divider between groups; hidden while searching.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the divider. |
+
+## Variants
+No `variant` or `tone`. The trigger is the field look (fill, inset control border, tier radius); the panel is the shared floating surface with menu rows.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28 trigger, 12/16 text, 24 rows | Dense table filters | |
+| `s` | 32 trigger, 13/20 text, 28 rows | Compact toolbars and side panels | |
+| `m` | 36 trigger, 14/20 text, 32 rows | Regular forms | yes |
+| `l` | 40 trigger, 16/24 text, 36 rows | Spacious forms | |
+| `xl` | 48 trigger, 16/24 text, 40 rows | Touch-first screens | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `multiple` | checkbox on the left of every row, the list stays open, labels joined in the trigger | A few values from a short list | `false` |
+| `clearable` | × segment before the chevron while a value is set (full height, one hover wash) | The field is optional and can be reset | `false` |
+| `loading` | spinner instead of the chevron, a «Загрузка…» row in the list | Options load asynchronously | `false` |
+| `searchable` (Content) | search row with a faint hairline at the top of the list | More than ~10 options | `false` |
+| rich options | `Thumbnail.Root` or `Select.ItemDescription` in an item: a two-line row; the trigger the same with `renderValue` | Products, people, delivery tariffs | |
+
+**Combinations** — `renderValue` is single-mode only; with `multiple` the trigger shows the joined labels. `error` implies `invalid`. A status Badge can follow `Select.Value` inside the trigger; it takes the tier one step down by itself.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| empty | no value | `data-placeholder="true"` on Value, placeholder color |
+| open | `open` / click / arrows | trigger `data-state="open"`, `aria-expanded`; panel `data-state`, `data-side`; chevron turns 180° |
+| invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the trigger; error text below |
+| disabled | `disabled` | native `disabled`, `data-disabled="true"` |
+| loading | `loading` | `data-loading="true"`, `aria-busy`; status row in the list |
+| searching | typing in the search | panel `data-searching="true"`; groups without matches and separators hide; the match in an option's title, description and plain text is a `<mark>` in `accent-text` (not in the trigger) |
+| option highlighted / selected / disabled | keyboard and pointer / value / `disabled` | `data-highlighted`, `data-selected` + `aria-selected`, `data-disabled` + `aria-disabled`; highlight is a fill only |
+
+## Layout & spacing
+- The trigger is 100% wide; set the width with the layout (grid column, max-width wrapper).
+- Label → field: tier `label-gap`; field → hint: tier `hint-gap`; field → field in a form: `--prime-space-5`.
+- Panel: at least the trigger width and `--prime-panel-min-width`, at most twice that; max height `--prime-panel-max-height` (scrolls); flips near the viewport edge.
+- Long values truncate with an ellipsis in the trigger.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` · `Space` · `ArrowDown` · `ArrowUp` | On the trigger open the list; focus moves into the search or the list. |
+| `ArrowDown` · `ArrowUp` · `Home` · `End` | In the list move the highlight over the enabled options, wrapping. |
+| `Enter` · `Space` | Pick the highlighted option; a single pick closes the list and returns focus to the trigger. |
+| `A–Я` | Typeahead: the highlight jumps to the option starting with the letter or the typed prefix. |
+| `Delete` · `Backspace` | On the trigger with `clearable` clear the value. |
+| `Escape` | Closes the list; focus returns to the trigger. |
+| `Tab` | Returns focus to the trigger, closes the list and moves on from the trigger. |
+
+### ARIA
+- The trigger is `role="combobox"` with `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`; `label` names it.
+- The list is `role="listbox"` (`aria-multiselectable` with `multiple`); options are `role="option"` with `aria-selected`; the highlight goes through `aria-activedescendant`.
+- The hint and the error are linked by `aria-describedby`; the error sets `aria-invalid`; loading sets `aria-busy`.
+- An outside press closes the list without moving focus back: focus follows the pointer (foundation §8).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `search` | `"Поиск"` | Placeholder and accessible name of the search field. |
+| `empty` | `"Ничего не найдено"` | Empty state: no items or nothing matches. |
+| `emptyHint` | `"Попробуйте изменить запрос"` | Second line of the empty state while searching; `""` hides it. |
+| `loading` | `"Загрузка…"` | Status row while `loading`. |
+| `clear` | `"Очистить"` | Tooltip of the clear segment. |
+| `optional` | `"необязательно"` | Muted marker after the label when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A labelled field with a placeholder; picking an option closes the list and shows its label — `label`, `placeholder`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier; the label, the list rows and the hint take the tier of the field — `size`. |
+| [states.tsx](examples/states.tsx) | A default field next to a disabled, a loading, an invalid one and a list with nothing in it — `disabled`, `loading`, `invalid`, `labels`. |
+| [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. |
+| [with-icon.tsx](examples/with-icon.tsx) | A leading icon in the trigger and an icon before every option label — `Select.TriggerIcon`, `Select.ItemIcon`. |
+| [multiple.tsx](examples/multiple.tsx) | Several values: checkboxes in the list, the list stays open on a pick, labels joined in the trigger — `multiple`. |
+| [searchable.tsx](examples/searchable.tsx) | A long list with a search field: options match their label and keywords, groups and the separator hide while searching — `searchable`, `keywords`, `Select.Group`. |
+| [clearable.tsx](examples/clearable.tsx) | An optional field that can be reset: a clear segment before the chevron, Delete or Backspace on the trigger — `clearable`. |
+| [rich-options.tsx](examples/rich-options.tsx) | Options with a picture, a second line and a price; the trigger draws the picked option with the same parts — `renderValue`, `Select.ItemText`, `Select.ItemDescription`, `Select.ItemMeta`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the value: the plan drives the price under the field and a button resets it — `value`, `onValueChange`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the list: a button opens it from code, a pick or Escape closes it — `open`, `onOpenChange`. |
+| [in-form.tsx](examples/in-form.tsx) | Regional settings form: the required country is checked on submit, the error replaces the hint — `required`, `error`, `hint`. |
+
+## Mistakes
+- A Label + `aria-labelledby` next to the field → pass `label`, `hint`, `error` to `Select.Root`.
+- A function inside `Select.Value` → use `renderValue`.
+- `Select.Group` with a separate heading element → pass the heading as `label`.
+- Rich parts wrapped in your own `<div>` → put them as direct children of the item.
+- A system select via a prop → use [NativeSelect](../native-select/COMPONENT.md).
+- Mixing sizes in one form → keep every field of a form at one `size`.
 
 ## Related
-
-- [Label](../label/COMPONENT.md) — visible field label; pair with **`aria-labelledby`** on **`Select.Trigger`** when needed.
-- [Hint](../hint/COMPONENT.md) — helper or error text below the field.
-- [Input](../input/COMPONENT.md) — free-form text when a fixed list is not appropriate.
-- [Tag select](../tag-select/COMPONENT.md) — chips, filter input, optional creatable values.
-- [Dropdown](../dropdown/COMPONENT.md) — action menus, not single form values.
-- [Modal](../modal/COMPONENT.md) / [Drawer](../drawer/COMPONENT.md) — nested focus and stacking when the select sits inside overlays.
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (list), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in `multiple`), [Spinner](../spinner/COMPONENT.md) (`loading`), [EmptyPage](../empty-page/COMPONENT.md) (empty state), [Divider](../divider/COMPONENT.md) (`Separator`), [Thumbnail](../thumbnail/COMPONENT.md) (rich media), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame)
+- **See also:** [NativeSelect](../native-select/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Radio](../radio/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/select/examples/clearable.tsx

@@ -0,0 +1,23 @@
+/** An optional field that can be reset: a clear segment before the chevron, Delete or Backspace on the trigger — `clearable`. */
+import { Select } from "prime-ui-kit";
+
+export default function SelectClearableExample() {
+  return (
+    <Select.Root
+      label="Менеджер клиента"
+      optional
+      clearable
+      defaultValue="anna"
+      placeholder="Не назначен"
+    >
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        <Select.Item value="anna">Анна Петрова</Select.Item>
+        <Select.Item value="ivan">Иван Смирнов</Select.Item>
+        <Select.Item value="olga">Ольга Ким</Select.Item>
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/src/components/select/examples/controlled-open.tsx

@@ -0,0 +1,30 @@
+/** The parent owns the list: a button opens it from code, a pick or Escape closes it — `open`, `onOpenChange`. */
+import { Button, Select } from "prime-ui-kit";
+import * as React from "react";
+
+export default function SelectControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Select.Root
+        label="Склад отгрузки"
+        placeholder="Склад не выбран"
+        open={open}
+        onOpenChange={setOpen}
+      >
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="msk">Москва, Южные ворота</Select.Item>
+          <Select.Item value="spb">Санкт-Петербург, Шушары</Select.Item>
+          <Select.Item value="ekb">Екатеринбург, Кольцово</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Выбрать склад
+      </Button.Root>
+    </>
+  );
+}

package/src/components/select/examples/controlled.tsx

@@ -0,0 +1,34 @@
+/** The parent owns the value: the plan drives the price under the field and a button resets it — `value`, `onValueChange`. */
+import { Button, Select, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const PRICES: Record<string, string> = {
+  free: "0 ₽ в месяц",
+  pro: "990 ₽ в месяц",
+  team: "4 900 ₽ в месяц",
+};
+
+export default function SelectControlledExample() {
+  const [plan, setPlan] = React.useState("pro");
+
+  return (
+    <>
+      <Select.Root label="Тариф" value={plan} onValueChange={setPlan} placeholder="Выберите тариф">
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="free">Бесплатный</Select.Item>
+          <Select.Item value="pro">Профессиональный</Select.Item>
+          <Select.Item value="team">Командный</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Typography as="p" variant="body-s" tone="secondary">
+        {PRICES[plan] ?? "Тариф не выбран"}
+      </Typography>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setPlan("free")}>
+        Вернуть бесплатный
+      </Button.Root>
+    </>
+  );
+}