prime-ui-kit 0.17.0 → 0.19.0

package/dist/skill/layouts.md

@@ -5,10 +5,12 @@ The app is navigation and the page: `AppShell.Root` with the Sidebar in `AppShel
 app's; everything inside Main is the page's — a screen renders one `Page.Root` with its own top
 (`Page.TopBar`: the page title and the page's tools, [composition.md](composition.md#1-page-skeleton))
 and its body in `Page.Body`.
-`AppShell.Main` hands the page its gutters and top air and `Page` spaces it — blocks 24, a titled
+`AppShell.Main` hands the page its gutters and its edge air and `Page` spaces it — blocks 24, a titled
 `Page.Section` 40, tiles in a `Page.Grid` 16 on both axes — so your code adds **no outer padding and no margins**. Your CSS only lays out the inside of a block (grids, rows) with `gap` on `--prime-space-*`.
-The page's top air is part of the frame — 24, then 32 from 1024px: the page's first block
-starts there; never cancel it with a negative margin or a padding override.
+The edge air is part of the frame. On top: 24, then 32 from 1024px, where a page without a bar
+starts; under a `Page.TopBar` the body starts 24 below the bar's controls. At the bottom: a long
+page keeps a 64 scroll tail, a `Page.Root fill` page only the side gutter, beside the Sidebar rail
+as well. Never cancel it with a negative margin or a padding override.
 
 The page recipes are whole, working screens — the `screen.tsx` example of their main component
 ([the list](composition.md#screens)): start from the closest one and keep its skeleton. The rules behind them are in [composition.md](composition.md).
@@ -153,7 +155,7 @@ shows only icons); none on the children of a sub-list.
   page's title and tools are in its `Page.TopBar`, its blocks go into `Page.Body`
   ([the page skeleton](composition.md#1-page-skeleton)).
 - Document pages — settings and long forms: `Page.Root maxWidth="wide"` with `Page.Header` in the
-  flow (the page's h1) and a `Page.Section layout="aside"` (heading column + panel) per section
+  flow (the page's h1) and a `Card.Root` with its own `Card.Header` per section
   ([the settings page](reference/layout/page/examples/screen.tsx)), or `maxWidth="readable"` for a single
   narrow column of fields.
 - Long reading text (terms, help): `Page.Root maxWidth="readable"` with `Page.Header` in the flow.

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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`. |

package/dist/skill/reference/components/chat/examples/time-zone.tsx

