lume-js 1.0.0 → 2.0.0-alpha.2

package/src/addons/repeat.js

@@ -18,65 +18,58 @@
  * - Set to null/false to disable, or provide custom functions
  * - Export utilities so you can wrap/extend them
  *
- * Usage:
- *   import { repeat } from "lume-js/addons/repeat.js";
- *   
- *   // ⚠️ IMPORTANT: Arrays must be updated immutably!
- *   // store.items.push(x)      // ❌ Won't trigger update
- *   // store.items = [...items] // ✅ Triggers update
- *   
- *   // Basic usage (focus & scroll preservation enabled by default)
+ * ⚠️ IMPORTANT: Arrays must be updated immutably!
+ * store.items.push(x)      // ❌ Won't trigger update
+ * store.items = [...items] // ✅ Triggers update
+ * 
+ * ═══════════════════════════════════════════════════════════════════════
+ * PATTERN 1: Simple (render only) - for simple cases or backward compat
+ * ═══════════════════════════════════════════════════════════════════════
+ * 
  *   repeat('#list', store, 'todos', {
  *     key: todo => todo.id,
  *     render: (todo, el) => {
- *       if (!el.dataset.init) {
- *         el.innerHTML = `<input value="${todo.text}">`;
- *         el.dataset.init = 'true';
- *       }
+ *       el.textContent = todo.name;  // Called on every update
  *     }
  *   });
