@quazardous/qdadm 1.19.3

package/src/kernel/KernelContext.zones.ts

@@ -0,0 +1,54 @@
+/**
+ * Patch KernelContext prototype with UI extensibility methods:
+ *   - zone(name, options)        — define a zone slot
+ *   - block(zoneName, config)    — register a block in a zone
+ *   - provide(key, value)        — Vue dependency injection
+ *   - component(name, component) — global Vue component registration
+ *
+ * provide/component fall back to the kernel's _pendingProvides /
+ * _pendingComponents maps when the Vue app isn't created yet, so modules can
+ * call them during connect().
+ */
+
+import type { Component } from 'vue'
+import type { BlockConfig, ZoneOptions } from './KernelContext.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyZoneMethods(KernelContextClass: { prototype: any }): void {
+  const proto = KernelContextClass.prototype as Self
+
+  proto.zone = function (this: Self, name: string, options: ZoneOptions = {}): Self {
+    if (this._kernel.zoneRegistry) {
+      this._kernel.zoneRegistry.defineZone(name, options)
+    }
+    return this
+  }
+
+  proto.block = function (this: Self, zoneName: string, config: BlockConfig): Self {
+    if (this._kernel.zoneRegistry) {
+      this._kernel.zoneRegistry.registerBlock(zoneName, config)
+    }
+    return this
+  }
+
+  proto.provide = function (this: Self, key: string | symbol, value: unknown): Self {
+    if (this._kernel.vueApp) {
+      this._kernel.vueApp.provide(key, value)
+    } else {
+      this._kernel._pendingProvides.set(key, value)
+    }
+    return this
+  }
+
+  proto.component = function (this: Self, name: string, component: Component): Self {
+    if (this._kernel.vueApp) {
+      this._kernel.vueApp.component(name, component)
+    } else {
+      this._kernel._pendingComponents.set(name, component)
+    }
+    return this
+  }
+}

package/src/kernel/Module.ts

@@ -0,0 +1,169 @@
+/**
+ * Module Base Class
+ *
+ * Defines the interface for qdadm modules. Modules encapsulate:
+ * - Entity definitions
+ * - Route registration
+ * - Navigation items
+ * - Zone definitions
+ * - Signal listeners
+ *
+ * Usage patterns:
+ *
+ * 1. Class-based (full control):
+ *    class MyModule extends Module {
+ *      static moduleName = 'mymodule'
+ *      static requires = ['auth']
+ *      static priority = 50
+ *      enabled(ctx) { return ctx.isDev }
+ *      async connect(ctx) { ... }
+ *      async disconnect() { ... }
+ *    }
+ *
+ * 2. Object-based (simple modules):
+ *    export default {
+ *      name: 'simple',
+ *      connect(ctx) { ctx.entity(...).routes(...) }
+ *    }
+ *
+ * 3. Legacy function (backward compat):
+ *    export function init({ registry, zones }) { ... }
+ */
+
+// Forward declaration for KernelContext (to avoid circular deps)
+export interface KernelContextLike {
+  [key: string]: unknown
+}
+
+/**
+ * Module static properties interface
+ */
+export interface ModuleStatic {
+  moduleName: string
+  requires: string[]
+  priority: number
+  styles: (() => Promise<unknown>) | null
+}
+
+/**
+ * Module constructor options
+ */
+export interface ModuleOptions {
+  name?: string
+  [key: string]: unknown
+}
+
+export class Module {
+  /**
+   * Unique module name (used for dependency resolution)
+   */
+  static moduleName = 'base'
+
+  /**
+   * Module dependencies - names of modules that must be loaded first
+   */
+  static requires: string[] = []
+
+  /**
+   * Load priority - higher values load later (useful for cross-module wiring)
+   */
+  static priority = 0
+
+  /**
+   * Path to module styles (relative import or absolute)
+   * Set in subclass to auto-load CSS/SCSS when module connects.
+   * Styles are loaded once and cached.
+   *
+   * @example
+   * class DebugModule extends Module {
+   *   static styles = () => import('./styles.scss')
+   * }
+   */
+  static styles: (() => Promise<unknown>) | null = null
+
+  options: ModuleOptions
+  ctx: KernelContextLike | null = null
+  protected _signalCleanups: Array<() => void> = []
+  protected _stylesLoaded = false
+
+  constructor(options: ModuleOptions = {}) {
+    this.options = options
+  }
+
+  /**
+   * Get the module name (from static property or options)
+   * Priority: options.name > own static moduleName > own static name > inherited moduleName
+   */
+  get name(): string {
+    if (this.options.name) {
+      return this.options.name
+    }
+    const ctor = this.constructor as typeof Module
+    // Check for OWN moduleName property (not inherited from Module base class)
+    if (Object.hasOwn(ctor, 'moduleName')) {
+      return ctor.moduleName
+    }
+    // Check for OWN static name property (legacy pattern: static name = 'xxx')
+    if (Object.hasOwn(ctor, 'name')) {
+      return ctor.name as unknown as string
+    }
+    // Fallback to inherited moduleName (should be 'base' only for Module itself)
+    return ctor.moduleName
+  }
+
+  /**
+   * Check if module should be enabled
+   * Override in subclass for conditional loading
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  enabled(_ctx: any): boolean {
+    return true
+  }
+
+  /**
+   * Load module styles if defined
+   * Called automatically by ModuleLoader before connect()
+   */
+  async loadStyles(): Promise<void> {
+    const stylesLoader = (this.constructor as typeof Module).styles
+    if (this._stylesLoaded || !stylesLoader) return
+
+    try {
+      await stylesLoader()
+      this._stylesLoaded = true
+    } catch (e) {
+      console.warn(`[${(this.constructor as typeof Module).moduleName}] Failed to load styles:`, e)
+    }
+  }
+
+  /**
+   * Connect module to kernel - main registration point
+   * Override in subclass to register entities, routes, etc.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async connect(_ctx: any): Promise<void> {
+    // Override in subclass
+  }
+
+  /**
+   * Disconnect module from kernel - cleanup
+   * Override in subclass to remove listeners, cleanup resources
+   */
+  async disconnect(): Promise<void> {
+    // Cleanup signal listeners registered via ctx.on()
+    for (const cleanup of this._signalCleanups) {
+      cleanup()
+    }
+    this._signalCleanups = []
+  }
+
+  /**
+   * Register a signal cleanup function (used by KernelContext.on())
+   * @internal
+   */
+  _addSignalCleanup(cleanup: () => void): void {
+    this._signalCleanups.push(cleanup)
+  }
+}
+
+export default Module