pulse-js-framework 1.7.15 → 1.7.16

package/runtime/ssr-hydrator.js

@@ -0,0 +1,310 @@
+/**
+ * Pulse SSR Hydrator - Client-side hydration utilities
+ *
+ * Provides utilities for hydrating server-rendered HTML by attaching
+ * event listeners and reactive bindings to existing DOM elements.
+ */
+
+// ============================================================================
+// Hydration State
+// ============================================================================
+
+/** @type {boolean} */
+let isHydrating = false;
+
+/** @type {HydrationContext|null} */
+let hydrationCtx = null;
+
+// ============================================================================
+// Hydration Context
+// ============================================================================
+
+/**
+ * @typedef {Object} HydrationContext
+ * @property {Element} root - Root container element
+ * @property {Node|null} cursor - Current position in DOM tree
+ * @property {Array<Function>} cleanups - Cleanup functions for disposal
+ * @property {Array<{element: Element, event: string, handler: Function}>} listeners - Attached event listeners
+ * @property {number} depth - Current nesting depth
+ * @property {boolean} mismatchWarned - Whether a mismatch warning was shown
+ */
+
+/**
+ * Create a new hydration context for a container element.
+ * @param {Element} root - Root container element
+ * @returns {HydrationContext}
+ */
+export function createHydrationContext(root) {
+  return {
+    root,
+    cursor: root.firstChild,
+    cleanups: [],
+    listeners: [],
+    depth: 0,
+    mismatchWarned: false
+  };
+}
+
+// ============================================================================
+// Hydration Mode Control
+// ============================================================================
+
+/**
+ * Enable or disable hydration mode.
+ * @param {boolean} enabled - Whether to enable hydration mode
+ * @param {HydrationContext|null} ctx - Hydration context (required when enabling)
+ */
+export function setHydrationMode(enabled, ctx = null) {
+  isHydrating = enabled;
+  hydrationCtx = enabled ? ctx : null;
+}
+
+/**
+ * Check if currently in hydration mode.
+ * @returns {boolean}
+ */
+export function isHydratingMode() {
+  return isHydrating;
+}
+
+/**
+ * Get the current hydration context.
+ * @returns {HydrationContext|null}
+ */
+export function getHydrationContext() {
+  return hydrationCtx;
+}
+
+// ============================================================================
+// DOM Cursor Navigation
+// ============================================================================
+
+/**
+ * Get the current node at the cursor position.
+ * @param {HydrationContext} ctx - Hydration context
+ * @returns {Node|null}
+ */
+export function getCurrentNode(ctx) {
+  return ctx.cursor;
+}
+
+/**
+ * Advance the cursor to the next sibling.
+ * @param {HydrationContext} ctx - Hydration context
+ */
+export function advanceCursor(ctx) {
+  if (ctx.cursor) {
+    ctx.cursor = ctx.cursor.nextSibling;
+  }
+}
+
+/**
+ * Enter a child scope (for nested elements).
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {Element} element - Parent element to enter
+ */
+export function enterChild(ctx, element) {
+  ctx.cursor = element.firstChild;
+  ctx.depth++;
+}
+
+/**
+ * Exit a child scope and restore cursor to parent level.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {Element} element - Element we're exiting
+ */
+export function exitChild(ctx, element) {
+  ctx.cursor = element.nextSibling;
+  ctx.depth--;
+}
+
+/**
+ * Skip comment nodes (used as markers).
+ * @param {HydrationContext} ctx - Hydration context
+ */
+export function skipComments(ctx) {
+  while (ctx.cursor && ctx.cursor.nodeType === 8) {
+    ctx.cursor = ctx.cursor.nextSibling;
+  }
+}
+
+// ============================================================================
+// DOM Matching
+// ============================================================================
+
+/**
+ * Check if an element matches expected tag and basic attributes.
+ * @param {Node} node - Node to check
+ * @param {string} expectedTag - Expected tag name (lowercase)
+ * @param {string} [expectedId] - Expected ID (optional)
+ * @param {string} [expectedClass] - Expected class (optional)
+ * @returns {boolean}
+ */
+export function matchesElement(node, expectedTag, expectedId, expectedClass) {
+  if (!node || node.nodeType !== 1) return false;
+
+  const tag = node.tagName?.toLowerCase();
+  if (tag !== expectedTag) return false;
+
+  if (expectedId && node.id !== expectedId) return false;
+  if (expectedClass && !node.classList?.contains(expectedClass)) return false;
+
+  return true;
+}
+
+/**
+ * Log a hydration mismatch warning.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {string} expected - What was expected
+ * @param {Node|null} actual - What was found
+ */
+export function warnMismatch(ctx, expected, actual) {
+  if (ctx.mismatchWarned) return;
+
+  const actualDesc = actual
+    ? `<${actual.tagName?.toLowerCase() || actual.nodeName}>`
+    : 'null';
+
+  console.warn(
+    `[Pulse Hydration] Mismatch at depth ${ctx.depth}: ` +
+    `expected ${expected}, found ${actualDesc}. ` +
+    `This may cause hydration errors.`
+  );
+
+  ctx.mismatchWarned = true;
+}
+
+// ============================================================================
+// Event Listener Management
+// ============================================================================
+
+/**
+ * Register an event listener during hydration.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {Element} element - Target element
+ * @param {string} event - Event name
+ * @param {Function} handler - Event handler
+ * @param {Object} [options] - Event listener options
+ */
+export function registerListener(ctx, element, event, handler, options) {
+  element.addEventListener(event, handler, options);
+  ctx.listeners.push({ element, event, handler, options });
+}
+
+/**
+ * Register a cleanup function.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {Function} cleanup - Cleanup function
+ */
+export function registerCleanup(ctx, cleanup) {
+  ctx.cleanups.push(cleanup);
+}
+
+// ============================================================================
+// Hydration Disposal
+// ============================================================================
+
+/**
+ * Dispose of all hydration resources.
+ * Removes event listeners and runs cleanup functions.
+ * @param {HydrationContext} ctx - Hydration context
+ */
+export function disposeHydration(ctx) {
+  // Remove all event listeners
+  for (const { element, event, handler, options } of ctx.listeners) {
+    element.removeEventListener(event, handler, options);
+  }
+  ctx.listeners = [];
+
+  // Run cleanup functions
+  for (const cleanup of ctx.cleanups) {
+    try {
+      cleanup();
+    } catch (e) {
+      console.error('[Pulse Hydration] Cleanup error:', e);
+    }
+  }
+  ctx.cleanups = [];
+}
+
+// ============================================================================
+// Hydration Helpers
+// ============================================================================
+
+/**
+ * Find the next element matching a tag within the current scope.
+ * Useful for recovering from mismatches.
+ * @param {HydrationContext} ctx - Hydration context
+ * @param {string} tag - Tag name to find
+ * @returns {Element|null}
+ */
+export function findNextElement(ctx, tag) {
+  let node = ctx.cursor;
+  while (node) {
+    if (node.nodeType === 1 && node.tagName?.toLowerCase() === tag) {
+      return node;
+    }
+    node = node.nextSibling;
+  }
+  return null;
+}
+
+/**
+ * Count remaining elements in the current scope.
+ * Useful for debugging hydration issues.
+ * @param {HydrationContext} ctx - Hydration context
+ * @returns {number}
+ */
+export function countRemaining(ctx) {
+  let count = 0;
+  let node = ctx.cursor;
+  while (node) {
+    if (node.nodeType === 1) count++;
+    node = node.nextSibling;
+  }
+  return count;
+}
+
+/**
+ * Check if hydration is complete (no more nodes to process).
+ * @param {HydrationContext} ctx - Hydration context
+ * @returns {boolean}
+ */
+export function isHydrationComplete(ctx) {
+  return ctx.cursor === null && ctx.depth === 0;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+  // Mode control
+  setHydrationMode,
+  isHydratingMode,
+  getHydrationContext,
+
+  // Context
+  createHydrationContext,
+
+  // Navigation
+  getCurrentNode,
+  advanceCursor,
+  enterChild,
+  exitChild,
+  skipComments,
+
+  // Matching
+  matchesElement,
+  warnMismatch,
+  findNextElement,
+
+  // Resources
+  registerListener,
+  registerCleanup,
+  disposeHydration,
+
+  // Helpers
+  countRemaining,
+  isHydrationComplete
+};

