prime-ui-kit 0.15.0 → 0.17.0

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

@@ -10,34 +10,39 @@ const SIZES = [
 
 export default function DrawerSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map(({ size, width }) => (
-        <Drawer.Root key={size}>
-          <Drawer.Trigger>
-            <Button.Root variant="soft" tone="neutral">
-              {size}
-            </Button.Root>
-          </Drawer.Trigger>
-          <Drawer.Content size={size}>
-            <Drawer.Header>
-              <Drawer.Title>Детали заказа</Drawer.Title>
-              <Drawer.Description>Ширина панели {width}</Drawer.Description>
-            </Drawer.Header>
-            <Drawer.Body>
-              <Typography variant="body-m" tone="secondary">
-                На экране уже 640 px панель занимает всю ширину и теряет скругления.
-              </Typography>
-            </Drawer.Body>
-            <Drawer.Footer>
-              <Drawer.Close>
-                <Button.Root variant="outline" tone="neutral">
-                  Закрыть
-                </Button.Root>
-              </Drawer.Close>
-            </Drawer.Footer>
-          </Drawer.Content>
-        </Drawer.Root>
+        <div key={size}>
+          <Drawer.Root>
+            <Drawer.Trigger>
+              <Button.Root variant="soft" tone="neutral">
+                Детали заказа
+              </Button.Root>
+            </Drawer.Trigger>
+            <Drawer.Content size={size}>
+              <Drawer.Header>
+                <Drawer.Title>Детали заказа</Drawer.Title>
+                <Drawer.Description>Ширина панели {width}</Drawer.Description>
+              </Drawer.Header>
+              <Drawer.Body>
+                <Typography variant="body-m" tone="secondary">
+                  На экране уже 640 px панель занимает всю ширину и теряет скругления.
+                </Typography>
+              </Drawer.Body>
+              <Drawer.Footer>
+                <Drawer.Close>
+                  <Button.Root variant="outline" tone="neutral">
+                    Закрыть
+                  </Button.Root>
+                </Drawer.Close>
+              </Drawer.Footer>
+            </Drawer.Content>
+          </Drawer.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
       ))}
-    </>
+    </div>
   );
 }

package/src/components/dropdown/COMPONENT.md

@@ -7,7 +7,7 @@
 
 ## When to use
 - Secondary actions of a card, row or document behind a «⋯» or labelled button.
-- An account / user menu in the app header.
+- An account / user menu behind the Sidebar account row (`Sidebar.Account`).
 - A short list of commands (export formats, move to project) where picking one runs an action.
 
 ## When not to use
@@ -25,7 +25,8 @@ import { Dropdown } from "prime-ui-kit";
 ## Anatomy
 ```
 Dropdown.Root                     state and dismiss policy (no DOM)
-├── Dropdown.Trigger              clones its child; toggles the menu
+├── Dropdown.Trigger              clones its child; toggles the menu, opens it on the arrow keys
+├── Dropdown.Anchor               instead of Trigger: the row or list a context menu opens at (anchorPoint)
 └── Dropdown.Content              portaled role="menu" on the floating surface, scrolls
     ├── Dropdown.Header           non-interactive row: [avatar] [Title + Description] [badge]
     │   ├── Dropdown.Title
@@ -54,60 +55,81 @@ No DOM, no ref. Open state and dismiss policy.
 | `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, item pick, Escape, outside press, code. |
 | `closeOnOutsideClick` | `boolean` | `true` | A pointerdown outside the menu and its trigger closes it; focus follows the pointer. |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the menu and returns focus to the trigger. |
-| `children` | `ReactNode` | — (required) | Trigger and Content. |
+| `anchorPoint` | `{ x: number; y: number } \| null` | `null` | A point inside the trigger or `Dropdown.Anchor` (px from its top-left corner) the menu opens at: a context menu at the pointer. It moves with the element on scroll. |
+| `children` | `ReactNode` | — (required) | Trigger (or Anchor) and Content. |
 
