Submenu should use `shortTitle` or be configurable to do so

[verhovsky]

My extension takes a string from the clipboard, transforms that string to the programming language of the current editor and then "pastes" the modified result into the current editor. When the editor's language isn't set (i.e. editorLangId == plaintext), I want to show a dropdown and let the user manually select the language.

The first issue I ran into is that I'm forced to add the command I want to refer to in the drop down as a menu item to cmd+P, otherwise I got this error:

Menu item references a command `curlconverter.toBrowser` which is not defined in the 'commands' section

This is annoying because I don't want to pollute the user's cmd+P menu with an item for each language my extension supports, but whatever. Maybe I'll open a separate issue for that, I bet someone has already asked about that.

Anyway, my issue in the title is that I put this in my package.json to get a dropdown of the languages

    "commands": [
      {
        "command": "curlconverter.toBrowser",
        "title": "Paste cURL As JavaScript",
        "category": "curlconverter"
      },
      {
        "command": "curlconverter.toPython",
        "title": "Paste cURL As Python",
        "category": "curlconverter"
      },
    ],
    "menus": {
      "editor/context": [
        {
          "submenu": "curlconverter.pasteAs",
          "group": "9_cutcopypaste@5",
          "when": "editorLangId == plaintext"
        }
      ],
      "curlconverter.pasteAs": [
        {
          "command": "curlconverter.toBrowser",
          // neither of these have an effect
          "label": "JavaScript",
          "title": "JavaScript"
        },
        {
          "command": "curlconverter.toPython",
          "label": "Python",
          "title": "Python"
        },
      ]
    },
    "submenus": [
      {
        "id": "curlconverter.pasteAs",
        "label": "Paste cURL As"
      }
    ]

but the "label": "Python" has no effect and I just see the commands' title property in my dropdown:

What I expected to happen is for the label of the items in menus would have precedence over the commands' title property, like this:

I can't rename the command because when the user does cmd+P I would rather they see "curlconverter: Paste cURL As Python" instead of "curlconverter: Python", which they wouldn't know what that means. As I mentioned earlier, ideally I would actually like them to not see any languages, and just see one "curlconverter: Paste cURL As Code" which would use the current editor's language, which is what I have now, but if adding all the language-specific commands to cmd+P is necessary then whatever.

I ended up working around this by defining each command twice as toPython and toPythonShort and hiding both from the cmd+P menu like this

    "commands": [
      {
        "command": "curlconverter.toBrowser",
        "title": "Paste cURL As JavaScript",
        "category": "curlconverter"
      },
      {
        "command": "curlconverter.toPython",
        "title": "Paste cURL As Python",
        "category": "curlconverter"
      },
      {
        "command": "curlconverter.toBrowserShort",
        "title": "JavaScript",
        "category": "curlconverter"
      },
      {
        "command": "curlconverter.toPythonShort",
        "title": "Python",
        "category": "curlconverter"
      },
    ],
    "menus": {
      "editor/context": [
        {
          "submenu": "curlconverter.toPython",
          "group": "9_cutcopypaste@5",
          "when": "editorLangId == python"
        },
        {
          "submenu": "curlconverter.pasteAs",
          "group": "9_cutcopypaste@5",
          "when": "editorLangId == plaintext"
        }
      ],
      "curlconverter.pasteAs": [
        {
          "command": "curlconverter.toBrowserShort",
        },
        {
          "command": "curlconverter.toPythonShort",
        },
      ],
      "commandPalette": [
        {
          "command": "curlconverter.toBrowser",
          "when": "false"
        },
        {
          "command": "curlconverter.toBrowserShort",
          "when": "false"
        },
        {
          "command": "curlconverter.toPython",
          "when": "false"
        },
        {
          "command": "curlconverter.toPythonShort",
          "when": "false"
        },
      ]
    },
    "submenus": [
      {
        "id": "curlconverter.pasteAs",
        "label": "Paste cURL As"
      }
    ]

https://github.com/curlconverter/curlconverter-vscode/pull/4

[jrieken]

This is annoying because I don't want to pollute the user's cmd+P menu with an item for each language my extension supports, but whatever. Maybe I'll open a separate issue for that, I bet someone has already asked about that.

Yeah, that's unfortunate and I agree on it be PITA. There is some history to it has the command-contribution existed before the menus-contribution. The former now defines all UX properties of a command (label, category, icon, etc) and the latter are "placements". When contributing a command there should be a short-hand syntax like f1: false

As said, the command-contribution is the sole place that defines all UX properties of a command and we are not going to change that, e.g there will be no support for menu specific icons or titles etc. However we have understood the problem and that's why there is the shortTitle-property for commands. It's exists for this exact use-case, have a shorter title where from the context the rest is obvious. Think of it like the opposite of the category-property. It's then up to the UI to decide which of those UX properties to use, like icon+short-title, category+title etc pp.

Tho, no happy end yet. There is no rule that makes submenus pick the short title by default. We need to either add that or let extension spell this out when defining a submenu.

[VSCodeTriageBot]

This feature request is now a candidate for our backlog. The community has 60 days to upvote the issue. If it receives 20 upvotes we will move it to our backlog. If not, we will close it. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[geekley]

@jrieken Where exactly is shortTitle used? I can't find any documentation on that at all. It just says:

(Optional) Short title by which the command is represented in the UI. Menus pick either title or shortTitle depending on the context in which they show commands.

But I can't find any docs showing specific examples of when shortTitle is used, or a list of which menus use it. Doing a Ctrl+F in the docs for contribution-points, it doesn't even have any mention of shortTitle or short title. I can't use a feature if I can't understand it at all.

E.g. I expected menus.editor/title to use the short version, but it doesn't seem to be the case. I'd like it be long on command palette and short in my placement where I know its context is clear.

the command-contribution is the sole place that defines all UX properties of a command and we are not going to change that

That's unfortunate. Ideally, there should be at least a contributes.menus.*.useShortTitle: boolean property, as knowing whether context is clear enough depends on the extension author. In any case, please add at least info on every menu docs page saying whether it uses the short or long title (by default).