# ContextMenuPlugin

> _Since v0.1.1_

Context Menu Plugin for tbw-grid

Adds a customizable right-click menu to grid cells. Build anything from simple
copy/paste actions to complex nested menus with conditional visibility, icons,
and keyboard shortcuts.

## Installation

```ts
import { ContextMenuPlugin } from '@toolbox-web/grid/plugins/context-menu';
```

## Menu Item Structure

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Unique item identifier |
| `name` | `string` | Display label |
| `icon` | `string` | Icon class or HTML |
| `shortcut` | `string` | Keyboard shortcut hint |
| `action` | `(params) => void` | Click handler |
| `disabled` | `boolean \| (params) => boolean` | Disable condition |
| `visible` | `boolean \| (params) => boolean` | Visibility condition |
| `items` | `MenuItem[]` | Submenu items |
| `separator` | `boolean` | Create a divider line |

## Menu Context (params)

| Property | Type | Description |
|----------|------|-------------|
| `rowIndex` | `number` | Clicked row index |
| `colIndex` | `number` | Clicked column index |
| `field` | `string` | Column field name |
| `value` | `any` | Cell value |
| `row` | `any` | Full row data |
| `column` | `ColumnConfig` | Column configuration |

## CSS Custom Properties

| Property | Default | Description |
|----------|---------|-------------|
| `--tbw-context-menu-bg` | `var(--tbw-color-panel-bg)` | Menu background |
| `--tbw-context-menu-fg` | `var(--tbw-color-fg)` | Menu text color |
| `--tbw-context-menu-hover` | `var(--tbw-color-row-hover)` | Item hover background |

## [Configuration Options](/grid/plugins/context-menu/interfaces/contextmenuconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `items?` | <code><a href="/grid/plugins/context-menu/interfaces/contextmenuitem/">ContextMenuItem</a>[] &#124; (params: <a href="/grid/plugins/context-menu/interfaces/contextmenuparams/">ContextMenuParams</a>) =&gt; <a href="/grid/plugins/context-menu/interfaces/contextmenuitem/">ContextMenuItem</a>[]</code> | Menu items - static array or function returning items |

## Examples

### Basic Context Menu

```ts
import '@toolbox-web/grid';
import { ContextMenuPlugin } from '@toolbox-web/grid/plugins/context-menu';

grid.gridConfig = {
  plugins: [
    new ContextMenuPlugin({
      items: [
        { id: 'copy', name: 'Copy', shortcut: 'Ctrl+C', action: (ctx) => navigator.clipboard.writeText(ctx.value) },
        { separator: true, id: 'sep1', name: '' },
        { id: 'delete', name: 'Delete', action: (ctx) => removeRow(ctx.rowIndex) },
      ],
    }),
  ],
};
```

### Conditional Menu Items

```ts
new ContextMenuPlugin({
  items: [
    { id: 'edit', name: 'Edit', visible: (ctx) => ctx.column.editable === true },
    { id: 'delete', name: 'Delete', disabled: (ctx) => ctx.row.locked === true },
  ],
})
```

## See Also

- [`ContextMenuConfig`](/grid/plugins/context-menu/interfaces/contextmenuconfig.md) for configuration options
- [`ContextMenuItem`](/grid/plugins/context-menu/interfaces/contextmenuitem.md) for menu item structure
- [`ContextMenuParams`](/grid/plugins/context-menu/interfaces/contextmenuparams.md) for action callback parameters

> **Extends** [BaseGridPlugin](/docs/grid-api-plugin-development-classes-basegridplugin--docs)
>
> Inherited methods like `attach()`, `detach()`, `afterRender()`, etc. are documented in the base class.

## Methods

### showMenu()

Programmatically show the context menu at the specified position.

Use this to open the menu from custom UI elements or keyboard shortcuts
without requiring a native `contextmenu` event.

```ts
showMenu(x: number, y: number, params: Partial<ContextMenuParams>): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `x` | <code>number</code> | Viewport X coordinate (pixels) |
| `y` | <code>number</code> | Viewport Y coordinate (pixels) |
| `params` | <code>Partial&lt;<a href="/grid/plugins/context-menu/interfaces/contextmenuparams/">ContextMenuParams</a>&gt;</code> | Partial context menu parameters — unspecified fields receive sensible defaults |

#### Example

```ts
const menu = grid.getPluginByName('context-menu');
// Open menu at a button's position with row context
const rect = button.getBoundingClientRect();
menu.showMenu(rect.left, rect.bottom, {
  row: selectedRow,
  rowIndex: 3,
  column: columns[0],
});
```

***

### hideMenu()

Hide the context menu if it is currently open.

Safe to call even when the menu is already closed.

```ts
hideMenu(): void
```

***

### isMenuOpen()

Check if the context menu is currently open.

```ts
isMenuOpen(): boolean
```

#### Returns

`boolean` - `true` when the menu is visible

***