kimu-core 0.4.1 → 0.4.2

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

@@ -1,136 +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);
-      }
-    }
-  }
-}
+/**
+ * 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-reactive.ts

@@ -1,196 +1,196 @@
-/**
- * KIMU Reactive System - Optimized & Minimal
- * 
- * Lightweight reactive property decorator for KIMU components.
- * Designed for simplicity, performance, and minimal bundle size.
- * 
- * Philosophy: KIMU is intentionally minimal. We focus on doing the essentials
- * perfectly, not everything adequately. For complex reactivity needs, use Vue/React.
- * 
- * Usage Example:
- * 
- * ```typescript
- * export class MyComponent extends KimuComponentElement {
- *   @property({ type: Number })
- *   counter = 0;
- * 
- *   @property({ type: String, reflect: true })
- *   label = 'Counter';
- * 
- *   increment() {
- *     this.counter++; // Auto re-render!
- *   }
- * }
- * ```
- */
-
-/**
- * Options for the @property decorator
- */
-export interface PropertyOptions {
-  /**
-   * The type of the property. Used for type conversion.
-   * Supported types: String, Number, Boolean
-   */
-  type?: StringConstructor | NumberConstructor | BooleanConstructor;
-  
-  /**
-   * Whether the property should reflect to an attribute.
-   * If true, changes to the property will update the corresponding HTML attribute.
-   */
-  reflect?: boolean;
-}
-
-/**
- * Convert property name to attribute name (camelCase to kebab-case)
- */
-const toKebab = (str: string): string => str.replace(/([A-Z])/g, '-$1').toLowerCase();
-
-/**
- * Convert value to specified type
- * @param value - Value to convert
- * @param type - Target type constructor
- * @returns Converted value
- */
-function convert(value: any, type?: any): any {
-  if (!type) return value;
-  if (type === Number) return value == null ? 0 : Number(value) || 0;
-  if (type === Boolean) return value !== null && value !== 'false' && value !== false;
-  if (type === String) return value == null ? '' : String(value);
-  return value;
-}
-
-/**
- * Reactive property decorator
- * 
- * Transforms a class property into a reactive property that automatically
- * triggers re-rendering when its value changes.
- * 
- * @param options - Configuration options for the reactive property
- * @returns Property decorator function
- * 
- * @example
- * ```typescript
- * export class Counter extends KimuComponentElement {
- *   @property({ type: Number })
- *   count = 0;
- * 
- *   @property({ type: String, reflect: true })
- *   label = 'Counter';
- * }
- * ```
- */
-export function property(options: PropertyOptions = {}) {
-  return function (target: any, propertyKey: string) {
-    const privateKey = `__${propertyKey}`;
-    const { type, reflect = false } = options;
-    const attrName = toKebab(propertyKey);
-    
-    // Store metadata for attribute observation
-    const ctor = target.constructor;
-    if (!ctor.__kimu_reactive_props__) {
-      ctor.__kimu_reactive_props__ = new Map();
-      ctor.__kimu_attr_to_prop__ = new Map(); // Inverse map for O(1) lookup
-    }
-    ctor.__kimu_reactive_props__.set(propertyKey, { type, reflect, attribute: attrName });
-    ctor.__kimu_attr_to_prop__.set(attrName, { propertyKey, type }); // Store inverse mapping
-    
-    // Define the reactive property with optimized getter/setter
-    Object.defineProperty(target, propertyKey, {
-      get() {
-        return this[privateKey];
-      },
-      set(value: any) {
-        const oldValue = this[privateKey];
-        const newValue = type ? convert(value, type) : value;
-        
-        // Early return if value hasn't changed
-        if (oldValue === newValue) return;
-        
-        this[privateKey] = newValue;
-        
-        // Reflect to attribute if enabled (optimized conditionals)
-        if (reflect && this instanceof HTMLElement) {
-          if (newValue == null || newValue === false) {
-            this.removeAttribute(attrName);
-          } else {
-            this.setAttribute(attrName, type === Boolean ? '' : String(newValue));
-          }
-        }
-        
-        // Batched re-render using RAF (prevents multiple renders in same frame)
-        // Call refresh directly - it already handles RAF batching internally
-        if (typeof this.refresh === 'function') {
-          this.refresh();
-        }
-      },
-      enumerable: true,
-      configurable: true
-    });
-  };
-}
-
-
-/**
- * Initialize reactive properties from attributes
- * 
- * This should be called in the connectedCallback of components that use @property
- * 
- * @param component - The component instance
- */
-export function initReactiveProperties(component: any): void {
-  const props = component.constructor.__kimu_reactive_props__;
-  if (!props) return;
-  
-  // Initialize properties from attributes
-  props.forEach((options: any, propertyKey: string) => {
-    const attrValue = component.getAttribute(options.attribute);
-    if (attrValue !== null) {
-      (component as any)[propertyKey] = convert(attrValue, options.type);
-    }
-  });
-}
-
-/**
- * Get observed attributes for reactive properties
- * 
- * @param componentClass - The component class
- * @returns Array of observed attributes
- */
-export function getObservedAttributes(componentClass: any): string[] {
-  const props = componentClass.__kimu_reactive_props__;
-  if (!props) return [];
-  
-  return Array.from(props.values())
-    .map((opts: any) => opts.attribute)
-    .filter(Boolean);
-}
-
-/**
- * Handle attribute changes for reactive properties
- * 
- * This should be called from attributeChangedCallback
- * 
- * @param component - The component instance
- * @param name - Attribute name
- * @param oldValue - Old attribute value
- * @param newValue - New attribute value
- */
-export function handleAttributeChange(
-  component: any,
-  name: string,
-  _oldValue: string | null,
-  newValue: string | null
-): void {
-  const attrMap = component.constructor.__kimu_attr_to_prop__;
-  if (!attrMap) return;
-  
-  // O(1) lookup using inverse map
-  const propInfo = attrMap.get(name);
-  if (propInfo) {
-    component[propInfo.propertyKey] = newValue !== null 
-      ? convert(newValue, propInfo.type) 
-      : null;
-  }
-}
-
+/**
+ * KIMU Reactive System - Optimized & Minimal
+ * 
+ * Lightweight reactive property decorator for KIMU components.
+ * Designed for simplicity, performance, and minimal bundle size.
+ * 
+ * Philosophy: KIMU is intentionally minimal. We focus on doing the essentials
+ * perfectly, not everything adequately. For complex reactivity needs, use Vue/React.
+ * 
+ * Usage Example:
+ * 
+ * ```typescript
+ * export class MyComponent extends KimuComponentElement {
+ *   @property({ type: Number })
+ *   counter = 0;
+ * 
+ *   @property({ type: String, reflect: true })
+ *   label = 'Counter';
+ * 
+ *   increment() {
+ *     this.counter++; // Auto re-render!
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Options for the @property decorator
+ */
+export interface PropertyOptions {
+  /**
+   * The type of the property. Used for type conversion.
+   * Supported types: String, Number, Boolean
+   */
+  type?: StringConstructor | NumberConstructor | BooleanConstructor;
+  
+  /**
+   * Whether the property should reflect to an attribute.
+   * If true, changes to the property will update the corresponding HTML attribute.
+   */
+  reflect?: boolean;
+}
+
+/**
+ * Convert property name to attribute name (camelCase to kebab-case)
+ */
+const toKebab = (str: string): string => str.replace(/([A-Z])/g, '-$1').toLowerCase();
+
+/**
+ * Convert value to specified type
+ * @param value - Value to convert
+ * @param type - Target type constructor
+ * @returns Converted value
+ */
+function convert(value: any, type?: any): any {
+  if (!type) return value;
+  if (type === Number) return value == null ? 0 : Number(value) || 0;
+  if (type === Boolean) return value !== null && value !== 'false' && value !== false;
+  if (type === String) return value == null ? '' : String(value);
+  return value;
+}
+
+/**
+ * Reactive property decorator
+ * 
+ * Transforms a class property into a reactive property that automatically
+ * triggers re-rendering when its value changes.
+ * 
+ * @param options - Configuration options for the reactive property
+ * @returns Property decorator function
+ * 
+ * @example
+ * ```typescript
+ * export class Counter extends KimuComponentElement {
+ *   @property({ type: Number })
+ *   count = 0;
+ * 
+ *   @property({ type: String, reflect: true })
+ *   label = 'Counter';
+ * }
+ * ```
+ */
+export function property(options: PropertyOptions = {}) {
+  return function (target: any, propertyKey: string) {
+    const privateKey = `__${propertyKey}`;
+    const { type, reflect = false } = options;
+    const attrName = toKebab(propertyKey);
+    
+    // Store metadata for attribute observation
+    const ctor = target.constructor;
+    if (!ctor.__kimu_reactive_props__) {
+      ctor.__kimu_reactive_props__ = new Map();
+      ctor.__kimu_attr_to_prop__ = new Map(); // Inverse map for O(1) lookup
+    }
+    ctor.__kimu_reactive_props__.set(propertyKey, { type, reflect, attribute: attrName });
+    ctor.__kimu_attr_to_prop__.set(attrName, { propertyKey, type }); // Store inverse mapping
+    
+    // Define the reactive property with optimized getter/setter
+    Object.defineProperty(target, propertyKey, {
+      get() {
+        return this[privateKey];
+      },
+      set(value: any) {
+        const oldValue = this[privateKey];
+        const newValue = type ? convert(value, type) : value;
+        
+        // Early return if value hasn't changed
+        if (oldValue === newValue) return;
+        
+        this[privateKey] = newValue;
+        
+        // Reflect to attribute if enabled (optimized conditionals)
+        if (reflect && this instanceof HTMLElement) {
+          if (newValue == null || newValue === false) {
+            this.removeAttribute(attrName);
+          } else {
+            this.setAttribute(attrName, type === Boolean ? '' : String(newValue));
+          }
+        }
+        
+        // Batched re-render using RAF (prevents multiple renders in same frame)
+        // Call refresh directly - it already handles RAF batching internally
+        if (typeof this.refresh === 'function') {
+          this.refresh();
+        }
+      },
+      enumerable: true,
+      configurable: true
+    });
+  };
+}
+
+
+/**
+ * Initialize reactive properties from attributes
+ * 
+ * This should be called in the connectedCallback of components that use @property
+ * 
+ * @param component - The component instance
+ */
+export function initReactiveProperties(component: any): void {
+  const props = component.constructor.__kimu_reactive_props__;
+  if (!props) return;
+  
+  // Initialize properties from attributes
+  props.forEach((options: any, propertyKey: string) => {
+    const attrValue = component.getAttribute(options.attribute);
+    if (attrValue !== null) {
+      (component as any)[propertyKey] = convert(attrValue, options.type);
+    }
+  });
+}
+
+/**
+ * Get observed attributes for reactive properties
+ * 
+ * @param componentClass - The component class
+ * @returns Array of observed attributes
+ */
+export function getObservedAttributes(componentClass: any): string[] {
+  const props = componentClass.__kimu_reactive_props__;
+  if (!props) return [];
+  
+  return Array.from(props.values())
+    .map((opts: any) => opts.attribute)
+    .filter(Boolean);
+}
+
+/**
+ * Handle attribute changes for reactive properties
+ * 
+ * This should be called from attributeChangedCallback
+ * 
+ * @param component - The component instance
+ * @param name - Attribute name
+ * @param oldValue - Old attribute value
+ * @param newValue - New attribute value
+ */
+export function handleAttributeChange(
+  component: any,
+  name: string,
+  _oldValue: string | null,
+  newValue: string | null
+): void {
+  const attrMap = component.constructor.__kimu_attr_to_prop__;
+  if (!attrMap) return;
+  
+  // O(1) lookup using inverse map
+  const propInfo = attrMap.get(name);
+  if (propInfo) {
+    component[propInfo.propertyKey] = newValue !== null 
+      ? convert(newValue, propInfo.type) 
+      : null;
+  }
+}
+