prime-ui-kit 0.17.0 → 0.18.0

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/layout/sidebar/COMPONENT.md

@@ -299,6 +299,7 @@ Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header,
 ## States
 | State | Driven by | DOM |
 |---|---|---|
+| held | a `Page.Guard` that is `busy` or `dirty` on the page | a press on `Sidebar.Item` or `Sidebar.Brand` stops before it navigates (a router link included) and the panel stays; `dirty` asks first, then repeats it |
 | mode | `mode` / `defaultMode` | Root `data-mode`, `data-panel-mode` (the last visible mode while hidden); `<nav inert>` while hidden |
 | off-canvas | `offCanvas="always"`, or `"auto"` + viewport < 768px | Root `data-off-canvas`, `data-state="open" \| "closed"`; `<nav inert>` while closed; the kit scrim (`role="presentation"`) while open; in an `AppShell` the shell Root `data-off-canvas` |
 | placing | the viewport crossed the off-canvas breakpoint (not a person's choice) | Root `data-placing` for one painted frame: the rail lands at its new width with no motion (no growing from 0, no folding rows, no sliding panel) |

package/dist/skill/responsive.md

@@ -48,7 +48,8 @@ A layout inside a page needs no breakpoint: it takes its columns from the room i
 
 - The tiles of a page (KPI cards, charts, panels) are one `Page.Grid` with a
   `Page.Cell span` per tile: it folds by its own width (below 30rem every tile takes the row,
-  then small tiles pair up, from 64rem each its span).
+  then small tiles pair up, from 64rem each its span). Write a wide tile (`span` 7–11) next to a
+  narrow one (4–5): between 40 and 64rem the two pair up as 2/3 + 1/3, so an 8 + 4 row keeps no hole.
 - A grid inside one block (thumbnails, short fields of one record) is the block's own
   `grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--prime-layout-tile-min-width)), 1fr))`
   — `auto-fill`, so a lone item keeps its column width instead of stretching across the row.
@@ -61,9 +62,9 @@ Use these as they are; never wrap them in your own breakpoints.
 
 | Need | Built in |
 |---|---|
