@eocrm/design-system 0.0.0-stage → 0.6.18

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" />
+```

package/docs/components/EntityChip.md

@@ -0,0 +1,102 @@
+# `<EntityChip>` — inline entity-link chip
+
+```tsx
+// Inline, inside a sentence — canonically a link to its entity:
+<Text>
+  Reassigned <EntityChip href="/contacts/12" icon={<User size={14} />} label="Priya Shah" /> to this deal.
+</Text>
+
+// href, prefix + status:
+<EntityChip
+  href="/tasks/5"
+  prefix="ENG-5"
+  label="Fix login bug"
+  status={{ label: 'In progress', category: 'in_progress' }}
+/>
+
+// RouterLink via `as`, or a status color override:
+import { Link as RouterLink } from 'react-router-dom';
+<EntityChip as={RouterLink} to="/deals/9" label="Acme Corp" status={{ label: 'At risk', color: 'amber' }} />
+
+// Chip fill override (categorical, independent of status):
+<EntityChip href="/deals/9" label="Acme Corp" color="violet" />
+
+// One-line list row: only the label ellipsizes; adornments inside the chip:
+<EntityChip
+  truncate
+  href="/tasks/5"
+  icon={<CheckSquare size={14} />}
+  prefix="ENG-5"
+  label="Fix the login bug that only happens on Safari"
+  status={{ label: 'In progress', category: 'in_progress' }}
+  trailing={<ArrowUp size={14} aria-label="High priority" />}
+/>
+
+// Segmented task chip — coloured `before`/`after` parts, capped label:
+<EntityChip
+  as={RouterLink} to="/tasks/ENG-15"
+  prefix="ENG-15" label="Fix the login bug on Safari" labelMaxWidth={40}
+  before={[{ kind: 'icon', icon: <Bug />, label: 'Bug', color: 'red' }]}
+  after={[
+    { kind: 'icon', icon: <Equal />, label: 'Normal priority', color: 'slate' },
+    { kind: 'text', text: 'Reported', color: 'amber' },
+  ]}
+/>
+
+// `labelWeight="semibold"` — a heavier key + title:
+<EntityChip href="/tasks/ENG-15" prefix="ENG-15" label="Fix the login bug on Safari" labelWeight="semibold" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | no | Leading icon — consumer passes the element (e.g. a lucide icon). Rendered aria-hidden. |
+| `label` | `ReactNode` | no | Entity name. Optional at the type level only to satisfy the polymorphic `forwardRef` generic (same workaround `<Rail.Item>` documents on its `children`); in practice every chip needs a label. |
+| `prefix` | `ReactNode` | no | Muted leading run before the name (e.g. task key `ENG-5`). |
+| `status` | `EntityChipStatus` | no | Inline workflow status `{ label, category?, color? }`, separated by a small dot and rendered in the status's own color. `category` (`to_do`/`in_progress`/`open`/`done`/`won`/`lost`) resolves a default palette color (same mapping as `<PillMenu>`); `color` overrides it. The dot takes the resolved color too. |
+| `color` | `PaletteColor` | no | Optional categorical palette color for the chip fill. When set, takes precedence over the default accent chip tokens: the chip fills with the matching `--color-palette-<name>-bg/-fg` pair (same contract as `Badge color` — picking a readable pair is the consumer's call). Omit for the default fill, which matches RichText's `@mention` styling (`--color-accent-bg-subtle` / `--color-accent`) so a chip and a rendered mention read as the same visual object. The `status` run keeps its own resolved color independent of this prop, and `unavailable` still mutes the label/status text over any `color`. |
+| `href` | `string` | no | Renders `as="a"` with this href when `as` is omitted. |
+| `loading` | `boolean` | no | Loading placeholder: icon slot + `…` body, aria-busy; the label stays in the DOM visually hidden so the chip keeps its accessible name. Purely visual — with a link target (`href`/`as`) the chip stays a live, keyboard-reachable link while loading. The state is announced: a localized word is rendered visually hidden, so a linked chip's name becomes "Appointment (loading)". `aria-busy` alone did not do this. It is a GLOBAL ARIA state, so unlike `aria-disabled` it is perfectly valid on the chip's role-less span and browsers do expose it — but no mainstream screen reader conveys `busy` as a state on a non-live element, and the ellipsis is `aria-hidden`. The label reached the user fine; no signal of the LOADING STATE did. Know the trade: the accessible name CHANGES when loading resolves — and by more than this word. The loading branch renders neither `prefix` nor `status` (nor `before`/`after` segments), so a chip with both goes from "Fix login bug (loading)" to "ENG-5 Fix login bug In progress". That is unavoidable when announcing a transient state through the name, and it is why this was initially left alone. Note it also means a consumer query like `getByRole('link', { name: 'Appointment' })` no longer matches a LOADING chip. Measured, the mutation itself is benign: Chromium keeps the SAME accessibility node across the transition (same backendNodeId) and focus survives, so nothing is torn down and rebuilt — the name and `busy` simply change on the existing object. The alternative — an `aria-live` region — has to be owned by the consumer, because only the consumer knows whether a given chip resolving is worth interrupting someone for. To take that route, override this word to `''` at your TOP-LEVEL provider: the override is global to a provider subtree (there is no per-chip opt-out), `I18nProvider` requires a `locale`, and a nested provider replaces rather than extends its parent — so wrapping a single chip would silently discard every other override you have set. |
+| `unavailable` | `boolean` | no | Entity missing/no access: muted styling. With a link target (`href`/`as`) the chip remains a real link — unavailable is a visual state, not a disabling one. Only a target-less chip (bare span) becomes non-interactive with aria-disabled. The state is also announced: a localized word is rendered visually hidden inside the chip. A linked chip's accessible name becomes "Appointment (unavailable)"; a target-less chip is `role=generic`, which has no accessible name at all, so the word is announced as part of the chip's text in reading order. Either way it reaches the user. That matters because the canonical use is to withhold the entity's name and show a TYPE word instead — without the state, a masked reference is indistinguishable from a real entity that happens to be called "Appointment". Colour alone cannot carry it, and `aria-disabled` does not either: browsers do expose it, but it carries no meaning on a non-widget role such as `generic`, so no assistive tech conveys it. `loading` is announced the same way — see that prop for why `aria-busy` alone was not enough, and for the name-mutation trade it carries. Do NOT put an `aria-label` on the chip. It replaces the whole name and takes the state word with it; the state lives in the chip's contents. Override the word via the i18n provider (`entityChip.unavailable`); it carries its own punctuation so a locale can choose different marks. |
+| `truncate` | `boolean` | no | Single-line mode for list rows. The chip is capped at its container's width (`max-width: 100%`, `min-width: 0`, so it also shrinks as a flex item) and only the `label` ellipsizes — `icon`, `prefix`, `status` and `trailing` keep their full size. Default `false`: the label wraps, which is right for a chip inside running text. The full label stays in the DOM, so the accessible name is unchanged. A clipped label shows its full text in a tooltip on hover or keyboard focus — don't add a `title`, which would give a double tooltip. |
+| `trailing` | `ReactNode` | no | Extra adornments inside the chip, after `status` (e.g. a priority icon or a status `<Badge>`), kept at full size under `truncate`. Not rendered while `loading` (same as `prefix`/`status`). Non-interactive content only: the chip is itself a link, so a button or link here is invalid nested interactive content. Its text JOINS the chip's accessible name ("ENG-5 Fix login bug High") — give a decorative icon `aria-hidden`, and a meaningful one a short text alternative. |
+| `before` | `readonly EntityChipSegment[]` | no | Coloured segments before the chip's core, in order (e.g. the task type). Any segment turns the chip segmented: one line, only the outer corners rounded, only the label shrinks (as with `truncate`). Every segment's text joins the accessible name ("Bug ENG-15 Fix login bug Normal Reported"). Not rendered while `loading` or `unavailable`. |
+| `after` | `readonly EntityChipSegment[]` | no | Coloured segments after the core, in order (e.g. priority, status). See `before`. |
+| `labelMaxWidth` | `number` | no | Caps the label's width, a positive number of `ch`; past it the label ellipsizes on one line (also on a chip without `truncate`). For chips in running text, where the container edge is a whole paragraph away. The full label stays in the DOM and the accessible name; a clipped label shows it in a tooltip on hover or keyboard focus. |
+| `labelEllipsis` | `'end' \| 'start'` | no | Which end of a clipped label is cut. Applies only where the label can clip at all (`truncate`, segments, or `labelMaxWidth`); ignored on a wrapping chip. - `'end'` (default) — `Fix the login bu…`. Right for titles, whose distinctive part is the start. - `'start'` — `…/pull/1116`. For labels whose distinctive part is the tail, e.g. a URL path under a host `prefix`. The text keeps its order; `prefix` and segments stay whole, and the tooltip still shows it all. |
+| `labelWeight` | `'medium' \| 'semibold'` | no | Font weight for `label`. `'medium'` (default) matches a plain chip's fixed weight and the RichText `@mention` — most chips should leave this unset. `'medium'` does NOT apply to `prefix`: `.prefix` carries no font-weight rule of its own and simply inherits (normal), so a default chip's key is lighter than its title. `'semibold'` is the one value that touches BOTH — it sets `prefix` AND `label` to the same heavier weight (a task-chip design that wants its key heavier along with its title). Use `'semibold'` for a design that explicitly wants that. Don't reach for a styled `<Text weight="semibold">` around `label` to get a heavier title instead (see the clipped-label tooltip bullet in `docs/components/EntityChip.md`) — it buys nothing: the clipped-label tooltip reads the label's own `textContent` and always renders it plain, in the tooltip's own color, regardless of what the label node carries. Only this prop changes the rendered weight. |
+| `as` | `ElementType` | no |  |
+| …native | | | plus native attributes of the `as` element (default `<a>`) |
+
+<!-- props:end -->
+
+- Polymorphic inline chip: optional `icon` (rendered `aria-hidden`), optional muted `prefix` (e.g. a task key), the `label`, and an optional colored `status`. All inline `<span>`s inside one root — safe to drop directly inside a `<p>`/`<Text>`.
+- **An EntityChip is always a link to its entity**: pass `href` (renders `<a href>`) or `as` (`RouterLink`, `'button'`, any component — same polymorphic contract as `<Link>`). The bare `<span>` form (no target) is for rare non-navigable contexts only.
+- Default chip fill matches RichText's `@mention` styling (`--color-accent-bg-subtle` / `--color-accent`) — a chip and a rendered mention read as the same visual object in both themes. `color?: PaletteColor` overrides the fill (same inline-injection contract as `Badge color`) — independent of `status`, which keeps its own resolved color. `unavailable` still mutes the label/status/dot over any `color`.
+- ⚠️ **On a chip with a link target, both state words change the accessible name**, so a name-exact query stops matching: `getByRole('link', { name: 'Appointment' })` misses a chip that is loading or unavailable. If your tests select chips by name over lists that render placeholders, use a regex or query before the state applies.
+- **`loading` is announced too.** Same mechanism, and `aria-busy` alone did not do it either — it is a _global_ ARIA state so it IS valid on the role-less span and browsers expose it, but no mainstream screen reader reliably conveys `busy` on a non-live element, and the `…` is `aria-hidden`. The label reached the user; the state did not. A linked chip's name becomes `"Appointment (loading)"`. **The trade:** the accessible name changes when loading resolves. Announcing a transient state through the name always costs that; the alternative is a consumer-owned `aria-live` region, since only the consumer knows whether a chip resolving is worth interrupting for. Override the word to `''` **at your top-level provider** if you'd rather handle it yourself — a nested `I18nProvider` replaces its parent rather than extending it, so wrapping a single chip would discard every other override you have set.
+- **`unavailable` is announced, not just muted.** A localized word is rendered visually hidden inside the chip. A **linked** chip's accessible name becomes `"Appointment (unavailable)"`; a **target-less** chip is `role=generic`, which has no accessible name at all, so the word is announced as part of the chip's text in reading order. Either way it reaches the user.
+- Why `aria-disabled` was not enough: browsers do expose it, but it carries no meaning on a non-widget role such as `generic`, so no assistive tech conveys it. This matters because the canonical use is to withhold the entity's name and show a TYPE word instead — without the state, a masked reference is indistinguishable from a real entity that happens to be called "Appointment".
+- ❌ Don't put an `aria-label` on the chip — it replaces the whole name and takes the state word with it. The state lives in the chip's contents. Override the word via `<I18nProvider overrides={{ entityChip: { unavailable: '…' } }}>` instead; it carries its own punctuation so a locale can pick different marks.
+- **`truncate`** — single-line mode for list rows: the chip caps at its container (`max-width: 100%`, `min-width: 0`) and only `label` ellipsizes; `icon`/`prefix`/`status`/`trailing` keep full size. The accessible name keeps the full label. Default wraps — right for chips in running text, so don't set `truncate` there.
+- **`trailing`** — adornments inside the chip after `status` (a priority icon, a `<Badge>`), full size under `truncate`, not rendered while `loading`. Its text JOINS the link's name (`aria-hidden` a decorative icon). ❌ Never interactive content — the chip is a link; row actions go beside it.
+- Hover affordance on link/button chips: the background deepens a step plus a brightness dip. Never a weight change, never an underline, even under aggressive consumer link CSS.
+- Chip text inherits the surrounding font size — inside a heading it renders at heading size, by design (that's what keeps the chip box symmetric around the local text in any context).
+- **Segments** (`before` / `after`): coloured parts butted against the chip — `{ kind: 'icon', icon, label, color?, size? }` (label = accessible name + tooltip) or `{ kind: 'text', text, color?, tooltip?, size? }`; `size` is in em of the chip text, at most 1 (larger is clamped, so a segment never makes the chip taller or knocks its text off the label's baseline); glyph default 0.85em, text default 0.9em. The whole chip stays one link; every segment joins its name. Any segment makes the chip one line (only the label shrinks) with only the outer corners rounded. Not rendered while `loading`/`unavailable`. `labelMaxWidth` (ch) caps the label in running text; a clipped label shows its full text in a tooltip on hover or keyboard focus. That text is always plain; a non-string `label` is read when the tooltip opens, so it can show old text if the label changes while the tooltip is open. `labelEllipsis="start"` cuts a clipped label from its START (`…/pull/1116`) for labels whose tail is the distinctive part, e.g. a URL path under a host `prefix`; default `'end'`. Ignored on a chip whose label can't clip.
+- **A text segment's text sits on the label's baseline, not centred**: the segment's own box keeps the chip's font-size/line-height (so its box and first-line baseline match the core exactly); the smaller `--entity-chip-segment-text-size` lives on an inner span instead, which then sits on that baseline through normal inline layout. Icon (glyph) segments stay vertically centred, as before — only text segments changed.
+- **The clipped-label tooltip is always plain text**: it reads the label element's own `textContent` when it opens, not the `label` node itself — so a styled `label` (e.g. a `<Text tone="accent">`) never leaks its color/weight into the tooltip. No prop controls this; it's automatic.
+- **`labelWeight`**: `'medium'` (default, matches a plain chip / the RichText `@mention`) applies to `label` only — `prefix` has no weight rule of its own and stays inherited (normal). `'semibold'` is the one value that also touches `prefix`, setting BOTH `prefix` and `label` together (a heavier key + title, e.g. a segmented task chip). Backed by a component token (`--entity-chip-label-font-weight-semibold`), not by wrapping `label` in a styled `<Text>` — see the anti-pattern below.
+- **When NOT to use**: plain status with no linked entity → `<Badge>`/`<PillMenu>`; standalone navigation with no icon/prefix/status chrome → `<Link>`; removable filter pills → `<FilterChip>`.
+- **Anti-pattern**: nesting a `<Badge>` inside another `<Badge>` to fake an entity-with-status chip — `EntityChip` replaces that composition. `status.color` and the chip's own `color` are `PaletteColor` names, never raw hex strings. Omitting a link target (`href`/`as`) is also an anti-pattern — an EntityChip should link to its entity. Nesting `<IconTile>`/`<Badge>` in `icon`/`trailing` to fake coloured parts is also an anti-pattern — use `before`/`after` segments instead. Wrapping `label` in a styled `<Text weight="semibold">` to get a heavier title is also an anti-pattern — use `labelWeight="semibold"`; it buys nothing anyway, since the clipped-label tooltip always renders the label's plain text regardless of how `label` is styled.
+- ❌ Block-level children (e.g. a `<div>`) inside `label` / `prefix` — the inline-safety contract requires span-only content.
+- ❌ An icon segment without a meaningful `label` — it is the segment's accessible name; a decorative glyph belongs in `icon`, not a segment.
+
+```tsx
+// Loading / unavailable — still live links with a target
+<EntityChip href="/contacts/7" label="Contact" loading />
+<EntityChip href="/contacts/9" label="Deleted contact" unavailable />
+```