@igojs/signal 6.0.0-beta.1

package/README.md

@@ -0,0 +1,203 @@
+# @igojs/signal
+
+Reactive frontend/SSR framework for Igo.js with automatic dependency tracking.
+
+## Installation
+
+```sh
+npm install @igojs/signal
+```
+
+## Features
+
+- **Reactive State** - Deep reactivity via Proxy (like Vue 3)
+- **Auto-tracking** - Automatic dependency detection for computed values
+- **SSR Support** - Server-side rendering with hydration
+- **DiffDOM** - Efficient DOM reconciliation
+- **Form Handling** - Two-way binding for forms
+- **Dust Templates** - Integration with @igojs/dust
+
+## Architecture
+
+```
+Props (immutable) → State (reactive) → Derived (computed) → Template → DOM
+                          ↓                                           ↓
+                    Proxy tracking                         DiffDOM reconciliation
+```
+
+## Quick Start
+
+### Server Setup
+
+```javascript
+const express = require('express');
+const signal = require('@igojs/signal');
+
+const app = express();
+
+// Configure translations (optional)
+signal.configure({
+  translations: require('./locales/fr/translation.json')
+});
+
+// Add signal middleware
+app.use(signal.middleware);
+
+// Template endpoint for client-side loading
+app.get('/__signal/templates', signal.templates);
+
+// Controller
+app.get('/products', (req, res) => {
+  res.locals.signal_props = {
+    products: await Product.list(),
+    form: { search: req.query.search || '' }
+  };
+  res.render('products/index');
+});
+```
+
+### Component Definition
+
+```javascript
+// components/ProductList.js
+const { SignalComponent } = require('@igojs/signal');
+
+class ProductList extends SignalComponent {
+  constructor(element) {
+    super(element, 'components/ProductList');
+  }
+
+  // Computed value with auto-tracking
+  get filteredProducts() {
+    const search = this.state.form?.search?.toLowerCase() || '';
+    return this.props.products.filter(p =>
+      p.name.toLowerCase().includes(search)
+    );
+  }
+
+  // Event handlers
+  get events() {
+    return [
+      { selector: '.delete-btn', eventType: 'click', handler: this.onDelete }
+    ];
+  }
+
+  async onDelete(e) {
+    const id = e.target.dataset.id;
+    await fetch(`/api/products/${id}`, { method: 'DELETE' });
+    this.props.products = this.props.products.filter(p => p.id !== id);
+  }
+}
+
+module.exports = ProductList;
+```
+
+### Template (Dust)
+
+```dust
+{! views/components/ProductList.dust !}
+<div data-component="components/ProductList" data-props="{@serialize props="products,form" /}">
+  <input type="text" name="search" value="{form.search}" placeholder="Search...">
+
+  <ul>
+    {#filteredProducts}
+      <li>
+        {name} - ${price}
+        <button class="delete-btn" data-id="{id}">Delete</button>
+      </li>
+    {/filteredProducts}
+  </ul>
+</div>
+```
+
+### Client Entry Point
+
+```javascript
+// assets/js/app.js
+const signal = require('@igojs/signal/src/client');
+
+signal.start({
+  components: require.context('./components', true, /\.js$/),
+  helpers: require('./helpers')
+});
+```
+
+## API
+
+### Server
+
+| Export | Description |
+|--------|-------------|
+| `middleware` | Express middleware for SSR |
+| `templates` | Endpoint for client template loading |
+| `configure({ translations })` | Configure i18n translations |
+| `serialize(data)` | Serialize data for hydration |
+| `SignalComponent` | Base component class |
+
+### SignalComponent
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `this.props` | Immutable props from server |
+| `this.state` | Reactive state (triggers re-render on change) |
+| `this.rawState` | Direct state access (no reactivity) |
+| `get xyz()` | Computed values with auto-tracking |
+| `get events()` | Event bindings `[{selector, eventType, handler}]` |
+| `beforeRender()` | Lifecycle hook before render |
+| `afterRender()` | Lifecycle hook after render |
+| `destroy()` | Cleanup component |
+
+### Reactivity
+
+```javascript
+// Deep reactivity
+this.state.user = { name: 'John' };
+this.state.user.name = 'Jane';           // Triggers render
+this.state.items.push({ id: 1 });        // Triggers render
+this.state.items[0].active = true;       // Triggers render
+```
+
+### Form Handling
+
+Forms are automatically bound when `props.form` exists:
+
+```javascript
+// In your component
+get selectedProduct() {
+  const id = Number(this.state.form?.product_id);
+  return this.props.products.find(p => p.id === id);
+}
+```
+
+```dust
+<select name="product_id">
+  {#products}
+    <option value="{id}" {@selected key=id value=form.product_id /}>{name}</option>
+  {/products}
+</select>
+```
+
+## Module Structure
+
+```
+src/
+├── client/                   # Browser code
+│   ├── index.js              # Entry point, start()
+│   ├── SignalComponent.js    # Base component class
+│   ├── StateProxy.js         # Deep reactivity
+│   ├── DerivedCache.js       # Computed value memoization
+│   ├── EventBinder.js        # Event listener management
+│   ├── FormHandler.js        # Two-way form binding
+│   └── dust/
+│       ├── Templates.js      # Template loading
+│       ├── Utils.js          # Dust helpers/filters
+│       └── i18n.js           # i18next setup
+└── server/                   # Node.js code
+    ├── index.js              # Server exports
+    ├── SignalController.js   # SSR middleware
+    └── SerializeUtils.js     # Data serialization
+```
+
+## Documentation
+
+See the [full documentation](https://igocreate.github.io/igo/#/signal/components).

package/index.js

@@ -0,0 +1,24 @@
+// @igojs/signal - Reactive frontend/SSR framework for Igo.js
+
+// Server-side exports
+const server = require('./src/server');
+
+// Re-export server utilities
+module.exports = {
+  // Server middleware for SSR
+  middleware: server.middleware,
+
+  // Template serving endpoint
+  templates: server.templates,
+
+  // Configure signal (translations, etc.)
+  configure: server.configure,
+
+  // Serialization for client hydration
+  serialize: server.serialize,
+
+  // SignalComponent for SSR rendering
+  get SignalComponent() {
+    return require('./src/client/SignalComponent');
+  },
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@igojs/signal",
+  "version": "6.0.0-beta.1",
+  "description": "Signal - Reactive frontend/SSR framework for Igo.js",
+  "main": "index.js",
+  "browser": "src/client/index.js",
+  "scripts": {
+    "test": "mocha --exit 'test/**/*.js'"
+  },
+  "keywords": [
+    "frontend",
+    "ssr",
+    "reactive",
+    "signals",
+    "components"
+  ],
+  "author": "@igocreate",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@igojs/server": "*",
+    "@igojs/dust": "*",
+    "devalue": "^5.6.1",
+    "diff-dom": "^5.2.1",
+    "i18next": "^25.7.3",
+    "lodash": "^4.17.21"
+  }
+}

