prime-ui-kit 0.12.0 → 0.13.1

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

@@ -0,0 +1,100 @@
+/** 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`. */
+import { Button, Card, Chat, Message } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const LOAD_MS = 1500;
+
+const MESSAGES = [
+  {
+    id: "m-a",
+    direction: "incoming",
+    time: "09:58",
+    text: "Здравствуйте! Подскажите, когда выставите счёт по договору № 118?",
+  },
+  {
+    id: "m-b",
+    direction: "outgoing",
+    time: "10:02",
+    text: "Добрый день! Счёт № 2041 уже в личном кабинете, продублировал на почту.",
+  },
+  {
+    id: "m-c",
+    direction: "incoming",
+    time: "10:03",
+    text: "Получили, передаю в бухгалтерию.",
+  },
+  {
+    id: "m-1",
+    direction: "incoming",
+    time: "10:12",
+    text: "Добрый день! Счёт № 2041 оплатили, проверьте, пожалуйста.",
+  },
+  {
+    id: "m-2",
+    direction: "outgoing",
+    time: "10:15",
+    text: "Вижу оплату, спасибо. Отгрузка — завтра до обеда.",
+  },
+  {
+    id: "m-3",
+    direction: "incoming",
+    time: "10:16",
+    text: "Отлично. Закрывающие документы пришлёте в ЭДО?",
+  },
+  {
+    id: "m-4",
+    direction: "outgoing",
+    time: "10:18",
+    text: "Да, акт и УПД уйдут вместе с отгрузкой.",
+  },
+  {
+    id: "m-5",
+    direction: "incoming",
+    time: "10:19",
+    text: "Спасибо, ждём.",
+  },
+] as const;
+
+export default function ChatStatesExample() {
+  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 (
+    <div className={styles.live}>
+      <div className={styles.liveBar}>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          disabled={loading}
+          onClick={() => setLoading(true)}
+        >
+          Открыть заново
+        </Button.Root>
+      </div>
+      <Card.Root className={styles.short}>
+        <Chat.Root>
+          <Chat.Messages aria-label="Переписка с ООО «Вектор»" loading={loading}>
+            {MESSAGES.map((message) => (
+              <Message.Root
+                key={message.id}
+                value={message.id}
+                direction={message.direction}
+                time={message.time}
+                status={message.direction === "outgoing" ? "read" : undefined}
+              >
+                <Message.Text>{message.text}</Message.Text>
+              </Message.Root>
+            ))}
+          </Chat.Messages>
+        </Chat.Root>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/chat-list/COMPONENT.md

@@ -0,0 +1,256 @@
+# ChatList
+
+**Category:** messages
+**Kind:** composite
+
+> The conversation list of a messenger: the pane where the reader picks a dialog — avatar, name, time, the last message, counts, «печатает…» and drafts.
+
+## When to use
+- The left pane of a messenger, a support inbox, a sales inbox (Telegram, WhatsApp, Intercom): dialogs as data, the open one beside it in [Chat](../chat/COMPONENT.md).
+- Any list of conversations with a last message: client chats in a CRM card, team channels, bot sessions.
+- A long or growing inbox: hundreds of dialogs render only around the view, more load near the end (`hasMore`, `onLoadMore`).
+
+## When not to use
+- Records that are not conversations (tickets, letters, invoices) → use [List](../list/COMPONENT.md) — the same rows without the messenger parts.
+- The messages of one conversation → use [Chat](../chat/COMPONENT.md) (`Chat.Messages`).
+- App sections → use [Sidebar](../../layout/sidebar/COMPONENT.md); a choice of options → [Select](../select/COMPONENT.md).
+- People compared by columns, sorted or selected in bulk → use [DataTable](../data-table/COMPONENT.md).
+
+## Import
+```tsx
+import { ChatList, formatChatTime } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+ChatList.Root                 <div> column filling its host (container `chat-list`); items, getKey, renderItem
+├─ search field               Input type="search" — with search / defaultSearch / onSearchChange
+├─ 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.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 «печатает…»
+│           ├─ (meta)                    delivery ticks · time
+│           ├─ (badges)                  «@» · unread count · pin
+│           └─ ChatList.ItemMenu         Dropdown.Content of the row, opened at the pointer
+└─ VisuallyHidden live        «Загрузка диалогов», «Найдено: 4», «Ничего не найдено»
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ChatList.Root
+`ref` → `HTMLDivElement`. The conversation list of a messenger: dialogs as data drawn by `renderItem`, the open one `value`, an optional search field, placeholders while loading, more on scroll. Draws no surface.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `readonly T[]` | — (required) | Dialogs in the order to show: pinned first, then by the last message. Rows glide when it changes. |
+| `getKey` | `(item: T) => string` | — (required) | A stable key of a dialog: the `value` of its row. |
+| `renderItem` | `(item: T) => ReactElement` | — (required) | Renders a dialog as a `ChatList.Item` with its parts. |
+| `value` | `string \| null` | — | The open dialog (controlled): the current fill and `aria-current`; `null` — none. |
+| `defaultValue` | `string \| null` | `null` | The dialog open at first (uncontrolled). |
+| `onValueChange` | `(value: string) => void` | — | The reader opened a dialog: a click, a tap, Enter or Space on its row. |
+| `search` | `string` | — | The search query (controlled). Any of the triad shows the search field. |
+| `defaultSearch` | `string` | — | The initial query (uncontrolled). |
+| `onSearchChange` | `(search: string) => void` | — | The query changed: filter `items` by it; the rows mark the match in the name and the preview. |
+| `loading` | `boolean` | `false` | The first load: placeholder rows in the rows' geometry (`aria-busy`), then a cross-fade into the dialogs. |
+| `hasMore` | `boolean` | `false` | More dialogs exist: a placeholder row ends the list and `onLoadMore` runs near the end. |
+| `onLoadMore` | `() => void \| Promise<void>` | — | The reader came near the end while `hasMore`: append the next dialogs. A promise is awaited before the next call. |
+| `empty` | `ReactNode` | — | The empty state without a search (an `EmptyPage` with an action). Default: «Нет диалогов». |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Row tier: height, text, avatar, glyphs and the search field. |
+| `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». |
+| `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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `time` | `Date \| string` | — | When the last message was sent: a `Date` shown with the root's `formatTime`, or the text to show. |
+| `status` | `"sending" \| "sent" \| "read" \| "failed"` | — | Delivery of the reader's own last message: the clock, ✓, ✓✓ in the accent, or the failure mark — cross-fading. |
+| `unread` | `number` | `0` | Unread messages: a solid count under the time (gray while `muted`); the number rolls. |
+| `mention` | `boolean` | `false` | The reader is mentioned among the unread: an «@» beside the count. |
+| `muted` | `boolean` | `false` | Notifications are off: a muted glyph beside the name and a gray count. |
+| `pinned` | `boolean` | `false` | Pinned: a pin under the time while nothing is unread. Put pinned dialogs first in `items`. |
+| `typing` | `boolean \| string` | `false` | The other side types: the preview cross-fades into «печатает…» in the accent; a name for a group («Анна печатает…»). |
+| `draft` | `string` | — | The reader's unsent text: the preview shows «Черновик:» in danger and the text. |
+| `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | — | Runs before the dialog opens; `preventDefault()` keeps it closed. |
+| `href` | `string` | — | Renders an `<a>` instead of a `<button>` (a dialog with its own URL). |
+| `children` | `ReactNode` | — | `ChatList.ItemIcon`, `ChatList.ItemText`, `ChatList.ItemDescription`, `ChatList.ItemMenu`. |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `className` and the native attributes of the row element. |
+
+### ChatList.ItemIcon
+`ref` → `HTMLSpanElement`. Before the name: the avatar slot (`aria-hidden`), an `Avatar.Root` sized by the row. After the name: a glyph beside it (verified, bot, group).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | An `Avatar.Root` (with `Avatar.Status`), or after the name an `Icon` with a `label`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other `span` attributes. |
+
+### ChatList.ItemText
+`ref` → `HTMLSpanElement`. The name of the dialog: one line, truncated, the glyphs after it kept whole; the search query is marked.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className`, `title` and the other `span` attributes. |
+
+### ChatList.ItemDescription
+`ref` → `HTMLSpanElement`. The preview of the last message, one line: «{author}: », a media word, the text; the search query is marked in the text.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `author` | `string` | — | Who wrote it: «Вы» for the reader, a member's name in a group. |
+| `kind` | `"photo" \| "video" \| "voice" \| "videoNote" \| "file" \| "location" \| "contact"` | — | The message is not text: its word («Фото», «Голосовое сообщение») leads the preview in the accent. |
+| `duration` | `number` | — | Length of a voice or video message in seconds: «Голосовое сообщение 0:42». |
+| `children` | `ReactNode` | — | The text: the message, a caption, a file name. |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other `span` attributes. |
+
+### ChatList.ItemMenu
+`ref` → `HTMLDivElement`. The menu of a dialog: your `Dropdown.Item`s. Opens where the pointer is on right click and a long press, from the keyboard on Shift+F10 and the menu key.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | `Dropdown.Item`s: Закрепить, Без звука, Отметить прочитанным, Удалить (`tone="danger"`). |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | — | Item tier of the menu. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other attributes of the menu panel. |
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | List `xs` rows, 20 avatar, caption preview, 14 glyphs | a narrow side panel next to a busy screen | |
+| `s` | List `s` rows, 24 avatar, caption preview | a compact inbox inside a card | |
+| `m` | List `m` rows, 32 avatar, body-s preview, 14 glyphs | default: a support or sales inbox | yes |
+| `l` | List `l` rows, 40 avatar, 16 glyphs | a messenger feel, touch-first screens | |
+| `xl` | List `xl` rows, 48 avatar, 20 glyphs | a phone-first messenger | |
+
+The search field takes the tier too; counts are one tier down (the Badge's own rule).
+
+### Row content
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| text preview | muted line, brighter while `unread` | the last message is text | yes |
+| `author` | «Вы: », «Дмитрий: » before the text | the reader's own message, a member of a group | |
+| `kind` (+ `duration`) | «Фото», «Голосовое сообщение 0:42» in the accent, then the caption | the last message is media, a file, a place, a contact | |
+| `draft` | «Черновик:» in danger, then the text | the reader left unsent text in the dialog | |
+| `typing` | «печатает…» / «Анна печатает…» in the accent | the other side types now | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `unread` | solid blue count under the time; the number rolls | unread messages | `0` |
+| `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` |
+| `status` | ✓ / ✓✓ in the accent / clock / failure mark before the time | the reader wrote the last message | — |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| open | `value` / `defaultValue` | `aria-current="true"` on the row button (`"page"` on a link); List's current fill |
+| focus | keyboard | one row `tabindex="0"`, the rest `-1`; List's focus ring inside the row |
+| hover · pressed | pointer | List's `fill-subtle` wash (hover only under `@media (hover: hover)`) |
+| unread | `unread > 0` | `data-unread="true"` on the row; preview in `text-secondary` |
+| muted | `muted` | `data-muted="true"`; the count `soft` gray |
+| typing · draft | `typing`, `draft` | `data-shown="typing" \| "draft" \| "preview"` on the preview; the layers cross-fade (`opacity`, `--prime-motion-duration-fast`), the hidden ones `aria-hidden` |
+| delivery | `status` | `data-status` on a `role="img"` mark; the four ticks share one box and cross-fade |
+| loading | `loading` | six placeholder `List` rows (`inert`, `aria-hidden`), the scroller `aria-busy`; cross-fade into the list |
+| empty | `items` empty | `EmptyPage layout="compact"` («Нет диалогов» or `empty`); with a query «Ничего не найдено» |
+| more | `hasMore` | one placeholder row after the list; `onLoadMore` near the end (`aria-busy` while its promise runs) |
+| menu | right click, long press, Shift+F10 | the row's `ChatList.ItemMenu` in a `Dropdown` anchored at the point; `data-menu="true"` rows take no callout or text selection |
+| reorder | a new order of `items` | rows glide from their old places (`transform`, `--prime-motion-duration-base`); new rows rise in (`enterMotion`); rows removed with nothing else changed close up in place |
+
+Root attribute: `data-size`. Every motion honours reduced motion (durations collapse, glides and ghosts are skipped).
+
+## Layout & spacing
+- The root is a flex column that fills its host's height: put it straight into a `Card.Root` or a `PageContent.List` pane with a height; the scroller takes the rest under the search field.
+- The search field stands on 8px sides; the rows on 8px sides and 4px between them (a margin inside each `<li>`, so the virtual window measures rows with their space).
+- A row: avatar · name and preview · time over the counts. The name and the preview truncate; glyphs, the time and the counts never do.
+- From 100 dialogs only the rows around the view render; spacers hold the rest of the height. The row with the Tab stop and the row with an open menu stay rendered.
+- The root is the `chat-list` container: below 240px the preview line and the time step out, the names and counts stay. At 320px (a phone) everything shows.
+- On a coarse pointer a row is at least the touch target (List).
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Enters the list at one stop — the open dialog (or where the focus was last); the next Tab leaves the list. |
+| `↑` · `↓` | Moves the focus to the previous or next dialog; ↑ on the first goes to the search field. |
+| `Home` · `End` | Moves the focus to the first or last dialog. |
+| `Enter` · `Space` | Opens the focused dialog; a link row takes Enter only. |
+| `Shift + F10` · `ContextMenu` | Opens the dialog's menu under the row. |
+| `Escape` | In the search field clears the query; in the menu closes it and returns the focus to the row. |
+
+### ARIA
+- The list is a `<ul>` named «Диалоги» (`labels.list`); each row an `<li>` with a button, or a link with `href`.
+- 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 «Черновик: …».
+- A row with a menu has `aria-keyshortcuts="Shift+F10"`; the menu is a `Dropdown` (`menu` / `menuitem`).
+- The search field is `type="search"` named «Поиск по диалогам»; after a search a polite status says «Найдено: 4» or «Ничего не найдено».
+- While loading the scroller is `aria-busy` and «Загрузка диалогов» is announced; placeholder rows are `inert` and `aria-hidden`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `list` | `"Диалоги"` | `aria-label` of the list. |
+| `search` | `"Поиск по диалогам"` | `aria-label` of the search field. |
+| `searchPlaceholder` | `"Поиск"` | Placeholder of the search field. |
+| `loading` | `"Загрузка диалогов"` | Announced while `loading`. |
+| `empty` | `"Нет диалогов"` | The empty state without a search. |
+| `noResults` | `"Ничего не найдено"` | The empty state of a search; announced. |
+| `results` | `"Найдено: {count}"` | Announced after a search changes the list; `{count}` — the dialogs found. |
+| `typing` | `"печатает…"` | The preview while the other side types. |
+| `typingName` | `"{name} печатает…"` | The preview while a member of a group types; `{name}` — who. |
+| `draft` | `"Черновик:"` | Before an unsent draft in the preview. |
+| `unread` | `"непрочитанных: {count}"` | Spoken for the unread count; `{count}` — the number. |
+| `mention` | `"упоминание"` | Spoken for the «@» mark. |
+| `muted` | `"Без звука"` | Name of the muted glyph. |
+| `pinned` | `"Закреплён"` | Name of the pin glyph. |
+| `sending` | `"Отправляется"` | Name of the delivery mark: on its way. |
+| `sent` | `"Отправлено"` | Name of the delivery mark: sent. |
+| `read` | `"Прочитано"` | Name of the delivery mark: read. |
+| `failed` | `"Не отправлено"` | Name of the delivery mark: failed. |
+| `photo` | `"Фото"` | Media word: `kind="photo"`. |
+| `video` | `"Видео"` | Media word: `kind="video"`. |
+| `voice` | `"Голосовое сообщение"` | Media word: `kind="voice"`. |
+| `videoNote` | `"Видеосообщение"` | Media word: `kind="videoNote"`. |
+| `file` | `"Файл"` | Media word: `kind="file"`. |
+| `location` | `"Геопозиция"` | Media word: `kind="location"`. |
+| `contact` | `"Контакт"` | Media word: `kind="contact"`. |
+| `menu` | `"Действия с диалогом"` | `aria-label` of the point the row menu opens from. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A support inbox: pinned dialogs first, the search, unread and muted counts, the typing line, a draft, delivery ticks and a row menu that pins, mutes, marks read and deletes after a confirm — `ChatList.Root`, `items`, `renderItem`, `value`, `onSearchChange`, `ChatList.Item`, `ChatList.ItemMenu`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier: row height, text, avatar, glyphs and the search field follow the tier — `size`. |
+| [structure.tsx](examples/structure.tsx) | Every piece of a row: a photo or initials with presence, a glyph beside the name, the author of the last message, media words with a length, a member typing in a group, ticks from sending to failed — `ChatList.ItemIcon`, `ChatList.ItemDescription`, `author`, `kind`, `duration`, `typing`, `status`. |
+| [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`. |
+| [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`. |
+
+## Mistakes
+- A dialog list hand-built from `List.Item` with a `Badge` count and a home-made «печатает…» → `ChatList.Item` with `unread`, `typing`, `draft`.
+- Filtering inside `renderItem` (returning `null`) → filter `items`: the list counts, announces and glides by `items`.
+- Pinned dialogs mixed into the time order → put them first in `items`; `pinned` only draws the pin.
+- `onValueChange` used to mark a dialog read on focus → arrows only move the focus; mark read when the conversation shows it (`Chat.Messages onRead`) or on open.
+- 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.
+
+## 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), [Dnd](../dnd/COMPONENT.md) (the glide of a new order)
+- **See also:** [Chat](../chat/COMPONENT.md), [Message](../message/COMPONENT.md), [Avatar](../avatar/COMPONENT.md), [PageContent](../page-content/COMPONENT.md), [ConfirmDialog](../confirm-dialog/COMPONENT.md)

package/src/components/chat-list/examples/controlled.tsx

@@ -0,0 +1,103 @@
+/** 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`. */
+import { Avatar, Button, Card, ChatList, hueOf, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const NOW = new Date(2026, 9, 14, 15, 0);
+const at = (day: number, hour: number, minute: number) => new Date(2026, 9, day, hour, minute);
+
+const DIALOGS = [
+  {
+    id: "vector",
+    name: "ООО «Вектор»",
+    initials: "ВК",
+    preview: "Не можем выгрузить счёт в 1С",
+    at: at(14, 14, 32),
+    unread: 2,
+  },
+  {
+    id: "granit",
+    name: "ООО «Гранит»",
+    initials: "ГР",
+    preview: "Акт сверки подписан",
+    at: at(14, 12, 5),
+    unread: 0,
+  },
+  {
+    id: "kozlov",
+    name: "ИП Козлов",
+    initials: "ИК",
+    preview: "Подключите, пожалуйста, ЭДО",
+    at: at(13, 11, 40),
+    unread: 1,
+  },
+  {
+    id: "leto",
+    name: "ООО «Лето»",
+    initials: "ЛТ",
+    preview: "Можно перенести доставку?",
+    at: at(12, 9, 15),
+    unread: 3,
+  },
+];
+
+export default function ChatListControlledExample() {
+  const [dialogs, setDialogs] = React.useState(DIALOGS);
+  const [dialogId, setDialogId] = React.useState<string | null>(null);
+
+  const open = (id: string) => {
+    setDialogId(id);
+    setDialogs((current) =>
+      current.map((item) => (item.id === id ? { ...item, unread: 0 } : item)),
+    );
+  };
+  const nextUnread = dialogs.find((item) => item.unread > 0);
+  const dialog = dialogs.find((item) => item.id === dialogId);
+
+  return (
+    <div className={styles.stage}>
+      <div className={styles.bar}>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          disabled={!nextUnread}
+          onClick={() => {
+            if (nextUnread) open(nextUnread.id);
+          }}
+        >
+          Следующий непрочитанный
+        </Button.Root>
+      </div>
+      <div className={styles.split}>
+        <Card.Root>
+          <ChatList.Root
+            items={dialogs}
+            getKey={(item) => item.id}
+            value={dialogId}
+            onValueChange={open}
+            now={NOW}
+            renderItem={(item) => (
+              <ChatList.Item time={item.at} unread={item.unread}>
+                <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>
+              </ChatList.Item>
+            )}
+          />
+        </Card.Root>
+        <Card.Root>
+          <Card.Body>
+            <Typography variant="body-m" tone={dialog ? "default" : "muted"}>
+              {dialog ? `Открыт диалог: ${dialog.name}` : "Выберите диалог слева"}
+            </Typography>
+          </Card.Body>
+        </Card.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/chat-list/examples/examples.module.css

@@ -0,0 +1,66 @@
+/* A dialog list in a card as wide as the master side of a messenger: the card is its height. */
+.pane {
+  display: flex;
+  flex-direction: column;
+  inline-size: min(100%, calc(var(--prime-space-24) * 4));
+  block-size: calc(var(--prime-space-24) * 5);
+}
+
+/* A shorter pane: a few dialogs, or a list that scrolls. */
+.short {
+  display: flex;
+  flex-direction: column;
+  inline-size: min(100%, calc(var(--prime-space-24) * 4));
+  block-size: calc(var(--prime-space-24) * 3);
+}
+
+/* sizes: a caption above each tier's list. */
+.tier {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  inline-size: min(100%, calc(var(--prime-space-24) * 4));
+}
+
+/* A pane with its controls above it. */
+.stage {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+  inline-size: min(100%, calc(var(--prime-space-24) * 4));
+}
+
+.bar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-2);
+}
+
+/* controlled: the list beside the open dialog; they stack in a narrow column. */
+.split {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-3);
+  inline-size: 100%;
+}
+
+.split > * {
+  flex: 1 1 calc(var(--prime-space-24) * 3);
+  block-size: calc(var(--prime-space-24) * 3);
+}
+
+/* narrow: a pane squeezed under 240px. */
+.rail {
+  display: flex;
+  flex-direction: column;
+  inline-size: calc(var(--prime-space-24) * 2);
+}
+
+/* A phone-width stage: the list at 320px. */
+.phone {
+  display: flex;
+  flex-direction: column;
+  inline-size: min(100%, calc(var(--prime-space-20) * 4));
+  block-size: calc(var(--prime-space-24) * 5);
+}

package/src/components/chat-list/examples/live.tsx

@@ -0,0 +1,133 @@
+/** 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`. */
+import { Avatar, Button, Card, ChatList, hueOf } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Dialog = {
+  id: string;
+  name: string;
+  initials: string;
+  preview: string;
+  at: Date;
+  unread: number;
+  typing: boolean;
+};
+
+const minutesAgo = (minutes: number) => new Date(Date.now() - minutes * 60_000);
+
+const DIALOGS: Dialog[] = [
+  {
+    id: "vector",
+    name: "ООО «Вектор»",
+    initials: "ВК",
+    preview: "Спасибо, всё работает",
+    at: minutesAgo(5),
+    unread: 0,
+    typing: false,
+  },
+  {
+    id: "granit",
+    name: "ООО «Гранит»",
+    initials: "ГР",
+    preview: "Акт сверки подписан",
+    at: minutesAgo(40),
+    unread: 0,
+    typing: false,
+  },
+  {
+    id: "kozlov",
+    name: "ИП Козлов",
+    initials: "ИК",
+    preview: "Подключите ЭДО",
+    at: minutesAgo(90),
+    unread: 1,
+    typing: false,
+  },
+  {
+    id: "leto",
+    name: "ООО «Лето»",
+    initials: "ЛТ",
+    preview: "Доставка в среду",
+    at: minutesAgo(200),
+    unread: 0,
+    typing: false,
+  },
+];
+
+/** Who writes next and what: the bottom dialogs come up one after another. */
+const INCOMING = [
+  { id: "leto", text: "Машина будет к девяти, пропуск заказан" },
+  { id: "kozlov", text: "Получили приглашение в ЭДО, спасибо" },
+  { id: "granit", text: "Пришлите, пожалуйста, счёт на ноябрь" },
+];
+
+const TYPING_MS = 1600;
+
+export default function ChatListLiveExample() {
+  const [dialogs, setDialogs] = React.useState(DIALOGS);
+  const [dialogId, setDialogId] = React.useState<string | null>("vector");
+  const [step, setStep] = React.useState(0);
+  const [busy, setBusy] = React.useState(false);
+
+  const patch = (id: string, next: Partial<Dialog>) =>
+    setDialogs((current) => current.map((item) => (item.id === id ? { ...item, ...next } : item)));
+
+  const receive = () => {
+    const message = INCOMING[step % INCOMING.length];
+    if (!message) return;
+    setStep(step + 1);
+    setBusy(true);
+    patch(message.id, { typing: true });
+    window.setTimeout(() => {
+      setDialogs((current) =>
+        current.map((item) =>
+          item.id === message.id
+            ? {
+                ...item,
+                typing: false,
+                preview: message.text,
+                at: new Date(),
+                unread: item.id === dialogId ? 0 : item.unread + 1,
+              }
+            : item,
+        ),
+      );
+      setBusy(false);
+    }, TYPING_MS);
+  };
+
+  const shown = [...dialogs].sort((a, b) => +b.at - +a.at);
+
+  return (
+    <div className={styles.stage}>
+      <div className={styles.bar}>
+        <Button.Root variant="soft" tone="neutral" loading={busy} onClick={receive}>
+          Клиент пишет
+        </Button.Root>
+      </div>
+      <Card.Root className={styles.short}>
+        <ChatList.Root
+          items={shown}
+          getKey={(item) => item.id}
+          value={dialogId}
+          onValueChange={(id) => {
+            setDialogId(id);
+            patch(id, { unread: 0 });
+          }}
+          renderItem={(item) => (
+            <ChatList.Item time={item.at} unread={item.unread} typing={item.typing}>
+              <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>
+            </ChatList.Item>
+          )}
+        />
+      </Card.Root>
+    </div>
+  );
+}