@igojs/signal 6.0.0-beta.1

package/src/client/README.md

@@ -0,0 +1,273 @@
+# Igo2Component - Architecture technique
+
+Framework réactif minimaliste basé sur Igo-Dust, avec deep réactivité et auto-tracking des dépendances.
+
+## Vue d'ensemble
+
+```
+Props (immutable) → State (reactive) → Derived (computed) → Template → DOM
+                           ↓                                            ↓
+                      Proxy tracking                            DiffDOM reconciliation
+```
+
+## Fichiers
+
+| Fichier | LOC | Responsabilité |
+|---------|-----|----------------|
+| `Igo2Component.js` | ~320 | Classe de base, lifecycle, render |
+| `StateProxy.js` | ~80 | Deep reactivity via Proxy |
+| `EventBinder.js` | ~110 | Gestion optimisée des événements |
+| `DerivedCache.js` | ~65 | Memoization des getters |
+| `FormHandler.js` | ~125 | Two-way binding des formulaires |
+
+---
+
+## StateProxy.js
+
+Wraps le state dans un Proxy récursif pour détecter les mutations à n'importe quelle profondeur.
+
+### Fonctionnement
+
+1. Chaque objet/array est wrappé dans un Proxy
+2. Le trap `set` intercepte les mutations et appelle `_triggerRender()`
+3. Les méthodes d'array (push, pop, splice, etc.) sont wrappées
+4. Un WeakMap évite le double-wrapping
+
+### Code clé
+
+```javascript
+const handler = {
+  set(target, property, value) {
+    target[property] = wrap(value);  // Wrap récursif
+    component._triggerRender();       // Déclenche le render
+    return true;
+  }
+};
+```
+
+### Mutations supportées
+
+```javascript
+this.state.count = 5;                    // Niveau 1
+this.state.user.name = 'John';           // Niveau 2
+this.state.user.address.city = 'Paris';  // Niveau 3+
+this.state.items.push({ id: 1 });        // Array methods
+this.state.items[0].name = 'Updated';    // Array item mutation
+```
+
+---
+
+## DerivedCache.js
+
+Memoization des getters avec tracking automatique des dépendances.
+
+### Fonctionnement
+
+1. Au premier appel d'un getter, `_isTracking = true`
+2. Chaque accès à `this.props.x` ou `this.state.y` est enregistré
+3. Le résultat est mis en cache avec ses dépendances
+4. Aux renders suivants, recalcul uniquement si les dépendances ont changé
+
+### Code clé
+
+```javascript
+memoize(key, fn, deps, context, currentValue) {
+  const cached = this._cache.get(key);
+
+  if (cached && !this._depsChanged(cached.deps, deps, context)) {
+    return cached.value;  // Cache hit
+  }
+
+  this._cache.set(key, { value: currentValue, deps });
+  return currentValue;
+}
+```
+
+---
+
+## EventBinder.js
+
+Gestion optimisée des événements avec WeakMap.
+
+### Fonctionnement
+
+1. `WeakMap<Element, Map<eventType, handler>>` stocke les listeners
+2. Au render, vérifie si le listener existe déjà
+3. Si l'élément est préservé par DiffDOM, le listener est réutilisé
+4. Si l'élément est remplacé, nouveau listener créé
+5. Les éléments supprimés sont garbage collectés automatiquement
+
+### Performance
+
+- O(1) lookup pour vérifier si un listener existe
+- Pas de rebinding si l'élément n'a pas changé
+- Pas de memory leaks grâce à WeakMap
+
+---
+
+## FormHandler.js
+
+Synchronisation automatique des champs de formulaire avec `this.state.form`.
+
+### Activation
+
+Le FormHandler s'active si `this.props.form` existe dans le constructeur.
+
+### Fonctionnement
+
+1. `initForm()` : Copie les valeurs initiales dans un objet partagé (`window.__igo2_form`)
+2. `bind()` : Attache les listeners sur les inputs
+3. `handleInput()` : Met à jour `this.state.form` à chaque changement
+
+### Valeurs toujours stockées comme strings
+
+Les valeurs du formulaire sont **toujours stockées comme strings** (sauf checkboxes → boolean).
+Cela garantit la cohérence entre le SSR (où `req.query` retourne des strings) et le client.
+
+**Les getters doivent convertir explicitement les types quand nécessaire :**
+
+```javascript
+get selected_product() {
+  const productId = Number(this.state.form?.product_id);
+  return this.props.products?.find(p => p.id === productId);
+}
+```
+
+### Types supportés
+
+| Attribut | Valeur stockée |
+|----------|----------------|
+| `type="text"` | String |
+| `type="number"` | String (convertir avec `Number()` si besoin) |
+| `type="checkbox"` | Boolean ou Array de strings |
+| `name="x[]"` | Array de strings |
+| `name="x[0][]"` | Nested array de strings |
+
+---
+
+## Igo2Component.js
+
+Classe de base orchestrant tous les modules.
+
+### Lifecycle
+
+```
+constructor()
+    ↓
+init()
+    ↓
+loadTemplate()
+    ↓
+render() ←──────────────┐
+    ↓                   │
+beforeRender()          │
+    ↓                   │
+_computeGettersAsDerived()
+    ↓                   │
+dust.render()           │
+    ↓                   │
+DiffDOM.apply()         │
+    ↓                   │
+_syncChildProps()       │
+    ↓                   │
+_bindEvents()           │
+    ↓                   │
+_mountChildComponents() │
+    ↓                   │
+afterRender()           │
+    ↓                   │
+[state mutation] ───────┘
+```
+
+### Render optimization
+
+Les renders sont synchronisés avec le browser paint :
+
+```javascript
+_triggerRender() {
+  if (this._renderFrame) {
+    cancelAnimationFrame(this._renderFrame);
+  }
+  this._renderFrame = requestAnimationFrame(() => this.render());
+}
+```
+
+### Props hydration
+
+Les props locales sont désérialisées avec `devalue` :
+
+```javascript
+if (this.element.dataset.props) {
+  const hydrate = new Function('return ' + this.element.dataset.props);
+  localProps = hydrate();
+}
+this._props = { ...globalProps, ...localProps };
+```
+
+### Child components
+
+Les composants enfants sont :
+1. Préservés par DiffDOM (leurs attributes peuvent être mis à jour)
+2. Montés automatiquement après le render parent
+3. Synchronisés via `_syncChildProps()` quand leurs data-props changent
+
+### Cleanup
+
+```javascript
+async destroy() {
+  cancelAnimationFrame(this._renderFrame);
+  this._eventBinder.unbind();
+  this._formHandler?.unbind();
+  this._derivedCache.clear();
+  this.element.__igoInstance = null;
+  // ... null toutes les références
+}
+```
+
+---
+
+## DiffDOM
+
+Bibliothèque externe pour la réconciliation DOM.
+
+### Usage
+
+```javascript
+const diff = diffDom.diff(this.element, newElement);
+diffDom.apply(this.element, filteredDiff);
+```
+
+### Filtrage des child components
+
+Les diffs touchant des composants enfants sont filtrés pour préserver leur état :
+
+```javascript
+const filteredDiff = diff.filter(d => {
+  // Toujours autoriser les modifications d'attributs (data-props sync)
+  if (d.action === 'modifyAttribute') return true;
+
+  // Filtrer les diffs qui touchent des [data-component]
+  // ...
+});
+```
+
+---
+
+## Templates Dust
+
+Les templates reçoivent un contexte fusionné :
+
+```javascript
+const context = {
+  ...this._props,           // Props serveur
+  ...this._state,           // State réactif
+  ...this._derivedValues    // Getters calculés
+};
+```
+
+### Helpers disponibles
+
+- `{@json value=x /}` : Sérialise en JSON
+- `{@devalue value=x /}` : Sérialise avec devalue (préserve les types)
+- `{@selected key=a value=b /}` : Attribut selected conditionnel
+- `{@disabled key=a value=b /}` : Attribut disabled conditionnel

