feat(hub): add dock grouping (groupId + type:'group')

antfubot · antfubot · commit c3c24f420039 · 2026-06-10T05:24:11.000Z
Let a hub collapse related dock entries under a single dock-bar button
when many integrations share one UI. Grouping only makes sense once a hub
combines tools, so the data model and host validation land here while the
hub continues to ship no UI — downstream kits derive the visual collapse
from the existing 'devframe:docks' shared state.

- Add an optional `groupId` pointer to every dock entry (membership, not
  containment) and a new `type:'group'` entry (`DevframeViewGroup`) with an
  optional `defaultChildId`. This is a flat pointer model: members stay
  independently-registered top-level entries, so register/update/values,
  the views map, settings, and shared-state sync all keep working unchanged.
- Validate in the host: reject self-grouping (DF8103) and nested groups
  (DF8104, one level only). Orphan members whose group is unregistered are
  tolerated and render as normal top-level entries, keeping registration
  order-independent.
diff --git a/docs/errors/DF8103.md b/docs/errors/DF8103.md
@@ -0,0 +1,22 @@
+---
+outline: deep
+---
+
+# DF8103: Dock Entry Cannot Group Itself
+
+## Message
+
+> Dock entry "`{id}`" cannot set groupId to its own id
+
+## Cause
+
+A dock entry registered with `groupId` pointing at its own `id`. `groupId` is a pointer to a *different* group entry the entry belongs to, so a self-reference would describe an entry that collapses under itself.
+
+## Fix
+
+- Point `groupId` at the `id` of a `type: 'group'` entry, such as `groupId: 'nuxt'`.
+- Omit `groupId` entirely to keep the entry as a normal top-level dock entry.
+
+## Source
+
+- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts) — `DevframeDocksHost.register()` and `update()` throw this when `view.groupId === view.id`.
diff --git a/docs/errors/DF8104.md b/docs/errors/DF8104.md
@@ -0,0 +1,22 @@
+---
+outline: deep
+---
+
+# DF8104: Nested Dock Groups Unsupported
+
+## Message
+
+> Dock group "`{id}`" cannot itself belong to a group (nested groups are unsupported)
+
+## Cause
+
+A `type: 'group'` entry was registered with `groupId` set. Dock grouping is one level deep: a group collects member entries, but a group cannot itself be a member of another group.
+
+## Fix
+
+- Remove `groupId` from the group entry so it stays a top-level dock-bar button.
+- Keep members one level under their group; place each member's `groupId` on the leaf entry, not on another group.
+
+## Source
+
+- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts) — `DevframeDocksHost.register()` and `update()` throw this when `view.type === 'group'` and `view.groupId` is set.
diff --git a/docs/guide/hub.md b/docs/guide/hub.md
@@ -15,7 +15,7 @@ A hub-aware node context (`DevframeHubContext`) extends `DevframeNodeContext` wi
 
 | Subsystem | Surface | Purpose |
 |---|---|---|
-| `ctx.docks` | `register / update / values` | Multi-tool dock entries (iframes, launchers, json-render, custom-render). |
+| `ctx.docks` | `register / update / values` | Multi-tool dock entries (iframes, launchers, json-render, custom-render) and groups that collapse them under one button. |
 | `ctx.terminals` | `register / startChildProcess` | Aggregate terminal sessions, stream output over a well-known channel. |
 | `ctx.messages` | `add / update / remove / clear` | Server-side toast/notification queue (FIFO, capped at 1000). |
 | `ctx.commands` | `register / execute / list` | Hierarchical command palette with keybindings and `when` clauses. |
@@ -43,6 +43,34 @@ await mountDevframe(ctx, myDevframe)
 
 Framework kits typically wrap this in a plugin shell. `@vitejs/devtools-kit`'s `createPluginFromDevframe` returns a Vite `Plugin` whose `devtools.setup` calls into `mountDevframe`.
 
