prime-ui-kit 0.9.0 → 0.9.1

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

@@ -0,0 +1,45 @@
+/** Toasts of one position and tone stack; hover expands the stack and pauses the timers — `max`, `items`, `dismissAll`. */
+import { Button, NotificationProvider, Typography, useNotifications } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+function StackControls() {
+  const { notify, dismissAll, items } = useNotifications();
+  return (
+    <div className={styles.row}>
+      <Button.Root
+        variant="outline"
+        tone="neutral"
+        onClick={() =>
+          notify({
+            tone: "success",
+            title: "Заказ оформлен",
+            description: `№ ${48_213 + items.length}, доставка завтра.`,
+          })
+        }
+      >
+        Оформить заказ
+      </Button.Root>
+      <Button.Root
+        variant="ghost"
+        tone="neutral"
+        disabled={items.length === 0}
+        onClick={dismissAll}
+      >
+        Закрыть все
+      </Button.Root>
+      <Typography as="span" variant="body-s" tone="secondary">
+        Активных: {items.length}
+      </Typography>
+    </div>
+  );
+}
+
+export default function NotificationStackingExample() {
+  // In an app NotificationProvider wraps the root once; here it keeps the example self-contained.
+  return (
+    <NotificationProvider max={4}>
+      <StackControls />
+    </NotificationProvider>
+  );
+}

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

@@ -0,0 +1,20 @@
+/** Optional parts on static cards: a custom icon, a counter, an action and a close button, or a title alone — `icon`, `badge`, `action`, `onDismiss`. */
+import { Icon, NotificationCard } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function NotificationStructureExample() {
+  return (
+    <div className={styles.cards}>
+      <NotificationCard
+        title="Новые ответы в обсуждении"
+        description="Мария и ещё двое ответили на ваш комментарий."
+        icon={<Icon name="object.message" />}
+        badge={3}
+        action={{ label: "Открыть", onClick: () => undefined }}
+        onDismiss={() => undefined}
+      />
+      <NotificationCard tone="success" title="Ссылка скопирована" />
+    </div>
+  );
+}

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

