feat(ui): shortcut field on ui.commands.register (SD-2936)

[caio-pizzol]

Adds a shortcut field to ui.commands.register({...}) so consumers wiring custom actions ("Insert clause", "AI Rewrite", "Toggle Comment Sidebar") stop hand-rolling per-command keydown listeners and conflict-handling.

ui.commands.register({
  id: 'company.insertClause',
  execute: ({ payload, editor }) => { /* ... */ },
  shortcut: 'Mod-Shift-C',
});

ui.commands.register({
  id: 'company.action',
  execute: () => true,
  shortcut: ['Mod-1', 'Mod-Shift-1'], // multiple bindings on one command
});

Shortcut strings follow the ProseMirror / Tiptap convention so consumers don't have to relearn a new format: Mod-K, Mod-Shift-C, Alt-Enter, Mod-Alt-1. Mod is the platform-correct meta key (Cmd on macOS, Ctrl elsewhere) — both Cmd-K on Mac and Ctrl-K on Windows match the same 'Mod-K' registration. Modifier order in the input is normalized to canonical Mod, Alt, Shift, KEY.

The controller installs a single keydown listener (capture phase, on globalThis.document) and filters to events whose target lies inside this controller's painted host (presentationEditor.visibleHost) — same scoping as entityAt. So Cmd-B typed in a sidebar input doesn't toggle Bold on the document. Matched shortcuts dispatch through the same path ui.commands.get(id).execute() uses, and the listener torn down via the controller's existing teardown chain.

Custom-vs-custom collisions warn and the later registration wins (matches the register({ id }) replacement posture). Built-in editor keymaps (Bold's Cmd-B, etc.) are owned by the editor's own keymap plugin and are out of scope for collision detection — registering 'Mod-B' fires alongside Bold rather than instead of it. That's documented on the field's JSDoc.

Last in the SD-2936 stack. Stacks on PR #3146.

Verified: pnpm exec vitest run src/ui → 244 passed (16 files, +14 new — 8 in keyboard-shortcuts, 6 in custom-commands); pnpm exec tsc -b tsconfig.references.json → clean.

[linear]

SD-2936 Building custom UI on SuperDoc requires reaching into internals

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 59ae2ff279

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[superdoc-bot]

🎉 This PR is included in @superdoc-dev/mcp v0.3.0-next.52

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in @superdoc-dev/react v1.2.0-next.94

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in vscode-ext v2.3.0-next.96

[superdoc-bot]

🎉 This PR is included in superdoc v1.30.0-next.53

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in superdoc-cli v0.8.0-next.70

The release is available on GitHub release

[superdoc-bot]

🎉 This PR is included in superdoc-sdk v1.8.0-next.53