-### Dropdown.Trigger
-No DOM: clones the single child, merges `ref` and `onClick`; toggles the menu and sets its ARIA.
+### Dropdown.Trigger · Dropdown.Anchor
+No DOM: clone the single child and merge `ref`. Trigger toggles the menu on a click, opens it on the arrow keys and sets its ARIA; Anchor only places the menu (a context menu with `anchorPoint`, opened through `open`) and names it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactElement` | — (required) | One element, usually a Button. |
+| `children` | `ReactElement` | — (required) | One element: usually a Button (Anchor: the row or list the context menu belongs to). |
 
 ### Dropdown.Content
-`ref` → `HTMLDivElement`. Portal + `role="menu"` floating panel that scrolls inside, named by the trigger; focus moves to the first item. Below 640px of viewport it is a bottom sheet.
+`ref` → `HTMLDivElement`. Portal + `role="menu"` floating panel that scrolls inside, named by the control it opened from; focus moves to the first enabled item. Below 640px of viewport it is a bottom sheet.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Preferred side; flips to the opposite side when there is no room. |
 | `align` | `"auto" \| "start" \| "center" \| "end"` | `"auto"` | Alignment along the trigger. `auto` lines the menu up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix the edge. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Row tier: item height, text and icon; key hints one tier down. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Row tier: item height, text and icon; key hints one tier down. The menu's own: it does not follow the trigger's size. |
 | `matchTriggerWidth` | `boolean` | `false` | The menu is at least as wide as the trigger. |
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "role">` | — | `className`, `onKeyDown` (runs before the arrow-key navigation) and the other attributes of the menu. |
 
 ### Dropdown.Item
-`ref` → `HTMLButtonElement` (or the `asChild` element). A `<button role="menuitem">`; a click, Enter or Space runs `onSelect` and closes the menu. + native button props.
+`ref` → `HTMLButtonElement` (or the `asChild` element). A `<button role="menuitem">`, no tab stop of its own (`tabIndex -1`, the arrow keys move between items); a click, Enter or Space runs `onSelect` and closes the menu.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `onSelect` | `() => void` | — | The action of the item. |
-| `disabled` | `boolean` | `false` | Muted, `aria-disabled`, skipped by the arrow keys, does nothing on click. |
+| `disabled` | `boolean` | `false` | Muted and `disabled` (a link item: `aria-disabled`), skipped by the arrow keys; no handler runs, the item's own `onClick` included. |
 | `tone` | `"neutral" \| "danger"` | `"neutral"` | `danger`: destructive action — danger text, icon and hover fill. |
 | `asChild` | `boolean` | `false` | The item is its single child link (`<a href>`, a router `Link`), so Cmd / Ctrl-click and «open in a new tab» work; the pick still closes the menu. |
 | `children` | `ReactNode` | — | `Dropdown.ItemIcon`, the label, `Dropdown.ItemDescription`, `Dropdown.ItemShortcut`; with `asChild` one link element holding them. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "role" \| "onSelect">` | — | `className`, `onClick` (runs before `onSelect`; `preventDefault()` keeps the menu open) and the other attributes of the item. |
 
 ### Dropdown.CheckboxItem
-`ref` → `HTMLButtonElement`. A `<button role="menuitemcheckbox">` with `aria-checked` and a check mark at the end while checked; a click, Enter or Space toggles it and the menu stays open. + native button props.
+`ref` → `HTMLButtonElement`. A `<button role="menuitemcheckbox">` with `aria-checked` and a check mark at the end while checked; a click, Enter or Space toggles it and the menu stays open.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `checked` | `boolean` | — | Checked state (controlled). |
 | `defaultChecked` | `boolean` | `false` | Initial state (uncontrolled). |
 | `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state. |
