pulse-js-framework 1.7.5 → 1.7.6

package/runtime/dom-list.js

@@ -0,0 +1,267 @@
+/**
+ * Pulse DOM List Module
+ * Reactive list rendering with efficient keyed diffing using LIS algorithm
+ *
+ * @module dom-list
+ */
+
+import { effect } from './pulse.js';
+import { getAdapter } from './dom-adapter.js';
+
+// =============================================================================
+// LIS ALGORITHM
+// =============================================================================
+
+/**
+ * Compute Longest Increasing Subsequence indices
+ * Used to minimize DOM moves during list reconciliation
+ *
+ * @private
+ * @param {number[]} arr - Array of indices
+ * @returns {number[]} Indices of elements in the LIS
+ */
+export function computeLIS(arr) {
+  const n = arr.length;
+  if (n === 0) return [];
+
+  // dp[i] = smallest tail of LIS of length i+1
+  const dp = [];
+  // parent[i] = index of previous element in LIS ending at i
+  const parent = new Array(n).fill(-1);
+  // indices[i] = index in original array of dp[i]
+  const indices = [];
+
+  for (let i = 0; i < n; i++) {
+    const val = arr[i];
+
+    // Binary search for position
+    let lo = 0, hi = dp.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (dp[mid] < val) lo = mid + 1;
+      else hi = mid;
+    }
+
+    if (lo === dp.length) {
+      dp.push(val);
+      indices.push(i);
+    } else {
+      dp[lo] = val;
+      indices[lo] = i;
+    }
+
+    parent[i] = lo > 0 ? indices[lo - 1] : -1;
+  }
+
+  // Reconstruct LIS indices
+  const lis = [];
+  let idx = indices[dp.length - 1];
+  while (idx !== -1) {
+    lis.push(idx);
+    idx = parent[idx];
+  }
+
+  return lis.reverse();
+}
+
+// =============================================================================
+// LIST RENDERING
+// =============================================================================
+
+/**
+ * Create a reactive list with efficient keyed diffing
+ *
+ * LIST DIFFING ALGORITHM:
+ * -----------------------
+ * This uses a keyed reconciliation strategy to minimize DOM operations:
+ *
+ * 1. KEY EXTRACTION: Each item gets a unique key via keyFn (defaults to index)
+ *    Good keys: item.id, item.uuid (stable across re-renders)
+ *    Bad keys: array index (causes unnecessary re-renders on reorder)
+ *
+ * 2. RECONCILIATION PHASES:
+ *    a) Build a map of new items by key
+ *    b) For existing keys: reuse the DOM nodes (no re-creation)
+ *    c) For removed keys: remove DOM nodes and run cleanup
+ *    d) For new keys: batch create via DocumentFragment
+ *
+ * 3. REORDERING: Uses LIS (Longest Increasing Subsequence):
+ *    - Computes which nodes are already in correct relative order
+ *    - Only moves nodes NOT in the LIS (minimizes DOM operations)
+ *    - New items are batched into DocumentFragment before insertion
+ *
+ * 4. BOUNDARY MARKERS: Uses comment nodes to track list boundaries:
+ *    - startMarker: Insertion point for first item
+ *    - endMarker: End boundary (not currently used but reserved)
+ *
+ * COMPLEXITY: O(n log n) for LIS + O(m) DOM moves where m = n - LIS length
+ * Best case (append only): O(n) with single DocumentFragment insert
+ *
+ * @param {Function|Pulse} getItems - Items source (reactive)
+ * @param {Function} template - (item, index) => Node | Node[]
+ * @param {Function} keyFn - (item, index) => key (default: index)
+ * @returns {DocumentFragment} Container fragment with reactive list
+ */
+export function list(getItems, template, keyFn = (item, i) => i) {
+  const dom = getAdapter();
+  const container = dom.createDocumentFragment();
+  const startMarker = dom.createComment('list-start');
+  const endMarker = dom.createComment('list-end');
+
+  dom.appendChild(container, startMarker);
+  dom.appendChild(container, endMarker);
+
+  // Map: key -> { nodes: Node[], cleanup: Function, item: any }
+  let itemNodes = new Map();
+  let keyOrder = []; // Track order of keys for diffing
+
+  effect(() => {
+    const items = typeof getItems === 'function' ? getItems() : getItems.get();
+    const itemsArray = Array.isArray(items) ? items : Array.from(items);
+
+    const newKeys = [];
+    const newItemNodes = new Map();
+    const newItems = []; // Track new items for batched insertion
+
+    // Phase 1: Build map of new items by key
+    itemsArray.forEach((item, index) => {
+      const key = keyFn(item, index);
+      newKeys.push(key);
+
+      if (itemNodes.has(key)) {
+        // Reuse existing entry
+        newItemNodes.set(key, itemNodes.get(key));
+      } else {
+        // Mark as new (will batch create later)
+        newItems.push({ key, item, index });
+      }
+    });
+
+    // Phase 2: Batch create new nodes using DocumentFragment
+    if (newItems.length > 0) {
+      for (const { key, item, index } of newItems) {
+        const result = template(item, index);
+        const nodes = Array.isArray(result) ? result : [result];
+        newItemNodes.set(key, { nodes, cleanup: null, item });
+      }
+    }
+
+    // Phase 3: Remove items that are no longer present
+    for (const [key, entry] of itemNodes) {
+      if (!newItemNodes.has(key)) {
+        for (const node of entry.nodes) {
+          dom.removeNode(node);
+        }
+        if (entry.cleanup) entry.cleanup();
+      }
+    }
+
+    // Phase 4: Efficient reordering using LIS algorithm
+    // Build old position map for existing keys
+    const oldKeyIndex = new Map();
+    keyOrder.forEach((key, i) => oldKeyIndex.set(key, i));
+
+    // Get indices of existing items in old order
+    const existingIndices = [];
+    const existingKeys = [];
+    for (let i = 0; i < newKeys.length; i++) {
+      const key = newKeys[i];
+      if (oldKeyIndex.has(key)) {
+        existingIndices.push(oldKeyIndex.get(key));
+        existingKeys.push(key);
+      }
+    }
+
+    // Compute LIS - these nodes don't need to move
+    const lisIndices = new Set(computeLIS(existingIndices));
+    const stableKeys = new Set();
+    existingKeys.forEach((key, i) => {
+      if (lisIndices.has(i)) {
+        stableKeys.add(key);
+      }
+    });
+
+    // Phase 5: Position nodes with minimal DOM operations
+    const parent = dom.getParentNode(startMarker);
+    if (!parent) {
+      // Not yet in DOM, use simple append with DocumentFragment batch
+      const fragment = dom.createDocumentFragment();
+      for (const key of newKeys) {
+        const entry = newItemNodes.get(key);
+        for (const node of entry.nodes) {
+          dom.appendChild(fragment, node);
+        }
+      }
+      dom.insertBefore(container, fragment, endMarker);
+    } else {
+      // Optimized reordering: batch consecutive inserts using DocumentFragment
+      let prevNode = startMarker;
+
+      // Process items in new order
+      for (let i = 0; i < newKeys.length; i++) {
+        const key = newKeys[i];
+        const entry = newItemNodes.get(key);
+        const firstNode = entry.nodes[0];
+        const isNew = !oldKeyIndex.has(key);
+        const isStable = stableKeys.has(key);
+
+        // Check if node is already in correct position
+        const inPosition = dom.getNextSibling(prevNode) === firstNode;
+
+        if (inPosition && (isStable || isNew)) {
+          // Already in correct position, just advance
+          prevNode = entry.nodes[entry.nodes.length - 1];
+        } else {
+          // Collect consecutive items that need to be inserted at this position
+          const fragment = dom.createDocumentFragment();
+          let j = i;
+
+          while (j < newKeys.length) {
+            const k = newKeys[j];
+            const e = newItemNodes.get(k);
+            const f = e.nodes[0];
+            const n = !oldKeyIndex.has(k);
+            const s = stableKeys.has(k);
+
+            // If this item is already in position after prevNode, stop batching
+            if (j > i && dom.getNextSibling(prevNode) === f) {
+              break;
+            }
+
+            // Add to batch if it's new or needs to move
+            if (n || !s || dom.getNextSibling(prevNode) !== f) {
+              for (const node of e.nodes) {
+                dom.appendChild(fragment, node);
+              }
+              j++;
+            } else {
+              break;
+            }
+          }
+
+          // Insert the batch
+          if (dom.getFirstChild(fragment)) {
+            dom.insertBefore(parent, fragment, dom.getNextSibling(prevNode));
+          }
+
+          // Update prevNode to last inserted node
+          if (j > i) {
+            const lastEntry = newItemNodes.get(newKeys[j - 1]);
+            prevNode = lastEntry.nodes[lastEntry.nodes.length - 1];
+            i = j - 1; // Continue from where we left off
+          }
+        }
+      }
+    }
+
+    itemNodes = newItemNodes;
+    keyOrder = newKeys;
+  });
+
+  return container;
+}
+
+export default {
+  list,
+  computeLIS
+};

