qdadm 0.29.0 → 0.31.0

package/src/debug/LocalStorageAdapter.js

@@ -0,0 +1,150 @@
+/**
+ * LocalStorageAdapter - Debug settings persistence
+ *
+ * Persists debug bridge state (enabled, collector settings) to localStorage.
+ * Allows debug settings to survive page refreshes.
+ *
+ * @example
+ * import { createDebugBridge, LocalStorageAdapter } from '@qdadm/core/debug'
+ *
+ * const debug = createDebugBridge()
+ * const storage = new LocalStorageAdapter('qdadm-debug')
+ * storage.attach(debug) // Auto-saves on change, restores on load
+ */
+
+/**
+ * LocalStorage adapter for debug settings persistence
+ */
+export class LocalStorageAdapter {
+  /**
+   * Create a new LocalStorageAdapter
+   * @param {string} key - localStorage key prefix
+   */
+  constructor(key = 'qdadm-debug') {
+    this.key = key
+    this._bridge = null
+    this._unwatch = null
+  }
+
+  /**
+   * Get the full key for a setting
+   * @param {string} name - Setting name
+   * @returns {string} Full localStorage key
+   */
+  _getKey(name) {
+    return `${this.key}:${name}`
+  }
+
+  /**
+   * Get a value from localStorage
+   * @param {string} name - Setting name
+   * @param {*} defaultValue - Default if not found
+   * @returns {*} The value
+   */
+  get(name, defaultValue = null) {
+    try {
+      const stored = localStorage.getItem(this._getKey(name))
+      return stored !== null ? JSON.parse(stored) : defaultValue
+    } catch {
+      return defaultValue
+    }
+  }
+
+  /**
+   * Set a value in localStorage
+   * @param {string} name - Setting name
+   * @param {*} value - Value to store
+   */
+  set(name, value) {
+    try {
+      localStorage.setItem(this._getKey(name), JSON.stringify(value))
+    } catch {
+      // localStorage might be full or disabled
+    }
+  }
+
+  /**
+   * Remove a value from localStorage
+   * @param {string} name - Setting name
+   */
+  remove(name) {
+    localStorage.removeItem(this._getKey(name))
+  }
+
+  /**
+   * Clear all debug settings
+   */
+  clear() {
+    const prefix = this.key + ':'
+    const keys = []
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i)
+      if (key && key.startsWith(prefix)) {
+        keys.push(key)
+      }
+    }
+    keys.forEach(key => localStorage.removeItem(key))
+  }
+
+  /**
+   * Attach to a DebugBridge and sync state
+   * Restores saved state and watches for changes
+   * @param {DebugBridge} bridge - The debug bridge to attach to
+   * @returns {LocalStorageAdapter} this for chaining
+   */
+  attach(bridge) {
+    this._bridge = bridge
+
+    // Restore saved enabled state
+    const savedEnabled = this.get('enabled')
+    if (savedEnabled !== null && bridge.enabled.value !== savedEnabled) {
+      bridge.enabled.value = savedEnabled
+    }
+
+    // Watch for enabled changes (if Vue's watch is available)
+    if (typeof window !== 'undefined' && window.__VUE_WATCH__) {
+      // In a real Vue app, use watch from vue
+    }
+
+    return this
+  }
+
+  /**
+   * Detach from the debug bridge
+   */
+  detach() {
+    if (this._unwatch) {
+      this._unwatch()
+      this._unwatch = null
+    }
+    this._bridge = null
+  }
+
+  /**
+   * Save current bridge state
+   */
+  save() {
+    if (!this._bridge) return
+    this.set('enabled', this._bridge.enabled.value)
+  }
+
+  /**
+   * Restore bridge state from localStorage
+   */
+  restore() {
+    if (!this._bridge) return
+    const savedEnabled = this.get('enabled')
+    if (savedEnabled !== null) {
+      this._bridge.enabled.value = savedEnabled
+    }
+  }
+}
+
+/**
+ * Factory function to create a LocalStorageAdapter
+ * @param {string} key - localStorage key prefix
+ * @returns {LocalStorageAdapter}
+ */
+export function createLocalStorageAdapter(key) {
+  return new LocalStorageAdapter(key)
+}

package/src/debug/SignalCollector.js

