prime-ui-kit 0.11.1 → 0.13.0

package/dist/skill/reference/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/dist/skill/reference/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>
+  );
+}

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

@@ -5,6 +5,18 @@
   width: min(100%, var(--prime-modal-width-s));
 }
 
+/* compact: a client list, the name and its trend on one line per client. */
+.list {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(var(--prime-space-24), 1fr);
+  align-items: center;
+  gap: var(--prime-space-3) var(--prime-space-4);
+}
+
+.listRow {
+  display: contents;
+}
+
 /* The period switch above the chart inside the card body. */
 .body {
   display: flex;

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

@@ -9,6 +9,7 @@
 - Free-form text longer than one line: comments, descriptions, reviews, support requests, notes.
 - A plain growing input (`rows={1} maxRows={8}`) when a full chat composer with attachments, reply and voice is not needed.
 - Text with a length limit shown to the user (`Textarea.Counter`).
+- Text that is later shown with its Markdown (an announcement, a comment, a task description): `formatting` adds the toolbar and hotkeys Composer has.
 
 ## When not to use
 - A single-line value (name, e-mail, search) → use [Input](../input/COMPONENT.md).
@@ -26,6 +27,7 @@ import { Textarea } from "prime-ui-kit";
 Textarea.Root       label row → field box with the native <textarea> → support row (hint | error · counter)
 ├─ Textarea.CopyButton   children: copies the text from the top end corner (kit-rendered)
 └─ Textarea.Action       children: the consumer's named icon action with a tooltip (button or asChild link)
+(toolbar)           with `formatting`: floating role="toolbar" over a selection — 7 ghost Buttons with Tooltip + Kbd
 Textarea.Counter    goes into Textarea.Root `counter` (right side of the support row)
 ```
 Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the whole field and takes native `<textarea>` props directly. Its children are only the corner actions: they sit in the top end corner as full-height segments flush with the box edges, in JSX order, after the commit status of `onCommit`.
@@ -56,6 +58,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `id` | `string` | — | Id of the `<textarea>` (auto-generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
 | `aria-describedby` | `string` | — | Merged before the hint/error ids. |
 | `onCommit` | `(value: string) => void \| Promise<void>` | — | Inline save: fires with a changed value on blur and Mod+Enter; Escape reverts. Return a Promise: the field shows a spinner and stays editable; a rejection restores the value — show why through `error`. |
+| `formatting` | `boolean` | `false` | Selecting text shows a floating toolbar of seven Markdown tools and enables their hotkeys; a tool wraps the selection, a second press unwraps it. Off: plain text. |
 | `children` | `ReactNode` | — | Actions in the field's top end corner: `Textarea.CopyButton`, `Textarea.Action`. |
 | `labels` | `Partial<TextareaLabels>` | — | Built-in strings, see Labels. |
 | `className` | `string` | — | Class on the field frame `<div>` (label, field box, support row), as on every field root. |
@@ -112,6 +115,7 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `focusRing={false}` | No focus ring; focus fill and caret remain | A single composer field where focus is obvious | `true` |
+| `formatting` | A floating toolbar over a selection (bold, italic, strikethrough, code, spoiler, link, quote) and the Mod-hotkeys; each writes Markdown around the selection | The text is shown later with its Markdown (Message renders the same subset) | `false` |
 | `reserveSupportRow` | Empty support row of hint height | Live validation, fields side by side | `false` |
 | `required` / `optional` | Red `*` / muted «необязательно» after the label | Mark the minority of the form | — / `false` |
 
@@ -135,6 +139,7 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 | saving | `onCommit` returned a pending Promise | `aria-busy="true"` on the textarea, a `Spinner` in the top end corner (`data-commit="pending"`); the field stays editable; a live region says `labels.saving` |
 | saved | the Promise resolved (or `onCommit` returned nothing) | the spinner cross-fades into a success check (`data-commit="saved"`) that fades out; the live region says `labels.saved` |
 | save refused | the Promise rejected | the committed text is put back (unless the person typed on); the owner shows why through `error` |
+| selection | `formatting` and a non-empty selection while the focus is in the field or its toolbar (not disabled or read-only) | the floating toolbar fades in from below above the field's start edge (`overlayMotion` floating, `data-side="top"`); a tool wraps the selection in its Markdown, a second press removes it; the edit is typed into the field, so `Mod+Z` takes it back |
 | copied | `Textarea.CopyButton` pressed | the copy glyph cross-fades into a check, the name becomes `labels.copied` (or `labels.copyError`) |
 
 Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+Enter (Ctrl or ⌘ with Enter — a plain Enter is a line break) commit a changed text, Escape puts the committed text back and is consumed. An unchanged text never fires. Return a Promise for a server save: pending shows a spinner while the field stays editable and Tab moves on, reject restores the text, resolve shows the check.
@@ -146,6 +151,7 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 - Field → field in a form: `--prime-space-5`; group → actions: `--prime-space-8`.
 - Width is always `100%` of the parent; set the width with the layout column.
 - Long words wrap (`overflow-wrap: anywhere`), so the field never overflows horizontally.
+- With `formatting` the toolbar floats `--prime-space-2` above the field box's start edge on the floating layer, over whatever is above the field; it takes no room in the layout.
 
 ## Accessibility
 
@@ -154,7 +160,10 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 |---|---|
 | `Tab` | Focuses the field, then the buttons in its corner; Enter inserts a line break instead of submitting the form. |
 | `Mod+Enter` | With `onCommit`: saves a changed text; focus stays in the field. |
-| `Escape` | With `onCommit`: puts the committed text back. |
+| `Escape` | With `formatting`: first clears a selection with the toolbar. With `onCommit`: puts the committed text back. |
+| `Mod + B` · `Mod + I` · `Mod + Shift + X` · `Mod + E` · `Mod + Shift + H` · `Mod + K` · `Mod + Shift + 9` | With `formatting`: bold, italic, strikethrough, code, spoiler, link and quote for the selection; the physical key counts, so any layout works. |
+| `←` · `→` | Move between the formatting buttons. |
+| `Home` · `End` | Jump to the first / last formatting button. |
 
 ### ARIA
 - `label` renders `<label htmlFor>` bound to the textarea; without it set `aria-label`. A placeholder never replaces the label.
@@ -163,6 +172,7 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 - `Textarea.Counter` shows `12/280` visually and announces `labels.counter` (`aria-live="polite"`).
 - `Textarea.Action` and `Textarea.CopyButton` are buttons (or a link with `asChild`) named by their label, with a tooltip; copying announces `labels.copied`. A press on them never moves focus into the textarea.
 - With `onCommit` the textarea carries `aria-busy="true"` while saving; a polite live region says `labels.saving`, then `labels.saved`.
+- The formatting toolbar is `role="toolbar"` named `labels.formatting`, `aria-controls` the textarea, with one Tab stop and arrow keys; every button has `aria-keyshortcuts` and a tooltip with its keys (`⌘B` on Apple systems, `Ctrl+B` elsewhere). A press on a tool keeps the focus and the selection in the field.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -176,6 +186,14 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 | `copyError` | `"Не удалось скопировать"` | Name, tooltip and announcement when the clipboard refuses. |
 | `saving` | `"Сохранение"` | Announced while an `onCommit` save is pending. |
 | `saved` | `"Сохранено"` | Announced once an `onCommit` save succeeds. |
+| `formatting` | `"Форматирование"` | Accessible name of the formatting toolbar. |
+| `bold` | `"Жирный"` | Bold tool. |
+| `italic` | `"Курсив"` | Italic tool. |
+| `strikethrough` | `"Зачёркнутый"` | Strikethrough tool. |
+| `code` | `"Моноширинный"` | Code tool. |
+| `spoiler` | `"Скрытый текст"` | Spoiler tool (`\|\|…\|\|`). |
+| `link` | `"Ссылка"` | Link tool. |
+| `quote` | `"Цитата"` | Quote tool. |
 
 ## Examples
 | Example | Shows |
@@ -188,6 +206,7 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 | [without-focus-ring.tsx](examples/without-focus-ring.tsx) | A single reply composer where the caret and the lighter fill show focus — `focusRing`. |
 | [edge-actions.tsx](examples/edge-actions.tsx) | A read-only generated reply with copying and a link to the template in the field's corner — `Textarea.CopyButton`, `Textarea.Action`. |
 | [inline-edit.tsx](examples/inline-edit.tsx) | A record card note that saves on blur and Mod+Enter, reverts on Escape and shows the server's refusal — `onCommit`, `error`. |
+| [formatting.tsx](examples/formatting.tsx) | A long announcement where a selection gets the formatting toolbar and its hotkeys, written as Markdown around it — `formatting`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the text; the counter follows it and `maxLength` stops extra input — `value`, `onValueChange`, `Textarea.Counter`, `maxLength`. |
 | [in-form.tsx](examples/in-form.tsx) | Support request form: the description is checked on submit, its error leaves as soon as the text is long enough and does not shift the form, a sent request turns the button green — `required`, `error`, `reserveSupportRow`. |
 
@@ -200,7 +219,8 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 - Only a placeholder, no label → add `label` or `aria-label`.
 - A copy `Button` under a read-only result → `Textarea.CopyButton` as a child of the root.
 - Other children than `Textarea.CopyButton` / `Textarea.Action` → the root renders the textarea itself; children are only the corner actions.
+- `formatting` on text that is shown as plain text → the reader sees `**` and `||`; turn it on only where the text is rendered with its Markdown.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (corner actions), [Spinner](../spinner/COMPONENT.md) (`onCommit`)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (corner actions, formatting tools), [Spinner](../spinner/COMPONENT.md) (`onCommit`), [Button](../button/COMPONENT.md) and [Kbd](../kbd/COMPONENT.md) (formatting tools), Icon (`format.*`); `internal/textFormatting` + `internal/textFormattingToolbar` (the formatting shared with Composer)
 - **See also:** [Input](../input/COMPONENT.md) — the same field contract for one line; [Composer](../composer/COMPONENT.md) — a chat message input built on Textarea; [CodeBlock](../code-block/COMPONENT.md)

package/dist/skill/reference/components/textarea/examples/formatting.tsx

@@ -0,0 +1,20 @@
+/** A long announcement where a selection gets the formatting toolbar and its hotkeys, written as Markdown around it — `formatting`. */
+import { Textarea } from "prime-ui-kit";
+
+const ANNOUNCEMENT = `С понедельника счета клиентам выставляет **отдел расчётов**, а не менеджеры проектов.
+
+> Счёт уходит в течение _одного рабочего дня_ после подписания акта.
+
+Шаблон договора — [в базе знаний](https://prime.app/kb/contracts). Пароль от архива актов: ||Prime-2048||. Старый процесс ~~через почту~~ отключаем 1 апреля.`;
+
+export default function TextareaFormattingExample() {
+  return (
+    <Textarea.Root
+      label="Текст публикации"
+      hint="Выделите текст, чтобы оформить его; публикация покажет оформление"
+      defaultValue={ANNOUNCEMENT}
+      rows={6}
+      formatting
+    />
+  );
+}

package/dist/skill/reference/components/visually-hidden/COMPONENT.md

@@ -36,7 +36,8 @@ VisuallyHidden    <span>: out of sight (1px, clipped), pinned to its containing
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — | The text to read. |
-| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `id` (to point `aria-describedby` at it), `role="status"` with `aria-live` for an announcement, `className` and the other span attributes. |
+| `live` | `"polite" \| "assertive"` | — | An announcement region, read as a whole on every change: `polite` — `role="status"`, `assertive` — `role="alert"` (urgent only). |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `id` (to point `aria-describedby` at it), `className` and the other span attributes. |
 
 ## Variants
 One look: none. It renders no pixels and takes no room.
@@ -45,7 +46,7 @@ One look: none. It renders no pixels and takes no room.
 | State | Driven by | DOM |
 |---|---|---|
 | hidden text | children | a clipped `<span>` |
-| live region | `role="status"` + `aria-live="polite"` | read when its text changes; mount it empty first, then set the message |
+| live region | `live="polite"` (`"assertive"` for an urgent one) | `role="status"` (`"alert"`), `aria-live`, `aria-atomic`: read as a whole when its text changes; mount it empty first, then set the message |
 
 ## Layout & spacing
 - Takes no room and never scrolls its column: it is pinned to the start of the nearest positioned ancestor.
@@ -58,7 +59,7 @@ No keyboard interaction.
 
 ### ARIA
 - The text stays in the accessibility tree: it joins the accessible name of the element around it.
-- With `role="status"` it is a polite live region; keep it mounted and change its text — a region mounted together with its message is often not read.
+- With `live="polite"` it is a polite live region (`role="status"`), with `live="assertive"` an alert (`role="alert"`) for what cannot wait; keep it mounted and change its text — a region mounted together with its message is often not read.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -73,6 +74,8 @@ No `labels`.
 ## Mistakes
 - `display: none` or `hidden` for screen-reader text → both remove it from the accessibility tree.
 - A live region mounted with its first message → mount it empty, then set the text.
+- `role="status"` and `aria-live` written by hand → `live="polite"` sets them together, atomic.
+- `live="assertive"` for a routine result («Сохранено») → it interrupts the reader; keep it for errors that block.
 - VisuallyHidden as the only name of a button that has `aria-label` → the `aria-label` wins; use one of them.
 - Hidden text that repeats the visible label → screen readers read it twice.
 

package/dist/skill/reference/components/visually-hidden/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** A count that sighted users read from the layout, said in words to screen readers, and a polite announcement after an action — `VisuallyHidden`. */
+/** A count that sighted users read from the layout, said in words to screen readers, and a polite announcement after an action — `VisuallyHidden`, `live`. */
 import { Badge, Button, Typography, VisuallyHidden } from "prime-ui-kit";
 import * as React from "react";
 
@@ -14,7 +14,7 @@ export default function VisuallyHiddenOverviewExample() {
       <Button.Root variant="soft" tone="neutral" onClick={() => setArchived((count) => count + 1)}>
         В архив
       </Button.Root>
-      <VisuallyHidden role="status" aria-live="polite">
+      <VisuallyHidden live="polite">
         {archived > 0 ? `Счетов в архиве: ${archived}` : ""}
       </VisuallyHidden>
     </>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "packageManager": "bun@1.3.13",
-  "description": "React 19 UI kit for product interfaces: 77 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
+  "description": "React 19 UI kit for product interfaces: 79 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
   "bin": {
     "prime-ui-kit": "bin/prime-ui-kit.js"
   },

package/src/components/chat/COMPONENT.md

@@ -25,7 +25,7 @@ import { Chat, Composer, Message, groupMessages, formatMessageDate, hueOf } from
 ```
 Chat.Root                         <div> column, fills its host; owns selection, search, typing, jumps
 ├─ Chat.Header                    grid: lead · title over description · actions
-│  ├─ [Avatar]                    any other child leads the row
+│  ├─ [lead]                      every other child (a back button, an Avatar), side by side
 │  ├─ Chat.Title                  <h2>, names the list (aria-labelledby)
 │  ├─ Chat.Description            status line, cross-fades into «печатает…» while `typing`
 │  └─ Chat.Actions                a call, a Dropdown of more
@@ -33,6 +33,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 ├─ Chat.Search                    while the search is open: field · «2 из 5» · older · newer
 ├─ Chat.Pinned                    rail · pin · title over one line · unpin; a press jumps to the message
 ├─ Chat.Messages                  the scroller (anchor="end") and the list: role="log" (a listbox while selecting)
+│  ├─ [first-load placeholders]   Skeleton bubbles on both sides in the list's place while `loading`
 │  ├─ [older placeholder]         a Skeleton bubble above the first message while `hasOlder`
 │  ├─ Chat.Separator              a date pill, sticky at the top of its day (from `items`, or yours)
 │  ├─ Chat.Service                an event of the chat, centered pill
@@ -102,11 +103,11 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">` | — | `className` and the other attributes of the frame. |
 
 ### Chat.Header
-`ref` → `HTMLDivElement`. The top of the chat: who it is with. A row of the leading element (an `Avatar`), the title over the description, and the actions at the end; anything that is not a title, a description or actions leads the row.
+`ref` → `HTMLDivElement`. The top of the chat: who it is with. The title over the description and the actions at the end; every other child (a back button, an `Avatar`) leads the row, side by side in the order written.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (an `Avatar`, `Chat.Title`, `Chat.Description`, `Chat.Actions`), `className`. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (a `PageContent.BackButton`, an `Avatar`, `Chat.Title`, `Chat.Description`, `Chat.Actions`), `className`. |
 
 ### Chat.Title
 `ref` → `HTMLHeadingElement`. Who the chat is with, one line that ellipsizes; it also names the message list (`aria-labelledby`).
@@ -174,6 +175,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `groupWindow` | `number` | `5` | Messages of one author further apart than this many minutes start a new run. |
 | `now` | `Date` | `new Date()` | «Today» for the dates. |
 | `formatDate` | `(date: Date, now: Date) => string` | `formatMessageDate` | The label of a date. |
+| `loading` | `boolean` | `false` | The first load: bubble-shaped `Skeleton`s on both sides stand in the list's place (`aria-busy`, `labels.loading` announced), then cross-fade into the messages; none of them counts as new. |
 | `hasOlder` | `boolean` | `false` | Older history exists: a bubble-shaped placeholder stands above the first message and `onLoadOlder` runs when the reader reaches the top. |
 | `onLoadOlder` | `() => void \| Promise<void>` | — | Load older messages and prepend them (while `hasOlder`); the reader's place is kept. |
 | `quickReaction` | `string \| false` | `«👍»` | The reaction of a double tap (and `L`) on a message: puts it or takes it back through `onReactionToggle`. `false` — off. |
@@ -231,6 +233,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | Prop | Effect |
 |---|---|
 | `Chat.Root typing` | the description turns into «печатает…» and the list ends with the typing bubble |
+| `Chat.Messages loading` | the first load: bubble-shaped placeholders in the list's place, cross-fading into the messages |
 | `Chat.Messages hasOlder` | a placeholder above the first message; `onLoadOlder` at the top |
 | `Chat.Messages quickReaction` | the emoji of a double tap and `L` (default «👍», `false` — off); a double click that selected text puts none, and selection mode adds nothing |
 | `Chat.Messages reactionOptions` | the reactions of the reaction bar, seven in its row, the rest glide open behind «⌄»; the bar floats above the message on a long press (with the menu), after a long hover on pointer devices (~500 ms, the bar alone) or on `R` |
@@ -243,6 +246,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | new, theirs | an incoming message added at the end | `data-enter="incoming"`: the same float-up and fade; scrolled away, the «к последним» button counts it. Arriving with the end of the typing, it takes the typing's place — the typing goes at once |
 | not new | the first render, history prepended, a message put back in the middle, a row the window renders as it scrolls into view, a status or text change | nothing moves. Reduced motion makes every enter instant |
 | away from the end | the reader scrolled up | a round soft «к последним» button at the bottom-end, rising in (`fast`); a `Badge` counts incoming messages that came meanwhile; a press glides to the end — from far away it lands one view before the end first — and stops when the reader scrolls; at the end it leaves and the count resets |
+| first load | `Chat.Messages loading` | the messages' region is `aria-busy`: six `Skeleton` bubbles in the message geometry (the bubble's radius, one or two lines of body text in its padding, widths within its cap), on alternating sides at the end of the list, a group chat's incoming ones beside a circle in the avatar's gutter; `labels.loading` is announced politely. When it ends they cross-fade into the list (`Crossfade`: the new state in `base`, the placeholders out in `fast`); the list mounts then, so what it shows is its first render — nothing enters, nothing is reported new |
 | older history | `hasOlder` | a bubble-shaped `Skeleton` above the first message; reaching it calls `onLoadOlder`; the rows that arrive above keep the reader's place |
 | jumped to | `Message.Reply target`, `Chat.Pinned`, `current` | the list brings the message to the middle (a near one glides, a far one lands at once — rendering it first — and settles once its neighbours have laid out); nothing is drawn on it: every other message steps back and comes forward three times (opacity 1 → `--prime-message-dim-opacity` → 1, `base` each) — `data-pointing="a"` / `"b"` on the list, flipped on every jump so a repeated jump restarts it, and `data-pointed` on the message; a reply's target also takes the focus, a `current` change leaves it where it is. While the search is open its current match takes the place of `current`. Reduced motion: the others stand back for a moment, no blink |
 | search | `search` (the bar open) | every case-insensitive match in the messages' text and transcripts under a soft accent wash (`<mark>`); the newest match is current: brought into view while the others stay back (`data-pointing="current"`); Enter and the older / newer buttons move the full strength to the older or newer match in one step; «2 из 5» or «Нет совпадений» beside the field |
@@ -252,6 +256,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 
 ## Layout & spacing
 - `Chat.Root` is a column that fills its host's height (`block-size: 100%`, a flex item that grows): give the host a height — a `Card` sized by the page, a page pane, the viewport. Only `Chat.Messages` grows and scrolls; the header, the search, the pinned bar and the footer keep their height.
+- The header sorts its children by type: `Chat.Title`, `Chat.Description` and `Chat.Actions` take their places, every other child (fragments opened) goes into the lead, a row centred with `space-2` between its items — a back button and an avatar stand side by side; without them the text starts the row.
 - The header: `space-3` top and end, `space-2` bottom, `space-4` start; `space-3` between its columns; the title `title-s` on one line that ellipsizes, the description a muted caption; the actions keep their width, so at 320px the title gives way.
 - The search bar and the pinned bar stand under the header with `space-3` side padding; the footer pads the Composer by `space-2` / `space-3`.
 - The list pads its own sides (`space-2`), so the focus rings of the bubbles fit; every row is a container: a bubble is at most `--prime-message-max-width` and 85% of the chat.
@@ -282,6 +287,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 - `Chat.SelectionBar` is a `toolbar` named by the count «Выбрано: N», which is announced politely as it changes.
 - The quick reaction (double tap, `L`) is announced politely.
 - «Печатает…» in the header is visible text; in the list the typing bubble is a polite `status` «Собеседник печатает».
+- While `loading` the messages' region is `aria-busy`, the placeholders are `aria-hidden`, and «Загрузка сообщений» (`labels.loading`) is announced politely.
 - A message reached by a jump or the current search match is not announced as such: a reply's target takes the focus, a search keeps it in its field; the others stepping back is visual only.
 
 ### Labels
@@ -305,6 +311,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `pinnedOf` | `"Закреплённое {index} из {count}"` | `Chat.Pinned labels`: the title with several, the newest last. |
 | `unpin` | `"Открепить"` | `Chat.Pinned labels`: the name of the unpin button. |
 | `unread` | `"Непрочитанные сообщения"` | The text of the «unread» band: `Chat.Root labels` for rows from `items`, `Chat.Unread labels` for a hand-placed band. |
+| `loading` | `"Загрузка сообщений"` | Announced politely while the conversation loads for the first time (`Chat.Messages loading`). |
 
 ## Examples
 | Example | Shows |
@@ -314,11 +321,13 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | [group-chat.tsx](examples/group-chat.tsx) | A team chat from data: the first message of an author's run opens with the name in the author's hue, a crown for the owner and the member's tag; the avatar — a photo, or initials — closes the run; a direct chat shows neither — `type`, `items`, `renderMessage`, `Message.Author`, `tag`, `Message.AuthorIcon`, `hueOf`. |
 | [live.tsx](examples/live.tsx) | A live support chat: the client types — the header and the end of the list say so — then answers; new messages enter at the end, read receipts come from what is on screen, and scrolled up the round button counts what arrived — `typing`, `onNewMessage`, `onRead`. |
 | [search.tsx](examples/search.tsx) | Search and pinned messages: the search bar marks every match in the texts and transcripts, counts them and steps between them while the others step back; a pinned message's press jumps to it and blinks the others — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. |
+| [states.tsx](examples/states.tsx) | The first load of a conversation: bubble-shaped placeholders on both sides stand in the list's place, then cross-fade into the messages — `loading`. |
 | [controlled.tsx](examples/controlled.tsx) | Selection mode owned by the screen: the Select item of a message's menu starts it, a check stands beside every message, a press toggles one while the others step back, the bar counts and acts, Escape leaves — `selected`, `onSelectedChange`, `Chat.SelectionBar`. |
 | [narrow.tsx](examples/narrow.tsx) | At phone width the header keeps its actions and lets the title ellipsize, bubbles take up to 85% of the chat, long links wrap and an album keeps its layout — `Chat.Root`, `Chat.Header`, `Chat.Messages`, `Chat.Footer`. |
 
 ## Mistakes
 - A header, a search bar and a scroller of your own around the messages → `Chat.Header`, `Chat.Search`, `Chat.Messages`: the chat wires typing, search, jumps and selection between them.
+- A spinner or grey boxes of your own while a dialog loads → `Chat.Messages loading`: bubbles in the messages' geometry that cross-fade into the list.
 - A `ScrollContainer` or a virtualizing list of your own around messages → `Chat.Messages` scrolls itself and renders a window, keeping the reader's place.
 - Dates, runs and the unread band built by hand → `Chat.Messages items` with `getKey`, `getAuthor`, `getDate`; `groupMessages` if you build rows yourself.
 - An inline `renderMessage` in a long history → wrap it in `useCallback`: a new function renders every item again.
@@ -332,5 +341,5 @@ Chat.Root                         <div> column, fills its host; owns selection,
 - Checkboxes and selection handling of your own → `Chat.Root selected` with `Chat.SelectionBar`: click, Shift range and drag like DataTable rows.
 
 ## Related
-- **Built from:** [Message](../message/COMPONENT.md) (`Message.Typing`, the rows), [ScrollContainer](../scroll-container/COMPONENT.md) (the scroller, `anchor="end"`), [Input](../input/COMPONENT.md) (the search field), [Button](../button/COMPONENT.md) (search, steps, unpin, «к последним», the selection bar), [Badge](../badge/COMPONENT.md), [Crossfade](../crossfade/COMPONENT.md) (the status line), [Skeleton](../skeleton/COMPONENT.md) (older history), Icon (`action.search`, `nav.chevronUp`, `nav.chevronDown`, `action.pin`, `action.close`); `useVirtualRows` (the window), `internal/messageList` (the contract between the list and its messages), `internal/readReceipts`, `internal/useRangeSelection` (selection by click, Shift and drag), `internal/messagePart` (the search query its texts mark)
+- **Built from:** [Message](../message/COMPONENT.md) (`Message.Typing`, the rows), [ScrollContainer](../scroll-container/COMPONENT.md) (the scroller, `anchor="end"`), [Input](../input/COMPONENT.md) (the search field), [Button](../button/COMPONENT.md) (search, steps, unpin, «к последним», the selection bar), [Badge](../badge/COMPONENT.md), [Crossfade](../crossfade/COMPONENT.md) (the status line, the first load), [Skeleton](../skeleton/COMPONENT.md) (the first load, older history), `internal/VisuallyHidden` (the loading announcement), Icon (`action.search`, `nav.chevronUp`, `nav.chevronDown`, `action.pin`, `action.close`); `useVirtualRows` (the window), `internal/messageList` (the contract between the list and its messages), `internal/readReceipts`, `internal/useRangeSelection` (selection by click, Shift and drag), `internal/messagePart` (the search query its texts mark)
 - **See also:** [Message](../message/COMPONENT.md) — one message and every content part; [Composer](../composer/COMPONENT.md) — the input in `Chat.Footer`; [Gallery](../gallery/COMPONENT.md), [VoicePlayer](../voice-player/COMPONENT.md), [VideoNote](../video-note/COMPONENT.md), [Timeline](../timeline/COMPONENT.md)

package/src/components/chat/examples/states.tsx

@@ -0,0 +1,100 @@
+/** The first load of a conversation: bubble-shaped placeholders on both sides stand in the list's place, then cross-fade into the messages — `loading`. */
+import { Button, Card, Chat, Message } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const LOAD_MS = 1500;
+
+const MESSAGES = [
+  {
+    id: "m-a",
+    direction: "incoming",
+    time: "09:58",
+    text: "Здравствуйте! Подскажите, когда выставите счёт по договору № 118?",
+  },
+  {
+    id: "m-b",
+    direction: "outgoing",
+    time: "10:02",
+    text: "Добрый день! Счёт № 2041 уже в личном кабинете, продублировал на почту.",
+  },
+  {
+    id: "m-c",
+    direction: "incoming",
+    time: "10:03",
+    text: "Получили, передаю в бухгалтерию.",
+  },
+  {
+    id: "m-1",
+    direction: "incoming",
+    time: "10:12",
+    text: "Добрый день! Счёт № 2041 оплатили, проверьте, пожалуйста.",
+  },
+  {
+    id: "m-2",
+    direction: "outgoing",
+    time: "10:15",
+    text: "Вижу оплату, спасибо. Отгрузка — завтра до обеда.",
+  },
+  {
+    id: "m-3",
+    direction: "incoming",
+    time: "10:16",
+    text: "Отлично. Закрывающие документы пришлёте в ЭДО?",
+  },
+  {
+    id: "m-4",
+    direction: "outgoing",
+    time: "10:18",
+    text: "Да, акт и УПД уйдут вместе с отгрузкой.",
+  },
+  {
+    id: "m-5",
+    direction: "incoming",
+    time: "10:19",
+    text: "Спасибо, ждём.",
+  },
+] as const;
+
+export default function ChatStatesExample() {
+  const [loading, setLoading] = React.useState(true);
+
+  React.useEffect(() => {
+    if (!loading) return;
+    const timer = window.setTimeout(() => setLoading(false), LOAD_MS);
+    return () => window.clearTimeout(timer);
+  }, [loading]);
+
+  return (
+    <div className={styles.live}>
+      <div className={styles.liveBar}>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          disabled={loading}
+          onClick={() => setLoading(true)}
+        >
+          Открыть заново
+        </Button.Root>
+      </div>
+      <Card.Root className={styles.short}>
+        <Chat.Root>
+          <Chat.Messages aria-label="Переписка с ООО «Вектор»" loading={loading}>
+            {MESSAGES.map((message) => (
+              <Message.Root
+                key={message.id}
+                value={message.id}
+                direction={message.direction}
+                time={message.time}
+                status={message.direction === "outgoing" ? "read" : undefined}
+              >
+                <Message.Text>{message.text}</Message.Text>
+              </Message.Root>
+            ))}
+          </Chat.Messages>
+        </Chat.Root>
+      </Card.Root>
+    </div>
+  );
+}