# [draft] menu items spec

## Status

- NC and JNI drafted, 2022-06-28

This document is intended to collect questions around menu item design.

Parts of this might inform a NAP.

## Example manifest

name: my-plugin
display_name: My Plugin
on_activate: my_plugin:activate
on_deactivate: my_plugin:deactivate
contributions:
  commands:
    - id: my-plugin.hello_world
      title: Hello World
    - id: my-plugin.another_command
      title: Another Command
  menus:
    /napari/layer_context:
      - submenu: my-plugin.mysubmenu
      - command: my-plugin.hello_world
  submenus:
    - id: my-plugin.mysubmenu
      label: My SubMenu
      contents:
        - command: my-plugin.another_command
        - command: my-plugin.another_command

## Definitions

- submenu id - the unique id for a plugin submenu.
- label - text displayed for a submenu
- command - a plugin command contribution. This is the functionality to invoke when a user clicks on a menu item.

## Allowable top level menu locations

## Open questions

### 1. Foreign submenu references. Can a plugin attach submenus to other plugin's submenus.

Probably have agreement here:
* Yes, items appended
* missing foreign references are ignored

### 2. Menu path collisions. How to handle when two submenu/menu trees from different plugins are the same.

e.g. Different id's, same label.
- Plugin A: "/napari/layer_context/Image/Shape"
- Plugin B: "/napari/layer_context/Image/Shape"
What to do about "Shape?"

Options:
1. Put plugin name in parentheses to disambiguate.
2. NO OTHER OPTIONS. DONE

### 3. Top-level menu-items

Options:
- Robert-like
- Permissive top-level whitelist. Effectively allow plugins to add most anywhere, but there is a whitelist that might change over time.
- blacklist, but otherwise anything goes
- Allow menus to add anywhere

## Relevant prs/links

- [npe2#160](https://github.com/napari/npe2/pull/160)
- [npe2#161](https://github.com/napari/npe2/pull/161)
- [how menus get extended in #4742](https://github.com/napari/napari/pull/4742/files#diff-568b9a696950cc6898d5a4ca3dc48db51f9009243ab8d8cc4038cfe2721ac28cR181-R194)
- [menu groups are named and sorted lexicographically](https://github.com/napari/napari/pull/4742/files#diff-fb91040c669f699c2f25c43a9e7724334fc96fc52de32637b695c0e0f72b7b43R10-R15)
- [VSCode extension menu items](https://code.visualstudio.com/api/references/contribution-points#contributes.menus)