@@ -1,36 +1,24 @@
-/** The four tones as static `NotificationCard`s: the tone icon carries the meaning, the card is a raised surface without a border. Use static cards for docs and mockups; in an app toasts come from `notify()`. */
-import { NotificationCard, type NotificationRecord } from "prime-ui-kit";
+/** The four tones: the icon carries the meaning; danger and warning are announced at once — `tone`. */
+import { NotificationCard } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const copy: Record<NotificationRecord["tone"], [string, string]> = {
-  success: ["Изменения сохранены", "Профиль компании обновлён."],
-  info: ["Обновление ночью", "Сервис будет недоступен с 02:00 до 03:00."],
-  warning: ["Заканчивается подписка", "Через 3 дня закончится оплаченный период."],
-  danger: ["Не удалось отправить", "Проверьте соединение и повторите попытку."],
-};
-
-function card(tone: NotificationRecord["tone"]): NotificationRecord {
-  const [title, description] = copy[tone];
-  return {
-    id: `tones-${tone}`,
-    tone,
-    title,
-    description,
-    position: "top-right",
-    size: "m",
-    duration: 0,
-    persistent: true,
-    closable: true,
-    createdAt: 0,
-  };
-}
+const TONES = [
+  { tone: "success", title: "Изменения сохранены", description: "Профиль компании обновлён." },
+  { tone: "info", title: "Обновление ночью", description: "Сервис недоступен с 02:00 до 03:00." },
+  {
+    tone: "warning",
+    title: "Заканчивается подписка",
+    description: "Оплата закончится через 3 дня.",
+  },
+  { tone: "danger", title: "Не удалось отправить", description: "Проверьте соединение." },
+] as const;
 
 export default function NotificationTonesExample() {
   return (
     <div className={styles.cards}>
-      {(["success", "info", "warning", "danger"] as const).map((tone) => (
-        <NotificationCard key={tone} item={card(tone)} paused onDismiss={() => {}} />
+      {TONES.map((item) => (
+        <NotificationCard key={item.tone} {...item} onDismiss={() => undefined} />
       ))}
     </div>
   );

package/src/components/page-content/COMPONENT.md

@@ -1,6 +1,7 @@
 # PageContent
 
 **Category:** layout
+**Kind:** layout
 
 > Page structure inside the main column: title, description, page actions and content sections.
 
@@ -23,86 +24,67 @@ import { PageContent } from "prime-ui-kit";
 ## Anatomy
 ```
 PageContent.Root | PageContent.Section     column; Root adds maxWidth, Section renders <section>
-├── PageContent.Header                     heading column + actions in one wrapping row
-│   ├── PageContent.Title                  <h1>, heading-m
-│   ├── PageContent.Description            <p>, secondary body-m
-│   └── PageContent.Actions                page buttons (moved to the end of the header row)
-└── PageContent.Body                       page content, blocks 40 apart
+├─ PageContent.Header                      heading column + actions in one wrapping row
+│  ├─ PageContent.Title                    <h1>, heading-m
+│  ├─ PageContent.Description              <p>, secondary body-m
+│  └─ PageContent.Actions                  page buttons (moved to the end of the header row)
+└─ PageContent.Body                        page content, blocks 40 apart
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### PageContent.Root
-`forwardRef` to `<div>`.
+`ref` → `HTMLDivElement`. The page column inside `main`: header → body 32 apart, centred under its cap.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `maxWidth` | `"full" \| "readable" \| "wide"` | `"full"` | Max width of the column (centred with `margin-inline: auto`). |
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Header, Body. |
-
-+ native `<div>` props.
+| `maxWidth` | `"full" \| "readable" \| "wide"` | `"full"` | Cap of the column: the whole main, `--prime-layout-content-max-width`, or a ~65ch reading measure. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Header, Body), `className` and the other div attributes. |
 
 ### PageContent.Section
-`forwardRef` to `<section>`. Same column and rhythm as Root, without `maxWidth`.
+`ref` → `HTMLElement`. The same column as a `<section>`, without a cap; name it with `aria-labelledby` → the Title `id`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Header, Body. |
-
-+ native `<section>` props (`HTMLAttributes<HTMLElement>`; use `aria-labelledby` pointing at the Title `id`).
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `aria-labelledby`, `className` and the other section attributes. |
 
 ### PageContent.Header
-Plain function component (no ref). Children of type `PageContent.Actions` are moved after the heading column; all other children go into the heading column.
+`ref` → `HTMLDivElement`. Heading column and page actions in one wrapping row; `PageContent.Actions` children move to the end.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Title, Description, Actions. |
-
-+ native `<div>` props.
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Title, Description, Actions), `className` and the other div attributes. |
 
 ### PageContent.Title
-`forwardRef` to `<h1>`.
+`ref` → `HTMLHeadingElement`. The page `<h1>` in heading-m.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Page title. |
-
-+ native `<h1>` props.
+| `…rest` | `HTMLAttributes<HTMLHeadingElement>` | — | `children`, `id`, `className` and the other heading attributes. |
 
 ### PageContent.Description
-`forwardRef` to `<p>`.
+`ref` → `HTMLParagraphElement`. Intro `<p>` in secondary body-m.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `measure` | `"readable" \| "full"` | `"readable"` | `readable` caps the line at the reading width; `full` uses the full width of the parent. |
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Intro text. |
-
-+ native `<p>` props.
+| `measure` | `"readable" \| "full"` | `"readable"` | `readable` — max ~65ch; `full` — the full width of the parent. |
+| `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `children`, `className` and the other paragraph attributes. |
 
 ### PageContent.Actions
-Plain function component (no ref).
+`ref` → `HTMLDivElement`. Page-level buttons next to the title; they wrap under the heading on narrow columns.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Page buttons. |
-
-+ native `<div>` props.
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Buttons), `className` and the other div attributes. |
 
 ### PageContent.Body
-Plain function component (no ref).
+`ref` → `HTMLDivElement`. The page content; blocks 40 apart.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Page content blocks. |
-
-+ native `<div>` props.
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ## Variants
 
@@ -117,51 +99,43 @@ Plain function component (no ref).
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `readable` | Intro line wraps at the reading width | Default, most pages | yes |
-| `full` | Intro uses the full header width | The column is already narrow, or the intro sits next to actions | |
-
-**Combinations** — `Root maxWidth="readable"` with the default Description measure for text pages; `Section` + `measure="full"` + `Actions` for app pages. `Description measure="full"` inside `Root maxWidth="readable"` changes nothing visible.
+| `full` | Intro uses the full header width | The column is already narrow | |
 
-**Hierarchy** — one `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s` / `title-m` headings (`h2`). One primary button in Actions, the rest `soft`/`ghost` neutral.
+One `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s` / `title-m` headings (`h2`). One primary button in Actions, the rest `soft` / `ghost` neutral.
 
 ## States
-Static layout. DOM: `data-max-width="readable" | "wide"` on Root (absent for `full`), `data-measure="full"` on Description (absent for `readable`), `data-has-actions="true"` on Header when it contains Actions.
+| State | Driven by | DOM |
+|---|---|---|
+| capped column | `maxWidth` | `data-max-width="readable" \| "wide"` on Root (absent for `full`) |
+| full-width intro | `measure="full"` | `data-measure="full"` on Description |
+| with actions | `PageContent.Actions` child | `data-has-actions="true"` on Header |
 
 ## Layout & spacing
 - No outer padding: edge gutters come from `AppShell.Main`.
 - Header → Body `--prime-space-8` (32); blocks inside Body `--prime-space-10` (40); Title → Description `--prime-space-2` (8); buttons in Actions `--prime-space-2`.
-- Header is a wrapping row (`gap: --prime-space-4` / `--prime-space-6`): actions stay to the right of the title while the heading keeps half a reading measure, otherwise wrap below it — no breakpoint needed, works from 320px.
+- Header is a wrapping row: actions stay to the right of the title while the heading keeps half a reading measure, otherwise they wrap below it — no breakpoint needed, works from 320px.
 - Title and Description wrap long words (`overflow-wrap: anywhere`).
 
 ## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
 - Title is an `<h1>`; use one per page.
 - Give `PageContent.Section` an `aria-labelledby` that points at the Title `id` to name the region.
-- No keyboard behaviour, no `labels`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [settings-page.tsx](examples/settings-page.tsx) | Section with title, description, actions and panel cards in Body | App pages with page-level actions |
-| [readable.tsx](examples/readable.tsx) | `Root maxWidth="readable"` with reading text | Terms, articles, help pages |
-| [widths.tsx](examples/widths.tsx) | `Root maxWidth` full · wide · readable side by side | Choosing the column cap |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```tsx
-import { Button, PageContent } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <PageContent.Section>
-      <PageContent.Header>
-        <PageContent.Title>Заказы</PageContent.Title>
-        <PageContent.Description>Все заказы за последний месяц.</PageContent.Description>
-        <PageContent.Actions>
-          <Button.Root>Создать заказ</Button.Root>
-        </PageContent.Actions>
-      </PageContent.Header>
-      <PageContent.Body>…</PageContent.Body>
-    </PageContent.Section>
-  );
-}
-```
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A page in the main column: title, description and page actions, then the body blocks — `PageContent.Actions`. |
+| [variants.tsx](examples/variants.tsx) | The same page column at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. |
+| [narrow.tsx](examples/narrow.tsx) | In a phone-width column the page actions wrap under the heading instead of squeezing it. |
 
 ## Mistakes
 - Padding on `PageContent.Root` to imitate gutters → gutters come from `AppShell.Main`.
@@ -170,4 +144,5 @@ export function Example() {
 - Margins between blocks in Body → Body already sets the 40 gap.
 
 ## Related
-[AppShell](../../layout/app-shell/COMPONENT.md) · [Sidebar](../../layout/sidebar/COMPONENT.md) · [Card](../card/COMPONENT.md) · [EmptyPage](../empty-page/COMPONENT.md)
+- **Built from:** —
+- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)

package/src/components/page-content/examples/examples.module.css

@@ -1,4 +1,4 @@
-/* Layout for the PageContent examples: the frame imitates AppShell.Main (canvas + gutter). */
+/* Layout of the PageContent scenarios: the frame imitates AppShell.Main (canvas + gutter). */
 
 .main {
   box-sizing: border-box;
@@ -16,11 +16,7 @@
   gap: var(--prime-space-10);
 }
 
-/* A visible block so the column width can be read at a glance. */
-.block {
-  box-sizing: border-box;
-  padding: var(--prime-space-4);
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
+/* A phone-width main column (360px). */
+.narrow {
+  width: min(100%, calc(var(--prime-space-24) * 3.75));
 }

package/src/components/page-content/examples/narrow.tsx

@@ -0,0 +1,25 @@
+/** In a phone-width column the page actions wrap under the heading instead of squeezing it. */
+import { Button, PageContent } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function PageContentNarrowExample() {
+  return (
+    <div className={styles.narrow}>
+      <div className={styles.main}>
+        <PageContent.Root>
+          <PageContent.Header>
+            <PageContent.Title>Счета</PageContent.Title>
+            <PageContent.Description>Выставленные и оплаченные за квартал.</PageContent.Description>
+            <PageContent.Actions>
+              <Button.Root variant="soft" tone="neutral">
+                Экспорт
+              </Button.Root>
+              <Button.Root>Новый счёт</Button.Root>
+            </PageContent.Actions>
+          </PageContent.Header>
+        </PageContent.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/page-content/examples/overview.tsx

@@ -0,0 +1,41 @@
+/** A page in the main column: title, description and page actions, then the body blocks — `PageContent.Actions`. */
+import { Button, Card, PageContent, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function PageContentOverviewExample() {
+  return (
+    <div className={styles.main}>
+      <PageContent.Section aria-labelledby="settings-heading">
+        <PageContent.Header>
+          <PageContent.Title id="settings-heading">Настройки</PageContent.Title>
+          <PageContent.Description>
+            Профиль рабочего пространства и уведомления.
+          </PageContent.Description>
+          <PageContent.Actions>
+            <Button.Root variant="soft" tone="neutral">
+              Экспорт
+            </Button.Root>
+            <Button.Root>Сохранить</Button.Root>
+          </PageContent.Actions>
+        </PageContent.Header>
+        <PageContent.Body>
+          <Card.Root variant="panel">
+            <Card.Body>
+              <Typography variant="body-m" tone="secondary">
+                Компания «Прайм Софт», часовой пояс Москва (UTC+3), валюта — рубль.
+              </Typography>
+            </Card.Body>
+          </Card.Root>
+          <Card.Root variant="panel">
+            <Card.Body>
+              <Typography variant="body-m" tone="secondary">
+                Письма о новых заказах и сводка по понедельникам включены.
+              </Typography>
+            </Card.Body>
+          </Card.Root>
+        </PageContent.Body>
+      </PageContent.Section>
+    </div>
+  );
+}

package/src/components/page-content/examples/variants.tsx

@@ -0,0 +1,39 @@
+/** The same page column at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. */
+import { Card, PageContent, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const WIDTHS = [
+  { value: "full", title: "Сделки", text: "Колонка занимает всю ширину main." },
+  { value: "wide", title: "Дашборд продаж", text: "Не шире ширины контента, по центру." },
+  {
+    value: "readable",
+    title: "Условия использования",
+    text: "Около 65 знаков в строке, по центру.",
+  },
+] as const;
+
+export default function PageContentVariantsExample() {
+  return (
+    <div className={styles.main}>
+      <div className={styles.stack}>
+        {WIDTHS.map(({ value, title, text }) => (
+          <PageContent.Root key={value} maxWidth={value}>
+            <PageContent.Header>
+              <PageContent.Title>{title}</PageContent.Title>
+            </PageContent.Header>
+            <PageContent.Body>
+              <Card.Root>
+                <Card.Body>
+                  <Typography variant="body-s" tone="secondary">
+                    {value} — {text}
+                  </Typography>
+                </Card.Body>
+              </Card.Root>
+            </PageContent.Body>
+          </PageContent.Root>
+        ))}
+      </div>
+    </div>
+  );
+}