prime-ui-kit 0.17.0 → 0.19.0

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

@@ -1,15 +1,39 @@
-/** Funnel stages in the team's order: a stage moves by its handle or Alt+arrows and is saved on the server — `onReorder`, `value`. */
-import { Card, List, moveBefore } from "prime-ui-kit";
+/** 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`. */
+import { Card, List, moveBefore, Switch } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 const STAGES = [
-  { id: "lead", name: "Новый лид", description: "Заявка с сайта или от партнёра", deals: 42 },
-  { id: "qualified", name: "Квалификация", description: "Бюджет и сроки подтверждены", deals: 18 },
-  { id: "proposal", name: "Коммерческое предложение", description: "КП отправлено", deals: 11 },
-  { id: "contract", name: "Договор", description: "Согласование с юристами", deals: 6 },
-  { id: "won", name: "Оплата", description: "Счёт выставлен", deals: 3 },
+  {
+    id: "lead",
+    name: "Новый лид",
+    description: "Заявка с сайта или от партнёра",
+    deals: 42,
+    shown: true,
+  },
+  {
+    id: "qualified",
+    name: "Квалификация",
+    description: "Бюджет и сроки подтверждены",
+    deals: 18,
+    shown: true,
+  },
+  {
+    id: "proposal",
+    name: "Коммерческое предложение",
+    description: "КП отправлено",
+    deals: 11,
+    shown: true,
+  },
+  {
+    id: "contract",
+    name: "Договор",
+    description: "Согласование с юристами",
+    deals: 6,
+    shown: true,
+  },
+  { id: "won", name: "Оплата", description: "Счёт выставлен", deals: 3, shown: false },
 ];
 
 const SAVE_DELAY_MS = 600;
