prime-ui-kit 0.10.0 → 0.11.0

package/src/components/drawer/COMPONENT.md

@@ -3,17 +3,17 @@
 **Category:** overlays
 **Kind:** overlay
 
-> A modal panel that slides in from the edge: filters, forms and record details at the side, a bottom sheet on a phone.
+> A modal panel that slides in from the side: filters, forms and record details without leaving the page.
 
 ## When to use
 - Editing settings or a record without leaving the page.
 - Filters or navigation on narrow screens (`side="left"`).
-- Read-only details of a list row (order, user, event).
+- Read-only details of a list row (order, user, event), with its status and a ⋯ menu in the header (`Drawer.Actions`).
 - Long content (history, logs) that needs a tall scrolling area.
-- A short task on a phone — pick a date, choose an action, fill two fields — in a bottom sheet (`side="bottom"`).
 
 ## When not to use
-- Confirmations and short decisions → use [Modal](../modal/COMPONENT.md).
+- Confirmations of a destructive action → use [ConfirmDialog](../confirm-dialog/COMPONENT.md); short decisions → [Modal](../modal/COMPONENT.md).
+- A short task that ends by itself — pick a date, choose an action — raised from the bottom edge → use [Sheet](../sheet/COMPONENT.md).
 - A small panel anchored to a button, without blocking the page → use [Popover](../popover/COMPONENT.md).
 - Persistent app navigation → use [Sidebar](../../layout/sidebar/COMPONENT.md).
 - Collapsible content inside the page → use [Accordion](../accordion/COMPONENT.md).
@@ -27,14 +27,16 @@ import { Drawer } from "prime-ui-kit";
 ```
 Drawer.Root                    state and dismiss policy (no DOM)
 ├─ Drawer.Trigger              clones its child; opens on click
-└─ Drawer.Content              portal + scrim + role="dialog" panel at the edge
-   ├─ (grab handle)            side="bottom" only: aria-hidden bar, a drag starts here
-   ├─ Drawer.Header            grid: [Icon] [Title + Description] [close Button]
+└─ Drawer.Content              portal + scrim + role="dialog" panel at the side
+   ├─ Drawer.Guard             no DOM: holds the drawer (busy / dirty) from inside
+   ├─ Drawer.Header            grid: [Icon] [Title + Description] [Actions] [close Button]
    │  ├─ Drawer.Icon
    │  ├─ Drawer.Title          <h2>
-   │  └─ Drawer.Description    <p>
+   │  ├─ Drawer.Description    <p>
+   │  └─ Drawer.Actions        row of tier-s controls before the close button
    ├─ Drawer.Body              the only scrolling zone (ScrollContainer)
-   └─ Drawer.Footer            actions, primary last
+   └─ Drawer.Footer            always: Close or Cancel + the main action, primary last
+      ├─ Drawer.Meta           <p>, muted status at the start
       └─ Drawer.Close          clones its child; closes on click
 ```
 
@@ -49,19 +51,19 @@ No DOM, no ref. State and dismiss policy.
 |---|---|---|---|
 | `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
-| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. A `Guard` holds the dismisses (not code). |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the dialog. |
-| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim (and a swipe on a bottom sheet) closes the dialog; turn off for destructive confirms. |
+| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim closes the dialog; turn off for destructive confirms. |
 | `labels` | `Partial<DrawerLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | Trigger and Content. |
 
 ### Drawer.Content
-`ref` → `HTMLDivElement` (the dialog panel). Portal + scrim + `role="dialog"` panel at the edge; renders while open and during its exit animation.
+`ref` → `HTMLDivElement` (the dialog panel). Portal + scrim + `role="dialog"` panel at the edge; renders while open and during its exit animation, showing the children it had open (a record cleared with `open` does not empty the panel mid-motion).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `side` | `"left" \| "right" \| "bottom"` | `"right"` | Edge the panel slides from; rounded only on the edge facing the page. `bottom` is a sheet: a grab handle on top, height by content. A swipe toward the edge closes the panel (with `closeOnOutsideClick`): a bottom sheet from its handle or header, a side drawer by touch anywhere (by mouse from the header). |
-| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 360 · 480 · 640 · 800; a bottom sheet is centred and at least 560 (`--prime-sheet-min-width`). Below 640 px of viewport — full width; side drawers lose their corners. |
+| `side` | `"left" \| "right"` | `"right"` | Edge the panel slides from; rounded only on the edge facing the page. No swipe: the drawer closes by its buttons, Escape and the scrim. A panel from the bottom edge is a Sheet. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 360 · 480 · 640 · 800. Below 640 px of viewport — full width, without corners. |
 | `aria-label` | `string` | — | Dialog name when there is no Title. |
 | `aria-labelledby` | `string` | — | Overrides the Title id. |
 | `aria-describedby` | `string` | — | Overrides the Description id. |