@@ -0,0 +1,87 @@
+/**
+ * SignalCollector - Debug collector for SignalBus events
+ *
+ * Extends the base Collector to capture all signals emitted through the SignalBus.
+ * Uses wildcard subscription to capture all domain:action events.
+ *
+ * @example
+ * const collector = new SignalCollector({ maxEntries: 50 })
+ * collector.install(ctx) // ctx.signals is the SignalBus
+ *
+ * // Later, retrieve captured signals
+ * collector.getEntries() // [{ name, data, source, timestamp }, ...]
+ */
+
+import { Collector } from './Collector.js'
+
+/**
+ * Collector for SignalBus events
+ *
+ * Records all signals with their name, data, and source for debugging.
+ * Uses the `*:*` wildcard pattern to capture all signals following the
+ * domain:action naming convention.
+ */
+export class SignalCollector extends Collector {
+  /**
+   * Collector name for identification
+   * @type {string}
+   */
+  static name = 'signals'
+
+  /**
+   * Internal install - subscribe to all signals
+   *
+   * @param {object} ctx - Context object from Kernel
+   * @param {import('../kernel/SignalBus.js').SignalBus} ctx.signals - SignalBus instance
+   * @protected
+   */
+  _doInstall(ctx) {
+    if (!ctx?.signals) {
+      console.warn('[SignalCollector] No signals bus found in context')
+      return
+    }
+
+    // Subscribe to all signals using wildcard pattern
+    // QuarKernel supports wildcards with the configured delimiter (:)
+    // '*:*' matches any domain:action signal
+    this._unsubscribe = ctx.signals.on('*:*', (event) => {
+      this.record({
+        name: event.name,
+        data: event.data,
+        source: event.data?.source ?? null
+      })
+    })
+  }
+
+  /**
+   * Internal uninstall - cleanup subscription
+   * @protected
+   */
+  _doUninstall() {
+    if (this._unsubscribe) {
+      this._unsubscribe()
+      this._unsubscribe = null
+    }
+  }
+
+  /**
+   * Get entries filtered by signal name pattern
+   *
+   * @param {string|RegExp} pattern - Pattern to match signal names
+   * @returns {Array<object>} Filtered entries
+   */
+  getByPattern(pattern) {
+    const regex = pattern instanceof RegExp ? pattern : new RegExp(pattern)
+    return this.entries.filter((entry) => regex.test(entry.name))
+  }
+
+  /**
+   * Get entries for a specific signal domain
+   *
+   * @param {string} domain - Domain prefix (e.g., 'entity', 'auth', 'books')
+   * @returns {Array<object>} Entries matching the domain
+   */
+  getByDomain(domain) {
+    return this.entries.filter((entry) => entry.name.startsWith(`${domain}:`))
+  }
+}

package/src/debug/ToastCollector.js

@@ -0,0 +1,82 @@
+/**
+ * ToastCollector - Captures toast notifications via signal bus
+ *
+ * This collector listens to toast signals emitted on the signal bus
+ * and records them for display in the debug panel.
+ *
+ * Toast signals should follow the pattern:
+ * - signals.emit('toast:success', { summary: '...', detail: '...' })
+ * - signals.emit('toast:error', { summary: '...', detail: '...' })
+ * - signals.emit('toast:info', { summary: '...', detail: '...' })
+ * - signals.emit('toast:warn', { summary: '...', detail: '...' })
+ *
+ * Use with ToastBridge module which handles displaying toasts via PrimeVue.
+ *
+ * @example
+ * const collector = new ToastCollector()
+ * collector.install(ctx)
+ * // Toasts emitted via signals are now automatically recorded
+ */
+
+import { Collector } from './Collector.js'
+
+/**
+ * Collector for toast notifications
+ */
+export class ToastCollector extends Collector {
+  /**
+   * Collector name identifier
+   * @type {string}
+   */
+  static name = 'toasts'
+
+  /**
+   * Internal install - subscribe to toast signals
+   * @param {object} ctx - Context object
+   * @protected
+   */
+  _doInstall(ctx) {
+    // Listen for toast signals on the signal bus
+    if (ctx?.signals) {
+      this._unsubscribe = ctx.signals.on('toast:*', (event) => {
+        this.record({
+          severity: event.name.split(':')[1], // toast:success -> success
+          summary: event.data?.summary,
+          detail: event.data?.detail,
+          life: event.data?.life,
+          emitter: event.data?.emitter || 'unknown'
+        })
+      })
+    } else {
+      console.warn('[ToastCollector] No signals bus in context - toast recording disabled')
+    }
+  }
+
+  /**
+   * Internal uninstall - cleanup
+   * @protected
+   */
+  _doUninstall() {
+    if (this._unsubscribe) {
+      this._unsubscribe()
+      this._unsubscribe = null
+    }
+  }
+
+  /**
+   * Get entries by severity
+   * @param {string} severity - Severity level (success, info, warn, error)
+   * @returns {Array<object>} Filtered entries
+   */
+  getBySeverity(severity) {
+    return this.entries.filter((entry) => entry.severity === severity)
+  }
+
+  /**
+   * Get error toasts count for badge
+   * @returns {number}
+   */
+  getErrorCount() {
+    return this.entries.filter((e) => e.severity === 'error').length
+  }
+}