package/src/client/DerivedCache.js

@@ -0,0 +1,63 @@
+/**
+ * DerivedCache - Memoization with auto-tracked dependencies (like Vue 3 computed)
+ *
+ * Caches expensive calculations and recalculates only when dependencies change.
+ * Uses Proxy-based dependency tracking to automatically detect what values are accessed.
+ */
+class DerivedCache {
+  constructor() {
+    this._cache = new Map(); // Map<key, { value, deps }>
+  }
+
+  // Memoize a derived value with optional precomputed value
+  memoize(key, fn, deps, context, precomputedValue) {
+    const resolvedDeps = context ? this._resolveDeps(deps, context) : deps;
+
+    // If precomputed value provided, use it directly (first render optimization)
+    if (precomputedValue !== undefined) {
+      this._cache.set(key, { value: precomputedValue, deps: [...resolvedDeps], fn });
+      return precomputedValue;
+    }
+
+    // Check cache for existing value
+    const cached = this._cache.get(key);
+    if (cached && this._areDepsEqual(cached.deps, resolvedDeps)) {
+      return cached.value;
+    }
+
+    // Recompute
+    const value = fn();
+    this._cache.set(key, { value, deps: [...resolvedDeps] });
+    return value;
+  }
+
+  // Resolve dependency paths like ['props', 'products'] to actual values
+  _resolveDeps(deps, context) {
+    return deps.map(dep => {
+      if (!Array.isArray(dep)) return dep;
+
+      let value = context;
+      for (const key of dep) value = value?.[key];
+      return value;
+    });
+  }
+
+  // Shallow comparison (Object.is like React)
+  _areDepsEqual(prevDeps, nextDeps) {
+    if (prevDeps.length !== nextDeps.length) return false;
+    for (let i = 0; i < prevDeps.length; i++) {
+      if (!Object.is(prevDeps[i], nextDeps[i])) return false;
+    }
+    return true;
+  }
+
+  clear() {
+    this._cache.clear();
+  }
+
+  invalidate(key) {
+    this._cache.delete(key);
+  }
+}
+
+module.exports = DerivedCache;