-| app frame | `AppShell.Main` hands the page its gutters 16 → 24 → 32 and top air 24 → 32; `Page.TopBar` un-sticks on screens lower than 480px and respects the top safe area; in the bar the title and its line of data truncate |
+| app frame | `AppShell.Main` hands the page its gutters 16 → 24 → 32, top air 24 → 32 and bottom air 64 (the gutter under a `fill` page; above a floating BottomNav it keeps the capsule's room); `Page.TopBar` un-sticks on screens lower than 480px and respects the top safe area |
 | app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by the menu button `Page.TopBar` draws by itself while the Sidebar is off-canvas; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
-| page top bar | `Page.TopBar` lays out its groups from their natural widths: one line while they fit, then the tools on a line of their own, then icon-only buttons, then «⋯», and the heading truncates last ([below](#the-pages-top-bar--pagetopbar)). `Page.Header` in the flow: actions wrap under the title |
+| page top bar | `Page.TopBar` lays out its groups from their natural widths: one line while they fit, then the tools on a line of their own, then icon-only buttons, then «⋯», and the heading gives last ([below](#the-pages-top-bar--pagetopbar)). `Page.Header` in the flow: actions wrap under the title |
 | switchers | [Switchers](#switchers) never wrap or truncate: they scroll inside themselves |
 | tables | DataTable scrolls inside itself, edge shadows show hidden columns, `stickyFirstColumn`, `DataTable.ColumnsMenu` for a column chooser, the toolbar stacks below a 30rem table, sticky head off on short screens |
 | floating layers | Popover (opened from a Trigger), Dropdown, Select (and Datepicker, ColorPresets) never wider than the viewport − 16, 8 from the edges, flip when out of room; below 640 they open as a bottom sheet — scrim, grab handle, swipe down to close, page scroll locked; Tooltip and TagSelect stay anchored |
@@ -85,12 +86,16 @@ in this order, and nothing ever overflows:
 
 1. **One line** — `Page.Heading`, `Page.Tools` and `Page.Actions` side by side while they fit.
 2. **Tools below** — the tools take a line of their own under the first one and fill its width: a
-   search (`SmartFilter.Toolbar`, `Input.Root`) grows first, the switchers share the rest and wrap
-   when one line is not enough. The actions stay on the first line beside the heading at every width.
+   search (`SmartFilter.Toolbar`, `Input.Root`) grows first, the switchers and a period
+   (`Datepicker.Root`) share the rest and wrap when one line is not enough. Beside a search that
+   would get too little room the SmartFilter button shows only its icon and count, on the same row.
+   The actions stay on the first line beside the heading at every width.
 3. **Icons** — every Button with an icon shows only the icon, the secondary ones first, then the
    primary; its label stays its accessible name and becomes its tooltip.
 4. **«⋯»** — the secondary Buttons fold into a menu (`labels.more`); the primary always stays.
-5. **The heading truncates** — only after every button step: the path levels first, then the title.
+5. **The heading gives** — only after every button step: the middle levels of the path fold into
+   «…»; a heading with a path that still does not fit stacks (the path on its own line over the
+   title, the title and its description wrapping), so no level is cut to a fragment; a heading without a path truncates.
 
 `Page.Chips` is always a line of its own under everything, gone while no filter is set. The heading
 keeps its natural width: the bar sizes the title, so there is nothing to tune.
@@ -182,7 +187,7 @@ export function OrdersPage() {
   inside takes that tier.
 - A Button without an icon keeps its label at every step and leaves the bar less room before it
   folds: give each one a `Button.Icon`.
-- A SegmentedControl in `Page.Tools` needs no `fullWidth`: the bar sets it.
+- A SegmentedControl or a Datepicker in `Page.Tools` needs no `fullWidth`: the bar sets it.
 - The primary action is on screen at every width — as its icon at the narrowest; it never folds and
   never disappears.
 - Section totals go into `SegmentedControl.Count`, not into stat cards above the table.

package/dist/skill/ux.md

@@ -55,8 +55,10 @@ Every word on screen must carry something the person does not see already.
   list already counts. The list label names the rows.
 - **No label that repeats its heading.** A field «Цена» inside the section «Цена» needs no label of
   its own beyond what the section says; a group of one field is the field.
-- **A unit lives in one place.** In the field (`Input.InlineAffix`) or in the heading, never both.
-  Prefer the field: the unit stays beside the number when the row stacks.
+- **A unit lives in one place.** In the field (`Input.InlineAffix`) or in the heading, never both;
+  never in the field's own label («Бюджет», not «Бюджет, ₽»). Prefer the field: the unit stays
+  beside the number when the row stacks, and a screen reader hears it with the field (the affix
+  describes the input; `aria-label="рублей"` on it when the sign reads badly).
 - **No text that explains the layout.** «Двигатель, места и скорость всегда первыми» — the lock on
   those rows says it. A hint says what the person cannot see (a format, a consequence, a limit).
 - **One name per thing.** The same action, entity and status keep one word on the whole screen
@@ -97,7 +99,7 @@ Pick the lightest step that keeps the person safe ([choosing.md](choosing.md) ha
 | One standalone action that is easy to redo by hand | `Button.Root holdToConfirm` |
 | Irreversible loss of work, or an outward action that cannot be called back once it leaves the product (an invoice or a message sent to a client, a payment) | `ConfirmDialog` that names the thing and the consequence |
 | Bulk destructive | `ConfirmDialog` that names the count («Удалить 12 счетов?») |
-| Leaving a form with changes | `Modal.Guard` / `Drawer.Guard dirty` |
+| Leaving a form with changes | `Modal.Guard` / `Drawer.Guard dirty`; a form that is the page — `Page.Guard dirty` |
 
 A confirm on every action trains people to click through it; the one that mattered is then missed.
 Which button starts each step and how the confirm behaves:

package/dist/tokens/semantic.d.ts

@@ -801,6 +801,8 @@ export declare const semanticTokens: {
         readonly videoNote: "14.5rem";
         /** The box of a sent round video message (`VideoNote`): its diameter, at most the row. */
         readonly videoNoteBox: "16.75rem";
+        /** The square box of a sticker (`Message.Sticker`), at most the row. */
+        readonly sticker: "10rem";
         /**
          * A message changing size (a reaction row, a transcript that opens): the bubble's box, its
          * parts and the messages around glide in one calm stroke, between `fast` and `base`; zeroed

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "packageManager": "bun@1.3.13",
-  "description": "React 19 UI kit for product interfaces: 78 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
+  "description": "React 19 UI kit for product interfaces: 79 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
   "bin": {
     "prime-ui-kit": "bin/prime-ui-kit.js"
   },

package/src/components/badge/COMPONENT.md

@@ -12,6 +12,7 @@
 - A selected value, keyword or applied filter the user can remove (`onRemove`).
 - Values in a filter panel that toggle on press and hide with a hover action (the `pressed` triad, `Badge.Action`).
 - A short code as a square tile (a file format «PDF») — `shape="square"`.
+- Several badges as one value (the tags of a client, a record's labels) — `Badge.Group`: it wraps and keeps one gap.
 
 ## When not to use
 - A multi-select field with chips → use [TagSelect](../tag-select/COMPONENT.md) (it renders badges itself).
@@ -33,6 +34,8 @@ Badge.Root          <span>: fill, tier dimensions
 │                   (a toggle <button> with the pressed triad; a <span> with a trailing segment; none when read-only)
 ├─ Badge.Action     optional end segment revealed on hover / focus (always shown on touch screens)
 └─ remove segment   with onRemove: full height, the whole end is the hit area (Icon action.close)
+
+Badge.Group         <div>: a wrapping row of Badge.Root, one value; `size` sets every badge's tier
 ```
 
 ## API
@@ -60,6 +63,14 @@ Badge.Root          <span>: fill, tier dimensions
 | `children` | `ReactNode` | — | Text, `Badge.Dot`, `Badge.Icon`, one `Badge.Action`. Only `Badge.Icon` children (no remove or action) make a square icon-only badge. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "onClick" \| "color">` | — | `aria-label` (an icon-only badge named by it is an image) and the other span attributes; no `onClick` — a pressable chip is the toggle. |
 
+### Badge.Group
+`ref` → `HTMLDivElement`. A row of badges as one value (the tags of a record): it wraps onto more lines, the badges a chip gap apart.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | the host tier, one step down | Tier of every badge in the group; a badge's own `size` wins. Small tiers stand closer. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the `Badge.Root`s), `className`, `aria-label` (a named group is `role="group"`) and the other div attributes. |
+
 ### Badge.Icon
 `ref` → `HTMLSpanElement`. A `<span>` holding one icon at the tier icon size. At the first or last position it becomes a full-height edge segment.
 
@@ -163,7 +174,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - `Badge.Dot` is 6px, 8px from `l`; alone it takes the tier of the surrounding control; `color` paints it in the solid step of that hue.
 - The root never clips: the text ellipsizes in its own box, so the segments' touch areas reach past the chip.
 - `Badge.Action` room is reserved, so revealing it never changes the badge width.
-- Several badges in a row: `gap: var(--prime-space-2)`.
+- Several badges in a row: `Badge.Group` — it wraps, badges 8 apart (4 at the `xs` and `s` tiers).
 - In a list row the badge is the trailing column; the title column gets `min-width: 0` and an ellipsis.
 
 ## Accessibility
@@ -206,6 +217,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 | [server-tags.tsx](examples/server-tags.tsx) | Order tags removed on the server: a badge waits dimmed with a spinner, leaves once the server agrees and stays with an announcement when it refuses — `onRemove`, `labels`. |
 | [filter-values.tsx](examples/filter-values.tsx) | Filter values as toggles with a hide action that slides in without changing the width — `pressed`, `onPressedChange`, `Badge.Action`, `persistent`. |
 | [square.tsx](examples/square.tsx) | File formats as square tiles of text, large enough for three letters; the hue sorts them by kind — `shape`, `size`, `color`. |
+| [tag-row.tsx](examples/tag-row.tsx) | The tags of a client as one value: the row wraps in a narrow column and keeps one gap between badges — `Badge.Group`, `size`. |
 | [controlled.tsx](examples/controlled.tsx) | Delivery cities as toggle chips whose state the screen owns: the summary counts the chosen ones — `pressed`, `onPressedChange`. |
 
 ## Mistakes
@@ -217,6 +229,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - Several removable badges with the default «Удалить» → pass `labels.remove` with the badge text.
 - A colored badge with no text → keep a word; color alone is not a signal.
 - An explicit `size` inside a control → drop it; the badge takes the tier one step down.
+- A row of badges in a hand-made flex wrapper with its own gap → `Badge.Group`.
 - `onRemove` together with `Badge.Action` → one end segment per badge.
 - Removing the badge from your list first and putting it back when the request fails → return the request's promise and remove it after it succeeds; the badge waits meanwhile.
 

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

@@ -23,3 +23,10 @@
   align-items: center;
   gap: var(--prime-space-2);
 }
+
+/* tag-row.tsx: a 320 px column, narrow enough for the row of badges to wrap. */
+.column {
+  display: grid;
+  gap: var(--prime-space-6);
+  inline-size: min(100%, calc(var(--prime-space-20) * 4));
+}

package/src/components/badge/examples/tag-row.tsx

@@ -0,0 +1,34 @@
+/** The tags of a client as one value: the row wraps in a narrow column and keeps one gap between badges — `Badge.Group`, `size`. */
+import { Badge } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TAGS = [
+  { label: "Ключевой клиент", color: "purple" },
+  { label: "Оптовые закупки", color: "blue" },
+  { label: "Отсрочка 30 дней", color: "orange" },
+  { label: "ЭДО", color: "teal" },
+  { label: "Москва", color: "gray" },
+  { label: "Новый договор", color: "green" },
+] as const;
+
+export default function BadgeTagRowExample() {
+  return (
+    <div className={styles.column}>
+      <Badge.Group aria-label="Теги клиента">
+        {TAGS.map((tag) => (
+          <Badge.Root key={tag.label} color={tag.color}>
+            {tag.label}
+          </Badge.Root>
+        ))}
+      </Badge.Group>
+      <Badge.Group size="s" aria-label="Теги заказа">
+        {TAGS.slice(0, 4).map((tag) => (
+          <Badge.Root key={tag.label} color={tag.color}>
+            {tag.label}
+          </Badge.Root>
+        ))}
+      </Badge.Group>
+    </div>
+  );
+}

package/src/components/breadcrumb/COMPONENT.md

@@ -23,7 +23,7 @@ import { Breadcrumb } from "prime-ui-kit";
 ## Anatomy
 ```
 Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels; auto-collapse into a «…» menu
-├─ Breadcrumb.Item        <li>: a link (href → LinkButton), text, or the current page (current)
+├─ Breadcrumb.Item        <li>: a link (href → LinkButton, or a router link with asChild), text, or the current page (current)
 └─ Breadcrumb.Ellipsis    <li> with «…» for levels skipped on purpose
 ```
 
@@ -42,14 +42,15 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other `nav` attributes; an `aria-label` here overrides `labels.nav`. |
 
 ### Breadcrumb.Item
-`ref` → `HTMLLIElement`. `<li>`: a muted `LinkButton` (`href`), plain text, or the current page (`current`).
+`ref` → `HTMLLIElement`. `<li>`: a muted `LinkButton` (`href`, or the consumer's router link with `asChild`), plain text, or the current page (`current`). A press on the link goes through `Page.Guard`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `href` | `string` | — | Renders a link; without it the item is text. |
+| `href` | `string` | — | Renders a link; without it (and without `asChild`) the item is text. |
+| `asChild` | `boolean` | `false` | The single child (a router `Link`) is the level's link with the same look; its own text is the level. In the «…» menu of a folded path it is the menu item. |
 | `current` | `boolean` | — | Current page: `aria-current="page"` (on the link when `href` is set), primary text, medium weight. Usually the last item, without `href`. |
 | `aria-label` | `string` | — | Name of a link without visible text (e.g. a home icon); set on the link, not the `li`. |
-| `children` | `ReactNode` | — | Text or an `Icon`. A string also becomes the `title` of a text item (full text when truncated). |
+| `children` | `ReactNode` | — | Text or an `Icon`; with `asChild` one element. A string also becomes the `title` of a text item (full text when truncated). |
 | `…rest` | `Omit<LiHTMLAttributes<HTMLLIElement>, "aria-label">` | — | `className` and the other `li` attributes. |
 
 ### Breadcrumb.Ellipsis
@@ -77,6 +78,7 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 | text (no `href`, no `current`) | muted text | a level without its own page | yes |
 | current (`current`) | primary text, medium weight | the last item — this page | |
 | icon link (`href` + `aria-label`, `Icon` child) | icon at the tier icon size | a «home» root | |
+| router link (`asChild`, one `Link` child) | the same muted link, the consumer's element | an app with a client router: the path moves without a reload | |
 
 Use links for every ancestor and `current` on the last item; `s` above a `heading-m` page title. Avoid `href` on the current item and two `current` items.
 
@@ -89,6 +91,7 @@ Use links for every ancestor and `current` on the last item; `s` above a `headin
 | auto-collapse | 2+ levels whose whole path does not fit the width uncut (measured on every resize) | `data-collapsible="true"`, `data-collapsed="true"`; middle levels are `display: none` and replaced by «… ›»: a ghost menu button (`Dropdown.Trigger`, named by `labels.ellipsis`) whose menu lists them — links stay links, a level without `href` is a disabled row |
 | deep collapse | the path folded as above still does not fit | `data-collapsed="deep"`; the first level folds too: «…» › current page, the menu lists every level before it |
 | collapse menu open | a press, `Enter` or `ArrowDown` on the «…» | `aria-expanded="true"` on the button; a `role="menu"` panel at the tier size |
+| held | a `Page.Guard` that is `busy` or `dirty` on the page | a press on a level's link (in the path or the «…» menu) stops before it navigates; `dirty` asks first, then repeats it |
 
 Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`), `data-collapsed` (`"true"` / `"deep"`).
 
@@ -133,12 +136,14 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`), `data-c
 | [with-icon.tsx](examples/with-icon.tsx) | The root level as a home icon; a link without text is named for screen readers — `aria-label`. |
 | [overflow.tsx](examples/overflow.tsx) | A long path: levels truncate, and in a 320px container the middle ones collapse into a «…» menu that lists them — `Breadcrumb.Item`, `current`. |
 | [ellipsis.tsx](examples/ellipsis.tsx) | Levels skipped on purpose shown as «…» whose hidden text names them for screen readers — `Breadcrumb.Ellipsis`, `labels`. |
+| [router.tsx](examples/router.tsx) | Router links as the levels above: the path moves without a reload; render it inside a router — `asChild`, `current`. |
 
 ## Mistakes
 - Separators by hand between items → the root draws the chevrons.
 - `<Breadcrumb.Item href="…" current>` → the current page has no `href`.
 - Breadcrumb inside a flex row collapsing to zero width → give it `flex: 1 1 auto; min-width: 0`.
 - Home icon link without `aria-label` → add `aria-label="Главная"`.
+- `href` + `onClick` with `preventDefault()` and `navigate()` for a router → `asChild` with the router's `Link`.
 
 ## Related
 - **Built from:** [LinkButton](../link-button/COMPONENT.md) (`tone="muted"`), [Button](../button/COMPONENT.md) and [Dropdown](../dropdown/COMPONENT.md) (the collapse menu), Icon (`nav.chevronRight`), [VisuallyHidden](../visually-hidden/COMPONENT.md)

package/src/components/breadcrumb/examples/router.tsx

@@ -0,0 +1,17 @@
+/** Router links as the levels above: the path moves without a reload; render it inside a router — `asChild`, `current`. */
+import { Breadcrumb } from "prime-ui-kit";
+import { Link } from "react-router-dom";
+
+export default function BreadcrumbRouterExample() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item asChild>
+        <Link to="/crm">CRM</Link>
+      </Breadcrumb.Item>
+      <Breadcrumb.Item asChild>
+        <Link to="/crm/clients">Клиенты</Link>
+      </Breadcrumb.Item>
+      <Breadcrumb.Item current>ООО «Северный ветер»</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}

package/src/components/button/COMPONENT.md

@@ -66,7 +66,7 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | `labels` | `Partial<ButtonLabels>` | — | Built-in strings, see Labels. |
 | `asChild` | `boolean` | `false` | Merges Button props and styles onto the single child element (a link) instead of rendering `<button>`. `disabled`/`loading` become `aria-disabled`; `progress` and `holdToConfirm` need a `<button>`. |
 | `disabled` | `boolean` | — | Disabled state; `loading` also disables. With `asChild` the child leaves the Tab order and a link loses its `href`. |
-| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. With `asChild`, the one child element. |
+| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. With `asChild`, the one child element; its text is the label too. |
 | `aria-label` | `string` | — | The name of a button without a visible label; required with `shape="circle"`. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size" \| "aria-pressed">` | — | `onClick`, `type` (`"button"` by default, not passed on with `asChild`), `className`, `aria-*`, `data-*` and the other button attributes. |
 

package/src/components/button-group/COMPONENT.md

@@ -47,6 +47,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 `group`. |
 | `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 `group`; 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/card/COMPONENT.md

@@ -47,6 +47,7 @@ Card.Root asChild                <a> or <button> (the only child) holding the pa
 |---|---|---|---|
 | `variant` | `"panel" \| "mini" \| "stat-trend" \| "split" \| "cta" \| "list" \| "cover"` | `"panel"` | Structural template: titled block with zones (`panel`), KPI tiles, a call to action, a list or a cover tile. |
 | `flat` | `boolean` | `false` | No raised shadow: a flat tile for dense grids. |
+| `loading` | `boolean` | `false` | The KPI is loading: `Card.Value`, `Card.Delta` and `Card.Meta` show a Skeleton in their own geometry and the root sets `aria-busy`; the data fades in when it arrives. Labels and titles stay. |
 | `asChild` | `boolean` | `false` | The whole card is one link or button: pass that element as the only child with the parts inside it; it gets hover, press and the focus ring. Nothing interactive may sit inside it. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` + `aria-labelledby` for a landmark block, and the other div attributes. |
 
@@ -154,6 +155,7 @@ Card.Root asChild                <a> or <button> (the only child) holding the pa
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `flat` | same fill, no shadow | dense grids of tiles | `false` |
+| `loading` | `Card.Value`, `Card.Delta` and `Card.Meta` hold a Skeleton in their own geometry (the value a bar one line of its role high); the data fades in under the same element | a KPI waits for its report | `false` |
 | `asChild` | the card is the link or button it wraps: lifts on hover (raised → overlay shadow), presses, focus ring | the whole tile opens its details | `false` |
 
 ## States
@@ -161,6 +163,7 @@ Card.Root asChild                <a> or <button> (the only child) holding the pa
 |---|---|---|
 | template | `variant` | `data-variant` |
 | flat | `flat` | `data-flat` |
+| loading | `loading` | `aria-busy` on the root; `data-loading` on `Card.Value`, `Card.Delta`, `Card.Meta`, each holding a `Skeleton`; on `false` the data fades in (`useSwapIn`, foundation §1 rule 7) |
 | depth | nesting: one above the nearest surface (the page and the AppShell panel are 0) | `data-depth` (`1`–`4`, `floating-1`/`floating-2` inside a floating layer); the fill is `--prime-color-layer-current`, the shadow only at depth 1 |
 | card width | container queries | `split` stacks below 22rem, `Header` wraps below 22rem (a header control under its description), the `stat-trend` value changes at 20rem / 36rem |
 | hover | `asChild`, a fine pointer | the fill stays (a whole surface never changes its fill, foundation §8); the shadow lifts to `--prime-shadow-overlay` over `fast` |
@@ -195,6 +198,7 @@ Without `asChild` a card is static: no hover, focus or press of its own. With it
 - `Card.Root` is a plain `<div>`; give it `role="region"` + `aria-labelledby` only when it is a landmark-worthy block.
 - `Card.Title` renders `<h3>`; directly under the page title pass `as="h2"`.
 - Decorative icons in `Card.Icon` and cover images in `Card.Media` get `aria-hidden`; controls in `Card.Header` need their own names.
+- A `loading` card sets `aria-busy` on its root; the Skeletons are decorative (`aria-hidden`).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -211,6 +215,7 @@ No `labels`.
 | [interactive.tsx](examples/interactive.tsx) | Whole cards as links to their reports: one tab stop each, a lift on hover, a press and the focus ring — `asChild`. |
 | [content-templates.tsx](examples/content-templates.tsx) | Content templates: a call to action, an events list and a campaign tile with a cover — `Card.Footer`, `Card.List`, `Card.Media`. |
 | [flat.tsx](examples/flat.tsx) | A flat tile without the raised shadow next to the default one, for dense grids — `flat`. |
+| [states.tsx](examples/states.tsx) | A KPI tile while its report loads next to the loaded one, in the `stat-trend` and `mini` templates — `loading`. |
 | [narrow.tsx](examples/narrow.tsx) | The card is a size container: the split template stacks its cells below 22rem and the trend value shrinks below 20rem — `variant`. |
 | [screen.tsx](examples/screen.tsx) | A dashboard: the title and a line of data in the page flow, the period switch and the report in the top bar that keeps the title once it scrolls away; one grid of KPI tiles that cross-fade to the new period, a revenue trend, invoiced against paid beside two panels, and the latest payments with a link to the list — `collapse`, `Page.Grid`. |
 
@@ -225,7 +230,8 @@ No `labels`.
 - A clickable `<div>` card with `onClick` → `asChild` with a real `<a href>` (Cmd-click, a new tab) or a `<button>`.
 - Buttons or links inside an `asChild` card → nested interactive elements; move them out of the card.
 - The reference figures written into `Card.Delta` or `Card.Label` → `Card.Meta`.
+- Skeletons placed by hand inside `Card.Value` → `Card.Root loading`; keep the parts mounted while loading so each holds its place.
 
 ## Related
-- **Built from:** —
+- **Built from:** [Skeleton](../skeleton/COMPONENT.md)
 - **See also:** [Page](../../layout/page/COMPONENT.md), [DescriptionList](../description-list/COMPONENT.md) (record details inside a `Card.Body`), [Fieldset](../fieldset/COMPONENT.md) (groups of fields inside a settings card), [DataTable](../data-table/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Sparkline](../sparkline/COMPONENT.md) (a trend with its total inside a `panel`), [ChartFrame](../chart-frame/COMPONENT.md) (a full chart with legend and states)

package/src/components/card/examples/states.tsx

@@ -0,0 +1,59 @@
+/** A KPI tile while its report loads next to the loaded one, in the `stat-trend` and `mini` templates — `loading`. */
+import { Card, Icon, Typography } from "prime-ui-kit";
+
+export default function CardStatesExample() {
+  return (
+    <>
+      <div>
+        <div>
+          <Card.Root variant="stat-trend" loading>
+            <Card.Label>Выручка за месяц</Card.Label>
+            <Card.Value />
+            <Card.Delta />
+            <Card.Meta />
+          </Card.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            stat-trend · loading
+          </Typography>
+        </div>
+        <div>
+          <Card.Root variant="stat-trend">
+            <Card.Label>Выручка за месяц</Card.Label>
+            <Card.Value>4,2 млн ₽</Card.Value>
+            <Card.Delta tone="success">+18% к сентябрю</Card.Delta>
+            <Card.Meta>Лидов 1 240 · сделок 186</Card.Meta>
+          </Card.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            stat-trend
+          </Typography>
+        </div>
+      </div>
+      <div>
+        <div>
+          <Card.Root variant="mini" loading>
+            <Card.Icon>
+              <Icon name="object.users" />
+            </Card.Icon>
+            <Card.Label>Активные сессии</Card.Label>
+            <Card.Value />
+          </Card.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            mini · loading
+          </Typography>
+        </div>
+        <div>
+          <Card.Root variant="mini">
+            <Card.Icon>
+              <Icon name="object.users" />
+            </Card.Icon>
+            <Card.Label>Активные сессии</Card.Label>
+            <Card.Value>1 248</Card.Value>
+          </Card.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            mini
+          </Typography>
+        </div>
+      </div>
+    </>
+  );
+}

package/src/components/chat/COMPONENT.md

@@ -81,6 +81,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 - `renderMessage` may be an inline function: an item renders again only when it or its place changes, so whatever a row shows lives in its item (an edit, a reaction, a pin). Another message (a reply's original) comes from `entry.find(key)`.
 - `onRead` reports an incoming message once at least half of it, or half the view, has been on screen while the page is visible (`IntersectionObserver`); batched per frame, each `value` once per mount.
 - One sound at a time on the page: a `VoicePlayer`, a `VideoNote` and a video in `Message.Media` pause each other; nothing to wire.
+- Times in a profile's zone: `timeZone` (an IANA name) on `Chat.Messages` moves the date separators, the runs and every message's time to it; without it they follow the browser.
 
 ## API
 
@@ -174,7 +175,8 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `unread` | `string` | — | The key of the first unread item: the «Непрочитанные сообщения» band stands above it. |
 | `groupWindow` | `number` | `5` | Messages of one author further apart than this many minutes start a new run. |
 | `now` | `Date` | today | «Today» for the dates. |
-| `formatDate` | `(date: Date, now: Date) => string` | `formatMessageDate` | The label of a date. |
+| `timeZone` | `string` | the browser's zone | The IANA zone of the date separators, the runs and every message time (`"Asia/Vladivostok"`): a profile's zone, not the browser's. |
+| `formatDate` | `(date: Date, now: Date, timeZone?: string) => string` | `formatMessageDate` | The label of a date; gets the `timeZone`. |
 | `loading` | `boolean` | `false` | The first load: bubble-shaped `Skeleton`s on both sides stand in the list's place (`aria-busy`, `labels.loading` announced), then cross-fade into the messages; none of them counts as new. |
 | `hasOlder` | `boolean` | `false` | Older history exists: a bubble-shaped placeholder stands above the first message and `onLoadOlder` runs when the reader reaches the top. |
 | `onLoadOlder` | `() => void \| Promise<void>` | — | Load older messages and prepend them (while `hasOlder`); the reader's place is kept. |
@@ -334,6 +336,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | [reactions.tsx](examples/reactions.tsx) | A team's own reactions for approvals: a double tap or `L` puts the approval mark, a long press or `R` opens the team's set, and a chip toggles them back — `quickReaction`, `reactionOptions`, `onReactionToggle`. |
 | [live.tsx](examples/live.tsx) | A live support chat: the client types — the header and the end of the list say so — then answers; new messages enter at the end, read receipts come from what is on screen, and scrolled up the round button counts what arrived — `typing`, `onNewMessage`, `onRead`. |
 | [search.tsx](examples/search.tsx) | Search and pinned messages: the search bar marks every match in the texts and transcripts, counts them and steps between them while the others step back; a pinned message's press jumps to it and blinks it — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. |
+| [time-zone.tsx](examples/time-zone.tsx) | The conversation in the zone of the manager's profile, not the browser's: the date separators, the runs and every time follow it — `timeZone`, `items`, `renderMessage`. |
 | [states.tsx](examples/states.tsx) | The first load of a conversation: bubble-shaped placeholders on both sides stand in the list's place, then cross-fade into the messages — `loading`. |
 | [controlled.tsx](examples/controlled.tsx) | Selection mode owned by the screen: the Select item of a message's menu starts it, a check stands beside every message, a press toggles one while the others step back, the bar counts and acts, Escape leaves — `selected`, `onSelectedChange`, `Chat.SelectionBar`. |
 | [narrow.tsx](examples/narrow.tsx) | At phone width the header keeps its actions and lets the title ellipsize, bubbles take up to 85% of the chat, long links wrap and an album keeps its layout — `Chat.Root`, `Chat.Header`, `Chat.Messages`, `Chat.Footer`. |