-| `disabled` | `boolean` | `false` | Muted, `aria-disabled`, skipped by the arrow keys, does not toggle. |
+| `disabled` | `boolean` | `false` | Muted and `disabled`, skipped by the arrow keys; no handler runs, the item's own `onClick` included. |
 | `children` | `ReactNode` | — | The label (optionally after a `Dropdown.ItemIcon`). |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "role" \| "onSelect" \| "onChange" \| "defaultChecked">` | — | `className`, `onClick` (runs before the toggle; `preventDefault()` skips it) and the other attributes of the item. |
 
 ### Dropdown.ItemDescription
-`ref` → `HTMLSpanElement`. A muted second line under the item label: what the action does, or why a disabled item is unavailable. Describes the item for assistive tech. + native `<span>` props except `id`.
+`ref` → `HTMLSpanElement`. A muted second line under the item label: what the action does, or why a disabled item is unavailable. Describes the item for assistive tech.
 
-### Dropdown.ItemIcon · Dropdown.ItemShortcut
-`ref` → `HTMLSpanElement` / `HTMLElement` (the `<kbd>`). The `aria-hidden` leading glyph at the menu icon size / a `Kbd` key hint at the end of the item — a hint, not a handler. + native props.
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The sentence; it wraps inside the menu's width. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "id">` | — | `className` and the other attributes except `id` (the item points at it). |
+
+### Dropdown.ItemIcon
+`ref` → `HTMLSpanElement`. The `aria-hidden` leading glyph of an item at the menu icon size.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className`, `children` (the glyph) and the other attributes. |
+
+### Dropdown.ItemShortcut
+`ref` → `HTMLElement` (the `<kbd>`). A `Kbd` key hint at the end of the item, one tier below the menu — a hint, not a handler.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The keys («⌘D»). |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "children">` | — | `className` and the other attributes of the `<kbd>`. |
 
 ### Dropdown.Group
-`ref` → `HTMLDivElement`. `<div role="group">` named by its visible `label`. + native `<div>` props.
+`ref` → `HTMLDivElement`. `<div role="group">` named by its visible `label`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `children` (the items) and the other attributes of the group. |
 
 ### Dropdown.Separator
 `ref` → `HTMLDivElement`. A full-bleed Divider between items or groups.
@@ -117,7 +139,11 @@ No DOM: clones the single child, merges `ref` and `onClick`; toggles the menu an
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the divider. |
 
 ### Dropdown.Header · Dropdown.Title · Dropdown.Description
-`ref` → `HTMLDivElement`. A non-interactive row at the top (who is signed in, the plan): an avatar, Title + Description in one column, a trailing badge or button. + native `<div>` props.
+`ref` → `HTMLDivElement`. A non-interactive row at the top (who is signed in, the plan): an avatar, Title + Description in one column, a trailing badge or button.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `children` and the other attributes of the `<div>`. |
 
 ## Variants
 The panel is the shared floating surface: the floating layer of the ladder (`data-depth="floating"`), `--prime-panel-radius` (12), padding 4, `shadow-overlay`; rows have radius 8 and the tier item height.
