prime-ui-kit 0.13.1 → 0.15.0

package/src/components/chat/examples/search.tsx

@@ -1,4 +1,4 @@
-/** Search and pinned messages: the search bar marks every match in the texts and transcripts, counts them and steps between them while the others step back; a pinned message's press jumps to it and blinks the others — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. */
+/** Search and pinned messages: the search bar marks every match in the texts and transcripts, counts them and steps between them while the others step back; a pinned message's press jumps to it and blinks it — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. */
 import { Card, Chat, Message, VoicePlayer } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/src/components/chat-list/COMPONENT.md

@@ -170,7 +170,7 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 
 ## Layout & spacing
 - The root is a flex column that fills its host's height: put it straight into a `Card.Root` or a `PageContent.List` pane with a height; the scroller takes the rest under the search field.
-- The search field stands on 8px sides; the rows on 8px sides and 4px between them (a margin inside each `<li>`, so the virtual window measures rows with their space).
+- One inset all round, the panel's 4px: the search field and the rows stand 4px from every edge of the host, so in a card (radius 12) their 8px corners follow the card's (nested radius = outer − padding). Rows stand 4px apart (a margin inside each `<li>`, so the virtual window measures rows with their space); the last row's margin is the inset below it.
 - A row: avatar · name and preview · time over the counts. The name and the preview truncate; glyphs, the time and the counts never do.
 - From 100 dialogs only the rows around the view render; spacers hold the rest of the height. The row with the Tab stop and the row with an open menu stay rendered.
 - The root is the `chat-list` container: below 240px the preview line and the time step out, the names and counts stay. At 320px (a phone) everything shows.
@@ -238,6 +238,7 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 | [search.tsx](examples/search.tsx) | The search field filters dialogs by name and by the last message, marks the match in both, says how many were found and shows a quiet state when none match — `defaultSearch`, `onSearchChange`. |
 | [live.tsx](examples/live.tsx) | A live inbox: a client types, then writes — the preview turns into the typing line and back, the count rolls up and the dialog glides to the top; opening it clears the count — `typing`, `unread`, `items`. |
 | [long-list.tsx](examples/long-list.tsx) | A sales inbox of a thousand dialogs: only the rows around the view render, arrows walk through all of them, and the next page loads as the end comes near — `hasMore`, `onLoadMore`. |
+| [links.tsx](examples/links.tsx) | Dialogs with their own address: every row is a link the router opens, the time reads as how long ago, and the list is named for its queue — `href`, `formatTime`, `labels`. |
 | [states.tsx](examples/states.tsx) | Loading and empty: placeholder rows in the rows' geometry cross-fade into the dialogs; a new workspace without dialogs shows its own empty state with an action — `loading`, `empty`. |
 | [controlled.tsx](examples/controlled.tsx) | The open dialog lives in the screen: a row opens it beside the list, and a next-unread button opens the next one from outside — `value`, `onValueChange`. |
 | [narrow.tsx](examples/narrow.tsx) | At phone width long names and previews truncate while the time and counts stay whole; a pane squeezed under 240px keeps only the names and the counts — `ChatList.Root`, `search`. |

package/src/components/chat-list/examples/links.tsx

