pulse-js-framework 1.8.0 → 1.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "sideEffects": false,

package/runtime/dom-event-delegate.js

@@ -145,22 +145,50 @@ export function delegatedList(getItems, template, keyFn, options = {}) {
   // Internal map: key -> { item, index }
   const itemMap = new Map();
 
+  // Track active keys per render cycle to clean stale itemMap entries
+  let activeKeys = new Set();
+
   // Wrap template to add data-pulse-key attribute
   const wrappedTemplate = (item, index) => {
-    const key = keyFn(item, index);
+    const rawKey = keyFn(item, index);
+    // Security: ensure key is a string or number to prevent collisions
+    // Objects would all stringify to "[object Object]"
+    const key = (typeof rawKey === 'string' || typeof rawKey === 'number')
+      ? String(rawKey)
+      : String(index);
     const node = template(item, index);
     const root = Array.isArray(node) ? node[0] : node;
 
     if (root && dom.isElement(root)) {
-      dom.setAttribute(root, KEY_ATTR, String(key));
+      dom.setAttribute(root, KEY_ATTR, key);
     }
 
-    itemMap.set(String(key), { item, index });
+    itemMap.set(key, { item, index });
+    activeKeys.add(key);
     return node;
   };
 
+  // Wrap getItems to track render cycles and prune stale entries
+  const wrappedGetItems = typeof getItems === 'function'
+    ? () => {
+        activeKeys = new Set();
+        const result = getItems();
+        // Schedule cleanup after current effect cycle completes
+        if (typeof queueMicrotask === 'function') {
+          queueMicrotask(() => {
+            for (const key of itemMap.keys()) {
+              if (!activeKeys.has(key)) {
+                itemMap.delete(key);
+              }
+            }
+          });
+        }
+        return result;
+      }
+    : getItems; // Pulse source — template calls track keys directly
+
   // Create list with wrapped template
-  const fragment = list(getItems, wrappedTemplate, keyFn, listOptions);
+  const fragment = list(wrappedGetItems, wrappedTemplate, keyFn, listOptions);
 
   // Set up delegation on the fragment's parent when it's mounted
   const cleanups = [];

package/runtime/dom-list.js

@@ -142,10 +142,60 @@ export function list(getItems, template, keyFn = (item, i) => i, options = {}) {
     });
 
     // Phase 2: Batch create new nodes using DocumentFragment
+    // When recycling is enabled, try to acquire root elements from the pool
+    // before falling back to createElement
     if (newItems.length > 0) {
       for (const { key, item, index } of newItems) {
         const result = template(item, index);
         const nodes = Array.isArray(result) ? result : [result];
+
+        // Pool acquire: if the root node is an element and pool has a matching
+        // tag, transfer children/attributes from template result to recycled element
+        if (pool && nodes.length === 1 && dom.isElement(nodes[0])) {
+          const original = nodes[0];
+          const tagName = (original.tagName || original.nodeName || '').toLowerCase();
+          if (tagName) {
+            const recycled = pool.acquire(tagName);
+            // Only use recycled element if it came from the pool (not freshly created)
+            // Pool.acquire creates new if empty, so always returns a valid element
+            if (recycled !== original) {
+              // Transfer attributes (skip event handler attributes for security)
+              if (original.attributes) {
+                const attrs = original.attributes;
+                for (let a = 0; a < attrs.length; a++) {
+                  const attrName = attrs[a].name;
+                  // Security: skip inline event handlers (onclick, onerror, etc.)
+                  if (attrName.length > 2 && attrName.charCodeAt(0) === 111 &&
+                      attrName.charCodeAt(1) === 110 && attrName.charCodeAt(2) > 96) {
+                    continue;
+                  }
+                  dom.setAttribute(recycled, attrName, attrs[a].value);
+                }
+              }
+              // Transfer children
+              let child = dom.getFirstChild(original);
+              while (child) {
+                const next = dom.getNextSibling(child);
+                dom.appendChild(recycled, child);
+                child = next;
+              }
+              // Transfer event listeners if tracked
+              if (original._eventListeners) {
+                recycled._eventListeners = original._eventListeners;
+              }
+              // Transfer inline styles
+              if (original.style && original.style.cssText) {
+                recycled.style.cssText = original.style.cssText;
+              }
+              // Transfer className
+              if (original.className) {
+                recycled.className = original.className;
+              }
+              nodes[0] = recycled;
+            }
+          }
+        }
+
         newItemNodes.set(key, { nodes, cleanup: null, item });
       }
     }

package/runtime/dom-virtual-list.js

@@ -12,6 +12,7 @@
 import { pulse, effect, computed, batch } from './pulse.js';
 import { getAdapter } from './dom-adapter.js';
 import { list } from './dom-list.js';
+import { delegate } from './dom-event-delegate.js';
 
 // ============================================================================
 // Constants
@@ -20,7 +21,8 @@ import { list } from './dom-list.js';
 const DEFAULT_OPTIONS = {
   overscan: 5,
   containerHeight: 400,
-  recycle: false
+  recycle: false,
+  on: null
 };
 
 // ============================================================================
@@ -38,7 +40,8 @@ const DEFAULT_OPTIONS = {
  * @param {number} [options.overscan=5] - Extra items above/below viewport
  * @param {number|string} [options.containerHeight=400] - Viewport height in px or 'auto'
  * @param {boolean} [options.recycle=false] - Enable element recycling for removed items
- * @returns {Element} Scroll container element
+ * @param {Object} [options.on] - Delegated event handlers: { eventType: (event, item, index) => void }
+ * @returns {Element} Scroll container element with scrollToIndex(index) and _dispose() methods
  *
  * @example
  * const vlist = virtualList(
@@ -51,7 +54,7 @@ const DEFAULT_OPTIONS = {
  */
 export function virtualList(getItems, template, keyFn, options = {}) {
   const config = { ...DEFAULT_OPTIONS, ...options };
-  const { itemHeight, overscan, containerHeight, recycle } = config;
+  const { itemHeight, overscan, containerHeight, recycle, on: eventHandlers } = config;
 
   if (!itemHeight || itemHeight <= 0) {
     throw new Error('[Pulse] virtualList requires a positive itemHeight');
@@ -66,6 +69,7 @@ export function virtualList(getItems, template, keyFn, options = {}) {
 
   // Outer container: fixed height, scrollable
   const container = dom.createElement('div');
+  container.scrollTop = 0; // Initialize for mock/SSR compatibility
   dom.setAttribute(container, 'role', 'list');
   dom.setAttribute(container, 'aria-label', 'Virtual scrolling list');
   setStyles(dom, container, {
@@ -107,10 +111,13 @@ export function virtualList(getItems, template, keyFn, options = {}) {
 
   // ---- Compute visible items slice ----
   const visibleSlice = pulse([]);
+  const currentStartIndex = pulse(0);
+  let allItems = [];
 
   effect(() => {
     const items = typeof getItems === 'function' ? getItems() : getItems.get();
-    const totalItems = Array.isArray(items) ? items.length : 0;
+    allItems = Array.isArray(items) ? items : [];
+    const totalItems = allItems.length;
     const top = scrollTop.get();
 
     // Update spacer height
@@ -121,20 +128,21 @@ export function virtualList(getItems, template, keyFn, options = {}) {
       ? containerHeight
       : (container.clientHeight || 400);
 
-    let startIndex = Math.floor(top / itemHeight) - overscan;
-    let endIndex = Math.ceil((top + height) / itemHeight) + overscan;
-    startIndex = Math.max(0, startIndex);
-    endIndex = Math.min(totalItems, endIndex);
+    let startIdx = Math.floor(top / itemHeight) - overscan;
+    let endIdx = Math.ceil((top + height) / itemHeight) + overscan;
+    startIdx = Math.max(0, startIdx);
+    endIdx = Math.min(totalItems, endIdx);
 
     // Position viewport at start offset
-    dom.setStyle(viewport, 'top', `${startIndex * itemHeight}px`);
+    dom.setStyle(viewport, 'top', `${startIdx * itemHeight}px`);
 
     // ARIA: announce total count
     dom.setAttribute(container, 'aria-rowcount', String(totalItems));
 
-    // Extract visible slice
-    const slice = Array.isArray(items) ? items.slice(startIndex, endIndex) : [];
-    visibleSlice.set(slice);
+    batch(() => {
+      currentStartIndex.set(startIdx);
+      visibleSlice.set(allItems.slice(startIdx, endIdx));
+    });
   });
 
   // ---- Render visible items using list() ----
@@ -143,14 +151,30 @@ export function virtualList(getItems, template, keyFn, options = {}) {
     listOptions.recycle = true;
   }
 
+  // Item map for event delegation
+  const itemMap = new Map();
+  const KEY_ATTR = 'data-pulse-key';
+
   const rendered = list(
     () => visibleSlice.get(),
     (item, relativeIndex) => {
-      const node = template(item, relativeIndex);
-      // Set ARIA rowindex for accessibility
+      const absIndex = currentStartIndex.peek() + relativeIndex;
+      const node = template(item, absIndex);
       const root = Array.isArray(node) ? node[0] : node;
       if (root && dom.isElement(root)) {
         dom.setAttribute(root, 'role', 'listitem');
+        // ARIA: set 1-based row index for screen readers
+        dom.setAttribute(root, 'aria-rowindex', String(absIndex + 1));
+        // Mark for event delegation
+        if (eventHandlers) {
+          const rawKey = keyFn(item, absIndex);
+          // Security: ensure key is a primitive to prevent collisions
+          const key = (typeof rawKey === 'string' || typeof rawKey === 'number')
+            ? String(rawKey)
+            : String(absIndex);
+          dom.setAttribute(root, KEY_ATTR, key);
+          itemMap.set(key, { item, index: absIndex });
+        }
       }
       return node;
     },
@@ -160,6 +184,65 @@ export function virtualList(getItems, template, keyFn, options = {}) {
 
   dom.appendChild(viewport, rendered);
 
+  // ---- Event delegation on viewport ----
+  const delegateCleanups = [];
+
+  if (eventHandlers && typeof eventHandlers === 'object') {
+    // Set up delegation after microtask (viewport needs to be in DOM)
+    const setupDelegation = () => {
+      for (const [eventType, handler] of Object.entries(eventHandlers)) {
+        const cleanup = delegate(viewport, eventType, `[${KEY_ATTR}]`, (event, matchedEl) => {
+          const key = dom.getAttribute(matchedEl, KEY_ATTR);
+          const entry = itemMap.get(key);
+          if (entry) {
+            handler(event, entry.item, entry.index);
+          }
+        });
+        delegateCleanups.push(cleanup);
+      }
+    };
+
+    if (typeof queueMicrotask === 'function') {
+      queueMicrotask(setupDelegation);
+    } else {
+      setupDelegation();
+    }
+  }
+
+  // ---- Programmatic scroll API ----
+
+  /**
+   * Scroll to bring a specific item index into view.
+   * @param {number} index - Zero-based item index
+   * @param {Object} [scrollOptions] - Options
+   * @param {'start'|'center'|'end'} [scrollOptions.align='start'] - Alignment in viewport
+   */
+  container.scrollToIndex = (index, scrollOptions = {}) => {
+    const { align = 'start' } = scrollOptions;
+    const totalItems = allItems.length;
+    const clampedIndex = Math.max(0, Math.min(index, totalItems - 1));
+
+    const height = typeof containerHeight === 'number'
+      ? containerHeight
+      : (container.clientHeight || 400);
+
+    let targetTop;
+    if (align === 'center') {
+      targetTop = clampedIndex * itemHeight - (height / 2) + (itemHeight / 2);
+    } else if (align === 'end') {
+      targetTop = (clampedIndex + 1) * itemHeight - height;
+    } else {
+      targetTop = clampedIndex * itemHeight;
+    }
+
+    targetTop = Math.max(0, targetTop);
+
+    if (container.scrollTop !== undefined) {
+      container.scrollTop = targetTop;
+    }
+    scrollTop.set(targetTop);
+  };
+
   // ---- Cleanup method ----
   container._dispose = () => {
     dom.removeEventListener(container, 'scroll', onScroll);
@@ -167,6 +250,9 @@ export function virtualList(getItems, template, keyFn, options = {}) {
       (typeof cancelAnimationFrame === 'function' ? cancelAnimationFrame : clearTimeout)(rafId);
       rafId = null;
     }
+    for (const cleanup of delegateCleanups) cleanup();
+    delegateCleanups.length = 0;
+    itemMap.clear();
   };
 
   return container;

package/runtime/pulse.js

@@ -526,7 +526,12 @@ export class Pulse {
    * unsub(); // Stop listening
    */
   subscribe(fn) {
-    const subscriber = { run: fn, dependencies: new Set() };
+    const self = this;
+    const subscriber = {
+      run() { fn(self.peek()); },
+      dependencies: new Set(),
+      _isSubscriber: true
+    };
     this.#subscribers.add(subscriber);
     return () => this.#subscribers.delete(subscriber);
   }