refactor: move when evaluator to kit, replace isHidden with when on docks

Move evaluateWhen/WhenContext/getContextValue to packages/kit/src/utils/when.ts
as a dedicated module exported from @vitejs/devtools-kit. Core keybindings.ts
now re-exports from kit.

Replace isHidden?: boolean on DevToolsDockEntryBase with when?: string, using
the same expression syntax as command when clauses. The ~terminals dock now
uses `get when() { return sessions.size === 0 ? 'false' : undefined }`.

evaluateWhen now supports 'true' and 'false' as literal values, enabling
unconditional hide/show without a context variable.

DockEntries.vue evaluates dock when clauses client-side with a reactive
WhenContext. docksGroupByCategories accepts optional whenContext for filtering.

Comprehensive when.test.ts in kit (32 test files, 245 tests total).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: antfu

packages/core/src/client/webcomponents/components/dock/DockEntries.vue

@@ -1,7 +1,8 @@
 <script setup lang="ts">
-import type { DevToolsDockEntry } from '@vitejs/devtools-kit'
+import type { DevToolsDockEntry, WhenContext } from '@vitejs/devtools-kit'
 import type { DocksContext } from '@vitejs/devtools-kit/client'
-import { toRefs } from 'vue'
+import { evaluateWhen } from '@vitejs/devtools-kit'
+import { computed, toRefs } from 'vue'
 import DockEntry from './DockEntry.vue'
 
 const props = defineProps<{
@@ -17,6 +18,19 @@ const emit = defineEmits<{
 
 const { selected, isVertical, entries } = toRefs(props)
 
+const whenContext = computed<WhenContext>(() => ({
+  clientType: props.context.clientType,
+  dockOpen: props.context.panel.store.open,
+  paletteOpen: props.context.commands.paletteOpen,
+  dockSelectedId: props.context.docks.selectedId ?? '',
+}))
+
+function isDockVisible(dock: DevToolsDockEntry): boolean {
+  if (!dock.when)
+    return true
+  return evaluateWhen(dock.when, whenContext.value)
+}
+
 function toggleDockEntry(dock: DevToolsDockEntry) {
   if (selected.value?.id === dock.id)
     emit('select', undefined!)
@@ -28,7 +42,7 @@ function toggleDockEntry(dock: DevToolsDockEntry) {
 <template>
   <template v-for="dock of entries" :key="dock.id">
     <DockEntry
-      v-if="!dock.isHidden"
+      v-if="isDockVisible(dock)"
       :context="context"
       :dock
       :is-selected="selected?.id === dock.id"

packages/core/src/client/webcomponents/state/__tests__/keybindings.test.ts

@@ -1,7 +1,6 @@
 import type { DevToolsCommandEntry, DevToolsCommandKeybinding } from '@vitejs/devtools-kit'
-import type { WhenContext } from '../keybindings'
 import { describe, expect, it } from 'vitest'
-import { collectAllKeybindings, evaluateWhen, formatKeybinding, KNOWN_BROWSER_SHORTCUTS, normalizeKeyEvent } from '../keybindings'
+import { collectAllKeybindings, formatKeybinding, KNOWN_BROWSER_SHORTCUTS, normalizeKeyEvent } from '../keybindings'
 
 describe('formatKeybinding', () => {
   it('splits key string into parts', () => {
@@ -10,7 +9,6 @@ describe('formatKeybinding', () => {
 
   it('formats modifier keys', () => {
     const result = formatKeybinding('Mod+Shift+K')
-    // Platform-dependent, but should have 3 parts
     expect(result).toHaveLength(3)
     expect(result[2]).toBe('K')
   })
@@ -41,7 +39,6 @@ describe('normalizeKeyEvent', () => {
 
   it('ignores modifier-only events', () => {
     const result = normalizeKeyEvent(makeKeyEvent({ key: 'Control', ctrlKey: true }))
-    // On non-Mac, ctrlKey maps to Mod; key is Control which is filtered out
     expect(result).toMatch(/^(Mod|Ctrl)?$/)
   })
 
@@ -56,145 +53,6 @@ describe('normalizeKeyEvent', () => {
   })
 })
 
-describe('evaluateWhen', () => {
-  const ctx: WhenContext = {
-    clientType: 'embedded',
-    dockOpen: true,
-    paletteOpen: false,
-    dockSelectedId: 'my-dock',
-  }
-
-  describe('bare truthy', () => {
-    it('evaluates true for truthy values', () => {
-      expect(evaluateWhen('dockOpen', ctx)).toBe(true)
-    })
-
-    it('evaluates false for falsy values', () => {
-      expect(evaluateWhen('paletteOpen', ctx)).toBe(false)
-    })
-
-    it('evaluates true for non-empty string', () => {
-      expect(evaluateWhen('dockSelectedId', ctx)).toBe(true)
-    })
-
-    it('evaluates false for undefined keys', () => {
-      expect(evaluateWhen('unknownKey', ctx)).toBe(false)
-    })
-  })
-
-  describe('negation (!)', () => {
-    it('negates truthy to false', () => {
-      expect(evaluateWhen('!dockOpen', ctx)).toBe(false)
-    })
-
-    it('negates falsy to true', () => {
-      expect(evaluateWhen('!paletteOpen', ctx)).toBe(true)
-    })
-
-    it('negates undefined to true', () => {
-      expect(evaluateWhen('!unknownKey', ctx)).toBe(true)
-    })
-  })
-
-  describe('equality (==)', () => {
-    it('matches string values', () => {
-      expect(evaluateWhen('clientType == embedded', ctx)).toBe(true)
-    })
-
-    it('rejects non-matching string values', () => {
-      expect(evaluateWhen('clientType == standalone', ctx)).toBe(false)
-    })
-
-    it('compares boolean as string', () => {
-      expect(evaluateWhen('dockOpen == true', ctx)).toBe(true)
-      expect(evaluateWhen('dockOpen == false', ctx)).toBe(false)
-    })
-
-    it('matches dockSelectedId', () => {
-      expect(evaluateWhen('dockSelectedId == my-dock', ctx)).toBe(true)
-      expect(evaluateWhen('dockSelectedId == other-dock', ctx)).toBe(false)
-    })
-  })
-
-  describe('inequality (!=)', () => {
-    it('true when values differ', () => {
-      expect(evaluateWhen('clientType != standalone', ctx)).toBe(true)
-    })
-
-    it('false when values match', () => {
-      expect(evaluateWhen('clientType != embedded', ctx)).toBe(false)
-    })
-  })
-
-  describe('aND (&&)', () => {
-    it('true when all parts are true', () => {
-      expect(evaluateWhen('dockOpen && !paletteOpen', ctx)).toBe(true)
-    })
-
-    it('false when any part is false', () => {
-      expect(evaluateWhen('dockOpen && paletteOpen', ctx)).toBe(false)
-    })
-
-    it('supports three-part AND', () => {
-      expect(evaluateWhen('dockOpen && !paletteOpen && clientType == embedded', ctx)).toBe(true)
-      expect(evaluateWhen('dockOpen && !paletteOpen && clientType == standalone', ctx)).toBe(false)
-    })
-  })
-
-  describe('oR (||)', () => {
-    it('true when any part is true', () => {
-      expect(evaluateWhen('paletteOpen || dockOpen', ctx)).toBe(true)
-    })
-
-    it('false when all parts are false', () => {
-      expect(evaluateWhen('paletteOpen || !dockOpen', ctx)).toBe(false)
-    })
-
-    it('supports mixed AND and OR (OR of ANDs)', () => {
-      // paletteOpen=false, so first branch fails; dockOpen=true, so second branch succeeds
-      expect(evaluateWhen('paletteOpen && clientType == standalone || dockOpen', ctx)).toBe(true)
-    })
-  })
-
-  describe('with empty dockSelectedId', () => {
-    const emptyCtx: WhenContext = {
-      clientType: 'standalone',
-      dockOpen: false,
-      paletteOpen: true,
-      dockSelectedId: '',
-    }
-
-    it('empty string is falsy', () => {
-      expect(evaluateWhen('dockSelectedId', emptyCtx)).toBe(false)
-    })
-
-    it('negation of empty string is true', () => {
-      expect(evaluateWhen('!dockSelectedId', emptyCtx)).toBe(true)
-    })
-  })
-
-  describe('with custom context variables', () => {
-    const customCtx: WhenContext = {
-      clientType: 'embedded',
-      dockOpen: true,
-      paletteOpen: false,
-      dockSelectedId: '',
-      myPluginActive: true,
-      myPluginMode: 'debug',
-    }
-
-    it('evaluates custom boolean', () => {
-      expect(evaluateWhen('myPluginActive', customCtx)).toBe(true)
-      expect(evaluateWhen('!myPluginActive', customCtx)).toBe(false)
-    })
-
-    it('evaluates custom string equality', () => {
-      expect(evaluateWhen('myPluginMode == debug', customCtx)).toBe(true)
-      expect(evaluateWhen('myPluginMode == release', customCtx)).toBe(false)
-    })
-  })
-})
-
 describe('collectAllKeybindings', () => {
   it('collects from top-level and children', () => {
     const commands = {

packages/core/src/client/webcomponents/state/context.ts

@@ -1,4 +1,4 @@
-import type { DevToolsClientCommand } from '@vitejs/devtools-kit'
+import type { DevToolsClientCommand, WhenContext } from '@vitejs/devtools-kit'
 import type { CommandsContext, DevToolsRpcClient, DockClientScriptContext, DockEntryState, DockPanelStorage, DocksContext } from '@vitejs/devtools-kit/client'
 import type { SharedState } from '@vitejs/devtools-kit/utils/shared-state'
 import type { Ref } from 'vue'
@@ -109,18 +109,22 @@ export async function createDocksContext(
   // Get settings store and create computed grouped entries
   const settingsStore = markRaw(await getSettingsStore())
   const settings = sharedStateToRef(settingsStore)
-  const groupedEntries = computed(() => {
-    return docksGroupByCategories(dockEntries.value, settings.value)
-  })
 
-  // Initialize commands context with reactive when-context
+  // Shared when-context provider — used by both commands and docks
   let commandsContext: CommandsContext
-  const commandsContextResult = await createCommandsContext(clientType, rpc, () => ({
+  const getWhenContext = (): WhenContext => ({
     clientType,
     dockOpen: panelStore.value.open,
     paletteOpen: commandsContext?.paletteOpen ?? false,
     dockSelectedId: selectedId.value ?? '',
-  }))
+  })
+
+  const groupedEntries = computed(() => {
+    return docksGroupByCategories(dockEntries.value, settings.value, { whenContext: getWhenContext() })
+  })
+
+  // Initialize commands context with reactive when-context
+  const commandsContextResult = await createCommandsContext(clientType, rpc, getWhenContext)
   commandsContext = commandsContextResult
 
   // Register built-in client commands
@@ -194,11 +198,10 @@ export async function createDocksContext(
     const dockChildren: DevToolsClientCommand[] = dockEntries.value
       .filter(entry => entry.type !== '~builtin')
       .map((entry) => {
-        const isAction = entry.type === 'action'
         return {
           id: `devtools:docks:${entry.id}`,
           source: 'client' as const,
-          title: `${isAction ? 'Execute' : 'Open'} ${entry.title}`,
+          title: entry.title,
           icon: typeof entry.icon === 'string' ? entry.icon : undefined,
           action: () => {
             switchEntry(entry.id)

packages/core/src/client/webcomponents/state/dock-settings.ts

@@ -1,5 +1,6 @@
-import type { DevToolsDockEntriesGrouped, DevToolsDockEntry, DevToolsDocksUserSettings } from '@vitejs/devtools-kit'
+import type { DevToolsDockEntriesGrouped, DevToolsDockEntry, DevToolsDocksUserSettings, WhenContext } from '@vitejs/devtools-kit'
 import type { Immutable } from '@vitejs/devtools-kit/utils/shared-state'
+import { evaluateWhen } from '@vitejs/devtools-kit'
 import { DEFAULT_CATEGORIES_ORDER } from '../constants'
 
 export type { DevToolsDocksUserSettings }
@@ -17,15 +18,17 @@ export interface SplitGroupsResult {
 export function docksGroupByCategories(
   entries: DevToolsDockEntry[],
   settings: Immutable<DevToolsDocksUserSettings>,
-  options?: { includeHidden?: boolean },
+  options?: { includeHidden?: boolean, whenContext?: WhenContext },
 ): DevToolsDockEntriesGrouped {
   const { docksHidden, docksCategoriesHidden, docksCustomOrder, docksPinned } = settings
-  const { includeHidden = false } = options ?? {}
+  const { includeHidden = false, whenContext } = options ?? {}
 
   const map = new Map<string, DevToolsDockEntry[]>()
   for (const entry of entries) {
-    // Skip if hidden by entry property
-    if (entry.isHidden && !includeHidden)
+    // Skip if hidden by `when` clause
+    if (entry.when && whenContext && !evaluateWhen(entry.when, whenContext) && !includeHidden)
+      continue
+    if (entry.when && !whenContext && entry.when === 'false' && !includeHidden)
       continue
     if (!includeHidden && docksHidden.includes(entry.id))
       continue

packages/core/src/client/webcomponents/state/keybindings.ts

@@ -1,50 +1,8 @@
 import type { DevToolsCommandEntry, DevToolsCommandKeybinding } from '@vitejs/devtools-kit'
 
-export interface WhenContext {
-  clientType: 'embedded' | 'standalone'
-  dockOpen: boolean
-  paletteOpen: boolean
-  dockSelectedId: string
-  /** Allow custom context variables from plugins */
-  [key: string]: unknown
-}
-
-export function evaluateWhen(expression: string, ctx: WhenContext): boolean {
-  // Simple expression evaluator: supports ==, !=, &&, ||, !, bare truthy
-  const parts = expression.split('||').map(s => s.trim())
-  return parts.some((orPart) => {
-    const andParts = orPart.split('&&').map(s => s.trim())
-    return andParts.every((part) => {
-      const trimmed = part.trim()
-
-      // Negation
-      if (trimmed.startsWith('!')) {
-        const key = trimmed.slice(1).trim()
-        return !getContextValue(key, ctx)
-      }
-
-      // Equality/inequality
-      const eqIdx = trimmed.indexOf('==')
-      const neqIdx = trimmed.indexOf('!=')
-      if (eqIdx !== -1 || neqIdx !== -1) {
-        const isNeq = neqIdx !== -1 && (eqIdx === -1 || neqIdx < eqIdx)
-        const opIdx = isNeq ? neqIdx : eqIdx
-        const opLen = isNeq ? 2 : 2
-        const key = trimmed.slice(0, opIdx).trim()
-        const value = trimmed.slice(opIdx + opLen).trim()
-        const actual = String(getContextValue(key, ctx))
-        return isNeq ? actual !== value : actual === value
-      }
-
-      // Bare truthy
-      return !!getContextValue(trimmed, ctx)
-    })
-  })
-}
-
-export function getContextValue(key: string, ctx: WhenContext): unknown {
-  return (ctx as unknown as Record<string, unknown>)[key]
-}
+// Re-export when utilities from kit
+export type { WhenContext } from '@vitejs/devtools-kit'
+export { evaluateWhen, getContextValue } from '@vitejs/devtools-kit'
 
 export const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform ?? '')
 

packages/core/src/node/host-docks.ts

@@ -38,8 +38,8 @@ export class DevToolsDockHost implements DevToolsDockHostType {
         title: 'Terminals',
         icon: 'ph:terminal-duotone',
         category: '~builtin',
-        get isHidden() {
-          return context.terminals.sessions.size === 0
+        get when() {
+          return context.terminals.sessions.size === 0 ? 'false' : undefined
         },
       },
       {

packages/kit/src/index.ts

@@ -1,3 +1,4 @@
 export type * from './types'
 export * from './utils/define'
 export * from './utils/json-render'
+export * from './utils/when'

packages/kit/src/types/docks.ts

@@ -34,10 +34,16 @@ export interface DevToolsDockEntryBase {
    */
   category?: DevToolsDockEntryCategory
   /**
-   * Whether the entry should be hidden from the user.
-   * @default false
+   * Conditional visibility expression.
+   * When set, the dock entry is only visible when the expression evaluates to true.
+   * Uses the same syntax as command `when` clauses.
+   *
+   * Set to `'false'` to unconditionally hide the entry.
+   *
+   * @example 'clientType == embedded'
+   * @see {@link import('../utils/when').evaluateWhen}
    */
-  isHidden?: boolean
+  when?: string
   /**
    * Badge text to display on the dock icon (e.g., unread count)
    */