context-menus

# Context menus A context menu lists the actions for the clicked object in a predictable order, so users find the same action in the same place on every object and surface. ## Group order Groups render in lexicographic order of their ID, with `navigation` always first. Use these groups, in this order, for new menus and for all Agents window menus: | Group | Purpose | |---|---| | `navigation` | Open, create, or run the object. The default (double-click or Enter) action comes first. | | `1_state` | Change the object's state. | | `2_organize` | Change where the object is listed or how it is ordered. | | `3_copy` | Copy information about the object to the clipboard. | | `4_manage` | Configure or edit the object itself. Destructive actions come last. | - Order items within a group with `order` (or `group@n` in `package.json`) instead of relying on title sorting. - Prefer these groups over inventing new ones. A new group needs a purpose none of them covers. - Established workbench menus with documented groups (editor, Explorer, terminal, editor title) keep their own group IDs. Add to the closest matching group. - Group IDs of menus open to extensions are API. When you change one, update every contribution, including `extensions/*/package.json`. ## Rules - **Destructive actions last.** An action that deletes or removes data is the final item of the menu. Never place it mid-menu. - **Same object, same menu.** An object shown in several places (list row, tab, header, card) offers the same actions in the same order. Reuse one `MenuId` or the same group IDs rather than building a parallel action list by hand. - **Inline actions are in the menu too.** Every hover or toolbar action of a row or header also appears in its context menu. - **Only actions for the clicked object.** List-wide or unrelated actions belong on the section header, view title, or empty space, not on an item. - **Hide what doesn't apply; disable what can't run now.** Use `when` for actions irrelevant to the object and `precondition` for applicable actions that are temporarily unavailable, such as single-item actions during multi-selection. - **Keep it short.** At most about 5 groups and 15 items, with one level of submenus. Use a submenu for 3 or more related targets, and a toggle rather than a submenu for a two-way choice. - **Labels.** Use Title Case. End with `...` when the action asks for more input or confirmation. Labels must be unique within a menu. - **Dynamic actions join their group.** When actions must be built in code, merge them into the matching group of the menu's actions instead of appending them after a final separator. Join groups with `Separator.join`. Based on the [VS Code context menu UX guidelines](https://code.visualstudio.com/api/ux-guidelines/context-menus), the [Windows menu guidelines](https://learn.microsoft.com/windows/win32/uxguide/cmd-menus), and the [Apple context menu guidelines](https://developer.apple.com/design/human-interface-guidelines/context-menus).