`/sap.ui5/commands/shortcuts` description insufficient

[boghyon]

In the topic _Descriptor for Applications, Components, and Libraries_ section sap.ui5/commands, it says

Specifies provided commands with a unique key/alias. Contains:

• shortcut: String that describes a key combination. When the user presses the key combination, the command is triggered.

Unfortunately it is not enough to understand how it can be achieved exactly.

• [ ] Is the shortcut value space-sensitive or case-sensitive? (Yes and no, according to the current source code)
• [ ] Are single key commands allowed? (Yes, according to the source code)
• [ ] Are commands freely definable or is there a limited set of allowed commands?
  • List of already defined shortcuts categorized by UI5 controls: https://help.sap.com/docs/SAPUI5/bc5a64aac808463baa95b4230f221716/144d377d68784689a9b21565dfa14065.html
  • List of already defined shortcuts by SAP Fiori elements: https://github.com/SAP-docs/sapui5/blob/main/docs/06_SAP_Fiori_Elements/keyboard-shortcuts-0cd318c.md which states the following restrictions:

  • Don't use a keyboard shortcut for a custom button that is already defined as a standard shortcut by SAP Fiori elements. This results in unexpected behavior.

  • Keyboard shortcuts aren't supported for application-defined inline actions and inline navigation buttons in tables.

  • Current valid and list of disallowed shortcuts visible in the source code: sap/ui/core/util/ShortcutHelper.js
• [ ] Other limitations?
  • [x] Document: adding <core:CommandExecution command="MyCommand"/> requires "MyCommand": { "shortcut": "..." } to exist in manifest.json. Otherwise, this will lead to the following error which prevents the app from being cleaned up:

    TypeError: Cannot read properties of null (reading 'shortcut')

    ... and causes the "duplicate id" error when attempting to open the app again.
    Fix 1: https://github.com/SAP/openui5-docs/pull/90
    Fix 2: https://github.com/SAP/openui5/commit/a500d77e530fc41f58cf8d1c4aded4c88349516b "CommandExecution: Log error when command not found + make destroy fail-safe"

  • [ ] Document: focus-independent or focus-less command execution is not allowed either (Cf. https://github.com/SAP/openui5/issues/2788).
  • [ ] ...
• [ ] Brief documentation regarding the popup opened by the sap.ui.core.ShortcutHintsMixin and how the popup's behavior differs from the native tooltip. → There are cases where the native tooltip and the shortcut popup are both shown at the same time. According to some users, it's confusing since the popup and the native tooltip don't differ much in visual design (depending on the OS).

A link pointing to a dedicated topic would be nice so that readers can learn more if they intend to implement commands.

[flovogt]

Hello @boghyon , Thank you for sharing this finding. I've created an internal incident 2280031691. The status of the issue will be updated here in GitHub.

[flovogt]

This topic will be covered in the backlog item CPOUI5FRAMEWORK-344.