prime-ui-kit 0.14.0 → 0.16.0

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

@@ -8,33 +8,38 @@ const SIDES = [
 
 export default function DrawerPlacementExample() {
   return (
-    <>
+    <div>
       {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>
+        <div key={side}>
+          <Drawer.Root>
+            <Drawer.Trigger>
+              <Button.Root variant="soft" tone="neutral">
+                {title}
+              </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>
+          <Typography as="span" variant="caption" tone="muted">
+            {side}
+          </Typography>
+        </div>
       ))}
-    </>
+    </div>
   );
 }

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

@@ -0,0 +1,14 @@
+/* Form in a Drawer: group → group 32; a Fieldset sets heading → fields 16 and field → field 20. */
+
+.form {
+  display: grid;
+  gap: var(--prime-space-8);
+}
+
+/* Two short fields side by side when the panel is wide enough; tops aligned. */
+.pair {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-16) * 3)), 1fr));
+  align-items: start;
+  gap: var(--prime-space-5);
+}

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

@@ -0,0 +1,298 @@
+/** A create form in a Drawer opened from the primary action in the app header: grouped fields, errors on submit with focus on the first invalid field, a loading submit, a toast and the new row in the list — `Drawer.Trigger`, `Drawer.Guard`. */
+import {
+  AppHeader,
+  Badge,
+  Button,
+  Checkbox,
+  DataTable,
+  type DataTableColumn,
+  Drawer,
+  Fieldset,
+  Icon,
+  Input,
+  PageContent,
+  PageToolbar,
+  Radio,
+  Select,
+  SmartFilter,
+  Textarea,
+  useNotifications,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./screen.module.css";
+
+type Client = { id: string; name: string; kind: "company" | "person"; manager: string };
+type Errors = Partial<Record<"name" | "inn" | "email", string>>;
+
+const MANAGERS = ["Анна Климова", "Илья Петров", "Марат Хасанов"];
+
+const CLIENTS: Client[] = [
+  { id: "c1", name: "ООО «Северный ветер»", kind: "company", manager: "Анна Климова" },
+  { id: "c2", name: "АО «Техностиль»", kind: "company", manager: "Илья Петров" },
+  { id: "c3", name: "ИП Соколова М. А.", kind: "person", manager: "Анна Климова" },
+];
+
+const COLUMNS: DataTableColumn<Client>[] = [
+  { id: "name", header: "Клиент", accessor: "name" },
+  {
+    id: "kind",
+    header: "Тип",
+    cell: (row) =>
+      row.kind === "company" ? (
+        <Badge.Root color="blue">Компания</Badge.Root>
+      ) : (
+        <Badge.Root color="purple">ИП</Badge.Root>
+      ),
+  },
+  { id: "manager", header: "Менеджер", accessor: "manager" },
+];
+
+const CLIENT_WORDS = ["клиент", "клиента", "клиентов"] as const;
+const COMPANY_WORDS = ["компания", "компании", "компаний"] as const;
+
+/** «1 клиент», «3 клиента», «5 клиентов». */
+const plural = (count: number, [one, few, many]: readonly [string, string, string]) => {
+  const tens = count % 100;
+  const ones = count % 10;
+  if (tens >= 11 && tens <= 14) return `${count} ${many}`;
+  if (ones === 1) return `${count} ${one}`;
+  if (ones >= 2 && ones <= 4) return `${count} ${few}`;
+  return `${count} ${many}`;
+};
+
+function validate(data: FormData): Errors {
+  const errors: Errors = {};
+  const name = String(data.get("name") ?? "").trim();
+  const inn = String(data.get("inn") ?? "").replace(/\s/g, "");
+  const email = String(data.get("email") ?? "").trim();
+  if (!name) errors.name = "Введите название клиента";
+  if (!/^\d{10}(\d{2})?$/.test(inn)) errors.inn = "ИНН — 10 цифр для компании или 12 для ИП";
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+    errors.email = "Введите почту в формате name@company.ru";
+  return errors;
+}
+
+export default function DrawerScreenExample() {
+  const { notify } = useNotifications();
+  const formId = React.useId();
+  const [clients, setClients] = React.useState(CLIENTS);
+  const [open, setOpen] = React.useState(false);
+  const [errors, setErrors] = React.useState<Errors>({});
+  const [saving, setSaving] = React.useState(false);
+  const [dirty, setDirty] = React.useState(false);
+  const [manager, setManager] = React.useState(MANAGERS[0]);
+  const [search, setSearch] = React.useState("");
+
+  // Drawer.Guard holds every way out while saving and asks before an edited form is discarded.
+  const changeOpen = (next: boolean) => {
+    setOpen(next);
+    if (!next) {
+      setErrors({});
+      setDirty(false);
+    }
+  };
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const form = event.currentTarget;
+    const data = new FormData(form);
+    const found = validate(data);
+    setErrors(found);
+    const firstInvalid = (["name", "inn", "email"] as const).find((key) => found[key]);
+    if (firstInvalid) {
+      form.querySelector<HTMLInputElement>(`[name="${firstInvalid}"]`)?.focus();
+      return;
+    }
+    setSaving(true);
+    window.setTimeout(() => {
+      const name = String(data.get("name")).trim();
+      setClients((list) => [
+        {
+          id: `c${list.length + 1}`,
+          name,
+          kind: data.get("kind") === "person" ? "person" : "company",
+          manager,
+        },
+        ...list,
+      ]);
+      setSaving(false);
+      setDirty(false);
+      setOpen(false);
+      notify({ tone: "success", title: "Клиент добавлен", description: name });
+    }, 900);
+  };
+
+  const query = search.trim().toLowerCase();
+  const shown = clients.filter((client) => client.name.toLowerCase().includes(query));
+  const people = clients.filter((client) => client.kind === "person").length;
+
+  return (
+    <>
+      {/* The page lives in the app header: the only h1, the counts under it, search and the one
+          primary action — the Drawer trigger — in the tools row; main has no PageContent.Header. */}
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <AppHeader.Title>
+            Клиенты
+            <AppHeader.Description>
+              {plural(clients.length, CLIENT_WORDS)} ·{" "}
+              {plural(clients.length - people, COMPANY_WORDS)} и {people} ИП
+            </AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+        <AppHeader.Tools>
+          <SmartFilter.Root fields={[]} search={search} onSearchChange={setSearch}>
+            <PageToolbar.Root aria-label="Клиенты">
+              <PageToolbar.Tools>
+                <SmartFilter.Toolbar />
+              </PageToolbar.Tools>
+              <PageToolbar.Actions>
+                <Drawer.Root open={open} onOpenChange={changeOpen}>
+                  <Drawer.Trigger>
+                    <Button.Root>
+                      <Button.Icon>
+                        <Icon name="action.add" />
+                      </Button.Icon>
+                      Новый клиент
+                    </Button.Root>
+                  </Drawer.Trigger>
+                  <Drawer.Content>
+                    <Drawer.Header>
+                      <Drawer.Title>Новый клиент</Drawer.Title>
+                      <Drawer.Description>
+                        Появится в списке и в выборе клиента при выставлении счёта.
+                      </Drawer.Description>
+                    </Drawer.Header>
+                    <Drawer.Body>
+                      <Drawer.Guard busy={saving} dirty={dirty} />
+                      <form
+                        id={formId}
+                        className={styles.form}
+                        noValidate
+                        onSubmit={submit}
+                        onChange={() => setDirty(true)}
+                      >
+                        <Fieldset label="Реквизиты" disabled={saving}>
+                          <Radio.Group
+                            name="kind"
+                            label="Тип клиента"
+                            defaultValue="company"
+                            orientation="horizontal"
+                          >
+                            <Radio.Root value="company">
+                              <Radio.Label>Компания</Radio.Label>
+                            </Radio.Root>
+                            <Radio.Root value="person">
+                              <Radio.Label>ИП</Radio.Label>
+                            </Radio.Root>
+                          </Radio.Group>
+                          <Input.Root label="Название" error={errors.name}>
+                            <Input.Wrapper>
+                              <Input.Field
+                                name="name"
+                                placeholder="ООО «Ромашка»"
+                                autoComplete="organization"
+                              />
+                            </Input.Wrapper>
+                          </Input.Root>
+                          <div className={styles.pair}>
+                            <Input.Root label="ИНН" error={errors.inn} reserveSupportRow>
+                              <Input.Wrapper>
+                                <Input.Field
+                                  name="inn"
+                                  inputMode="numeric"
+                                  placeholder="7704512908"
+                                />
+                              </Input.Wrapper>
+                            </Input.Root>
+                            <Input.Root label="КПП" optional reserveSupportRow>
+                              <Input.Wrapper>
+                                <Input.Field
+                                  name="kpp"
+                                  inputMode="numeric"
+                                  placeholder="770401001"
+                                />
+                              </Input.Wrapper>
+                            </Input.Root>
+                          </div>
+                        </Fieldset>
+                        <Fieldset label="Контакты" disabled={saving}>
+                          <Input.Root
+                            label="Почта для счетов"
+                            error={errors.email}
+                            hint="На неё уйдут счета и акты"
+                          >
+                            <Input.Wrapper>
+                              <Input.Icon side="start">
+                                <Icon name="field.email" />
+                              </Input.Icon>
+                              <Input.Field
+                                name="email"
+                                type="email"
+                                placeholder="billing@company.ru"
+                              />
+                            </Input.Wrapper>
+                          </Input.Root>
+                          <Select.Root
+                            label="Менеджер"
+                            value={manager}
+                            onValueChange={(next) => {
+                              setManager(next);
+                              setDirty(true);
+                            }}
+                          >
+                            <Select.Trigger>
+                              <Select.Value />
+                            </Select.Trigger>
+                            <Select.Content>
+                              {MANAGERS.map((name) => (
+                                <Select.Item key={name} value={name}>
+                                  {name}
+                                </Select.Item>
+                              ))}
+                            </Select.Content>
+                          </Select.Root>
+                          <Textarea.Root name="note" label="Комментарий" optional rows={2} />
+                          <Checkbox.Root
+                            name="invite"
+                            defaultChecked
+                            hint="Клиент увидит свои счета и акты онлайн"
+                          >
+                            <Checkbox.Label>Пригласить в личный кабинет</Checkbox.Label>
+                          </Checkbox.Root>
+                        </Fieldset>
+                      </form>
+                    </Drawer.Body>
+                    <Drawer.Footer>
+                      <Drawer.Close>
+                        <Button.Root variant="outline" tone="neutral">
+                          Отмена
+                        </Button.Root>
+                      </Drawer.Close>
+                      <Button.Root type="submit" form={formId} loading={saving}>
+                        Добавить клиента
+                      </Button.Root>
+                    </Drawer.Footer>
+                  </Drawer.Content>
+                </Drawer.Root>
+              </PageToolbar.Actions>
+            </PageToolbar.Root>
+          </SmartFilter.Root>
+        </AppHeader.Tools>
+      </AppHeader.Root>
+
+      <PageContent.Root>
+        <PageContent.Body>
+          <DataTable
+            columns={COLUMNS}
+            rows={shown}
+            getRowKey={(row) => row.id}
+            paging="none"
+            empty="Клиентов не найдено"
+          />
+        </PageContent.Body>
+      </PageContent.Root>
+    </>
+  );
+}

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

@@ -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`)