package/src/client/SignalComponent.js

@@ -0,0 +1,409 @@
+// Isomorphic imports (safe for Node.js)
+const DerivedCache  = require('./DerivedCache');
+const StateProxy    = require('./StateProxy');
+
+// Browser-only imports are loaded lazily in constructor
+
+// Detect server-side rendering
+const isServer = typeof window === 'undefined';
+
+// Browser-only dependencies (lazy loaded once)
+let _browserDeps = null;
+const getBrowserDeps = () => {
+  if (!_browserDeps) {
+    _browserDeps = {
+      DiffDOM: require('diff-dom').DiffDOM,
+      EventBinder: require('./EventBinder'),
+      Templates: require('./dust/Templates'),
+      FormHandler: require('./FormHandler'),
+    };
+  }
+  return _browserDeps;
+};
+
+class Igo2Component {
+  // Component registry for auto-discovery
+  static _registry = {};
+
+
+  // Register components for auto-initialization
+  static register(components) {
+    Object.assign(this._registry, components);
+  }
+
+  // Mount all registered components found on the page
+  static mountAll() {
+    document.querySelectorAll('[data-component]').forEach(element => {
+      const componentName = element.dataset.component;
+      const ComponentClass = this._registry[componentName];
+
+      if (ComponentClass) {
+        if (element.__igoInstance) {
+          console.warn(`Component "${componentName}" already mounted on`, element);
+          return;
+        }
+        new ComponentClass(element);
+      } else {
+        console.warn(`Component "${componentName}" not registered`);
+      }
+    });
+  }
+
+  // Server-side rendering: compute derived values (getters) for Dust templates
+  static ssr(props) {
+    const instance = new this(null, null, props);
+
+    const derived = {};
+    const descriptors = Object.getOwnPropertyDescriptors(this.prototype);
+
+    for (const [key, desc] of Object.entries(descriptors)) {
+      if (!desc.get || key.startsWith('_') || key === 'rawState' || key === 'events') {
+        continue;
+      }
+      try {
+        derived[key] = desc.get.call(instance);
+      } catch (e) {
+        // Getter may access DOM or throw → log and skip
+        console.error(`SSR getter "${key}" error:`, e.message);
+      }
+    }
+
+    return derived;
+  }
+
+  constructor(element, template, props) {
+
+    this.template = template;
+
+    // Browser-only setup
+    if (!isServer) {
+      const deps = getBrowserDeps();
+
+      this.element = element;
+      this.element.__igoInstance  = this;
+      this._dustTemplateFn        = null;
+      this._eventBinder           = new deps.EventBinder();
+      this._derivedCache          = new DerivedCache();
+      this._isInitialized         = false;
+      this._renderFrame           = null;
+      this._diffDom               = new deps.DiffDOM();
+    }
+
+    // Default events array (only if not defined as getter in subclass)
+    if (!Object.getOwnPropertyDescriptor(Object.getPrototypeOf(this), 'events')?.get) {
+      this.events = [];
+    }
+
+    // Auto-tracking system for smart dependencies
+    this._isTracking = false;
+    this._trackedDeps = [];
+
+    // Setup props, state, and derived with tracking proxies
+    let initialProps = {};
+
+    if (isServer) {
+      // SSR: use props passed to constructor
+      initialProps = props || {};
+    } else {
+      // Browser: hydrate from window and element
+      const globalProps = window.__signal_props || {};
+      let localProps = {};
+
+      // Hydrate local props from data-props attribute (serialized with devalue)
+      if (this.element.dataset.props) {
+        try {
+          // devalue produces a JS expression, so we need to evaluate it
+          // new Function is safer than eval because it creates a local scope
+          const hydrate = new Function('return ' + this.element.dataset.props);
+          localProps = hydrate();
+        } catch (e) {
+          console.error('Failed to parse data-props for component', this.element, e);
+        }
+      }
+
+      initialProps = { ...globalProps, ...localProps };
+    }
+
+    this._props = initialProps;
+    this._state = {};
+    this._derivedValues = {};
+
+    // Initialize form state from props (for SSR and browser)
+    if (initialProps.form) {
+      this._state.form = initialProps.form;
+    }
+
+    // Props (simple object in SSR, tracking proxy in browser)
+    if (isServer) {
+      this.props = this._props;
+      this.state = this._state;
+    } else {
+      this.props = this._createTrackingProxy(this._props, 'props');
+      this._stateProxy = new StateProxy(this, 'state');
+      this.state = this._stateProxy.create(this._state);
+    }
+
+    // Initialize component (browser only, async fire-and-forget)
+    if (!isServer) {
+      this.init();
+    }
+  }
+
+  // Create a tracking proxy for dependency detection
+  _createTrackingProxy(target, namespace) {
+    return new Proxy(target, {
+      get: (target, property) => {
+        if (this._isTracking) {
+          this._trackedDeps.push([namespace, property]);
+        }
+        return target[property];
+      }
+    });
+  }
+
+  // Expose raw state for internal use (bypasses Proxy, no auto-render)
+  get rawState() {
+    return this._state;
+  }
+
+  // Compute a derived value with automatic dependency tracking
+  _computeDerived(value, cacheKey) {
+    if (typeof value !== 'function') return value;
+
+    this._isTracking = true;
+    this._trackedDeps = [];
+    const boundFn = value.bind(this);
+    const computedValue = boundFn();
+    const deps = [...this._trackedDeps];
+    this._isTracking = false;
+
+    return this._derivedCache.memoize(cacheKey, boundFn, deps, this, computedValue);
+  }
+
+  // Initialize getters once (redefine on instance for lazy computation)
+  _initGetters() {
+    if (this._getterKeys) return; // Already initialized
+
+    const proto = Object.getPrototypeOf(this);
+    const descriptors = Object.getOwnPropertyDescriptors(proto);
+    const reserved = ['rawState', 'events'];
+
+    this._getterKeys = Object.keys(descriptors).filter(key => {
+      const desc = descriptors[key];
+      return desc.get && !reserved.includes(key) && !key.startsWith('_');
+    });
+
+    this._getterDescriptors = descriptors;
+
+    // Redefine getters on instance for lazy computation and tracking
+    this._getterKeys.forEach(key => {
+      Object.defineProperty(this, key, {
+        get: () => {
+          if (this._isTracking) {
+            this._trackedDeps.push(['derived', key]);
+          }
+          // Compute if not yet computed this cycle
+          if (!this._computedThisCycle?.has(key)) {
+            this._computeGetter(key);
+          }
+          return this._derivedValues[key];
+        },
+        configurable: true
+      });
+    });
+  }
+
+  // Compute a single getter
+  _computeGetter(key) {
+    this._computedThisCycle?.add(key);
+    const getterFn = this._getterDescriptors[key].get.bind(this);
+    this._derivedValues[key] = this._computeDerived(getterFn, key);
+  }
+
+  // Compute all getters for this render cycle
+  _computeGettersAsDerived() {
+    this._initGetters();
+    this._computedThisCycle = new Set();
+    this._getterKeys.forEach(key => this._computeGetter(key));
+  }
+
+  // Initialize component (called automatically by constructor)
+  // Can be overridden in subclasses for custom initialization
+  async init() {
+    const deps = getBrowserDeps();
+    this._dustTemplateFn = await deps.Templates.loadTemplate(this.template);
+    this._isInitialized = true;
+
+    // Initialize form handler if props.form exists
+    if (this.props.form) {
+      this._formHandler = new deps.FormHandler(this, this.props.form);
+    }
+
+    await this.render();
+  }
+
+  async render() {
+    try {
+      // beforeRender hook
+      await this.beforeRender?.();
+
+      // Calculate derived values (getters) with smart dependency tracking
+      this._computeGettersAsDerived();
+
+      // Merge props + state + derived for template context (flat)
+      const context = { ...this._props, ...this._state, ...this._derivedValues };
+      const html = await this._dustTemplateFn(context, window.__signal.IgoDustUtils, null);
+
+      const tempElement = document.createElement('div');
+      tempElement.innerHTML = html;
+
+      const diff = this._diffDom.diff(this.element, tempElement.firstElementChild);
+      const filteredDiff = this._filterChildComponentDiffs(diff);
+      this._diffDom.apply(this.element, filteredDiff);
+
+      // Sync props for child components (after DiffDOM updated data-props)
+      this._syncChildProps();
+
+      this._bindEvents();
+      this._mountChildComponents();
+      await this.afterRender();
+
+    } catch (error) {
+      console.error('SignalComponent render failed:', error);
+      await this.onError?.(error);
+    }
+  }
+
+  // Filter diffs that touch child components (preserve their state)
+  // Allow attribute modifications (like data-props) to pass through
+  _filterChildComponentDiffs(diff) {
+    return diff.filter(d => {
+      if (d.action === 'modifyAttribute' || d.action === 'addAttribute' || d.action === 'removeAttribute') {
+        return true;
+      }
+      let el = this.element;
+      for (const step of d.route || []) {
+        if (step === 'childNodes') continue;
+        if (typeof step === 'number') {
+          el = el?.childNodes?.[step];
+          if (el?.nodeType === 1 && el.hasAttribute?.('data-component') && el !== this.element) {
+            return false;
+          }
+        }
+      }
+      return true;
+    });
+  }
+
+  _bindEvents() {
+    this._formHandler?.unbind();
+    this._eventBinder.bind(this.element, this.events, this);
+    this._formHandler?.bind();
+  }
+
+  _mountChildComponents() {
+    // Mount any child components that were added during render
+    // Use global mountElement from signal/index.js
+    const mountElement = window.__signal?.mountElement;
+    if (!mountElement) {
+      return;
+    }
+
+    this.element.querySelectorAll('[data-component]').forEach(childElement => {
+      if (childElement === this.element) return;
+      if (childElement.__igoInstance) return;
+      mountElement(childElement);
+    });
+  }
+
+  _triggerRender() {
+    if (!this._isInitialized) {
+      return;
+    }
+    // Cancel any pending render
+    if (this._renderFrame) {
+      cancelAnimationFrame(this._renderFrame);
+    }
+    // Schedule render synchronized with browser paint
+    this._renderFrame = requestAnimationFrame(() => this.render());
+  }
+
+  // Sync props from parent (called after parent render)
+  _syncProps() {
+    if (!this.element?.dataset.props) {
+      return;
+    }
+
+    try {
+      const hydrate = new Function('return ' + this.element.dataset.props);
+      const newLocalProps = hydrate();
+
+      // Check if any prop changed
+      let hasChanges = false;
+      for (const key in newLocalProps) {
+        if (this._props[key] !== newLocalProps[key]) {
+          hasChanges = true;
+          break;
+        }
+      }
+
+      if (hasChanges) {
+        // Update _props with new local values
+        Object.assign(this._props, newLocalProps);
+        // Re-render (getters that depend on props will return new values)
+        this._triggerRender();
+      }
+    } catch (e) {
+      console.error('Failed to sync props', e);
+    }
+  }
+
+  // Sync props for all child components
+  _syncChildProps() {
+    this.element.querySelectorAll('[data-component]').forEach(childElement => {
+      if (childElement === this.element) return;
+      if (childElement.__igoInstance) {
+        childElement.__igoInstance._syncProps();
+      }
+    });
+  }
+
+  // Cleanup component (unbind listeners, clear timers, remove references)
+  async destroy() {
+    // Cancel any pending render
+    if (this._renderFrame) {
+      cancelAnimationFrame(this._renderFrame);
+    }
+
+    // Unbind all event listeners
+    this._eventBinder.unbind();
+
+    // Unbind form handler
+    this._formHandler?.unbind();
+    this._formHandler = null;
+
+    // Clear derived cache
+    this._derivedCache.clear();
+
+    // Clear references to help garbage collection
+    if (this.element) {
+      this.element.__igoInstance = null;
+    }
+    this.element = null;
+    this._dustTemplateFn = null;
+    this._eventBinder = null;
+    this._derivedCache = null;
+    this._stateProxy = null;
+    this._state = {};
+    this._derivedValues = {};
+    this._trackedDeps = [];
+  }
+
+  // Lifecycle hooks (can be overridden in subclasses)
+  async beforeRender() { }
+  async afterRender() { }
+  async onError(error) { }
+
+}
+
+module.exports = Igo2Component;