Commands and menus

A command is the one implementation behind a menu item, a toolbar button and a renderer's runCommand — "Sort ascending", "Hide column", "Clear filters". Whether it shows and whether it can run are predicates over a context, a snapshot of the grid taken where it was asked for, and it changes the grid only through the controller's actions, so a change made from a menu reports through the same callback as the user's own gesture would.

import {
  createCommandContext,
  createGridController,
  defaultMessages,
  resolveCommands,
  runCommand,
} from "@gridkitjs/core";

const controller = createGridController<Order>({
  dataSource: orders,
  columns,
  sortableColumns: true,
});
const commands = resolveCommands<Order>(undefined);

const context = createCommandContext({
  controller,
  target: { area: "header", columnId: "Amount" },
  messages: defaultMessages,
  host: { autoFitColumns() {}, openPanel() {}, announce() {} },
});

const sortAscending = commands.get("sort.ascending");
if (sortAscending !== undefined) {
  runCommand(sortAscending, context); // true — the grid now sorts by Amount
}

Commands#

A GridCommand<Row>:

The predicates are asked whenever a menu or toolbar is resolved, so a command follows the grid's state without being told about it.

Targets#

A GridCommandTarget says where a command was asked for. A built-in reads the column, row or group it acts on from here.

The context#

createCommandContext({ controller, target, messages, host }) — a GridCommandContextInput — builds the GridCommandContext<Row> every predicate and execute receive, from the controller's state, view and options as they are now. messages is the grid's messages already laid over the defaults, as resolveMessages returns them. The controller may be of any node type, so a renderer's GridController<Row, ReactNode> serves as it is.

A context is a snapshot. A renderer builds one each time it resolves a menu or a toolbar, so its commands see the state the user sees.

The host#

A GridCommandHost holds what a command needs that only a renderer has. A caller with no renderer — a test, a script in Node — passes members that do nothing.

Built-in commands#

builtInCommands<Row>() returns the grid's own commands. Each acts on a column, a row, a group or the whole grid, and is hidden on a target that has none of what it needs — so any id can be listed in any menu without checks. Their labels come from messages, and their ids form the BuiltInCommandId type.

"Sortable" is the column's sortable, else the grid's sortableColumns; "groupable" the same with groupable and groupableColumns; "resizable" is the column as rendered, after resizableColumns. hideable defaults to true and, like sortable, gates only the user's ways to do it: hideColumns still hides a column that is not hideable.

The sorting, grouping, hiding and autofit built-ins carry an icon key — a BuiltInCommandIcon: sortAscending and sortDescending on the two sorts, group on group.add and group.remove, hide on column.hide, and autoFit on both autofits. @gridkitjs/react draws each as an icon of its own; a command of yours may use the same keys to look like the built-ins, and a renderer of your own maps them to its icons or leaves them out.

The ids filter.open, copy.cell, copy.row, copy.selection, export.csv, export.json, export.xlsx, export.pdf, print and layout.reset are reserved for built-ins still to come.

Panels#

A panel is a small dialog a renderer opens beside where it was asked for — the column chooser now, a column's filter editor later. A command opens one through host.openPanel(kind, target), passing its own target along, so the renderer can anchor it: below a header, beside a toolbar button, or at the grid's corner for { area: "grid" }. The renderer holds which panel is open, one at a time; core holds what each one shows.

The column chooser#

column.choose opens the column chooser: a checkbox for every data column in column order, hidden ones included, a search box narrowing the list, and a "Show all" checkbox over what the search shows. resolveColumnChooser({ columns, visibility, search }) — a ColumnChooserInput — works out what it draws, and what "Show all" does:

import { resolveColumnChooser } from "@gridkitjs/core";

const { dataColumns } = controller.getView();
const { columnVisibility } = controller.getState();
const chooser = resolveColumnChooser({
  columns: dataColumns,
  visibility: columnVisibility,
  search: "date",
});

for (const entry of chooser.entries) {
  drawCheckbox(entry.label, entry.visible, entry.disabled, () =>
    entry.visible
      ? controller.hideColumns([entry.columnId])
      : controller.showColumns([entry.columnId]),
  );
}
const toggle = chooser.toggleAll;
drawShowAll(chooser.selectAll, toggle === null, () => {
  if (toggle?.visible === true) controller.showColumns(toggle.columnIds);
  if (toggle?.visible === false) controller.hideColumns(toggle.columnIds);
});

The rules every chooser keeps:

• An entry is disabled — its checkbox cannot be unchecked — while its column shows and is either not hideable or the last column shown. A hidden column can always be shown, hideable or not.
• "Show all" shows every hidden column the search lists once any is hidden, and hides those it lists once none is. It never touches a column that is not hideable, and never hides the last column shown: when that is all that would be left, the first of them stays.
• Changes go through showColumns and hideColumns, so each reports through onColumnVisibilityChange like any other.

App commands and overrides#

resolveCommands(commands) returns every command a grid knows, keyed by id: the built-ins, then yours. A command of yours with a built-in's id replaces it, so every menu and toolbar listing that id gets your version — translated, gated by a privilege, or doing something else entirely — without being changed itself.

import { resolveCommands, type GridCommand } from "@gridkitjs/core";

const exportSelected: GridCommand<Order> = {
  id: "orders.exportSelected",
  label: "Export selected",
  isEnabled: (context) => context.selectedRows().length > 0,
  execute: (context) => {
    exportOrders(context.selectedRows().map((entry) => entry.row));
  },
};

