prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/reference/components/drawer/examples/overview.tsx

@@ -0,0 +1,56 @@
+/** Order details next to the list: the three zones of every drawer — a header with a close button, a read-only body and a footer with Close and the main action — `Drawer.Trigger`, `Drawer.Body`, `Drawer.Footer`. */
+import { Button, Drawer, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const DETAILS = [
+  { term: "Клиент", value: "Анна Смирнова" },
+  { term: "Сумма", value: "12 480 ₽" },
+  { term: "Доставка", value: "Курьер, 5 октября" },
+  { term: "Статус", value: "Собирается на складе" },
+];
+
+export default function DrawerOverviewExample() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Заказ № 1042
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content size="s">
+        <Drawer.Header>
+          <Drawer.Title>Заказ № 1042</Drawer.Title>
+          <Drawer.Description>Оформлен 3 октября</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Body>
+          <dl className={styles.details}>
+            {DETAILS.map(({ term, value }) => (
+              <React.Fragment key={term}>
+                <dt>
+                  <Typography as="span" variant="body-m" tone="muted">
+                    {term}
+                  </Typography>
+                </dt>
+                <dd>
+                  <Typography as="span" variant="body-m">
+                    {value}
+                  </Typography>
+                </dd>
+              </React.Fragment>
+            ))}
+          </dl>
+        </Drawer.Body>
+        <Drawer.Footer>
+          <Drawer.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Закрыть
+            </Button.Root>
+          </Drawer.Close>
+          <Button.Root>Изменить заказ</Button.Root>
+        </Drawer.Footer>
+      </Drawer.Content>
+    </Drawer.Root>
+  );
+}

package/dist/skill/reference/components/drawer/examples/placement.tsx