@@ -154,20 +180,22 @@ The panel is the shared floating surface: the floating layer of the ladder (`dat
 | `disabled` (Item) | Disabled text, skipped by arrows | Not allowed right now (say why in `Dropdown.ItemDescription`) | `false` |
 | `matchTriggerWidth` | Menu at least as wide as the trigger | Full-width buttons | `false` |
 | `closeOnOutsideClick={false}` · `closeOnEscape={false}` | Stays open until an item is picked | A required choice in an onboarding step | |
+| `anchorPoint` (Root) | The menu opens at a point inside the trigger or `Dropdown.Anchor` | A context menu at the pointer over a row or a list | `null` |
 
-**Combinations** — menu `size` = trigger `size`. Destructive items go last, after a separator. Key hints only for shortcuts the app really handles.
+**Combinations** — `size` is the menu's own, set on `Dropdown.Content`; match it to the trigger by hand when they stand together. Destructive items go last, after a separator. Key hints only for shortcuts the app really handles. A context menu: `Dropdown.Anchor` around the row, `anchorPoint` from the `contextmenu` event, `open` driven by it.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state` on the menu (closed while the exit animation plays) and on the trigger, `aria-expanded` on the trigger |
+| dismiss | `closeOnEscape`, `closeOnOutsideClick` (both default `true`) | Escape and a press outside close the menu; `false` turns that way off |
 | side | `side` and the room next to the trigger | `data-side` (resolved) |
 | size | `size` on Content | `data-size` |
 | item hover / focus | a hovering pointer, arrow keys | subtle fill (danger-soft for `danger`), no movement; a tap leaves no hover fill |
-| item disabled | `disabled` | `aria-disabled="true"`, `data-disabled="true"` |
+| item disabled | `disabled` | native `disabled` (a link item `aria-disabled="true"`), `data-disabled="true"`; no handler runs |
 | item tone | `tone` | `data-tone` |
 | item checked | `checked` / `defaultChecked` / `onCheckedChange` on `Dropdown.CheckboxItem` | `aria-checked`; an accent check mark at the end while checked, nothing while not |
-| sheet | viewport below 640px | a scrim and a full-width bottom sheet with an `aria-hidden` grab handle around the menu; the sheet carries `data-state`, the menu keeps its role and ref; page scroll locked; a swipe down from the handle closes it (with `closeOnOutsideClick`) |
+| sheet | a phone viewport | a scrim and a full-width bottom sheet around the menu; the sheet carries `data-state`, the menu `data-sheet` and keeps its role and ref; page scroll locked; with `closeOnOutsideClick` an `aria-hidden` grab handle, and a swipe down from it closes the sheet |
 
 Motion (`overlayMotion`): the menu grows out of the side that faces its trigger and fades, in and out over `fast`; as a sheet it slides up over `slow` and down over `base`. Content stays mounted until the exit ends; under `prefers-reduced-motion` it unmounts at once.
 
@@ -183,17 +211,21 @@ Motion (`overlayMotion`): the menu grows out of the side that faces its trigger
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Enter` · `Space` | On the trigger opens the menu (focus on the first item); on an item runs it and returns focus to the trigger; on a checkbox item toggles it and the menu stays open. |
-| `ArrowDown` · `ArrowUp` | Move focus to the next / previous enabled item, wrapping. |
+| `ArrowDown` · `ArrowUp` | On the trigger open the menu at its first item; in the menu move focus to the next / previous enabled item, wrapping. |
 | `Home` · `End` | First / last enabled item. |
 | `Escape` | Closes the menu (`closeOnEscape`); focus returns to the trigger. |
 | `Tab` · `Shift+Tab` | Closes the menu; focus returns to the trigger (Tab then goes on to the next stop). |
 
 ### ARIA
-- The menu is `role="menu"` named by the trigger; items are `role="menuitem"`, checkbox items `role="menuitemcheckbox"` with `aria-checked`, disabled ones `aria-disabled`.
-- The trigger gets `aria-haspopup="menu"`, `aria-expanded`, `aria-controls` and `data-state`; the child's own `id` wins. Other props given to `Dropdown.Trigger` (handlers, ARIA, `ref`) reach the child, so a wrapping `Tooltip.Trigger` keeps working.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- The menu is `role="menu"` named by the control it opened from (the trigger, or the control inside `Dropdown.Anchor`), read from the page; items are `role="menuitem"`, checkbox items `role="menuitemcheckbox"` with `aria-checked`, disabled ones `disabled`. Items are no tab stops: one Tab leaves the menu.
+- The trigger gets `aria-haspopup="menu"`, `aria-expanded`, `data-state` and, while open, `aria-controls`; the child's own `id` wins. Other props given to `Dropdown.Trigger` (handlers, ARIA, `ref`) reach the child, so a wrapping `Tooltip.Trigger` keeps working.
 - With a `Dropdown.ItemDescription` the label names the item (`aria-labelledby`) and the description describes it (`aria-describedby`).
 - An `asChild` item merges its props onto the link; the link's children are the item content. A disabled link item gets `aria-disabled` and its click is stopped.
 - `Dropdown.Group` is `role="group"` named by its `label`.
@@ -210,11 +242,12 @@ No `labels`.
 |---|---|
 | [overview.tsx](examples/overview.tsx) | An icon-only button opens the row actions; picking an item runs it and closes the menu — `Dropdown.Item`, `onSelect`. |
 | [structure.tsx](examples/structure.tsx) | 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`. |
-| [sizes.tsx](examples/sizes.tsx) | Every size tier with icons, key hints and a destructive item; the menu takes the tier of its trigger — `size`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier with icons, key hints and a destructive item; the tier is the menu's own, set on `Dropdown.Content`, not taken from its trigger — `size`. |
 | [placement.tsx](examples/placement.tsx) | Every side and alignment relative to the trigger; near the viewport edge the menu flips and shifts — `side`, `align`. |
 | [states.tsx](examples/states.tsx) | A regular, a disabled and a destructive item; arrow keys skip the disabled one — `disabled`, `tone`. |
 | [item-description.tsx](examples/item-description.tsx) | A second line under an item: what an action does, and why a disabled one is unavailable, readable by everyone and read with the item — `Dropdown.ItemDescription`. |
 | [link-items.tsx](examples/link-items.tsx) | Items that navigate are real links: Cmd-click or the context menu opens them in a new tab, a plain pick closes the menu — `asChild`. |
+| [context-menu.tsx](examples/context-menu.tsx) | A right-click on a deal opens its menu at the pointer, and Escape or a pick returns focus to that row — `anchorPoint`, `Dropdown.Anchor`. |
 | [match-trigger-width.tsx](examples/match-trigger-width.tsx) | Under a full-width button the menu is at least as wide as the trigger — `matchTriggerWidth`. |
 | [checkbox-items.tsx](examples/checkbox-items.tsx) | A column chooser: toggles in the menu keep it open, the key column cannot be hidden — `Dropdown.CheckboxItem`, `checked`, `onCheckedChange`. |
 | [long-list.tsx](examples/long-list.tsx) | More projects than fit: the grouped list scrolls inside the panel, capped by the room next to the trigger — `Dropdown.Group`. |
@@ -229,6 +262,8 @@ No `labels`.
 - A destructive item without `tone="danger"`, or in the middle of the list → mark it and put it last.
 - A Tooltip on a disabled item to say why → keyboard and touch users never see it; put the reason in `Dropdown.ItemDescription`.
 - `onSelect={() => navigate(url)}` for an item that opens a page → `asChild` with a link, so Cmd-click and a new tab work.
+- A hidden button placed at the pointer to anchor a context menu → `Dropdown.Anchor` around the row and `anchorPoint` from the `contextmenu` event.
+- Expecting the menu to take the trigger's `size` → it has its own; set `size` on `Dropdown.Content`.
 
 ## Related
 - **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (the menu), [Kbd](../kbd/COMPONENT.md) (`ItemShortcut`), [Divider](../divider/COMPONENT.md) (`Separator`), `Icon` (`action.check` of `CheckboxItem`)

package/src/components/dropdown/examples/context-menu.tsx

@@ -0,0 +1,75 @@
+/** A right-click on a deal opens its menu at the pointer, and Escape or a pick returns focus to that row — `anchorPoint`, `Dropdown.Anchor`. */
+import { Card, Dropdown, Icon, List } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const DEALS = [
+  { id: "d-1042", title: "Поставка оборудования", client: "ООО «Гранит»" },
+  { id: "d-1043", title: "Годовое обслуживание", client: "АО «Северсталь-Сервис»" },
+  { id: "d-1044", title: "Пилотный проект", client: "ИП Козлов" },
+];
+
+export default function DropdownContextMenuExample() {
+  const [menu, setMenu] = React.useState<{ id: string; x: number; y: number } | null>(null);
+
+  return (
+    <Card.Root className={styles.column}>
+      <Card.Body>
+        <List.Root aria-label="Сделки">
+          {DEALS.map((deal) => {
+            const open = menu?.id === deal.id;
+            return (
+              <Dropdown.Root
+                key={deal.id}
+                open={open}
+                onOpenChange={(next) => {
+                  if (!next) setMenu(null);
+                }}
+                anchorPoint={open ? menu : null}
+              >
+                <Dropdown.Anchor>
+                  <List.Item
+                    onContextMenu={(event) => {
+                      event.preventDefault();
+                      const box = event.currentTarget.getBoundingClientRect();
+                      setMenu({
+                        id: deal.id,
+                        x: event.clientX - box.left,
+                        y: event.clientY - box.top,
+                      });
+                    }}
+                  >
+                    <List.ItemText>{deal.title}</List.ItemText>
+                    <List.ItemDescription>{deal.client}</List.ItemDescription>
+                  </List.Item>
+                </Dropdown.Anchor>
+                <Dropdown.Content>
+                  <Dropdown.Item>
+                    <Dropdown.ItemIcon>
+                      <Icon name="action.edit" />
+                    </Dropdown.ItemIcon>
+                    Переименовать
+                  </Dropdown.Item>
+                  <Dropdown.Item>
+                    <Dropdown.ItemIcon>
+                      <Icon name="action.copy" />
+                    </Dropdown.ItemIcon>
+                    Дублировать
+                  </Dropdown.Item>
+                  <Dropdown.Separator />
+                  <Dropdown.Item tone="danger">
+                    <Dropdown.ItemIcon>
+                      <Icon name="action.delete" />
+                    </Dropdown.ItemIcon>
+                    Удалить
+                  </Dropdown.Item>
+                </Dropdown.Content>
+              </Dropdown.Root>
+            );
+          })}
+        </List.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

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

@@ -1,6 +1,6 @@
 /* Layout of the Dropdown scenarios: semantic tokens only. */
 
-/* match-trigger-width.tsx: a column with a full-width button. */
+/* match-trigger-width.tsx, context-menu.tsx: a column of a full-width button or of rows. */
 .column {
   display: flex;
   flex-direction: column;

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

@@ -1,43 +1,48 @@
-/** 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";
+/** Every size tier with icons, key hints and a destructive item; the tier is the menu's own, set on `Dropdown.Content`, not taken from its trigger — `size`. */
+import { Button, Dropdown, Icon, Typography } from "prime-ui-kit";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function DropdownSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <Dropdown.Root key={size}>
-          <Dropdown.Trigger>
-            <Button.Root variant="soft" tone="neutral" size={size}>
-              {size}
-            </Button.Root>
-          </Dropdown.Trigger>
-          <Dropdown.Content size={size}>
-            <Dropdown.Item>
-              <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>
-                <Icon name="action.delete" />
-              </Dropdown.ItemIcon>
-              Удалить
-            </Dropdown.Item>
-          </Dropdown.Content>
-        </Dropdown.Root>
+        <div key={size}>
+          <Dropdown.Root>
+            <Dropdown.Trigger>
+              <Button.Root variant="soft" tone="neutral" size={size}>
+                Документ
+              </Button.Root>
+            </Dropdown.Trigger>
+            <Dropdown.Content size={size}>
+              <Dropdown.Item>
+                <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>
+                  <Icon name="action.delete" />
+                </Dropdown.ItemIcon>
+                Удалить
+              </Dropdown.Item>
+            </Dropdown.Content>
+          </Dropdown.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
       ))}
-    </>
+    </div>
   );
 }

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

