prime-ui-kit 0.17.0 → 0.19.0

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`. |

package/src/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/src/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/src/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/src/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/src/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. |

package/src/components/color-field/COMPONENT.md

@@ -12,7 +12,7 @@
 
 ## When not to use
 - The color comes from a short fixed palette and the choice should be visible at once → use [ColorSwatches](../color-swatches/COMPONENT.md).
-- A compact color next to a field or in a dense list row → use [ColorPresets](../color-picker/COMPONENT.md) (square trigger + palette).
+- A compact color next to a field or in a dense list row → use [ColorPresets](../color-picker/COMPONENT.md) (square trigger + palette; `allowCustom` adds a hex field for any other color).
 - The picker panel itself is the screen (a design tool, an inline editor) → compose [ColorPicker](../color-picker/COMPONENT.md) parts.
 - A plain text field for a hex code → use [Input](../input/COMPONENT.md).
 
@@ -55,6 +55,7 @@ ColorField                       field frame: label · field button · hint | er
 | `required` | `boolean` | `false` | Red `*` after the label; the field button is described by `labels.required` (a button takes no `aria-required`). |
 | `optional` | `boolean` | — | 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` | — | Danger ring and `aria-invalid` without a message. A non-empty `error` implies it. |
 | `disabled` | `boolean` | `false` | Disables the field: it shows the color and does not open. |

package/src/components/color-picker/COMPONENT.md

@@ -7,7 +7,7 @@
 
 ## When to use
 - `ColorPicker` — any color is allowed and the picker parts are laid out by hand: an inline panel, a design tool, a hex field with a custom trigger.
-- `ColorPresets` — a color from a fixed palette with an optional «no color»: label, project or calendar colors, one trigger per row.
+- `ColorPresets` — a color from a fixed palette with an optional «no color»: label, project or calendar colors, one trigger per row. With `allowCustom` the palette is a shortcut, not a limit: any hex is typed under it (a spec color on a site, a brand color in a dense list row).
 - `parseColor` — turning a CSS string into a `Color` for a controlled `ColorPicker`.
 
 ## When not to use
@@ -49,6 +49,7 @@ ColorPresets.Root                value, open, presets (no DOM)
 ├─ ColorPresets.Trigger          slot around one element
 │  └─ ColorPresets.SwatchButton  square swatch button (or your Button with ColorPresets.Swatch)
 └─ ColorPresets.Content          popover with the swatch grid (listbox)
+   └─ Input                      hex field with the typed color's chip (`allowCustom`)
 ```
 Helpers: `parseColor(value)` (throws on invalid input; back to text with `color.toString("hex" | "hexa" | "css")`), `COLOR_PRESETS` (16 colors: step 500 and step 700 of eight hues), types `ColorPickerColorValue`, `ColorValueFormat`, `ColorPreset`.
 
@@ -86,6 +87,7 @@ No DOM. Holds the color (React Aria `ColorPicker`) and the value format for ever
 |---|---|---|---|
 | `label` | `ReactNode` | — | Field label; defaults to `labels.hex`. |
 | `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; marks the field invalid. |
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring of the fields (`data-focus-ring="false"`); focus, keyboard and ARIA stay. |
 | `children` | `ReactNode` | — | End segments of the field box after the value: `ColorPicker.SwatchButton` (in a `Popover.Trigger`), so the hex and its swatch read as one field. |
@@ -164,7 +166,7 @@ No DOM. Holds the color (React Aria `ColorPicker`) and the value format for ever
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `presets` | `readonly ColorPreset[]` | `COLOR_PRESETS` | Swatches `{ value, label }`; the label names the swatch. |
-| `label · hint · error · invalid · required · optional · disabled · size · id · labels · aria-label · aria-labelledby · aria-describedby` | `ColorSwatchesProps` | — | As on `ColorSwatches`. |
+| `label · hint · hintTone · error · invalid · required · optional · disabled · size · id · labels · aria-label · aria-labelledby · aria-describedby` | `ColorSwatchesProps` | — | As on `ColorSwatches`. |
 | `…rest` | `Omit<ColorSwatchesProps, "value" \| "defaultValue" \| "onValueChange" \| "allowEmpty" \| "name">` | — | `className` and the other attributes of the field frame. |
 
 ### ColorPicker.EyeDropperButton
