prime-ui-kit 0.14.0 → 0.15.0

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

@@ -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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/components/checkbox/examples/indicator.tsx

@@ -4,10 +4,11 @@ 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. */
@@ -24,10 +25,14 @@ export default function CheckboxIndicatorExample() {
   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
@@ -53,19 +58,20 @@ export default function CheckboxIndicatorExample() {
             }}
             role="option"
             aria-selected={isSelected}
+            aria-disabled={city.disabled || undefined}
             tabIndex={index === active ? 0 : -1}
             className={styles.option}
             onFocus={() => setActive(index)}
-            onClick={() => toggle(city.value)}
+            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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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 |
 |---|---|---|---|
@@ -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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/components/crossfade/examples/screen.tsx

@@ -0,0 +1,197 @@
+/** 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`. */
+import {
+  AppHeader,
+  Banner,
+  Button,
+  Card,
+  Crossfade,
+  DataTable,
+  type DataTableColumn,
+  EmptyPage,
+  Icon,
+  PageContent,
+  Skeleton,
+  Typography,
+  useNotifications,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./screen.module.css";
+
+type Status = "error" | "loading" | "ready";
+type Payment = { id: string; payer: string; purpose: string; amount: number };
+
+const PAYMENTS: Payment[] = [
+  { id: "b1", payer: "ООО «Гранит»", purpose: "Оплата по сч. 2026-0414", amount: 94_750 },
+  { id: "b2", payer: "ИП Орлов Д. С.", purpose: "Предоплата за обучение", amount: 18_000 },
+  { id: "b3", payer: "АО «Альфа Медиа»", purpose: "Без указания счёта", amount: 380_000 },
+];
+
+const ACCOUNTS = [
+  { name: "Т-Банк, расчётный", balance: "4 812 300 ₽" },
+  { name: "Сбербанк, расчётный", balance: "1 207 950 ₽" },
+];
+
+const MONEY = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+const COLUMNS: DataTableColumn<Payment>[] = [
+  { id: "payer", header: "Плательщик", accessor: "payer" },
+  { id: "purpose", header: "Назначение", accessor: "purpose" },
+  {
+    id: "amount",
+    header: "Сумма",
+    numeric: true,
+    headerAlign: "end",
+    cell: (row) => MONEY.format(row.amount),
+  },
+];
+
+export default function CrossfadeScreenExample() {
+  const { notify } = useNotifications();
+  const [status, setStatus] = React.useState<Status>("error");
+
+  const retry = () => {
+    setStatus("loading");
+    window.setTimeout(() => {
+      setStatus("ready");
+      notify({
+        tone: "success",
+        title: "Выписка получена",
+        description: "3 платежа ждут разнесения",
+      });
+    }, 1500);
+  };
+
+  return (
+    <>
+      {/* The header carries the page: the only h1 and a line of data, here the date of the last
+          statement — it moves on once the statement arrives. Main has no PageContent.Header. */}
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <AppHeader.Title>
+            Сверка с банком
+            <AppHeader.Description>
+              2 счёта · выписка на {status === "ready" ? "7" : "6"} октября
+            </AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+      </AppHeader.Root>
+
+      <PageContent.Root>
+        <PageContent.Body>
+          {/* The page banner and the panels are one block: the banner, with the 40 below it, comes and
+            goes inside a Crossfade, so the panels glide instead of jumping. */}
+          <div className={styles.lead}>
+            <Crossfade state={status === "error" ? "error" : "ok"}>
+              {status === "error" ? (
+                <div className={styles.bannerSlot}>
+                  <Banner.Root tone="danger">
+                    <Banner.Content>
+                      <Banner.Icon>
+                        <Icon name="status.danger" />
+                      </Banner.Icon>
+                      <Banner.Title>Выписка за 7 октября не получена</Banner.Title>
+                      <Banner.Description>
+                        Т-Банк не ответил на запрос. Остатки показаны на 6 октября.
+                      </Banner.Description>
+                      <Banner.Actions>
+                        <Button.Root tone="danger" onClick={retry}>
+                          Повторить
+                        </Button.Root>
+                      </Banner.Actions>
+                    </Banner.Content>
+                  </Banner.Root>
+                </div>
+              ) : null}
+            </Crossfade>
+
+            <PageContent.Grid>
+              <PageContent.Cell span={6}>
+                <Card.Root variant="panel" aria-busy={status === "loading"}>
+                  <Card.Header>
+                    <Card.Title as="h2">Остатки</Card.Title>
+                    <Typography as="span" variant="caption" tone="muted">
+                      {status === "ready" ? "на 7 октября" : "на 6 октября"}
+                    </Typography>
+                  </Card.Header>
+                  <Card.Body>
+                    {/* Loading ↔ data cross-fade in place; the table below swaps its body the same way. */}
+                    <Crossfade state={status === "loading" ? "loading" : "ready"}>
+                      {status === "loading" ? (
+                        <ul className={styles.accounts}>
+                          {ACCOUNTS.map((account) => (
+                            <li key={account.name} className={styles.account}>
+                              <Skeleton className={styles.nameBar} />
+                              {/* title-m is the l text tier: 16 / 24. */}
+                              <Skeleton size="l" className={styles.balanceBar} />
+                            </li>
+                          ))}
+                        </ul>
+                      ) : (
+                        <ul className={styles.accounts}>
+                          {ACCOUNTS.map((account) => (
+                            <li key={account.name} className={styles.account}>
+                              <Typography as="span" variant="body-m" tone="secondary">
+                                {account.name}
+                              </Typography>
+                              <Typography as="span" variant="title-m" className={styles.amount}>
+                                {account.balance}
+                              </Typography>
+                            </li>
+                          ))}
+                        </ul>
+                      )}
+                    </Crossfade>
+                  </Card.Body>
+                </Card.Root>
+              </PageContent.Cell>
+
+              <PageContent.Cell span={6}>
+                <Card.Root variant="panel">
+                  <Card.Header>
+                    <Card.Title as="h2">Правила разнесения</Card.Title>
+                  </Card.Header>
+                  <Card.Body>
+                    <EmptyPage.Root size="s" aria-labelledby="rules-empty">
+                      <EmptyPage.Icon tone="accent">
+                        <Icon name="action.filter" />
+                      </EmptyPage.Icon>
+                      <EmptyPage.Title as="h3" id="rules-empty">
+                        Правил пока нет
+                      </EmptyPage.Title>
+                      <EmptyPage.Description>
+                        Правило свяжет платёж со счётом по ИНН или назначению.
+                      </EmptyPage.Description>
+                      <EmptyPage.Actions>
+                        <Button.Root variant="soft" tone="neutral">
+                          Создать правило
+                        </Button.Root>
+                      </EmptyPage.Actions>
+                    </EmptyPage.Root>
+                  </Card.Body>
+                </Card.Root>
+              </PageContent.Cell>
+            </PageContent.Grid>
+          </div>
+
+          <PageContent.Section label="Неразнесённые платежи">
+            <DataTable
+              columns={COLUMNS}
+              rows={status === "ready" ? PAYMENTS : []}
+              getRowKey={(row) => row.id}
+              paging="none"
+              loading={status === "loading"}
+              loadingRows={3}
+              error={status === "error" ? "Платежи появятся после загрузки выписки" : undefined}
+              empty="Все платежи разнесены"
+            />
+          </PageContent.Section>
+        </PageContent.Body>
+      </PageContent.Root>
+    </>
+  );
+}