feat(hub): report extensible panel state

Author: dvcolomban

docs/content/8.references/3.events.md

@@ -26,14 +26,14 @@ Each subsystem emits on `ctx.<subsystem>.events`, consumed **inside the same nod
 | `messages:added` / `messages:updated` / `messages:removed` / `messages:cleared` | `MessagesHost` mutations | context → `devframe:messages:updated`; the messages devframe | entry / entry / id / — |
 | `commands:registered` / `commands:unregistered` | `CommandsHost` register / update / unregister | context → `devframe:commands` shared state | entry / id |
 
-`docks:panel:state` emits `connected` with the first reported `open` value, `changed` when that value changes, and `disconnected` when the reporting RPC connection closes. Its numeric `sessionId` identifies that connection for the lifetime of the Node process. A reload or reconnect receives a new id.
+`docks:panel:state` emits `connected` with the first reported panel snapshot, `changed` when its state or selected dock changes, and `disconnected` when the reporting RPC connection closes. A snapshot contains `state: 'open' | 'closed' | 'hidden'` and an optional `selectedDockId`. Its numeric `sessionId` identifies that connection for the lifetime of the Node process. A reload or reconnect receives a new id.
 
 ### Server RPC methods — client → server
 
 | Method | Signature | Purpose |
 |---|---|---|
 | `hub:docks:activate` | `({ dockId, params? }) => void` | Ask the hub UI provider to switch its active dock — see [Deep Linking](/guide/deep-linking). |
-| `hub:docks:panel:state` | `(open) => void` | Report this viewer connection's current dock-panel state. |
+| `hub:docks:panel:state` | `(panelState: DevframeDockPanelState) => void` | Report this viewer connection's current dock-panel state and selected dock. |
 | `hub:commands:execute` | `(id, ...args) => unknown` | Invoke a registered server command by id. |
 | `hub:messages:add` | `(input) => DevframeMessageEntry` | Add a message to the feed (marked `from: 'browser'`). |
 | `hub:messages:update` | `(id, patch) => DevframeMessageEntry \| undefined` | Patch a message by id. |

packages/hub-ui/src/client/embedded/index.ts

@@ -1,6 +1,7 @@
 import type { DockPanelStorage, DockSessionStorage } from '@devframes/hub/client'
 import { getDevframeRpcClient, setDevframeClientContext } from '@devframes/hub/client'
 import { useLocalStorage, useSessionStorage } from '@vueuse/core'
+import { ref } from 'vue'
 import { applyPrimaryColor, setBranding } from '../state/branding'
 import { DEFAULT_DOCK_PANEL_STORE, DEFAULT_DOCK_SESSION_STORE } from '../state/docks'
 import { setupEmbeddedVisibility } from './visibility'
@@ -74,8 +75,9 @@ async function mountDock(): Promise<void> {
   // carried by the connection we just established above.
   const branding = setBranding(rpc.connectionMeta.configs?.ui?.branding || {})
 
+  const panelVisible = ref<boolean>()
   const { createDocksContext } = await import('../state/context')
-  const context = await createDocksContext('embedded', rpc, state, session)
+  const context = await createDocksContext('embedded', rpc, state, session, panelVisible)
   setDevframeClientContext(context)
 
   const { DockEmbedded } = await import('../components/DockEmbedded')
@@ -97,8 +99,12 @@ async function mountDock(): Promise<void> {
       show: () => {
         if (dockEl && !dockEl.isConnected)
           document.body.appendChild(dockEl)
+        panelVisible.value = true
+      },
+      hide: () => {
+        dockEl?.remove()
+        panelVisible.value = false
       },
-      hide: () => dockEl?.remove(),
     },
   )
 }

