fix(hub): handle nested command trees consistently

Author: SaKaNa-Y

packages/hub-ui/src/client/components/command-palette/CommandPalette.vue

@@ -1,10 +1,10 @@
 <script setup lang="ts">
-import type { DevframeClientCommand, DevframeCommandEntry } from '@devframes/hub'
+import type { DevframeClientCommand } from '@devframes/hub'
 import type { DocksContext } from '@devframes/hub/client'
 import type { PaletteCrumb, PaletteFlatItem } from '../../state/palette'
 import Fuse from 'fuse.js'
 import { computed, nextTick, ref, useTemplateRef, watch } from 'vue'
-import { flattenPaletteCommands, paletteScopeTrail } from '../../state/palette'
+import { flattenPaletteCommands, paletteActionKeepsOpen, paletteScopeTrail, paletteTrailScopeId, reconcilePaletteTrail, resolvePaletteSelection } from '../../state/palette'
 import BrandWordmark from '../icons/BrandWordmark.vue'
 import CommandPaletteItem from './CommandPaletteItem.vue'
 
@@ -70,7 +70,10 @@ function showScope(scopeId: string | null) {
   search.value = ''
   selectedIndex.value = 0
   dynamicItems.value = undefined
-  breadcrumb.value = paletteScopeTrail(commandsCtx.value.paletteCommands, scopeId)
+  const next = paletteScopeTrail(commandsCtx.value.paletteCommands, scopeId)
+  breadcrumb.value = next
+  if (scopeId != null && !next.some(crumb => crumb.id === scopeId))
+    commandsCtx.value.paletteScopeId = null
 }
 
 watch(show, (v) => {
@@ -96,10 +99,25 @@ watch(show, (v) => {
 // group picked from the root list, say. `show` stays `true` throughout, so the
 // drill-down follows the scope itself rather than the open transition.
 watch(() => commandsCtx.value.paletteScopeId, (scopeId) => {
-  if (show.value && scopeId)
+  if (show.value)
     showScope(scopeId)
 })
 
+// A command tree can change while the palette is open (dock registration,
+// `when` context, or a client command update). Rebuild each crumb by id so the
+// rendered rows and their actions always come from the live tree.
+watch(() => commandsCtx.value.paletteCommands, (commands) => {
+  if (!show.value || breadcrumb.value.length === 0)
+    return
+  const scopeId = commandsCtx.value.paletteScopeId
+  const scopeWasActive = scopeId != null && breadcrumb.value.some(crumb => crumb.id === scopeId)
+  const next = reconcilePaletteTrail(commands, breadcrumb.value, scopeId)
+  breadcrumb.value = next
+  selectedIndex.value = Math.min(selectedIndex.value, Math.max(filtered.value.length - 1, 0))
+  if (scopeWasActive && scopeId != null && !next.some(crumb => crumb.id === scopeId))
+    commandsCtx.value.paletteScopeId = null
+})
+
 function moveSelected(delta: number) {
   const len = filtered.value.length
   if (len === 0)
@@ -120,17 +138,16 @@ function scrollToItem() {
 const loadingId = ref<string | null>(null)
 
 async function enterItem(flatItem: PaletteFlatItem) {
-  const entry = flatItem.entry
+  // The row may have been rendered just before the command tree changed. Look
+  // it up again so a removed entry no-ops and a replacement runs its new action.
+  const entry = activeItems.value.find(item => item.entry.id === flatItem.entry.id)?.entry
+  if (!entry)
+    return
 
-  // If has static children, drill down
-  if (entry.children && entry.children.length > 0) {
-    breadcrumb.value.push({
-      title: entry.title,
-      items: entry.children as DevframeCommandEntry[],
-    })
-    search.value = ''
-    selectedIndex.value = 0
-    dynamicItems.value = undefined
+  // Ordinary command parents drill down. Dock groups are actionable parents:
+  // their action opens a preferred member or scopes the palette for a choice.
+  if (resolvePaletteSelection(entry, props.context.docks.entries) === 'drill') {
+    commandsCtx.value.paletteScopeId = entry.id
     return
   }
 
@@ -149,6 +166,8 @@ async function enterItem(flatItem: PaletteFlatItem) {
     catch (err) {
       console.error(`[@devframes/hub-ui] Command "${entry.id}" failed:`, err)
     }
+    if (paletteActionKeepsOpen(entry, props.context.docks.entries, commandsCtx.value.paletteOpen, commandsCtx.value.paletteScopeId))
+      return
     close()
     return
   }
@@ -193,7 +212,7 @@ function goBack() {
   }
   if (breadcrumb.value.length > 0) {
     breadcrumb.value.pop()
-    dropScopeAtRoot()
+    commandsCtx.value.paletteScopeId = paletteTrailScopeId(breadcrumb.value)
     search.value = ''
     selectedIndex.value = 0
     return
@@ -204,21 +223,11 @@ function goBack() {
 /** Jump to the level the crumb at `index` sits above. */
 function goToCrumb(index: number) {
   breadcrumb.value.splice(index)
-  dropScopeAtRoot()
+  commandsCtx.value.paletteScopeId = paletteTrailScopeId(breadcrumb.value)
   search.value = ''
   selectedIndex.value = 0
 }
 
-/**
- * Stepping back out to the root list leaves the palette unscoped, so the
- * shortcut that scoped it drills back in instead of reading as "press again to
- * close".
- */
-function dropScopeAtRoot() {
-  if (breadcrumb.value.length === 0)
-    commandsCtx.value.paletteScopeId = null
-}
-
 function onKeyDown(e: KeyboardEvent) {
   if (e.key === 'Backspace' && !search.value && (breadcrumb.value.length > 0 || dynamicItems.value)) {
     e.preventDefault()

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

@@ -259,6 +259,20 @@ describe('dock group command activation', () => {
     expect(context.commands.paletteScopeId).toBe('devframes:docks:tools')
   })
 
+  it('re-scopes after the palette steps back to the Docks parent', async () => {
+    expect.assertions(2)
+
+    const context = await createGroupedContext()
+    await context.commands.execute('devframes:docks:tools')
+    // The palette keeps its scope aligned with the breadcrumb whose children
+    // are currently visible.
+    context.commands.paletteScopeId = 'devframes:docks'
+    await context.commands.execute('devframes:docks:tools')
+
+    expect(context.commands.paletteOpen).toBe(true)
+    expect(context.commands.paletteScopeId).toBe('devframes:docks:tools')
+  })
+
   it('opens the sole visible member directly instead of a one-item palette', async () => {
     expect.assertions(2)
 

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

@@ -14,6 +14,7 @@ import { createCommandsContext } from './commands'
 import { docksGroupByCategories, getGroupMembers, getRegisteredGroupIds, resolveCommandIcon, resolveGroupPreferredChild } from './dock-settings'
 import { createDockEntryState, DEFAULT_DOCK_PANEL_STORE, DEFAULT_DOCK_SESSION_STORE, sharedStateToRef, useDocksEntries, waitForInitialSharedStateSync } from './docks'
 import { createClientMessagesClient } from './messages-client'
+import { dockCommandId } from './palette'
 import { registerMainFrameDockActionHandler, triggerMainFrameDockAction, useIsDockPopupOpen } from './popup'
 import { executeSetupScript } from './setup-script'
 
@@ -515,7 +516,7 @@ export async function createDocksContext(
     cleanupDocksCommand?.()
 
     const toCommand = (entry: DevframeDockEntry): DevframeClientCommand => ({
-      id: `devframes:docks:${entry.id}`,
+      id: dockCommandId(entry.id),
       source: 'client' as const,
       title: entry.title,
       icon: resolveCommandIcon(entry.icon),
@@ -576,7 +577,7 @@ export async function createDocksContext(
         // dead row in the palette and the shortcut settings.
         if (visibleMembers.length === 0 && !preferredChildId)
           return []
-        const commandId = `devframes:docks:${entry.id}`
+        const commandId = dockCommandId(entry.id)
         return [{
           ...toCommand(entry),
           action: () => activateGroup(

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

@@ -1,6 +1,6 @@
-import type { DevframeCommandEntry } from '@devframes/hub'
+import type { DevframeClientCommand, DevframeCommandEntry, DevframeDockEntry } from '@devframes/hub'
 import { describe, expect, it } from 'vitest'
-import { flattenPaletteCommands, paletteScopeTrail } from './palette'
+import { flattenPaletteCommands, paletteActionKeepsOpen, paletteScopeTrail, paletteTrailScopeId, reconcilePaletteTrail, resolvePaletteSelection } from './palette'
 
 /**
  * The shape the palette actually sees: dock navigation two deep (`Docks` › a
@@ -47,6 +47,10 @@ const commands = [
   },
 ] as unknown as DevframeCommandEntry[]
 
+const docks = [
+  { id: 'tools', type: 'group' },
+] as DevframeDockEntry[]
+
 describe('flattenPaletteCommands', () => {
   it('lists a nested command with its full path for search and its parent for display', () => {
     const rows = flattenPaletteCommands(commands)
@@ -81,6 +85,40 @@ describe('flattenPaletteCommands', () => {
   })
 })
 
+describe('resolvePaletteSelection', () => {
+  it('executes a dock group while ordinary command parents still drill down', () => {
+    const action = () => {}
+    const dockGroup = {
+      ...commands[0]!.children![1],
+      action,
+    } as DevframeCommandEntry
+    const ordinaryParent = {
+      ...commands[1],
+      action,
+    } as DevframeCommandEntry
+
+    expect(resolvePaletteSelection(dockGroup, docks)).toBe('execute')
+    expect(resolvePaletteSelection(ordinaryParent, docks)).toBe('drill')
+
+    const namespacedParent = {
+      ...ordinaryParent,
+      id: 'devframes:docks:not-a-group',
+    } as DevframeCommandEntry
+    expect(resolvePaletteSelection(namespacedParent, docks)).toBe('drill')
+  })
+
+  it('keeps the palette open only when a dock group action scoped it to itself', () => {
+    const dockGroup = {
+      ...commands[0]!.children![1],
+      action: () => {},
+    } as DevframeCommandEntry
+
+    expect(paletteActionKeepsOpen(dockGroup, docks, true, dockGroup.id)).toBe(true)
+    expect(paletteActionKeepsOpen(dockGroup, docks, true, null)).toBe(false)
+    expect(paletteActionKeepsOpen(commands[1]!, docks, true, commands[1]!.id)).toBe(false)
+  })
+})
+
 describe('paletteScopeTrail', () => {
   it('builds the crumb stack a user would have clicked to reach the scope', () => {
     const trail = paletteScopeTrail(commands, 'devframes:docks:tools')
@@ -103,4 +141,39 @@ describe('paletteScopeTrail', () => {
   it('opens the root list for a command with nothing to drill into', () => {
     expect(paletteScopeTrail(commands, 'devframes:docks:overview')).toEqual([])
   })
+
+  it('tracks the scope as the user backs out through each breadcrumb level', () => {
+    const trail = paletteScopeTrail(commands, 'devframes:docks:tools')
+
+    expect(paletteTrailScopeId(trail)).toBe('devframes:docks:tools')
+    trail.pop()
+    expect(paletteTrailScopeId(trail)).toBe('devframes:docks')
+    trail.pop()
+    expect(paletteTrailScopeId(trail)).toBeNull()
+  })
+})
+
+describe('reconcilePaletteTrail', () => {
+  it('replaces scoped rows with the live command entries', () => {
+    const current = paletteScopeTrail(commands, 'devframes:docks:tools')
+    const replacementAction = () => {}
+    const replacement = structuredClone(commands) as DevframeCommandEntry[]
+    const tools = replacement[0]!.children![1] as DevframeClientCommand
+    tools.children![0] = {
+      ...tools.children![0]!,
+      action: replacementAction,
+    }
+
+    const reconciled = reconcilePaletteTrail(replacement, current, 'devframes:docks:tools')
+
+    expect((reconciled.at(-1)!.items[0] as DevframeClientCommand).action).toBe(replacementAction)
+  })
+
+  it('returns to the root when the scoped command is removed', () => {
+    const current = paletteScopeTrail(commands, 'devframes:docks:tools')
+    const withoutTools = structuredClone(commands) as DevframeCommandEntry[]
+    withoutTools[0]!.children!.splice(1, 1)
+
+    expect(reconcilePaletteTrail(withoutTools, current, 'devframes:docks:tools')).toEqual([])
+  })
 })

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

@@ -1,22 +1,70 @@
-import type { DevframeCommandEntry } from '@devframes/hub'
+import type { DevframeCommandEntry, DevframeDockEntry } from '@devframes/hub'
 import { walkCommands } from './keybindings'
 
+const DOCKS_COMMAND_ID = 'devframes:docks'
+
+/** Build the command id used for one dock entry. */
+export function dockCommandId(dockId: string): string {
+  return `${DOCKS_COMMAND_ID}:${dockId}`
+}
+
 /**
  * One level of the palette's drill-down stack: the command the user stepped
  * into, and the rows that level shows.
  */
 export interface PaletteCrumb {
+  id: string
   title: string
   items: DevframeCommandEntry[]
 }
 
+/** The command whose children the current breadcrumb level displays. */
+export function paletteTrailScopeId(trail: PaletteCrumb[]): string | null {
+  return trail.at(-1)?.id ?? null
+}
+
 /** A palette row, flattened out of the command tree for root search. */
 export interface PaletteFlatItem {
   entry: DevframeCommandEntry
   parentTitle?: string
   searchTitle: string
 }
 
+export type PaletteSelection = 'drill' | 'execute'
+
+/** Dock groups are the actionable parents directly below the Docks command. */
+function isDockGroupCommand(
+  entry: DevframeCommandEntry,
+  docks: readonly DevframeDockEntry[],
+): boolean {
+  return entry.source === 'client'
+    && !!entry.action
+    && !!entry.children?.length
+    && docks.some(dock => dock.type === 'group' && dockCommandId(dock.id) === entry.id)
+}
+
+/** Decide whether selecting a row navigates into it or executes it. */
+export function resolvePaletteSelection(
+  entry: DevframeCommandEntry,
+  docks: readonly DevframeDockEntry[],
+): PaletteSelection {
+  if (isDockGroupCommand(entry, docks))
+    return 'execute'
+  return entry.children?.length ? 'drill' : 'execute'
+}
+
+/** An ambiguous dock group keeps the palette open by scoping it to itself. */
+export function paletteActionKeepsOpen(
+  entry: DevframeCommandEntry,
+  docks: readonly DevframeDockEntry[],
+  paletteOpen: boolean,
+  paletteScopeId: string | null,
+): boolean {
+  return isDockGroupCommand(entry, docks)
+    && paletteOpen
+    && paletteScopeId === entry.id
+}
+
 /**
  * Every command at every depth, so root search finds a nested entry — a dock
  * group's members, and anything a devframe nests below them — without drilling.
@@ -73,9 +121,38 @@ export function paletteScopeTrail(
     if (cmd.children?.length) {
       crumbs = [...ancestors, cmd]
         .filter(c => c.children?.length)
-        .map(c => ({ title: c.title, items: c.children as DevframeCommandEntry[] }))
+        .map(c => ({ id: c.id, title: c.title, items: c.children as DevframeCommandEntry[] }))
     }
     return 'stop'
   })
   return crumbs
 }
+
+/**
+ * Rebuild an open drill-down trail from the live command tree. Command ids keep
+ * the user's current level stable while every row is replaced with its latest
+ * entry object, so an unregistered or updated action cannot linger in a crumb.
+ */
+export function reconcilePaletteTrail(
+  commands: DevframeCommandEntry[],
+  current: PaletteCrumb[],
+  scopeId: string | null,
+): PaletteCrumb[] {
+  const scopeWasActive = scopeId != null && current.some(crumb => crumb.id === scopeId)
+  const result: PaletteCrumb[] = []
+  let level = commands
+
+  for (const crumb of current) {
+    const entry = level.find(command => command.id === crumb.id)
+    if (!entry?.children?.length)
+      break
+    const items = entry.children as DevframeCommandEntry[]
+    result.push({ id: entry.id, title: entry.title, items })
+    level = items
+  }
+
+  if (scopeWasActive && !result.some(crumb => crumb.id === scopeId))
+    return paletteScopeTrail(commands, scopeId)
+
+  return result
+}