package/src/debug/ZonesCollector.js

@@ -0,0 +1,300 @@
+/**
+ * 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 } from './Collector.js'
+
+/**
+ * Collector for Zone Registry state visualization
+ */
+export class ZonesCollector extends Collector {
+  /**
+   * Collector name identifier
+   * @type {string}
+   */
+  static name = 'zones'
+
+  /**
+   * This collector shows state, not events
+   * @type {boolean}
+   */
+  static records = false
+
+  constructor(options = {}) {
+    super(options)
+    this._registry = null
+    this._ctx = null
+    this._highlightedZone = null
+    this._overlays = new Map()
+    this._showCurrentPageOnly = options.showCurrentPageOnly ?? true
+    this._showInternalZones = options.showInternalZones ?? false
+    this._routerCleanup = null
+  }
+
+  /**
+   * Internal install - get zone registry reference and subscribe to navigation
+   * @param {object} ctx - Context object
+   * @protected
+   */
+  _doInstall(ctx) {
+    this._ctx = ctx
+    this._registry = ctx.zones
+    if (!this._registry) {
+      console.warn('[ZonesCollector] No zone registry found in context')
+    }
+    this._setupRouterListener()
+  }
+
+  /**
+   * Setup router listener for navigation changes
+   * @private
+   */
+  _setupRouterListener() {
+    const router = this._ctx?.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
+   */
+  _doUninstall() {
+    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 {string} zoneName - Zone name to check
+   * @returns {boolean}
+   *
+   * Note: Internal zones (prefixed with _) are currently considered always on page
+   * since they're typically global (app:debug, app:toasts). If contextual internal
+   * zones are needed later, consider using a different prefix convention (e.g. `__`
+   * for global, `_` for contextual) or adding a `global` flag to zone config.
+   */
+  isZoneOnPage(zoneName) {
+    // Internal zones are global, always considered "on page"
+    // TODO: revisit if contextual internal zones are needed
+    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
+   * @type {boolean}
+   */
+  get showCurrentPageOnly() {
+    return this._showCurrentPageOnly
+  }
+
+  set showCurrentPageOnly(value) {
+    this._showCurrentPageOnly = value
+  }
+
+  /**
+   * Toggle current page filter
+   * @returns {boolean} New filter state
+   */
+  toggleFilter() {
+    this._showCurrentPageOnly = !this._showCurrentPageOnly
+    return this._showCurrentPageOnly
+  }
+
+  /**
+   * Get/set filter for internal zones (prefixed with _)
+   * @type {boolean}
+   */
+  get showInternalZones() {
+    return this._showInternalZones
+  }
+
+  set showInternalZones(value) {
+    this._showInternalZones = value
+  }
+
+  /**
+   * Toggle internal zones filter
+   * @returns {boolean} New filter state
+   */
+  toggleInternalFilter() {
+    this._showInternalZones = !this._showInternalZones
+    return this._showInternalZones
+  }
+
+  /**
+   * Get badge - show number of zones (filtered if filter active)
+   * @returns {number}
+   */
+  getBadge() {
+    if (!this._registry) return 0
+    let count = 0
+    for (const [name] of this._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 {boolean} [forceAll=false] - If true, ignore filter and return all zones
+   * @returns {Array<object>} Zone info array
+   */
+  getEntries(forceAll = false) {
+    if (!this._registry) return []
+
+    const zones = []
+    for (const [name, config] of this._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 = this._registry.getBlocks(name)
+      zones.push({
+        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 {string} zoneName - Zone name to highlight
+   */
+  highlightZone(zoneName) {
+    this.clearHighlights()
+    this._highlightedZone = zoneName
+
+    // Find zone elements by data attribute
+    // Note: CSS.escape() handles special characters like colons in zone names
+    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() {
+    this._overlays.forEach(overlay => overlay.remove())
+    this._overlays.clear()
+    this._highlightedZone = null
+  }
+
+  /**
+   * Get currently highlighted zone
+   * @returns {string|null}
+   */
+  getHighlightedZone() {
+    return this._highlightedZone
+  }
+
+  /**
+   * Toggle zone highlight
+   * @param {string} zoneName - Zone name
+   * @returns {boolean} Whether zone is now highlighted
+   */
+  toggleHighlight(zoneName) {
+    if (this._highlightedZone === zoneName) {
+      this.clearHighlights()
+      return false
+    } else {
+      this.highlightZone(zoneName)
+      return true
+    }
+  }
+}