lume-js 2.2.1 → 2.3.1

package/src/addons/repeat.js

@@ -22,6 +22,38 @@
  * store.items = [...items] // ✅ Triggers update
  * 
  * ═══════════════════════════════════════════════════════════════════════
+ * PATTERN 0: Template-based (recommended) — declarative, zero DOM code
+ * ═══════════════════════════════════════════════════════════════════════
+ *
+ *   HTML — a standard <template> element, valid HTML, no custom syntax:
+ *
+ *   <ul id="list">
+ *     <template>
+ *       <li>
+ *         <strong data-bind="name"></strong>
+ *         <span data-bind="role"></span>
+ *         <em data-bind="$index"></em>
+ *       </li>
+ *     </template>
+ *   </ul>
+ *
+ *   JS:
+ *
+ *   repeat('#list', store, 'people', {
+ *     key: p => p.id,
+ *     template: true   // use the <template> inside the container
+ *   });
+ *
+ *   data-bind paths resolve against EACH ITEM: "name" → item.name,
+ *   "user.city" → item.user.city, "$item" → the item itself (primitive
+ *   arrays), "$index" → current index. Inputs get .value/.checked, other
+ *   elements get textContent — identical semantics to bindDom's data-bind.
+ *   These are one-way snapshot bindings re-applied per list update (items
+ *   are plain objects, not stores). Combine with create/update for event
+ *   listeners or extra binding. template also accepts a CSS selector or an
+ *   HTMLTemplateElement.
+ *
+ * ═══════════════════════════════════════════════════════════════════════
  * PATTERN 1: Simple (render only) - for simple cases or backward compat
  * ═══════════════════════════════════════════════════════════════════════
  * 
@@ -79,6 +111,79 @@
  *   });
  */
 import { logWarn, logError } from '../utils/log.js';
