contextMenu

Opens a menu on a cell, with the actions of the features you give it and your own items.

Import	import { contextMenu } from '@dzgrid/dom/context-menu';
Signature	contextMenu<T = unknown>(o?: ContextMenuOptions<T>): ContextMenuFeature<T>
Texts	import { EN_CONTEXT_MENU } from '@dzgrid/dom/locales/en-context-menu'; languages: en, fr, ar
Style sheet	import '@dzgrid/theme/menu.css';
Declared in	packages/dom/src/context-menu/index.ts

Options	Type
use	{ /** Copy, Copy with headers; with `edit` Cut and Paste. */ readonly range?: { api(grid: Grid): RangeApiLike | null }; /** Fill down / Fill right, by its `along`. */ readonly fill?: { api(grid: Grid): FillApiLike | null }; /** Undo / Redo; Cut and Paste need it too. */ readonly edit?: { api(grid: Grid): EditApiLike | null }; /** Export to CSV (the displayed rows). */ readonly csv?: { run(scope?: 'displayed'): Promise<unknown> }; /** Export to Excel (the displayed rows): `csvExport({ xlsx })`'s `xlsx` (Phase 9); its label `cmenu.exportXlsx` is then required. */ readonly xlsx?: { run(scope?: 'displayed'): Promise<unknown> } | undefined; /** Expand / Collapse on a parent row. */ readonly tree?: { api(grid: Grid): TreeApiLike | null }; /** Pin / Unpin the row (owner Q-CM3 A). */ readonly pinned?: { api(grid: Grid): PinnedRowsApiLike<T> | null }; /** « Read the totals » on a cell of the block (`statusBar()`, owner Q-SB3; its label from the status bar's texts). */ readonly status?: { api(grid: Grid): StatusApiLike | null } }
items	(c: CellMenuContext<T>, defaults: readonly MenuEntry<CellMenuContext<T>>[]) => readonly MenuEntry<CellMenuContext<T>>[]
classes	{ readonly menu?: string; readonly item?: string }
onPin	(rows: { readonly top: readonly T[]; readonly bottom: readonly T[] }) => void

What it does

contextMenu() opens a menu on a cell: a right-click (Shift+right-click keeps the browser’s own), Ctrl+click on a Mac, Shift+F10 or the Menu key on the focused cell. Inside the block it acts on the block; outside, the cell is focused first. With nothing to offer, or for a finger, a pen, or an open editor, the browser’s own menu shows.

The menu ships none of the features it drives: you give them in use, and only their items appear. range: Copy, Copy with headers, and with edit Cut and Paste. fill: fill down and toward the end. edit: Undo and Redo. tree: Expand or Collapse on a parent row. pinned: Pin to the top or the bottom, Unpin. csv and xlsx: export the displayed rows. status: « Read the totals » on a cell of the block. While a filter or the search is on, « Clear all filters » is offered when its text is in the messages.

api(grid) gives open(at) (for your own button), close() and current(). A throw in items falls back on the default items and is reported.

Options

• use: the features the default items drive — range, fill, edit, csv, xlsx (the export’s xlsx), tree, pinned, status. Absent: their items are absent.
• items(context, defaults): your items — the defaults kept, reordered, removed or added to. The context holds the row, its key, the column, the value, the block and the grid.
• classes: your classes (Tailwind, Bootstrap) on the list (menu) and on every item (item).
• onPin(rows): told after Pin or Unpin changed a band, so your application keeps its pinned rows.

Example

import { createGrid } from '@dzgrid/dom';
import { range } from '@dzgrid/dom/range';
import { contextMenu } from '@dzgrid/dom/context-menu';
import { EN } from '@dzgrid/dom/locales/en';
import { EN_RANGE } from '@dzgrid/dom/locales/en-range';
import { EN_CONTEXT_MENU } from '@dzgrid/dom/locales/en-context-menu';

type Crate = { id: string; fruit: string; kilos: number };

const blocks = range();

createGrid<Crate>(document.getElementById('crates')!, {
  rows: [{ id: 'c1', fruit: 'Quince', kilos: 12 }, { id: 'c2', fruit: 'Medlar', kilos: 7 }],
  columns: [
    { id: 'fruit', header: 'Fruit' },
    { id: 'kilos', header: 'Kilos', type: 'number' },
  ],
  getRowId: (c) => c.id,
  messages: { ...EN, text: { ...EN.text, ...EN_RANGE.text, ...EN_CONTEXT_MENU.text } },
  features: [
    blocks,
    contextMenu<Crate>({
      use: { range: blocks },
      items: (c, defaults) => [
        ...defaults,
        { separator: true },
        { id: 'weigh', label: 'Weigh again', action: () => console.log(c.row.fruit) },
      ],
    }),
  ],
});

Live demo

Right-click a cell, or focus it and press Shift+F10: copy, copy with headers, fill.

See also

• rowDrag: menuItems(c) adds Move up, Move down… to this menu.
• csvExport: the file the export items write.
• range: the block the menu acts on.