Unify the format of Command.shortcut or add a new Command.shortcutKeys property

hanguokai commented 1 year ago

Use Case

Developers can use browser.commands.getAll() to display a shortcuts table for users. Command.shortcut is a string, for example "Ctrl+Shift+U". I want to parse this string and style it in HTML, for example: shortcut.split('+') get each key string, then transform them to <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>U</kbd> in HTML and use css to style kbd element.

The Problem

There is no document to define the format of Command.shortcut (don't confused with "suggested_key" in manifest), and it is different format cross platforms in Chrome, I don't test it in Firefox.

For example, the shortcut Ctrl+F. On Chrome OS , the value is "Ctrl+F" (PS: I don't have computers to test it on Windows and Linux). But on macOS, it is "^F" (no plus sign and use ^ for Ctrl). The format is different!

Solution

There are two solutions for this problem.

Solution 1: Unify the format of Command.shortcut

I understand, on macOS, it is usually use ⌃ for Ctrl, ⌥ for Opt and ⇧ for Shift. I don't want to unify the key string. I want to unify the format of key combination. For example, on all platforms, use the format of key1+key2 or key1+key2+key3, and no space between key and +. Note: the key + can't be use in shortcut, so it is safe as the separator between keys.

Solution 2: Add a new Command.shortcutKeys property

class Command {
  name, // existing property
  description, // existing property
  shortcut, // existing property, like "Ctrl+F" on ChromeOS or "^F" on macOS
  shortcutKeys // new property, it is an array of keys, like ['Ctrl', 'F'] or ['^', 'F']
}

Thus, developers can use this property to format shortcut in page, like below:

browser.commands.getAll(commands => {
  for (let cmd of commands) {
    let keys = cmd.shortcutKeys;
    // format [key1, key2, key3] to html <kbd>key1</kbd> + <kbd>key2</kbd> + <kbd>key3</kbd>
  }
});

Rob--W commented 1 year ago

P.S. This was originally filed at #300 but split off.

Relevant thread:

Fragment by @Rob--W at https://github.com/w3c/webextensions/issues/300#issuecomment-1294657897 :

The format is clearly documented, not just for Chrome, but also for Firefox (including Ctrl and MacCtrl): https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands . If ChromeOS does something special, then that's a bug in Chrome. Not a WECG issue.

Reply by @hanguokai at https://github.com/w3c/webextensions/issues/300#issuecomment-1294966405 :

For proposal 3, you're missing my point. I don't mean the format of "suggested_key" in manifest. I mean the value of Command.shortcut https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/commands/Command . There is no document for it's format, and it is different format cross platforms in Chrome, I didn't test it in Firefox.

Reply by @Rob--W at https://github.com/w3c/webextensions/issues/300#issuecomment-1295044388 :

In Firefox the shortcut format is identical to suggested_key, minus whitespace if any to have a canonical format. It looks like Chrome behaves differently. Since Chrome does not offer a programmatic way to change the shortcut (whereas Firefox has commands.update), the shortcut could only be used for informational purposes and the impact is limited. In any case, the desired behavior here seems obvious, so I suggest to report a bug to Chromium, not here. A WECG issue could be considered if the Chromium people disagree with updating the format of shortcut, since then some discussion may be needed to converge to a common solution (e.g. the introduction of a new property name shortcut_key).

For next reports, please test in Firefox (and/or Safari), not just Chrome. That would make it easier to determine whether a bug is an implementation-specific bug or possibly a broader cross-browser issue.

hanguokai commented 1 year ago

the shortcut could only be used for informational purposes and the impact is limited.

I think the problem is there is no definition of the format for this property. If it is only used for informational purposes, then I suggest add a new property like Solution 2.

birtles commented 1 year ago

For what it's worth, I've seen the following returned from this API:

⌥⇧R on Chrome for Mac
Alternatif+T on Edge
Strg + R on Opera

carlosjeurissen commented 1 year ago

My proposal would be to split the concerns here being: 1) Having 'beautiful' printed version of the shortcut key combo for display. This can be different across browsers and operating systems. (MacOS for example prefers to skip the +)

2) Have a canonical list of keys which can be used for storage and programmatic use cases.

For the first we can keep using the shortcut property, while for the second one can go for the proposed shortcutKeys which can use the key names as defined by other web standards like the key names as given by KeyboardEvent.key.

For updating the commands it would thus make more sense to be using the shortcutKeys array.

w3c / webextensions