prime-ui-kit 0.12.0 → 0.13.1

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

@@ -25,7 +25,7 @@ import { Chat, Composer, Message, groupMessages, formatMessageDate, hueOf } from
 ```
 Chat.Root                         <div> column, fills its host; owns selection, search, typing, jumps
 ├─ Chat.Header                    grid: lead · title over description · actions
-│  ├─ [Avatar]                    any other child leads the row
+│  ├─ [lead]                      every other child (a back button, an Avatar), side by side
 │  ├─ Chat.Title                  <h2>, names the list (aria-labelledby)
 │  ├─ Chat.Description            status line, cross-fades into «печатает…» while `typing`
 │  └─ Chat.Actions                a call, a Dropdown of more
@@ -33,6 +33,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 ├─ Chat.Search                    while the search is open: field · «2 из 5» · older · newer
 ├─ Chat.Pinned                    rail · pin · title over one line · unpin; a press jumps to the message
 ├─ Chat.Messages                  the scroller (anchor="end") and the list: role="log" (a listbox while selecting)
+│  ├─ [first-load placeholders]   Skeleton bubbles on both sides in the list's place while `loading`
 │  ├─ [older placeholder]         a Skeleton bubble above the first message while `hasOlder`
 │  ├─ Chat.Separator              a date pill, sticky at the top of its day (from `items`, or yours)
 │  ├─ Chat.Service                an event of the chat, centered pill
@@ -102,11 +103,11 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">` | — | `className` and the other attributes of the frame. |
 
 ### Chat.Header
-`ref` → `HTMLDivElement`. The top of the chat: who it is with. A row of the leading element (an `Avatar`), the title over the description, and the actions at the end; anything that is not a title, a description or actions leads the row.
+`ref` → `HTMLDivElement`. The top of the chat: who it is with. The title over the description and the actions at the end; every other child (a back button, an `Avatar`) leads the row, side by side in the order written.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (an `Avatar`, `Chat.Title`, `Chat.Description`, `Chat.Actions`), `className`. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (a `PageContent.BackButton`, an `Avatar`, `Chat.Title`, `Chat.Description`, `Chat.Actions`), `className`. |
 
 ### Chat.Title
 `ref` → `HTMLHeadingElement`. Who the chat is with, one line that ellipsizes; it also names the message list (`aria-labelledby`).
@@ -174,6 +175,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `groupWindow` | `number` | `5` | Messages of one author further apart than this many minutes start a new run. |
 | `now` | `Date` | `new Date()` | «Today» for the dates. |
 | `formatDate` | `(date: Date, now: Date) => string` | `formatMessageDate` | The label of a date. |