// Replaces the built-in: only an administrator may hide columns.
const hideColumn: GridCommand<Order> = {
  id: "column.hide",
  label: ({ messages }) => messages.hideColumn,
  isVisible: ({ target, column }) =>
    target.area === "header" && column !== null && user.isAdmin,
  execute: ({ column, actions }) => {
    if (column !== null) {
      actions.hideColumns([column.id]);
    }
  },
};

const commands = resolveCommands([exportSelected, hideColumn]);

A command with the id "separator" is left out with a console.error — a menu reads that string as a separator.

runCommand(command, context) runs a command only when it is visible and enabled on the context's target, and returns whether it ran — so a renderer reports only a command that did something, and a call through the API cannot run one the grid's state no longer allows.

On a grid#

A grid takes its app commands through the commands option, which a renderer passes to resolveCommands — so the grid's menus list them by id, and a built-in's id replaced there is replaced in every menu:

<DataGrid
  columns={columns}
  dataSource={orders}
  commands={[exportSelected, hideColumn]}
  contextMenu={{ cell: ["orders.exportSelected", "separator", "selection.clear"] }}
  onCommand={({ commandId, target, source }) => track(commandId, source)}
/>

onCommand is called after a command runs, with a GridCommandEvent — and after an inline menu item runs, with that item's id. A hidden or disabled one, which does not run, is not reported.

Menus#

A menu is a list of MenuEntry<Row>s, the one vocabulary every grid menu and toolbar is written in:

An inline item has a command's fields under the names a menu reads naturally: label, icon and shortcut; hidden, disabled and checked, each a boolean or a function of the context, with checked present only on a checkable item; and onSelect(context) in place of execute. A submenu has a label, an optional icon and its items.

import { resolveMenu, type MenuEntry } from "@gridkitjs/core";

const headerMenu: readonly MenuEntry<Order>[] = [
  "sort.ascending",
  "sort.descending",
  "sort.clear",
  "separator",
  {
    type: "submenu",
    id: "grouping",
    label: "Grouping",
    items: ["group.add", "group.remove", "group.clearAll"],
  },
  "separator",
  {
    type: "item",
    id: "orders.pin",
    label: "Pin column",
    checked: ({ column }) => column !== null && pinned.has(column.id),
    onSelect: ({ column }) => {
      if (column !== null) {
        togglePin(column.id);
      }
    },
  },
];

const entries = resolveMenu(headerMenu, { commands, context });

resolveMenu(entries, { commands, context }) — a MenuResolveOptions — resolves a menu against the grid as the context sees it, and returns the ResolvedMenuEntry[] a renderer draws:

• A command id becomes its command's item. A hidden command or inline item is left out, and so is an id naming no command, reported once per command map with a console.error.
• Labels become strings and flags booleans; checked stays undefined for an item that is not checkable.
• A submenu is resolved the same way, and left out when nothing in it shows.
• Separators never lead, trail or sit next to another, however the items around them came and went.

An empty result means there is nothing to show, so a renderer shows no grid menu there.

run() runs an item against the context its menu was resolved in — a command through runCommand, so only while it is visible and enabled; an inline item unless it is disabled — and returns whether it ran.

Context menus#

A grid's contextMenu option — boolean | GridContextMenuOptions<Row> — says which context menus it shows, by area. It is off by default, leaving the browser's menu. true shows each area's defaults; an object gives an area's entries in the menu vocabulary above — or a function working them out, below — an area left out keeping its defaults and [] leaving the browser's menu there.

A GridContextMenuTarget is a command target in one of these areas.

<DataGrid
  columns={columns}
  dataSource={orders}
  sortableColumns
  contextMenu={{
    header: ["sort.ascending", "sort.descending", "separator", "column.hide"],
    cell: ["selection.selectAllRows", "selection.clear"],
  }}
/>

defaultContextMenu holds each area's defaults — each item hidden where it has nothing to act on, and the separators collapsing around what is left:

An area takes a GridContextMenuEntries<Row, Area>: its entries, or a function asked each time its menu opens with a GridContextMenuRequest<Row, Area> and returning the entries to show — or null, like [], for no grid menu there.

contextMenu={{
  cell: ({ target, defaults, context }) =>
    target.columnId === "Id"
      ? null
      : [
          { type: "item", id: "orders.open", label: "Open", onSelect: ({ row }) => open(row) },
          "separator",
          ...defaults,
        ],
}}

For a renderer of your own, two functions read the option:

No entries, or none left once resolved, means no grid menu there: the renderer leaves the browser's.

import {
  contextMenuEntries,
  createCommandContext,
  resolveMenu,
} from "@gridkitjs/core";

const context = createCommandContext({
  controller,
  target: { area: "header", columnId },
  messages,
  host,
});
const entries = resolveMenu(
  contextMenuEntries(controller.getOptions().contextMenu, context),
  { commands, context },
);
if (entries.length > 0) {
  event.preventDefault();
  showMenu(entries);
}

onContextMenuOpenChange is called as a grid's context menu opens and closes, with a ContextMenuOpenChangeEvent — { open, target }, where the menu opened or where the one closing had. A menu opened in place of another reports that one closing first. The open state itself is the renderer's: no option holds it.

@gridkitjs/react draws them and opens them for you — see its context menu.

Keyboard#

Grid menus follow the WAI-ARIA menu pattern. A disabled item stays focusable, so a screen reader can find it, and does nothing when activated; a checkable item is a menuitemcheckbox with aria-checked.

Hovering over an item moves focus to it, and hovering over a submenu item opens it after a short delay.

The two decisions those keys need are pure, and live here; the behaviour that holds a menu's focus — @gridkitjs/dom's attachMenu — calls them: