kimu-core 0.4.1

package/src/core/kimu-extension-manager.ts

@@ -0,0 +1,281 @@
+import { KimuStore } from './kimu-store';
+import { KimuExtensionMeta } from './kimu-types';
+import { KimuPathConfig } from './kimu-path-config';
+
+/**
+ * Get the extension manifest path with proper base path resolution
+ */
+const getExtManifestPath = () => KimuPathConfig.resolvePath('/extensions/extensions-manifest.json');
+
+/**
+ * The `KimuExtensionManager` class manages extensions in the Kimu framework.
+ * It handles the initialization, loading, and runtime management of extensions.
+ * 
+ * Key functionalities:
+ * - Loads the initial manifest of extensions.
+ * - Synchronizes the database with the manifest.
+ * - Dynamically loads extensions at runtime.
+ * - Provides methods to list, save, disable, and remove extensions.
+ * - Maintains a registry of loaded extensions to avoid duplicate loading.
+ */
+export class KimuExtensionManager {
+
+  /** Singleton instance of the extension manager */
+  private static _instance: KimuExtensionManager;
+
+  /** Registered extensions in the system (stored in IndexedDB) */
+  private _extensions: Map<string, KimuExtensionMeta> = new Map<string, KimuExtensionMeta>();
+
+  /** Map to track whether an extension has been loaded */
+  private _loaded: Map<string, boolean> = new Map();
+
+  /** Map to track loading promises to avoid duplicate loading */
+  private _loadingPromises: Map<string, Promise<void>> = new Map();
+
+  /**
+   * Retrieves the singleton instance of the extension manager.
+   * If the instance does not exist, it initializes a new one.
+   */
+  static getInstance(): KimuExtensionManager {
+    if (!this._instance) {
+      // Check if an existing instance is stored in the global window object
+      const existing = (window as any).__kimu_extension_manager__;
+      if (existing) {
+        this._instance = existing;
+      } else {
+        this._instance = new KimuExtensionManager();
+        (window as any).__kimu_extension_manager__ = this._instance;
+      }
+    }
+    return this._instance;
+  }
+
+  /**
+   * Initializes IndexedDB and loads the initial manifest on the first run.
+   */
+  async init(): Promise<void> {
+    // Initialize the extension store (IndexedDB)
+    await KimuStore.init();
+    // Check if the database is empty (first run)
+    // If empty, loads the initial manifest and saves it to the database
+    const isEmpty = await KimuStore.isEmpty();
+    const manifest = await this.loadInitialManifest();
+    if (isEmpty) {
+      // Load the initial manifest and save extensions to the database
+      console.log('[KimuExtensionManager] ⚠️ Database is empty, loading initial manifest...');
+      for (const entry of manifest) {
+        await KimuStore.save(entry);
+      }
+      console.log('[KimuExtensionManager] ✅ KimuStore (IndexedDB) initialized with the manifest JSON');
+    } else {
+      //console.log('[KimuExtensionManager] 🔄 DB present: sync with json manifest');
+      await this.syncWithManifest(manifest);
+    }
+    const all = await KimuStore.list();
+    this._extensions.clear();
+    this._loaded.clear();
+    for (const ext of all) {
+      this._extensions.set(ext.tag, ext);
+      this._loaded.set(ext.tag, false);
+    }
+    // console.log('[KimuExtensionManager] 📦 Extensions available:', this._extensions);
+  }
+
+  /**
+   * Synchronizes the database with the initial manifest of extensions.
+   * Adds new extensions from the manifest and updates existing ones if necessary.
+   * If it is present in the DB but not in the manifest, remove it.
+   */
+  private async syncWithManifest(manifest: KimuExtensionMeta[]): Promise<void> {
+    const current = await KimuStore.list();
+    const currentMap = new Map(current.map(e => [e.tag, e]));
+  
+    for (const entry of manifest) {
+      const existing = currentMap.get(entry.tag);
+  
+      if (!existing) {
+        console.log(`[KimuExtensionManager] ➕ Adding new extension: ${entry.tag}`);
+        await KimuStore.save(entry);
+      } else {
+        // Puoi raffinare il confronto: qui controlliamo solo se version o path sono cambiati
+        const changed =
+          existing.version !== entry.version ||
+          existing.path !== entry.path ||
+          existing.name !== entry.name;
+  
+        if (changed) {
+          console.log(`[KimuExtensionManager] 🔁 Updating extension: ${entry.tag}`);
+          await KimuStore.save(entry);
+        }
+      }
+    }
+  }  
+
+  /**
+   * Loads the initial manifest of extensions (only once).
+   */
+  private async loadInitialManifest(): Promise<KimuExtensionMeta[]> {
+    // console.log('[KimuExtensionManager] Loading initial manifest...');
+    // Load the extension manifest
+    try {
+      const manifestPath = getExtManifestPath();
+      const res = await fetch(manifestPath);
+      if (!res.ok) {
+        throw new Error('File not found');
+      }
+      const manifest: KimuExtensionMeta[] = await res.json();
+      return manifest;
+    } catch (err) {
+      console.warn('[KimuExtensionManager] ⚠️ Initial manifest not loaded:', err);
+      return [];
+    }
+  }
+
+  /**
+   * Reloads the extension manifest from the remote source.
+   */
+  async reloadManifest(): Promise<void> {
+    // console.log('[KimuExtensionManager] Reload manifest...');
+    const newManifest = await this.loadInitialManifest();
+    for (const entry of newManifest) {
+      await this.save(entry);
+    }
+    console.log('[KimuExtensionManager] 🔁 Manifest manually reloaded');
+  }
+
+  /**
+   * Returns all extensions currently registered in memory.
+   */
+  listAvailable(): KimuExtensionMeta[] {
+    return Array.from(this._extensions.values());
+  }
+
+  /**
+   * Returns all extensions saved in IndexedDB.
+   */
+  async list(): Promise<KimuExtensionMeta[]> {
+    return  await KimuStore.list();
+  }
+  
+  /**
+   * Retrieves an extension from IndexedDB by its tag.
+   */
+  get(tag: string): KimuExtensionMeta | undefined {
+    return this._extensions.get(tag);
+  }
+
+  /**
+   * Returns the tags of extensions already loaded dynamically.
+   */
+  getTags(): string[] {
+    return Array.from(this._extensions.keys());
+  }
+
+  /**
+   * Checks if an extension has been loaded into the system.
+   */
+  isLoaded(tag: string): boolean {
+    return this._loaded.get(tag) ?? false;
+  }
+
+  /**
+   * Dynamically loads an extension at runtime (only once).
+   */
+  async load(tag: string): Promise<void> {
+    //console.log(`[KimuExtensionManager] Load extension: ${tag}`);
+    
+    // Check if the extension is already loaded
+    if (!this._extensions.has(tag)) {
+      console.log(`[KimuExtensionManager] ⚠️ Extension not present: ${tag}`);
+      return;
+    }
+    
+    // Check if already loaded
+    if (this.isLoaded(tag)) {
+      //console.log(`[KimuExtensionManager] ⚠️ Extension already loaded: ${tag}`);
+      return;
+    }
+    
+    // Check if already loading
+    if (this._loadingPromises.has(tag)) {
+      return this._loadingPromises.get(tag);
+    }
+    
+    const ext = this._extensions.get(tag);
+    if (!ext) {
+      console.warn(`[KimuExtensionManager] ⚠️ Extension not found: ${tag}`);
+      return;
+    }
+    
+    if (!ext.path) {
+      console.warn(`[KimuExtensionManager] ⚠️ Path not defined for extension: ${tag}`);
+      return;
+    }
+    
+    // Create loading promise
+    const loadingPromise = this._loadExtension(tag, ext);
+    this._loadingPromises.set(tag, loadingPromise);
+    
+    try {
+      await loadingPromise;
+    } finally {
+      this._loadingPromises.delete(tag);
+    }
+  }
+
+  /**
+   * Internal method to load an extension
+   */
+  private async _loadExtension(tag: string, ext: KimuExtensionMeta): Promise<void> {
+    try {
+      const componentPath = KimuPathConfig.resolvePath(`/extensions/${ext.path}/component.js`);
+      await import(/* @vite-ignore */ componentPath);
+      this._loaded.set(tag, true);
+      // console.log(`[KimuExtensionManager] ✅ Extension loaded: ${tag}`);
+    } catch (err) {
+      console.error(`[KimuExtensionManager] ❌ Error loading Extension tag "${tag}":`, err);
+      throw err;
+    }
+  }
+
+  /**
+   * Saves an extension to the database.
+   */
+  async save(entry: KimuExtensionMeta): Promise<void> {
+    await KimuStore.save(entry);
+    this._extensions.set(entry.tag, entry);
+    this._loaded.set(entry.tag, false);
+  }
+
+  /**
+   * Disables an extension.
+   */
+  async disable(tag: string): Promise<void> {
+    const ext = await this.get(tag);
+    if (ext) {
+      ext.enabled = false;
+      await this.save(ext);
+      console.log(`[KimuExtensionManager] ⛔ Extension disabled: ${tag}`);
+    }
+  }
+
+  /**
+   * Removes an extension from the database.
+   */
+  async remove(tag: string): Promise<void> {
+    await KimuStore.remove(tag);
+    this._extensions.delete(tag);
+    this._loaded.delete(tag);
+    console.log(`[KimuExtensionManager] 🗑️ Extension removed: ${tag}`);
+  }
+
+  /**
+   * Resets the database completely. Clears all data (use with caution).
+   */
+  async reset(): Promise<void> {
+    await KimuStore.clear();
+    this._extensions.clear();
+    this._loaded.clear();
+    console.log('[KimuExtensionManager] 🔄 Complete database reset');
+  }
+}

package/src/core/kimu-global-styles.ts

@@ -0,0 +1,136 @@
+/**
+ * KimuGlobalStyles manages global CSS files that should be injected into all extensions.
+ * This allows modules (like the theme module) to register additional global styles
+ * without hardcoding dependencies in the core framework.
+ * 
+ * Usage:
+ * - Core always injects 'assets/kimu-style.css' as the base style
+ * - Modules can register additional global CSS using registerGlobalStyle()
+ * - All registered styles are automatically injected into every extension's shadow root
+ */
+export class KimuGlobalStyles {
+  /** List of global CSS files to inject in all extensions */
+  private static _globalStyles: Array<{ id: string; path: string }> = [
+    // Default KIMU base styles - always included
+    { id: 'kimu-style-default', path: 'assets/kimu-style.css' }
+  ];
+
+  /**
+   * Register a global CSS file to be injected in all extensions.
+   * This is useful for modules that want to provide global theming or styling.
+   * 
+   * @param id - Unique identifier for the style (e.g., 'theme-dark', 'theme-light')
+   * @param path - Path to the CSS file relative to the base path
+   * 
+   * @example
+   * // In a theme module
+   * KimuGlobalStyles.registerGlobalStyle('theme-active', 'themes/theme-dark.css');
+   */
+  static registerGlobalStyle(id: string, path: string): void {
+    // Check if already registered
+    const existing = this._globalStyles.find(s => s.id === id);
+    if (existing) {
+      // Update path if already registered
+      existing.path = path;
+      console.log(`[KimuGlobalStyles] Updated global style: ${id} -> ${path}`);
+    } else {
+      // Add new global style
+      this._globalStyles.push({ id, path });
+      console.log(`[KimuGlobalStyles] Registered global style: ${id} -> ${path}`);
+    }
+  }
+
+  /**
+   * Unregister a global CSS file.
+   * 
+   * @param id - Unique identifier of the style to remove
+   */
+  static unregisterGlobalStyle(id: string): void {
+    const index = this._globalStyles.findIndex(s => s.id === id);
+    if (index !== -1) {
+      this._globalStyles.splice(index, 1);
+      console.log(`[KimuGlobalStyles] Unregistered global style: ${id}`);
+    }
+  }
+
+  /**
+   * Get all registered global styles.
+   * Used internally by KimuComponentElement to inject styles into extensions.
+   * 
+   * @returns Array of registered global styles
+   */
+  static getGlobalStyles(): Array<{ id: string; path: string }> {
+    return [...this._globalStyles]; // Return a copy to prevent external modifications
+  }
+
+  /**
+   * Clear all registered styles (useful for testing or reset scenarios).
+   * Note: This will also remove the default kimu-style.css.
+   */
+  static clearAllStyles(): void {
+    this._globalStyles = [
+      { id: 'kimu-style-default', path: 'assets/kimu-style.css' }
+    ];
+    console.log('[KimuGlobalStyles] Cleared all global styles, keeping only default');
+  }
+
+  /**
+   * Get the number of registered global styles.
+   */
+  static getStyleCount(): number {
+    return this._globalStyles.length;
+  }
+
+  /**
+   * Check if a specific style ID is registered.
+   */
+  static hasStyle(id: string): boolean {
+    return this._globalStyles.some(s => s.id === id);
+  }
+
+  /**
+   * Update a specific global style in all currently loaded extensions.
+   * This is useful when a theme changes and needs to be propagated to all extensions.
+   * 
+   * @param id - Style ID to update (e.g., 'kimu-theme-active')
+   * 
+   * Note: This method uses KimuEngine.injectStyle() to update styles in all shadow roots.
+   * It requires KimuEngine to be imported dynamically to avoid circular dependencies.
+   */
+  static async updateStyleInAllExtensions(id: string): Promise<void> {
+    const style = this._globalStyles.find(s => s.id === id);
+    if (!style) {
+      console.warn(`[KimuGlobalStyles] Style "${id}" not found, cannot update`);
+      return;
+    }
+
+    // Find all custom elements (extensions) in the DOM
+    const allCustomElements = document.querySelectorAll('*');
+    const extensions: HTMLElement[] = [];
+
+    allCustomElements.forEach((el) => {
+      // Check if element is a custom element with shadow root
+      if (el.tagName.includes('-') && (el as any).shadowRoot) {
+        extensions.push(el as HTMLElement);
+      }
+    });
+
+    if (extensions.length === 0) {
+      console.log('[KimuGlobalStyles] No extensions found to update');
+      return;
+    }
+
+    // Dynamically import KimuEngine to avoid circular dependency
+    const { KimuEngine } = await import('./kimu-engine');
+
+    // Update style in all extensions
+    console.log(`[KimuGlobalStyles] Updating style "${id}" in ${extensions.length} extensions`);
+    for (const ext of extensions) {
+      try {
+        await KimuEngine.injectStyle(ext, style.path, style.id);
+      } catch (error) {
+        console.warn(`[KimuGlobalStyles] Failed to update style in ${ext.tagName}:`, error);
+      }
+    }
+  }
+}

package/src/core/kimu-module-manager.ts

@@ -0,0 +1,69 @@
+import { KimuModule } from './kimu-module';
+import { KimuModuleOptions } from './kimu-types';
+import { KimuPathConfig } from './kimu-path-config';
+
+export class KimuModuleManager {
+  private static instance: KimuModuleManager | null = null;
+  private modules: Map<string, KimuModule> = new Map();
+
+  static getInstance(): KimuModuleManager {
+    if (!KimuModuleManager.instance) {
+      KimuModuleManager.instance = new KimuModuleManager();
+    }
+    return KimuModuleManager.instance;
+  }
+
+  async loadModule(name: string, options?: KimuModuleOptions): Promise<KimuModule> {
+    // Check if module already exists (singleton support)
+    if (this.modules.has(name)) {
+      const existing = this.modules.get(name)!;
+      if (existing.singleton) {
+        return existing;
+      }
+    }
+
+    // Import dinamico del modulo con base path
+    const modPath = KimuPathConfig.resolvePath(`/modules/${name}/module.js`);
+    const modImport = await import(/* @vite-ignore */ modPath);
+    const instance: KimuModule = new modImport.default(name, '1.0.0', options);
+    
+    if (instance.onInit) await instance.onInit();
+    this.modules.set(name, instance);
+    return instance;
+  }
+
+  getModule(name: string): KimuModule | undefined {
+    return this.modules.get(name);
+  }
+
+  async closeModule(name: string): Promise<void> {
+    const mod = this.modules.get(name);
+    if (mod && mod.onClose) await mod.onClose();
+    this.modules.delete(name);
+  }
+
+  getService(name: string): any {
+    const mod = this.modules.get(name);
+    return mod ? mod.getService() : undefined;
+  }
+
+  // Convenience methods for commonly used modules
+  async getI18nService(options?: KimuModuleOptions): Promise<any> {
+    const module = await this.loadModule('i18n', options);
+    return module.getService();
+  }
+
+  async getRouterService(options?: KimuModuleOptions): Promise<any> {
+    const module = await this.loadModule('router', options);
+    return module.getService();
+  }
+
+  // Static convenience methods for global access
+  static async getI18nService(options?: KimuModuleOptions): Promise<any> {
+    return KimuModuleManager.getInstance().getI18nService(options);
+  }
+
+  static async getRouterService(options?: KimuModuleOptions): Promise<any> {
+    return KimuModuleManager.getInstance().getRouterService(options);
+  }
+}

