kimu-core 0.4.1

package/src/modules-repository/state/state-service.ts

@@ -0,0 +1,296 @@
+/**
+ * State Management Service for KIMU-Core
+ * 
+ * Provides reactive state management with observers and computed properties.
+ * Allows components to share and react to state changes.
+ * 
+ * @module StateService
+ * @version 1.0.0
+ */
+
+export type StateListener<T = any> = (newValue: T, oldValue: T) => void;
+export type ComputedGetter<T = any> = () => T;
+
+/**
+ * StateService - Reactive state management for KIMU applications
+ * 
+ * @example
+ * ```typescript
+ * import { stateService } from './modules/state/state-service';
+ * 
+ * // Set initial state
+ * stateService.setState('user', { id: 1, name: 'John' });
+ * 
+ * // Watch for changes
+ * stateService.watch('user', (newUser, oldUser) => {
+ *   console.log('User changed:', newUser);
+ * });
+ * 
+ * // Update state
+ * stateService.setState('user', { id: 1, name: 'Jane' });
+ * ```
+ */
+export class StateService {
+  private state: Map<string, any> = new Map();
+  private observers: Map<string, Set<StateListener>> = new Map();
+  private computed: Map<string, ComputedGetter> = new Map();
+  private computedCache: Map<string, any> = new Map();
+  private debugMode: boolean = false;
+
+  /**
+   * Enable or disable debug mode for state logging
+   */
+  setDebugMode(enabled: boolean): void {
+    this.debugMode = enabled;
+  }
+
+  /**
+   * Set a state value
+   * 
+   * @param key - State key
+   * @param value - New value
+   */
+  setState<T = any>(key: string, value: T): void {
+    const oldValue = this.state.get(key);
+    
+    // Check if value actually changed
+    if (oldValue === value || this.deepEqual(oldValue, value)) {
+      return;
+    }
+
+    this.state.set(key, value);
+
+    if (this.debugMode) {
+      console.log(`[State] Set: ${key}`, value);
+    }
+
+    // Notify observers
+    this.notifyObservers(key, value, oldValue);
+
+    // Invalidate computed properties that may depend on this key
+    this.invalidateComputedCache();
+  }
+
+  /**
+   * Get a state value
+   * 
+   * @param key - State key
+   * @param defaultValue - Default value if key doesn't exist
+   * @returns Current state value
+   */
+  getState<T = any>(key: string, defaultValue?: T): T | undefined {
+    return this.state.has(key) ? this.state.get(key) : defaultValue;
+  }
+
+  /**
+   * Update nested state properties
+   * 
+   * @param key - State key
+   * @param updates - Partial updates to merge
+   */
+  updateState<T = any>(key: string, updates: Partial<T>): void {
+    const current = this.getState<T>(key) || {} as T;
+    const updated = { ...current, ...updates };
+    this.setState(key, updated);
+  }
+
+  /**
+   * Delete a state key
+   * 
+   * @param key - State key to delete
+   */
+  deleteState(key: string): void {
+    const oldValue = this.state.get(key);
+    this.state.delete(key);
+
+    if (this.debugMode) {
+      console.log(`[State] Deleted: ${key}`);
+    }
+
+    // Notify observers with undefined as new value
+    this.notifyObservers(key, undefined, oldValue);
+  }
+
+  /**
+   * Check if a state key exists
+   * 
+   * @param key - State key
+   * @returns True if key exists
+   */
+  hasState(key: string): boolean {
+    return this.state.has(key);
+  }
+
+  /**
+   * Watch for state changes
+   * 
+   * @param key - State key to watch
+   * @param listener - Callback when state changes
+   * @returns Unwatch function
+   */
+  watch<T = any>(key: string, listener: StateListener<T>): () => void {
+    if (!this.observers.has(key)) {
+      this.observers.set(key, new Set());
+    }
+
+    this.observers.get(key)!.add(listener);
+
+    if (this.debugMode) {
+      console.log(`[State] Watching: ${key}`);
+    }
+
+    // Return unwatch function
+    return () => this.unwatch(key, listener);
+  }
+
+  /**
+   * Stop watching a state key
+   * 
+   * @param key - State key
+   * @param listener - Listener to remove
+   */
+  unwatch(key: string, listener: StateListener): void {
+    if (this.observers.has(key)) {
+      this.observers.get(key)!.delete(listener);
+
+      if (this.observers.get(key)!.size === 0) {
+        this.observers.delete(key);
+      }
+
+      if (this.debugMode) {
+        console.log(`[State] Unwatched: ${key}`);
+      }
+    }
+  }
+
+  /**
+   * Define a computed property
+   * 
+   * @param key - Computed property key
+   * @param getter - Function that computes the value
+   */
+  defineComputed<T = any>(key: string, getter: ComputedGetter<T>): void {
+    this.computed.set(key, getter);
+    this.computedCache.delete(key); // Invalidate cache
+
+    if (this.debugMode) {
+      console.log(`[State] Computed defined: ${key}`);
+    }
+  }
+
+  /**
+   * Get a computed property value (cached)
+   * 
+   * @param key - Computed property key
+   * @returns Computed value
+   */
+  getComputed<T = any>(key: string): T | undefined {
+    if (!this.computed.has(key)) {
+      return undefined;
+    }
+
+    // Return cached value if available
+    if (this.computedCache.has(key)) {
+      return this.computedCache.get(key);
+    }
+
+    // Compute and cache
+    const getter = this.computed.get(key)!;
+    const value = getter();
+    this.computedCache.set(key, value);
+
+    if (this.debugMode) {
+      console.log(`[State] Computed: ${key}`, value);
+    }
+
+    return value;
+  }
+
+  /**
+   * Get all state as a plain object
+   */
+  getAll(): Record<string, any> {
+    return Object.fromEntries(this.state.entries());
+  }
+
+  /**
+   * Clear all state
+   */
+  clear(): void {
+    this.state.clear();
+    this.observers.clear();
+    this.computed.clear();
+    this.computedCache.clear();
+
+    if (this.debugMode) {
+      console.log('[State] Cleared all state');
+    }
+  }
+
+  /**
+   * Reset state to initial values
+   * 
+   * @param initialState - Initial state object
+   */
+  reset(initialState: Record<string, any> = {}): void {
+    this.clear();
+    Object.entries(initialState).forEach(([key, value]) => {
+      this.setState(key, value);
+    });
+  }
+
+  /**
+   * Subscribe to multiple state keys
+   * 
+   * @param keys - Array of state keys
+   * @param listener - Callback when any key changes
+   * @returns Unsubscribe function
+   */
+  watchMultiple(keys: string[], listener: (key: string, newValue: any, oldValue: any) => void): () => void {
+    const unwatchers = keys.map(key => 
+      this.watch(key, (newValue, oldValue) => listener(key, newValue, oldValue))
+    );
+
+    return () => unwatchers.forEach(unwatch => unwatch());
+  }
+
+  // Private helpers
+
+  private notifyObservers(key: string, newValue: any, oldValue: any): void {
+    if (this.observers.has(key)) {
+      const listeners = Array.from(this.observers.get(key)!);
+      listeners.forEach(listener => {
+        try {
+          listener(newValue, oldValue);
+        } catch (error) {
+          console.error(`[State] Error in observer for "${key}":`, error);
+        }
+      });
+    }
+  }
+
+  private invalidateComputedCache(): void {
+    this.computedCache.clear();
+  }
+
+  private deepEqual(a: any, b: any): boolean {
+    if (a === b) return true;
+    if (a == null || b == null) return false;
+    if (typeof a !== 'object' || typeof b !== 'object') return false;
+
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+
+    if (keysA.length !== keysB.length) return false;
+
+    for (const key of keysA) {
+      if (!keysB.includes(key)) return false;
+      if (!this.deepEqual(a[key], b[key])) return false;
+    }
+
+    return true;
+  }
+}
+
+// Export singleton instance
+export const stateService = new StateService();

