@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/Drawer.md

@@ -0,0 +1,94 @@
+# `<Drawer>` — edge-anchored slide-in panel
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Button onClick={() => setOpen(true)}>Show filters</Button>
+
+<Drawer open={open} onOpenChange={setOpen} side="right" size="md">
+  <Drawer.Header>Filters</Drawer.Header>
+  <Drawer.Body>
+    <Stack gap="md">
+      <Input label="Name" value={...} onChange={...} />
+    </Stack>
+  </Drawer.Body>
+  <Drawer.Footer>
+    <Drawer.Close><Button variant="secondary">Cancel</Button></Drawer.Close>
+    <Button onClick={apply}>Apply</Button>
+  </Drawer.Footer>
+</Drawer>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `DrawerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `open` | `boolean` | yes | Controlled open state. Required — Drawer has no uncontrolled mode. |
+| `onOpenChange` | `(open: boolean) => void` | yes | Fired when Drawer wants to change open state — Esc, overlay click, Close, swipe, programmatic. |
+| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` | no | Edge the drawer slides in from: `left`, `right` (default), `top`, `bottom`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Size preset: `sm` 320px, `md` 440px (default), `lg` 640px. Width for left/right, height for top/bottom. Capped to `viewport - 32px` on narrow viewports; always edge-anchored, never fullscreen. |
+| `overlay` | `'solid' \| 'blur'` | no | Overlay variant. 'solid' (default) \| 'blur' (frosted glass, `backdrop-filter: blur(4px)`). |
+| `stackMode` | `'replace' \| 'overlay'` | no | How this drawer relates to other open overlays (Modals or Drawers). 'overlay' (default): parent stays visible. 'replace': parent hidden via display:none. |
+| `disableEscapeClose` | `boolean` | no | Disable Escape-to-close. Default false. |
+| `dismissOnOverlayClick` | `boolean` | no | When false, overlay click does NOT close. Default true. |
+| `dragToClose` | `boolean` | no | Enable swipe-to-close gesture on touch devices (from Header). Default true. |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | no | Initial focus target on open. |
+| `children` | `ReactNode` | yes |  |
+| `className` | `string` | no |  |
+| `style` | `CSSProperties` | no |  |
+| `aria-label` | `string` | no |  |
+| `aria-describedby` | `string` | no |  |
+
+### `DrawerBodyProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `padding` | `'none' \| 'default'` | no | Override body padding. Default 'default' (--space-4). 'none' for edge-to-edge. |
+| …native | | | plus native `<div>` attributes |
+
+### `DrawerCloseProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Exactly one React element. Close clones it to inject an onClick that closes the drawer, chained with the child's existing onClick. |
+
+### `DrawerFooterProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `align` | `'start' \| 'end' \| 'space-between'` | no | Horizontal action alignment. Default 'end'. |
+| …native | | | plus native `<div>` attributes |
+
+### `DrawerHeaderProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `closeButton` | `boolean` | no | Show the built-in × close button. Default true. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Compound API:** `<Drawer.Header>` — title, auto-wired `aria-labelledby`, built-in × close button unless `closeButton={false}`, and the drag-to-close origin; `<Drawer.Body>` — scrollable content; `<Drawer.Footer>` — pinned action bar; `<Drawer.Close>` — wraps a clickable child so activating it dismisses the drawer.
+- **Dialog semantics:** same focus-lock and scroll-lock as Modal. Passing neither `<Drawer.Header>` nor `aria-label` fires a dev warning.
+- **Drag-to-close** on mobile: swipe the Header in the dismiss direction (right drawer → swipe right, bottom → swipe down, etc.). Threshold: 40% of drawer size or 0.5 px/ms velocity. Opt out with `dragToClose={false}`.
+- **Stacks with Modal.** Both share one overlay registry — a Drawer can open from inside a Modal (and vice versa). Escape closes the topmost regardless of type — after yielding to any open floating surface (innermost-first: the first press closes the surface, the next closes the host); body scroll lock is shared.
+- **Focus return:** the element focused before the Drawer opened gets focus back on close — also when the Drawer mounts already open (`{seed && <Drawer open …/>}`) and when it unmounts while open. On unmount it only restores if focus was actually lost, so an element your own code focused after the unmount keeps focus.
+- **Forced step:** combine `disableEscapeClose + dismissOnOverlayClick={false} + dragToClose={false}` + `<Drawer.Header closeButton={false}>` + omit `<Drawer.Close>`.
+
+**Anti-patterns:**
+
+- ❌ Same-side stacked drawers as a navigation pattern. They visually overlap — use route changes instead.
+- ❌ Drag from inside `<Drawer.Body>` does not close the drawer. Only Header is draggable (so Body scroll works correctly).
+- ❌ For center-anchored dialogs, use `<Modal>` not Drawer. For lightweight popovers use `<Popover>` or `<DropdownMenu>`; for non-blocking notifications use `<Toast>` (not yet shipped).
+- ❌ Worrying about a `position: fixed` ancestor — the Drawer portals to `document.body`, so render it at any level.
+
+**See also:** `<Modal>` for center-anchored variant.

