@xsolla/xui-context-menu 0.149.1 → 0.150.0-pr250.1778061864

package/README.md

@@ -1,336 +1,175 @@
 # Context Menu
 
-A cross-platform React context menu component that can be triggered by a button or right-click, supporting various item types including checkboxes and radio buttons.
+## Overview
 
-## Installation
+`ContextMenu` is an anchored panel of selectable cells. The component is built around two primitives: a single `ContextMenuItem` whose `type` prop switches between cell variants (`option`, `search`, `heading`, `divider`), and a panel that supports a preset shorthand (`type="list" | "phone" | "checkbox" | "radio" | "status" | "brandLogo" | "avatar" | "loading"`) plus a fully custom composition path via `children`.
 
-```bash
-npm install @xsolla/xui-context-menu
-# or
-yarn add @xsolla/xui-context-menu
-```
+## When to use
 
-## Demo
+- A primary action menu attached to a trigger (e.g. a button's overflow actions).
+- A selection control with checkbox or radio cells (multi-select or single-select).
+- A lightweight picker for status, country, or brand-logo lists.
 
-### Basic Context Menu
+## When not to use
 
-```tsx
-import * as React from 'react';
-import { ContextMenu } from '@xsolla/xui-context-menu';
-import { Button } from '@xsolla/xui-button';
-
-export default function BasicContextMenu() {
-  return (
-    <ContextMenu
-      trigger={<Button>Open Menu</Button>}
-      list={[
-        { id: 'edit', label: 'Edit' },
-        { id: 'duplicate', label: 'Duplicate' },
-        { id: 'delete', label: 'Delete' },
-      ]}
-      onSelect={(item) => console.log('Selected:', item.id)}
-    />
-  );
-}
-```
-
-### Compound Component API
+- For form fields driven by validation — use `Select`, `Autocomplete` or a plain `Input` instead.
+- For navigational menus or app-level navigation — use the appropriate navigation primitives.
+- For a single destructive confirmation — use a `Dialog`.
 
-```tsx
-import * as React from 'react';
-import { ContextMenu } from '@xsolla/xui-context-menu';
-import { Button } from '@xsolla/xui-button';
-
-export default function CompoundAPI() {
-  return (
-    <ContextMenu trigger={<Button>Actions</Button>}>
-      <ContextMenu.Item onPress={() => console.log('Edit')}>Edit</ContextMenu.Item>
-      <ContextMenu.Item onPress={() => console.log('Copy')}>Copy</ContextMenu.Item>
-      <ContextMenu.Separator />
-      <ContextMenu.Item onPress={() => console.log('Delete')}>Delete</ContextMenu.Item>
-    </ContextMenu>
-  );
-}
-```
-
-### With Groups
-
-```tsx
-import * as React from 'react';
-import { ContextMenu } from '@xsolla/xui-context-menu';
-import { Button } from '@xsolla/xui-button';
-
-export default function WithGroups() {
-  return (
-    <ContextMenu
-      trigger={<Button>Menu with Groups</Button>}
-      groups={[
-        {
-          id: 'file',
-          label: 'File',
-          items: [
-            { id: 'new', label: 'New' },
-            { id: 'open', label: 'Open' },
-            { id: 'save', label: 'Save' },
-          ],
-        },
-        {
-          id: 'edit',
-          label: 'Edit',
-          items: [
-            { id: 'cut', label: 'Cut' },
-            { id: 'copy', label: 'Copy' },
-            { id: 'paste', label: 'Paste' },
-          ],
-        },
-      ]}
-    />
-  );
-}
-```
-
-## Anatomy
-
-```jsx
-import { ContextMenu } from '@xsolla/xui-context-menu';
+## Installation
 
-<ContextMenu
-  trigger={<Button>Menu</Button>}  // Trigger element
-  isOpen={isOpen}                   // Controlled open state
-  onOpenChange={setIsOpen}          // Open state callback
-  list={items}                      // Data-driven items
-  groups={groups}                   // Grouped items
-  size="md"                          // Size variant
-  width={200}                       // Menu width
-  maxHeight={300}                   // Max height with scroll
-  closeOnSelect={true}              // Close after selection
-  onSelect={handleSelect}           // Selection callback
-  onCheckedChange={handleChecked}   // Checkbox/radio callback
-/>
+```bash
+yarn add @xsolla/xui-context-menu
 ```
 
-## Examples
+## Two API paths
 
-### Checkbox Items
-
-```tsx
-import * as React from 'react';
-import { ContextMenu } from '@xsolla/xui-context-menu';
-import { Button } from '@xsolla/xui-button';
-
-export default function CheckboxItems() {
-  const [settings, setSettings] = React.useState({
-    notifications: true,
-    sound: false,
-    autoSave: true,
-  });
-
-  return (
-    <ContextMenu
-      trigger={<Button>Settings</Button>}
-      list={[
-        { id: 'notifications', label: 'Notifications', variant: 'checkbox', checked: settings.notifications },
-        { id: 'sound', label: 'Sound', variant: 'checkbox', checked: settings.sound },
-        { id: 'autoSave', label: 'Auto Save', variant: 'checkbox', checked: settings.autoSave },
-      ]}
-      onCheckedChange={(id, checked) => {
-        setSettings((prev) => ({ ...prev, [id]: checked }));
-      }}
-    />
-  );
-}
-```
+### Preset path
 
-### Radio Group
+Pass `type` and `items`. The panel renders the preset's chrome and composes each option with the right control or slot.
 
 ```tsx
-import * as React from 'react';
-import { ContextMenu } from '@xsolla/xui-context-menu';
-import { Button } from '@xsolla/xui-button';
-
-export default function RadioGroupMenu() {
-  const [theme, setTheme] = React.useState('light');
-
-  return (
-    <ContextMenu trigger={<Button>Theme: {theme}</Button>}>
-      <ContextMenu.Group label="Theme">
-        <ContextMenu.RadioGroup value={theme} onValueChange={setTheme}>
-          <ContextMenu.RadioItem value="light">Light</ContextMenu.RadioItem>
-          <ContextMenu.RadioItem value="dark">Dark</ContextMenu.RadioItem>
-          <ContextMenu.RadioItem value="system">System</ContextMenu.RadioItem>
-        </ContextMenu.RadioGroup>
-      </ContextMenu.Group>
-    </ContextMenu>
-  );
-}
-```
+import { ContextMenu } from "@xsolla/xui-context-menu";
 
-### With Search
-
-```tsx
-import * as React from 'react';
-import { ContextMenu } from '@xsolla/xui-context-menu';
-import { Button } from '@xsolla/xui-button';
-
-export default function WithSearch() {
-  const [search, setSearch] = React.useState('');
-
-  const allItems = [
-    { id: 'apple', label: 'Apple' },
-    { id: 'banana', label: 'Banana' },
-    { id: 'cherry', label: 'Cherry' },
-    { id: 'date', label: 'Date' },
-    { id: 'elderberry', label: 'Elderberry' },
-  ];
-
-  const filteredItems = allItems.filter((item) =>
-    item.label.toLowerCase().includes(search.toLowerCase())
-  );
-
-  return (
-    <ContextMenu trigger={<Button>Select Fruit</Button>}>
-      <ContextMenu.Search
-        value={search}
-        onValueChange={setSearch}
-        placeholder="Search fruits..."
-      />
-      {filteredItems.map((item) => (
-        <ContextMenu.Item key={item.id}>{item.label}</ContextMenu.Item>
-      ))}
-    </ContextMenu>
-  );
-}
+<ContextMenu
+  type="list"
+  trigger={<Button>Open</Button>}
+  items={[
+    { type: "option", label: "Edit" },
+    { type: "option", label: "Duplicate" },
+    { type: "option", label: "Delete", destructive: true },
+  ]}
+/>;
 ```
 
-### With Icons and Shortcuts
-
-```tsx
-import * as React from 'react';
-import { ContextMenu } from '@xsolla/xui-context-menu';
-import { Button } from '@xsolla/xui-button';
-import { Copy, Scissors, Clipboard } from '@xsolla/xui-icons-base';
-
-export default function WithIconsAndShortcuts() {
-  return (
-    <ContextMenu
-      trigger={<Button>Edit</Button>}
-      list={[
-        { id: 'cut', label: 'Cut', icon: <Scissors />, trailing: { type: 'shortcut', content: 'Cmd+X' } },
-        { id: 'copy', label: 'Copy', icon: <Copy />, trailing: { type: 'shortcut', content: 'Cmd+C' } },
-        { id: 'paste', label: 'Paste', icon: <Clipboard />, trailing: { type: 'shortcut', content: 'Cmd+V' } },
-      ]}
-    />
-  );
-}
-```
+### Custom path
 
-### Right-Click Context Menu
+Compose cells as children when you need full control of the layout, want to mix headings and dividers freely, or render a slot the preset path doesn't cover.
 
 ```tsx
-import * as React from 'react';
-import { ContextMenu } from '@xsolla/xui-context-menu';
-
-export default function RightClickMenu() {
-  const [position, setPosition] = React.useState<{ x: number; y: number } | null>(null);
-
-  const handleContextMenu = (e: React.MouseEvent) => {
-    e.preventDefault();
-    setPosition({ x: e.clientX, y: e.clientY });
-  };
-
-  return (
-    <div
-      onContextMenu={handleContextMenu}
-      style={{ width: 300, height: 200, background: '#f0f0f0', padding: 16 }}
-    >
-      Right-click anywhere in this area
-
-      {position && (
-        <ContextMenu
-          isOpen={!!position}
-          onOpenChange={(open) => !open && setPosition(null)}
-          position={position}
-          list={[
-            { id: 'inspect', label: 'Inspect' },
-            { id: 'refresh', label: 'Refresh' },
-          ]}
-        />
-      )}
-    </div>
-  );
-}
+import { ContextMenu, ContextMenuItem } from "@xsolla/xui-context-menu";
+
+<ContextMenu trigger={<Button>Open</Button>} aria-label="Actions">
+  <ContextMenuItem type="heading" label="Workspace" />
+  <ContextMenuItem type="option" label="Personal" />
+  <ContextMenuItem type="option" label="Acme Inc." />
+  <ContextMenuItem type="divider" />
+  <ContextMenuItem type="option" label="Sign out" destructive />
+</ContextMenu>;
 ```
 
-## API Reference
-
-### ContextMenu
-
-**ContextMenuProps:**
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| children | `ReactNode` | - | Compound component children. |
-| trigger | `ReactNode` | - | Element that triggers the menu. |
-| list | `ContextMenuItemData[]` | - | Data-driven item list. |
-| groups | `ContextMenuGroupData[]` | - | Grouped items with labels. |
-| isOpen | `boolean` | - | Controlled open state. |
-| onOpenChange | `(open: boolean) => void` | - | Open state change callback. |
-| position | `{ x: number; y: number }` | - | Fixed position for right-click menus. |
-| size | `"sm" \| "md" \| "lg"` | `"md"` | Menu size variant. |
-| width | `number` | - | Menu width in pixels. |
-| maxHeight | `number` | `300` | Max height before scrolling. |
-| closeOnSelect | `boolean` | `true` | Close menu after item selection. |
-| isLoading | `boolean` | `false` | Show loading spinner. |
-| onSelect | `(item: ContextMenuItemData) => void` | - | Item selection callback. |
-| onCheckedChange | `(id: string, checked: boolean) => void` | - | Checkbox/radio change callback. |
-| aria-label | `string` | - | Accessible menu label. |
-
-**ContextMenuItemData:**
-
-```typescript
-interface ContextMenuItemData {
-  id: string;
-  label: string;
-  icon?: ReactNode;
-  description?: string;
-  disabled?: boolean;
-  selected?: boolean;
-  checked?: boolean;
-  variant?: 'default' | 'checkbox' | 'radio';
-  trailing?: { type: 'shortcut' | 'content' | 'none'; content?: string | ReactNode };
-  children?: ContextMenuItemData[];
-  onPress?: () => void;
-}
-```
-
-### Compound Components
-
-| Component | Description |
-| :-------- | :---------- |
-| `ContextMenu.Item` | Standard menu item. |
-| `ContextMenu.CheckboxItem` | Item with checkbox. |
-| `ContextMenu.RadioGroup` | Container for radio items. |
-| `ContextMenu.RadioItem` | Radio button item. |
-| `ContextMenu.Group` | Group with optional label. |
-| `ContextMenu.Separator` | Visual separator line. |
-| `ContextMenu.Search` | Search input for filtering. |
-
-## Keyboard Navigation
+Choose the preset path for typical menus where the data is uniform; choose the custom path when cells differ structurally or when you need to drop in bespoke nodes between cells.
+
+## `ContextMenuItem` reference
+
+`ContextMenuItem` is a discriminated union on `type`. All cell types accept `size`, `data-testid` and theme-override props.
+
+### `type="option"`
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `label` | `ReactNode` | Primary cell text (required). |
+| `description` | `ReactNode` | Secondary line beneath the label. |
+| `leadingControl` | `"checkbox" \| "radio"` | Renders a `Checkbox` or `Radio` at the start. |
+| `leadingIcon` | `ReactNode` | Icon node before the label group. |
+| `status` | `ReactNode` | Status indicator slot (e.g. `<Status>`). |
+| `iconWrapper` | `ReactNode` | Wrapped icon / avatar slot. |
+| `slot` / `slotContent` | `ReactNode` | Generic slot before the label. |
+| `value` | `ReactNode` | Right-side primary text (e.g. shortcut value, dial code). |
+| `hint` | `ReactNode` | Right-side secondary text below `value`. |
+| `trailingIcon` | `ReactNode` | Trailing icon at the end of the cell. |
+| `keyboardShortcut` | `string` | Display-only shortcut rendered as `<kbd>` and exposed via `aria-keyshortcuts`. |
+| `hasSubmenu` | `boolean` | Marks the cell as a submenu trigger and renders a chevron. |
+| `submenu` | `ReactNode` | A nested `<ContextMenu>` opened on hover/`ArrowRight`/`Enter`. |
+| `checked` | `boolean` | Fully controlled checked state. |
+| `disabled` | `boolean` | Disables interaction and applies the disabled style. |
+| `destructive` | `boolean` | Applies the destructive content colour. |
+| `onSelect` | `() => void` | Fires on activation (click, `Enter`, `Space`). |
+| `onCheckedChange` | `(checked: boolean) => void` | Optional change callback for controls. |
+
+Render order (left → right): `leadingControl`, `leadingIcon`, `status`, `iconWrapper`, `slotContent`, `label` (with optional `description` below), `value` (with optional `hint` below), `keyboardShortcut`, submenu chevron, `trailingIcon`.
+
+### `type="search"`
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `value` | `string` | Controlled value (required). |
+| `onValueChange` | `(value: string) => void` | Change callback (required). |
+| `placeholder` | `string` | Defaults to `"Search"`. |
+| `autoFocus` | `boolean` | Focuses the input on mount. |
+| `aria-label` | `string` | Defaults to `"Search options"`. |
+
+### `type="heading"`
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `label` | `ReactNode` | Section title (uppercase styling). |
+| `description` | `ReactNode` | Optional helper line beneath. |
+
+### `type="divider"`
+
+A horizontal rule with `role="separator"`. No content props.
+
+## `ContextMenu` reference
+
+| Prop | Type | Purpose |
+| --- | --- | --- |
+| `type` | `"list" \| "loading" \| "phone" \| "checkbox" \| "status" \| "brandLogo" \| "radio" \| "avatar"` | Panel preset; works with `items`. |
+| `items` | `ReadonlyArray<Option \| Heading \| Divider>` | Data-driven cells for the preset path. |
+| `children` | `ReactNode` | Custom-composition cells (alternative to `items`). |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | Controls cell sizing across the panel. Default `md`. |
+| `searchable` | `boolean` | Auto-renders a sticky search cell and filters options. |
+| `loading` | `boolean` | Renders a centred spinner instead of the cell list. |
+| `emptyMessage` | `string` | Custom message for the default empty state. |
+| `empty` | `ReactNode` | Replace the empty state entirely. |
+| `trigger` | `ReactNode` | Element that toggles the panel; receives `aria-haspopup` / `aria-expanded`. |
+| `placement` | `"bottom-start" \| "top-start" \| "bottom-end" \| "top-end"` | Initial placement. Auto-flips when clipped. |
+| `isOpen` | `boolean` | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | Open-state callback. |
+| `closeOnSelect` | `boolean` | Override the per-preset default. |
+| `width` | `number` | Forces panel width (px). |
+| `maxHeight` | `number` | Caps panel height (px); body scrolls and search stays sticky. |
+| `onSelect` | `(item: ContextMenuOptionItemProps) => void` | Fires for the preset path on option activation. |
+| `aria-label` | `string` | Accessible name for the menu container. |
+| `data-testid` | `string` | Testing handle. |
+
+## Behaviour & accessibility
+
+- The panel root is `role="menu"` (or hosts `role="menuitemcheckbox"` / `role="menuitemradio"` cells when `checked` is provided). Headings render as `role="presentation"`, dividers as `role="separator"`, and the search cell as `role="searchbox"`.
+- `closeOnSelect` defaults to `true` for every preset except `checkbox`, where multi-select keeps the panel open.
+- On open, focus moves to the search input when present, otherwise to the first option.
+- On close, focus returns to the trigger.
+- The trigger element receives `aria-haspopup="menu"` and `aria-expanded` synced to the open state.
+
+## Keyboard reference
 
 | Key | Action |
-| :-- | :----- |
-| `ArrowDown` | Move to next item |
-| `ArrowUp` | Move to previous item |
-| `Home` | Move to first item |
-| `End` | Move to last item |
-| `Enter` / `Space` | Select current item |
-| `Escape` | Close menu |
-| `Tab` | Close menu |
-
-## Accessibility
-
-- Menu has `role="menu"` with proper ARIA attributes
-- Items have `role="menuitem"`, checkboxes have `role="menuitemcheckbox"`
-- Keyboard navigation follows WAI-ARIA menu pattern
-- Focus is trapped within menu when open
-- Escape key closes menu and returns focus to trigger
+| --- | --- |
+| `↑` / `↓` | Move active option up/down (skips heading/divider). |
+| `Enter` / `Space` | Activate the focused option. |
+| `Esc` | Close the menu and return focus to the trigger. |
+| `Tab` | Close the menu and continue natural focus order. |
+| `Home` / `End` | Jump to the first/last option. |
+| `→` / `Enter` | Open a submenu when on a `hasSubmenu` option. |
+| `←` / `Esc` | Close the submenu and return focus to its parent option. |
+
+## Content guidelines
+
+- Use short, imperative labels ("Edit", "Duplicate", "Sign out").
+- Use sentence case for option labels.
+- Use uppercase for headings — the heading cell already applies the visual treatment.
+- Place destructive options at the bottom of the list, ideally separated by a divider.
+- Prefer specific empty messages ("No countries match") over the generic default.
+- Aim for seven options or fewer per panel; group with headings or split into submenus when longer.
+
+## Migration from prior API
+
+| Old | New |
+| --- | --- |
+| `ContextMenuCheckboxItem` | `<ContextMenuItem type="option" leadingControl="checkbox" />` |
+| `ContextMenuRadioItem` | `<ContextMenuItem type="option" leadingControl="radio" />` |
+| `ContextMenuRadioGroup` | `type="radio"` panel preset with shared selected state |
+| `ContextMenuGroup` | `<ContextMenuItem type="heading" />` |
+| `ContextMenuSeparator` | `<ContextMenuItem type="divider" />` |
+| `ContextMenuSearch` | `<ContextMenuItem type="search" />` (or set `searchable: true` on the panel for auto-render) |
+| Size scale `s` / `m` / `l` / `xl` | `sm` / `md` / `lg` / `xl` |