@xsolla/xui-context-menu 0.154.1-pr250.1778744843 → 0.154.2

package/README.md

@@ -1,175 +1,334 @@
 # Context Menu
 
-## Overview
+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.
 
-`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`.
+## Installation
 
-## When to use
+```bash
+npm install @xsolla/xui-context-menu
+```
 
-- 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.
+## Demo
 
-## When not to use
+### Basic Context Menu
 
-- 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 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)}
+    />
+  );
+}
+```
 
-## Installation
+### Compound Component API
 
-```bash
-yarn add @xsolla/xui-context-menu
+```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>
+  );
+}
 ```
 
-## Two API paths
+### With Groups
 
-### Preset path
+```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' },
+          ],
+        },
+      ]}
+    />
+  );
+}
+```
 
-Pass `type` and `items`. The panel renders the preset's chrome and composes each option with the right control or slot.
+## Anatomy
 
-```tsx
-import { ContextMenu } from "@xsolla/xui-context-menu";
+```jsx
+import { ContextMenu } from '@xsolla/xui-context-menu';
 
 <ContextMenu
-  type="list"
-  trigger={<Button>Open</Button>}
-  items={[
-    { type: "option", label: "Edit" },
-    { type: "option", label: "Duplicate" },
-    { type: "option", label: "Delete", destructive: true },
-  ]}
-/>;
+  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
+/>
 ```
 
-### Custom path
+## Examples
+
+### Checkbox Items
 
-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';
+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 }));
+      }}
+    />
+  );
+}
+```
+
+### Radio Group
 
 ```tsx
-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>;
+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>
+  );
+}
 ```
 
-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
+### 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>
+  );
+}
+```
+
+### 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' } },
+      ]}
+    />
+  );
+}
+```
+
+### Right-Click Context Menu
+
+```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>
+  );
+}
+```
+
+## 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
 
 | Key | Action |
-| --- | --- |
-| `↑` / `↓` | 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` |
+| :-- | :----- |
+| `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