Skip to main content

Context menus

One menu, assembled per right-click from whoever has something to say about the thing under the cursor.

The problem it replaces​

There were four hand-rolled menus — the file tree, the activity rail, the workspace tabs, the game panel — and each one owned all three of the hard parts itself:

  • Its own dismissal. Three separate window keydown listeners, each closing on Escape (and one on any key), racing the shell's Escape ladder.
  • Its own positioning. The activity rail rendered at the raw clientX/ clientY with no clamp at all, so a right-click near the bottom-right corner put the menu off-screen entirely. The file tree clamped against hardcoded guesses at its own size (window.innerWidth - 200, window.innerHeight - 260) — correct only while that menu had exactly the items it had the day the numbers were written.
  • Its own item list, baked into the component that owned the pixels. That makes "the menu depends on what was clicked" something every component reimplements, and it makes a cross-module action impossible: the file tree cannot know that the notebook module would like an Open as Notebook entry on a .ipynb.

The model​

A right-click reports a target — a kind plus that kind's payload — and the menu is built from every provider registered for that kind.

onContextMenu={(e) => {
if (openContextMenu(e, { kind: 'files.node', path: row.path, nodeKind: row.kind })) {
e.preventDefault();
}
}}

openContextMenu returns false when no provider offered an item, and the caller should then let the event through to the browser's own menu rather than swallowing the gesture to show an empty box.

Providers are declared on the module manifest, next to commands and panels:

contextMenu: [{ kind: 'files.node', order: 0, items: filesNodeItems }],

or registered imperatively with addContextMenuProvider for shell chrome, which has no manifest.

Groups, not a flat list​

itemsForTarget returns one group per provider, ordered by order then registration. Each group is drawn with a separator above it. Grouping is preserved rather than flattened because the separator is the only cue that two items came from different places — flattened, another module's Delete sits flush against the owner's Open as though they belonged together.

A provider that returns [] is dropped entirely, so declining a target costs nothing and never leaves a stray divider. A provider that throws is logged and skipped: one module's bad provider must not take down the whole menu.

hint beside, detail below​

An item can carry two kinds of secondary text and they are not interchangeable. A hint shares the row with the label, right-aligned: a keybinding, a parent directory, a one-word state. A detail is a sentence and is drawn on its own line underneath.

The row can only lay out one of those well. The label column is minmax(0, 1fr), so it is what gives way when the row is crowded — passing prose as a hint took the whole 340px and ellipsized the label to nothing. That is literally what happened to the theme picker: every entry showed a full sentence about a theme and none of them showed its name, in a menu whose only job is to let you pick one by name. Both the theme and backdrop pickers now pass their description as detail; a hint is additionally capped at half the row.

Absent, not disabled​

A virtual root in the file tree (a mounted Drive) is read-only and has no local directory behind it, so every write action is omitted rather than greyed out. There is no state in which they become available, and a permanently disabled row only invites the user to keep trying it.

Placement​

placeLayer (packages/core/src/overlay/placement.ts) is pure and unit-tested. The component measures itself first and then positions, so the arithmetic runs against the menu's real size rather than a guess:

  1. Choose a side: the preferred one if it fits, else the opposite if that fits, else whichever has more room. Keeping the preference when neither fits pushes items off the edge where they cannot be clicked at all.
  2. Clamp on both axes to the padded viewport.
  3. With shrink, cap the height so the tail scrolls instead of being drawn past the edge.

A menu taller than the window is capped to the space on the side it was placed on, not expanded to the full viewport — growing it past its own anchor would move it away from the thing it acts on, and the anchor is the only cue about what the menu applies to.

Escape and the keyboard​

The menu registers on the shared transient stack (registerTransient), so Escape closes it through the shell's one ordered ladder instead of a fifth window keydown listener racing the other four. See Keybindings.

Arrows, Home/End, and Enter are handled on the focused menu element — not on window — with ArrowRight/ArrowLeft opening and closing submenus. Hover and keyboard focus set the same activeIndex, so a menu driven by both never shows two highlighted rows.

Scrolling the surface under an open menu closes it: a menu left anchored to a row that has moved is pointing at the wrong thing.

Built-in target kinds​

kindpayloadcontributors
files.nodepath, nodeKind, namefiles, notebook
files.background(none)files
desktop(none)desktop
taskbar(none)desktop
taskbar.windowinstanceId (a status-bar pane button)desktop
taskbar.theme(none)desktop
editor.selectionuri, text, emptyllamacpp
library.chunktext, title, sourceId, chunkIndexllamacpp
training.projectprojectId, name, ownertraining

files.background is the empty space below the last row of the tree, which the tree used to swallow. It is a separate kind rather than files.node with a null path, because the two genuinely differ: there is no row, so every row-scoped verb (open, rename, delete, copy path) is absent, and the create verbs fall back to the first writable root instead of the clicked directory. Reusing the node kind would have produced a menu whose every second item was permanently grey — exactly what absent, not disabled exists to prevent. The tree's row handler runs first and this one checks defaultPrevented, so a row click never opens both.

training.project is a row in the training projects list, and is the clearest case of the menu paying for itself. That row used to carry five inline buttons — open, recipe, two pushes and delete — on one flex line in a narrow list; the row is the open action now and the rest live here, with Kaggle/Colab folded into a Push a copy to ▸ submenu. A project another module owns keeps every item but disabled with a detail saying why, rather than absent: the explanation is the point, and hiding them would make an inert project look identical to a healthy one. Delete stays enabled, because reclaiming the disk is exactly what still applies. The row also exposes a ⋯ button that opens this same menu — a menu nobody knows is there is the actions being gone.

editor.selection and library.chunk are the two text kinds, and both exist because a surface owned by one module holds text another can do something with: the llama.cpp module puts Trace this on both, and neither the editor nor the library has any idea it did. The editor reads the selection from the live CodeMirror view rather than the buffer's persisted bytes — what is on screen is what was right-clicked, and acting on anything else is worse than declining. An empty selection is a real target rather than an absent one, following the same convention "run selection" tools use: no selection means the whole file.

files.node is the one to copy: the notebook module contributes Open as Notebook for a .ipynb without the files module knowing anything about it, and deliberately in addition to Open rather than instead of it — a notebook is still a JSON file, and opening the raw text is how you fix one the editor cannot load.

Adding a surface​

  1. Call openContextMenu(event, target) from onContextMenu, and preventDefault() and stopPropagation() only when it returns true.

    A nested surface must stop propagation

    preventDefault() suppresses the browser's menu; it does nothing about the event continuing up the tree. Where a surface sits inside another one that also has a menu — a taskbar window button inside the taskbar, a file row inside the tree — the ancestor's handler runs next and calls openContextMenu again, and because the store keeps a single open menu the ancestor's simply replaces the one just opened.

    The failure is quiet and looks like a missing feature rather than a bug: for a while a right-click on a taskbar window button showed the taskbar's own menu (Position / Auto-hide / Reset), so Close appeared not to exist even though windowButtonMenu had always offered it.

  2. Retarget any selection first if the click landed outside it — acting on a row the user cannot see highlighted is how Delete hits the wrong thing.

  3. Declare a provider in the owning module's manifest with order: 0.

  4. Put the actions somewhere a provider can reach. They must not live in a component closure; the file tree's deleteSelection moved to modules/files/actions.ts for exactly this reason, which also collapsed a second, drifting copy that the command palette had been using.