@@ -1,35 +1,43 @@
 /** A regular, a disabled and a destructive item; arrow keys skip the disabled one — `disabled`, `tone`. */
-import { Button, Dropdown, Icon } from "prime-ui-kit";
+import { Button, Dropdown, Icon, Typography } 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.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.Item tone="danger">
-          <Dropdown.ItemIcon>
-            <Icon name="action.delete" />
-          </Dropdown.ItemIcon>
-          Удалить
-        </Dropdown.Item>
-      </Dropdown.Content>
-    </Dropdown.Root>
+    <div>
+      <div>
+        <Dropdown.Root>
+          <Dropdown.Trigger>
+            <Button.Root variant="soft" tone="neutral">
+              Документ
+            </Button.Root>
+          </Dropdown.Trigger>
+          <Dropdown.Content>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon>
+                <Icon name="action.copy" />
+              </Dropdown.ItemIcon>
+              Дублировать
+            </Dropdown.Item>
+            <Dropdown.Item disabled>
+              <Dropdown.ItemIcon>
+                <Icon name="status.locked" />
+              </Dropdown.ItemIcon>
+              Архивировать
+              <Dropdown.ItemDescription>Доступно владельцу документа</Dropdown.ItemDescription>
+            </Dropdown.Item>
+            <Dropdown.Separator />
+            <Dropdown.Item tone="danger">
+              <Dropdown.ItemIcon>
+                <Icon name="action.delete" />
+              </Dropdown.ItemIcon>
+              Удалить
+            </Dropdown.Item>
+          </Dropdown.Content>
+        </Dropdown.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled · tone="danger"
+        </Typography>
+      </div>
+    </div>
   );
 }

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