package/src/client/EventBinder.js

@@ -0,0 +1,135 @@
+/**
+ * EventBinder - Optimized event listener management with WeakMap caching
+ *
+ * Similar to how modern frameworks (Vue, Svelte, Solid) optimize event binding,
+ * this class avoids unnecessary rebinding by caching listeners and reusing them
+ * when DOM elements are preserved by DiffDOM.
+ *
+ * Strategy: WeakMap<Element, Map<eventType, handler>>
+ * - Outer WeakMap: Element → Map of events (automatic garbage collection)
+ * - Inner Map: eventType → handler (supports multiple events per element)
+ *
+ * Performance:
+ * - O(1) lookup to check if listener exists
+ * - No rebinding if element is preserved by DiffDOM
+ * - Automatic cleanup when elements are removed (WeakMap GC)
+ */
+class EventBinder {
+  constructor() {
+    // WeakMap<Element, Map<eventType, handler>>
+    this._elementListeners = new WeakMap();
+    this._boundListeners = [];
+  }
+
+  /**
+   * Bind events to elements with optimization
+   *
+   * @param {HTMLElement} rootElement - Root element to search within
+   * @param {Array} events - Array of {selector, eventType, handler}
+   * @param {Object} context - Context to bind handlers to (usually the component)
+   */
+  bind(rootElement, events, context) {
+    if (!events || !Array.isArray(events)) return;
+
+    const newListeners = [];
+    const processedElements = new Map(); // Map<Element, Set<eventType>>
+
+    events.forEach(({ selector, eventType, handler }) => {
+      // Support 'document'/'window' strings as selector for global events
+      let elements;
+      if (selector === 'document') {
+        elements = [document];
+      } else if (selector === 'window') {
+        elements = [window];
+      } else {
+        elements = rootElement.querySelectorAll(selector);
+      }
+
+      elements.forEach(targetElement => {
+        // Skip warning for global selectors (document/window)
+        const isGlobalSelector = targetElement === document || targetElement === window;
+
+        // Warn if trying to bind to an element inside a child component
+        // Only warn if targeting elements INSIDE a child component, not the component's root element itself
+        if (!isGlobalSelector) {
+          const closestComponent = targetElement.closest('[data-component]');
+          const isTargetingChildComponentRoot = closestComponent === targetElement;
+          if (closestComponent && closestComponent !== rootElement && !isTargetingChildComponentRoot) {
+            console.warn(
+              `[EventBinder] Warning: Attempting to bind ${eventType} event to selector "${selector}" ` +
+              `which is inside a child component (${closestComponent.dataset.component}). ` +
+              `Consider listening to a custom event from the child component instead.`,
+              { parentComponent: context.constructor?.name, childComponent: closestComponent.dataset.component, targetElement }
+            );
+          }
+        }
+
+        // Get or create event map for this element
+        let eventMap = this._elementListeners.get(targetElement);
+        if (!eventMap) {
+          eventMap = new Map();
+          this._elementListeners.set(targetElement, eventMap);
+        }
+
+        // Check if this (element, eventType) already has a listener
+        const existingHandler = eventMap.get(eventType);
+
+        if (existingHandler) {
+          // ✅ Element preserved by DiffDOM → reuse existing listener
+          newListeners.push({
+            element: targetElement,
+            eventType,
+            handler: existingHandler
+          });
+        } else {
+          // ✅ New element or new eventType → create new listener
+          const boundHandler = handler.bind(context);
+          targetElement.addEventListener(eventType, boundHandler);
+          eventMap.set(eventType, boundHandler);
+          newListeners.push({
+            element: targetElement,
+            eventType,
+            handler: boundHandler
+          });
+        }
+
+        // Track processed elements for cleanup
+        if (!processedElements.has(targetElement)) {
+          processedElements.set(targetElement, new Set());
+        }
+        processedElements.get(targetElement).add(eventType);
+      });
+    });
+
+    // Cleanup: Remove listeners for elements that were removed or changed
+    this._boundListeners.forEach(({ element, eventType, handler }) => {
+      const processedEvents = processedElements.get(element);
+      if (!processedEvents || !processedEvents.has(eventType)) {
+        // Element was removed or event type changed → cleanup
+        element?.removeEventListener(eventType, handler);
+        const eventMap = this._elementListeners.get(element);
+        if (eventMap) {
+          eventMap.delete(eventType);
+          if (eventMap.size === 0) {
+            this._elementListeners.delete(element);
+          }
+        }
+      }
+    });
+
+    this._boundListeners = newListeners;
+  }
+
+  /**
+   * Unbind all listeners and clear cache
+   */
+  unbind() {
+    this._boundListeners.forEach(({ element, eventType, handler }) => {
+      element?.removeEventListener(eventType, handler);
+    });
+    this._boundListeners = [];
+    // Note: WeakMap clears itself automatically when elements are garbage collected
+  }
+}
+
+module.exports = EventBinder;

