prime-ui-kit 0.7.13 → 0.9.1

package/src/components/notification/COMPONENT.md

@@ -1,156 +1,190 @@
 # Notification
 
-**Default `size`:** use **`m`** for the notification card size unless the surface explicitly needs **`s`** or **`l`**.
+**Category:** feedback
+**Kind:** overlay
 
-## Canonical
+> Pop-up toast notifications: `NotificationProvider` at the app root and `notify()` from any screen.
 
-- **`NotificationProvider`** — wraps the tree that calls hooks; mounts a **portal** with fixed **zones** per viewport corner/edge. Each **`notify`** item is grouped by **`position`** and **`type`** into separate stacks (**`max`** per stack, default **`5`**).
-- **`useNotifications`** — **`notify`**, **`dismiss`**, **`dismissAll`** only; throws outside the provider.
-- **`useNotificationStore`** — same methods plus **`items`** (**`NotificationRecord[]`**, active only, no exit-animation rows).
-- **`NotificationCard`** — **`article`** with live region semantics, icon, title, optional badge/description/**`action`** (neutral stroke **`Button.Root`**), optional close, progress track unless **`persistent`**.
-- **Stacks** — Framer Motion list; hover expands stack and **pauses** countdowns until collapse. **`error`** / **`warning`** → **`role="alert"`**, **`aria-live="assertive"`**; **`success`** / **`info`** → **`status`**, **`polite`**.
+## 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 («Повторить»).
 
-## Extended
-
-### About
-
-Toast notifications for short, non-blocking feedback after actions (save, send, job finished) when focus must not be trapped.
-
-- **When to use** — confirmations or lightweight errors that do not need a blocking dialog.
-- **When to use** — one optional secondary **`action`** (e.g. undo, open detail) alongside auto-dismiss.
-- **When to use** — **`useNotificationStore`** when the UI must reflect **`items`** (counters, bulk dismiss, custom chrome).
-- **When not to use** — blocking decisions, long forms, or primary workflow inside the toast; prefer [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), or [Banner](../banner/COMPONENT.md).
-- **When not to use** — multiple nested **`NotificationProvider`**s unless you intentionally want several portals.
-
-### Composition
-
-- **`NotificationProvider`** → context + **`NotificationToaster`** (portal, zones, **`NotificationStack`** per **`position`** + **`type`**).
-- **`NotificationStack` / `NotificationStackItem`** (internal) — ordered list; peek/collapse behavior and **`paused`** passed to **`NotificationCard`**.
-- **`NotificationCard`** — public for static previews or fully custom wiring; live toasts should use **`notify`**.
-
-### Scenarios (playground + `examples/`)
-
-Live demos in the playground use **`playground/snippets/notification/*.tsx`** (see **`playground/sections/NotificationSection.tsx`**). The table below lists the same scenarios with package-oriented copies under **`examples/`** (aligned 1:1 with those snippets).
-
-| Scenario | Approach |
-|----------|----------|
-| Sizes | Static **`NotificationCard`** row for **`s`** / **`m`** / **`l`** with **`persistent`** and **`closable: false`** so only scale differs. → [`examples/sizes.tsx`](examples/sizes.tsx) |
-| Variants (`type`) | Four **`type`** values on static cards; **`persistent: true`** shows accent border and glow pulse (default live **`notify()`** is **`persistent: false`**). → [`examples/variants.tsx`](examples/variants.tsx) |
-| States | Static **`persistent`** vs **`closable: false`**, plus buttons for timed toast, hover-pause stack, and **`notify`** with **`persistent`**. → [`examples/states.tsx`](examples/states.tsx) |
-| Positions | Six **`NotificationPosition`** values; **`position`** in **`notify`** options. → [`examples/positions.tsx`](examples/positions.tsx) |
-| Controlled store | **`useNotificationStore()`** — **`items`**, **`notify`**, **`dismiss(id)`** per row. → [`examples/controlled.tsx`](examples/controlled.tsx) |
-| Composition | **`icon`**, **`badge`**, **`description`**, **`action`**; static card plus live **`notify`** (e.g. lucide **`Bell`**). → [`examples/composition.tsx`](examples/composition.tsx) |
-| Stack / timing | Burst stack (**`max`** per stack), hover expand + pause, **`dismissAll`**, short vs long **`duration`**. → [`examples/features.tsx`](examples/features.tsx) |
-
-**Additional examples:** interactive **`type`** buttons → [`examples/error-success.tsx`](examples/error-success.tsx); **`action`** + **`LinkButton`** trigger → [`examples/action-toast.tsx`](examples/action-toast.tsx). Deprecated aliases: [`examples/toast-queue.tsx`](examples/toast-queue.tsx) → **`features`**, [`examples/notification-store.tsx`](examples/notification-store.tsx) → **`controlled`**.
-
-### Minimal example
+## When not to use
+- A persistent message about a page or account state → use [Banner](../banner/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 → [ProgressBar](../progress-bar/COMPONENT.md) in the UI.
 
+## Import
 ```tsx
-import { NotificationProvider, useNotifications } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <NotificationProvider>
-      <Notifier />
-    </NotificationProvider>
-  );
-}
-
-function Notifier() {
-  const { notify } = useNotifications();
-  return (
-    <button type="button" onClick={() => notify({ type: "info", title: "Hello" })}>
-      Notify
-    </button>
-  );
-}
+import { NotificationCard, NotificationProvider, useNotifications } from "prime-ui-kit";
 ```
 
-### Rules
-
-- Call **`useNotifications`** or **`useNotificationStore`** only under **`NotificationProvider`**; both hooks throw if context is missing.
-- **`notify`** returns a string **`id`**; pass it to **`dismiss`** or use **`dismissAll`** for every active toast.
-- **`useNotificationStore`** exposes the same methods plus **`items`**: **`NotificationRecord[]`** of non-dismissing entries only (no internal closing-animation flag).
-- Options passed to **`notify`** are merged with defaults: **`size`** `"m"`, **`position`** from the provider, **`duration`** `5000` ms, **`persistent`** `false`, **`closable`** `true`.
-- With **`persistent`**, there is no auto-dismiss, no progress bar, and duration does not drive closing; users or **`dismiss`** / **`dismissAll`** must close the card. Visually, **`persistent`** also turns on the accent-tinted **border** and (unless **`prefers-reduced-motion`**) the **`notification-glow`** shadow pulse — default **`notify()`** uses **`persistent: false`**, so live toasts look flatter unless you opt in.
-- If **`duration <= 0`**, the countdown effect does not run—time-based auto-dismiss does not occur; close via **`dismiss`** or the close button when **`closable`**.
-- Stacks are keyed by **`position`** and **`type`**; **`max`** (default `5`) caps depth per stack—older items in that stack are dropped when exceeded.
-- **`type`** `error` and **`warning`** use **`role="alert"`** and **`aria-live="assertive"`**; other types use **`role="status"`** and **`aria-live="polite"`**.
-- Close control uses **`aria-label="Dismiss notification"`**; default type icons are **`aria-hidden`** inside the icon wrapper.
-- Each stack list has **`aria-label`** `Notifications at <position>`.
-- Nested **`NotificationProvider`** instances each render their own portal and zones—usually one root provider is enough.
-- **`NotificationCard`** is not connected to the store by itself; supply **`item`**, **`paused`**, and **`onDismiss`** and keep **`item`** fields consistent with **`NotificationRecord`**.
+## Anatomy
+```
+NotificationProvider                 store + portaled viewport (z-index toast)
+└─ zone per position                 top/bottom × left/center/right
+   └─ 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             ghost icon, when `closable`
+         └─ countdown line           when not `persistent`
+NotificationCard                     the same card, static, without a timer
+```
 
 ## API
 
-### NotificationProvider
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | Yes | Subtree where notification hooks are used |
-| position | `NotificationPosition` | `"top-right"` | No | Default **`position`** for **`notify`** when omitted in options |
-| max | `number` | `5` | No | Maximum items per stack (same **`position`** + **`type`**) |
-
-### NotificationOptions (`notify` payload)
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| type | `"success" \| "error" \| "warning" \| "info"` | — | Yes | Semantics, default icon, and stack grouping |
-| title | `string` | — | Yes | Primary heading |
-| description | `string` | — | No | Secondary text |
-| size | `"s" \| "m" \| "l"` | `"m"` | No | Card scale |
-| position | `NotificationPosition` | provider default | No | Corner or edge anchor |
-| duration | `number` | `5000` | No | Auto-dismiss delay in ms (ignored for closing when **`persistent`**; see Rules when `<= 0`) |
-| persistent | `boolean` | `false` | No | Disable timer and progress UI |
-| icon | `React.ReactNode` | type default | No | Custom leading icon |
-| badge | `string \| number` | — | No | Label next to the title |
-| closable | `boolean` | `true` | No | Show dismiss button |
-| action | `{ label: string; onClick: () => void }` | — | No | Secondary action rendered as neutral stroke **`Button.Root`** |
-
-`notify` returns the new record’s **`id`** (`string`).
-
-### NotificationRecord
-
-All **`NotificationOptions`** fields plus required **`id`**, **`position`**, **`size`**, **`duration`**, **`persistent`**, **`closable`**, and **`createdAt`** (`number`, ms). Defaults are filled when the record is created inside **`notify`**.
-
-### NotificationCard
+### 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 | Required | Description |
-|------|------|---------|----------|-------------|
-| item | `NotificationRecord` | — | Yes | Card data |
-| paused | `boolean` | — | Yes | Pause countdown (e.g. expanded stack) |
-| onDismiss | `(id: string) => void` | — | Yes | Called to remove the toast (timer or UI) |
-| stackDepth | `number` | `0` | No | Stack index for layout / `data-*` |
-| stackExpanded | `boolean` | `false` | No | Whether the parent stack is expanded |
-| className | `string` | — | No | Extra class on the root `article` |
+| 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. |
 
 ### useNotifications()
+Must be called inside `NotificationProvider`; returns the store.
+
+| 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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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. |
 
-| Field | Type | Description |
-|------|------|-------------|
-| notify | `(options: NotificationOptions) => string` | Enqueue a notification |
-| dismiss | `(id: string) => void` | Dismiss one by id |
-| dismissAll | `() => void` | Dismiss all active |
-
-### useNotificationStore()
-
-Same **`notify`**, **`dismiss`**, and **`dismissAll`** as above, plus **`items`**: `NotificationRecord[]` (active only, excluding items in the exit-animation phase).
+### NotificationCard
+`ref` → `HTMLElement`. A static `<article role="status|alert">` card without a timer: inline confirmations, docs, mockups.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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, 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 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` · `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` | 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
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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` (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 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
+- A fixed, portaled viewport; zones are `--prime-space-5` from the edge (`--prime-space-3` below 640px), at most 24rem wide.
+- Cards in an expanded stack are `--prime-space-2` apart.
+- The viewport takes pointer events only over the cards.
+
+## Accessibility
+
+### 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. |
+
+### 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 |
+|---|---|---|
+| `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. |
+
+## 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.
+- `tone: "error"` → use `tone: "danger"`.
+- Expecting `action` to close the toast → call `dismiss(id)` in `onClick` if it should.
+- A toast for a permanent state («пробный период закончится через 3 дня») → use a Banner.
 
 ## Related
-
-- [Banner](../banner/COMPONENT.md)
-- [Button](../button/COMPONENT.md)
-- [Drawer](../drawer/COMPONENT.md)
-- [Modal](../modal/COMPONENT.md)
-
-## LLM note
-
-- Imports: **`NotificationProvider`**, **`useNotifications`**, **`useNotificationStore`**, **`NotificationCard`**, types **`NotificationOptions`**, **`NotificationRecord`**, **`NotificationPosition`**, **`NotificationType`**, **`NotificationSize`**, **`NotificationAction`** from **`"prime-ui-kit"`**.
-- **`notify`** requires **`type`** and **`title`**; optional **`description`**, **`size`**, **`position`**, **`duration`**, **`persistent`**, **`icon`**, **`badge`**, **`closable`**, **`action`**.
-- **`action`** is not a React node — it is **`{ label: string; onClick: () => void }`**; the kit renders **`Button.Root`** (neutral stroke) inside the card.
-- Stack key = **`position` + `type`**; **`max`** applies per stack, not globally.
-- **`persistent: true`** removes the progress bar and auto-dismiss; closing is manual or via **`dismiss`** / **`dismissAll`**.
-- **`duration <= 0`** disables timer-based dismissal (still closable if **`closable`**).
-- Do not nest **`NotificationProvider`** without a reason; one app root is typical.
-- For static **`NotificationCard`**, build a full **`NotificationRecord`** (including **`id`**, **`position`**, **`size`**, **`duration`**, **`persistent`**, **`closable`**, **`createdAt`**) and wire **`onDismiss`** yourself.
+- **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

@@ -0,0 +1,42 @@
+/* Layout of the Notification scenarios: semantic tokens only. */
+
+/* Static cards in a column about as wide as a toast (24rem). */
+.cards {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+  width: min(100%, calc(var(--prime-space-24) * 4));
+  min-width: 0;
+}
+
+/* Buttons that raise toasts. */
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: var(--prime-space-2);
+}
+
+/* placement.tsx: a 16rem position picker. */
+.select {
+  width: min(100%, calc(var(--prime-space-16) * 4));
+}
+
+/* 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);
+  padding: var(--prime-card-padding-m);
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
+}

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,53 +1,22 @@
-import { NotificationCard, NotificationProvider, type NotificationRecord } from "prime-ui-kit";
+/** Every tier changes padding, icon and text of the card — `size`. */
+import { NotificationCard } from "prime-ui-kit";
 
