feat: improve hub-ui-onboard

Author: antfu

knip.jsonc

@@ -37,6 +37,11 @@
       // one a standalone, runnable example, not imported by anything else.
       "entry": ["design/*.ts", "skills/devframe/templates/*.ts", "scripts/smoke-bun.ts"]
     },
+    "packages/hub-ui-onboard": {
+      // The playground is a dev-only Vite app (`pnpm play`); its config is
+      // loaded by the Vite CLI, not imported.
+      "entry": ["playground/vite.config.ts"]
+    },
     "docs": {
       // Nuxt auto-registers `app/components` and `app/composables`; the files
       // here shadow same-named pieces of the comark-docs layer (AppHeaderBrand,

packages/hub-ui-onboard/package.json

@@ -32,7 +32,8 @@
     "build:css": "tsx scripts/build-css.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "prepack": "turbo run build --filter=@devframes/hub-ui-onboard"
+    "prepack": "turbo run build --filter=@devframes/hub-ui-onboard",
+    "play": "pnpm run build:css && pnpm -C playground play"
   },
   "dependencies": {
     "nostics": "catalog:deps",

packages/hub-ui-onboard/playground/index.html

@@ -0,0 +1,53 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="color-scheme" content="light dark">
+    <title>hub-ui-onboard playground</title>
+    <style>
+      body { font: 14px/1.5 system-ui, sans-serif; max-width: 36rem; margin: 3rem auto; padding: 0 1rem; }
+      fieldset { margin: 0 0 1rem; border: 1px solid #8884; border-radius: 6px; }
+      button { font: inherit; margin: 0 0.25rem 0.25rem 0; }
+      code { font-family: ui-monospace, monospace; }
+    </style>
+  </head>
+  <body>
+    <h1>hub-ui-onboard</h1>
+    <p>The floating button loads from <code>src/client</code> and talks to a mock <code>__onboard</code> API.</p>
+    <fieldset>
+      <legend>State</legend>
+      <button data-state="idle">idle</button>
+      <button data-state="installing">installing</button>
+      <button data-state="installed">installed</button>
+      <button data-state="error">error</button>
+      <button data-state="idle" data-outcome="error">idle (install fails)</button>
+    </fieldset>
+    <fieldset>
+      <legend>Theme</legend>
+      <button data-theme="light">light</button>
+      <button data-theme="dark">dark</button>
+      <button data-theme="">system</button>
+    </fieldset>
+    <p>Each choice reloads the page. Hide state lives in <code>sessionStorage</code> and resets on reload here.</p>
+    <script type="module">
+      document.addEventListener('click', async (event) => {
+        const el = event.target.closest('button')
+        if (!el)
+          return
+        sessionStorage.clear()
+        if ('theme' in el.dataset) {
+          if (el.dataset.theme)
+            localStorage.setItem('devframes-color-scheme', el.dataset.theme)
+          else
+            localStorage.removeItem('devframes-color-scheme')
+        }
+        else {
+          await fetch(`/__mock/state?state=${el.dataset.state}&outcome=${el.dataset.outcome ?? ''}`)
+        }
+        location.reload()
+      })
+    </script>
+    <script type="module" src="/src/client/index.ts"></script>
+  </body>
+</html>

packages/hub-ui-onboard/playground/package.json

@@ -0,0 +1,6 @@
+{
+  "private": true,
+  "scripts": {
+    "play": "vite dev"
+  }
+}

packages/hub-ui-onboard/playground/vite.config.ts

@@ -0,0 +1,102 @@
+import type { Plugin } from 'vite'
+import type { OnboardingState, OnboardingStatus } from '../src/types'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+import { defaultMessages } from '../src/index'
+
+const root = fileURLToPath(new URL('..', import.meta.url))
+const productName = 'Devframes'
+
+/**
+ * A fake of the `__onboard/*` routes `createOnboarding` serves. The client
+ * resolves them next to its own module (`/src/client/`). The playground page
+ * picks the state through `/__mock/state`; Install runs a timer instead of a
+ * package manager and ends in `installed` or `error`.
+ */
+function mockOnboarding(): Plugin {
+  let state: OnboardingState = 'idle'
+  let outcome: 'installed' | 'error' = 'installed'
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  const status = (): OnboardingStatus => ({
+    state,
+    command: ['pnpm', 'add', '-D', '@devframes/hub', '@devframes/hub-ui'],
+    branding: { productName, primaryColor: '#646cff' },
+    messages: defaultMessages(productName),
+    error: state === 'error' ? { code: 'DF9001', message: 'Mock install failed.' } : undefined,
+  })
+
+  return {
+    name: 'mock-onboarding',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const send = (body: unknown) => {
+          res.setHeader('Content-Type', 'application/json')
+          res.setHeader('Cache-Control', 'no-store')
+          res.end(JSON.stringify(body))
+        }
+        if (url.pathname === '/__mock/state') {
+          clearTimeout(timer)
+          state = (url.searchParams.get('state') ?? 'idle') as OnboardingState
+          outcome = url.searchParams.get('outcome') === 'error' ? 'error' : 'installed'
+          return send({ state, outcome })
+        }
+        if (!url.pathname.startsWith('/src/client/__onboard/'))
+          return next()
+        const route = url.pathname.split('/').pop()
+        if (route === 'install') {
+          state = 'installing'
+          timer = setTimeout(() => (state = outcome), 2500)
+        }
+        else if (route === 'disable') {
+          state = 'disabled'
+        }
+        send(route === 'status' ? status() : { ok: true })
+      })
+    },
+  }
+}
+
+/**
+ * The button's styles are compiled ahead of time into `.generated/css.ts`.
+ * When a source file, `style.css` or a UnoCSS config changes, run the same
+ * script `pnpm build:css` runs, then reload. The client is a self-running
+ * module, so HMR would mount a second button: every change is a full reload.
+ */
+function rebuildCss(): Plugin {
+  const watched = [
+    fileURLToPath(new URL('../src/client/', import.meta.url)),
+    fileURLToPath(new URL('../uno.config.ts', import.meta.url)),
+    fileURLToPath(new URL('../../../design/', import.meta.url)),
+  ]
+  const generated = fileURLToPath(new URL('../src/client/.generated/', import.meta.url))
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  return {
+    name: 'rebuild-onboard-css',
+    configureServer(server) {
+      server.watcher.add(watched)
+      server.watcher.on('change', (file) => {
+        if (file.startsWith(generated) || !watched.some(path => file.startsWith(path)))
+          return
+        clearTimeout(timer)
+        timer = setTimeout(() => {
+          const child = spawn('pnpm', ['run', 'build:css'], { cwd: root, stdio: 'inherit' })
+          child.on('close', (code) => {
+            if (code === 0)
+              server.ws.send({ type: 'full-reload' })
+          })
+        }, 100)
+      })
+    },
+    handleHotUpdate: ({ file }) => watched.some(path => file.startsWith(path)) ? [] : undefined,
+  }
+}
+
+export default defineConfig({
+  root,
+  server: { open: '/playground/' },
+  plugins: [mockOnboarding(), rebuildCss()],
+})