Skip to content

feat(hub): let dock entries add items to the context menu - #501

Merged
antfu merged 4 commits into
mainfrom
feat/dock-context-menu
Nov 19, 2026
Merged

antfu merged 4 commits into
mainfrom
feat/dock-context-menu

Conversation

@antfubot

@antfubot antfubot commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

A devframe can now add its own items to the right-click menu of its dock button. Before this change, the menu had only the built-in items (Pin, Hide, Refresh, Edge mode, Popup).

The request came from the Svelte inspector use case. A left-click toggles the inspector, and a right-click shows its settings, so the settings do not need a second dock entry.

A dock entry declares contextMenu. Each item points to a command id, so one handler serves the menu, the palette and keybindings. This is the same pattern that launcher.command uses. The items are serializable, so a node-side devframe can declare them and an out-of-process viewer can show them.

ctx.docks.register({
  type: 'action',
  id: 'inspector',
  toggle: true,
  // ...
  contextMenu: [
    { command: 'inspector:settings', icon: 'ph:gear-duotone' },
    { type: 'separator' },
    { command: 'inspector:hold-mode', checked: holdMode },
  ],
})

Change map

Module Before After
@devframes/hub types No way to add menu items DevframeDockEntryBase.contextMenu: command items (command, args, title, titleLocales, icon, when, checked) and { type: 'separator' }
@devframes/hub-ui DockContextMenu.ts Fixed list of built-in items Entry items first, then a separator, then built-in items. Check items use role="menuitemcheckbox" with aria-checked
@devframes/hub-ui state/dock-context-menu.ts - Pure resolver: hides items whose own when or command when is false, unknown command ids, and client commands with no action. Title and icon default to the command's. Removes separators at the start and end and merges repeated ones
examples/hub-vite - JSON Render dock gets "Ping" and a checkable "Compact Mode" item
Docs - "Dock context menu" section in the hub guide, a note in "Build your own hub UI"

Design notes:

  • args takes only string | number | boolean | null. Shared state wraps entries in Immutable<T>. With unknown[], the storybook typecheck failed, and a recursive JSON type hit "excessively deep". Object args can come later if a tool needs them.
  • checked is a plain boolean that the author patches with docks.update(). The when-context has no custom keys today, so a when-expression could not reflect a tool's own setting.
  • The menu is flat. It does not show the children of a command.
  • Only @devframes/hub-ui renders the items. custom-hub-vite and custom-hub-next have no dock context menu today, so they stay unchanged and still match each other.
  • Icons in the menu now sit in a fixed 18px box, so labels of built-in and custom items line up.

Visual changes

Right-click on the JSON Render dock in examples/hub-vite, after "Compact Mode" was clicked once. The triangle icons are the fallback because the sandbox blocks the Iconify CDN. No "before" capture: on main, the same menu shows only Pin and Hide.

Dock context menu with Ping, Compact Mode (checked), Pin and Hide

Verification

  • pnpm lint, pnpm knip, pnpm build, pnpm typecheck: pass (after the rebase on eaa9f7b5).
  • pnpm test: 1896 passed, 2 failed. The 2 failures are dev.test.ts and initiate.test.ts, which fetch [::1], and the sandbox HTTP proxy blocks that. With the proxy variables unset, both files pass (51 of 51).
  • vitest run packages/hub-ui: 170 of 170, including 5 new tests for the resolver (fallbacks, locales, when, unknown and action-less commands, separator cleanup).
  • Manual check in headless Chrome with examples/hub-vite: the right-click menu shows Ping, a separator, Compact Mode, a separator, Pin, Hide. Clicking Compact Mode ran the server command, and the next open showed checked=true. Label x-offsets are 92px for all four items.
  • Not verified: keyboard opening (Shift+F10) in a real browser. Headless Chrome did not fire contextmenu for it. The existing focus and arrow-key code now also selects menuitemcheckbox.

User prompts

Claude Opus 5.5 in Claude Code (inside Paseo). The user forwarded a community request for devtools to add their own right-click items to the dock icon (Svelte inspector: left-click toggles, right-click opens settings). They asked to implement it as "devframe registers the right-click menu and binds a command to it", using an interview to settle the design: item fields, placement, when behavior, separators, scope, demo and docs. Then they asked for a PR.

