prime-ui-kit 0.13.1 → 0.15.0

package/src/components/modal/examples/enter-key.tsx

@@ -0,0 +1,116 @@
+/** Enter in a dialog: deleting a workspace takes a click, never Enter in its field; in the tags dialog Enter adds the typed tag instead of saving — `confirmOnEnter`, `onEnterConfirm`. */
+import { Badge, Button, Input, Modal } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const WORKSPACE = "Отдел продаж";
+const INITIAL_TAGS = ["VIP", "Опт"];
+
+export default function ModalEnterKeyExample() {
+  const [deleteOpen, setDeleteOpen] = React.useState(false);
+  const [typed, setTyped] = React.useState("");
+  const [tags, setTags] = React.useState(INITIAL_TAGS);
+  const [draft, setDraft] = React.useState("");
+
+  const addTag = () => {
+    const tag = draft.trim();
+    if (tag && !tags.includes(tag)) setTags([...tags, tag]);
+    setDraft("");
+  };
+
+  return (
+    <>
+      <Modal.Root
+        open={deleteOpen}
+        onOpenChange={(next) => {
+          setDeleteOpen(next);
+          setTyped("");
+        }}
+        confirmOnEnter={false}
+      >
+        <Modal.Trigger>
+          <Button.Root variant="outline" tone="danger">
+            Удалить пространство
+          </Button.Root>
+        </Modal.Trigger>
+        <Modal.Content size="s">
+          <Modal.Header>
+            <Modal.Title>Удалить «{WORKSPACE}»?</Modal.Title>
+            <Modal.Description>
+              Сделки, клиенты и счета пространства удалятся без возможности восстановления.
+            </Modal.Description>
+          </Modal.Header>
+          <Modal.Body>
+            <Input.Root label={`Введите «${WORKSPACE}», чтобы подтвердить`}>
+              <Input.Wrapper>
+                <Input.Field value={typed} onValueChange={setTyped} autoComplete="off" />
+              </Input.Wrapper>
+            </Input.Root>
+          </Modal.Body>
+          <Modal.Footer>
+            <Modal.Close>
+              <Button.Root variant="outline" tone="neutral">
+                Отмена
+              </Button.Root>
+            </Modal.Close>
+            {/* The confirm button is a click target only: `confirmOnEnter={false}` keeps Enter off it. */}
+            <Modal.Confirm>
+              <Button.Root
+                tone="danger"
+                disabled={typed !== WORKSPACE}
+                onClick={() => setDeleteOpen(false)}
+              >
+                Удалить
+              </Button.Root>
+            </Modal.Confirm>
+          </Modal.Footer>
+        </Modal.Content>
+      </Modal.Root>
+
+      <Modal.Root
+        onOpenChange={() => setDraft("")}
+        onEnterConfirm={(event) => {
+          event.preventDefault();
+          addTag();
+        }}
+      >
+        <Modal.Trigger>
+          <Button.Root variant="soft" tone="neutral">
+            Теги клиента
+          </Button.Root>
+        </Modal.Trigger>
+        <Modal.Content size="s">
+          <Modal.Header>
+            <Modal.Title>Теги клиента</Modal.Title>
+            <Modal.Description>ООО «Северный ветер»</Modal.Description>
+          </Modal.Header>
+          <Modal.Body>
+            <div className={styles.tags}>
+              {tags.map((tag) => (
+                <Badge.Root key={tag} color="blue">
+                  {tag}
+                </Badge.Root>
+              ))}
+            </div>
+            <Input.Root label="Новый тег" hint="Enter добавляет тег">
+              <Input.Wrapper>
+                <Input.Field value={draft} onValueChange={setDraft} placeholder="Партнёр" />
+              </Input.Wrapper>
+            </Input.Root>
+          </Modal.Body>
+          <Modal.Footer>
+            <Modal.Close>
+              <Button.Root variant="outline" tone="neutral">
+                Отмена
+              </Button.Root>
+            </Modal.Close>
+            <Modal.Close>
+              <Button.Root>Сохранить</Button.Root>
+            </Modal.Close>
+          </Modal.Footer>
+        </Modal.Content>
+      </Modal.Root>
+    </>
+  );
+}

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

