kimu-core 0.4.1

package/src/core/kimu-component-element.ts

@@ -0,0 +1,325 @@
+import { KimuEngine } from './kimu-engine';
+import { KimuExtensionManager } from './kimu-extension-manager';
+import { KimuExtensionMeta } from './kimu-types';
+import { KimuPathConfig } from './kimu-path-config';
+import { KimuGlobalStyles } from './kimu-global-styles';
+import { 
+  initReactiveProperties, 
+  getObservedAttributes, 
+  handleAttributeChange 
+} from './kimu-reactive';
+
+/**
+ * The `KimuComponentElement` class serves as the base class for all components and extensions
+ * in the Kimu framework. It provides lifecycle hooks, metadata management, and utility methods
+ * for rendering and managing resources.
+ * 
+ * Key functionalities:
+ * - Provides lifecycle hooks (`onInit`, `onRender`, `onDestroy`) for component management.
+ * - Manages metadata associated with the component.
+ * - Handles template rendering and resource loading.
+ * - Supports dependency injection and external asset management.
+ * 
+ * This class is designed to be extended by custom components and used with the `@KimuComponent` decorator.
+ */
+export abstract class KimuComponentElement extends HTMLElement {
+
+  /**
+   * Static method to get observed attributes from reactive properties
+   * This enables automatic attribute reflection for @property decorated properties
+   */
+  static get observedAttributes(): string[] {
+    return getObservedAttributes(this);
+  }
+
+  /** Global optimization settings - simplified */
+  private static _optimizationSettings = {
+    enableTemplateCache: true,
+    enableFileCache: true,
+    enableRenderDebouncing: true,
+    enableErrorBoundaries: true,  // New: Safe error isolation
+    cacheMaxSize: 50,             // New: Cache size limiting  
+    enableAssetPreloading: false  // New: Asset preloading (opt-in)
+  };
+
+  /**
+   * Configure global optimization settings for all components
+   */
+  static configureOptimizations(settings: Partial<typeof KimuComponentElement._optimizationSettings>) {
+    Object.assign(this._optimizationSettings, settings);
+    
+    // Apply cache size settings to KimuEngine
+    if (settings.cacheMaxSize !== undefined) {
+      KimuEngine.configureCaching(settings.cacheMaxSize);
+    }
+  }
+
+  /**
+   * Get current optimization settings (for debugging)
+   */
+  static getOptimizationSettings() {
+    return { ...this._optimizationSettings };
+  }
+
+  /**
+   * Preload critical assets for better performance
+   */
+  static async preloadAssets(assetPaths: string[]): Promise<void> {
+    if (!this._optimizationSettings.enableAssetPreloading) {
+      console.warn('[KimuComponentElement] Asset preloading is disabled');
+      return;
+    }
+    
+    return KimuEngine.preloadAssets(assetPaths);
+  }
+
+  /**
+   * Force refresh without optimizations (for debugging)
+   */
+  async forceRefresh(): Promise<void> {
+    if (!this._renderFn) {
+      console.warn('[KimuComponentElement] ⚠️ Template render function (_renderFn) not initialized for component:', this.tagName);
+      return;
+    }
+    
+    // Force render immediately without debouncing
+    const currentData = this.getData();
+    await KimuEngine.render(this, currentData, this._renderFn!);
+    this.onRender();
+  }
+
+  /** Private reference to the KimuApp singleton (lazy loaded) */
+  private _app: any = null;
+  /** Each component must provide data for rendering */
+  getData(): Record<string, any> {
+    return {};
+  }
+
+  /** Lifecycle: initialization */
+  onInit(): void { }
+
+  /** Called every time after a render or refresh */
+  onRender(): void { }
+
+  /** Lifecycle: destruction */
+  onDestroy(): void { }
+
+  /** Optional error handling hook - override in components that need custom error handling */
+  onError?(error: Error): void;
+
+  /** Hook for loading the template */
+  private _renderFn?: (html: any, data: Record<string, any>) => any;
+
+  /** Lifecycle: destruction (override for custom cleanup, calls onDestroy by default) */
+  _onDestroyInternal(): void {
+    this.onDestroy();
+  }
+
+  /**
+   * Returns the KimuApp singleton, importing it dynamically only once.
+   * Usage: await this.getApp() in your extension/component.
+   */
+  protected async getApp(): Promise<any> {
+    if (this._app) {
+      return this._app;
+    }
+    // Dynamically import KimuApp to avoid circular dependencies
+    const { KimuApp } = await import('./kimu-app');
+    this._app = KimuApp.getInstance();
+    return this._app;
+  }
+
+  /**
+   * Constructor for the Kimu component.
+   * Initializes the shadow DOM and attaches it to the component.
+   */
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    //console.log("\n\n###### META DATA: ", this.getMeta());
+  }
+
+  /**
+   * Called when an observed attribute changes
+   * This is part of the Web Components lifecycle and enables attribute reflection
+   */
+  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
+    // Handle reactive property attribute changes
+    handleAttributeChange(this, name, oldValue, newValue);
+  }
+
+  /** Shortcut for querying the DOM */
+  $(selector: string): HTMLElement | null {
+    return this.shadowRoot?.querySelector(selector) ?? null;
+  }
+
+  /** Retrieves metadata associated with the component */
+  protected getMeta(): KimuExtensionMeta {
+    return (this.constructor as any).__kimu_meta__ as KimuExtensionMeta;
+  }
+
+  /** 
+   * Hook called automatically by the browser when the component is connected to the DOM.
+   * Method automatically called by the browser when the component is connected.
+   */
+  async connectedCallback(): Promise<void> {
+    const meta = this.getMeta();
+    //console.log('[KimuComponentElement] Init tag:', this.tagName, 'meta:', meta);
+    if (!meta || !meta.tag) {
+      console.warn('[KimuComponentElement] ❌ No metadata found for the component:', this.tagName , " - meta:", meta);
+      return;
+    }
+
+    // Initialize reactive properties from HTML attributes
+    initReactiveProperties(this);
+
+    // Load dependencies - use Promise.all for parallel loading
+    if (meta.dependencies?.length) {
+      const manager = KimuExtensionManager.getInstance();
+      await Promise.all(meta.dependencies.map(dep => manager.load(dep)));
+    }
+
+    // Inject all registered global styles (kimu-style.css + theme CSS, etc.)
+    const globalStyles = KimuGlobalStyles.getGlobalStyles();
+    for (const style of globalStyles) {
+      await KimuEngine.injectStyle(this, style.path, style.id);
+    }
+
+    // Inject external styles (if present, just once)
+    if (meta.style) {
+      let styleId = `kimu-style-ext-${meta.tag}`;
+      const cssPath = KimuPathConfig.resolvePath(`extensions/${meta.basePath}/${meta.style}`);
+      await KimuEngine.injectStyle(this, cssPath, styleId);
+    }
+    
+    // Compile the template on the first connection
+    if (meta.template) {
+      const templatePath = KimuPathConfig.resolvePath(`extensions/${meta.basePath}/${meta.template}`);
+      // Use template caching based on global settings
+      const useCache = KimuComponentElement._optimizationSettings.enableTemplateCache;
+      this._renderFn = await KimuEngine.loadTemplate(templatePath, useCache);
+    }
+    
+    // Initial render - wait for completion before calling onInit
+    await this.refresh(); // Render the template with data and wait for completion
+    // Call the initialization hook - DOM is now guaranteed to be ready
+    this.onInit();   // Call once, after DOM is fully rendered
+  }
+
+  /** 
+   * Forces a refresh of the interface component
+   * Note: For @property decorated properties, this is called automatically.
+   * Manual calls are only needed for non-reactive state changes.
+   */
+  async refresh(): Promise<void> {
+    if (!this._renderFn) {
+      console.warn('[KimuComponentElement] ⚠️ Template render function (_renderFn) not initialized for component:', this.tagName);
+      return;
+    }
+
+    // Skip debouncing if disabled or call directly
+    if (!KimuComponentElement._optimizationSettings.enableRenderDebouncing) {
+      await this._doRender();
+      return;
+    }
+
+    // Use the same RAF batching mechanism as kimu-reactive
+    // This ensures consistent behavior across manual and reactive updates
+    if ((this as any).__kimu_render_pending__) {
+      return; // Already scheduled
+    }
+
+    (this as any).__kimu_render_pending__ = true;
+    
+    return new Promise<void>((resolve) => {
+      requestAnimationFrame(async () => {
+        try {
+          await this._doRender();
+          resolve();
+        } catch (error) {
+          console.error('[KimuComponentElement] Render error:', error);
+          resolve(); // Resolve anyway to prevent hanging
+        } finally {
+          (this as any).__kimu_render_pending__ = false;
+        }
+      });
+    });
+  }
+
+  /**
+   * Internal render method - simplified without snapshot optimization
+   */
+  private async _doRender(): Promise<void> {
+    if (!KimuComponentElement._optimizationSettings.enableErrorBoundaries) {
+      // Original behavior without error boundaries
+      const currentData = this.getData();
+      await KimuEngine.render(this, currentData, this._renderFn!);
+      this.onRender();
+      return;
+    }
+
+    // Safe rendering with error boundaries
+    try {
+      const currentData = this.getData();
+      await KimuEngine.render(this, currentData, this._renderFn!);
+      this.onRender();
+    } catch (error) {
+      console.error(`[${this.tagName}] Render error:`, error);
+      console.error('Component data:', this.getData());
+      
+      // Fallback UI - safe and informative
+      if (this.shadowRoot) {
+        this.shadowRoot.innerHTML = `
+          <div style="
+            color: #721c24; 
+            background-color: #f8d7da; 
+            border: 1px solid #f5c6cb; 
+            padding: 10px; 
+            border-radius: 4px;
+            font-family: monospace;
+            font-size: 12px;
+          ">
+            <strong>⚠️ Component Error</strong><br>
+            <em>${this.tagName}</em><br>
+            ${error instanceof Error ? error.message : 'Unknown error'}
+          </div>
+        `;
+      }
+      
+      // Call error hook if available
+      if (typeof this.onError === 'function') {
+        try {
+          this.onError(error instanceof Error ? error : new Error(String(error)));
+        } catch (hookError) {
+          console.error(`[${this.tagName}] Error in onError hook:`, hookError);
+        }
+      }
+    }
+  }
+
+  /** 
+   * Hook called automatically when the component is disconnected from the DOM.
+   * Method automatically called on logout.
+  */
+  disconnectedCallback(): void {
+    // Clean up RAF batching state
+    (this as any).__kimu_render_pending__ = false;
+    
+    // Call the destruction hook
+    this._onDestroyInternal();
+  }
+
+  /** Loads a resource from an external file */
+  loadResource(file: string): Promise<any> {
+    const path = this.getMeta()?.path;
+    if (!path) throw new Error('Extension without valid path');
+    const resourcePath = KimuPathConfig.resolvePath(`extensions/${path}/resources/${file}`);
+    return fetch(resourcePath).then(r => r.json());
+  }
+  
+  /** Loads an asset from an external file */
+  loadAssetUrl(file: string): string {
+    const path = this.getMeta()?.path;
+    return KimuPathConfig.resolvePath(`extensions/${path}/assets/${file}`);
+  }
+}