- *   
- *   // Disable all preservation (bare-bones repeat)
- *   repeat('#list', store, 'items', {
- *     key: item => item.id,
- *     render: (item, el) => { el.textContent = item.name; },
- *     preserveFocus: null,
- *     preserveScroll: null
- *   });
- *   
- *   // Custom focus preservation
- *   repeat('#list', store, 'items', {
- *     key: item => item.id,
- *     render: (item, el) => { ... },
- *     preserveFocus: (container) => {
- *       // Your custom logic
- *       const state = { focused: document.activeElement };
- *       return () => state.focused?.focus();
+ *
+ * ═══════════════════════════════════════════════════════════════════════
+ * PATTERN 2: Clean separation (create + update) - recommended
+ * ═══════════════════════════════════════════════════════════════════════
+ * 
+ *   repeat('#list', store, 'todos', {
+ *     key: todo => todo.id,
+ *     create: (todo, el) => {
+ *       // Called ONCE when element is created - build DOM structure
+ *       el.innerHTML = `<span class="name"></span><button>Delete</button>`;
+ *       el.querySelector('button').onclick = () => deleteTodo(todo.id);
+ *     },
+ *     update: (todo, el, index, { isFirstRender }) => {
+ *       // Called on every update - bind data
+ *       // isFirstRender = true on initial render, false on subsequent
+ *       // Skipped if same object reference (optimization)
+ *       el.querySelector('.name').textContent = todo.name;
  *     }
  *   });
- *   
- *   // Mix built-in and custom
- *   import { defaultFocusPreservation, defaultScrollPreservation } from "lume-js/addons/repeat.js";
+ *
+ * ═══════════════════════════════════════════════════════════════════════
+ * ADVANCED: Custom preservation strategies
+ * ═══════════════════════════════════════════════════════════════════════
+ * 
+ *   import { defaultFocusPreservation, defaultScrollPreservation } from "lume-js/addons";
  *   
  *   repeat('#list', store, 'items', {
  *     key: item => item.id,
- *     render: (item, el) => { ... },
- *     preserveFocus: defaultFocusPreservation, // use built-in
+ *     create: (item, el) => { ... },
+ *     update: (item, el) => { ... },
+ *     preserveFocus: null, // disable focus preservation
  *     preserveScroll: (container, context) => {
- *       // wrap/extend built-in
  *       const restore = defaultScrollPreservation(container, context);
- *       return () => {
- *         restore();
- *         console.log('Scroll restored!');
- *       };
+ *       return () => { restore(); console.log('Scroll restored!'); };
  *     }
  *   });
  */
 
-// ============================================================================
-// PRESERVATION UTILITIES (Exported for customization)
-// ============================================================================
-
 /**
  * Default focus preservation strategy
  * Saves activeElement and selection state before DOM updates
@@ -158,10 +151,6 @@ export function defaultScrollPreservation(container, context = {}) {
   };
 }
 
-// ============================================================================
-// MAIN REPEAT FUNCTION
-// ============================================================================
-
 /**
  * Efficiently render a list with element reuse
  * 
@@ -170,7 +159,9 @@ export function defaultScrollPreservation(container, context = {}) {
  * @param {string} arrayKey - Key in store containing the array
  * @param {Object} options - Configuration
  * @param {Function} options.key - Function to extract unique key: (item) => key
- * @param {Function} options.render - Function to render item: (item, element, index) => void
+ * @param {Function} [options.render] - Function to render item (called for all items): (item, element, index) => void
+ * @param {Function} [options.create] - Function for new elements only: (item, element, index) => void
+ * @param {Function} [options.update] - Function for data binding: (item, element, index, { isFirstRender }) => void. Skipped if same item reference AND same index.
  * @param {string|Function} [options.element='div'] - Element tag name or factory function
  * @param {Function|null} [options.preserveFocus=defaultFocusPreservation] - Focus preservation strategy (null to disable)
  * @param {Function|null} [options.preserveScroll=defaultScrollPreservation] - Scroll preservation strategy (null to disable)
@@ -180,6 +171,8 @@ export function repeat(container, store, arrayKey, options) {
   const {
     key,
     render,
+    create,
+    update,
     element = 'div',
     preserveFocus = defaultFocusPreservation,
     preserveScroll = defaultScrollPreservation
@@ -200,12 +193,16 @@ export function repeat(container, store, arrayKey, options) {
     throw new Error('[Lume.js] repeat(): options.key must be a function');
   }
 
-  if (typeof render !== 'function') {
-    throw new Error('[Lume.js] repeat(): options.render must be a function');
+  if (typeof render !== 'function' && typeof create !== 'function') {
+    throw new Error('[Lume.js] repeat(): options.render or options.create must be a function');
   }
 
   // key -> HTMLElement
   const elementsByKey = new Map();
+  // key -> previous item (for reference comparison)
+  const prevItemsByKey = new Map();
+  // key -> previous index (for reorder detection)
+  const prevIndexByKey = new Map();
   const seenKeys = new Set();
 
   function createElement() {
@@ -254,24 +251,38 @@ export function repeat(container, store, arrayKey, options) {
       nextKeys.add(k);
 
       let el = elementsByKey.get(k);
-      const isNew = !el;
+      const isFirstRender = !el;
 
-      if (isNew) {
+      if (isFirstRender) {
         el = createElement();
         elementsByKey.set(k, el);
       }
 
       try {
-        if (isNew) {
-          el.__lume_new = true;
+        // Call create for new elements (DOM structure)
+        if (isFirstRender && create) {
+          create(item, el, i);
+        }
+
+        // Call update for data binding (new and existing elements)
+        // Skip if same item reference AND same index (optimization)
+        const prevItem = prevItemsByKey.get(k);
+        const prevIndex = prevIndexByKey.get(k);
+        if (update) {
+          if (prevItem !== item || prevIndex !== i) {
+            update(item, el, i, { isFirstRender });
+          }
+        } else if (render) {
+          // Backward compatibility: render handles both create and update
+          render(item, el, i);
         }
 
-        render(item, el, i);
+        // Store reference and index for next comparison
+        prevItemsByKey.set(k, item);
+        prevIndexByKey.set(k, i);
 
       } catch (err) {
         console.error(`[Lume.js] repeat(): error rendering key "${k}"`, err);
-      } finally {
-        delete el.__lume_new;
       }
 
       nextEls.push(el);
@@ -298,12 +309,13 @@ export function repeat(container, store, arrayKey, options) {
       ptr = next;
     }
 
-    // Clean map: remove keys not in nextKeys
-    // Iterate over elementsByKey entries and delete if not in nextKeys
+    // Clean maps: remove keys not in nextKeys
     if (elementsByKey.size !== nextKeys.size) {
       for (const k of elementsByKey.keys()) {
         if (!nextKeys.has(k)) {
           elementsByKey.delete(k);
+          prevItemsByKey.delete(k);
+          prevIndexByKey.delete(k);
         }
       }
     }
@@ -328,6 +340,8 @@ export function repeat(container, store, arrayKey, options) {
     return () => {
       containerEl.replaceChildren();
       elementsByKey.clear();
+      prevItemsByKey.clear();
+      prevIndexByKey.clear();
       seenKeys.clear();
     };
   }
@@ -337,6 +351,8 @@ export function repeat(container, store, arrayKey, options) {
     // Clear DOM elements (replaceChildren is faster than loop)
     containerEl.replaceChildren();
     elementsByKey.clear();
+    prevItemsByKey.clear();
+    prevIndexByKey.clear();
     seenKeys.clear();
   };
 }

package/src/core/bindDom.js

@@ -52,9 +52,12 @@ export function bindDom(root, store, options = {}) {
     const nodes = root.querySelectorAll("[data-bind]");
     const cleanups = [];
 
+    // Map for event delegation: element → { target, lastKey }
+    const bindingMap = new Map();
+
     nodes.forEach(el => {
       const bindPath = el.getAttribute("data-bind");
-      
+
       if (!bindPath) {
         console.warn('[Lume.js] Empty data-bind attribute found', el);
         return;
@@ -82,18 +85,27 @@ export function bindDom(root, store, options = {}) {
       });
       cleanups.push(unsubscribe);
 
-      // Two-way binding for form inputs
+      // Store binding info for event delegation (form inputs only)
       if (isFormInput(el)) {
-        const handler = e => {
-          target[lastKey] = getInputValue(e.target);
-        };
-        el.addEventListener("input", handler);
-        cleanups.push(() => el.removeEventListener("input", handler));
+        bindingMap.set(el, { target, lastKey });
       }
     });
 
+    // Event delegation: single listener on root for all form inputs
+    const delegatedHandler = e => {
+      const el = e.target;
+      const binding = bindingMap.get(el);
+      if (binding) {
+        binding.target[binding.lastKey] = getInputValue(el);
+      }
+    };
+
+    root.addEventListener("input", delegatedHandler);
+    cleanups.push(() => root.removeEventListener("input", delegatedHandler));
+
     return () => {
       cleanups.forEach(cleanup => cleanup());
+      bindingMap.clear();
     };
   };
 
@@ -104,7 +116,7 @@ export function bindDom(root, store, options = {}) {
       cleanup = performBinding();
     };
     document.addEventListener('DOMContentLoaded', onReady, { once: true });
-    
+
     // Return cleanup function that handles both cases
     return () => {
       if (cleanup) {
@@ -165,7 +177,7 @@ function getInputValue(el) {
  * @private
  */
 function isFormInput(el) {
-  return el.tagName === "INPUT" || 
-         el.tagName === "TEXTAREA" || 
-         el.tagName === "SELECT";
+  return el.tagName === "INPUT" ||
+    el.tagName === "TEXTAREA" ||
+    el.tagName === "SELECT";
 }

package/src/core/effect.js

@@ -1,100 +1,140 @@
 /**
  * Lume-JS Effect
  * 
- * Automatic dependency tracking for reactive effects.
- * Tracks which state properties are accessed during execution
- * and automatically re-runs when those properties change.
+ * Reactive effects with two modes:
+ * 1. Auto-tracking (default): Tracks dependencies automatically
+ * 2. Explicit deps: You specify exactly what triggers re-runs
  * 
  * Part of core because it's fundamental to modern reactivity.
  * 
  * Usage:
  *   import { effect } from "lume-js";
  *   
+ *   // Auto-tracking mode (existing behavior)
  *   effect(() => {
  *     console.log('Count is:', store.count);
  *     // Automatically re-runs when store.count changes
  *   });
+ *   
+ *   // Explicit deps mode (new - no magic)
+ *   effect(() => {
+ *     console.log('Count is:', store.count);
+ *   }, [[store, 'count']]);  // Only re-runs when store.count changes
  * 
  * Features:
- * - Automatic dependency collection
- * - Dynamic dependencies (tracks what you actually access)
+ * - Automatic dependency collection (default)
+ * - Explicit dependencies for side-effects
  * - Returns cleanup function
- * - Plays nicely with per-state batching (no global scheduler)
- *
+ * - Compatible with per-state batching
  */
 
 /**
- * Creates an effect that automatically tracks dependencies
+ * Creates an effect that runs reactively
  *
- * The effect runs immediately and collects dependencies by tracking
- * which state properties are accessed. When any dependency changes,
- * the effect re-runs automatically.
- * 
  * @param {function} fn - Function to run reactively
+ * @param {Array<[object, string]>} [deps] - Optional explicit dependencies as [store, key] tuples
  * @returns {function} Cleanup function to stop the effect
  * 
  * @example
- * const store = state({ count: 0, name: 'Alice' });
- * 
- * const cleanup = effect(() => {
- *   // Only tracks 'count' (name not accessed)
+ * // Auto-tracking (default)
+ * const store = state({ count: 0 });
+ * effect(() => {
  *   document.title = `Count: ${store.count}`;
  * });
  * 
- * store.count = 5;  // Effect re-runs
- * store.name = 'Bob'; // Effect does NOT re-run
- * 
- * cleanup(); // Stop tracking
+ * @example
+ * // Explicit deps (no magic)
+ * effect(() => {
+ *   analytics.log(store.count);  // Won't track store.count automatically
+ * }, [[store, 'count']]);        // Explicit: only re-run on store.count
  */
-export function effect(fn) {
+export function effect(fn, deps) {
   if (typeof fn !== 'function') {
     throw new Error('effect() requires a function');
   }
 
   const cleanups = [];
-  let isRunning = false; // Prevent infinite recursion
-  
+  let isRunning = false;
+
   /**
-   * Execute the effect function and collect dependencies
-   *
-   * The execution re-tracks accessed keys on every run. Subscriptions
-   * are cleaned up and re-established so the effect always reflects
-   * current dependencies.
+   * Execute the effect function
    */
   const execute = () => {
-    if (isRunning) return; // Prevent re-entry
-    
-    // Clean up previous subscriptions
-    cleanups.forEach(cleanup => cleanup());
-    cleanups.length = 0;
-    
-    // Create effect context for tracking
-    const effectContext = {
-      fn,
-      cleanups,
-      execute, // Reference to this execute function
-      tracking: {} // Map of tracked keys
-    };
-    
-    // Set as current effect (for state.js to detect)
-    globalThis.__LUME_CURRENT_EFFECT__ = effectContext;
+    if (isRunning) return;
     isRunning = true;
-    
+
     try {
-      // Run the effect function (this triggers state getters)
       fn();
     } catch (error) {
       console.error('[Lume.js effect] Error in effect:', error);
       throw error;
     } finally {
-      // Always clean up, even if error
-      globalThis.__LUME_CURRENT_EFFECT__ = undefined;
       isRunning = false;
     }
   };
-  
-  // Run immediately to collect initial dependencies
-  execute();
+
+  // EXPLICIT DEPS MODE: deps array provided
+  if (Array.isArray(deps)) {
+    // Subscribe to each [store, key1, key2, ...] tuple explicitly
+    for (const dep of deps) {
+      if (Array.isArray(dep) && dep.length >= 2) {
+        const [store, ...keys] = dep;
+        if (store && typeof store.$subscribe === 'function') {
+          // Subscribe to each key in this tuple
+          for (const key of keys) {
+            // $subscribe calls immediately, then on changes
+            // We want: call execute immediately once, then on changes
+            let isFirst = true;
+            const unsub = store.$subscribe(key, () => {
+              if (isFirst) {
+                isFirst = false;
+                return; // Skip first call, we'll run execute() below
+              }
+              execute();
+            });
+            cleanups.push(unsub);
+          }
+        }
+      }
+    }
+    // Run immediately
+    execute();
+  }
+  // AUTO-TRACKING MODE: no deps (existing behavior)
+  else {
+    const executeWithTracking = () => {
+      if (isRunning) return;
+
+      // Clean up previous subscriptions
+      cleanups.forEach(cleanup => cleanup());
+      cleanups.length = 0;
+
+      // Create effect context for tracking
+      const effectContext = {
+        fn,
+        cleanups,
+        execute: executeWithTracking,
+        tracking: {}
+      };
+
+      // Set as current effect (for state.js to detect)
+      globalThis.__LUME_CURRENT_EFFECT__ = effectContext;
+      isRunning = true;
+
+      try {
+        fn();
+      } catch (error) {
+        console.error('[Lume.js effect] Error in effect:', error);
+        throw error;
+      } finally {
+        globalThis.__LUME_CURRENT_EFFECT__ = undefined;
+        isRunning = false;
+      }
+    };
+
+    // Run immediately to collect initial dependencies
+    executeWithTracking();
+  }
 
   // Return cleanup function
   return () => {

package/src/core/state.js

@@ -4,6 +4,7 @@
  * Provides minimal reactive state with standard JavaScript.
  * Features automatic microtask batching for performance.
  * Supports automatic dependency tracking for effects.
+ * Supports optional plugin system for extensibility (v2.0+).
  * 
  * Features:
  * - Lightweight and Go-style
@@ -12,47 +13,93 @@
  * - Cleanup with unsubscribe
  * - Per-state microtask batching for writes
  * - Effect dependency tracking support (deduped per state flush)
+ * - Plugin system for custom behaviors (v2.0+)
  *
  * Usage:
  *   import { state } from "lume-js";
+ *   
+ *   // Basic usage (v1.x compatible)
  *   const store = state({ count: 0 });
  *   const unsub = store.$subscribe("count", val => console.log(val));
  *   unsub(); // cleanup
+ *   
+ *   // With plugins (v2.0+)
+ *   const store = state(
+ *     { count: 0 },
+ *     { plugins: [debugPlugin] }
+ *   );
  */
 
 // Per-state batching – each state object maintains its own microtask flush.
 // This keeps effects simple and aligned with Lume's minimal philosophy.
 
 /**
- * Creates a reactive state object.
+ * Creates a reactive state object with optional plugin support.
  * 
- * @param {Object} obj - Initial state object
+ * @param {Object} obj - Initial state object (must be plain object)
+ * @param {Object} [options] - Optional configuration
+ * @param {Array<Plugin>} [options.plugins] - Array of plugins to apply
  * @returns {Proxy} Reactive proxy with $subscribe method
+ * 
+ * @example
+ * // Basic usage
+ * const store = state({ count: 0 });
+ * 
+ * @example
+ * // With plugins
+ * const store = state(
+ *   { count: 0 },
+ *   { 
+ *     plugins: [
+ *       {
+ *         name: 'logger',
+ *         onGet: (key, value) => {
+ *           console.log(`GET ${key}:`, value);
+ *           return value;
+ *         }
+ *       }
+ *     ]
+ *   }
+ * );
  */
 // Internal symbol used to mark reactive proxies (non-enumerable via Proxy trap)
 const REACTIVE_MARKER = Symbol('__LUME_REACTIVE__');
 
-export function state(obj) {
+export function state(obj, options = {}) {
   // Validate input
   if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
     throw new Error('state() requires a plain object');
   }
 
+  // Extract plugins (minimal validation)
+  const plugins = options.plugins || [];
+
   const listeners = {};
   const pendingNotifications = new Map(); // Per-state pending changes
   const pendingEffects = new Set(); // Dedupe effects per state
   let flushScheduled = false;
 
+  // Call onInit hooks
+  for (const p of plugins) {
+    try { 
+      p.onInit?.(); 
+    } catch (e) { 
+      console.error(`[Lume.js] Plugin "${p.name}" error in onInit:`, e); 
+    }
+  }
+
   /**
    * Schedule a single microtask flush for this state object.
    *
    * Flush order per state:
-   * 1) Notify subscribers for changed keys (key → subscribers)
-   * 2) Run each queued effect exactly once (Set-based dedupe)
+   * 1) Call plugin onNotify hooks for each changed key
+   * 2) Notify subscribers for changed keys (key → subscribers)
+   * 3) Run each queued effect exactly once (Set-based dedupe)
    *
    * Notes:
    * - Batching is per state; effects that depend on multiple states
    *   may run once per state that changed (by design).
+   * - Plugin onNotify hooks run before subscribers (can observe before notification)
    */
   function scheduleFlush() {
     if (flushScheduled) return;
@@ -61,6 +108,17 @@ export function state(obj) {
     queueMicrotask(() => {
       flushScheduled = false;
       
+      // Plugin onNotify hooks (before subscribers)
+      for (const [key, value] of pendingNotifications) {
+        for (const p of plugins) {
+          try { 
+            p.onNotify?.(key, value); 
+          } catch (e) { 
+            console.error(`[Lume.js] Plugin "${p.name}" error in onNotify:`, e); 
+          }
+        }
+      }
+      
       // Notify all subscribers of changed keys
       // Snapshot listeners array to handle unsubscribes during iteration
       for (const [key, value] of pendingNotifications) {
@@ -87,7 +145,21 @@ export function state(obj) {
       if (typeof key === 'string' && key.startsWith('$')) {
         return target[key];
       }
-      // Support effect tracking
+      
+      // Get original value
+      let value = target[key];
+      
+      // Plugin onGet hooks run first (effects track key, not value)
+      for (const p of plugins) {
+        try {
+          const r = p.onGet?.(key, value);
+          if (r !== undefined) value = r;
+        } catch (e) {
+          console.error(`[Lume.js] Plugin "${p.name}" error in onGet:`, e);
+        }
+      }
+      
+      // Effect tracking
       // Check if we're inside an effect context
       if (typeof globalThis.__LUME_CURRENT_EFFECT__ !== 'undefined') {
         const currentEffect = globalThis.__LUME_CURRENT_EFFECT__;
@@ -121,17 +193,30 @@ export function state(obj) {
         }
       }
       
-      return target[key];
+      return value;
     },
     
     set(target, key, value) {
       const oldValue = target[key];
-      if (oldValue === value) return true;
+      let newValue = value;
       
-      target[key] = value;
+      // Plugin onSet hooks (chain pattern)
+      for (const p of plugins) {
+        try {
+          const r = p.onSet?.(key, newValue, oldValue);
+          if (r !== undefined) newValue = r;
+        } catch (e) {
+          console.error(`[Lume.js] Plugin "${p.name}" error in onSet:`, e);
+        }
+      }
+      
+      // Skip update if value unchanged after plugin processing
+      if (oldValue === newValue) return true;
+      
+      target[key] = newValue;
       
       // Batch notifications at the state level (per-state, not global)
-      pendingNotifications.set(key, value);
+      pendingNotifications.set(key, newValue);
       scheduleFlush();
       
       return true;
@@ -152,6 +237,15 @@ export function state(obj) {
       throw new Error('Subscriber must be a function');
     }
 
+    // Plugin onSubscribe hooks
+    for (const p of plugins) {
+      try { 
+        p.onSubscribe?.(key); 
+      } catch (e) { 
+        console.error(`[Lume.js] Plugin "${p.name}" error in onSubscribe:`, e); 
+      }
+    }
+
     if (!listeners[key]) listeners[key] = [];
     listeners[key].push(fn);