@@ -194,6 +196,7 @@ No DOM and no ref, except a field frame in a FieldList cell (the column heading
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the trigger, the swatches and the panel. Without it the tier of its host, else `m`. |
 | `disabled` | `boolean` | `false` | The trigger is disabled and does not open the panel. A disabled `Fieldset` around it sets it too. |
 | `allowEmpty` | `boolean` | `false` | Adds the «no color» swatch after the presets (value `null`). |
+| `allowCustom` | `boolean` | `false` | Any color beyond the palette: a hex field under the swatches (`labels.custom`) shows the typed color, Enter picks it as `#rrggbb`; invalid text gets `labels.customInvalid`. |
 | `closeOnSelect` | `boolean` | `true` | Close the panel after a pick (focus returns to the trigger). |
 | `labels` | `Partial<ColorPresetsLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — (required) | `ColorPresets.Trigger` and `ColorPresets.Content`. |
@@ -260,6 +263,7 @@ No `variant` / `tone` / `color`.
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `allowEmpty` (ColorPresets) | checkerboard «Без цвета» swatch at the end | the color is optional | `false` |
+| `allowCustom` (ColorPresets) | a «Свой цвет» hex field under the swatches, its chip showing the typed color | any color is valid, the palette only speeds the common ones | `false` |
 | `closeOnSelect={false}` (ColorPresets) | panel stays open after a pick | trying several colors in a row | `true` |
 | `closeOnOutsideClick={false}` (ColorPresets) | a press beside the panel keeps it open | comparing presets with the page | `true` |
 | `closeOnEscape={false}` (ColorPresets) | Escape leaves the panel open | the panel closes only by a pick or the trigger | `true` |
@@ -280,6 +284,7 @@ No `variant` / `tone` / `color`.
 | eyedropper unsupported | no `window.EyeDropper` | button `disabled`, `aria-hidden` |
 | selected swatch | the color | `data-state="checked"`; a check mark that contrasts with the color draws in — no ring, the check is the selection |
 | ColorPresets open | `open` / click / ArrowDown · ArrowUp on the trigger | popover `data-state`; focus on the selected swatch |
+| ColorPresets custom color | `allowCustom` + a value that is no preset, or Enter in the hex field | no swatch is checked; the hex field holds the value; the trigger is named «`labels.trigger`: #rrggbb»; invalid text on Enter shows `labels.customInvalid` as the field's error (the error drops in, the field shakes once) |
 | ColorPresets empty | value `null` | the trigger shows the checkerboard fill and is named «`labels.trigger`: `labels.empty`» |
 
 There is no `disabled` on `ColorPicker.Root` — disable parts individually. Controlled: `value` + `onValueChange` (both components), `open` + `onOpenChange` (ColorPresets). Uncontrolled: `defaultValue`, `defaultOpen`.
@@ -301,8 +306,8 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 | `ArrowLeft` · `ArrowRight` · `ArrowUp` · `ArrowDown` | Move the area thumb or a slider; in the ColorPresets grid, move between swatches. |
 | `PageUp` · `PageDown` | Larger steps on the area and the sliders. |
 | `Home` · `End` | Slider ends; the first / last swatch in the ColorPresets grid. |
-| `Enter` · `Space` | Commit a field; pick the focused preset swatch and close. |
-| `Tab` | Moves through the parts; inside the ColorPresets grid returns to the trigger and closes. |
+| `Enter` · `Space` | Commit a field; pick the focused preset swatch and close. In the ColorPresets hex field (`allowCustom`) Enter picks the typed color. |
+| `Tab` | Moves through the parts; inside the ColorPresets grid returns to the trigger and closes. With `allowCustom` Tab goes from the grid to the hex field; past it the panel closes and focus goes on from the trigger. |
 | `Escape` | Closes the ColorPresets panel. |
 
 ### ARIA
@@ -355,6 +360,8 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 | `trigger` | `"Цвет"` | ColorPresets trigger name prefix: «<trigger>: <color name>»; in a FieldList cell the column heading. |
 | `list` | `"Цвета"` | ColorPresets swatch list name when `Content` has no `label`. |
 | `empty` | `"Без цвета"` | ColorPresets «no color» swatch and the trigger name for an empty value. |
+| `custom` | `"Свой цвет"` | Label of the ColorPresets hex field (`allowCustom`). |
+| `customInvalid` | `"Введите цвет в формате #RRGGBB"` | Error of the ColorPresets hex field when Enter finds no hex color. |
 
 ## Examples
 | Example | Shows |
@@ -366,12 +373,14 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 | [panel.tsx](examples/panel.tsx) | The full raised panel and its part order: format, area, hue and alpha sliders, channels, brand swatches — `ColorPicker.Panel`, `surface`, `ColorPicker.Swatches`. |
 | [formats.tsx](examples/formats.tsx) | The channel strip in each value format; three pickers edit one color — `defaultFormat`, `ColorPicker.ChannelStrip`. |
 | [presets.tsx](examples/presets.tsx) | A quick color from the palette: a square trigger with «no color» and a Button trigger whose grid of four columns stays open after a pick — `ColorPresets`, `allowEmpty`, `ColorPresets.Trigger`, `columns`, `closeOnSelect`. |
+| [presets-custom.tsx](examples/presets-custom.tsx) | A spec's color on the site: the brand palette one click away and any hex typed under it — `ColorPresets`, `allowCustom`. |
 | [presets-sizes.tsx](examples/presets-sizes.tsx) | The preset trigger in every size, a square of the control height next to an input of the same tier — `ColorPresets`, `size`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the color and its format: brand swatches and the channels edit it, the format stays as picked, a button resets both — `value`, `onValueChange`, `format`, `onFormatChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent opens the preset palette from its own button and keeps the chosen color — `open`, `onOpenChange`, `value`, `onValueChange`. |
 | [in-form.tsx](examples/in-form.tsx) | Theme settings: the color goes with the form, a too light color shakes in an error on save that leaves once the color changes — `value`, `error`. |
 
 ## Mistakes
+- A ColorPresets palette padded with dozens of colors so that «any» color fits, or a ColorField beside it for the rest → `allowCustom`: the palette stays short, any hex is typed under it.
 - Trigger in one `ColorPicker.Root` and panel in another → they will not share the color; wrap both in one Root.
 - `isDisabled` on Area / Slider → use `disabled`.
 - `onChange` on `ColorPicker.Root` → use `onValueChange`.
@@ -383,5 +392,5 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 - `<ColorPresets.Trigger />` with no child → put `ColorPresets.SwatchButton` (or your Button) inside it.
 
 ## Related
-- **Built from:** [Input](../input/COMPONENT.md) (`HexInput`; its field action segment for `SwatchButton`), [Tooltip](../tooltip/COMPONENT.md) (`SwatchButton`), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (the `HexInput` label, hint and error), [Select](../select/COMPONENT.md) (`FormatSelect`), [Button](../button/COMPONENT.md) (`EyeDropperButton`), [ColorSwatches](../color-swatches/COMPONENT.md) (`Swatches`), [Popover](../popover/COMPONENT.md) (`ColorPresets.Root`, `ColorPresets.Content`), `Icon` (pipette), [VisuallyHidden](../visually-hidden/COMPONENT.md)
+- **Built from:** [Input](../input/COMPONENT.md) (`HexInput`; its field action segment for `SwatchButton`; the hex field of `ColorPresets allowCustom`), [Tooltip](../tooltip/COMPONENT.md) (`SwatchButton`), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (the `HexInput` label, hint and error), [Select](../select/COMPONENT.md) (`FormatSelect`), [Button](../button/COMPONENT.md) (`EyeDropperButton`), [ColorSwatches](../color-swatches/COMPONENT.md) (`Swatches`), [Popover](../popover/COMPONENT.md) (`ColorPresets.Root`, `ColorPresets.Content`), `Icon` (pipette), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [ColorField](../color-field/COMPONENT.md), [ColorSwatches](../color-swatches/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md)

package/src/components/color-picker/examples/presets-custom.tsx

@@ -0,0 +1,31 @@
+/** A spec's color on the site: the brand palette one click away and any hex typed under it — `ColorPresets`, `allowCustom`. */
+import { ColorPresets } from "prime-ui-kit";
+import * as React from "react";
+
+const BRAND_COLORS = [
+  { value: "#5b5bd6", label: "Индиго" },
+  { value: "#0090ff", label: "Синий" },
+  { value: "#12a594", label: "Бирюзовый" },
+  { value: "#30a46c", label: "Зелёный" },
+  { value: "#f76b15", label: "Оранжевый" },
+  { value: "#e5484d", label: "Красный" },
+];
+
+export default function ColorPickerPresetsCustomExample() {
+  const [color, setColor] = React.useState<string | null>("#8e4ec6");
+
+  return (
+    <ColorPresets.Root
+      presets={BRAND_COLORS}
+      allowCustom
+      value={color}
+      onValueChange={setColor}
+      labels={{ trigger: "Цвет характеристики" }}
+    >
+      <ColorPresets.Trigger>
+        <ColorPresets.SwatchButton />
+      </ColorPresets.Trigger>
+      <ColorPresets.Content label="Цвет характеристики" />
+    </ColorPresets.Root>
+  );
+}

package/src/components/color-swatches/COMPONENT.md

@@ -49,6 +49,7 @@ ColorSwatches                 field frame: label → swatches → hint | error
 | `required` | `boolean` | — | Red `*` after the label and `aria-required` on the group. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the swatches. 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` | — | Danger inner edge on every swatch and `aria-invalid`. A non-empty `error` implies it. |
 | `disabled` | `boolean` | `false` | Disables every swatch (grey, half transparent). |

package/src/components/confirm-dialog/COMPONENT.md

@@ -134,5 +134,5 @@ The dialog is a Modal `s` with the floating surface, a header and a footer; ther
 - `tone="accent"` for a delete → destructive is always `danger`.
 
 ## Related
-- **Built from:** the dialog Modal stands on (`internal/overlay/ModalDialog` at `s`, the header, body and footer of `internal/overlay/DialogParts`), [ScrollContainer](../scroll-container/COMPONENT.md) (the body), [Avatar](../avatar/COMPONENT.md) and [Thumbnail](../thumbnail/COMPONENT.md) (pictures the shared icon slot recognises), [Button](../button/COMPONENT.md) (Cancel, the confirm with `loading`), [Banner](../banner/COMPONENT.md) (the failure message), `Icon` (`status.danger` in the Banner)
+- **Built from:** the dialog Modal stands on (`internal/overlay/ModalDialog` at `s`, the header, body and footer of `internal/overlay/DialogParts`), [ScrollContainer](../scroll-container/COMPONENT.md) (the body), [Avatar](../avatar/COMPONENT.md) and [Thumbnail](../thumbnail/COMPONENT.md) (pictures the shared icon slot recognises), [Skeleton](../skeleton/COMPONENT.md) (the shared description's loading line), [Button](../button/COMPONENT.md) (Cancel, the confirm with `loading`), [Banner](../banner/COMPONENT.md) (the failure message), `Icon` (`status.danger` in the Banner)
 - **See also:** [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), [Notification](../notification/COMPONENT.md)

package/src/components/crossfade/COMPONENT.md

@@ -45,7 +45,7 @@ Crossfade          <div>; holds the region's height while it changes
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `state` | `string \| number` | — (required) | Key of what the region shows: `"loading"`, `"ready"`, `"empty"`, `"error"` or a record id. A new value cross-fades the old content into the new one; the same value updates in place. |
-| `fill` | `boolean` | `false` | The region takes its parent's height (a flex or grid item, or a sized block) and every state stretches to it; the height never glides. |
+| `fill` | `boolean` | `false` | The region takes its parent's height (a flex or grid item, or a sized block) and every state stretches to it; the height never glides. A `Crossfade` that is the child of a `Page.Cell` fills it unless `fill` is set. |
 | `children` | `ReactNode` | — | Content of the current `state`. Nothing (`null`, `false`) leaves no box once the old state has faded: no gap in a grid or a flex column. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `aria-busy`, `aria-live`, `role` and the other div attributes. |