@@ -36,6 +60,17 @@ export default function ListReorderExample() {
         >
           {stages.map((stage) => (
             <List.Item key={stage.id} value={stage.id}>
+              <List.ItemActions side="start">
+                <Switch.Root
+                  aria-label={`Показывать «${stage.name}» на доске`}
+                  checked={stage.shown}
+                  onCheckedChange={(shown) =>
+                    setStages((current) =>
+                      current.map((item) => (item.id === stage.id ? { ...item, shown } : item)),
+                    )
+                  }
+                />
+              </List.ItemActions>
               <List.ItemText>{stage.name}</List.ItemText>
               <List.ItemDescription>{stage.description}</List.ItemDescription>
               <List.ItemCount>{stage.deals}</List.ItemCount>

package/dist/skill/reference/components/list/examples/row-controls.tsx

@@ -0,0 +1,80 @@
+/** 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`. */
+import { Badge, Button, Card, Dropdown, Icon, List, type PaletteColor, Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Stage = { id: string; name: string; color: PaletteColor; deals: number; shown: boolean };
+
+const STAGES: Stage[] = [
+  { id: "lead", name: "Новый лид", color: "blue", deals: 42, shown: true },
+  { id: "qualified", name: "Квалификация", color: "purple", deals: 18, shown: true },
+  { id: "proposal", name: "Коммерческое предложение", color: "orange", deals: 11, shown: true },
+  { id: "paused", name: "Отложено", color: "gray", deals: 7, shown: false },
+];
+
+export default function ListRowControlsExample() {
+  const [stages, setStages] = React.useState(STAGES);
+  const [current, setCurrent] = React.useState("lead");
+
+  const patch = (id: string, next: Partial<Stage>) =>
+    setStages((list) => list.map((stage) => (stage.id === id ? { ...stage, ...next } : stage)));
+
+  return (
+    <Card.Root className={styles.pane}>
+      <Card.Body>
+        <List.Root aria-label="Этапы воронки">
+          {stages.map((stage) => (
+            <List.Item
+              key={stage.id}
+              value={stage.id}
+              current={current === stage.id}
+              onClick={() => setCurrent(stage.id)}
+            >
+              <List.ItemIcon>
+                <Badge.Dot color={stage.color} />
+              </List.ItemIcon>
+              <List.ItemText>{stage.name}</List.ItemText>
+              <List.ItemCount>{stage.deals}</List.ItemCount>
+              <List.ItemActions>
+                <Switch.Root
+                  aria-label={`Показывать «${stage.name}» на доске`}
+                  checked={stage.shown}
+                  onCheckedChange={(shown) => patch(stage.id, { shown })}
+                />
+                <Dropdown.Root>
+                  <Dropdown.Trigger>
+                    <Button.Root
+                      variant="ghost"
+                      tone="neutral"
+                      aria-label={`Действия с этапом «${stage.name}»`}
+                    >
+                      <Button.Icon>
+                        <Icon name="action.more" />
+                      </Button.Icon>
+                    </Button.Root>
+                  </Dropdown.Trigger>
+                  <Dropdown.Content>
+                    <Dropdown.Item onSelect={() => setCurrent(stage.id)}>Открыть</Dropdown.Item>
+                    <Dropdown.Item onSelect={() => patch(stage.id, { color: "green" })}>
+                      Отметить зелёным
+                    </Dropdown.Item>
+                    <Dropdown.Separator />
+                    <Dropdown.Item
+                      tone="danger"
+                      onSelect={() =>
+                        setStages((list) => list.filter((item) => item.id !== stage.id))
+                      }
+                    >
+                      Удалить этап
+                    </Dropdown.Item>
+                  </Dropdown.Content>
+                </Dropdown.Root>
+              </List.ItemActions>
+            </List.Item>
+          ))}
+        </List.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/dist/skill/reference/components/list/examples/with-icon.tsx

@@ -1,5 +1,5 @@
-/** Leading avatars of clients and icons of queues; an avatar takes the row tier — `List.ItemIcon`. */
-import { Avatar, Icon, List, Typography } from "prime-ui-kit";
+/** 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`. */
+import { Avatar, Badge, Icon, List, Typography } from "prime-ui-kit";
 
 const CLIENTS = [
   { id: "belova", name: "Ирина Белова", company: "ООО «Гранит»", initials: "ИБ", color: "blue" },
@@ -7,6 +7,12 @@ const CLIENTS = [
   { id: "kozlov", name: "Сергей Козлов", company: "ИП Козлов", initials: "СК", color: "orange" },
 ] as const;
 
+const PROJECTS = [
+  { id: "crm", name: "Внедрение CRM", color: "purple" },
+  { id: "portal", name: "Клиентский портал", color: "teal" },
+  { id: "billing", name: "Биллинг", color: "orange" },
+] as const;
+
 export default function ListWithIconExample() {
   return (
     <div>
@@ -56,6 +62,21 @@ export default function ListWithIconExample() {
             Icon
           </Typography>
         </div>
+        <div>
+          <List.Root aria-label="Проекты">
+            {PROJECTS.map((project, index) => (
+              <List.Item key={project.id} current={index === 0}>
+                <List.ItemIcon>
+                  <Badge.Dot color={project.color} />
+                </List.ItemIcon>
+                <List.ItemText>{project.name}</List.ItemText>
+              </List.Item>
+            ))}
+          </List.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            Badge.Dot
+          </Typography>
+        </div>
       </div>
     </div>
   );

package/dist/skill/reference/components/login-form/COMPONENT.md

@@ -34,7 +34,7 @@ LoginForm.Root                      width cap; a Card inside: card fill, radius,
    │  └─ LoginForm.Actions          primary button + ghost back action
    └─ LoginForm.Footer              «Нет аккаунта? <LinkButton>»
 ```
-Every part is optional except `Root`, `Title` and `Form`. Fields, buttons, dividers, banners and links are the regular kit components; LoginForm owns only the layout and the rhythm.
+Every part is optional except `Root`, `Title` and `Form`. Fields, buttons, dividers and links are the regular kit components; LoginForm owns only the layout and the rhythm.
 
 ## API
 
@@ -149,8 +149,8 @@ Every part is optional except `Root`, `Title` and `Form`. Fields, buttons, divid
 | `flat` | card fill, no shadow | inside a Modal or any other surface | `false` |
 
 **Combinations**
-- Recommended: one `size` on Root only (fields and buttons follow it); `hint` / `error` on fields for validation; a danger [Banner](../banner/COMPONENT.md) at the top of `Form` for server errors.
-- Avoid: more than one primary button; provider buttons in `solid` (they compete with the submit); a Card around LoginForm.
+- Recommended: one `size` on Root only (fields and buttons follow it); `hint` / `error` on fields for validation; a refused sign-in as `invalid` on the fields it concerns plus a [VisuallyHidden](../visually-hidden/COMPONENT.md) live region with the reason.
+- Avoid: a [Banner](../banner/COMPONENT.md) in the form; more than one primary button; provider buttons in `solid` (they compete with the submit); a Card around LoginForm.
 
 ## States
 LoginForm has no state of its own. Compose them:
@@ -159,7 +159,7 @@ LoginForm has no state of its own. Compose them:
 |---|---|---|
 | submitting | `loading` on the submit Button; the fields in a `Fieldset disabled`, the submit Button outside it | `aria-busy` on the button; native `disabled` on the `<fieldset>`, the fields in their disabled look |
 | field error | `error` / `invalid` on `Input.Root`, `error` on `DigitInput` | `aria-invalid`, the error under the field |
-| server error | `Banner.Root tone="danger" role="alert"` as the first child of `LoginForm.Form` | `role="alert"` |
+| refused sign-in | `invalid` on the fields it concerns (they shake once); `VisuallyHidden live="assertive"`, mounted from the start in `LoginForm.Form`, gets the reason | `aria-invalid` on the fields; `role="alert"` on the hidden region |
 
 Root carries `data-size`, `data-align` and `data-flat`.
 
@@ -185,7 +185,7 @@ Root carries `data-size`, `data-align` and `data-flat`.
 - The logo is decorative; with an `aria-label` it is the product mark image (`role="img"`).
 - Give `LoginForm.Form` an `aria-label` (or `aria-labelledby` pointing to the title id) so the form is a landmark.
 - Fields use `autoComplete` (`email`, `current-password`, `new-password`, `one-time-code`) so password managers and OTP autofill work.
-- Server errors in a Banner need `role="alert"`; field errors come from the fields (`aria-invalid`, described by the error).
+- Field errors come from the fields (`aria-invalid`, described by the error). A refused sign-in has no Banner: the fields it concerns take `invalid` and an always-mounted `VisuallyHidden live="assertive"` says why.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -202,16 +202,17 @@ No `labels`.
 | [forgot-password.tsx](examples/forgot-password.tsx) | Password reset request: one field, the primary action and a quiet way back — `LoginForm.Actions`. |
 | [reset-password.tsx](examples/reset-password.tsx) | A new password after the e-mail link: a strength meter on the first field and a mismatch error under the second one — `strength`, `error`. |
 | [verification-code.tsx](examples/verification-code.tsx) | The second step with a one-time code: a rejected code shows its error under the cells, resend is a quiet action — `DigitInput`, `LoginForm.Actions`. |
-| [states.tsx](examples/states.tsx) | The submit cycle: the button is busy while the request runs, a failed request shows a danger Banner and marks the password — `loading`, `invalid`. |
+| [states.tsx](examples/states.tsx) | The submit cycle: the button is busy while the request runs, a refused sign-in marks both fields, which shake once, and a hidden live region says why — `loading`, `invalid`, `VisuallyHidden`. |
 | [narrow.tsx](examples/narrow.tsx) | On a phone-width screen the card keeps its padding, the header wraps and the buttons stay full width — `LoginForm.Form`. |
 
 ## Mistakes
 - A separate block of your own for provider buttons → put them in `LoginForm.Actions`.
 - `disabled` on every field while the request runs → one [Fieldset](../fieldset/COMPONENT.md) `disabled` around the fields; keep the submit Button outside it so it shows `loading`.
+- A danger Banner above the fields for a refused sign-in → `invalid` on the fields and the reason in a `VisuallyHidden live="assertive"`; a sign-in or sign-up form has no banners.
 - A placeholder instead of a field label → pass `label` to the field.
 - A Card around LoginForm → the root already is the card; use `flat` inside another surface.
 - Repeating the card `size` on every field and button → set it once on Root; fields and buttons follow it.
 
 ## Related
 - **Built from:** [Card](../card/COMPONENT.md) (the surface), [Typography](../typography/COMPONENT.md) (`Title`, `Description`, `Footer`), the icon tile (`iconBox` `.tile`, the `start` logo)
-- **See also:** [Input](../input/COMPONENT.md), [Fieldset](../fieldset/COMPONENT.md) (disables the fields while signing in), [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [DigitInput](../digit-input/COMPONENT.md), [Banner](../banner/COMPONENT.md), [Modal](../modal/COMPONENT.md)
+- **See also:** [Input](../input/COMPONENT.md), [Fieldset](../fieldset/COMPONENT.md) (disables the fields while signing in), [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [DigitInput](../digit-input/COMPONENT.md), [VisuallyHidden](../visually-hidden/COMPONENT.md), [Modal](../modal/COMPONENT.md)

package/dist/skill/reference/components/login-form/examples/states.tsx

@@ -1,5 +1,5 @@
-/** The submit cycle: the button is busy while the request runs, a failed request shows a danger Banner and marks the password — `loading`, `invalid`. */
-import { Banner, Button, Fieldset, Icon, Input, LoginForm } from "prime-ui-kit";
+/** The submit cycle: the button is busy while the request runs, a refused sign-in marks both fields, which shake once, and a hidden live region says why — `loading`, `invalid`, `VisuallyHidden`. */
+import { Button, Fieldset, Icon, Input, LoginForm, VisuallyHidden } from "prime-ui-kit";
 import * as React from "react";
 
 export default function LoginFormStatesExample() {
@@ -30,20 +30,18 @@ export default function LoginFormStatesExample() {
             }, 1200);
           }}
         >
-          {failed ? (
-            <Banner.Root tone="danger" role="alert">
-              <Banner.Content>
-                <Banner.Icon>
-                  <Icon name="status.danger" />
-                </Banner.Icon>
-                <Banner.Title>Неверный email или пароль</Banner.Title>
-              </Banner.Content>
-            </Banner.Root>
-          ) : null}
+          <VisuallyHidden live="assertive">
+            {failed ? "Неверный email или пароль" : ""}
+          </VisuallyHidden>
           <Fieldset disabled={pending}>
-            <Input.Root label="Email" required>
+            <Input.Root label="Email" required invalid={failed}>
               <Input.Wrapper>
-                <Input.Field type="email" autoComplete="email" placeholder="name@company.ru" />
+                <Input.Field
+                  type="email"
+                  autoComplete="email"
+                  placeholder="name@company.ru"
+                  onValueChange={() => setFailed(false)}
+                />
               </Input.Wrapper>
             </Input.Root>
             <Input.Root label="Пароль" required invalid={failed}>

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

@@ -8,7 +8,8 @@
 ## When to use
 - A message of any kind: text with formatting, a reply, a forwarded message, reactions, photos and albums (`Message.Media`, a `Gallery`), a round video message (`VideoNote` inside), a voice message (`VoicePlayer` inside), a file, a location, a contact, a link preview.
 - The rows of a conversation in [Chat](../chat/COMPONENT.md) (`Chat.Messages`): the list, dates, search, selection and jumps live there; the message is one row.
-- A message on its own: a quoted reply in a ticket, the last message in a card, a preview of what will be sent.
+- A message on its own: a quoted reply in a ticket, the last message in a card, a preview of what will be sent (`preview` — a bot's welcome message on its settings page).
+- A sticker (`Message.Sticker`): a webp or gif by `src`, or your own Lottie / video player as children.
 - «Печатает…» (`Message.Typing`) as the last row of a list.
 
 ## When not to use
@@ -17,6 +18,7 @@
 - A feed of events with a time axis (an order history, an audit log) → [Timeline](../timeline/COMPONENT.md).
 - One system message on a page (saved, failed) → [Banner](../banner/COMPONENT.md) or a [Notification](../notification/COMPONENT.md).
 - Photos outside a message → [Gallery](../gallery/COMPONENT.md); a recording outside a chat → [VoicePlayer](../voice-player/COMPONENT.md).
+- Formatted text outside a message, with no bubble → [RichText](../rich-text/COMPONENT.md).
 
 ## Import
 ```tsx
@@ -35,7 +37,8 @@ Message.Root                      role="article" row «{author}, {time}» (an op
 │  ├─ Message.Forwarded           «Переслано от …»
 │  ├─ Message.Reply               quote of the answered message (button with target / onClick)
 │  ├─ content                     Message.Text · Message.Media (+ caption Text) · VoicePlayer · Message.File ·
-│  │                              Message.Location · Message.Contact · Message.LinkPreview · VideoNote
+│  │                              Message.Location · Message.Contact · Message.LinkPreview · VideoNote ·
+│  │                              Message.Sticker
 │  │                              (a voice message or a circle may open its transcript under it)
 │  ├─ Message.Reactions           a row held closed in every message; chips closing a bubble
 │  │                              (under a picture or a circle), the meta's spacer at its end
@@ -52,9 +55,9 @@ 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.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_, ~~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 «Выбрать».
 
-`formatMessageTime(date)` gives «09:05», the default `formatTime`. `hueOf(id)` gives a palette hue stable per id for `Message.Author color` and the author's `Avatar`.
+`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`.
 
 ## API
 
@@ -68,9 +71,11 @@ Content parts in short: `Message.Media` — a [Gallery](../gallery/COMPONENT.md)
 | `direction` | `"incoming" \| "outgoing"` | `"incoming"` | `incoming` — on the start side, a surface one step off the chat; `outgoing` — on the end side, in the accent hue (`--prime-color-message-outgoing-*`), everything inside recolors with it. |
 | `position` | `"single" \| "first" \| "middle" \| "last"` | `"single"` | The place in a run of one author (`Chat.Messages items` sets it): `single` and `last` end a run with the tail (and a group chat's avatar); `single` and `first` show the author's header. |
 | `time` | `Date \| string` | — | When it was sent: a `Date` shown with `formatTime` (and put in `<time dateTime>`), or the text to show. |
-| `formatTime` | `(date: Date) => string` | «09:05» | Display of a `Date` time. |
+| `timeZone` | `string` | the list's `timeZone`, else the browser's zone | The IANA zone the time is read in (`"Asia/Vladivostok"`): a profile's zone, not the browser's. |
+| `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`. |
+| `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. |
 | `value` | `string` | — | The message id for selection, jumps, read receipts, search, pins and `Message.Reply target` (`Chat.Messages items` sets the item's key). Keep it when the server confirms a sent message. |
@@ -206,6 +211,16 @@ Content parts in short: `Message.Media` — a [Gallery](../gallery/COMPONENT.md)
 | `image` | `string` | — | The page's picture, full width under the text. |
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "title">` | — | `className` and the other attributes of the link. |
 
+### Message.Sticker
+`ref` → `HTMLDivElement` (`role="img"`). A sticker: a square picture with no bubble, the meta on a pill over its corner; a `Skeleton` holds the box until it is ready.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `aria-label` | `string` | — (required) | The sticker's name («Стикер «Класс»», or its emoji); shown in its box when `src` fails. |
+| `src` | `string` | — | A still or animated picture (webp, gif, apng), decoded before it shows. Without it the children are the sticker. |
+| `loading` | `boolean` | `false` | Your player in the children is not ready yet: the `Skeleton` stays over the box. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role" \| "aria-label">` | — | `children` — your player for a Lottie (.tgs) or a video sticker, sized to the box; `className`. |
+
 ### Message.Reactions
 `ref` → `HTMLDivElement`. Reaction chips at the bottom of a bubble, or under a picture or a circle: a `role="group"` of toggle chips — the emoji, then who reacted (`users`) or the count. A press goes to `Message.Root onReactionToggle`.
 
@@ -250,7 +265,7 @@ Decided by the content parts, not a prop (`data-shell` on the bubble): a circle
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `bubble` | fill (surface or accent), padding, the meta in the bottom-end corner over the last line's reserve | text, voice, file, contact, location, link preview, a picture **with** a caption | yes |
-| `media` | the picture itself, clipped to the radius — no backing, no padding; the meta on a dark pill over its bottom-end corner; reactions in a row of their own **under** it, on the message's side (chips in their own fill); an album's gaps show the incoming surface in both directions, never the outgoing fill | a photo, a video or an album **without** a caption | |
+| `media` | the picture itself, clipped to the radius — no backing, no padding; the meta on a dark pill over its bottom-end corner; reactions in a row of their own **under** it, on the message's side (chips in their own fill); an album's gaps show the incoming surface in both directions, never the outgoing fill | a photo, a video or an album **without** a caption; a sticker | |
 | `round` | `VideoNote`: a circle standing on the chat — no backing in either direction; the duration and the meta float on their own pills over its bottom; reactions under it as for `media` | a round video message | |
 
 With a caption a picture sits at the top of a normal bubble, edge to edge, and its reactions stay inside it, under the caption. The row of reactions is held closed in every message and opens with the first reaction (see States).
@@ -294,6 +309,8 @@ The fill moves between the two in a color transition (`fast`, both ways); the av
 | Prop | Effect |
 |---|---|
 | `edited` | «изменено» before the time |
+| `preview` | a picture of the message outside a chat: no menu, reaction bar, reactions toggle, retry or row focus; `Message.Actions` rows `inert` (seen, never pressed); links, players and spoilers still work |
+| `Message.Sticker loading` | the Skeleton stays over the sticker's box while your player prepares |
 | `Message.Location live` | a breathing pin and a «Трансляция» badge |
 | `Message.Text plain` | a string without Markdown |
 | `Message.Typing open` | the typing bubble shows; off, it leaves closing its height |
@@ -313,6 +330,8 @@ The list-level settings a message reads — the group chat's author header and a
 | 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 |
+| 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 |
 | size change | a reaction row that opens or closes, a chip that comes or goes, a transcript, an edit, an upload state | one stroke (`bubbleMorph`, `--prime-message-morph-duration` 300 ms): the new layout is laid out at once, in the same frame, and the bubble's visible box glides from the old rectangle to the new one — width and height together, one `clip-path: inset(… round …)` animation on the compositor, the fill a layer under the content that reaches over both boxes. Every part that moved (the text, the meta, the cards, the chips, the tail, the retry) glides from where it was by a `transform` on the same clock; a part that came fades (a chip also scales from 0.9) in where it stands once the box has room for it; a part that went fades out where it stood, out of flow. A change mid-flight retargets from what is on screen; a commit that moves nothing touches nothing. The meta and the tail stay put on a reaction: the message grows upward, the chat scrolling by the change in the same frame while the rows above glide as one block on the same clock (the rows below never move). A disclosed block (a transcript) fades over the whole stroke while the box opens or closes over it. The text glides straight with the bubble's top-start corner, keeping its padding all the way. Nothing travels across text: a meta that stays while text passes through its place dips — it fades out at the same spot before the text reaches it and back once the text has left — and a meta that changes line (a transcript's last line ↔ the player row) cross-fades — out at its old place in the first 40 % of the stroke, in at its new place in the last 40 %. Easing `standard`. Reduced motion: instant (the scroll still keeps the view) |
 | new reaction | an emoji not on the message yet (the reader's or anyone's) | part of the size change: its room is there at once and the chip fades and scales in from 0.9 where it stands, on the bubble's clock, once the parts moving away have left its place. Never on the first render of a message: opening a chat or loading history plays nothing |
@@ -337,7 +356,7 @@ The list-level settings a message reads — the group chat's author header and a
 - **The author's header** (a group chat, the first of a run): one line `body-s` — the name semibold in the author's hue, an `xs` icon, the tag muted after them; the name ellipsizes first, then the tag. The bubble hugs the whole line, so a long name or tag widens it up to its cap. Over a picture or a circle without a caption it stands on the media pill at `space-2` from the top-start corner, in the pill's colors.
 - **A bubble hugs its text** (`bubbleHug`): a bubble of text — text, author, reply, forwarded, reactions — is as wide as its widest laid-out line plus the padding, never the width its lines wrapped in, and never wider than the cap; the meta's room counts on the last line only, where it sits, the reactions row as one line of chips with the meta after them, and the author's header at its full width (`data-message-fit="row"`, an ellipsized name counted whole). Quote and code blocks stretch to the bubble's width; long code lines wrap. Plain wrapping, never `pretty`. The width is measured once per text and row width — cleared, measured and written in one pass in the commit that changed the text, before paint, so a size change's morph runs to the hugged width — and cached by both: a row the window renders again takes its width with nothing measured. Row widths come from one shared `ResizeObserver`, batched per frame; hover, the menu, the reaction bar and selection never measure; a morph reads boxes only, never the hug width; fonts that finish loading measure once more. A bubble with any other part (a card, a player, a picture) keeps the width its parts give it.
 - No minimum width beyond the corners: «Ок 10:16» is a compact pill — the text, the meta on the same line and the padding. With reactions the meta moves to the end of the row's last line and the text gives its room back.
-- Fixed kinds stay one width: a file, a contact and a location are `--prime-message-card-width` (16rem, at most 75% of the chat), a voice message is the player's width, a round video is the VideoNote circle (268, at most the row), a link preview the media width (360) or what the row allows.
+- Fixed kinds stay one width: a file, a contact and a location are `--prime-message-card-width` (16rem, at most 75% of the chat), a voice message is the player's width, a round video is the VideoNote circle (268, at most the row), a sticker the square `--prime-message-sticker` (160, at most 85% of the row), a link preview the media width (360) or what the row allows.
 - Embedded blocks (a link preview, a reply quote, a forwarded header, the cards) span the bubble's content width; long unbreakable text (URLs) wraps instead of widening the bubble.
 - Pictures follow the album layout of their Gallery, at most `--prime-gallery-max-size` (360) wide and tall and within 85% of the row; a bubble with a picture or a card is exactly that part's width and a caption wraps under it.
 - A file's name stands on one line without the extension its format tile shows; the full name is its tooltip and the download label. The tile downloads by an `href` link, or with `transfer="remote"` through `onDownload` in the app.
@@ -488,6 +507,8 @@ The list-level settings a message reads — the group chat's author header and a
 | [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: rows of buttons under the bubble at its width, sharing each row equally, one of them a link — `Message.Actions`, `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`. |
 
 ## Mistakes
@@ -513,5 +534,5 @@ The list-level settings a message reads — the group chat's author header and a
 - 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.
 
 ## 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), Icon (status ticks, file glyphs, `action.forward`, `action.refresh`); `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)
-- **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; [Timeline](../timeline/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`); `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)
+- **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/preview.tsx

@@ -0,0 +1,28 @@
+/** 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`. */
+import { Button, Message } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SENT = new Date(Date.UTC(2026, 9, 14, 23, 30));
+
+export default function MessagePreviewExample() {
+  return (
+    <div className={styles.thread}>
+      <Message.Root preview time={SENT} timeZone="Asia/Vladivostok">
+        <Message.Text>
+          {
+            "**Здравствуйте!** Я бот склада «Прайм»: подскажу статус заказа и пришлю счёт. Выберите, с чего начать."
+          }
+        </Message.Text>
+        <Message.Actions>
+          <Button.Root variant="soft" tone="neutral">
+            Статус заказа
+          </Button.Root>
+          <Button.Root variant="soft" tone="neutral">
+            Прислать счёт
+          </Button.Root>
+        </Message.Actions>
+      </Message.Root>
+    </div>
+  );
+}

package/dist/skill/reference/components/message/examples/sticker.tsx

@@ -0,0 +1,35 @@
+/** 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`. */
+import { Message } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const THUMBS_UP = "https://fonts.gstatic.com/s/e/notoemoji/latest/1f44d/512.webp";
+const CLIP = "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4";
+
+export default function MessageStickerExample() {
+  const [clipReady, setClipReady] = React.useState(false);
+
+  return (
+    <div className={styles.thread}>
+      <Message.Root value="sticker-text" time="10:42">
+        <Message.Text>Отгрузку подтвердили, машина выезжает в 14:00.</Message.Text>
+      </Message.Root>
+      <Message.Root value="sticker-image" direction="outgoing" time="10:43" status="read">
+        <Message.Sticker src={THUMBS_UP} aria-label="Стикер «Класс»" />
+      </Message.Root>
+      <Message.Root value="sticker-video" time="10:44">
+        <Message.Sticker aria-label="Видеостикер «Цветок»" loading={!clipReady}>
+          <video
+            src={CLIP}
+            autoPlay
+            loop
+            muted
+            playsInline
+            onLoadedData={() => setClipReady(true)}
+          />
+        </Message.Sticker>
+      </Message.Root>
+    </div>
+  );
+}