kimu-core 0.4.1

package/src/modules-repository/event-bus/README.md

@@ -0,0 +1,273 @@
+# Event Bus Module
+
+## Overview
+The Event Bus module provides a global publish/subscribe mechanism for component communication in KIMU-Core applications. It enables loose coupling between components by allowing them to emit and listen to custom events without direct references.
+
+## Features
+- ✅ **Global event bus** - Centralized communication hub
+- ✅ **Type-safe callbacks** - TypeScript support for event handlers
+- ✅ **Auto-unsubscribe** - Subscription objects with cleanup
+- ✅ **Once subscriptions** - Auto-unsubscribe after first event
+- ✅ **Debug mode** - Optional logging for development
+- ✅ **Error handling** - Isolated callback errors don't affect other subscribers
+- ✅ **Event introspection** - Query registered events and subscriber counts
+
+## Installation
+The Event Bus module is included in KIMU-Core. No additional installation required.
+
+## Usage
+
+### Basic Example
+```typescript
+import { eventBusService } from './modules/event-bus/event-bus-service';
+
+// Subscribe to an event
+const subscription = eventBusService.on('user:login', (user) => {
+  console.log('User logged in:', user);
+});
+
+// Emit an event
+eventBusService.emit('user:login', { id: 1, name: 'John Doe' });
+
+// Unsubscribe when done
+subscription.unsubscribe();
+```
+
+### In a Component
+```typescript
+import { KimuComponent } from '../core/kimu-component';
+import { KimuComponentElement } from '../core/kimu-component-element';
+import { eventBusService } from '../modules/event-bus/event-bus-service';
+
+@KimuComponent({
+  tag: 'my-component',
+  name: 'My Component',
+  // ...
+})
+export class MyComponent extends KimuComponentElement {
+  private subscriptions: any[] = [];
+
+  onInit() {
+    // Subscribe to events
+    this.subscriptions.push(
+      eventBusService.on('data:updated', this.handleDataUpdate.bind(this))
+    );
+    
+    this.subscriptions.push(
+      eventBusService.on('theme:changed', this.handleThemeChange.bind(this))
+    );
+  }
+
+  handleDataUpdate(data: any) {
+    console.log('Data updated:', data);
+    this.onRender();
+  }
+
+  handleThemeChange(theme: string) {
+    console.log('Theme changed:', theme);
+    // Update UI based on theme
+  }
+
+  // Emit events
+  saveData() {
+    // ... save logic
+    eventBusService.emit('data:saved', { timestamp: Date.now() });
+  }
+
+  // Clean up on component destroy
+  disconnectedCallback() {
+    this.subscriptions.forEach(sub => sub.unsubscribe());
+    super.disconnectedCallback();
+  }
+}
+```
+
+### One-time Events
+```typescript
+// Subscribe only once
+eventBusService.once('app:initialized', () => {
+  console.log('App initialized!');
+});
+
+// This will trigger the callback and auto-unsubscribe
+eventBusService.emit('app:initialized');
+```
+
+### Debug Mode
+```typescript
+// Enable debug logging
+eventBusService.setDebugMode(true);
+
+// All subscriptions, emissions, and unsubscriptions will be logged
+eventBusService.on('test:event', () => {});
+// Console: [EventBus] Subscribed to: test:event
+
+eventBusService.emit('test:event', 'data');
+// Console: [EventBus] Emitting: test:event ['data']
+```
+
+### Event Introspection
+```typescript
+// Get list of all registered events
+const events = eventBusService.getEventList();
+console.log('Active events:', events);
+
+// Check subscriber count
+const count = eventBusService.getSubscriberCount('user:login');
+console.log(`Subscribers for user:login: ${count}`);
+
+// Check if event has subscribers
+if (eventBusService.hasSubscribers('data:updated')) {
+  console.log('Someone is listening to data:updated');
+}
+```
+
+## API Reference
+
+### `eventBusService.on(event, callback)`
+Subscribe to an event.
+- **event**: `string` - Event name
+- **callback**: `Function` - Handler function
+- **Returns**: `EventSubscription` - Subscription object with `unsubscribe()` method
+
+### `eventBusService.once(event, callback)`
+Subscribe to an event once (auto-unsubscribe after first emission).
+- **event**: `string` - Event name
+- **callback**: `Function` - Handler function
+- **Returns**: `EventSubscription` - Subscription object
+
+### `eventBusService.emit(event, ...args)`
+Emit an event to all subscribers.
+- **event**: `string` - Event name
+- **args**: `any[]` - Arguments to pass to callbacks
+
+### `eventBusService.off(event, callback)`
+Unsubscribe from an event.
+- **event**: `string` - Event name
+- **callback**: `Function` - Callback to remove
+
+### `eventBusService.clear(event?)`
+Remove all subscribers for a specific event or all events.
+- **event**: `string` (optional) - Event name
+
+### `eventBusService.setDebugMode(enabled)`
+Enable or disable debug logging.
+- **enabled**: `boolean` - Debug mode state
+
+### `eventBusService.getEventList()`
+Get list of all registered events.
+- **Returns**: `string[]` - Array of event names
+
+### `eventBusService.getSubscriberCount(event)`
+Get number of subscribers for a specific event.
+- **event**: `string` - Event name
+- **Returns**: `number` - Subscriber count
+
+### `eventBusService.hasSubscribers(event)`
+Check if an event has any subscribers.
+- **event**: `string` - Event name
+- **Returns**: `boolean` - True if event has subscribers
+
+## Event Naming Conventions
+Use namespaced event names for better organization:
+- `user:login`, `user:logout`, `user:updated`
+- `data:loaded`, `data:saved`, `data:error`
+- `ui:theme-changed`, `ui:modal-opened`, `ui:notification`
+- `app:initialized`, `app:ready`, `app:shutdown`
+
+## Best Practices
+
+### 1. Always Unsubscribe
+```typescript
+class MyComponent extends KimuComponentElement {
+  private subscriptions: any[] = [];
+
+  onInit() {
+    this.subscriptions.push(
+      eventBusService.on('event', this.handler.bind(this))
+    );
+  }
+
+  disconnectedCallback() {
+    this.subscriptions.forEach(sub => sub.unsubscribe());
+    super.disconnectedCallback();
+  }
+}
+```
+
+### 2. Use Namespaced Events
+```typescript
+// Good
+eventBusService.emit('user:profile:updated', userData);
+eventBusService.emit('notification:success', message);
+
+// Avoid generic names
+eventBusService.emit('update', data); // Too generic!
+```
+
+### 3. Document Event Payloads
+```typescript
+/**
+ * Event: user:login
+ * Payload: { id: number, name: string, email: string }
+ */
+eventBusService.emit('user:login', { id: 1, name: 'John', email: 'john@example.com' });
+```
+
+### 4. Handle Errors
+```typescript
+eventBusService.on('data:process', (data) => {
+  try {
+    processData(data);
+  } catch (error) {
+    eventBusService.emit('data:error', error);
+  }
+});
+```
+
+## Common Use Cases
+
+### 1. Component Communication
+```typescript
+// Component A emits
+eventBusService.emit('cart:item-added', { id: 123, name: 'Product' });
+
+// Component B listens
+eventBusService.on('cart:item-added', (item) => {
+  updateCartCount();
+});
+```
+
+### 2. State Synchronization
+```typescript
+// When state changes
+eventBusService.emit('state:updated', newState);
+
+// Components react to state changes
+eventBusService.on('state:updated', (state) => {
+  this.updateUI(state);
+});
+```
+
+### 3. User Actions
+```typescript
+// Button click
+eventBusService.emit('button:save-clicked', { form: 'userProfile' });
+
+// Multiple handlers can react
+eventBusService.on('button:save-clicked', validateForm);
+eventBusService.on('button:save-clicked', showLoadingIndicator);
+eventBusService.on('button:save-clicked', trackAnalytics);
+```
+
+## Performance Considerations
+- Event bus is synchronous - handlers execute immediately
+- Use wisely for frequently emitted events (e.g., scroll, mousemove)
+- Consider debouncing or throttling for high-frequency events
+- Always clean up subscriptions to prevent memory leaks
+
+## License
+This module is part of KIMU-Core and follows the same license (MPL-2.0).
+
+## Version History
+- **1.0.0** - Initial release with core event bus functionality

