prime-ui-kit 0.21.1 → 0.21.3

package/dist/skill/reference/components/file-upload/COMPONENT.md

@@ -55,7 +55,7 @@ FileUpload.Root                 field frame: label → trigger → files → hin
       │                         middle: picture, video frame + play mark or the file's sheet ·
       │                         band at the bottom: name (no extension) … size (a video: duration);
       │                         the upload disk over the middle
-      └─ add tile               trigger="tile": «+», «Добавить», `count из max`; the whole row when empty
+      └─ add tile               trigger="tile": «+», «Добавить»; the whole row when empty, gone at `max`
 
 FileUpload.Queue                the same files with no trigger of their own (a tray whose paperclip lives elsewhere)
 
@@ -67,7 +67,7 @@ FileUpload.Item                 a file row the set does not draw (own actions, a
 ├─ FileUpload.ItemActions       buttons at the end of the row (kit Button)
 └─ FileUpload.ItemProgress      the kit ProgressBar across the row
 ```
-The built-in zone body (icon, `labels.title`, `labels.description` and a decorative soft Button) renders when there are no children; the built-in button content is the paperclip and `labels.browse`. The set draws its rows and tiles itself from `value` and `queue`; the `Item` parts are for a row it does not draw (a download button, a report being prepared).
+The built-in zone body (icon, `labels.title` and a decorative soft Button; formats and limits go in `hint`) renders when there are no children; the built-in button content is the paperclip and `labels.browse`. The set draws its rows and tiles itself from `value` and `queue`; the `Item` parts are for a row it does not draw (a download button, a report being prepared).
 
 **One set of files.** The files are application data: `value` (`{ id, name, size?, type?, src?, alt?, href? }`, controlled, or `defaultValue`) in its order, then every upload of `queue` that is not in it, in the queue's order. A file of `value` whose `id` is an upload's id shows that upload's state. `type` is the MIME type (without it the kind — picture, video, other — is read from the name's extension); `src` is a picture or a video; `alt` is spoken in place of the name and never drawn. `href` is the file's address: the row's name (a neutral `LinkButton`) or the whole tile under its chips becomes a link that opens the file in a new tab — the server's `Content-Disposition` decides open or download. Every change — a reorder by drag or Alt + ← / →, a removal, files added to the queue — goes through `onValueChange` with the whole new list, uploads included; the queue follows (a removed upload leaves it and stops, a moved one keeps its order through `queue.move`). Without `value` and `defaultValue` the set is the queue alone: an uncontrolled list of uploads that reorders through `queue.move`. Return a promise from `onValueChange` to save on a server: the touched files wait busy, a moved file or new files stand in their new places meanwhile, a removed file stays until the answer. Resolve and the change stands (a controlled owner applies `value` before resolving); reject and the set goes back and `labels.changeFailed` is announced.
 
@@ -127,7 +127,7 @@ A rejection of `upload` fails the file with its message as the reason; retry que
 | `disabled` | `boolean` | `false` | Blocks picking and drag-and-drop; the files are read-only: no add tile, no reorder, no remove. |
 | `accept` | `string` | — | Native `accept` of the file input; dropped files outside it are not taken (MIME type, `type/*` or `.ext`; a file with no MIME type by its extension). |
 | `multiple` | `boolean` | — | Allows several files at once in the picker. |
-| `max` | `number` | — | Most files in the set: picked and dropped files are cut to the room left; the add tile counts `count из max` (the digits roll) and at the limit says «Лимит файлов» and takes nothing. |
+| `max` | `number` | — | Most files in the set: picked and dropped files are cut to the room left; at the limit the add tile closes up in place and comes back once a file leaves. The limit a person should know goes in `hint`. |
 | `name` | `string` | — | Name of the file input inside a form. |
 | `onFilesChange` | `(files: File[]) => void` | — | Called with the picked or dropped files (of `accept`, cut to `max`); the input is reset, so the same file can be picked again. Not called when `queue.add` takes them. |
 | `picker` | `Ref<{ open: (options?: { accept?: string }) => void }>` | — | Opens the file picker from code (a custom body button, a menu item): `open()`, or `open({ accept })` for one pick of other types that also filter its files. A disabled or full field does not open. |
@@ -250,7 +250,7 @@ The upload queue of FileUpload: `concurrency` files go at once through `upload`,
 |---|---|---|---|
 | `dropzone` | the drop area with an icon, a title, a description and a decorative browse button, the files under it | a standalone upload field of a form; documents | yes |
 | `button` | a kit Button of the tier, no zone and no drop: soft with the paperclip and text, ghost when its content is a `Button.Icon` alone | a composer's paperclip, an «attach» action in a toolbar or a dense form; pair it with `FileUpload.Queue` when the files live elsewhere | |
-| `tile` | a dashed add tile — «+», «Добавить», `count из max` — as the last cell of the files; the whole row while empty; files drop anywhere on the set | file cards and the image gallery: files are added where they will lie | |
+| `tile` | a dashed add tile — «+», «Добавить» — as the last cell of the files; the whole row while empty; files drop anywhere on the set | file cards and the image gallery: files are added where they will lie | |
 | `none` | nothing of its own: a hidden file input that `picker.open({ accept })` clicks, no drop | a menu of attachment kinds whose items each open the picker with their own types (`Composer.Attach` with `Composer.Item`) | |
 
 ### variant (FileUpload.Root)
@@ -299,7 +299,7 @@ The upload queue of FileUpload: `concurrency` files go at once through `upload`,
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `max` | the add tile counts `count из max` (the digits roll); at the limit it says «Лимит файлов» and takes nothing | the set has a limit | — |
+| `max` | at the limit the add tile closes up in place and comes back once a file leaves; the limit is stated in `hint` | the set has a limit | — |
 | `invalid` (Root) | danger line and icon | a rejected file without a message; otherwise pass `error` | — |
 | `invalid` (Item) | danger soft fill, danger ring, danger description | an upload failed | `false` |
 | `disabled` | disabled fill and text, drops ignored; the files read-only | uploading is unavailable, a published set | `false` |
@@ -322,7 +322,7 @@ The upload queue of FileUpload: `concurrency` files go at once through `upload`,
 | disabled | `disabled` | `data-disabled="true"`, disabled input, disabled fill and text, drops ignored; no add tile, actions or drag; a disabled button with `trigger="button"` |
 | empty | no files, `trigger="tile"` | the add tile spans the row with «Нажмите или перетащите файлы» |
 | cover | `cover`, the first tile | «Обложка» in place of the format pill, `data-cover` on the tiles wrapper (the first tile takes a 2 × 2 cell in a grid) |
-| full | the set reaches `max` | `data-full` on the add tile: «Лимит файлов», faded; the file input is `aria-disabled` and opens no picker, so the field label stays undimmed |
+| full | the set reaches `max` | the add tile (and its file input) closes up in place; focus that was on it moves to the last file; it enters again once a file leaves |
 | queued | queue item `status: "queued"` | a row reads «size · В очереди» over an empty bar; a tile (`data-upload="queued"`) dims under a 40px disk on the `media` shade (Button `shape="circle"` `variant="shade"`) whose ring turns at its least arc, described by «В очереди» |
 | loading | `status: "loading"` | a row reads «size · Загрузка 40%» and its bar fills (`accent`); a tile's white arc grows clockwise from 12 o'clock with the share sent (the `progress` ring of a shade circle Button, one variable `--ring-value`, gliding `base` while it turns); the disk is the remove («Отменить загрузку: name», described by the state), the corner × is not drawn; the tile still reorders, its carried copy keeps the disk |
 | done | `status: "done"` | a row reads «size» over a full `success` bar; a tile's ring fills, then its disk fades and shrinks to 0.9 (`fast`, `inert`), the picture returns to full or the sheet comes back |
@@ -379,15 +379,11 @@ Also `data-size`, `data-variant` on the zone, `data-size` on Item, `data-status`
 | Key | Default | Used for |
 |---|---|---|
 | `title` | `"Выберите файл или перетащите его сюда"` | Title of the built-in zone body. |
-| `description` | `"JPEG, PNG, PDF, MP4 до 50 МБ"` | Description of the built-in body; an empty string hides it. |
 | `browse` | `"Выбрать файл"` | Text of the browse button: decorative in the built-in zone body, the control itself with `trigger="button"`. |
 | `optional` | `"необязательно"` | Marker after the label when `optional`. |
 | `add` | `"Добавить"` | Text of the add tile (`trigger="tile"`). |
 | `addLabel` | `"Добавить файлы"` | Accessible name of the add tile's file input. |
 | `empty` | `"Нажмите или перетащите файлы"` | Text of the add tile of an empty set (it spans the row). |
-| `emptyHint` | `"Можно несколько сразу"` | Second line of the empty add tile without `max` (with it the counter stands there). |
-| `full` | `"Лимит файлов"` | Text of the add tile when `max` is reached. |
-| `count` | `"{count} из {max}"` | Counter on the add tile (with `max`). |
 | `cover` | `"Обложка"` | Pill of the first tile with `cover`. |
 | `queued` | `"В очереди"` | A file waiting for a free slot (a row's status, a tile's name and its empty ring). |
 | `uploading` | `"Загрузка {percent}%"` | A file in flight. |
@@ -415,7 +411,7 @@ Also `data-size`, `data-variant` on the zone, `data-size` on Item, `data-status`
 | [sizes.tsx](examples/sizes.tsx) | Every tier of the zone and of its file rows: padding, icon, button, text and the format badge follow it — `size`. |
 | [states.tsx](examples/states.tsx) | A default zone, a disabled one whose files are read-only and an invalid one without a message — `disabled`, `invalid`. |
 | [validation.tsx](examples/validation.tsx) | A required scan checked as soon as it is picked: a wrong type or a large file shakes in an error that leaves when the file is removed; a hint and an optional zone — `required`, `hint`, `error`, `optional`. |
-| [gallery.tsx](examples/gallery.tsx) | An image gallery of an office listing: the first photo is the cover on two tiles and a photo dragged first takes its place, new photos upload in their tiles, one fails and retries, and the add tile counts up to the limit and then says so — `trigger`, `layout`, `cover`, `max`, `value`, `queue`. |
+| [gallery.tsx](examples/gallery.tsx) | An image gallery of an office listing: the first photo is the cover on two tiles and a photo dragged first takes its place, new photos upload in their tiles, one fails and retries, and the add tile leaves at the limit — `trigger`, `layout`, `cover`, `max`, `value`, `queue`. |
 | [file-cards.tsx](examples/file-cards.tsx) | Materials of a warehouse inspection as cards: photos and documents in one grid, each with its picture or format and the name with the size in megabytes as the report gives it; new files upload in their cards and the order is set by drag or Alt + arrows — `trigger`, `layout`, `defaultValue`, `queue`, `formatSize`. |
 | [attachment-tray.tsx](examples/attachment-tray.tsx) | A reply to a client with a paperclip instead of a drop zone: the icon-only picker button, and the attachments as one scrolling row of tiles above the message — `trigger`, `aria-label`, `FileUpload.Queue`, `layout`. |
 | [saving.tsx](examples/saving.tsx) | Published listing photos with no picker, every change saved on the server: a moved or removed photo waits busy, and a change the server refuses puts the set back — `FileUpload.Queue`, `onValueChange`, `value`, `cover`. |
@@ -431,7 +427,7 @@ Also `data-size`, `data-variant` on the zone, `data-size` on Item, `data-status`
 - A `Label` and a `Hint` placed around the zone by hand → pass `label`, `hint`, `error`.
 - Nesting `FileUpload.Root` in another `<label>` → it already is one.
 - A plain `<button>` in a custom body expecting it to open the picker → call `picker.current?.open()` in its `onClick` (`open({ accept })` for one pick of other types); an inline «browse» link is `<LinkButton asChild><button type="button" onClick={…}>`.
-- `labels.hint` → the built-in secondary line is `labels.description`; `hint` is the field hint under the zone.
+- Formats and size limits written into the zone → the zone states none of its own; they go in `hint`, under the zone.
 - A hand-written upload loop with its own progress, retry and abort per row → `useUploadQueue` + `queue`.
 - A zone recolored into a button for a paperclip → `trigger="button"`.
 - An image gallery — a grid of photos, an add tile, a cover and drag — written by hand, or looked for as a separate component → it is this one: `trigger="tile"`, `layout="grid"`, `cover`.

package/dist/skill/reference/components/file-upload/examples/gallery.tsx

@@ -1,4 +1,4 @@
-/** An image gallery of an office listing: the first photo is the cover on two tiles and a photo dragged first takes its place, new photos upload in their tiles, one fails and retries, and the add tile counts up to the limit and then says so — `trigger`, `layout`, `cover`, `max`, `value`, `queue`. */
+/** An image gallery of an office listing: the first photo is the cover on two tiles and a photo dragged first takes its place, new photos upload in their tiles, one fails and retries, and the add tile leaves at the limit — `trigger`, `layout`, `cover`, `max`, `value`, `queue`. */
 import { FileUpload, type FileUploadFile, type UploadContext, useUploadQueue } from "prime-ui-kit";
 import * as React from "react";
 
@@ -88,7 +88,7 @@ export default function FileUploadGalleryExample() {
     <div className={styles.wide}>
       <FileUpload.Root
         label="Фотографии помещения"
-        hint="JPG или PNG, первое фото — обложка в каталоге"
+        hint="JPG или PNG, до 6 фото; первое фото — обложка в каталоге"
         trigger="tile"
         layout="grid"
         cover

package/dist/skill/reference/components/file-upload/examples/in-form.tsx

@@ -4,9 +4,8 @@ import * as React from "react";
 
 import styles from "./examples.module.css";
 
-const HINT = "Все страницы, с подписями обеих сторон";
-/** The zone names the formats the check takes. */
-const ZONE_LABELS = { description: "PDF до 20 МБ" };
+/** The hint names the formats the check takes. */
+const HINT = "PDF до 20 МБ, все страницы с подписями обеих сторон";
 const MAX_SIZE = 20 * 1024 * 1024;
 
 /** A picked file as a file of the set. */
@@ -52,7 +51,6 @@ export default function FileUploadInFormExample() {
         accept=".pdf"
         required
         hint={HINT}
-        labels={ZONE_LABELS}
         error={error}
         value={scan}
         onValueChange={change}

package/dist/skill/reference/components/file-upload/examples/narrow.tsx

@@ -58,6 +58,7 @@ export default function FileUploadNarrowExample() {
       <FileUpload.Root label="Чек об оплате" defaultValue={RECEIPT} />
       <FileUpload.Root
         label="Фотографии скутера"
+        hint="До 10 фото"
         trigger="tile"
         layout="grid"
         cover

package/dist/skill/reference/components/file-upload/examples/overview.tsx

@@ -5,9 +5,6 @@ import styles from "./examples.module.css";
 
 const MAX_SIZE = 10 * 1024 * 1024;
 
-/** The zone names the limit the stand-in server holds. */
-const ZONE_LABELS = { description: "Любые файлы до 10 МБ" };
-
 const ATTACHED: readonly FileUploadFile[] = [
   {
     id: "deal-contract",
@@ -53,8 +50,7 @@ export default function FileUploadOverviewExample() {
     <div className={styles.column}>
       <FileUpload.Root
         label="Документы сделки"
-        hint="Договор, смета и акты по сделке; можно несколько сразу"
-        labels={ZONE_LABELS}
+        hint="Договор, смета и акты по сделке; любые файлы до 10 МБ"
         multiple
         defaultValue={ATTACHED}
         queue={queue}

package/dist/skill/reference/components/file-upload/examples/sizes.tsx

@@ -16,7 +16,7 @@ export default function FileUploadSizesExample() {
           size={size}
           label={size}
           defaultValue={CONTRACT}
-          labels={{ title: "Перетащите файл", description: "" }}
+          labels={{ title: "Перетащите файл" }}
         />
       ))}
     </div>

package/dist/skill/reference/components/file-upload/examples/states.tsx

@@ -1,8 +1,8 @@
 /** A default zone, a disabled one whose files are read-only and an invalid one without a message — `disabled`, `invalid`. */
 import { FileUpload, type FileUploadFile } from "prime-ui-kit";
 
-/** The zone names the formats the order takes. */
-const ZONE_LABELS = { description: "PDF или PNG до 20 МБ" };
+/** The hint names the formats the order takes. */
+const HINT = "PDF или PNG до 20 МБ";
 
 const ACT: readonly FileUploadFile[] = [
   { id: "act", name: "Акт сверки.pdf", size: 310_000, type: "application/pdf" },
@@ -11,15 +11,14 @@ const ACT: readonly FileUploadFile[] = [
 export default function FileUploadStatesExample() {
   return (
     <div>
-      <FileUpload.Root label="default" labels={ZONE_LABELS} />
+      <FileUpload.Root label="default" hint={HINT} />
       <FileUpload.Root
         label="disabled"
         disabled
-        labels={ZONE_LABELS}
         defaultValue={ACT}
         hint="Заказ закрыт, документы только для просмотра"
       />
-      <FileUpload.Root label="invalid" invalid labels={ZONE_LABELS} />
+      <FileUpload.Root label="invalid" invalid hint={HINT} />
     </div>
   );
 }

package/dist/skill/reference/components/file-upload/examples/validation.tsx

@@ -6,9 +6,6 @@ import styles from "./examples.module.css";
 
 const MAX_SIZE = 20 * 1024 * 1024;
 
-/** The zone names the formats the check takes. */
-const ZONE_LABELS = { description: "PDF до 20 МБ" };
-
 /** A picked file as a file of the set. */
 const toFile = (file: File): FileUploadFile => ({
   id: `${file.name}-${file.size}-${file.lastModified}`,
@@ -33,8 +30,7 @@ export default function FileUploadValidationExample() {
       <FileUpload.Root
         label="Скан договора"
         required
-        hint="Все страницы, с подписями обеих сторон"
-        labels={ZONE_LABELS}
+        hint="PDF до 20 МБ, все страницы с подписями обеих сторон"
         error={scanError(scan)}
         value={scan}
         onValueChange={setScan}
@@ -43,8 +39,7 @@ export default function FileUploadValidationExample() {
       <FileUpload.Root
         label="Доверенность"
         optional
-        hint="Если подписывает не директор"
-        labels={ZONE_LABELS}
+        hint="PDF до 20 МБ, если подписывает не директор"
       />
     </div>
   );

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

@@ -159,7 +159,7 @@ Do not wrap a `plain` board's columns in your own boxes, and do not put a `well`
 | refused | `limit` reached, `canDrop` returns `false` or a reason | `data-dnd-reject` on the `<ul>`: `danger-soft` fill; the reason in a chip under the carried card |
 | locked column | `locked` | `data-locked` on the column; the grip is a lock named «Закреплено» |
 | full | count ≥ `limit` | `data-full` on the column, orange count `count / limit` |
-| empty | no cards | a compact `EmptyPage` in Dnd's dashed drop slot at the top (`fill-strong` dashed line, no fill): «Нет карточек» and the hint «Перетащите сюда карточку»; a `disabled` board shows the text alone; the whole column stays a drop area |
+| empty | no cards | a compact `EmptyPage` in Dnd's dashed drop slot at the top (`fill-strong` dashed line, no fill): «Нет карточек»; the whole column stays a drop area |
 | loading | `loading` | `aria-busy` and `data-loading` on the root; `Skeleton` cards; `Crossfade` swaps them for the cards |
 | loading, no columns yet | `loading` with empty `columns` | an `aria-hidden` row of `loadingColumns` placeholder columns; the columns fade in where they stood (`enterMotion`) |
 | disabled | `disabled` / `Kanban.Item disabled` | `data-disabled` on the root / card; no `aria-roledescription`, no shortcuts, no column grips |
@@ -217,7 +217,6 @@ A card's own `onKeyDown` runs before the board's: `preventDefault()` in it keeps
 | `count` | `"Карточек: {count}"` | Spoken name of the count badge. |
 | `countLimit` | `"Карточек: {count} из {limit}"` | Spoken name of the count badge of a column with a `limit`. |
 | `empty` | `"Нет карточек"` | Text of an empty column. |
-| `emptyHint` | `"Перетащите сюда карточку"` | Hint under the empty-column text, while cards can be dropped (not on a `disabled` board). |
 | `full` | `"Колонка «{column}» заполнена ({limit})"` | Why a full column refuses a card: spoken, and shown under the carried card. |
 | `moveColumn` | `"Переместить колонку «{column}»"` | Name of the column grip (`reorderableColumns`). |
 | `column` | `"Колонка «{column}»"` | A column as the live region names it when it is carried or moved («Колонка «Демо»: позиция 2 из 4»). |

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

@@ -8,7 +8,7 @@
 ## When to use
 - The list side of a list + detail screen (`Page.Split` → `Page.List`): tickets, letters, invoices worked through one by one; the open one is `current`.
 - A short column of records that each open something — a page (`href`, `asChild` with a router link) or a detail pane (`onClick`).
-- A short list the team puts in order (funnel stages, queues, priorities) — `onReorder`, a `value` per item.
+- A short list the team puts in order (funnel stages, queues, priorities) — `onReorder`, a `value` per item; rows the system fixes stay in the same list with `locked`.
 - Rows with controls of their own beside the row that opens the record (a stage shown on the board, a ⋯ menu) — `List.ItemActions`.
 
 ## When not to use
@@ -67,6 +67,7 @@ List.Root                   <ul aria-label>; size (else the host tier) → row t
 | `rel` | `string` | — | Relationship of the `<a>` (`href` only). |
 | `asChild` | `boolean` | `false` | Renders the single child (a router link) as the row; its children are the content. |
 | `disabled` | `boolean` | `false` | Muted and out of the Tab order: a disabled button, or `aria-disabled` and no navigation on a link. |
+| `locked` | `boolean` | `false` | With `onReorder`: the row holds its place (a system stage) and shows a lock in the grip's box; no row moves past it. The row and its `List.ItemActions` work as on any row. |
 | `children` | `ReactNode` | — | `List.ItemIcon`, `List.ItemText`, `List.ItemDescription`, `List.ItemMeta`, `List.ItemCount`, `List.ItemActions`; loose text becomes the text line. |
 | `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `className` and native attributes of the row element (`target`, `rel` on a link). |
 
@@ -155,6 +156,7 @@ A second line or an avatar makes a row taller than the one-line height; the vert
 | focus-visible | keyboard | the focus ring inside the row edge |
 | disabled | `disabled` | `disabled` on a button; `aria-disabled="true"`, no `href` on a link, `tabindex="-1"` on an `asChild` element; `data-disabled="true"`; disabled text; in a reorderable list the handle is disabled and the row holds its place |
 | reorderable | `onReorder` | `data-reorderable="true"` on the root (a `Dnd.Sortable` `<ul>`); each `<li>` is a sortable item (`data-dnd-item` = `value`) with a `Dnd.Handle` at its end; drag by the handle (a touch hold on touch), Alt + ↑ / ↓ from the handle or the row; a lifted row leaves a dashed gap in the row's radius, its neighbours glide, the copy (handle and row, in the row's padding and radius) follows the pointer and sets down in its new place without a jump |
+| locked | `locked` (with `onReorder`) | `data-locked` on the `<li>`; the Dnd lock (`role="img"`, «{label}: закреплено») in the grip's box, so the columns line up with the movable rows; the row does not drag or move by Alt + arrows, and no other row is put where it would shift it — a keyboard step over it is refused aloud; the row element and its `List.ItemActions` work as on any row |
 | saving a move | `onReorder` returned a pending promise | the row stays in its new place, `aria-busy="true"`, the handle is busy (Dnd: a spinner in the disabled grip), the row content dims to 0.6 (`--prime-motion-fade-fast` both ways); a rejection glides the row back |
 | own controls | `List.ItemActions` in the item | the row element and the controls stand in one frame that takes the hover, press and current fills for both; the element itself stays clear; `side="start"` controls come before the element in the frame, `data-side` on the actions |
 | rows come and go | the data adds or takes out a `List.Item` (`value`, else its key) | a new row rises in once (`enterMotion`), a removed one closes up in place (`listPresence`); the first render stays still |
@@ -168,7 +170,8 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 - Text and description truncate with an ellipsis; give a long `List.ItemText` a `title` with the full text.
 - On a coarse pointer a row is at least the touch target (44px).
 - Reorderable (`onReorder`): an `xs` handle box ends each row, 4px after the row element and its `List.ItemActions` (inline-end: on the left in RTL); the row keeps its own padding and fill, so every row's handle stands on one line.
-- `List.ItemActions`: the controls one tier below the row, 4px apart, as far from the row's edge as a control box of that tier stands from its top and bottom — at any row height: one line, with `List.ItemDescription`, with an avatar, the touch row. The end edge, or the start edge with `side="start"`, where the row's own padding then parts the controls from its icon or text.
+- `List.ItemActions`: the controls one tier below the row, 4px apart, as far from the row's edge as a control box of that tier stands from its top and bottom — at any row height: one line, with `List.ItemDescription`, with an avatar, the touch row. The row's height is measured onto it (a ResizeObserver), so the inset never rests on a percentage height that engines resolve differently. The end edge, or the start edge with `side="start"`, where the row's own padding then parts the controls from its icon or text.
+- A locked row keeps every column of the movable rows: its `List.ItemActions` on the same side, the lock in the grip's box. System stages and the team's stages are one list, not two.
 - One toggle place per row: a plain row ends with its toggle (label first); a reorderable row leads with it (`side="start"`) and ends with the grip — never a toggle between the label and the grip.
 - A colour dot in `List.ItemIcon` is the large `Badge.Dot` (8px) centred in an icon-wide box, so the text lines up with the rows that carry icons.
 
@@ -181,7 +184,7 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 |---|---|
 | `Tab` | Moves focus between rows; a disabled row is skipped. |
 | `Enter` · `Space` | Opens the record; a link row takes Enter only. |
-| `Alt + ↑` · `Alt + ↓` | With `onReorder`, moves the row one place up or down (from its handle or the row). |
+| `Alt + ↑` · `Alt + ↓` | With `onReorder`, moves the row one place up or down (from its handle or the row); a `locked` row does not move, and a step over one is refused and announced. |
 
 ### ARIA
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -191,7 +194,7 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 - The row's name is its text, description, meta and count, in that order; the leading icon or avatar is `aria-hidden` — the text names the row.
 - Arrow keys do not move between rows: rows are ordinary Tab stops, as in the Sidebar.
 - `List.ItemActions` stand beside the row element, never inside it: the row's name stays its text. Tab follows the row as it reads: the `side="start"` controls, the row, the `side="end"` controls.
-- With `onReorder` each row gets a handle named «Переместить {label}» (`labels.reorderItem`, `{label}` is the row's text line) and `aria-keyshortcuts`, last in the row: Tab reaches the row with its `List.ItemActions`, then the handle; the new place is announced politely («Новый лид: позиция 2 из 5»), a row being saved is `aria-busy`.
+- With `onReorder` each row gets a handle named «Переместить {label}» (`labels.reorderItem`, `{label}` is the row's text line) and `aria-keyshortcuts`, last in the row: Tab reaches the row with its `List.ItemActions`, then the handle; the new place is announced politely («Новый лид: позиция 2 из 5»), a row being saved is `aria-busy`. A `locked` row ends with a lock instead: `role="img"` named «{label}: закреплено» (`labels.lockedItem`); a keyboard step over it is refused aloud («Переговоры: «Новая» закреплено, дальше не переместить», Dnd `labels.blocked`).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -199,6 +202,7 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 | Key | Default | Used for |
 |---|---|---|
 | `reorderItem` | `"Переместить {label}"` | `aria-label` of a row's drag handle (`onReorder`); `{label}` is the row's text line. |
+| `lockedItem` | `"{label}: закреплено"` | Name of the lock a `locked` row shows in the grip's place; `{label}` is the row's text line. |
 
 ## Examples
 | Example | Shows |
@@ -209,7 +213,7 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 | [with-icon.tsx](examples/with-icon.tsx) | Leading avatars of clients, icons of queues and colour dots of projects; an avatar takes the row tier, a dot stands in an icon-wide box — `List.ItemIcon`, `Badge.Dot`. |
 | [overflow.tsx](examples/overflow.tsx) | A long inbox in a pane of a fixed height: the list scrolls in a ScrollContainer and long names and previews truncate — `List.ItemText`, `List.ItemDescription`. |
 | [as-link.tsx](examples/as-link.tsx) | Rows as links to the invoice pages: a plain link, or your router link through the slot — `href`, `asChild`. |
-| [reorder.tsx](examples/reorder.tsx) | Funnel stages in the team's order: a stage moves by its handle or Alt+arrows and is saved on the server; its switch leads the row, the grip ends it — `onReorder`, `value`, `side`. |
+| [reorder.tsx](examples/reorder.tsx) | Funnel stages in one list: the team's stages move by the handle or Alt+arrows and are saved on the server, the system ones hold their places with a lock where the grip is; the switch leads every row, the grip ends it — `onReorder`, `value`, `locked`, `side`. |
 | [row-controls.tsx](examples/row-controls.tsx) | Funnel stages with their own controls: a colour dot names the stage's hue, a switch shows it on the board and a menu edits it, all beside the row that opens the stage — `List.ItemActions`, `Badge.Dot`. |
 
 ## Mistakes
@@ -221,9 +225,10 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 - Up / down buttons on rows or a hand-made `Dnd.Sortable` of rows to order them → `List.Root onReorder` with a `value` on every item.
 - `onReorder` that rolls the order back itself on an error → return the promise; a rejection moves the row back.
 - A Switch or a menu button put inside a row, or a row rebuilt as a `div` to hold one → `List.ItemActions` beside the row element.
+- System stages in a list of their own above or below the movable ones, or `disabled` to pin them (it dims the row and lets neighbours pass) → one list, `locked` on the system rows.
 - A Switch at the end of a reorderable row, between its label and the grip → `List.ItemActions side="start"`; the grip keeps the end.
 - A hollow `Icon` circle or a hand-drawn dot as a stage colour → `Badge.Dot color` in `List.ItemIcon`.
 
 ## Related
-- **Built from:** [Badge](../badge/COMPONENT.md) (`List.ItemCount`; `Badge.Dot` in `List.ItemIcon`), [Avatar](../avatar/COMPONENT.md) (`List.ItemIcon` gives an avatar the row tier), [Dnd](../dnd/COMPONENT.md) (`onReorder`: `Dnd.Sortable`, the busy `Dnd.Handle`)
+- **Built from:** [Badge](../badge/COMPONENT.md) (`List.ItemCount`; `Badge.Dot` in `List.ItemIcon`), [Avatar](../avatar/COMPONENT.md) (`List.ItemIcon` gives an avatar the row tier), [Dnd](../dnd/COMPONENT.md) (`onReorder`: `Dnd.Sortable`, the busy `Dnd.Handle`, the lock of a `locked` row)
 - **See also:** [Page](../../layout/page/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Tabs](../tabs/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Card](../card/COMPONENT.md)

package/dist/skill/reference/components/list/examples/reorder.tsx

@@ -1,16 +1,25 @@
-/** Funnel stages in the team's order: a stage moves by its handle or Alt+arrows and is saved on the server; its switch leads the row, the grip ends it — `onReorder`, `value`, `side`. */
+/** Funnel stages in one list: the team's stages move by the handle or Alt+arrows and are saved on the server, the system ones hold their places with a lock where the grip is; the switch leads every row, the grip ends it — `onReorder`, `value`, `locked`, `side`. */
 import { Card, List, moveBefore, Switch } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 const STAGES = [
+  {
+    id: "new",
+    name: "Новая",
+    description: "Сюда попадает каждая заявка",
+    deals: 57,
+    shown: true,
+    system: true,
+  },
   {
     id: "lead",
     name: "Новый лид",
     description: "Заявка с сайта или от партнёра",
     deals: 42,
     shown: true,
+    system: false,
   },
   {
     id: "qualified",
@@ -18,6 +27,7 @@ const STAGES = [
     description: "Бюджет и сроки подтверждены",
     deals: 18,
     shown: true,
+    system: false,
   },
   {
     id: "proposal",
@@ -25,6 +35,7 @@ const STAGES = [
     description: "КП отправлено",
     deals: 11,
     shown: true,
+    system: false,
   },
   {
     id: "contract",
@@ -32,8 +43,24 @@ const STAGES = [
     description: "Согласование с юристами",
     deals: 6,
     shown: true,
+    system: false,
+  },
+  {
+    id: "won",
+    name: "Успешно",
+    description: "Сделка закрыта",
+    deals: 24,
+    shown: false,
+    system: true,
+  },
+  {
+    id: "lost",
+    name: "Отказ",
+    description: "Сделка не состоялась",
+    deals: 9,
+    shown: false,
+    system: true,
   },
-  { id: "won", name: "Оплата", description: "Счёт выставлен", deals: 3, shown: false },
 ];
 
 const SAVE_DELAY_MS = 600;
@@ -59,7 +86,7 @@ export default function ListReorderExample() {
           }}
         >
           {stages.map((stage) => (
-            <List.Item key={stage.id} value={stage.id}>
+            <List.Item key={stage.id} value={stage.id} locked={stage.system}>
               <List.ItemActions side="start">
                 <Switch.Root
                   aria-label={`Показывать «${stage.name}» на доске`}

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

@@ -46,6 +46,7 @@ Message.Root                      role="article" row «{author}, {time}» (an op
 │                                 over a picture or a circle)
 ├─ Message.Actions                a row of a bot's inline keyboard under the bubble (Button.Root children);
 │                                 several make several rows
+├─ [failure reason]               a danger caption under a failed message (`failureReason`)
 ├─ Message.Menu                   Dropdown.Content anchored to the message (Dropdown.Anchor) at the pointer (+ «Выбрать» in a chat with a selection)
 └─ [reaction bar]                 floating toolbar above the bubble: long press, long hover, `R`
 
@@ -55,7 +56,7 @@ The part that ends a bubble closes its last line with the meta's spacer — an i
 
 In a list (`Chat.Messages`) a message reads the list through `internal/messageList`: its place in a run (`position`) and the chat's kind decide the author's header (first of a run in a group chat) and the avatar (last of a run); the list registers it for new-message entry and read receipts, selects it, jumps to it and holds its size changes still. On its own a message given an author or an avatar does the same by its `position`: the header on `single` / `first`, the avatar (and the gutter) on `single` / `last`.
 
-Content parts in short: `Message.Media` — a [Gallery](../gallery/COMPONENT.md) the message shapes (the messenger album layout from the items' ratios, every box final before load, the shared transfer disk over a tile, the meta overlay; an album's gaps stand on the incoming surface in both directions). `VideoNote` and `VoicePlayer` are components of their own that declare themselves parts (the round shell, and a fill bubble) and carry the same transfer props as `Message.File`. `Message.File` — a round format tile (or the preview) that is also its one action (download, cancel inside the progress ring, retry), the name, and the size line under it ending with the spacer. `Message.Location` — the map edge to edge with an accent pin (breathing when `live`), the place and the address ending with the spacer. `Message.Sticker` — a square picture with no bubble (`media` shell, the meta on its pill): the kit draws a webp, gif or apng from `src`; a Lottie (.tgs) or video sticker is your player as children (the kit has no runtime dependencies), with `loading` while it prepares. `Message.Text` renders the Markdown subset the Composer writes — **bold**, _italic_, ~~strike~~, `code`, fenced code, Markdown links, bare URLs, `> ` quotes — as elements; links take only http(s), mailto and tel addresses (anything else stays text) and open in a new tab. `Message.Menu` holds the `Dropdown.Item`s you write (Ответить, Скопировать, Закрепить, Переслать, Пожаловаться, Удалить with `tone="danger"`); in a chat with a selection the kit appends a separator and «Выбрать».
+Content parts in short: `Message.Media` — a [Gallery](../gallery/COMPONENT.md) the message shapes (the messenger album layout from the items' ratios, every box final before load, the shared transfer disk over a tile, the meta overlay; an album's gaps stand on the incoming surface in both directions). `VideoNote` and `VoicePlayer` are components of their own that declare themselves parts (the round shell, and a fill bubble) and carry the same transfer props as `Message.File`. `Message.File` — a round format tile (or the preview) that is also its one action (download, cancel inside the progress ring, retry), the name, and the size line under it ending with the spacer. `Message.Location` — the map edge to edge with an accent pin (breathing when `live`), the place and the address ending with the spacer. `Message.Sticker` — a square picture with no bubble (`media` shell, the meta on its pill): the kit draws a webp, gif or apng from `src`; a Lottie (.tgs) or video sticker is your player as children (the kit has no runtime dependencies), with `loading` while it prepares. `Message.Text` renders the Markdown subset the Composer writes — **bold**, _italic_, __underline__, ~~strike~~, `||spoiler||`, `code`, fenced code, Markdown links, bare URLs, `> ` quotes; a backslash writes a mark as text (`\*`) — as elements; a messenger's text comes as a plain string with its `entities` (offsets in UTF-16 code units, Telegram style), never read as Markdown, so `**` in it stays text and a range may start inside a word (`TextEntity`, `getTextEntities` and `getRichTextSource` in [RichText](../rich-text/COMPONENT.md)); links take only http(s), mailto and tel addresses (anything else stays text) and open in a new tab. `Message.Menu` holds the `Dropdown.Item`s you write (Ответить, Скопировать, Закрепить, Переслать, Пожаловаться, Удалить with `tone="danger"`); in a chat with a selection the kit appends a separator and «Выбрать».
 
 `formatMessageTime(date, timeZone?)` gives «09:05», the default `formatTime`; the time is read in `timeZone`, else the list's (`Chat.Messages timeZone`), else the browser's zone. `hueOf(id)` gives a palette hue stable per id for `Message.Author color` and the author's `Avatar`.
 
@@ -75,6 +76,7 @@ Content parts in short: `Message.Media` — a [Gallery](../gallery/COMPONENT.md)
 | `formatTime` | `(date: Date, timeZone?: string) => string` | «09:05» | Display of a `Date` time; gets the `timeZone` in force. |
 | `edited` | `boolean` | `false` | The text was edited: `labels.edited` before the time. |
 | `status` | `"sending" \| "sent" \| "read" \| "failed"` | — | Delivery of an outgoing message: a clock, one check, two checks (accent), or a danger mark; the glyphs cross-fade from one state to the next. Named for assistive tech by `labels`. |
+| `failureReason` | `ReactNode` | — | Why a `failed` message was not sent: a danger caption under the message that describes its row (`aria-describedby`). Shown only while `status` is `failed`; a retry in flight takes it away. |
 | `preview` | `boolean` | `false` | A picture of the message outside a chat (a bot's settings): no menu, reactions, retry or row focus, `Message.Actions` inert; links and players still work. |
 | `onRetry` | `() => void \| Promise<void>` | — | Sends a failed message again: a ghost danger button beside the bubble. A returned promise shows `sending` until it settles; a rejection leaves it failed. |
 | `onReactionToggle` | `(emoji: string) => void \| Promise<unknown>` | — | Puts or takes back the reader's reaction (a chip, a double tap, `L`, the reaction bar). Shown at once; a returned promise keeps it pending, a rejection drops it back. Without it reactions are read-only. |
@@ -127,11 +129,12 @@ Content parts in short: `Message.Media` — a [Gallery](../gallery/COMPONENT.md)
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "color" \| "onClick">` | — | `children` (the quoted text, one line), `className`. |
 
 ### Message.Text
-`ref` → `HTMLDivElement`. The text: a string renders the Markdown subset the Composer writes as elements, never as HTML (`plain` shows it as is). Marks the matches of the chat's search.
+`ref` → `HTMLDivElement`. The text: a string renders the Markdown subset the Composer writes as elements, never as HTML (`plain` shows it as is; with `entities` it is plain text those ranges format). Marks the matches of the chat's search.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `plain` | `boolean` | `false` | Render a string as is, without its Markdown. |
+| `entities` | `readonly TextEntity[]` | — | Formatted ranges of a messenger's text (`TextEntity`, see RichText): the string is then plain text — `**` in it stays text — and a range may start inside a word. |
+| `plain` | `boolean` | `false` | Render a string as is, without its Markdown or `entities`. |
 | `children` | `ReactNode` | — (required) | The text: a string renders its Markdown subset. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes. |
 
@@ -233,7 +236,7 @@ Content parts in short: `Message.Media` — a [Gallery](../gallery/COMPONENT.md)
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes. |
 
 ### Message.Actions
-`ref` → `HTMLDivElement`. A row of a bot's inline keyboard under the bubble: `Button.Root` keys (`soft` `neutral` by default) share one line equally, long labels ellipsize. A link key gets the link mark; a key whose `onClick` returns a promise loads until it settles.
+`ref` → `HTMLDivElement`. A bot's inline keyboard row under the bubble: `Button.Root` keys (`soft` `neutral` by default) share one line, long labels ellipsize. A link key gets a corner mark: ↗ out of the product, a window into it; a promise from `onClick` keeps a key loading.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -329,7 +332,7 @@ The list-level settings a message reads — the group chat's author header and a
 | status change | `status` | the ticks cross-fade and scale (`base`, `emphasized`), interruptible |
 | retrying | `onRetry` returns a promise | `sending` ticks and a `loading` retry button until it settles |
 | inline keyboard | `Message.Actions` children | `data-actions` on the message column: the rows under the bubble, the bubble at least as wide as them, no tail |
-| failed | `status="failed"` | `data-failed` on the row; danger mark, retry button |
+| failed | `status="failed"` | `data-failed` on the row; danger mark, retry button; with `failureReason` a danger caption under the message rises in (`partPresence`) and describes the row (`aria-describedby`); a retry in flight closes it up |
 | preview | `preview` | `data-preview` on the row, no `tabindex`; `inert` on every `Message.Actions` row |
 | sticker loading | `Message.Sticker` until its `src` is decoded, or while `loading` | `data-status="loading"`, `aria-busy`: a `Skeleton` covers the box, then fades out over the picture (`fade-base`); a `src` that fails shows the sticker's name, `data-status="error"` |
 | reaction toggled | a chip, a double tap, `L`, the reaction bar | the chip changes in place (never remounts) in the same frame: the fill is a color transition (`fast`); a reactor who joins fades and scales in from 0.9 while the stack widens (its width follows its circles), one who leaves the reverse; a count that only changes value rolls its digits and the chip does not move — its width follows the number of digits (tabular) and moves (`fast`) only when that changes; the reader (`Chat.Messages reader`) joins or leaves the avatar stack; while a returned promise runs `aria-busy`, `data-pending` — update `items` before it resolves; a rejection drops it back. Without `onReactionToggle` the chips are read-only and there is no reaction bar |
@@ -363,7 +366,7 @@ The list-level settings a message reads — the group chat's author header and a
 - `Message.Text` wraps anywhere; the meta stands at the end of its last line.
 - Round controls (download, cancel, retry, play) are a Button `shape="circle"`: hover, press, focus ring and the touch area follow the circle. A file's action is its round tile (48): the transfer disk (`internal/transferDisk`, `xl`) with its ring, the retry or the download stand on it — never a separate button beside the name. Every transfer, either way (media, file, video note, voice), is that one disk.
 - `Message.Typing` is the last row of a list; a chat puts it there itself (`Chat.Root typing`).
-- **A bot's inline keyboard** (`Message.Actions`): each part is a row under the bubble, `--prime-space-1` below it and between rows and keys, on the chat's own surface (outside the bubble's fill). The keyboard is as wide as the message: the column takes the wider of the bubble and the keyboard (up to the bubble's cap) and the bubble widens to it, so their edges line up. A row is one line, as in Telegram: its keys share it equally (`flex: 1 1 0`, each key `fullWidth`), and a label longer than its share ellipsizes. Keys keep the control radius; the last row's outer bottom corners take the bubble's (`--prime-message-radius`), so the keyboard closes the message. A key is `Button.Root` `variant="soft" tone="neutral"` at the host tier unless it sets its own: Telegram's button `style` maps onto `tone` — `primary` → `accent`, `success`, `danger` (`variant="solid"` for a filled key). A custom emoji before the label is a `Button.Icon`. A link key (`asChild` around an `<a href>`) carries the link mark (`action.externalLink`, `xs`) at its top-end corner, out of the label's flow. A callback key whose `onClick` returns a promise is `loading` until it settles: the spinner takes its leading icon's place or covers the label, the width never changes. A message with a keyboard has no tail: the keyboard closes it.
+- **A bot's inline keyboard** (`Message.Actions`): each part is a row under the bubble, `--prime-space-1` below it and between rows and keys, on the chat's own surface (outside the bubble's fill). The keyboard is as wide as the message: the column takes the wider of the bubble and the keyboard (up to the bubble's cap) and the bubble widens to it, so their edges line up. A row is one line, as in Telegram: its keys share it equally (`flex: 1 1 0`, each key `fullWidth`), and a label longer than its share ellipsizes. Keys keep the control radius; the last row's outer bottom corners take the bubble's (`--prime-message-radius`), so the keyboard closes the message. A key is `Button.Root` `variant="soft" tone="neutral"` at the host tier unless it sets its own: Telegram's button `style` maps onto `tone` — `primary` → `accent`, `success`, `danger` (`variant="solid"` for a filled key). A custom emoji before the label is a `Button.Icon`. A link key (`asChild` around an element with `href`, or a router link's `to`) carries one mark (`xs`) at its top-end corner, out of the label's flow, chosen by where the address leads, as Telegram tells a url key from a web app key: `action.externalLink` when it leaves the product (another origin, or another scheme — `mailto:`, `tel:`, an app link — which opens another program), `action.openApp` when it opens a page of the product (a relative path, a hash, an absolute address on this origin; on the server, without `location`, every address that is not absolute). A callback key whose `onClick` returns a promise is `loading` until it settles: the spinner takes its leading icon's place or covers the label, the width never changes. A message with a keyboard has no tail: the keyboard closes it.
 
 ## Accessibility
 
@@ -390,7 +393,7 @@ The list-level settings a message reads — the group chat's author header and a
 - Reactions are a group of buttons with `aria-pressed`; a chip is named «{emoji}: {count}», with `users` «{emoji} {count}: {users}» («❤️ 3: Анна, Пётр, Мария», «ещё N» when not everyone is listed); its avatars are `aria-hidden`; without `onReactionToggle` the chips are `disabled`. The reaction bar is a `toolbar` of toggle buttons named by the reaction («Нравится», «Огонь»…); its «⌄» is `aria-expanded`. The quick reaction is announced in the list's polite live region.
 - `VideoNote` and `VoicePlayer` carry their own ARIA (see their pages); inside a message their transcript is a plain paragraph, selectable and marked by the chat's search.
 - Media tiles are buttons «Открыть: {alt}» that open the album in MediaViewer, the focus returning to the tile on close; a transfer is the round cancel, retry or download button, the share its accessible description; a refused retry or cancel is announced politely; a done transfer's disk is `inert`.
-- `Message.Actions` are plain buttons and links (`Button.Root`, `asChild`) with visible labels, in row order; in a chat's selection mode they take no presses.
+- `Message.Actions` are plain buttons and links (`Button.Root`, `asChild`) with visible labels, in row order; the corner mark of a link key is decorative (`aria-hidden`), the link is named by its label; in a chat's selection mode they take no presses.
 - Color is never the only signal: the status is named, the own reaction is `aria-pressed`, a selected message is `aria-selected` with a check, the author is text.
 
 ### Labels
@@ -495,8 +498,8 @@ The list-level settings a message reads — the group chat's author header and a
 | [kinds.tsx](examples/kinds.tsx) | Every kind of message in its shell, both directions, single and in runs: text bubbles, pictures and circles as blocks, a caption bubble, voice, file, contact, place and link cards, reactions inside a bubble and under a picture — `Message.Media`, `VideoNote`, `Message.File`, `Message.Contact`, `Message.Location`, `Message.LinkPreview`, `VoicePlayer`. |
 | [author.tsx](examples/author.tsx) | A group chat's run of one author: the first message opens with the name in the author's hue, a crown and the member's tag, the last one shows the avatar in the gutter; another author with initials only, a long name that ellipsizes before its tag, a header on a pill over a photo, and your own reply — `Message.Author`, `tag`, `Message.AuthorIcon`, `Message.Avatar`, `position`, `hueOf`. |
 | [typing.tsx](examples/typing.tsx) | The typing signal: an incoming bubble of three dots that enters like a message and leaves closing its height; switch it, keep it mounted — `Message.Typing`, `open`. |
-| [status.tsx](examples/status.tsx) | Delivery of outgoing messages: a clock while sending, one check when sent, two when read, and a failed one with a retry that resolves after a second; the time comes as a date and reads to the second — `status`, `onRetry`, `formatTime`. |
-| [text-formatting.tsx](examples/text-formatting.tsx) | The Markdown the Composer writes, rendered safely: bold, italic, strike, code, a code block, links and a quote; long words and URLs wrap; a pasted error log stays as typed, its stars and underscores kept — `Message.Text`, `edited`, `plain`. |
+| [status.tsx](examples/status.tsx) | Delivery of outgoing messages: a clock while sending, one check when sent, two when read, and a failed one with its reason and a retry that resolves after a second; the time comes as a date and reads to the second — `status`, `failureReason`, `onRetry`, `formatTime`. |
+| [text-formatting.tsx](examples/text-formatting.tsx) | The Markdown the Composer writes, rendered safely: bold, italic, underline, strike, code, a code block, links and a quote; long words and URLs wrap; a messenger's text comes with its entities, its stars kept; a pasted error log stays as typed — `Message.Text`, `entities`, `edited`, `plain`. |
 | [reactions.tsx](examples/reactions.tsx) | Reactions under a message: each chip shows who reacted — up to three avatars, from four on two and «+N» — and a press on a chip, or a double tap on the message, puts or takes back your own at once while the request runs behind it — `Message.Reactions`, `users`, `onReactionToggle`. |
 | [context-menu.tsx](examples/context-menu.tsx) | Long press: the reaction bar above the message and its menu below — a right click opens the menu, a long hover only the bar, `R` and Shift+F10 from the keyboard — `Message.Menu`, `onReactionToggle`. |
 | [media.tsx](examples/media.tsx) | Captions under a photo, a tall portrait, an album and a video, each as wide as its media; an album with a video laid out as tiles, an outgoing album with neutral gaps and a photo still uploading with its ring and cancel; a tile opens the album in the viewer — `Message.Media`, `items`, `onCancel`. |
@@ -506,7 +509,7 @@ The list-level settings a message reads — the group chat's author header and a
 | [location.tsx](examples/location.tsx) | A place on a map picture from your map service with a pin, the place and its address, and a live location of a courier on its way — `Message.Location`, `href`, `live`. |
 | [contact.tsx](examples/contact.tsx) | A shared contact: initials or a photo, name and phone, with the actions to write or save — `Message.Contact`, `phone`. |
 | [link-preview.tsx](examples/link-preview.tsx) | A message with a link and the card of the page under it: site, title, description and picture — `Message.LinkPreview`, `site`, `image`. |
-| [bot-actions.tsx](examples/bot-actions.tsx) | A bot's message with an inline keyboard: one-line rows whose keys share the row equally, a coloured key with an icon that loads while its promise runs, a link with its mark — `Message.Actions`, `tone`, `Button.Icon`, `asChild`. |
+| [bot-actions.tsx](examples/bot-actions.tsx) | A bot's message with an inline keyboard: one-line rows whose keys share the row equally, a coloured key with an icon that loads while its promise runs, links marked by where they lead: a page of the product or another site — `Message.Actions`, `tone`, `Button.Icon`, `asChild`. |
 | [sticker.tsx](examples/sticker.tsx) | Stickers in a conversation: a picture by its address and a video sticker in your own player, no bubble, the time on a pill over the corner — `Message.Sticker`, `src`, `loading`. |
 | [preview.tsx](examples/preview.tsx) | A bot's welcome message as its settings page shows it: the same bubble with its keyboard, nothing in it pressed or opened, the time in the zone of the profile — `preview`, `timeZone`. |
 | [narrow.tsx](examples/narrow.tsx) | At phone width bubbles take up to 85% of the chat, long words and links wrap inside, an album keeps its rows — `Message.Root`, `Message.Media`. |
@@ -518,6 +521,8 @@ The list-level settings a message reads — the group chat's author header and a
 - An author's role written into the name («Олег (админ)») → `tag`; a crown or a badge drawn next to the name → `Message.AuthorIcon`.
 - Colors of authors picked at random on every render → `hueOf(user.id)`: one hue per person, stable everywhere.
 - Rendering message HTML (`dangerouslySetInnerHTML`) → pass the string to `Message.Text`; its Markdown subset renders as elements.
+- Converting a messenger's entities to Markdown, or showing its text `plain` because it may hold `**` → `Message.Text entities`.
+- The reason of a failed send in a Banner or a toast → `failureReason` under the message itself.
 - A status that flips without a transition, or a custom ✓ glyph → `status`.
 - Waiting for the server before showing a reaction → return the promise from `onReactionToggle`: the chip shows the new state at once and drops it back on a rejection.
 - Avatars of reactors drawn next to the chip, or a count where names are known → pass `users` (in the order they reacted) and `Chat.Messages reader`.
@@ -532,7 +537,8 @@ The list-level settings a message reads — the group chat's author header and a
 - A transcript as a separate `Message.Text`, or a height animation of your own around it → `transcript` / `onTranscribe` on `VoicePlayer` and `VideoNote`: the text opens inside the same message, in one stroke with its height.
 - A list, dates, search or selection built around messages → [Chat](../chat/COMPONENT.md).
 - A bot's buttons placed inside `Message.Text`, or a row of buttons of your own under a message → `Message.Actions` with `Button.Root` children: one row per part, at the message's width.
+- An arrow icon of your own in a link key (`Button.Icon` with `action.externalLink`) → leave the label alone: `Message.Actions` draws the key's one corner mark itself, ↗ for another site and a window for a page of the product; a second arrow doubles it.
 
 ## Related
-- **Built from:** [Dropdown](../dropdown/COMPONENT.md) (`Message.Menu`), [ScrollContainer](../scroll-container/COMPONENT.md) (the floating panel of the reaction bar), [Gallery](../gallery/COMPONENT.md) (`Message.Media`), [Avatar](../avatar/COMPONENT.md) (`Avatar.Group` + `Avatar.Overflow` in reaction chips), [Badge](../badge/COMPONENT.md) (the «Трансляция» mark of a live location), [Thumbnail](../thumbnail/COMPONENT.md) (the map, the link preview picture, a file's preview), [Button](../button/COMPONENT.md) (retry, the transfer disk, `shape="circle"`, the buttons of `Message.Actions`), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in selection mode), [Spinner](../spinner/COMPONENT.md) (pending transfers and transcripts), [Skeleton](../skeleton/COMPONENT.md) (a sticker while it loads), Icon (status ticks, file glyphs, `action.forward`, `action.refresh`, `action.externalLink` — the link mark of a key); `internal/messagePart` (the contract of content parts), `internal/messageList` (the contract with a chat's list), `internal/palette` (`hueOf`), `internal/Disclosure` (the reactions row, transcripts), `bubbleMorph` (every size change as one stroke), `bubbleHug` (a bubble of text as wide as its widest line), `internal/transferDisk` (the transfer of a file), `internal/mediaPill` (the meta, the author's pill), `internal/HighlightMatch` (search marks), `internal/richText` (Markdown), [VisuallyHidden](../visually-hidden/COMPONENT.md)
+- **Built from:** [Dropdown](../dropdown/COMPONENT.md) (`Message.Menu`), [ScrollContainer](../scroll-container/COMPONENT.md) (the floating panel of the reaction bar), [Gallery](../gallery/COMPONENT.md) (`Message.Media`), [Avatar](../avatar/COMPONENT.md) (`Avatar.Group` + `Avatar.Overflow` in reaction chips), [Badge](../badge/COMPONENT.md) (the «Трансляция» mark of a live location), [Thumbnail](../thumbnail/COMPONENT.md) (the map, the link preview picture, a file's preview), [Button](../button/COMPONENT.md) (retry, the transfer disk, `shape="circle"`, the buttons of `Message.Actions`), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in selection mode), [Spinner](../spinner/COMPONENT.md) (pending transfers and transcripts), [Skeleton](../skeleton/COMPONENT.md) (a sticker while it loads), Icon (status ticks, file glyphs, `action.forward`, `action.refresh`, `action.externalLink` and `action.openApp` — the marks of a link key); `internal/messagePart` (the contract of content parts), `internal/messageList` (the contract with a chat's list), `internal/palette` (`hueOf`), `internal/Disclosure` (the reactions row, transcripts), `bubbleMorph` (every size change as one stroke), `bubbleHug` (a bubble of text as wide as its widest line), `internal/transferDisk` (the transfer of a file), `internal/mediaPill` (the meta, the author's pill), `internal/HighlightMatch` (search marks), `internal/richText` (Markdown and entities), `internal/partPresence` (the failure reason), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Chat](../chat/COMPONENT.md) — the conversation the messages stand in; [Gallery](../gallery/COMPONENT.md) — the album of `Message.Media`; [VideoNote](../video-note/COMPONENT.md) — the round video message; [VoicePlayer](../voice-player/COMPONENT.md) — the content of a voice message; [Composer](../composer/COMPONENT.md) — the input under the list; [RichText](../rich-text/COMPONENT.md) — the text of `Message.Text` outside a message; [Timeline](../timeline/COMPONENT.md)

package/dist/skill/reference/components/message/examples/bot-actions.tsx

@@ -1,10 +1,11 @@
-/** A bot's message with an inline keyboard: one-line rows whose keys share the row equally, a coloured key with an icon that loads while its promise runs, a link with its mark — `Message.Actions`, `tone`, `Button.Icon`, `asChild`. */
+/** A bot's message with an inline keyboard: one-line rows whose keys share the row equally, a coloured key with an icon that loads while its promise runs, links marked by where they lead: a page of the product or another site — `Message.Actions`, `tone`, `Button.Icon`, `asChild`. */
 import { Button, Icon, Message } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 const INVOICE_URL = "https://vector.example/invoices/4821";
+const CATALOG_PATH = "#catalog";
 const CONFIRM_DELAY_MS = 1200;
 
 export default function MessageBotActionsExample() {
@@ -58,9 +59,12 @@ export default function MessageBotActionsExample() {
           </Message.Actions>
         ) : null}
         <Message.Actions>
+          <Button.Root asChild>
+            <a href={CATALOG_PATH}>Каталог</a>
+          </Button.Root>
           <Button.Root asChild>
             <a href={INVOICE_URL} target="_blank" rel="noreferrer">
-              Открыть счёт
+              Счёт
             </a>
           </Button.Root>
         </Message.Actions>