prime-ui-kit 0.11.1 → 0.13.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./components/index";
 export * from "./hooks/useTokenValue";
 export * from "./hooks/useUploadQueue";
 export * from "./icons/index";
+export { formatFileSize } from "./internal/fileSize";
 export { hueOf } from "./internal/palette";
 export * from "./internal/states";
 export type { TransferDirection, TransferHandler, TransferState } from "./internal/transfer";

package/dist/index.js

@@ -11,6 +11,7 @@ import {
   Card,
   ChartFrame,
   Chat,
+  ChatList,
   CodeBlock,
   ColorPresets,
   CommandMenu,
@@ -33,6 +34,7 @@ import {
   Kanban,
   Kbd,
   LinkButton,
+  List,
   LoginForm,
   MediaViewer,
   Message,
@@ -66,7 +68,9 @@ import {
   celebrate,
   chartColors,
   datepickerPresets,
+  formatChatTime,
   formatDatepickerValue,
+  formatFileSize,
   formatMessageDate,
   formatMessageTime,
   getWaveform,
@@ -81,7 +85,7 @@ import {
   useSidebar,
   useTokenValue,
   useUploadQueue
-} from "./chunks/chunk-CUH6DJ57.js";
+} from "./chunks/chunk-Z3WKKAS6.js";
 import {
   Avatar,
   Badge,
@@ -113,7 +117,7 @@ import {
   textTones,
   tones,
   variants
-} from "./chunks/chunk-WDTSHOTD.js";
+} from "./chunks/chunk-E6SQBSDF.js";
 import {
   ControlSizeProvider,
   useOptionalControlSize
@@ -133,6 +137,7 @@ export {
   Card,
   ChartFrame,
   Chat,
+  ChatList,
   Checkbox,
   CodeBlock,
   ColorPresets,
@@ -164,6 +169,7 @@ export {
   Kbd,
   Label,
   LinkButton,
+  List,
   LoginForm,
   MediaViewer,
   Message,
@@ -209,7 +215,9 @@ export {
   createIcon,
   dataStates,
   datepickerPresets,
+  formatChatTime,
   formatDatepickerValue,
+  formatFileSize,
   formatMessageDate,
   formatMessageTime,
   getPasswordStrength,

package/dist/internal/VisuallyHidden.d.ts

@@ -1,5 +1,10 @@
 import type * as React from "react";
 export type VisuallyHiddenProps = React.HTMLAttributes<HTMLSpanElement> & {
+    /**
+     * An announcement region: `polite` — `role="status"`, read after what is being said; `assertive`
+     * — `role="alert"`, read at once. Both are atomic: the whole text is read on every change.
+     */
+    live?: "polite" | "assertive";
     ref?: React.Ref<HTMLSpanElement>;
 };
 /** The sr-only recipe as a class, for an element that must stay itself (a focusable file input). */
@@ -9,7 +14,7 @@ export declare const visuallyHiddenClass: string;
  * Public as `VisuallyHidden` (docs in `src/components/visually-hidden/`); inside the kit it replaces
  * the per-component `.srOnly` / `.visuallyHidden` CSS copies.
  */
-export declare function VisuallyHidden({ className, ...rest }: VisuallyHiddenProps): import("react/jsx-runtime").JSX.Element;
+export declare function VisuallyHidden({ className, live, ...rest }: VisuallyHiddenProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace VisuallyHidden {
     var displayName: string;
 }

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/api-contract.md

@@ -235,7 +235,7 @@ it saves).
 | `Icon`, `createIcon` | kit icon set and domain glyphs — see Icons below |
 | `chartColors` | the chart palette as CSS values for a chart library: `series` 1…8 in order, `other`, `grid`, `axis`, `scale` — follows the theme |
 | `useTokenValue("--prime-space-7")` | a length token in px for geometry CSS cannot take (SVG coordinates, canvas, virtual rows); follows a theme switch |
-| `VisuallyHidden` | text for screen readers only (an icon-only part's name, a spoken count); `role="status"` on it for a polite announcement |
+| `VisuallyHidden` | text for screen readers only (an icon-only part's name, a spoken count); `live="polite"` on it for an announcement (`"assertive"` only for an error that blocks) |
 
 ## Icons
 

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.
@@ -163,7 +175,7 @@ Full rules: [responsive.md](responsive.md).
 - Breakpoints 640 · 768 · 1024 · 1280 only for the app frame; inside a page — intrinsic grids (`auto-fill, minmax`) and container queries.
 - A wide table scrolls inside itself; offer `DataTable.ColumnsMenu` in its `toolbar` — never drop columns by breakpoint, never hand-build the chooser.
 - A row that opens a record page is `getRowHref` (a real link: ⌘-click, new tab), a row that opens a drawer is `onRowClick` — never `navigate()` in `onRowClick`, never your own `event.target` checks for buttons in the row.
-- A list + detail screen is `PageContent.Split` in a `PageContent.Root fill` page; a full-height table is `scrollHeight="fill"` — never a height computed from `100vh`.
+- A list + detail screen is `PageContent.Split` in a `PageContent.Root fill` page, its records a `List` (`current` on the open one) — never ghost Buttons with a soft current; a full-height table is `scrollHeight="fill"` — never a height computed from `100vh`.
 - App sections on phones: `BottomNav` in `AppShell.Footer` — not in Main, not `position: fixed`, no own media query: the shell hides the footer while the Sidebar rail is on screen; a short task from the bottom edge: `Sheet` — Select, Dropdown, Popover and Modal become sheets below 640 by themselves.
 - Your hover styles inside `@media (hover: hover)`; nothing hover-only. Do not wrap kit fields to raise their text for iOS — they keep 16px on touch already.
 - A long form saves through the panel action with a count («Сохранить 3 изменения») — not a sticky bar at the bottom of a phone.

package/dist/skill/choosing.md

@@ -11,9 +11,9 @@ 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 path, pages, steps | Navigation — Tabs, Breadcrumb, Pagination, Stepper, Sidebar, BottomNav |
+| 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 |
 | get the app frame and the structure of a page | Page — AppShell, AppHeader, PageContent, PageToolbar, Divider, ScrollContainer |
 | drag things by hand | Interaction — Dnd (a status board: Kanban in Data display) |
@@ -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`
@@ -125,7 +128,8 @@ filter above a single table goes into the DataTable `toolbar` instead. A page th
 height to the work (a board, a chat) may let `AppHeader` carry the page instead: `AppHeader.Title
 as="h1"` and the PageToolbar in `AppHeader.Tools` — then main has no `PageContent.Header`. A record
 opened from a table: its own page → DataTable `getRowHref`; in place → `onRowClick` + Drawer; a list
-worked through record by record (mail, chat, tickets) → `PageContent.Split`. Sections of a long rail → `Sidebar.Group
+worked through record by record (mail, chat, tickets) → `PageContent.Split` with a `List` of the records
+(`current` on the open one). Sections of a long rail → `Sidebar.Group
 collapsible`; a section with sub-pages → `Sidebar.Sub`; the signed-in user → `Sidebar.Account` in a
 `Dropdown.Trigger` at the bottom of `Sidebar.Footer`.
 
@@ -133,6 +137,7 @@ collapsible`; a section with sub-pages → `Sidebar.Sub`; the signed-in user →
 
 | Pair | Rule |
 |---|---|
+| List / Sidebar / Tabs / Card list / DataTable | List: the records of a list + detail screen (dialogs, tickets, mail), one open at a time (`current`), each row a button or a link with a text line, a preview, meta and a count. Sidebar: the sections of the **app**. Tabs: panels of **one screen**. `Card.List` (`variant="list"`): static facts in a card, nothing opens. DataTable: many records compared by columns, sorted, filtered, selected in bulk. |
 | Tabs / SegmentedControl | Tabs switch **panels of content** (navigation inside a screen). SegmentedControl switches a **value or mode** of the same content (period, view mode, filter). |
 | Modal / Drawer / Sheet / Popover / Tooltip | Modal: blocking decision or a short form (≤ 4 fields) that needs full attention. Drawer: long form, filters, record details beside the page, while keeping page context. Sheet: a short task that ends by itself — a pick, an action, a short note — raised from the bottom edge. Popover: small non-modal panel anchored to a control (quick edit, explanation with a link). Tooltip: a few words naming or explaining a control, no interactive content. |
 | Select / NativeSelect | Select: the kit's floating list — icons, descriptions, groups, search, `multiple`, `clearable`. NativeSelect: a plain text list where the OS picker is better (phones) or the value must post with a form by `name`. |

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`)
 
@@ -103,13 +104,14 @@ Say what happens: system messages, progress, loading placeholders, state swaps,
 
 ## Navigation (`navigation`)
 
-Move between places: app navigation (side rail, bottom bar on phones), tabs, the path, pages, steps.
+Move between places: app navigation (side rail, bottom bar on phones), tabs, the records of a list, the path, pages, steps.
 
 | Component | Purpose | Docs |
 |---|---|---|
 | Tabs | Tabs for navigating between content panels of one screen. | [COMPONENT.md](reference/components/tabs/COMPONENT.md) · [examples](reference/components/tabs/examples/) |
 | Breadcrumb | Breadcrumbs: the path to the current page. | [COMPONENT.md](reference/components/breadcrumb/COMPONENT.md) · [examples](reference/components/breadcrumb/examples/) |
 | Pagination | Page-by-page navigation: arrows, page numbers with ellipsis and a compact «3 / 12» view. | [COMPONENT.md](reference/components/pagination/COMPONENT.md) · [examples](reference/components/pagination/examples/) |
+| List | A selectable list of rows — the list half of a list + detail screen: conversations, tickets, mail, records; the open one is `current`. | [COMPONENT.md](reference/components/list/COMPONENT.md) · [examples](reference/components/list/examples/) |
 | Stepper | Steps of a multi-step process with pending, active, completed and danger statuses. | [COMPONENT.md](reference/components/stepper/COMPONENT.md) · [examples](reference/components/stepper/examples/) |
 | Sidebar | App side navigation in three modes — expanded, compact, hidden — and an off-canvas panel on narrow screens. | [COMPONENT.md](reference/layout/sidebar/COMPONENT.md) · [examples](reference/layout/sidebar/examples/) |
 | BottomNav | Phone navigation: 2–6 sections at the bottom, flat or a floating glass capsule, icons with or without labels, an optional round action. | [COMPONENT.md](reference/layout/bottom-nav/COMPONENT.md) · [examples](reference/layout/bottom-nav/examples/) |

package/dist/skill/composition.md

@@ -17,7 +17,11 @@ 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` |
+| Resource schedule | [schedule.tsx](patterns/schedule.tsx) | full-height `Gantt` (`scrollHeight="fill"`) under a `PageToolbar` with search, role / client filters and team sections; people with avatars, client hues, lanes for overlaps, locked absences and milestones; moves saved through an async `onBarChange` or refused and glided back, new work drawn with `onBarCreate` and named in a Modal (cancel fades the ghost), `onSelect` details in a Drawer with a `DescriptionList` and a confirmed removal, `loading` and filtered `empty` |
 
 Pick the closest one, rename the domain, keep the skeleton. Change structure only when the task needs
 it, and then by the rules below.
@@ -176,6 +180,10 @@ Hierarchy comes from space and a handful of type roles, not from size jumps, col
 
 - A list page is `DataTable` with the filters in its `toolbar` — `SmartFilter.Toolbar` and
   `SmartFilter.Chips` inside `SmartFilter.Root` (or one SegmentedControl / Select for a single field).
+- Where the filters go: tools of one table live in its `toolbar`; when the page itself carries
+  sections with counts, a view switch (board / list, grid / list) or filters that drive more than one
+  table — a board, a schedule, a media grid — the page gets `PageToolbar` and the table keeps only its
+  own tools (`DataTable.ColumnsMenu`).
 - Paging is built in: `paging="pages"` (default, Pagination and the «Показано 1–6 из 10» range in the
   footer), `paging="infinite"` for feeds, `paging="none"` for short lists on dashboards and details.
 - When the server holds more than you load (a CRM list, a register): `source="server"` — `rows` is the

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).
@@ -191,7 +193,8 @@ from what people do, not from how the backend is split. The full guide with the
   `PageContent.Detail` in a filling page. Side by side from 48rem of the split's own width, one pane
   at a time below it with `PageContent.BackButton` first in the detail's header; `open` is «a record
   is chosen». Each pane gives its last child the free height: a Card with its own `ScrollContainer`
-  (`anchor="end"` for a thread). Details that open over a table and close again are a Drawer instead.
+  (`anchor="end"` for a thread). The records in the list pane are a `List` (`current` on the open
+  one). Details that open over a table and close again are a Drawer instead.
 
 ## Which pattern to start from
 

package/dist/skill/patterns/app-shell.module.css

@@ -0,0 +1,18 @@
+/* App shell: the frame (Sidebar / BottomNav / AppHeader) lays itself out; this file only places the
+   home page's blocks. Blocks 40 apart come from PageContent.Body. */
+
+/* KPI row: as many ~14rem tiles as fit, one column on a phone. */
+.kpis {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-14) * 4)), 1fr));
+  gap: var(--prime-space-4);
+}
+
+/* A list row: the text at the start, the meta (time, sum) at the end. */
+.row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+  min-width: 0;
+}