kimu-core 0.4.1

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

@@ -0,0 +1,436 @@
+/**
+ * Notification Service for KIMU-Core
+ * 
+ * Provides toast notifications, alerts, and user feedback system.
+ * Supports different notification types, durations, and positions.
+ * 
+ * @module NotificationService
+ * @version 1.0.0
+ */
+
+export type NotificationType = 'success' | 'error' | 'warning' | 'info';
+export type NotificationPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center';
+
+export interface NotificationOptions {
+  type?: NotificationType;
+  duration?: number; // in milliseconds, 0 = no auto-dismiss
+  position?: NotificationPosition;
+  dismissible?: boolean;
+  icon?: string;
+  onClick?: () => void;
+  onClose?: () => void;
+}
+
+export interface Notification {
+  id: string;
+  message: string;
+  type: NotificationType;
+  duration: number;
+  position: NotificationPosition;
+  dismissible: boolean;
+  icon?: string;
+  timestamp: number;
+  element?: HTMLElement;
+  timeoutId?: number;
+  onClick?: () => void;
+  onClose?: () => void;
+}
+
+/**
+ * NotificationService - Toast notifications and alerts
+ * 
+ * @example
+ * ```typescript
+ * import { notificationService } from './modules/notification/notification-service';
+ * 
+ * // Show success notification
+ * notificationService.success('Operation completed!');
+ * 
+ * // Show error with custom duration
+ * notificationService.error('Something went wrong!', { duration: 5000 });
+ * 
+ * // Show info with custom position
+ * notificationService.info('New message received', { position: 'bottom-right' });
+ * ```
+ */
+export class NotificationService {
+  private notifications: Map<string, Notification> = new Map();
+  private container?: HTMLElement;
+  private defaultDuration: number = 3000;
+  private defaultPosition: NotificationPosition = 'top-right';
+  private maxNotifications: number = 5;
+  private debugMode: boolean = false;
+
+  constructor() {
+    this.initContainer();
+  }
+
+  /**
+   * Enable or disable debug mode
+   */
+  setDebugMode(enabled: boolean): void {
+    this.debugMode = enabled;
+  }
+
+  /**
+   * Set default notification duration
+   */
+  setDefaultDuration(duration: number): void {
+    this.defaultDuration = duration;
+  }
+
+  /**
+   * Set default notification position
+   */
+  setDefaultPosition(position: NotificationPosition): void {
+    this.defaultPosition = position;
+  }
+
+  /**
+   * Set maximum number of visible notifications
+   */
+  setMaxNotifications(max: number): void {
+    this.maxNotifications = max;
+  }
+
+  /**
+   * Show a success notification
+   */
+  success(message: string, options?: NotificationOptions): string {
+    return this.show(message, { ...options, type: 'success' });
+  }
+
+  /**
+   * Show an error notification
+   */
+  error(message: string, options?: NotificationOptions): string {
+    return this.show(message, { ...options, type: 'error' });
+  }
+
+  /**
+   * Show a warning notification
+   */
+  warning(message: string, options?: NotificationOptions): string {
+    return this.show(message, { ...options, type: 'warning' });
+  }
+
+  /**
+   * Show an info notification
+   */
+  info(message: string, options?: NotificationOptions): string {
+    return this.show(message, { ...options, type: 'info' });
+  }
+
+  /**
+   * Show a notification with custom options
+   */
+  show(message: string, options: NotificationOptions = {}): string {
+    const id = this.generateId();
+    
+    const notification: Notification = {
+      id,
+      message,
+      type: options.type || 'info',
+      duration: options.duration !== undefined ? options.duration : this.defaultDuration,
+      position: options.position || this.defaultPosition,
+      dismissible: options.dismissible !== undefined ? options.dismissible : true,
+      icon: options.icon || this.getDefaultIcon(options.type || 'info'),
+      timestamp: Date.now(),
+      onClick: options.onClick,
+      onClose: options.onClose
+    };
+
+    if (this.debugMode) {
+      console.log('[Notification] Show:', notification);
+    }
+
+    // Remove oldest notification if max limit reached
+    if (this.notifications.size >= this.maxNotifications) {
+      const oldestId = Array.from(this.notifications.keys())[0];
+      this.dismiss(oldestId);
+    }
+
+    this.notifications.set(id, notification);
+    this.renderNotification(notification);
+
+    // Auto-dismiss if duration > 0
+    if (notification.duration > 0) {
+      notification.timeoutId = window.setTimeout(() => {
+        this.dismiss(id);
+      }, notification.duration);
+    }
+
+    return id;
+  }
+
+  /**
+   * Dismiss a specific notification
+   */
+  dismiss(id: string): void {
+    const notification = this.notifications.get(id);
+    if (!notification) return;
+
+    if (this.debugMode) {
+      console.log('[Notification] Dismiss:', id);
+    }
+
+    // Clear timeout
+    if (notification.timeoutId) {
+      clearTimeout(notification.timeoutId);
+    }
+
+    // Remove element with animation
+    if (notification.element) {
+      notification.element.classList.add('kimu-notification-exit');
+      setTimeout(() => {
+        notification.element?.remove();
+      }, 300);
+    }
+
+    // Call onClose callback
+    if (notification.onClose) {
+      notification.onClose();
+    }
+
+    this.notifications.delete(id);
+  }
+
+  /**
+   * Dismiss all notifications
+   */
+  dismissAll(): void {
+    const ids = Array.from(this.notifications.keys());
+    ids.forEach(id => this.dismiss(id));
+  }
+
+  /**
+   * Get all active notifications
+   */
+  getAll(): Notification[] {
+    return Array.from(this.notifications.values());
+  }
+
+  /**
+   * Get notification count
+   */
+  getCount(): number {
+    return this.notifications.size;
+  }
+
+  // Private methods
+
+  private initContainer(): void {
+    if (typeof document === 'undefined') return;
+
+    this.container = document.createElement('div');
+    this.container.id = 'kimu-notification-container';
+    this.injectStyles();
+    document.body.appendChild(this.container);
+  }
+
+  private renderNotification(notification: Notification): void {
+    if (!this.container) return;
+
+    const element = document.createElement('div');
+    element.className = `kimu-notification kimu-notification-${notification.type} kimu-notification-${notification.position}`;
+    element.setAttribute('data-id', notification.id);
+
+    const content = `
+      <div class="kimu-notification-content">
+        ${notification.icon ? `<span class="kimu-notification-icon">${notification.icon}</span>` : ''}
+        <span class="kimu-notification-message">${this.escapeHtml(notification.message)}</span>
+      </div>
+      ${notification.dismissible ? '<button class="kimu-notification-close" aria-label="Close">×</button>' : ''}
+    `;
+
+    element.innerHTML = content;
+
+    // Add click handlers
+    if (notification.onClick) {
+      element.addEventListener('click', (e) => {
+        if (!(e.target as HTMLElement).classList.contains('kimu-notification-close')) {
+          notification.onClick!();
+        }
+      });
+    }
+
+    if (notification.dismissible) {
+      const closeBtn = element.querySelector('.kimu-notification-close');
+      closeBtn?.addEventListener('click', (e) => {
+        e.stopPropagation();
+        this.dismiss(notification.id);
+      });
+    }
+
+    notification.element = element;
+    this.container.appendChild(element);
+
+    // Trigger animation
+    setTimeout(() => element.classList.add('kimu-notification-enter'), 10);
+  }
+
+  private generateId(): string {
+    return `notification-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  private getDefaultIcon(type: NotificationType): string {
+    const icons = {
+      success: '✅',
+      error: '❌',
+      warning: '⚠️',
+      info: 'ℹ️'
+    };
+    return icons[type];
+  }
+
+  private escapeHtml(text: string): string {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  }
+
+  private injectStyles(): void {
+    if (typeof document === 'undefined') return;
+    if (document.getElementById('kimu-notification-styles')) return;
+
+    const style = document.createElement('style');
+    style.id = 'kimu-notification-styles';
+    style.textContent = `
+      #kimu-notification-container {
+        position: fixed;
+        z-index: 9999;
+        pointer-events: none;
+      }
+
+      .kimu-notification {
+        position: fixed;
+        min-width: 280px;
+        max-width: 400px;
+        padding: 16px 20px;
+        margin: 12px;
+        background: white;
+        border-radius: 8px;
+        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        opacity: 0;
+        transform: translateY(-20px);
+        transition: all 0.3s ease;
+        pointer-events: auto;
+        cursor: default;
+      }
+
+      .kimu-notification-enter {
+        opacity: 1;
+        transform: translateY(0);
+      }
+
+      .kimu-notification-exit {
+        opacity: 0;
+        transform: translateY(-20px);
+      }
+
+      .kimu-notification-content {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        flex: 1;
+      }
+
+      .kimu-notification-icon {
+        font-size: 20px;
+        line-height: 1;
+      }
+
+      .kimu-notification-message {
+        color: #333;
+        font-size: 14px;
+        line-height: 1.5;
+      }
+
+      .kimu-notification-close {
+        background: none;
+        border: none;
+        font-size: 24px;
+        line-height: 1;
+        color: #999;
+        cursor: pointer;
+        padding: 0;
+        margin-left: 12px;
+        transition: color 0.2s;
+      }
+
+      .kimu-notification-close:hover {
+        color: #333;
+      }
+
+      /* Types */
+      .kimu-notification-success {
+        background: #f0fdf4;
+        border-left: 4px solid #22c55e;
+      }
+
+      .kimu-notification-error {
+        background: #fef2f2;
+        border-left: 4px solid #ef4444;
+      }
+
+      .kimu-notification-warning {
+        background: #fffbeb;
+        border-left: 4px solid #f59e0b;
+      }
+
+      .kimu-notification-info {
+        background: #eff6ff;
+        border-left: 4px solid #3b82f6;
+      }
+
+      /* Positions */
+      .kimu-notification-top-right {
+        top: 0;
+        right: 0;
+      }
+
+      .kimu-notification-top-left {
+        top: 0;
+        left: 0;
+      }
+
+      .kimu-notification-bottom-right {
+        bottom: 0;
+        right: 0;
+      }
+
+      .kimu-notification-bottom-left {
+        bottom: 0;
+        left: 0;
+      }
+
+      .kimu-notification-top-center {
+        top: 0;
+        left: 50%;
+        transform: translateX(-50%) translateY(-20px);
+      }
+
+      .kimu-notification-top-center.kimu-notification-enter {
+        transform: translateX(-50%) translateY(0);
+      }
+
+      .kimu-notification-bottom-center {
+        bottom: 0;
+        left: 50%;
+        transform: translateX(-50%) translateY(20px);
+      }
+
+      .kimu-notification-bottom-center.kimu-notification-enter {
+        transform: translateX(-50%) translateY(0);
+      }
+    `;
+
+    document.head.appendChild(style);
+  }
+}
+
+// Export singleton instance
+export const notificationService = new NotificationService();

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

@@ -0,0 +1,39 @@
+# Kimu Router Module
+
+Questo modulo fornisce un servizio di routing per kimu-core, permettendo la gestione delle rotte e la navigazione tra componenti/estensioni in base all'URL.
+
+## Funzionalità
+- Configurazione centralizzata delle rotte
+- Navigazione tramite history API
+- Callback sugli eventi di cambio rotta
+- API per registrare nuove rotte dinamicamente
+
+## Utilizzo
+
+```typescript
+import { KimuRouterService } from './src/modules/router/router';
+
+const router = KimuRouterService.getInstance();
+router.configure([
+  { path: '/', component: HomeComponent },
+  { path: '/about', component: AboutComponent },
+]);
+
+router.onRouteChange((route) => {
+  // Logica per gestire il cambio rotta
+});
+
+// Per navigare
+router.navigate('/about');
+```
+
+## Estensione
+- Puoi estendere il sistema per supportare parametri dinamici, fallback, rotte nidificate, ecc.
+- Le estensioni possono registrare le proprie rotte tramite `registerRoute`.
+
+## Best practice
+- Mantieni la configurazione delle rotte separata dalla logica di rendering.
+- Documenta sempre le rotte principali e i parametri accettati.
+
+---
+Autore: UnicoVerso

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

@@ -0,0 +1,39 @@
+# Kimu Router Module
+
+This module provides a routing service for kimu-core, allowing you to manage routes and navigation between components/extensions based on the URL.
+
+## Features
+- Centralized route configuration
+- Navigation via the History API
+- Callback on route change events
+- API to register new routes dynamically
+
+## Usage
+
+```typescript
+import { KimuRouterService } from './src/modules/router/router';
+
+const router = KimuRouterService.getInstance();
+router.configure([
+  { path: '/', component: HomeComponent },
+  { path: '/about', component: AboutComponent },
+]);
+
+router.onRouteChange((route) => {
+  // Logic to handle route change
+});
+
+// To navigate
+router.navigate('/about');
+```
+
+## Extension
+- You can extend the system to support dynamic parameters, fallback, nested routes, etc.
+- Extensions can register their own routes via `registerRoute`.
+
+## Best practices
+- Keep route configuration separated from rendering logic.
+- Always document main routes and accepted parameters.
+
+---
+Author: UnicoVerso

package/src/modules-repository/router/manifest.json

@@ -0,0 +1,21 @@
+{
+  "name": "router",
+  "version": "1.0.0",
+  "description": "Client-side routing module for KIMU applications with History API support",
+  "author": "KIMU Team",
+  "license": "MPL-2.0",
+  "dependencies": [],
+  "kimuCoreVersion": "^0.3.0",
+  "keywords": [
+    "router",
+    "routing",
+    "navigation",
+    "history-api",
+    "spa"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/UnicoVerso/kimu-core",
+    "directory": "src/modules/router"
+  }
+}

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

@@ -0,0 +1,23 @@
+// KimuRouterModule
+// Provides the routing service as a KimuModule
+// Inspired by the structure of the i18n module
+
+import { KimuModule } from '../../core/kimu-module';
+import { KimuRouterService } from './router';
+import { KimuRouterModuleOptions } from './router';
+
+export default class KimuRouterModule extends KimuModule {
+  private service: KimuRouterService;
+
+  constructor(name: string = 'router', version: string = '1.0.0', options?: KimuRouterModuleOptions) {
+    super(name, version, options);
+    this.service = KimuRouterService.getInstance();
+    if (options?.routes) {
+      this.service.configure(options.routes);
+    }
+  }
+
+  getService(): KimuRouterService {
+    return this.service;
+  }
+}

package/src/modules-repository/router/router.ts

@@ -0,0 +1,144 @@
+// Kimu Router Module
+// Provides routing service and configuration for kimu-core extensions and core
+// Author: UnicoVerso
+//
+// Usage: Import KimuRouterService and configure routes in your app or extension.
+
+// Router module options (extensible for future features)
+import { KimuModuleOptions } from '../../core/kimu-types';
+
+/**
+ * RouteConfig defines a single route mapping for the router.
+ * - path: URL path to match
+ * - component: KimuComponentElement to render
+ * - name: Optional route name
+ * - meta: Optional metadata for custom usage
+ */
+export interface RouteConfig {
+  path: string;
+  component: any; // Should extend KimuComponentElement
+  name?: string;
+  meta?: Record<string, any>;
+}
+
+/**
+ * Options for initializing the router module.
+ * - routes: Array of RouteConfig for initial setup
+ */
+export interface KimuRouterModuleOptions extends KimuModuleOptions {
+  routes?: RouteConfig[];
+}
+
+/**
+ * Callback type for route change events.
+ * - route: The matched RouteConfig
+ * - params: Optional route parameters (future extension)
+ */
+export type RouteChangeCallback = (route: RouteConfig, params?: Record<string, string>) => void;
+
+/**
+ * KimuRouterService provides SPA-like routing for KIMU extensions/components.
+ * Use getInstance() for singleton access.
+ */
+export class KimuRouterService {
+  /** Singleton instance */
+  private static instance: KimuRouterService;
+  /** Registered routes */
+  private routes: RouteConfig[] = [];
+  /** Currently active route */
+  private currentRoute: RouteConfig | null = null;
+  /** Listeners for route change events */
+  private listeners: RouteChangeCallback[] = [];
+
+  /**
+   * Private constructor. Sets up popstate listener for browser navigation.
+   */
+  private constructor() {
+    window.addEventListener('popstate', this.handlePopState.bind(this));
+  }
+
+  /**
+   * Returns the singleton instance of the router service.
+   */
+  public static getInstance(): KimuRouterService {
+    if (!KimuRouterService.instance) {
+      KimuRouterService.instance = new KimuRouterService();
+    }
+    return KimuRouterService.instance;
+  }
+
+  /**
+   * Configure the router with a set of routes.
+   * @param routes Array of RouteConfig
+   */
+  public configure(routes: RouteConfig[]): void {
+    this.routes = routes;
+  }
+
+  /**
+   * Register a new route at runtime.
+   * @param route RouteConfig to add
+   */
+  public registerRoute(route: RouteConfig): void {
+    this.routes.push(route);
+  }
+
+  /**
+   * Navigate to a given path, updating browser history and resolving route.
+   * @param path URL path to navigate to
+   */
+  public navigate(path: string): void {
+    history.pushState({}, '', path);
+    this.resolveRoute(path);
+  }
+
+  /**
+   * Get the currently active route.
+   */
+  public getCurrentRoute(): RouteConfig | null {
+    return this.currentRoute;
+  }
+
+  /**
+   * Register a callback for route change events.
+   * @param callback Function to call on route change
+   */
+  public onRouteChange(callback: RouteChangeCallback): void {
+    this.listeners.push(callback);
+  }
+
+  /**
+   * Handles browser back/forward navigation.
+   */
+  private handlePopState(): void {
+    this.resolveRoute(window.location.pathname);
+  }
+
+  /**
+   * Resolves the route for a given path and notifies listeners.
+   * @param path URL path to resolve
+   */
+  private resolveRoute(path: string): void {
+    const match = this.routes.find(r => r.path === path);
+    this.currentRoute = match || null;
+    this.listeners.forEach(cb => cb(this.currentRoute!, this.extractParams(path)));
+  }
+
+  /**
+   * Extracts route parameters from the path (future extension).
+   * @param _path URL path
+   * @returns Object with route params (currently empty)
+   */
+  private extractParams(_path: string): Record<string, string> {
+    // Basic implementation, extend for dynamic params
+    return {};
+  }
+}
+
+// Example usage (in app or extension):
+// const router = KimuRouterService.getInstance();
+// router.configure([
+//   { path: '/', component: HomeComponent },
+//   { path: '/about', component: AboutComponent },
+// ]);
+// router.onRouteChange((route) => { ... });