fix(hub-ui): allow commands to opt out of keyboard shortcuts (#395)

Author: SaKaNa-Y

docs/content/1.guide/16.hub.md

@@ -79,6 +79,8 @@ ctx.commands.register({
 
 Set `showInPalette: 'without-children'` on a parent to keep its whole subtree out of root search while leaving it reachable by drilling down.
 
+Set `allowShortcuts: false` for commands that require arguments from their caller. The hub UI hides their shortcut settings and ignores default and saved bindings. Explicit calls through `ctx.commands.execute(id, ...args)` remain available. This option is independent of `showInPalette` and applies to each command individually, including nested commands.
+
 ## Cross-iframe dock activation
 
 A mounted devframe's iframe uses `hub:docks:activate` to switch the active dock.

packages/hub-ui/src/client/components/views-builtin/SettingsShortcuts.vue

@@ -1,10 +1,11 @@
 <script setup lang="ts">
 import type { DevframeCommandEntry, DevframeCommandKeybinding } from '@devframes/hub'
 import type { DocksContext } from '@devframes/hub/client'
+import type { ShortcutRow } from '../../state/keybindings'
 import DisplayKbd from '@antfu/design/components/Display/DisplayKbd.vue'
 import { computed, nextTick, ref, watch } from 'vue'
 import { t } from '../../i18n'
-import { filterCommandsByWhen, findCommandDeep, formatKeybinding, isKeybindingOverrideDifferentFromDefault, isMac, KNOWN_BROWSER_SHORTCUTS, walkCommands } from '../../state/keybindings'
+import { filterCommandsByWhen, findCommandDeep, formatKeybinding, getShortcutRows, isKeybindingOverrideDifferentFromDefault, isMac, KNOWN_BROWSER_SHORTCUTS } from '../../state/keybindings'
 import { useSettings } from '../../state/settings-defaults'
 import DockIcon from '../dock/DockIcon.vue'
 
@@ -17,13 +18,6 @@ const settings = useSettings(props.context)
 const shortcutOverrides = computed(() => settings.value.commandShortcuts ?? {})
 const shortcutSearch = ref('')
 
-interface ShortcutRow {
-  command: DevframeCommandEntry
-  parentTitle?: string
-  /** Nesting level: 0 for a top-level command, +1 per ancestor. */
-  depth: number
-}
-
 // This page is only reachable with the dock open and the palette closed, so `when`
 // is evaluated against that context rather than the live one. `dockOpen`/`paletteOpen`
 // are transient dispatch state: `close-panel`'s `!paletteOpen` exists to hand Escape
@@ -36,26 +30,7 @@ const availableCommands = computed(() => filterCommandsByWhen(
   { ...props.context.when.context, dockOpen: true, paletteOpen: false },
 ))
 
-/**
- * One row per command at every depth, in tree order, so anything the palette
- * can run can be given a shortcut here.
- *
- * Nesting runs deeper than a parent and its children: a dock group's members sit
- * two levels below the `Docks` command, and a devframe's own `children` go deeper
- * still.
- */
-const shortcutRows = computed<ShortcutRow[]>(() => {
-  const rows: ShortcutRow[] = []
-  walkCommands(availableCommands.value, (cmd, ancestors) => {
-    const parentTitle = ancestors.at(-1)?.title
-    rows.push({
-      command: cmd,
-      ...(parentTitle ? { parentTitle } : {}),
-      depth: ancestors.length,
-    })
-  })
-  return rows
-})
+const shortcutRows = computed(() => getShortcutRows(availableCommands.value))
 
 const filteredShortcutRows = computed(() => {
   if (!shortcutSearch.value)

packages/hub-ui/src/client/state/commands.test.ts

@@ -1,7 +1,8 @@
-import type { DevframeDocksUserSettings } from '@devframes/hub'
+import type { DevframeDocksUserSettings, DevframeServerCommandEntry } from '@devframes/hub'
 import type { DevframeRpcClient } from '@devframes/hub/client'
+import { DEFAULT_STATE_USER_SETTINGS, HUB_EVENTS } from '@devframes/hub/constants'
 import { createSharedState } from 'devframe/utils/shared-state'
-import { afterEach, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { effectScope, nextTick, shallowRef } from 'vue'
 import { createCommandsContext } from './commands'
 import { isMac } from './keybindings'
@@ -65,3 +66,61 @@ it.each(['standalone', 'shadow-root', 'popup'] as const)('leaves recording keyst
     scope.stop()
   }
 })
+
+describe('command shortcut eligibility', () => {
+  it('ignores saved and default bindings while preserving explicit calls and palette shortcuts', async () => {
+    const command = {
+      id: 'tool:open-file',
+      title: 'Open File',
+      source: 'server',
+      showInPalette: false,
+      allowShortcuts: false,
+      keybindings: [{ key: 'Alt+E' }],
+    } satisfies DevframeServerCommandEntry
+    const serverState = createSharedState<DevframeServerCommandEntry[]>({ initialValue: [command] })
+    const settings = createSharedState({
+      initialValue: {
+        ...DEFAULT_STATE_USER_SETTINGS(),
+        commandShortcuts: { [command.id]: [{ key: 'Alt+Y' }] },
+      },
+    })
+    const call = vi.fn()
+    // eslint-disable-next-line slop/no-chained-type-assertions -- the command context only needs these two RPC APIs.
+    const rpc = { sharedState: { get: async () => serverState }, call } as unknown as DevframeRpcClient
+    const window = new EventTarget()
+    vi.stubGlobal('window', window)
+    const context = await createCommandsContext('embedded', rpc, settings)
+    const openPalette = vi.fn()
+    context.register({
+      id: 'tool:palette',
+      title: 'Toggle Palette',
+      source: 'client',
+      showInPalette: false,
+      keybindings: [{ key: 'Alt+K' }],
+      action: openPalette,
+    })
+
+    const press = (key: string) => window.dispatchEvent(Object.assign(new Event('keydown', { cancelable: true }), {
+      key,
+      altKey: true,
+      ctrlKey: false,
+      metaKey: false,
+      shiftKey: false,
+    }))
+
+    const unhandled = press('y')
+    expect(call).not.toHaveBeenCalled()
+    expect(unhandled).toBe(true)
+    expect(context.getKeybindings(command.id)).toEqual([])
+    settings.mutate((state) => {
+      delete state.commandShortcuts[command.id]
+    })
+    expect(press('e')).toBe(true)
+    expect(call).not.toHaveBeenCalled()
+
+    press('k')
+    expect(openPalette).toHaveBeenCalledOnce()
+    await context.execute(command.id, 'src/main.ts')
+    expect(call).toHaveBeenCalledExactlyOnceWith(HUB_EVENTS.rpc.commandsExecute, command.id, 'src/main.ts')
+  })
+})

packages/hub-ui/src/client/state/commands.ts

@@ -107,11 +107,14 @@ export async function createCommandsContext(
   }
 
   function getKeybindings(id: string): DevframeCommandKeybinding[] {
+    const cmd = findCommandDeep(commands.value, id)
+    if (cmd?.allowShortcuts === false)
+      return []
+
     const overrides = shortcutOverrides.value[id]
     if (overrides !== undefined)
       return overrides
 
-    const cmd = findCommandDeep(commands.value, id)
     return cmd?.keybindings ?? []
   }
 

packages/hub-ui/src/client/state/keybindings.test.ts

@@ -1,7 +1,30 @@
 import type { DevframeCommandEntry, DevframeCommandKeybinding } from '@devframes/hub'
 import type { WhenContext } from 'devframe/utils/when'
 import { describe, expect, it } from 'vitest'
-import { collectAllKeybindings, filterCommandsByWhen, findCommandDeep, walkCommands } from './keybindings'
+import { collectAllKeybindings, filterCommandsByWhen, findCommandDeep, getShortcutRows, walkCommands } from './keybindings'
+
+describe('getShortcutRows', () => {
+  it('omits opted-out commands while retaining their bindable descendants and palette-hidden commands', () => {
+    const commands: DevframeCommandEntry[] = [
+      { id: 'open-file', title: 'Open File', source: 'server', allowShortcuts: false },
+      {
+        id: 'tools',
+        title: 'Tools',
+        source: 'client',
+        allowShortcuts: false,
+        children: [
+          { id: 'open-selected', title: 'Open Selected', source: 'client', allowShortcuts: true },
+          { id: 'open-path', title: 'Open Path', source: 'client', allowShortcuts: false },
+        ],
+      },
+      { id: 'palette', title: 'Palette', source: 'client', showInPalette: false },
+    ]
+    expect(getShortcutRows(commands).map(row => ({ id: row.command.id, parentTitle: row.parentTitle, depth: row.depth }))).toEqual([
+      { id: 'open-selected', parentTitle: 'Tools', depth: 1 },
+      { id: 'palette', parentTitle: undefined, depth: 0 },
+    ])
+  })
+})
 
 /**
  * Dock-navigation commands nest two deep (`Docks` › a group › its members), and

packages/hub-ui/src/client/state/keybindings.ts

@@ -111,6 +111,28 @@ export function findCommandDeep(
   return found
 }
 
+export interface ShortcutRow {
+  command: DevframeCommandEntry
+  parentTitle?: string
+  depth: number
+}
+
+/** List bindable commands at every depth, retaining each command's ancestry. */
+export function getShortcutRows(commands: DevframeCommandEntry[]): ShortcutRow[] {
+  const rows: ShortcutRow[] = []
+  walkCommands(commands, (cmd, ancestors) => {
+    if (cmd.allowShortcuts === false)
+      return
+    const parentTitle = ancestors.at(-1)?.title
+    rows.push({
+      command: cmd,
+      ...(parentTitle ? { parentTitle } : {}),
+      depth: ancestors.length,
+    })
+  })
+  return rows
+}
+
 /**
  * Drop the commands whose `when` clause does not hold in the current context,
  * descendants included at every depth; `when` controls palette visibility at

packages/hub/src/node/__tests__/host-commands.test.ts

@@ -7,6 +7,29 @@ import { DevframeCommandsHost } from '../host-commands'
 
 type DeepPartial<T> = { [K in keyof T]?: DeepPartial<T[K]> }
 
+describe('command shortcut metadata', () => {
+  it('publishes eligibility for nested commands without preventing explicit execution', async () => {
+    const host = new DevframeCommandsHost({} as DevframeHubContext)
+    host.register({
+      id: 'tool:files',
+      title: 'Files',
+      children: [{
+        id: 'tool:open',
+        title: 'Open',
+        allowShortcuts: false,
+        handler: (path: string) => path,
+      }],
+    })
+
+    expect(host.list()[0]?.children?.[0]).toMatchObject({
+      id: 'tool:open',
+      allowShortcuts: false,
+      source: 'server',
+    })
+    await expect(host.execute('tool:open', 'src/main.ts')).resolves.toBe('src/main.ts')
+  })
+})
+
 describe('devframeCommandsHost command id validation', () => {
   it('rejects duplicate ids inside one command tree', () => {
     const host = new DevframeCommandsHost({} as DevframeHubContext)

packages/hub/src/types/commands.ts

@@ -41,6 +41,13 @@ export interface DevframeCommandBase {
    * when the expression evaluates to true.
    */
   when?: string
+  /**
+   * Whether keyboard shortcuts can invoke this command. Default: true.
+   * Set to false for commands that require arguments from their caller.
+   * The hub UI hides their shortcut settings and ignores default and saved bindings.
+   * Explicit calls through `commands.execute(id, ...args)` remain available.
+   */
+  allowShortcuts?: boolean
   /**
    * Default keyboard shortcut(s) for this command
    */

tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts

@@ -54,6 +54,7 @@ export interface DevframeCommandBase {
   category?: string;
   showInPalette?: boolean | 'without-children';
   when?: string;
+  allowShortcuts?: boolean;
   keybindings?: DevframeCommandKeybinding[];
 }
 export interface DevframeCommandHandle {