prime-ui-kit 0.9.0 → 0.9.2

package/src/components/notification/COMPONENT.md

@@ -1,204 +1,190 @@
 # Notification
 
-**Category:** feedback
+**Category:** status
+**Kind:** overlay
 
 > Pop-up toast notifications: `NotificationProvider` at the app root and `notify()` from any screen.
 
 ## When to use
 - A short reaction to a user action: saved, sent, copied, failed to save.
 - A background event the user should notice without leaving the screen (new message, low stock).
-- An error with a quick recovery action ("Повторить").
+- An error with a quick recovery action («Повторить»).
 
 ## When not to use
 - A persistent message about a page or account state → use [Banner](../banner/COMPONENT.md).
-- A field validation error → use the field `error` / [Hint](../hint/COMPONENT.md).
+- A field validation error → the field `error` / [Hint](../hint/COMPONENT.md).
 - A decision the user must make before continuing → use [Modal](../modal/COMPONENT.md).
-- Progress of a long operation → use [ProgressBar](../progress-bar/COMPONENT.md) in the UI.
+- Progress of a long operation → [ProgressBar](../progress-bar/COMPONENT.md) in the UI.
 
 ## Import
 ```tsx
 import { NotificationCard, NotificationProvider, useNotifications } from "prime-ui-kit";
 ```