@@ -69,12 +71,15 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other attributes of the `role="dialog"` element. |
 
 ### Drawer.Header
-`ref` → `HTMLElement`. Renders `<header>`: [Icon] [Title + Description] [close button]. + native `HTMLAttributes<HTMLElement>`.
+`ref` → `HTMLElement`. Renders `<header>`: [Icon] [Title + Description] [Actions] [close button]. + native `HTMLAttributes<HTMLElement>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `showClose` | `boolean` | `true` | Built-in square ghost `s` close button named by `labels.close`. |
-| `children` | `ReactNode` | — | Icon, Title, Description in any order; the icon goes to the leading slot. |
+| `showClose` | `boolean` | `true` | Built-in square ghost `s` close button named by `labels.close`; disabled in place while a `Guard` is `busy`. |
+| `children` | `ReactNode` | — | Icon, Title, Description, Actions in any order; each goes to its column. A `Tabs.List` (with `Tabs.Root` around header and body) turns the header into a tab strip. |
+
+### Drawer.Actions
+`ref` → `HTMLDivElement`. A row of controls at the end of the header, before the close button: a status Badge, a ⋯ Dropdown, an icon button. Controls inside take tier `s`. + native `<div>` props.
 
 ### Drawer.Icon
 `ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill.
@@ -92,14 +97,25 @@ No DOM, no ref. State and dismiss policy.
 `ref` → `HTMLDivElement`. The only scrolling zone (a ScrollContainer), 16 gap between blocks. + native `<div>` props.
 
 ### Drawer.Footer