package/src/modules-repository/theme/README.md

@@ -0,0 +1,267 @@
+# Theme Module - CSS-Based Theme Management
+
+## Overview
+
+The **Theme Module** provides a complete CSS-based theme management system for KIMU-Core applications. It supports multiple predefined themes (Light, Dark, Ocean, Cozy) and allows easy registration of custom themes through external CSS files.
+
+## Architecture
+
+The theme module uses **KIMU Global Styles** system to inject theme CSS into all extensions automatically:
+
+1. **KimuGlobalStyles** (core): Manages CSS files that should be injected in all extensions
+2. **ThemeService**: Registers the active theme CSS as a global style
+3. **KimuComponentElement**: Automatically injects all global styles into each extension's shadow root
+4. **themes-config.json**: Configuration file with all available themes
+
+This architecture ensures:
+- ✅ Theme module is **optional** - framework works without it (fallback styles in `style.css`)
+- ✅ Themes are automatically applied to **all extensions** (including shadow DOM)
+- ✅ Theme changes propagate to **existing extensions** dynamically
+- ✅ **No hardcoded dependencies** in core framework
+- ✅ **Easy theme management** via JSON configuration file
+
+## Module Structure
+
+```
+src/modules/theme/
+├── themes/                    # Theme source CSS files
+│   ├── theme-light.css
+│   ├── theme-dark.css
+│   ├── theme-ocean.css
+│   ├── theme-cozy.css
+│   ├── theme-nord.css
+│   ├── theme-forest.css
+│   ├── theme-high-contrast.css
+│   └── theme-cyberpunk.css
+├── themes-config.json         # Theme configuration
+├── pre-build.js               # Pre-build script (copies themes to public/)
+├── theme-service.ts           # Main service
+└── README.md                  # This file
+```
+
+**Build Process**: The pre-build script automatically copies all CSS files from `themes/` to `public/themes/` before compilation.
+
+## Features
+
+- 🎨 **CSS-Based Themes**: Each theme is a separate CSS file for maximum flexibility
+- ☀️ **Light Mode**: Clean and bright theme for daytime use  
+- 🌙 **Dark Mode**: Dark theme for low-light environments
+- 🌊 **Ocean Theme**: Ocean-inspired dark theme with blue-green tones
+- 🌸 **Cozy Theme**: Warm, feminine and cozy theme with soft colors
+- ❄️ **Nord Theme**: Cold and relaxing Nordic theme for developers
+- 🌲 **Forest Theme**: Natural green theme inspired by nature
+- ⚡ **High Contrast Theme**: WCAG AAA accessible theme
+- 🎮 **Cyberpunk Theme**: Futuristic neon aesthetic
+- 🔄 **Auto Mode**: Automatically follows system color scheme preferences
+- 💾 **Persistence**: User preferences saved in localStorage
+- 🎯 **System Integration**: MediaQuery API for system preference detection
+- 🔌 **Extensible**: Easy registration of custom CSS themes
+- 🌐 **Global Styles**: Themes automatically injected in all extensions via Global Styles system
+
+## Quick Start
+
+### Basic Usage
+
+\`\`\`typescript
+import { themeService } from './modules/theme/theme-service';
+
+// Set theme
+themeService.setMode('dark');    // Switch to dark theme
+themeService.setMode('light');   // Switch to light theme
+themeService.setMode('ocean');   // Switch to ocean theme
+themeService.setMode('cozy');    // Switch to cozy theme
+themeService.setMode('auto');    // Use system preference
+
+// Quick toggle
+themeService.toggle();           // Toggle between light/dark
+
+// Get current theme
+const mode = themeService.getMode();
+const themeName = themeService.getCurrentThemeName();
+\`\`\`
+
+### Listen to Theme Changes
+
+\`\`\`typescript
+themeService.onChange((themeName: string, mode: string) => {
+  console.log(\`Theme changed to: \${themeName}\`);
+});
+\`\`\`
+
+## Available Themes
+
+### 1. Light Theme
+Clean and bright theme optimized for daytime use.
+
+### 2. Dark Theme
+Dark theme for low-light environments and reduced eye strain.
+
+### 3. Ocean Theme
+Ocean-inspired dark theme with blue-green tones.
+
+### 4. Cozy Theme
+Warm, feminine and cozy theme with soft pastel colors.
+
+## Creating Custom Themes
+
+### Step 1: Create CSS File
+
+\`\`\`css
+/* my-custom-theme.css */
+:root {
+  --kimu-primary: #your-color;
+  --kimu-background: #your-background;
+  --kimu-text-primary: #your-text-color;
+  /* ...other variables... */
+}
+\`\`\`
+
+### Step 2: Register the Theme
+
+\`\`\`typescript
+themeService.registerCssTheme({
+  name: 'my-theme',
+  mode: 'dark',
+  cssPath: '/themes/my-custom-theme.css',
+  description: 'My awesome custom theme'
+});
+\`\`\`
+
+### Step 3: Apply the Theme
+
+\`\`\`typescript
+themeService.setMode('my-theme');
+\`\`\`
+
+## Using CSS Variables
+
+\`\`\`css
+.my-component {
+  background: var(--kimu-background);
+  color: var(--kimu-text-primary);
+  border: 1px solid var(--kimu-border);
+}
+
+.my-button {
+  background: var(--kimu-primary);
+  color: white;
+}
+\`\`\`
+
+## Module Independence & Fallback System
+
+### How It Works
+
+The theme system is designed to work as an **optional module**:
+
+1. **Without Theme Module**: 
+   - Default CSS variables are defined in `src/assets/style.css`
+   - Application has basic Light theme styling
+   - All components work normally with default colors
+
+2. **With Theme Module**:
+   - Theme CSS files **override** default values from `style.css`
+   - Dynamic theme switching available
+   - User preferences persist across sessions
+
+### Architecture
+
+\`\`\`
+┌─────────────────────────────────────────────┐
+│ style.css (ALWAYS loaded)                  │
+│ :root { --kimu-primary: #667eea; }         │  ← DEFAULT values
+└─────────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────┐
+│ theme-dark.css (OPTIONAL, loaded by module)│
+│ :root { --kimu-primary: #818cf8; }         │  ← OVERRIDES defaults
+└─────────────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────┐
+│ Components use variables                    │
+│ button { background: var(--kimu-primary); }│  ← Uses active value
+└─────────────────────────────────────────────┘
+\`\`\`
+
+### Benefits
+
+✅ **App works without theme module** - defaults provide basic styling
+✅ **No breaking changes** - removing theme module doesn't break the app
+✅ **Gradual adoption** - themes can be added later
+✅ **Consistent API** - components always use same CSS variables
+
+### CSS Variable Priority
+
+When theme module is active:
+\`\`\`
+Theme CSS values > Default style.css values > Browser defaults
+\`\`\`
+
+When theme module is NOT installed:
+\`\`\`
+Default style.css values > Browser defaults
+\`\`\`
+
+## Theme Configuration File
+
+### Structure
+
+The theme module uses a JSON configuration file (`themes-config.json`) to define available themes:
+
+```json
+{
+  "themes": [
+    {
+      "name": "light",
+      "mode": "light",
+      "cssPath": "theme-light.css",
+      "description": "Clean and bright theme"
+    },
+    {
+      "name": "dark",
+      "mode": "dark",
+      "cssPath": "theme-dark.css",
+      "description": "Dark theme for low-light environments"
+    }
+  ],
+  "defaultTheme": "light"
+}
+```
+
+### Adding New Themes
+
+To add a new theme, simply:
+
+1. Create the CSS file in `src/modules/theme/themes/` (e.g., `theme-nord.css`)
+2. Add entry to `src/modules/theme/themes-config.json`:
+
+```json
+{
+  "name": "nord",
+  "mode": "dark",
+  "cssPath": "theme-nord.css",
+  "description": "Cold and relaxing Nordic theme"
+}
+```
+
+3. Run `npm run build` to copy themes to `public/themes/` (via pre-build script)
+4. The pre-build script automatically copies all CSS files from `src/modules/theme/themes/` to `public/themes/`
+
+**Benefits of configuration file:**
+- ✅ No code changes needed to add themes
+- ✅ Easy to maintain and extend
+- ✅ Clear separation of configuration and logic
+- ✅ Can be easily customized per deployment
+
+### Theme Configuration Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | ✅ | Unique theme identifier (used in `setMode()`) |
+| `mode` | 'light' \| 'dark' | ✅ | Base mode for system preference detection |
+| `cssPath` | string | ✅ | CSS file name in `public/themes/` folder |
+| `description` | string | ❌ | Human-readable theme description |
+
+## License
+
+This module is part of KIMU-Core and is licensed under the Mozilla Public License 2.0 (MPL-2.0).

package/src/modules-repository/theme/module.ts

@@ -0,0 +1,30 @@
+/**
+ * Theme Module for KIMU-Core
+ * 
+ * Provides centralized theme management with dark/light/auto modes.
+ * 
+ * @module ThemeModule
+ */
+
+import { KimuModule } from '../../core/kimu-module';
+import { themeService } from './theme-service'
+/**
+ * ThemeModule - Module class for theme management integration
+ */
+export default class ThemeModule extends KimuModule {
+  constructor(name = 'theme', version = '1.0.0', options?: any) {
+    super(name, version, options);
+  }
+
+  /**
+   * Get the theme service instance
+   */
+  getService() {
+    return themeService;
+  }
+}
+
+// Re-export for convenience
+export { themeService } from './theme-service';
+export { ThemeService } from './theme-service';
+export type { ThemeMode, CssTheme } from './theme-service';

package/src/modules-repository/theme/pre-build.js

@@ -0,0 +1,40 @@
+/**
+ * Pre-Build Script for Theme Module
+ * 
+ * This script runs BEFORE the theme module is compiled.
+ * It copies CSS theme files to public/themes/ so they're available
+ * during development and will be included in the Vite build.
+ * 
+ * This approach keeps the module self-contained and independent.
+ */
+import fs from 'fs';
+import path from 'path';
+
+export default async function preBuild({ moduleDir, rootDir }) {
+  const themesDir = path.join(moduleDir, 'themes');
+  
+  if (!fs.existsSync(themesDir)) {
+    console.log('⚠️  No themes directory found, skipping theme copy');
+    return;
+  }
+
+  const cssFiles = fs.readdirSync(themesDir).filter(f => f.endsWith('.css'));
+  
+  if (cssFiles.length === 0) {
+    console.log('⚠️  No CSS files found in themes directory');
+    return;
+  }
+
+  // Copy to public/themes/ (Vite will include them in build automatically)
+  const publicThemesDir = path.join(rootDir, 'public', 'themes');
+  fs.mkdirSync(publicThemesDir, { recursive: true });
+  
+  for (const cssFile of cssFiles) {
+    fs.copyFileSync(
+      path.join(themesDir, cssFile),
+      path.join(publicThemesDir, cssFile)
+    );
+  }
+
+  console.log(`📄 Theme module: Copied ${cssFiles.length} CSS files to public/themes/`);
+}