package/src/modules-repository/event-bus/event-bus-service.ts

@@ -0,0 +1,176 @@
+/**
+ * Event Bus Service for KIMU-Core
+ * 
+ * Provides a global publish/subscribe mechanism for component communication.
+ * Components can emit and listen to custom events without direct coupling.
+ * 
+ * @module EventBusService
+ * @version 1.0.0
+ */
+
+export type EventCallback = (...args: any[]) => void;
+
+export interface EventSubscription {
+  event: string;
+  callback: EventCallback;
+  unsubscribe: () => void;
+}
+
+/**
+ * EventBusService - Global event bus for component communication
+ * 
+ * @example
+ * ```typescript
+ * import { eventBusService } from './modules/event-bus/event-bus-service';
+ * 
+ * // Subscribe to an event
+ * const subscription = eventBusService.on('user:login', (user) => {
+ *   console.log('User logged in:', user);
+ * });
+ * 
+ * // Emit an event
+ * eventBusService.emit('user:login', { id: 1, name: 'John' });
+ * 
+ * // Unsubscribe
+ * subscription.unsubscribe();
+ * ```
+ */
+export class EventBusService {
+  private events: Map<string, Set<EventCallback>> = new Map();
+  private debugMode: boolean = false;
+
+  /**
+   * Enable or disable debug mode for event logging
+   */
+  setDebugMode(enabled: boolean): void {
+    this.debugMode = enabled;
+  }
+
+  /**
+   * Subscribe to an event
+   * 
+   * @param event - Event name (e.g., 'user:login', 'data:updated')
+   * @param callback - Function to call when event is emitted
+   * @returns Subscription object with unsubscribe method
+   */
+  on(event: string, callback: EventCallback): EventSubscription {
+    if (!this.events.has(event)) {
+      this.events.set(event, new Set());
+    }
+    
+    this.events.get(event)!.add(callback);
+    
+    if (this.debugMode) {
+      console.log(`[EventBus] Subscribed to: ${event}`);
+    }
+
+    return {
+      event,
+      callback,
+      unsubscribe: () => this.off(event, callback)
+    };
+  }
+
+  /**
+   * Subscribe to an event only once (auto-unsubscribe after first emit)
+   * 
+   * @param event - Event name
+   * @param callback - Function to call when event is emitted
+   * @returns Subscription object
+   */
+  once(event: string, callback: EventCallback): EventSubscription {
+    const wrappedCallback = (...args: any[]) => {
+      callback(...args);
+      this.off(event, wrappedCallback);
+    };
+
+    return this.on(event, wrappedCallback);
+  }
+
+  /**
+   * Unsubscribe from an event
+   * 
+   * @param event - Event name
+   * @param callback - Callback to remove
+   */
+  off(event: string, callback: EventCallback): void {
+    if (this.events.has(event)) {
+      this.events.get(event)!.delete(callback);
+      
+      // Clean up empty event sets
+      if (this.events.get(event)!.size === 0) {
+        this.events.delete(event);
+      }
+
+      if (this.debugMode) {
+        console.log(`[EventBus] Unsubscribed from: ${event}`);
+      }
+    }
+  }
+
+  /**
+   * Emit an event to all subscribers
+   * 
+   * @param event - Event name
+   * @param args - Arguments to pass to callbacks
+   */
+  emit(event: string, ...args: any[]): void {
+    if (this.debugMode) {
+      console.log(`[EventBus] Emitting: ${event}`, args);
+    }
+
+    if (this.events.has(event)) {
+      const callbacks = Array.from(this.events.get(event)!);
+      callbacks.forEach(callback => {
+        try {
+          callback(...args);
+        } catch (error) {
+          console.error(`[EventBus] Error in event handler for "${event}":`, error);
+        }
+      });
+    }
+  }
+
+  /**
+   * Remove all subscribers for a specific event or all events
+   * 
+   * @param event - Event name (optional, if not provided clears all)
+   */
+  clear(event?: string): void {
+    if (event) {
+      this.events.delete(event);
+      if (this.debugMode) {
+        console.log(`[EventBus] Cleared event: ${event}`);
+      }
+    } else {
+      this.events.clear();
+      if (this.debugMode) {
+        console.log('[EventBus] Cleared all events');
+      }
+    }
+  }
+
+  /**
+   * Get list of all registered events
+   */
+  getEventList(): string[] {
+    return Array.from(this.events.keys());
+  }
+
+  /**
+   * Get number of subscribers for a specific event
+   */
+  getSubscriberCount(event: string): number {
+    return this.events.get(event)?.size || 0;
+  }
+
+  /**
+   * Check if an event has any subscribers
+   */
+  hasSubscribers(event: string): boolean {
+    return this.getSubscriberCount(event) > 0;
+  }
+}
+
+// Export singleton instance
+export const eventBusService = new EventBusService();