@@ -0,0 +1,72 @@
+/** Dialogs with their own address: every row is a link the router opens, the time reads as how long ago, and the list is named for its queue — `href`, `formatTime`, `labels`. */
+import { Avatar, Card, ChatList, hueOf } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const NOW = new Date(2026, 9, 14, 15, 0);
+const at = (day: number, hour: number, minute: number) => new Date(2026, 9, day, hour, minute);
+
+const DIALOGS = [
+  {
+    id: "t-1042",
+    name: "ООО «Вектор»",
+    initials: "ВК",
+    preview: "Не можем выгрузить счёт в 1С",
+    at: at(14, 14, 52),
+    unread: 2,
+  },
+  {
+    id: "t-1039",
+    name: "ООО «Гранит»",
+    initials: "ГР",
+    preview: "Акт сверки подписан",
+    at: at(14, 12, 5),
+    unread: 0,
+  },
+  {
+    id: "t-1031",
+    name: "ИП Козлов",
+    initials: "ИК",
+    preview: "Подключите, пожалуйста, ЭДО",
+    at: at(12, 11, 40),
+    unread: 0,
+  },
+];
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+/** A support queue reads waiting time: «8 мин», «3 ч», «2 дн». */
+const formatAgo = (date: Date, now: Date) => {
+  const passed = now.getTime() - date.getTime();
+  if (passed < HOUR) return `${Math.max(1, Math.round(passed / MINUTE))} мин`;
+  if (passed < DAY) return `${Math.round(passed / HOUR)} ч`;
+  return `${Math.round(passed / DAY)} дн`;
+};
+
+export default function ChatListLinksExample() {
+  return (
+    <Card.Root className={styles.short}>
+      <ChatList.Root
+        labels={{ list: "Обращения" }}
+        items={DIALOGS}
+        getKey={(item) => item.id}
+        value="t-1042"
+        now={NOW}
+        formatTime={formatAgo}
+        renderItem={(item) => (
+          <ChatList.Item href={`/support/tickets/${item.id}`} time={item.at} unread={item.unread}>
+            <ChatList.ItemIcon>
+              <Avatar.Root color={hueOf(item.id)}>
+                <Avatar.Fallback>{item.initials}</Avatar.Fallback>
+              </Avatar.Root>
+            </ChatList.ItemIcon>
+            <ChatList.ItemText>{item.name}</ChatList.ItemText>
+            <ChatList.ItemDescription>{item.preview}</ChatList.ItemDescription>
+          </ChatList.Item>
+        )}
+      />
+    </Card.Root>
+  );
+}

package/src/components/checkbox/COMPONENT.md

@@ -152,7 +152,7 @@ No `labels`.
 | [overview.tsx](examples/overview.tsx) | A checkbox with its label; a click anywhere on the row toggles it. |
 | [variants.tsx](examples/variants.tsx) | The rounded square next to the circle, in three states — `shape`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size; the box and the text follow the control tier — `size`. |
-| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `indeterminate`, `invalid`, `disabled`. |
+| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `indeterminate`, `readOnly`, `invalid`, `disabled`. |
 | [without-label.tsx](examples/without-label.tsx) | Bare boxes in table rows, named by `aria-label` and submitted with `name` and `value`. |
 | [indicator.tsx](examples/indicator.tsx) | The box alone in a multi-select list: the option row carries `aria-selected`, the box only shows it — `Checkbox.Indicator`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the selection; «select all» turns indeterminate on a partial one — `checked`, `onCheckedChange`, `indeterminate`. |

package/src/components/checkbox/examples/examples.module.css

@@ -57,8 +57,12 @@
     var(--prime-motion-easing-standard);
 }
 
