pulse-js-framework 1.7.4 → 1.7.6

package/runtime/dom-conditional.js

@@ -0,0 +1,133 @@
+/**
+ * Pulse DOM Conditional Module
+ * Conditional rendering primitives (when, match, show)
+ *
+ * @module dom-conditional
+ */
+
+import { effect } from './pulse.js';
+import { getAdapter } from './dom-adapter.js';
+
+// =============================================================================
+// CONDITIONAL RENDERING
+// =============================================================================
+
+/**
+ * Conditional rendering - renders content based on condition
+ *
+ * @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
+ * @returns {DocumentFragment} Container fragment with conditional content
+ */
+export function when(condition, thenTemplate, elseTemplate = null) {
+  const dom = getAdapter();
+  const container = dom.createDocumentFragment();
+  const marker = dom.createComment('when');
+  dom.appendChild(container, marker);
+
+  let currentNodes = [];
+  let currentCleanup = null;
+
+  effect(() => {
+    const show = typeof condition === 'function' ? condition() : condition.get();
+
+    // Cleanup previous
+    for (const node of currentNodes) {
+      dom.removeNode(node);
+    }
+    if (currentCleanup) currentCleanup();
+    currentNodes = [];
+    currentCleanup = null;
+
+    // Render new
+    const template = show ? thenTemplate : elseTemplate;
+    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.appendChild(fragment, node);
+            currentNodes.push(node);
+          }
+        }
+        const markerParent = dom.getParentNode(marker);
+        if (markerParent) {
+          dom.insertBefore(markerParent, fragment, dom.getNextSibling(marker));
+        }
+      }
+    }
+  });
+
+  return container;
+}
+
+/**
+ * Switch/case rendering - renders content based on matching value
+ *
+ * @param {Function|Pulse} getValue - Value source (reactive)
+ * @param {Object} cases - Map of value -> template, with optional 'default' key
+ * @returns {Comment} Marker node for position tracking
+ */
+export function match(getValue, cases) {
+  const dom = getAdapter();
+  const marker = dom.createComment('match');
+  let currentNodes = [];
+
+  effect(() => {
+    const value = typeof getValue === 'function' ? getValue() : getValue.get();
+
+    // Remove old nodes
+    for (const node of currentNodes) {
+      dom.removeNode(node);
+    }
+    currentNodes = [];
+
+    // Find matching case
+    const template = cases[value] ?? cases.default;
+    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.appendChild(fragment, node);
+            currentNodes.push(node);
+          }
+        }
+        const markerParent = dom.getParentNode(marker);
+        if (markerParent) {
+          dom.insertBefore(markerParent, fragment, dom.getNextSibling(marker));
+        }
+      }
+    }
+  });
+
+  return marker;
+}
+
+/**
+ * Toggle element visibility without removing from DOM
+ * Unlike when(), this keeps the element in the DOM but hides it
+ *
+ * @param {Function|Pulse} condition - Condition source (reactive)
+ * @param {HTMLElement} element - Element to show/hide
+ * @returns {HTMLElement} The element for chaining
+ */
+export function show(condition, element) {
+  const dom = getAdapter();
+  effect(() => {
+    const shouldShow = typeof condition === 'function' ? condition() : condition.get();
+    dom.setStyle(element, 'display', shouldShow ? '' : 'none');
+  });
+  return element;
+}
+
+export default {
+  when,
+  match,
+  show
+};

package/runtime/dom-element.js