-`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last. + native `HTMLAttributes<HTMLElement>`.
+`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last, and an optional `Meta` at the start. + native `HTMLAttributes<HTMLElement>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `layout` | `"fill" \| "end"` | `"end"` | `fill`: equal-width buttons in one row; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px. |
 
+### Drawer.Meta
+`ref` → `HTMLParagraphElement`. A `<p>` at the start of the footer: short muted status text («Есть несохранённые изменения»); the buttons keep their width at the end. Not part of the dialog description. + native `<p>` props.
+
+### Drawer.Guard
+No DOM, no ref. Holds the dialog from anywhere inside Content, where the form state lives; renders only the built-in «discard changes?» confirm. Closing from code is never held.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `busy` | `boolean` | `false` | A request runs: Escape, a press outside, the close button and `Close` do nothing; the close button and the `Close` child stay in place, disabled. |
+| `dirty` | `boolean` | `false` | Unsaved changes: any of those dismisses first asks «Не сохранять изменения?» (a ConfirmDialog with `labels.discard*`); confirming closes the dialog. |
+
 ### Drawer.Trigger · Drawer.Close
-No DOM: clone the single child and chain its `onClick` (unless the child's handler calls `preventDefault()`).
+No DOM: clone the single child and chain its `onClick` (unless the child's handler calls `preventDefault()`). `Close` goes through a `Guard` and makes its child `disabled` while the guard is busy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -112,7 +128,6 @@ No DOM: clone the single child and chain its `onClick` (unless the child's handl
 |---|---|---|---|
 | `right` | slides from the right, rounded on its left edge | details and forms | yes |
 | `left` | slides from the left, rounded on its right edge | filters, mobile navigation | |
-| `bottom` | rises from the bottom, rounded on top, grab handle, height by content | a short task on a phone | |
 
 ### size (Content)
 | Value | Looks like | Use when | Default |
@@ -122,7 +137,7 @@ No DOM: clone the single child and chain its `onClick` (unless the child's handl
 | `l` | 640 wide | wide forms | |
 | `xl` | 800 wide | tables, previews | |
 
-A bottom sheet is centred at its width, never narrower than 560 (`--prime-sheet-min-width`), so a tablet gets a real sheet. Below 640px of viewport every size is full width; side drawers lose their corners, the sheet keeps its top radius.
+Below 640px of viewport every size is full width and loses its corners.
 
 ### layout (Footer)
 | Value | Looks like | Use when | Default |
@@ -138,15 +153,22 @@ A bottom sheet is centred at its width, never narrower than 560 (`--prime-sheet-
 |---|---|---|
 | open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state` on the scrim and the panel; mounted until the slide-out ends |
 | side / size | Content props | `data-side`, `data-size` on the panel |
-| swiping | a drag toward the edge (with `closeOnOutsideClick`) | `data-swiping` and `--swipe-offset` on the panel while the pointer drags it; `data-swipe-dismissed` while it glides out after a closing release; `--swipe-progress` (0…1) on the scrim |
 | open: trapped | while open | focus trapped, page scroll locked, siblings of the portal `inert` (the toast region stays usable); a drawer opened from a Modal or another drawer stacks above it |
+| closing | `open` turns false | the panel keeps showing the children it had open while it slides out |
+| busy | `Drawer.Guard busy` | Escape, the scrim, the close button and `Drawer.Close` do nothing; the close button and the `Close` child are `disabled` in place |
+| dirty | `Drawer.Guard dirty` | a dismiss opens the «Не сохранять изменения?» ConfirmDialog (`labels.discard*`); its confirm closes the drawer |
 
-Motion: the scrim fades, the panel slides from its side over `slow` and leaves over `base` (`overlayMotion`); under `prefers-reduced-motion` it unmounts at once. A swipe moves the panel with the pointer; on release it closes past 30% of its size or on a quick flick and glides the rest of the way out from where it was let go, otherwise it glides back — both over `base` on the `emphasized` (iOS sheet) curve. A pull the other way meets growing resistance and stops at 24; the panel's fill continues that far past the screen edge, so it never comes away from it. The scrim follows the panel: its fill thins in proportion to how far out the panel is, tracks the finger while dragging and glides with the panel on release. A bottom sheet drags from its handle or header; a side drawer by touch anywhere (not on text fields, sliders or sideways scrollers), by mouse from the header.
+Motion: the scrim fades, the panel slides from its side over `slow` and leaves over `base` (`overlayMotion`); under `prefers-reduced-motion` it unmounts at once. The drawer has no touch gestures: it is not dragged or swiped away — it closes by its buttons, Escape and the scrim, with the same slide-out.
 
 ## Layout & spacing
+- A drawer has three zones: `Drawer.Header` (title, the × close button), `Drawer.Body` (the content, the only zone that scrolls) and `Drawer.Footer` (the actions). The footer is not optional decoration — it is where the drawer is finished:
+  - read-only details: `Drawer.Close` around `<Button.Root variant="outline" tone="neutral">Закрыть</Button.Root>`, plus the record's main action (solid, last) when it has one;
+  - a form: «Отмена» (`Drawer.Close`, outline neutral) and the submit button (solid, last; `type="submit" form={formId}`), `Drawer.Meta` for «Есть несохранённые изменения»;
+  - one acknowledgement: `<Drawer.Footer layout="fill">`.
+  Both the header × and the footer button stay: the × is the quick way out at the top, the footer is the end of the reading or editing path, where the hand already is.
 - Zone padding `--prime-drawer-padding`; hairlines between header, body and footer.
 - Full viewport height; only the body scrolls, with its own side padding.
-- Bottom sheet: width by `size`, at least `--prime-sheet-min-width` (560); height by content up to `100dvh − --prime-sheet-top-gap`, radius `--prime-sheet-radius`, a `--prime-sheet-handle-area` strip with the handle bar, the bottom safe-area inset below the content.
+- Tabs in the header: a `Tabs.List` inside `Drawer.Header` (with `Tabs.Root` around the header and the body) spans the header's last row. The header becomes the tab strip, edge to edge and without the hairline; the active tab is the body rising into it, the panels sit in the body.
 - Fields inside get the surface field fill.
 
 ## Accessibility
@@ -162,7 +184,8 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 - Focus moves into the panel on open and returns to the opener on close, including after a scrim click.
 - The page behind is `inert`, scroll is locked; only the topmost layer reacts.
 - A drawer opened from a Modal stacks above it.
-- A swipe toward the edge is an extra way out; the close button and Escape stay. The grab handle is `aria-hidden`.
+- No swipe: the close button, `Drawer.Close`, Escape and the scrim are the ways out.
+- A busy `Guard` keeps the close button and the `Close` child in place, `disabled`; a dirty one opens a `role="alertdialog"` confirm with focus on «Продолжить».
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -170,27 +193,37 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 | Key | Default | Used for |
 |---|---|---|
 | `close` | `"Закрыть"` | `aria-label` of the header close button. |
+| `discardTitle` | `"Не сохранять изменения?"` | Title of the confirm a dismiss opens while a `Guard` is `dirty`. |
+| `discardDescription` | `"Изменения в форме пропадут."` | Its description. |
+| `discardConfirm` | `"Не сохранять"` | Its confirm button: close and lose the changes. |
+| `discardCancel` | `"Продолжить"` | Its cancel button: back to the form. |
 
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | Order details next to the list: a trigger, a header with a close button and a read-only body — `Drawer.Trigger`, `Drawer.Body`. |
+| [overview.tsx](examples/overview.tsx) | 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`. |
 | [structure.tsx](examples/structure.tsx) | Optional parts: an icon tile in the header and one full-width action in the footer — `Drawer.Icon`, `Drawer.Footer`, `layout`. |
 | [sizes.tsx](examples/sizes.tsx) | Every panel width, 360 to 800 px; below 640 px of viewport the panel takes the full width — `size`. |
