prime-ui-kit 0.9.0 → 0.9.2

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

@@ -1,56 +1,22 @@
-/* Layout for the Dropdown examples: layout only, text goes through Typography. */
+/* Layout of the Dropdown scenarios: semantic tokens only. */
 
-.row {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  justify-content: center;
-  gap: var(--prime-space-3);
-}
-
-/* Unstyled button around a Typography label that reads as a text link. */
-.linkTrigger {
-  padding: 0;
-  border: 0;
-  background: none;
-  cursor: pointer;
-}
-
-.underline {
-  text-decoration: underline;
-  text-underline-offset: var(--prime-space-1);
-}
-
-.linkTrigger:focus-visible {
-  outline: var(--prime-focus-width) solid var(--prime-color-focus-ring);
-  outline-offset: var(--prime-focus-offset);
-  border-radius: var(--prime-radius-xs);
-}
-
-.wideColumn {
+/* match-trigger-width.tsx: a column with a full-width button. */
+.column {
   display: flex;
   flex-direction: column;
   width: 100%;
   max-width: calc(var(--prime-space-24) * 3);
 }
 
-.toolbar {
+/* overview.tsx: a list row — the record on the left, its actions button at the end. */
+.row {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: var(--prime-space-3);
-  width: 100%;
-  max-width: calc(var(--prime-space-24) * 6);
-}
-
-.toolbarText {
-  display: flex;
-  flex-direction: column;
-  min-width: 0;
-}
-
-.toolbarActions {
-  display: flex;
-  flex-shrink: 0;
-  gap: var(--prime-space-2);
+  gap: var(--prime-space-4);
+  width: min(100%, calc(var(--prime-space-24) * 4));
+  padding-block: var(--prime-space-1);
+  padding-inline: var(--prime-space-4) var(--prime-space-1);
+  border-radius: var(--prime-radius-l);
+  background: var(--prime-color-card-bg);
 }

package/src/components/dropdown/examples/long-list.tsx

@@ -0,0 +1,42 @@
+/** More projects than fit: the grouped list scrolls inside the panel, capped by the room next to the trigger — `Dropdown.Group`. */
+import { Button, Dropdown } from "prime-ui-kit";
+
+const RECENT = ["Сайт компании", "Платёжный шлюз"];
+
+const PROJECTS = [
+  "Мобильное приложение",
+  "Личный кабинет",
+  "Админ-панель",
+  "Лендинг акции",
+  "Справочный центр",
+  "Внутренний портал",
+  "Аналитика продаж",
+  "CRM для партнёров",
+  "Бот поддержки",
+  "Дизайн-система",
+];
+
+export default function DropdownLongListExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Переместить в проект
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Group label="Недавние">
+          {RECENT.map((name) => (
+            <Dropdown.Item key={name}>{name}</Dropdown.Item>
+          ))}
+        </Dropdown.Group>
+        <Dropdown.Separator />
+        <Dropdown.Group label="Все проекты">
+          {PROJECTS.map((name) => (
+            <Dropdown.Item key={name}>{name}</Dropdown.Item>
+          ))}
+        </Dropdown.Group>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/dropdown/examples/{full-width.tsx → match-trigger-width.tsx}

@@ -1,17 +1,18 @@
-/** `sameMinWidthAsTrigger`: the menu is at least as wide as a full-width trigger. Use for full-width buttons in a column. */
+/** Under a full-width button the menu is at least as wide as the trigger — `matchTriggerWidth`. */
 import { Button, Dropdown } from "prime-ui-kit";
+
 import styles from "./examples.module.css";
 
-export default function DropdownFullWidthExample() {
+export default function DropdownMatchTriggerWidthExample() {
   return (
-    <div className={styles.wideColumn}>
+    <div className={styles.column}>
       <Dropdown.Root>
         <Dropdown.Trigger>
           <Button.Root variant="soft" tone="neutral" fullWidth>
             Экспортировать отчёт
           </Button.Root>
         </Dropdown.Trigger>
-        <Dropdown.Content sameMinWidthAsTrigger>
+        <Dropdown.Content matchTriggerWidth>
           <Dropdown.Item>PDF</Dropdown.Item>
           <Dropdown.Item>Excel (.xlsx)</Dropdown.Item>
           <Dropdown.Item>CSV</Dropdown.Item>

package/src/components/dropdown/examples/overview.tsx

@@ -0,0 +1,41 @@
+/** An icon-only button opens the row actions; picking an item runs it and closes the menu — `Dropdown.Item`, `onSelect`. */
+import { Button, Dropdown, Icon, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function DropdownOverviewExample() {
+  const [status, setStatus] = React.useState("Счёт № 4821 · черновик");
+
+  return (
+    <div className={styles.row}>
+      <Typography as="span" variant="body-m">
+        {status}
+      </Typography>
+      <Dropdown.Root>
+        <Dropdown.Trigger>
+          <Button.Root variant="ghost" tone="neutral" aria-label="Действия со счётом">
+            <Button.Icon>
+              <Icon name="action.more" />
+            </Button.Icon>
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content align="end">
+          <Dropdown.Item onSelect={() => setStatus("Счёт № 4821 · отправлен")}>
+            Отправить клиенту
+          </Dropdown.Item>
+          <Dropdown.Item onSelect={() => setStatus("Счёт № 4822 · копия")}>
+            Дублировать
+          </Dropdown.Item>
+          <Dropdown.Item onSelect={() => setStatus("Счёт № 4821 · скачан")}>
+            Скачать PDF
+          </Dropdown.Item>
+          <Dropdown.Separator />
+          <Dropdown.Item tone="danger" onSelect={() => setStatus("Счёт № 4821 · удалён")}>
+            Удалить счёт
+          </Dropdown.Item>
+        </Dropdown.Content>
+      </Dropdown.Root>
+    </div>
+  );
+}

package/src/components/dropdown/examples/placement.tsx

@@ -1,30 +1,33 @@
-/** `align` (start · center · end) and `side` (bottom · top). Near the viewport edge the panel flips and shifts automatically. */
+/** Every side and alignment relative to the trigger; near the viewport edge the menu flips and shifts — `side`, `align`. */
 import { Button, Dropdown } from "prime-ui-kit";
-import styles from "./examples.module.css";
 
 const PLACEMENTS = [
-  { label: "Начало", align: "start", side: "bottom" },
-  { label: "Центр", align: "center", side: "bottom" },
-  { label: "Конец", align: "end", side: "bottom" },
-  { label: "Сверху", align: "start", side: "top" },
+  { side: "bottom", align: "start" },
+  { side: "bottom", align: "center" },
+  { side: "bottom", align: "end" },
+  { side: "top", align: "start" },
+  { side: "top", align: "center" },
+  { side: "top", align: "end" },
+  { side: "left", align: "start" },
+  { side: "right", align: "start" },
 ] as const;
 
 export default function DropdownPlacementExample() {
   return (
-    <div className={styles.row}>
-      {PLACEMENTS.map(({ label, align, side }) => (
-        <Dropdown.Root key={label}>
+    <>
+      {PLACEMENTS.map(({ side, align }) => (
+        <Dropdown.Root key={`${side}-${align}`}>
           <Dropdown.Trigger>
-            <Button.Root variant="soft" tone="neutral" size="s">
-              {label}
+            <Button.Root variant="soft" tone="neutral">
+              {side} · {align}
             </Button.Root>
           </Dropdown.Trigger>
-          <Dropdown.Content align={align} side={side}>
+          <Dropdown.Content side={side} align={align}>
             <Dropdown.Item>Экспорт в PDF и печатная версия</Dropdown.Item>
             <Dropdown.Item>Дублировать в проект</Dropdown.Item>
           </Dropdown.Content>
         </Dropdown.Root>
       ))}
-    </div>
+    </>
   );
 }

package/src/components/dropdown/examples/sizes.tsx

@@ -1,40 +1,43 @@
-/** Dropdown.Content at every size tier xs → xl with icons, shortcuts and a danger item. Give the menu the same size as its trigger. */
-import { Copy, Pencil, Trash2 } from "lucide-react";
-import { Button, Dropdown } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** Every size tier with icons, key hints and a destructive item; the menu takes the tier of its trigger — `size`. */
+import { Button, Dropdown, Icon } from "prime-ui-kit";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function DropdownSizesExample() {
   return (
-    <div className={styles.row}>
+    <>
       {SIZES.map((size) => (
         <Dropdown.Root key={size}>
           <Dropdown.Trigger>
             <Button.Root variant="soft" tone="neutral" size={size}>
-              Размер {size}
+              {size}
             </Button.Root>
           </Dropdown.Trigger>
           <Dropdown.Content size={size}>
             <Dropdown.Item>
-              <Dropdown.ItemIcon as={Pencil} />
-              Переименовать
-              <Dropdown.ItemShortcut>F2</Dropdown.ItemShortcut>
-            </Dropdown.Item>
-            <Dropdown.Item>
-              <Dropdown.ItemIcon as={Copy} />
+              <Dropdown.ItemIcon>
+                <Icon name="action.copy" />
+              </Dropdown.ItemIcon>
               Дублировать
               <Dropdown.ItemShortcut>⌘D</Dropdown.ItemShortcut>
             </Dropdown.Item>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon>
+                <Icon name="action.download" />
+              </Dropdown.ItemIcon>
+              Скачать
+              <Dropdown.ItemShortcut>⌘S</Dropdown.ItemShortcut>
+            </Dropdown.Item>
             <Dropdown.Separator />
             <Dropdown.Item tone="danger">
-              <Dropdown.ItemIcon as={Trash2} />
+              <Dropdown.ItemIcon>
+                <Icon name="action.delete" />
+              </Dropdown.ItemIcon>
               Удалить
             </Dropdown.Item>
           </Dropdown.Content>
         </Dropdown.Root>
       ))}
-    </div>
+    </>
   );
 }

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

@@ -1,42 +1,34 @@
-/** A long grouped list that scrolls inside the panel, with a disabled row skipped by arrow keys. Use when a menu has more items than fit the panel max height. */
-import { Button, Dropdown } from "prime-ui-kit";
-
-const PROJECTS = [
-  "Сайт компании",
-  "Мобильное приложение",
-  "Личный кабинет",
-  "Админ-панель",
-  "Лендинг акции",
-  "Платёжный шлюз",
-  "Справочный центр",
-  "Внутренний портал",
-  "Аналитика продаж",
-  "CRM для партнёров",
-  "Бот поддержки",
-  "Дизайн-система",
-];
+/** A regular, a disabled and a destructive item; arrow keys skip the disabled one — `disabled`, `tone`. */
+import { Button, Dropdown, Icon } from "prime-ui-kit";
 
 export default function DropdownStatesExample() {
   return (
     <Dropdown.Root>
       <Dropdown.Trigger>
         <Button.Root variant="soft" tone="neutral">
-          Переместить в проект
+          Документ
         </Button.Root>
       </Dropdown.Trigger>
       <Dropdown.Content>
-        <Dropdown.Group>
-          <Dropdown.GroupLabel>Недавние</Dropdown.GroupLabel>
-          <Dropdown.Item>Сайт компании</Dropdown.Item>
-          <Dropdown.Item disabled>Архив 2023 — только чтение</Dropdown.Item>
-        </Dropdown.Group>
+        <Dropdown.Item>
+          <Dropdown.ItemIcon>
+            <Icon name="action.copy" />
+          </Dropdown.ItemIcon>
+          Дублировать
+        </Dropdown.Item>
+        <Dropdown.Item disabled>
+          <Dropdown.ItemIcon>
+            <Icon name="status.locked" />
+          </Dropdown.ItemIcon>
+          Архивировать — нет прав
+        </Dropdown.Item>
         <Dropdown.Separator />
-        <Dropdown.Group>
-          <Dropdown.GroupLabel>Все проекты</Dropdown.GroupLabel>
-          {PROJECTS.map((name) => (
-            <Dropdown.Item key={name}>{name}</Dropdown.Item>
-          ))}
-        </Dropdown.Group>
+        <Dropdown.Item tone="danger">
+          <Dropdown.ItemIcon>
+            <Icon name="action.delete" />
+          </Dropdown.ItemIcon>
+          Удалить
+        </Dropdown.Item>
       </Dropdown.Content>
     </Dropdown.Root>
   );

package/src/components/dropdown/examples/structure.tsx

@@ -0,0 +1,56 @@
+/** Optional parts of an account menu: a header with an avatar, a labelled group, item icons, key hints and separators — `Dropdown.Header`, `Dropdown.Group`, `Dropdown.ItemIcon`, `Dropdown.ItemShortcut`. */
+import { Avatar, Badge, Button, Dropdown, Icon } from "prime-ui-kit";
+
+export default function DropdownStructureExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Анна Петрова
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content align="end">
+        <Dropdown.Header>
+          <Avatar.Root size="l">
+            <Avatar.Fallback>АП</Avatar.Fallback>
+          </Avatar.Root>
+          <Dropdown.Title>Анна Петрова</Dropdown.Title>
+          <Dropdown.Description>anna.petrova@example.com</Dropdown.Description>
+          <Badge.Root color="purple" size="s">
+            PRO
+          </Badge.Root>
+        </Dropdown.Header>
+        <Dropdown.Separator />
+        <Dropdown.Group label="Аккаунт">
+          <Dropdown.Item>
+            <Dropdown.ItemIcon>
+              <Icon name="object.user" />
+            </Dropdown.ItemIcon>
+            Профиль
+            <Dropdown.ItemShortcut>⌘P</Dropdown.ItemShortcut>
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon>
+              <Icon name="action.settings" />
+            </Dropdown.ItemIcon>
+            Настройки
+            <Dropdown.ItemShortcut>⌘,</Dropdown.ItemShortcut>
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon>
+              <Icon name="object.book" />
+            </Dropdown.ItemIcon>
+            Руководство
+          </Dropdown.Item>
+        </Dropdown.Group>
+        <Dropdown.Separator />
+        <Dropdown.Item>
+          <Dropdown.ItemIcon>
+            <Icon name="action.logout" />
+          </Dropdown.ItemIcon>
+          Выйти
+        </Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/src/components/empty-page/COMPONENT.md

@@ -1,20 +1,20 @@
 # EmptyPage
 
-**Category:** feedback
+**Category:** status
+**Kind:** composite
 
-> Empty state of a page or a block: icon, title, explanation and an action.
+> Empty state of a page, a block or a menu: icon, title, explanation and an action.
 
 ## When to use
 - A list, table or page has no data yet (first run) and the user should know what to do.
-- A search or filter returned nothing.
+- A search or filter returned nothing (`layout="compact"` inside menus and lists).
 - Data failed to load and the user can retry.
 - Inside a card or data region that should keep its height (`layout="fill"`).
 
 ## When not to use
-- A short "no rows" line inside a table → use the [DataTable](../data-table/COMPONENT.md) `empty` slot.
 - A message about the page while data is present → use [Banner](../banner/COMPONENT.md).
 - A transient result of an action → use [Notification](../notification/COMPONENT.md).
-- Loading in progress → show a loading state, not an empty state.
+- Loading in progress → a [Skeleton](../skeleton/COMPONENT.md) of the content (a [Spinner](../spinner/COMPONENT.md) when there is no shape to hold), not an empty state; [Crossfade](../crossfade/COMPONENT.md) swaps it for the data or the empty state.
 
 ## Import
 ```tsx
@@ -23,121 +23,117 @@ import { EmptyPage } from "prime-ui-kit";
 
 ## Anatomy
 ```
-EmptyPage.Root              centered column, provides size to children
-├─ EmptyPage.Icon           rounded icon tile (tone)
-├─ EmptyPage.Title          <h2>
-├─ EmptyPage.Description    <p>, secondary text
-└─ EmptyPage.Actions        centered row of buttons
+EmptyPage.Root               centered column; size, layout
+├─ EmptyPage.Icon            tile with one icon; tone
+├─ EmptyPage.Title           <h2> (as)
+├─ EmptyPage.Description     <p>
+└─ EmptyPage.Actions         row of buttons
 ```
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### EmptyPage.Root
-`forwardRef` to `HTMLDivElement`. + native `<div>` props (`aria-labelledby`, `role`, …).
+`ref` → `HTMLDivElement`. A centered column: icon tile, title, description, actions; parts rise in one after another on first render.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Icon tile, type sizes and padding. Provided to children via the control-size context (pass it to Buttons explicitly). |
-| `layout` | `"default" \| "fill"` | `"default"` | `default`: compact block sized by content. `fill`: stretches over the height of a flex parent and centers the content. |
-| `className` | `string` | — | Class on the root. |
-| `children` | `ReactNode` | — | Parts. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Icon tile, title type and padding; given to the controls inside. |
+| `layout` | `"default" \| "fill" \| "compact"` | `"default"` | `default` sizes by content; `fill` stretches to the parent's height and centers; `compact` — a quiet state inside a menu or list: smaller text and icon, no entrance motion. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`status` in a filtered list), `aria-labelledby` and the other div attributes. |
 
 ### EmptyPage.Icon
-No ref. + native `<div>` props.
+`ref` → `HTMLDivElement`. A `<div>` tile holding one icon.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"neutral" \| "accent" \| "danger"` | `"neutral"` | Tile color. |
-| `children` | `ReactNode` | — | An svg icon (mark it `aria-hidden`); sized by the tier. |
-| `className` | `string` | — | Class. |
+| `tone` | `"neutral" \| "accent" \| "danger"` | `"neutral"` | `neutral` — no data yet, `accent` — a first run and a call to start, `danger` — a failed load. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the icon), `className` and the other div attributes. |
 
-### EmptyPage.Title
-`forwardRef` to `HTMLHeadingElement`. + native `<h2>` props. Semibold title capped at the reading width.
+### EmptyPage.Title · EmptyPage.Description
+`ref` → the element. `<h2>` (or `as`) and `<p>`, both capped at the reading width.
 
-### EmptyPage.Description
-`forwardRef` to `HTMLParagraphElement`. + native `<p>` props. Secondary text capped at the reading width.
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `as` | `"h2" \| "h3" \| "h4" \| "p"` | `"h2"` | Title: tag that fits the outline; the look does not change. `p` inside menus, lists and table cells. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `id` (for `aria-labelledby`), `className` and the other attributes. |
 
 ### EmptyPage.Actions
-No ref. + native `<div>` props. Wrapping centered row, gap `--prime-space-2`.
+`ref` → `HTMLDivElement`. A `<div>` row of buttons that wraps when narrow.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Buttons in the same `size`), `className` and the other div attributes. |
 
 ## Variants
 
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | Padding 24 × 12, tile 32 / icon 16, title 14/20, description 12/16 | Inside small cards, popovers | |
-| `s` | Padding 32 × 16, tile 40 / icon 20, title 14/20, description 13/20 | Cards, side panels, table regions | |
-| `m` | Padding 40 × 16, tile 48 / icon 24, title 16/24, description 14/20 | Sections and data regions | yes |
-| `l` | Padding 48 × 24, tile 56 / icon 24, title 18/24, description 14/20 | Large regions | |
-| `xl` | Padding 64 × 32, tile 64 / icon 32, title 20/28, description 16/24 | A whole empty page | |
+| `xs` · `s` | small tile, title-s, compact padding | inside cards, tables, side panels | |
+| `m` | 48px tile, title-m, body-m description | regions and pages | yes |
+| `l` · `xl` | large tile, title-l / heading-s, roomy padding | whole empty pages, onboarding | |
 
-### tone (EmptyPage.Icon)
+### layout
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `neutral` | `fill-muted` tile, secondary icon | No data / no results | yes |
-| `accent` | Accent soft tile, accent icon | First run, invitation to create something | |
-| `danger` | Danger soft tile, danger icon | Loading failed | |
+| `default` | sized by its content | most cases | yes |
+| `fill` | stretches to the parent's height, centered | a card or data region that keeps its height | |
+| `compact` | panel padding, body-s title, caption description, small tile, no entrance motion | menus, listboxes, command lists that filter to nothing | |
 
-### layout
+### tone (Icon)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `default` | Height by content | Standalone empty states | yes |
-| `fill` | Grows to fill a flex parent, content centered | Inside cards/regions with a fixed or min height | |
-
-**Combinations**
-- Recommended: `neutral` + "Сбросить фильтры" for no results; `accent` + a primary action for first run; `danger` + an outline "Повторить".
-- Hierarchy: at most one primary (solid) button, placed last; the rest outline/ghost.
-- Pointless: `layout="fill"` in a parent that is not a flex column with height.
+| `neutral` | muted tile | no data yet | yes |
+| `accent` | accent-soft tile | first run, a call to start | |
+| `danger` | danger-soft tile | failed to load | |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| size | `size` | `data-size` on Root |
-| fill | `layout="fill"` | `data-layout="fill"` on Root |
-| tone | Icon `tone` | `data-tone` on Icon |
+| first render | mount (not `compact`) | parts rise in (`enterMotion`), `--prime-motion-stagger` apart; collapses under reduced motion |
+| layout | `layout` | `data-layout="fill" \| "compact"` (none for `default`) |
+| size | `size` | `data-size`; controls inside get the same tier |
 
 ## Layout & spacing
-- Base gap `--prime-space-2`; icon → title gets `--prime-space-2` more; description → actions `--prime-space-3` more.
-- Text is centered and capped at `--prime-layout-reading-max-width`; long words wrap.
-- EmptyPage has no fill or radius of its own: the host card/region provides the surface.
+- Centered column, gap `--prime-space-2`; icon → title adds `--prime-space-2`, actions sit `--prime-space-3` lower.
+- Title and description are capped at the reading width; actions wrap.
+- Pass the same `size` to the buttons in Actions.
 
 ## Accessibility
-- Give the title an `id` and the root `aria-labelledby` so the region is named.
-- Mark the icon `aria-hidden`; the title carries the meaning.
-- Title is an `<h2>`: make sure it fits the page heading outline.
-- EmptyPage has no `labels`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [data-region.tsx](examples/data-region.tsx) | Card region with a header and `layout="fill"`, accent icon, two actions | Empty list/table area |
-| [no-results.tsx](examples/no-results.tsx) | Search with no results: Icon, Title, Description, Actions | Filters/queries returning nothing |
-| [icon-tones.tsx](examples/icon-tones.tsx) | `neutral`, `accent`, `danger` icon tones | Choosing the tone by cause |
-| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl` with a button of the same size | Picking a size |
+### Keyboard
+No keyboard interaction.
 
-```tsx
-import { Button, EmptyPage } from "prime-ui-kit";
-
-export function NoInvoices() {
-  return (
-    <EmptyPage.Root aria-labelledby="no-invoices-title">
-      <EmptyPage.Title id="no-invoices-title">Счетов нет</EmptyPage.Title>
-      <EmptyPage.Description>Выставленные счета появятся здесь.</EmptyPage.Description>
-      <EmptyPage.Actions>
-        <Button.Root>Выставить счёт</Button.Root>
-      </EmptyPage.Actions>
-    </EmptyPage.Root>
-  );
-}
-```
+### ARIA
+- The title is an `<h2>` (`as` picks `h3` / `h4` by the outline, `p` inside menus, lists and table cells); link the root to it with `aria-labelledby` when the empty state replaces a whole region.
+- In a filtered menu or list set `role="status"`, so screen readers announce «Ничего не найдено».
+- The icon is decorative: pass it with `aria-hidden`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | An empty search result: icon, title, description and two actions — `EmptyPage.Icon`, `EmptyPage.Actions`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier changes the icon tile, the title and the padding; buttons in Actions take the same size — `size`. |
+| [icon-tones.tsx](examples/icon-tones.tsx) | The tile tone tells why the area is empty: no data yet, a first run, or a failed load — `tone`. |
+| [data-region.tsx](examples/data-region.tsx) | An empty data region: the empty state stretches over the rest of a card with a header — `layout`. |
+| [compact.tsx](examples/compact.tsx) | The quiet empty state of a search panel: no entrance motion, smaller text, a paragraph title, one action — `layout`, `as`. |
+| [narrow.tsx](examples/narrow.tsx) | In a 320 px side panel the text wraps under the tile and the actions wrap to a second line. |
 
 ## Mistakes
 - Buttons in a non-`m` EmptyPage without `size` → pass the same `size` to them.
 - `tone` on `EmptyPage.Root` → `tone` belongs to `EmptyPage.Icon`.
 - Showing an empty state while data is loading → show loading first.
 - Several primary buttons → one primary, placed last.
+- A default empty state inside a menu → use `layout="compact"`; the entrance motion on every keystroke is noise.
+- An `<h2>` title inside a menu, listbox or table cell → `EmptyPage.Title as="p"`.
 
 ## Related
-- [DataTable](../data-table/COMPONENT.md) — built-in `empty` slot for tables.
-- [Banner](../banner/COMPONENT.md), [Notification](../notification/COMPONENT.md).
-- [Card](../card/COMPONENT.md) — host surface for data regions.
+- **Built from:** —
+- **See also:** [DataTable](../data-table/COMPONENT.md), [Banner](../banner/COMPONENT.md), [Notification](../notification/COMPONENT.md), [Card](../card/COMPONENT.md)