prime-ui-kit 0.17.0 → 0.19.0

package/src/components/switch/COMPONENT.md

@@ -46,6 +46,7 @@ Switch.Root          field grid; ref and input props go to the native input (rol
 | `optional` | `boolean` | `false` | Muted `labels.optional` after the label text; the field may stay off. |
 | `labels` | `Partial<SwitchLabels>` | — | Built-in strings, see Labels. |
 | `hint` | `ReactNode` | — | Help text under the label text. Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger ring on the off track and `aria-invalid`. A non-empty `error` implies it. |
 | `disabled` | `boolean` | `false` | No toggling; muted track (on = `accent-soft`), dimmed text and hint. |

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

@@ -60,6 +60,7 @@ TagSelect                       field frame: label · control · hint/error (sin
 | `onOptionDelete` | `(value: string) => void \| Promise<void>` | — | Enables «Удалить» in the row menu; the value also leaves the selection. A returned Promise defers it: resolve deletes, reject keeps everything (e.g. after a confirmation). |
 | `label` | `ReactNode` | — | Field label above; names the input. |
 | `hint` | `ReactNode` | — | Support text under the field; linked by `aria-describedby`. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message; replaces the hint and implies `invalid`. |
 | `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the input. |
 | `optional` | `boolean` | — | Muted `labels.optional` after the label. |

package/src/components/textarea/COMPONENT.md

@@ -46,6 +46,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `required` | `boolean` | — | Native `required` on the textarea and a red `*` after the label (`aria-hidden`). |
 | `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the field. Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger inset ring on the field box, `aria-invalid` on the textarea. A non-empty `error` implies it. |
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring on the field box (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay. |

package/src/components/timeline/COMPONENT.md

@@ -27,7 +27,7 @@ Timeline.Root                    size container, sets the tier (size, else the h
 └─ Timeline.Group label          labelled <ol role="list">; the line runs from its first dot to its last
    ├─ Timeline.Item              <li> + row (div | button | a | asChild element) with the dot
    │  ├─ Timeline.ItemTitle      first line
-   │  ├─ Timeline.ItemMeta       second line (date); <strong> emphasizes a part
+   │  ├─ Timeline.ItemMeta       second line (date); <strong> emphasizes a part; repeats, lines stack
    │  └─ Timeline.ItemValue      trailing amount
    │     └─ Timeline.ItemMeta    second line under the amount
    └─ Timeline.Gap               <li>: interval between events (dashed segment, hollow dot)
@@ -73,7 +73,7 @@ Timeline.Root                    size container, sets the tier (size, else the h
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "color" \| "onClick">` | — | The other row attributes (`target`, `rel`, `download` with `href`). |
 
 ### Timeline.ItemTitle · Timeline.ItemMeta
-`ref` → `HTMLSpanElement`. `<span>` lines: the event (medium, accent on the highlighted row, wraps) and the muted secondary line with tabular numbers — under the title the date (emphasize a part with `<strong>`), inside `Timeline.ItemValue` the value's second line.
+`ref` → `HTMLSpanElement`. `<span>` lines: the event (medium, wraps) and the muted secondary line, tabular — under the title the date (`<strong>` emphasizes a part; several `Timeline.ItemMeta` stack), inside `Timeline.ItemValue` the value's second line.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -180,7 +180,7 @@ No `labels`.
 | [overview.tsx](examples/overview.tsx) | An operations feed: one labelled group, a line through the dots, the row under the pointer highlighted — `Timeline.Group`, `Timeline.ItemValue`. |
 | [variants.tsx](examples/variants.tsx) | Dot hues for categories at reduced emphasis, and status tones on items, values and gaps at full emphasis — `color`, `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier scales text, dot and row rhythm, rows 40 to 76 px — `size`. |
-| [structure.tsx](examples/structure.tsx) | A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.Description`, `Timeline.ItemMeta`. |
+| [structure.tsx](examples/structure.tsx) | A service history with intervals between events, a caption on the right of a gap, two meta lines under a repair and a second value line — `Timeline.Gap`, `Timeline.Description`, `Timeline.ItemMeta`. |
 | [links.tsx](examples/links.tsx) | Rows that open something: an operation page by a link or by your router link through the slot, a receipt in place by a button; one Tab stop each with a focus ring — `href`, `asChild`, `onClick`. |
 | [narrow.tsx](examples/narrow.tsx) | At 375 px the title wraps and the amount stays right; below 20rem of its own width the amount moves under the meta line — `Timeline.ItemValue`. |
 

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

@@ -1,4 +1,4 @@
-/** A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.Description`, `Timeline.ItemMeta`. */
+/** A service history with intervals between events, a caption on the right of a gap, two meta lines under a repair and a second value line — `Timeline.Gap`, `Timeline.Description`, `Timeline.ItemMeta`. */
 import { Timeline } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -36,6 +36,7 @@ export default function TimelineStructureExample() {
           <Timeline.ItemMeta>
             <strong>07.06.26</strong> · 12 100 км
           </Timeline.ItemMeta>
+          <Timeline.ItemMeta>Мастер Олег Смирнов · гарантия 6 месяцев</Timeline.ItemMeta>
           <Timeline.ItemValue>
             2 800 ₽<Timeline.ItemMeta>Ремонт</Timeline.ItemMeta>
           </Timeline.ItemValue>

package/src/layout/app-shell/COMPONENT.md

@@ -126,8 +126,8 @@ The navigation of the nearest `AppShell.Root` for a trigger outside the rail (a
 
 ## Layout & spacing
 - Two full-height planes edge to edge: no inset, radius, shadow or border — the boundary is the fill change (the Sidebar rail is layer 1, the panel the page: white rail beside a gray page in light, a rail one step lighter than the near-black page in dark).
-- Main hands the page its edge air: `--page-gutter` is the page gutter `--prime-layout-gutter` — `--prime-layout-gutter-s` (16) → `-m` (24) from 640px → `-l` (32) from 1024px; `--page-top` is `--prime-space-6` (24) → `--prime-space-8` (32) from 1024px. `Page.Root` pads itself with them (its top bar steps out to the panel's edges). Main itself pads only the bottom: `--prime-space-16`. Inside Main the page gutter is the small one again, so a frame nested in the page starts from its own gutter, not the shell's.
-- A page that fills the panel height (`Page.Root fill`): Main's bottom padding drops to the side gutter, so no long scroll tail stays under it.
+- Main hands the page its edge air: `--page-gutter` is the page gutter `--prime-layout-gutter` — `--prime-layout-gutter-s` (16) → `-m` (24) from 640px → `-l` (32) from 1024px; `--page-top` is `--prime-space-6` (24) → `--prime-space-8` (32) from 1024px. `Page.Root` pads itself with them (its top bar steps out to the panel's edges). Main itself pads only the bottom: `--prime-space-16`, the scroll tail of a long page. Inside Main the page gutter is the small one again, so a frame nested in the page starts from its own gutter, not the shell's.
+- A page that fills the panel height (`Page.Root fill`): Main's bottom padding drops to the side gutter, so no long scroll tail stays under it — beside the Sidebar rail too.
 - Main scrolls with `overscroll-behavior: contain`, so its scroll never chains to the document.
 - Nav column: sticky at the top, viewport high, `z-index: --prime-z-sticky` (above the panel, so the compact Sidebar toggle can ride the rail edge); with `fillViewport` it fills the shell height instead.
 - Footer: no padding of its own (BottomNav keeps the bottom safe-area inset), sticky at the bottom, `z-index: --prime-z-sticky`.

package/src/layout/bottom-nav/COMPONENT.md

@@ -107,6 +107,7 @@ Without flags the bar is flat at the screen edge on the surface, with a faint to
 | State | Driven by | DOM |
 |---|---|---|
 | current | `current` or a router link setting `aria-current` | `aria-current="page"` on the item; flat, its glyph on a `fill-muted` pill |
+| held | a `Page.Guard` that is `busy` or `dirty` on the page | a press on an item stops before it navigates (a router link included); `dirty` asks first, then repeats it |
 | pressed | pointer down | the glyph scales to `--prime-motion-press-scale-compact` (`internal/press`), flat and floating |
 | overflow | items wider than the bar | the items scroll inside the bar with faded edges; no label is cut |
 | focus | keyboard | focus ring inside the item edge |

package/src/layout/page/COMPONENT.md

@@ -12,14 +12,15 @@
 - A nested record: a `Breadcrumb` path in `Page.Heading`; in the bar the title reads as its last level.
 - A text page held to a reading measure (`maxWidth="readable"`), a wide dashboard capped at the content width (`maxWidth="wide"`).
 - The tiles of a dashboard — KPI cards, charts, panels — as one board (`Page.Grid` + `Page.Cell`).
-- A new topic of the page with its own heading and a link or button beside it (`Page.Section`); a settings page with a heading column beside each panel (`layout="aside"`).
+- A new topic of the page with its own heading and a link or button beside it (`Page.Section`, the heading over its content).
 - 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 (`Page.Split`).
+- A form that is the whole page (a record's editor, settings with one save): `Page.Guard dirty busy` holds leaving it through the navigation, the path and the browser.
 
 ## When not to use
 - The app frame (navigation rail, scrolling main, phone footer) → use [AppShell](../app-shell/COMPONENT.md); there is no global app header — a bar belongs to its page.
 - A search across the whole app → a page of its own or a [CommandMenu](../../components/command-menu/COMPONENT.md); the top bar carries only what its page needs.
-- A bounded block inside the page → use [Card](../../components/card/COMPONENT.md).
+- A bounded block inside the page, a titled panel of a settings page included → use [Card](../../components/card/COMPONENT.md) with its own `Card.Header`.
 - An empty / error / not-found page → use [EmptyPage](../../components/empty-page/COMPONENT.md).
 - A heading inside a card → `Card.Title`; text headings inside prose → use [Typography](../../components/typography/COMPONENT.md).
 - A grid inside one block (thumbnails, fields, bars in a panel) → the block's own CSS grid; `Page.Grid` places the page's tiles.
@@ -33,6 +34,7 @@ import { Page } from "prime-ui-kit";
 ## Anatomy
 ```
 Page.Root                          the page column (<div>); maxWidth, fill, labels
+├─ Page.Guard                      no DOM: holds leaving the page; busy, dirty (anywhere inside)
 ├─ Page.TopBar                     <header> strip at the top edge, sticky; sticky, collapse
 │  │                               (+ the menu button while the Sidebar is off-canvas)
 │  │                               groups in any JSX order, rendered in this order:
@@ -43,7 +45,8 @@ Page.Root                          the page column (<div>); maxWidth, fill, labe
 │  ├─ Page.Tools                   the page's controls in the order written, one wrapper each
 │  │  ├─ SegmentedControl.Root     sections, view (fullWidth unless set)
 │  │  ├─ SmartFilter.Toolbar       search and filter: grows first on a line of its own
-│  │  └─ Select.Root …             a period, columns
+│  │  ├─ Datepicker.Root           a period (fullWidth unless set)
+│  │  └─ Select.Root …             a period, columns; the trigger fills its place
 │  ├─ Page.Actions                 every button of the page; icons, then «⋯» when short
 │  └─ Page.Chips                   SmartFilter.Chips on a line under everything
 ├─ Page.Header                     the document header in the flow
@@ -114,10 +117,11 @@ Page.Root                          the page column (<div>); maxWidth, fill, labe
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `loading` | `boolean` | `false` | Its data is loading: a Skeleton keeps the line's place, so the title never moves; the data then fades in. Sets `aria-busy`. |
 | `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `children`, `className` and the other paragraph attributes. |
 
 ### Page.Tools
-`ref` → `HTMLDivElement`. The page's tools as kit controls in the order written: sections, `SmartFilter.Toolbar`, view. On a line of their own a search grows first; a `SegmentedControl.Root` is `fullWidth` unless set. Named, a `group`.
+`ref` → `HTMLDivElement`. The page's tools in the order written: sections, `SmartFilter.Toolbar`, view. On a line of their own a search grows first, the rest share the line: a `SegmentedControl.Root` and a `Datepicker.Root` are `fullWidth` unless set. Named, a `group`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -151,18 +155,17 @@ Page.Root                          the page column (<div>); maxWidth, fill, labe
 |---|---|---|---|
 | `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; `Page.Actions` goes to the heading row), `className` and the other section attributes. |
 
 ### Page.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).
+`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, a wide cell next to a narrow one pairs up (see Grid columns).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (`Page.Cell`), `className` and the other div attributes. |
 
 ### Page.Cell
-`ref` → `HTMLDivElement`. One tile place in `Page.Grid`; its child (a Card, a ChartFrame) stretches to it, so the tiles of a row share one height.
+`ref` → `HTMLDivElement`. One tile place in `Page.Grid`; its child (a Card, a ChartFrame) stretches to it, so the tiles of a row share one height; a `Crossfade` child gets `fill` unless it sets it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -170,6 +173,14 @@ Page.Root                          the page column (<div>); maxWidth, fill, labe
 | `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. |
 
+### Page.Guard
+No DOM, no ref. Holds the page from anywhere inside it: a press on a `Sidebar.Item`, `BottomNav.Item` or `Breadcrumb.Item` link (a router link too) stops before it navigates, and the browser asks before the tab closes. Renders only its `ConfirmDialog`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `busy` | `boolean` | `false` | A request runs (a save): a press on those items does nothing until it ends; the browser asks before the tab closes. |
+| `dirty` | `boolean` | `false` | Changes are not saved: a press on those items asks «leave without saving?»; its confirm (`labels.leaveConfirm`) repeats the press, its cancel keeps the page. The browser asks before the tab closes. |
+
 ### Page.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.
 
@@ -224,12 +235,8 @@ The size follows the place; the consumer passes nothing, and there are no title
 | `fill` (Root) | the page is as high as main; the body takes what the bar and the header leave; main keeps gutter-high air under it | a full-height table, board, chat or `Page.Split` in an `AppShell.Root fillViewport` | `false` |
 | `sticky` (TopBar) | the bar stays at the top of main while the page scrolls under it | every page; `false` for a bar that should scroll away | `true` |
 | `collapse` (TopBar) | the flow title rises into the bar's title row once it scrolls away | a document page or an overview with the title in the flow | `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 | |
+| `dirty` (Guard) | nothing until a person leaves: a press on the navigation or the path asks «leave without saving?» | a form that is the page has unsaved changes | `false` |
+| `busy` (Guard) | nothing until a person leaves: a press on the navigation or the path does nothing | the page's save request runs | `false` |
 
 ### Top bar plan
 One plan, chosen from the natural widths of the groups (`data-plan` on the bar's row). The bar takes the first step whose first line fits:
@@ -237,7 +244,7 @@ One plan, chosen from the natural widths of the groups (`data-plan` on the bar's
 | Step | Looks like | Use when | Default |
 |---|---|---|---|
 | `one` | `[Heading 1fr][Tools][Actions]` on one line | everything fits | yes |
-| `below` | the tools on a line of their own under the heading and the actions, filling it: a search (`SmartFilter.Toolbar`, `Input.Root`) grows first, switchers share the rest and wrap when one line is not enough | heading + tools + actions do not fit | |
+| `below` | the tools on a line of their own under the heading and the actions, filling it: a search (`SmartFilter.Toolbar`, `Input.Root`) grows first, switchers and fields (`SegmentedControl.Root`, `Datepicker.Root`, a Select) share the rest and wrap when one line is not enough | heading + tools + actions do not fit | |
 | `icons-secondary` | as `below`; secondary Buttons with a `Button.Icon` show only the icon, the label is their name and their tooltip | heading + actions still do not fit | |
 | `icons` | the primary Button gives way to its icon too | still too wide | |
 | `fold` | the secondary Buttons fold into «⋯» (`labels.more`); the primary stays | still too wide, and «⋯» is narrower than their icons (a single secondary keeps its icon); past it a Breadcrumb path folds into «…»; if the path and the title still do not share the line, the heading stacks: the path on its own line over the title, the title and the description wrapping (`data-heading="stack"`); a heading without a path truncates | |
@@ -249,9 +256,11 @@ The actions stay on the first line beside the heading at every step; `Page.Chips
 |---|---|---|---|---|---|
 | < 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 |
+| 40–64rem | half | a third | half (a third in a pair) | the row (2/3 in a pair) | spans |
 | ≥ 64rem | its span | its span | its span | its span | spans |
 
+A wide cell (`span` 7–11) written next to a narrow one (`span` 4–5) is a pair: on a 40–64rem grid it takes 2/3 and its neighbour 1/3, so an 8 + 4 row keeps no hole. Cells pair in the order written, two at a time; a `span` 12 never pairs. The flow is `dense`: a small cell fills a hole left by a wide one.
+
 ### Split layout
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -262,6 +271,7 @@ The actions stay on the first line beside the heading at every step; `Page.Chips
 | State | Driven by | DOM |
 |---|---|---|
 | capped page | `maxWidth` | `data-max-width="readable" \| "wide"` on Root (absent for `full`) |
+| line of data loading | `loading` on Description | a Skeleton in the line (its height kept, so the title never moves), `aria-busy`; the data fades in under the same element |
 | filling | `fill` | `data-fill="true"` on Root; `AppShell.Main` drops its long bottom air for it |
 | sticky bar | `sticky` | `data-sticky="true"` on TopBar |
 | title repeated in the bar | `collapse` and the flow title out of view | `data-collapsed="true"` on TopBar; the echo rises in (`transform` on the fast movement clock, `opacity` on the fast fade; reduced motion keeps the fade). After a `Breadcrumb` path the echo is the path's last level (an `aria-hidden`, `inert` `Breadcrumb.Item`), so the path folds its levels into «…» for it (`data-collapsed` on the Breadcrumb) and the title stays readable; a path whose last level already reads as the title (the same words, however spaced or cased) gets no echo |
@@ -271,14 +281,15 @@ The actions stay on the first line beside the heading at every step; `Page.Chips
 | folded buttons | plan `fold` | the secondary Buttons' wrappers `hidden`; a «⋯» Dropdown in their place, their `menuitem`s inside |
 | heading place | inside TopBar or in the flow | `data-place="bar" \| "flow"` on Heading |
 | with actions | `Page.Actions` child | `data-has-actions="true"` on Header / the section heading row |
-| section heading column | `layout="aside"` on Section | `data-layout="aside"` on Section (absent for `stack`) |
 | tile span | `span` / `rows` on Cell | `data-span="1"…"12"` (always), `data-rows="2"…"4"` (absent for 1) |
+| tile pair | a `span` 7–11 Cell next to a `span` 4–5 Cell in the Grid | `data-pair="wide" \| "narrow"` on both Cells (set by the Grid) |
+| held | `Page.Guard` `busy` or `dirty` | a press on a `Sidebar.Item`, `Sidebar.Brand`, `BottomNav.Item` or `Breadcrumb.Item` link is stopped (capture phase, before the item's and the router link's handlers); `dirty` opens the `ConfirmDialog` and its confirm repeats the press once the dialog has closed (its texts are the `leave*` keys of `labels` on `Page.Root`); a `beforeunload` listener while either is on. A press that opens a new tab (a modifier key, a middle click, `target="_blank"`) and navigation from code are never held |
 | 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`); focus moves into the detail, or back to the list control |
 
 ## Layout & spacing
 - The edge air comes from the host: `AppShell.Main` sets `--page-gutter` (the page gutter, 16 → 24 → 32) and `--page-top` (24 → 32 from 1024px); `Page.Root` pads itself with them. Outside a host the page brings no air. The page resets both for what it holds, so a page nested in it starts clean.
-- `Page.TopBar` steps out of the gutter to the panel's edges and keeps the gutter inside; padding 12 above (or the top safe-area inset) and below; the page's top air goes under it. The first line is as high as the Sidebar brand row (control m + 8), so the two read as one line. Groups 16 apart on a line, lines 12 apart; tools 8 apart; buttons 8 apart.
+- `Page.TopBar` steps out of the gutter to the panel's edges and keeps the gutter inside; padding 12 above (or the top safe-area inset) and below; what follows starts 24 under its controls (header → body; the bar's own 12 counts in). The first line is as high as the Sidebar brand row (control m + 8), so the two read as one line. Groups 16 apart on a line, lines 12 apart; tools 8 apart; buttons 8 apart.
 - In the bar only the heading's column gives (`minmax(0, 1fr)`): the tools and the actions keep their width. The heading keeps its natural width until every button step is taken; then a heading with a path stacks (the path over the title, the title and the description wrapping), so no level is cut to a fragment; a heading without a path truncates its title.
 - The plan is measured, never chosen by breakpoints: the bar lays itself out from its own width.
 - Header (flow) → Body 24; blocks inside Body 24; a `Page.Section` 40 from its neighbours (the body's 24 + 16); tile → tile in a Grid 16 on both axes; section heading → content 16, heading → description 4; flow Title → Description 8; heading → Actions 24 side by side, 16 once they wrap below.
@@ -303,6 +314,7 @@ The actions stay on the first line beside the heading at every step; `Page.Chips
 - The menu button carries `aria-expanded` and `aria-controls` → the Sidebar's `<nav>`. A Button that shows only its icon keeps its label as its accessible name; its tooltip repeats it. Folded Buttons are `hidden` in the bar and `menuitem`s in the «⋯» menu (named by `labels.more`), named by the Button's `aria-label` or its text, disabled with it; their `onClick` runs from the menu.
 - `Page.TopBar` renders its groups in reading order — `Page.Heading`, `Page.Tools`, `Page.Actions`, `Page.Chips` — whatever the JSX order; the plan moves them only visually. A named `Page.Tools` is a `group`. The chevron between the path and the title is decorative (`aria-hidden`): the title is the `<h1>`, outside the path's `<nav>`.
 - `Page.Section` is a `<section>` named by its own `<h2>` (`label`) through `aria-labelledby`; the heading levels go h1 (page) → h2 (section) → h3 (a card title inside it).
+- `Page.Guard` holds a press made by pointer or keyboard alike (Enter on a link is a click). Its confirm is a `ConfirmDialog` (`alertdialog`): focus moves into it and, on «stay», returns to the item that was pressed.
 - Name both panes of `Page.Split` with `aria-label`: a named pane is `role="region"`. 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`. `Page.BackButton` is named by `labels.back` and shown only while the split shows one pane.
 
 ### Labels
@@ -313,6 +325,10 @@ The actions stay on the first line beside the heading at every step; `Page.Chips
 | `menu` | `"Открыть меню"` | Name of the menu button `Page.TopBar` draws while the shell's Sidebar is off-canvas. |
 | `more` | `"Ещё действия"` | Name of the «⋯» button the secondary Buttons of the top bar's `Page.Actions` fold into. |
 | `back` | `"Назад к списку"` | Name of `Page.BackButton`. |
+| `leaveTitle` | `"Уйти без сохранения?"` | Title of the confirm `Page.Guard` opens when a person leaves a `dirty` page. |
+| `leaveDescription` | `"Изменения на странице пропадут."` | Its description. |
+| `leaveConfirm` | `"Уйти"` | Its confirm button: leave and lose the changes. |
+| `leaveCancel` | `"Остаться"` | Its cancel button: stay on the page. |
 
 ## Examples
 | Example | Shows |
@@ -321,16 +337,19 @@ The actions stay on the first line beside the heading at every step; `Page.Chips
 | [variants.tsx](examples/variants.tsx) | The same page at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. |
 | [structure.tsx](examples/structure.tsx) | A document page in the flow: the path over the large title, its line of data and the page's buttons beside them, then the body with a section — `Page.Header`, `Page.Heading`, `Page.Description`, `Page.Section`. |
 | [top-bar.tsx](examples/top-bar.tsx) | A nested record in the top bar: the path ending in the title, a line of data, the page's tools and its buttons — `Page.TopBar`, `Page.Heading`, `Page.Tools`, `Page.Actions`. |
+| [loading.tsx](examples/loading.tsx) | A page whose figures load after it opens: the line of data keeps its place under the title while it loads, so nothing in the bar moves — `loading`. |
 | [collapse.tsx](examples/collapse.tsx) | An overview whose large title scrolls away under the top bar: the bar repeats it with its line of data and keeps the period and the page's buttons in reach — `collapse`. |
 | [tools.tsx](examples/tools.tsx) | The orders page's tools in its top bar: sections with counts, search and filter, the period, in the order written; the active filters on a line under everything — `Page.Tools`, `Page.Chips`. |
 | [actions-collapse.tsx](examples/actions-collapse.tsx) | The buttons of an invoices page on a tablet-wide column: the line runs short, so the secondary buttons show only their icons with the label as the name and the tooltip, the primary keeps its label — `Page.Actions`, `Button.Icon`. |
-| [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 — `Page.Section`, `label`, `description`, `Page.Actions`, `layout`. |
+| [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 — `Page.Section`, `label`, `description`, `Page.Actions`. |
 | [grid.tsx](examples/grid.tsx) | A dashboard board: four KPI tiles, a chart two rows high beside two panels, one gap on both axes — `Page.Grid`, `Page.Cell`, `span`, `rows`. |
 | [list-detail.tsx](examples/list-detail.tsx) | A ticket queue 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; the chosen ticket cross-fades in — `Page.Split`, `Page.List`, `Page.Detail`, `Page.BackButton`, `fill`. |
+| [guard.tsx](examples/guard.tsx) | A client's card edited on its own page: after an edit a press on the navigation or the path asks before the changes are lost, and while it saves nothing leaves — `Page.Guard`, `dirty`, `busy`. |
 | [narrow.tsx](examples/narrow.tsx) | On a phone the top bar leads with the menu button that opens the navigation by itself, the primary button gives way to its icon and the secondary ones fold into «⋯» — `offCanvas`, `Page.Actions`. |
-| [screen.tsx](examples/screen.tsx) | A settings page as a document: the path in the top bar that repeats the title once it scrolls away, the large title in the flow, 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 — `collapse`, `layout`, `maxWidth`. |
+| [screen.tsx](examples/screen.tsx) | A settings page as a document: the path in the top bar that repeats the title once it scrolls away, the large title in the flow, each section a card with its own heading, a form saved by its own button, switches that apply at once and a danger zone with a confirm — `collapse`, `maxWidth`, `Card.Header`. |
 
 ## Mistakes
+- `{ready ? <Page.Description>…</Page.Description> : null}` → the line appears after the load and the title jumps; keep it mounted with `loading` until the data comes.
 - A global header above every page → the app is navigation and the page; each page renders its own `Page.TopBar` with only what it needs.
 - Padding on `Page.Root` or around it to imitate gutters → the page takes them from `AppShell.Main`.
 - Two titles — one in the bar, one in the flow → one `Page.Title`; a flow title with `collapse` is repeated in the bar by itself.
@@ -344,10 +363,13 @@ The actions stay on the first line beside the heading at every step; `Page.Chips
 - Hiding buttons with media queries on a phone → `Page.Actions` in the bar collapses and folds them by measured width.
 - Wrapping a group of the bar or `Page.Title` in your own component → the bar and the heading find their parts among their direct children.
 - A hand-made `<section>` + `Typography as="h2"` + own gap CSS → `Page.Section label`.
+- A heading column beside a panel (the section's title and description on the left, its card on the right) → it wastes the width and breaks the reading line; a titled block is a `Card.Root` with its own `Card.Header` (`Card.Title as="h2"`, `Card.Description`) stacked in the flow.
 - Each row of cards in its own grid → put every tile of the screen in one `Page.Grid`.
 - Computing a height from `100vh` minus the bar for a full-height table or chat → `Page.Root fill` and a filling child.
 - A list + detail built with window media queries → `Page.Split` follows its own width.
+- A `beforeunload` listener and a ConfirmDialog on a crumb of your own for unsaved changes → `Page.Guard dirty`; it also holds the Sidebar and BottomNav items.
+- Tiles of a row cut to 6 + 6 so a mid-width grid keeps no hole → write the 8 and the 4 next to each other; the grid pairs them as 2/3 + 1/3.
 
 ## Related
-- **Built from:** [AppShell](../app-shell/COMPONENT.md) (the navigation the menu button opens), [Breadcrumb](../../components/breadcrumb/COMPONENT.md) (the path the heading places), [Button](../../components/button/COMPONENT.md) (the menu button, «⋯», `Page.BackButton`; the icon-only label hook), [Dropdown](../../components/dropdown/COMPONENT.md) (folded buttons), [Tooltip](../../components/tooltip/COMPONENT.md) (the label of an icon-only button), [SegmentedControl](../../components/segmented-control/COMPONENT.md) (`fullWidth` in `Page.Tools`), [SmartFilter](../../components/smart-filter/COMPONENT.md) and [Input](../../components/input/COMPONENT.md) (the search that grows first in `Page.Tools`), Icon (`nav.menu`, `nav.chevronRight`, `action.more`, `nav.chevronLeft`)
+- **Built from:** [AppShell](../app-shell/COMPONENT.md) (the navigation the menu button opens), [Breadcrumb](../../components/breadcrumb/COMPONENT.md) (the path the heading places), [Button](../../components/button/COMPONENT.md) (the menu button, «⋯», `Page.BackButton`; the icon-only label hook), [Dropdown](../../components/dropdown/COMPONENT.md) (folded buttons), [Tooltip](../../components/tooltip/COMPONENT.md) (the label of an icon-only button), [SegmentedControl](../../components/segmented-control/COMPONENT.md) and [Datepicker](../../components/datepicker/COMPONENT.md) (`fullWidth` in `Page.Tools`), [SmartFilter](../../components/smart-filter/COMPONENT.md) and [Input](../../components/input/COMPONENT.md) (the search that grows first in `Page.Tools`), [Crossfade](../../components/crossfade/COMPONENT.md) (a `Page.Cell` child gets `fill`), [Skeleton](../../components/skeleton/COMPONENT.md) (the line of data while it loads), [ConfirmDialog](../../components/confirm-dialog/COMPONENT.md) (the confirm of `Page.Guard`), Icon (`nav.menu`, `nav.chevronRight`, `action.more`, `nav.chevronLeft`)
 - **See also:** [Sidebar](../sidebar/COMPONENT.md), [BottomNav](../bottom-nav/COMPONENT.md), [Select](../../components/select/COMPONENT.md), [Card](../../components/card/COMPONENT.md), [ChartFrame](../../components/chart-frame/COMPONENT.md), [List](../../components/list/COMPONENT.md), [EmptyPage](../../components/empty-page/COMPONENT.md), [Drawer](../../components/drawer/COMPONENT.md), [VisuallyHidden](../../components/visually-hidden/COMPONENT.md)

package/src/layout/page/examples/examples.module.css

@@ -77,6 +77,13 @@
   padding: var(--prime-space-2) var(--prime-space-4);
 }
 
+/* guard.tsx: the fields of the form, one column of the form width. */
+.fields {
+  display: grid;
+  gap: var(--prime-space-4);
+  max-width: var(--prime-layout-form-width-m);
+}
+
 /* actions-collapse.tsx: a tablet-width page column (600px). */
 .tablet {
   width: 100%;

package/src/layout/page/examples/guard.tsx

@@ -0,0 +1,87 @@
+/** A client's card edited on its own page: after an edit a press on the navigation or the path asks before the changes are lost, and while it saves nothing leaves — `Page.Guard`, `dirty`, `busy`. */
+import { AppShell, Breadcrumb, Button, Card, Icon, Input, Page, Sidebar } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SAVED_NAME = "ООО «Северный ветер»";
+const SAVED_MANAGER = "Анна Морозова";
+
+export default function PageGuardExample() {
+  const [name, setName] = React.useState(SAVED_NAME);
+  const [manager, setManager] = React.useState(SAVED_MANAGER);
+  const [saved, setSaved] = React.useState({ name: SAVED_NAME, manager: SAVED_MANAGER });
+  const [saving, setSaving] = React.useState(false);
+  const formId = React.useId();
+  const dirty = name !== saved.name || manager !== saved.manager;
+
+  const save = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSaving(true);
+    window.setTimeout(() => {
+      setSaved({ name, manager });
+      setSaving(false);
+    }, 1200);
+  };
+
+  return (
+    <div className={styles.window}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppShell.Nav>
+          <Sidebar.Root>
+            <Sidebar.Content>
+              <Sidebar.Item href="#orders">
+                <Sidebar.ItemIcon>
+                  <Icon name="object.package" />
+                </Sidebar.ItemIcon>
+                Заказы
+              </Sidebar.Item>
+              <Sidebar.Item href="#clients" current>
+                <Sidebar.ItemIcon>
+                  <Icon name="object.users" />
+                </Sidebar.ItemIcon>
+                Клиенты
+              </Sidebar.Item>
+            </Sidebar.Content>
+          </Sidebar.Root>
+        </AppShell.Nav>
+        <AppShell.Main>
+          <Page.Root>
+            <Page.Guard dirty={dirty} busy={saving} />
+            <Page.TopBar>
+              <Page.Heading>
+                <Breadcrumb.Root>
+                  <Breadcrumb.Item href="#clients">Клиенты</Breadcrumb.Item>
+                </Breadcrumb.Root>
+                <Page.Title>{saved.name}</Page.Title>
+              </Page.Heading>
+              <Page.Actions>
+                <Button.Root type="submit" form={formId} loading={saving} disabled={!dirty}>
+                  Сохранить
+                </Button.Root>
+              </Page.Actions>
+            </Page.TopBar>
+            <Page.Body>
+              <Card.Root>
+                <Card.Body>
+                  <form id={formId} className={styles.fields} onSubmit={save}>
+                    <Input.Root label="Название">
+                      <Input.Wrapper>
+                        <Input.Field value={name} onValueChange={setName} />
+                      </Input.Wrapper>
+                    </Input.Root>
+                    <Input.Root label="Менеджер">
+                      <Input.Wrapper>
+                        <Input.Field value={manager} onValueChange={setManager} />
+                      </Input.Wrapper>
+                    </Input.Root>
+                  </form>
+                </Card.Body>
+              </Card.Root>
+            </Page.Body>
+          </Page.Root>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  );
+}

package/src/layout/page/examples/loading.tsx

@@ -0,0 +1,57 @@
+/** A page whose figures load after it opens: the line of data keeps its place under the title while it loads, so nothing in the bar moves — `loading`. */
+import { Button, Card, Crossfade, Icon, Page, Skeleton, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const ORDERS = [
+  { id: "№ 4821", client: "ООО «Север»", sum: "84 000 ₽" },
+  { id: "№ 4820", client: "ИП Котов", sum: "12 500 ₽" },
+  { id: "№ 4819", client: "ООО «Вектор»", sum: "230 000 ₽" },
+];
+
+const LOAD_MS = 1200;
+
+export default function PageLoadingExample() {
+  const [loading, setLoading] = React.useState(true);
+
+  React.useEffect(() => {
+    if (!loading) return;
+    const timer = window.setTimeout(() => setLoading(false), LOAD_MS);
+    return () => window.clearTimeout(timer);
+  }, [loading]);
+
+  return (
+    <Page.Root>
+      <Page.TopBar sticky={false}>
+        <Page.Heading>
+          <Page.Title>Заказы</Page.Title>
+          <Page.Description loading={loading}>128 в работе · 6 ждут оплаты</Page.Description>
+        </Page.Heading>
+        <Page.Actions>
+          <Button.Root variant="soft" tone="neutral" onClick={() => setLoading(true)}>
+            <Button.Icon>
+              <Icon name="action.refresh" />
+            </Button.Icon>
+            Обновить
+          </Button.Root>
+        </Page.Actions>
+      </Page.TopBar>
+      <Page.Body>
+        <Card.Root variant="list" aria-busy={loading || undefined}>
+          <Card.Body>
+            <Crossfade state={loading ? "loading" : "data"}>
+              {loading ? (
+                <Skeleton lines={ORDERS.length} />
+              ) : (
+                ORDERS.map((order) => (
+                  <Typography key={order.id} variant="body-m">
+                    {order.id} · {order.client} · {order.sum}
+                  </Typography>
+                ))
+              )}
+            </Crossfade>
+          </Card.Body>
+        </Card.Root>
+      </Page.Body>
+    </Page.Root>
+  );
+}

package/src/layout/page/examples/screen.module.css

@@ -1,4 +1,4 @@
-/* Settings page: each section is a Page.Section layout="aside"; here only the panels' insides. */
+/* Settings page: each section is a Card with its own header; here only the cards' insides. */
 
 /* Field → field 20. */