+| `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. |
 | `quickReaction` | `string \| false` | `«👍»` | The reaction of a double tap (and `L`) on a message: puts it or takes it back through `onReactionToggle`. `false` — off. |
@@ -231,6 +233,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | Prop | Effect |
 |---|---|
 | `Chat.Root typing` | the description turns into «печатает…» and the list ends with the typing bubble |
+| `Chat.Messages loading` | the first load: bubble-shaped placeholders in the list's place, cross-fading into the messages |
 | `Chat.Messages hasOlder` | a placeholder above the first message; `onLoadOlder` at the top |
 | `Chat.Messages quickReaction` | the emoji of a double tap and `L` (default «👍», `false` — off); a double click that selected text puts none, and selection mode adds nothing |
 | `Chat.Messages reactionOptions` | the reactions of the reaction bar, seven in its row, the rest glide open behind «⌄»; the bar floats above the message on a long press (with the menu), after a long hover on pointer devices (~500 ms, the bar alone) or on `R` |
@@ -243,6 +246,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | new, theirs | an incoming message added at the end | `data-enter="incoming"`: the same float-up and fade; scrolled away, the «к последним» button counts it. Arriving with the end of the typing, it takes the typing's place — the typing goes at once |
 | not new | the first render, history prepended, a message put back in the middle, a row the window renders as it scrolls into view, a status or text change | nothing moves. Reduced motion makes every enter instant |
 | away from the end | the reader scrolled up | a round soft «к последним» button at the bottom-end, rising in (`fast`); a `Badge` counts incoming messages that came meanwhile; a press glides to the end — from far away it lands one view before the end first — and stops when the reader scrolls; at the end it leaves and the count resets |
+| first load | `Chat.Messages loading` | the messages' region is `aria-busy`: six `Skeleton` bubbles in the message geometry (the bubble's radius, one or two lines of body text in its padding, widths within its cap), on alternating sides at the end of the list, a group chat's incoming ones beside a circle in the avatar's gutter; `labels.loading` is announced politely. When it ends they cross-fade into the list (`Crossfade`: the new state in `base`, the placeholders out in `fast`); the list mounts then, so what it shows is its first render — nothing enters, nothing is reported new |
 | older history | `hasOlder` | a bubble-shaped `Skeleton` above the first message; reaching it calls `onLoadOlder`; the rows that arrive above keep the reader's place |
 | jumped to | `Message.Reply target`, `Chat.Pinned`, `current` | the list brings the message to the middle (a near one glides, a far one lands at once — rendering it first — and settles once its neighbours have laid out); nothing is drawn on it: every other message steps back and comes forward three times (opacity 1 → `--prime-message-dim-opacity` → 1, `base` each) — `data-pointing="a"` / `"b"` on the list, flipped on every jump so a repeated jump restarts it, and `data-pointed` on the message; a reply's target also takes the focus, a `current` change leaves it where it is. While the search is open its current match takes the place of `current`. Reduced motion: the others stand back for a moment, no blink |
 | search | `search` (the bar open) | every case-insensitive match in the messages' text and transcripts under a soft accent wash (`<mark>`); the newest match is current: brought into view while the others stay back (`data-pointing="current"`); Enter and the older / newer buttons move the full strength to the older or newer match in one step; «2 из 5» or «Нет совпадений» beside the field |
@@ -252,6 +256,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 
 ## Layout & spacing
 - `Chat.Root` is a column that fills its host's height (`block-size: 100%`, a flex item that grows): give the host a height — a `Card` sized by the page, a page pane, the viewport. Only `Chat.Messages` grows and scrolls; the header, the search, the pinned bar and the footer keep their height.
+- The header sorts its children by type: `Chat.Title`, `Chat.Description` and `Chat.Actions` take their places, every other child (fragments opened) goes into the lead, a row centred with `space-2` between its items — a back button and an avatar stand side by side; without them the text starts the row.
 - The header: `space-3` top and end, `space-2` bottom, `space-4` start; `space-3` between its columns; the title `title-s` on one line that ellipsizes, the description a muted caption; the actions keep their width, so at 320px the title gives way.
 - The search bar and the pinned bar stand under the header with `space-3` side padding; the footer pads the Composer by `space-2` / `space-3`.
 - The list pads its own sides (`space-2`), so the focus rings of the bubbles fit; every row is a container: a bubble is at most `--prime-message-max-width` and 85% of the chat.
@@ -282,6 +287,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 - `Chat.SelectionBar` is a `toolbar` named by the count «Выбрано: N», which is announced politely as it changes.
 - The quick reaction (double tap, `L`) is announced politely.
 - «Печатает…» in the header is visible text; in the list the typing bubble is a polite `status` «Собеседник печатает».
+- While `loading` the messages' region is `aria-busy`, the placeholders are `aria-hidden`, and «Загрузка сообщений» (`labels.loading`) is announced politely.
 - A message reached by a jump or the current search match is not announced as such: a reply's target takes the focus, a search keeps it in its field; the others stepping back is visual only.
 
 ### Labels
@@ -305,6 +311,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `pinnedOf` | `"Закреплённое {index} из {count}"` | `Chat.Pinned labels`: the title with several, the newest last. |
 | `unpin` | `"Открепить"` | `Chat.Pinned labels`: the name of the unpin button. |
 | `unread` | `"Непрочитанные сообщения"` | The text of the «unread» band: `Chat.Root labels` for rows from `items`, `Chat.Unread labels` for a hand-placed band. |
+| `loading` | `"Загрузка сообщений"` | Announced politely while the conversation loads for the first time (`Chat.Messages loading`). |
 
 ## Examples
 | Example | Shows |
@@ -314,11 +321,13 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | [group-chat.tsx](examples/group-chat.tsx) | A team chat from data: the first message of an author's run opens with the name in the author's hue, a crown for the owner and the member's tag; the avatar — a photo, or initials — closes the run; a direct chat shows neither — `type`, `items`, `renderMessage`, `Message.Author`, `tag`, `Message.AuthorIcon`, `hueOf`. |
 | [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 the others — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. |
+| [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`. |
 
 ## Mistakes
 - A header, a search bar and a scroller of your own around the messages → `Chat.Header`, `Chat.Search`, `Chat.Messages`: the chat wires typing, search, jumps and selection between them.
