@quazardous/qdadm 1.19.3

package/src/modules/debug/ZonesCollector.ts

@@ -0,0 +1,447 @@
+/**
+ * ZonesCollector - Debug collector for Zone Registry visualization
+ *
+ * This collector provides real-time visibility into the zone system:
+ * - All defined zones
+ * - Blocks registered in each zone
+ * - Wrapper chains
+ * - Visual highlighting of zones on the page
+ *
+ * Unlike event collectors, this shows current state rather than historical events.
+ *
+ * @example
+ * const collector = new ZonesCollector()
+ * collector.install(ctx)
+ * collector.getZoneInfo() // { zones: [...], totalBlocks: n }
+ */
+
+import {
+  Collector,
+  type CollectorContext,
+  type CollectorEntry,
+  type CollectorManifest,
+  type CollectorOptions,
+  type CollectorSnapshot,
+} from './Collector'
+import type { ZoneRegistry } from '../../zones/ZoneRegistry'
+import type { Router } from 'vue-router'
+
+/**
+ * Zone entry type (state-based, not event-based)
+ */
+export interface ZoneEntry extends CollectorEntry {
+  name: string
+  isOnPage: boolean
+  hasDefault: boolean
+  defaultName: string | null
+  blocksCount: number
+  blocks: ZoneBlock[]
+}
+
+/**
+ * Zone block info
+ */
+export interface ZoneBlock {
+  id: string
+  weight: number
+  component: string
+  hasWrappers: boolean
+  wrappersCount: number
+  wrappers: ZoneWrapper[]
+}
+
+/**
+ * Zone wrapper info
+ */
+export interface ZoneWrapper {
+  component: string
+  weight: number
+}
+
+/**
+ * ZonesCollector options
+ */
+export interface ZonesCollectorOptions extends CollectorOptions {
+  showCurrentPageOnly?: boolean
+  showInternalZones?: boolean
+}
+
+/**
+ * Extended context for zones collector
+ */
+interface ZonesCollectorContext extends CollectorContext {
+  zones?: ZoneRegistry
+  router?: Router
+}
+
+/**
+ * Collector for Zone Registry state visualization
+ */
+export class ZonesCollector extends Collector<ZoneEntry> {
+  /**
+   * Collector name identifier
+   */
+  static override collectorName = 'zones'
+
+  /**
+   * This collector shows state, not events
+   */
+  static override records = false
+
+  private _registry: ZoneRegistry | null = null
+  private _highlightedZone: string | null = null
+  private _overlays: Map<string, HTMLDivElement> = new Map()
+  private _showCurrentPageOnly: boolean
+  private _showInternalZones: boolean
+  private _routerCleanup: (() => void) | null = null
+
+  constructor(options: ZonesCollectorOptions = {}) {
+    super(options)
+    this._showCurrentPageOnly = options.showCurrentPageOnly ?? true
+    this._showInternalZones = options.showInternalZones ?? false
+  }
+
+  /**
+   * Internal install - get zone registry reference and subscribe to navigation
+   * @protected
+   */
+  protected override _doInstall(ctx: CollectorContext): void {
+    this._ctx = ctx
+    this._registry = (ctx as ZonesCollectorContext).zones ?? null
+    if (!this._registry) {
+      console.warn('[ZonesCollector] No zone registry found in context')
+    }
+    this._setupRouterListener()
+  }
+
+  /**
+   * Setup router listener for navigation changes
+   * @private
+   */
+  private _setupRouterListener(): void {
+    const router = (this._ctx as ZonesCollectorContext)?.router
+    if (!router) {
+      setTimeout(() => this._setupRouterListener(), 100)
+      return
+    }
+
+    // Listen to route changes - zones on page may differ
+    this._routerCleanup = router.afterEach(() => {
+      // Small delay to let DOM update
+      setTimeout(() => this.notifyChange(), 50)
+    })
+  }
+
+  /**
+   * Internal uninstall - cleanup highlights and router listener
+   * @protected
+   */
+  protected override _doUninstall(): void {
+    this.clearHighlights()
+    if (this._routerCleanup) {
+      this._routerCleanup()
+      this._routerCleanup = null
+    }
+    this._registry = null
+    this._ctx = null
+  }
+
+  /**
+   * Check if a zone is rendered on the current page
+   * @param zoneName - Zone name to check
+   *
+   * Note: Internal zones (prefixed with _) are currently considered always on page
+   * since they're typically global (app:debug, app:toasts).
+   */
+  isZoneOnPage(zoneName: string): boolean {
+    // Internal zones are global, always considered "on page"
+    if (zoneName.startsWith('_')) {
+      return true
+    }
+    const escapedName = CSS.escape(zoneName)
+    return document.querySelector(`[data-zone="${zoneName}"], .zone-${escapedName}`) !== null
+  }
+
+  /**
+   * Get/set filter for current page zones only
+   */
+  get showCurrentPageOnly(): boolean {
+    return this._showCurrentPageOnly
+  }
+
+  set showCurrentPageOnly(value: boolean) {
+    this._showCurrentPageOnly = value
+  }
+
+  /**
+   * Toggle current page filter
+   * @returns New filter state
+   */
+  toggleFilter(): boolean {
+    this._showCurrentPageOnly = !this._showCurrentPageOnly
+    return this._showCurrentPageOnly
+  }
+
+  /**
+   * Get/set filter for internal zones (prefixed with _)
+   */
+  get showInternalZones(): boolean {
+    return this._showInternalZones
+  }
+
+  set showInternalZones(value: boolean) {
+    this._showInternalZones = value
+  }
+
+  /**
+   * Toggle internal zones filter
+   * @returns New filter state
+   */
+  toggleInternalFilter(): boolean {
+    this._showInternalZones = !this._showInternalZones
+    return this._showInternalZones
+  }
+
+  /**
+   * Get badge - show number of zones (filtered if filter active)
+   */
+  override getBadge(): number {
+    if (!this._registry) return 0
+    const registry = this._registry as unknown as { _zones: Map<string, unknown> }
+    let count = 0
+    for (const [name] of registry._zones) {
+      // Skip internal zones (prefixed with _) unless showing them
+      if (name.startsWith('_') && !this._showInternalZones) continue
+      // Apply page filter if enabled
+      if (this._showCurrentPageOnly && !this.isZoneOnPage(name)) continue
+      count++
+    }
+    return count
+  }
+
+  /**
+   * Get all zone information for display
+   * @param forceAll - If true, ignore filter and return all zones
+   * @returns Zone info array
+   */
+  override getEntries(forceAll = false): ZoneEntry[] {
+    if (!this._registry) return []
+
+    const registry = this._registry as unknown as {
+      _zones: Map<string, { default?: { name?: string; __name?: string } }>
+      getBlocks: (name: string) => Array<{
+        id?: string
+        weight: number
+        component?: { name?: string; __name?: string }
+        wrappers?: Array<{
+          component?: { name?: string; __name?: string }
+          weight: number
+        }>
+      }>
+    }
+
+    const zones: ZoneEntry[] = []
+    for (const [name, config] of registry._zones) {
+      // Skip internal zones (prefixed with _) unless showing them
+      if (name.startsWith('_') && !this._showInternalZones) {
+        continue
+      }
+
+      // Apply filter if enabled
+      const isOnPage = this.isZoneOnPage(name)
+      if (!forceAll && this._showCurrentPageOnly && !isOnPage) {
+        continue
+      }
+
+      const blocks = registry.getBlocks(name)
+      zones.push({
+        timestamp: Date.now(),
+        name,
+        isOnPage,
+        hasDefault: !!config.default,
+        defaultName: config.default?.name || config.default?.__name || null,
+        blocksCount: blocks.length,
+        blocks: blocks.map(b => ({
+          id: b.id || '(anonymous)',
+          weight: b.weight,
+          component: b.component?.name || b.component?.__name || 'Component',
+          hasWrappers: !!(b.wrappers && b.wrappers.length),
+          wrappersCount: b.wrappers?.length || 0,
+          wrappers: b.wrappers?.map(w => ({
+            component: w.component?.name || w.component?.__name || 'Wrapper',
+            weight: w.weight
+          })) || []
+        }))
+      })
+    }
+    return zones.sort((a, b) => a.name.localeCompare(b.name))
+  }
+
+  /**
+   * Highlight a zone on the page
+   * Creates a visual overlay around zone elements
+   * @param zoneName - Zone name to highlight
+   */
+  highlightZone(zoneName: string): void {
+    this.clearHighlights()
+    this._highlightedZone = zoneName
+
+    // Find zone elements by data attribute
+    const escapedName = CSS.escape(zoneName)
+    const elements = document.querySelectorAll(`[data-zone="${zoneName}"], .zone-${escapedName}`)
+
+    elements.forEach((el, idx) => {
+      const rect = el.getBoundingClientRect()
+      const overlay = document.createElement('div')
+      overlay.className = 'qdadm-zone-overlay'
+      overlay.style.cssText = `
+        position: fixed;
+        top: ${rect.top}px;
+        left: ${rect.left}px;
+        width: ${rect.width}px;
+        height: ${rect.height}px;
+        border: 2px dashed #8b5cf6;
+        background: rgba(139, 92, 246, 0.1);
+        pointer-events: none;
+        z-index: 99998;
+        transition: all 0.2s;
+      `
+
+      // Label
+      const label = document.createElement('div')
+      label.style.cssText = `
+        position: absolute;
+        top: -20px;
+        left: 0;
+        background: #8b5cf6;
+        color: white;
+        padding: 2px 6px;
+        font-size: 10px;
+        font-family: system-ui, sans-serif;
+        border-radius: 2px;
+        white-space: nowrap;
+      `
+      label.textContent = zoneName
+      overlay.appendChild(label)
+
+      document.body.appendChild(overlay)
+      this._overlays.set(`${zoneName}-${idx}`, overlay)
+    })
+  }
+
+  /**
+   * Clear all zone highlights
+   */
+  clearHighlights(): void {
+    this._overlays.forEach(overlay => overlay.remove())
+    this._overlays.clear()
+    this._highlightedZone = null
+  }
+
+  /**
+   * Get currently highlighted zone
+   */
+  getHighlightedZone(): string | null {
+    return this._highlightedZone
+  }
+
+  /**
+   * Toggle zone highlight
+   * @param zoneName - Zone name
+   * @returns Whether zone is now highlighted
+   */
+  toggleHighlight(zoneName: string): boolean {
+    if (this._highlightedZone === zoneName) {
+      this.clearHighlights()
+      return false
+    } else {
+      this.highlightZone(zoneName)
+      return true
+    }
+  }
+
+  override describe(): CollectorManifest {
+    return {
+      name: this.name,
+      records: false,
+      summary:
+        'Lists every zone defined in the running app and the blocks/wrappers registered in each. Reflects current page (filterable).',
+      entryShape: {
+        name: 'string',
+        isOnPage: 'boolean',
+        hasDefault: 'boolean',
+        defaultName: 'string?',
+        blocksCount: 'number',
+        blocks: 'ZoneBlock[]',
+      },
+      stateShape: {
+        showCurrentPageOnly: 'boolean',
+        showInternalZones: 'boolean',
+        highlightedZone: 'string?',
+      },
+      actions: [
+        ...this._builtinActionManifests(),
+        {
+          name: 'highlight',
+          summary: 'Draw an overlay on the page around a zone (browser-only).',
+          args: { name: 'string' },
+          mutates: true,
+        },
+        {
+          name: 'clearHighlights',
+          summary: 'Remove every zone overlay.',
+          mutates: true,
+        },
+        {
+          name: 'setShowCurrentPageOnly',
+          summary: 'Filter zones to those rendered on the current page.',
+          args: { value: 'boolean' },
+          mutates: true,
+        },
+        {
+          name: 'setShowInternalZones',
+          summary: 'Show internal zones (prefixed with _).',
+          args: { value: 'boolean' },
+          mutates: true,
+        },
+      ],
+    }
+  }
+
+  override snapshot(): CollectorSnapshot {
+    const entries = this.getEntries(true)
+    return {
+      name: this.name,
+      entries,
+      count: entries.length,
+      unseen: 0,
+      state: {
+        showCurrentPageOnly: this._showCurrentPageOnly,
+        showInternalZones: this._showInternalZones,
+        highlightedZone: this._highlightedZone,
+      },
+    }
+  }
+
+  override async call(actionName: string, args: Record<string, unknown> = {}): Promise<unknown> {
+    if (actionName === 'highlight') {
+      this.highlightZone(String(args.name ?? ''))
+      return { ok: true }
+    }
+    if (actionName === 'clearHighlights') {
+      this.clearHighlights()
+      return { ok: true }
+    }
+    if (actionName === 'setShowCurrentPageOnly') {
+      this._showCurrentPageOnly = Boolean(args.value)
+      this.notifyChange()
+      return { ok: true, value: this._showCurrentPageOnly }
+    }
+    if (actionName === 'setShowInternalZones') {
+      this._showInternalZones = Boolean(args.value)
+      this.notifyChange()
+      return { ok: true, value: this._showInternalZones }
+    }
+    return super.call(actionName, args)
+  }
+}

