prime-ui-kit 0.20.1 → 0.21.0

package/src/components/badge/COMPONENT.md

@@ -35,7 +35,9 @@ Badge.Root          <span>: fill, tier dimensions
 ├─ Badge.Action     optional end segment revealed on hover / focus (always shown on touch screens)
 └─ remove segment   with onRemove: full height, the whole end is the hit area (Icon action.close)
 
-Badge.Group         <div>: a wrapping row of Badge.Root, one value; `size` sets every badge's tier
+Badge.Group         <div>: a row of Badge.Root, one value; `size` sets every badge's tier
+├─ Badge.Root …     one per value; with overflow="count" the ones that do not fit are hidden
+└─ «+N» badge       overflow="count": a focusable Badge.Root in a Tooltip listing the hidden values
 ```
 
 ## API
@@ -64,12 +66,14 @@ Badge.Group         <div>: a wrapping row of Badge.Root, one value; `size` sets
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "onClick" \| "color">` | — | `aria-label` (an icon-only badge named by it is an image) and the other span attributes; no `onClick` — a pressable chip is the toggle. |
 
 ### Badge.Group
-`ref` → `HTMLDivElement`. A row of badges as one value (the tags of a record): it wraps onto more lines, the badges a chip gap apart.
+`ref` → `HTMLDivElement`. A row of badges as one value (the tags of a record): it wraps onto more lines, the badges a chip gap apart, or with `overflow` stays on one line behind a «+N» badge.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | the host tier, one step down | Tier of every badge in the group; a badge's own `size` wins. Small tiers stand closer. |
-| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the `Badge.Root`s), `className`, `aria-label` (a named group is `role="group"`) and the other div attributes. |
+| `overflow` | `"wrap" \| "count"` | `"wrap"` | `wrap` — the row wraps onto more lines. `count` — one line (a table cell): the badges that fit the container, the rest behind a focusable «+N» badge whose tooltip lists them. |
+| `labels` | `Partial<BadgeGroupLabels>` | — | Built-in strings of the «+N» badge, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the `Badge.Root`s, one per value), `className`, `aria-label` (a named group is `role="group"`) and the other div attributes. |
 
 ### Badge.Icon
 `ref` → `HTMLSpanElement`. A `<span>` holding one icon at the tier icon size. At the first or last position it becomes a full-height edge segment.
@@ -146,6 +150,12 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 | `xl` | 32px high, text 14, icon 16 | large headers | |
 | — (omitted) | one tier below the surrounding control | inside Button, Input, Tabs | yes (inside controls) |
 
+### overflow (Badge.Group)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `wrap` | the row wraps onto more lines | tags of a record in a card, a form, a detail pane | yes |
+| `count` | one line: the badges that fit, then «+N» | a table cell, a list row — a set of values that must keep the row's height | |
+
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -167,6 +177,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 | disabled | `disabled` | `data-disabled`, `aria-disabled`; inner buttons disabled, no hover wash |
 | icon-only, named | only `Badge.Icon` children and `aria-label` | `role="img"` with that name |
 | count | a number as the only child | the digits roll to the new value when the number changes |
+| overflowed | `Badge.Group overflow="count"`, the badge does not fit the row | `data-overflowed` on the badge (out of the flow, `visibility: hidden`); the group's `data-overflow="count"`; re-measured on every resize of the row or a badge (`useResizeEffect`), the «+N» text from `labels.more` |
 
 ## Layout & spacing
 - Inline-flex, `width: fit-content`, `max-width: 100%`; text never wraps and ends in an ellipsis.
@@ -175,6 +186,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - The root never clips: the text ellipsizes in its own box, so the segments' touch areas reach past the chip.
 - `Badge.Action` room is reserved, so revealing it never changes the badge width.
 - Several badges in a row: `Badge.Group` — it wraps, badges 8 apart (4 at the `xs` and `s` tiers).
+- `overflow="count"` fits the container, not the viewport: a DataTable cell, a 320px column. At least the first badge stays; when it alone does not fit it ellipsizes.
 - In a list row the badge is the trailing column; the title column gets `min-width: 0` and an ellipsis.
 
 ## Accessibility
@@ -184,7 +196,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 
 | Key | Action |
 |---|---|
-| `Tab` | Focuses the body of a toggle chip, then its action or remove segment. |
+| `Tab` | Focuses the body of a toggle chip, then its action or remove segment; in `Badge.Group` with `overflow` the «+N» badge, which opens its tooltip with the hidden values. |
 | `Enter` · `Space` | Presses the focused body (the toggle flips), remove or action button. |
 
 ### ARIA
@@ -195,15 +207,25 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - Give every remove button a unique name with `labels.remove`; after removing, move focus to a neighbouring badge or the source field.
 - While a removal is saved the badge has `aria-busy` and the segment `aria-disabled`; once a removal waits, the badge mounts a polite live region that speaks `labels.removeFailed` if the promise rejects.
 - `Badge.Dot` is `aria-hidden`; an icon-only badge needs `aria-label` and then is `role="img"`. Color never carries meaning alone, a `tone` neither.
+- `overflow="count"`: the badges that did not fit are `visibility: hidden` (out of the tree and the Tab order); the «+N» badge is a tab stop read as `labels.moreCount`; its tooltip, open while it has focus, lists the hidden values as its description.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
+#### Badge.Root
+
 | Key | Default | Used for |
 |---|---|---|
 | `remove` | `"Удалить"` | Accessible name of the remove segment; include the badge text («Убрать фильтр «Москва»»). |
 | `removeFailed` | `"Не удалось удалить"` | Spoken when the `onRemove` promise rejects and the badge stays; name the badge («Фильтр «Москва» не убран»). |
 