-Public types: `NotificationOptions`, `NotificationRecord`, `NotificationPosition`, `NotificationAction`, `NotificationLabels`, `NotificationProviderProps`, `NotificationCardProps`.
 
 ## Anatomy
 ```
 NotificationProvider                 store + portaled viewport (z-index toast)
 └─ zone per position                 top/bottom × left/center/right
-   └─ stack per tone                 <ol> named by labels.regions[position]; newest in front
-      └─ NotificationCard            <article role="status|alert">
-         ├─ icon                     tone icon or `icon`
-         ├─ title + badge
+   └─ stack per tone                 <ol> named by labels; newest in front
+      └─ card                        <article role="status|alert">
+         ├─ icon                     tone Icon or `icon`
+         ├─ title + Badge            `badge` counter
          ├─ description
-         ├─ action button            soft neutral, one tier below the card
-         ├─ close button             when `closable`
+         ├─ action Button            soft neutral, one tier below the card
+         ├─ close Button             ghost icon, when `closable`
          └─ countdown line           when not `persistent`
+NotificationCard                     the same card, static, without a timer
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### NotificationProvider
+No DOM of its own, no ref. Wraps the app once: keeps the toasts and renders their stacks in a portal (one stack per position × tone).
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"top-right"` | Default position for `notify()` calls without one. |
+| `max` | `number` | `5` | Max toasts per stack; older ones are dropped. |
+| `labels` | `Partial<NotificationLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — (required) | The app. |
-| `position` | `NotificationPosition` | `"top-right"` | Default position for `notify()` calls without one. |
-| `max` | `number` | `5` | Max toasts per stack (position × tone); older ones are dropped. |
-| `labels` | `{ close?: string; regions?: Partial<Record<NotificationPosition, string>> }` | see Accessibility | Built-in strings; `regions` merges per position. |
-
-`NotificationPosition` = `"top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"`.
 
 ### useNotifications()
-Must be called inside `NotificationProvider` (throws otherwise). Returns:
+Must be called inside `NotificationProvider`; returns the store.
 
-| Field | Type | Description |
-|---|---|---|
-| `notify` | `(options: NotificationOptions) => string` | Shows a toast and returns its id. |
-| `dismiss` | `(id: string) => void` | Closes one toast (plays the exit animation). |
-| `dismissAll` | `() => void` | Closes all toasts. |
-| `items` | `NotificationRecord[]` | Active toasts (without the ones playing their exit). |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `notify` | `(options: NotificationOptions) => string` | — | Shows a toast and returns its id. |
+| `dismiss` | `(id: string) => void` | — | Closes one toast with its exit animation. |
+| `dismissAll` | `() => void` | — | Closes every toast. |
+| `items` | `NotificationRecord[]` | — | Active toasts (without the ones playing their exit). |
+
+### notify(options)
+`NotificationOptions`: what the toast shows and how it closes.
 
-### NotificationOptions (argument of `notify`)
-| Option | Type | Default | Description |
+| Prop | Type | Default | Description |
 |---|---|---|---|
-| `title` | `string` | — (required) | Title. |
-| `description` | `string` | — | Text under the title. |
-| `tone` | `"info" \| "success" \| "warning" \| "danger"` | `"info"` | Meaning, default icon, stack grouping; `warning` and `danger` are announced assertively. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Padding, icon and text of the card. |
-| `position` | `NotificationPosition` | provider `position` | Screen corner or edge. |
-| `duration` | `number` | `5000` | Auto-close timeout in ms. A value `<= 0` disables the timer. |
-| `persistent` | `boolean` | `false` | No timer and no countdown line; closes only by the close button or `dismiss`. |
-| `icon` | `ReactNode` | tone icon | Custom icon. |
-| `badge` | `string \| number` | — | Counter next to the title. |
-| `closable` | `boolean` | `true` | Close button. |
-| `action` | `{ label: string; onClick: () => void }` | — | Secondary button in the card. Clicking it does not close the toast. |
-
-### NotificationRecord
-`NotificationOptions` with `id`, `createdAt` and resolved `tone`, `position`, `size`, `duration`, `persistent`, `closable` (all required). Used by `items` and by `NotificationCard`.
+| `tone` | `"info" \| "success" \| "warning" \| "danger"` | `"info"` | Semantic color and tone icon; `danger` and `warning` are announced assertively. |
+| `title` | `string` | — (required) | The message. |
+| `description` | `string` | — | Secondary text under the title. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Padding, icon and text tier of the card. |
+| `icon` | `ReactNode` | — | Replaces the tone icon. |
+| `badge` | `string \| number` | — | A counter next to the title (a `Badge` in the tone hue). |
+| `action` | `{ label: string; onClick: () => void }` | — | One soft button under the text, one tier below the card. |
+| `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | — | Default: the provider's `position`. |
+| `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. |
 
 ### NotificationCard
-A single toast card without the store, for docs, mockups or custom hosts. No ref.
+`ref` → `HTMLElement`. A static `<article role="status|alert">` card without a timer: inline confirmations, docs, mockups.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `item` | `NotificationRecord` | — (required) | What to render. |
-| `paused` | `boolean` | — (required) | Pauses the countdown. Pass `true` for static cards. |
-| `onDismiss` | `(id: string) => void` | — (required) | Called by the close button and when the countdown ends. |
-| `className` | `string` | — | Class on the `<article>`. |
-| `stackDepth` | `number` | `0` | Depth in a stack (`data-stack-depth`). |
-| `stackExpanded` | `boolean` | `false` | Whether the stack is expanded (`data-stack-expanded`). |
+| `tone` | `"info" \| "success" \| "warning" \| "danger"` | `"info"` | Semantic color and tone icon; `danger` and `warning` are announced assertively. |
+| `title` | `string` | — (required) | The message. |
+| `description` | `string` | — | Secondary text under the title. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Padding, icon and text tier of the card. |
+| `icon` | `ReactNode` | — | Replaces the tone icon. |
+| `badge` | `string \| number` | — | A counter next to the title (a `Badge` in the tone hue). |
+| `action` | `{ label: string; onClick: () => void }` | — | One soft button under the text, one tier below the card. |
+| `onDismiss` | `() => void` | — | Shows the close button and is called on its click. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "title" \| "children" \| "role">` | — | `className` and the other attributes of the `<article>`. |
 
 ## Variants
 
 ### tone
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `info` | Raised card, info icon (circle "i"), info countdown | Neutral events, messages | yes |
-| `success` | Success check icon | Completed actions | |
-| `warning` | Warning triangle icon | Something needs attention soon | |
-| `danger` | Danger cross icon | Failed actions; pair with `action` to retry | |
+| `info` | raised card, info icon, info countdown | neutral events, messages | yes |
+| `success` | success icon | completed actions | |
+| `warning` | warning icon | something needs attention soon | |
+| `danger` | danger icon | failed actions; pair with `action` to retry | |
 