+import { applyBindValue } from '../core/bindDom.js';
+
+/**
+ * Resolve the template option to the <template> element.
+ * Accepts true (first <template> inside the container), a CSS selector,
+ * or an HTMLTemplateElement directly.
+ */
+function resolveTemplateEl(template, containerEl) {
+  let templateEl = template;
+  if (template === true) {
+    templateEl = containerEl.querySelector('template');
+  } else if (typeof template === 'string') {
+    templateEl = document.querySelector(template);
+  }
+  if (!templateEl || templateEl.tagName !== 'TEMPLATE') {
+    throw new Error('[Lume.js] repeat(): template not found or not a <template> element');
+  }
+  if (templateEl.content.children.length !== 1) {
+    throw new Error('[Lume.js] repeat(): template must contain exactly one root element');
+  }
+  return templateEl;
+}
+
+/**
+ * Resolve the template option to its clone root, plus the container child
+ * that is (or contains) the source <template>. Reconciliation and cleanup
+ * must leave that child alone — it's the user's markup, and removing it
+ * would break re-binding with `template: true` after cleanup. keepEl is
+ * null when there is no template or it lives outside the container.
+ */
+function resolveTemplate(template, containerEl) {
+  if (!template) return { templateRoot: null, keepEl: null };
+  const templateEl = resolveTemplateEl(template, containerEl);
+  let keepEl = templateEl;
+  while (keepEl && keepEl.parentNode !== containerEl) keepEl = keepEl.parentNode;
+  return { templateRoot: templateEl.content.firstElementChild, keepEl };
+}
+
+/**
+ * Collect [data-bind] nodes of a cloned item element into a compiled
+ * binding list. Paths are resolved against the ITEM (not the store):
+ *   data-bind="name"      → item.name
+ *   data-bind="user.city" → item.user.city
+ *   data-bind="$item"     → the item itself (for primitive arrays)
+ *   data-bind="$index"    → the item's current index
+ */
+function collectItemBindings(el) {
+  const bindings = [];
+  const add = (node) => {
+    const path = node.getAttribute('data-bind');
+    bindings.push({ node, path, keys: path === '$item' || path === '$index' ? null : path.split('.') });
+  };
+  if (el.hasAttribute('data-bind')) add(el);
+  for (const node of el.querySelectorAll('[data-bind]')) add(node);
+  return bindings;
+}
+
+function applyItemBindings(bindings, item, index) {
+  for (const b of bindings) {
+    let val;
+    if (b.path === '$index') {
+      val = index;
+    } else if (b.path === '$item') {
+      val = item;
+    } else {
+      val = item;
+      for (let i = 0; i < b.keys.length && val != null; i++) {
+        val = val[b.keys[i]];
+      }
+    }
+    applyBindValue(b.node, val);
+  }
+}
 
 /**
  * Default focus preservation strategy
@@ -173,7 +278,8 @@ export function defaultScrollPreservation(container, context = {}) {
  * @param {Function} [options.create] - Function for new elements only: (item, element, index) => void | Function. If a function is returned, it is registered as the element's cleanup and called automatically when the element is removed (by list update or full cleanup).
  * @param {Function} [options.update] - Function for data binding: (item, element, index, { isFirstRender }) => void. Skipped if same item reference AND same index.
  * @param {Function} [options.remove] - Additional cleanup when element is removed: (item, element) => void. Called after any cleanup function returned by create(). Optional — prefer returning a cleanup from create() for automatic lifecycle management.
- * @param {string|Function} [options.element='div'] - Element tag name or factory function
+ * @param {true|string|HTMLTemplateElement} [options.template] - Declarative item structure from a <template> element: true = first <template> inside the container, string = CSS selector, or the element itself. The template must have exactly one root element; it is cloned per item and its [data-bind] paths are bound to the item on every update ("name", "user.city", "$item", "$index"). When set, options.element is ignored and options.render is ignored (with a warning); create/update remain available on top.
+ * @param {string|Function} [options.element='div'] - Element tag name or factory function (ignored when options.template is set)
  * @param {Function|null} [options.preserveFocus=defaultFocusPreservation] - Focus preservation strategy (null to disable)
  * @param {Function|null} [options.preserveScroll=defaultScrollPreservation] - Scroll preservation strategy (null to disable)
  * @returns {Function} Cleanup function
@@ -186,6 +292,7 @@ export function repeat(container, store, arrayKey, options) {
     create,
     update,
     remove,
+    template = null,
     element = 'div',
     preserveFocus = defaultFocusPreservation,
     preserveScroll = defaultScrollPreservation
@@ -206,7 +313,15 @@ export function repeat(container, store, arrayKey, options) {
     throw new Error('[Lume.js] repeat(): options.key must be a function');
   }
 
-  if (typeof render !== 'function' && typeof create !== 'function') {
+  // Template mode: structure and data binding come from the <template>;
+  // render/create/update are all optional on top of it.
+  const { templateRoot, keepEl } = resolveTemplate(template, containerEl);
+
+  if (templateRoot && typeof render === 'function') {
+    logWarn('[Lume.js] repeat(): options.render is ignored when options.template is set — use create/update instead');
+  }
+
+  if (!templateRoot && typeof render !== 'function' && typeof create !== 'function') {
     throw new Error('[Lume.js] repeat(): options.render or options.create must be a function');
   }
 
@@ -218,18 +333,40 @@ export function repeat(container, store, arrayKey, options) {
   const prevIndexByKey = new Map();
   // key -> cleanup function returned by create()
   const cleanupByKey = new Map();
+  // key -> compiled [data-bind] nodes of the clone (template mode only)
+  const bindingsByKey = new Map();
   const seenKeys = new Set();
 
   function createElement() {
+    if (templateRoot) return templateRoot.cloneNode(true);
     return typeof element === 'function'
       ? element()
       : document.createElement(element);
   }
 
+  /**
+   * Empty the container, preserving the in-container source template.
+   * Manual removal (not replaceChildren) for two reasons: replaceChildren
+   * is Chrome 86+/Safari 14+ — above the documented ES2020-era browser
+   * floor — and re-inserting keepEl would re-parent a template the user
+   * has since moved (or resurrect one they deleted).
+   */
+  function clearContainer() {
+    let node = containerEl.firstChild;
+    while (node) {
+      const next = node.nextSibling;
+      if (node !== keepEl) containerEl.removeChild(node);
+      node = next;
+    }
+  }
+
   function reconcileDOM(container, nextEls) {
     let ptr = container.firstChild;
 
     for (let i = 0; i < nextEls.length; i++) {
+      // Never treat the source template (or its wrapper) as a list row
+      if (keepEl && ptr === keepEl) ptr = ptr.nextSibling;
+
       const desired = nextEls[i];
 
       if (ptr === desired) {
@@ -240,10 +377,10 @@ export function repeat(container, store, arrayKey, options) {
       container.insertBefore(desired, ptr);
     }
 
-    // Remove leftover children not in nextEls
+    // Remove leftover children not in nextEls (preserving the template)
     while (ptr) {
       const next = ptr.nextSibling;
-      container.removeChild(ptr);
+      if (ptr !== keepEl) container.removeChild(ptr);
       ptr = next;
     }
   }
@@ -298,10 +435,13 @@ export function repeat(container, store, arrayKey, options) {
       if (isFirstRender) {
         el = createElement();
         elementsByKey.set(k, el);
+        if (templateRoot) {
+          bindingsByKey.set(k, collectItemBindings(el));
+        }
       }
 
       try {
-        // Call create for new elements (DOM structure)
+        // Call create for new elements (DOM structure / event listeners)
         if (isFirstRender && create) {
           const cleanup = create(item, el, i);
           if (typeof cleanup === 'function') {
@@ -309,11 +449,17 @@ export function repeat(container, store, arrayKey, options) {
           }
         }
 
-        // Call update for data binding (new and existing elements)
+        // 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 (templateRoot) {
+          if (prevItem !== item || prevIndex !== i) {
+            applyItemBindings(bindingsByKey.get(k), item, i);
+            // update is optional extra binding on top of the template
+            if (update) update(item, el, i, { isFirstRender });
+          }
+        } else if (update) {
           if (prevItem !== item || prevIndex !== i) {
             update(item, el, i, { isFirstRender });
           }
@@ -359,6 +505,7 @@ export function repeat(container, store, arrayKey, options) {
             prevItemsByKey.delete(k);
             prevIndexByKey.delete(k);
             cleanupByKey.delete(k);
+            bindingsByKey.delete(k);
           }
         }
       }
@@ -397,11 +544,12 @@ export function repeat(container, store, arrayKey, options) {
           remove(prevItem, el);
         }
       }
-      containerEl.replaceChildren();
+      clearContainer();
       elementsByKey.clear();
       prevItemsByKey.clear();
       prevIndexByKey.clear();
       cleanupByKey.clear();
+      bindingsByKey.clear();
       seenKeys.clear();
     };
   }
