kimu-core 0.4.1

package/src/core/kimu-reactive.ts

@@ -0,0 +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;
+  }
+}
+

package/src/core/kimu-render.ts

@@ -0,0 +1,91 @@
+import { html, render as litRender, TemplateResult } from 'lit';
+
+/**
+ * The `KimuRender` class provides utility methods for reactive rendering and template compilation
+ * in the Kimu framework. It leverages the Lit library to enable dynamic and efficient UI updates.
+ * 
+ * Key functionalities:
+ * - Performs reactive rendering using Lit.
+ * - Loads HTML templates from files and compiles them into Lit rendering functions.
+ * - Compiles HTML strings into dynamic Lit rendering functions.
+ */
+export class KimuRender {
+
+    /**
+     * Performs reactive rendering using Lit.
+     * 
+     * @param component - The target component where the template will be rendered.
+     * @param data - The data to be passed to the rendering function.
+     * @param renderFn - The Lit rendering function that generates the template.
+     */
+    static render(component: HTMLElement, data: Record<string, any>, renderFn: (html: any, data: Record<string, any>) => TemplateResult): void {
+        if (!component.shadowRoot) {
+            console.warn('[KimuRender] Shadow DOM not found for component:', component.tagName);
+            return;
+        }
+        
+        try {
+            const template = renderFn(html, data);
+            
+            // Ensure we're working with a valid Lit TemplateResult
+            if (!template || !template.strings) {
+                console.warn('[KimuRender] Invalid template result from renderFn');
+                return;
+            }
+            
+            // Use Lit's native render function which handles efficient updates
+            litRender(template, component.shadowRoot);
+        } catch (error) {
+            console.error('[KimuRender] Error during Lit rendering:', error);
+            console.error('Component:', component.tagName);
+            console.error('Data:', data);
+        }
+    }
+
+    /**
+     * Loads an HTML template from a file and compiles it into a Lit rendering function.
+     * 
+     * @param template - The HTML template string to be compiled.
+     * @returns A compiled Lit rendering function.
+     */
+    static async loadTemplate(template: string) {
+        return this.compileTemplate(template);
+    }
+
+    /**
+     * Compiles an HTML string into a dynamic Lit rendering function.
+     * 
+     * @param template - The HTML string to be compiled.
+     * @returns A Lit rendering function that can be used for reactive rendering.
+     */
+    static compileTemplate(template: string): (html: typeof import('lit').html, data: Record<string, any>) => TemplateResult {
+        // Simple and safe template compilation without 'with' statement
+        return (html: typeof import('lit').html, data: Record<string, any>) => {
+            try {
+                // Create a function that has access to data properties as parameters
+                const keys = Object.keys(data || {});
+                const values = Object.values(data || {});
+                
+                // Create template function with destructured parameters
+                const templateFunction = new Function(
+                    ...keys, 
+                    'html', 
+                    `return html\`${template}\`;`
+                );
+                
+                // Execute with data values
+                return templateFunction(...values, html);
+            } catch (error) {
+                console.error('[KimuRender] Template compilation error:', error);
+                console.error('Template:', template.slice(0, 200));
+                console.error('Data:', data);
+                
+                // Return safe fallback template
+                return html`<div class="kimu-template-error">
+                    <strong>Template Error:</strong> ${error instanceof Error ? error.message : 'Unknown error'}
+                </div>`;
+            }
+        };
+    }
+
+}

package/src/core/kimu-store.ts

