prime-ui-kit 0.10.0 → 0.11.1

package/src/components/message/examples/status.tsx

@@ -0,0 +1,45 @@
+/** Delivery of outgoing messages: a clock while sending, one check when sent, two when read, and a failed one with a retry that resolves after a second — `status`, `onRetry`. */
+import { Message, type MessageStatus } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const STEPS: MessageStatus[] = ["sending", "sent", "read"];
+
+export default function MessageStatusExample() {
+  const [step, setStep] = React.useState(0);
+  const [failed, setFailed] = React.useState(true);
+
+  React.useEffect(() => {
+    const timer = window.setInterval(
+      () => setStep((current) => (current + 1) % STEPS.length),
+      1600,
+    );
+    return () => window.clearInterval(timer);
+  }, []);
+
+  const retry = () =>
+    new Promise<void>((resolve) => {
+      window.setTimeout(() => {
+        setFailed(false);
+        resolve();
+      }, 1000);
+    });
+
+  return (
+    <div className={styles.thread}>
+      <Message.Root direction="outgoing" position="first" time="14:20" status={STEPS[step]}>
+        <Message.Text>Акт сверки за сентябрь во вложении.</Message.Text>
+      </Message.Root>
+      <Message.Root
+        direction="outgoing"
+        position="last"
+        time="14:21"
+        status={failed ? "failed" : "sent"}
+        onRetry={retry}
+      >
+        <Message.Text>Подпишите, пожалуйста, до пятницы.</Message.Text>
+      </Message.Root>
+    </div>
+  );
+}

package/src/components/message/examples/structure.tsx

@@ -0,0 +1,32 @@
+/** Optional parts of a bubble in their order: the author, a forwarded header, a reply quote, the text and reactions — `Message.Author`, `Message.Forwarded`, `Message.Reply`, `Message.Reactions`. */
+import { Message } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const REACTIONS = [
+  { emoji: "👍", count: 3, selected: true },
+  { emoji: "🔥", count: 1 },
+];
+
+export default function MessageStructureExample() {
+  return (
+    <div className={styles.thread}>
+      <Message.Root direction="incoming" time="11:02">
+        <Message.Author color="purple">Олег Смирнов</Message.Author>
+        <Message.Text>Макет страницы заказа готов, ссылка в задаче PRJ-412.</Message.Text>
+      </Message.Root>
+      <Message.Root direction="incoming" time="11:05">
+        <Message.Author color="green">Анна Котова</Message.Author>
+        <Message.Forwarded from="Ирина Белова" />
+        <Message.Text>Клиент просит добавить в заказ поле «Номер договора».</Message.Text>
+      </Message.Root>
+      <Message.Root direction="outgoing" time="11:07" status="read">
+        <Message.Reply author="Олег Смирнов" color="purple">
+          Макет страницы заказа готов, ссылка в задаче PRJ-412.
+        </Message.Reply>
+        <Message.Text>Посмотрел — согласовано, передаю в разработку.</Message.Text>
+        <Message.Reactions items={REACTIONS} />
+      </Message.Root>
+    </div>
+  );
+}

package/src/components/message/examples/text-formatting.tsx