package/runtime/dom-selector.js

@@ -0,0 +1,267 @@
+/**
+ * Pulse DOM Selector Module
+ * CSS selector parsing with LRU caching
+ *
+ * @module dom-selector
+ */
+
+import { loggers } from './logger.js';
+import { LRUCache } from './lru-cache.js';
+import { getAdapter } from './dom-adapter.js';
+
+const log = loggers.dom;
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+/**
+ * @typedef {Object} DomConfig
+ * @property {number} [selectorCacheCapacity=500] - Max selectors to cache (0 = disabled)
+ * @property {boolean} [trackCacheMetrics=true] - Enable cache hit/miss tracking
+ */
+
+/** @type {DomConfig} */
+const config = {
+  selectorCacheCapacity: 500,
+  trackCacheMetrics: true
+};
+
+// =============================================================================
+// SELECTOR CACHE
+// =============================================================================
+// LRU (Least Recently Used) cache for parseSelector results.
+//
+// Why LRU instead of Map?
+// - Apps typically reuse the same selectors (e.g., 'div.container', 'button.primary')
+// - Without eviction, memory grows unbounded in long-running apps
+// - LRU keeps frequently-used selectors hot while evicting rare ones
+//
+// Default capacity: 500 selectors (configurable via configureDom())
+// - Most apps use 50-200 unique selectors
+// - 500 provides headroom for dynamic selectors without excessive memory
+//
+// Cache hit returns a shallow copy to prevent mutation of cached config
+// Metrics tracking enabled for performance monitoring
+let selectorCache = new LRUCache(config.selectorCacheCapacity, { trackMetrics: config.trackCacheMetrics });
+
+/**
+ * Configure DOM module settings.
+ *
+ * Call this before using any DOM functions if you need non-default settings.
+ * Changing configuration clears the selector cache.
+ *
+ * @param {Partial<DomConfig>} options - Configuration options
+ * @returns {DomConfig} Current configuration after applying changes
+ *
+ * @example
+ * // Increase cache for large apps
+ * configureDom({ selectorCacheCapacity: 1000 });
+ *
+ * @example
+ * // Disable caching for debugging
+ * configureDom({ selectorCacheCapacity: 0 });
+ *
+ * @example
+ * // Disable metrics tracking in production
+ * configureDom({ trackCacheMetrics: false });
+ */
+export function configureDom(options = {}) {
+  let cacheChanged = false;
+
+  if (options.selectorCacheCapacity !== undefined) {
+    config.selectorCacheCapacity = options.selectorCacheCapacity;
+    cacheChanged = true;
+  }
+
+  if (options.trackCacheMetrics !== undefined) {
+    config.trackCacheMetrics = options.trackCacheMetrics;
+    cacheChanged = true;
+  }
+
+  // Recreate cache if settings changed
+  if (cacheChanged) {
+    if (config.selectorCacheCapacity > 0) {
+      selectorCache = new LRUCache(config.selectorCacheCapacity, {
+        trackMetrics: config.trackCacheMetrics
+      });
+    } else {
+      // Disable caching with a null-like cache
+      selectorCache = {
+        get: () => undefined,
+        set: () => {},
+        clear: () => {},
+        getMetrics: () => ({ hits: 0, misses: 0, evictions: 0, hitRate: 0, size: 0, capacity: 0 }),
+        resetMetrics: () => {}
+      };
+    }
+  }
+
+  return { ...config };
+}
+
+/**
+ * Get current DOM configuration.
+ * @returns {DomConfig} Current configuration (copy)
+ */
+export function getDomConfig() {
+  return { ...config };
+}
+
+/**
+ * Clear the selector cache.
+ * Useful for memory management or after significant DOM structure changes.
+ */
+export function clearSelectorCache() {
+  selectorCache.clear();
+}
+
+/**
+ * Get selector cache performance metrics.
+ * Useful for debugging and performance tuning.
+ *
+ * @returns {{hits: number, misses: number, evictions: number, hitRate: number, size: number, capacity: number}}
+ * @example
+ * const stats = getCacheMetrics();
+ * console.log(`Cache hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+ * console.log(`Cache size: ${stats.size}/${stats.capacity}`);
+ */
+export function getCacheMetrics() {
+  return selectorCache.getMetrics();
+}
+
+/**
+ * Reset cache metrics counters.
+ * Useful for measuring performance over specific time periods.
+ */
+export function resetCacheMetrics() {
+  selectorCache.resetMetrics();
+}
+
+/**
+ * Resolve a selector string or element to a DOM element
+ * @param {string|HTMLElement} target - CSS selector or DOM element
+ * @param {string} context - Context name for error messages
+ * @returns {{element: HTMLElement|null, selector: string}} Resolved element and original selector
+ */
+export function resolveSelector(target, context = 'target') {
+  if (typeof target === 'string') {
+    const dom = getAdapter();
+    const element = dom.querySelector(target);
+    return { element, selector: target };
+  }
+  return { element: target, selector: '(element)' };
+}
+
+/**
+ * Parse a CSS selector-like string into element configuration
+ * Results are cached for performance using LRU cache.
+ *
+ * Supported syntax:
+ * - Tag: `div`, `span`, `custom-element`
+ * - ID: `#app`, `#my-id`, `#_private`
+ * - Classes: `.class`, `.my-class`, `.-modifier`
+ * - Attributes: `[attr]`, `[attr=value]`, `[attr="quoted value"]`, `[attr='single quoted']`
+ *
+ * Examples:
+ *   "div" -> { tag: "div" }
+ *   "#app" -> { tag: "div", id: "app" }
+ *   ".container" -> { tag: "div", classes: ["container"] }
+ *   "button.primary.large" -> { tag: "button", classes: ["primary", "large"] }
+ *   "input[type=text][placeholder=Name]" -> { tag: "input", attrs: { type: "text", placeholder: "Name" } }
+ *   "div[data-id=\"complex-123\"]" -> { tag: "div", attrs: { "data-id": "complex-123" } }
+ *
+ * @param {string} selector - CSS selector-like string
+ * @returns {{tag: string, id: string|null, classes: string[], attrs: Object}} Parsed configuration
+ */
+export function parseSelector(selector) {
+  if (!selector || selector === '') {
+    return { tag: 'div', id: null, classes: [], attrs: {} };
+  }
+
+  // Check cache first
+  const cached = selectorCache.get(selector);
+  if (cached) {
+    // Return a shallow copy to prevent mutation
+    return {
+      tag: cached.tag,
+      id: cached.id,
+      classes: [...cached.classes],
+      attrs: { ...cached.attrs }
+    };
+  }
+
+  const config = {
+    tag: 'div',
+    id: null,
+    classes: [],
+    attrs: {}
+  };
+
+  let remaining = selector;
+
+  // Match tag name at the start
+  const tagMatch = remaining.match(/^([a-zA-Z][a-zA-Z0-9-]*)/);
+  if (tagMatch) {
+    config.tag = tagMatch[1];
+    remaining = remaining.slice(tagMatch[0].length);
+  }
+
+  // Match ID (supports starting with letter, underscore, or hyphen followed by valid chars)
+  const idMatch = remaining.match(/#([a-zA-Z_-][a-zA-Z0-9-_]*)/);
+  if (idMatch) {
+    config.id = idMatch[1];
+    remaining = remaining.replace(idMatch[0], '');
+  }
+
+  // Match classes (supports starting with letter, underscore, or hyphen)
+  const classMatches = remaining.matchAll(/\.([a-zA-Z_-][a-zA-Z0-9-_]*)/g);
+  for (const match of classMatches) {
+    config.classes.push(match[1]);
+  }
+
+  // Match attributes - improved regex handles quoted values with special characters
+  // Matches: [attr], [attr=value], [attr="quoted value"], [attr='quoted value']
+  const attrRegex = /\[([a-zA-Z_][a-zA-Z0-9-_]*)(?:=(?:"([^"]*)"|'([^']*)'|([^\]]*)))?\]/g;
+  const attrMatches = remaining.matchAll(attrRegex);
+  for (const match of attrMatches) {
+    const key = match[1];
+    // Value can be in match[2] (double-quoted), match[3] (single-quoted), or match[4] (unquoted)
+    const value = match[2] ?? match[3] ?? match[4] ?? '';
+    config.attrs[key] = value;
+  }
+
+  // Validate: check for unparsed content (malformed selector parts)
+  // Remove all parsed parts to see if anything remains
+  let unparsed = remaining
+    .replace(/#[a-zA-Z_-][a-zA-Z0-9-_]*/g, '')  // Remove IDs
+    .replace(/\.[a-zA-Z_-][a-zA-Z0-9-_]*/g, '') // Remove classes
+    .replace(/\[([a-zA-Z_][a-zA-Z0-9-_]*)(?:=(?:"[^"]*"|'[^']*'|[^\]]*))?\]/g, '') // Remove attrs
+    .trim();
+
+  if (unparsed) {
+    log.warn(`Selector "${selector}" contains unrecognized parts: "${unparsed}". ` +
+      'Supported syntax: tag#id.class[attr=value]');
+  }
+
+  // Cache the result (LRU cache handles eviction automatically)
+  selectorCache.set(selector, config);
+
+  // Return a copy
+  return {
+    tag: config.tag,
+    id: config.id,
+    classes: [...config.classes],
+    attrs: { ...config.attrs }
+  };
+}
+
+export default {
+  parseSelector,
+  resolveSelector,
+  configureDom,
+  getDomConfig,
+  clearSelectorCache,
+  getCacheMetrics,
+  resetCacheMetrics
+};