prime-ui-kit 0.10.0 → 0.11.1

package/src/components/scroll-container/examples/lock.tsx

@@ -0,0 +1,49 @@
+/** While an order is opened for review, the queue behind it holds still: no wheel, touch, key or drag moves it — `lock`. */
+import { Button, Card, ScrollContainer, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const ORDERS = [
+  "Заказ № 1040 · ООО «Северный склад»",
+  "Заказ № 1041 · АО «Тепломонтаж»",
+  "Заказ № 1042 · ИП Кравцова",
+  "Заказ № 1043 · ООО «Логистик Плюс»",
+  "Заказ № 1044 · ООО «Альфа Ритейл»",
+  "Заказ № 1045 · АО «ПромСнаб»",
+  "Заказ № 1046 · ООО «Городские аптеки»",
+  "Заказ № 1047 · ООО «Вектор»",
+];
+
+export default function ScrollContainerLockExample() {
+  const [reviewing, setReviewing] = React.useState(false);
+
+  return (
+    <Card.Root role="region" className={styles.card} aria-label="Очередь заказов">
+      <div className={styles.cardHeader}>
+        <Typography as="h3" variant="title-s">
+          Очередь заказов
+        </Typography>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          pressed={reviewing}
+          onClick={() => setReviewing((current) => !current)}
+        >
+          {reviewing ? "Закрыть проверку" : "Проверить заказ"}
+        </Button.Root>
+      </div>
+      <ScrollContainer lock={reviewing}>
+        <ul className={styles.list}>
+          {ORDERS.map((order) => (
+            <li key={order}>
+              <Typography as="span" variant="body-m">
+                {order}
+              </Typography>
+            </li>
+          ))}
+        </ul>
+      </ScrollContainer>
+    </Card.Root>
+  );
+}

package/src/components/scroll-container/examples/scrollbar.tsx

@@ -0,0 +1,52 @@
+/** The kit's quiet thin bar on a list and no bar on a strip of chips, where the faded edges show the overflow — `scrollbar`. */
+import { Badge, Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const CLIENTS = [
+  "ООО «Северный склад»",
+  "АО «Тепломонтаж»",
+  "ИП Кравцова",
+  "ООО «Логистик Плюс»",
+  "ООО «Альфа Ритейл»",
+  "АО «ПромСнаб»",
+  "ООО «Городские аптеки»",
+  "ООО «Вектор»",
+  "ИП Сафонов",
+];
+const TAGS = ["Новые", "В работе", "Ждут оплаты", "Отгружены", "Возвраты", "Архив", "Черновики"];
+
+export default function ScrollContainerScrollbarExample() {
+  return (
+    <div className={styles.layout}>
+      <Card.Root role="region" className={styles.card} aria-label="Клиенты">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          thin
+        </Typography>
+        <ScrollContainer>
+          <ul className={styles.list}>
+            {CLIENTS.map((client) => (
+              <li key={client}>
+                <Typography as="span" variant="body-m">
+                  {client}
+                </Typography>
+              </li>
+            ))}
+          </ul>
+        </ScrollContainer>
+      </Card.Root>
+      <Card.Root role="region" className={styles.card} aria-label="Фильтры заказов">
+        <Typography as="h3" variant="title-s" className={styles.cardTitle}>
+          hidden
+        </Typography>
+        <ScrollContainer axis="horizontal" scrollbar="hidden">
+          <div className={styles.strip}>
+            {TAGS.map((tag) => (
+              <Badge.Root key={tag}>{tag}</Badge.Root>
+            ))}
+          </div>
+        </ScrollContainer>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/scroll-container/examples/snap.tsx

@@ -0,0 +1,36 @@
+/** A strip of warehouse cards that comes to rest on a card's start, scrolled by touch, a trackpad or the mouse wheel — `snap`, `axis`. */
+import { Card, ScrollContainer, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const WAREHOUSES = [
+  { id: "msk", city: "Москва", stock: "12 480 позиций" },
+  { id: "spb", city: "Санкт-Петербург", stock: "8 215 позиций" },
+  { id: "kzn", city: "Казань", stock: "4 030 позиций" },
+  { id: "ekb", city: "Екатеринбург", stock: "5 772 позиции" },
+  { id: "nsk", city: "Новосибирск", stock: "3 118 позиций" },
+  { id: "krd", city: "Краснодар", stock: "2 904 позиции" },
+];
+
+export default function ScrollContainerSnapExample() {
+  return (
+    <ScrollContainer axis="horizontal" snap scrollbar="hidden" aria-label="Склады">
+      <ul className={styles.tiles}>
+        {WAREHOUSES.map((warehouse) => (
+          <li key={warehouse.id} className={styles.tile}>
+            <Card.Root>
+              <Card.Body>
+                <Typography as="h3" variant="title-s">
+                  {warehouse.city}
+                </Typography>
+                <Typography as="p" variant="caption" tone="muted">
+                  {warehouse.stock}
+                </Typography>
+              </Card.Body>
+            </Card.Root>
+          </li>
+        ))}
+      </ul>
+    </ScrollContainer>
+  );
+}

package/src/components/segmented-control/COMPONENT.md

@@ -24,20 +24,22 @@ import { SegmentedControl } from "prime-ui-kit";
 
 ## Anatomy
 ```
-SegmentedControl.Root                 role="radiogroup"; track + sliding thumb, scrolling row, keyboard
-└─ SegmentedControl.Item              role="radio" button, one option
-   ├─ SegmentedControl.Icon           icon slot (optional; icon-only → square segment)
-   ├─ SegmentedControl.Label          title, one line (optional; plain text is wrapped automatically)
-   ├─ SegmentedControl.Count          counter Badge after the label (optional)
-   └─ SegmentedControl.Description    second line; makes the segment two-line (optional)
+SegmentedControl.Root                 field frame: label row · track · support row (hint | error)
+└─ (track)                            role="radiogroup"; sliding thumb, scrolling row, keyboard
+   └─ SegmentedControl.Item           role="radio" button, one option
+      ├─ SegmentedControl.Icon        icon slot (optional; icon-only → square segment)
+      ├─ SegmentedControl.Label       title, one line (optional; plain text is wrapped automatically)
+      ├─ SegmentedControl.Count       counter Badge after the label (optional)
+      └─ SegmentedControl.Description second line; makes the segment two-line (optional)
 ```
+The root is a field root: `className`, `ref` and the native attributes land on the frame, which hugs the track unless `fullWidth`; `id`, `onKeyDown` and the `aria-label*` / `aria-describedby` names land on the radiogroup. Without `label`, `hint` and `error` the frame shows only the track.
 
 ## API
 
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### SegmentedControl.Root
-`ref` → `HTMLDivElement`. `<div role="radiogroup">`: the track with the sliding thumb, keyboard handling and a horizontally scrolling `ScrollContainer` row.
+`ref` → `HTMLDivElement` (the field frame). The field: label · `<div role="radiogroup">` track with the sliding thumb, keyboard handling and a horizontally scrolling `ScrollContainer` row · support row. The frame hugs the track unless `fullWidth`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -47,8 +49,17 @@ SegmentedControl.Root                 role="radiogroup"; track + sliding thumb,
 | `disabled` | `boolean` | `false` | Disables the whole group. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | 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`. |
 | `fullWidth` | `boolean` | `false` | 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. |
+| `label` | `ReactNode` | — | Heading above the control; names the `radiogroup` (`aria-labelledby`). Without it give the root an `aria-label`. |
+| `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the `radiogroup`. |
+| `optional` | `boolean` | `false` | Muted marker after the label (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the control (`aria-describedby`). Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | `false` | Danger inset ring, `aria-invalid` and `data-invalid` on the `radiogroup`; the control shakes once when an error arrives. |
+| `reserveSupportRow` | `boolean` | `false` | Always render the support row, so an appearing error does not shift the layout. |
+| `id` | `string` | — | Id of the `radiogroup` element (generated when omitted); hint id is `<id>-hint`, error id `<id>-error`. |
+| `labels` | `Partial<SegmentedControlLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | `SegmentedControl.Item`s (may be wrapped, e.g. in `Tooltip.Trigger`). |
-| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" \| "onChange">` | — | `aria-label` / `aria-labelledby` (name the group), `className` and the other div attributes. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange" \| "dir">` | — | `aria-label` / `aria-labelledby` / `aria-describedby` and `onKeyDown` go to the radiogroup (a prevented key skips the kit's handling); `className`, `data-*` and the other attributes to the field frame `<div>`. |
 
 ### SegmentedControl.Item
 `ref` → `HTMLButtonElement`. One option, a `<button role="radio">` with roving `tabIndex`; plain text is wrapped in a `SegmentedControl.Label`.
@@ -136,13 +147,16 @@ Colour all items or none; do not give an item and its Count the same hue; prefer
 | unselected | — | `aria-checked="false"`, `data-state="unchecked"`; `text-secondary`, hover → `text-primary` (no fill) |
 | no selection | `value` / `defaultValue` = `""` | thumb hidden; the first enabled segment takes Tab focus |
 | item disabled | item `disabled` | `data-disabled="true"`, native `disabled`, `text-disabled`, skipped by arrows |
-| group disabled | root `disabled` | root `data-disabled="true"`, `aria-disabled`; every segment disabled |
+| group disabled | root `disabled` | track `data-disabled="true"`, `aria-disabled`; every segment disabled; label and hint dimmed |
+| invalid | `invalid` or non-empty `error` | track `data-invalid="true"` + `aria-invalid="true"`, inset danger ring on the track; the error replaces the hint; the track shakes once when an error arrives |
+| required | `required` | red `*` after the label, `aria-required="true"` on the radiogroup |
 | focus-visible | keyboard | focus ring inside the segment |
 | overflow | row wider than the container | root `data-overflow-start` / `data-overflow-end`: edge fades in the track color |
 
 Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `data-value`, `data-color`. The thumb glides (`emphasized` + `base`, `data-animate`) only into a user's choice (click, arrows); a value set from outside and layout changes snap it; it stays still under `prefers-reduced-motion`. It sits inside the segment track, which clips it, so moving the selection never changes the row's scroll area. When the row scrolls, the selected segment is kept in view on mount and on every value change: only the row scrolls, never the page, and the scroll glides only after a user's choice.
 
 ## Layout & spacing
+- In a form it is a field: label → track `label-gap`, track → support row `hint-gap`, field → field `--prime-space-5` like every field.
 - Width is content-based by default; segments never wrap. In a narrow container the row scrolls horizontally with fading edges.
 - In a toolbar: gap `--prime-space-3` between controls; keep every control at one size.
 - Caption under a group: gap `--prime-space-2`.
@@ -159,7 +173,8 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 | `Tab` | Enters the group on the selected option (or the first enabled one) and leaves it. |
 
 ### ARIA
-- Root `role="radiogroup"` — always name it with `aria-label` / `aria-labelledby`; `aria-disabled` when disabled.
+- The track is `role="radiogroup"`, named by `label` (`aria-labelledby`); without a label give the root `aria-label`. `aria-disabled` when disabled.
+- Hint and error are linked through `aria-describedby`; an error sets `aria-invalid="true"`, `required` sets `aria-required="true"`.
 - Items are `<button role="radio" aria-checked>` with roving `tabIndex`.
 - Two-line items: `aria-labelledby` = label (+ count), `aria-describedby` = description.
 - Icons are `aria-hidden`; icon-only items need `aria-label` (and a Tooltip for sighted users).
@@ -167,7 +182,9 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-No `labels`.
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
 
 ## Examples
 | Example | Shows |
@@ -181,15 +198,17 @@ No `labels`.
 | [scroll.tsx](examples/scroll.tsx) | Segments never wrap: in a column narrower than the row it scrolls with edge fades and brings the chosen segment into view. |
 | [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a metric on the second — `SegmentedControl.Label`, `SegmentedControl.Count`, `SegmentedControl.Description`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the choice and updates other content from it — `value`, `onValueChange`. |
+| [in-form.tsx](examples/in-form.tsx) | An expense form: the choice is a labelled field with a hint, checked on submit, its error leaves as soon as a segment is chosen — `label`, `hint`, `required`, `error`. |
 
 ## Mistakes
 - Using it as tabs that show different panels → use `Tabs`.
-- No `aria-label` on the root → the radiogroup has no name.
+- No `label` and no `aria-label` → the radiogroup has no name.
+- A `Label` + `Hint` pair wired by hand with `aria-labelledby` in a form → `label`, `hint`, `error` on the root.
 - Icon-only item without `aria-label` → add `aria-label` and wrap in `Tooltip`.
 - `variant="…"` or `tone="…"` on the root → there is none; use `color` on items for hue.
 - Different `size` than neighbouring controls in a toolbar → use the same tier so heights match.
 - Expecting segments to wrap on narrow screens → they scroll; use `fullWidth` or fewer options.
 
 ## Related
-- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Badge](../badge/COMPONENT.md)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
 - **See also:** [Tabs](../tabs/COMPONENT.md), [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md)

package/src/components/segmented-control/examples/examples.module.css

@@ -7,3 +7,14 @@
   align-items: flex-start;
   gap: var(--prime-space-3);
 }
+
+/* in-form.tsx: field → field and fields → action at the form rhythm; controls keep their width. */
+.form {
+  display: grid;
+  justify-items: start;
+  gap: var(--prime-space-5);
+}
+
+.form > :last-child {
+  margin-block-start: var(--prime-space-3);
+}

package/src/components/segmented-control/examples/in-form.tsx

@@ -0,0 +1,42 @@
+/** An expense form: the choice is a labelled field with a hint, checked on submit, its error leaves as soon as a segment is chosen — `label`, `hint`, `required`, `error`. */
+import { Button, Input, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SegmentedControlInFormExample() {
+  const [owner, setOwner] = React.useState("");
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError(owner ? undefined : "Выберите, чей это расход");
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Input.Root label="Сумма, ₽" required>
+        <Input.Wrapper>
+          <Input.Field name="amount" inputMode="decimal" defaultValue="12 400" />
+          <Input.InlineAffix side="end">₽</Input.InlineAffix>
+        </Input.Wrapper>
+      </Input.Root>
+      <SegmentedControl.Root
+        label="Чей расход"
+        hint="Личные расходы не попадают в отчёт компании"
+        required
+        error={error}
+        value={owner}
+        onValueChange={(next) => {
+          setOwner(next);
+          setError(undefined);
+        }}
+      >
+        <SegmentedControl.Item value="company">Компании</SegmentedControl.Item>
+        <SegmentedControl.Item value="project">Проекта</SegmentedControl.Item>
+        <SegmentedControl.Item value="personal">Личный</SegmentedControl.Item>
+      </SegmentedControl.Root>
+      <Button.Root type="submit">Сохранить расход</Button.Root>
+    </form>
+  );
+}

package/src/components/select/COMPONENT.md

@@ -8,8 +8,9 @@
 ## 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 value out of thousands of records searched on the server (`search`, `onSearchChange`, `filter={false}`, `hasMore` + `onLoadMore`).
 - 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).
+- Options that need a picture, an avatar, a second line, a badge 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).
@@ -31,16 +32,18 @@ Select.Root                       field frame: label · control · hint/error; v
 ├── 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
+└── Select.Content                portaled panel while open; closed, the items render hidden in place so the trigger knows their labels
     ├── 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.Item       role="option": [checkbox] [icon / Avatar / Thumbnail] [text] [meta / Badge] [check]
+    │   │       ├── Select.ItemIcon · Avatar.Root · Thumbnail.Root
     │   │       ├── Select.ItemText · Select.ItemDescription
-    │   │       └── Select.ItemMeta
-    │   └── Select.Separator      full-bleed Divider
-    └── empty state               compact EmptyPage
+    │   │       └── Select.ItemMeta · Badge.Root
+    │   ├── Select.Separator      full-bleed Divider
+    │   └── skeleton rows         `loading` with no items, `loadingMore` at the end
+    ├── empty state               compact EmptyPage
+    └── load error                compact EmptyPage, role="alert", retry Button (`loadError`, `onRetry`)
 ```
 
 ## API
@@ -66,8 +69,18 @@ Select.Root                       field frame: label · control · hint/error; v
 | `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. |
+| `search` | `string` | — | Controlled search query (`Select.Content searchable`); together with `onSearchChange`. Cleared when the list closes. |
+| `defaultSearch` | `string` | `""` | Initial query, uncontrolled. |
+| `onSearchChange` | `(search: string) => void` | — | Called with the new query: typing, and `""` when the list closes. Load the matching options here for a server search. |
+| `filter` | `boolean` | `true` | 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. |
+| `loading` | `boolean` | `false` | 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. |
+| `loadingMore` | `boolean` | `false` | More options are loading at the end: skeleton rows after the items. |
+| `hasMore` | `boolean` | `false` | More options exist: reaching the end of the list calls `onLoadMore`. |
+| `onLoadMore` | `() => void \| Promise<void>` | — | 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. |
+| `loadError` | `ReactNode` | — | The options failed to load: the message replaces the list in `role="alert"`. Not the field `error` (validation). |
+| `onRetry` | `() => void` | — | A retry button (`labels.retry`) under `loadError`; Enter in the open list runs it too. |
 | `clearable` | `boolean` | `false` | A clear segment before the chevron while a value is set; `Delete` / `Backspace` on the trigger clear too. |
+| `name` | `string` | — | Form field name: hidden inputs submit the value (`""` while empty; one input per value with `multiple`). |
 | `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. |
@@ -77,7 +90,7 @@ Select.Root                       field frame: label · control · hint/error; v
 | `…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.
+`ref` → `HTMLButtonElement`. `<button role="combobox">` with the value, the clear segment and the chevron (a Spinner while `loading`). + native button props (`onFocus`, `onBlur`, `onKeyDown`… reach the button).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -88,18 +101,18 @@ Select.Root                       field frame: label · control · hint/error; v
 
 | 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. |
+| `renderValue` | `(item: { value: string; label: string }) => ReactNode` | — | Single mode: draws the picked option in the trigger with the same parts as the row (Avatar, ItemText, Badge…); not called while empty. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the 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. Below 640px of viewport the panel is a bottom sheet: a scrim, a grab handle, swipe down to close, page scroll locked.
+`ref` → `HTMLDivElement` (the panel). Portal + the floating list panel with the search row, the `role="listbox"`, the empty and load states. Closed, the items render hidden so the trigger knows their labels. Below 640px it is a bottom sheet.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `searchable` | `boolean` | `false` | A search field on top; items filter by label, description and `keywords`. |
+| `searchable` | `boolean` | `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). |
 | `children` | `ReactNode` | — (required) | Items, groups, separators. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "hidden" \| "onKeyDown" \| "onAnimationEnd">` | — | `className` and the other attributes of the panel. |
 
@@ -112,10 +125,10 @@ Select.Root                       field frame: label · control · hint/error; v
 | `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. |
+| `children` | `ReactNode` | — (required) | Text, or `Select.ItemIcon`, `Avatar.Root`, `Thumbnail.Root`, `Select.ItemText`, `Select.ItemDescription`, `Select.ItemMeta`, `Badge.Root` as direct children. |
 
 ### 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.
+`ref` → `HTMLSpanElement`. Rich option parts: the title (its text is the label) / a muted second line / a trailing muted value. Leading media is an `Avatar.Root` or `Thumbnail.Root` child, a trailing status a `Badge.Root`.
 
 ### Select.Group
 `ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while the search leaves none of its options. + native `<div>` props.
@@ -148,11 +161,13 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 |---|---|---|---|
 | `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` |
+| `loading` | spinner instead of the chevron; skeleton rows in the option geometry while no item is on screen | Options load asynchronously | `false` |
+| `loadingMore` | skeleton rows after the items | The next page is loading (`hasMore` + `onLoadMore`) | `false` |
+| `filter={false}` | every item shows whatever the query; the query is still marked in the labels | The owner searches on the server (`search`, `onSearchChange`) | `true` |
 | `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 | |
+| rich options | `Thumbnail.Root` or `Select.ItemDescription` in an item: a two-line row; `Avatar.Root` before the text and `Badge.Root` after it keep one line; 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.
+**Combinations** — `renderValue` is single-mode only; with `multiple` the trigger shows the joined labels. `error` implies `invalid`; `loadError` is a different thing — the options failed to load — and never marks the field invalid. `Select.ItemDescription` is searchable. A status Badge can follow `Select.Value` inside the trigger; it takes the tier one step down by itself. An `Avatar.Root` or `Thumbnail.Root` in a row or `renderValue` takes the tier media size (`xs` · `xs` · `s` · `s` · `m` for `xs`–`xl`) unless it sets `size`. A server search: `searchable` + `search` / `onSearchChange` + `filter={false}` + `loading`; paging adds `hasMore`, `loadingMore`, `onLoadMore`; keep the selected option among the items (or draw it with `renderValue`) so the trigger knows its label.
 
 ## States
 | State | Driven by | DOM |
@@ -161,8 +176,12 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | 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; the control shakes once when an error arrives (`data-shake` on the frame) |
 | 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) |
+| loading | `loading` | `data-loading="true"`, `aria-busy` on the trigger and the list; with no item on screen, `aria-hidden` skeleton rows (`data-skeleton`) in the list; `labels.loading` in a polite live region |
+| loading more | `loadingMore` | skeleton rows after the items; the end of the list is watched while `hasMore` (`onLoadMore` once per batch) |
+| load error | `loadError` | the list is `hidden`; a compact EmptyPage with `role="alert"` and a retry Button (`onRetry`) |
+| state swap | loading ↔ items ↔ load error | the new content fades in (`swapMotion`), the first render stays still |
+| 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); the query clears when the list closes (`onSearchChange("")`) |
+| nothing to show | no option matches (and not loading) | a compact EmptyPage with `role="status"`: `labels.empty`, plus `labels.emptyHint` while a query is typed |
 | sheet | viewport below 640px | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the panel; the sheet carries `data-state`, the panel keeps its role and ref; page scroll locked; a swipe down from the handle closes it |
 | option highlighted / selected / disabled | keyboard and pointer / value / `disabled` | `data-highlighted`, `data-selected` + `aria-selected`, `data-disabled` + `aria-disabled`; highlight is a fill only |
 
@@ -171,6 +190,43 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 - 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.
+- A rich row and its trigger use the same parts in the same order: leading media (`Avatar.Root`,
+  `Thumbnail.Root`) → `Select.ItemText` (+ `Select.ItemDescription`) → trailing `Badge.Root` /
+  `Select.ItemMeta`. In a row the trailing part sits before the check; in the trigger, at the end
+  before the chevron. Draw the trigger with `renderValue` returning the row's parts, so the picked
+  person keeps their avatar and role badge when the list is closed:
+
+```tsx
+<Select.Root label="Ответственный" defaultValue="lebedeva">
+  <Select.Trigger>
+    <Select.Value
+      renderValue={({ value, label }) => {
+        const member = BY_VALUE.get(value);
+        return (
+          <>
+            <Avatar.Root color={member?.color}>
+              <Avatar.Fallback>{member?.initials}</Avatar.Fallback>
+            </Avatar.Root>
+            <Select.ItemText>{label}</Select.ItemText>
+            {member?.role ? <Badge.Root color={member.color}>{member.role}</Badge.Root> : null}
+          </>
+        );
+      }}
+    />
+  </Select.Trigger>
+  <Select.Content>
+    {TEAM.map((member) => (
+      <Select.Item key={member.value} value={member.value}>
+        <Avatar.Root color={member.color}>
+          <Avatar.Fallback>{member.initials}</Avatar.Fallback>
+        </Avatar.Root>
+        <Select.ItemText>{member.name}</Select.ItemText>
+        {member.role ? <Badge.Root color={member.color}>{member.role}</Badge.Root> : null}
+      </Select.Item>
+    ))}
+  </Select.Content>
+</Select.Root>
+```
 
 ## Accessibility
 
@@ -182,6 +238,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | `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. |
+| `Enter` | With a load error in the open list, retries (`onRetry`). |
 | `Escape` | Closes the list; focus returns to the trigger. |
 | `Tab` | Returns focus to the trigger, closes the list and moves on from the trigger. |
 
@@ -189,6 +246,9 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 - 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`.
+- While loading the list is `aria-busy` and `labels.loading` is announced politely; skeleton rows are hidden from screen readers; a load error is `role="alert"`.
+- The highlight reaching the last option asks for the next batch the same way scrolling does.
+- With `name`, hidden inputs carry the value into a native form submit; native trigger events (`onFocus`, `onBlur`, `onKeyDown`) reach the button.
 - An outside press closes the list without moving focus back: focus follows the pointer (foundation §8).
 
 ### Labels
@@ -199,7 +259,8 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | `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`. |
+| `loading` | `"Загрузка…"` | Announced while `loading` or `loadingMore`. |
+| `retry` | `"Повторить"` | The retry button under `loadError` (`onRetry`). |
 | `clear` | `"Очистить"` | Tooltip of the clear segment. |
 | `optional` | `"необязательно"` | Muted marker after the label when `optional`. |
 
@@ -213,8 +274,11 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | [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`. |
+| [server-search.tsx](examples/server-search.tsx) | A client out of thousands: the parent searches on the server as the query changes and loads the next page at the end of the list — `search`, `onSearchChange`, `filter`, `loading`, `hasMore`, `loadingMore`, `onLoadMore`. |
+| [load-error.tsx](examples/load-error.tsx) | The options failed to load: the list says so in place and a retry loads them again — `loadError`, `onRetry`, `loading`. |
 | [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`. |
+| [people.tsx](examples/people.tsx) | People in the rows and the trigger: an avatar sized to the tier before the name, a role badge after it — `Avatar.Root`, `Badge.Root`, `renderValue`. |
 | [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 shakes the field and leaves once a country is picked, a calm note confirms the save — `required`, `error`, `hint`. |
@@ -226,7 +290,11 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 - 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`.
+- Results from a server passed as items with the kit filter still on → set `filter={false}`, or the kit hides results that do not contain the query literally.
+- A spinner or «Загрузка…» item drawn by hand while options load → set `loading` (skeleton rows) and `loadingMore`.
+- A failed load shown through the field `error` → use `loadError` + `onRetry`; `error` is for validation.
+- An Avatar wrapped in `Select.ItemIcon` → put `Avatar.Root` as a direct child of the item; it takes the tier size.
 
 ## Related
-- **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)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (list), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in `multiple`), [Spinner](../spinner/COMPONENT.md) (`loading` in the trigger), [Skeleton](../skeleton/COMPONENT.md) (loading rows), [EmptyPage](../empty-page/COMPONENT.md) (empty state, load error), [Button](../button/COMPONENT.md) (retry), [Divider](../divider/COMPONENT.md) (`Separator`), [Thumbnail](../thumbnail/COMPONENT.md) and [Avatar](../avatar/COMPONENT.md) (row media), [Badge](../badge/COMPONENT.md) (row badge), [VisuallyHidden](../visually-hidden/COMPONENT.md) (loading announcement), `Icon` (chevron, clear, check, search, retry), [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/load-error.tsx

@@ -0,0 +1,45 @@
+/** The options failed to load: the list says so in place and a retry loads them again — `loadError`, `onRetry`, `loading`. */
+import { Select } from "prime-ui-kit";
+import * as React from "react";
+
+type LoadState = "error" | "loading" | "ready";
+
+const WAREHOUSES = [
+  { value: "msk-1", label: "Москва, Южный порт" },
+  { value: "spb-1", label: "Санкт-Петербург, Шушары" },
+  { value: "ekb-1", label: "Екатеринбург, Кольцово" },
+  { value: "kzn-1", label: "Казань, Зеленодольск" },
+];
+const LATENCY_MS = 800;
+
+export default function SelectLoadErrorExample() {
+  const [state, setState] = React.useState<LoadState>("error");
+
+  const retry = () => {
+    setState("loading");
+    window.setTimeout(() => setState("ready"), LATENCY_MS);
+  };
+
+  return (
+    <Select.Root
+      label="Склад отгрузки"
+      placeholder="Выберите склад"
+      loading={state === "loading"}
+      loadError={state === "error" ? "Не удалось загрузить склады" : undefined}
+      onRetry={retry}
+    >
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        {state === "ready"
+          ? WAREHOUSES.map((warehouse) => (
+              <Select.Item key={warehouse.value} value={warehouse.value}>
+                {warehouse.label}
+              </Select.Item>
+            ))
+          : null}
+      </Select.Content>
+    </Select.Root>
+  );
+}