qdadm 0.53.2 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.53.2",
+  "version": "0.55.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "./editors": "./src/editors/index.js",
     "./module": "./src/module/index.js",
     "./utils": "./src/utils/index.js",
-    "./debug": "./src/debug/index.js",
+    "./modules/debug": "./src/modules/debug/index.js",
     "./styles": "./src/styles/index.scss",
     "./styles/breakpoints": "./src/styles/_breakpoints.scss",
     "./gen": "./src/gen/index.js",

package/src/chain/ActiveStack.js

@@ -1,74 +1,170 @@
 /**
- * ActiveStack - Reactive container for the active navigation stack
+ * ActiveStack - Sync navigation context from route
  *
- * Simple container rebuilt from route by useActiveStack.
- * Each level: { entity, id, data, label }
+ * Pure vanilla JS container using SignalBus for events.
+ * Rebuilt from route.meta on navigation.
+ *
+ * Stack only contains levels WITH IDs (entities with context).
+ * - /bots/bot-xyz/commands → stack = [bots(id:bot-xyz)]
+ * - /bots/bot-xyz/commands/cmd-123 → stack = [bots(id:bot-xyz), commands(id:cmd-123)]
+ *
+ * Signals emitted:
+ * - stack:change - when stack levels change
+ *
+ * For Vue reactivity, use useActiveStack composable.
  *
  * @example
- * // Route /books/123/loans → Stack:
- * [
- *   { entity: 'books', id: '123', data: null, label: 'Books' },
- *   { entity: 'loans', id: null, data: null, label: 'Loans' }
- * ]
+ * const stack = new ActiveStack(signalBus)
+ * signalBus.on('stack:change', ({ levels }) => console.log('Stack:', levels))
+ * stack.set([{ entity: 'bots', param: 'uuid', id: 'bot-123' }])
  */
 