+## Grouping dock entries
+
+When a hub combines many integrations, related dock entries can collapse under a single dock-bar button. A `type: 'group'` entry is that button; any entry pointing its `groupId` at the group's `id` becomes a member.
+
+```ts
+ctx.docks.register({
+  type: 'group',
+  id: 'nuxt',
+  title: 'Nuxt',
+  icon: 'logos:nuxt-icon',
+  category: 'framework',
+  defaultChildId: 'nuxt:overview', // optional; popover-only when omitted
+})
+
+ctx.docks.register({
+  type: 'iframe',
+  id: 'nuxt:overview',
+  title: 'Overview',
+  icon: 'ph:gauge-duotone',
+  url: '/__nuxt-overview/',
+  groupId: 'nuxt', // joins the group above
+})
+```
+
+`groupId` lives on every entry kind, so iframes, launchers, json-render panels, and custom-render views all join groups the same way. The group and its members stay independent top-level entries in `devframe:docks`; a downstream UI derives the visual collapse by matching each member's `groupId` to the group's `id` and renders members in a popover or sub-navigation. `defaultChildId` names the member opened when the group button is activated.
+
+Grouping is one level deep: members join a group, and a group is always a top-level button. A member whose group is never registered renders as a normal top-level entry, so registration order is free.
+
 ## The protocol — what the UI sees
 
 A hub-aware UI doesn't import any hub classes; it reads three shared-state keys and one RPC method:
diff --git a/packages/hub/src/node/__tests__/host-docks.test.ts b/packages/hub/src/node/__tests__/host-docks.test.ts
@@ -76,3 +76,102 @@ describe('devframeDockHost remote URL enrichment', () => {
     expect(parseRemoteConnection(url)?.websocket).toBe('ws://localhost:4173')
   })
 })