@@ -0,0 +1,83 @@
+/** 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`. */
+import { Card, Chat, Message, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const ZONES = [
+  { value: "Europe/Moscow", label: "Москва" },
+  { value: "Asia/Vladivostok", label: "Владивосток" },
+];
+
+const NOW = new Date(Date.UTC(2026, 9, 15, 4, 0));
+const utc = (day: number, hour: number, minute: number) =>
+  new Date(Date.UTC(2026, 9, day, hour, minute));
+
+const MESSAGES = [
+  {
+    id: "tz-1",
+    author: "client",
+    sentAt: utc(14, 12, 40),
+    text: "Добрый вечер! Машина с заказом № 4821 уже вышла?",
+  },
+  {
+    id: "tz-2",
+    author: "manager",
+    sentAt: utc(14, 13, 5),
+    text: "Вышла в 18:00, будет у вас завтра до обеда.",
+  },
+  {
+    id: "tz-3",
+    author: "client",
+    sentAt: utc(14, 14, 30),
+    text: "Спасибо, предупрежу склад.",
+  },
+  {
+    id: "tz-4",
+    author: "manager",
+    sentAt: utc(15, 0, 10),
+    text: "Водитель на месте, выгрузка через 10 минут.",
+  },
+];
+
+type ChatMessage = (typeof MESSAGES)[number];
+
+export default function ChatTimeZoneExample() {
+  const [zone, setZone] = React.useState("Asia/Vladivostok");
+
+  return (
+    <div className={styles.live}>
+      <div className={styles.liveBar}>
+        <SegmentedControl.Root value={zone} onValueChange={setZone} aria-label="Пояс профиля">
+          {ZONES.map((item) => (
+            <SegmentedControl.Item key={item.value} value={item.value}>
+              {item.label}
+            </SegmentedControl.Item>
+          ))}
+        </SegmentedControl.Root>
+      </div>
+      <Card.Root className={styles.short}>
+        <Chat.Root>
+          <Chat.Messages
+            aria-label="Переписка по заказу № 4821"
+            timeZone={zone}
+            now={NOW}
+            items={MESSAGES}
+            getKey={(message: ChatMessage) => message.id}
+            getAuthor={(message: ChatMessage) => message.author}
+            getDate={(message: ChatMessage) => message.sentAt}
+            renderMessage={(message: ChatMessage) => (
+              <Message.Root
+                direction={message.author === "manager" ? "outgoing" : "incoming"}
+                time={message.sentAt}
+                status={message.author === "manager" ? "read" : undefined}
+              >
+                <Message.Text>{message.text}</Message.Text>
+              </Message.Root>
+            )}
+          />
+        </Chat.Root>
+      </Card.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/chat-list/COMPONENT.md

@@ -28,7 +28,7 @@ ChatList.Root                 <div> column filling its host (container `chat-lis
 ├─ ScrollContainer            the list's own scroller; onReachEnd → onLoadMore while hasMore
 │  └─ Crossfade               loading (placeholder List rows) ⇄ empty (EmptyPage compact) ⇄ the list
 │     └─ List.Root <ul>       aria-label «Диалоги»; spacer <li aria-hidden> stand for rows out of view
-│        └─ ChatList.Item     List.Item <li> + <button> | <a href>; current from value; one Tab stop
+│        └─ ChatList.Item     List.Item <li> + <button> | <a href> | your element (asChild); current from value; one Tab stop
 │           ├─ ChatList.ItemIcon         before the name: avatar slot (aria-hidden); after it: a glyph
 │           ├─ ChatList.ItemText         the name; muted glyph after it
 │           ├─ ChatList.ItemDescription  author · media word · text — cross-fades with draft and «печатает…»
@@ -62,12 +62,13 @@ ChatList.Root                 <div> column filling its host (container `chat-lis
 | `empty` | `ReactNode` | — | The empty state without a search (an `EmptyPage` with an action). Default: «Нет диалогов». |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Row tier: height, text, avatar, glyphs and the search field. Without it the tier of the host. |
 | `now` | `Date` | — | «Now» for the times of the rows. Default: the moment of the render. |
-| `formatTime` | `(date: Date, now: Date) => string` | `formatChatTime` | Display of a row's `Date` time: «14:32» today, «пн» this week, «12 мар», «12.03.2025». |
+| `timeZone` | `string` | the browser's zone | The IANA zone the times of the rows are read in (`"Asia/Vladivostok"`): a profile's zone, not the browser's. |
+| `formatTime` | `(date: Date, now: Date, timeZone?: string) => string` | `formatChatTime` | Display of a row's `Date` time: «14:32» today, «пн» this week, «12 мар», «12.03.2025»; gets the `timeZone`. |
 | `labels` | `Partial<ChatListLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other `div` attributes of the column. |
 
 ### ChatList.Item
-`ref` → `HTMLElement` (the `<button>` or `<a>`, not the `<li>`). A dialog: a `List.Item` row with the avatar, the name and the time over the preview and the counts. Its key and `current` come from the root.
+`ref` → `HTMLElement` (the `<button>`, `<a>` or `asChild` element, not the `<li>`). A dialog: a `List.Item` row with the avatar, the name and the time over the preview and the counts. Its key and `current` come from the root.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -83,7 +84,8 @@ ChatList.Root                 <div> column filling its host (container `chat-lis
 | `href` | `string` | — | Renders an `<a>` instead of a `<button>` (a dialog with its own URL). |
 | `target` | `string` | — | Where the `<a>` opens (`href` only). |
 | `rel` | `string` | — | Relationship of the `<a>` (`href` only). |
-| `children` | `ReactNode` | — | `ChatList.ItemIcon`, `ChatList.ItemText`, `ChatList.ItemDescription`, `ChatList.ItemMenu`. |
+| `asChild` | `boolean` | `false` | The one child element (a router `Link`) is the row; the parts go inside it. |
+| `children` | `ReactNode` | — | `ChatList.ItemIcon`, `ChatList.ItemText`, `ChatList.ItemDescription`, `ChatList.ItemMenu` — inside the child element with `asChild`. |
 | `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `className` and the native attributes of the row element. |
 
 ### ChatList.ItemIcon
@@ -150,6 +152,7 @@ The search field takes the tier too; counts are one tier down (the Badge's own r
 | `muted` | a muted glyph after the name; the count soft gray | notifications are off | `false` |
 | `mention` | a solid «@» before the count | the reader is mentioned | `false` |
 | `pinned` | a pin under the time while nothing is unread | pinned by the reader — order pinned first in `items` | `false` |
+| `asChild` | the same row, rendered as your one child element with the parts inside it | a router's `Link` opens the dialog without a reload | `false` |
 | `status` | ✓ / ✓✓ in the accent / clock / failure mark before the time | the reader wrote the last message | — |
 
 ## States
@@ -195,7 +198,7 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 ### ARIA
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-- The list is a `<ul>` named «Диалоги» (`labels.list`); each row an `<li>` with a button, or a link with `href`.
+- The list is a `<ul>` named «Диалоги» (`labels.list`); each row an `<li>` with a button, a link with `href`, or your link with `asChild`.
 - The open dialog is `aria-current="true"` on a button, `"page"` on a link. Selection does not follow the focus: arrows only move it (a dialog may load a conversation); Enter, Space and a click open.
 - The row is named by its content: the name, glyphs with a `label` («Без звука», a verified mark), the preview, the delivery mark («Прочитано»), the time, then «упоминание» and «непрочитанных: 3» instead of the bare badges; the avatar is `aria-hidden`.
 - While the other side types, the preview is `aria-hidden` and «печатает…» is read; a draft reads «Черновик: …».
@@ -243,7 +246,8 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 | [search.tsx](examples/search.tsx) | The search field filters dialogs by name and by the last message, marks the match in both, says how many were found and shows a quiet state when none match — `defaultSearch`, `onSearchChange`. |
 | [live.tsx](examples/live.tsx) | A live inbox: a client types, then writes — the preview turns into the typing line and back, the count rolls up and the dialog glides to the top; opening it clears the count — `typing`, `unread`, `items`. |
 | [long-list.tsx](examples/long-list.tsx) | A sales inbox of a thousand dialogs: only the rows around the view render, arrows walk through all of them, and the next page loads as the end comes near — `hasMore`, `onLoadMore`. |
-| [links.tsx](examples/links.tsx) | Dialogs with their own address: every row is a link the router opens, the time reads as how long ago, and the list is named for its queue — `href`, `formatTime`, `labels`. |
+| [links.tsx](examples/links.tsx) | Dialogs with their own address: every row is a link to the ticket's page, the time reads as how long ago, and the list is named for its queue — `href`, `formatTime`, `labels`. |
+| [router.tsx](examples/router.tsx) | Router links as the dialogs, the times in the zone of the operator's profile; render it inside a router — `asChild`, `timeZone`. |
 | [states.tsx](examples/states.tsx) | Loading and empty: placeholder rows in the rows' geometry cross-fade into the dialogs; a new workspace without dialogs shows its own empty state with an action — `loading`, `empty`. |
 | [controlled.tsx](examples/controlled.tsx) | The open dialog lives in the screen: a row opens it beside the list, and a next-unread button opens the next one from outside — `value`, `onValueChange`. |
 | [narrow.tsx](examples/narrow.tsx) | At phone width long names and previews truncate while the time and counts stay whole; a pane squeezed under 240px keeps only the names and the counts — `ChatList.Root`, `search`. |
@@ -256,6 +260,8 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 - An `Avatar.Root size="s"` to fit the row → leave `size` out; the slot sizes the avatar to the tier.
 - A «⋯» button nested inside the row for the menu → `ChatList.ItemMenu`: it opens on right click, a long press and Shift+F10.
 - Deleting from the menu without a question → open a `ConfirmDialog` from the menu item.
+- `href` with an `onClick` that calls `preventDefault()` and the router's `navigate` → `asChild` with the router's `Link`, the parts inside it.
+- Times shifted by hand to a profile's zone before `time` → `timeZone` on the root: «сегодня», the weekday and the clock are read in it.
 
 ## Related
 - **Built from:** [List](../list/COMPONENT.md) (rows, current fill, focus, touch height), [Input](../input/COMPONENT.md) (search), [ScrollContainer](../scroll-container/COMPONENT.md), [Crossfade](../crossfade/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Badge](../badge/COMPONENT.md) (counts), [Dropdown](../dropdown/COMPONENT.md) (row menu), [VisuallyHidden](../visually-hidden/COMPONENT.md), `useFlipList` (the glide of a new order)

package/dist/skill/reference/components/chat-list/examples/links.tsx

@@ -1,4 +1,4 @@
-/** Dialogs with their own address: every row is a link the router opens, the time reads as how long ago, and the list is named for its queue — `href`, `formatTime`, `labels`. */
+/** Dialogs with their own address: every row is a link to the ticket's page, the time reads as how long ago, and the list is named for its queue — `href`, `formatTime`, `labels`. */
 import { Avatar, Card, ChatList, hueOf } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/dist/skill/reference/components/chat-list/examples/router.tsx

@@ -0,0 +1,63 @@
+/** Router links as the dialogs, the times in the zone of the operator's profile; render it inside a router — `asChild`, `timeZone`. */
+import { Avatar, Card, ChatList, hueOf } from "prime-ui-kit";
+import { Link } from "react-router-dom";
+
+import styles from "./examples.module.css";
+
+const NOW = new Date(Date.UTC(2026, 9, 15, 4, 0));
+const utc = (day: number, hour: number, minute: number) =>
+  new Date(Date.UTC(2026, 9, day, hour, minute));
+
+const DIALOGS = [
+  {
+    id: "c-311",
+    name: "ООО «Вектор»",
+    initials: "ВК",
+    preview: "Машина на месте, начинаем выгрузку",
+    at: utc(15, 0, 10),
+    unread: 1,
+  },
+  {
+    id: "c-308",
+    name: "ООО «Гранит»",
+    initials: "ГР",
+    preview: "Счёт № 2041 оплачен",
+    at: utc(14, 14, 30),
+    unread: 0,
+  },
+  {
+    id: "c-297",
+    name: "ИП Козлов",
+    initials: "ИК",
+    preview: "Пришлите, пожалуйста, акт сверки",
+    at: utc(12, 6, 15),
+    unread: 0,
+  },
+];
+
+export default function ChatListRouterExample() {
+  return (
+    <Card.Root className={styles.short}>
+      <ChatList.Root
+        items={DIALOGS}
+        getKey={(item) => item.id}
+        defaultValue="c-311"
+        now={NOW}
+        timeZone="Asia/Vladivostok"
+        renderItem={(item) => (
+          <ChatList.Item asChild time={item.at} unread={item.unread}>
+            <Link to={`/chats/${item.id}`}>
+              <ChatList.ItemIcon>
+                <Avatar.Root color={hueOf(item.id)}>
+                  <Avatar.Fallback>{item.initials}</Avatar.Fallback>
+                </Avatar.Root>
+              </ChatList.ItemIcon>
+              <ChatList.ItemText>{item.name}</ChatList.ItemText>
+              <ChatList.ItemDescription>{item.preview}</ChatList.ItemDescription>
+            </Link>
+          </ChatList.Item>
+        )}
+      />
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/checkbox/COMPONENT.md

@@ -50,6 +50,7 @@ Checkbox.Indicator     the box alone, no input — a mark inside option / menu r
 | `optional` | `boolean` | `false` | Muted `labels.optional` after the label text; the field may stay off. |
 | `labels` | `Partial<CheckboxLabels>` | — | 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 unchecked box and `aria-invalid`. A non-empty `error` implies it. |
 | `disabled` | `boolean` | `false` | Disabled fill, dimmed label and hint, no toggling. |