-import { ref, computed } from 'vue'
+/**
+ * @typedef {Object} StackLevel
+ * @property {string} entity - Entity name (e.g., 'bots', 'commands')
+ * @property {string} param - Route param name (e.g., 'uuid', 'id')
+ * @property {string|null} foreignKey - Foreign key field for parent relation (null for root)
+ * @property {string|null} id - Entity ID from route params
+ */
 
 export class ActiveStack {
-  constructor() {
-    this._stack = ref([])
+  /**
+   * @param {import('../kernel/SignalBus.js').SignalBus} [signalBus] - Optional signal bus for events
+   */
+  constructor(signalBus = null) {
+    /** @type {StackLevel[]} */
+    this._levels = []
+
+    /** @type {import('../kernel/SignalBus.js').SignalBus|null} */
+    this._signalBus = signalBus
   }
 
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Mutators
+  // ═══════════════════════════════════════════════════════════════════════════
+
   /**
    * Replace entire stack (called on route change)
+   * Only emits if levels actually changed (prevents duplicate emissions)
+   * @param {StackLevel[]} levels
+   *
+   * BUG: Still getting duplicate signals (4 instead of 2) on navigation.
+   * Equality check should prevent this but something is triggering multiple calls
+   * with different levels. Need to investigate router.afterEach timing.
    */
   set(levels) {
-    this._stack.value = levels
+    // Quick equality check - same length and same entity+id pairs
+    if (this._levelsEqual(levels)) {
+      return
+    }
+    this._levels = levels
+    this._emit('stack:change', { levels: this._levels })
   }
 
   /**
-   * Update a level's data and label
+   * Check if new levels match current levels
+   * @param {StackLevel[]} newLevels
+   * @returns {boolean}
+   * @private
    */
-  updateLevel(index, data, label) {
-    if (index < 0 || index >= this._stack.value.length) return
-    const newStack = [...this._stack.value]
-    newStack[index] = { ...newStack[index], data, label }
-    this._stack.value = newStack
+  _levelsEqual(newLevels) {
+    if (this._levels.length !== newLevels.length) return false
+    for (let i = 0; i < this._levels.length; i++) {
+      const curr = this._levels[i]
+      const next = newLevels[i]
+      if (curr.entity !== next.entity || curr.id !== next.id) {
+        return false
+      }
+    }
+    return true
   }
 
   /**
-   * Find and update level by entity name
+   * Clear the stack
+   * Only emits if not already empty
    */
-  updateByEntity(entity, data, label) {
-    const index = this._stack.value.findIndex(l => l.entity === entity)
-    if (index !== -1) {
-      this.updateLevel(index, data, label)
-    }
+  clear() {
+    if (this._levels.length === 0) return
+    this._levels = []
+    this._emit('stack:change', { levels: this._levels })
   }
 
-  clear() {
-    this._stack.value = []
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Accessors
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * All stack levels
+   * @returns {StackLevel[]}
+   */
+  getLevels() {
+    return this._levels
   }
 
-  // Computed accessors
-  get levels() {
-    return computed(() => this._stack.value)
+  /**
+   * Get level by index
+   * @param {number} index
+   * @returns {StackLevel|null}
+   */
+  getLevel(index) {
+    return this._levels[index] ?? null
   }
 
-  get current() {
-    return computed(() => this._stack.value.at(-1) || null)
+  /**
+   * Get level by entity name
+   * @param {string} entity
+   * @returns {StackLevel|null}
+   */
+  getLevelByEntity(entity) {
+    return this._levels.find(l => l.entity === entity) ?? null
+  }
+
+  /**
+   * Current (deepest) level
+   * @returns {StackLevel|null}
+   */
+  getCurrent() {
+    return this._levels.at(-1) ?? null
+  }
+
+  /**
+   * Parent level (one above current)
+   * @returns {StackLevel|null}
+   */
+  getParent() {
+    return this._levels.at(-2) ?? null
   }
 
-  get parent() {
-    return computed(() => this._stack.value.at(-2) || null)
+  /**
+   * Root level (first/topmost)
+   * @returns {StackLevel|null}
+   */
+  getRoot() {
+    return this._levels[0] ?? null
   }
 
-  get root() {
-    return computed(() => this._stack.value[0] || null)
+  /**
+   * Stack depth
+   * @returns {number}
+   */
+  getDepth() {
+    return this._levels.length
   }
 
-  get depth() {
-    return computed(() => this._stack.value.length)
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Internal
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Emit event via SignalBus
+   * @param {string} signal
+   * @param {*} payload
+   * @private
+   */
+  _emit(signal, payload) {
+    if (this._signalBus) {
+      this._signalBus.emit(signal, payload)
+    }
   }
 }
 

package/src/chain/StackHydrator.js

@@ -0,0 +1,279 @@
+/**
+ * StackHydrator - Async hydration layer for ActiveStack
+ *
+ * Pure vanilla JS using SignalBus for events.
+ * Listens to stack:change and hydrates each level with entity data.
+ *
+ * Signals emitted:
+ * - stack:hydration:change - when a level's hydration completes { levels }
+ *
+ * For Vue reactivity, use useStackHydrator composable.
+ *
+ * @example
+ * const hydrator = new StackHydrator(activeStack, orchestrator, signalBus)
+ * signalBus.on('stack:hydration:change', (event) => console.log('Hydrated:', event.data.levels))
+ */
+
+/**
+ * @typedef {Object} HydratedLevel
+ * @property {string} entity - Entity name
+ * @property {string} param - Route param name
+ * @property {string|null} foreignKey - Foreign key field
+ * @property {string|null} id - Entity ID
+ * @property {Promise<void>} promise - Resolves when hydrated
+ * @property {boolean} loading - True while fetching
+ * @property {boolean} hydrated - True when data is loaded
+ * @property {Error|null} error - Error if fetch failed
+ * @property {Record<string, any>|null} data - Entity data
+ * @property {string|null} label - Resolved label
+ */
+
+export class StackHydrator {
+  /**
+   * @param {import('./ActiveStack.js').ActiveStack} activeStack
+   * @param {import('../orchestrator/Orchestrator.js').Orchestrator} orchestrator
+   * @param {import('../kernel/SignalBus.js').SignalBus} [signalBus]
+   */
+  constructor(activeStack, orchestrator, signalBus = null) {
+    this._activeStack = activeStack
+    this._orchestrator = orchestrator
+    this._signalBus = signalBus
+
+    /** @type {HydratedLevel[]} */
+    this._levels = []
+
+    // Listen to stack changes via SignalBus
+    // QuarKernel passes (event, ctx) where event.data contains the payload
+    if (signalBus) {
+      this._unsubscribe = signalBus.on('stack:change', (event) => {
+        const levels = event.data?.levels
+        if (levels) {
+          this._onStackChange(levels)
+        }
+      })
+    }
+    // Note: No initial check needed - stack is always empty at construction time
+    // The Kernel's router.afterEach will trigger stack:change after navigation
+  }
+
+  /**
+   * Cleanup
+   */
+  destroy() {
+    if (this._unsubscribe) {
+      this._unsubscribe()
+      this._unsubscribe = null
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Stack change handling
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Handle stack change - rebuild hydrated levels
+   * @param {import('./ActiveStack.js').StackLevel[]} stackLevels
+   * @private
+   */
+  _onStackChange(stackLevels) {
+    // Create new hydrated levels (each starts its own async hydration)
+    this._levels = stackLevels.map((level, index) =>
+      this._createHydratedLevel(level, index)
+    )
+    // Don't emit here - each level will emit when hydration completes
+  }
+
+  /**
+   * Create a hydrated level with its own promise
+   * @param {import('./ActiveStack.js').StackLevel} stackLevel
+   * @param {number} index
+   * @returns {HydratedLevel}
+   * @private
+   */
+  _createHydratedLevel(stackLevel, index) {
+    const level = {
+      // Sync config (copied from stack)
+      entity: stackLevel.entity,
+      param: stackLevel.param,
+      foreignKey: stackLevel.foreignKey,
+      id: stackLevel.id,
+
+      // Async state
+      promise: null,
+      loading: false,
+      hydrated: false,
+      error: null,
+      data: null,
+      label: null,
+    }
+
+    // Start hydration and store promise
+    level.promise = this._hydrate(level)
+
+    return level
+  }
+
+  /**
+   * Hydrate a single level
+   * @param {HydratedLevel} level
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _hydrate(level) {
+    // All levels in stack have IDs (that's the new contract)
+    // But check anyway for safety
+    if (!level.id) {
+      const manager = this._orchestrator?.get(level.entity)
+      level.label = manager?.labelPlural ?? level.entity
+      level.hydrated = true
+      this._emitChange()
+      return
+    }
+
+    level.loading = true
+    // Don't emit on loading start - reduces signal noise
+
+    try {
+      const manager = this._orchestrator?.get(level.entity)
+      if (!manager) {
+        level.label = level.id
+        level.hydrated = true
+        level.loading = false
+        this._emitChange()
+        return
+      }
+
+      // Fetch entity data
+      level.data = await manager.get(level.id)
+      level.label = manager.getEntityLabel?.(level.data) ?? level.id
+      level.hydrated = true
+    } catch (err) {
+      level.error = err
+      level.label = level.id // Fallback to ID
+      level.hydrated = true // Mark as hydrated even on error
+    } finally {
+      level.loading = false
+      this._emitChange()
+    }
+  }
+
+  /**
+   * Emit hydration change signal
+   * @private
+   */
+  _emitChange() {
+    this._emit('stack:hydration:change', { levels: this._levels })
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Accessors
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * All hydrated levels
+   * @returns {HydratedLevel[]}
+   */
+  getLevels() {
+    return this._levels
+  }
+
+  /**
+   * Get hydrated level by index
+   * @param {number} index
+   * @returns {HydratedLevel|null}
+   */
+  getLevel(index) {
+    return this._levels[index] ?? null
+  }
+
+  /**
+   * Get hydrated level by entity name
+   * @param {string} entity
+   * @returns {HydratedLevel|null}
+   */
+  getLevelByEntity(entity) {
+    return this._levels.find(l => l.entity === entity) ?? null
+  }
+
+  /**
+   * Current hydrated level
+   * @returns {HydratedLevel|null}
+   */
+  getCurrent() {
+    return this._levels.at(-1) ?? null
+  }
+
+  /**
+   * Parent hydrated level
+   * @returns {HydratedLevel|null}
+   */
+  getParent() {
+    return this._levels.at(-2) ?? null
+  }
+
+  /**
+   * Root hydrated level
+   * @returns {HydratedLevel|null}
+   */
+  getRoot() {
+    return this._levels[0] ?? null
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Manual update (for pages that load their own data)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Manually set data for current level (skips fetch)
+   * Used by pages that already loaded the entity
+   * @param {Record<string, any>} data
+   */
+  setCurrentData(data) {
+    const level = this.getCurrent()
+    if (!level) return
+
+    const manager = this._orchestrator?.get(level.entity)
+    level.data = data
+    level.label = manager?.getEntityLabel?.(data) ?? level.id
+    level.hydrated = true
+    level.loading = false
+    this._emit('stack:hydrated', { level })
+    this._emit('stack:hydration:change', { levels: this._levels })
+  }
+
+  /**
+   * Manually set data for a level by entity name
+   * @param {string} entity
+   * @param {Record<string, any>} data
+   */
+  setEntityData(entity, data) {
+    const level = this.getLevelByEntity(entity)
+    if (!level) return
+
+    const manager = this._orchestrator?.get(entity)
+    level.data = data
+    level.label = manager?.getEntityLabel?.(data) ?? level.id
+    level.hydrated = true
+    level.loading = false
+    this._emit('stack:hydrated', { level })
+    this._emit('stack:hydration:change', { levels: this._levels })
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // Internal
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Emit event via SignalBus
+   * @param {string} signal
+   * @param {*} payload
+   * @private
+   */
+  _emit(signal, payload) {
+    if (this._signalBus) {
+      this._signalBus.emit(signal, payload)
+    }
+  }
+}
+
+export default StackHydrator

package/src/chain/index.js

@@ -2,11 +2,18 @@
  * Chain Module - Active navigation stack management
  *
  * Provides:
- * - ActiveStack: Reactive container for current navigation stack
- * - useActiveStack: Composable to build and access the stack
+ * - ActiveStack: Sync container for navigation context (entity, param, foreignKey, id)
+ * - StackHydrator: Async layer for entity data and labels
+ * - useActiveStack: Composable to build and access the sync stack
+ * - useStackHydrator: Composable to access hydrated data
  *
  * @module chain
  */
 
+// Sync stack (context only)
 export { ActiveStack } from './ActiveStack.js'
 export { useActiveStack } from './useActiveStack.js'
+
+// Async hydration (data + labels)
+export { StackHydrator } from './StackHydrator.js'
+export { useStackHydrator } from './useStackHydrator.js'