+
+describe('devframeDockHost grouping', () => {
+  it('registers a group entry: stored, projected, and emitted', () => {
+    const host = new DevframeDocksHost(createContext())
+    const emitted: string[] = []
+    host.events.on('dock:entry:updated', entry => emitted.push(entry.id))
+
+    host.register({
+      type: 'group',
+      id: 'nuxt',
+      title: 'Nuxt',
+      icon: 'logos:nuxt-icon',
+      category: 'framework',
+      defaultChildId: 'nuxt:overview',
+    })
+
+    expect(host.views.has('nuxt')).toBe(true)
+    expect(emitted).toEqual(['nuxt'])
+    const entry = host.values({ includeBuiltin: false })[0]
+    expect(entry.type).toBe('group')
+    expect(entry).toMatchObject({ id: 'nuxt', defaultChildId: 'nuxt:overview' })
+  })
+
+  it('round-trips a member groupId through values()', () => {
+    const host = new DevframeDocksHost(createContext())
+    host.register({
+      type: 'iframe',
+      id: 'nuxt:overview',
+      title: 'Overview',
+      icon: 'ph:gauge-duotone',
+      url: '/__nuxt-overview/',
+      groupId: 'nuxt',
+    })
+
+    const entry = host.values({ includeBuiltin: false })[0]
+    expect(entry.groupId).toBe('nuxt')
+  })
+
+  it('tolerates a member registered before its group (orphan tolerance)', () => {
+    const host = new DevframeDocksHost(createContext())
+    host.register({
+      type: 'iframe',
+      id: 'nuxt:overview',
+      title: 'Overview',
+      icon: 'ph:gauge-duotone',
+      url: '/__nuxt-overview/',
+      groupId: 'nuxt',
+    })
+    host.register({
+      type: 'group',
+      id: 'nuxt',
+      title: 'Nuxt',
+      icon: 'logos:nuxt-icon',
+    })
+
+    const ids = host.values({ includeBuiltin: false }).map(entry => entry.id)
+    expect(ids).toEqual(['nuxt:overview', 'nuxt'])
+  })
+
+  it('rejects an entry that groups itself (DF8103)', () => {
+    const host = new DevframeDocksHost(createContext())
+    expect(() => host.register({
+      type: 'iframe',
+      id: 'self',
+      title: 'Self',
+      icon: 'ph:gauge-duotone',
+      url: '/__self/',
+      groupId: 'self',
+    })).toThrow('cannot set groupId to its own id')
+  })
+
+  it('rejects a nested group (DF8104)', () => {
+    const host = new DevframeDocksHost(createContext())
+    expect(() => host.register({
+      type: 'group',
+      id: 'child-group',
+      title: 'Child Group',
+      icon: 'logos:nuxt-icon',
+      groupId: 'parent-group',
+    })).toThrow('nested groups are unsupported')
+  })
+
+  it('updates a group entry while preserving type and rejecting id change', () => {
+    const host = new DevframeDocksHost(createContext())
+    const handle = host.register({
+      type: 'group',
+      id: 'nuxt',
+      title: 'Nuxt',
+      icon: 'logos:nuxt-icon',
+    })
+
+    handle.update({ title: 'Nuxt DevTools' })
+    const entry = host.views.get('nuxt')!
+    expect(entry.type).toBe('group')
+    expect(entry.title).toBe('Nuxt DevTools')
+
+    expect(() => handle.update({ id: 'other' })).toThrow('Cannot change the id of a dock')
+  })
+})
diff --git a/packages/hub/src/node/diagnostics.ts b/packages/hub/src/node/diagnostics.ts
@@ -24,6 +24,14 @@ export const diagnostics = defineDiagnostics({
     DF8102: {
       why: (p: { id: string }) => `Dock with id "${p.id}" is not registered. Use register() to add new docks.`,
     },
+    DF8103: {
+      why: (p: { id: string }) => `Dock entry "${p.id}" cannot set groupId to its own id`,
+      fix: 'Point groupId at a different group entry, or omit it.',
+    },
+    DF8104: {
+      why: (p: { id: string }) => `Dock group "${p.id}" cannot itself belong to a group (nested groups are unsupported)`,
+      fix: 'Remove groupId from the group entry; nest members one level only.',
+    },
     DF8200: {
       why: (p: { id: string }) => `Terminal session with id "${p.id}" already registered`,
     },
diff --git a/packages/hub/src/node/host-docks.ts b/packages/hub/src/node/host-docks.ts
@@ -179,6 +179,7 @@ export class DevframeDocksHost implements DevframeDocksHostType {
     if (this.views.has(view.id) && !force) {
       throw diagnostics.DF8100({ id: view.id })
     }
+    this.validateGroupMembership(view)
     this.prepareRemoteRegistration(view)
     this.views.set(view.id, view)
     this.events.emit('dock:entry:updated', view)
@@ -197,11 +198,21 @@ export class DevframeDocksHost implements DevframeDocksHostType {
     if (!this.views.has(view.id)) {
       throw diagnostics.DF8102({ id: view.id })
     }
+    this.validateGroupMembership(view)
     this.prepareRemoteRegistration(view)
     this.views.set(view.id, view)
     this.events.emit('dock:entry:updated', view)
   }
 
+  private validateGroupMembership(view: DevframeDockUserEntry): void {
+    if (view.groupId === undefined)
+      return
+    if (view.groupId === view.id)
+      throw diagnostics.DF8103({ id: view.id })
+    if (view.type === 'group')
+      throw diagnostics.DF8104({ id: view.id })
+  }
+
   private prepareRemoteRegistration(view: DevframeDockUserEntry): void {
     const internal = getInternalContext(this.context as DevframeNodeContext)
     // Always revoke any previously allocated token for this dock id — covers
diff --git a/packages/hub/src/types/docks.ts b/packages/hub/src/types/docks.ts
@@ -58,6 +58,19 @@ export interface DevframeDockEntryBase {
    * Badge text to display on the dock icon (e.g., unread count)
    */
   badge?: string
+  /**
+   * Id of the group this entry belongs to. When set, hosts collapse this entry
+   * under the matching group's button instead of showing it directly on the
+   * dock bar.
+   *
+   * This is a flat pointer — membership, not containment. The entry stays an
+   * independently-registered, top-level entry; only its rendering is grouped
+   * downstream. If the referenced group is never registered, the entry renders
+   * as a normal top-level entry (orphan tolerance).
+   *
+   * @see {@link DevframeViewGroup}
+   */
+  groupId?: string
 }
 
 export interface ClientScriptEntry {
@@ -169,7 +182,29 @@ export interface DevframeViewJsonRender extends DevframeDockEntryBase {
   ui: JsonRenderer
 }
 
-export type DevframeDockUserEntry = DevframeViewIframe | DevframeViewAction | DevframeViewCustomRender | DevframeViewLauncher | DevframeViewJsonRender
+/**
+ * A dock group: a single dock-bar button that collapses every entry whose
+ * {@link DevframeDockEntryBase.groupId} matches this group's `id`.
+ *
+ * A group carries its own `title`/`icon`/`category`/`defaultOrder`/`when`
+ * (inherited from {@link DevframeDockEntryBase}) and has no view payload of its
+ * own — hosts render its members in a popover / sub-navigation. It flows
+ * through the same `register`/`update`/`values` machinery as every other entry,
+ * keyed by `id`.
+ *
+ * Grouping is one level deep: a group entry must not itself set `groupId`.
+ */
+export interface DevframeViewGroup extends DevframeDockEntryBase {
+  type: 'group'
+  /**
+   * Member id auto-opened when the group button is activated. When unset,
+   * activating the group only reveals its members (popover-only); no view
+   * opens until a member is chosen.
+   */
+  defaultChildId?: string
+}
+
+export type DevframeDockUserEntry = DevframeViewIframe | DevframeViewAction | DevframeViewCustomRender | DevframeViewLauncher | DevframeViewJsonRender | DevframeViewGroup
 
 export type DevframeDockEntry = DevframeDockUserEntry | DevframeViewBuiltin
 
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
@@ -65,6 +65,7 @@ export { DevframeTerminalStatus }
 export { DevframeViewAction }
 export { DevframeViewBuiltin }
 export { DevframeViewCustomRender }
+export { DevframeViewGroup }
 export { DevframeViewHost }
 export { DevframeViewIframe }
 export { DevframeViewJsonRender }
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts
@@ -40,6 +40,7 @@ export declare class DevframeDocksHost implements DevframeDocksHost$1 {
     update: (_: Partial<T>) => void;
   };
   update(_: DevframeDockUserEntry): void;
+  private validateGroupMembership;
   private prepareRemoteRegistration;
 }
 export declare class DevframeMessagesHost implements DevframeMessagesHost$1 {
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.js
@@ -27,6 +27,7 @@ export class DevframeDocksHost {
   resolveDevServerOrigin() {}
   register(_, _) {}
   update(_) {}
+  validateGroupMembership(_) {}
   prepareRemoteRegistration(_) {}
 }
 export class DevframeMessagesHost {
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
@@ -51,6 +51,7 @@ export { DevframeTerminalStatus }
 export { DevframeViewAction }
 export { DevframeViewBuiltin }
 export { DevframeViewCustomRender }
+export { DevframeViewGroup }
 export { DevframeViewHost }
 export { DevframeViewIframe }
 export { DevframeViewJsonRender }

Original file line number	Diff line number	Diff line change
`@@ -40,6 +40,7 @@ export declare class DevframeDocksHost implements DevframeDocksHost$1 {`
`40`	`40`	`update: (_: Partial<T>) => void;`
`41`	`41`	`};`
`42`	`42`	`update(_: DevframeDockUserEntry): void;`
	`43`	`+ private validateGroupMembership;`
`43`	`44`	`private prepareRemoteRegistration;`
`44`	`45`	`}`
`45`	`46`	`export declare class DevframeMessagesHost implements DevframeMessagesHost$1 {`
Original file line number	Diff line number	Diff line change
`@@ -27,6 +27,7 @@ export class DevframeDocksHost {`
`27`	`27`	`resolveDevServerOrigin() {}`
`28`	`28`	`register(_, _) {}`
`29`	`29`	`update(_) {}`
	`30`	`+ validateGroupMembership(_) {}`
`30`	`31`	`prepareRemoteRegistration(_) {}`
`31`	`32`	`}`
`32`	`33`	`export class DevframeMessagesHost {`