-The card itself is always a raised surface without a border; only the icon, the badge and the countdown take the tone. Each tone forms its own stack in a position.
+The card is always a raised surface without a border; only the icon, the badge and the countdown take the tone. Each tone forms its own stack in a position.
 
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | Smallest padding and icon, `xs` text; action button `xs` | Very dense apps | |
-| `s` | Compact; action button `xs` | Dense dashboards | |
-| `m` | Padding 16, icon 16, title 14/20, description 13/20; action button `s` | Default | yes |
-| `l` | Larger padding and text; action button `m` | Touch screens | |
-| `xl` | Largest; action button `l` | Kiosk / large screens | |
+| `xs` · `s` | compact padding and text; action `xs` | dense apps | |
+| `m` | padding 16, title 14/20, description 13/20; action `s` | default | yes |
+| `l` · `xl` | larger padding and text; action `m` / `l` | touch and large screens | |
 
 ### position
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `top-right` | Stack in the top-right corner, grows down | Desktop apps | yes |
-| `top-center` | Centered at the top | Global system events | |
-| `top-left` | Top-left corner | Right-side panels occupy the right | |
-| `bottom-right` | Bottom-right corner, grows up | Chat-like or editor apps | |
-| `bottom-center` | Centered at the bottom | Mobile-like layouts | |
-| `bottom-left` | Bottom-left corner | Apps with right-bottom controls | |
+| `top-right` | top-right corner, grows down | desktop apps | yes |
+| `top-center` · `top-left` | top edge | global events; right panels occupy the right | |
+| `bottom-right` · `bottom-center` · `bottom-left` | bottom edge, grows up | chat-like or mobile-like layouts | |
 
 ### Flags
-| Flag | Looks like | Use when | Default |
+| Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `persistent` | No countdown line, no auto-close | Errors the user must read or act on | `false` |
-| `closable: false` | No close button | Very short confirmations ("Ссылка скопирована") | `true` |
-| `badge` | Small counter after the title | Grouped events ("3 ответа") | — |
-
-**Combinations**
-- Recommended: `danger` + `persistent` + `action: Повторить`; `success` with a short title only.
-- Pointless: `persistent` + `closable: false` (the toast can only be closed by code); `duration` together with `persistent`.
-- Avoid: several positions in one app; long descriptions — keep one or two lines.
+| `persistent` | no countdown line, no auto-close | errors the user must read or act on | `false` |
+| `closable` | close button | turn off for very short confirmations | `true` |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | tone / size | options | `data-tone`, `data-size` on the card |
-| persistent | `persistent` | `data-persistent="true"` |
-| stack position | store | `data-stack-depth`, `data-stack-expanded` on the card; `data-stack-index`, `data-hidden`, `data-state="open" \| "closed"` on the stack item; `data-expanded` on the stack |
-| paused | hover over the stack | countdown stops while the stack is expanded |
+| persistent | `persistent` (always on a static card) | `data-persistent="true"` |
+| stack position | store | `data-stack-depth`, `data-stack-expanded` on the card; `data-stack-index`, `data-hidden`, `data-state` on the item; `data-expanded` on the stack |
+| paused | hover or focus in the stack, a swipe, a hidden tab | the countdown stops and resumes where it stopped |
+| swipe | pointer drag | `data-swipe="drag" \| "return" \| "out"`, `data-swipe-axis` on the motion wrapper |
 
-Collapsed stacks show up to 3 cards peeking behind each other; hover expands the stack and pauses the timers. Under `prefers-reduced-motion` toasts are removed without an exit animation.
+Collapsed stacks show up to 3 cards peeking behind each other. Hover or keyboard focus expands the stack. Toasts enter from their edge and leave toward it, faster than they came; a swipe toward the edge dismisses (past `--prime-space-12` or a quick flick). Under `prefers-reduced-motion` toasts are removed without an exit animation.
 
 ## Layout & spacing
-- Toasts render in a fixed, portaled viewport; zones are `--prime-space-5` from the viewport edge (`--prime-space-3` below 640px) and at most 24rem wide.
+- A fixed, portaled viewport; zones are `--prime-space-5` from the edge (`--prime-space-3` below 640px) plus the safe-area insets (`env(safe-area-inset-*)`), at most 24rem wide.
 - Cards in an expanded stack are `--prime-space-2` apart.
-- The viewport does not take pointer events except over the cards.
+- The viewport takes pointer events only over the cards.
 
 ## Accessibility
-- Each card is an `<article>`: `role="status"` + `aria-live="polite"` for `info`/`success`, `role="alert"` + `aria-live="assertive"` for `warning`/`danger`.
-- Each stack is an `<ol>` with an accessible name from `labels.regions[position]`.
-- The icon and countdown line are `aria-hidden`; the close button has `labels.close`.
-- Do not put the only copy of important information in a toast with a timer — use `persistent` or a Banner.
 