@@ -0,0 +1,40 @@
+/** The panel slides from the right for details and from the left for filters, rounded only on the edge facing the page — `side`. */
+import { Button, Drawer, Typography } from "prime-ui-kit";
+
+const SIDES = [
+  { side: "left", title: "Фильтры" },
+  { side: "right", title: "Детали заказа" },
+] as const;
+
+export default function DrawerPlacementExample() {
+  return (
+    <>
+      {SIDES.map(({ side, title }) => (
+        <Drawer.Root key={side}>
+          <Drawer.Trigger>
+            <Button.Root variant="soft" tone="neutral">
+              {side}
+            </Button.Root>
+          </Drawer.Trigger>
+          <Drawer.Content side={side} size="s">
+            <Drawer.Header>
+              <Drawer.Title>{title}</Drawer.Title>
+            </Drawer.Header>
+            <Drawer.Body>
+              <Typography variant="body-m" tone="secondary">
+                Скругление только со стороны страницы, подложка затемняет остальное.
+              </Typography>
+            </Drawer.Body>
+            <Drawer.Footer>
+              <Drawer.Close>
+                <Button.Root variant="outline" tone="neutral">
+                  Закрыть
+                </Button.Root>
+              </Drawer.Close>
+            </Drawer.Footer>
+          </Drawer.Content>
+        </Drawer.Root>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/drawer/examples/sizes.tsx

@@ -0,0 +1,43 @@
+/** Every panel width, 360 to 800 px; below 640 px of viewport the panel takes the full width — `size`. */
+import { Button, Drawer, Typography } from "prime-ui-kit";
+
+const SIZES = [
+  { size: "s", width: "360 px" },
+  { size: "m", width: "480 px" },
+  { size: "l", width: "640 px" },
+  { size: "xl", width: "800 px" },
+] as const;
+
+export default function DrawerSizesExample() {
+  return (
+    <>
+      {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>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/drawer/examples/structure.tsx

@@ -0,0 +1,35 @@
+/** Optional parts: an icon tile in the header and one full-width action in the footer — `Drawer.Icon`, `Drawer.Footer`, `layout`. */
+import { Button, Drawer, Icon, Typography } from "prime-ui-kit";
+
+export default function DrawerStructureExample() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Как считается выручка
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content size="s">
+        <Drawer.Header>
+          <Drawer.Icon tone="info">
+            <Icon name="status.info" />
+          </Drawer.Icon>
+          <Drawer.Title>Выручка</Drawer.Title>
+          <Drawer.Description>Справка по отчёту</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Body>
+          <Typography variant="body-m" tone="secondary">
+            В выручку входят оплаченные заказы за период без возвратов и отменённых доставок.
+          </Typography>
+        </Drawer.Body>
+        <Drawer.Footer layout="fill">
+          <Drawer.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Понятно
+            </Button.Root>
+          </Drawer.Close>
+        </Drawer.Footer>
+      </Drawer.Content>
+    </Drawer.Root>
+  );
+}

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

@@ -0,0 +1,235 @@
+# Dropdown
+
+**Category:** overlays
+**Kind:** overlay
+
+> A menu of actions that opens from a trigger: picking an item runs it and closes the menu.
+
+## When to use
+- Secondary actions of a card, row or document behind a «⋯» or labelled button.
+- An account / user menu in the app header.
+- A short list of commands (export formats, move to project) where picking one runs an action.
+
+## When not to use
+- Choosing and showing a value in a form → use [Select](../select/COMPONENT.md) (or [TagSelect](../tag-select/COMPONENT.md) for several).
+- Searching across many commands → use [CommandMenu](../command-menu/COMPONENT.md).
+- Free content, forms or filters in a floating panel → use [Popover](../popover/COMPONENT.md).
+- A hint on hover → use [Tooltip](../tooltip/COMPONENT.md).
+- Two to four always-visible actions → show [Button](../button/COMPONENT.md)s or a [ButtonGroup](../button-group/COMPONENT.md).
+
+## Import
+```tsx
+import { Dropdown } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Dropdown.Root                     state and dismiss policy (no DOM)
+├── Dropdown.Trigger              clones its child; toggles the menu
+└── Dropdown.Content              portaled role="menu" on the floating surface, scrolls
+    ├── Dropdown.Header           non-interactive row: [avatar] [Title + Description] [badge]
+    │   ├── Dropdown.Title
+    │   └── Dropdown.Description
+    ├── Dropdown.Separator        full-bleed Divider
+    ├── Dropdown.Group            role="group", named by `label`
+    │   └── Dropdown.Item         <button role="menuitem"> (or the asChild link)
+    │       ├── Dropdown.ItemIcon         leading glyph (aria-hidden)
+    │       ├── Dropdown.ItemDescription  muted second line; describes the item
+    │       └── Dropdown.ItemShortcut     Kbd at the end
+    ├── Dropdown.CheckboxItem     <button role="menuitemcheckbox">: label + check mark at the end while checked; stays open
+    └── Dropdown.Item
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Dropdown.Root
+No DOM, no ref. Open state and dismiss policy.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
+| `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
+| `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. |
+
+### Dropdown.Trigger
+No DOM: clones the single child, merges `ref` and `onClick`; toggles the menu and sets its ARIA.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactElement` | — (required) | One element, usually a Button. |
+
+### 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.
+
+| 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. |
+| `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.
+
+| 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. |
+| `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. |
+
+### 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.
+
+| 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. |
+| `children` | `ReactNode` | — | The label (optionally after a `Dropdown.ItemIcon`). |
+
+### 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`.
+
+### 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.
+
+### Dropdown.Group
+`ref` → `HTMLDivElement`. `<div role="group">` named by its visible `label`. + native `<div>` props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
+
+### Dropdown.Separator
+`ref` → `HTMLDivElement`. A full-bleed Divider between items or groups.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…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.
+
+## 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.
+
+### size (Content)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | item 24, text 12/16, icon 14 | Dense toolbars | |
+| `s` | item 28, text 13/20, icon 16 | Table rows, compact headers | |
+| `m` | item 32, text 14/20, icon 16 | Most menus | yes |
+| `l` | item 36, text 16/24, icon 20 | Roomy layouts | |
+| `xl` | item 40, text 16/24, icon 20 | Touch-first screens | |
+
+### tone (Item)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | primary text, muted icon, subtle fill on hover | Regular actions | yes |
+| `danger` | danger text and icon, danger-soft fill on hover | Delete, revoke, leave | |
+
+### side / align (Content)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `side="bottom"` | Below the trigger | Default | yes |
+| `side="top"` | Above the trigger | Triggers near the bottom of the screen | |
+| `side="left"` / `"right"` | Beside the trigger, aligned along its height | Triggers in a side rail (account menu at the bottom of a sidebar) | |
+| `align="auto"` | Lined up with the trigger edge that has more room: near the end of the screen the end edges meet and the menu grows toward the start, near the start the other way; below the trigger, flipping to the top without room | Default — triggers anywhere | yes |
+| `align="end"` | End edges aligned: the menu grows toward the start | The menu must line up with the end of a block whatever room there is | |
+| `align="center"` | Centred on the trigger | Small triggers | |
+| `align="start"` | Start edges aligned: the menu grows toward the end | The menu must line up with the start of a block whatever room there is | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `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 | |
+
+**Combinations** — menu `size` = trigger `size`. Destructive items go last, after a separator. Key hints only for shortcuts the app really handles.
+
+## 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 |
+| 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 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`) |
+
+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.
+
+## Layout & spacing
+- Width is `max-content` between `--prime-panel-min-width` and twice that; item labels never wrap, a `Dropdown.ItemDescription` wraps inside that limit.
+- Max height = min(`--prime-panel-max-height`, the room on the resolved side); the menu scrolls inside.
+- A checkbox item keeps the label (and an `ItemIcon`) on the left like any item; the check mark sits at the end.
+- `Dropdown.ItemIcon` holds the glyph at the menu icon size (a kit `Icon` follows it); `Dropdown.ItemShortcut` is a `Kbd` one tier below the menu, pushed to the end of the item.
+- `Dropdown.Header` lays out its children in the written order; `Dropdown.Title` is the medium heading line, `Dropdown.Description` the muted line under it; both truncate.
+- Separators run edge to edge across the panel padding; group labels take `--prime-panel-group-label-height`.
+- Kept `--prime-space-2` from viewport edges; follows the trigger on scroll and resize.
+
+## Accessibility
+
+### Keyboard
+| 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. |
+| `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.
+- 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`.
+- `Dropdown.ItemIcon` is hidden from screen readers; a key hint is text only — the app handles the shortcut.
+- An outside press closes the menu without moving focus back to the trigger: focus follows the pointer (foundation §8).
+
+### 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 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`. |
+| [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`. |
+| [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`. |
+| [dismiss.tsx](examples/dismiss.tsx) | An onboarding step keeps the menu open on an outside press and on Escape until an item is picked — `closeOnOutsideClick`, `closeOnEscape`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state and opens the menu from another button; the picked step updates the trigger — `open`, `onOpenChange`. |
+
+## Mistakes
+- Using Dropdown to pick a form value → Select shows the value and works with forms.
+- An icon passed as a component (`as={Icon}`) → put the glyph inside `Dropdown.ItemIcon`.
+- A hand-written shortcut `<kbd>` → `Dropdown.ItemShortcut` (a Kbd at the end of the item).
+- `Dropdown.Group` with a separate heading element → pass the heading as `label`.
+- 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.
+
+## 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`)
+- **See also:** [Select](../select/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Button](../button/COMPONENT.md)

package/dist/skill/reference/components/dropdown/examples/checkbox-items.tsx

@@ -0,0 +1,48 @@
+/** A column chooser: toggles in the menu keep it open, the key column cannot be hidden — `Dropdown.CheckboxItem`, `checked`, `onCheckedChange`. */
+import { Button, Dropdown, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+const COLUMNS = [
+  { id: "number", label: "Номер", locked: true },
+  { id: "client", label: "Клиент", locked: false },
+  { id: "status", label: "Статус", locked: false },
+  { id: "amount", label: "Сумма", locked: false },
+  { id: "due", label: "Срок оплаты", locked: false },
+];
+
+export default function DropdownCheckboxItemsExample() {
+  const [hidden, setHidden] = React.useState<string[]>(["due"]);
+  const shown = COLUMNS.length - hidden.length;
+
+  const toggle = (id: string, visible: boolean) =>
+    setHidden((list) => (visible ? list.filter((item) => item !== id) : [...list, id]));
+
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          <Button.Icon>
+            <Icon name="action.settings" />
+          </Button.Icon>
+          Колонки: {shown} из {COLUMNS.length}
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Group label="Показывать">
+          {COLUMNS.map((column) => (
+            <Dropdown.CheckboxItem
+              key={column.id}
+              checked={!hidden.includes(column.id)}
+              disabled={column.locked}
+              onCheckedChange={(visible) => toggle(column.id, visible)}
+            >
+              {column.label}
+            </Dropdown.CheckboxItem>
+          ))}
+        </Dropdown.Group>
+        <Dropdown.Separator />
+        <Dropdown.Item onSelect={() => setHidden([])}>Показать все</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/dist/skill/reference/components/dropdown/examples/controlled-open.tsx

@@ -0,0 +1,32 @@
+/** The parent owns the open state and opens the menu from another button; the picked step updates the trigger — `open`, `onOpenChange`. */
+import { Button, Dropdown } from "prime-ui-kit";
+import * as React from "react";
+
+const STEPS = ["Шаг 1 · Реквизиты", "Шаг 2 · Товары", "Шаг 3 · Оплата"];
+
+export default function DropdownControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+  const [step, setStep] = React.useState(STEPS[1]);
+
+  return (
+    <>
+      <Button.Root variant="ghost" tone="neutral" onClick={() => setOpen(true)}>
+        Перейти к шагу
+      </Button.Root>
+      <Dropdown.Root open={open} onOpenChange={setOpen}>
+        <Dropdown.Trigger>
+          <Button.Root variant="soft" tone="neutral">
+            {step}
+          </Button.Root>
+        </Dropdown.Trigger>
+        <Dropdown.Content>
+          {STEPS.map((item) => (
+            <Dropdown.Item key={item} onSelect={() => setStep(item)}>
+              {item}
+            </Dropdown.Item>
+          ))}
+        </Dropdown.Content>
+      </Dropdown.Root>
+    </>
+  );
+}

package/dist/skill/reference/components/dropdown/examples/dismiss.tsx

@@ -0,0 +1,17 @@
+/** An onboarding step keeps the menu open on an outside press and on Escape until an item is picked — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Button, Dropdown } from "prime-ui-kit";
+
+export default function DropdownDismissExample() {
+  return (
+    <Dropdown.Root closeOnOutsideClick={false} closeOnEscape={false}>
+      <Dropdown.Trigger>
+        <Button.Root>Выберите роль в команде</Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>Руководитель</Dropdown.Item>
+        <Dropdown.Item>Менеджер проектов</Dropdown.Item>
+        <Dropdown.Item>Бухгалтер</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/dist/skill/reference/components/dropdown/examples/examples.module.css

@@ -0,0 +1,22 @@
+/* Layout of the Dropdown scenarios: semantic tokens only. */
+
+/* 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);
+}
+
+/* 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-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-layer-nested);
+}

package/dist/skill/reference/components/dropdown/examples/item-description.tsx

@@ -0,0 +1,30 @@
+/** 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`. */
+import { Button, Dropdown, Icon } from "prime-ui-kit";
+
+export default function DropdownItemDescriptionExample() {
+  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.ItemDescription>Копия без задач и участников</Dropdown.ItemDescription>
+        </Dropdown.Item>
+        <Dropdown.Item disabled tone="danger">
+          <Dropdown.ItemIcon>
+            <Icon name="action.delete" />
+          </Dropdown.ItemIcon>
+          Удалить проект
+          <Dropdown.ItemDescription>Доступно владельцу проекта</Dropdown.ItemDescription>
+        </Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/dist/skill/reference/components/dropdown/examples/link-items.tsx

@@ -0,0 +1,29 @@
+/** 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`. */
+import { Button, Dropdown, Icon } from "prime-ui-kit";
+
+const LINKS = [
+  { href: "#deal-1042", label: "Открыть сделку" },
+  { href: "#client-nwind", label: "Карточка клиента" },
+  { href: "#invoice-318", label: "Счёт №318" },
+] as const;
+
+export default function DropdownLinkItemsExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root variant="ghost" tone="neutral" aria-label="Перейти">
+          <Button.Icon>
+            <Icon name="action.externalLink" />
+          </Button.Icon>
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        {LINKS.map(({ href, label }) => (
+          <Dropdown.Item key={href} asChild>
+            <a href={href}>{label}</a>
+          </Dropdown.Item>
+        ))}
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}

package/dist/skill/reference/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>
+  );
+}