+- A spinner or grey boxes of your own while a dialog loads → `Chat.Messages loading`: bubbles in the messages' geometry that cross-fade into the list.
 - A `ScrollContainer` or a virtualizing list of your own around messages → `Chat.Messages` scrolls itself and renders a window, keeping the reader's place.
 - Dates, runs and the unread band built by hand → `Chat.Messages items` with `getKey`, `getAuthor`, `getDate`; `groupMessages` if you build rows yourself.
 - An inline `renderMessage` in a long history → wrap it in `useCallback`: a new function renders every item again.
@@ -332,5 +341,5 @@ Chat.Root                         <div> column, fills its host; owns selection,
 - Checkboxes and selection handling of your own → `Chat.Root selected` with `Chat.SelectionBar`: click, Shift range and drag like DataTable rows.
 
 ## Related
-- **Built from:** [Message](../message/COMPONENT.md) (`Message.Typing`, the rows), [ScrollContainer](../scroll-container/COMPONENT.md) (the scroller, `anchor="end"`), [Input](../input/COMPONENT.md) (the search field), [Button](../button/COMPONENT.md) (search, steps, unpin, «к последним», the selection bar), [Badge](../badge/COMPONENT.md), [Crossfade](../crossfade/COMPONENT.md) (the status line), [Skeleton](../skeleton/COMPONENT.md) (older history), Icon (`action.search`, `nav.chevronUp`, `nav.chevronDown`, `action.pin`, `action.close`); `useVirtualRows` (the window), `internal/messageList` (the contract between the list and its messages), `internal/readReceipts`, `internal/useRangeSelection` (selection by click, Shift and drag), `internal/messagePart` (the search query its texts mark)
+- **Built from:** [Message](../message/COMPONENT.md) (`Message.Typing`, the rows), [ScrollContainer](../scroll-container/COMPONENT.md) (the scroller, `anchor="end"`), [Input](../input/COMPONENT.md) (the search field), [Button](../button/COMPONENT.md) (search, steps, unpin, «к последним», the selection bar), [Badge](../badge/COMPONENT.md), [Crossfade](../crossfade/COMPONENT.md) (the status line, the first load), [Skeleton](../skeleton/COMPONENT.md) (the first load, older history), `internal/VisuallyHidden` (the loading announcement), Icon (`action.search`, `nav.chevronUp`, `nav.chevronDown`, `action.pin`, `action.close`); `useVirtualRows` (the window), `internal/messageList` (the contract between the list and its messages), `internal/readReceipts`, `internal/useRangeSelection` (selection by click, Shift and drag), `internal/messagePart` (the search query its texts mark)
 - **See also:** [Message](../message/COMPONENT.md) — one message and every content part; [Composer](../composer/COMPONENT.md) — the input in `Chat.Footer`; [Gallery](../gallery/COMPONENT.md), [VoicePlayer](../voice-player/COMPONENT.md), [VideoNote](../video-note/COMPONENT.md), [Timeline](../timeline/COMPONENT.md)

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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);
+}