prime-ui-kit 0.11.1 → 0.13.0

package/src/components/message/examples/bot-actions.tsx

@@ -0,0 +1,51 @@
+/** A bot's message with an inline keyboard: rows of buttons under the bubble at its width, sharing each row equally, one of them a link — `Message.Actions`, `asChild`. */
+import { Button, Message } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const INVOICE_URL = "https://vector.example/invoices/4821";
+
+export default function MessageBotActionsExample() {
+  const [answer, setAnswer] = React.useState<string | null>(null);
+
+  return (
+    <div className={styles.thread}>
+      <Message.Root value="bot-order" time="15:02">
+        <Message.Author>Бот склада</Message.Author>
+        <Message.Text>
+          Заказ № 4821 собран: 12 позиций на 184 300 ₽. Подтвердите отгрузку до 16:00.
+        </Message.Text>
+        <Message.Actions>
+          <Button.Root variant="soft" tone="neutral" onClick={() => setAnswer("Подтвердить заказ")}>
+            Подтвердить заказ
+          </Button.Root>
+          <Button.Root variant="soft" tone="neutral" onClick={() => setAnswer("Изменить")}>
+            Изменить
+          </Button.Root>
+        </Message.Actions>
+        <Message.Actions>
+          <Button.Root
+            variant="soft"
+            tone="neutral"
+            onClick={() => setAnswer("Связаться с менеджером")}
+          >
+            Связаться с менеджером
+          </Button.Root>
+        </Message.Actions>
+        <Message.Actions>
+          <Button.Root variant="soft" tone="neutral" asChild>
+            <a href={INVOICE_URL} target="_blank" rel="noreferrer">
+              Открыть счёт
+            </a>
+          </Button.Root>
+        </Message.Actions>
+      </Message.Root>
+      {answer ? (
+        <Message.Root value="reply" direction="outgoing" time="15:03" status="sent">
+          <Message.Text>{answer}</Message.Text>
+        </Message.Root>
+      ) : null}
+    </div>
+  );
+}

package/src/components/modal/COMPONENT.md

@@ -29,7 +29,7 @@ Modal.Root                    state and dismiss policy (no DOM)
     ├── (grab handle)         below 640px only: aria-hidden bar, a drag starts here
     ├── Modal.Guard           no DOM: holds the dialog (busy / dirty) from inside
     ├── Modal.Header          grid: [Icon] [Title + Description] [Actions] [close button]
-    │   ├── Modal.Icon        40 tile with a tone fill
+    │   ├── Modal.Icon        40 tile with a tone fill; no tile around an Avatar.Root / Thumbnail.Root
     │   ├── Modal.Title       <h2>, names the dialog
     │   ├── Modal.Description <p>, describes the dialog
     │   └── Modal.Actions     row of tier-s controls before the close button
@@ -84,12 +84,12 @@ No DOM, no ref. State and dismiss policy.
 `ref` → `HTMLDivElement`. A row of controls at the end of the header, before the close button: a status Badge, a ⋯ Dropdown, an icon button. Controls inside take tier `s`. + native `<div>` props.
 
 ### Modal.Icon