package/src/core/kimu-component.ts

@@ -0,0 +1,33 @@
+import { KimuExtensionMeta } from "./kimu-types";
+
+/**
+ * Decorator to define a Kimu component with static metadata.
+ * 
+ * This script defines the `@KimuComponent` decorator, which is used to register
+ * custom components in the Kimu framework with static metadata.
+ * 
+ * Key functionalities:
+ * - Allows defining metadata for components, such as tag name, template path, and style path.
+ * - Automatically sets default paths for the template and style if not provided.
+ * - Registers the custom element with the browser using `customElements.define`.
+ * - Attaches static metadata directly to the class for later use.
+ * 
+ * @param meta - Metadata describing the component, including tag name, paths, and dependencies.
+ */
+export function KimuComponent(meta: KimuExtensionMeta) {
+  return function <T extends CustomElementConstructor>(target: T) {
+    // Sets the base path as a fallback (e.g., extensions/hello)
+    const basePath = meta.path ?? `extensions/${meta.tag}`;
+
+    // Sets default paths for the template and style if not specified
+    meta.basePath = basePath;
+    meta.template = meta.template ?? 'view.html'; //`${basePath}/view.html`;
+    meta.style = meta.style ?? 'style.css'; //`${basePath}/style.css`;
+
+    //  Registers the custom element with the browser
+    customElements.define(meta.tag, target);
+
+    // Attaches static metadata directly to the class for later use
+    (target as any).__kimu_meta__ = meta;
+  };
+}