-| [placement.tsx](examples/placement.tsx) | The panel slides from the right for details, from the left for filters and up from the bottom as a sheet — `side`. |
-| [date-sheet.tsx](examples/date-sheet.tsx) | A date picked in a bottom sheet: a grab handle on top, a swipe down or a pick closes it — `side`, `Drawer.Body`. |
+| [placement.tsx](examples/placement.tsx) | The panel slides from the right for details and from the left for filters, rounded only on the edge facing the page — `side`. |
+| [header-actions.tsx](examples/header-actions.tsx) | A record card: its status and a ⋯ menu sit in the header before the close button, one tier smaller — `Drawer.Actions`. |
+| [guard.tsx](examples/guard.tsx) | A form that holds the drawer from inside: after an edit Escape, the scrim and Cancel ask before discarding, the footer says so, and saving locks every way out — `Drawer.Guard`, `Drawer.Meta`. |
 | [long-content.tsx](examples/long-content.tsx) | A long body scrolls on its own while the header and the footer stay in place — `Drawer.Body`. |
 | [dismiss.tsx](examples/dismiss.tsx) | An import closes only from its buttons, and not at all while it runs — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the state and opens the drawer from a link, without a trigger — `open`, `onOpenChange`. |
 | [in-form.tsx](examples/in-form.tsx) | A settings form in the panel: the footer button submits the form and an empty name shakes the field and keeps it open until it is filled — `Drawer.Body`, `Drawer.Footer`, `error`. |
 
 ## Mistakes
-- A delete confirmation in a Drawer → use Modal.
+- A drawer without `Drawer.Footer` → add one: «Закрыть» for details, «Отмена» + the submit button for a form. The header × alone is not the end of the panel.
+- Save or Cancel buttons at the end of the body, or in the header → they go in `Drawer.Footer`, which stays in place while the body scrolls.
+- A delete confirmation in a Drawer → use ConfirmDialog.
+- Busy or unsaved state lifted out of the form into Root props → put `Drawer.Guard` next to the form, inside Content.
+- Clearing the record together with `open` and rendering a skeleton for «no record» → not needed: the panel keeps its last content while it slides out.
+- A Badge or a menu as a custom child of the header text column → put them in `Drawer.Actions`.
 - Expecting Enter to submit via `Drawer.Confirm` → Drawer has no Confirm; use a `<form>` with a submit button.
-- `side="top"` → only `left`, `right` and `bottom`.
-- Swipe as the only way to close → keep `Drawer.Header` with its close button (or `Drawer.Close`); a swipe is an extra gesture.
+- `side="top"` or `side="bottom"` → only `left` and `right`; a panel from the bottom edge is a [Sheet](../sheet/COMPONENT.md).
+- Expecting a swipe to close a drawer → it has none; keep the header × and a footer button. A panel that swipes away is a [Sheet](../sheet/COMPONENT.md).
 - Padding on a wrapper inside Body → Body already pads and scrolls.
 
 ## Related
-- **Built from:** Button, Icon, ScrollContainer
-- **See also:** [Modal](../modal/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Popover](../popover/COMPONENT.md)
+- **Built from:** [Button](../button/COMPONENT.md) (close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Drawer.Body`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Drawer.Guard` discard confirm), `Icon` (the close glyph)
+- **See also:** [Modal](../modal/COMPONENT.md) (the same header, body, footer and `Guard` in the centre), [Sheet](../sheet/COMPONENT.md) (the same parts raised from the bottom edge for a short task), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (a destructive confirm), [Sidebar](../../layout/sidebar/COMPONENT.md), [Popover](../popover/COMPONENT.md)