This PR was written with an AI agent. The user gave the task and made each design decision in the interview. They have not reviewed the diff yet.

@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
devframe Ready Ready Preview Nov 19, 2026 1:36am UTC

@github-actions

Copy link
Copy Markdown

👁️‍🗨️ Review this pull request with grouped, summarized diffs at:
👉 https://pulls.review/gh/devframes/devframe/501?from=github-actions[bot]

raw result

💭 analyzed by vercel-ai-gateway/anthropic/claude-sonnet-5
🕰️ 2026-11-19 01:35 UTC
🔗 head 75ae123
🤖 automated by pulls.review

{
  "headSha": "75ae12362455e7bb773af07b48957c6adc853817",
  "result": {
    "overallSummary": "Lets a dock entry declare `contextMenu` items that run a command (server or client), so a devframe can add its own right-click actions to its dock button alongside the built-in Pin/Hide/Refresh/Edge/Popup items. Adds the type, a pure resolver that applies `when`/fallback/separator rules, the hub-ui rendering (including checkbox items), a demo in `examples/hub-vite`, and guide docs.",
    "groups": [
      {
        "key": "types",
        "label": "Dock contextMenu types",
        "summary": "Adds the `contextMenu` field to `DevframeDockEntryBase` along with the new serializable `DevframeDockContextMenuItem` (command/separator) types; snapshot files are the generated type-API diffs for this change.",
        "category": "api",
        "filePaths": [
          "packages/hub/src/types/docks.ts",
          "tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts",
          "tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/hub/src/types/docks.ts",
            "text": "`args` is restricted to `string | number | boolean | null` so items stay serializable across the wire for out-of-process viewers."
          }
        ]
      },
      {
        "key": "ui",
        "label": "Render entry menu items",
        "summary": "Implements the dock context menu UI: a pure resolver turns an entry's `contextMenu` into renderable items (applying `when`, fallbacks, separator cleanup), and `DockContextMenu.ts` renders them above the built-in items with checkbox support.",
        "category": "ui",
        "filePaths": [
          "packages/hub-ui/src/client/components/dock/DockContextMenu.ts",
          "packages/hub-ui/src/client/state/dock-context-menu.ts"
        ],
        "critical": true,
        "fileNotes": [
          {
            "path": "packages/hub-ui/src/client/state/dock-context-menu.ts",
            "text": "Pure resolver: drops items whose own or command `when` is false, unknown command ids, and client commands with no `action`; also collapses leading/trailing/duplicate separators."
          }
        ]
      },
      {
        "key": "ui-tests",
        "label": "Resolver tests",
        "summary": "Unit tests for `resolveDockContextMenu` covering fallbacks, locales, `when` filtering, unknown/action-less commands, and separator cleanup.",
        "category": "tests",
        "filePaths": [
          "packages/hub-ui/src/client/state/dock-context-menu.test.ts"
        ]
      },
      {
        "key": "example",
        "label": "Demo in hub-vite example",
        "summary": "Adds a \"Ping\" command item and a checkable \"Compact Mode\" item to the JSON Render dock to demonstrate and manually verify the new feature.",
        "category": "examples",
        "filePaths": [
          "examples/hub-vite/vite.config.ts"
        ]
      },
      {
        "key": "docs",
        "label": "Document dock context menu",
        "summary": "Adds a \"Dock context menu\" guide section explaining the item fields and resolution rules, plus a pointer for custom hub UI authors.",
        "category": "docs",
        "filePaths": [
          "docs/content/1.guide/16.hub.md",
          "docs/content/1.guide/22.build-your-own-hub-ui.md"
        ]
      }
    ],
    "schemaVersion": 1,
    "source": "llm",
    "generatedAt": "2026-11-19T01:35:31.059Z",
    "model": "vercel-ai-gateway/anthropic/claude-sonnet-5",
    "locale": "en"
  }
}

@antfu
antfu merged commit f3ca21e into main Nov 19, 2026
16 checks passed
@antfu
antfu deleted the feat/dock-context-menu branch November 19, 2026 01:40

This branch was successfully deployed

1 active deployment
Preview — 75ae1236 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants