qdadm 0.15.1 → 0.17.0

package/src/kernel/SignalBus.js

@@ -0,0 +1,180 @@
+/**
+ * SignalBus - Wrapper around QuarKernel for qdadm event-driven architecture
+ *
+ * Provides a clean API for entity lifecycle events and cross-component communication.
+ * Uses QuarKernel's wildcard support for flexible event subscriptions.
+ *
+ * Signal naming conventions:
+ * - Generic CRUD: entity:created, entity:updated, entity:deleted
+ * - Entity-specific: {entityName}:created, {entityName}:updated, {entityName}:deleted
+ *
+ * Wildcard subscriptions (via QuarKernel):
+ * - 'entity:*' matches entity:created, entity:updated, entity:deleted
+ * - 'books:*' matches books:created, books:updated, books:deleted
+ * - '*:created' matches any entity creation
+ */
+
+import { createKernel } from '@quazardous/quarkernel'
+
+/**
+ * Signal names for entity operations
+ */
+export const SIGNALS = {
+  // Generic entity lifecycle signals
+  ENTITY_CREATED: 'entity:created',
+  ENTITY_UPDATED: 'entity:updated',
+  ENTITY_DELETED: 'entity:deleted',
+
+  // Pattern for entity-specific signals
+  // Use buildSignal(entityName, action) for these
+}
+
+/**
+ * Actions for entity signals
+ */
+export const SIGNAL_ACTIONS = {
+  CREATED: 'created',
+  UPDATED: 'updated',
+  DELETED: 'deleted',
+}
+
+/**
+ * Build an entity-specific signal name
+ * @param {string} entityName - Entity name (e.g., 'books', 'users')
+ * @param {string} action - Action from SIGNAL_ACTIONS
+ * @returns {string} Signal name (e.g., 'books:created')
+ */
+export function buildSignal(entityName, action) {
+  return `${entityName}:${action}`
+}
+
+/**
+ * SignalBus class - wraps QuarKernel for qdadm
+ */
+export class SignalBus {
+  /**
+   * @param {object} options - QuarKernel options
+   * @param {boolean} options.debug - Enable debug logging
+   */
+  constructor(options = {}) {
+    this._kernel = createKernel({
+      delimiter: ':',
+      wildcard: true,
+      errorBoundary: true,
+      debug: options.debug ?? false,
+    })
+  }
+
+  /**
+   * Emit a signal with payload
+   * @param {string} signal - Signal name
+   * @param {*} payload - Signal payload (typically { entity, data, context })
+   * @returns {Promise<void>}
+   */
+  async emit(signal, payload) {
+    return this._kernel.emit(signal, payload)
+  }
+
+  /**
+   * Subscribe to a signal
+   * @param {string} signal - Signal name (supports wildcards via QuarKernel)
+   * @param {Function} handler - Handler function (event, ctx) => void
+   * @param {object} options - Listener options
+   * @param {number} options.priority - Listener priority (higher = earlier)
+   * @param {string} options.id - Unique listener ID
+   * @param {string|string[]} options.after - Run after these listener IDs
+   * @param {boolean} options.once - Remove after first call
+   * @returns {Function} Unbind function
+   */
+  on(signal, handler, options = {}) {
+    return this._kernel.on(signal, handler, options)
+  }
+
+  /**
+   * Unsubscribe from a signal
+   * @param {string} signal - Signal name
+   * @param {Function} handler - Handler function to remove (optional, removes all if omitted)
+   */
+  off(signal, handler) {
+    this._kernel.off(signal, handler)
+  }
+
+  /**
+   * Subscribe to a signal once (Promise-based)
+   * @param {string} signal - Signal name
+   * @param {object} options - Options
+   * @param {number} options.timeout - Timeout in ms
+   * @returns {Promise<object>} Event object
+   */
+  once(signal, options = {}) {
+    return this._kernel.once(signal, options)
+  }
+
+  /**
+   * Emit an entity lifecycle signal
+   * @param {string} entityName - Entity name
+   * @param {string} action - Action from SIGNAL_ACTIONS
+   * @param {object} data - Entity data
+   * @returns {Promise<void>}
+   */
+  async emitEntity(entityName, action, data) {
+    const specificSignal = buildSignal(entityName, action)
+    const genericSignal = buildSignal('entity', action)
+
+    // Emit both specific and generic signals
+    // Specific first, then generic
+    await this.emit(specificSignal, { entity: entityName, data })
+    await this.emit(genericSignal, { entity: entityName, data })
+  }
+
+  /**
+   * Get listener count for a signal
+   * @param {string} signal - Signal name (optional, total if omitted)
+   * @returns {number}
+   */
+  listenerCount(signal) {
+    return this._kernel.listenerCount(signal)
+  }
+
+  /**
+   * Get all registered signal names
+   * @returns {string[]}
+   */
+  signalNames() {
+    return this._kernel.eventNames()
+  }
+
+  /**
+   * Remove all listeners
+   * @param {string} signal - Signal name (optional, all if omitted)
+   */
+  offAll(signal) {
+    this._kernel.offAll(signal)
+  }
+
+  /**
+   * Enable/disable debug mode
+   * @param {boolean} enabled
+   */
+  debug(enabled) {
+    this._kernel.debug(enabled)
+  }
+
+  /**
+   * Get the underlying QuarKernel instance
+   * Used for sharing the kernel with HookRegistry
+   * @returns {QuarKernel}
+   */
+  getKernel() {
+    return this._kernel
+  }
+}
+
+/**
+ * Factory function to create a SignalBus instance
+ * @param {object} options - SignalBus options
+ * @returns {SignalBus}
+ */
+export function createSignalBus(options = {}) {
+  return new SignalBus(options)
+}