-function demoItem(
-  overrides: Partial<NotificationRecord> & Pick<NotificationRecord, "id" | "size">,
-): NotificationRecord {
-  return {
-    type: "info",
-    title: `Size ${overrides.size}`,
-    description: "Same type and copy; only the card scale changes.",
-    position: "top-right",
-    duration: 60000,
-    persistent: true,
-    closable: false,
-    createdAt: Date.now(),
-    ...overrides,
-  };
-}
+import styles from "./examples.module.css";
 
-function SizesDemo() {
-  const sizes = (["s", "m", "l"] as const).map((size) =>
-    demoItem({ id: `demo-size-${size}`, size, title: `Size ${size}` }),
-  );
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
+export default function NotificationSizesExample() {
   return (
-    <div
-      style={{
-        display: "flex",
-        flexDirection: "column",
-        gap: "var(--prime-sys-spacing-m)",
-        maxWidth: 420,
-      }}
-    >
-      {sizes.map((item) => (
+    <div className={styles.cards}>
+      {SIZES.map((size) => (
         <NotificationCard
-          key={item.id}
-          item={item}
-          paused={false}
-          onDismiss={() => {}}
-          stackDepth={0}
-          stackExpanded
+          key={size}
+          size={size}
+          title={`Отчёт готов · ${size}`}
+          description="Выгрузка за сентябрь доступна в разделе «Отчёты»."
+          onDismiss={() => undefined}
         />
       ))}
     </div>
   );
 }
-
-export default function SizesExample() {
-  return (
-    <NotificationProvider>
-      <SizesDemo />
-    </NotificationProvider>
-  );
-}