prime-ui-kit 0.15.0 → 0.17.0

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

@@ -78,7 +78,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 
 - Send optimistically: add the message with `status="sending"` under a client id and return from `onSend`; patch the status as the server answers. Keep its key when the server id arrives — the row stays the same element, so it never enters twice and the ticks cross-fade.
 - The list needs nothing to animate: it decides itself which message is new at the end, scrolls to your own message, keeps the end, or counts new ones on the «к последним» button.
-- Keep `renderMessage` stable (`useCallback`): an item renders again only when it, its place or this function changes. Read lookups across messages (a reply's original) through a ref rather than listing the messages as a dependency — a function that changes with every message renders the whole history again, and a reaction's stroke then starts late.
+- `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.
 
@@ -97,9 +97,9 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `search` | `string \| null` | — | The search query (controlled); `null` — the search bar is closed. Matches in the messages' text and transcripts are marked; the newest is current. |
 | `defaultSearch` | `string \| null` | `null` | The initial search (uncontrolled). |
 | `onSearchChange` | `(search: string \| null) => void` | — | The search opened (`""`), changed its query or closed (`null`). |
-| `current` | `string \| null` | `null` | A message to bring into view (a link, a notification): on change the chat brings it to the middle and the message itself blinks. The focus stays where it is. |
+| `jumpTo` | `string \| null` | `null` | A message to jump to (a link, a notification): on change the chat brings it to the middle and the message itself blinks. The focus stays where it is; while the search is open its current match takes this place. |
 | `typing` | `boolean` | `false` | The other side is typing: `Chat.Description` cross-fades into «печатает…» and the list ends with the typing bubble (`Message.Typing`), which gives way at once to the reply that ends it. |
-| `labels` | `Partial<ChatLabels>` | — | System strings, see Labels. |
+| `labels` | `Partial<ChatLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">` | — | `className` and the other attributes of the frame. |
 
 ### Chat.Header
@@ -107,7 +107,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (a `PageContent.BackButton`, an `Avatar`, `Chat.Title`, `Chat.Description`, `Chat.Actions`), `className`. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (a `Page.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`).
@@ -152,11 +152,11 @@ Chat.Root                         <div> column, fills its host; owns selection,
 |---|---|---|---|
 | `items` | `readonly { value: string; text: string }[]` | — (required) | The pinned messages, oldest first: the `value` of each `Message.Root` and one line of it («Фото», «Голосовое сообщение» for media). |
 | `value` | `string` | — | The pinned message shown (controlled). |
-| `defaultValue` | `string` | `the last item` | The one shown first (uncontrolled): the newest. |
+| `defaultValue` | `string` | the last item | The one shown first (uncontrolled): the newest. |
 | `onValueChange` | `(value: string) => void` | — | The shown message changed: a press stepped to the next older one (the oldest wraps to the newest). |
 | `onSelect` | `(value: string) => void` | — | A press on the bar, after the chat has jumped to the message: load it when it is not in the list yet. |
 | `onRemove` | `(value: string) => void` | — | Unpin the shown message: a ghost close button at the end. Without it no button. |
-| `labels` | `Partial<ChatPinnedLabels>` | — | System strings, see Labels. |
+| `labels` | `Partial<ChatPinnedLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onSelect">` | — | `className` and the other attributes. |
 
 ### Chat.Messages
@@ -164,22 +164,22 @@ Chat.Root                         <div> column, fills its host; owns selection,
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `type` | `"direct" \| "group"` | `"direct"` | `direct` — a conversation of two; `group` — many authors, with the author's header and avatar on each run. |
+| `group` | `boolean` | `false` | A group chat of many authors: the first message of a run shows the author's header, the last one the avatar, and incoming messages keep the avatar's gutter. Without it a conversation of two. |
 | `items` | `readonly T[]` | — | Messages as application data, in time order: the list adds the dates, the runs and the unread band and sets each message's `value` and `position`. Without it, children are the rows. |
 | `getKey` | `(item: T) => string` | — | A stable key of an item (with `items`): also its message's `value`. Keep it when the server confirms a sent message. |
 | `getAuthor` | `(item: T) => string` | — | Who wrote an item (an id, with `items`): a change of author starts a new run. |
 | `getDate` | `(item: T) => Date` | — | When an item was sent (with `items`): a new day gets a date. |
-| `renderMessage` | `(item: T, entry: ChatMessageEntry) => ReactElement` | — | Renders an item (with `items`): a `Message.Root` (`value` and `position` set for you) or a `Chat.Service`; `entry` is `{ position, showAuthor, showAvatar }`. Keep it stable (`useCallback`). |
+| `renderMessage` | `(item: T, entry: ChatMessageEntry<T>) => ReactElement` | — | Renders an item: a `Message.Root` or a `Chat.Service`; `entry` — `{ position, showAuthor, showAvatar, find }`, `find(key)` gives another item (a reply's original). Runs again only for an item whose data or place changed. |
 | `isService` | `(item: T) => boolean` | — | An event of the chat, not a message: it stands alone and breaks the runs around it. |
 | `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` | `new Date()` | «Today» for the dates. |
+| `now` | `Date` | today | «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. |
-| `reactionOptions` | `readonly { emoji: string; label: string }[]` | `👍 🔥 🤣 👌 🤔 😢 😱, then 7 more` | The reactions of the bar above a message (long press, long hover or `R`): the first seven in a row, «⌄» opens the rest. `label` names each toggle button. |
+| `quickReaction` | `string \| false` | `"👍"` | The reaction of a double tap (and `L`) on a message: puts it or takes it back through `onReactionToggle`. `false` — off. |
+| `reactionOptions` | `readonly { emoji: string; label: string }[]` | 👍 🔥 🤣 👌 🤔 😢 😱, then 7 more | The reactions of the bar above a message (long press, long hover or `R`): the first seven in a row, «⌄» opens the rest. `label` names each toggle button. |
 | `reader` | `MessageUser` | — | The reader (`{ id, name: «Вы», src?, color? }`): a reaction they put shows them among the chip's avatars at once, before the data comes back; matched by `id`. |
 | `onNewMessage` | `(value: string, details: { direction: "incoming" \| "outgoing" }) => void` | — | A message was added at the end after mount, sent or received: for a sound, a counter, a title badge. Not called for the first render, history or a message put back in the middle. |
 | `onRead` | `(values: string[]) => void` | — | Incoming messages the reader has seen (at least half on screen while the page is visible); batched per frame, each `value` once per mount. Send read receipts from here. |
@@ -193,7 +193,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` — the actions (`Button.Root size="s"`: Переслать, Удалить), `className`. |
 
 ### Chat.Separator
-`ref` → `HTMLDivElement`. A date between messages (`items` add them for you) («Сегодня», «12 марта» — `formatMessageDate`): a pill in the middle that stays at the top while its day scrolls.
+`ref` → `HTMLDivElement`. A date between messages (`items` add them for you) («Сегодня», «12 марта» — `formatMessageDate`): a pill a step above the bubbles that stays at the top while its day scrolls, until the next date pushes it out.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -248,11 +248,11 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | 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); the message itself steps back and comes forward three times, the others stay still (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: no blink, the others stand back for a moment |
+| jumped to | `Message.Reply target`, `Chat.Pinned`, `jumpTo` | 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); the message itself steps back and comes forward three times, the others stay still (opacity 1 → the dimmed opacity of `Message` → 1, `base` each) — `data-pointing="a"` / `"b"` on the list, flipped on every jump so a repeated jump restarts it, and `data-pointed` with the same `data-blink` on the message; a reply's target also takes the focus, a `jumpTo` change leaves it where it is. While the search is open its current match takes the place of `jumpTo`. Reduced motion: no blink, the others stand back for a moment |
 | 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 |
 | typing | `typing` | the description cross-fades into «печатает…» in the accent (`Crossfade`); the typing bubble enters at the end of the list like an incoming message and leaves closing its height |
 | pinned | `Chat.Pinned items` | the rail's current segment in the accent; a press jumps to the message and steps the bar to the older one (the oldest wraps to the newest), its line entering; without items the bar renders nothing |
-| selection mode | `selected` (not `null`); any of `selected` / `defaultSelected` / `onSelectedChange` adds «Выбрать» to every `Message.Menu` | listbox / options with `aria-selected`; a check at the row start; a click toggles, Shift+click selects the range from the anchor, press-and-drag (or a finger slid from a check) paints the messages it passes with the first one's new state and scrolls the list at its edges; the unselected messages step back to `--prime-message-dim-opacity` with a slight desaturation (`fast`, both ways; `data-selecting` on the list, `data-selected` on the message); `Chat.SelectionBar` — the «к последним» button rises above it first (its height in `--message-bottom-bar` on the list, `fast`), then the bar fades in, so the two never overlap; outside selection the bar renders nothing |
+| selection mode | `selected` (not `null`); any of `selected` / `defaultSelected` / `onSelectedChange` adds «Выбрать» to every `Message.Menu` | listbox / options with `aria-selected`; a check at the row start; a click toggles, Shift+click selects the range from the anchor, press-and-drag (or a finger slid from a check) paints the messages it passes with the first one's new state and scrolls the list at its edges; the unselected messages step back to the dimmed opacity of `Message` with a slight desaturation (`fast`, both ways; `data-selecting` on the list, `data-selected` on the message); `Chat.SelectionBar` — the «к последним» button rises above it first (its height upward in `--message-bottom-lift` on the list, `fast`), then the bar fades in, so the two never overlap; outside selection the bar renders nothing |
 
 ## 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.
@@ -268,6 +268,8 @@ Chat.Root                         <div> column, fills its host; owns selection,
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Enters the list on the last (or last focused) message, then its buttons and links |
@@ -280,12 +282,15 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `Escape` | In the search field closes the search and returns the focus to `Chat.SearchButton`; in the list leaves selection mode |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The list is `role="log"`: new messages are announced politely; its name is `Chat.Title` (`aria-labelledby`), else `labels.messages`, or your `aria-label`. It is one tab stop; the messages carry `aria-posinset` / `aria-setsize`, so the keyboard reaches rows the window does not render. In selection mode it is a `listbox` with `aria-multiselectable`, the messages `option`s with `aria-selected`.
 - `Chat.SearchButton` is a toggle (`aria-pressed`); the search field takes the focus as it opens and keeps it while the chat steps through matches; the place of the match («2 из 5», «Нет совпадений») is announced politely.
 - `Chat.Pinned` is a button named by its content, the title and the line («Закреплённое 2 из 3» + the text); the rail is decorative; «Открепить» is a separate button.
 - The «к последним» button is named «К последним сообщениям», with the count «Новых сообщений: N. …»; the badge is `aria-hidden`.
 - `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.
+- One sound at a time on the page: a voice message, a video note and a chat video pause each other.
 - «Печатает…» 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.
@@ -293,46 +298,54 @@ Chat.Root                         <div> column, fills its host; owns selection,
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
+#### Chat.Root
+
 | Key | Default | Used for |
 |---|---|---|
+| `selectedCount` | `"Выбрано: {count}"` | The count of the selection bar. |
+| `cancel` | `"Отмена"` | The selection bar's button that leaves selection. |
+| `scrollToEnd` | `"К последним сообщениям"` | The name of the round button that goes to the newest message. |
+| `newMessages` | `"Новых сообщений: {count}. К последним сообщениям"` | The name of that button while new messages wait below. |
 | `typing` | `"печатает…"` | The status line of the header while the other side types. |
 | `search` | `"Поиск по переписке"` | The search button and the name of the search field. |
-| `searchPlaceholder` | `"Поиск по сообщениям"` | The placeholder of the search field. |
+| `searchPlaceholder` | `"Поиск"` | The placeholder of the search field. |
 | `matches` | `"{index} из {count}"` | The place of the current match, counted from the newest. |
 | `noMatches` | `"Нет совпадений"` | The search found nothing. |
 | `previousMatch` | `"Предыдущее совпадение"` | The button that goes to the older match. |
 | `nextMatch` | `"Следующее совпадение"` | The button that goes to the newer match. |
 | `messages` | `"Переписка"` | The name of the list when the header has no `Chat.Title`. |
-| `selectedCount` | `"Выбрано: {count}"` | The count of the selection bar. |
-| `cancel` | `"Отмена"` | The selection bar's button that leaves selection. |
-| `scrollToEnd` | `"К последним сообщениям"` | The name of the round button that goes to the newest message. |
-| `newMessages` | `"Новых сообщений: {count}. К последним сообщениям"` | The name of that button while new messages wait below. |
+| `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`). |
+
+#### Chat.Pinned
+
+| Key | Default | Used for |
+|---|---|---|
 | `pinned` | `"Закреплённое сообщение"` | `Chat.Pinned labels`: the title with one pinned message. |
 | `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 |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | A complete team messenger over two thousand messages: the header whose status turns into typing, search with highlight, pinned messages, history that loads above, author headers with tags in a group chat, every kind of message, transcripts, reactions, the menu with reply, edit, pin and select, jumps, the new-messages button and the Composer whose messages rise into the list — `Chat.Root`, `Chat.Header`, `Chat.Search`, `Chat.Pinned`, `Chat.Messages`, `type`, `items`, `renderMessage`, `typing`, `selected`, `Chat.Footer`. |
+| [overview.tsx](examples/overview.tsx) | A complete team messenger over two thousand messages: the header whose status turns into typing, search with highlight, pinned messages, history that loads above, author headers with tags in a group chat, every kind of message, transcripts, reactions, the menu with reply, edit, pin and select, jumps, the new-messages button and the Composer whose messages rise into the list — `Chat.Root`, `Chat.Header`, `Chat.Search`, `Chat.Pinned`, `Chat.Messages`, `group`, `items`, `renderMessage`, `typing`, `selected`, `Chat.Footer`. |
 | [structure.tsx](examples/structure.tsx) | The list alone, written as parts: `Chat.Root` with only `Chat.Messages`, a date that stays on top while its day scrolls, an event of the chat and the unread band — `Chat.Messages`, `Chat.Separator`, `Chat.Service`, `Chat.Unread`. |
-| [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, which holds messages up to a quarter of an hour apart; the dates carry the weekday — `type`, `items`, `renderMessage`, `groupWindow`, `formatDate`, `Message.Author`, `tag`, `Message.AuthorIcon`, `hueOf`. |
+| [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, which holds messages up to a quarter of an hour apart; the dates carry the weekday — `group`, `items`, `renderMessage`, `groupWindow`, `formatDate`, `Message.Author`, `tag`, `Message.AuthorIcon`, `hueOf`. |
 | [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`. |
 | [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`. |
-| [screen.tsx](examples/screen.tsx) | A support messenger as a work screen: the title and the unread count in the app header, the dialogs with a search over them beside the conversation (one pane at a time on a phone), history that loads above as you scroll up, the unread band, reply and edit from the menu, the typing signal both ways, unread counts from what was seen, and the Composer whose messages rise into the list while the client answers — `items`, `renderMessage`, `hasOlder`, `onLoadOlder`, `typing`. |
+| [screen.tsx](examples/screen.tsx) | A support messenger as a work screen: the title and the unread count in its top bar, the dialogs with a search over them beside the conversation (one pane at a time on a phone), history that loads above as you scroll up, the unread band, reply and edit from the menu, the typing signal both ways, unread counts from what was seen, and the Composer whose messages rise into the list while the client answers — `items`, `renderMessage`, `hasOlder`, `onLoadOlder`, `typing`. |
 
 ## 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.
+- A row that shows state kept outside its item (an edit, a pin held in a separate set) → put it into the item: rows render again only when their item or place changes.
+- A ref mirror of the messages to find a reply's original → `entry.find(key)`.
 - `Message.Author` and `Message.Avatar` only on some messages → put them on every message of a group chat: the message shows the header on the first of a run and the avatar on the last.
 - An enter animation of your own, or `scrollTop = scrollHeight` after a send → the list enters new messages and keeps the end itself; a hand-made one also plays on history loads.
 - A new key for a message when the server confirms it → keep the client id: a re-keyed row is a new message, enters again and calls `onNewMessage` again.
@@ -343,5 +356,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, 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)
+- **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), [VisuallyHidden](../visually-hidden/COMPONENT.md) (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/group-chat.tsx

@@ -1,4 +1,4 @@
-/** 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, which holds messages up to a quarter of an hour apart; the dates carry the weekday — `type`, `items`, `renderMessage`, `groupWindow`, `formatDate`, `Message.Author`, `tag`, `Message.AuthorIcon`, `hueOf`. */
+/** 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, which holds messages up to a quarter of an hour apart; the dates carry the weekday — `group`, `items`, `renderMessage`, `groupWindow`, `formatDate`, `Message.Author`, `tag`, `Message.AuthorIcon`, `hueOf`. */
 import { Avatar, Card, Chat, hueOf, Icon, Message } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -126,7 +126,7 @@ export default function ChatGroupChatExample() {
     <Card.Root className={styles.short}>
       <Chat.Root>
         <Chat.Messages
-          type="group"
+          group
           aria-label="Чат команды релиза"
           items={MESSAGES}
           getKey={(message) => message.id}

package/dist/skill/reference/components/chat/examples/overview.tsx

@@ -1,11 +1,11 @@
-/** A complete team messenger over two thousand messages: the header whose status turns into typing, search with highlight, pinned messages, history that loads above, author headers with tags in a group chat, every kind of message, transcripts, reactions, the menu with reply, edit, pin and select, jumps, the new-messages button and the Composer whose messages rise into the list — `Chat.Root`, `Chat.Header`, `Chat.Search`, `Chat.Pinned`, `Chat.Messages`, `type`, `items`, `renderMessage`, `typing`, `selected`, `Chat.Footer`. */
+/** A complete team messenger over two thousand messages: the header whose status turns into typing, search with highlight, pinned messages, history that loads above, author headers with tags in a group chat, every kind of message, transcripts, reactions, the menu with reply, edit, pin and select, jumps, the new-messages button and the Composer whose messages rise into the list — `Chat.Root`, `Chat.Header`, `Chat.Search`, `Chat.Pinned`, `Chat.Messages`, `group`, `items`, `renderMessage`, `typing`, `selected`, `Chat.Footer`. */
 import {
   Avatar,
   Button,
   Card,
   Chat,
+  type ChatMessageEntry,
   Composer,
-  type ComposerMediaItem,
   type ComposerMessage,
   type ComposerRecording,
   Dropdown,
@@ -47,6 +47,7 @@ type ChatMessage = Content & {
   forwardedFrom?: string;
   replyTo?: string;
   reactions?: MessageReaction[];
+  pinned?: boolean;
 };
 
 const NOW = new Date(2026, 9, 8, 15, 0);
@@ -315,8 +316,6 @@ const READ_MS = 1200;
 const TYPING_MS = 1800;
 const HISTORY_MS = 900;
 const TRANSCRIBE_MS = 1400;
-/** An album holds up to ten photos and videos: more go as the next album. */
-const ALBUM_MAX = 10;
 
 const wait = (ms: number) => new Promise<void>((resolve) => window.setTimeout(resolve, ms));
 
@@ -367,11 +366,6 @@ const transcribeVideoNote = () =>
     () => "Снимаю склад: стеллаж B, третий ряд. Коробки по заказу 4821 тут.",
   );
 
-const albumsOf = (media: readonly ComposerMediaItem[]) =>
-  Array.from({ length: Math.ceil(media.length / ALBUM_MAX) }, (_, index) =>
-    media.slice(index * ALBUM_MAX, (index + 1) * ALBUM_MAX),
-  );
-
 /** The media URLs a message plays from. */
 const sourcesOf = (message: ChatMessage): string[] =>
   message.kind === "media"
@@ -478,20 +472,21 @@ const content = (message: ChatMessage, onCancel: () => void) => {
 };
 
 export default function ChatOverviewExample() {
-  const [messages, setMessages] = React.useState(() => [...ARCHIVE, ...HISTORY]);
+  // Everything a row shows lives in its message (a pin too): a row renders again only when its
+  // message changes.
+  const [messages, setMessages] = React.useState(() =>
+    [...ARCHIVE, ...HISTORY].map((message) =>
+      PINNED_FIRST.includes(message.id) ? { ...message, pinned: true } : message,
+    ),
+  );
   const [hasOlder, setHasOlder] = React.useState(true);
   const [selected, setSelected] = React.useState<readonly string[] | null>(null);
-  const [pinned, setPinned] = React.useState<readonly string[]>(PINNED_FIRST);
   const [typing, setTyping] = React.useState(false);
   const [replyTo, setReplyTo] = React.useState<ChatMessage | null>(null);
   const [editing, setEditing] = React.useState<ChatMessage | null>(null);
   const [draft, setDraft] = React.useState("");
   const replies = React.useRef(0);
   const queue = useUploadQueue({ upload: uploadFile });
-  // The newest messages for what a row looks up (a reply's original, the files to let go), without
-  // making every row render again when one message changes.
-  const messagesRef = React.useRef(messages);
-  messagesRef.current = messages;
 
   const patch = (id: string, next: Partial<ChatMessage>) =>
     setMessages((current) =>
@@ -549,15 +544,15 @@ export default function ChatOverviewExample() {
     };
   }, []);
 
-  // Photos and videos go as albums in the order of the tray, the text as their caption; other
-  // files as file messages.
-  const send = ({ text, media, files, replyTo: reply, editOf }: ComposerMessage) => {
+  // Photos and videos go as albums in the order of the tray, the text as the first one's caption;
+  // other files as file messages.
+  const send = ({ text, albums, files, replyTo: reply, editOf }: ComposerMessage) => {
     if (editOf) {
       patch(editOf, { kind: "text", text, edited: true } as Partial<ChatMessage>);
       setDraft("");
       return;
     }
-    albumsOf(media).forEach((album, index) => {
+    albums.forEach((album, index) => {
       post(
         {
           kind: "media",
@@ -573,7 +568,7 @@ export default function ChatOverviewExample() {
     });
     for (const item of files)
       post({ kind: "file", name: item.file.name, size: item.file.size }, reply);
-    if (text && media.length === 0) post({ kind: "text", text }, reply);
+    if (text && albums.length === 0) post({ kind: "text", text }, reply);
   };
 
   const sendRecording =
@@ -607,129 +602,123 @@ export default function ChatOverviewExample() {
     setHasOlder(false);
   };
 
-  const remove = (ids: readonly string[]) => {
-    for (const message of messagesRef.current) {
-      if (!ids.includes(message.id)) continue;
+  const remove = (removed: readonly ChatMessage[]) => {
+    for (const message of removed) {
       for (const url of sourcesOf(message)) {
         if (localUrls.current.delete(url)) URL.revokeObjectURL(url);
       }
     }
-    setMessages((current) => current.filter((message) => !ids.includes(message.id)));
-    setPinned((current) => current.filter((id) => !ids.includes(id)));
+    const ids = new Set(removed.map((message) => message.id));
+    setMessages((current) => current.filter((message) => !ids.has(message.id)));
   };
 
   const togglePin = (id: string) =>
-    setPinned((current) =>
-      current.includes(id) ? current.filter((item) => item !== id) : [...current, id],
+    setMessages((current) =>
+      current.map((message) =>
+        message.id === id ? { ...message, pinned: !message.pinned } : message,
+      ),
     );
 
-  const pinnedItems = pinned.flatMap((id) => {
-    const message = messages.find((item) => item.id === id);
-    return message ? [{ value: id, text: excerpt(message) }] : [];
-  });
+  const pinnedItems = messages.flatMap((message) =>
+    message.pinned ? [{ value: message.id, text: excerpt(message) }] : [],
+  );
 
-  // Stable while the pins are: a reaction, a status or a keystroke in the composer renders again
-  // only the row whose data changed.
-  // biome-ignore lint/correctness/useExhaustiveDependencies: the handlers only call state setters
-  const renderMessage = React.useCallback(
-    (message: ChatMessage) => {
-      if (message.kind === "service") return <Chat.Service>{message.text}</Chat.Service>;
-      const own = message.from === "me";
-      const author = MEMBERS[message.from];
-      const original = message.replyTo
-        ? messagesRef.current.find((item) => item.id === message.replyTo)
-        : undefined;
-      return (
-        <Message.Root
-          direction={own ? "outgoing" : "incoming"}
-          time={message.sentAt}
-          status={message.status}
-          edited={message.edited}
-          onRetry={
-            message.status === "failed"
-              ? () => wait(900).then(() => patch(message.id, { status: "read" }))
-              : undefined
-          }
-          onReactionToggle={(emoji) =>
-            patch(message.id, { reactions: toggleOwn(message.reactions ?? [], emoji) })
-          }
-        >
-          {own ? null : (
-            <Message.Avatar>
-              <Avatar.Root color={hueOf(author.id)}>
-                {author.src ? <Avatar.Image src={author.src} alt="" /> : null}
-                <Avatar.Fallback>{initialsOf(author.name)}</Avatar.Fallback>
-              </Avatar.Root>
-            </Message.Avatar>
-          )}
-          {own ? null : (
-            <Message.Author color={hueOf(author.id)} tag={author.tag}>
-              {author.name}
-              {author.owner ? (
-                <Message.AuthorIcon>
-                  <Icon name="object.crown" />
-                </Message.AuthorIcon>
-              ) : null}
-            </Message.Author>
-          )}
-          {message.forwardedFrom ? <Message.Forwarded from={message.forwardedFrom} /> : null}
-          {original ? (
-            <Message.Reply
-              author={MEMBERS[original.from].name}
-              color={hueOf(original.from)}
-              target={original.id}
-            >
-              {excerpt(original)}
-            </Message.Reply>
-          ) : null}
-          {content(message, () => remove([message.id]))}
-          {message.reactions?.length ? <Message.Reactions items={message.reactions} /> : null}
-          <Message.Menu>
-            <Dropdown.Item
-              onSelect={() => {
-                setEditing(null);
-                setReplyTo(message);
-              }}
-            >
-              <Dropdown.ItemIcon>
-                <Icon name="action.reply" />
-              </Dropdown.ItemIcon>
-              Ответить
-            </Dropdown.Item>
-            {own && message.kind === "text" ? (
-              <Dropdown.Item onSelect={() => startEdit(message)}>
-                <Dropdown.ItemIcon>
-                  <Icon name="action.edit" />
-                </Dropdown.ItemIcon>
-                Изменить
-              </Dropdown.Item>
+  // A reaction, a status or a keystroke in the composer renders again only the row whose message
+  // changed; a reply's original comes from the list (`entry.find`).
+  const renderMessage = (message: ChatMessage, entry: ChatMessageEntry<ChatMessage>) => {
+    if (message.kind === "service") return <Chat.Service>{message.text}</Chat.Service>;
+    const own = message.from === "me";
+    const author = MEMBERS[message.from];
+    const original = message.replyTo ? entry.find(message.replyTo) : undefined;
+    return (
+      <Message.Root
+        direction={own ? "outgoing" : "incoming"}
+        time={message.sentAt}
+        status={message.status}
+        edited={message.edited}
+        onRetry={
+          message.status === "failed"
+            ? () => wait(900).then(() => patch(message.id, { status: "read" }))
+            : undefined
+        }
+        onReactionToggle={(emoji) =>
+          patch(message.id, { reactions: toggleOwn(message.reactions ?? [], emoji) })
+        }
+      >
+        {own ? null : (
+          <Message.Avatar>
+            <Avatar.Root color={hueOf(author.id)}>
+              {author.src ? <Avatar.Image src={author.src} alt="" /> : null}
+              <Avatar.Fallback>{initialsOf(author.name)}</Avatar.Fallback>
+            </Avatar.Root>
+          </Message.Avatar>
+        )}
+        {own ? null : (
+          <Message.Author color={hueOf(author.id)} tag={author.tag}>
+            {author.name}
+            {author.owner ? (
+              <Message.AuthorIcon>
+                <Icon name="object.crown" />
+              </Message.AuthorIcon>
             ) : null}
-            <Dropdown.Item onSelect={() => navigator.clipboard?.writeText(excerpt(message))}>
+          </Message.Author>
+        )}
+        {message.forwardedFrom ? <Message.Forwarded from={message.forwardedFrom} /> : null}
+        {original ? (
+          <Message.Reply
+            author={MEMBERS[original.from].name}
+            color={hueOf(original.from)}
+            target={original.id}
+          >
+            {excerpt(original)}
+          </Message.Reply>
+        ) : null}
+        {content(message, () => remove([message]))}
+        {message.reactions?.length ? <Message.Reactions items={message.reactions} /> : null}
+        <Message.Menu>
+          <Dropdown.Item
+            onSelect={() => {
+              setEditing(null);
+              setReplyTo(message);
+            }}
+          >
+            <Dropdown.ItemIcon>
+              <Icon name="action.reply" />
+            </Dropdown.ItemIcon>
+            Ответить
+          </Dropdown.Item>
+          {own && message.kind === "text" ? (
+            <Dropdown.Item onSelect={() => startEdit(message)}>
               <Dropdown.ItemIcon>
-                <Icon name="action.copy" />
+                <Icon name="action.edit" />
               </Dropdown.ItemIcon>
-              Скопировать
+              Изменить
             </Dropdown.Item>
-            <Dropdown.Item onSelect={() => togglePin(message.id)}>
+          ) : null}
+          <Dropdown.Item onSelect={() => navigator.clipboard?.writeText(excerpt(message))}>
+            <Dropdown.ItemIcon>
+              <Icon name="action.copy" />
+            </Dropdown.ItemIcon>
+            Скопировать
+          </Dropdown.Item>
+          <Dropdown.Item onSelect={() => togglePin(message.id)}>
+            <Dropdown.ItemIcon>
+              <Icon name="action.pin" />
+            </Dropdown.ItemIcon>
+            {message.pinned ? "Открепить" : "Закрепить"}
+          </Dropdown.Item>
+          {own ? (
+            <Dropdown.Item tone="danger" onSelect={() => remove([message])}>
               <Dropdown.ItemIcon>
-                <Icon name="action.pin" />
+                <Icon name="action.delete" />
               </Dropdown.ItemIcon>
-              {pinned.includes(message.id) ? "Открепить" : "Закрепить"}
+              Удалить
             </Dropdown.Item>
-            {own ? (
-              <Dropdown.Item tone="danger" onSelect={() => remove([message.id])}>
-                <Dropdown.ItemIcon>
-                  <Icon name="action.delete" />
-                </Dropdown.ItemIcon>
-                Удалить
-              </Dropdown.Item>
-            ) : null}
-          </Message.Menu>
-        </Message.Root>
-      );
-    },
-    [pinned],
-  );
+          ) : null}
+        </Message.Menu>
+      </Message.Root>
+    );
+  };
 
   return (
     <Card.Root className={styles.messenger}>
@@ -770,7 +759,7 @@ export default function ChatOverviewExample() {
         <Chat.Search />
         <Chat.Pinned items={pinnedItems} onRemove={togglePin} />
         <Chat.Messages
-          type="group"
+          group
           reader={ME}
           items={messages}
           getKey={(message) => message.id}
@@ -793,7 +782,7 @@ export default function ChatOverviewExample() {
               size="s"
               disabled={!selected?.length}
               onClick={() => {
-                remove(selected ?? []);
+                remove(messages.filter((message) => selected?.includes(message.id)));
                 setSelected(null);
               }}
             >
@@ -813,7 +802,7 @@ export default function ChatOverviewExample() {
           >
             <Composer.Attach />
             {replyTo ? (
-              <Composer.Context value={replyTo.id} onDismiss={() => setReplyTo(null)}>
+              <Composer.Context messageId={replyTo.id} onDismiss={() => setReplyTo(null)}>
                 <Composer.Title>Ответ {MEMBERS[replyTo.from].name}</Composer.Title>
                 <Composer.Description>{excerpt(replyTo)}</Composer.Description>
               </Composer.Context>
@@ -821,7 +810,7 @@ export default function ChatOverviewExample() {
             {editing ? (
               <Composer.Context
                 mode="edit"
-                value={editing.id}
+                messageId={editing.id}
                 onDismiss={() => {
                   setEditing(null);
                   setDraft("");