-`ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill.
+`ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill; around an `Avatar.Root` or a `Thumbnail.Root` (the record's picture) no tile — `data-media`, the avatar sized to 40 px.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Soft fill and icon color. |
-| `children` | `ReactNode` | — (required) | Icon glyph (sized to the m icon). |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Soft fill and icon color; not used around a picture. |
+| `children` | `ReactNode` | — (required) | An icon glyph (sized to the m icon), or the record's picture: an `Avatar.Root` (sized to the tile) or a `Thumbnail.Root`. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the tile. |
 
 ### Modal.Title · Modal.Description
@@ -155,6 +155,8 @@ With a `Modal.Meta` the footer is a row in any layout: the status takes the free
 | `danger` | `danger-soft` tile, danger icon | Delete confirmations | |
 | `info` | `info-soft` tile, info icon | Informational notices | |
 
+Around the record's picture — an `Avatar.Root` or a `Thumbnail.Root` (found by element type) — there is no tile and no tone: `data-media`, the avatar sized to 40 px.
+
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|

package/src/components/page-content/COMPONENT.md

@@ -170,7 +170,7 @@ One `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s
 - Header is a wrapping row: actions stay to the right of the title while the heading keeps half a reading measure, otherwise they wrap below it — no breakpoint needed, works from 320px.
 - Title and Description wrap long words (`overflow-wrap: anywhere`).
 - `fill` needs a main with a height: `AppShell.Root fillViewport` (main scrolls inside the panel). The body passes its free height on to a filling child — DataTable `scrollHeight="fill"`, Crossfade `fill`, `PageContent.Split`.
-- Split takes the free height of a filling page and lays itself out from its own width (container `prime-split`), never from the window: a split beside an open Sidebar may be narrow on a wide screen. Each pane is a column whose last child takes the free height — put a Card with its own `ScrollContainer` there, so the list and the thread scroll separately.
+- Split takes the free height of a filling page and lays itself out from its own width (container `prime-split`), never from the window: a split beside an open Sidebar may be narrow on a wide screen. Each pane is a column whose last child takes the free height — put a Card with its own `ScrollContainer` there, so the list and the thread scroll separately. The records of the list pane are a [List](../list/COMPONENT.md).
 - The detail pane is on screen all the time on a wide split: while nothing is chosen it shows a short hint («Выберите диалог»), never an empty card.
 
 ## Accessibility
@@ -212,4 +212,4 @@ One `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s
 
 ## Related
 - **Built from:** [Button](../button/COMPONENT.md) (`PageContent.BackButton`), Icon (`nav.chevronLeft`)
-- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Drawer](../drawer/COMPONENT.md)
+- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [List](../list/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Drawer](../drawer/COMPONENT.md)

package/src/components/page-content/examples/examples.module.css

@@ -46,24 +46,17 @@
   min-height: 0;
 }
 