package/runtime/ssr-serializer.js

@@ -0,0 +1,266 @@
+/**
+ * Pulse SSR Serializer - HTML serialization for MockNode trees
+ *
+ * Converts MockDOMAdapter node trees into HTML strings for server-side rendering.
+ * Handles all node types: elements, text, comments, and fragments.
+ */
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Void elements that are self-closing in HTML (no closing tag).
+ */
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr'
+]);
+
+/**
+ * Boolean attributes that are present or absent (no value needed).
+ */
+const BOOLEAN_ATTRS = new Set([
+  'disabled', 'checked', 'readonly', 'required', 'autofocus',
+  'multiple', 'selected', 'hidden', 'open', 'inert', 'novalidate',
+  'async', 'defer', 'formnovalidate', 'allowfullscreen', 'autoplay',
+  'controls', 'loop', 'muted', 'playsinline', 'reversed', 'ismap'
+]);
+
+/**
+ * Attributes that should be skipped during serialization.
+ */
+const SKIP_ATTRS = new Set(['class', 'id', 'style']);
+
+// ============================================================================
+// HTML Escaping
+// ============================================================================
+
+/**
+ * Escape HTML special characters in text content.
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for HTML text content
+ */
+export function escapeHTML(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Escape special characters for use in HTML attributes.
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string safe for attribute values
+ */
+export function escapeAttr(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+// ============================================================================
+// Style Serialization
+// ============================================================================
+
+/**
+ * Convert camelCase to kebab-case for CSS properties.
+ * @param {string} str - camelCase string
+ * @returns {string} kebab-case string
+ */
+function camelToKebab(str) {
+  return str.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
+}
+
+/**
+ * Serialize a style object to a CSS string.
+ * @param {Object} styleObj - Style object with camelCase properties
+ * @returns {string} CSS string like "color: red; font-size: 16px"
+ */
+function serializeStyle(styleObj) {
+  if (!styleObj || typeof styleObj !== 'object') return '';
+
+  const styles = [];
+  for (const [key, value] of Object.entries(styleObj)) {
+    if (value != null && value !== '') {
+      styles.push(`${camelToKebab(key)}: ${value}`);
+    }
+  }
+  return styles.join('; ');
+}
+
+// ============================================================================
+// Attribute Serialization
+// ============================================================================
+
+/**
+ * Serialize element attributes to an HTML attribute string.
+ * @param {MockElement} element - Element to serialize attributes from
+ * @returns {string} Attribute string like ' id="foo" class="bar"'
+ */
+function serializeAttributes(element) {
+  const parts = [];
+
+  // ID attribute
+  if (element.id) {
+    parts.push(`id="${escapeAttr(element.id)}"`);
+  }
+
+  // Class attribute
+  if (element.className) {
+    parts.push(`class="${escapeAttr(element.className)}"`);
+  }
+
+  // Other attributes from _attributes Map
+  if (element._attributes) {
+    for (const [name, value] of element._attributes) {
+      // Skip already handled attributes
+      if (SKIP_ATTRS.has(name)) continue;
+
+      if (BOOLEAN_ATTRS.has(name)) {
+        // Boolean attributes: present if truthy
+        if (value === 'true' || value === true || value === name || value === '') {
+          parts.push(name);
+        }
+      } else {
+        // Regular attributes
+        parts.push(`${name}="${escapeAttr(value)}"`);
+      }
+    }
+  }
+
+  // Style attribute
+  const styleStr = serializeStyle(element._style || element.style);
+  if (styleStr) {
+    parts.push(`style="${escapeAttr(styleStr)}"`);
+  }
+
+  return parts.length > 0 ? ' ' + parts.join(' ') : '';
+}
+
+// ============================================================================
+// Node Serialization
+// ============================================================================
+
+/**
+ * Serialize a MockNode tree to an HTML string.
+ *
+ * Supports all node types:
+ * - Element nodes (nodeType 1)
+ * - Text nodes (nodeType 3)
+ * - Comment nodes (nodeType 8)
+ * - Document fragments (nodeType 11)
+ *
+ * @param {MockNode} node - Root node to serialize
+ * @param {Object} [options] - Serialization options
+ * @param {boolean} [options.pretty=false] - Pretty print with indentation
+ * @param {number} [options.indent=0] - Initial indentation level
+ * @param {string} [options.indentStr='  '] - Indentation string
+ * @returns {string} HTML string
+ *
+ * @example
+ * const adapter = new MockDOMAdapter();
+ * const div = adapter.createElement('div');
+ * div.id = 'app';
+ * div.className = 'container';
+ * adapter.appendChild(div, adapter.createTextNode('Hello'));
+ *
+ * serializeToHTML(div);
+ * // '<div id="app" class="container">Hello</div>'
+ */
+export function serializeToHTML(node, options = {}) {
+  if (!node) return '';
+
+  const { pretty = false, indent = 0, indentStr = '  ' } = options;
+  const prefix = pretty ? indentStr.repeat(indent) : '';
+  const newline = pretty ? '\n' : '';
+
+  // Text node (nodeType 3)
+  if (node.nodeType === 3) {
+    const text = node.textContent ?? node.data ?? '';
+    return escapeHTML(text);
+  }
+
+  // Comment node (nodeType 8)
+  if (node.nodeType === 8) {
+    const data = node.data ?? node.textContent ?? '';
+    return `${prefix}<!--${data}-->`;
+  }
+
+  // Document fragment (nodeType 11)
+  if (node.nodeType === 11) {
+    return (node.childNodes || [])
+      .map(child => serializeToHTML(child, { ...options, indent }))
+      .join(newline);
+  }
+
+  // Element node (nodeType 1)
+  if (node.nodeType === 1) {
+    const tag = (node.tagName || 'div').toLowerCase();
+    const attrs = serializeAttributes(node);
+
+    // Void elements (self-closing)
+    if (VOID_ELEMENTS.has(tag)) {
+      return `${prefix}<${tag}${attrs}>`;
+    }
+
+    // Elements with children
+    const children = node.childNodes || [];
+    let childrenHTML = '';
+
+    if (children.length > 0) {
+      if (pretty) {
+        childrenHTML = newline +
+          children
+            .map(child => serializeToHTML(child, { ...options, indent: indent + 1 }))
+            .join(newline) +
+          newline + prefix;
+      } else {
+        childrenHTML = children
+          .map(child => serializeToHTML(child, options))
+          .join('');
+      }
+    }
+
+    return `${prefix}<${tag}${attrs}>${childrenHTML}</${tag}>`;
+  }
+
+  // Unknown node type
+  return '';
+}
+
+/**
+ * Serialize only the children of a node (excludes the node itself).
+ * Useful for serializing the body content without the body tag.
+ *
+ * @param {MockNode} node - Node whose children to serialize
+ * @param {Object} [options] - Serialization options
+ * @returns {string} HTML string of children
+ */
+export function serializeChildren(node, options = {}) {
+  if (!node || !node.childNodes) return '';
+
+  const { pretty = false } = options;
+  const newline = pretty ? '\n' : '';
+
+  return node.childNodes
+    .map(child => serializeToHTML(child, options))
+    .join(newline);
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+  serializeToHTML,
+  serializeChildren,
+  escapeHTML,
+  escapeAttr,
+  VOID_ELEMENTS,
+  BOOLEAN_ATTRS
+};