packages/hub-ui/src/client/embedded/visibility.test.ts

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { HUB_UI_HIDE_EVENT } from '../constants'
+import { setupEmbeddedVisibility } from './visibility'
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('setupEmbeddedVisibility', () => {
+  it('reports the initial hidden state and later reveal and conceal transitions', () => {
+    expect.assertions(5)
+
+    const listeners = new Map<string, EventListener>()
+    vi.stubGlobal('window', {
+      addEventListener: vi.fn((type: string, listener: EventListener) => {
+        listeners.set(type, listener)
+      }),
+    })
+    const show = vi.fn()
+    const hide = vi.fn()
+
+    setupEmbeddedVisibility('hidden', 'Devframe', { show, hide })
+
+    expect(hide).toHaveBeenCalledOnce()
+    expect(show).not.toHaveBeenCalled()
+
+    const preventDefault = vi.fn()
+    listeners.get('keydown')!({
+      shiftKey: true,
+      altKey: true,
+      ctrlKey: false,
+      metaKey: false,
+      code: 'KeyD',
+      preventDefault,
+    } as unknown as KeyboardEvent)
+    expect(preventDefault).toHaveBeenCalledOnce()
+    expect(show).toHaveBeenCalledOnce()
+
+    listeners.get(HUB_UI_HIDE_EVENT)!({} as Event)
+    expect(hide).toHaveBeenCalledTimes(2)
+  })
+})

packages/hub-ui/src/client/embedded/visibility.ts

@@ -95,10 +95,14 @@ export function setupEmbeddedVisibility(
     handlers.hide()
   }
 
-  if (shown)
+  if (shown) {
     handlers.show()
-  else if (mode === 'passive')
-    printHint(label)
+  }
+  else {
+    handlers.hide()
+    if (mode === 'passive')
+      printHint(label)
+  }
 
   // Shift+Alt+D toggles the dock — the always-available "summon" chord.
   window.addEventListener('keydown', (e) => {

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

@@ -75,36 +75,54 @@ async function flushRestore(): Promise<void> {
 }
 
 describe('createDocksContext', () => {
-  it('reports the restored panel state and later open-state transitions', async () => {
-    expect.assertions(4)
+  it('reports restored, selected, hidden, and closed panel snapshots', async () => {
+    expect.assertions(8)
 
     const { rpc, sharedStates, trust } = createStubRpc()
+    const panelVisible = ref<boolean>()
     const session = ref<DockSessionStorage>({
       open: true,
       selectedDockId: 'git',
       selectedDockRoute: null,
     })
-    await createDocksContext('embedded', rpc, undefined, session)
+    await createDocksContext('embedded', rpc, undefined, session, panelVisible)
 
     trust()
     sharedStates.get('devframe:docks')!.push([gitEntry])
     sharedStates.get('devframe:dock-renderers')!.push({})
     await flushRestore()
+    expect(rpc.call).not.toHaveBeenCalled()
+
+    panelVisible.value = true
+    await nextTick()
     await vi.waitFor(() => {
       if (vi.mocked(rpc.call).mock.calls.length !== 1)
         throw new Error('waiting for the restored panel state report')
     })
-
     expect(rpc.call).toHaveBeenCalledTimes(1)
-    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, true)
+    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'open', selectedDockId: 'git' })
+
+    session.value.selectedDockId = '~settings'
+    await nextTick()
+    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'open', selectedDockId: '~settings' })
+
+    panelVisible.value = false
+    await nextTick()
+    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'hidden', selectedDockId: '~settings' })
 
     session.value.open = false
+    session.value.selectedDockId = null
+    await nextTick()
+    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'hidden' })
+
+    panelVisible.value = true
     await nextTick()
-    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, false)
+    expect(rpc.call).toHaveBeenLastCalledWith(HUB_EVENTS.rpc.docksPanelState, { state: 'closed' })
 
+    panelVisible.value = true
     session.value.open = false
     await nextTick()
