pulse-js-framework 1.9.3 → 1.10.0

package/runtime/dom-advanced.js

@@ -21,63 +21,142 @@ const log = loggers.dom;
  *
  * @param {*|Function} children - Children to render (static or reactive)
  * @param {string|HTMLElement} target - Target selector or element
- * @returns {Comment} Marker node for position tracking
+ * @param {Object} [options] - Portal options
+ * @param {string} [options.key] - Unique key for multiple portals to same target
+ * @param {boolean} [options.prepend=false] - Insert at beginning of target
+ * @param {Function} [options.onMount] - Called when children are mounted
+ * @param {Function} [options.onUnmount] - Called when children are unmounted
+ * @returns {Comment} Marker node with dispose(), moveTo(), getNodes() methods
  */
-export function portal(children, target) {
+export function portal(children, target, options = {}) {
   const dom = getAdapter();
-  const { element: resolvedTarget, selector } = resolveSelector(target, 'portal');
+  const { key = null, prepend = false, onMount = null, onUnmount = null } = options;
+
+  let currentTarget = null;
+  let currentSelector = null;
+  let mountedNodes = [];
+  let disposed = false;
+  let disposeEffect = null;
+
+  // Resolve target
+  function _resolveTarget(tgt) {
+    const { element: resolvedTarget, selector } = resolveSelector(tgt, 'portal');
+    currentTarget = resolvedTarget;
+    currentSelector = selector;
+    return resolvedTarget;
+  }
+
+  const resolvedTarget = _resolveTarget(target);
 
   if (!resolvedTarget) {
-    log.warn(`Portal target not found: "${selector}"`);
-    return dom.createComment('portal-target-not-found');
+    log.warn(`Portal target not found: "${currentSelector}"`);
+    const marker = dom.createComment(key ? `portal:${key}` : 'portal-target-not-found');
+    marker.dispose = () => {};
+    marker.moveTo = () => {};
+    marker.getNodes = () => [];
+    return marker;
   }
 
-  const marker = dom.createComment('portal');
-  let mountedNodes = [];
+  const marker = dom.createComment(key ? `portal:${key}` : 'portal');
 
-  // 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();
+  function _clearNodes() {
+    for (const node of mountedNodes) {
+      dom.removeNode(node);
+      if (node._pulseUnmount) {
+        for (const cb of node._pulseUnmount) cb();
+      }
+    }
+    if (mountedNodes.length > 0) {
+      onUnmount?.();
+    }
+    mountedNodes = [];
+  }
+
+  function _mountNodes(nodes, tgt) {
+    for (const node of nodes) {
+      if (dom.isNode(node)) {
+        if (prepend && tgt.firstChild) {
+          dom.insertBefore(tgt, node, tgt.firstChild);
+        } else {
+          dom.appendChild(tgt, node);
         }
+        mountedNodes.push(node);
       }
-      mountedNodes = [];
+    }
+    if (mountedNodes.length > 0) {
+      onMount?.();
+    }
+  }
 
+  function _renderChildren(tgt) {
+    if (typeof children === 'function') {
       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);
-          }
-        }
+        _mountNodes(nodes, tgt);
       }
+    } else {
+      const nodes = Array.isArray(children) ? children : [children];
+      _mountNodes(nodes, tgt);
+    }
+  }
+
+  // Handle reactive children
+  if (typeof children === 'function') {
+    disposeEffect = effect(() => {
+      if (disposed) return;
+      _clearNodes();
+      _renderChildren(currentTarget);
     });
   } 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);
-      }
-    }
+    _renderChildren(currentTarget);
   }
 
-  // Return marker for position tracking, attach cleanup
-  marker._pulseUnmount = [() => {
-    for (const node of mountedNodes) {
+  /**
+   * Manually dispose portal (remove all portaled nodes)
+   */
+  marker.dispose = function () {
+    if (disposed) return;
+    disposed = true;
+    _clearNodes();
+    if (disposeEffect) disposeEffect();
+  };
+
+  /**
+   * Move portaled content to a new target
+   * @param {string|HTMLElement} newTarget - New target selector or element
+   */
+  marker.moveTo = function (newTarget) {
+    if (disposed) return;
+
+    const resolved = _resolveTarget(newTarget);
+    if (!resolved) {
+      log.warn(`Portal moveTo target not found: "${currentSelector}"`);
+      return;
+    }
+
+    // Re-mount existing nodes in new target
+    const existingNodes = [...mountedNodes];
+    // Remove from old target without unmount callbacks
+    for (const node of existingNodes) {
       dom.removeNode(node);
-      if (node._pulseUnmount) {
-        for (const cb of node._pulseUnmount) cb();
-      }
     }
-  }];
+    mountedNodes = [];
+
+    // Re-mount in new target
+    _mountNodes(existingNodes, resolved);
+  };
+
+  /**
+   * Get currently portaled nodes
+   * @returns {Array} Currently mounted nodes
+   */
+  marker.getNodes = function () {
+    return [...mountedNodes];
+  };
+
+  // Attach cleanup for parent effect cascade
+  marker._pulseUnmount = [() => marker.dispose()];
 
   return marker;
 }