package/src/kernel/index.js

@@ -5,3 +5,10 @@
  */
 
 export { Kernel } from './Kernel.js'
+export {
+  SignalBus,
+  createSignalBus,
+  SIGNALS,
+  SIGNAL_ACTIONS,
+  buildSignal,
+} from './SignalBus.js'

package/src/module/moduleRegistry.js

@@ -36,6 +36,13 @@ const entityConfigs = new Map()  // Entity declarations from modules
 // Configurable section order (set via setSectionOrder or bootstrap)
 let sectionOrder = []
 
+// Altered nav sections after menu:alter hook
+// null means not yet altered, use raw navSections
+let alteredNavSections = null
+
+// Promise for in-flight alteration (prevents concurrent calls)
+let alterationPromise = null
+
 /**
  * Registry API passed to module init functions
  */
@@ -52,9 +59,10 @@ const registry = {
    * @param {string} options.parent.foreignKey - Foreign key field (e.g., 'book_id')
    * @param {string} [options.parent.itemRoute] - Override parent item route (auto: parentEntity.routePrefix + '-edit')
    * @param {string} [options.label] - Label for navlinks (defaults to entity labelPlural)
+   * @param {string} [options.layout] - Default layout type for routes ('list', 'form', 'dashboard', 'base')
    */
   addRoutes(prefix, moduleRoutes, options = {}) {
-    const { entity, parent, label } = options
+    const { entity, parent, label, layout } = options
     const prefixedRoutes = moduleRoutes.map(route => ({
       ...route,
       path: route.path ? `${prefix}/${route.path}` : prefix,
@@ -62,7 +70,9 @@ const registry = {
         ...route.meta,
         ...(entity && { entity }),
         ...(parent && { parent }),
-        ...(label && { navLabel: label })
+        ...(label && { navLabel: label }),
+        // Layout can be set per-route or inherited from options
+        ...((route.meta?.layout || layout) && { layout: route.meta?.layout || layout })
       }
     }))
     routes.push(...prefixedRoutes)
@@ -154,9 +164,10 @@ export function getRoutes() {
 }
 
 /**
- * Get navigation sections in order
+ * Build raw navigation sections from registered nav items (before alteration)
+ * @returns {Array<{title: string, items: Array}>}
  */
-export function getNavSections() {
+function buildRawNavSections() {
   const sections = []
 
   // First add sections in the configured order
@@ -164,7 +175,7 @@ export function getNavSections() {
     if (navSections.has(title)) {
       sections.push({
         title,
-        items: navSections.get(title)
+        items: [...navSections.get(title)]  // Clone items array
       })
     }
   }
@@ -172,13 +183,118 @@ export function getNavSections() {
   // Add any sections not in the predefined order
   for (const [title, items] of navSections) {
     if (!sectionOrder.includes(title)) {
-      sections.push({ title, items })
+      sections.push({ title, items: [...items] })  // Clone items array
     }
   }
 
   return sections
 }
 
+/**
+ * Get navigation sections in order
+ *
+ * Returns altered sections if menu:alter hook has been invoked,
+ * otherwise returns raw sections from module registrations.
+ *
+ * @returns {Array<{title: string, items: Array}>}
+ */
+export function getNavSections() {
+  // Return altered sections if available, otherwise build from raw
+  if (alteredNavSections !== null) {
+    return alteredNavSections
+  }
+  return buildRawNavSections()
+}
+
+/**
+ * Invoke menu:alter hook to allow modules to modify navigation structure
+ *
+ * Called lazily by useNavigation on first access. Modules can register
+ * handlers for 'menu:alter' hook to add, remove, reorder, or modify
+ * navigation sections and items.
+ *
+ * @param {HookRegistry} hooks - The hook registry instance
+ * @returns {Promise<void>}
+ *
+ * @typedef {Object} MenuAlterContext
+ * @property {Array<MenuSection>} sections - Navigation sections (mutable)
+ *
+ * @typedef {Object} MenuSection
+ * @property {string} title - Section title
+ * @property {Array<NavItem>} items - Navigation items in this section
+ *
+ * @typedef {Object} NavItem
+ * @property {string} route - Route name
+ * @property {string} label - Display label
+ * @property {string} [icon] - Icon class (e.g., 'pi pi-users')
+ * @property {string} [entity] - Entity name for permission checks
+ * @property {boolean} [exact] - Use exact route matching
+ *
+ * @example
+ * // In module init or extension
+ * hooks.register('menu:alter', (context) => {
+ *   // Add a new section
+ *   context.sections.push({
+ *     title: 'Tools',
+ *     items: [{ route: 'tools', label: 'Tools', icon: 'pi pi-wrench' }]
+ *   })
+ *
+ *   // Add item to existing section
+ *   const adminSection = context.sections.find(s => s.title === 'Admin')
+ *   if (adminSection) {
+ *     adminSection.items.push({ route: 'settings', label: 'Settings' })
+ *   }
+ *
+ *   // Remove a section
+ *   const idx = context.sections.findIndex(s => s.title === 'Legacy')
+ *   if (idx !== -1) context.sections.splice(idx, 1)
+ *
+ *   return context
+ * })
+ */
+export async function alterMenuSections(hooks) {
+  // Already altered? Return immediately
+  if (alteredNavSections !== null) {
+    return
+  }
+
+  // In-flight alteration? Wait for it
+  if (alterationPromise !== null) {
+    await alterationPromise
+    return
+  }
+
+  // No hooks registry? Mark as altered with raw sections
+  if (!hooks) {
+    alteredNavSections = buildRawNavSections()
+    return
+  }
+
+  // Perform alteration
+  alterationPromise = (async () => {
+    const rawSections = buildRawNavSections()
+
+    // Invoke menu:alter hook with mutable context
+    const alteredContext = await hooks.alter('menu:alter', {
+      sections: rawSections
+    })
+
+    // Store altered sections for getNavSections()
+    alteredNavSections = alteredContext.sections
+    alterationPromise = null
+  })()
+
+  await alterationPromise
+}
+
+/**
+ * Check if menu:alter hook has been invoked
+ * @returns {boolean}
+ */
+export function isMenuAltered() {
+  return alteredNavSections !== null
+}
+
 /**
  * Get route families mapping
  */
@@ -239,6 +355,8 @@ export function resetRegistry() {
   navSections.clear()
   entityConfigs.clear()
   sectionOrder = []
+  alteredNavSections = null
+  alterationPromise = null
 }
 
 // Export registry for direct access if needed

package/src/orchestrator/Orchestrator.js

@@ -35,11 +35,20 @@ export class Orchestrator {
     const {
       entityFactory = null,
       // Optional: pre-registered managers (for special cases)
-      managers = {}
+      managers = {},
+      // SignalBus instance for event-driven communication
+      signals = null,
+      // HookRegistry instance for lifecycle hooks
+      hooks = null,
+      // Optional: AuthAdapter for entity permission checks (scope/silo)
+      entityAuthAdapter = null
     } = options
 
     this._entityFactory = entityFactory
     this._managers = new Map()
+    this._signals = signals
+    this._hooks = hooks
+    this._entityAuthAdapter = entityAuthAdapter
 
     // Register pre-provided managers
     for (const [name, manager] of Object.entries(managers)) {
@@ -47,6 +56,56 @@ export class Orchestrator {
     }
   }
 
+  /**
+   * Set the SignalBus instance
+   * @param {SignalBus} signals
+   */
+  setSignals(signals) {
+    this._signals = signals
+  }
+
+  /**
+   * Get the SignalBus instance
+   * @returns {SignalBus|null}
+   */
+  get signals() {
+    return this._signals
+  }
+
+  /**
+   * Set the entity AuthAdapter for permission checks
+   * This adapter will be injected into all newly registered managers
+   * (unless they already have their own adapter)
+   * @param {AuthAdapter} adapter
+   */
+  setEntityAuthAdapter(adapter) {
+    this._entityAuthAdapter = adapter
+  }
+
+  /**
+   * Get the entity AuthAdapter
+   * @returns {AuthAdapter|null}
+   */
+  get entityAuthAdapter() {
+    return this._entityAuthAdapter
+  }
+
+  /**
+   * Set the HookRegistry instance
+   * @param {HookRegistry} hooks
+   */
+  setHooks(hooks) {
+    this._hooks = hooks
+  }
+
+  /**
+   * Get the HookRegistry instance
+   * @returns {HookRegistry|null}
+   */
+  get hooks() {
+    return this._hooks
+  }
+
   /**
    * Set the entity factory
    * @param {function} factory - (entityName, entityConfig) => EntityManager
@@ -64,6 +123,19 @@ export class Orchestrator {
    */
   register(name, manager) {
     this._managers.set(name, manager)
+    // Pass signals reference to manager for event emission
+    if (this._signals && manager.setSignals) {
+      manager.setSignals(this._signals)
+    }
+    // Pass hooks reference to manager for lifecycle hooks
+    if (this._hooks && manager.setHooks) {
+      manager.setHooks(this._hooks)
+    }
+    // Inject entityAuthAdapter if provided and manager doesn't have one
+    // Manager's own adapter takes precedence (allows per-entity customization)
+    if (this._entityAuthAdapter && !manager._authAdapter) {
+      manager.authAdapter = this._entityAuthAdapter
+    }
     if (manager.onRegister) {
       manager.onRegister(this)
     }

package/src/plugin.js

@@ -22,6 +22,7 @@ import qdadmLogo from './assets/logo.svg'
  * @param {object} options.features - Optional: Feature toggles (auth, poweredBy)
  * @param {object} options.builtinModules - Optional: Builtin modules configuration
  * @param {object} options.endpoints - Optional: API endpoints configuration
+ * @param {string} options.homeRoute - Optional: Home route name for breadcrumb
  * @returns {object} Vue plugin
  */
 export function createQdadm(options) {
@@ -112,6 +113,10 @@ export function createQdadm(options) {
         app.provide('qdadmSectionOrder', options.modules.sectionOrder)
       }
 
+      if (options.homeRoute) {
+        app.provide('qdadmHomeRoute', options.homeRoute)
+      }
+
       // Add route guard for entity permissions
       options.router.beforeEach((to, from, next) => {
         const entity = to.meta?.entity