@@ -1,21 +1,15 @@
 /* Layout of the Modal scenarios: semantic tokens only. */
 
+/* enter-key.tsx: the client's tags in a wrapping row. */
+.tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2);
+}
+
 /* in-form.tsx: field → field 20 (foundation §1). */
 .form {
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-5);
 }
-
-/* custom-container.tsx: a bounded block (§4) takes the host's card fill so it reads in both themes. */
-.portalHost {
-  position: relative;
-  box-sizing: border-box;
-  display: flex;
-  justify-content: center;
-  width: 100%;
-  padding: var(--prime-space-4);
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-layer-nested);
-  box-shadow: var(--prime-shadow-raised);
-}

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

@@ -1,5 +1,5 @@
-/** 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`. */
-import { Button, Icon, Modal } from "prime-ui-kit";
+/** Optional parts: an icon tile with a header-only notice, and a header with a status before the close button and a footer but no body — `Modal.Icon`, `Modal.Actions`, `Modal.Body`, `Modal.Footer`. */
+import { Badge, Button, Icon, Modal } from "prime-ui-kit";
 
 export default function ModalStructureExample() {
   return (
@@ -35,6 +35,9 @@ export default function ModalStructureExample() {
             <Modal.Description>
               Новые клиенты увидят тариф сразу после публикации.
             </Modal.Description>
+            <Modal.Actions>
+              <Badge.Root color="gray">Черновик</Badge.Root>
+            </Modal.Actions>
           </Modal.Header>
           <Modal.Footer>
             <Modal.Close>

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

@@ -115,7 +115,7 @@ One look, the Select trigger's: field fill, inset control border, tier radius; t
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A labelled system select with a hint; the OS picker opens on phones — `label`, `hint`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; the label and the hint follow the field tier — `size`. |
-| [states.tsx](examples/states.tsx) | A default field next to a disabled and an invalid one — `disabled`, `invalid`. |
+| [states.tsx](examples/states.tsx) | A default field next to a disabled and an invalid one, and one whose focus shows without the ring — `disabled`, `invalid`, `focusRing`. |
 | [validation.tsx](examples/validation.tsx) | Live validation: unassigning the owner shakes the field and drops the error in, picking someone clears it; required and optional markers and a hint — `required`, `optional`, `hint`, `error`. |
 | [option-groups.tsx](examples/option-groups.tsx) | Options under group headings with the native optgroup, and a placeholder while nothing is picked — `placeholder`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value: the plan drives the price under the field — `value`, `onValueChange`. |

package/src/components/native-select/examples/states.tsx

@@ -1,4 +1,4 @@
-/** A default field next to a disabled and an invalid one — `disabled`, `invalid`. */
+/** A default field next to a disabled and an invalid one, and one whose focus shows without the ring — `disabled`, `invalid`, `focusRing`. */
 import { NativeSelect } from "prime-ui-kit";
 
 export default function NativeSelectStatesExample() {
@@ -16,6 +16,10 @@ export default function NativeSelectStatesExample() {
         <option value="viewer">Наблюдатель</option>
         <option value="editor">Редактор</option>
       </NativeSelect>
+      <NativeSelect label="focusRing={false}" defaultValue="editor" focusRing={false}>
+        <option value="viewer">Наблюдатель</option>
+        <option value="editor">Редактор</option>
+      </NativeSelect>
     </>
   );
 }

package/src/components/notification/COMPONENT.md

@@ -152,6 +152,7 @@ Collapsed stacks show up to 3 cards peeking behind each other. Hover or keyboard
 ### 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`.
+- A toast is a non-modal live region, not a layer of the overlay stack: Escape and a press elsewhere belong to the page and to the topmost open layer, so a toast takes no `closeOnEscape` / `closeOnOutsideClick` — it leaves by its timer, the close button, a swipe or `dismiss()`.
 - Do not keep the only copy of important information in a toast with a timer — use `persistent` or a Banner.
 
 ### Labels
@@ -177,7 +178,7 @@ Collapsed stacks show up to 3 cards peeking behind each other. Hover or keyboard
 | [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`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A short timer, a toast that stays until closed, and one without a close button; the close button's name comes from labels — `duration`, `persistent`, `closable`, `labels`. |
 | [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

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

@@ -1,4 +1,4 @@
-/** A short timer, a toast that stays until closed, and one without a close button — `duration`, `persistent`, `closable`. */
+/** A short timer, a toast that stays until closed, and one without a close button; the close button's name comes from labels — `duration`, `persistent`, `closable`, `labels`. */
 import { Button, NotificationProvider, useNotifications } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -43,7 +43,7 @@ function DismissButtons() {
 export default function NotificationDismissExample() {
   // In an app NotificationProvider wraps the root once; here it keeps the example self-contained.
   return (
-    <NotificationProvider>
+    <NotificationProvider labels={{ close: "Скрыть уведомление" }}>
       <DismissButtons />
     </NotificationProvider>
   );

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

@@ -3,12 +3,14 @@
 **Category:** page
 **Kind:** layout
 
-> Page structure inside the main column: title, description, page actions and content sections; a page as high as the panel and the list + detail layout.
+> Page structure inside the main column: title, page actions and content blocks, titled sections and the tile grid of a dashboard; a page as high as the panel and the list + detail layout.
 
 ## When to use
 - Every route rendered inside `AppShell.Main`: a page heading (`<h1>`), an intro line, page-level actions and the page body.
 - A text page held to a reading measure (`PageContent.Root maxWidth="readable"`).
 - A wide dashboard page capped at the content width (`maxWidth="wide"`).
+- The tiles of a dashboard — KPI cards, charts, panels — as one board (`PageContent.Grid` + `PageContent.Cell`).
+- A new topic of the page with its own heading and a link or button beside it (`PageContent.Section`); a settings page with a heading column beside each panel (`layout="aside"`).
 - A page whose body takes the rest of the panel's height — a log table, a board, a chat (`fill`).
 - Mail, a messenger, a ticket queue: a list and the chosen record side by side, one at a time on a narrow panel (`PageContent.Split`).
 
@@ -16,7 +18,8 @@
 - The app frame (navigation rail, header, scrolling main column) → use [AppShell](../../layout/app-shell/COMPONENT.md).
 - A bounded block inside the page → use [Card](../card/COMPONENT.md).
 - An empty / error / not-found page → use [EmptyPage](../empty-page/COMPONENT.md).
-- Arbitrary headings inside content → use [Typography](../typography/COMPONENT.md).
+- A heading inside a card → `Card.Title`; text headings inside prose → use [Typography](../typography/COMPONENT.md).
+- A grid inside one block (thumbnails, fields, bars in a panel) → the block's own CSS grid; `PageContent.Grid` places the page's tiles.
 - Details that open over the list and close again (a record from a table) → use [Drawer](../drawer/COMPONENT.md); `Split` is for a list people work through record by record.
 
 ## Import
@@ -26,12 +29,16 @@ import { PageContent } from "prime-ui-kit";
 
 ## Anatomy
 ```
-PageContent.Root | PageContent.Section     column; Root adds maxWidth and fill, Section renders <section>
+PageContent.Root | PageContent.Page        column; Root adds maxWidth and fill, Page 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.Body                        page content, blocks 24 apart
+   ├─ PageContent.Grid                     12-column tile grid, 16 on both axes; a container (prime-grid)
+   │  └─ PageContent.Cell                  one tile place: span, rows; its child fills it
+   ├─ PageContent.Section                  <section> + <h2> label, 40 from its neighbours
+   │  └─ PageContent.Actions               a link or button at the end of the section heading
    └─ PageContent.Split                    list + detail; a container (prime-split)
       ├─ PageContent.List                  list pane: 16–20rem column, or the whole split while closed
       └─ PageContent.Detail                detail pane: the rest, or the whole split while open
@@ -43,7 +50,7 @@ PageContent.Root | PageContent.Section     column; Root adds maxWidth and fill,
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### PageContent.Root
-`ref` → `HTMLDivElement`. The page column inside `main`: header → body 32 apart, centred under its cap.
+`ref` → `HTMLDivElement`. The page column inside `main`: header → body 24 apart, centred under its cap.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -51,8 +58,8 @@ PageContent.Root | PageContent.Section     column; Root adds maxWidth and fill,
 | `fill` | `boolean` | `false` | The page takes the height of main (`AppShell.Root fillViewport`) and the body takes what the header leaves: for a full-height table, board, chat or `PageContent.Split`. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Header, Body), `className` and the other div attributes. |
 
-### PageContent.Section
-`ref` → `HTMLElement`. The same column as a `<section>`, without a cap; name it with `aria-labelledby` → the Title `id`.
+### PageContent.Page
+`ref` → `HTMLElement`. The whole app page as a `<section>` (the same column, the full panel width); name it with `aria-labelledby` → the Title `id`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -88,12 +95,38 @@ PageContent.Root | PageContent.Section     column; Root adds maxWidth and fill,
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Buttons), `className` and the other div attributes. |
 
 ### PageContent.Body
-`ref` → `HTMLDivElement`. The page content; blocks 40 apart.
+`ref` → `HTMLDivElement`. The page content: blocks of one screen 24 apart, a `PageContent.Section` 40 from its neighbours.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
+### PageContent.Section
+`ref` → `HTMLElement`. A titled section of the page — a `<section>` named by its `h2` (title-m): the heading with an optional description and `PageContent.Actions` at its end, then the content 16 below. Stands 40 from its neighbours in Body.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — (required) | The visible heading (`h2`); it also names the section. |
+| `description` | `ReactNode` | — | One line of context under the heading, in secondary body-s. |
+| `layout` | `"stack" \| "aside"` | `"stack"` | `stack` — the heading over the content; `aside` — a ~16rem heading column beside it (a settings page), above it once the content would get narrower than 30rem. |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "title">` | — | `children` (the content; `PageContent.Actions` goes to the heading row), `className` and the other section attributes. |
+
+### PageContent.Grid
+`ref` → `HTMLDivElement`. The grid of the page's tiles (KPI cards, charts, panels): 12 columns, 16 apart on both axes, so its rows read as one board. A size container: cells fold by its own width (see Grid columns).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (`PageContent.Cell`), `className` and the other div attributes. |
+
+### PageContent.Cell
+`ref` → `HTMLDivElement`. One tile place in `PageContent.Grid`; its child (a Card, a ChartFrame) stretches to it, so the tiles of a row share one height.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `span` | `1 \| 2 \| … \| 12` | `12` | Columns of 12 on a wide grid (64rem+). Narrower grids round it: see Grid columns in COMPONENT.md. |
+| `rows` | `1 \| 2 \| 3 \| 4` | `1` | Rows the cell spans from 40rem: a chart beside two stacked tiles (`ChartFrame.Plot height="fill"` fills the height). |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (one tile), `className` and the other div attributes. |
+
 ### PageContent.Split
 `ref` → `HTMLDivElement`. List + detail (mail, a messenger, a ticket queue): side by side from 48rem of its own width, one pane at a time below it, focus following the pane that comes into view.
 
@@ -141,13 +174,27 @@ PageContent.Root | PageContent.Section     column; Root adds maxWidth and fill,
 | `readable` | Intro line wraps at the reading width | Default, most pages | yes |
 | `full` | Intro uses the full header width | The column is already narrow | |
 
-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; a topic inside Body is a `PageContent.Section` (its `h2`). One primary button in Actions, the rest `soft` / `ghost` neutral.
 
 ### Flags
 | Flag | Looks like when on | Use when | Default |
 |---|---|---|---|
 | `fill` (Root) | the page is as high as main; the body takes what the header leaves; main keeps gutter-high air under it | a full-height table, board, chat or `PageContent.Split` in an `AppShell.Root fillViewport` | `false` |
 
+### layout (Section)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `stack` | the heading row over the content, 16 apart | a topic of a dashboard, a list or a detail page | ✓ |
+| `aside` | a ~16rem heading column beside the content, above it once the content would get < 30rem | a settings page: a heading column beside each panel | |
+
+### Grid columns
+| Grid width | Cell `span` 1–3 | `span` 4 | `span` 5–6 | `span` 7–12 | `rows` |
+|---|---|---|---|---|---|
+| < 30rem | the row | the row | the row | the row | — |
+| 30–40rem | half | the row | the row | the row | — |
+| 40–64rem | half | a third | half | the row | spans |
+| ≥ 64rem | its span | its span | its span | its span | spans |
+
 ### Split layout
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -161,14 +208,18 @@ One `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s
 | filling | `fill` | `data-fill="true"` on Root; `AppShell.Main` drops its long bottom air for it |
 | full-width intro | `measure="full"` | `data-measure="full"` on Description |
 | with actions | `PageContent.Actions` child | `data-has-actions="true"` on Header |
+| section heading column | `layout="aside"` on Section | `data-layout="aside"` on Section (absent for `stack`) |
+| section with actions | `PageContent.Actions` child of Section | `data-has-actions="true"` on the section heading row |
+| tile span | `span` / `rows` on Cell | `data-span="1"…"12"` (always), `data-rows="2"…"4"` (absent for 1) |
 | detail open | `open` / `defaultOpen` on Split | `data-open="true"` on Split; narrow: the list is `display: none`, else the detail is |
 | pane swap | `open` changes on a narrow split | the pane that comes into view enters once (`enterMotion.enterBase`: base, opacity + a 4 px rise); focus moves into the detail, or back to the list control; a wide split moves nothing |
 
 ## 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`; heading → Actions `--prime-space-6` (24) side by side, `--prime-space-4` (16) once they wrap below.
+- Header → Body `--prime-space-6` (24); blocks inside Body `--prime-space-6` (24); a `PageContent.Section` 40 from its neighbours (the body's 24 + `--prime-space-4`); tile → tile in a Grid `--prime-space-4` (16) on both axes; section heading → content `--prime-space-4` (16), heading → description `--prime-space-1` (4); Title → Description `--prime-space-2` (8); buttons in Actions `--prime-space-2`; heading → Actions `--prime-space-6` (24) side by side, `--prime-space-4` (16) once they wrap below.
 - 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`).
+- Grid lays itself out from its own width (container `prime-grid`), never from the window, so a board beside an open Sidebar folds on its own. A Cell stretches its child: the tiles of a row share one height; a chart in a `rows={2}` cell fills it with `ChartFrame.Plot height="fill"`. `dense` flow lets a small tile fill a hole left by a wide one.
 - `fill` needs a main with a height: `AppShell.Root fillViewport` (main scrolls inside the panel). The body passes its free height on to a filling child — DataTable `scrollHeight="fill"`, Crossfade `fill`, `PageContent.Split`.
 - Split takes the free height of a filling page and lays itself out from its own width (container `prime-split`), never from the window: a split beside an open Sidebar may be narrow on a wide screen. Each pane is a column whose last child takes the free height — put a Card with its own `ScrollContainer` there, so the list and the thread scroll separately. The records of the list pane are a [List](../list/COMPONENT.md).
 - The detail pane is on screen all the time on a wide split: while nothing is chosen it shows a short hint («Выберите диалог»), never an empty card.
@@ -182,7 +233,8 @@ One `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s
 
 ### 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.
+- Give `PageContent.Page` an `aria-labelledby` that points at the Title `id` to name the region.
+- `PageContent.Section` is a `<section>` named by its own `<h2>` (`label`) through `aria-labelledby`, so it is a region landmark with the heading's name; the heading levels go h1 (page) → h2 (section) → h3 (a card title inside it).
 - Name `PageContent.List` and `PageContent.Detail` with `aria-label`. On a narrow split opening the detail moves focus into it and going back returns focus to the list control; the hidden pane is `display: none`, out of Tab and the accessibility tree. The panes take focus from code only (`tabindex="-1"`, no ring).
 - `PageContent.BackButton` is named by `labels.back` and is shown only while the split shows one pane.
 
@@ -198,18 +250,23 @@ One `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s
 |---|---|
 | [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`. |
+| [grid.tsx](examples/grid.tsx) | A dashboard board: four KPI tiles, a chart two rows high beside two panels, one gap on both axes — `PageContent.Grid`, `PageContent.Cell`, `span`, `rows`. |
+| [sections.tsx](examples/sections.tsx) | A page with titled sections: tiles of one screen close together, a new topic set off by air, a link at the end of the heading, a heading column beside a panel — `PageContent.Section`, `label`, `description`, `PageContent.Actions`, `layout`. |
 | [list-detail.tsx](examples/list-detail.tsx) | A support inbox as list + detail on a full-height page: side by side on a wide panel, one pane at a time with a back button on a narrow one — `PageContent.Split`, `PageContent.BackButton`, `fill`. |
 | [narrow.tsx](examples/narrow.tsx) | In a phone-width column the page actions wrap under the heading instead of squeezing it. |
+| [screen.tsx](examples/screen.tsx) | A settings page: sections with a heading column and a panel, a form saved by its own button, switches that apply at once and a danger zone with a confirm — `layout`, `maxWidth`. |
 
 ## Mistakes
 - Padding on `PageContent.Root` to imitate gutters → gutters come from `AppShell.Main`.
 - Actions placed outside Header → put `PageContent.Actions` inside `PageContent.Header` so it aligns with the title and wraps.
-- Several `PageContent.Title` on one page → one `<h1>`, sub-headings via Typography.
-- Margins between blocks in Body → Body already sets the 40 gap.
+- Several `PageContent.Title` on one page → one `<h1>`; a topic of the page is a `PageContent.Section` with its `<h2>`.
+- A hand-made `<section>` + `Typography as="h2"` + own gap CSS → `PageContent.Section label`.
+- Each row of cards in its own auto-fit grid → the rows stand 24 apart instead of 16; put every tile of the screen in one `PageContent.Grid`.
+- Margins between blocks in Body → Body already sets the 24 gap and the 40 around a Section.
 - Computing a height from `100vh` minus the header for a full-height table or chat → `PageContent.Root fill` and a filling child.
 - A list + detail built with window media queries → `PageContent.Split` follows its own width.
 - Unmounting the detail content the moment the narrow split goes back → keep the last record until another is chosen (the pane leaves with it on screen).
 
 ## Related
 - **Built from:** [Button](../button/COMPONENT.md) (`PageContent.BackButton`), Icon (`nav.chevronLeft`)
-- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [List](../list/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Drawer](../drawer/COMPONENT.md)
+- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [ChartFrame](../chart-frame/COMPONENT.md), [List](../list/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Drawer](../drawer/COMPONENT.md)

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

@@ -0,0 +1,107 @@
+/** A dashboard board: four KPI tiles, a chart two rows high beside two panels, one gap on both axes — `PageContent.Grid`, `PageContent.Cell`, `span`, `rows`. */
+import { Card, ChartFrame, type ChartFrameSeries, chartColors, PageContent } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const KPIS = [
+  { label: "Выручка", value: "4,8 млн ₽", delta: "+12% к сентябрю", tone: "success" },
+  { label: "Заказы", value: "1 284", delta: "+6% к сентябрю", tone: "success" },
+  { label: "Средний чек", value: "3 740 ₽", delta: "−2% к сентябрю", tone: "danger" },
+  { label: "Возвраты", value: "1,8%", delta: "без изменений", tone: "neutral" },
+] as const;
+
+const SERIES: ChartFrameSeries[] = [{ id: "orders", label: "Заказы" }];
+
+const WEEKS = [
+  { week: "1 нед", orders: 268 },
+  { week: "2 нед", orders: 301 },
+  { week: "3 нед", orders: 287 },
+  { week: "4 нед", orders: 334 },
+  { week: "5 нед", orders: 352 },
+];
+
+const MARGIN = { top: 8, right: 8, bottom: 24, left: 8 };
+
+const formatOrders = (value: number) => `${value.toLocaleString("ru-RU")} заказов`;
+
+export default function PageContentGridExample() {
+  return (
+    <div className={styles.main}>
+      <PageContent.Body>
+        <PageContent.Grid>
+          {KPIS.map((kpi) => (
+            <PageContent.Cell key={kpi.label} span={3}>
+              <Card.Root variant="stat-trend">
+                <Card.Label>{kpi.label}</Card.Label>
+                <Card.Value>{kpi.value}</Card.Value>
+                <Card.Delta tone={kpi.tone}>{kpi.delta}</Card.Delta>
+              </Card.Root>
+            </PageContent.Cell>
+          ))}
+          <PageContent.Cell span={8} rows={2}>
+            <ChartFrame.Root series={SERIES} formatValue={formatOrders}>
+              <ChartFrame.Header>
+                <ChartFrame.Title>Заказы по неделям</ChartFrame.Title>
+                <ChartFrame.Description>Октябрь</ChartFrame.Description>
+              </ChartFrame.Header>
+              <ChartFrame.Plot
+                height="fill"
+                renderPlot={({ width, height, series }) => {
+                  const max = Math.max(...WEEKS.map((w) => w.orders));
+                  const innerW = width - MARGIN.left - MARGIN.right;
+                  const innerH = height - MARGIN.top - MARGIN.bottom;
+                  const slot = innerW / WEEKS.length;
+                  const bar = slot * 0.56;
+                  return (
+                    <svg width={width} height={height} aria-hidden="true">
+                      <line
+                        x1={MARGIN.left}
+                        x2={width - MARGIN.right}
+                        y1={MARGIN.top + innerH}
+                        y2={MARGIN.top + innerH}
+                        stroke={chartColors.axis}
+                      />
+                      {WEEKS.map((w, i) => {
+                        const h = (innerH * w.orders) / max;
+                        const x = MARGIN.left + slot * i + (slot - bar) / 2;
+                        return (
+                          <g key={w.week} data-hidden={series[0].hidden}>
+                            <rect
+                              x={x}
+                              y={MARGIN.top + innerH - h}
+                              width={bar}
+                              height={h}
+                              rx={4}
+                              fill={series[0].color}
+                            />
+                            <text x={x + bar / 2} y={height - 4} textAnchor="middle">
+                              {w.week}
+                            </text>
+                          </g>
+                        );
+                      })}
+                    </svg>
+                  );
+                }}
+              />
+            </ChartFrame.Root>
+          </PageContent.Cell>
+          <PageContent.Cell span={4}>
+            <Card.Root variant="stat-trend">
+              <Card.Label>Новые клиенты</Card.Label>
+              <Card.Value>86</Card.Value>
+              <Card.Delta tone="success">+14 к сентябрю</Card.Delta>
+            </Card.Root>
+          </PageContent.Cell>
+          <PageContent.Cell span={4}>
+            <Card.Root variant="stat-trend">
+              <Card.Label>Ждут оплаты</Card.Label>
+              <Card.Value>312 400 ₽</Card.Value>
+              <Card.Delta tone="warning">7 счетов</Card.Delta>
+            </Card.Root>
+          </PageContent.Cell>
+        </PageContent.Grid>
+      </PageContent.Body>
+    </div>
+  );
+}

package/src/components/page-content/examples/list-detail.tsx

@@ -45,9 +45,6 @@ export default function PageContentListDetailExample() {
   return (
     <div className={styles.fillMain}>
       <PageContent.Root fill>
-        <PageContent.Header>
-          <PageContent.Title>Обращения</PageContent.Title>
-        </PageContent.Header>
         <PageContent.Body>
           <PageContent.Split
             open={dialogId !== null}

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

@@ -6,7 +6,7 @@ import styles from "./examples.module.css";
 export default function PageContentOverviewExample() {
   return (
     <div className={styles.main}>
-      <PageContent.Section aria-labelledby="settings-heading">
+      <PageContent.Page aria-labelledby="settings-heading">
         <PageContent.Header>
           <PageContent.Title id="settings-heading">Настройки</PageContent.Title>
           <PageContent.Description>
@@ -35,7 +35,7 @@ export default function PageContentOverviewExample() {
             </Card.Body>
           </Card.Root>
         </PageContent.Body>
-      </PageContent.Section>
+      </PageContent.Page>
     </div>
   );
 }

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

@@ -0,0 +1,27 @@
+/* Settings page: each section is a PageContent.Section layout="aside"; here only the panels' insides. */
+
+/* Field → field 20. */
+
+/* Two short related fields side by side when there is room; tops aligned. */
+.pair {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-16) * 3)), 1fr));
+  align-items: start;
+  gap: var(--prime-space-5);
+}
+
+/* Danger zone row: text takes the room, the button stays at the end and wraps under it. */
+.danger {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+}
+
+.dangerText {
+  display: grid;
+  flex: 1 1 calc(var(--prime-space-16) * 4);
+  gap: var(--prime-space-1);
+  min-width: 0;
+}