-    expect(rpc.call).toHaveBeenCalledTimes(2)
+    expect(rpc.call).toHaveBeenCalledTimes(5)
   })
 
   it('mounts a restored dock once after all initial server state arrives', async () => {

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

@@ -23,6 +23,7 @@ export async function createDocksContext(
   rpc: DevframeRpcClient,
   panelStore?: Ref<DockPanelStorage>,
   sessionStore?: Ref<DockSessionStorage>,
+  panelVisible: Ref<boolean | undefined> = ref(true),
 ): Promise<DocksContext> {
   if (docksContextByRpc.has(rpc)) {
     return docksContextByRpc.get(rpc)!
@@ -666,8 +667,15 @@ export async function createDocksContext(
   const reportPanelStateAfterInitialization = async (): Promise<void> => {
     await restoreAfterInitialization()
     watch(
-      () => sessionStore.value.open,
-      open => void reportDockPanelState(rpc, open).catch(() => {}),
+      [panelVisible, () => sessionStore.value.open, selectedDockId],
+      ([visible, open, currentSelectedDockId]) => {
+        if (visible === undefined)
+          return
+        void reportDockPanelState(rpc, {
+          state: visible ? (open ? 'open' : 'closed') : 'hidden',
+          ...(currentSelectedDockId !== null ? { selectedDockId: currentSelectedDockId } : {}),
+        }).catch(() => {})
+      },
       { immediate: true },
     )
   }

packages/hub/src/client/__tests__/host.test.ts

@@ -68,23 +68,32 @@ function groupEntry(id: string, extra?: Record<string, unknown>): DevframeDockEn
 }
 
 describe('createDevframeClientRuntime', () => {
-  it('reports its initial panel state and later open-state assignments', async () => {
-    expect.assertions(3)
+  it('reports complete panel snapshots and coalesces related session changes', async () => {
+    expect.assertions(4)
 
-    const { rpc, calls } = createStubRpc()
+    const { rpc, calls, states } = createStubRpc()
     const host = await createDevframeClientRuntime({ rpc, clientType: 'embedded' })
 
-    expect(calls).toEqual([[HUB_EVENTS.rpc.docksPanelState, false]])
+    expect(calls).toEqual([[HUB_EVENTS.rpc.docksPanelState, { state: 'closed' }]])
 
+    states.get('devframe:docks')!.push([iframeEntry('one')])
     host.context.panel.session.open = true
-    host.context.panel.session.open = true
+    const switched = host.context.docks.switchEntry('one')
+    await switched
     expect(calls).toEqual([
-      [HUB_EVENTS.rpc.docksPanelState, false],
-      [HUB_EVENTS.rpc.docksPanelState, true],
+      [HUB_EVENTS.rpc.docksPanelState, { state: 'closed' }],
+      [HUB_EVENTS.rpc.docksPanelState, { state: 'open', selectedDockId: 'one' }],
     ])
 
+    host.context.panel.session.open = true
+    host.context.panel.session.selectedDockId = 'one'
+    await Promise.resolve()
+    expect(calls).toHaveLength(2)
+
     host.context.panel.session.open = false
-    expect(calls.at(-1)).toEqual([HUB_EVENTS.rpc.docksPanelState, false])
+    const cleared = host.context.docks.switchEntry(null)
+    await cleared
+    expect(calls.at(-1)).toEqual([HUB_EVENTS.rpc.docksPanelState, { state: 'closed' }])
     host.dispose()
   })
 

packages/hub/src/client/__tests__/panel-state.test.ts

@@ -0,0 +1,20 @@
+import type { DevframeRpcClient } from 'devframe/client'
+import { describe, expect, it, vi } from 'vitest'
+import { HUB_EVENTS } from '../../events'
+import { reportDockPanelState } from '../panel-state'
+
+describe('reportDockPanelState', () => {
+  it('reports the complete panel snapshot through the hub RPC', async () => {
+    expect.assertions(1)
+
+    const call = vi.fn(async () => {})
+    const rpc = { call } as unknown as DevframeRpcClient
+
+    await reportDockPanelState(rpc, { state: 'open', selectedDockId: 'git' })
+
+    expect(call).toHaveBeenCalledWith(
+      HUB_EVENTS.rpc.docksPanelState,
+      { state: 'open', selectedDockId: 'git' },
+    )
+  })
+})

packages/hub/src/client/host.ts

@@ -20,6 +20,7 @@ import type {
   DockClientType,
   DockEntryState,
   DocksEntriesContext,
+  DockSessionStorage,
   DocksPanelContext,
   WhenClauseContext,
 } from './docks'
@@ -125,6 +126,7 @@ export async function createDevframeClientRuntime(
 ): Promise<DevframeClientRuntime> {
   const clientType: DockClientType = options.clientType ?? 'standalone'
   const rpc = options.rpc ?? await connectDevframe(options.connect)
+  let disposed = false
   // Set by createRenderersContext(); teardown disposes every live mount.
   let mountedRenderers: Set<() => void> | undefined
 
@@ -155,10 +157,24 @@ export async function createDevframeClientRuntime(
     ...options.categoryOrder,
   }
 
-  const sendPanelState = (open: boolean): void => {
-    void reportDockPanelState(rpc, open).catch(() => {})
+  const reportPanelState = (session: DockSessionStorage): void => {
+    void reportDockPanelState(rpc, {
+      state: session.open ? 'open' : 'closed',
+      ...(session.selectedDockId !== null ? { selectedDockId: session.selectedDockId } : {}),
+    }).catch(() => {})
   }
-  const panel = createPanelContext(clientType, sendPanelState)
+  let panelStateReportPending = false
+  const schedulePanelStateReport = (session: DockSessionStorage): void => {
+    if (panelStateReportPending)
+      return
+    panelStateReportPending = true
+    queueMicrotask(() => {
+      panelStateReportPending = false
+      if (!disposed)
+        reportPanelState(session)
+    })
+  }
+  const panel = createPanelContext(clientType, schedulePanelStateReport)
   const docks = createDocksContext()
   const commands = createCommandsContext()
   const renderers = createRenderersContext()
@@ -229,7 +245,7 @@ export async function createDevframeClientRuntime(
     )
   }
   setDevframeClientContext(context)
-  sendPanelState(panel.session.open)
+  reportPanelState(panel.session)
 
   const loadedScripts = new Set<string>()
   if (loadScriptsEnabled) {
@@ -240,6 +256,7 @@ export async function createDevframeClientRuntime(
   return {
     context,
     dispose() {
+      disposed = true
       for (const off of disposers.splice(0)) off()
       for (const disposeAdapter of frameNavAdapters.values()) disposeAdapter()
       frameNavAdapters.clear()
@@ -556,7 +573,7 @@ export async function createDevframeClientRuntime(
 
 function createPanelContext(
   clientType: DockClientType,
-  onOpenChange: (open: boolean) => void,
+  onSessionChange: (session: DockSessionStorage) => void,
 ): DocksPanelContext {
   const store: DocksPanelContext['store'] = {
     mode: 'edge',
@@ -568,6 +585,7 @@ function createPanelContext(
     inactiveTimeout: 0,
   }
   let open = clientType === 'standalone'
+  let selectedDockId: string | null = null
   const session: DocksPanelContext['session'] = {
     get open() {
       return open
@@ -576,9 +594,17 @@ function createPanelContext(
       if (nextOpen === open)
         return
       open = nextOpen
-      onOpenChange(open)
+      onSessionChange(session)
+    },
+    get selectedDockId() {
+      return selectedDockId
+    },
+    set selectedDockId(nextSelectedDockId) {
+      if (nextSelectedDockId === selectedDockId)
+        return
+      selectedDockId = nextSelectedDockId
+      onSessionChange(session)
     },
-    selectedDockId: null,
     selectedDockRoute: null,
   }
   return {

packages/hub/src/client/panel-state.ts

@@ -1,10 +1,11 @@
 import type { DevframeRpcClient } from 'devframe/client'
+import type { DevframeDockPanelState } from '../types/docks'
 import { HUB_EVENTS } from '../events'
 
 /** Report this RPC connection's current dock-panel state to the hub. */
 export async function reportDockPanelState(
   rpc: DevframeRpcClient,
-  open: boolean,
+  panelState: DevframeDockPanelState,
 ): Promise<void> {
-  await rpc.call(HUB_EVENTS.rpc.docksPanelState, open)
+  await rpc.call(HUB_EVENTS.rpc.docksPanelState, panelState)
 }