+#### Badge.Group
+
+| Key | Default | Used for |
+|---|---|---|
+| `more` | `"+{count}"` | Visible text of the badge for the badges that did not fit; `{count}` — how many. |
+| `moreCount` | `"Ещё {count}"` | What assistive tech reads for that badge instead of its visible text; `{count}` — how many. The values themselves come in its tooltip. |
+
 ## Examples
 | Example | Shows |
 |---|---|
@@ -218,6 +240,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 | [filter-values.tsx](examples/filter-values.tsx) | Filter values as toggles with a hide action that slides in without changing the width — `pressed`, `onPressedChange`, `Badge.Action`, `persistent`. |
 | [square.tsx](examples/square.tsx) | File formats as square tiles of text, large enough for three letters; the hue sorts them by kind — `shape`, `size`, `color`. |
 | [tag-row.tsx](examples/tag-row.tsx) | The tags of a client as one value: the row wraps in a narrow column and keeps one gap between badges — `Badge.Group`, `size`. |
+| [overflow-count.tsx](examples/overflow-count.tsx) | The sections of each role in one line of a narrow cell: what does not fit waits behind «+N» with the full list in its tooltip — `Badge.Group`, `overflow`. |
 | [controlled.tsx](examples/controlled.tsx) | Delivery cities as toggle chips whose state the screen owns: the summary counts the chosen ones — `pressed`, `onPressedChange`. |
 
 ## Mistakes
@@ -230,9 +253,10 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - A colored badge with no text → keep a word; color alone is not a signal.
 - An explicit `size` inside a control → drop it; the badge takes the tier one step down.
 - A row of badges in a hand-made flex wrapper with its own gap → `Badge.Group`.
+- A set of values in a table cell that wraps and grows the row, or a hand-made «+N» → `Badge.Group overflow="count"`.
 - `onRemove` together with `Badge.Action` → one end segment per badge.
 - Removing the badge from your list first and putting it back when the request fails → return the request's promise and remove it after it succeeds; the badge waits meanwhile.
 
 ## Related
