prime-ui-kit 0.12.0 → 0.13.1

package/dist/index.js

@@ -11,6 +11,7 @@ import {
   Card,
   ChartFrame,
   Chat,
+  ChatList,
   CodeBlock,
   ColorPresets,
   CommandMenu,
@@ -67,6 +68,7 @@ import {
   celebrate,
   chartColors,
   datepickerPresets,
+  formatChatTime,
   formatDatepickerValue,
   formatFileSize,
   formatMessageDate,
@@ -83,7 +85,7 @@ import {
   useSidebar,
   useTokenValue,
   useUploadQueue
-} from "./chunks/chunk-YJO3NJIJ.js";
+} from "./chunks/chunk-JV2KB5JZ.js";
 import {
   Avatar,
   Badge,
@@ -115,7 +117,7 @@ import {
   textTones,
   tones,
   variants
-} from "./chunks/chunk-VOZ7J72X.js";
+} from "./chunks/chunk-PK2GC77E.js";
 import {
   ControlSizeProvider,
   useOptionalControlSize
@@ -135,6 +137,7 @@ export {
   Card,
   ChartFrame,
   Chat,
+  ChatList,
   Checkbox,
   CodeBlock,
   ColorPresets,
@@ -212,6 +215,7 @@ export {
   createIcon,
   dataStates,
   datepickerPresets,
+  formatChatTime,
   formatDatepickerValue,
   formatFileSize,
   formatMessageDate,

package/dist/internal/attachmentTile.d.ts

@@ -16,6 +16,10 @@ export type AttachmentTileProps = Omit<React.HTMLAttributes<HTMLElement>, "child
     nameTitle?: string;
     /** The size, at the end of the bottom band; a video without it shows its duration. */
     meta?: string;
+    /** The file's address: the tile's middle becomes a link that opens it in a new tab. */
+    href?: string;
+    /** Name of the `href` link («Открыть договор.pdf»). */
+    openLabel?: string;
     /**
      * The pill at the top start — the format (JPG, PDF) or a word such as «Обложка»; decorative, the
      * name says it. On a picture or a video it stands on the media shade; a file passes a kit Badge.
@@ -56,7 +60,7 @@ export type AttachmentTileProps = Omit<React.HTMLAttributes<HTMLElement>, "child
  * picture, a video's first frame (lazy) with its play mark, or the sheet of a file; the upload disk
  * with its progress ring stands over the middle. Shared by FileUpload tiles and the Composer tray.
  */
-export declare function AttachmentTile({ id, kind, src, name, nameTitle, meta, badge, upload, uploadState, cancelLabel, retryLabel, onRetry, onRemove, removeLabel, pending, arrived, leaving, className, ref, ...rest }: AttachmentTileProps): import("react/jsx-runtime").JSX.Element;
+export declare function AttachmentTile({ id, kind, src, name, nameTitle, meta, href, openLabel, badge, upload, uploadState, cancelLabel, retryLabel, onRetry, onRemove, removeLabel, pending, arrived, leaving, className, ref, ...rest }: AttachmentTileProps): import("react/jsx-runtime").JSX.Element;
 /** A row of tiles scrolls sideways — its hidden edges fade, a scroll rests on a tile, a vertical
  * wheel moves it — with the bar hidden. */
 export declare function AttachmentStripScroller({ children }: {

package/dist/internal/richText.d.ts

@@ -3,7 +3,7 @@ export type RichInline = {
     type: "text";
     text: string;
 } | {
-    type: "bold" | "italic" | "strike";
+    type: "bold" | "italic" | "strike" | "spoiler";
     children: RichInline[];
 } | {
     type: "code";
@@ -29,12 +29,17 @@ export declare function safeHref(raw: string): string | null;
 export declare function parseInline(source: string): RichInline[];
 /** Blocks of a message: runs of text, quotes (`> ` lines) and fenced code. */
 export declare function parseRichText(source: string): RichBlock[];
+export type RichTextLabels = {
+    /** Accessible name of a masked spoiler: its text is not read until it is revealed. */
+    spoiler: string;
+};
 export type RichTextProps = {
     source: string;
     /** Rendered at the very end of the last line (a chat bubble's meta reserve). */
     end?: React.ReactNode;
     /** Marks every case-insensitive match of this text (a search through a chat). */
     highlight?: string;
+    labels?: Partial<RichTextLabels>;
 };
 /** A message text with its Markdown subset rendered safely; `end` closes the last text line. */
-export declare function RichText({ source, end, highlight }: RichTextProps): import("react/jsx-runtime").JSX.Element;
+export declare function RichText({ source, end, highlight, labels: labelsProp }: RichTextProps): import("react/jsx-runtime").JSX.Element;

package/dist/internal/textFormatting.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Markdown formatting of a plain text (the formatting toolbar and hotkeys of Composer and Textarea,
+ * `useTextFormatting`): pure functions over the text and its selection, so a component only applies
+ * the result to its textarea. `internal/richText` renders the same subset.
+ */
+/** A formatting command: what the toolbar button or the hotkey applies to the selection. */
+export type TextFormat = "bold" | "italic" | "strikethrough" | "code" | "spoiler" | "link" | "quote";
+/** Names of the formatting toolbar and of its tools, one per format. */
+export type TextFormattingLabels = Record<TextFormat, string> & {
+    /** Accessible name of the formatting toolbar. */
+    formatting: string;
+};
+export declare const TEXT_FORMATTING_LABELS: TextFormattingLabels;
+/** Every format in toolbar order. */
+export declare const TEXT_FORMATS: readonly TextFormat[];
+/** Text with its selection, `start <= end` (a caret when equal). */
+export type TextSelection = {
+    text: string;
+    start: number;
+    end: number;
+};
+/** The text and selection after `format` is applied to the selection. */
+export declare function applyFormat(selection: TextSelection, format: TextFormat): TextSelection;
+/**
+ * The one span that differs between two texts (common prefix and suffix removed), so the change can
+ * be typed into the textarea as one edit and stay on its undo stack.
+ */
+export declare function diffRange(before: string, after: string): {
+    start: number;
+    end: number;
+    insert: string;
+};
+/**
+ * The format a key press asks for: Mod+B · Mod+I · Mod+Shift+X · Mod+E · Mod+Shift+H · Mod+K ·
+ * Mod+Shift+9. The spoiler is not Telegram's Mod+Shift+P: Firefox and Edge reserve it for a private
+ * window and never hand it to the page.
+ */
+export declare function formatForKey(event: {
+    key: string;
+    code: string;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+}): TextFormat | null;
+/** Shortcut of every format, by modifier names: rendered as `⌘B` on Apple systems, `Ctrl+B` elsewhere. */
+export declare const FORMAT_SHORTCUTS: Record<TextFormat, {
+    shift: boolean;
+    key: string;
+}>;
+/** `⌘⇧X` on Apple systems, `Ctrl+Shift+X` elsewhere. */
+export declare function shortcutText(format: TextFormat, apple: boolean): string;

package/dist/internal/textFormattingToolbar.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+import { type ControlSize } from "./states";
+import { type TextFormattingLabels } from "./textFormatting";
+export type TextFormattingOptions = {
+    textareaRef: React.RefObject<HTMLTextAreaElement | null>;
+    /** The hotkeys and the toolbar. */
+    enabled: boolean;
+    /** Whether the toolbar may show now (not while the field is disabled, read-only or covered). */
+    toolbar: boolean;
+    labels: TextFormattingLabels;
+    /** Tier of the field; the tools stand one tier smaller. */
+    size: ControlSize;
+    /** Id of the textarea (`aria-controls` of the toolbar). */
+    controlsId?: string;
+};
+export type TextFormatting = {
+    /** On the textarea's `onSelect`. */
+    onSelect: () => void;
+    /** Call first in the textarea's `onKeyDown`; `true` when the key was a formatting one and is used. */
+    onKeyDown: (event: React.KeyboardEvent<HTMLTextAreaElement>) => boolean;
+    /** On the `position: relative` box around the field and the toolbar. */
+    anchorProps: Pick<React.HTMLAttributes<HTMLElement>, "onFocus" | "onBlur">;
+    /** The toolbar while it shows or leaves. */
+    toolbar: React.ReactNode;
+};
+export declare function useTextFormatting({ textareaRef, enabled, toolbar: toolbarAllowed, labels, size, controlsId, }: TextFormattingOptions): TextFormatting;

package/dist/skill/cheatsheet.md

@@ -34,8 +34,10 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - Show `error` after blur or on submit; `<form noValidate onSubmit>` + `<Button.Root type="submit" loading>` — not validation on every keystroke.
 - Groups of fields: `<Fieldset label="Контакты" disabled={saving}>` with the submit `<Button.Root loading>` outside it — not a hand-reset `<fieldset>` with a `Typography` heading, not `disabled` on every field while saving. One choice with a heading (`Radio.Group label`) needs no Fieldset.
 - Uploads: `const queue = useUploadQueue({ upload })` → `<FileUpload.Root queue={queue} />` (`FileUpload.Queue` when the picker lives elsewhere) — progress, «В очереди», the reason of a failure, retry and remove come with it (three at once by default, `concurrency`); not a hand-kept list of files with own progress bars. A photo appears at once from its local preview.
+- After-upload work (attach the file to a record) runs inside `upload` after the request resolves — `context.id` is the item; a file the user can open is `FileUploadFile.href`, not your own download button beside the row.
 - A choice in a form (SegmentedControl, ButtonGroup) is a field too: `label`, `hint`, `error` on its root — not a `Label` wired by hand.
 - A record card that saves each field: `<Input.Root onCommit={save}>` (save returns a Promise) — not hand-written blur / Enter / Escape handlers or a field disabled while saving.
+- Markdown text outside a chat (an announcement, a task description) is `<Textarea.Root formatting>`: the Composer's toolbar, hotkeys and subset (`**`, `_`, `~~`, `` ` ``, `||spoiler||`, links, `> `) — not a hand-made toolbar over a textarea. Turn it on only where the text is shown with its Markdown.
 - Copy or call next to a value: `Input.CopyButton`, `Input.Action` inside `Input.Wrapper` — not a Button beside the field; a password: `Input.RevealButton`.
 
 ## State
@@ -44,6 +46,9 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - Controlled triads, same names everywhere: `value` / `onValueChange`, `checked` / `onCheckedChange`, `open` / `onOpenChange` — not `onChange(event)` (except the native `Input.Field` / Textarea `onChange`), `isOpen`, `onToggle`.
 - Selection count is `multiple` (`Select.Root multiple`) — not `type="multiple"`.
 - A slow or risky action is an async event: return the request's Promise from `onConfirm`, `onCommit`, `onReorder`, `onBarChange`, `onSend`, a Switch's `onCheckedChange`, a Slider's `onCommit`, a DigitInput's `onComplete`, a Kanban or FileUpload change, a Badge `onRemove`, TagSelect `onCreate`… — the component shows pending, keeps the change on resolve and rolls it back on reject; not `true` / `false`, not your own pending flag, no `onBeforeX`.
+- A Select that saves on pick: return the save's Promise from `onValueChange` — the value shows at once with a Spinner on the trigger and a rejection rolls it back (`labels.changeFailed`); never reset the value by hand. A «Новый клиент» row in the list is `Select.Action` (`onSelect`), never a fake `Select.Item` with a sentinel value or a button under the field.
+- An option reads its parts by element type: put `Avatar.Root`, `Thumbnail.Root`, `Badge.Root` and `Select.Item*` straight in the item and call your helper as a function (`{clientAvatar(c)}`), not as `<ClientAvatar />`; anything else trailing goes in `Select.ItemMeta`.
+- Create from a search: one `persistent` `CommandMenu.Item` at the end («Создать клиента «{query}»», while the query is not empty) — it stays when a namesake matches; `CommandMenu.Empty` holds only the text.
 - A value that settles at the end of a gesture saves in its own event: Slider `onCommit` — not a request on every `onValueChange` step.
 
 ## Text: labels vs children
@@ -87,12 +92,18 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - A chart with axes or several series: `<ChartFrame.Root series state>` around the library (or your SVG) with `ChartFrame.Plot renderPlot`, `Legend`, `Table` — not a hand-made Card with a grey box while loading and a legend of colored dots.
 - Amounts, counts and dates are `numeric` columns; statuses are `Badge.Root color` from one status → color map.
 - Rows people order by hand: `onReorder(id, beforeId)` (apply it with `moveBefore`, return the save's Promise) — not a Dnd list rebuilt next to the table.
+- A short list of records people order by hand (stages, priorities) is `<List.Root onReorder>` with `List.Item value` — not up / down buttons or a hand-made `Dnd.Sortable`.
+- Groups that fold: pass `defaultCollapsedGroups={[]}` (or the controlled `collapsedGroups` + `onCollapsedGroupsChange`) — not your own button in `renderGroupHeader` or filtering `rows`. One heatmap over several columns: the same `scale: { min, max }` on each.
+- A trend in a table row is `<Sparkline layout="compact">` in the column's `cell` (a column `width`, series built once, not inline); the number itself goes in its own column.
 - Properties of one record: `<DescriptionList.Root>` of `DescriptionList.Item` — not a hand-made grid of label / value text, not a one-row DataTable.
 - Who is busy when, a plan with dates: `Gantt` with `onBarChange` / `onBarCreate` — not bars drawn by hand or a DataTable of start and end dates. Statuses moved by hand: `Kanban`.
+- Open a board card with `Kanban.Root onItemClick` (click, Enter, Space, never after a drag) or `getItemHref`; a Gantt row with `onRowClick` / `getRowHref` (the DataTable contract), a bar with `onSelect`; more facts in a bar tooltip with `renderBarTooltip` (it adds lines under the dates). A legend of hues is a row of `Badge.Root color` + `Badge.Dot` in the host's `toolbar`, the category also in text. Hour slots (bookings, appointments) are not Gantt — its unit is a calendar day.
 
 ## Chat
 
 - A conversation is `Chat`: `<Chat.Root typing selected search>` with `Chat.Header` (avatar, `Chat.Title`, `Chat.Description`, `Chat.Actions` + `Chat.SearchButton`), `Chat.Search`, `Chat.Pinned`, `<Chat.Messages items getKey getAuthor getDate renderMessage>` and `<Chat.Footer><Composer.Root /></Chat.Footer>` — not a header, a ScrollContainer and a list of your own, not Cards or a Timeline styled as bubbles, not a Textarea with a send button. A list without the rest is `Chat.Root` with `Chat.Messages` alone; one message on its own is `Message.Root`.
+- The list of conversations is `ChatList` — not a `List` or Cards with your own preview, unread counts and «печатает…». Back button and avatar in the chat header are plain children of `Chat.Header`: it lays them out side by side.
+- A dialog loading is `<Chat.Messages loading>` (bubble skeletons that cross-fade into the list) — not a Spinner or grey boxes. A bot's buttons under a message are `Message.Actions` rows of `Button.Root variant="soft" tone="neutral"` (`asChild` for links), never buttons inside `Message.Text`.
 - `renderMessage` returns a `Message.Root` (its `value` and `position` are set for you) or a `Chat.Service`; keep it stable with `useCallback` (other messages it looks up through a ref) — an item renders again only when it, its place or the function changes. Dates, runs and the unread band (`unread={key}`) come from the list.
 - A group chat is `<Chat.Messages type="group">`: put `Message.Author` (`color={hueOf(user.id)}`, `tag`, `Message.AuthorIcon` for a crown) and `Message.Avatar` on every message — the list shows the header on the first of a run and the avatar on the last; a direct chat shows neither.
 - A voice message is `VoicePlayer` inside `Message.Root`; a round video is `VideoNote` inside `Message.Root`; photos, files, places and contacts are `Message` parts — not FileUpload rows or Cards. The same album outside a chat is `Gallery`. The two players share one API: learn one, use both.
@@ -111,6 +122,7 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 ## Overlays
 
 - Blocking decision or ≤ 4 fields → `Modal` (`<Modal.Content size="s">` for a confirm); long form, filters, details → `Drawer`; a short task that ends by itself (a date, an action, a note) → `Sheet`; small panel at a control → `Popover`; list of actions → `Dropdown`; a field value → `Select`; a name for an icon button → `Tooltip`; ⌘K → `CommandMenu`; a photo, a scan or a video full screen from its thumbnail → `MediaViewer` (an album in a grid is `Gallery`, which opens it for you; a standalone viewer keeps `open` and `index` in two states) — not a Modal with an `<img>`.
+- A record's drawer or modal shows its person or object as `Drawer.Icon` / `Modal.Icon` around `Avatar.Root` / `Thumbnail.Root`. A confirm that asks for input (a reason) is a `Modal size="s"` with the field, `Modal.Confirm` and `Modal.Guard busy` — `ConfirmDialog` is a question only.
 - Never a hand-made `div` backdrop, dialog, menu or tooltip.
 - Every Modal and Drawer has all three zones: `Header` (title, ×) · `Body` (content, scrolls) · `Footer` (actions). Details: `<Drawer.Footer><Drawer.Close><Button.Root variant="outline" tone="neutral">Закрыть</Button.Root></Drawer.Close></Drawer.Footer>`, plus the main action last; a form: «Отмена» + submit. Not a drawer that ends with the body, not Save at the bottom of the body. A `Sheet` (from the bottom edge) is the opposite: no footer by default — a pick or a swipe ends it — and its header is optional: keep it when the content needs a title, drop it (× and hairline go too) when the content speaks for itself, with `aria-label` on `Sheet.Content`. Never `Drawer.Content side="bottom"`.
 - Content inside a Drawer, a Sheet or a Card is the host's own: a calendar is `Datepicker.Panel` straight in the body, across its width — no card, no padded box around it.

package/dist/skill/choosing.md

@@ -11,7 +11,7 @@ confuse. Links: [components.md](components.md). Whole screens: [composition.md](
 | type a value (text, number, code, file, photos), group the fields of a form | Inputs — Input, Textarea, DigitInput, FileUpload, Label, Hint, Fieldset |
 | pick from options, toggle, set a range, filter, a date or a color | Selection — Checkbox, Radio, Switch, SegmentedControl, Slider, Select, NativeSelect, TagSelect, SmartFilter, Datepicker, ColorField, ColorPicker, ColorSwatches |
 | see data: status labels, people, objects, numbers and their trend, properties of a record, rows, a board, a schedule, events, code, disclosed sections | Data display — Badge, Avatar, Thumbnail, Kbd, Card, DescriptionList, DataTable, Kanban, Gantt, Timeline, CodeBlock, Accordion, Sparkline, ChartFrame |
-| hold a conversation: read and send chat messages of every kind | Messages — Chat, Message, Gallery, VoicePlayer, VideoNote, Composer |
+| hold a conversation: pick a dialog, read and send chat messages of every kind | Messages — Chat, ChatList, Message, Gallery, VoicePlayer, VideoNote, Composer |
 | learn what happened, how far along it is, or watch a region load and change state; say it to a screen reader | Status and loading — Banner, Notification, ProgressBar, ProgressCircle, Spinner, Skeleton, Crossfade, EmptyPage, VisuallyHidden |
 | move between places: app sections, panels of a screen, the records of a list, the path, pages, steps | Navigation — Tabs, Breadcrumb, Pagination, List, Stepper, Sidebar, BottomNav |
 | see something on top of the page, or a photo or video full screen | Overlays — Tooltip, Popover, Dropdown, Modal, ConfirmDialog, Drawer, Sheet, CommandMenu, MediaViewer |
@@ -74,7 +74,10 @@ never a Timeline or a list of Cards styled as bubbles. Code → CodeBlock. A num
 `Chat.Messages` (from `items` with `renderMessage`, or `Message.Root` children) and `Chat.Footer`
 with the Composer — never a hand-built header, ScrollContainer and list. A list of messages without
 the rest (comments as a chat, a read-only history) → `Chat.Root` with `Chat.Messages` alone; one
-message on its own → `Message.Root`. A group chat → `Chat.Messages type="group"`: `Message.Author`
+message on its own → `Message.Root`. The list of conversations beside the chat (the dialogs pane of a
+messenger or an inbox) → `ChatList` (`items`, `renderItem` with `ChatList.Item`, `value`): unread
+counts, «печатает…», drafts, ticks, a row menu and search come with it — never `List` with a hand-made
+count and preview; `List` stays for records that are not conversations (tickets, letters, invoices). A group chat → `Chat.Messages type="group"`: `Message.Author`
 (`tag`, `Message.AuthorIcon`) and `Message.Avatar` on every message, the list shows them on the
 first and the last of a run. A voice message → `VoicePlayer` inside `Message.Root`; a call recording
 outside a chat → `VoicePlayer` alone. A round video message → `VideoNote` inside `Message.Root`

package/dist/skill/components.md

@@ -24,7 +24,7 @@ Type a value, and the field anatomy: label, hint, error.
 | Component | Purpose | Docs |
 |---|---|---|
 | Input | Single-line text field with label, hint, error and slots for icons, affixes, a clear button and a counter. | [COMPONENT.md](reference/components/input/COMPONENT.md) · [examples](reference/components/input/examples/) |
-| Textarea | Multi-line text field with label, hint, error and a character counter; grows with its content from `rows` lines up to `maxRows`, then scrolls inside. | [COMPONENT.md](reference/components/textarea/COMPONENT.md) · [examples](reference/components/textarea/examples/) |
+| Textarea | Multi-line text field with label, hint, error and a character counter; grows with its content from `rows` lines up to `maxRows`, then scrolls inside; `formatting` adds the Composer's Markdown toolbar and hotkeys. | [COMPONENT.md](reference/components/textarea/COMPONENT.md) · [examples](reference/components/textarea/examples/) |
 | DigitInput | A row of square single-digit cells for a fixed-length code (OTP from SMS, PIN, pickup code), with the field label, hint and error. | [COMPONENT.md](reference/components/digit-input/COMPONENT.md) · [examples](reference/components/digit-input/examples/) |
 | FileUpload | Files and the image gallery in one component: a document field (rows), file cards, an image gallery with a cover (`trigger="tile"` `layout="grid"` `cover`) or an attachment tray (`trigger="button"` + `FileUpload.Queue layout="strip"`); uploads through a queue (`useUploadQueue`), reorder and server saves. | [COMPONENT.md](reference/components/file-upload/COMPONENT.md) · [examples](reference/components/file-upload/examples/) |
 | Label | Field label (native `<label>`) with required and optional markers. | [COMPONENT.md](reference/components/label/COMPONENT.md) · [examples](reference/components/label/examples/) |
@@ -60,7 +60,7 @@ Show data: labels, people, objects, cards, tables, boards, feeds, code, disclose
 | Badge | The kit's one chip: a static label for a status, category or count, a removable value or applied filter, and a pressable toggle with a hover action — in a palette color. | [COMPONENT.md](reference/components/badge/COMPONENT.md) · [examples](reference/components/badge/examples/) |
 | Avatar | A round photo of a person or organization with an initials or icon fallback, a presence dot and overlapping groups. | [COMPONENT.md](reference/components/avatar/COMPONENT.md) · [examples](reference/components/avatar/examples/) |
 | Thumbnail | A preview of an object — product, vehicle, file, cover — at a fixed aspect ratio (`ratio`), an image or a video (`Thumbnail.Video`, first frame and length), a colored icon fallback, and a selectable tile (`checked`). | [COMPONENT.md](reference/components/thumbnail/COMPONENT.md) · [examples](reference/components/thumbnail/examples/) |
-| Sparkline | A small line or bar chart with its headline — the value at rest, its change against the point before and its date — where any point can be scrubbed. | [COMPONENT.md](reference/components/sparkline/COMPONENT.md) · [examples](reference/components/sparkline/examples/) |
+| Sparkline | A small line or bar chart with its headline — the value at rest, its change against the point before and its date — where any point can be scrubbed; `layout="compact"` — just the plot, for a table cell. | [COMPONENT.md](reference/components/sparkline/COMPONENT.md) · [examples](reference/components/sparkline/examples/) |
 | ChartFrame | A dashboard panel around any chart (Recharts, ECharts, visx, Chart.js or a hand-drawn SVG): title, headline value, a measured plot area, a series legend that hides series (`hiddenSeries`), loading / empty / error states (`state`, `onRetry`) that cross-fade, a tooltip body and a data table for screen readers. | [COMPONENT.md](reference/components/chart-frame/COMPONENT.md) · [examples](reference/components/chart-frame/examples/) |
 | Kbd | A key cap for a keyboard key or a shortcut, rendered as a native `<kbd>`. | [COMPONENT.md](reference/components/kbd/COMPONENT.md) · [examples](reference/components/kbd/examples/) |
 | Card | A filled surface block with structural templates for metrics, charts, lists, calls to action and covers. | [COMPONENT.md](reference/components/card/COMPONENT.md) · [examples](reference/components/card/examples/) |
@@ -78,12 +78,13 @@ A conversation: message bubbles of every kind and the composer.
 
 | Component | Purpose | Docs |
 |---|---|---|
-| Chat | A conversation assembled: `Chat.Header` (avatar, title, status that turns into «печатает…», actions, `Chat.SearchButton`), `Chat.Search` (marks, counts and steps through matches), `Chat.Pinned`, `Chat.Messages` — the one message list: from `items` + `renderMessage` (dates, runs, unread band added) or `Message.Root` children, virtualized, new messages that enter by themselves, the «к последним» button, read receipts, jumps, selection with `Chat.SelectionBar`, history paging, `type="group"` author headers and avatars — and `Chat.Footer` for the Composer. | [COMPONENT.md](reference/components/chat/COMPONENT.md) · [examples](reference/components/chat/examples/) |
-| Message | One chat message in its shell (bubble, picture, circle): incoming / outgoing, runs of one author (the tail ends a run), time and delivery ticks in the corner, a group chat's author header (`Message.Author` with `tag` and `Message.AuthorIcon`), reply, forwarded, reactions with the reaction bar, the context menu, and every content kind (text with Markdown, `Message.Media` albums, round video, voice, file, location, contact, link preview); `Message.Typing`. | [COMPONENT.md](reference/components/message/COMPONENT.md) · [examples](reference/components/message/examples/) |
+| Chat | A conversation assembled: `Chat.Header` (avatar, title, status that turns into «печатает…», actions, `Chat.SearchButton`), `Chat.Search` (marks, counts and steps through matches), `Chat.Pinned`, `Chat.Messages` — the one message list: from `items` + `renderMessage` (dates, runs, unread band added) or `Message.Root` children, virtualized, new messages that enter by themselves, the «к последним» button, read receipts, jumps, selection with `Chat.SelectionBar`, history paging, `type="group"` author headers and avatars — and `Chat.Footer` for the Composer; a first-load state of bubble skeletons (`Chat.Messages loading`). | [COMPONENT.md](reference/components/chat/COMPONENT.md) · [examples](reference/components/chat/examples/) |
+| Message | One chat message in its shell (bubble, picture, circle): incoming / outgoing, runs of one author (the tail ends a run), time and delivery ticks in the corner, a group chat's author header (`Message.Author` with `tag` and `Message.AuthorIcon`), reply, forwarded, reactions with the reaction bar, the context menu, and every content kind (text with Markdown, `Message.Media` albums, round video, voice, file, location, contact, link preview); `Message.Typing`; a bot's inline keyboard (`Message.Actions`); spoilers in the Markdown. | [COMPONENT.md](reference/components/message/COMPONENT.md) · [examples](reference/components/message/examples/) |
 | Gallery | Photos and videos as a messenger album: one, or up to ten laid out from their aspect ratios with nothing measured; video tiles with a first frame and length, the shared transfer disk per tile, tiles that open the album in MediaViewer (`viewer={false}` to open your own from `onOpenChange` / `onIndexChange`). `Message.Media` is a Gallery in a message. | [COMPONENT.md](reference/components/gallery/COMPONENT.md) · [examples](reference/components/gallery/examples/) |
 | VoicePlayer | A voice message player: a round play disk, a waveform that is the seek slider, and the time with the playback speed — in a chat bubble or standalone; one sound at a time on the page; `getWaveform` for audio without levels. | [COMPONENT.md](reference/components/voice-player/COMPONENT.md) · [examples](reference/components/voice-player/examples/) |
 | VideoNote | A round video message: a still first frame with the play disk, played with sound on a press; the same player API as VoicePlayer (transcript, transfer either way, one sound at a time); alone in `Message.Root` it is the message. | [COMPONENT.md](reference/components/video-note/COMPONENT.md) · [examples](reference/components/video-note/examples/) |
 | Composer | The message input of a chat: a field that grows from one line, Enter to send, attachments through an upload queue, a reply / edit bar whose id goes with the send, Markdown formatting of a selection, voice and round video messages with pause, and the «печатает…» signal (`onActivityChange`). | [COMPONENT.md](reference/components/composer/COMPONENT.md) · [examples](reference/components/composer/examples/) |
+| ChatList | The conversation list of a messenger, built from List: dialogs from `items` + `renderItem` (`ChatList.Item` with the avatar, name, time, preview), the open one `value`, a search field that marks matches, unread / muted / «@» counts, pin, delivery ticks, «печатает…» and drafts that cross-fade, a row menu at the pointer (`ChatList.ItemMenu`), rows that glide to a new order, virtualized rows, loading placeholders and `hasMore` / `onLoadMore`. | [COMPONENT.md](reference/components/chat-list/COMPONENT.md) · [examples](reference/components/chat-list/examples/) |
 
 ## Status and loading (`status`)
 

package/dist/skill/composition.md

@@ -17,7 +17,7 @@ is, and is shown live with its code in the playground (category «Компози
 | Create in a side panel | [form-drawer.tsx](patterns/form-drawer.tsx) | Drawer form: groups, errors on submit, focus on the first invalid field, loading, toast |
 | Dashboard | [dashboard.tsx](patterns/dashboard.tsx) | period switch, KPI row that cross-fades to the new period, a Sparkline revenue trend, invoiced vs paid in a ChartFrame, panels with progress and a split, short table + link to the list |
 | Screen states | [screen-states.tsx](patterns/screen-states.tsx) | page error in a Banner with retry, region loading with a Skeleton, Crossfade between states, table error in place, first-run EmptyPage |
-| Messenger | [chat.tsx](patterns/chat.tsx) | PageContent.Split of dialogs and a `Chat`: `Chat.Header` with the back button, avatar, title, the status that turns into «печатает…» (`typing`) and the search button, `Chat.Search`, `Chat.Pinned`, `Chat.Messages` from `items` + a stable `renderMessage` (dates, runs, the unread band and service events from the data, history loaded above with `hasOlder` / `onLoadOlder`), every kind of Message (photos, file, contact, voice in a VoicePlayer with a transcript, round video), reactions, reply and edit from the menu through `Composer.Context value` (`replyTo` / `editOf`), the jump to the quoted message (`Message.Reply target`), optimistic sends whose messages rise from the composer while the client's answer slides in, «печатает…» both ways (`onActivityChange` → `Chat.Root typing`), unread counts from `onNewMessage` and `onRead`, selection with `Chat.SelectionBar`, delivery ticks, the Composer in `Chat.Footer` |
+| Messenger | [chat.tsx](patterns/chat.tsx) | PageContent.Split of a `ChatList` (live last message, ticks, unread counts, «печатает…») and a `Chat`: `Chat.Header` with the back button, avatar, title, the status that turns into «печатает…» (`typing`) and the search button, `Chat.Search`, `Chat.Pinned`, `Chat.Messages` from `items` + a stable `renderMessage` (dates, runs, the unread band and service events from the data, history loaded above with `hasOlder` / `onLoadOlder`), every kind of Message (photos, file, contact, voice in a VoicePlayer with a transcript, round video), reactions, reply and edit from the menu through `Composer.Context value` (`replyTo` / `editOf`), the jump to the quoted message (`Message.Reply target`), optimistic sends whose messages rise from the composer while the client's answer slides in, «печатает…» both ways (`onActivityChange` → `Chat.Root typing`), unread counts from `onNewMessage` and `onRead`, selection with `Chat.SelectionBar`, delivery ticks, the Composer in `Chat.Footer` |
 | Sales pipeline board | [kanban-board.tsx](patterns/kanban-board.tsx) | header with one primary action, PageToolbar with SmartFilter search and a board / list SegmentedControl, Crossfade between a Kanban and a DataTable of the same deals, column totals in `renderColumnMeta`, moves saved through an `onValueChange` promise that the server can refuse, movable stages with locked first and last, the deal in a Drawer with a DescriptionList and stage actions, skeleton first load |
 | App frame for desktop and phone (root layout) | [app-shell.tsx](patterns/app-shell.tsx) | Sidebar rail on a wide screen, floating BottomNav in `AppShell.Footer` on a phone («Ещё» opens the Sidebar panel), AppHeader with the menu button, title and search to CommandMenu, counts on items, a home page that cross-fades between sections |
 | Media library | [media-library.tsx](patterns/media-library.tsx) | PageToolbar with sections and counts, search (`SmartFilter` with `fields={[]}`), order and «Загрузить»; uploads through `useUploadQueue` in `FileUpload` tiles (`trigger="tile"`, `layout="grid"`) with progress, a failure and retry, a done file moving into the library; a grid of `Thumbnail` / `Thumbnail.Video` tiles that open `MediaViewer` out of the tile (`getOrigin`, `thumbnails`, `renderActions`) or, in selection mode, are picked (`checked`) for bulk download and a `ConfirmDialog` delete; a Skeleton first load and a filtered `EmptyPage` in a `Crossfade` |

package/dist/skill/layouts.md

@@ -4,6 +4,8 @@ Every screen sits in one frame: `AppShell.Root` with Nav / `AppHeader` / Main (t
 the nav rail one layer above it) → `PageContent` (header + body). `AppShell.Main` carries the page gutters
 and `PageContent.Body` spaces its blocks 40 apart, so your code adds **no outer padding and no
 margins**. Your CSS only lays out the inside of a block (grids, rows) with `gap` on `--prime-space-*`.
+Main's top space under the header is part of the frame — 24, then 40 from 1024px: a page header starts
+there; never cancel it with a negative margin or a padding override.
 
 The page recipes are whole, working screens in [patterns/](patterns/) — start from the closest one
 ([the list](composition.md#patterns)) and keep its skeleton. The rules behind them are in [composition.md](composition.md).

package/dist/skill/patterns/chat.module.css

@@ -6,12 +6,3 @@
   flex-direction: column;
   min-height: 0;
 }
-
-.pane {
-  flex: 1 1 auto;
-  min-height: 0;
-}
-
-.dialogs {
-  padding: var(--prime-space-2);
-}

package/dist/skill/patterns/chat.tsx

@@ -4,6 +4,7 @@ import {
   Button,
   Card,
   Chat,
+  ChatList,
   Composer,
   type ComposerActivity,
   type ComposerMediaItem,
@@ -11,14 +12,13 @@ import {
   type ComposerRecording,
   Dropdown,
   type GalleryItem,
+  hueOf,
   Icon,
-  List,
   Message,
   type MessageReaction,
   type MessageStatus,
   type MessageUser,
   PageContent,
-  ScrollContainer,
   type UploadContext,
   useUploadQueue,
   VideoNote,
@@ -50,7 +50,14 @@ type ChatMessage = Content & {
   reactions?: MessageReaction[];
 };
 
-type Dialog = { id: string; name: string; initials: string; unread: number };
+type Dialog = {
+  id: string;
+  name: string;
+  initials: string;
+  unread: number;
+  preview: string;
+  at: Date;
+};
 
 const NOW = new Date(2026, 9, 8, 15, 0);
 const at = (day: number, hour: number, minute: number) => new Date(2026, 9, day, hour, minute);
@@ -86,9 +93,30 @@ const photo = (seed: string, width: number, height: number, alt: string): Galler
 });
 
 const DIALOGS: Dialog[] = [
-  { id: "vector", name: "ООО «Вектор»", initials: "ВК", unread: 2 },
-  { id: "granit", name: "ООО «Гранит»", initials: "ГР", unread: 0 },
-  { id: "kozlov", name: "ИП Козлов", initials: "ИК", unread: 1 },
+  {
+    id: "vector",
+    name: "ООО «Вектор»",
+    initials: "ВК",
+    unread: 2,
+    preview: "Ок, жду акт",
+    at: at(8, 14, 31),
+  },
+  {
+    id: "granit",
+    name: "ООО «Гранит»",
+    initials: "ГР",
+    unread: 0,
+    preview: "Акт сверки подписан",
+    at: at(7, 16, 5),
+  },
+  {
+    id: "kozlov",
+    name: "ИП Козлов",
+    initials: "ИК",
+    unread: 1,
+    preview: "Подключите ЭДО",
+    at: at(6, 11, 40),
+  },
 ];
 
 /** Older history, loaded when the conversation is scrolled to its start. */
@@ -239,6 +267,7 @@ const MESSAGE_SEND_MS = 700;
 const MESSAGE_READ_MS = 1500;
 const CLIENT_TYPING_MS = 1800;
 const HISTORY_MS = 900;
+const DIALOG_MS = 800;
 const TRANSCRIBE_MS = 1400;
 
 /** A stand-in for the file server: sends an attachment in a few steps. */
@@ -521,6 +550,13 @@ export default function ChatPattern() {
     };
   }, []);
   const dialog = DIALOGS.find((item) => item.id === dialogId) ?? DIALOGS[0];
+  /** The dialog whose history has arrived: opening another one loads it first. */
+  const [loadedId, setLoadedId] = React.useState<string | null>(null);
+  React.useEffect(() => {
+    if (!dialogId) return;
+    const timer = window.setTimeout(() => setLoadedId(dialogId), DIALOG_MS);
+    return () => window.clearTimeout(timer);
+  }, [dialogId]);
 
   const loadOlder = async () => {
     if (!hasOlder) return;
@@ -728,27 +764,36 @@ export default function ChatPattern() {
         >
           <PageContent.List aria-label="Диалоги">
             <Card.Root className={styles.paneCard}>
-              <ScrollContainer className={styles.pane}>
-                <List.Root className={styles.dialogs}>
-                  {DIALOGS.map((item) => (
-                    <List.Item
-                      key={item.id}
-                      current={item.id === dialogId}
-                      onClick={() => setDialogId(item.id)}
+              <ChatList.Root
+                items={DIALOGS}
+                getKey={(item) => item.id}
+                value={dialogId}
+                onValueChange={setDialogId}
+                now={NOW}
+                renderItem={(item) => {
+                  // The open dialog shows its live last message; the others their stored one.
+                  const last = item.id === dialogId ? messages[messages.length - 1] : undefined;
+                  return (
+                    <ChatList.Item
+                      time={last?.sentAt ?? item.at}
+                      status={last?.from === "me" ? last.status : undefined}
+                      unread={unread[item.id] ?? 0}
+                      typing={item.id === dialogId && clientTyping}
                     >
-                      <List.ItemIcon>
-                        <Avatar.Root color="blue">
+                      <ChatList.ItemIcon>
+                        <Avatar.Root color={hueOf(item.id)}>
                           <Avatar.Fallback>{item.initials}</Avatar.Fallback>
+                          {item.id === "vector" ? <Avatar.Status status="online" /> : null}
                         </Avatar.Root>
-                      </List.ItemIcon>
-                      <List.ItemText>{item.name}</List.ItemText>
-                      {(unread[item.id] ?? 0) > 0 ? (
-                        <List.ItemCount color="blue">{unread[item.id]}</List.ItemCount>
-                      ) : null}
-                    </List.Item>
-                  ))}
-                </List.Root>
-              </ScrollContainer>
+                      </ChatList.ItemIcon>
+                      <ChatList.ItemText>{item.name}</ChatList.ItemText>
+                      <ChatList.ItemDescription author={last?.from === "me" ? "Вы" : undefined}>
+                        {last ? excerpt(last) : item.preview}
+                      </ChatList.ItemDescription>
+                    </ChatList.Item>
+                  );
+                }}
+              />
             </Card.Root>
           </PageContent.List>
 
@@ -757,7 +802,7 @@ export default function ChatPattern() {
               <Chat.Root typing={clientTyping} selected={selected} onSelectedChange={setSelected}>
                 <Chat.Header>
                   <PageContent.BackButton />
-                  <Avatar.Root color="blue">
+                  <Avatar.Root color={hueOf(dialog.id)}>
                     <Avatar.Fallback>{dialog.initials}</Avatar.Fallback>
                     <Avatar.Status status="online" />
                   </Avatar.Root>
@@ -770,6 +815,7 @@ export default function ChatPattern() {
                 <Chat.Search />
                 <Chat.Pinned items={pinnedItems} onRemove={togglePin} />
                 <Chat.Messages
+                  loading={loadedId !== dialogId}
                   reader={ME}
                   items={messages}
                   getKey={(message) => message.id}

package/dist/skill/patterns/kanban-board.tsx

@@ -471,15 +471,9 @@ export default function KanbanBoardPattern() {
                 }}
                 renderColumnMeta={figures}
                 loading={loading}
+                onItemClick={(item) => openDeal(item.id)}
                 renderItem={(item) => (
-                  <Kanban.Item
-                    onClick={() => openDeal(item.id)}
-                    onKeyDown={(event) => {
-                      if (event.key === "Enter" && event.target === event.currentTarget) {
-                        openDeal(item.id);
-                      }
-                    }}
-                  >
+                  <Kanban.Item>
                     <Kanban.ItemTitle>{item.company}</Kanban.ItemTitle>
                     <Kanban.ItemDescription>
                       {RUBLES.format(item.amount)} · до {DAY.format(new Date(item.due))}

package/dist/skill/patterns/schedule.tsx

@@ -530,10 +530,22 @@ export default function SchedulePattern() {
               setSelected({ bar, person: findPerson(row.id) });
               setDetailOpen(true);
             }}
+            renderBarTooltip={(bar) => (bar.client ? CLIENTS[bar.client].name : KIND[bar.kind])}
             toolbar={
-              <Typography as="span" variant="body-s" tone="muted">
-                {loading ? "Загружаем график…" : `Сотрудников: ${rows.length} из ${people.length}`}
-              </Typography>
+              <>
+                <Typography as="span" variant="body-s" tone="muted">
+                  {loading
+                    ? "Загружаем график…"
+                    : `Сотрудников: ${rows.length} из ${people.length}`}
+                </Typography>
+                {/* The legend of client hues: the bar's hue repeats its client, the tooltip names it. */}
+                {(Object.keys(CLIENTS) as ClientId[]).map((client) => (
+                  <Badge.Root key={client} color={CLIENTS[client].color}>
+                    <Badge.Dot />
+                    {CLIENTS[client].name}
+                  </Badge.Root>
+                ))}
+              </>
             }
             empty={
               <EmptyPage.Root size="s" role="status" aria-labelledby="schedule-empty">