-.dialogs,
-.messages {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-1);
-  margin: 0;
+.dialogs {
   padding: var(--prime-space-2);
-  list-style: none;
 }
 
 .messages {
+  display: flex;
+  flex-direction: column;
   gap: var(--prime-space-3);
+  margin: 0;
   padding: var(--prime-space-2) var(--prime-space-4) var(--prime-space-4);
-}
-
-/* A dialog row: the name at the start, the unread count at the end. */
-.dialog {
-  justify-content: space-between;
+  list-style: none;
 }
 
 .hint {

package/src/components/page-content/examples/list-detail.tsx

@@ -1,5 +1,5 @@
 /** A support inbox as list + detail on a full-height page: side by side on a wide panel, one pane at a time with a back button on a narrow one — `PageContent.Split`, `PageContent.BackButton`, `fill`. */
-import { Badge, Button, Card, PageContent, ScrollContainer, Typography } from "prime-ui-kit";
+import { Card, List, PageContent, ScrollContainer, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -58,25 +58,20 @@ export default function PageContentListDetailExample() {
             <PageContent.List aria-label="Диалоги">
               <Card.Root className={styles.paneCard}>
                 <ScrollContainer className={styles.pane}>
-                  <ul className={styles.dialogs}>
+                  <List.Root className={styles.dialogs}>
                     {DIALOGS.map((dialog) => (
-                      <li key={dialog.id}>
-                        <Button.Root
-                          variant={dialog.id === dialogId ? "soft" : "ghost"}
-                          tone="neutral"
-                          fullWidth
-                          aria-current={dialog.id === dialogId ? "true" : undefined}
-                          className={styles.dialog}
-                          onClick={() => open(dialog)}
-                        >
-                          {dialog.client}
-                          {dialog.unread > 0 ? (
-                            <Badge.Root color="blue">{dialog.unread}</Badge.Root>
-                          ) : null}
-                        </Button.Root>
-                      </li>
+                      <List.Item
+                        key={dialog.id}
+                        current={dialog.id === dialogId}
+                        onClick={() => open(dialog)}
+                      >
+                        <List.ItemText>{dialog.client}</List.ItemText>
+                        {dialog.unread > 0 ? (
+                          <List.ItemCount color="blue">{dialog.unread}</List.ItemCount>
+                        ) : null}
+                      </List.Item>
                     ))}
-                  </ul>
+                  </List.Root>
                 </ScrollContainer>
               </Card.Root>
             </PageContent.List>

package/src/components/select/COMPONENT.md

@@ -43,9 +43,18 @@ Select.Root                       field frame: label · control · hint/error; v
     │   ├── Select.Separator      full-bleed Divider
     │   └── skeleton rows         `loading` with no items, `loadingMore` at the end
     ├── empty state               compact EmptyPage
+    ├── role="group"              pinned under the list, owned by the listbox (`aria-owns`)
+    │   └── Select.Action         role="option": [Select.ItemIcon] [text]; never filtered
     └── load error                compact EmptyPage, role="alert", retry Button (`loadError`, `onRetry`)
 ```
 
+An item reads its parts by element type, among its direct children (fragments are opened):
+`Select.ItemIcon`, `Avatar.Root`, `Thumbnail.Root` lead; `Select.ItemText`, `Select.ItemDescription`
+make the text column; `Select.ItemMeta`, `Badge.Root` trail. A wrapper component is a different
+type and lands in the text column: call your helper as a function (`{clientAvatar(client)}`), not as
+an element (`<ClientAvatar client={client} />`). Any other trailing element (a Kbd, a price with
+an icon) goes inside `Select.ItemMeta`.
+
 ## API
 
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -57,7 +66,7 @@ Select.Root                       field frame: label · control · hint/error; v
 |---|---|---|---|
 | `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`. |
+| `onValueChange` | `(value: string) => void \| Promise<void> · (value: string[]) => void \| Promise<void>` | — | The picked value (`""` after clearing) or, with `multiple`, the new list. A promise: the value shows at once with a trigger Spinner, picks wait; reject rolls back and announces `labels.changeFailed`. |
 | `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. |
@@ -113,7 +122,7 @@ Select.Root                       field frame: label · control · hint/error; v
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `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. |
+| `children` | `ReactNode` | — (required) | Items, groups, separators; `Select.Action` children stand under the list. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "hidden" \| "onKeyDown" \| "onAnimationEnd">` | — | `className` and the other attributes of the panel. |
 
 ### Select.Item
@@ -144,6 +153,16 @@ Select.Root                       field frame: label · control · hint/error; v
 |---|---|---|---|
 | `…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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onSelect` | `() => void` | — (required) | Runs the action: a click, or Enter / Space while it is highlighted; the list then closes and the value stays. |
+| `disabled` | `boolean` | `false` | Muted, skipped by the keyboard, not runnable. |
+| `children` | `ReactNode` | — (required) | The action text; an optional `Select.ItemIcon` in front. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "onSelect" \| "role" \| "id" \| "children">` | — | `className` and the other attributes of the row. |
+
 ## 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.
 
@@ -166,8 +185,10 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | `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; `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: «Новый клиент», «Пригласить в команду» | |
+| async `onValueChange` | the picked value at once, a Spinner instead of the chevron until the promise settles | The choice saves on the server right away | |
 
-**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.
+**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. `Select.Action` is a direct child of `Select.Content`; when the search finds nothing, the empty text and the action show together (text above, action pinned below) and the action takes the highlight, so Enter runs it — never repeat the action inside the empty state. A promise from `onValueChange` works in single and `multiple` mode: picks and the clear segment wait until it settles; on a rejection show the reason through `error` (and rethrow, so the value rolls back).
 
 ## States
 | State | Driven by | DOM |
@@ -177,11 +198,12 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | 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 |
+| saving | a pending promise from `onValueChange` | the new value shows; Spinner instead of the chevron, `data-loading="true"` and `aria-busy` on the trigger, `aria-busy` on the list; picks and clear wait; a rejection restores the value and puts `labels.changeFailed` in a polite `role="status"` 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 |
+| 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; a `Select.Action` stays under it, highlighted |
 | 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 |
 
@@ -234,8 +256,8 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | 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. |
+| `ArrowDown` · `ArrowUp` · `Home` · `End` | In the list move the highlight over the enabled options, wrapping; a `Select.Action` is the last stop after the options. |
+| `Enter` · `Space` | Pick the highlighted option; a single pick closes the list and returns focus to the trigger. On a `Select.Action`, run it and close the list. |
 | `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`). |
@@ -248,6 +270,8 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 - 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.
+- `Select.Action` rows are `role="option"` in a `role="group"` under the scroller; the listbox owns the group through `aria-owns`, and the highlight reaches them through `aria-activedescendant`.
+- While an `onValueChange` promise is pending the trigger is `aria-busy`; a rejection announces `labels.changeFailed` in a polite `role="status"` region.
 - 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).
 
@@ -263,6 +287,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | `retry` | `"Повторить"` | The retry button under `loadError` (`onRetry`). |
 | `clear` | `"Очистить"` | Tooltip of the clear segment. |
 | `optional` | `"необязательно"` | Muted marker after the label when `optional`. |
+| `changeFailed` | `"Не удалось сохранить выбор"` | Announced when the `onValueChange` promise rejects and the value rolls back. |
 
 ## Examples
 | Example | Shows |
@@ -275,8 +300,10 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | [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`. |
+| [create-action.tsx](examples/create-action.tsx) | A client search with a pinned "new client" action: it stays under the list whatever the query, the arrows reach it after the last client, and it opens the form that adds and picks the new client — `Select.Action`, `searchable`. |
 | [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`. |
+| [saving.tsx](examples/saving.tsx) | A choice that saves on the server at once: the picked value shows with a spinner on the trigger, and a refused save rolls it back and says why — `onValueChange`, `error`. |
 | [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`. |
@@ -294,7 +321,11 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 - 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.
+- `<ClientAvatar />` or `<RoleBadge />` (your own component) inside an item → the item reads parts by element type and puts an unknown component in the text column; call the helper as a function (`{clientAvatar(client)}`) so `Avatar.Root` / `Badge.Root` is the direct child.
+- A custom trailing element (a Kbd, an icon with a price) as a bare child → wrap it in `Select.ItemMeta`.
+- A «Новый клиент» row faked as a `Select.Item` with a sentinel value, or a button under the field → use `Select.Action`: never filtered, reached by the arrows, never a value.
+- Saving the choice in `onValueChange` and resetting the value by hand on failure → return the promise; the Select shows the value, waits and rolls back by itself.
 
 ## Related
-- **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)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (list), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in `multiple`), [Spinner](../spinner/COMPONENT.md) (`loading` and saving 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 and save-failure announcements), `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/create-action.tsx

@@ -0,0 +1,107 @@
+/** A client search with a pinned "new client" action: it stays under the list whatever the query, the arrows reach it after the last client, and it opens the form that adds and picks the new client — `Select.Action`, `searchable`. */
+import { Button, Icon, Input, Modal, Select } from "prime-ui-kit";
+import * as React from "react";
+
+type Client = { value: string; name: string; city: string };
+
+const CLIENTS: Client[] = [
+  { value: "romashka", name: "ООО «Ромашка»", city: "Москва" },
+  { value: "vector", name: "АО «Вектор»", city: "Санкт-Петербург" },
+  { value: "severstroy", name: "ООО «Северстрой»", city: "Мурманск" },
+  { value: "techno", name: "ИП Технопарк", city: "Казань" },
+];
+
+export default function SelectCreateActionExample() {
+  const formId = React.useId();
+  const [clients, setClients] = React.useState(CLIENTS);
+  const [client, setClient] = React.useState("");
+  const [query, setQuery] = React.useState("");
+  const [creating, setCreating] = React.useState(false);
+  const [draft, setDraft] = React.useState("");
+  const [error, setError] = React.useState<string>();
+
+  const startCreate = () => {
+    // The query the person typed becomes the name to start from.
+    setDraft(query.trim());
+    setError(undefined);
+    setCreating(true);
+  };
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const name = draft.trim();
+    if (!name) {
+      setError("Введите название клиента");
+      return;
+    }
+    const value = `client-${clients.length + 1}`;
+    setClients((current) => [...current, { value, name, city: "Город не указан" }]);
+    setClient(value);
+    setCreating(false);
+  };
+
+  return (
+    <>
+      <Select.Root
+        label="Клиент"
+        placeholder="Выберите клиента"
+        value={client}
+        onValueChange={setClient}
+        search={query}
+        onSearchChange={setQuery}
+        labels={{ search: "Найти клиента" }}
+      >
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content searchable>
+          {clients.map((item) => (
+            <Select.Item key={item.value} value={item.value}>
+              <Select.ItemText>{item.name}</Select.ItemText>
+              <Select.ItemDescription>{item.city}</Select.ItemDescription>
+            </Select.Item>
+          ))}
+          <Select.Action onSelect={startCreate}>
+            <Select.ItemIcon>
+              <Icon name="action.add" />
+            </Select.ItemIcon>
+            Новый клиент
+          </Select.Action>
+        </Select.Content>
+      </Select.Root>
+      <Modal.Root open={creating} onOpenChange={setCreating}>
+        <Modal.Content size="s">
+          <Modal.Header>
+            <Modal.Title>Новый клиент</Modal.Title>
+          </Modal.Header>
+          <Modal.Body>
+            <form id={formId} noValidate onSubmit={submit}>
+              <Input.Root label="Название" required error={error}>
+                <Input.Wrapper>
+                  <Input.Field
+                    value={draft}
+                    autoFocus
+                    onValueChange={(next) => {
+                      setDraft(next);
+                      setError(undefined);
+                    }}
+                  />
+                </Input.Wrapper>
+              </Input.Root>
+            </form>
+          </Modal.Body>
+          <Modal.Footer>
+            <Modal.Close>
+              <Button.Root variant="outline" tone="neutral">
+                Отмена
+              </Button.Root>
+            </Modal.Close>
+            <Button.Root type="submit" form={formId}>
+              Добавить
+            </Button.Root>
+          </Modal.Footer>
+        </Modal.Content>
+      </Modal.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,47 @@
+/** A choice that saves on the server at once: the picked value shows with a spinner on the trigger, and a refused save rolls it back and says why — `onValueChange`, `error`. */
+import { Select } from "prime-ui-kit";
+import * as React from "react";
+
+/** The server's answer a beat later: an invoice cannot go back to a draft once it is sent. */
+function saveStatus(status: string) {
+  return new Promise<void>((resolve, reject) => {
+    setTimeout(() => {
+      if (status === "draft") reject(new Error("Отправленный счёт нельзя вернуть в черновик"));
+      else resolve();
+    }, 900);
+  });
+}
+
+export default function SelectSavingExample() {
+  const [status, setStatus] = React.useState("sent");
+  const [error, setError] = React.useState<string>();
+
+  return (
+    <Select.Root
+      label="Статус счёта № 2048"
+      value={status}
+      error={error}
+      hint="Сохраняется сразу"
+      onValueChange={async (next) => {
+        setError(undefined);
+        try {
+          await saveStatus(next);
+        } catch (reason) {
+          setError(reason instanceof Error ? reason.message : String(reason));
+          throw reason;
+        }
+        setStatus(next);
+      }}
+    >
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        <Select.Item value="draft">Черновик</Select.Item>
+        <Select.Item value="sent">Отправлен</Select.Item>
+        <Select.Item value="paid">Оплачен</Select.Item>
+        <Select.Item value="cancelled">Отменён</Select.Item>
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/src/components/sheet/COMPONENT.md

@@ -79,12 +79,12 @@ No DOM, no ref. State and dismiss policy.
 `ref` → `HTMLDivElement`. A row of controls at the end of the header, before the close button: a status Badge, a ⋯ Dropdown, an icon button. Controls inside take tier `s`. + native `<div>` props.
 
 ### Sheet.Icon
-`ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill.
+`ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill; around an `Avatar.Root` or a `Thumbnail.Root` (the record's picture) no tile — `data-media`, the avatar sized to 40 px.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Soft fill and icon color. |
-| `children` | `ReactNode` | — (required) | Icon glyph (sized to the m icon). |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Soft fill and icon color; not used around a picture. |
+| `children` | `ReactNode` | — (required) | An icon glyph (sized to the m icon), or the record's picture: an `Avatar.Root` (sized to the tile) or a `Thumbnail.Root`. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the tile. |
 
 ### Sheet.Title · Sheet.Description
@@ -135,7 +135,7 @@ Sheet has no `variant`, `side` or `size`: it always rises from the bottom edge,
 | `fill` | equal-width buttons in one row | two equal answers | |
 
 ### tone (Icon)
-`neutral` (default) · `accent` · `success` · `warning` · `danger` · `info` — soft tile fill and icon color, as in Modal.
+`neutral` (default) · `accent` · `success` · `warning` · `danger` · `info` — soft tile fill and icon color, as in Modal. Around the record's picture — an `Avatar.Root` or a `Thumbnail.Root` (found by element type) — there is no tile and no tone: `data-media`, the avatar sized to 40 px.
 
 ## States
 | State | Driven by | DOM |

package/src/components/sparkline/COMPONENT.md

@@ -10,6 +10,7 @@
 - A trend next to a number where the shape matters more than exact axes.
 - Values with a sign by period — profit, net new customers (`variant="bars"`: up when positive, down when negative), with the current period highlighted (`highlight`).
 - A detail page header that shows how a value moved.
+- A trend per record in a table cell or a list row (`layout="compact"`): revenue by month per client.
 
 ## When not to use
 - Exact values on axes, several series, or a legend → a full chart library on the kit's chart palette (`chartColors`); Sparkline has no axes.
@@ -31,6 +32,7 @@ Sparkline              <div>; the headline and the chart; aria-busy while loadin
    ├─ line:            svg line and area + cursor (guide line and dot, aria-hidden)
    └─ bars:            zero line (chart axis) + a slot per point with its bar (aria-hidden)
 loading:               Skeletons of the date, the value line and the plot
+compact:               the plot alone (no head, no value row); loading — the plot Skeleton
 ```
 
 ## API
@@ -43,7 +45,8 @@ loading:               Skeletons of the date, the value line and the plot
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `data` | `SparklinePoint[]` | — (required) | Points oldest first, `{ label, value }`; `label` names the point («8 окт»). Two or more draw a line. A new array cross-fades the line in. |
-| `label` | `string` | — (required) | Visible title above the value and the accessible name of the chart. |
+| `label` | `string` | — (required) | Visible title above the value and the accessible name of the chart; with `layout="compact"` only the accessible name. |
+| `layout` | `"default" \| "compact"` | `"default"` | `default` — the headline over an 80 px plot; `compact` — the plot alone at an `xs` control height with the dot at rest, for a DataTable cell; the point stays in `aria-valuetext`. |
 | `variant` | `"line" \| "bars"` | `"line"` | `line` — a line over a soft area; `bars` — a bar per point standing on a zero line: up when positive, down (danger) when negative, the value end rounded. |
 | `highlight` | `number` | `the latest point` | Index of the point at rest (the current month): the headline shows it when nobody scrubs and leaving the chart returns to it; `bars` draw the other bars quieter. |
 | `loading` | `boolean` | `false` | The series is on its way: Skeletons of the date, the value and the plot that cross-fade into the data; the title stays, the root is `aria-busy` and the chart is not focusable yet. |
@@ -59,6 +62,12 @@ loading:               Skeletons of the date, the value line and the plot
 | `line` | an accent line over a soft area, a dot on the shown point | a continuous trend (daily revenue) | yes |
 | `bars` | a bar per point from a zero line (`--prime-color-chart-axis`): accent up, danger down, value end rounded | values by period, especially with a sign (monthly profit) | |
 
+### layout
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `default` | the headline (title · date, value · change) over an 80 px plot | a dashboard tile, a page header | yes |
+| `compact` | the plot alone at the height of an `xs` control (28 px), the dot on the point at rest, the guide line only while scrubbing; at least 96 px wide | a DataTable cell or a list row: one trend per record next to its name or total | |
+
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -76,6 +85,7 @@ Put it in a `Card` for a dashboard tile.
 | settle | pointer leaves, touch ends, focus leaves | back to the point at rest |
 | change hidden | the first point, the previous value is 0, or the sign flips | no change Badge: a percentage would mean nothing |
 | new series | a new `data` array | the chart cross-fades in (swap motion); the trend arrow turns half a turn between up and down |
+| compact | `layout="compact"` | `data-layout="compact"` on the root; no headline: `label` names the slider, the point is spoken through `aria-valuetext`; the guide fades in while scrubbing (`fast`) |
 | loading | `loading` | `aria-busy` on the root; Skeletons in place of the date, the value and the plot; no slider until the data comes; the data cross-fades in |
 
 ## Layout & spacing
@@ -83,6 +93,7 @@ Put it in a `Card` for a dashboard tile.
 - Bars share the width equally, 4 px apart; the zero line sits where 0 falls on the scale (the bottom when every value is positive).
 - In a dashboard, wrap it in `Card.Root` + `Card.Body`; several cards go in a grid.
 - When the value row does not fit (a narrow card), the change badge wraps under the value.
+- `layout="compact"` fits a DataTable row of any tier (plot and dot within an `xs` control height) and takes the cell width, at least `--prime-space-24`; give the column a `width` for an even plot per row. Put the number next to it in its own column: the compact plot shows no value.
 
 ## Accessibility
 
@@ -98,6 +109,7 @@ Put it in a `Card` for a dashboard tile.
 - The headline with the value and change reads as plain text.
 - The change carries a sign and an arrow, never color alone; a negative bar goes down, not only red.
 - While `loading` the root is `aria-busy` and the chart is not in the tab order yet.
+- `layout="compact"`: no visible title; `label` is only the slider's name, the point still goes to `aria-valuetext`. The plot carries `data-row-click-ignore` (and is a slider), so its pointer and keys never open a DataTable row.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -112,6 +124,7 @@ Put it in a `Card` for a dashboard tile.
 | [overview.tsx](examples/overview.tsx) | Revenue for 30 days in a dashboard card: drag across the chart, the headline follows and the trend arrow turns — `data`, `label`, `formatValue`. |
 | [variants.tsx](examples/variants.tsx) | The same week as a line and as bars from zero — `variant`. |
 | [states.tsx](examples/states.tsx) | While the series loads the date, the value and the plot are Skeletons in their own places; the title stays — `loading`. |
+| [compact.tsx](examples/compact.tsx) | Revenue by month per client in a list: the plot alone at a row's height with the dot on the current month, the label is the chart's accessible name — `layout`, `label`. |
 | [signed-bars.tsx](examples/signed-bars.tsx) | Monthly profit with a sign: losses go below the zero line, the current month rests highlighted and any bar shows its value under the pointer or the arrows — `variant`, `highlight`. |
 | [period.tsx](examples/period.tsx) | Another period swaps the series: the line cross-fades in and the headline digits roll to the new total — `data`. |
 
@@ -121,7 +134,8 @@ Put it in a `Card` for a dashboard tile.
 - A Sparkline without a container width (inside an inline flex row) → give it a width or put it in a `Card`.
 - A separate tooltip over the bars → the headline already shows the scrubbed point; a floating tooltip would cover the next bar.
 - A grey box while the series loads → `loading`.
+- A full Sparkline squeezed into a table cell, or its headline hidden with CSS → `layout="compact"`.
 
 ## Related
 - **Built from:** [Badge](../badge/COMPONENT.md) (change), [Skeleton](../skeleton/COMPONENT.md) (loading), `Icon` (trend arrow)
-- **See also:** [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)
+- **See also:** [DataTable](../data-table/COMPONENT.md) (a compact Sparkline per row), [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/sparkline/examples/compact.tsx

@@ -0,0 +1,41 @@
+/** Revenue by month per client in a list: the plot alone at a row's height with the dot on the current month, the label is the chart's accessible name — `layout`, `label`. */
+import { Card, Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const MONTHS = ["май", "июн", "июл", "авг", "сен", "окт"];
+
+const CLIENTS = [
+  { name: "ООО «Северный ветер»", revenue: [184, 196, 172, 210, 238, 251] },
+  { name: "АО «Технопарк»", revenue: [612, 580, 545, 498, 470, 455] },
+  { name: "ИП Козлов", revenue: [28, 31, 27, 35, 33, 41] },
+];
+
+const series = (revenue: number[]): SparklinePoint[] =>
+  revenue.map((value, i) => ({ label: MONTHS[i] ?? "", value: value * 1000 }));
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+export default function SparklineCompactExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Body>
+        <div className={styles.list}>
+          {CLIENTS.map((client) => (
+            <div key={client.name} className={styles.listRow}>
+              <Typography as="span" variant="body-s">
+                {client.name}
+              </Typography>
+              <Sparkline
+                layout="compact"
+                data={series(client.revenue)}
+                label={`Выручка по месяцам, ${client.name}`}
+                formatValue={formatRubles}
+              />
+            </div>
+          ))}
+        </div>
+      </Card.Body>
+    </Card.Root>
+  );
+}