+.option[aria-disabled="true"] {
+  cursor: default;
+}
+
 @media (hover: hover) {
-  .option:hover {
+  .option:not([aria-disabled="true"]):hover {
     background: var(--prime-color-fill-subtle);
   }
 }

package/src/components/checkbox/examples/indicator.tsx

@@ -4,19 +4,35 @@ import * as React from "react";
 
 import styles from "./examples.module.css";
 
-const CITIES = [
+const CITIES: { value: string; label: string; disabled?: boolean }[] = [
   { value: "msk", label: "Москва" },
   { value: "spb", label: "Санкт-Петербург" },
   { value: "kzn", label: "Казань" },
+  { value: "tver", label: "Тверь · закрыт", disabled: true },
 ];
 
+/** One tab stop: arrows move the focused row (wrapping), Home / End jump to the ends. */
+function nextIndex(key: string, index: number, count: number): number | null {
+  if (key === "ArrowDown") return (index + 1) % count;
+  if (key === "ArrowUp") return (index - 1 + count) % count;
+  if (key === "Home") return 0;
+  if (key === "End") return count - 1;
+  return null;
+}
+
 export default function CheckboxIndicatorExample() {
   const [selected, setSelected] = React.useState<string[]>(["msk"]);
+  const [active, setActive] = React.useState(0);
+  const optionRefs = React.useRef<(HTMLDivElement | null)[]>([]);
 
-  const toggle = (value: string) =>
+  const toggle = (city: (typeof CITIES)[number]) => {
+    if (city.disabled) return;
     setSelected((current) =>
-      current.includes(value) ? current.filter((item) => item !== value) : [...current, value],
+      current.includes(city.value)
+        ? current.filter((item) => item !== city.value)
+        : [...current, city.value],
     );
+  };
 
   return (
     <div
@@ -24,26 +40,38 @@ export default function CheckboxIndicatorExample() {
       aria-label="Города доставки"
       aria-multiselectable
       className={styles.optionList}
+      onKeyDown={(event) => {
+        const next = nextIndex(event.key, active, CITIES.length);
+        if (next === null) return;
+        event.preventDefault();
+        setActive(next);
+        optionRefs.current[next]?.focus();
+      }}
     >
-      {CITIES.map((city) => {
+      {CITIES.map((city, index) => {
         const isSelected = selected.includes(city.value);
         return (
           <div
             key={city.value}
+            ref={(node) => {
+              optionRefs.current[index] = node;
+            }}
             role="option"
             aria-selected={isSelected}
-            tabIndex={0}
+            aria-disabled={city.disabled || undefined}
+            tabIndex={index === active ? 0 : -1}
             className={styles.option}
-            onClick={() => toggle(city.value)}
+            onFocus={() => setActive(index)}
+            onClick={() => toggle(city)}
             onKeyDown={(event) => {
               if (event.key === " " || event.key === "Enter") {
                 event.preventDefault();
-                toggle(city.value);
+                toggle(city);
               }
             }}
           >
-            <Checkbox.Indicator checked={isSelected} />
-            <Typography as="span" variant="body-m">
+            <Checkbox.Indicator checked={isSelected} disabled={city.disabled} />
+            <Typography as="span" variant="body-m" tone={city.disabled ? "muted" : undefined}>
               {city.label}
             </Typography>
           </div>

package/src/components/checkbox/examples/states.tsx

@@ -1,4 +1,4 @@
-/** Every state side by side, each labelled by its prop — `checked`, `indeterminate`, `invalid`, `disabled`. */
+/** Every state side by side, each labelled by its prop — `checked`, `indeterminate`, `readOnly`, `invalid`, `disabled`. */
 import { Checkbox } from "prime-ui-kit";
 
 export default function CheckboxStatesExample() {
@@ -20,6 +20,11 @@ export default function CheckboxStatesExample() {
             <Checkbox.Label>indeterminate</Checkbox.Label>
           </Checkbox.Root>
         </div>
+        <div>
+          <Checkbox.Root defaultChecked readOnly>
+            <Checkbox.Label>readOnly</Checkbox.Label>
+          </Checkbox.Root>
+        </div>
         <div>
           <Checkbox.Root invalid>
             <Checkbox.Label>invalid</Checkbox.Label>

package/src/components/color-field/COMPONENT.md

@@ -93,7 +93,7 @@ ColorField                       field frame: label · field button · hint | er
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| closed / open | click, `Enter` · `Space`, `Escape`, an outside press | `aria-expanded` and `data-state` on the button; the chevron turns; the button keeps the focus fill while open |
+| closed / open | click, `Enter` · `Space`, `Escape`, an outside press | `aria-expanded` and `data-state` on the button; the chevron turns; the button holds the hover fill while open |
 | value | `value` / `defaultValue`, the panel | the chip and the hex follow the color as it is dragged; `onValueChange` gets every change as hex |
 | invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the button; the field shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | native `disabled` on the button, `data-disabled` on the frame; the hidden `name` input is disabled too, so the form does not submit the value |

package/src/components/color-picker/COMPONENT.md

@@ -163,7 +163,7 @@ No DOM. Holds the color (React Aria `ColorPicker`) and the value format for ever
 | `…rest` | `Omit<ButtonRootProps, "variant" \| "tone" \| "size" \| "aria-label">` | — | The other Button props. |
 
 ### ColorPresets.Root
-No DOM. A quick color from a fixed palette: a square trigger and a popover grid of presets (Popover overlay contract).
+A quick color from a fixed palette: a square trigger and a popover grid of presets. No DOM, except a field frame in a FieldList cell (the column heading as its label).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -270,7 +270,7 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 - Field + trigger row: gap `--prime-space-2`, `align-items: flex-end` so the trigger aligns with the field box under a label.
 - Panel parts gap: 12px (`--prime-space-3`) from `ColorPicker.Panel`.
 - ColorPresets.Content `align="auto"`: a trigger near the end of the screen lines up the panel's end edge and the panel grows toward the start, and the other way near the start; a fixed `align` still flips at the screen edge.
-- ColorPresets grid: one row for up to 8 presets (+ «no color»), else rows of 8 (`columns` overrides); below 480px viewport width the `l` / `xl` grids wrap to half the columns.
+- ColorPresets grid: one row for up to 8 presets (+ «no color»), else rows of 8 (`columns` overrides); below 480px viewport width the `l` / `xl` grids wrap to half the columns. On a coarse pointer every swatch grows to the 44 px touch target and the grid takes at most 5 columns, so it still fits a 320px panel; the arrow keys walk the same columns.
 
 ## Accessibility
 
@@ -306,7 +306,7 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 | `red` | `"Красный, 0–255"` | Red channel field. |
 | `green` | `"Зелёный, 0–255"` | Green channel field. |
 | `blue` | `"Синий, 0–255"` | Blue channel field. |
-| `trigger` | `"Цвет"` | ColorPresets trigger name prefix: «<trigger>: <color name>». |
+| `trigger` | `"Цвет"` | ColorPresets trigger name prefix: «<trigger>: <color name>»; in a FieldList cell the column heading. |
 | `list` | `"Цвета"` | ColorPresets swatch list name when `Content` has no `label`. |
 | `empty` | `"Без цвета"` | ColorPresets «no color» swatch and the trigger name for an empty value. |
 
@@ -315,13 +315,14 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A color field: a hex value and a swatch button that opens the picker panel — `ColorPicker.HexInput`, `ColorPicker.TriggerSwatch`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size of the hex field with a swatch button of the same tier — `size`. |
-| [states.tsx](examples/states.tsx) | A disabled area and hue slider keep showing the color but take no input — `disabled`. |
+| [states.tsx](examples/states.tsx) | A disabled area, hue slider and preset trigger keep showing the color but take no input — `disabled`. |
 | [validation.tsx](examples/validation.tsx) | A button color checked live: a too light color shakes in an error that leaves once the color is darker; a hint under the other field, invalid text reverts on blur — `hint`, `error`. |
 | [panel.tsx](examples/panel.tsx) | The full raised panel and its part order: format, area, hue and alpha sliders, channels, brand swatches — `ColorPicker.Panel`, `surface`, `ColorPicker.Swatches`. |
 | [formats.tsx](examples/formats.tsx) | The channel strip in each value format; three pickers edit one color — `defaultFormat`, `ColorPicker.ChannelStrip`. |
-| [presets.tsx](examples/presets.tsx) | A quick color from the palette: a square trigger next to a field and a Button trigger; «no color» allowed — `ColorPresets`, `allowEmpty`, `ColorPresets.Trigger`. |
+| [presets.tsx](examples/presets.tsx) | A quick color from the palette: a square trigger with «no color» and a Button trigger whose grid of four columns stays open after a pick — `ColorPresets`, `allowEmpty`, `ColorPresets.Trigger`, `columns`, `closeOnSelect`. |
 | [presets-sizes.tsx](examples/presets-sizes.tsx) | The preset trigger in every size, a square of the control height next to an input of the same tier — `ColorPresets`, `size`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the color: brand swatches and the hex field edit it, a button resets it — `value`, `onValueChange`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent opens the preset palette from its own button and keeps the chosen color — `open`, `onOpenChange`, `value`, `onValueChange`. |
 | [in-form.tsx](examples/in-form.tsx) | Theme settings: the color goes with the form, a too light color shakes in an error on save that leaves once the color changes — `value`, `error`. |
 
 ## Mistakes

package/src/components/color-picker/examples/controlled-open.tsx

@@ -0,0 +1,37 @@
+/** The parent opens the preset palette from its own button and keeps the chosen color — `open`, `onOpenChange`, `value`, `onValueChange`. */
+import { Button, COLOR_PRESETS, ColorPresets, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PRESETS = COLOR_PRESETS.slice(0, 8);
+
+export default function ColorPickerControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+  const [color, setColor] = React.useState<string | null>("#ef4444");
+  const name = PRESETS.find((preset) => preset.value === color)?.label ?? "без цвета";
+
+  return (
+    <div className={styles.inlineRow}>
+      <ColorPresets.Root
+        presets={PRESETS}
+        value={color}
+        onValueChange={setColor}
+        open={open}
+        onOpenChange={setOpen}
+        labels={{ trigger: "Цвет метки «Срочно»" }}
+      >
+        <ColorPresets.Trigger>
+          <ColorPresets.SwatchButton />
+        </ColorPresets.Trigger>
+        <ColorPresets.Content label="Цвет метки «Срочно»" />
+      </ColorPresets.Root>
+      <Typography as="span" variant="body-s" tone="secondary">
+        Метка «Срочно»: {name}
+      </Typography>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Сменить цвет
+      </Button.Root>
+    </div>
+  );
+}

package/src/components/color-picker/examples/presets.tsx

@@ -1,4 +1,4 @@
-/** A quick color from the palette: a square trigger next to a field and a Button trigger; «no color» allowed — `ColorPresets`, `allowEmpty`, `ColorPresets.Trigger`. */
+/** A quick color from the palette: a square trigger with «no color» and a Button trigger whose grid of four columns stays open after a pick — `ColorPresets`, `allowEmpty`, `ColorPresets.Trigger`, `columns`, `closeOnSelect`. */
 import { Button, COLOR_PRESETS, ColorPresets } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -19,7 +19,7 @@ export default function ColorPickerPresetsExample() {
         </ColorPresets.Trigger>
         <ColorPresets.Content />
       </ColorPresets.Root>
-      <ColorPresets.Root defaultValue="#22c55e">
+      <ColorPresets.Root presets={ONE_ROW} columns={4} closeOnSelect={false} defaultValue="#22c55e">
         <ColorPresets.Trigger>
           <Button.Root variant="soft" tone="neutral">
             <Button.Icon>

package/src/components/color-picker/examples/states.tsx

@@ -1,22 +1,31 @@
-/** A disabled area and hue slider keep showing the color but take no input — `disabled`. */
+/** A disabled area, hue slider and preset trigger keep showing the color but take no input — `disabled`. */
+import { ColorPresets } from "prime-ui-kit";
 import { ColorPicker } from "prime-ui-kit/color-picker";
 
 import styles from "./examples.module.css";
 
 export default function ColorPickerStatesExample() {
   return (
-    <ColorPicker.Root defaultValue="#30a46c">
-      <ColorPicker.Panel className={styles.panel}>
-        <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness" disabled>
-          <ColorPicker.AreaThumb />
-        </ColorPicker.Area>
-        <ColorPicker.Slider channel="hue" colorSpace="hsl" disabled>
-          <ColorPicker.SliderMeta label="disabled" />
-          <ColorPicker.SliderTrack>
-            <ColorPicker.Thumb />
-          </ColorPicker.SliderTrack>
-        </ColorPicker.Slider>
-      </ColorPicker.Panel>
-    </ColorPicker.Root>
+    <>
+      <ColorPicker.Root defaultValue="#30a46c">
+        <ColorPicker.Panel className={styles.panel}>
+          <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness" disabled>
+            <ColorPicker.AreaThumb />
+          </ColorPicker.Area>
+          <ColorPicker.Slider channel="hue" colorSpace="hsl" disabled>
+            <ColorPicker.SliderMeta label="disabled" />
+            <ColorPicker.SliderTrack>
+              <ColorPicker.Thumb />
+            </ColorPicker.SliderTrack>
+          </ColorPicker.Slider>
+        </ColorPicker.Panel>
+      </ColorPicker.Root>
+      <ColorPresets.Root disabled defaultValue="#22c55e" labels={{ trigger: "Цвет метки" }}>
+        <ColorPresets.Trigger>
+          <ColorPresets.SwatchButton />
+        </ColorPresets.Trigger>
+        <ColorPresets.Content />
+      </ColorPresets.Root>
+    </>
   );
 }

package/src/components/color-swatches/COMPONENT.md

@@ -97,6 +97,7 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 
 ## Layout & spacing
 - The swatches take the container width in equal columns: each one stretches across its column (the height stays the tier's). A row wraps only when they no longer fit, and then the swatches split evenly over the rows (16 → 8 + 8, never 14 + 2); no column count to set. In a content-sized container they stand in one row at the tier size.
+- On a coarse pointer the swatches grow to the 44 px touch target (a dense grid cannot grow an invisible hit area past its neighbours) and wrap into more rows.
 - The keyboard focus ring sits outside the swatches; kit hosts (Modal / Drawer body, panels, cards) already keep `--prime-focus-space` padding, so the ring is never clipped. In your own `overflow` container, keep that padding.
 - Label → swatches and swatches → hint use the tier `label-gap` / `hint-gap`; field → field 20.
 

package/src/components/composer/COMPONENT.md

@@ -283,7 +283,8 @@ Motion: the tray opens and closes as a Crossfade (fade and height glide, the row
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A reply to a client in a support chat: Enter sends, Shift+Enter breaks the line, the paperclip attaches files and an empty field records a voice message — `onSend`, `onSendVoice`, `queue`, `Composer.Attach`. |
 | [sizes.tsx](examples/sizes.tsx) | One composer in every tier: field, buttons and the paperclip follow it — `size`. |
-| [attachments.tsx](examples/attachments.tsx) | Warehouse photos and documents for a client go through an upload queue: the paperclip opens the file picker, a paste or a drop adds files too, every attachment is a tile of one strip that drags into its order, and send waits until the uploads finish — `queue`, `Composer.Attach`, `useUploadQueue`. |
+| [attachments.tsx](examples/attachments.tsx) | Warehouse photos and documents for a client go through an upload queue: the paperclip opens the file picker for photos, videos and office documents, a paste or a drop adds files too, every attachment is a tile of one strip that drags into its order, and send waits until the uploads finish — `queue`, `Composer.Attach`, `accept`, `useUploadQueue`. |
+| [attach-menu.tsx](examples/attach-menu.tsx) | The paperclip as a menu of attachment kinds: photos and videos, documents, any file, and an invoice from the system that puts its link into the message and returns the focus to the field — `Composer.Item`, `Composer.ItemIcon`, `accept`, `onSelect`, `inputRef`. |
 | [reply-edit.tsx](examples/reply-edit.tsx) | Answering a client's message and correcting your own: the bar above the field quotes the message, Escape or the cross cancels, ↑ in an empty field opens your last message, send becomes save and hands over the message id — `Composer.Context`, `mode`, `value`, `onDismiss`, `onEditLast`. |
 | [typing.tsx](examples/typing.tsx) | The other side's status line follows what you do: typing, recording a voice or a video message, then nothing — `onActivityChange`. |
 | [formatting.tsx](examples/formatting.tsx) | Selected text gets a toolbar of bold, italic, strikethrough, code, spoiler, link and quote, each with its shortcut, written as Markdown around the selection — `formatting`. |

package/src/components/composer/examples/attach-menu.tsx

@@ -0,0 +1,78 @@
+/** The paperclip as a menu of attachment kinds: photos and videos, documents, any file, and an invoice from the system that puts its link into the message and returns the focus to the field — `Composer.Item`, `Composer.ItemIcon`, `accept`, `onSelect`, `inputRef`. */
+import { Composer, Icon, type UploadContext, useUploadQueue } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const TICK_MS = 300;
+
+const INVOICE_LINK = "Счёт INV-2051 на 184 000 ₽: https://prime.app/invoices/2051";
+
+/** A stand-in for the file server: sends a file in a few steps. */
+function sendFile(file: File, { signal, onProgress }: UploadContext): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let sent = 0;
+    const timer = window.setInterval(() => {
+      sent = Math.min(1, sent + 0.25);
+      onProgress(sent);
+      if (sent < 1) return;
+      window.clearInterval(timer);
+      resolve(`https://files.example.com/chat/${encodeURIComponent(file.name)}`);
+    }, TICK_MS);
+    signal.addEventListener("abort", () => {
+      window.clearInterval(timer);
+      reject(signal.reason);
+    });
+  });
+}
+
+export default function ComposerAttachMenuExample() {
+  const queue = useUploadQueue({ upload: sendFile });
+  const [draft, setDraft] = React.useState("");
+  const inputRef = React.useRef<HTMLTextAreaElement>(null);
+
+  const attachInvoice = () => {
+    setDraft((current) => (current ? `${current}\n${INVOICE_LINK}` : INVOICE_LINK));
+    // The menu returns the focus to the paperclip; the reader goes on typing in the field.
+    window.requestAnimationFrame(() => inputRef.current?.focus());
+  };
+
+  return (
+    <div className={styles.chat}>
+      <Composer.Root
+        value={draft}
+        onValueChange={setDraft}
+        inputRef={inputRef}
+        queue={queue}
+        onSend={() => setDraft("")}
+      >
+        <Composer.Attach>
+          <Composer.Item accept="image/*,video/*">
+            <Composer.ItemIcon>
+              <Icon name="object.image" />
+            </Composer.ItemIcon>
+            Фото и видео
+          </Composer.Item>
+          <Composer.Item accept=".pdf,.docx,.xlsx">
+            <Composer.ItemIcon>
+              <Icon name="object.document" />
+            </Composer.ItemIcon>
+            Документ
+          </Composer.Item>
+          <Composer.Item accept="">
+            <Composer.ItemIcon>
+              <Icon name="object.file" />
+            </Composer.ItemIcon>
+            Любой файл
+          </Composer.Item>
+          <Composer.Item onSelect={attachInvoice}>
+            <Composer.ItemIcon>
+              <Icon name="object.receipt" />
+            </Composer.ItemIcon>
+            Счёт из системы
+          </Composer.Item>
+        </Composer.Attach>
+      </Composer.Root>
+    </div>
+  );
+}

package/src/components/composer/examples/attachments.tsx

@@ -1,4 +1,4 @@
-/** Warehouse photos and documents for a client go through an upload queue: the paperclip opens the file picker, a paste or a drop adds files too, every attachment is a tile of one strip that drags into its order, and send waits until the uploads finish — `queue`, `Composer.Attach`, `useUploadQueue`. */
+/** Warehouse photos and documents for a client go through an upload queue: the paperclip opens the file picker for photos, videos and office documents, a paste or a drop adds files too, every attachment is a tile of one strip that drags into its order, and send waits until the uploads finish — `queue`, `Composer.Attach`, `accept`, `useUploadQueue`. */
 import { Composer, type UploadContext, useUploadQueue } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -29,7 +29,7 @@ export default function ComposerAttachmentsExample() {
   return (
     <div className={styles.chat}>
       <Composer.Root queue={queue} onSend={() => {}}>
-        <Composer.Attach />
+        <Composer.Attach accept="image/*,video/*,.pdf,.docx,.xlsx" />
       </Composer.Root>
     </div>
   );

package/src/components/crossfade/COMPONENT.md

@@ -103,6 +103,7 @@ No `labels`.
 | [overview.tsx](examples/overview.tsx) | A card region that cross-fades between loading, data, empty and error and glides to the new height — `state`. |
 | [record-switch.tsx](examples/record-switch.tsx) | A detail panel keyed by the record id: picking another client cross-fades the details of a different height — `state`. |
 | [fill.tsx](examples/fill.tsx) | A deal board that fills its panel's height while it swaps between loading and data, and a notice slot above it that takes no room while empty — `fill`, `state`. |
+| [screen.tsx](examples/screen.tsx) | Screen states: the title and the date of the statement in the app header, a page-level error in a Banner with a retry, a region loading with a Skeleton of its rows and a table skeleton, the table error in place and a first-run EmptyPage; regions cross-fade between states — `state`. |
 
 ## Mistakes
 - A new `state` on every data refresh (`state={Date.now()}`) → key by what the region shows, not by when it was fetched.

package/src/components/crossfade/examples/screen.module.css

@@ -0,0 +1,40 @@
+/* Screen states: the layout keeps its shape in every state, only the content of a region changes. */
+
+/* The banner and the panels as one block with no gap of its own: the 24 under the banner (the body's
+   block gap) lives in its slot inside the Crossfade, so it arrives and leaves with the banner. */
+.lead {
+  display: grid;
+  min-width: 0;
+}
+
+.bannerSlot {
+  padding-block-end: var(--prime-space-6);
+}
+
+/* Skeleton rows mirror the account rows, so the card keeps its height when data arrives. */
+.nameBar {
+  width: 50%;
+}
+
+.balanceBar {
+  width: 35%;
+}
+
+/* The card stretches to its neighbour's height: rows stay at the top. */
+.accounts {
+  display: grid;
+  align-content: start;
+  gap: var(--prime-space-4);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.account {
+  display: grid;
+  gap: var(--prime-space-1);
+}
+
+.amount {
+  font-variant-numeric: tabular-nums;
+}