nuxtseo-layer-devtools 0.1.2 → 0.2.0

package/assets/css/global.css

@@ -42,8 +42,8 @@
   --color-surface: var(--color-neutral-950);
   --color-surface-elevated: var(--color-neutral-900);
   --color-surface-sunken: oklch(7% 0.004 260);
-  --color-border: var(--color-neutral-800);
-  --color-border-subtle: oklch(16% 0.008 260);
+  --color-border: oklch(25% 0.012 260);
+  --color-border-subtle: oklch(20% 0.01 260);
   --color-text: var(--color-neutral-100);
   --color-text-muted: var(--color-neutral-400);
   --color-text-subtle: var(--color-neutral-500);
@@ -507,42 +507,26 @@ html.dark {
 }
 
 /* Preview source toggle */
-.devtools-preview-toggle {
-  display: flex;
-  gap: 1px;
-  background: var(--color-border);
-  border-radius: 6px;
-  overflow: hidden;
-}
-
-.devtools-preview-btn {
-  display: flex;
+.devtools-mode-btn {
+  display: inline-flex;
   align-items: center;
   gap: 0.25rem;
-  padding: 0.25rem 0.5rem;
+  padding: 0.2rem 0.5rem;
   font-size: 0.6875rem;
   font-weight: 500;
   color: var(--color-text-muted);
   background: var(--color-surface-sunken);
-  border: none;
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
   cursor: pointer;
-  transition: color 150ms, background 150ms;
+  transition: color 150ms, background 150ms, border-color 150ms;
   white-space: nowrap;
 }
 
-.devtools-preview-btn:hover {
+.devtools-mode-btn:hover {
   color: var(--color-text);
   background: var(--color-surface-elevated);
-}
-
-.devtools-preview-btn.active {
-  color: var(--color-text);
-  background: var(--color-surface-elevated);
-  box-shadow: 0 1px 2px oklch(0% 0 0 / 0.06);
-}
-
-.dark .devtools-preview-btn.active {
-  box-shadow: 0 1px 2px oklch(0% 0 0 / 0.2);
+  border-color: var(--color-border-hover, var(--color-border));
 }
 
 /* Production URL badge */

package/components/DevtoolsKeyValue.vue

@@ -5,6 +5,8 @@ export interface KeyValueItem {
   copyable?: boolean
   mono?: boolean
   link?: string
+  /** Render value using DevtoolsSnippet. Pass the language for syntax highlighting. */
+  code?: 'js' | 'json' | 'xml'
 }
 
 const { items, striped = false } = defineProps<{
@@ -19,10 +21,13 @@ const { items, striped = false } = defineProps<{
       v-for="item in items"
       :key="item.key"
       class="devtools-kv-row group"
-      :class="{ 'devtools-kv-striped': striped }"
+      :class="{
+        'devtools-kv-striped': striped,
+        'devtools-kv-stacked': !!item.code,
+      }"
     >
       <span class="devtools-kv-key">{{ item.key }}</span>
-      <div class="devtools-kv-value-wrap">
+      <div class="devtools-kv-value-wrap" :class="{ 'devtools-kv-value-wrap-full': !!item.code }">
         <a
           v-if="item.link"
           :href="item.link"
@@ -32,6 +37,12 @@ const { items, striped = false } = defineProps<{
         >
           {{ item.value }}
         </a>
+        <DevtoolsSnippet
+          v-else-if="item.code && item.value !== undefined && item.value !== ''"
+          :code="String(item.value)"
+          :lang="item.code"
+          class="devtools-kv-snippet"
+        />
         <span
           v-else
           class="devtools-kv-value"
@@ -45,7 +56,7 @@ const { items, striped = false } = defineProps<{
           {{ item.value === undefined || item.value === '' ? '(empty)' : item.value }}
         </span>
         <DevtoolsCopyButton
-          v-if="item.copyable && item.value !== undefined && item.value !== ''"
+          v-if="!item.code && item.copyable && item.value !== undefined && item.value !== ''"
           :text="String(item.value)"
           class="opacity-0 group-hover:opacity-100 transition-opacity"
         />
@@ -64,6 +75,12 @@ const { items, striped = false } = defineProps<{
   transition: background-color 150ms ease;
 }
 
+.devtools-kv-row.devtools-kv-stacked {
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.375rem;
+}
+
 .devtools-kv-row:hover {
   background: var(--color-surface-sunken);
 }
@@ -86,12 +103,20 @@ const { items, striped = false } = defineProps<{
   min-width: 0;
 }
 
+.devtools-kv-value-wrap-full {
+  width: 100%;
+}
+
 .devtools-kv-value {
   font-size: 0.8125rem;
   text-align: right;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
+  overflow-wrap: break-word;
+  word-break: break-all;
+}
+
+.devtools-kv-snippet {
+  width: 100%;
+  margin: 0 !important;
 }
 
 .devtools-kv-true {

package/components/DevtoolsLayout.vue

@@ -92,8 +92,34 @@ const isRouteNav = computed(() => navItems.some(item => item.to))
                 v-if="version"
                 class="font-mono text-[10px] sm:text-xs hidden sm:inline-flex"
               >
-                {{ version }}
+                v{{ version }}
               </UBadge>
+              <UDropdownMenu
+                v-if="hasProductionUrl"
+                :items="[
+                  { label: 'Local', icon: 'carbon:laptop', onSelect: () => previewSource = 'local' },
+                  { label: 'Production', icon: 'carbon:cloud', hostname: productionHostname, onSelect: () => previewSource = 'production' },
+                ]"
+              >
+                <button type="button" class="devtools-mode-btn">
+                  <UIcon :name="isProductionMode ? 'carbon:cloud' : 'carbon:laptop'" class="w-3.5 h-3.5" />
+                  <span class="hidden sm:inline">{{ isProductionMode ? 'Production' : 'Local' }}</span>
+                  <template v-if="isProductionMode">
+                    <span class="devtools-production-badge">
+                      <span class="devtools-production-dot" />
+                      {{ productionHostname }}
+                    </span>
+                  </template>
+                  <UIcon name="carbon:chevron-down" class="w-3 h-3 opacity-50" />
+                </button>
+                <template #item-label="{ item }">
+                  <span>{{ item.label }}</span>
+                  <span v-if="(item as any).hostname" class="devtools-production-badge text-[10px]">
+                    <span class="devtools-production-dot" />
+                    {{ (item as any).hostname }}
+                  </span>
+                </template>
+              </UDropdownMenu>
             </div>
           </div>
 
@@ -150,36 +176,6 @@ const isRouteNav = computed(() => navItems.some(item => item.to))
               </template>
             </div>
 
-            <!-- Preview source toggle -->
-            <div v-if="hasProductionUrl" class="devtools-preview-toggle">
-              <button
-                type="button"
-                class="devtools-preview-btn"
-                :class="{ active: previewSource === 'local' }"
-                @click="previewSource = 'local'"
-              >
-                <UIcon name="carbon:laptop" class="w-3.5 h-3.5" aria-hidden="true" />
-                <span class="hidden sm:inline">Local</span>
-              </button>
-              <button
-                type="button"
-                class="devtools-preview-btn"
-                :class="{ active: previewSource === 'production' }"
-                @click="previewSource = 'production'"
-              >
-                <UIcon name="carbon:cloud" class="w-3.5 h-3.5" aria-hidden="true" />
-                <span class="hidden sm:inline">Production</span>
-              </button>
-            </div>
-
-            <!-- Production URL indicator -->
-            <UTooltip v-if="isProductionMode" :text="productionUrl">
-              <span class="devtools-production-badge">
-                <span class="devtools-production-dot" />
-                <span class="hidden sm:inline text-xs">{{ productionHostname }}</span>
-              </span>
-            </UTooltip>
-
             <!-- Actions -->
             <div class="flex items-center gap-1">
               <slot name="actions" />

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxtseo-layer-devtools",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Shared Nuxt layer for Nuxt SEO devtools clients.",
   "author": {
     "name": "Harlan Wilton",
@@ -15,13 +15,14 @@
     "assets",
     "components",
     "composables",
-    "nuxt.config.ts"
+    "nuxt.config.ts",
+    "skills"
   ],
   "dependencies": {
     "@nuxt/devtools-kit": "^3.2.4",
     "@nuxt/fonts": "^0.14.0",
     "@nuxt/kit": "^4.4.2",
-    "@nuxt/ui": "^4.5.1",
+    "@nuxt/ui": "^4.6.0",
     "@shikijs/langs": "^4.0.2",
     "@shikijs/themes": "^4.0.2",
     "@vueuse/core": "^14.2.1",

package/skills/devtools-layer-skilld/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: devtools-layer-skilld
+description: "nuxtseo-layer-devtools shared devtools layer for Nuxt SEO modules. ALWAYS use when building, modifying, or reviewing devtools client code in any Nuxt SEO module. Consult for component API, composables, implementation patterns, or debugging devtools clients."
+---
+
+# nuxtseo-layer-devtools
+
+Shared Nuxt layer providing components, composables, and a design system for all Nuxt SEO module devtools clients.
+
+**Source:** `packages/devtools-layer/` (published as `nuxtseo-layer-devtools`)
+
+## Architecture
+
+1. **nuxtseo-shared/devtools** (`packages/shared/src/devtools.ts`): `setupDevToolsUI()` registers iframe tab, handles dev proxy + production sirv
+2. **nuxtseo-layer-devtools** (`packages/devtools-layer/`): Nuxt layer with shared UI, composables, CSS
+3. **Module client** (`<module>/client/`): Extends the layer, adds module specific UI and debug routes
+
+## Rules
+
+1. ALWAYS extend `nuxtseo-layer-devtools` in client/nuxt.config.ts
+2. ALWAYS create `client/composables/rpc.ts` that calls `useDevtoolsConnection()`
+3. ALWAYS use layer components over custom HTML: `DevtoolsSection` not custom details, `DevtoolsKeyValue` not custom tables, `DevtoolsSnippet` not custom code blocks
+4. NEVER add custom CSS that duplicates what the layer provides
+5. NEVER enable SSR in the client (it runs in an iframe)
+6. ALWAYS disable the module itself in the client nuxt config (e.g. `robots: false`)
+7. ALWAYS guard devtools setup with `if (nuxt.options.dev)` in module.ts
+8. ALWAYS use `useAsyncData` with `watch: [refreshTime]` for reactive data fetching
+9. Use Carbon icons consistently (prefix: `carbon:`)
+10. Debug server routes ONLY registered in dev mode
+
+## Required File Structure
+
+```
+client/
+├── nuxt.config.ts          # extends nuxtseo-layer-devtools
+├── app.vue                 # OR pages/ directory
+├── composables/
+│   └── rpc.ts              # connection setup (REQUIRED)
+src/
+├── devtools.ts             # calls setupDevToolsUI from nuxtseo-shared/devtools
+├── module.ts               # calls setupDevToolsUI in dev, registers debug routes
+└── runtime/server/routes/__<module>__/
+    └── debug.ts            # JSON debug endpoint
+```
+
+## Implementation Templates
+
+For full component/composable API reference, read [reference.md](./reference.md).
+
+### client/nuxt.config.ts
+
+```ts
+export default defineNuxtConfig({
+  extends: ['nuxtseo-layer-devtools'],
+  <moduleName>: false,
+  app: { baseURL: '/__<module-route>' },
+  nitro: { output: { publicDir: resolve('./dist/client') } },
+})
+```
+
+### client/composables/rpc.ts
+
+```ts
+useDevtoolsConnection({
+  onConnected() { refreshSources() },
+  onRouteChange() { refreshSources() },
+})
+```
+
+### src/devtools.ts
+
+```ts
+import { setupDevToolsUI as _setup } from 'nuxtseo-shared/devtools'
+
+export function setupDevToolsUI(config: any, resolve: Resolver['resolve'], nuxt?: Nuxt) {
+  return _setup({ route: '/__<route>', name: '<name>', title: '<Title>', icon: 'carbon:<icon>' }, resolve, nuxt)
+}
+```
+
+### src/module.ts
+
+```ts
+if (nuxt.options.dev) {
+  addServerHandler({ route: '/__<module>__/debug', handler: resolve('./runtime/server/routes/__<module>__/debug') })
+  setupDevToolsUI(config, resolve)
+}
+```
+
+### app.vue pattern
+
+```vue
+<script setup lang="ts">
+const activeTab = ref('overview')
+const loading = ref(true)
+const { data } = await useAsyncData('debug', () => $fetch('/__<module>__/debug.json'), { watch: [refreshTime] })
+watch(data, () => { loading.value = false })
+</script>
+
+<template>
+  <DevtoolsLayout v-model:active-tab="activeTab" title="Name" icon="carbon:icon" :nav-items="navItems" github-url="..." :loading @refresh="refreshSources">
+    <DevtoolsLoading v-if="loading" />
+    <template v-else-if="activeTab === 'overview'">
+      <!-- content -->
+    </template>
+  </DevtoolsLayout>
+</template>
+```

package/skills/devtools-layer-skilld/reference.md

@@ -0,0 +1,148 @@
+# Devtools Layer API Reference
+
+## Components (auto imported)
+
+### Layout & Structure
+
+| Component | Props | Key Slots | Purpose |
+|---|---|---|---|
+| `DevtoolsLayout` | `title`, `icon`, `version?`, `navItems`, `githubUrl`, `loading?` | `actions`, default | Main shell with header, tabs, refresh |
+| `DevtoolsPanel` | `title?` | `header`, `actions`, default | Card container with close button |
+| `DevtoolsToolbar` | `variant` ('default'\|'minimal') | default | Horizontal toolbar strip |
+| `DevtoolsSection` | `icon?`, `text?`, `description?`, `collapse?`, `open?`, `padding?` | `text`, `description`, `actions`, `details`, default, `footer` | Collapsible details/summary block |
+
+### Feedback & States
+
+| Component | Props | Key Slots | Purpose |
+|---|---|---|---|
+| `DevtoolsAlert` | `icon?`, `variant` ('info'\|'warning'\|'success'\|'production') | default, `action` | Color coded status bar |
+| `DevtoolsError` | `icon?`, `title?`, `error?` | default | Centered error display |
+| `DevtoolsEmptyState` | `icon?`, `title`, `description?`, `variant` ('default'\|'error') | default, `description` | No results placeholder |
+| `DevtoolsProductionError` | `error?` | none | Production URL unreachable |
+| `DevtoolsLoading` | none | none | Centered spinner |
+
+### Data Display
+
+| Component | Props | Key Slots | Purpose |
+|---|---|---|---|
+| `DevtoolsKeyValue` | `items: KeyValueItem[]`, `striped?` | none | Key value table with copy, links, booleans |
+| `DevtoolsMetric` | `label?`, `value`, `icon?`, `variant` | none | Small inline metric badge |
+| `DevtoolsCopyButton` | `text` | none | Copy to clipboard button |
+| `DevtoolsSnippet` | `label?`, `code`, `lang` ('js'\|'json'\|'xml') | `header` | Code block with header and copy |
+| `OCodeBlock` | `code`, `lang`, `lines?`, `transformRendered?` | none | Shiki syntax highlighted pre |
+| `DevtoolsDocs` | `url` | none | Full height iframe |
+
+### KeyValueItem Interface
+
+```ts
+interface KeyValueItem {
+  key: string
+  value: any
+  copyable?: boolean
+  mono?: boolean
+  link?: string
+}
+```
+
+## Composables (auto imported)
+
+### Connection (`composables/rpc.ts`)
+
+```ts
+const appFetch: Ref<$Fetch | undefined> // Host app's $fetch
+const devtools: Ref<NuxtDevtoolsClient> // Devtools client instance
+const colorMode: Ref<'dark' | 'light'> // Synced from host
+
+function useDevtoolsConnection(options?: {
+  onConnected?: (client: any) => void
+  onRouteChange?: (route: any) => void
+}): void
+```
+
+### State (`composables/state.ts`)
+
+```ts
+const refreshTime: Ref<number> // Watch to trigger re-fetch
+const hostname: string
+const path: Ref<string>
+const query: Ref<any>
+const base: Ref<string>
+const host: ComputedRef<string>
+const refreshSources: Function // Debounced 200ms
+const slowRefreshSources: Function // Debounced 1000ms
+
+// Production preview mode
+const previewSource: Ref<'local' | 'production'> // localStorage persisted
+const productionUrl: Ref<string>
+const hasProductionUrl: ComputedRef<boolean>
+const isProductionMode: ComputedRef<boolean>
+```
+
+### Shiki (`composables/shiki.ts`)
+
+```ts
+async function loadShiki(options?: { extraLangs?: LanguageRegistration[] }): Promise<HighlighterCore>
+function useRenderCodeHighlight(code: MaybeRef<string>, lang: string): ComputedRef<string>
+```
+
+### Clipboard (`composables/clipboard.ts`)
+
+```ts
+function useCopy(timeout?: number): { copy: (text: string) => Promise<void>, copied: Ref<boolean> }
+```
+
+## CSS Design System
+
+Do NOT add custom CSS unless layer components are insufficient.
+
+### Semantic Variables
+
+`--color-surface`, `--color-surface-elevated`, `--color-surface-sunken`, `--color-border`, `--color-border-subtle`, `--color-text`, `--color-text-muted`, `--color-text-subtle`, `--seo-green`, `--radius-sm/md/lg`
+
+### Utility Classes
+
+`.glass` (backdrop blur), `.gradient-bg` (green/blue radials), `.card` (elevated hover), `.code-block`, `.status-enabled/.status-disabled`, `.link-external` (with arrow), `.hint-callout`, `.panel-grids`, `.animate-fade-up/.scale-in/.spin`, `.stagger-children`
+
+### Nuxt UI Defaults (app.config.ts)
+
+Primary: green, Neutral: neutral. Buttons: ghost/neutral/sm. Badges: subtle/neutral/xs. Tooltips: zero delay.
+
+## Common Patterns
+
+### Production Mode Data Fetching
+
+```ts
+async function refreshSources() {
+  if (isProductionMode.value)
+    data.value = await $fetch(`/__<module>__/debug-production.json`, { query: { url: productionUrl.value } })
+  else
+    data.value = await $fetch('/__<module>__/debug.json', { query: { path: path.value } })
+}
+watch(isProductionMode, refreshSources)
+```
+
+### Custom Shiki Language
+
+```ts
+import { loadShiki as _loadShiki } from '#imports'
+
+const customLang: LanguageRegistration = { name: 'my-lang', scopeName: 'source.my-lang', patterns: [] }
+export function loadShiki() { return _loadShiki({ extraLangs: [customLang] }) }
+```
+
+### Fallback Connection
+
+```ts
+const connectionState = ref<'connecting' | 'connected' | 'fallback' | 'failed'>('connecting')
+useDevtoolsConnection({
+  onConnected() { connectionState.value = 'connected'; refreshSources() },
+  onRouteChange(route) { path.value = route.path; refreshSources() },
+})
+setTimeout(() => {
+  if (connectionState.value === 'connecting') {
+    connectionState.value = 'fallback'
+    appFetch.value = $fetch.create({ baseURL: 'http://localhost:3000' })
+    refreshSources()
+  }
+}, 2000)
+```