devframes · antfu · Aug 6, 2026 · Aug 6, 2026
diff --git a/alias.ts b/alias.ts
@@ -49,6 +49,7 @@ export const alias = {
   '@devframes/hub/node': r('hub/src/node/index.ts'),
   '@devframes/hub/types': r('hub/src/types/index.ts'),
   '@devframes/hub': r('hub/src/index.ts'),
+  '@devframes/hub-ui': r('hub-ui/src/index.ts'),
   '@devframes/nuxt/runtime/plugin.client': r('nuxt/src/runtime/plugin.client.ts'),
   '@devframes/nuxt': r('nuxt/src/index.ts'),
   '@devframes/next/client': r('next/src/client.tsx'),

diff --git a/packages/hub-ui/.storybook/main.ts b/packages/hub-ui/.storybook/main.ts
@@ -0,0 +1,25 @@
+import type { StorybookConfig } from '@storybook/vue3-vite'
+import vue from '@vitejs/plugin-vue'
+import UnoCSS from 'unocss/vite'
+import { mergeConfig } from 'vite'
+import { alias } from '../../../alias'
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: ['@storybook/addon-docs'],
+  framework: {
+    name: '@storybook/vue3-vite',
+    options: {},
+  },
+  docs: {},
+  async viteFinal(config) {
+    return mergeConfig(config, {
+      resolve: { alias },
+      plugins: [vue(), UnoCSS()],
+      // Dev tool reached from arbitrary hostnames (LAN IPs, tunnels,
+      // tailnets), e.g. when iframed by the storybook-hub example.
+      server: { allowedHosts: true },
+    })
+  },
+}
+export default config
diff --git a/packages/hub-ui/.storybook/preview.ts b/packages/hub-ui/.storybook/preview.ts
@@ -0,0 +1,48 @@
+import type { Decorator, Preview } from '@storybook/vue3-vite'
+import 'virtual:uno.css'
+import '@antfu/design/styles.css'
+import '../src/client/style.css'
+
+// Drive the shared `@antfu/design` tokens off the toolbar theme toggle: dark mode
+// is the `.dark` class on `<html>`, and the canvas takes the semantic
+// `bg-base`/`color-base` surface — matching every other devframe surface.
+function applyTheme(theme: string): void {
+  document.documentElement.classList.toggle('dark', theme !== 'light')
+  document.body.classList.add('bg-base', 'color-base', 'font-sans')
+}
+
+const withTheme: Decorator = (story, context) => {
+  applyTheme(context.globals.theme ?? 'dark')
+  return { components: { story }, template: '<story />' }
+}
+
+const preview: Preview = {
+  parameters: {
+    layout: 'fullscreen',
+    controls: {
+      expanded: true,
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+  globalTypes: {
+    theme: {
+      description: 'Color theme',
+      defaultValue: 'dark',
+      toolbar: {
+        title: 'Theme',
+        icon: 'contrast',
+        items: [
+          { value: 'light', title: 'Light', icon: 'sun' },
+          { value: 'dark', title: 'Dark', icon: 'moon' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
+  decorators: [withTheme],
+}
+
+export default preview
diff --git a/packages/hub-ui/package.json b/packages/hub-ui/package.json
@@ -0,0 +1,70 @@
+{
+  "name": "@devframes/hub-ui",
+  "type": "module",
+  "version": "0.8.1",
+  "description": "Reference UI for @devframes/hub \u2014 the floating dock and standalone viewer filling the hub's ui slot.",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/devframes/devframe#readme",
+  "repository": {
+    "directory": "packages/hub-ui",
+    "type": "git",
+    "url": "git+https://github.com/devframes/devframe.git"
+  },
+  "bugs": "https://github.com/devframes/devframe/issues",
+  "keywords": [
+    "devtools",
+    "devframe",
+    "hub",
+    "dock",
+    "ui"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "pnpm run build:css && pnpm run build:node && pnpm run build:embedded && pnpm run build:standalone",
+    "build:css": "tsx scripts/build-css.ts",
+    "build:node": "tsdown",
+    "build:embedded": "vite build --config vite.embedded.config.ts",
+    "build:standalone": "vite build --config src/client/standalone/vite.config.ts",
+    "typecheck": "tsc --noEmit",
+    "prepack": "pnpm build",
+    "storybook": "storybook dev -p 6014",
+    "build-storybook": "storybook build"
+  },
+  "peerDependencies": {
+    "@devframes/hub": "workspace:*",
+    "devframe": "workspace:*"
+  },
+  "devDependencies": {
+    "@devframes/hub": "workspace:*",
+    "@iconify-json/ph": "catalog:frontend",
+    "@json-render/core": "catalog:deps",
+    "@json-render/vue": "catalog:frontend",
+    "@storybook/addon-docs": "catalog:storybook",
+    "@storybook/vue3-vite": "catalog:storybook",
+    "@types/node": "catalog:types",
+    "@unocss/reset": "catalog:frontend",
+    "@vitejs/plugin-vue": "catalog:build",
+    "@vueuse/core": "catalog:frontend",
+    "devframe": "workspace:*",
+    "dompurify": "catalog:frontend",
+    "fuse.js": "catalog:frontend",
+    "iframe-pane": "catalog:frontend",
+    "magic-string": "catalog:build",
+    "storybook": "catalog:storybook",
+    "tinyglobby": "catalog:deps",
+    "tsdown": "catalog:build",
+    "tsx": "catalog:build",
+    "unocss": "catalog:frontend",
+    "vite": "catalog:build",
+    "vue": "catalog:frontend"
+  }
+}
diff --git a/packages/hub-ui/scripts/build-css.ts b/packages/hub-ui/scripts/build-css.ts
@@ -0,0 +1,63 @@
+import fs from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { colors as c } from 'devframe/utils/colors'
+import MagicString from 'magic-string'
+import { glob } from 'tinyglobby'
+import { createGenerator } from 'unocss'
+import config from '../uno.config'
+
+// Compile the components' UnoCSS output ahead of time into a plain string
+// module (`src/client/.generated/css.ts`) that `defineCustomElement` adopts
+// into each shadow root — the dock stays fully styled inside any host page
+// without a global stylesheet, and the host page's own styles can't leak in.
+const SRC_DIR = fileURLToPath(new URL('../src/client', import.meta.url))
+const GLOBS = ['components/**/*.{ts,vue}', 'state/**/*.ts', 'embedded/**/*.ts', 'standalone/**/*.{ts,html}']
+// Story-only utility classes must not leak into the shipped stylesheet.
+const IGNORE = ['**/*.stories.*', '**/__tests__/**']
+const USER_STYLE = join(SRC_DIR, 'style.css')
+const GENERATED_CSS = join(SRC_DIR, '.generated/css.ts')
+
+export async function buildCSS(): Promise<void> {
+  const require = createRequire(import.meta.url)
+  const reset = await fs.readFile(require.resolve('@unocss/reset/tailwind.css'), 'utf-8')
+  const files = await glob(GLOBS, {
+    cwd: SRC_DIR,
+    absolute: true,
+    ignore: IGNORE,
+  })
+
+  const generator = await createGenerator(config)
+
+  const tokens = new Set<string>()
+  for (const file of files) {
+    const content = await fs.readFile(file, 'utf-8')
+    await generator.applyExtractors(content, file, tokens)
+  }
+
+  // The hand-written stylesheet may use `--at-apply` — run it through the
+  // configured transformers (directives, variant groups) before merging.
+  const userStyle = new MagicString(await fs.readFile(USER_STYLE, 'utf-8').catch(() => ''))
+  for (const transformer of generator.config.transformers ?? []) {
+    await transformer.transform(userStyle, USER_STYLE, { uno: generator } as any)
+  }
+
+  const unoResult = await generator.generate(tokens)
+  const css = [
+    reset,
+    userStyle.toString(),
+    unoResult.css,
+  ].join('\n')
+
+  await fs.mkdir(join(SRC_DIR, '.generated'), { recursive: true })
+  await fs.writeFile(GENERATED_CSS, [
+    `/* eslint-disable eslint-comments/no-unlimited-disable */`,
+    `/* eslint-disable */`,
+    `export default ${JSON.stringify(String(css))}`,
+    '',
+  ].join('\n'))
+  console.log(`${c.green('✓')} CSS built (${files.length} sources, ${(css.length / 1024).toFixed(1)} kB)`)
+}
+
+await buildCSS()
diff --git a/packages/hub-ui/src/client/.generated/css.ts b/packages/hub-ui/src/client/.generated/css.ts
diff --git a/packages/hub-ui/src/client/components/DockEmbedded.ts b/packages/hub-ui/src/client/components/DockEmbedded.ts
@@ -0,0 +1,17 @@
+import type { DocksContext } from '@devframes/hub/client'
+import type { VueElementConstructor } from 'vue'
+import { defineCustomElement } from 'vue'
+import css from '../.generated/css'
+import Component from './dock/DockEmbedded.vue'
+
+export const DockEmbedded = defineCustomElement(
+  Component,
+  {
+    shadowRoot: true,
+    styles: [css],
+  },
+) as VueElementConstructor<{
+  context: DocksContext
+}>
+
+customElements.define('devframes-dock-embedded', DockEmbedded)
diff --git a/packages/hub-ui/src/client/components/DockStandalone.ts b/packages/hub-ui/src/client/components/DockStandalone.ts
@@ -0,0 +1,18 @@
+import type { DocksContext } from '@devframes/hub/client'
+import type { VueElementConstructor } from 'vue'
+import { defineCustomElement } from 'vue'
+import css from '../.generated/css'
+import Component from './dock/DockStandalone.vue'
+
+export const DockStandalone = defineCustomElement(
+  Component,
+  {
+    shadowRoot: true,
+    styles: [css],
+  },
+) as VueElementConstructor<{
+  context: DocksContext
+}>
+
+if (!customElements.get('devframes-dock-standalone'))
+  customElements.define('devframes-dock-standalone', DockStandalone)
diff --git a/packages/hub-ui/src/client/components/command-palette/CommandPalette.stories.ts b/packages/hub-ui/src/client/components/command-palette/CommandPalette.stories.ts
@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import { defineComponent, h, onMounted } from 'vue'
+import { groupedEntries } from '../../stories/fixtures'
+import { mountWithContext } from '../../stories/story-helpers'
+import CommandPalette from './CommandPalette.vue'
+
+const meta = {
+  title: 'Commands/Palette',
+  component: CommandPalette,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    // Fixed, full-screen overlay — render in an iframe for the docs canvas.
+    docs: {
+      story: { inline: false, height: '480px' },
+      description: {
+        component: 'The ⌘K command palette. Lists client + server commands (and dock navigation), supports fuzzy search and drill-down into grouped commands.',
+      },
+    },
+  },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+/**
+ * The palette opened over the built-in and dock-navigation commands.
+ *
+ * `paletteOpen` is flipped in `onMounted` (not before mount): the palette's
+ * open transition keys off the `show` change, so a value that's already `true`
+ * at mount would leave it stuck at `opacity-0`.
+ */
+export const Open: Story = {
+  render: () => ({
+    setup: () => mountWithContext(
+      { entries: groupedEntries },
+      ctx => h(defineComponent({
+        setup() {
+          onMounted(() => {
+            ctx.commands.paletteOpen = true
+          })
+          return () => h(CommandPalette, { context: ctx })
+        },
+      })),
+    ),
+  }),
+}