-| `labels` key | Default | Used for |
-|---|---|---|
-| `close` | `"Закрыть уведомление"` | `aria-label` of the close button |
-| `regions["top-left"]` | `"Уведомления сверху слева"` | Name of the top-left stack |
-| `regions["top-center"]` | `"Уведомления сверху по центру"` | Name of the top-center stack |
-| `regions["top-right"]` | `"Уведомления сверху справа"` | Name of the top-right stack |
-| `regions["bottom-left"]` | `"Уведомления снизу слева"` | Name of the bottom-left stack |
-| `regions["bottom-center"]` | `"Уведомления снизу по центру"` | Name of the bottom-center stack |
-| `regions["bottom-right"]` | `"Уведомления снизу справа"` | Name of the bottom-right stack |
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focuses the action and the close button; focus inside a stack expands it and pauses the timers. |
+| `Enter` · `Space` | Presses the action or the close button. |
 
-## Examples
-| File | Scenario | When to use this pattern |
+### ARIA
+- Each stack is an `<ol>` named by the region label of its position; each card is an `<article>`: `role="status"` + `aria-live="polite"`, or `role="alert"` + `aria-live="assertive"` for `warning` / `danger`.
+- The icon and the countdown are `aria-hidden`; the close button is named by `labels.close`.
+- Do not keep the only copy of important information in a toast with a timer — use `persistent` or a Banner.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
 |---|---|---|
-| [save-form.tsx](examples/save-form.tsx) | Button `loading`, then a success toast or a danger toast with "Повторить" | Async save feedback |
-| [live.tsx](examples/live.tsx) | `notify()` per tone with a position picker, `persistent`, `items.length`, `dismissAll` | Positions, stacking, timers |
-| [tones.tsx](examples/tones.tsx) | Static `NotificationCard` per tone | Docs and mockups |
-| [sizes.tsx](examples/sizes.tsx) | Static cards `xs`…`xl` | Picking a size |
-| [features.tsx](examples/features.tsx) | `icon`, `badge`, `action`, title-only with `closable: false` | Digests and quick confirmations |
+| `close` | `"Закрыть уведомление"` | `aria-label` of the close button. |
+| `regionTopLeft` | `"Уведомления сверху слева"` | Name of the top-left toast list. |
+| `regionTopCenter` | `"Уведомления сверху по центру"` | Name of the top-center toast list. |
+| `regionTopRight` | `"Уведомления сверху справа"` | Name of the top-right toast list. |
+| `regionBottomLeft` | `"Уведомления снизу слева"` | Name of the bottom-left toast list. |
+| `regionBottomCenter` | `"Уведомления снизу по центру"` | Name of the bottom-center toast list. |
+| `regionBottomRight` | `"Уведомления снизу справа"` | Name of the bottom-right toast list. |
 