@@ -0,0 +1,27 @@
+/** The Markdown the Composer writes, rendered safely: bold, italic, strike, code, a code block, links and a quote; long words and URLs wrap — `Message.Text`, `edited`. */
+import { Message } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const RELEASE = `**Релиз 2.4** готов к выкатке.
+Изменения: _экспорт счетов_, ~~старый отчёт~~ удалён, флаг \`invoices.v2\`.
+> Миграцию запускать только после бэкапа.
+\`\`\`
+bun run migrate --env=prod
+\`\`\`
+Чеклист: https://prime.app/wiki/release-2-4`;
+
+export default function MessageTextFormattingExample() {
+  return (
+    <div className={styles.thread}>
+      <Message.Root direction="incoming" time="16:05">
+        <Message.Text>{RELEASE}</Message.Text>
+      </Message.Root>
+      <Message.Root direction="outgoing" time="16:07" edited status="read">
+        <Message.Text>
+          Принято, запускаю после бэкапа. Отчёт положу в [задачу](https://prime.app/t/PRJ-430).
+        </Message.Text>
+      </Message.Root>
+    </div>
+  );
+}

package/src/components/message/examples/typing.tsx

@@ -0,0 +1,22 @@
+/** The typing signal: an incoming bubble of three dots that enters like a message and leaves closing its height; switch it, keep it mounted — `Message.Typing`, `active`. */
+import { Button, Message } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function MessageTypingExample() {
+  const [active, setActive] = React.useState(true);
+  return (
+    <div className={styles.stage}>
+      <div className={styles.thread}>
+        <Message.Root time="14:02">
+          <Message.Text>Сейчас проверю остатки на складе.</Message.Text>
+        </Message.Root>
+        <Message.Typing active={active} />
+      </div>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setActive((on) => !on)}>
+        {active ? "Перестал печатать" : "Снова печатает"}
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/message/examples/voice.tsx

@@ -0,0 +1,39 @@
+/** Voice messages on their bubbles: the player keeps room for the time in the corner; a new one carries the unplayed dot until it is played — `VoicePlayer`, `unplayed`. */
+import { Message, VoicePlayer } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const AUDIO = "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3";
+
+const WAVE_IN = [
+  0.2, 0.35, 0.6, 0.8, 0.5, 0.3, 0.7, 0.9, 0.65, 0.4, 0.25, 0.55, 0.85, 0.7, 0.45, 0.3, 0.5, 0.75,
+  0.6, 0.35, 0.2, 0.4, 0.65, 0.5, 0.3,
+];
+
+const WAVE_OUT = [
+  0.3, 0.5, 0.4, 0.7, 0.9, 0.6, 0.35, 0.5, 0.8, 0.55, 0.3, 0.45, 0.7, 0.4, 0.25, 0.6, 0.8, 0.5, 0.3,
+  0.2,
+];
+
+export default function MessageVoiceExample() {
+  const [unplayed, setUnplayed] = React.useState(true);
+  return (
+    <div className={styles.thread}>
+      <Message.Root direction="incoming" time="10:41">
+        <VoicePlayer
+          src={AUDIO}
+          waveform={WAVE_IN}
+          duration={27}
+          unplayed={unplayed}
+          onPlayingChange={(playing) => {
+            if (playing) setUnplayed(false);
+          }}
+        />
+      </Message.Root>
+      <Message.Root direction="outgoing" time="10:44" status="read">
+        <VoicePlayer src={AUDIO} waveform={WAVE_OUT} duration={14} />
+      </Message.Root>
+    </div>
+  );
+}

package/src/components/modal/COMPONENT.md

@@ -6,7 +6,6 @@
 > A dialog over the page for confirmations, short forms and important text.
 
 ## When to use
-- Confirming a destructive or irreversible action.
 - A short form that must be finished or cancelled before returning to the page.
 - Important information that needs an explicit acknowledgement.
 
@@ -14,6 +13,7 @@
 - Long forms, filters or record details next to the page → use [Drawer](../drawer/COMPONENT.md).
 - A light confirm or form tied to one button, without blocking the page → use [Popover](../popover/COMPONENT.md).
 - Searching and running commands → use [CommandMenu](../command-menu/COMPONENT.md).
+- Confirming a destructive or weighty action → use [ConfirmDialog](../confirm-dialog/COMPONENT.md): the request, its pending state and its failure are built in.
 - Non-blocking status messages → use [Notification](../notification/COMPONENT.md) or [Banner](../banner/COMPONENT.md).
 
 ## Import
@@ -27,12 +27,15 @@ Modal.Root                    state and dismiss policy (no DOM)
 ├── Modal.Trigger             clones its child; opens on click
 └── Modal.Content             portal + scrim + role="dialog"
     ├── (grab handle)         below 640px only: aria-hidden bar, a drag starts here
-    ├── Modal.Header          grid: [Icon] [Title + Description] [close button]
+    ├── 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.Title       <h2>, names the dialog
-    │   └── Modal.Description <p>, describes the dialog
+    │   ├── Modal.Description <p>, describes the dialog
+    │   └── Modal.Actions     row of tier-s controls before the close button
     ├── Modal.Body            the only scrolling zone
     └── Modal.Footer          actions, primary last
+        ├── Modal.Meta        <p>, muted status at the start
         ├── Modal.Close       clones its child; closes on click
         └── Modal.Confirm     clones its child; Enter clicks it
 ```
@@ -48,20 +51,20 @@ No DOM, no ref. State and dismiss policy.
 |---|---|---|---|
 | `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
-| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. A `Guard` holds the dismisses (not code). |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the dialog. |
-| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim (and a swipe on a bottom sheet) closes the dialog; turn off for destructive confirms. |
+| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim (and a swipe down) closes the dialog; turn off for destructive confirms. |
 | `labels` | `Partial<ModalLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | Trigger and Content. |
 | `confirmOnEnter` | `boolean` | `true` | Enter inside the dialog clicks the element wrapped in `Modal.Confirm`; Enter on a button or link activates that element instead. |
 | `onEnterConfirm` | `(event: KeyboardEvent) => void` | — | Replaces the default Enter confirm. |
 
 ### Modal.Content
-`ref` → `HTMLDivElement` (the dialog panel). Portal + scrim + `role="dialog"`; renders while open and during its exit animation. Controls inside get size `m`.
+`ref` → `HTMLDivElement` (the dialog panel). Portal + scrim + `role="dialog"`; renders while open and during its exit animation, showing the children it had open (a record cleared with `open` does not empty the panel mid-motion). Controls inside get size `m`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 440 · 560 · 720 · 960. Below 640 px of viewport — a full-width bottom sheet with a grab handle; a swipe down from the handle or the header closes it. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 360 · 440 · 560 · 720 · 960. Below 640 px of viewport — a full-width bottom sheet with a grab handle; a swipe down from the handle or the header closes it. |
 | `container` | `HTMLElement \| null` | `document.body` | Portal target. |
 | `aria-label` | `string` | — | Dialog name when there is no Title. |
 | `aria-labelledby` | `string` | — | Overrides the Title id. |
@@ -70,12 +73,15 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other attributes of the `role="dialog"` element. |
 
 ### Modal.Header
-`ref` → `HTMLElement`. Renders `<header>`: [Icon] [Title + Description] [close button]. + native `HTMLAttributes<HTMLElement>`.
+`ref` → `HTMLElement`. Renders `<header>`: [Icon] [Title + Description] [Actions] [close button]. + native `HTMLAttributes<HTMLElement>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `showClose` | `boolean` | `true` | Built-in square ghost `s` close button named by `labels.close`. |
-| `children` | `ReactNode` | — | Icon, Title, Description in any order; the icon goes to the leading slot. |
+| `showClose` | `boolean` | `true` | Built-in square ghost `s` close button named by `labels.close`; disabled in place while a `Guard` is `busy`. |
+| `children` | `ReactNode` | — | Icon, Title, Description, Actions in any order; each goes to its column. A `Tabs.List` (with `Tabs.Root` around header and body) turns the header into a tab strip. |
+
+### Modal.Actions
+`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.
@@ -93,14 +99,25 @@ No DOM, no ref. State and dismiss policy.
 `ref` → `HTMLDivElement`. The only scrolling zone (a ScrollContainer), 16 gap between blocks. + native `<div>` props.
 
 ### Modal.Footer
-`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last. + native `HTMLAttributes<HTMLElement>`.
+`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last, and an optional `Meta` at the start. + native `HTMLAttributes<HTMLElement>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `layout` | `"fill" \| "end"` | `"fill" (s/m), "end" (l/xl)` | `fill`: equal-width buttons in one row; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px. |
+| `layout` | `"fill" \| "end"` | `"fill" (xs/s/m), "end" (l/xl)` | `fill`: equal-width buttons in one row; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px. |
+
+### Modal.Meta
+`ref` → `HTMLParagraphElement`. A `<p>` at the start of the footer: short muted status text («Есть несохранённые изменения»); the buttons keep their width at the end. Not part of the dialog description. + native `<p>` props.
+
+### Modal.Guard
+No DOM, no ref. Holds the dialog from anywhere inside Content, where the form state lives; renders only the built-in «discard changes?» confirm. Closing from code is never held.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `busy` | `boolean` | `false` | A request runs: Escape, a press outside, a swipe, the close button and `Close` do nothing; the close button and the `Close` child stay in place, disabled. |
+| `dirty` | `boolean` | `false` | Unsaved changes: any of those dismisses first asks «Не сохранять изменения?» (a ConfirmDialog with `labels.discard*`); confirming closes the dialog. |
 
 ### Modal.Trigger · Modal.Close · Modal.Confirm
-No DOM: clone the single child and chain its `onClick` (unless the child's handler calls `preventDefault()`).
+No DOM: clone the single child and chain its `onClick` (unless the child's handler calls `preventDefault()`). `Close` goes through a `Guard` and makes its child `disabled` while the guard is busy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -112,6 +129,7 @@ The dialog has one look: the floating layer of the ladder (`data-depth="floating
 ### size (Content)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
+| `xs` | 360 wide, equal-width footer buttons | One or two fields (rename, a code) | |
 | `s` | 440 wide, equal-width footer buttons | Confirmations | |
 | `m` | 560 wide, equal-width footer buttons | Short forms | yes |
 | `l` | 720 wide, footer buttons right-aligned | Two-column forms | |
@@ -122,10 +140,10 @@ Below 640px of viewport every size becomes a full-width bottom sheet with a grab
 ### layout (Footer)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `fill` | Equal-width buttons in one row, gap 12 | Narrow dialogs with two actions | for `s`, `m` |
+| `fill` | Equal-width buttons in one row, gap 12 | Narrow dialogs with two actions | for `xs`, `s`, `m` |
 | `end` | Auto-width buttons at the end, gap 8 | Wide dialogs | for `l`, `xl` |
 
-On phones (viewport below 640px, where the dialog is a bottom sheet) and in a dialog narrower than 360px, actions stack full width in DOM order (primary last).
+With a `Modal.Meta` the footer is a row in any layout: the status takes the free room at the start, the buttons keep their width at the end. On phones (viewport below 640px, where the dialog is a bottom sheet) and in a dialog narrower than 360px, actions stack full width in DOM order (primary last), the status above them.
 
 ### tone (Icon)
 | Value | Looks like | Use when | Default |
@@ -145,7 +163,7 @@ On phones (viewport below 640px, where the dialog is a bottom sheet) and in a di
 | Header + Footer, no Body | Hairline between them | Confirmations | |
 | Header only | Header with full bottom padding | Short notices | |
 
-**Combinations** — destructive confirm: `size="s"`, `Modal.Icon tone="danger"`, `closeOnOutsideClick={false}`, outline neutral «Отмена» in `Modal.Close`, solid `tone="danger"` action in `Modal.Confirm` with `loading` during the request.
+**Combinations** — destructive confirm: use [ConfirmDialog](../confirm-dialog/COMPONENT.md). An edit form: `Modal.Guard busy={saving} dirty={changed}`, `Modal.Meta` «Есть несохранённые изменения» while changed, the submit Button `loading` while saving.
 
 **Hierarchy** — one primary action, last in the footer and wrapped in `Modal.Confirm`; the secondary is `outline` neutral.
 
@@ -158,13 +176,19 @@ On phones (viewport below 640px, where the dialog is a bottom sheet) and in a di
 | footer layout | `layout` or the size default | `data-layout` on the footer |
 | icon tone | `tone` on Icon | `data-tone` on the tile |
 | while open | — | focus trapped inside, page scroll locked, siblings of the portal `inert` (the toast region stays usable) |
+| closing | `open` turns false | the dialog keeps showing the children it had open while the exit motion plays |
+| busy | `Modal.Guard busy` | Escape, the scrim, a swipe, the close button and `Modal.Close` do nothing; the close button and the `Close` child are `disabled` in place |
+| dirty | `Modal.Guard dirty` | a dismiss opens the «Не сохранять изменения?» ConfirmDialog (`labels.discard*`); its confirm closes the dialog; no swipe |
 | swiping | below 640px, a drag down from the handle or the header (with `closeOnOutsideClick`) | `data-swiping` and `--swipe-offset` on the dialog while the pointer drags it; past 30% of its height or on a flick it closes, otherwise it glides back |
 
 Loading or disabled actions use the Button props (`loading`, `disabled`) inside the footer.
 
+Motion (`overlayMotion`): the scrim fades in and out over `base`; the dialog fades and scales from 0.98 over `base` and leaves over `fast`; as a bottom sheet it slides up over `slow` and down over `base`. Content stays mounted until the exit ends; under `prefers-reduced-motion` it unmounts at once.
+
 ## Layout & spacing
 - Dialog padding `--prime-modal-padding` (24) on every zone; header 24 top / 20 bottom, body 20 with a 16 gap between blocks, footer 20 top / 24 bottom.
 - Max height = viewport minus `--prime-modal-viewport-padding` on both sides; only the body scrolls.
+- Tabs in the header: a `Tabs.List` inside `Modal.Header` (with `Tabs.Root` around the header and the body) spans the header's last row. The header becomes the tab strip, edge to edge and without the hairline; the active tab is the body rising into it, the panels sit in the body.
 - Fields inside take the floating layer's fill; a card inside is the next layer (`floating-1`), a flat tile. Group fields with a 20 gap.
 - Narrow viewport (< 640px): bottom sheet, full width, top corners `--prime-sheet-radius`, a grab handle strip on top, up to `100dvh − --prime-sheet-top-gap` high, the bottom safe-area inset below the content.
 
@@ -183,6 +207,7 @@ Loading or disabled actions use the Button props (`loading`, `disabled`) inside
 - The page behind is `inert` and its scroll is locked.
 - Only the topmost layer reacts: a Select open inside the dialog closes first.
 - On a narrow viewport a swipe down is an extra way out; the close button and Escape stay. A destructive confirm (`closeOnOutsideClick={false}`) does not close by swipe. The grab handle is `aria-hidden`.
+- A busy `Guard` keeps the close button and the `Close` child in place, `disabled`; a dirty one opens a `role="alertdialog"` confirm with focus on «Продолжить».
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -190,15 +215,20 @@ Loading or disabled actions use the Button props (`loading`, `disabled`) inside
 | Key | Default | Used for |
 |---|---|---|
 | `close` | `"Закрыть"` | `aria-label` of the header close button. |
+| `discardTitle` | `"Не сохранять изменения?"` | Title of the confirm a dismiss opens while a `Guard` is `dirty`. |
+| `discardDescription` | `"Изменения в форме пропадут."` | Its description. |
+| `discardConfirm` | `"Не сохранять"` | Its confirm button: close and lose the changes. |
+| `discardCancel` | `"Продолжить"` | Its cancel button: back to the form. |
 
 ## Examples
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A trigger opens a dialog with a title, a field and two actions; Enter presses the confirm — `Modal.Trigger`, `Modal.Confirm`. |
 | [structure.tsx](examples/structure.tsx) | Optional parts: an icon tile with a header-only notice, and a header with a footer but no body — `Modal.Icon`, `Modal.Body`, `Modal.Footer`. |
-| [sizes.tsx](examples/sizes.tsx) | Every width; s and m fill the footer with equal buttons, l and xl align them to the end — `size`. |
+| [sizes.tsx](examples/sizes.tsx) | Every width; xs, s and m fill the footer with equal buttons, l and xl align them to the end — `size`. |
 | [long-content.tsx](examples/long-content.tsx) | A long body scrolls on its own while the header and the footer stay in place — `Modal.Body`. |
 | [custom-container.tsx](examples/custom-container.tsx) | The dialog portals into a given node instead of the document body — `container`. |
+| [guard.tsx](examples/guard.tsx) | An edit form that holds the dialog: changes make any dismiss ask first and show a note in the footer; while saving nothing closes it — `Modal.Guard`, `Modal.Meta`. |
 | [dismiss.tsx](examples/dismiss.tsx) | A destructive confirm closes only from its buttons, and not at all while the request runs — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state and opens the dialog from code, without a trigger — `open`, `onOpenChange`. |
 | [in-form.tsx](examples/in-form.tsx) | A settings form in a dialog: the footer button submits the form and an empty name shakes the field and keeps it open until it is filled — `Modal.Body`, `Modal.Footer`, `error`. |
@@ -207,10 +237,11 @@ Loading or disabled actions use the Button props (`loading`, `disabled`) inside
 - Destructive confirm that closes on a stray scrim click → `closeOnOutsideClick={false}`.
 - Primary action not in `Modal.Confirm` → Enter does nothing; wrap it.
 - Primary action first in the footer → put it last (DOM order is the visual order).
-- `size="xs"` → not supported; sizes are `s`–`xl`.
+- Busy or unsaved state lifted out of the form into Root props → put `Modal.Guard` next to the form, inside Content.
+- `key` or a conditional around `Modal.Root` to reset a form → the dialog unmounts at once, without its exit; keep the Root mounted and drive `open`.
 - Scrolling wrapper inside Modal.Body → Body already scrolls.
 - Long multi-section forms in a modal → use Drawer.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md) (header close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Modal.Body`)
-- **See also:** [Drawer](../drawer/COMPONENT.md), [Popover](../popover/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md)
+- **Built from:** [Button](../button/COMPONENT.md) (header close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Modal.Body`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Modal.Guard` discard confirm), `Icon` (the close glyph)
+- **See also:** [ConfirmDialog](../confirm-dialog/COMPONENT.md) (a destructive confirm built on Modal `s`), [Drawer](../drawer/COMPONENT.md) (the same header, body, footer and `Guard` at the edge), [Popover](../popover/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md)

package/src/components/modal/examples/guard.tsx

@@ -0,0 +1,87 @@
+/** An edit form that holds the dialog: changes make any dismiss ask first and show a note in the footer; while saving nothing closes it — `Modal.Guard`, `Modal.Meta`. */
+import { Button, Fieldset, Input, Modal } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const CLIENT = { company: "ООО «Северный ветер»", email: "office@nwind.ru" };
+
+/** Pretends to send the form. */
+function saveClient() {
+  return new Promise((resolve) => setTimeout(resolve, 1200));
+}
+
+export default function ModalGuardExample() {
+  const formId = React.useId();
+  const [open, setOpen] = React.useState(false);
+  const [dirty, setDirty] = React.useState(false);
+  const [saving, setSaving] = React.useState(false);
+
+  const submit = async (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSaving(true);
+    await saveClient();
+    setSaving(false);
+    setDirty(false);
+    setOpen(false);
+  };
+
+  return (
+    <Modal.Root
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) setDirty(false);
+      }}
+    >
+      <Modal.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Изменить клиента
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Content>
+        <Modal.Guard busy={saving} dirty={dirty} />
+        <Modal.Header>
+          <Modal.Title>Клиент</Modal.Title>
+          <Modal.Description>Реквизиты для счетов и актов</Modal.Description>
+        </Modal.Header>
+        <Modal.Body>
+          <form id={formId} className={styles.form} onSubmit={submit}>
+            <Fieldset disabled={saving}>
+              <Input.Root label="Компания">
+                <Input.Wrapper>
+                  <Input.Field
+                    name="company"
+                    defaultValue={CLIENT.company}
+                    onValueChange={() => setDirty(true)}
+                  />
+                </Input.Wrapper>
+              </Input.Root>
+              <Input.Root label="Почта для документов">
+                <Input.Wrapper>
+                  <Input.Field
+                    name="email"
+                    type="email"
+                    defaultValue={CLIENT.email}
+                    onValueChange={() => setDirty(true)}
+                  />
+                </Input.Wrapper>
+              </Input.Root>
+            </Fieldset>
+          </form>
+        </Modal.Body>
+        <Modal.Footer>
+          {dirty ? <Modal.Meta>Есть несохранённые изменения</Modal.Meta> : null}
+          <Modal.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Отмена
+            </Button.Root>
+          </Modal.Close>
+          <Button.Root type="submit" form={formId} loading={saving} disabled={!dirty}>
+            Сохранить
+          </Button.Root>
+        </Modal.Footer>
+      </Modal.Content>
+    </Modal.Root>
+  );
+}

package/src/components/modal/examples/sizes.tsx

@@ -1,7 +1,8 @@
-/** Every width; s and m fill the footer with equal buttons, l and xl align them to the end — `size`. */
+/** Every width; xs, s and m fill the footer with equal buttons, l and xl align them to the end — `size`. */
 import { Button, Modal, Typography } from "prime-ui-kit";
 
 const SIZES = [
+  { size: "xs", width: "360 px — одно-два поля" },
   { size: "s", width: "440 px — подтверждения" },
   { size: "m", width: "560 px — короткие формы" },
   { size: "l", width: "720 px — формы в две колонки" },

package/src/components/native-select/COMPONENT.md

@@ -128,5 +128,5 @@ One look, the Select trigger's: field fill, inset control border, tier radius; t
 - Several values with `multiple` → not supported; use Select `multiple` or TagSelect.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) (field frame)
+- **Built from:** [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) (field frame), `Icon` (chevron)
 - **See also:** [Select](../select/COMPONENT.md), [Radio](../radio/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/notification/COMPONENT.md

@@ -76,6 +76,7 @@ Must be called inside `NotificationProvider`; returns the store.
 | `duration` | `number` | `5000` | Auto-close delay in ms; the timer pauses on hover, focus, swipe and in a hidden tab. |
 | `persistent` | `boolean` | `false` | No timer and no countdown line. |
 | `closable` | `boolean` | `true` | Shows the close button. |
+| `onDismiss` | `() => void` | — | The toast left: its timer ran out, the close button, a swipe, `dismiss()`, or a newer toast pushed it out of a full stack. Called once — the place to commit an action the toast offered to undo. |
 
 ### NotificationCard
 `ref` → `HTMLElement`. A static `<article role="status|alert">` card without a timer: inline confirmations, docs, mockups.
@@ -175,6 +176,7 @@ Collapsed stacks show up to 3 cards peeking behind each other. Hover or keyboard
 | [placement.tsx](examples/placement.tsx) | Toasts in each corner or centered at the top or bottom edge — `position`. |
 | [tones.tsx](examples/tones.tsx) | The four tones: the icon carries the meaning; danger and warning are announced at once — `tone`. |
 | [stacking.tsx](examples/stacking.tsx) | Toasts of one position and tone stack; hover expands the stack and pauses the timers — `max`, `items`, `dismissAll`. |
+| [undo.tsx](examples/undo.tsx) | Delete at once and offer to undo: the row leaves the list, the toast brings it back, and the deletion is sent only when the toast leaves without an undo — `onDismiss`, `action`. |
 | [dismiss.tsx](examples/dismiss.tsx) | A short timer, a toast that stays until closed, and one without a close button — `duration`, `persistent`, `closable`. |
 | [in-form.tsx](examples/in-form.tsx) | Saving a form: the button shows loading, then a success toast or an error toast with a retry action — `notify`, `action`. |
 
@@ -183,8 +185,9 @@ Collapsed stacks show up to 3 cards peeking behind each other. Hover or keyboard
 - Several providers in one app → one provider at the root.
 - `tone: "error"` → use `tone: "danger"`.
 - Expecting `action` to close the toast → call `dismiss(id)` in `onClick` if it should.
+- Sending a deletion to the server before the «Отменить» toast is gone → send it in `onDismiss`, unless the action ran.
 - A toast for a permanent state («пробный период закончится через 3 дня») → use a Banner.
 
 ## Related
-- **Built from:** Button, Badge, Icon
+- **Built from:** [Button](../button/COMPONENT.md) (action, close), [Badge](../badge/COMPONENT.md) (`badge`), Icon (`status.*`, `action.close`)
 - **See also:** [Banner](../banner/COMPONENT.md), [Button](../button/COMPONENT.md), [Modal](../modal/COMPONENT.md)

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

@@ -20,7 +20,8 @@
 
 /* placement.tsx: a 16rem position picker. */
 .select {
-  width: min(100%, calc(var(--prime-space-16) * 4));
+  width: calc(var(--prime-space-16) * 4);
+  max-width: 100%;
 }
 
 /* in-form.tsx: a settings form in a Card. */
@@ -40,3 +41,12 @@
   justify-content: flex-end;
   gap: var(--prime-space-2);
 }
+
+/* undo.tsx: a task with its delete action at the end. */
+.taskRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
+  min-width: 0;
+}

package/src/components/notification/examples/undo.tsx

@@ -0,0 +1,61 @@
+/** Delete at once and offer to undo: the row leaves the list, the toast brings it back, and the deletion is sent only when the toast leaves without an undo — `onDismiss`, `action`. */
+import { Button, NotificationProvider, Typography, useNotifications } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TASKS = ["Подготовить договор", "Выставить счёт №318", "Созвониться с юристом"];
+
+function TaskList() {
+  const { notify, dismiss } = useNotifications();
+  const [tasks, setTasks] = React.useState(TASKS);
+  const [sent, setSent] = React.useState<string[]>([]);
+
+  const remove = (task: string) => {
+    setTasks((list) => list.filter((item) => item !== task));
+    let undone = false;
+    const id = notify({
+      title: "Задача удалена",
+      description: task,
+      action: {
+        label: "Отменить",
+        onClick: () => {
+          undone = true;
+          setTasks((list) => [...list, task]);
+          dismiss(id);
+        },
+      },
+      // The toast is gone: without an undo the deletion goes to the server now.
+      onDismiss: () => {
+        if (!undone) setSent((list) => [...list, task]);
+      },
+    });
+  };
+
+  return (
+    <div className={styles.cards}>
+      {tasks.map((task) => (
+        <div key={task} className={styles.taskRow}>
+          <Typography as="span" variant="body-m">
+            {task}
+          </Typography>
+          <Button.Root variant="ghost" tone="danger" onClick={() => remove(task)}>
+            Удалить
+          </Button.Root>
+        </div>
+      ))}
+      <Typography as="p" variant="caption" tone="muted">
+        Отправлено на сервер: {sent.length > 0 ? sent.join(", ") : "ничего"}
+      </Typography>
+    </div>
+  );
+}
+
+export default function NotificationUndoExample() {
+  // In an app NotificationProvider wraps the root once; here it keeps the example self-contained.
+  return (
+    <NotificationProvider>
+      <TaskList />
+    </NotificationProvider>
+  );
+}