package/runtime/i18n.js

@@ -0,0 +1,434 @@
+/**
+ * Pulse i18n Module
+ * Internationalization with reactive locale switching, pluralization, and interpolation.
+ *
+ * @module pulse-js-framework/runtime/i18n
+ */
+
+import { pulse, computed } from './pulse.js';
+import { loggers } from './logger.js';
+import { RuntimeError } from './errors.js';
+import { DANGEROUS_KEYS } from './security.js';
+
+const log = loggers.pulse;
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const DEFAULT_OPTIONS = {
+  locale: 'en',
+  fallbackLocale: 'en',
+  messages: {},
+  pluralRules: null,
+  missing: null,
+  modifiers: null,
+};
+
+/**
+ * Default English pluralization: 0 = zero, 1 = one, 2+ = other
+ */
+const DEFAULT_PLURAL_RULES = {
+  en: (count) => {
+    if (count === 0) return 0;
+    if (count === 1) return 1;
+    return 2;
+  },
+};
+
+// =============================================================================
+// MODULE-LEVEL DEFAULT INSTANCE
+// =============================================================================
+
+let _defaultInstance = null;
+
+// =============================================================================
+// I18N ERROR
+// =============================================================================
+
+export class I18nError extends RuntimeError {
+  constructor(message, options = {}) {
+    super(message, { code: 'I18N_ERROR', ...options });
+    this.name = 'I18nError';
+  }
+
+  static isI18nError(error) {
+    return error instanceof I18nError;
+  }
+}
+
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+
+/**
+ * Resolve a dot-notated key in a nested object
+ * @private
+ */
+function _resolveKey(messages, key) {
+  const parts = key.split('.');
+  let current = messages;
+
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = current[part];
+  }
+
+  return current;
+}
+
+/**
+ * Interpolate {param} placeholders in a message string
+ * @private
+ */
+function _interpolate(message, params) {
+  if (!params || typeof message !== 'string') return message;
+
+  return message.replace(/\{(\w+)\}/g, (match, key) => {
+    if (key in params) {
+      return String(params[key]);
+    }
+    return match;
+  });
+}
+
+/**
+ * Apply modifiers (pipe syntax): 'key | upper'
+ * @private
+ */
+function _applyModifiers(value, modifierStr, modifiers) {
+  if (!modifiers || !modifierStr) return value;
+
+  const parts = modifierStr.split('|').map(s => s.trim());
+  let result = value;
+
+  for (const mod of parts) {
+    if (mod && modifiers[mod]) {
+      result = modifiers[mod](result);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse key for modifiers: 'hello | upper' -> { key: 'hello', modifiers: 'upper' }
+ * @private
+ */
+function _parseKey(key) {
+  const pipeIdx = key.indexOf(' | ');
+  if (pipeIdx === -1) {
+    return { key: key.trim(), modifierStr: null };
+  }
+  return {
+    key: key.substring(0, pipeIdx).trim(),
+    modifierStr: key.substring(pipeIdx + 3),
+  };
+}
+
+/**
+ * Get the plural form index for a locale and count
+ * @private
+ */
+function _getPluralIndex(locale, count, customRules) {
+  // Check custom rules first
+  if (customRules && customRules[locale]) {
+    return customRules[locale](count);
+  }
+
+  // Check default rules
+  const lang = locale.split('-')[0];
+  if (DEFAULT_PLURAL_RULES[lang]) {
+    return DEFAULT_PLURAL_RULES[lang](count);
+  }
+
+  // Fallback: 0 = zero, 1 = one, 2+ = other
+  if (count === 0) return 0;
+  if (count === 1) return 1;
+  return 2;
+}
+
+// =============================================================================
+// createI18n
+// =============================================================================
+
+/**
+ * Create an i18n instance with reactive locale switching
+ *
+ * @param {Object} [options] - Configuration options
+ * @returns {Object} I18n instance
+ */
+export function createI18n(options = {}) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+
+  // Reactive locale
+  const locale = pulse(config.locale);
+  const messages = { ...config.messages };
+
+  /**
+   * Get available locales
+   * @returns {string[]}
+   */
+  function getAvailableLocales() {
+    return Object.keys(messages);
+  }
+
+  /**
+   * Translate a key with optional interpolation
+   *
+   * @param {string} key - Translation key (dot notation supported, pipe modifiers supported)
+   * @param {Object} [params] - Interpolation parameters
+   * @returns {string} Translated string
+   */
+  function t(key, params) {
+    const { key: resolvedKey, modifierStr } = _parseKey(key);
+    const currentLocale = locale.get();
+
+    // Look up in current locale
+    let message = _resolveKey(messages[currentLocale], resolvedKey);
+
+    // Fallback to fallback locale
+    if (message === undefined && config.fallbackLocale && config.fallbackLocale !== currentLocale) {
+      message = _resolveKey(messages[config.fallbackLocale], resolvedKey);
+    }
+
+    // Missing key handler
+    if (message === undefined) {
+      if (config.missing) {
+        return config.missing(currentLocale, resolvedKey);
+      }
+      log.warn(`Missing translation: "${resolvedKey}" for locale "${currentLocale}"`);
+      return resolvedKey;
+    }
+
+    // If message is not a string (e.g., nested object), return key
+    if (typeof message !== 'string') {
+      return resolvedKey;
+    }
+
+    // Interpolate
+    let result = _interpolate(message, params);
+
+    // Apply modifiers
+    if (modifierStr) {
+      result = _applyModifiers(result, modifierStr, config.modifiers);
+    }
+
+    return result;
+  }
+
+  /**
+   * Translate with pluralization
+   *
+   * @param {string} key - Translation key (message format: 'zero | one | other')
+   * @param {number} count - Count for pluralization
+   * @param {Object} [params] - Additional interpolation parameters
+   * @returns {string} Pluralized translated string
+   */
+  function tc(key, count, params) {
+    const currentLocale = locale.get();
+
+    let message = _resolveKey(messages[currentLocale], key);
+
+    if (message === undefined && config.fallbackLocale && config.fallbackLocale !== currentLocale) {
+      message = _resolveKey(messages[config.fallbackLocale], key);
+    }
+
+    if (message === undefined) {
+      if (config.missing) {
+        return config.missing(currentLocale, key);
+      }
+      log.warn(`Missing translation: "${key}" for locale "${currentLocale}"`);
+      return key;
+    }
+
+    if (typeof message !== 'string') return key;
+
+    // Split by ' | ' for plural forms
+    const forms = message.split(' | ').map(s => s.trim());
+    const pluralIndex = _getPluralIndex(currentLocale, count, config.pluralRules);
+    const selectedForm = forms[Math.min(pluralIndex, forms.length - 1)] || forms[forms.length - 1];
+
+    // Interpolate with count + additional params
+    return _interpolate(selectedForm, { count, ...params });
+  }
+
+  /**
+   * Check if a translation key exists
+   *
+   * @param {string} key - Translation key
+   * @param {string} [checkLocale] - Locale to check (defaults to current)
+   * @returns {boolean}
+   */
+  function te(key, checkLocale) {
+    const loc = checkLocale || locale.get();
+    return _resolveKey(messages[loc], key) !== undefined;
+  }
+
+  /**
+   * Get the raw message value (without interpolation)
+   *
+   * @param {string} key - Translation key
+   * @returns {*} Raw message value
+   */
+  function tm(key) {
+    const currentLocale = locale.get();
+    let message = _resolveKey(messages[currentLocale], key);
+
+    if (message === undefined && config.fallbackLocale) {
+      message = _resolveKey(messages[config.fallbackLocale], key);
+    }
+
+    return message;
+  }
+
+  /**
+   * Change the current locale
+   * @param {string} newLocale
+   */
+  function setLocale(newLocale) {
+    if (!messages[newLocale]) {
+      log.warn(`Locale "${newLocale}" not loaded. Available: ${getAvailableLocales().join(', ')}`);
+    }
+    locale.set(newLocale);
+  }
+
+  /**
+   * Dynamically load messages for a locale
+   *
+   * @param {string} loc - Locale code
+   * @param {Object} msgs - Message object
+   */
+  function loadMessages(loc, msgs) {
+    if (messages[loc]) {
+      // Deep merge
+      messages[loc] = _deepMerge(messages[loc], msgs);
+    } else {
+      messages[loc] = msgs;
+    }
+    log.info(`Loaded messages for locale "${loc}"`);
+  }
+
+  /**
+   * Format a number using Intl.NumberFormat
+   *
+   * @param {number} value - Number to format
+   * @param {Object} [opts] - Intl.NumberFormat options
+   * @returns {string}
+   */
+  function n(value, opts) {
+    try {
+      return new Intl.NumberFormat(locale.get(), opts).format(value);
+    } catch {
+      return String(value);
+    }
+  }
+
+  /**
+   * Format a date using Intl.DateTimeFormat
+   *
+   * @param {Date|number} value - Date to format
+   * @param {Object} [opts] - Intl.DateTimeFormat options
+   * @returns {string}
+   */
+  function d(value, opts) {
+    try {
+      return new Intl.DateTimeFormat(locale.get(), opts).format(value);
+    } catch {
+      return String(value);
+    }
+  }
+
+  /**
+   * Set this instance as the global default for useI18n()
+   */
+  function install() {
+    _defaultInstance = instance;
+  }
+
+  const instance = {
+    locale,
+    get availableLocales() { return getAvailableLocales(); },
+
+    t,
+    tc,
+    te,
+    tm,
+
+    setLocale,
+    loadMessages,
+    install,
+
+    n,
+    d,
+  };
+
+  return instance;
+}
+
+// =============================================================================
+// HOOK: useI18n
+// =============================================================================
+
+/**
+ * Get the global i18n instance (set via createI18n().install())
+ *
+ * @returns {Object} { t, tc, locale, setLocale, availableLocales }
+ */
+export function useI18n() {
+  if (!_defaultInstance) {
+    throw new I18nError(
+      'No i18n instance installed. Call createI18n().install() first.',
+      { suggestion: 'Create an i18n instance and call install() before using useI18n()' }
+    );
+  }
+
+  return {
+    t: _defaultInstance.t,
+    tc: _defaultInstance.tc,
+    te: _defaultInstance.te,
+    tm: _defaultInstance.tm,
+    locale: _defaultInstance.locale,
+    setLocale: _defaultInstance.setLocale,
+    availableLocales: _defaultInstance.availableLocales,
+    n: _defaultInstance.n,
+    d: _defaultInstance.d,
+  };
+}
+
+// =============================================================================
+// INTERNAL: Deep merge
+// =============================================================================
+
+const MAX_MERGE_DEPTH = 10;
+
+function _deepMerge(target, source, depth = 0) {
+  if (depth > MAX_MERGE_DEPTH) {
+    log.warn('Maximum nesting depth exceeded in i18n message merge');
+    return target;
+  }
+
+  const result = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    if (DANGEROUS_KEYS.has(key)) continue;
+    if (value && typeof value === 'object' && !Array.isArray(value) &&
+        result[key] && typeof result[key] === 'object' && !Array.isArray(result[key])) {
+      result[key] = _deepMerge(result[key], value, depth + 1);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+// =============================================================================
+// DEFAULT EXPORT
+// =============================================================================
+
+export default {
+  createI18n,
+  useI18n,
+  I18nError,
+};

package/runtime/index.js

@@ -60,6 +60,21 @@ export * from './lru-cache.js';
 // DOM Adapter (for SSR/testing)
 export * from './dom-adapter.js';
 
+// SSE (Server-Sent Events)
+export * from './sse.js';
+
+// Persistence adapters (IndexedDB, SessionStorage, Memory)
+export * from './persistence.js';
+
+// Animation system (Web Animations API)
+export * from './animation.js';
+
+// Internationalization (i18n)
+export * from './i18n.js';
+
+// Service worker (main thread registration)
+export * from './sw.js';
+
 // Default exports for namespace imports
 export { default as PulseCore } from './pulse.js';
 export { default as PulseDOM } from './dom.js';
@@ -75,6 +90,11 @@ export { default as PulseSSR } from './ssr.js';
 export { default as PulseA11y } from './a11y.js';
 export { default as PulseNative } from './native.js';
 export { default as PulseLogger } from './logger.js';
+export { default as PulseSSE } from './sse.js';
+export { default as PulsePersistence } from './persistence.js';
+export { default as PulseAnimation } from './animation.js';
+export { default as PulseI18n } from './i18n.js';
+export { default as PulseSW } from './sw.js';
 
 // Note: The following modules are intentionally NOT re-exported here
 // to enable tree-shaking. Import them directly when needed:

package/runtime/logger.js

@@ -382,7 +382,11 @@ export const loggers = {
   get native() { return isProduction ? noopLogger : createDevLogger('Native', {}); },
   get hmr() { return isProduction ? noopLogger : createDevLogger('HMR', {}); },
   get cli() { return isProduction ? noopLogger : createDevLogger('CLI', {}); },
-  get websocket() { return isProduction ? noopLogger : createDevLogger('WebSocket', {}); }
+  get websocket() { return isProduction ? noopLogger : createDevLogger('WebSocket', {}); },
+  get sse() { return isProduction ? noopLogger : createDevLogger('SSE', {}); },
+  get i18n() { return isProduction ? noopLogger : createDevLogger('I18n', {}); },
+  get animation() { return isProduction ? noopLogger : createDevLogger('Animation', {}); },
+  get sw() { return isProduction ? noopLogger : createDevLogger('SW', {}); }
 };
 
 export default logger;