package/src/modules-repository/event-bus/module.ts

@@ -0,0 +1,30 @@
+/**
+ * Event Bus Module for KIMU-Core
+ * 
+ * Provides global event bus for component communication.
+ * 
+ * @module EventBusModule
+ */
+
+import { KimuModule } from '../../core/kimu-module';
+import { eventBusService } from './event-bus-service';
+
+/**
+ * EventBusModule - Module class for event bus integration
+ */
+export default class EventBusModule extends KimuModule {
+  constructor(name = 'event-bus', version = '1.0.0', options?: any) {
+    super(name, version, options);
+  }
+
+  /**
+   * Get the event bus service instance
+   */
+  getService() {
+    return eventBusService;
+  }
+}
+
+// Re-export for convenience
+export { eventBusService } from './event-bus-service';
+export { EventBusService } from './event-bus-service';

package/src/modules-repository/i18n/README.it.md

@@ -0,0 +1,63 @@
+# Kimu I18n Module
+
+Il modulo `i18n` di kimu-core fornisce un sistema di internazionalizzazione (internationalization) per applicazioni ed estensioni basate su kimu-core. Permette di gestire facilmente interfacce multilingua, traduzioni di stringhe e cambio dinamico della lingua.
+
+## Scopo
+- Abilitare la localizzazione di tutte le stringhe visibili all’utente.
+- Gestire più lingue in modo centralizzato e modulare.
+- Fornire API semplici per accedere alle traduzioni e cambiare lingua a runtime.
+
+## Struttura del modulo
+```
+src/modules/i18n/
+  ├── kimu-i18n-service.ts   # Servizio principale per traduzioni e gestione lingua
+  ├── kimu-global-lang.ts    # Definizione delle lingue globali e risorse
+  ├── module.ts              # Esportazione del modulo come KimuModule
+  └── README.md              # Questa documentazione
+```
+
+## Come funziona
+- Il servizio `KimuI18nService` gestisce la lingua corrente e fornisce il metodo `translate(key)` per ottenere la stringa tradotta.
+- Le risorse delle lingue sono definite in oggetti o file separati (es. `en`, `it`, ecc.).
+- È possibile cambiare lingua a runtime e aggiornare dinamicamente l’interfaccia.
+
+## Utilizzo base
+```typescript
+import I18nModule from 'src/modules/i18n/module';
+
+// Istanzia il modulo e imposta la lingua di default
+const i18nModule = new I18nModule('i18n', '1.0.0', { lang: 'it' });
+const i18n = i18nModule.getService();
+
+// Traduci una chiave
+console.log(i18n.translate('hello'));
+
+// Cambia lingua
+i18n.setLang('en');
+```
+
+## Integrazione in un’estensione
+```typescript
+// Nel componente
+getData() {
+  return {
+    translate: this.i18n.translate,
+    // ...altri dati
+  };
+}
+// Nel template HTML: <span>${translate('welcome')}</span>
+```
+
+## Best practice
+- Definisci tutte le stringhe utente tramite chiavi, mai testo hardcoded.
+- Mantieni le risorse delle lingue aggiornate e documentate.
+- Fornisci sempre l’inglese come fallback.
+- Documenta come aggiungere nuove lingue.
+
+## Vantaggi
+- UI multilingua pronta all’uso.
+- Cambi di lingua reattivi e centralizzati.
+- Facilmente estendibile per nuove lingue o domini.
+
+---
+Autore: UnicoVerso

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