@@ -0,0 +1,142 @@
+/**
+ * Pulse DOM Element Module
+ * Core element creation and text node utilities
+ *
+ * @module dom-element
+ */
+
+import { effect } from './pulse.js';
+import { loggers } from './logger.js';
+import { safeSetAttribute } from './utils.js';
+import { getAdapter } from './dom-adapter.js';
+import { parseSelector } from './dom-selector.js';
+
+const log = loggers.dom;
+
+// =============================================================================
+// ELEMENT CREATION
+// =============================================================================
+
+/**
+ * Create a DOM element from a CSS selector-like string
+ *
+ * @param {string} selector - CSS selector-like string (e.g., 'div.container#main')
+ * @param {...*} children - Child elements, text, or reactive functions
+ * @returns {HTMLElement} Created DOM element
+ */
+export function el(selector, ...children) {
+  const dom = getAdapter();
+  const config = parseSelector(selector);
+  const element = dom.createElement(config.tag);
+
+  if (config.id) {
+    dom.setProperty(element, 'id', config.id);
+  }
+
+  if (config.classes.length > 0) {
+    dom.setProperty(element, 'className', config.classes.join(' '));
+  }
+
+  for (const [key, value] of Object.entries(config.attrs)) {
+    // Use safeSetAttribute to prevent XSS via event handlers and javascript: URLs
+    safeSetAttribute(element, key, value, {}, dom);
+  }
+
+  // Process children
+  for (const child of children) {
+    appendChild(element, child);
+  }
+
+  return element;
+}
+
+/**
+ * Append a child to an element, handling various types
+ *
+ * @private
+ * @param {HTMLElement} parent - Parent element
+ * @param {*} child - Child to append (string, number, Node, array, or function)
+ */
+function appendChild(parent, child) {
+  const dom = getAdapter();
+
+  if (child == null || child === false) return;
+
+  if (typeof child === 'string' || typeof child === 'number') {
+    dom.appendChild(parent, dom.createTextNode(String(child)));
+  } else if (dom.isNode(child)) {
+    dom.appendChild(parent, child);
+  } else if (Array.isArray(child)) {
+    for (const c of child) {
+      appendChild(parent, c);
+    }
+  } else if (typeof child === 'function') {
+    // Reactive child - create a placeholder and update it
+    const placeholder = dom.createComment('pulse');
+    dom.appendChild(parent, placeholder);
+    let currentNodes = [];
+
+    effect(() => {
+      const result = child();
+
+      // Remove old nodes
+      for (const node of currentNodes) {
+        dom.removeNode(node);
+      }
+      currentNodes = [];
+
+      // Add new nodes
+      if (result != null && result !== false) {
+        const fragment = dom.createDocumentFragment();
+        if (typeof result === 'string' || typeof result === 'number') {
+          const textNode = dom.createTextNode(String(result));
+          dom.appendChild(fragment, textNode);
+          currentNodes.push(textNode);
+        } else if (dom.isNode(result)) {
+          dom.appendChild(fragment, result);
+          currentNodes.push(result);
+        } else if (Array.isArray(result)) {
+          for (const r of result) {
+            if (dom.isNode(r)) {
+              dom.appendChild(fragment, r);
+              currentNodes.push(r);
+            } else if (r != null && r !== false) {
+              const textNode = dom.createTextNode(String(r));
+              dom.appendChild(fragment, textNode);
+              currentNodes.push(textNode);
+            }
+          }
+        }
+        const placeholderParent = dom.getParentNode(placeholder);
+        if (placeholderParent) {
+          dom.insertBefore(placeholderParent, fragment, dom.getNextSibling(placeholder));
+        } else {
+          log.warn('Cannot insert reactive children: placeholder has no parent node');
+        }
+      }
+    });
+  }
+}
+
+/**
+ * Create a reactive text node
+ *
+ * @param {*|Function} getValue - Text value or function returning text
+ * @returns {Text} Text node
+ */
+export function text(getValue) {
+  const dom = getAdapter();
+  if (typeof getValue === 'function') {
+    const node = dom.createTextNode('');
+    effect(() => {
+      dom.setTextContent(node, String(getValue()));
+    });
+    return node;
+  }
+  return dom.createTextNode(String(getValue));
+}
+
+export default {
+  el,
+  text
+};

package/runtime/dom-lifecycle.js