package/src/client/FormHandler.js

@@ -0,0 +1,94 @@
+class FormHandler {
+  constructor(component, formData) {
+    this.component = component;
+    this.element = component.element;
+    this._state = component.rawState;
+    this._boundListeners = [];
+
+    // Initialize form state
+    this._state.form = this.initForm(formData);
+  }
+
+  // Initialize form from props.form
+  // Uses a shared form object (window.__signal_form) so all components share the same form state
+  initForm(formData) {
+    if (!window.__signal_form) {
+      window.__signal_form = { ...formData };
+    }
+    return window.__signal_form;
+  }
+
+  bind() {
+    this.element.querySelectorAll('input, select, textarea').forEach(element => {
+      if (!element.name) {
+        return;
+      }
+
+      // Skip inputs that are inside child components
+      const parentComponent = element.closest('[data-component]');
+      if (parentComponent && parentComponent !== this.element) {
+        return; // Skip this input, it belongs to a child component
+      }
+
+      const eventType = ['checkbox', 'radio'].includes(element.type) || element.tagName === 'SELECT' ? 'change' : 'input';
+      const handler = (e) => this.handleInput(e.target);
+
+      element.addEventListener(eventType, handler);
+      this._boundListeners.push({ element, eventType, handler });
+    });
+  }
+
+  unbind() {
+    this._boundListeners.forEach(({ element, eventType, handler }) => {
+      element?.removeEventListener(eventType, handler);
+    });
+    this._boundListeners = [];
+  }
+
+  // Handle form input change
+  handleInput(element) {
+    const { name, type, value } = element;
+
+    // name[index][] format
+    const arrayWithIndexMatch = name.match(/^(.+)\[(\d+)\]\[\]$/);
+    if (arrayWithIndexMatch) {
+      const [, fieldName, indexStr] = arrayWithIndexMatch;
+      const index = parseInt(indexStr, 10);
+
+      this._state.form[fieldName] = this._state.form[fieldName] || [];
+
+      if (type === 'select-multiple') {
+        this._state.form[fieldName][index] = [...element.options].filter(o => o.selected).map(o => o.value);
+      } else if (type === 'checkbox') {
+        this._state.form[fieldName][index] = Array.from(this.element.querySelectorAll(`[name="${name}"]:checked`)).map(el => el.value);
+      } else {
+        this._state.form[fieldName][index] = value;
+      }
+      return this.component._triggerRender();
+    }
+
+    const isArray = name.endsWith('[]');
+    const fieldName = isArray ? name.slice(0, -2) : name;
+
+    if (type === 'checkbox') {
+      this._state.form[fieldName] = isArray
+        ? Array.from(this.element.querySelectorAll(`[name="${name}"]:checked`)).map(el => el.value)
+        : element.checked;
+    } else if (type === 'select-multiple') {
+      this._state.form[fieldName] = [...element.options].filter(o => o.selected).map(o => o.value);
+    } else if (isArray) {
+      this._state.form[fieldName] = this._state.form[fieldName] || [];
+      const elements = Array.from(this.element.querySelectorAll(`[name="${name}"]`));
+      const elementIndex = elements.indexOf(element);
+      if (elementIndex !== -1) {
+        this._state.form[fieldName][elementIndex] = value;
+      }
+    } else {
+      this._state.form[fieldName] = value;
+    }
+
+    this.component._triggerRender();
+  }
+}
+
+module.exports = FormHandler;