package/src/core/kimu-module.ts

@@ -0,0 +1,21 @@
+import { KimuModuleOptions } from './kimu-types';
+
+export abstract class KimuModule {
+  public name: string;
+  public version: string;
+  public singleton?: boolean = false;
+  public options?: KimuModuleOptions;
+
+  constructor(name: string, version: string, options?: KimuModuleOptions) {
+    this.name = name;
+    this.version = version;
+    this.options = options;
+  }
+
+  // Lifecycle hooks
+  onInit?(): void | Promise<void>;
+  onClose?(): void | Promise<void>;
+
+  // API per servizi/esportazioni
+  abstract getService(): any;
+}

package/src/core/kimu-path-config.ts

@@ -0,0 +1,127 @@
+import { KimuBuildConfig } from '../config/kimu-build-config';
+
+/**
+ * KimuPathConfig handles base path configuration for deployments in subdirectories.
+ * It integrates with the existing build configuration system and supports:
+ * - Automatic initialization from generated build config
+ * - Runtime path resolution for all framework resources
+ * - Support for deployment in any server subdirectory
+ * 
+ * Usage:
+ * - Paths are configured in env/*.config.json files
+ * - Can be overridden with environment variables (KIMU_BASE_PATH)
+ * - Automatically resolves all framework resource paths
+ */
+export class KimuPathConfig {
+  /** Current base path (without trailing slash, empty for root) */
+  private static _basePath: string | null = null;
+  
+  /** Initialization flag to avoid multiple initializations */
+  private static _initialized: boolean = false;
+
+  /**
+   * Initialize from generated build config.
+   * Called automatically on first path resolution.
+   */
+  static initialize(): void {
+    if (this._initialized) return;
+    
+    try {
+      // Get base path from generated configuration
+      const configBasePath = (KimuBuildConfig.build as any)['base-path'] || '/';
+      this.setBasePath(configBasePath);
+      this._initialized = true;
+      
+      console.log(`[KimuPathConfig] Initialized with base path: "${this._basePath || '/'}"`);
+    } catch (error) {
+      console.warn('[KimuPathConfig] Failed to initialize from build config, using root path', error);
+      this.setBasePath('/');
+      this._initialized = true;
+    }
+  }
+  
+  /**
+   * Set base path manually (mainly for testing or runtime override).
+   * @param path The base path to set (e.g., "/", "/dist/", "/my-app/")
+   */
+  static setBasePath(path: string): void {
+    // Normalize path: ensure starts with / and doesn't end with / (except root)
+    if (!path.startsWith('/')) path = '/' + path;
+    if (path.length > 1 && path.endsWith('/')) path = path.slice(0, -1);
+    
+    // Store as empty string for root path, or the normalized path
+    this._basePath = path === '/' ? '' : path;
+  }
+  
+  /**
+   * Get current base path.
+   * @returns The current base path (empty string for root)
+   */
+  static getBasePath(): string {
+    if (!this._initialized) this.initialize();
+    return this._basePath || '';
+  }
+  
+  /**
+   * Resolve an absolute path with the configured base path.
+   * @param path The path to resolve (e.g., "/extensions/manifest.json")
+   * @returns The resolved path with base path prepended
+   */
+  static resolvePath(path: string): string {
+    if (!this._initialized) this.initialize();
+    
+    // Skip external URLs
+    if (this.isExternalUrl(path)) return path;
+    
+    // Skip relative paths (they're already relative to current location)
+    if (!path.startsWith('/')) return path;
+    
+    // Apply base path to absolute paths
+    const basePath = this._basePath || '';
+    return basePath + path;
+  }
+  
+  /**
+   * Check if a path is an external URL.
+   * @param path The path to check
+   * @returns True if the path is an external URL
+   */
+  private static isExternalUrl(path: string): boolean {
+    return path.startsWith('http://') || 
+           path.startsWith('https://') || 
+           path.startsWith('//') ||
+           path.startsWith('mailto:') ||
+           path.startsWith('tel:');
+  }
+  
+  /**
+   * Force re-initialization (mainly for testing).
+   */
+  static reset(): void {
+    this._initialized = false;
+    this._basePath = null;
+  }
+  
+  /**
+   * Get full URL for a path (combines base URL from config with resolved path).
+   * @param path The path to convert to full URL
+   * @returns Full URL with base URL and path
+   */
+  static getFullUrl(path: string): string {
+    if (!this._initialized) this.initialize();
+    
+    try {
+      const webUrl = (KimuBuildConfig.build as any)['web-url'] || window.location.origin;
+      const resolvedPath = this.resolvePath(path);
+      
+      // If path is already a full URL, return as-is
+      if (this.isExternalUrl(resolvedPath)) return resolvedPath;
+      
+      // Combine base URL with resolved path
+      return webUrl + resolvedPath;
+    } catch (error) {
+      console.warn('[KimuPathConfig] Failed to get full URL, returning resolved path', error);
+      return this.resolvePath(path);
+    }
+  }
+}