@@ -0,0 +1,178 @@
+/**
+ * Pulse DOM Lifecycle Module
+ * Component lifecycle hooks and mounting utilities
+ *
+ * @module dom-lifecycle
+ */
+
+import { pulse, onCleanup } from './pulse.js';
+import { loggers } from './logger.js';
+import { getAdapter } from './dom-adapter.js';
+import { Errors } from './errors.js';
+import { resolveSelector } from './dom-selector.js';
+
+const log = loggers.dom;
+
+// Context utilities are injected by dom.js to avoid circular dependencies
+let _contextUtils = null;
+
+/**
+ * Set context utilities for component factory (called by dom.js)
+ * @private
+ */
+export function _setContextUtils(utils) {
+  _contextUtils = utils;
+}
+
+// =============================================================================
+// LIFECYCLE TRACKING
+// =============================================================================
+
+let currentMountContext = null;
+
+/**
+ * Register a callback to run when component mounts
+ *
+ * @param {Function} fn - Callback to run on mount
+ */
+export function onMount(fn) {
+  if (currentMountContext) {
+    currentMountContext.mountCallbacks.push(fn);
+  } else {
+    // Defer to next microtask if no context
+    const dom = getAdapter();
+    dom.queueMicrotask(fn);
+  }
+}
+
+/**
+ * Register a callback to run when component unmounts
+ *
+ * @param {Function} fn - Callback to run on unmount
+ */
+export function onUnmount(fn) {
+  if (currentMountContext) {
+    currentMountContext.unmountCallbacks.push(fn);
+  }
+  // Also register with effect cleanup if in an effect
+  onCleanup(fn);
+}
+
+/**
+ * Get current mount context (for internal use)
+ * @returns {Object|null} Current mount context
+ */
+export function getMountContext() {
+  return currentMountContext;
+}
+
+/**
+ * Set current mount context (for internal use)
+ * @param {Object|null} context - Mount context to set
+ * @returns {Object|null} Previous mount context
+ */
+export function setMountContext(context) {
+  const prev = currentMountContext;
+  currentMountContext = context;
+  return prev;
+}
+
+// =============================================================================
+// MOUNTING
+// =============================================================================
+
+/**
+ * Mount an element to a target
+ *
+ * @param {string|HTMLElement} target - CSS selector or DOM element
+ * @param {Node} element - Element to mount
+ * @returns {Function} Unmount function
+ * @throws {Error} If target element is not found
+ */
+export function mount(target, element) {
+  const dom = getAdapter();
+  const { element: resolved, selector } = resolveSelector(target, 'mount');
+  if (!resolved) {
+    throw Errors.mountNotFound(selector);
+  }
+  dom.appendChild(resolved, element);
+  return () => {
+    dom.removeNode(element);
+  };
+}
+
+// =============================================================================
+// COMPONENT FACTORY
+// =============================================================================
+
+/**
+ * Create a component factory with lifecycle support
+ *
+ * @param {Function} setup - Setup function that receives context
+ * @returns {Function} Component factory function
+ */
+export function component(setup) {
+  return (props = {}) => {
+    const dom = getAdapter();
+    const state = {};
+    const methods = {};
+
+    // Create mount context for lifecycle hooks
+    const mountContext = {
+      mountCallbacks: [],
+      unmountCallbacks: []
+    };
+
+    const prevContext = currentMountContext;
+    currentMountContext = mountContext;
+
+    // Build context with injected utilities
+    const ctx = {
+      state,
+      methods,
+      props,
+      pulse,
+      onMount,
+      onUnmount,
+      // Spread utilities injected from dom.js
+      ...(_contextUtils || {})
+    };
+
+    let result;
+    try {
+      result = setup(ctx);
+    } finally {
+      currentMountContext = prevContext;
+    }
+
+    // Schedule mount callbacks after DOM insertion
+    if (mountContext.mountCallbacks.length > 0) {
+      dom.queueMicrotask(() => {
+        for (const cb of mountContext.mountCallbacks) {
+          try {
+            cb();
+          } catch (e) {
+            log.error('Mount callback error:', e);
+          }
+        }
+      });
+    }
+
+    // Store unmount callbacks on the element for later cleanup
+    if (dom.isNode(result) && mountContext.unmountCallbacks.length > 0) {
+      result._pulseUnmount = mountContext.unmountCallbacks;
+    }
+
+    return result;
+  };
+}
+
+export default {
+  onMount,
+  onUnmount,
+  mount,
+  component,
+  getMountContext,
+  setMountContext,
+  _setContextUtils
+};