prime-ui-kit 0.15.0 → 0.17.0

package/dist/skill/reference/components/scroll-container/examples/lock.tsx

@@ -32,15 +32,15 @@ export default function ScrollContainerLockExample() {
         </Button.Root>
       </Card.Header>
       <ScrollContainer lock={reviewing}>
-        <ul className={styles.list}>
+        <Card.List>
           {ORDERS.map((order) => (
-            <li key={order}>
+            <Card.ListItem key={order}>
               <Typography as="span" variant="body-m">
                 {order}
               </Typography>
-            </li>
+            </Card.ListItem>
           ))}
-        </ul>
+        </Card.List>
       </ScrollContainer>
     </Card.Root>
   );

package/dist/skill/reference/components/scroll-container/examples/log.tsx

@@ -0,0 +1,97 @@
+/** A live exchange log pinned to its last entry: a new entry keeps it at the end, scrolling up loads older ones without moving what is on screen — `anchor`, `onReachStart`. */
+import { Button, Card, ScrollContainer, Skeleton, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Entry = { id: number; time: string; text: string };
+
+const HISTORY: Entry[] = [
+  "Выгрузка заказов в 1С начата",
+  "Заказ № 1042 выгружен",
+  "Заказ № 1043 выгружен",
+  "Заказ № 1044: нет склада отгрузки, пропущен",
+  "Остатки склада «Москва» обновлены",
+  "Цены прайса «Опт» обновлены",
+  "Счёт № 4830 выгружен",
+  "Счёт № 4831 выгружен",
+  "Платёж по счёту № 4821 получен",
+  "Контрагент ООО «Гранит» сопоставлен",
+  "Акт № 312 выгружен",
+  "Выгрузка завершена: 9 из 10",
+].map((text, index) => ({
+  id: index + 1,
+  time: `09:${String(index * 4).padStart(2, "0")}`,
+  text,
+}));
+
+const ARRIVING = [
+  "Новый заказ № 1045 принят",
+  "Остатки склада «Казань» обновлены",
+  "Счёт № 4832 выгружен",
+];
+
+const PAGE = 4;
+
+export default function ScrollContainerLogExample() {
+  // The newest entries first; older pages arrive when the reader scrolls up.
+  const [shown, setShown] = React.useState(PAGE);
+  const [loading, setLoading] = React.useState(false);
+  const [arrived, setArrived] = React.useState<Entry[]>([]);
+  const entries = [...HISTORY.slice(-shown), ...arrived];
+
+  const loadOlder = () => {
+    if (shown >= HISTORY.length) return;
+    setLoading(true);
+    // The promise keeps the region `aria-busy` and stops repeat calls until it settles.
+    return new Promise<void>((resolve) => {
+      window.setTimeout(() => {
+        setShown((count) => Math.min(count + PAGE, HISTORY.length));
+        setLoading(false);
+        resolve();
+      }, 800);
+    });
+  };
+
+  const receive = () => {
+    setArrived((list) => [
+      ...list,
+      {
+        id: HISTORY.length + list.length + 1,
+        time: `10:${String(list.length * 3).padStart(2, "0")}`,
+        text: ARRIVING[list.length % ARRIVING.length],
+      },
+    ]);
+  };
+
+  return (
+    <Card.Root className={styles.log}>
+      <Card.Header>
+        <Card.Title>Обмен с 1С</Card.Title>
+        <Button.Root variant="soft" tone="neutral" onClick={receive}>
+          Новое событие
+        </Button.Root>
+      </Card.Header>
+      <ScrollContainer
+        anchor="end"
+        onReachStart={loadOlder}
+        tabIndex={0}
+        role="log"
+        aria-label="Журнал обмена"
+        className={styles.entries}
+      >
+        {loading ? <Skeleton lines={2} className={styles.older} /> : null}
+        <Card.List>
+          {entries.map((entry) => (
+            <Card.ListItem key={entry.id}>
+              <Typography as="span" variant="caption" tone="muted">
+                {entry.time}
+              </Typography>
+              <Typography variant="body-m">{entry.text}</Typography>
+            </Card.ListItem>
+          ))}
+        </Card.List>
+      </ScrollContainer>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/scroll-container/examples/overscroll.tsx

@@ -12,15 +12,15 @@ export default function ScrollContainerOverscrollExample() {
         <Card.Title>Журнал выгрузок</Card.Title>
       </Card.Header>
       <ScrollContainer overscrollBehavior="auto" tabIndex={0} aria-label="Журнал выгрузок">
-        <ul className={styles.list}>
+        <Card.List>
           {HOURS.map((hour) => (
-            <li key={hour}>
+            <Card.ListItem key={hour}>
               <Typography as="span" variant="body-m" tone="secondary">
                 {hour} — отчёт выгружен
               </Typography>
-            </li>
+            </Card.ListItem>
           ))}
-        </ul>
+        </Card.List>
       </ScrollContainer>
     </Card.Root>
   );

package/dist/skill/reference/components/scroll-container/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** A feed that scrolls on its own inside a fixed-height card, with the kit's thin scrollbar. */
+/** A feed that scrolls on its own inside a fixed-height card, with the kit's thin scrollbar — `ScrollContainer`. */
 import { Card, ScrollContainer, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -12,15 +12,15 @@ export default function ScrollContainerOverviewExample() {
         <Card.Title>Лента событий</Card.Title>
       </Card.Header>
       <ScrollContainer>
-        <ul className={styles.list}>
+        <Card.List>
           {EVENTS.map((event) => (
-            <li key={event}>
+            <Card.ListItem key={event}>
               <Typography as="span" variant="body-m" tone="secondary">
                 {event}
               </Typography>
-            </li>
+            </Card.ListItem>
           ))}
-        </ul>
+        </Card.List>
       </ScrollContainer>
     </Card.Root>
   );

package/dist/skill/reference/components/scroll-container/examples/scrollbar.tsx

@@ -27,15 +27,15 @@ export default function ScrollContainerScrollbarExample() {
           </Typography>
         </Card.Header>
         <ScrollContainer>
-          <ul className={styles.list}>
+          <Card.List>
             {CLIENTS.map((client) => (
-              <li key={client}>
+              <Card.ListItem key={client}>
                 <Typography as="span" variant="body-m">
                   {client}
                 </Typography>
-              </li>
+              </Card.ListItem>
             ))}
-          </ul>
+          </Card.List>
         </ScrollContainer>
       </Card.Root>
       <Card.Root role="region" className={styles.card} aria-label="Статусы заказов">

package/dist/skill/reference/components/scroll-container/examples/snap.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** A strip of warehouse cards that always 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";
@@ -14,7 +14,7 @@ const WAREHOUSES = [
 
 export default function ScrollContainerSnapExample() {
   return (
-    <ScrollContainer axis="horizontal" snap scrollbar="hidden" aria-label="Склады">
+    <ScrollContainer axis="horizontal" snap="mandatory" scrollbar="hidden" aria-label="Склады">
       <ul className={styles.tiles}>
         {WAREHOUSES.map((warehouse) => (
           <li key={warehouse.id} className={styles.tile}>

package/dist/skill/reference/components/scroll-container/examples/variants.tsx

@@ -46,6 +46,7 @@ export default function ScrollContainerVariantsExample() {
                   as="div"
                   variant="caption"
                   tone="secondary"
+                  numeric="tabular"
                   className={styles.cell}
                 >
                   {room} · {hour}

package/dist/skill/reference/components/segmented-control/COMPONENT.md

@@ -25,10 +25,10 @@ import { SegmentedControl } from "prime-ui-kit";
 ## Anatomy
 ```
 SegmentedControl.Root                 field frame: label row · track · support row (hint | error)
-└─ (track)                            role="radiogroup"; sliding thumb, scrolling row, keyboard
+└─ (track)                            role="radiogroup"; sliding thumb, switcher 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.Label       title, one line (optional; plain text becomes the label)
       ├─ SegmentedControl.Count       counter Badge after the label (optional)
       └─ SegmentedControl.Description second line; makes the segment two-line (optional)
 ```
@@ -39,7 +39,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### SegmentedControl.Root
-`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`.
+`ref` → `HTMLDivElement` (the field frame). The field: label · `<div role="radiogroup">` track with the sliding thumb and the switcher row (titles go before it scrolls, when every segment has an icon) · support row. The frame hugs the track unless `fullWidth`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -47,7 +47,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | `defaultValue` | `string` | `""` | Initial value (uncontrolled); `""` — nothing selected. |
 | `onValueChange` | `(value: string) => void` | — | Called with the new value on click or arrow keys. |
 | `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`. |
+| `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`. |
@@ -70,6 +70,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | `disabled` | `boolean` | `false` | Disables this option; arrow keys skip it. |
 | `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | — | Palette hue: a dot before the content; while selected the thumb takes a soft fill of the hue with a ring of it. |
 | `children` | `ReactNode` | — (required) | Text, `Icon`, `Label`, `Count`, `Description`. Only an icon → square segment; give it `aria-label`. |
+| `className` | `string` | — | Class on the segment button. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" \| "type" \| "role">` | — | `aria-label`, `onClick` (runs first and can `preventDefault()` the selection), `className` and the other button attributes. |
 
 ### SegmentedControl.Icon
@@ -78,6 +79,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="theme.light" />`. |
+| `className` | `string` | — | Class on the icon box. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### SegmentedControl.Label
@@ -86,6 +88,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — (required) | Title text. |
+| `className` | `string` | — | Class on the label. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### SegmentedControl.Count
@@ -103,6 +106,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — (required) | Second-line text; wrap a key value in `<strong>`. |
+| `className` | `string` | — | Class on the description. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ## Variants
@@ -128,7 +132,7 @@ Track is `fill-muted` with a faint 1px ring; the selected segment is a floating
 ### color (Count)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `gray` | neutral soft badge (text wash so it reads on track and thumb) | plain counters | yes |
+| `gray` | neutral soft badge (a wash of the text ink, so it reads on track and thumb) | plain counters | yes |
 | other palette hues | soft badge of the hue | the count has a status meaning | |
 
 ### Flags
@@ -150,14 +154,18 @@ Colour all items or none; do not give an item and its Count the same hue; prefer
 | 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 |
+| optional | `optional` | a muted `labels.optional` marker after the label |
+| support row reserved | `reserveSupportRow` | the support row stays rendered while empty, so an error arriving shifts nothing |
 | 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 |
+| collapsed | row wider than the container and every segment has an icon | row `data-collapse="icon"`: titles, counts and descriptions leave the row, segments turn square; a `VisuallyHidden` copy of the title names each segment and a `Tooltip` shows it |
+| overflow | row still 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.
+Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `data-value`, `data-color`. The thumb (the shared selection indicator) 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.
+- Width is content-based by default; the row is a switcher (foundation §9): segments never wrap or truncate. In a narrow container segments with icons drop their titles first, then the row scrolls horizontally with fading edges.
+- Without `size` the control takes the tier of its host (a toolbar, a form), else `m`.
 - On a coarse pointer each segment's hit area grows to the 44 px touch target in height; the track keeps its tier height.
 - In a toolbar: gap `--prime-space-3` between controls; keep every control at one size.
 - Caption under a group: gap `--prime-space-2`.
@@ -166,6 +174,8 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `ArrowRight` · `ArrowDown` | Next option, wrapping and skipping disabled ones; focus and selection move together. |
@@ -174,11 +184,13 @@ 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
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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).
+- Two-line items: `aria-labelledby` = label (+ count), `aria-describedby` = description; plain text is the label, so every reference resolves.
+- Icons are `aria-hidden`; icon-only items need `aria-label` (and a Tooltip for sighted users). In a row collapsed to icons a `VisuallyHidden` copy of the title names the segment and a `Tooltip` shows it.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -196,7 +208,7 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 | [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and square icon-only segments named for screen readers — `SegmentedControl.Icon`, `aria-label`. |
 | [colors.tsx](examples/colors.tsx) | A status per option: a dot of its hue before the label and a tinted thumb when chosen — `color`. |
 | [full-width.tsx](examples/full-width.tsx) | The group fills its column; segments tend to equal widths and a long label keeps its own — `fullWidth`. |
-| [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. |
+| [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 — `defaultValue`. |
 | [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; an optional choice beside it — `label`, `hint`, `required`, `error`, `optional`. |
@@ -211,5 +223,5 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 - 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), [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (`internal/SwitcherScroller`, the row), [Badge](../badge/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md) (the title of a collapsed segment), [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md); `internal/selectionIndicator` (the thumb)
 - **See also:** [Tabs](../tabs/COMPONENT.md), [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md)

package/dist/skill/reference/components/segmented-control/examples/controlled.tsx

@@ -2,8 +2,6 @@
 import { SegmentedControl, Typography } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
 const REVENUE: Record<string, string> = {
   day: "Выручка за день: 48 200 ₽",
   week: "Выручка за неделю: 312 700 ₽",
@@ -14,7 +12,7 @@ export default function SegmentedControlControlledExample() {
   const [period, setPeriod] = React.useState("week");
 
   return (
-    <div className={styles.stack}>
+    <>
       <SegmentedControl.Root value={period} onValueChange={setPeriod} aria-label="Период отчёта">
         <SegmentedControl.Item value="day">День</SegmentedControl.Item>
         <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
@@ -23,6 +21,6 @@ export default function SegmentedControlControlledExample() {
       <Typography variant="body-m" tone="secondary">
         {REVENUE[period]}
       </Typography>
-    </div>
+    </>
   );
 }

package/dist/skill/reference/components/segmented-control/examples/examples.module.css

@@ -1,13 +1,5 @@
 /* Layout of the SegmentedControl scenarios: semantic tokens only. */
 
-/* controlled.tsx: the group and the content it drives, start-aligned in one column. */
-.stack {
-  display: flex;
-  flex-direction: column;
-  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;

package/dist/skill/reference/components/segmented-control/examples/scroll.tsx

@@ -1,4 +1,4 @@
-/** Segments never wrap: in a column narrower than the row it scrolls with edge fades and brings the chosen segment into view. */
+/** Segments never wrap: in a column narrower than the row it scrolls with edge fades and brings the chosen segment into view — `defaultValue`. */
 import { SegmentedControl } from "prime-ui-kit";
 
 export default function SegmentedControlScrollExample() {

package/dist/skill/reference/components/select/COMPONENT.md

@@ -71,6 +71,8 @@ an icon) goes inside `Select.ItemMeta`.
 | `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. |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the list and returns focus to the trigger. |
+| `closeOnOutsideClick` | `boolean` | `true` | A press outside the list and its trigger closes it; focus follows the pointer. |
 | `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`. |
@@ -91,19 +93,21 @@ an icon) goes inside `Select.ItemMeta`.
 | `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. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | 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`. |
 | `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. |
+| `className` | `string` | — | Class on the field frame `<div>`. |
 | `…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 (`onFocus`, `onBlur`, `onKeyDown`… reach the button).
+`ref` → `HTMLButtonElement`. `<button role="combobox">` with the value, the clear segment and the chevron (a Spinner while `loading` or saving).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — | `Select.TriggerIcon`, `Select.Value`, optionally a Badge after it. A `Select.TriggerIcon` alone makes an icon-only trigger (the value read, not shown). |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "id" \| "type" \| "role">` | — | `onFocus`, `onBlur`, `onKeyDown`, `className` and the other button attributes reach the button. |
 
 ### Select.Value
 `ref` → `HTMLSpanElement`. The picked label (labels joined with `multiple`) with an ellipsis, or the placeholder.
@@ -114,10 +118,14 @@ an icon) goes inside `Select.ItemMeta`.
 | `…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.
+`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` with a leading glyph at the tier icon size: before the value / before the option label.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the `Icon`), `className` and the other span attributes. |
 
 ### Select.Content
-`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.
+`ref` → `HTMLDivElement` (the panel). Portal + the list panel: search row, `role="listbox"`, empty and load states; closed, the items render hidden so the trigger knows their labels. Below 640px a bottom sheet: scrim, handle, swipe down to close, page scroll locked.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -135,16 +143,23 @@ an icon) goes inside `Select.ItemMeta`.
 | `keywords` | `string` | — | Extra words for the search. |
 | `disabled` | `boolean` | `false` | Muted, skipped by the keyboard, not selectable. |
 | `children` | `ReactNode` | — (required) | Text, or `Select.ItemIcon`, `Avatar.Root`, `Thumbnail.Root`, `Select.ItemText`, `Select.ItemDescription`, `Select.ItemMeta`, `Badge.Root` as direct children. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role" \| "id" \| "children">` | — | `className`, `data-*`, `onClick` and the other attributes of the option row. |
 
 ### Select.ItemText · Select.ItemDescription · Select.ItemMeta
 `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`.
 
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The text. |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
+
 ### Select.Group
-`ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while the search leaves none of its options. + native `<div>` props.
+`ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while the search leaves none of its options.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `children` (the items), `className` and the other div attributes. |
 
 ### Select.Separator
 `ref` → `HTMLDivElement`. A full-bleed Divider between groups; hidden while searching.
@@ -154,7 +169,7 @@ an icon) goes inside `Select.ItemMeta`.
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the divider. |
 
 ### Select.Action
-`ref` → `HTMLDivElement`. A list-level action («Новый клиент»), a direct child of `Select.Content`: a `role="option"` row pinned under the list, never filtered, the last stop of the arrows; highlighted while the search finds nothing.
+`ref` → `HTMLDivElement`. A list-level action («Новый клиент»), a direct child of `Select.Content`: a `role="option"` row under the list (and the empty state), never filtered, the last stop of the arrows; when the search finds nothing it is highlighted and Enter runs it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -182,7 +197,11 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | `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; 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` |
+| `filter` | items filter by the query; off, every item shows whatever the query and the query is still marked in the labels | Off when the owner searches on the server (`search`, `onSearchChange`) | `true` |
+| `required` / `optional` | red `*` / muted «необязательно» after the label | Mark the minority of the form | `false` / — |
+| `focusRing` | `false`: no focus ring; the trigger keeps its focus fill | Only where focus shows otherwise; never on a form field (WCAG 2.4.7) | `true` |
+| `closeOnOutsideClick` | `false`: the list stays open on a press beside it; Escape, the trigger, a single pick and Tab still close it | A filter list the person compares with the page | `true` |
+| `closeOnEscape` | `false`: Escape leaves the list open | The list must close only by a pick or the trigger | `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; `Avatar.Root` before the text and `Badge.Root` after it keep one line; the trigger the same with `renderValue` | Products, people, delivery tariffs | |
 | `Select.Action` | a row under the list behind a faint full-bleed hairline, with an optional leading icon; stays whatever the query | One list-level action: «Новый клиент», «Пригласить в команду» | |
@@ -194,7 +213,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | 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° |
+| open | `open` / `defaultOpen` / 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` 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 |
@@ -209,7 +228,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 
 ## 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`.
+- Label → field: tier `label-gap`; field → hint: tier `hint-gap`; field → field in a form: the gap of a label-less `Fieldset`.
 - 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.
 - The clear segment's hit area grows to the 44 px touch target in height on a coarse pointer, like the clear segment of an Input.
@@ -254,6 +273,8 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Enter` · `Space` · `ArrowDown` · `ArrowUp` | On the trigger open the list; focus moves into the search or the list. |
@@ -266,6 +287,8 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | `Tab` | Returns focus to the trigger, closes the list and moves on from the trigger. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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`.
@@ -308,6 +331,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | [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`. |
 | [icon-only.tsx](examples/icon-only.tsx) | An icon picker as wide as its glyph: the trigger holds only the picked icon and the chevron, the value is still read aloud — `Select.TriggerIcon`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A filter list that stays open while the person looks beside it: only Escape, the trigger or Tab close it — `closeOnOutsideClick`, `closeOnEscape`. |
 | [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`. |

package/dist/skill/reference/components/select/examples/dismiss.tsx

@@ -0,0 +1,26 @@
+/** A filter list that stays open while the person looks beside it: only Escape, the trigger or Tab close it — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Select } from "prime-ui-kit";
+
+export default function SelectDismissExample() {
+  return (
+    <Select.Root
+      label="Статусы заказов"
+      multiple
+      defaultValue={["new", "paid"]}
+      placeholder="Все статусы"
+      closeOnOutsideClick={false}
+      closeOnEscape
+    >
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        <Select.Item value="new">Новый</Select.Item>
+        <Select.Item value="paid">Оплачен</Select.Item>
+        <Select.Item value="shipped">Отгружен</Select.Item>
+        <Select.Item value="delivered">Доставлен</Select.Item>
+        <Select.Item value="cancelled">Отменён</Select.Item>
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/dist/skill/reference/components/select/examples/examples.module.css

@@ -5,7 +5,7 @@
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-8);
-  width: min(100%, var(--prime-modal-width-m));
+  width: min(100%, var(--prime-layout-form-width-m));
 }
 
 .formHeader {

package/dist/skill/reference/components/select/examples/server-search.tsx

@@ -43,9 +43,13 @@ export default function SelectServerSearchExample() {
   const [total, setTotal] = React.useState(0);
   const [loading, setLoading] = React.useState(true);
   const [loadingMore, setLoadingMore] = React.useState(false);
+  const pageTimer = React.useRef(0);
 
-  // A new query asks the server after a pause; the results on screen stay until the answer.
+  // A new query asks the server after a pause; the results on screen stay until the answer. A
+  // next page still on its way belongs to the old query: it is dropped.
   React.useEffect(() => {
+    window.clearTimeout(pageTimer.current);
+    setLoadingMore(false);
     setLoading(true);
     const timer = window.setTimeout(() => {
       const found = findClients(search);
@@ -58,7 +62,7 @@ export default function SelectServerSearchExample() {
 
   const loadMore = () => {
     setLoadingMore(true);
-    window.setTimeout(() => {
+    pageTimer.current = window.setTimeout(() => {
       setClients((shown) => findClients(search).slice(0, shown.length + PAGE_SIZE));
       setLoadingMore(false);
     }, LATENCY_MS);

package/dist/skill/reference/components/select/examples/sizes.tsx

@@ -5,7 +5,7 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function SelectSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
         <Select.Root key={size} size={size} label={size} defaultValue="week">
           <Select.Trigger>
@@ -18,6 +18,6 @@ export default function SelectSizesExample() {
           </Select.Content>
         </Select.Root>
       ))}
-    </>
+    </div>
   );
 }