package/src/components/drawer/examples/controlled-open.tsx

@@ -1,5 +1,5 @@
 /** The parent owns the state and opens the drawer from a link, without a trigger — `open`, `onOpenChange`. */
-import { Drawer, LinkButton, Typography } from "prime-ui-kit";
+import { Button, Drawer, LinkButton, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 export default function DrawerControlledOpenExample() {
@@ -26,6 +26,13 @@ export default function DrawerControlledOpenExample() {
               Счёт формируется 1-го числа по тарифу и числу активных пользователей за прошлый месяц.
             </Typography>
           </Drawer.Body>
+          <Drawer.Footer>
+            <Drawer.Close>
+              <Button.Root variant="outline" tone="neutral">
+                Закрыть
+              </Button.Root>
+            </Drawer.Close>
+          </Drawer.Footer>
         </Drawer.Content>
       </Drawer.Root>
     </>

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

@@ -19,8 +19,3 @@
   margin: 0;
   font-variant-numeric: tabular-nums;
 }
-
-/* date-sheet.tsx: the calendar keeps its own width, centred in the sheet. */
-.calendar {
-  align-self: center;
-}

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

@@ -0,0 +1,80 @@
+/** A form that holds the drawer from inside: after an edit Escape, the scrim and Cancel ask before discarding, the footer says so, and saving locks every way out — `Drawer.Guard`, `Drawer.Meta`. */
+import { Button, Drawer, Fieldset, Input, Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** Pretends to send the form. */
+function saveTask() {
+  return new Promise((resolve) => setTimeout(resolve, 1200));
+}
+
+export default function DrawerGuardExample() {
+  const formId = React.useId();
+  const [open, setOpen] = React.useState(false);
+  const [dirty, setDirty] = React.useState(false);
+  const [saving, setSaving] = React.useState(false);
+
+  const submit = async (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSaving(true);
+    await saveTask();
+    setSaving(false);
+    setDirty(false);
+    setOpen(false);
+  };
+
+  return (
+    <Drawer.Root
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) setDirty(false);
+      }}
+    >
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Изменить задачу
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content>
+        <Drawer.Header>
+          <Drawer.Title>Подготовить договор</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Body>
+          <Drawer.Guard busy={saving} dirty={dirty} />
+          <form id={formId} className={styles.form} onSubmit={submit}>
+            <Fieldset disabled={saving}>
+              <Input.Root label="Название">
+                <Input.Wrapper>
+                  <Input.Field
+                    name="title"
+                    defaultValue="Подготовить договор"
+                    onValueChange={() => setDirty(true)}
+                  />
+                </Input.Wrapper>
+              </Input.Root>
+              <Textarea.Root
+                label="Комментарий"
+                name="comment"
+                defaultValue="Согласовать сроки оплаты с юристами клиента"
+                onValueChange={() => setDirty(true)}
+              />
+            </Fieldset>
+          </form>
+        </Drawer.Body>
+        <Drawer.Footer>
+          {dirty ? <Drawer.Meta>Есть несохранённые изменения</Drawer.Meta> : null}
+          <Drawer.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Отмена
+            </Button.Root>
+          </Drawer.Close>
+          <Button.Root type="submit" form={formId} loading={saving} disabled={!dirty}>
+            Сохранить
+          </Button.Root>
+        </Drawer.Footer>
+      </Drawer.Content>
+    </Drawer.Root>
+  );
+}

package/src/components/drawer/examples/header-actions.tsx