@@ -425,12 +573,13 @@ export function repeat(container, store, arrayKey, options) {
         remove(prevItem, el);
       }
     }
-    // Clear DOM elements (replaceChildren is faster than loop)
-    containerEl.replaceChildren();
+    // Clear DOM elements (preserving the source template, if any)
+    clearContainer();
     elementsByKey.clear();
     prevItemsByKey.clear();
     prevIndexByKey.clear();
     cleanupByKey.clear();
+    bindingsByKey.clear();
     seenKeys.clear();
   };
 }

package/src/core/batch.js

@@ -0,0 +1,139 @@
+/**
+ * Lume-JS Cross-Store Batching
+ *
+ * While batchDepth > 0, states skip their microtask flush and enqueue a
+ * small flush handle here instead (via enqueueIfBatching, called from
+ * state.js's scheduler); batch() drains the set synchronously when the
+ * outermost batch ends. Effects collected from all enqueued states run
+ * from one Set per wave, so an effect depending on several mutated stores
+ * runs exactly once per batch instead of once per store.
+ *
+ * This module never imports state.js — state.js imports from here — so
+ * there is no cycle, no global scheduler object, and no import side effect.
+ */
+
+import { logError, logWarn } from '../utils/log.js';
+
+// Cap for cascading flush waves (effects mutating state that re-triggers
+// effects). Shared with the per-state microtask flush in state.js.
+export const MAX_FLUSH_ITERATIONS = 100;
+
+let batchDepth = 0;
+const batchedStates = new Set();
+
+/**
+ * Called by state.js when a write is scheduled. Returns true if a batch is
+ * active and the state's flush handle was captured (the caller must then
+ * skip its own microtask scheduling).
+ *
+ * Internal API between core modules — not exported from the package root.
+ *
+ * @param {{runBeforeFlushHooks: function, notifySubscribers: function, takeEffects: function}} handle
+ * @returns {boolean}
+ */
+export function enqueueIfBatching(handle) {
+  if (batchDepth === 0) return false;
+  batchedStates.add(handle);
+  return true;
+}
+
+function flushBatchedStates() {
+  let iterations = 0;
+  while (batchedStates.size > 0 && iterations < MAX_FLUSH_ITERATIONS) {
+    iterations++;
+    const wave = Array.from(batchedStates);
+    batchedStates.clear();
+
+    // Notify each state's subscribers, collecting effects into one
+    // deduplicated set (the same effect queued by N stores runs once).
+    const effects = new Set();
+    for (const s of wave) {
+      s.runBeforeFlushHooks();
+      s.notifySubscribers();
+      for (const fx of s.takeEffects()) effects.add(fx);
+    }
+
+    // Effects run after all subscribers of the wave. Writes they make
+    // re-enter batchedStates (depth is still held) → next iteration.
+    for (const fx of effects) {
+      try { fx(); }
+      catch (err) { logError('[Lume.js state] Error in effect:', err); }
+    }
+  }
+  if (iterations >= MAX_FLUSH_ITERATIONS) {
+    // Drop the runaway wave so a future, unrelated batch doesn't inherit
+    // it. Nothing is lost permanently: the states keep their queued work
+    // and flush it on their next write via the normal microtask path.
+    batchedStates.clear();
+    logError(
+      '[Lume.js state] Maximum batch flush iterations reached (100). ' +
+      'This usually indicates an infinite loop caused by an effect or computed mutating state it depends on.'
+    );
+  }
+}
+
+/**
+ * Group multiple state writes and flush them together, synchronously,
+ * when the outermost batch() returns.
+ *
+ * Guarantees:
+ * - Subscribers see only the final value of each key (intermediate writes
+ *   within the batch are coalesced, as with microtask batching).
+ * - An effect that depends on several stores mutated in the batch runs
+ *   exactly ONCE — unlike microtask batching, which is per-state and runs
+ *   such effects once per store.
+ * - Nested batch() calls are absorbed: everything flushes when the
+ *   outermost batch ends.
+ * - If fn throws, writes made before the throw still flush, then the
+ *   error propagates. State scheduling is left clean either way.
+ *
+ * `fn` must be synchronous — writes after an `await` happen outside the
+ * batch and fall back to normal per-state microtask flushing (a console
+ * warning is logged if fn returns a Promise).
+ *
+ * @param {function} fn - Function performing state writes
+ * @returns {*} The return value of fn
+ *
+ * @example
+ * import { state, effect, batch } from 'lume-js';
+ *
+ * const a = state({ value: 1 });
+ * const b = state({ value: 2 });
+ * effect(() => render(a.value + b.value));
+ *
+ * batch(() => {
+ *   a.value = 10;
+ *   b.value = 20;
+ * }); // render() ran exactly once, seeing 30
+ */
+export function batch(fn) {
+  if (typeof fn !== 'function') {
+    throw new Error('batch() requires a function');
+  }
+
+  // Nested batch: let the outermost batch flush everything
+  if (batchDepth > 0) return fn();
+
+  batchDepth++;
+  let result;
+  try {
+    result = fn();
+    if (result && typeof result.then === 'function') {
+      logWarn(
+        '[Lume.js batch] batch() received an async function. Only writes before the first await are batched; ' +
+        'later writes flush via normal microtasks.'
+      );
+    }
+    return result;
+  } finally {
+    // Flush while depth is still held so cascading writes from
+    // subscribers/effects keep collecting into batchedStates (deduped),
+    // then release. Runs on success AND when fn throws (writes made
+    // before the throw are committed, then the error propagates).
+    try {
+      flushBatchedStates();
+    } finally {
+      batchDepth--;
+    }
+  }
+}