-- **Built from:** `Icon` (remove ×, `Badge.Action` −), [Spinner](../spinner/COMPONENT.md) (removing), `internal/chipTier` (tiers), `internal/glyphSwap` (× ⇄ spinner), `internal/partPresence` (leaving), [VisuallyHidden](../visually-hidden/COMPONENT.md)
+- **Built from:** `Icon` (remove ×, `Badge.Action` −), [Spinner](../spinner/COMPONENT.md) (removing), `internal/chipTier` (tiers), `internal/glyphSwap` (× ⇄ spinner), `internal/partPresence` (leaving), [VisuallyHidden](../visually-hidden/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md) (the «+N» list), `useResizeEffect` (fitting the row), `internal/formatLabel` (`labels`)
 - **See also:** [TagSelect](../tag-select/COMPONENT.md), [Select](../select/COMPONENT.md) (row badges), [SegmentedControl](../segmented-control/COMPONENT.md) (`Count`, color dots), [SmartFilter](../smart-filter/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [Avatar](../avatar/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

package/src/components/badge/examples/examples.module.css

@@ -30,3 +30,17 @@
   gap: var(--prime-space-6);
   inline-size: min(100%, calc(var(--prime-space-20) * 4));
 }
+
+/* overflow-count.tsx: rows of a narrow table — the role, then its sections in a cell. */
+.roles {
+  display: grid;
+  gap: var(--prime-space-3);
+  inline-size: min(100%, var(--prime-layout-form-width-s));
+}
+
+.role {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  align-items: center;
+  gap: var(--prime-space-3);
+}

package/src/components/badge/examples/overflow-count.tsx

@@ -0,0 +1,32 @@
+/** The sections of each role in one line of a narrow cell: what does not fit waits behind «+N» with the full list in its tooltip — `Badge.Group`, `overflow`. */
+import { Badge, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ROLES = [
+  {
+    name: "Администратор",
+    sections: ["Сделки", "Контакты", "Счета", "Отчёты", "Склад", "Настройки"],
+  },
+  { name: "Менеджер", sections: ["Сделки", "Контакты", "Задачи"] },
+  { name: "Бухгалтер", sections: ["Счета", "Акты", "Платежи", "Отчёты"] },
+];
+
+export default function BadgeOverflowCountExample() {
+  return (
+    <div className={styles.roles}>
+      {ROLES.map((role) => (
+        <div key={role.name} className={styles.role}>
+          <Typography as="span" variant="body-m">
+            {role.name}
+          </Typography>
+          <Badge.Group overflow="count" aria-label={`Разделы роли «${role.name}»`}>
+            {role.sections.map((section) => (
+              <Badge.Root key={section}>{section}</Badge.Root>
+            ))}
+          </Badge.Group>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/banner/COMPONENT.md

@@ -117,7 +117,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 | dismissible | `onDismiss` | corner ghost Button (`xs`, `s` on `l` / `xl`), or the last outline Button in `Banner.Actions` |
 | narrow | own width < 36rem (a banner with `Banner.Actions` is a size container) | actions move under the text; the close button returns to the corner |
 
-No `open` prop: the parent mounts and unmounts the banner. A mounted banner enters (a short fade and rise); an unmounted one closes up in place, so the content below glides up instead of jumping. To swap the banner for another block in the same spot (a «restore» button), wrap both in [Crossfade](../crossfade/COMPONENT.md).
+No `open` prop: the parent mounts and unmounts the banner. A banner that appears on a page already shown enters (a short fade and rise), one that mounts with its page stands still; an unmounted one closes up in place, so the content below glides up instead of jumping. To swap the banner for another block in the same spot (a «restore» button), wrap both in [Crossfade](../crossfade/COMPONENT.md).
 
 ## Layout & spacing
 - `width: 100%`; text column capped at `--prime-layout-reading-max-width`.

package/src/components/card/COMPONENT.md

@@ -9,6 +9,7 @@
 - KPI tiles on a dashboard (`mini`, `stat-trend`, `split`).
 - A chart or text widget with a header and controls (`panel`).
 - A settings or profile form grouped on its own surface (`panel` + `Body` + `Footer`).
+- A block about one person or object — a linked account, a contact — headed by its picture (`Card.Icon` with an `Avatar.Root` in `Card.Header`).
 - An activity list (`list`), a call to action (`cta`), a tile with an image on top (`cover`).
 - A tile that is itself the way to its details — a KPI that opens its report, a project tile (`asChild` with a link or a button).
 
@@ -25,7 +26,7 @@ import { Card } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Card.Root variant="panel"        Header(Title, Description?, …trailing) · Body · Media · Footer
+Card.Root variant="panel"        Header(Icon?, Title, Description?, …trailing) · Body · Media · Footer
 Card.Root variant="mini"         Icon · Label · Value · Meta? · Media?
 Card.Root variant="stat-trend"   Label · Value · Delta · Meta?
                                  or Header(Badge or Icon, Value) · Description
@@ -52,7 +53,7 @@ Card.Root asChild                <a> or <button> (the only child) holding the pa
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` + `aria-labelledby` for a landmark block, and the other div attributes. |
 
 ### Card.Header
-`ref` → `HTMLDivElement`. The top row: `Card.Title` first, anything after it (a control, a quiet caption) at the end. Wraps below 22rem.
+`ref` → `HTMLDivElement`. The top row: an optional `Card.Icon`, `Card.Title` with an optional `Card.Description` under it, anything else (a control, a caption) at the end. Wraps below 22rem.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -95,7 +96,7 @@ Card.Root asChild                <a> or <button> (the only child) holding the pa
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes of the element. |
 
 ### Card.Icon
-`ref` → `HTMLDivElement`. The 40px accent tile of a KPI holding one icon; it spans the label and the value rows in `mini` and a `split` cell.
+`ref` → `HTMLDivElement`. The 40px accent tile of one icon: beside the label and value in `mini` and a `split` cell, first in `Card.Header`. An `Avatar.Root` or `Thumbnail.Root` inside (also in a wrapper) is the record's picture: no tile, 40px, `aria-hidden`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -179,6 +180,7 @@ Without `asChild` a card is static: no hover, focus or press of its own. With it
 - Depth comes from nesting (foundation §4): on the page — the AppShell panel is the page — a card is layer 1 (white in light) with the raised whisper; inside another card it is the next layer, a flat tile. The ladder stops at layer 4.
 - Long values wrap; labels truncate, except in a `mini` tile and a `split` cell, where a label beside the icon wraps instead; a chart SVG needs a CSS height.
 - In a `Header` the title takes the free width; a control or a caption after it sits at the end without a wrapper. A `Card.Description` in the header stacks under the title, 4 apart; the control stays at the end, centred on both lines.
+- A `Card.Icon` in a `Header` leads the row, 12 before the title, centred on the title and the description: the accent tile, or the record's picture — an `Avatar.Root` or a `Thumbnail.Root` anywhere inside, also from your own wrapper component, with no tile; it takes 40 px whatever size it was given — for a card about one person or object (a linked account, a contact).
 - `Card.Meta` in `stat-trend` takes the bottom of the tile (`margin-top: auto`), so tiles of one row line their meta up; in `mini` and a `split` cell it sits in the text column under the value.
 
 ## Accessibility
@@ -212,6 +214,7 @@ No `labels`.
 | [variants.tsx](examples/variants.tsx) | KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change in every tone and a reference line — `variant`, `Card.Delta`, `tone`, `Card.Meta`. |
 | [kpi-media.tsx](examples/kpi-media.tsx) | A KPI with a sparkline or a fill level in the bottom slot of `mini` — `Card.Media`. |
 | [panel-chart.tsx](examples/panel-chart.tsx) | A chart widget: a header with a short description and a period switch, and a Sparkline with the period total over its chart — `Card.Header`, `Card.Description`, `Card.Body`. |
+| [person-header.tsx](examples/person-header.tsx) | A linked Telegram account in an employee card: the avatar leads the header, the handle stands under the name and the unlink button sits at the end — `Card.Icon`, `Avatar.Root`, `Card.Description`. |
 | [interactive.tsx](examples/interactive.tsx) | Whole cards as links to their reports: one tab stop each, a lift on hover, a press and the focus ring — `asChild`. |
 | [content-templates.tsx](examples/content-templates.tsx) | Content templates: a call to action, an events list and a campaign tile with a cover — `Card.Footer`, `Card.List`, `Card.Media`. |
 | [flat.tsx](examples/flat.tsx) | A flat tile without the raised shadow next to the default one, for dense grids — `flat`. |
@@ -225,6 +228,7 @@ No `labels`.
 - `Card.Delta tone="success"` for every «+» → choose the tone by meaning.
 - Custom padding on a `panel` root → padding belongs to `Header` / `Body` / `Footer`.
 - A wrapper `<div>` around the label and the value of `mini` → put `Icon`, `Label`, `Value` straight into the root (or into a `split` cell); the template lays them out.
+- An avatar, a name and a handle hand-laid in `Card.Body` with a button beside them → `Card.Header` with `Card.Icon` (the `Avatar.Root`), `Card.Title`, `Card.Description` and the button.
 - A chart SVG with only a `viewBox` → give it a CSS height.
 - A hand-drawn trend SVG in a chart widget → `Sparkline` in the `Body` (or `Media`); a chart with a legend and states → `ChartFrame`.
 - A clickable `<div>` card with `onClick` → `asChild` with a real `<a href>` (Cmd-click, a new tab) or a `<button>`.
@@ -233,5 +237,5 @@ No `labels`.
 - Skeletons placed by hand inside `Card.Value` → `Card.Root loading`; keep the parts mounted while loading so each holds its place.
 
 ## Related
-- **Built from:** [Skeleton](../skeleton/COMPONENT.md)
+- **Built from:** [Skeleton](../skeleton/COMPONENT.md), `internal/mediaSlot` (a record's Avatar or Thumbnail in `Card.Icon`)
 - **See also:** [Page](../../layout/page/COMPONENT.md), [DescriptionList](../description-list/COMPONENT.md) (record details inside a `Card.Body`), [Fieldset](../fieldset/COMPONENT.md) (groups of fields inside a settings card), [DataTable](../data-table/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Sparkline](../sparkline/COMPONENT.md) (a trend with its total inside a `panel`), [ChartFrame](../chart-frame/COMPONENT.md) (a full chart with legend and states)

package/src/components/card/examples/person-header.tsx

@@ -0,0 +1,38 @@
+/** A linked Telegram account in an employee card: the avatar leads the header, the handle stands under the name and the unlink button sits at the end — `Card.Icon`, `Avatar.Root`, `Card.Description`. */
+import { Avatar, Button, Card, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ACCOUNT = {
+  name: "Анна Соколова",
+  initials: "АС",
+  handle: "@a.sokolova",
+  linkedAt: "Привязан 12 сентября",
+};
+
+export default function CardPersonHeaderExample() {
+  return (
+    <div className={styles.panel}>
+      <Card.Root>
+        <Card.Header>
+          <Card.Icon>
+            <Avatar.Root color="blue">
+              <Avatar.Fallback>{ACCOUNT.initials}</Avatar.Fallback>
+            </Avatar.Root>
+          </Card.Icon>
+          <Card.Title>{ACCOUNT.name}</Card.Title>
+          <Card.Description>{ACCOUNT.handle}</Card.Description>
+          <Button.Root variant="outline" tone="neutral">
+            Отвязать
+          </Button.Root>
+        </Card.Header>
+        <Card.Body>
+          <Typography as="p" variant="body-s" tone="secondary">
+            {ACCOUNT.linkedAt}. Бот присылает сюда новые заказы клиентов сотрудника и напоминания о
+            просроченных счетах.
+          </Typography>
+        </Card.Body>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/composer/COMPONENT.md

@@ -34,7 +34,7 @@ Composer.Root                  <form>: the column below, one tier for every part
 │  ├─ Composer.Title           «Ответ Анне», «Редактирование»
 │  └─ Composer.Description     the quoted message, one line
 ├─ (recording error)           Hint, role="alert"
-└─ (row)                       one grid row, always: auto · minmax(0, 1fr) · auto, bottom-aligned
+├─ (row)                       one grid row, always: auto · minmax(0, 1fr) · auto, bottom-aligned
    ├─ Composer.Attach          paperclip: FileUpload trigger="button", or a Dropdown of kinds
    │  └─ Composer.Item         a kind of attachment (accept), with Composer.ItemIcon
    ├─ (field)                  Textarea.Root rows={1} maxRows={8}, no focus ring (the caret shows focus)
@@ -42,10 +42,12 @@ Composer.Root                  <form>: the column below, one tier for every part
    ├─ (recording bar)          over the paperclip and the field cells: delete · pause Buttons · pulsing
    │                           dot (a pause glyph while paused) · timer · live waveform canvas (locked),
    │                           or dot · timer · «Влево — отмена» (held)
-   └─ (action Button)          send ↔ record ↔ save; the glyphs turn into one another
-      └─ (lock pill)           above it while a recording is held: slide up to lock
+│  ├─ (keyboard toggle)        with Composer.Keyboard: a ghost Button before the send button (grid ↔ chevron)
+│  └─ (action Button)          send ↔ record ↔ save; the glyphs turn into one another
+│     └─ (lock pill)           above it while a recording is held: slide up to lock
+└─ Composer.Keyboard           a bot's reply keyboard under the row: rows of soft Buttons, folding open and closed
 ```
-`Composer.Attach` may stand anywhere among the children, inside a fragment or a wrapper component: it renders itself into the start cell of the row (a portal), so the paperclip, the field and the button are always one row. Everything else stands above the row. Without it the row is field and button only.
+`Composer.Attach` may stand anywhere among the children, inside a fragment or a wrapper component: it renders itself into the start cell of the row (a portal), so the paperclip, the field and the button are always one row. `Composer.Keyboard` does the same with its two places: the keys under the row and the toggle before the send button. Everything else stands above the row. Without it the row is field and button only.
 
 Sending is an async event (`SKILL/api-contract.md`, Events):
 
@@ -160,6 +162,20 @@ In an optimistic chat the send returns at once: add the message to the list with
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the `Icon`), `className` and the other span attributes. |
 
+### Composer.Keyboard
+`ref` → `HTMLDivElement`. A bot's reply keyboard under the row (`role="group"`): a key sends its text through the root's `onSend` and loads while its promise runs; the toggle before the send button shows and hides it.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `rows` | `readonly (readonly ComposerKey[])[]` | — (required) | Rows of keys, each row one line shared equally. A key is its text, or `{ label, icon?, tone? }` with `tone` `"accent" \| "success" \| "danger"`. |
+| `placeholder` | `string` | — | The field's placeholder while the keyboard is shown («Выберите раздел»). |
+| `oneTime` | `boolean` | `false` | Hides the keyboard after a key is used (once its promise resolves) and puts the caret in the field; the toggle shows it again. |
+| `open` | `boolean` | — | Whether the keys are shown (controlled). |
+| `defaultOpen` | `boolean` | `true` | Shown at first, uncontrolled: a keyboard the bot just sent is open. |
+| `onOpenChange` | `(open: boolean) => void` | — | The toggle pressed, or a `oneTime` keyboard used. |
+| `aria-label` | `string` | — | Name of the keyboard and of its toggle. Default `labels.keyboard`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `id`, `className` and the other div attributes. |
+
 ## Variants
 Composer has no `variant`; what the row shows follows its state.
 
@@ -206,6 +222,8 @@ Composer has no `variant`; what the row shows follows its state.
 | starting | the press is answered, the device is not granted yet | already the recording bar with a running timer (it counts from the press) while the device is asked for in parallel; the waveform is a calm line of dots |
 | too short | a recording under 0.7 s | dropped: nothing is sent |
 | record error | the browser refused / found no device | the bar cross-fades back to the field; `Hint` with `role="alert"` above the row, cleared by typing or the next attempt |
+| reply keyboard | `Composer.Keyboard` `open` / `defaultOpen` (shown at first) | the keys fold open under the row (`internal/Disclosure`: height glide with a fade, both ways), the toggle shows a chevron down (`aria-expanded="true"`), the field's placeholder is the keyboard's `placeholder`; closed, the keys leave the Tab order and the toggle shows the grid; recording, both are `inert` and the toggle fades with the field |
+| key pressed | a key of `Composer.Keyboard` | `onSend({ text: key, albums: [], files: [] })`; a promise keeps that key `loading` (`aria-busy`); the draft in the field stays; with `oneTime` the keyboard closes once it resolves and the caret goes to the field |
 | disabled | `disabled` | `data-disabled`, disabled controls |
 
 Motion: the tray opens and closes as a Crossfade (fade and height glide, the row below stays still); tiles enter with `enterMotion`, a dragged or Alt-moved tile glides (Dnd), a removed tile closes up in place (`leaveInPlace`), an upload disk's ring fills along its edge and the disk fades out when done; the action glyphs cross-fade and turn (`fast` opacity, `base` emphasized transform) while the button's fill changes with the shared color transition — the button never changes its shape; the recording bar and the field cross-fade (`swapMotion`, both directions) inside the row's own height; the toolbar, the waveform and the delete button enter (`fast`); the recording dot breathes (`slow`, a status loop like a spinner); the lock pill rises in, its arrow follows the finger and it snaps away on lock (`fast`); the video preview scales in (`base` emphasized) and out (`fast`). The timer, the waveform and the video ring are painted per animation frame outside React: the waveform scrolls smoothly between samples. Under `prefers-reduced-motion` the loops stand still and the waveform steps sample by sample, still showing the level.
@@ -218,6 +236,7 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 - The recording bar covers the paperclip and the field, so entering and leaving a recording never changes the row height; its waveform takes all the width between the timer and the send button, as tall as the button minus `--prime-space-2`, in VoicePlayer's bar geometry.
 - On touch the editable text is at least 16 px (no iOS zoom) and every button has the 44 px hit area.
 - The formatting toolbar floats above the field's start edge on the floating layer, over whatever is above the composer.
+- The reply keyboard (`Composer.Keyboard`) stands under the row, `--prime-space-2` below it inside the fold (a closed keyboard takes no room), rows and keys `--prime-space-1` apart. A row is one line, as in Telegram: its keys share it equally (`fullWidth` soft Buttons at the host tier), a label longer than its share ellipsizes. The keyboard is as tall as its rows — Telegram's `resize_keyboard` is always on: a web page has no system keyboard height to match. A key with `icon` puts it before its label (`Button.Icon`); `tone` maps Telegram's button `style` (`primary` → `accent`, `success`, `danger`). The toggle stands before the send button with `--prime-space-1` between them.
 
 ## Accessibility
 
@@ -236,6 +255,7 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 | `↑` · `↓` | On the record button, with voice and video both offered: switches voice and video (`aria-keyshortcuts`, named in the button's description). |
 | `←` · `→` | Move between the formatting buttons. |
 | `Home` · `End` | Jump to the first / last formatting button. |
+| `Enter` · `Space` | On a key of the reply keyboard: sends its text; on the keyboard's toggle: shows or hides the keys. |
 | `Alt + ←` · `Alt + →` | On a tile of the tray: moves the attachment one place. |
 | `Delete` · `Backspace` | On a tile of the tray: removes the attachment; focus moves to its neighbour. |
 
@@ -251,10 +271,13 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 - The attachments are one `<ul>` named «Вложения» (FileUpload.Queue `layout="strip"`): every tile is «Фото N: name» / «Видео N: name» / «Файл N: name» with its upload state, `aria-keyshortcuts` for `Alt + ←` / `→` and `Delete`, a remove button «Убрать name»; the upload disk is a `progressbar` while the file goes up. Moves are announced by Dnd's live region, finished and failed files by the queue's. «Отправить как файлы, без сжатия» is a labelled Checkbox.
 - Touch: the buttons get a 44 px hit area; Enter breaks the line, the button sends.
 - Voice and video together: a single press records without holding, a double press (within 300 ms) switches the mode. The first press records silently until the window ends, so a double press shows no recording and sends nothing.
+- A reply keyboard is a `group` named «Клавиатура бота» of native buttons in Tab order; its toggle is a button of the same name with `aria-expanded` and `aria-controls`. A key whose send is pending is `aria-busy`. Closed, the keys leave the Tab order and the accessibility tree; a `oneTime` keyboard hands the focus to the field.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
+#### Composer.Root
+
 | Key | Default | Used for |
 |---|---|---|
 | `region` | `"Новое сообщение"` | Accessible name of the composer form. |
@@ -295,6 +318,12 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 | `cancelReply` | `"Отменить ответ"` | Name of the close button of a reply bar. |
 | `cancelEdit` | `"Отменить редактирование"` | Name of the close button of an edit bar. |
 
+#### Composer.Keyboard
+
+| Key | Default | Used for |
+|---|---|---|
+| `keyboard` | `"Клавиатура бота"` | Name of the reply keyboard and of the toggle that shows and hides it. |
+
 ## Examples
 | Example | Shows |
 |---|---|
@@ -306,6 +335,7 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 | [typing.tsx](examples/typing.tsx) | The other side's status line follows what you do: typing, recording a voice or a video message, then nothing — `onActivityChange`. |
 | [formatting.tsx](examples/formatting.tsx) | Selected text gets a toolbar of bold, italic, strikethrough, code, spoiler, link and quote, each with its shortcut, written as Markdown around the selection — `formatting`. |
 | [voice.tsx](examples/voice.tsx) | Voice and round video messages: hold the button to record and release to send, slide left to cancel, slide up or tap to record hands-free; a double tap or double click switches voice and video — `onSendVoice`, `onSendVideoNote`, `recordMode`. |
+| [bot-keyboard.tsx](examples/bot-keyboard.tsx) | A bot's reply keyboard under the field: a key sends its text as a message, the field asks for a key, the keyboard hides after use and the toggle brings it back — `Composer.Keyboard`, `rows`, `placeholder`, `oneTime`. |
 | [states.tsx](examples/states.tsx) | A closed conversation is disabled, a slow send keeps the text with a busy button until the server answers — `disabled`, `onSend`. |
 | [controlled.tsx](examples/controlled.tsx) | Every conversation keeps its own draft: switching the chat swaps the text, a template button fills it from outside — `value`, `onValueChange`. |
 | [narrow.tsx](examples/narrow.tsx) | On a phone-width chat the row keeps the paperclip, the field and the button; Enter makes a new line on touch screens and the button sends — `Composer.Attach`, `onSend`. |
@@ -326,5 +356,5 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 - An `aria-label` on the root to rename the field → use `labels.placeholder` (the field) and `labels.region` (the form).
 
 ## Related
-- **Built from:** [Textarea](../textarea/COMPONENT.md), [Button](../button/COMPONENT.md), [FileUpload](../file-upload/COMPONENT.md) (the paperclip and the picker of the menu; `FileUpload.Queue layout="strip"`, the tray), [Gallery](../gallery/COMPONENT.md) (`GALLERY_MAX`, the size of an album in `albums`), [Crossfade](../crossfade/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [Hint](../hint/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), Icon (`action.*`, `format.*`, `nav.chevronLeft`, `nav.chevronUp`, `status.locked`), `useUploadQueue` (the `queue`), `internal/ring` (the video preview's ring), `internal/textFormatting` + `internal/textFormattingToolbar` (the formatting shared with Textarea `formatting`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
+- **Built from:** [Textarea](../textarea/COMPONENT.md), [Button](../button/COMPONENT.md), [FileUpload](../file-upload/COMPONENT.md) (the paperclip and the picker of the menu; `FileUpload.Queue layout="strip"`, the tray), [Gallery](../gallery/COMPONENT.md) (`GALLERY_MAX`, the size of an album in `albums`), [Crossfade](../crossfade/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [Hint](../hint/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), Icon (`action.*`, `format.*`, `nav.chevronLeft`, `nav.chevronUp`, `nav.chevronDown`, `nav.layoutGrid`, `status.locked`), `internal/Disclosure` (the reply keyboard's fold), `useUploadQueue` (the `queue`), `internal/ring` (the video preview's ring), `internal/textFormatting` + `internal/textFormattingToolbar` (the formatting shared with Textarea `formatting`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Message](../message/COMPONENT.md) — the bubbles the composer writes into; [VoicePlayer](../voice-player/COMPONENT.md) — plays a sent voice message; [Textarea](../textarea/COMPONENT.md), [Input](../input/COMPONENT.md)

package/src/components/composer/examples/bot-keyboard.tsx

@@ -0,0 +1,43 @@
+/** A bot's reply keyboard under the field: a key sends its text as a message, the field asks for a key, the keyboard hides after use and the toggle brings it back — `Composer.Keyboard`, `rows`, `placeholder`, `oneTime`. */
+import { Composer, Icon, Message } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SEND_MS = 600;
+
+const BOT_KEYS = [
+  [{ label: "Оформить заказ", icon: <Icon name="action.add" />, tone: "accent" as const }],
+  ["Мои заказы", "Статус доставки"],
+  ["Счета и акты", "Связаться с менеджером"],
+];
+
+export default function ComposerBotKeyboardExample() {
+  const [sent, setSent] = React.useState<string | null>(null);
+
+  // A stand-in for the chat API: the message reaches the server after a moment.
+  const deliver = ({ text }: { text: string }) =>
+    new Promise<void>((resolve) =>
+      window.setTimeout(() => {
+        setSent(text);
+        resolve();
+      }, SEND_MS),
+    );
+
+  return (
+    <div className={styles.chat}>
+      <Message.Root value="bot-menu" time="09:14">
+        <Message.Author>Бот отдела продаж</Message.Author>
+        <Message.Text>Здравствуйте! Выберите раздел на клавиатуре ниже.</Message.Text>
+      </Message.Root>
+      {sent ? (
+        <Message.Root value="answer" direction="outgoing" time="09:15" status="read">
+          <Message.Text>{sent}</Message.Text>
+        </Message.Root>
+      ) : null}
+      <Composer.Root onSend={deliver}>
+        <Composer.Keyboard rows={BOT_KEYS} placeholder="Выберите раздел" oneTime />
+      </Composer.Root>
+    </div>
+  );
+}

package/src/components/confirm-dialog/COMPONENT.md

@@ -134,5 +134,5 @@ The dialog is a Modal `s` with the floating surface, a header and a footer; ther
 - `tone="accent"` for a delete → destructive is always `danger`.
 
 ## Related
-- **Built from:** the dialog Modal stands on (`internal/overlay/ModalDialog` at `s`, the header, body and footer of `internal/overlay/DialogParts`), [ScrollContainer](../scroll-container/COMPONENT.md) (the body), [Avatar](../avatar/COMPONENT.md) and [Thumbnail](../thumbnail/COMPONENT.md) (pictures the shared icon slot recognises), [Skeleton](../skeleton/COMPONENT.md) (the shared description's loading line), [Button](../button/COMPONENT.md) (Cancel, the confirm with `loading`), [Banner](../banner/COMPONENT.md) (the failure message), `Icon` (`status.danger` in the Banner)
+- **Built from:** the dialog Modal stands on (`internal/overlay/ModalDialog` at `s`, the header, body and footer of `internal/overlay/DialogParts`), [ScrollContainer](../scroll-container/COMPONENT.md) (the body), `internal/mediaSlot` (the shared icon slot that recognises a picture), [Skeleton](../skeleton/COMPONENT.md) (the shared description's loading line), [Button](../button/COMPONENT.md) (Cancel, the confirm with `loading`), [Banner](../banner/COMPONENT.md) (the failure message), `Icon` (`status.danger` in the Banner)
 - **See also:** [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), [Notification](../notification/COMPONENT.md)

package/src/components/crossfade/COMPONENT.md

@@ -3,11 +3,14 @@
 **Category:** status
 **Kind:** layout
 
-> A region that cross-fades between its states (loading → data → empty → error) and glides to the new height, so the page below does not jump.
+> A region that cross-fades between its states (loading → data → empty → error): the data replaces the loading skeleton in place, settled states glide to the new height, so the page below does not jump.
 
 Continuous state change is a foundation of the kit (foundation §1 rule 7): a region never flips from
-one state to another. Crossfade is the mechanic for regions; its loading state is a
-[Skeleton](../skeleton/COMPONENT.md) in the shape of the coming content.
+one state to another, and nothing that loads unfolds. Crossfade is the mechanic for regions; its
+loading state is the state `"loading"`, a [Skeleton](../skeleton/COMPONENT.md) in the shape of the
+coming content from the first render, which the data replaces in place — a short fade, the height
+settled in one frame. Only a swap between settled states (data, empty, error, another record)
+glides the height.
 
 ## When to use
 - A card, panel or page region that switches between loading, data, empty and error states of its own content — every such region, not only the prominent ones.
@@ -40,11 +43,11 @@ Crossfade          <div>; holds the region's height while it changes
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Crossfade
-`ref` → `HTMLDivElement`. A region that cross-fades its content when `state` changes and glides to the new height; still on the first render. Under reduced motion the old content goes at once and the height jumps; the new content still fades in.
+`ref` → `HTMLDivElement`. A region that cross-fades its content when `state` changes and, between settled states, glides to the new height; still on the first render. Under reduced motion the old content goes at once and the height jumps.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `state` | `string \| number` | — (required) | Key of what the region shows: `"loading"`, `"ready"`, `"empty"`, `"error"` or a record id. A new value cross-fades the old content into the new one; the same value updates in place. |
+| `state` | `string \| number` | — (required) | Key of what the region shows: `"loading"`, `"ready"`, `"empty"`, `"error"` or a record id. A new value cross-fades; the same one updates in place. A swap into or out of `"loading"` never glides the height. |
 | `fill` | `boolean` | `false` | The region takes its parent's height (a flex or grid item, or a sized block) and every state stretches to it; the height never glides. A `Crossfade` that is the child of a `Page.Cell` fills it unless `fill` is set. |
 | `children` | `ReactNode` | — | Content of the current `state`. Nothing (`null`, `false`) leaves no box once the old state has faded: no gap in a grid or a flex column. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `aria-busy`, `aria-live`, `role` and the other div attributes. |
@@ -60,7 +63,8 @@ Crossfade has no variants: one treatment, keyed by `state`.
 ### state
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| a status (`"loading"`, `"ready"`, `"empty"`, `"error"`) | the old content fades out over the new one fading in; the height glides | a region's screen states | — |
+| `"loading"` | the Skeleton; entering or leaving it the content swaps in place with a short fade (`fast`), the height settles at once | the region waits for its data | — |
+| a settled status (`"ready"`, `"empty"`, `"error"`) | the old content fades out over the new one fading in; the height glides | a region's screen states | — |
 | a record id | the same cross-fade between two records | a detail panel showing one record at a time | — |
 | the same value with new children | updated in place, no motion | data refreshes inside one state | — |
 
@@ -68,8 +72,9 @@ Crossfade has no variants: one treatment, keyed by `state`.
 | State | Driven by | DOM |
 |---|---|---|
 | first render | mount | one layer, `data-state="open"`, no motion |
-| swapping | `state` changes | previous layer `data-state="closed"`, `aria-hidden`, `inert`, absolutely placed, fades out over `fast` with `exit` easing and unmounts on `animationend` (timeout fallback); the new layer fades in over `base` with `enter` easing |
-| resizing | the new state has another height | root `data-resizing="true"`: height glides from the old to the new value over `base` with `standard` easing (a swap mid-glide starts from the height on screen), clipped with a `--prime-focus-space` margin, then returns to `auto` |
+| swapping | `state` changes | previous layer `data-state="closed"`, `aria-hidden`, `inert`, absolutely placed, fades out over `fast` with `exit` easing and unmounts on `animationend` (timeout fallback), clipped to the root while it leaves (`data-leaving="true"`); the new layer fades in over `base` with `enter` easing |
+| loading swap | `state` changes into or out of `"loading"` | as swapping, but the new layer fades in over `fast` and the root takes the new height at once (no `data-resizing`) |
+| resizing | a swap between settled states, the new one of another height | root `data-resizing="true"`: height glides from the old to the new value over `base` with `standard` easing (a swap mid-glide starts from the height on screen), clipped with a `--prime-focus-space` margin, then returns to `auto` |
 | reduced motion | `prefers-reduced-motion: reduce` | the old layer goes before it is painted and the height does not glide; the new layer still fades in (the fade clock, foundation §7 rule 12) |
 | focus handoff | focus was in the old state when `state` changed | focus moves into the new layer: its first tab stop, else the layer itself (`tabindex="-1"`); focus elsewhere stays |
 | empty | the current state renders nothing (`null`, `false`, `""`) | no current layer; once nothing is leaving the root is `:empty` and `display: none` — no box and no gap in its grid or flex parent |
@@ -79,9 +84,9 @@ Motion is opacity only, so nothing shifts under the pointer; the leaving content
 
 ## Layout & spacing
 - No padding, gap or fill of its own: it sits where the swapped content would sit (inside `Card.Body`, a page section, a panel).
-- Width follows the parent; height is the current content's height except while gliding — or, with `fill`, the parent's height (the parent needs one: a flex or grid column with a height, `Page.Root fill`).
+- Width spans the parent's inline size, also as the item of a centring grid (`place-items: center`): shrunk to its content there, a child that is an inline-size container (a Card, a LoginForm) would collapse. Inside a centring flex column give it `align-self: stretch` through `className`. Height is the current content's height except while gliding — or, with `fill`, the parent's height (the parent needs one: a flex or grid column with a height, `Page.Root fill`).
 - An empty Crossfade has no box: an optional block above a list keeps the page rhythm whether it is there or not.
-- The loading state is a `Skeleton` with the geometry of the data it stands for (same rows, same line heights), so the swap to data changes neither layout nor height.
+- The loading state is a `Skeleton` with the geometry of the data it stands for (same rows, same line heights), so the swap to data changes neither layout nor height. The swap out of `"loading"` never glides, so a skeleton of another height shows as a jump.
 
 ## Accessibility
 
@@ -118,6 +123,9 @@ No `labels`.
 - Hand-written `opacity` transitions or `height` animations for a state swap → Crossfade owns both, with tokens and reduced motion.
 - An effect that moves focus out of a state that is going away (the retry button of an error) → Crossfade hands focus to the new state itself.
 - `height: 100%` on the content of a full-height region → `fill` on the Crossfade; its layers stretch.
+- `fill` around a card on a full-screen canvas (a sign-in page) → the card stretches to the canvas height; leave `fill` off and put the Crossfade around the card inside the canvas.
+- A loading state that renders nothing (`{loading ? null : <List />}`) → the region grows from zero when the data arrives; content that mounts already loaded appears in place, and a loading state is a `Skeleton` in the data's geometry.
+- A loading state under another key (`"pending"`, `"fetching"`) → the swap to data glides the height as if it were a settled state; name it `"loading"`.
 - Rendering an optional block conditionally outside Crossfade (`{notice && <Banner />}`) → it pops in and out; keep the Crossfade and pass `null` when there is nothing to show.
 
 ## Related