package/src/core/kimu-engine.ts

@@ -0,0 +1,188 @@
+import { TemplateResult } from 'lit';
+import { KimuRender } from './kimu-render';
+import { KimuAssetManager } from './kimu-asset-manager';
+
+/**
+ * The `KimuEngine` class provides core functionalities for rendering, template management,
+ * and component loading in the Kimu framework. It acts as a bridge between the rendering engine
+ * (Lit) and the asset manager, enabling dynamic and reactive UI updates.
+ * 
+ * Key functionalities:
+ * - Injects styles into the Shadow DOM of components.
+ * - Loads and compiles HTML templates into Lit rendering functions.
+ * - Provides reactive rendering capabilities using Lit.
+ * - Dynamically loads and registers custom components.
+ */
+export class KimuEngine {
+
+  /** Cache for compiled templates to avoid recompilation */
+  private static _templateCache = new Map<string, any>();
+  
+  /** Cache access tracking for LRU eviction */
+  private static _cacheAccessTime = new Map<string, number>();
+  
+  /** Maximum cache size to prevent memory issues */
+  private static _maxCacheSize = 50;
+
+  /**
+   * Safely evict oldest cache entries when limit is reached
+   */
+  private static _evictOldestEntries(): void {
+    if (this._templateCache.size < this._maxCacheSize) return;
+    
+    // Get entries sorted by access time (oldest first)
+    const entriesToEvict = Array.from(this._cacheAccessTime.entries())
+      .sort(([, a], [, b]) => a - b)
+      .slice(0, Math.floor(this._templateCache.size * 0.2)) // Evict 20%
+      .map(([path]) => path);
+    
+    // Remove from both caches
+    entriesToEvict.forEach(path => {
+      this._templateCache.delete(path);
+      this._cacheAccessTime.delete(path);
+    });
+    
+    if (entriesToEvict.length > 0) {
+      console.log(`[KimuEngine] Evicted ${entriesToEvict.length} old template cache entries`);
+    }
+  }
+
+  /**
+   * Configure cache settings
+   */
+  static configureCaching(maxSize: number = 50): void {
+    this._maxCacheSize = maxSize;
+  }
+
+  /**
+   * Clear all caches (for debugging/testing)
+   */
+  static clearCaches(): void {
+    this._templateCache.clear();
+    this._cacheAccessTime.clear();
+  }
+
+  /**
+   * Preload critical assets to improve performance
+   */
+  static async preloadAssets(paths: string[]): Promise<void> {
+    if (paths.length === 0) return;
+    
+    console.log(`[KimuEngine] Preloading ${paths.length} assets...`);
+    
+    // Preload in parallel but with limited concurrency to avoid overwhelming the browser
+    const BATCH_SIZE = 5;
+    const batches = [];
+    
+    for (let i = 0; i < paths.length; i += BATCH_SIZE) {
+      batches.push(paths.slice(i, i + BATCH_SIZE));
+    }
+    
+    for (const batch of batches) {
+      const promises = batch.map(async (path) => {
+        try {
+          if (path.endsWith('.html')) {
+            // Preload template
+            await this.loadTemplate(path, true);
+          } else if (path.endsWith('.css')) {
+            // Preload style (just fetch to cache)
+            await KimuAssetManager.fetchFile(path);
+          } else {
+            // Generic asset preload
+            await KimuAssetManager.fetchFile(path);
+          }
+        } catch (error) {
+          console.warn(`[KimuEngine] Failed to preload asset: ${path}`, error);
+        }
+      });
+      
+      await Promise.all(promises);
+    }
+    
+    console.log(`[KimuEngine] Preloading completed`);
+  }
+
+  /**
+   * Injects an inline style from a file into the Shadow DOM of a component.
+   * 
+   * @param component - The target component.
+   * @param stylePath - Path to the style file.
+   * @param styleId - Optional ID for the style element.
+   */
+  static async injectStyle(component: HTMLElement, stylePath: string, styleId: string | null = null): Promise<void> {
+    return KimuAssetManager.injectStyle(component, stylePath, styleId);
+  }
+
+  /**
+   * Loads and compiles an HTML template from a file into a Lit rendering function.
+   * 
+   * @param path - Path to the template file.
+   * @param useCache - Whether to use template cache (default: true)
+   * @returns A compiled Lit rendering function.
+   * @throws Error if the template file is not found.
+   */
+  static async loadTemplate(path: string, useCache: boolean = true) {
+    // Check cache first (if caching is enabled)
+    if (useCache && this._templateCache.has(path)) {
+      // Update access time for LRU
+      this._cacheAccessTime.set(path, Date.now());
+      return this._templateCache.get(path);
+    }
+
+    //console.log(`[KimuEngine] 🔄 Loading template: ${path}`);
+    const template: string | null = await KimuAssetManager.fetchFile(path);
+    if (!template) {
+      throw new Error(`[KimuEngine] ⚠️ Template not found: ${template}`);
+    }
+    
+    const compiledTemplate = KimuRender.loadTemplate(template);
+    
+    // Cache the compiled template (if caching is enabled)
+    if (useCache) {
+      // Check if we need to evict old entries first
+      this._evictOldestEntries();
+      
+      this._templateCache.set(path, compiledTemplate);
+      this._cacheAccessTime.set(path, Date.now());
+    }
+    
+    return compiledTemplate;
+  }
+
+  /**
+   * Compiles an HTML string into a dynamic Lit rendering function.
+   * 
+   * @param template - The HTML string to compile.
+   * @returns A Lit rendering function.
+   */
+  static compileTemplate(template: string): (html: typeof import('lit').html, data: Record<string, any>) => TemplateResult {
+    return KimuRender.compileTemplate(template);
+  }
+
+  /**
+   * Performs reactive rendering using Lit.
+   * 
+   * @param component - The target component.
+   * @param data - Data to be passed to the rendering function.
+   * @param renderFn - The Lit rendering function.
+   */
+  static render(component: HTMLElement, data: Record<string, any>, renderFn: (html: any, data: Record<string, any>) => TemplateResult): void {
+    KimuRender.render(component, data, renderFn);
+  }
+
+  /**
+   * Loads a component from a specified path and registers it if not already registered.
+   * 
+   * @param tag - The tag name of the component.
+   * @param path - Path to the component module.
+   * @returns The loaded module.
+   */
+  static async loadComponent(tag: string, path: string): Promise<any> {
+    if (customElements.get(tag)) {
+      return; // Already registered
+    }
+    const module = await import(/* @vite-ignore */ path);
+    return module;
+  }
+
+}