-```tsx
-import { Button, NotificationProvider, useNotifications } from "prime-ui-kit";
-
-function CopyLink() {
-  const { notify } = useNotifications();
-  return (
-    <Button.Root onClick={() => notify({ tone: "success", title: "Ссылка скопирована" })}>
-      Копировать ссылку
-    </Button.Root>
-  );
-}
-
-export function App() {
-  return (
-    <NotificationProvider>
-      <CopyLink />
-    </NotificationProvider>
-  );
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A provider at the app root and a success toast from any screen — `NotificationProvider`, `notify`. |
+| [structure.tsx](examples/structure.tsx) | Optional parts on static cards: a custom icon, a counter, an action and a close button, or a title alone — `icon`, `badge`, `action`, `onDismiss`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier changes padding, icon and text of the card — `size`. |
+| [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`. |
+| [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`. |
 
 ## Mistakes
 - Calling `useNotifications()` outside `NotificationProvider` → it throws; wrap the app root once.
-- Several providers in one app → one provider at the root; nested ones create separate toasters.
+- 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.
-- Using a toast for a permanent state ("trial ends in 3 days") → use a Banner.
+- A toast for a permanent state («пробный период закончится через 3 дня») → use a Banner.
 
 ## Related
-- [Banner](../banner/COMPONENT.md) — persistent in-flow messages.
-- [Button](../button/COMPONENT.md) — `loading` before the result toast.
-- [Modal](../modal/COMPONENT.md) — blocking confirmations.
+- **Built from:** Button, Badge, Icon
+- **See also:** [Banner](../banner/COMPONENT.md), [Button](../button/COMPONENT.md), [Modal](../modal/COMPONENT.md)

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

@@ -0,0 +1,50 @@
+/** A short timer, a toast that stays until closed, and one without a close button — `duration`, `persistent`, `closable`. */
+import { Button, NotificationProvider, useNotifications } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+function DismissButtons() {
+  const { notify } = useNotifications();
+  return (
+    <div className={styles.row}>
+      <Button.Root
+        variant="outline"
+        tone="neutral"
+        onClick={() => notify({ title: "Черновик сохранён", duration: 2000 })}
+      >
+        На 2 секунды
+      </Button.Root>
+      <Button.Root
+        variant="outline"
+        tone="neutral"
+        onClick={() =>
+          notify({
+            tone: "danger",
+            title: "Платёж отклонён",
+            description: "Банк не подтвердил операцию.",
+            persistent: true,
+            action: { label: "Повторить", onClick: () => undefined },
+          })
+        }
+      >
+        Без таймера
+      </Button.Root>
+      <Button.Root
+        variant="outline"
+        tone="neutral"
+        onClick={() => notify({ tone: "success", title: "Ссылка скопирована", closable: false })}
+      >
+        Без кнопки закрытия
+      </Button.Root>
+    </div>
+  );
+}
+
+export default function NotificationDismissExample() {
+  // In an app NotificationProvider wraps the root once; here it keeps the example self-contained.
+  return (
+    <NotificationProvider>
+      <DismissButtons />
+    </NotificationProvider>
+  );
+}

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

@@ -1,6 +1,6 @@
-/* Layout helpers for the Notification examples. Semantic tokens only. */
+/* Layout of the Notification scenarios: semantic tokens only. */
 
-/* Column of static cards, about as wide as a toast (24rem). */
+/* Static cards in a column about as wide as a toast (24rem). */
 .cards {
   display: flex;
   flex-direction: column;
@@ -9,6 +9,7 @@
   min-width: 0;
 }
 
+/* Buttons that raise toasts. */
 .row {
   display: flex;
   flex-wrap: wrap;
@@ -17,31 +18,21 @@
   gap: var(--prime-space-2);
 }
 
-.controls {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-4);
-  width: 100%;
-}
-
-/* 16rem position picker. */
+/* placement.tsx: a 16rem position picker. */
 .select {
   width: min(100%, calc(var(--prime-space-16) * 4));
 }
 
-/* 26rem settings card. */
-.card {
-  box-sizing: border-box;
+/* in-form.tsx: a settings form in a Card. */
+.formCard {
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.form {
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-5);
-  width: min(100%, calc(var(--prime-space-24) * 4 + var(--prime-space-8)));
   padding: var(--prime-card-padding-m);
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
-  --prime-color-field-bg: var(--prime-color-field-bg-surface);
 }
 
 .actions {
@@ -49,7 +40,3 @@
   justify-content: flex-end;
   gap: var(--prime-space-2);
 }
-
-.count {
-  font-variant-numeric: tabular-nums;
-}

package/src/components/notification/examples/in-form.tsx

@@ -0,0 +1,64 @@
+/** Saving a form: the button shows loading, then a success toast or an error toast with a retry action — `notify`, `action`. */
+import { Button, Card, Input, NotificationProvider, useNotifications } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+function ReportsForm() {
+  const { notify } = useNotifications();
+  const [saving, setSaving] = React.useState(false);
+  const [email, setEmail] = React.useState("team@prime.dev");
+
+  const save = () => {
+    setSaving(true);
+    window.setTimeout(() => {
+      setSaving(false);
+      if (email.includes("@")) {
+        notify({
+          tone: "success",
+          title: "Настройки сохранены",
+          description: `Отчёты придут на ${email}.`,
+        });
+      } else {
+        notify({
+          tone: "danger",
+          title: "Не удалось сохранить",
+          description: "Укажите корректный адрес почты.",
+          action: { label: "Повторить", onClick: save },
+        });
+      }
+    }, 700);
+  };
+
+  return (
+    <Card.Root className={styles.formCard}>
+      <form
+        className={styles.form}
+        onSubmit={(event) => {
+          event.preventDefault();
+          save();
+        }}
+      >
+        <Input.Root label="Почта для отчётов" hint="Без «@» сохранение завершится ошибкой" required>
+          <Input.Wrapper>
+            <Input.Field value={email} onChange={(event) => setEmail(event.target.value)} />
+          </Input.Wrapper>
+        </Input.Root>
+        <div className={styles.actions}>
+          <Button.Root type="submit" loading={saving}>
+            Сохранить
+          </Button.Root>
+        </div>
+      </form>
+    </Card.Root>
+  );
+}
+
+export default function NotificationInFormExample() {
+  // In an app NotificationProvider wraps the root once; here it keeps the example self-contained.
+  return (
+    <NotificationProvider>
+      <ReportsForm />
+    </NotificationProvider>
+  );
+}

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

@@ -0,0 +1,24 @@
+/** A provider at the app root and a success toast from any screen — `NotificationProvider`, `notify`. */
+import { Button, NotificationProvider, useNotifications } from "prime-ui-kit";
+
+function CopyLinkButton() {
+  const { notify } = useNotifications();
+  return (
+    <Button.Root
+      variant="outline"
+      tone="neutral"
+      onClick={() => notify({ tone: "success", title: "Ссылка на счёт скопирована" })}
+    >
+      Скопировать ссылку
+    </Button.Root>
+  );
+}
+
+export default function NotificationOverviewExample() {
+  // In an app NotificationProvider wraps the root once; here it keeps the example self-contained.
+  return (
+    <NotificationProvider>
+      <CopyLinkButton />
+    </NotificationProvider>
+  );
+}

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

@@ -0,0 +1,66 @@
+/** Toasts in each corner or centered at the top or bottom edge — `position`. */
+import {
+  Button,
+  type NotificationPosition,
+  NotificationProvider,
+  Select,
+  useNotifications,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const POSITIONS: { value: NotificationPosition; label: string }[] = [
+  { value: "top-left", label: "Сверху слева" },
+  { value: "top-center", label: "Сверху по центру" },
+  { value: "top-right", label: "Сверху справа" },
+  { value: "bottom-left", label: "Снизу слева" },
+  { value: "bottom-center", label: "Снизу по центру" },
+  { value: "bottom-right", label: "Снизу справа" },
+];
+
+function PositionPicker() {
+  const { notify } = useNotifications();
+  const [position, setPosition] = React.useState<NotificationPosition>("top-right");
+
+  return (
+    <div className={styles.row}>
+      <div className={styles.select}>
+        <Select.Root value={position} onValueChange={(v) => setPosition(v as NotificationPosition)}>
+          <Select.Trigger aria-label="Позиция уведомлений">
+            <Select.Value />
+          </Select.Trigger>
+          <Select.Content>
+            {POSITIONS.map((item) => (
+              <Select.Item key={item.value} value={item.value}>
+                {item.label}
+              </Select.Item>
+            ))}
+          </Select.Content>
+        </Select.Root>
+      </div>
+      <Button.Root
+        variant="outline"
+        tone="neutral"
+        onClick={() =>
+          notify({
+            title: "Новое сообщение",
+            description: "Поддержка ответила в чате.",
+            position,
+          })
+        }
+      >
+        Показать
+      </Button.Root>
+    </div>
+  );
+}
+
+export default function NotificationPlacementExample() {
+  // In an app NotificationProvider wraps the root once; here it keeps the example self-contained.
+  return (
+    <NotificationProvider>
+      <PositionPicker />
+    </NotificationProvider>
+  );
+}

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

@@ -1,28 +1,21 @@
-/** Sizes xs–xl change padding, icon and text of the card; pass `size` to `notify()` or to a static record. Use smaller sizes for dense apps, larger ones for touch screens. */
-import { type ControlSize, NotificationCard, type NotificationRecord } from "prime-ui-kit";
+/** Every tier changes padding, icon and text of the card — `size`. */
+import { NotificationCard } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
-
-const card = (size: ControlSize): NotificationRecord => ({
-  id: `sizes-${size}`,
-  tone: "info",
-  title: `Размер ${size}`,
-  description: "Меняются отступы, иконка и текст карточки.",
-  position: "top-right",
-  size,
-  duration: 0,
-  persistent: true,
-  closable: true,
-  createdAt: 0,
-});
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function NotificationSizesExample() {
   return (
     <div className={styles.cards}>
-      {sizes.map((size) => (
-        <NotificationCard key={size} item={card(size)} paused onDismiss={() => {}} />
+      {SIZES.map((size) => (
+        <NotificationCard
+          key={size}
+          size={size}
+          title={`Отчёт готов · ${size}`}
+          description="Выгрузка за сентябрь доступна в разделе «Отчёты»."
+          onDismiss={() => undefined}
+        />
       ))}
     </div>
   );