package/src/modules/debug/components/DebugBar.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+/**
+ * qdadm DebugBar wrapper.
+ *
+ * Wraps the panel-pluggable `@quazardous/qddebug` `DebugBar` with qdadm's
+ * admin-specific panels (auth, entities, router, zones, i18n) and the
+ * matching tab metadata (icons / labels / colors). Existing call sites that
+ * imported this file continue to work unchanged.
+ */
+import { DebugBar as QddebugBar } from '@quazardous/qddebug'
+import { adminPanels, adminPanelsMeta } from './adminPanelsConfig'
+
+defineProps<{
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  bridge: any
+  zIndex?: number
+}>()
+
+// Preserve the legacy localStorage key so existing users keep their saved layout.
+const STORAGE_KEY = 'qdadm-debug-bar'
+</script>
+
+<template>
+  <QddebugBar
+    :bridge="bridge"
+    :z-index="zIndex"
+    :storage-key="STORAGE_KEY"
+    :panels="adminPanels"
+    :collector-meta="adminPanelsMeta"
+  />
+</template>

package/src/modules/debug/components/adminPanelsConfig.ts

@@ -0,0 +1,42 @@
+/**
+ * Admin panel registry — extracted from `DebugBar.vue` so host shells
+ * that own a shared bridge (qdcms demo) can merge these panels with
+ * their own and feed them to a single `<DebugBar />` instead of two.
+ *
+ * The keys MUST match what `bridge.collectors` keys into — both the
+ * lowercase short names (`zones`, `auth`, …) and the legacy
+ * collectorName strings (`ZonesCollector`, …) are aliased here so
+ * the bar resolves them under either form.
+ */
+
+import type { Component } from 'vue'
+import type { CollectorMeta } from '@quazardous/qddebug'
+import ZonesPanel from './panels/ZonesPanel.vue'
+import AuthPanel from './panels/AuthPanel.vue'
+import EntitiesPanel from './panels/EntitiesPanel.vue'
+import RouterPanel from './panels/RouterPanel.vue'
+import I18nPanel from './panels/I18nPanel.vue'
+
+export const adminPanels: Record<string, Component> = {
+  zones: ZonesPanel,
+  ZonesCollector: ZonesPanel,
+  auth: AuthPanel,
+  AuthCollector: AuthPanel,
+  entities: EntitiesPanel,
+  EntitiesCollector: EntitiesPanel,
+  router: RouterPanel,
+  RouterCollector: RouterPanel,
+  i18n: I18nPanel,
+  I18nCollector: I18nPanel,
+}
+
+export const adminPanelsMeta: Record<string, CollectorMeta> = {
+  zones: { icon: 'pi-th-large', label: 'Zones', color: '#06b6d4' },
+  ZonesCollector: { icon: 'pi-th-large', label: 'Zones', color: '#06b6d4' },
+  auth: { icon: 'pi-user', label: 'Auth', color: '#10b981' },
+  AuthCollector: { icon: 'pi-user', label: 'Auth', color: '#10b981' },
+  entities: { icon: 'pi-database', label: 'Entities', color: '#3b82f6' },
+  EntitiesCollector: { icon: 'pi-database', label: 'Entities', color: '#3b82f6' },
+  router: { icon: 'pi-directions', label: 'Router', color: '#ec4899' },
+  RouterCollector: { icon: 'pi-directions', label: 'Router', color: '#ec4899' },
+}

package/src/modules/debug/components/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Debug Components — qdadm.
+ *
+ * Re-exports the qdadm DebugBar wrapper and the qddebug ObjectTree to
+ * preserve qdadm's public API.
+ */
+
+export { default as DebugBar } from './DebugBar.vue'
+export { ObjectTree } from '@quazardous/qddebug'