package/src/core/bindDom.js

@@ -146,7 +146,7 @@ function handleDataBind(el, store, path, bindingMap) {
   if (!result) return null;
 
   const { target, key } = result;
-  const unsub = target.$subscribe(key, val => updateElement(el, val));
+  const unsub = target.$subscribe(key, val => applyBindValue(el, val));
 
   if (isFormInput(el)) {
     bindingMap.set(el, { target, key });
@@ -205,9 +205,13 @@ function resolveProp(store, path) {
 }
 
 /**
- * Update element with value (for data-bind)
+ * Update element with value (for data-bind).
+ *
+ * Exported for internal reuse (e.g. the repeat addon's template bindings)
+ * so addon and core data-bind semantics never drift. Not part of the
+ * public package API.
  */
-function updateElement(el, val) {
+export function applyBindValue(el, val) {
   if (el.tagName === "INPUT") {
     if (el.type === "checkbox") el.checked = Boolean(val);
     else if (el.type === "radio") el.checked = el.value === String(val);

package/src/core/effect.js

@@ -29,6 +29,8 @@ import { logError } from '../utils/log.js';
  * Features:
  * - Automatic dependency collection via withReadObserver scope (default)
  * - Explicit dependencies for side-effects
+ * - Explicit-deps notifications are coalesced: one run per microtask,
+ *   no matter how many tracked keys (or stores) changed in the same tick
  * - Returns cleanup function
  * - Compatible with per-state batching
  */
@@ -87,6 +89,27 @@ export function effect(fn, deps) {
 
   // EXPLICIT DEPS MODE: deps array provided
   if (Array.isArray(deps)) {
+    // Coalesce notifications: when several tracked keys change in the same
+    // flush (or several stores flush in the same tick), run the effect once
+    // per microtask instead of once per changed key. This matches the
+    // dedupe guarantee auto-tracking mode gets from the per-state effect queue.
+    let scheduled = false;
+    let disposed = false;
+    cleanups.push(() => { disposed = true; });
+
+    const scheduleExecute = () => {
+      if (scheduled) return;
+      scheduled = true;
+      queueMicrotask(() => {
+        scheduled = false;
+        if (disposed) return;
+        // execute() logs and re-throws; swallow here so a throwing effect
+        // doesn't become an uncaught error inside the microtask (same
+        // containment the state flush loop provides for subscribers).
+        try { execute(); } catch { /* already logged by execute() */ }
+      });
+    };
+
     // Subscribe to each [store, key1, key2, ...] tuple explicitly
     for (const dep of deps) {
       if (Array.isArray(dep) && dep.length >= 2) {
@@ -102,7 +125,7 @@ export function effect(fn, deps) {
                 isFirst = false;
                 return; // Skip first call, we'll run execute() below
               }
-              execute();
+              scheduleExecute();
             });
             cleanups.push(unsub);
           }
@@ -123,12 +146,13 @@ export function effect(fn, deps) {
       // them so the effect stays reactive.
       const oldCleanups = cleanups.splice(0);
 
-      // Create effect context for tracking
+      // Tracking is keyed per store proxy (WeakMap<proxy, Set<key>>) so the
+      // same key name on two different stores creates two subscriptions.
       const myContext = {
         fn,
         cleanups,
         execute: executeWithTracking,
-        tracking: {}
+        tracking: new WeakMap()
       };
 
       // Set as current effect (for state.js to detect)
@@ -141,8 +165,13 @@ export function effect(fn, deps) {
         const onRead = (proxy, key, registerEffect) => {
           // Only the currently active effect (not a nested one) creates subscriptions
           if (currentEffect !== myContext) return;
-          if (myContext.tracking[key]) return;
-          myContext.tracking[key] = true;
+          let keys = myContext.tracking.get(proxy);
+          if (!keys) {
+            keys = new Set();
+            myContext.tracking.set(proxy, keys);
+          }
+          if (keys.has(key)) return;
+          keys.add(key);
           myContext.cleanups.push(registerEffect(key, myContext.execute));
         };
         withReadObserver(onRead, fn);