@@ -0,0 +1,63 @@
+/** A record card: its status and a ⋯ menu sit in the header before the close button, one tier smaller — `Drawer.Actions`. */
+import { Badge, Button, Drawer, Dropdown, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const DEAL = {
+  title: "Сделка №1042",
+  client: "ООО «Северный ветер»",
+  amount: "480 000 ₽",
+  owner: "Анна Соколова",
+};
+
+export default function DrawerHeaderActionsExample() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Открыть сделку
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content>
+        <Drawer.Header>
+          <Drawer.Title>{DEAL.title}</Drawer.Title>
+          <Drawer.Description>{DEAL.client}</Drawer.Description>
+          <Drawer.Actions>
+            <Badge.Root color="green">Выиграна</Badge.Root>
+            <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>
+                <Dropdown.Item>Дублировать</Dropdown.Item>
+                <Dropdown.Item>Скопировать ссылку</Dropdown.Item>
+                <Dropdown.Separator />
+                <Dropdown.Item tone="danger">Удалить сделку</Dropdown.Item>
+              </Dropdown.Content>
+            </Dropdown.Root>
+          </Drawer.Actions>
+        </Drawer.Header>
+        <Drawer.Body>
+          <dl className={styles.details}>
+            <dt>Сумма</dt>
+            <dd>{DEAL.amount}</dd>
+            <dt>Ответственный</dt>
+            <dd>{DEAL.owner}</dd>
+          </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/src/components/drawer/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** Order details next to the list: a trigger, a header with a close button and a read-only body — `Drawer.Trigger`, `Drawer.Body`. */
+/** 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";
 
@@ -42,6 +42,14 @@ export default function DrawerOverviewExample() {
             ))}
           </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/src/components/drawer/examples/placement.tsx

@@ -1,10 +1,9 @@
-/** The panel slides from the right for details, from the left for filters and up from the bottom as a sheet — `side`. */
+/** 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: "Детали заказа" },
-  { side: "bottom", title: "Действия с заказом" },
 ] as const;
 
 export default function DrawerPlacementExample() {
@@ -23,10 +22,16 @@ export default function DrawerPlacementExample() {
             </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/src/components/drawer/examples/sizes.tsx

@@ -28,6 +28,13 @@ export default function DrawerSizesExample() {
                 На экране уже 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/src/components/dropdown/COMPONENT.md

@@ -32,9 +32,10 @@ Dropdown.Root                     state and dismiss policy (no DOM)
     │   └── Dropdown.Description
     ├── Dropdown.Separator        full-bleed Divider
     ├── Dropdown.Group            role="group", named by `label`
-    │   └── Dropdown.Item         <button role="menuitem">
-    │       ├── Dropdown.ItemIcon       leading glyph (aria-hidden)
-    │       └── Dropdown.ItemShortcut   Kbd at the end
+    │   └── 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
 ```
@@ -56,35 +57,36 @@ No DOM, no ref. Open state and dismiss policy.
 | `children` | `ReactNode` | — (required) | Trigger and Content. |
 
 ### Dropdown.Trigger
-No DOM: clones the single child, merges `ref` and `onClick` (toggles), sets `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`, `data-state`; the child's own `id` wins. Other props given to it (handlers, ARIA, `ref`) reach the child, so a wrapping `Tooltip.Trigger` keeps working.
+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"` on the floating surface (a ScrollContainer), named by the trigger; renders while open and during its exit animation. Focus moves to the first item; Tab closes the menu and returns focus to the trigger. Below 640px of viewport the menu is a bottom sheet: a scrim, a grab handle, swipe down to close (with `closeOnOutsideClick`), page scroll locked.
+`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` | `"start" \| "center" \| "end"` | `"start"` | Alignment along the trigger; shifts inside the viewport. |
+| `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`. 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">`; 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. |
-| `children` | `ReactNode` | — | `Dropdown.ItemIcon`, the label, `Dropdown.ItemShortcut`. |
+| `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`: the label (and an `ItemIcon`) on the left like any item, an accent check mark at the end while checked and nothing while not; 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. + native button props.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -94,8 +96,11 @@ No DOM: clones the single child, merges `ref` and `onClick` (toggles), sets `ari
 | `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>`). An `aria-hidden` `<span>` holding the leading glyph at the menu icon size (a kit `Icon` follows it) / a `Kbd` one tier below the menu, pushed to the end of the item — a hint, not a handler. + native props.
+`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.
@@ -112,7 +117,7 @@ No DOM: clones the single child, merges `ref` and `onClick` (toggles), sets `ari
 | `…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 stacked in one column, a trailing badge or button — in the written order / the medium heading line / the muted line under it; both truncate. + 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. + 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.
@@ -138,14 +143,15 @@ The panel is the shared floating surface: the floating layer of the ladder (`dat
 | `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="start"` | Start edges aligned | Default | yes |
+| `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="end"` | End edges aligned | «⋯» buttons at the end of a row | |
+| `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 the label) | `false` |
+| `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 | |
 
@@ -160,11 +166,17 @@ The panel is the shared floating surface: the floating layer of the ladder (`dat
 | 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; items never wrap.
+- 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.
 
@@ -181,7 +193,9 @@ The panel is the shared floating surface: the floating layer of the ladder (`dat
 
 ### 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` and `aria-controls`.
+- 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).
@@ -199,6 +213,8 @@ No `labels`.
 | [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`. |
@@ -211,7 +227,9 @@ No `labels`.
 - 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`)
+- **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)