@@ -0,0 +1,147 @@
+import { KimuExtensionMeta } from './kimu-types';
+
+const DB_NAME = 'kimu-db'; // Name of the IndexedDB database
+const STORE_NAME = 'extensions'; // Name of the store (table) in the database
+
+/**
+ * The `KimuStore` class provides utility methods for managing extensions in IndexedDB.
+ * It acts as a persistent storage layer for saving, retrieving, and managing extension metadata.
+ * 
+ * Key functionalities:
+ * - Initializes IndexedDB and creates the store if it does not exist.
+ * - Provides methods to check if the database is empty.
+ * - Saves, retrieves, and removes extensions from the database.
+ * - Clears all extensions from the database.
+ */
+export class KimuStore {
+  private static _db: IDBDatabase;
+
+  /**
+   * Initializes IndexedDB and creates the store if it does not exist.
+   * 
+   * @returns A promise that resolves when the database is initialized.
+   */
+  static async init(): Promise<void> {
+    // console.log('[KimuStore] IndexedDB initialize...');
+    // Check if IndexedDB is already initialized
+    if (this._db) {
+      // console.log('[KimuStore] ✅ IndexedDB is already initialized');
+      return;
+    }
+    // Initialize IndexedDB
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(DB_NAME, 1);
+      request.onerror = () => reject('❌ IndexedDB is not available');
+      request.onsuccess = () => {
+        this._db = request.result;
+        resolve();
+      };
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(STORE_NAME)) {
+          db.createObjectStore(STORE_NAME, { keyPath: 'tag' });
+        }
+      };
+    });
+  }
+
+  /**
+   * Checks if the database is empty.
+   * 
+   * @returns A promise that resolves to `true` if the database is empty, otherwise `false`.
+   */
+  static async isEmpty(): Promise<boolean> {
+    await this.init();
+    return new Promise((resolve, reject) => {
+      const tx = this._db.transaction(STORE_NAME, 'readonly');
+      const store = tx.objectStore(STORE_NAME);
+      const countRequest = store.count();
+      countRequest.onsuccess = () => resolve(countRequest.result === 0);
+      countRequest.onerror = () => reject(countRequest.error);
+    });
+  }
+
+  /**
+   * Retrieves all extensions saved in the database.
+   * 
+   * @returns A promise that resolves to an array of extension metadata.
+   */
+  static async list(): Promise<KimuExtensionMeta[]> {
+    await this.init();
+    return new Promise((resolve, reject) => {
+      const tx = this._db.transaction(STORE_NAME, 'readonly');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.getAll();
+      request.onsuccess = () => resolve(request.result as KimuExtensionMeta[]);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  /**
+   * Retrieves a specific extension by its tag.
+   * 
+   * @param tag - The tag of the extension to retrieve.
+   * @returns A promise that resolves to the extension metadata or `undefined` if not found.
+   */
+  static async get(tag: string): Promise<KimuExtensionMeta | undefined> {
+    await this.init();
+    return new Promise((resolve, reject) => {
+      const tx = this._db.transaction(STORE_NAME, 'readonly');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.get(tag);
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  /**
+   * Saves an extension to the database.
+   * 
+   * @param entry - The extension metadata to save.
+   * @returns A promise that resolves when the extension is saved.
+   */
+  static async save(entry: KimuExtensionMeta): Promise<void> {
+    await this.init();
+    return new Promise((resolve, reject) => {
+      const tx = this._db.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.put(entry);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  /**
+   * Removes an extension from the database by its tag.
+   * 
+   * @param tag - The tag of the extension to remove.
+   * @returns A promise that resolves when the extension is removed.
+   */
+  static async remove(tag: string): Promise<void> {
+    await this.init();
+    return new Promise((resolve, reject) => {
+      const tx = this._db.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.delete(tag);
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  /**
+   * Clears all extensions from the database.
+   * 
+   * @returns A promise that resolves when the database is cleared.
+   */
+  static async clear(): Promise<void> {
+    await this.init();
+    return new Promise((resolve, reject) => {
+      const tx = this._db.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.clear();
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+}

package/src/core/kimu-types.ts

@@ -0,0 +1,65 @@
+/**
+ * This code defines the types and interfaces used in the Kimu framework.
+ * It provides structured definitions for assets, languages, and extension metadata,
+ * enabling consistent and type-safe management of resources and extensions.
+ * 
+ * Key functionalities:
+ * - Defines types for assets (CSS, JS) and their metadata.
+ * - Provides interfaces for supported languages and their configurations.
+ * - Defines metadata for Kimu extensions, including version, author, dependencies, and more.
+ */
+
+// Type to define a single resource to load
+export type KimuAsset = {
+  path: string;       // Path to the resource (e.g., "style.css")
+  id?: string;        // Optional ID for the resource (e.g., "kimu-style")
+};
+
+// Type to define external resources to load
+export type KimuGroupAsset = {
+  css?: KimuAsset[]; // Array of CSS assets
+  js?: KimuAsset[];  // Array of JS assets
+}
+
+// Type to define a supported language
+export interface KimuLang {
+  code: string;           // language code e.g., 'it', 'en'
+  name?: string;          // e.g., 'Italian' (language name)
+  file?: string;          // e.g., 'custom-name.json' (language file)
+}
+
+// Type to define the languages supported by an extension
+export interface KimuExtensionLanguages {
+  default: string; // Default language code (e.g., 'en')
+  supported: Record<string, KimuLang>; // Map of supported languages
+}
+
+// Interface to define metadata associated with Kimu extensions
+export interface KimuExtensionMeta {
+  tag: string;              // e.g., "ext-hello" (component tag name)
+  name: string;             // e.g., "Hello World" (extension name)
+  version?: string;         // e.g., "1.0.0" (extension version)
+  description?: string;     // e.g., "Hello World component" (extension description)
+  author?: string;          // e.g., "UnicoVerso" (extension author)
+  icon?: string;            // e.g., "icon.png" (extension icon)
+  source?: string;          // 'local' | 'git' | 'marketplace' (source type)
+  link?: string;            // Reference to documentation or website
+  path?: string;            // e.g., "hello" (base path for the extension)
+  basePath?: string;        // e.g., "extensions/hello" (internal base path for the extension)
+  kimuVersion?: string;     // e.g., "1.0.0" (minimum required Kimu version)
+  enabled?: boolean;        // If true, the extension is enabled (default: true)
+  installed?: boolean;      // If true, the extension is installed (default: false)
+  internal?: boolean;       // If true, the extension is internal and not visible to the user (default: false)
+  template?: string;        // e.g., "hello.html" (HTML template for the extension)
+  style?: string;           // e.g., "hello.css" (CSS file for the extension)
+  external?: KimuGroupAsset; // Object defining external resources to load
+  dependencies?: string[];  // List of dependent extensions
+  languages?: KimuExtensionLanguages; // Object defining supported languages for the extension
+}
+
+// Interface to define options for Kimu modules
+export interface KimuModuleOptions {
+  [key: string]: any;
+  // Proprietà opzionali per configurare i moduli
+  // Esempio: lang?: string; debug?: boolean; resources?: string[];
+}

package/src/extensions/extensions-manifest.json

@@ -0,0 +1,13 @@
+[
+  {
+    "tag": "kimu-home",
+    "path": "kimu-home",
+    "internal": true,
+    "name": "KIMU Home",
+    "description": "Main interface container",
+    "version": "1.0.0",
+    "author": "UnicòVerso",
+    "icon": "🏠",
+    "kimuVersion": "1.0.0"
+  }
+]

package/src/extensions/kimu-home/component.ts

@@ -0,0 +1,80 @@
+//
+// This file can be freely modified by developers.
+// Changes made to this page are not subject to the publication requirement of the MPL framework license.
+//
+
+import { KimuComponent } from '../../core/kimu-component';
+import { KimuComponentElement } from '../../core/kimu-component-element';
+import { KimuGlobalLang, KimuI18nService } from '../../modules/i18n/module';
+
+@KimuComponent({
+    tag: 'kimu-home',
+    path: 'kimu-home',
+    name: 'KIMU Home',
+    version: '1.0.0',
+    description: 'Main interface container',
+    icon: '🏠',
+    author: 'UnicòVerso',
+    kimuVersion: '1.0.0',
+    languages: {
+        default: 'it',
+        supported: {
+            it: { code: 'it', name: 'Italian' },
+            en: { code: 'en', name: 'English' }
+        }
+    }
+})
+export class KimuHomeComponent extends KimuComponentElement {
+
+    /** I18n service instance for translations */
+    private i18n = new KimuI18nService(
+        this.getMeta().languages?.default,
+        'extensions/' + this.getMeta().path + '/lang',
+        this.getMeta().languages
+    );
+    /** Currently selected language code */
+    private selectedLang = KimuGlobalLang.get();
+
+    /** Versione del framework KIMU */
+    private kimuVersion = '';
+
+    /**
+     * Initializes the component, loads the current language, and sets up reactivity.
+     */
+    async onInit() {
+        this.selectedLang = await KimuGlobalLang.get();
+        await this.i18n.setLang(this.selectedLang);
+        // Recupera la versione del framework
+        const app = await this.getApp();
+        this.kimuVersion = app.version;
+        this.refresh();
+        // React to global language changes
+        KimuGlobalLang.onChange(async (lang: string) => {
+            await this.i18n.setLang(lang);
+            this.selectedLang = KimuGlobalLang.get();
+            this.refresh();
+        });
+    }
+
+    /**
+     * Returns the data object for template rendering.
+     * All properties are precomputed for compatibility with the template engine.
+     */
+    getData() {
+        return {
+            slogan: 'Keep It Minimal UI',
+            translate: this.i18n.translate,
+            selectedLang: this.selectedLang,
+            languages: this.getMeta().languages?.supported,
+            version: this.kimuVersion,
+            onLangIt: async () => {
+                await KimuGlobalLang.set('it');
+                this.refresh();
+            },
+            onLangEn: async () => {
+                await KimuGlobalLang.set('en');
+                this.refresh();
+            }
+        };
+    }
+}

package/src/extensions/kimu-home/lang/en.json

@@ -0,0 +1,5 @@
+{
+  "language": "English",
+  "welcome": "Welcome to KIMU!",
+  "selectedLanguage": "Current language:"
+}

package/src/extensions/kimu-home/lang/it.json

@@ -0,0 +1,5 @@
+{
+  "language": "Italiano",
+  "welcome": "Benvenuto in KIMU!",
+  "selectedLanguage": "Lingua corrente:"
+}

package/src/extensions/kimu-home/style.css

@@ -0,0 +1,61 @@
+/*
+This file can be freely modified by developers.
+Changes made to this page are not subject to the publication requirement of the MPL framework license.
+*/
+
+:host {
+  display: flex;
+  width: 100%;
+  height: 100%;
+  background-color: var(--kimu-bg); 
+  font-family: var(--kimu-font, sans-serif);
+  color: var(--kimu-text);
+}
+
+.container {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  min-height: 100vh;
+}
+
+.btn-lang {
+  display: flex;
+  justify-content: center;
+  gap: 14px;
+  margin-top: 18px;
+  margin-bottom: 8px;
+}
+
+.logo {
+    margin-bottom: 5px;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+}
+
+.logo img {
+    width: 200px;
+    height: auto;
+    display: block;
+}
+
+.kimu-footer {
+    margin-top: 32px;
+    text-align: center;
+    color: #888;
+    font-size: 0.92em;
+    letter-spacing: 0.01em;
+}
+.kimu-footer a {
+    color: #3a7afe;
+    text-decoration: none;
+    transition: color 0.15s;
+}
+.kimu-footer a:hover {
+    color: #1746a0;
+    text-decoration: underline;
+}