pulse-js-framework 1.7.5 → 1.7.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.7.5",
+  "version": "1.7.8",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -56,8 +56,14 @@
     "./runtime/lru-cache": "./runtime/lru-cache.js",
     "./runtime/utils": "./runtime/utils.js",
     "./runtime/dom-adapter": "./runtime/dom-adapter.js",
-    "./runtime/async": "./runtime/async.js",
-    "./runtime/form": "./runtime/form.js",
+    "./runtime/async": {
+      "types": "./types/async.d.ts",
+      "default": "./runtime/async.js"
+    },
+    "./runtime/form": {
+      "types": "./types/form.d.ts",
+      "default": "./runtime/form.js"
+    },
     "./runtime/devtools": "./runtime/devtools.js",
     "./compiler": {
       "types": "./types/index.d.ts",
@@ -87,7 +93,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run test:compiler && npm run test:sourcemap && npm run test:pulse && npm run test:dom && npm run test:dom-adapter && npm run test:router && npm run test:store && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze && npm run test:lru-cache && npm run test:utils && npm run test:docs && npm run test:async && npm run test:form && npm run test:devtools",
+    "test": "npm run test:compiler && npm run test:sourcemap && npm run test:pulse && npm run test:dom && npm run test:dom-adapter && npm run test:router && npm run test:store && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze && npm run test:lru-cache && npm run test:utils && npm run test:docs && npm run test:async && npm run test:form && npm run test:devtools && npm run test:native",
     "test:compiler": "node test/compiler.test.js",
     "test:sourcemap": "node test/sourcemap.test.js",
     "test:pulse": "node test/pulse.test.js",
@@ -105,6 +111,7 @@
     "test:async": "node test/async.test.js",
     "test:form": "node test/form.test.js",
     "test:devtools": "node test/devtools.test.js",
+    "test:native": "node test/native.test.js",
     "build:netlify": "node scripts/build-netlify.js",
     "version": "node scripts/sync-version.js",
     "docs": "node cli/index.js dev docs"

package/runtime/dom-advanced.js

@@ -0,0 +1,357 @@
+/**
+ * Pulse DOM Advanced Module
+ * Advanced features: portal, error boundary, transitions
+ *
+ * @module dom-advanced
+ */
+
+import { effect, pulse, onCleanup } from './pulse.js';
+import { loggers } from './logger.js';
+import { getAdapter } from './dom-adapter.js';
+import { resolveSelector } from './dom-selector.js';
+
+const log = loggers.dom;
+
+// =============================================================================
+// PORTAL
+// =============================================================================
+
+/**
+ * Portal - render children into a different DOM location
+ *
+ * @param {*|Function} children - Children to render (static or reactive)
+ * @param {string|HTMLElement} target - Target selector or element
+ * @returns {Comment} Marker node for position tracking
+ */
+export function portal(children, target) {
+  const dom = getAdapter();
+  const { element: resolvedTarget, selector } = resolveSelector(target, 'portal');
+
+  if (!resolvedTarget) {
+    log.warn(`Portal target not found: "${selector}"`);
+    return dom.createComment('portal-target-not-found');
+  }
+
+  const marker = dom.createComment('portal');
+  let mountedNodes = [];
+
+  // Handle reactive children
+  if (typeof children === 'function') {
+    effect(() => {
+      // Cleanup previous nodes
+      for (const node of mountedNodes) {
+        dom.removeNode(node);
+        if (node._pulseUnmount) {
+          for (const cb of node._pulseUnmount) cb();
+        }
+      }
+      mountedNodes = [];
+
+      const result = children();
+      if (result) {
+        const nodes = Array.isArray(result) ? result : [result];
+        for (const node of nodes) {
+          if (dom.isNode(node)) {
+            dom.appendChild(resolvedTarget, node);
+            mountedNodes.push(node);
+          }
+        }
+      }
+    });
+  } else {
+    // Static children
+    const nodes = Array.isArray(children) ? children : [children];
+    for (const node of nodes) {
+      if (dom.isNode(node)) {
+        dom.appendChild(resolvedTarget, node);
+        mountedNodes.push(node);
+      }
+    }
+  }
+
+  // Return marker for position tracking, attach cleanup
+  marker._pulseUnmount = [() => {
+    for (const node of mountedNodes) {
+      dom.removeNode(node);
+      if (node._pulseUnmount) {
+        for (const cb of node._pulseUnmount) cb();
+      }
+    }
+  }];
+
+  return marker;
+}
+
+// =============================================================================
+// ERROR BOUNDARY
+// =============================================================================
+
+/**
+ * Error boundary - catch errors in child components
+ *
+ * @param {*|Function} children - Children to render (static or reactive)
+ * @param {*|Function} fallback - Fallback to render on error (receives error)
+ * @returns {DocumentFragment} Container with error-protected content
+ */
+export function errorBoundary(children, fallback) {
+  const dom = getAdapter();
+  const container = dom.createDocumentFragment();
+  const marker = dom.createComment('error-boundary');
+  dom.appendChild(container, marker);
+
+  const error = pulse(null);
+  let currentNodes = [];
+
+  const renderContent = () => {
+    // Cleanup previous
+    for (const node of currentNodes) {
+      dom.removeNode(node);
+    }
+    currentNodes = [];
+
+    const hasError = error.peek();
+
+    try {
+      let result;
+      if (hasError && fallback) {
+        result = typeof fallback === 'function' ? fallback(hasError) : fallback;
+      } else {
+        result = typeof children === 'function' ? children() : children;
+      }
+
+      if (result) {
+        const nodes = Array.isArray(result) ? result : [result];
+        const fragment = dom.createDocumentFragment();
+        for (const node of nodes) {
+          if (dom.isNode(node)) {
+            dom.appendChild(fragment, node);
+            currentNodes.push(node);
+          }
+        }
+        const markerParent = dom.getParentNode(marker);
+        if (markerParent) {
+          dom.insertBefore(markerParent, fragment, dom.getNextSibling(marker));
+        }
+      }
+    } catch (e) {
+      log.error('Error in component:', e);
+      error.set(e);
+      // Re-render with error
+      if (!hasError) {
+        dom.queueMicrotask(renderContent);
+      }
+    }
+  };
+
+  effect(renderContent);
+
+  // Expose reset method on marker
+  marker.resetError = () => error.set(null);
+
+  return container;
+}
+
+// =============================================================================
+// TRANSITIONS
+// =============================================================================
+
+/**
+ * Transition helper - animate element enter/exit
+ *
+ * MEMORY SAFETY: All timers are tracked and cleared on cleanup
+ * to prevent callbacks executing on removed elements.
+ *
+ * @param {HTMLElement} element - Element to animate
+ * @param {Object} options - Transition options
+ * @param {string} [options.enter='fade-in'] - Enter animation class
+ * @param {string} [options.exit='fade-out'] - Exit animation class
+ * @param {number} [options.duration=300] - Animation duration in ms
+ * @param {Function} [options.onEnter] - Callback on enter start
+ * @param {Function} [options.onExit] - Callback on exit start
+ * @returns {HTMLElement} The element with transition attached
+ */
+export function transition(element, options = {}) {
+  const dom = getAdapter();
+  const {
+    enter = 'fade-in',
+    exit = 'fade-out',
+    duration = 300,
+    onEnter,
+    onExit
+  } = options;
+
+  // Track active timers for cleanup
+  const activeTimers = new Set();
+
+  const safeTimeout = (fn, delay) => {
+    const timerId = dom.setTimeout(() => {
+      activeTimers.delete(timerId);
+      fn();
+    }, delay);
+    activeTimers.add(timerId);
+    return timerId;
+  };
+
+  const clearAllTimers = () => {
+    for (const timerId of activeTimers) {
+      dom.clearTimeout(timerId);
+    }
+    activeTimers.clear();
+  };
+
+  // Apply enter animation
+  const applyEnter = () => {
+    dom.addClass(element, enter);
+    if (onEnter) onEnter(element);
+    safeTimeout(() => {
+      dom.removeClass(element, enter);
+    }, duration);
+  };
+
+  // Apply exit animation and return promise
+  const applyExit = () => {
+    return new Promise(resolve => {
+      dom.addClass(element, exit);
+      if (onExit) onExit(element);
+      safeTimeout(() => {
+        dom.removeClass(element, exit);
+        resolve();
+      }, duration);
+    });
+  };
+
+  // Apply enter on mount
+  dom.queueMicrotask(applyEnter);
+
+  // Attach exit method
+  element._pulseTransitionExit = applyExit;
+
+  // Register cleanup for all timers
+  onCleanup(clearAllTimers);
+
+  return element;
+}
+
+/**
+ * Conditional rendering with transitions
+ *
+ * MEMORY SAFETY: All timers are tracked and cleared on cleanup
+ * to prevent callbacks executing on removed elements.
+ *
+ * @param {Function|Pulse} condition - Condition source (reactive)
+ * @param {Function|Node} thenTemplate - Template to render when true
+ * @param {Function|Node|null} elseTemplate - Template to render when false
+ * @param {Object} options - Transition options
+ * @param {number} [options.duration=300] - Animation duration in ms
+ * @param {string} [options.enterClass='fade-in'] - Enter animation class
+ * @param {string} [options.exitClass='fade-out'] - Exit animation class
+ * @returns {DocumentFragment} Container with transitioning content
+ */
+export function whenTransition(condition, thenTemplate, elseTemplate = null, options = {}) {
+  const dom = getAdapter();
+  const container = dom.createDocumentFragment();
+  const marker = dom.createComment('when-transition');
+  dom.appendChild(container, marker);
+
+  const { duration = 300, enterClass = 'fade-in', exitClass = 'fade-out' } = options;
+
+  let currentNodes = [];
+  let isTransitioning = false;
+
+  // Track active timers for cleanup
+  const activeTimers = new Set();
+
+  const safeTimeout = (fn, delay) => {
+    const timerId = dom.setTimeout(() => {
+      activeTimers.delete(timerId);
+      fn();
+    }, delay);
+    activeTimers.add(timerId);
+    return timerId;
+  };
+
+  const clearAllTimers = () => {
+    for (const timerId of activeTimers) {
+      dom.clearTimeout(timerId);
+    }
+    activeTimers.clear();
+  };
+
+  // Register cleanup for all timers
+  onCleanup(clearAllTimers);
+
+  effect(() => {
+    const show = typeof condition === 'function' ? condition() : condition.get();
+
+    if (isTransitioning) return;
+
+    const template = show ? thenTemplate : elseTemplate;
+
+    // Exit animation for current nodes
+    if (currentNodes.length > 0) {
+      isTransitioning = true;
+      const nodesToRemove = [...currentNodes];
+      currentNodes = [];
+
+      for (const node of nodesToRemove) {
+        dom.addClass(node, exitClass);
+      }
+
+      safeTimeout(() => {
+        for (const node of nodesToRemove) {
+          dom.removeNode(node);
+        }
+        isTransitioning = false;
+
+        // Render new content
+        if (template) {
+          const result = typeof template === 'function' ? template() : template;
+          if (result) {
+            const nodes = Array.isArray(result) ? result : [result];
+            const fragment = dom.createDocumentFragment();
+            for (const node of nodes) {
+              if (dom.isNode(node)) {
+                dom.addClass(node, enterClass);
+                dom.appendChild(fragment, node);
+                currentNodes.push(node);
+                safeTimeout(() => dom.removeClass(node, enterClass), duration);
+              }
+            }
+            const markerParent = dom.getParentNode(marker);
+            if (markerParent) {
+              dom.insertBefore(markerParent, fragment, dom.getNextSibling(marker));
+            }
+          }
+        }
+      }, duration);
+    } else if (template) {
+      // No previous content, just render with enter animation
+      const result = typeof template === 'function' ? template() : template;
+      if (result) {
+        const nodes = Array.isArray(result) ? result : [result];
+        const fragment = dom.createDocumentFragment();
+        for (const node of nodes) {
+          if (dom.isNode(node)) {
+            dom.addClass(node, enterClass);
+            dom.appendChild(fragment, node);
+            currentNodes.push(node);
+            safeTimeout(() => dom.removeClass(node, enterClass), duration);
+          }
+        }
+        const markerParent = dom.getParentNode(marker);
+        if (markerParent) {
+          dom.insertBefore(markerParent, fragment, dom.getNextSibling(marker));
+        }
+      }
+    }
+  });
+
+  return container;
+}
+
+export default {
+  portal,
+  errorBoundary,
+  transition,
+  whenTransition
+};

package/runtime/dom-binding.js

@@ -0,0 +1,230 @@
+/**
+ * Pulse DOM Binding Module
+ * Reactive attribute, property, class, style, and event bindings
+ *
+ * @module dom-binding
+ */
+
+import { effect, onCleanup } from './pulse.js';
+import { sanitizeUrl, safeSetStyle } from './utils.js';
+import { getAdapter } from './dom-adapter.js';
+
+// =============================================================================
+// URL ATTRIBUTES (XSS Protection)
+// =============================================================================
+
+/**
+ * URL attributes that need sanitization in bind()
+ * @private
+ */
+const BIND_URL_ATTRIBUTES = new Set([
+  'href', 'src', 'action', 'formaction', 'data', 'poster',
+  'cite', 'codebase', 'background', 'profile', 'usemap', 'longdesc'
+]);
+
+// =============================================================================
+// REACTIVE BINDINGS
+// =============================================================================
+
+/**
+ * Bind an attribute reactively with XSS protection
+ *
+ * Security: URL attributes (href, src, etc.) are sanitized to prevent javascript: XSS
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {string} attr - Attribute name
+ * @param {*|Function} getValue - Value or function returning value
+ * @returns {HTMLElement} The element for chaining
+ */
+export function bind(element, attr, getValue) {
+  const dom = getAdapter();
+  const lowerAttr = attr.toLowerCase();
+  const isUrlAttr = BIND_URL_ATTRIBUTES.has(lowerAttr);
+
+  if (typeof getValue === 'function') {
+    effect(() => {
+      const value = getValue();
+      if (value == null || value === false) {
+        dom.removeAttribute(element, attr);
+      } else if (value === true) {
+        dom.setAttribute(element, attr, '');
+      } else {
+        // Sanitize URL attributes to prevent javascript: XSS
+        if (isUrlAttr) {
+          const sanitized = sanitizeUrl(String(value));
+          if (sanitized === null) {
+            console.warn(
+              `[Pulse Security] Dangerous URL blocked in bind() for ${attr}: "${String(value).slice(0, 50)}"`
+            );
+            dom.removeAttribute(element, attr);
+            return;
+          }
+          dom.setAttribute(element, attr, sanitized);
+        } else {
+          dom.setAttribute(element, attr, String(value));
+        }
+      }
+    });
+  } else {
+    // Sanitize URL attributes for static values too
+    if (isUrlAttr) {
+      const sanitized = sanitizeUrl(String(getValue));
+      if (sanitized === null) {
+        console.warn(
+          `[Pulse Security] Dangerous URL blocked in bind() for ${attr}: "${String(getValue).slice(0, 50)}"`
+        );
+        return element;
+      }
+      dom.setAttribute(element, attr, sanitized);
+    } else {
+      dom.setAttribute(element, attr, String(getValue));
+    }
+  }
+  return element;
+}
+
+/**
+ * Bind a property reactively
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {string} propName - Property name
+ * @param {*|Function} getValue - Value or function returning value
+ * @returns {HTMLElement} The element for chaining
+ */
+export function prop(element, propName, getValue) {
+  const dom = getAdapter();
+  if (typeof getValue === 'function') {
+    effect(() => {
+      dom.setProperty(element, propName, getValue());
+    });
+  } else {
+    dom.setProperty(element, propName, getValue);
+  }
+  return element;
+}
+
+/**
+ * Bind CSS class reactively
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {string} className - Class name to toggle
+ * @param {boolean|Function} condition - Condition or function returning condition
+ * @returns {HTMLElement} The element for chaining
+ */
+export function cls(element, className, condition) {
+  const dom = getAdapter();
+  if (typeof condition === 'function') {
+    effect(() => {
+      if (condition()) {
+        dom.addClass(element, className);
+      } else {
+        dom.removeClass(element, className);
+      }
+    });
+  } else if (condition) {
+    dom.addClass(element, className);
+  }
+  return element;
+}
+
+/**
+ * Bind style property reactively with CSS injection protection
+ *
+ * Security: CSS values are sanitized to prevent injection attacks via:
+ * - Semicolons (property injection: 'red; position: fixed')
+ * - url() (data exfiltration)
+ * - expression() (IE script execution)
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {string} prop - CSS property name
+ * @param {*} getValue - Value or function returning value
+ * @param {Object} [options] - Options passed to safeSetStyle
+ * @returns {HTMLElement} The element for chaining
+ */
+export function style(element, prop, getValue, options = {}) {
+  const dom = getAdapter();
+  if (typeof getValue === 'function') {
+    effect(() => {
+      safeSetStyle(element, prop, getValue(), options, dom);
+    });
+  } else {
+    safeSetStyle(element, prop, getValue, options, dom);
+  }
+  return element;
+}
+
+/**
+ * Attach an event listener with automatic cleanup
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {string} event - Event name
+ * @param {Function} handler - Event handler
+ * @param {Object} [options] - addEventListener options
+ * @returns {HTMLElement} The element for chaining
+ */
+export function on(element, event, handler, options) {
+  const dom = getAdapter();
+  dom.addEventListener(element, event, handler, options);
+
+  // Auto-cleanup: remove listener when effect is disposed (HMR support)
+  onCleanup(() => {
+    dom.removeEventListener(element, event, handler, options);
+  });
+
+  return element;
+}
+
+/**
+ * Two-way binding for form inputs
+ *
+ * MEMORY SAFETY: All event listeners are registered with onCleanup()
+ * to prevent memory leaks when the element is removed from the DOM.
+ *
+ * @param {HTMLElement} element - Form element (input, select, textarea)
+ * @param {Pulse} pulseValue - Pulse signal for two-way binding
+ * @returns {HTMLElement} The element for chaining
+ */
+export function model(element, pulseValue) {
+  const dom = getAdapter();
+  const tagName = dom.getTagName(element);
+  const type = dom.getInputType(element);
+
+  if (tagName === 'input' && (type === 'checkbox' || type === 'radio')) {
+    // Checkbox/Radio
+    effect(() => {
+      dom.setProperty(element, 'checked', pulseValue.get());
+    });
+    const handler = () => pulseValue.set(dom.getProperty(element, 'checked'));
+    dom.addEventListener(element, 'change', handler);
+    onCleanup(() => dom.removeEventListener(element, 'change', handler));
+  } else if (tagName === 'select') {
+    // Select
+    effect(() => {
+      dom.setProperty(element, 'value', pulseValue.get());
+    });
+    const handler = () => pulseValue.set(dom.getProperty(element, 'value'));
+    dom.addEventListener(element, 'change', handler);
+    onCleanup(() => dom.removeEventListener(element, 'change', handler));
+  } else {
+    // Text input, textarea, etc.
+    effect(() => {
+      if (dom.getProperty(element, 'value') !== pulseValue.get()) {
+        dom.setProperty(element, 'value', pulseValue.get());
+      }
+    });
+    const handler = () => pulseValue.set(dom.getProperty(element, 'value'));
+    dom.addEventListener(element, 'input', handler);
+    onCleanup(() => dom.removeEventListener(element, 'input', handler));
+  }
+
+  return element;
+}
+
+export default {
+  bind,
+  prop,
+  cls,
+  style,
+  on,
+  model
+};