prime-ui-kit 0.21.1 → 0.21.3

package/src/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/src/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/src/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>

package/src/components/message/examples/status.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** 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`. */
 import { Message, type MessageStatus } from "prime-ui-kit";
 import * as React from "react";
 
@@ -54,6 +54,7 @@ export default function MessageStatusExample() {
         time={SECOND_AT}
         formatTime={formatSeconds}
         status={failed ? "failed" : "sent"}
+        failureReason="Клиент заблокировал бота — сообщение не доставлено"
         onRetry={retry}
       >
         <Message.Text>Подпишите, пожалуйста, до пятницы.</Message.Text>

package/src/components/message/examples/text-formatting.tsx

@@ -1,16 +1,23 @@
-/** 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`. */
-import { Message } from "prime-ui-kit";
+/** 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`. */
+import { Message, type TextEntity } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
 const RELEASE = `**Релиз 2.4** готов к выкатке.
-Изменения: _экспорт счетов_, ~~старый отчёт~~ удалён, флаг \`invoices.v2\`.
+Изменения: _экспорт счетов_, __новый акт__, ~~старый отчёт~~ удалён, флаг \`invoices.v2\`.
 > Миграцию запускать только после бэкапа.
 \`\`\`
 bun run migrate --env=prod
 \`\`\`
 Чеклист: https://prime.app/wiki/release-2-4`;
 
+/** A Telegram message as its API sends it: plain text and its formatted ranges. */
+const TELEGRAM_TEXT = "Оплатил счёт PR-204. В поле **ИНН** звёздочки — так в выписке банка.";
+const TELEGRAM_ENTITIES: TextEntity[] = [
+  { type: "bold", offset: 0, length: 7 },
+  { type: "code", offset: 13, length: 6 },
+];
+
 /** An error copied from the 1C log: its stars and underscores are data, not markup. */
 const ERROR_LOG = "ERR_EXPORT_1C: поле *ИНН* пусто (counterparty_id=4_12_1)";
 
