prime-ui-kit 0.17.0 → 0.18.0

package/src/components/rich-text/COMPONENT.md

@@ -0,0 +1,93 @@
+# RichText
+
+**Category:** data-display
+**Kind:** primitive
+
+> Text in the chat's Markdown subset outside a message — a bot's welcome text, a template, a comment — rendered as elements, never as HTML.
+
+## When to use
+- A text written with the formatting toolbar of `Composer` or `Textarea formatting` is shown somewhere other than a chat: a bot's settings, a template list, a card.
+- Text from users or bots that may carry `**bold**`, links or a `||spoiler||` and must be rendered safely.
+
+## When not to use
+- The text of a chat message → [Message](../message/COMPONENT.md) `Message.Text` (it marks search matches and holds the meta's room).
+- A whole message shown outside a chat (a bot's welcome message with its keyboard) → `Message.Root preview`.
+- Plain text with a role → [Typography](../typography/COMPONENT.md).
+- Source code → [CodeBlock](../code-block/COMPONENT.md).
+
+## Import
+```tsx
+import { RichText } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+RichText         <div>; the source as children
+├─ <p>           a run of text, line breaks kept
+├─ <blockquote>  lines starting with "> "
+└─ <pre>         fenced code
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### RichText
+`ref` → `HTMLDivElement`. Text in the chat's Markdown subset outside a message, rendered as elements in the type of its host.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `string` | — (required) | The source: `**bold**`, `_italic_`, `~~strike~~`, `\|\|spoiler\|\|`, inline and fenced code, links (`[label]` then the address in parentheses), bare URLs, `> ` quotes; line breaks are kept. |
+| `labels` | `Partial<RichTextLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `id`, `data-*` and the other div attributes. |
+
+## Variants
+One look: the type of its host. Wrap it in `Typography as="div"` to pick a text role.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| masked spoiler | `\|\|text\|\|` in `children` | `role="button"`, `data-state="masked"`: a wash over transparent words |
+| revealed spoiler | a press, `Enter` or `Space` | `data-state="revealed"`: the wash and the words cross-fade on the fade clock; one way, like a chat |
+
+## Layout & spacing
+- Paragraphs, quotes and code blocks keep their line breaks and wrap anywhere, so a long address never widens the host; blocks stand 4px apart.
+- A quote is a wash with an accent bar on its start edge; code is the mono face on a wash.
+- No size of its own: the root takes the font and color of its host.
+
+## Accessibility
+
+### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves through the links and the masked spoilers. |
+| `Enter` · `Space` | On a masked spoiler: reveals it and moves the focus onto its text. |
+
+### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- A masked spoiler is a `role="button"` named `labels.spoiler`; its words are out of the accessibility tree until it is revealed.
+- Links take only http(s), `mailto:` and `tel:` addresses and open in a new tab (`rel="noopener noreferrer"`); markup is never parsed as HTML.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `spoiler` | `"Скрытый текст"` | The name of a masked spoiler until it is revealed. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | The welcome text of a support bot shown outside the chat: bold, a link, a quote, code and a spoiler from the chat's Markdown — `children`. |
+
+## Mistakes
+- `dangerouslySetInnerHTML` with a Markdown library for a chat text → `RichText`: the same subset as the chat, never HTML.
+- A `Message.Root` with no time and no author only to render formatted text → `RichText`.
+- Sizing the text with a class on `RichText` → put it inside the host that sets the type.
+
+## Related
+- **Built from:** `internal/richText` (the parser and the elements, shared with `Message.Text`)
+- **See also:** [Message](../message/COMPONENT.md), [Composer](../composer/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Typography](../typography/COMPONENT.md)

package/src/components/rich-text/examples/overview.tsx

@@ -0,0 +1,19 @@
+/** The welcome text of a support bot shown outside the chat: bold, a link, a quote, code and a spoiler from the chat's Markdown — `children`. */
+import { Card, RichText } from "prime-ui-kit";
+
+const WELCOME = [
+  "**Здравствуйте!** Это бот поддержки «Прайм».",
+  "Счета и акты — в [личном кабинете](https://prime.app/billing), номер договора начинается с `PR-`.",
+  "> Отвечаем в рабочие дни с 9:00 до 19:00 по Москве.",
+  "Код для входа в приложение: ||4821||",
+].join("\n");
+
+export default function RichTextOverviewExample() {
+  return (
+    <Card.Root>
+      <Card.Body>
+        <RichText>{WELCOME}</RichText>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/scroll-container/COMPONENT.md

@@ -44,7 +44,7 @@ ScrollContainer   <div> (or the `as` tag); thin scrollbar, soft hidden edges
 | `edges` | `"fade" \| "shadow" \| "none"` | `"fade"` | Edges that hide content: `fade` dissolves them over any background; `shadow` — a soft shadow on the region's own fill (a floating panel, a code well); `none` — plain edges. |
 | `scrollbar` | `"thin" \| "hidden"` | `"thin"` | `thin` — the kit's quiet scrollbar; `hidden` — no scrollbar, keep `edges` on so the overflow stays visible. |
 | `lock` | `boolean` | `false` | The person cannot scroll the region (wheel, touch, keys, a drag's auto-scroll); code still can. Sets `data-lock`. |
-| `snap` | `boolean \| "mandatory"` | `false` | Scrolling comes to rest on the start of a child: `true` near one (strips of tiles and cards), `"mandatory"` always on one (board columns, a carousel). A Dnd drag inside turns it off; not with `anchor="end"`. |
+| `snap` | `boolean \| "mandatory"` | `false` | Once a scroll ends, the region glides to the start of a child: `true` near one (strips of tiles), `"mandatory"` always (board columns, a carousel). Native scrolling meanwhile; any input stops the glide. |
 | `anchor` | `"start" \| "end"` | `"start"` | `end` — a chat or a log: opens at the end and follows new content while the person is at the end; scrolled away, the view holds still. |
 | `onReachStart` | `() => void \| Promise<void>` | — | Fires within 120 px of the start, once per approach: load older content. A returned promise blocks repeats and sets `aria-busy`; content added above keeps the view. |
 | `onReachEnd` | `() => void \| Promise<void>` | — | The scroll position came within 120 px of the end: load the next page. Same once-per-approach and promise rules as `onReachStart`. |
@@ -93,11 +93,12 @@ Only the reader scrolling back unpins the end: content that keeps growing (an an
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `lock` | nothing the person does scrolls the region (wheel, touch, keys, a drag's edge auto-scroll); the position stays, and code may still set it | a list behind an open review, a gesture that must not move it | off |
-| `snap` | a scroll comes to rest on the start of a direct child near one (proximity); a host aligns deeper items itself | strips of tiles or cards | off |
-| `snap="mandatory"` | a scroll always comes to rest on the start of a child | board columns, a carousel of cards | off |
+| `snap` | once a scroll ends near the start of a direct child (within 30% of the view), the region glides there; a host marks deeper items with `scroll-snap-align` itself | strips of tiles or cards | off |
+| `snap="mandatory"` | once a scroll ends, the region always glides to the nearest start of a child | board columns on a phone, a carousel of cards | off |
 
 ### Wheel and auto-scroll
-- `axis="horizontal"`: a vertical mouse wheel scrolls the strip sideways while it can move, gliding to an accumulated target (instant under reduced motion). A trackpad's sideways swipe and Shift + wheel stay native; a wheel gesture that began outside the strip keeps scrolling the page; at the strip's edge the wheel chains to the page. There is no drag-to-scroll: a press-and-drag in a strip belongs to its items (reordering tiles, tabs); touch pans natively.
+- Snapping never takes over the scroll: the trackpad, touch, the scrollbar and the keys scroll natively with their momentum, and the browser does not snap (no `scroll-snap-type` — it damps a trackpad's momentum and pulls a scroll near the end back to merged rest points). Once the scroll ends — no movement for a moment, nothing held — the region glides to its rest point on the kit's own frames, and any wheel, touch, press or key stops that glide at once; it settles again when the input goes quiet. A Dnd drag inside never settles.
+- `axis="horizontal"`: a vertical mouse wheel (whole notches; a trackpad stays native) scrolls the strip sideways while it can move — by the wheel's distance, or a rest point per notch on a strip that snaps — on the kit's frames (instant under reduced motion), each notch from where the glide is heading, so a turn the other way goes back mid-glide. Shift + wheel stays native; a wheel gesture that began outside the strip keeps scrolling the page; at the strip's edge the wheel chains to the page. There is no drag-to-scroll: a press-and-drag in a strip belongs to its items (reordering tiles, tabs); touch pans natively.
 - A gesture held near an edge — a Dnd drag, a Gantt bar moved or drawn, a drag that paints a selection over table rows or messages — scrolls the region toward it, faster the closer the pointer (`src/internal/edgeAutoScroll`, one speed curve for the kit). A `lock`ed region or one whose content fits never moves.
 
 ### Edge events
@@ -116,7 +117,7 @@ Each fires once per approach — again after the position leaves the zone or the
 | edge treatment | `edges` | `data-edges="fade" \| "shadow"` (none for `none`) |
 | content hidden at an edge | scroll position (with `edges="fade"`), measured at most once per frame on scroll, on resize of the region or a child and when children are added; only the scroll axes; logical in RTL | `data-overflow-top`, `data-overflow-bottom`, `data-overflow-start`, `data-overflow-end` = `"true"`; `--edge-*` depths written only while they change (within the last fade depth of an edge, `--scroll-fade-depth`), on non-inherited properties |
 | locked | `lock` | `data-lock`, `overflow: hidden` |
-| snapping | `snap` | `data-snap="proximity" \| "mandatory"`, `scroll-snap-type: <axis> <strictness>`; `scroll-snap-align: start` on the children; off while a Dnd list inside carries an item (`data-dnd-carrying`) |
+| snapping | `snap` | `data-snap="proximity" \| "mandatory"`; `scroll-snap-align: start` on the children marks the rest points (no `scroll-snap-type`); no settling while a Dnd list inside carries an item (`data-dnd-carrying`) |
 | kit anchoring | `anchor="end"` or `onReachStart` | `data-anchor="end" \| "start"`, `overflow-anchor: none`: the kit keeps the visible entry in place (or the end, while pinned) before paint, the same in every browser |
 | pinned to the end | `anchor="end"` and the position within 4 px of the end | content changes scroll to the new end at once (high-frequency: no animation) |
 | loading at an edge | a pending promise from `onReachStart` / `onReachEnd` | `aria-busy="true"` |
@@ -176,6 +177,8 @@ No `labels`.
 - `edges="fade"` on a region that paints its own fill or shadow → the mask dissolves them; use `edges="shadow"`.
 - A hand-made edge auto-scroll loop for a drag → `createEdgeAutoScroll` from `src/internal/edgeAutoScroll`.
 - `snap` together with `anchor="end"` → snapping fights the pin to the end.
+- `scroll-snap-type` on a region or its host → `snap`: the browser's snapping damps a trackpad's momentum and pulls a scroll near the end back.
+- `snap="mandatory"` on a strip of children narrower than the view (a wide board) → their rest points merge at the end; snap only where each child fills most of the view, or use `snap`.
 - Wrapping a Modal body or Dropdown panel in another ScrollContainer → they already scroll.
 - `scrollTop = scrollHeight` in an effect after every message → `anchor="end"` (it also leaves a reader who scrolled up alone).
 - `flex-direction: column-reverse` to keep a chat at the bottom → it reverses the reading and Tab order; use `anchor="end"`.

package/src/components/segmented-control/COMPONENT.md

@@ -53,6 +53,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the `radiogroup`. |
 | `optional` | `boolean` | `false` | Muted marker after the label (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the control (`aria-describedby`). 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, `aria-invalid` and `data-invalid` on the `radiogroup`; the control shakes once when an error arrives. |
 | `reserveSupportRow` | `boolean` | `false` | Always render the support row, so an appearing error does not shift the layout. |

package/src/components/segmented-control/examples/in-form.tsx

@@ -15,7 +15,7 @@ export default function SegmentedControlInFormExample() {
 
   return (
     <form className={styles.form} noValidate onSubmit={submit}>
-      <Input.Root label="Сумма, ₽" required>
+      <Input.Root label="Сумма" required>
         <Input.Wrapper>
           <Input.Field name="amount" inputMode="decimal" defaultValue="12 400" />
           <Input.InlineAffix side="end">₽</Input.InlineAffix>

package/src/components/select/COMPONENT.md

@@ -11,12 +11,13 @@
 - A value out of thousands of records searched on the server (`search`, `onSearchChange`, `filter={false}`, `hasMore` + `onLoadMore`).
 - A few values from a short list shown as comma-separated text (`multiple`).
 - Options that need a picture, an avatar, a second line, a badge or a trailing value (rich options).
+- A pick that belongs to a text field (an icon before a name): put the Select inside `Input.Wrapper` — it becomes the box's start segment, named by its `aria-label`.
 
 ## When not to use
 - 2–5 options that should all be visible → use [Radio](../radio/COMPONENT.md) or [SegmentedControl](../segmented-control/COMPONENT.md).
 - The OS picker on a mobile-first form → use [NativeSelect](../native-select/COMPONENT.md).
 - Many values shown as removable tags, or creating new values → use [TagSelect](../tag-select/COMPONENT.md).
-- Free text → use [Input](../input/COMPONENT.md).
+- Free text, even with suggestions → use [Input](../input/COMPONENT.md) (`suggestions`).
 - A menu of actions (not a value) → use [Dropdown](../dropdown/COMPONENT.md).
 - Global search / command palette → use [CommandMenu](../command-menu/COMPONENT.md).
 - Dates → use [Datepicker](../datepicker/COMPONENT.md).
@@ -60,7 +61,7 @@ an icon) goes inside `Select.ItemMeta`.
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Select.Root
-`ref` → `HTMLDivElement`. The field frame (label row · control · support row) holding the value, the open state and the search query.
+`ref` → `HTMLDivElement`. The field frame (label row · control · support row) holding the value, the open state and the search query. Inside `Input.Wrapper` it is the box's start segment instead: no frame, the trigger named by `aria-label` and the value.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -75,6 +76,7 @@ an icon) goes inside `Select.ItemMeta`.
 | `closeOnOutsideClick` | `boolean` | `true` | A press outside the list and its trigger closes it; focus follows the pointer. |
 | `label` | `ReactNode` | — | Field label above; names the trigger. |
 | `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 trigger. |
 | `optional` | `boolean` | — | Muted `labels.optional` after the label. |
@@ -224,6 +226,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | searching | typing in the search | panel `data-searching="true"`; groups without matches and separators hide; the match in an option's title, description and plain text is a `<mark>` in `accent-text` (not in the trigger); the query clears when the list closes (`onSearchChange("")`) |
 | nothing to show | no option matches (and not loading) | a compact EmptyPage with `role="status"`: `labels.empty`, plus `labels.emptyHint` while a query is typed; a `Select.Action` stays under it, highlighted |
 | sheet | viewport below 640px | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the panel; the sheet carries `data-state`, the panel keeps its role and ref; page scroll locked; a swipe down from the handle closes it |
+| segment | inside `Input.Wrapper` | no frame (label, hint, error, support row): the root is `data-field-segment`, the trigger `data-segment="true"` — a tinted section flush with the box's start edge, a stronger fill on hover and while open, an inset focus ring; named «`aria-label`: value» |
 | option highlighted / selected / disabled | keyboard and pointer / value / `disabled` | `data-highlighted`, `data-selected` + `aria-selected`, `data-disabled` + `aria-disabled`; highlight is a fill only |
 
 ## Layout & spacing
@@ -350,8 +353,9 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 - `<ClientAvatar />` or `<RoleBadge />` (your own component) inside an item → the item reads parts by element type and puts an unknown component in the text column; call the helper as a function (`{clientAvatar(client)}`) so `Avatar.Root` / `Badge.Root` is the direct child.
 - A custom trailing element (a Kbd, an icon with a price) as a bare child → wrap it in `Select.ItemMeta`.
 - A «Новый клиент» row faked as a `Select.Item` with a sentinel value, or a button under the field → use `Select.Action`: never filtered, reached by the arrows, never a value.
+- An icon-only Select set beside an Input for one value (an icon + a name) → put it inside `Input.Wrapper` with an `aria-label`; `label`, `hint` and `error` belong to the Input there.
 - Saving the choice in `onValueChange` and resetting the value by hand on failure → return the promise; the Select shows the value, waits and rolls back by itself.
 
 ## Related
-- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (list), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in `multiple`), [Spinner](../spinner/COMPONENT.md) (`loading` and saving in the trigger), [Skeleton](../skeleton/COMPONENT.md) (loading rows), [EmptyPage](../empty-page/COMPONENT.md) (empty state, load error), [Button](../button/COMPONENT.md) (retry), [Divider](../divider/COMPONENT.md) (`Separator`), [Thumbnail](../thumbnail/COMPONENT.md) and [Avatar](../avatar/COMPONENT.md) (row media), [Badge](../badge/COMPONENT.md) (row badge), [VisuallyHidden](../visually-hidden/COMPONENT.md) (loading and save-failure announcements), `Icon` (chevron, clear, check, search, retry), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (list), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in `multiple`), [Spinner](../spinner/COMPONENT.md) (`loading` and saving in the trigger), [Skeleton](../skeleton/COMPONENT.md) (loading rows), [EmptyPage](../empty-page/COMPONENT.md) (empty state, load error), [Button](../button/COMPONENT.md) (retry), [Divider](../divider/COMPONENT.md) (`Separator`), [Thumbnail](../thumbnail/COMPONENT.md) and [Avatar](../avatar/COMPONENT.md) (row media), [Badge](../badge/COMPONENT.md) (row badge), [VisuallyHidden](../visually-hidden/COMPONENT.md) (loading and save-failure announcements), `Icon` (chevron, clear, check, search, retry), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame), [Input](../input/COMPONENT.md) (the start segment of `Input.Wrapper`)
 - **See also:** [NativeSelect](../native-select/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Radio](../radio/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/slider/COMPONENT.md

@@ -59,6 +59,7 @@ Slider                 field frame (FieldFrame): className, ref, rest
 | `required` | `boolean` | — | Red `*` after the label (`aria-hidden`); a range always has a value, so there is no native `required`. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the track (`aria-describedby`). 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` | — | `aria-invalid` on the range input, a danger fill (over any `tone`) and a danger focus ring on the thumb. A non-empty `error` implies it. |
 | `showValue` | `boolean` | `false` | Shows the current value at the end of the label row (tabular numbers, `aria-hidden` — the input announces it). |

package/src/components/slider/examples/controlled.tsx

@@ -24,7 +24,7 @@ export default function SliderControlledExample() {
             type="number"
             min={0}
             max={MAX_DISCOUNT}
-            aria-label="Скидка для клиента, %"
+            aria-label="Скидка для клиента"
             value={discount}
             onValueChange={(text) => {
               const next = Number(text);

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

@@ -15,6 +15,7 @@
 - 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 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.
@@ -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 |
 |---|---|---|---|
@@ -155,14 +159,14 @@ Page.Root                          the page column (<div>); maxWidth, fill, labe
 | `…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 +174,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,6 +236,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` |
+| `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` |
 
 ### layout (Section)
 | Value | Looks like | Use when | Default |
@@ -237,7 +251,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 +263,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 +278,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 |
@@ -273,12 +290,14 @@ The actions stay on the first line beside the heading at every step; `Page.Chips
 | 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 +322,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 +333,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 +345,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`. |
 | [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`. |
 
 ## 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.
@@ -347,7 +374,9 @@ The actions stay on the first line beside the heading at every step; `Page.Chips
 - 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%;