package/docs/components/DropdownMenu.md

@@ -0,0 +1,299 @@
+# `<DropdownMenu>` — action menus from a trigger
+
+```tsx
+<DropdownMenu>
+  <DropdownMenu.Trigger>
+    <Button variant="secondary">Actions</Button>
+  </DropdownMenu.Trigger>
+  <DropdownMenu.Content align="end">
+    <DropdownMenu.Item onSelect={edit}>Edit</DropdownMenu.Item>
+    <DropdownMenu.Item onSelect={duplicate} shortcut="⌘D">
+      Duplicate
+    </DropdownMenu.Item>
+    <DropdownMenu.Separator />
+    <DropdownMenu.Item onSelect={remove} tone="danger">
+      Delete
+    </DropdownMenu.Item>
+  </DropdownMenu.Content>
+</DropdownMenu>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `DropdownMenuProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | Must contain exactly one `<DropdownMenu.Trigger>` and one `<DropdownMenu.Content>`. |
+| `open` | `boolean` | no | Controlled open state. Provide alongside `onOpenChange` to drive open externally. Omit both to let DropdownMenu own its own state (the common case). |
+| `onOpenChange` | `((open: boolean) => void)` | no | Fired whenever DropdownMenu wants to change open state. Required when `open` is provided. |
+| `defaultOpen` | `boolean` | no | Default open state for uncontrolled usage. Defaults to `false`. |
+
+### `DropdownMenuCheckboxItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `checked` | `boolean` | yes | Whether the item is checked. |
+| `onCheckedChange` | `(checked: boolean) => void` | yes | Called with the new checked state when activated (click or Enter/Space). |
+| `closeOnSelect` | `boolean` | no | Whether activating closes the entire menu chain. Defaults to `false` — checkbox items typically toggle in place inside a multi-select menu. Set to `true` for single-toggle "apply and close" patterns. |
+| `disabled` | `boolean` | no | Disabled items don't fire `onCheckedChange`, are skipped by keyboard nav, and render dimmed. |
+| `icon` | `ReactNode` | no | Leading icon, rendered in a fixed-size slot before the label (parity with `<DropdownMenu.Item icon>`). Prefer this over inlining an icon into `children`: typeahead derives its match string from the string children, so an inlined leading icon leaves the JSX whitespace `" "` as the first string child and breaks first-letter type-to-select. Passing the icon here keeps the typeahead label the pure label string. Mark the glyph `aria-hidden`. |
+| `shortcut` | `string` | no | Optional trailing shortcut hint (e.g. `'⌘D'`). Visual cue only — does NOT register a global key handler. |
+| `meta` | `ReactNode` | no | Trailing secondary content *about the item itself* — a region code, a count, a `<Badge>`. Distinct from `shortcut`, which is a keyboard hint and is styled (and free to evolve) as one. `ReactNode`, so a Badge or Dot can go here. It is NOT `aria-hidden`, so it joins the item's accessible name ("demo RU" rather than a second identical "demo") — which is the point when the label alone is ambiguous. It is a prop, not a child, so it stays out of the typeahead label; type-to-select still matches the pure label text. Renders before `shortcut` when both are present, keeping the keyboard hint rightmost. |
+| `children` | `ReactNode` | yes | Item content. May include a `<DropdownMenu.ItemIndicator>` as a direct child to provide a custom indicator glyph. |
+| …native | | | plus native `<div>` attributes |
+
+### `DropdownMenuContentProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | no | Preferred side. Default `'bottom'`. Auto-flips on collision. |
+| `align` | `'start' \| 'center' \| 'end'` | no | Edge alignment. Default `'start'`. |
+| `sideOffset` | `number` | no | Gap in px between trigger and menu. Default `4`. |
+| `minWidth` | `string \| number` | no | Preferred minimum width in px or any CSS length. Defaults to the trigger's width and is reduced when necessary to keep the menu within the viewport. |
+| …native | | | plus native `<div>` attributes |
+
+### `DropdownMenuGroupProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | Menu items (and optionally a `<DropdownMenu.Label>`) to include in the group. |
+| …native | | | plus native `<div>` attributes |
+
+### `DropdownMenuItemIndicatorProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | no | Indicator content (icon, custom glyph, animated element) to render in the parent item's indicator slot. The parent — CheckboxItem or RadioItem — decides when this is rendered based on its own `checked` state. |
+| …native | | | plus native `<span>` attributes |
+
+### `DropdownMenuItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `onSelect` | `() => void` | yes | Called when the item is activated (click or Enter/Space). The consumer performs the action. |
+| `tone` | `'default' \| 'danger'` | no | Visual tone. - `'default'` — normal action. - `'danger'` — destructive (Delete, Revoke, Remove). Reserve for irreversible operations. |
+| `icon` | `ReactNode` | no | Leading icon. Rendered in a fixed-size slot so labels stay aligned across items. |
+| `shortcut` | `string` | no | Trailing shortcut hint (e.g. `'⌘D'`). Visual cue only — does NOT register a global key handler. |
+| `meta` | `ReactNode` | no | Trailing secondary content *about the item itself* — a region code, a count, a `<Badge>`. Distinct from `shortcut`, which is a keyboard hint and is styled (and free to evolve) as one. `ReactNode`, so a Badge or Dot can go here. It is NOT `aria-hidden`, so it joins the item's accessible name ("demo RU" rather than a second identical "demo") — which is the point when the label alone is ambiguous. It is a prop, not a child, so it stays out of the typeahead label; type-to-select still matches the pure label text. Renders before `shortcut` when both are present, keeping the keyboard hint rightmost. |
+| `disabled` | `boolean` | no | Disabled items are skipped by keyboard nav, dimmed, and don't fire `onSelect` on click. |
+| `closeOnSelect` | `boolean` | no | Whether to close the menu after `onSelect` fires. Defaults to `true`. Set to `false` when this item is wrapped in a Popover/ConfirmationPopover trigger — the trigger will open its panel on this click; closing the menu would unmount the popover before the user could interact with it. The menu can be dismissed separately (Escape or outside-click). |
+| …native | | | plus native `<div>` attributes |
+
+### `DropdownMenuLabelProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | The label text content. |
+| …native | | | plus native `<div>` attributes |
+
+### `DropdownMenuRadioGroupProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | The currently-selected value. Must match the `value` prop of one of the child RadioItems. |
+| `onValueChange` | `(value: string) => void` | yes | Called with the new value when a `<DropdownMenu.RadioItem>` is activated. |
+| `children` | `ReactNode` | yes | `<DropdownMenu.RadioItem>` children (and optionally `<DropdownMenu.Label>`). |
+| …native | | | plus native `<div>` attributes |
+
+### `DropdownMenuRadioItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | The value this item represents. Activating sets the parent RadioGroup's value to this. |
+| `closeOnSelect` | `boolean` | no | Whether activating closes the entire menu chain. Defaults to `true` — radio selection IS the action; the menu's job is done once a value is chosen. Set to `false` for preview-style selection where the menu stays open. |
+| `disabled` | `boolean` | no | Disabled items don't fire `onValueChange`, are skipped by keyboard nav, and render dimmed. |
+| `icon` | `ReactNode` | no | Leading icon, rendered in a fixed-size slot before the label (parity with `<DropdownMenu.Item icon>`). Prefer this over inlining an icon into `children`: typeahead derives its match string from the string children, so an inlined leading icon leaves the JSX whitespace `" "` as the first string child and breaks first-letter type-to-select. Passing the icon here keeps the typeahead label the pure label string. Mark the glyph `aria-hidden`. |
+| `shortcut` | `string` | no | Optional trailing shortcut hint (e.g. `'⌘N'`). Visual cue only — does NOT register a global key handler. |
+| `meta` | `ReactNode` | no | Trailing secondary content *about the item itself* — a region code, a count, a `<Badge>`. Distinct from `shortcut`, which is a keyboard hint and is styled (and free to evolve) as one. `ReactNode`, so a Badge or Dot can go here. It is NOT `aria-hidden`, so it joins the item's accessible name ("demo RU" rather than a second identical "demo") — which is the point when the label alone is ambiguous. It is a prop, not a child, so it stays out of the typeahead label; type-to-select still matches the pure label text. Renders before `shortcut` when both are present, keeping the keyboard hint rightmost. |
+| `children` | `ReactNode` | yes | Item content. May include a `<DropdownMenu.ItemIndicator>` as a direct child to provide a custom indicator glyph. |
+| …native | | | plus native `<div>` attributes |
+
+### `DropdownMenuSeparatorProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| …native | | | plus native `<div>` attributes |
+
+### `DropdownMenuSubContentProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | no | Preferred side. Default `'bottom'`. Auto-flips on collision. |
+| `align` | `'start' \| 'center' \| 'end'` | no | Edge alignment. Default `'start'`. |
+| `sideOffset` | `number` | no | Gap in px between trigger and menu. Default `4`. |
+| `minWidth` | `string \| number` | no | Preferred minimum width in px or any CSS length. Defaults to the trigger's width and is reduced when necessary to keep the menu within the viewport. |
+| …native | | | plus native HTML attributes |
+
+### `DropdownMenuSubProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | The submenu trigger and content to render. Should contain exactly one `<DropdownMenu.SubTrigger>` and one `<DropdownMenu.SubContent>`. |
+| `open` | `boolean` | no | Controlled open state. When provided, `defaultOpen` is ignored. |
+| `onOpenChange` | `((open: boolean) => void)` | no | Called when the open state changes (user opens or closes the sub). |
+| `defaultOpen` | `boolean` | no | Initial open state when uncontrolled. Defaults to `false`. |
+
+### `DropdownMenuSubTriggerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `disabled` | `boolean` | no | When `true`, the trigger renders dimmed and pointer/keyboard interaction does not open the sub. |
+| `icon` | `ReactNode` | no | Optional leading icon. Rendered in a fixed-size slot, matching `<DropdownMenu.Item>`'s icon slot. |
+| `children` | `ReactNode` | yes | The trigger label text. String children participate in the parent menu's typeahead. |
+| …native | | | plus native `<div>` attributes |
+
+### `DropdownMenuTriggerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Exactly one React element. The Trigger clones this element to inject a ref, `aria-haspopup="menu"`, `aria-expanded`, `aria-controls`, and the pointerdown/keyboard handlers that open the menu. The child must accept a ref (i.e. use `forwardRef` if it's a custom component); a raw `<button>` or the library's `<Button>` both qualify. |
+
+<!-- props:end -->
+
+- Compound API: `<DropdownMenu>` is the provider; `<Trigger>` clones its single child to inject ARIA + handlers; `<Content>` portals to `document.body` and positions itself with Floating UI; `<Item>` renders a `menuitem`; `<Separator>` renders a divider.
+- Trigger child must accept a ref via `forwardRef`. `<Button>` does.
+- `<Item>` props: `onSelect` (required), `disabled`, `tone` (`'default'` | `'danger'`), `icon`, `shortcut`, `meta`, `closeOnSelect` (default `true`; set to `false` when wrapping the Item in a `<Popover.Trigger>` or `<ConfirmationPopover>` — otherwise the menu close would unmount the popover before it can render).
+- `<Content>` props: `side` (`'top'` | `'bottom'`, default `'bottom'`), `align` (`'start'` | `'center'` | `'end'`, default `'start'`), `sideOffset` (default `4`), `minWidth`.
+- Keyboard: Enter/Space/ArrowDown on trigger opens with first item active; ArrowUp opens with last; Arrow/Home/End navigate skipping disabled and separators; Enter/Space activates; Escape closes and returns focus to trigger; Tab closes and returns focus to trigger (then continues normal traversal); typeahead jumps to first matching label (500ms debounce).
+- Opens with a short scale-fade from the trigger side (140 ms `ease-out`). Closes instantly by design — menu close should feel like "get out of the way", not "play a transition". Respects `prefers-reduced-motion: reduce`.
+- For value selection (pick a status, country, etc.), use `<Select>` (not yet shipped) — DropdownMenu is for actions, not form values.
+- **Overlay host (like Popover).** A `DropdownMenu` content panel is also an overlay host: a `Popover` / `ConfirmationPopover` / `Select` / date-time popover (`DatePicker` / `DateRangePicker` / `TimeField`) opened from a `DropdownMenu.Item` auto-elevates to `--z-overlay-floating` (1190) so it floats above the menu (and above any Popover the menu itself lives in). Normal submenus are unaffected — they inherit the root trigger's overlay state.
+
+#### v2 — submenus, checkboxes, radios, groups
+
+```tsx
+<DropdownMenu>
+  <DropdownMenu.Trigger>
+    <Button variant="secondary">Filters</Button>
+  </DropdownMenu.Trigger>
+  <DropdownMenu.Content>
+    <DropdownMenu.Group>
+      <DropdownMenu.Label>Status</DropdownMenu.Label>
+      <DropdownMenu.CheckboxItem checked={active} onCheckedChange={setActive}>
+        Active
+      </DropdownMenu.CheckboxItem>
+      <DropdownMenu.CheckboxItem checked={pending} onCheckedChange={setPending}>
+        Pending
+      </DropdownMenu.CheckboxItem>
+    </DropdownMenu.Group>
+
+    <DropdownMenu.Separator />
+
+    <DropdownMenu.Group>
+      <DropdownMenu.Label>Sort by</DropdownMenu.Label>
+      <DropdownMenu.RadioGroup value={sort} onValueChange={setSort}>
+        <DropdownMenu.RadioItem value="name">Name</DropdownMenu.RadioItem>
+        <DropdownMenu.RadioItem value="date">Date</DropdownMenu.RadioItem>
+      </DropdownMenu.RadioGroup>
+    </DropdownMenu.Group>
+
+    <DropdownMenu.Sub>
+      <DropdownMenu.SubTrigger>More</DropdownMenu.SubTrigger>
+      <DropdownMenu.SubContent>
+        <DropdownMenu.Item onSelect={exportCsv}>Export CSV</DropdownMenu.Item>
+        <DropdownMenu.Item onSelect={exportJson}>Export JSON</DropdownMenu.Item>
+      </DropdownMenu.SubContent>
+    </DropdownMenu.Sub>
+  </DropdownMenu.Content>
+</DropdownMenu>
+```
+
+- `<CheckboxItem>` — `role="menuitemcheckbox"`, `aria-checked`. Default `closeOnSelect={false}` (multi-select friendly). Pass `closeOnSelect` to override. Checked items render an accent-tinted row + 2px left accent (no glyph by default).
+- `<RadioGroup>` + `<RadioItem>` — `role="radiogroup"` / `role="menuitemradio"`. Default `closeOnSelect={true}` (radio = the selection IS the action). Selected item gets the same accent-tinted-row treatment as checked CheckboxItem.
+- **Leading `icon` on `CheckboxItem` / `RadioItem`** (parity with `<Item icon>`) — pass a per-row glyph via the `icon` prop, **not** inlined into `children`. Typeahead derives its match string from the string children, so an inlined leading icon leaves the JSX whitespace `" "` as the first string child and kills first-letter type-to-select; the `icon` prop keeps the typeahead label the pure string. Mark the glyph `aria-hidden`. `icon={<Moon size={14} aria-hidden />}`.
+- `<Group>` + `<Label>` — wrap a section. Group is `role="group"` with `aria-labelledby` to the Label. Label outside Group still renders, no aria wiring.
+- `<Sub>` + `<SubTrigger>` + `<SubContent>` — nested menu. SubTrigger registers in the parent menu; SubContent is its own portaled panel. Opens on click, hover (100ms delay), Enter, or ArrowRight. Closes on ArrowLeft (level-only), Escape (level-only), click-outside (all levels), or selecting an item with `closeOnSelect=true` (all levels — cascading close).
+- `<ItemIndicator>` — optional slot child of CheckboxItem/RadioItem that adds a custom indicator glyph alongside the tinted-row treatment. Omit entirely when the row tint is sufficient (the common case). Detection is shallow: must be a direct child.
+- Per WAI-ARIA, mixing CheckboxItem and RadioItem in the same RadioGroup is invalid; CheckboxItems live outside RadioGroup.
+- **Trailing `meta` on `Item` / `CheckboxItem` / `RadioItem`** — secondary content _about the item itself_ (a region code, a count, a `<Badge>`). `ReactNode`. It is **not** `shortcut`: `shortcut` is a keyboard hint, styled as one, and free to become a `<Kbd>` key cap. Two rows whose labels legitimately collide (two workspaces both named `demo`) are disambiguated with `meta`, not `shortcut`.
+
+  ```tsx
+  <DropdownMenu.RadioGroup value={workspace} onValueChange={setWorkspace}>
+    <DropdownMenu.RadioItem value="demo-eu" meta="EU">
+      demo
+    </DropdownMenu.RadioItem>
+    <DropdownMenu.RadioItem value="demo-ru" meta="RU">
+      demo
+    </DropdownMenu.RadioItem>
+  </DropdownMenu.RadioGroup>
+  ```
+
+  `meta` renders after the label and before `shortcut` (the keyboard hint stays rightmost). It carries no `aria-hidden`, so it **joins the accessible name** — a screen reader announces "demo RU". Because it is a prop and not a child, it stays **out of the typeahead label**: type-to-select still matches the bare label.
+
+- ❌ Using DropdownMenu as a panel (a notification centre, a header with a "Mark all as read" button, rich feed rows). It is `role="menu"`, which may only hold menu items; a header button is invalid ARIA and unreachable by the menu's arrow keys. Use `Popover` + `ScrollArea`.
+
+#### More usage
+
+```tsx
+// Controlled open (rare — usually let DropdownMenu manage state)
+<DropdownMenu open={open} onOpenChange={setOpen}>...</DropdownMenu>
+
+// Table row kebab
+<DropdownMenu>
+  <DropdownMenu.Trigger>
+    <Button variant="ghost" aria-label="Row actions">⋯</Button>
+  </DropdownMenu.Trigger>
+  <DropdownMenu.Content align="end">
+    <DropdownMenu.Item onSelect={() => view(row)}>View</DropdownMenu.Item>
+    <DropdownMenu.Item onSelect={() => archive(row)}>Archive</DropdownMenu.Item>
+  </DropdownMenu.Content>
+</DropdownMenu>
+
+// CheckboxItem that applies then closes
+<DropdownMenu.CheckboxItem checked={isOn} onCheckedChange={setOn} closeOnSelect>
+  Apply and close
+</DropdownMenu.CheckboxItem>
+
+// RadioItem that keeps the menu open (e.g. live preview)
+<DropdownMenu.RadioItem value="compact" closeOnSelect={false}>Compact</DropdownMenu.RadioItem>
+
+// Custom glyph alongside the tinted checked row
+<DropdownMenu.CheckboxItem checked={isOn} onCheckedChange={setOn}>
+  <DropdownMenu.ItemIndicator><CheckIcon size={14} /></DropdownMenu.ItemIndicator>
+  Show archived
+</DropdownMenu.CheckboxItem>
+
+// Controlled submenu
+<DropdownMenu.Sub open={subOpen} onOpenChange={setSubOpen}>...</DropdownMenu.Sub>
+
+// Item with both trailing slots: `meta` qualifies the item and joins the accessible name
+// ("Duplicate 3 files"); `shortcut` is a keyboard hint.
+<DropdownMenu.Item onSelect={onDuplicate} meta="3 files" shortcut="⌘D">Duplicate</DropdownMenu.Item>
+```
+
+#### When NOT to use
+
+- An always-visible row of actions: use a `<Cluster>` of Buttons in a toolbar. Menus are for actions that don't deserve permanent screen space.
+- Navigation between pages: use the sidebar or a `<Link>`. Menu items are for actions, not page transitions.
+- `CheckboxItem` for a one-off action (use `Item`) or for mutually exclusive choices (use `RadioGroup`); `RadioGroup` for an action menu or for multi-select (use `CheckboxItem`s).
+- `Group` around a single Item, as a generic layout primitive (use `<Stack>` / `<Cluster>`), or around a `RadioGroup` that needs no visible Label (`RadioGroup` already has `role="radiogroup"`).
+- `Label` as a clickable item: it has no `role="menuitem"` and is not keyboard-focusable; use a disabled `Item` for a selectable header-style row. Outside a `Group` it carries no `aria-labelledby` wiring.
+- `Sub` for top-level sections (use `Group` + `Label`), beyond 2–3 nesting levels, or on touch-first surfaces — submenus rely on hover and lateral arrow keys.
+
+#### Rules and anti-patterns
+
+- `RadioItem` must be inside a `RadioGroup`, and `SubTrigger` inside a `Sub` — both throw in dev otherwise. A `Sub` holds exactly one `SubTrigger` and one `SubContent`.
+- `Content` renders only while the menu is open. `Separator` is a decorative `role="separator"`, not focusable.
+- ❌ Multiple `<DropdownMenu.Trigger>`s in one `<DropdownMenu>`: use one DropdownMenu per trigger.
+- ❌ `tone="danger"` for non-destructive actions like "Filter" or "Sort"; reserve it for irreversible destructive operations.
+- ❌ Nesting a full `<DropdownMenu>` root inside another; use `<DropdownMenu.Sub>`.
+- ❌ Putting `<ItemIndicator>` deeper than a direct child of CheckboxItem / RadioItem: the custom glyph is silently dropped (the row still looks selected). In a plain `<Item>` it just renders inline as any other child.
+- ❌ Using `shortcut` for text that is not a keyboard hint (a region code, a count, a status) — use `meta`.
+- ❌ Several checked CheckboxItems in a "pick one" context: switch to `RadioGroup`.