@@ -0,0 +1,63 @@
+# Kimu I18n Module
+
+The `i18n` module in kimu-core provides an internationalization system for kimu-core-based applications and extensions. It allows you to easily manage multilingual interfaces, string translations, and dynamic language switching.
+
+## Purpose
+- Enable localization of all user-visible strings.
+- Manage multiple languages in a centralized and modular way.
+- Provide simple APIs to access translations and change language at runtime.
+
+## Module Structure
+```
+src/modules/i18n/
+  ├── kimu-i18n-service.ts   # Main service for translations and language management
+  ├── kimu-global-lang.ts    # Definition of global languages and resources
+  ├── module.ts              # Module export as KimuModule
+  └── README.md              # This documentation
+```
+
+## How it works
+- The `KimuI18nService` manages the current language and provides the `translate(key)` method to get the translated string.
+- Language resources are defined in separate objects or files (e.g., `en`, `it`, etc.).
+- You can change language at runtime and dynamically update the interface.
+
+## Basic usage
+```typescript
+import I18nModule from 'src/modules/i18n/module';
+
+// Instantiate the module and set the default language
+const i18nModule = new I18nModule('i18n', '1.0.0', { lang: 'it' });
+const i18n = i18nModule.getService();
+
+// Translate a key
+console.log(i18n.translate('hello'));
+
+// Change language
+i18n.setLang('en');
+```
+
+## Integration in an extension
+```typescript
+// In the component
+getData() {
+  return {
+    translate: this.i18n.translate,
+    // ...other data
+  };
+}
+// In the HTML template: <span>${translate('welcome')}</span>
+```
+
+## Best practices
+- Define all user strings using keys, never hardcoded text.
+- Keep language resources updated and documented.
+- Always provide English as a fallback.
+- Document how to add new languages.
+
+## Advantages
+- Ready-to-use multilingual UI.
+- Reactive and centralized language changes.
+- Easily extendable for new languages or domains.
+
+---
+Author: UnicoVerso

package/src/modules-repository/i18n/kimu-global-lang.ts

@@ -0,0 +1,26 @@
+export type LangChangeCallback = (lang: string) => void;
+
+export class KimuGlobalLang {
+  private static currentLang: string = 'it';
+  private static listeners: LangChangeCallback[] = [];
+
+  static set(lang: string) {
+    //console.log(`[KimuGlobalLang] set language: ${lang}`);
+    if (lang !== this.currentLang) {
+      this.currentLang = lang;
+      this.listeners.forEach(fn => fn(lang));
+    }
+  }
+
+  static get(): string {
+    return this.currentLang;
+  }
+
+  static onChange(cb: LangChangeCallback) {
+    this.listeners.push(cb);
+  }
+
+  static off(cb: LangChangeCallback) {
+    this.listeners = this.listeners.filter(fn => fn !== cb);
+  }
+}