@@ -40,7 +40,7 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Icon tile, title type and padding; given to the controls inside. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Icon tile, title type and padding; given to the controls inside. Without it the tier of its host, else `m`. |
 | `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. |
 | `tone` | `"neutral" \| "danger"` | `"neutral"` | `neutral` — nothing here (yet); `danger` — the region failed to load: the icon tile turns danger and the root is `role="alert"` unless you pass a `role`. |
 | `labels` | `Partial<EmptyPageLabels>` | — | Built-in strings, see Labels. |
@@ -51,15 +51,22 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"neutral" \| "accent" \| "danger"` | `the root's `tone`` | `neutral` — no data yet, `accent` — a first run and a call to start, `danger` — a failed load. |
+| `tone` | `"neutral" \| "accent" \| "danger"` | the root's `tone` | `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 · EmptyPage.Description
-`ref` → the element. `<h2>` (or `as`) and `<p>`, both capped at the reading width.
+### EmptyPage.Title
+`ref` → the element. An `<h2>` (or `as`) capped at the reading width.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `as` | `"h2" \| "h3" \| "h4" \| "p"` | `"h2"` | 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.Description
+`ref` → `HTMLParagraphElement`. A `<p>` 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
@@ -124,15 +131,19 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Enter` · `Space` | On `EmptyPage.RetryButton`: retry the load; while the retry runs the button is loading and ignores presses. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `tone="danger"` makes the root `role="alert"`, so the failure is announced when it appears; a `role` you pass replaces it.
 - 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`.
+- `EmptyPage.Icon` is `aria-hidden`: the tile is decorative, the title says what the state is.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -149,11 +160,11 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 | [sizes.tsx](examples/sizes.tsx) | Every tier changes the icon tile, the title and the padding; buttons in Actions take the same size — `size`. |
 | [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`. |
 | [region-error.tsx](examples/region-error.tsx) | A data region that failed to load: the error state takes the region, the retry shows its loading until the data cross-fades in; its text comes from labels — `tone`, `layout`, `EmptyPage.RetryButton`, `onRetry`, `labels`. |
-| [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. |
+| [compact.tsx](examples/compact.tsx) | The quiet empty state of a search popover: 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 — `EmptyPage.Actions`. |
 
 ## Mistakes
-- Buttons in a non-`m` EmptyPage without `size` → they take the root's tier from context; do not pass another one.
+- A `size` on the Buttons of a sized EmptyPage → leave it out: they take the root's tier from context.
 - A failed load drawn as a neutral empty state → `tone="danger"` on the root; the icon follows.
 - A hand-made «Повторить» with its own pending flag → `EmptyPage.RetryButton` with an async `onRetry`.
 - Clearing the error the moment the retry starts → keep the error state until the retry settles; the button shows the wait.