package/docs/components/EmojiPicker.md

@@ -0,0 +1,84 @@
+# `<EmojiPicker>` — searchable emoji grid (reactions + input)
+
+**Use to let the user pick an emoji** — a reaction chip, an inline insert into a
+message/comment. Searchable, category-sectioned, keyboard-navigable 8-column grid
+over a **curated common set** (not the full ~1900-emoji Unicode catalog;
+skin-tone / ZWJ variants are out). It's the chooser only — calls
+`onSelect(emoji: string)` on click or Enter/Space; it has no notion of which
+emoji are already chosen or their counts. The bare picker is a surface — pair it
+with a `Popover` (or use `EmojiPickerPopover`).
+
+```tsx
+// Inside a Popover you control (e.g. an "add reaction" button on a comment):
+<Popover>
+  <Popover.Trigger>
+    <Button iconOnly variant="ghost" aria-label="Add reaction">
+      <Smile size={16} />
+    </Button>
+  </Popover.Trigger>
+  <Popover.Content>
+    <EmojiPicker onSelect={(emoji) => addReaction(emoji)} />
+  </Popover.Content>
+</Popover>
+
+// Batteries-included wrapper — owns the Popover, closes on select:
+<EmojiPickerPopover
+  trigger={<Button variant="secondary" size="sm">Add reaction</Button>}
+  onSelect={(emoji) => appendToDraft(emoji)}
+/>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `EmojiPickerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `invalid` | `boolean` | no | Consumed so a Field / SettingRow wrapping the picker cannot leak it onto the root div. The picker has no value to validate, so it renders nothing. |
+| `required` | `boolean` | no | Consumed for Field / SettingRow composition; the picker has no value, so nothing is forwarded. |
+| `onSelect` | `(emoji: string) => void` | yes | Fired with the chosen emoji character (e.g. `'👍'`) when the user clicks a cell or presses Enter/Space on a focused cell. This is the picker's single output — wire it to insert into an editor, set a reaction, etc. |
+| `recent` | `string[]` | no | Recently-used emoji characters (e.g. `['👍', '🎉', '❤️']`), most-recent first. When provided, a "Recently used" section renders at the top of the grid (only while not searching). The consumer owns persistence — keep the list yourself (e.g. in localStorage), update it in `onSelect`, and pass it back. Duplicates are de-duped; a char outside the curated set still renders (labelled by the char). Omit or pass `[]` for no recent section. |
+| …native | | | plus native `<div>` attributes |
+
+### `EmojiPickerPopoverProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `trigger` | `ReactNode` | yes | The element that opens the picker. Must be a single element that accepts a ref (this library's `<Button>` or a raw `<button>`); the open/close + ARIA wiring is injected by `Popover.Trigger`. |
+| `onSelect` | `(emoji: string) => void` | yes | Fired with the chosen emoji character. Selecting always closes the popover (both controlled and uncontrolled). |
+| `recent` | `string[]` | no | Recently-used emoji chars shown in a top "Recently used" section — see `EmojiPicker`. |
+| `open` | `boolean` | no | Controlled open state. Provide alongside `onOpenChange` to drive open externally. Omit both to let the wrapper own its state (the common case). |
+| `onOpenChange` | `((open: boolean) => void)` | no | Fired whenever the popover wants to change open state. Required when `open` is provided. |
+| `defaultOpen` | `boolean` | no | Initial open state for uncontrolled usage. Defaults to `false`. |
+
+<!-- props:end -->
+
+`EmojiPickerPopover` takes `trigger` + `onSelect`, plus the standard
+controlled-open contract (`open` / `onOpenChange` / `defaultOpen`).
+
+`recent?: string[]` (on both) pins a "Recently used" section at the top (shown only
+while not searching). The consumer owns persistence — keep the list (e.g.
+localStorage), update it in `onSelect` (move-to-front + de-dupe + cap), pass it back.
+
+**When NOT to use:** a small fixed reaction set (👍 ❤️ 🎉) → render a `Cluster`
+of `Button`s; a searchable grid is overkill for 3-6 choices. Also not for inline
+`:smile`-style autocomplete (the editor's suggestion engine owns that) or for
+rendering existing reaction counts (the consumer builds that display).
+
+```tsx
+// Controlled wrapper
+const [open, setOpen] = useState(false);
+<EmojiPickerPopover open={open} onOpenChange={setOpen} trigger={<Button>Emoji</Button>} onSelect={setEmoji} />
+
+// Reaction toggle on a comment
+<EmojiPickerPopover
+  trigger={<Button size="sm" variant="secondary">React</Button>}
+  onSelect={(char) => toggleReaction(commentId, char)}
+/>
+```
+
+❌ Expecting it to show which emoji a message already has or how many times — it only chooses.

package/docs/components/EmptyState.md

@@ -0,0 +1,55 @@
+# `<EmptyState>` — "nothing here" container
+
+```tsx
+<EmptyState
+  icon={<Inbox size={32} />}
+  title="No contacts yet"
+  description="Add your first contact to get started."
+  actions={<Button>Add contact</Button>}
+/>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | no | Icon rendered above the title. Pass a lucide icon, custom SVG, or any ReactNode. Sized by the consumer — recommended: sm=24, md=32, lg=48. Omit for an icon-less empty state. |
+| `title` | `ReactNode` | yes | Required title. Rendered as a semantic heading (default `<h3>`). Accepts ReactNode so inline emphasis works (e.g., `<>Found <strong>0</strong> results</>`). Keep it short and announceable — AT users hear it via heading navigation. |
+| `description` | `ReactNode` | no | Optional description rendered below the title. |
+| `actions` | `ReactNode` | no | Optional action(s) rendered below the description. Typically a `<Button>` or a `<Cluster gap="sm">` of buttons. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Visual size. Defaults to `'md'`. - `'sm'` — compact for inline / popover use (empty Select results, empty filter chips). Icon target 24px, font-size-sm title. - `'md'` — default for cards / sections (DataTable empty row, inbox empty). Icon target 32px, font-size-md title. - `'lg'` — hero / full-page empty states. Icon target 48px, font-size-xl title. |
+| `align` | `'center' \| 'start'` | no | Horizontal alignment of the stacked content. Defaults to `'center'`. Use `'start'` when the empty state sits in a tight column where centering would look stranded. |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | Heading level for the `title`. Defaults to `3` (renders `<h3>`). Set higher (4–6) when the empty state lives deep inside the page's heading hierarchy. Set to `2` when the empty state IS the page's primary content. Values outside `1–6` clamp to `3`. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- Use `<Skeleton>` for **loading** states — EmptyState implies "nothing here," not "data on its way."
+- No `variant="error"` — error treatments need different a11y (live regions, retry actions). Use a future `<Alert>` or render a danger-tinted EmptyState with your own error message.
+- No automatic `aria-hidden` on the icon — consumer's icon may be semantic (e.g., a country-flag icon in a "No results for this region" state). If the icon is purely decorative, the consumer should pass `aria-hidden`.
+- The wrapper `<section>` only becomes a screen-reader landmark when it has an accessible name — pass `aria-label` (or `aria-labelledby`) when the empty state should be navigable as a region (typically when it IS the page's primary content with `headingLevel={1 | 2}`).
+- Not for a page-level 404 / 500 — use a dedicated error page.
+- For unusual layouts compose `<Stack>` + `<Button>` directly; this component is deliberately inflexible.
+- ❌ A long sentence as `title` — keep titles short; long strings hurt heading navigation.
+- ❌ Multiple primary action buttons — one clear next action; secondaries are `ghost`.
+
+```tsx
+// Multiple actions
+<EmptyState
+  icon={<Search size={32} />}
+  title="No results"
+  description="Try a different query or clear the filters."
+  actions={
+    <Cluster gap="sm" justify="center">
+      <Button onClick={clearFilters}>Clear filters</Button>
+      <Button variant="ghost" onClick={openSearch}>New search</Button>
+    </Cluster>
+  }
+/>
+
+// Inline (e.g. a Select dropdown's empty results)
+<EmptyState size="sm" icon={<SearchX size={24} />} title="No matches" />
+```