New API: Open Shortcut Setting

[hanguokai]

The Problem

Take Chrome as an example, the shortcut page is chrome://extensions/shortcuts, which centralizes all extensions' shortcuts settings. We need to let users locate to current extension (not other extensions) in this page. Assuming that the user has dozens of extensions installed, if we cannot directly locate to current extension, then the user will spend the effort to find this extension first. Assuming that if the extension supports 30 shortcuts, it is also necessary to directly locate to a specified shortcut (not other shortcuts) in this extension.

The Proposal

/**
 * Open the browser extension shortcut page and locate to (scroll to):
 * 1. if no name parameter, locate to the beginning of this extension.
 * 2. if specify the name, locate to the specified shortcut of this extension.
 * The name parameter is `Command.name` of a shortcut.
 */
browser.commands.openShortcut( name ?: string );

[Rob--W]

Originally reported at #300, but split off it.

I posted the following reply at #300 (comment) :

There is already precedent for opening the extension settings page via runtime.openOptionsPage. Something similar for shortcuts (provided that the browser supports it) is reasonable. FYI Firefox supports the commands.update API to update a shortcut, but it cannot do the kind of conflict resolution that is available at the shortcuts UI page: https://bugzilla.mozilla.org/show_bug.cgi?id=1654403

[hanguokai]

In addition, for open shortcuts, not just to open a page, but to navigate to a specific shortcut in that page. The use case is user click the edit button from an extension page, then go to there for this shortcut.

[Rob--W]

There was also a feature request for a method to open the shortcuts management page from an extension, at https://bugzilla.mozilla.org/show_bug.cgi?id=1538451 . Someone has provided a patch there, so I'd like to discuss the shape of the API at the next meeting.

[oliverdunk]

We had a very similar issue back in 2021 that we may want to close given this updated proposal: #126

[zombie]

Bikeshed: openShortcutsConfig

[oliverdunk]

Chrome is supportive of this capability. We would like to have some further discussions about the namespace (runtime vs commands) before making a decision, since we're not sure what our preference is yet.

[mdmower]

I'm in favor of runtime as I don't see the need to disallow this feature if an extension doesn't provide commands of its own.

[Rob--W]

I'm in favor of the commands namespace over runtime, because that namespace is very related to the requested functionality here. The commands namespace can be unlocked without additional cost (such as permission warnings) - extensions can simply declare "commands": {} key in the manifest, without the need to declare additional commands/shortcuts.

Extension developers who are looking for ways to improve their support for shortcut management are far more likely going to look inside the commands namespace than the runtime namespace.

The question of which namespace to use originated from an earlier meeting (2024-08-15 meeting notes), where it was mentioned that Chrome allows users to assign a shortcut to the extension button, independently of whether an extension has declared a command. This is a browser feature, not an API feature. If extensions want first-class support for the ability to trigger an extension button in a cross-browser way, they would have to declare it in the manifest.json file:

{ ...
  "commands": {
    "_execute_action": {
      "description": "Activate the extension"
    }
  }
}

The description above is directly taken from Chrome's current UI. As you can see, it is a very generic description, and extensions who'd like to offer first-class support for shortcuts would serve the user much better by providing a more specific description. Putting the new method under commands could encourage extension authors to take a closer look at the commands manifest key, which I'd consider to be a small positive side effect of choosing that namespace as the home for this new method.

And from the capabilities point of view: if a browser does not support extension-specific shortcuts, then it is easier to document and implement the unavailability of the functionality by omitting the commands namespace altogether in that case. If we were to put it in the runtime namespace, then we would either have to make the API availability conditional, or raise an error when invoked.

[oliverdunk]

Thanks for writing that up @Rob--W. Happy from the Chrome side to move forward with the commands namespace based on those arguments.

The name proposed in this issue is openShortcut, which doesn't seem quite right. We discussed openShortcutSettings or openShortcutOptions on the Chrome side - would one of those be reasonable?

I expect we would also be fine with openShortcutsPage which I see used in the Firefox patch but that doesn't work as well with Safari's UI.

[Rob--W]

All of these names look acceptable to me. Between commands.openShortcutSettings and openShortcutOptions, I'd go with openShortcutSettings since "settings" sounds closer to what people may be looking for if they want to configure shortcuts, as also seen in the title of this issue.

Another name could be openShortcutsConfiguration, but that is much longer. openShortcutsConfig would be shorter.

I'll propose to proceed with commands.openShortcutSettings on the Firefox side. If there are compelling arguments for a new name, it would be trivial to rename it before shipping.