@vitejs/devtools-kit 0.0.0-alpha.8 → 0.1.0

package/skills/vite-devtools-kit/references/dock-entry-types.md

@@ -0,0 +1,295 @@
+# Dock Entry Types
+
+Detailed configuration for each dock entry type.
+
+## Common Properties
+
+All dock entries share these properties:
+
+```ts
+interface DockEntryBase {
+  id: string // Unique identifier
+  title: string // Display title
+  icon: string // URL, data URI, or Iconify name
+  category?: string // Grouping category
+  defaultOrder?: number // Sort order (higher = earlier)
+  isHidden?: boolean // Hide from dock
+  badge?: string // Badge text on dock icon (e.g., count)
+}
+```
+
+## Icons
+
+<!-- eslint-skip -->
+
+```ts
+// Iconify (recommended)
+icon: 'ph:chart-bar-duotone'  // Phosphor Icons
+icon: 'carbon:analytics'       // Carbon Icons
+icon: 'mdi:view-dashboard'     // Material Design
+
+// URL
+icon: 'https://example.com/logo.svg'
+
+// Data URI
+icon: 'data:image/svg+xml,<svg>...</svg>'
+
+// Light/dark variants
+icon: {
+  light: 'https://example.com/logo-light.svg',
+  dark: 'https://example.com/logo-dark.svg',
+}
+```
+
+Browse icons at [Iconify](https://icon-sets.iconify.design/).
+
+## Iframe Entries
+
+Most common type. Displays your UI in an isolated iframe.
+
+```ts
+interface IframeEntry extends DockEntryBase {
+  type: 'iframe'
+  url: string // URL to load
+  frameId?: string // Share iframe between entries
+  clientScript?: ClientScriptEntry // Optional client script
+}
+
+// Example
+ctx.docks.register({
+  id: 'my-plugin',
+  title: 'My Plugin',
+  icon: 'ph:house-duotone',
+  type: 'iframe',
+  url: '/.my-plugin/',
+})
+```
+
+### Hosting Your Own UI
+
+```ts
+import { fileURLToPath } from 'node:url'
+
+const clientDist = fileURLToPath(
+  new URL('../dist/client', import.meta.url)
+)
+
+ctx.views.hostStatic('/.my-plugin/', clientDist)
+
+ctx.docks.register({
+  id: 'my-plugin',
+  title: 'My Plugin',
+  icon: 'ph:house-duotone',
+  type: 'iframe',
+  url: '/.my-plugin/',
+})
+```
+
+## Action Entries
+
+Buttons that trigger client-side scripts. Perfect for inspectors and toggles.
+
+```ts
+interface ActionEntry extends DockEntryBase {
+  type: 'action'
+  action: {
+    importFrom: string // Package export path
+    importName?: string // Export name (default: 'default')
+  }
+}
+
+// Registration
+ctx.docks.register({
+  id: 'my-inspector',
+  title: 'Inspector',
+  icon: 'ph:cursor-duotone',
+  type: 'action',
+  action: {
+    importFrom: 'my-plugin/devtools-action',
+    importName: 'default',
+  },
+})
+```
+
+### Client Script Implementation
+
+```ts
+// src/devtools-action.ts
+import type { DevToolsClientScriptContext } from '@vitejs/devtools-kit/client'
+
+export default function setup(ctx: DevToolsClientScriptContext) {
+  let overlay: HTMLElement | null = null
+
+  ctx.current.events.on('entry:activated', () => {
+    overlay = document.createElement('div')
+    overlay.style.cssText = `
+      position: fixed;
+      inset: 0;
+      cursor: crosshair;
+      z-index: 99999;
+    `
+    overlay.onclick = (e) => {
+      const target = document.elementFromPoint(e.clientX, e.clientY)
+      console.log('Selected:', target)
+    }
+    document.body.appendChild(overlay)
+  })
+
+  ctx.current.events.on('entry:deactivated', () => {
+    overlay?.remove()
+    overlay = null
+  })
+}
+```
+
+### Package Export
+
+```json
+{
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./devtools-action": "./dist/devtools-action.mjs"
+  }
+}
+```
+
+## Custom Render Entries
+
+Render directly into the DevTools panel DOM. Use when you need direct DOM access or framework mounting.
+
+```ts
+interface CustomRenderEntry extends DockEntryBase {
+  type: 'custom-render'
+  renderer: {
+    importFrom: string
+    importName?: string
+  }
+}
+
+ctx.docks.register({
+  id: 'my-custom',
+  title: 'Custom View',
+  icon: 'ph:code-duotone',
+  type: 'custom-render',
+  renderer: {
+    importFrom: 'my-plugin/devtools-renderer',
+    importName: 'default',
+  },
+})
+```
+
+### Renderer Implementation
+
+```ts
+// src/devtools-renderer.ts
+import type { DevToolsClientScriptContext } from '@vitejs/devtools-kit/client'
+
+export default function setup(ctx: DevToolsClientScriptContext) {
+  ctx.current.events.on('dom:panel:mounted', (panel) => {
+    // Vanilla JS
+    panel.innerHTML = `<div style="padding: 16px;">Hello</div>`
+
+    // Or mount Vue
+    // import { createApp } from 'vue'
+    // import App from './App.vue'
+    // createApp(App).mount(panel)
+
+    // Or mount React
+    // import { createRoot } from 'react-dom/client'
+    // createRoot(panel).render(<App />)
+  })
+}
+```
+
+## Launcher Entries
+
+Actionable setup cards for running initialization tasks. Shows a card with title, description, and a launch button.
+
+```ts
+type LauncherStatus = 'idle' | 'loading' | 'success' | 'error'
+
+interface LauncherEntry extends DockEntryBase {
+  type: 'launcher'
+  launcher: {
+    title: string // Card title
+    description?: string // Card description
+    icon?: string | { light: string, dark: string } // Card icon
+    buttonStart?: string // Start button text
+    buttonLoading?: string // Loading button text
+    status?: LauncherStatus // Current status
+    error?: string // Error message when status is 'error'
+    onLaunch: () => Promise<void> // Callback when user clicks launch
+  }
+}
+
+// Registration
+const entry = ctx.docks.register({
+  id: 'my-setup',
+  title: 'My Setup',
+  icon: 'ph:rocket-launch-duotone',
+  type: 'launcher',
+  launcher: {
+    title: 'Initialize My Plugin',
+    description: 'Run the initial setup before the plugin can be used',
+    buttonStart: 'Start Setup',
+    buttonLoading: 'Setting up...',
+    onLaunch: async () => {
+      // Perform initialization
+      await runSetup()
+    },
+  },
+})
+
+// Update status after launch completes
+entry.update({
+  launcher: {
+    ...entry.launcher,
+    status: 'success',
+  },
+})
+```
+
+### Launcher Use Cases
+
+- **First-run setup** — Run initial scans or configuration before showing results
+- **Build triggers** — Start a build or analysis pass on demand
+- **Authentication** — Prompt user to connect external services
+
+## Client Script Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `entry:activated` | - | Entry was selected |
+| `entry:deactivated` | - | Entry was deselected |
+| `entry:updated` | `DevToolsDockUserEntry` | Entry metadata changed |
+| `dom:panel:mounted` | `HTMLDivElement` | Panel DOM ready (custom-render only) |
+| `dom:iframe:mounted` | `HTMLIFrameElement` | Iframe mounted (iframe only) |
+
+## Category Order
+
+Default category ordering:
+
+```ts
+DEFAULT_CATEGORIES_ORDER = {
+  '~viteplus': -1000, // First
+  'default': 0,
+  'app': 100,
+  'framework': 200,
+  'web': 300,
+  'advanced': 400,
+  '~builtin': 1000, // Last
+}
+```
+
+Use `category` to group related entries:
+
+```ts
+ctx.docks.register({
+  id: 'my-plugin',
+  title: 'My Plugin',
+  icon: 'ph:house-duotone',
+  type: 'iframe',
+  url: '/.my-plugin/',
+  category: 'framework',
+})
+```

package/skills/vite-devtools-kit/references/logs-patterns.md

@@ -0,0 +1,188 @@
+# Logs & Notification Patterns
+
+Structured log entries and toast notifications from both server and client contexts.
+
+## Log Entry Types
+
+```ts
+type DevToolsLogLevel = 'info' | 'warn' | 'error' | 'success' | 'debug'
+
+interface DevToolsLogEntryInput {
+  message: string // Required: short title
+  level: DevToolsLogLevel // Required: severity
+  description?: string // Detailed explanation
+  stacktrace?: string // Stack trace string
+  filePosition?: { file: string, line?: number, column?: number }
+  elementPosition?: { selector?: string, boundingBox?: { x: number, y: number, width: number, height: number }, description?: string }
+  notify?: boolean // Show as toast
+  category?: string // Grouping (e.g., 'a11y', 'lint')
+  labels?: string[] // Tags for filtering
+  autoDismiss?: number // Toast dismiss time in ms (default: 5000)
+  autoDelete?: number // Auto-delete time in ms
+  status?: 'loading' | 'idle' // Shows spinner when loading
+  id?: string // Explicit id for deduplication
+}
+```
+
+The `from` field (`'server' | 'browser'`) is set automatically.
+
+## Server-Side Patterns
+
+### Fire-and-Forget in Setup
+
+```ts
+export function myPlugin() {
+  return {
+    name: 'my-plugin',
+    devtools: {
+      setup(ctx) {
+        ctx.logs.add({
+          message: 'Plugin initialized',
+          level: 'info',
+        })
+      },
+    },
+  }
+}
+```
+
+### Handle-Based Updates
+
+```ts
+export function myPlugin() {
+  return {
+    name: 'my-plugin',
+    devtools: {
+      async setup(ctx) {
+        const log = await ctx.logs.add({
+          id: 'my-plugin:build',
+          message: 'Analyzing...',
+          level: 'info',
+          status: 'loading',
+        })
+
+        // Later, after work completes
+        await log.update({
+          message: 'Analysis complete — 42 modules',
+          level: 'success',
+          status: 'idle',
+        })
+      },
+    },
+  }
+}
+```
+
+### File Position (Clickable Links)
+
+```ts
+ctx.logs.add({
+  message: 'Unused import detected',
+  level: 'warn',
+  category: 'lint',
+  filePosition: {
+    file: '/src/App.vue',
+    line: 12,
+    column: 1,
+  },
+})
+```
+
+### Element Position (DOM Highlighting)
+
+```ts
+ctx.logs.add({
+  message: 'Missing alt attribute on image',
+  level: 'warn',
+  category: 'a11y',
+  labels: ['WCAG 1.1.1'],
+  elementPosition: {
+    selector: 'img.hero-image',
+    description: '<img class="hero-image">',
+  },
+})
+```
+
+## Client-Side Patterns
+
+### Client Script with Logs
+
+```ts
+import type { DockClientScriptContext } from '@vitejs/devtools-kit/client'
+
+export default async function (ctx: DockClientScriptContext) {
+  const log = await ctx.logs.add({
+    message: 'Running audit...',
+    level: 'info',
+    status: 'loading',
+    notify: true,
+  })
+
+  // ... perform work ...
+
+  log.update({
+    message: 'Audit complete — 3 issues found',
+    level: 'warn',
+    status: 'idle',
+  })
+}
+```
+
+## Toast Notifications
+
+```ts
+// Short-lived notification
+ctx.logs.add({
+  message: 'URL copied to clipboard',
+  level: 'success',
+  notify: true,
+  autoDismiss: 2000,
+})
+```
+
+Toasts appear as overlay notifications regardless of whether the Logs panel is open. Default auto-dismiss is 5 seconds.
+
+## Deduplication
+
+Re-adding with the same `id` updates the existing entry:
+
+```ts
+// Creates entry
+ctx.logs.add({ id: 'my-scan', message: 'Scanning...', level: 'info', status: 'loading' })
+
+// Updates same entry (no duplicate)
+ctx.logs.add({ id: 'my-scan', message: 'Scan complete', level: 'success', status: 'idle' })
+```
+
+## Log Handle API
+
+`ctx.logs.add()` returns `Promise<DevToolsLogHandle>`:
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `handle.id` | The log entry id |
+| `handle.entry` | The current `DevToolsLogEntry` data |
+| `handle.update(patch)` | Partially update the entry (returns `Promise`) |
+| `handle.dismiss()` | Remove the entry (returns `Promise`) |
+
+Both `update()` and `dismiss()` can be used without `await` for fire-and-forget.
+
+## Managing Logs
+
+```ts
+// Remove specific log
+ctx.logs.remove(entryId)
+
+// Clear all logs
+ctx.logs.clear()
+```
+
+Max capacity is 1000 entries; oldest entries are auto-removed when full.
+
+## Dock Badge
+
+The built-in Logs dock icon automatically shows a badge with the total log count and is hidden when empty.
+
+## Real-World Example
+
+See [`examples/plugin-a11y-checker`](https://github.com/vitejs/devtools/tree/main/examples/plugin-a11y-checker) for a complete plugin that uses logs to report accessibility violations with severity levels, element positions, WCAG labels, and log handle updates.