@@ -25,6 +32,9 @@ export default function MessageTextFormattingExample() {
           Принято, запускаю после бэкапа. Отчёт положу в [задачу](https://prime.app/t/PRJ-430).
         </Message.Text>
       </Message.Root>
+      <Message.Root direction="incoming" time="16:10">
+        <Message.Text entities={TELEGRAM_ENTITIES}>{TELEGRAM_TEXT}</Message.Text>
+      </Message.Root>
       <Message.Root direction="incoming" time="16:12">
         <Message.Text plain>{ERROR_LOG}</Message.Text>
       </Message.Root>

package/src/components/modal/COMPONENT.md

@@ -32,7 +32,7 @@ Modal.Root                    state and dismiss policy (no DOM)
     │   ├── Modal.Icon        40 tile with a tone fill; the record's Avatar / Thumbnail with no tile, 40
     │   ├── Modal.Title       line 1: <h2>, names the dialog; `loading` holds it with a skeleton
     │   ├── Modal.Description line 2: <p>, describes the dialog; status Badges lead it (tier s)
-    │   └── Modal.Actions     buttons only (icon buttons, a ⋯ Dropdown), tier s, on the title's line
+    │   └── Modal.Actions     one tab-wide switcher, then buttons (icon buttons, a ⋯ Dropdown), tier s, on the title's line
     ├── Modal.Body            the only scrolling zone
     │   └── Modal.Section     <section>: <h3> label, description, Modal.Actions at the heading's end
     └── Modal.Footer          actions, primary last
@@ -85,7 +85,7 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other attributes of the `<header>`. |
 
 ### Modal.Actions
-`ref` → `HTMLDivElement`. Header buttons only (icon buttons, a ⋯ Dropdown; a status goes in `Modal.Description`), tier `s`, on the title's line; under it below 12rem; at the end of a `Modal.Section` heading. In `Modal.Footer`: the start group at the footer tier.
+`ref` → `HTMLDivElement`. Header: a tab-wide switcher (`SegmentedControl`, `Datepicker`), then buttons (a status goes in `Modal.Description`), tier `s`; under the title below 12rem; at the end of a `Modal.Section` heading. In `Modal.Footer`: the start group at the footer tier.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -245,13 +245,13 @@ Motion (`overlayMotion`): the scrim fades in and out over `base`; the dialog fad
 ## Layout & spacing
 - The header has one anatomy, the same in every modal, drawer and sheet:
   ```
-  [mark]  Title                                [icon buttons] [⋯] [×]
+  [mark]  Title                                [tab switcher] [icon buttons] [⋯] [×]
           [status badges] description text
   ```
   - mark — `Modal.Icon`: a glyph on the tone tile, or the record's picture (`Avatar.Root`, `Thumbnail.Root`, also inside your own wrapper component) with no tile; both are 40 px.
   - line 1 — `Modal.Title`; `loading` holds it with a Skeleton while the name loads.
   - line 2 — `Modal.Description`: the record's statuses as `Badge.Root`s first, then the text. The kit sizes the badges (chip tier `s`, the line's 20 px), keeps them first and one gap apart, and wraps the text under them on a narrow panel.
-  - end — `Modal.Actions`: only buttons — ghost icon buttons with a Tooltip and a ⋯ Dropdown — at the close button's tier, centred on the title's line; a status never goes here.
+  - end — `Modal.Actions`: first one switcher for the whole open tab (a `SegmentedControl`, a `Datepicker` period), then the buttons — ghost icon buttons with a Tooltip and a ⋯ Dropdown — at the close button's tier, centred on the title's line; a status never goes here. A control rendered only on some tabs rises in and closes up in its own cell.
 - An action apart from the main pair («Удалить» of a record, «Выйти»): `Modal.Actions` inside `Modal.Footer` puts it at the start, at the footer's tier; stacked on a phone it comes first and the primary stays last.
 - Dialog padding `--prime-modal-padding` (24) on every zone; header 24 top / 20 bottom, body 20 with a 16 gap between blocks, footer 20 top / 24 bottom.
 - Max height = viewport minus `--prime-modal-viewport-padding` on both sides; only the body scrolls.
@@ -317,6 +317,7 @@ Motion (`overlayMotion`): the scrim fades in and out over `base`; the dialog fad
 - Busy or unsaved state lifted out of the form into Root props → put `Modal.Guard` next to the form, inside Content.
 - `key` or a conditional around `Modal.Root` to reset a form → the dialog unmounts at once, without its exit; keep the Root mounted and drive `open`.
 - A status `Badge` in the header's `Modal.Actions`, beside the buttons → put it in `Modal.Description`, before the text: the kit sizes it to the line and keeps it first.
+- A control that applies to the whole tab (the text language, the period) repeated in section headings or put in one section → one switcher in the header's `Modal.Actions`, before the buttons, rendered only on the tabs it applies to.
 - A Badge with its own `size` in `Modal.Description` → leave `size` out: the line gives every header the same chip tier.
 - A `Skeleton` placed by hand in `Modal.Title` or `Modal.Description` → their `loading`.
 - A start-side button («Выйти», «Удалить») put inside `Modal.Meta` → `Modal.Actions` inside `Modal.Footer`; `Meta` is status text only.

package/src/components/rich-text/COMPONENT.md

@@ -3,11 +3,13 @@
 **Category:** data-display
 **Kind:** primitive
 
-> Text in the chat's Markdown subset outside a message — a bot's welcome text, a template, a comment — rendered as elements, never as HTML.
+> Text in the chat's Markdown subset — or a messenger's plain text with its entities — outside a message (a bot's welcome text, a template, a comment), rendered as elements, never as HTML.
 
 ## When to use
 - A text written with the formatting toolbar of `Composer` or `Textarea formatting` is shown somewhere other than a chat: a bot's settings, a template list, a card.
 - Text from users or bots that may carry `**bold**`, links or a `||spoiler||` and must be rendered safely.
+- A text stored as a messenger sends it — plain text and formatted ranges (Telegram `entities`, VK `format_data`) → `entities`: the text is never read as Markdown, so `**` in it stays text and a range may start inside a word.
+- Moving between the two forms: `getTextEntities(source)` turns a Composer message into `{ text, entities }` for the messenger's API; `getRichTextSource({ text, entities })` turns a stored text back into Markdown for the editor, escaping what would read as markup (`\*`).
 
 ## When not to use
 - The text of a chat message → [Message](../message/COMPONENT.md) `Message.Text` (it marks search matches and holds the meta's room).
@@ -17,13 +19,13 @@
 
 ## Import
 ```tsx
-import { RichText } from "prime-ui-kit";
+import { getRichTextSource, getTextEntities, RichText, type TextEntity } from "prime-ui-kit";
 ```
 
 ## Anatomy
 ```
-RichText         <div>; the source as children
-├─ <p>           a run of text, line breaks kept
+RichText         <div>; the source (or the plain text of `entities`) as children
+├─ <p>           a run of text, line breaks kept; <strong> <em> <u> <s> <code> <a> inside
 ├─ <blockquote>  lines starting with "> "
 └─ <pre>         fenced code
 ```
@@ -37,17 +39,51 @@ RichText         <div>; the source as children
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `string` | — (required) | The source: `**bold**`, `_italic_`, `~~strike~~`, `\|\|spoiler\|\|`, inline and fenced code, links (`[label]` then the address in parentheses), bare URLs, `> ` quotes; line breaks are kept. |
+| `children` | `string` | — (required) | The Markdown subset (`**`, `_`, `__`, `~~`, `\|\|`, code, links, `> ` quotes; `\*` escapes a mark), or with `entities` the plain text they format. |
+| `entities` | `readonly TextEntity[]` | — | The formatted ranges of a messenger's text (Telegram, VK): `children` is then plain text, never read as Markdown, and a range may start inside a word. Bare URLs in it still link. |
 | `labels` | `Partial<RichTextLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `id`, `data-*` and the other div attributes. |
 
+### Types
+
+#### `TextEntity`
+One formatted range of a plain text, as messengers send it (Telegram `MessageEntity`, VK `format_data`): map their type names onto these.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `type` | `"bold" \| "italic" \| "underline" \| "strikethrough" \| "spoiler" \| "code" \| "pre" \| "link" \| "quote"` | — (required) | The format; `pre` and `quote` are blocks (the line breaks at their edges are theirs). A type the kit does not know shows its text. |
+| `offset` | `number` | — (required) | Start in UTF-16 code units (a JS string index, as in Telegram). |
+| `length` | `number` | — (required) | Length in UTF-16 code units; ranges nest and may cross (a crossing one is cut). |
+| `url` | `string` | — | The address of a `link`; without it the range itself is the address. Only http(s), `mailto:` and `tel:` link. |
+| `language` | `string` | — | The language of a `pre` block, kept through the conversions. |
+
+#### `FormattedText`
+A plain text with its formatted ranges: what a messenger sends and takes.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `text` | `string` | — (required) | The plain text. |
+| `entities` | `TextEntity[]` | — (required) | Its formatted ranges. |
+
+### Functions
+
+#### `getTextEntities(source)`
+`(source: string) => FormattedText`
+
+The plain `text` and `entities` of a Markdown source — what a messenger's API takes from a Composer message. Bare URLs make no entity (the messenger links them).
+
+#### `getRichTextSource(value)`
+`(value: FormattedText) => string`
+
+The Markdown source of `{ text, entities }` — to edit a received or stored text in Composer or `Textarea formatting`. Text that would read as markup is escaped (`\*`); an italic or underline inside a word, which the subset cannot hold, is dropped and its text kept.
+
 ## Variants
 One look: the type of its host. Wrap it in `Typography as="div"` to pick a text role.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| masked spoiler | `\|\|text\|\|` in `children` | `role="button"`, `data-state="masked"`: a wash over transparent words |
+| masked spoiler | `\|\|text\|\|` in `children`, or a `spoiler` entity | `role="button"`, `data-state="masked"`: a wash over transparent words |
 | revealed spoiler | a press, `Enter` or `Space` | `data-state="revealed"`: the wash and the words cross-fade on the fade clock; one way, like a chat |
 
 ## Layout & spacing
@@ -82,12 +118,14 @@ One look: the type of its host. Wrap it in `Typography as="div"` to pick a text
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | The welcome text of a support bot shown outside the chat: bold, a link, a quote, code and a spoiler from the chat's Markdown — `children`. |
+| [entities.tsx](examples/entities.tsx) | A bot's greeting stored as a messenger sends it — plain text with formatted ranges — shown with its stars kept as text — `entities`. |
 
 ## Mistakes
 - `dangerouslySetInnerHTML` with a Markdown library for a chat text → `RichText`: the same subset as the chat, never HTML.
 - A `Message.Root` with no time and no author only to render formatted text → `RichText`.
 - Sizing the text with a class on `RichText` → put it inside the host that sets the type.
+- Converting a messenger's entities to Markdown by hand, or showing a text `plain` because it may hold `**` → `entities`; for the editor, `getRichTextSource`.
 
 ## Related
-- **Built from:** `internal/richText` (the parser and the elements, shared with `Message.Text`)
+- **Built from:** `internal/richText` (the Markdown parser, the entities, the conversions and the elements, shared with `Message.Text`)
 - **See also:** [Message](../message/COMPONENT.md), [Composer](../composer/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Typography](../typography/COMPONENT.md)

package/src/components/rich-text/examples/entities.tsx

@@ -0,0 +1,20 @@
+/** A bot's greeting stored as a messenger sends it — plain text with formatted ranges — shown with its stars kept as text — `entities`. */
+import { Card, RichText, type TextEntity } from "prime-ui-kit";
+
+const GREETING = "Здравствуйте! Счета — в личном кабинете. Поле *ИНН* обязательно.";
+
+const GREETING_ENTITIES: TextEntity[] = [
+  { type: "bold", offset: 0, length: 13 },
+  { type: "link", offset: 24, length: 15, url: "https://prime.app/billing" },
+  { type: "underline", offset: 52, length: 11 },
+];
+
+export default function RichTextEntitiesExample() {
+  return (
+    <Card.Root>
+      <Card.Body>
+        <RichText entities={GREETING_ENTITIES}>{GREETING}</RichText>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/scroll-container/COMPONENT.md

@@ -48,7 +48,7 @@ ScrollContainer   <div> (or the `as` tag); thin scrollbar, soft hidden edges
 | `anchor` | `"start" \| "end"` | `"start"` | `end` — a chat or a log: opens at the end and follows new content while the person is at the end; scrolled away, the view holds still. |
 | `onReachStart` | `() => void \| Promise<void>` | — | Fires within 120 px of the start, once per approach: load older content. A returned promise blocks repeats and sets `aria-busy`; content added above keeps the view. |
 | `onReachEnd` | `() => void \| Promise<void>` | — | The scroll position came within 120 px of the end: load the next page. Same once-per-approach and promise rules as `onReachStart`. |
-| `overscrollBehavior` | `"auto" \| "contain" \| "none"` | `"contain"` | CSS `overscroll-behavior` along the region's own axes; `contain` stops scroll chaining into the page, a scroll across them still reaches the region around. |
+| `overscrollBehavior` | `"auto" \| "contain" \| "none"` | `"auto"` | At the region's end: `auto` hands the scroll on to the page (sideways it stops); `contain` / `none` hold both axes — an open layer, where the page behind must not move. |
 | `as` | `"div" \| "main" \| "aside" \| "section" \| "nav" \| "article" \| "pre"` | `"div"` | Root element; a landmark tag when the region is one, `pre` for preformatted text (CodeBlock). |
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` (height, padding), `aria-label`, `tabIndex`, `role`, event handlers and the other attributes. |
 
@@ -64,9 +64,9 @@ ScrollContainer   <div> (or the `as` tag); thin scrollbar, soft hidden edges
 ### overscrollBehavior
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `contain` | Reaching the end does not scroll the page behind | Nested panels, lists inside a page | yes |
-| `auto` | Browser default: scroll chains to the parent | The region is the page's main scroller and should hand off | |
-| `none` | No chaining and no overscroll glow / bounce | Full-screen app regions | |
+| `auto` | At its end up or down the scroll goes on to the page (or the region around); a region that does not scroll never holds the wheel. Sideways it stops without a bounce: a page never scrolls sideways, and a sideways chain would swipe the browser's history | every region on a page: lists, tables, boards, chats, code | yes |
+| `contain` | Reaching the end on either axis does not scroll what is behind | an open layer — Modal / Drawer / Sheet body, a floating panel, the CommandMenu list set it themselves; a panel of your own that floats over the page | |
+| `none` | `contain` without the overscroll glow / bounce | a full-screen layer of your own | |
 
 ### edges
 | Value | Looks like | Use when | Default |
@@ -165,7 +165,7 @@ No `labels`.
 | [snap.tsx](examples/snap.tsx) | A strip of warehouse cards that always comes to rest on a card's start, scrolled by touch, a trackpad or the mouse wheel — `snap`, `axis`. |
 | [lock.tsx](examples/lock.tsx) | While an order is opened for review, the queue behind it holds still: no wheel, touch, key or drag moves it — `lock`. |
 | [auto-scroll.tsx](examples/auto-scroll.tsx) | A task dragged to the top or bottom edge of a scrolling list scrolls it, faster the closer it comes — `ScrollContainer`, `Dnd.Sortable`. |
-| [overscroll.tsx](examples/overscroll.tsx) | At the end of the list the scroll passes on to the page instead of stopping — `overscrollBehavior`. |
+| [overscroll.tsx](examples/overscroll.tsx) | A panel that keeps its scroll: at the end of the list the page behind stays put — `overscrollBehavior`. |
 | [log.tsx](examples/log.tsx) | A live exchange log pinned to its last entry: a new entry keeps it at the end, scrolling up loads older ones without moving what is on screen — `anchor`, `onReachStart`. |
 | [load-more.tsx](examples/load-more.tsx) | An order log that loads the next page as the reader nears its end, with loading lines in the rows' place — `onReachEnd`. |
 

package/src/components/scroll-container/examples/overscroll.tsx

@@ -1,4 +1,4 @@
-/** At the end of the list the scroll passes on to the page instead of stopping — `overscrollBehavior`. */
+/** A panel that keeps its scroll: at the end of the list the page behind stays put — `overscrollBehavior`. */
 import { Card, ScrollContainer, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -11,7 +11,7 @@ export default function ScrollContainerOverscrollExample() {
       <Card.Header>
         <Card.Title>Журнал выгрузок</Card.Title>
       </Card.Header>
-      <ScrollContainer overscrollBehavior="auto" tabIndex={0} aria-label="Журнал выгрузок">
+      <ScrollContainer overscrollBehavior="contain" tabIndex={0} aria-label="Журнал выгрузок">
         <Card.List>
           {HOURS.map((hour) => (
             <Card.ListItem key={hour}>

package/src/components/select/COMPONENT.md

@@ -224,7 +224,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | load error | `loadError` | the list is `hidden`; a compact EmptyPage with `role="alert"` and a retry Button (`onRetry`) |
 | state swap | loading ↔ items ↔ load error | the new content fades in (`swapMotion`), the first render stays still |
 | searching | typing in the search | panel `data-searching="true"`; groups without matches and separators hide; the match in an option's title, description and plain text is a `<mark>` in `accent-text` (not in the trigger); the query clears when the list closes (`onSearchChange("")`) |
-| nothing to show | no option matches (and not loading) | a compact EmptyPage with `role="status"`: `labels.empty`, plus `labels.emptyHint` while a query is typed; a `Select.Action` stays under it, highlighted |
+| nothing to show | no option matches (and not loading) | a compact EmptyPage with `role="status"`: `labels.empty` alone; a `Select.Action` stays under it, highlighted |
 | sheet | viewport below 640px | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the panel; the sheet carries `data-state`, the panel keeps its role and ref; page scroll locked; a swipe down from the handle closes it |
 | segment | inside `Input.Wrapper` | no frame (label, hint, error, support row): the root is `data-field-segment`, the trigger `data-segment="true"` — a tinted section flush with the box's start edge, a stronger fill on hover and while open, an inset focus ring; named «`aria-label`: value» |
 | option highlighted / selected / disabled | keyboard and pointer / value / `disabled` | `data-highlighted`, `data-selected` + `aria-selected`, `data-disabled` + `aria-disabled`; highlight is a fill only |
@@ -312,7 +312,6 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 |---|---|---|
 | `search` | `"Поиск"` | Placeholder and accessible name of the search field. |
 | `empty` | `"Ничего не найдено"` | Empty state: no items or nothing matches. |
-| `emptyHint` | `"Попробуйте изменить запрос"` | Second line of the empty state while searching; `""` hides it. |
 | `loading` | `"Загрузка…"` | Announced while `loading` or `loadingMore`. |
 | `retry` | `"Повторить"` | The retry button under `loadError` (`onRetry`). |
 | `clear` | `"Очистить"` | Tooltip of the clear segment. |

package/src/components/sheet/COMPONENT.md

@@ -32,7 +32,7 @@ Sheet.Root                     state and dismiss policy (no DOM)
    │  ├─ Sheet.Icon            tone tile around an Icon, or the record's Avatar / Thumbnail, no tile, 40
    │  ├─ Sheet.Title           line 1: <h2>; `loading` holds it with a skeleton
    │  ├─ Sheet.Description     line 2: <p>; the record's status Badges lead it (tier s), then the text
-   │  └─ Sheet.Actions         buttons only (icon buttons, a ⋯ Dropdown), tier s, on the title's line
+   │  └─ Sheet.Actions         one tab-wide switcher, then buttons (icon buttons, a ⋯ Dropdown), tier s, on the title's line
    ├─ Sheet.Body               the content; the only scrolling zone (ScrollContainer)
    └─ Sheet.Footer             optional: only for a form with an explicit submit
       ├─ Sheet.Actions         the start group: an action apart from the main pair
@@ -78,7 +78,7 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other attributes of the `<header>`. |
 
 ### Sheet.Actions
-`ref` → `HTMLDivElement`. Header buttons only (icon buttons, a ⋯ Dropdown; a status goes in `Sheet.Description`), tier `s`, on the title's line; under it below 12rem. In `Sheet.Footer`: the start group at the footer tier.
+`ref` → `HTMLDivElement`. Header: a tab-wide switcher (`SegmentedControl`, `Datepicker`), then buttons (a status goes in `Sheet.Description`), tier `s`; under the title below 12rem. In `Sheet.Footer`: the start group at the footer tier.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -190,13 +190,13 @@ Motion: the scrim fades, the sheet slides up over `slow` and down over `base` (`
   - **The header is optional.** Keep it when the content needs a title to be understood (a list of actions on «Заказ № 1042»). Drop it — and with it the × and the hairline — when the content speaks for itself (a calendar opened from a «Дата отгрузки» button): name the sheet with `aria-label` on `Sheet.Content`.
 - The header has one anatomy, the same in every modal, drawer and sheet:
   ```
-  [mark]  Title                                [icon buttons] [⋯] [×]
+  [mark]  Title                                [tab switcher] [icon buttons] [⋯] [×]
           [status badges] description text
   ```
   - mark — `Sheet.Icon`: a glyph on the tone tile, or the record's picture (`Avatar.Root`, `Thumbnail.Root`, also inside your own wrapper component) with no tile; both are 40 px.
   - line 1 — `Sheet.Title`; `loading` holds it with a Skeleton while the name loads.
   - line 2 — `Sheet.Description`: the record's statuses as `Badge.Root`s first, then the text. The kit sizes the badges (chip tier `s`, the line's 20 px), keeps them first and one gap apart, and wraps the text under them on a narrow panel.
-  - end — `Sheet.Actions`: only buttons — ghost icon buttons with a Tooltip and a ⋯ Dropdown — at the close button's tier, centred on the title's line; a status never goes here.
+  - end — `Sheet.Actions`: first one switcher for the whole open tab (a `SegmentedControl`, a `Datepicker` period), then the buttons — ghost icon buttons with a Tooltip and a ⋯ Dropdown — at the close button's tier, centred on the title's line; a status never goes here. A control rendered only on some tabs rises in and closes up in its own cell.
 - A form's action apart from its submit pair: `Sheet.Actions` inside `Sheet.Footer` puts it at the start, at the footer's tier; stacked on a phone it comes first and the primary stays last.
 - The content is the sheet's own, across its width: `Datepicker.Panel` or a column of actions straight in `Sheet.Body` — never a Card or a padded box inside it.
 - Zone padding `--prime-sheet-padding`, width `--prime-sheet-width`. The bottom-sheet surface (`src/internal/sheet.module.css`, shared with a Modal and the floating layers on a phone) gives the height by content up to the top gap, the rounded top, the handle strip and the bottom safe-area inset below the content.
@@ -259,6 +259,7 @@ Motion: the scrim fades, the sheet slides up over `slow` and down over `base` (`
 - A header with only a title over a calendar or a list that already says what it is → drop the header and name the sheet with `aria-label`.
 - No header and no `aria-label` → the dialog has no name; give `Sheet.Content` an `aria-label`.
 - A status `Badge` in the header's `Sheet.Actions`, beside the buttons → put it in `Sheet.Description`, before the text: the kit sizes it to the line and keeps it first.
+- A control that applies to the whole tab (the text language, the period) repeated in section headings or put in one section → one switcher in the header's `Sheet.Actions`, before the buttons, rendered only on the tabs it applies to.
 - A Badge with its own `size` in `Sheet.Description` → leave `size` out: the line gives every header the same chip tier.
 - A `Skeleton` placed by hand in `Sheet.Title` or `Sheet.Description` → their `loading`.
 - A start-side button («Выйти», «Удалить») put inside `Sheet.Meta` → `Sheet.Actions` inside `Sheet.Footer`; `Meta` is status text only.