@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/component-hmr.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Generate the HMR client script for browser
+ */
+export declare function generateHMRClientScript(wsPort: number): string;
+/**
+ * Generate component wrapper code for HMR support
+ */
+export declare function wrapComponentForHMR(componentId: string, componentName: string, html: string, script: string): string;
+/**
+ * Get or create global HMR handler
+ */
+export declare function getHMRHandler(config?: ComponentHMRConfig): ComponentHMRHandler;
+/**
+ * Reset global HMR handler
+ */
+export declare function resetHMRHandler(): void;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
+/**
+ * Component HMR (Hot Module Replacement)
+ *
+ * Provides React Fast Refresh / Vue HMR-style hot reloading for stx components.
+ * Updates component code without losing component state or unmounting.
+ *
+ * ## Features
+ *
+ * - State preservation during component updates
+ * - Selective component re-rendering
+ * - Error recovery with state restoration
+ * - Integration with stx reactivity system
+ * - Support for nested component updates
+ *
+ * ## Usage
+ *
+ * Component HMR is automatically enabled in development mode. No configuration needed.
+ *
+ * @module component-hmr
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface ComponentState {
+  refs: Record<string, unknown>
+  reactiveObjects: Record<string, unknown>
+  custom: Record<string, unknown>
+  timestamp: number
+}
+export declare interface ComponentInstance {
+  id: string
+  name: string
+  element: HTMLElement | null
+  state: ComponentState
+  isMounted: boolean
+  props: Record<string, unknown>
+  children: Map<string, ComponentInstance>
+  setup?: () => void | Promise<void>
+  render?: () => string
+  cleanup?: () => void
+}
+export declare interface HMRUpdate {
+  file: string
+  code: string
+  type: 'full' | 'partial' | 'style'
+  timestamp: number
+}
+export declare interface ComponentHMRConfig {
+  preserveState?: boolean
+  maxStateAge?: number
+  errorRecovery?: boolean
+  verbose?: boolean
+  serializeState?: (instance: ComponentInstance) => ComponentState
+  deserializeState?: (state: ComponentState, instance: ComponentInstance) => void
+}
+/**
+ * Global registry of component instances for HMR
+ */
+declare class ComponentRegistry {
+  constructor(config?: ComponentHMRConfig);
+  register(instance: ComponentInstance): void;
+  unregister(instanceId: string): void;
+  getInstancesByFile(file: string): ComponentInstance[];
+  getInstance(id: string): ComponentInstance | undefined;
+  captureState(instanceId: string): void;
+  restoreState(instanceId: string): boolean;
+  getAllInstances(): ComponentInstance[];
+  clear(): void;
+}
+/**
+ * HMR Handler - processes component updates
+ */
+export declare class ComponentHMRHandler {
+  constructor(config?: ComponentHMRConfig);
+  register(instance: ComponentInstance): void;
+  unregister(instanceId: string): void;
+  handleUpdate(update: HMRUpdate): Promise<void>;
+  getRegistry(): ComponentRegistry;
+  refresh(componentName: string): Promise<void>;
+}
+// =============================================================================
+// Exports
+// =============================================================================
+export default {
+  ComponentHMRHandler,
+  getHMRHandler,
+  resetHMRHandler,
+  generateHMRClientScript,
+  wrapComponentForHMR,
+};

package/dist/component-hmr.js

@@ -0,0 +1,585 @@
+class ComponentRegistry {
+  instances = new Map;
+  componentsByFile = new Map;
+  stateSnapshots = new Map;
+  config;
+  constructor(config = {}) {
+    this.config = {
+      preserveState: config.preserveState ?? !0,
+      maxStateAge: config.maxStateAge ?? 30000,
+      errorRecovery: config.errorRecovery ?? !0,
+      verbose: config.verbose ?? !1,
+      serializeState: config.serializeState ?? this.defaultSerializeState.bind(this),
+      deserializeState: config.deserializeState ?? this.defaultDeserializeState.bind(this)
+    };
+  }
+  register(instance) {
+    this.instances.set(instance.id, instance);
+    if (!this.componentsByFile.has(instance.name))
+      this.componentsByFile.set(instance.name, new Set);
+    this.componentsByFile.get(instance.name).add(instance.id);
+    if (this.config.verbose)
+      console.log(`[HMR] Registered component: ${instance.name} (${instance.id})`);
+  }
+  unregister(instanceId) {
+    const instance = this.instances.get(instanceId);
+    if (!instance)
+      return;
+    this.componentsByFile.get(instance.name)?.delete(instanceId);
+    if (this.componentsByFile.get(instance.name)?.size === 0)
+      this.componentsByFile.delete(instance.name);
+    this.stateSnapshots.delete(instanceId);
+    instance.cleanup?.();
+    this.instances.delete(instanceId);
+    if (this.config.verbose)
+      console.log(`[HMR] Unregistered component: ${instance.name} (${instanceId})`);
+  }
+  getInstancesByFile(file) {
+    const ids = this.componentsByFile.get(file) || new Set;
+    return Array.from(ids).map((id) => this.instances.get(id)).filter(Boolean);
+  }
+  getInstance(id) {
+    return this.instances.get(id);
+  }
+  captureState(instanceId) {
+    const instance = this.instances.get(instanceId);
+    if (!instance || !this.config.preserveState)
+      return;
+    const state = this.config.serializeState(instance);
+    this.stateSnapshots.set(instanceId, state);
+    if (this.config.verbose)
+      console.log(`[HMR] Captured state for: ${instance.name}`);
+  }
+  restoreState(instanceId) {
+    const instance = this.instances.get(instanceId), state = this.stateSnapshots.get(instanceId);
+    if (!instance || !state || !this.config.preserveState)
+      return !1;
+    if (Date.now() - state.timestamp > this.config.maxStateAge) {
+      this.stateSnapshots.delete(instanceId);
+      if (this.config.verbose)
+        console.log(`[HMR] State expired for: ${instance.name}`);
+      return !1;
+    }
+    try {
+      this.config.deserializeState(state, instance);
+      if (this.config.verbose)
+        console.log(`[HMR] Restored state for: ${instance.name}`);
+      return !0;
+    } catch (error) {
+      console.error(`[HMR] Failed to restore state for ${instance.name}:`, error);
+      return !1;
+    }
+  }
+  defaultSerializeState(instance) {
+    const refs = {}, reactiveObjects = {};
+    if (instance.element)
+      instance.element.querySelectorAll("[data-stx-ref]").forEach((el) => {
+        const refName = el.getAttribute("data-stx-ref"), refValue = el.getAttribute("data-stx-value");
+        if (refName && refValue)
+          try {
+            refs[refName] = JSON.parse(refValue);
+          } catch {
+            refs[refName] = refValue;
+          }
+      });
+    return {
+      refs,
+      reactiveObjects,
+      custom: instance.state?.custom || {},
+      timestamp: Date.now()
+    };
+  }
+  defaultDeserializeState(state, instance) {
+    if (instance.element)
+      Object.entries(state.refs).forEach(([name, value]) => {
+        const el = instance.element.querySelector(`[data-stx-ref="${name}"]`);
+        if (el) {
+          el.setAttribute("data-stx-value", JSON.stringify(value));
+          el.dispatchEvent(new CustomEvent("stx:state-restored", {
+            detail: { name, value },
+            bubbles: !0
+          }));
+        }
+      });
+    instance.state = { ...state, timestamp: Date.now() };
+  }
+  getAllInstances() {
+    return Array.from(this.instances.values());
+  }
+  clear() {
+    for (const instance of this.instances.values())
+      instance.cleanup?.();
+    this.instances.clear();
+    this.componentsByFile.clear();
+    this.stateSnapshots.clear();
+  }
+}
+
+export class ComponentHMRHandler {
+  registry;
+  config;
+  pendingUpdates = new Map;
+  updateQueue = Promise.resolve();
+  constructor(config = {}) {
+    this.config = {
+      preserveState: config.preserveState ?? !0,
+      maxStateAge: config.maxStateAge ?? 30000,
+      errorRecovery: config.errorRecovery ?? !0,
+      verbose: config.verbose ?? !1,
+      serializeState: config.serializeState ?? (() => ({
+        refs: {},
+        reactiveObjects: {},
+        custom: {},
+        timestamp: Date.now()
+      })),
+      deserializeState: config.deserializeState ?? (() => {})
+    };
+    this.registry = new ComponentRegistry(this.config);
+  }
+  register(instance) {
+    this.registry.register(instance);
+  }
+  unregister(instanceId) {
+    this.registry.unregister(instanceId);
+  }
+  async handleUpdate(update) {
+    this.updateQueue = this.updateQueue.then(() => this.processUpdate(update));
+    return this.updateQueue;
+  }
+  async processUpdate(update) {
+    const instances = this.registry.getInstancesByFile(update.file);
+    if (instances.length === 0) {
+      if (this.config.verbose)
+        console.log(`[HMR] No instances found for: ${update.file}`);
+      return;
+    }
+    if (this.config.verbose)
+      console.log(`[HMR] Updating ${instances.length} instance(s) of: ${update.file}`);
+    for (const instance of instances)
+      await this.updateInstance(instance, update);
+    if (typeof window < "u" && typeof window.dispatchEvent === "function")
+      window.dispatchEvent(new CustomEvent("stx:hmr-update", {
+        detail: { file: update.file, count: instances.length }
+      }));
+  }
+  async updateInstance(instance, update) {
+    this.registry.captureState(instance.id);
+    let errorOccurred = !1;
+    const previousHTML = instance.element?.innerHTML || "";
+    try {
+      instance.element?.dispatchEvent(new CustomEvent("stx:before-hmr-update", {
+        bubbles: !0
+      }));
+      instance.cleanup?.();
+      if (update.type === "style")
+        await this.updateStyles(instance, update);
+      else
+        await this.updateComponent(instance, update);
+      const stateRestored = this.registry.restoreState(instance.id);
+      if (!stateRestored && instance.setup)
+        await instance.setup();
+      instance.element?.dispatchEvent(new CustomEvent("stx:after-hmr-update", {
+        detail: { stateRestored },
+        bubbles: !0
+      }));
+    } catch (error) {
+      errorOccurred = !0;
+      console.error(`[HMR] Error updating component ${instance.name}:`, error);
+      if (this.config.errorRecovery) {
+        if (instance.element && previousHTML) {
+          instance.element.innerHTML = previousHTML;
+          console.log(`[HMR] Recovered previous state for: ${instance.name}`);
+        }
+        instance.element?.dispatchEvent(new CustomEvent("stx:hmr-error", {
+          detail: { error },
+          bubbles: !0
+        }));
+      }
+    }
+    if (!errorOccurred && this.config.verbose)
+      console.log(`[HMR] Successfully updated: ${instance.name}`);
+  }
+  async updateComponent(instance, update) {
+    if (!instance.element)
+      return;
+    const { html, script } = this.parseComponentCode(update.code);
+    if (html)
+      instance.element.innerHTML = html;
+    if (script)
+      await this.executeScript(script, instance);
+    if (instance.render)
+      instance.element.innerHTML = instance.render();
+    this.reinitializeInteractivity(instance);
+  }
+  async updateStyles(instance, update) {
+    if (!instance.element)
+      return;
+    const styleMatch = update.code.match(/<style\b[^>]*>([\s\S]*?)<\/style>/i);
+    if (!styleMatch)
+      return;
+    const newStyles = styleMatch[1], componentId = instance.id;
+    let styleEl = document.querySelector(`style[data-stx-component="${componentId}"]`);
+    if (!styleEl) {
+      styleEl = document.createElement("style");
+      styleEl.setAttribute("data-stx-component", componentId);
+      document.head.appendChild(styleEl);
+    }
+    styleEl.textContent = newStyles;
+    if (this.config.verbose)
+      console.log(`[HMR] Updated styles for: ${instance.name}`);
+  }
+  parseComponentCode(code) {
+    let html = code, script = "", style = "";
+    const scriptMatch = code.match(/<script\b[^>]*>([\s\S]*?)<\/script>/i);
+    if (scriptMatch) {
+      script = scriptMatch[1];
+      html = html.replace(scriptMatch[0], "");
+    }
+    const styleMatch = code.match(/<style\b[^>]*>([\s\S]*?)<\/style>/i);
+    if (styleMatch) {
+      style = styleMatch[1];
+      html = html.replace(styleMatch[0], "");
+    }
+    return { html: html.trim(), script: script.trim(), style: style.trim() };
+  }
+  async executeScript(script, instance) {
+    try {
+      const context = {
+        element: instance.element,
+        props: instance.props,
+        ...typeof window < "u" ? window.stx : {}
+      }, wrappedScript = `
+        return (async function() {
+          ${script}
+        })()
+      `;
+      await Function(...Object.keys(context), wrappedScript)(...Object.values(context));
+    } catch (error) {
+      console.error("[HMR] Script execution error:", error);
+      throw error;
+    }
+  }
+  reinitializeInteractivity(instance) {
+    if (!instance.element)
+      return;
+    instance.element.querySelectorAll("[data-stx-events]").forEach((el) => {
+      const eventsStr = el.getAttribute("data-stx-events");
+      if (!eventsStr)
+        return;
+      try {
+        const events = JSON.parse(eventsStr);
+        for (const [eventName, handlerName] of Object.entries(events))
+          if (typeof window < "u" && window.stx?.[handlerName])
+            el.addEventListener(eventName, window.stx[handlerName]);
+      } catch {}
+    });
+    instance.element.dispatchEvent(new CustomEvent("stx:reinitialize", {
+      bubbles: !0
+    }));
+  }
+  getRegistry() {
+    return this.registry;
+  }
+  async refresh(componentName) {
+    const instances = this.registry.getInstancesByFile(componentName);
+    for (const instance of instances)
+      if (instance.render && instance.element) {
+        this.registry.captureState(instance.id);
+        instance.element.innerHTML = instance.render();
+        this.registry.restoreState(instance.id);
+        this.reinitializeInteractivity(instance);
+      }
+  }
+}
+export function generateHMRClientScript(wsPort) {
+  return `
+<script data-stx-hmr-client>
+(function() {
+  'use strict';
+
+  // Component registry
+  const __instances = new Map();
+  const __stateSnapshots = new Map();
+
+  // Register a component
+  function registerComponent(id, name, element, props, setup, render, cleanup) {
+    __instances.set(id, {
+      id,
+      name,
+      element,
+      props: props || {},
+      setup,
+      render,
+      cleanup,
+      state: { refs: {}, reactiveObjects: {}, custom: {}, timestamp: Date.now() },
+      isMounted: true,
+      children: new Map()
+    });
+
+    console.log('[HMR] Registered:', name, '(' + id + ')');
+  }
+
+  // Unregister a component
+  function unregisterComponent(id) {
+    const instance = __instances.get(id);
+    if (instance) {
+      instance.cleanup?.();
+      __instances.delete(id);
+      __stateSnapshots.delete(id);
+    }
+  }
+
+  // Capture component state
+  function captureState(id) {
+    const instance = __instances.get(id);
+    if (!instance || !instance.element) return;
+
+    const state = { refs: {}, reactiveObjects: {}, custom: {}, timestamp: Date.now() };
+
+    // Capture form values
+    instance.element.querySelectorAll('input, textarea, select').forEach(el => {
+      if (el.name || el.id) {
+        state.refs[el.name || el.id] = el.type === 'checkbox' ? el.checked : el.value;
+      }
+    });
+
+    // Capture data-stx-state attributes
+    instance.element.querySelectorAll('[data-stx-state]').forEach(el => {
+      const key = el.getAttribute('data-stx-state');
+      const value = el.getAttribute('data-stx-value');
+      if (key && value) {
+        try { state.custom[key] = JSON.parse(value); }
+        catch { state.custom[key] = value; }
+      }
+    });
+
+    __stateSnapshots.set(id, state);
+  }
+
+  // Restore component state
+  function restoreState(id) {
+    const instance = __instances.get(id);
+    const state = __stateSnapshots.get(id);
+    if (!instance || !state || !instance.element) return false;
+
+    // Restore form values
+    Object.entries(state.refs).forEach(([name, value]) => {
+      const el = instance.element.querySelector('[name="' + name + '"], #' + name);
+      if (el) {
+        if (el.type === 'checkbox') el.checked = value;
+        else el.value = value;
+      }
+    });
+
+    // Restore data-stx-state
+    Object.entries(state.custom).forEach(([key, value]) => {
+      const el = instance.element.querySelector('[data-stx-state="' + key + '"]');
+      if (el) {
+        el.setAttribute('data-stx-value', JSON.stringify(value));
+        el.dispatchEvent(new CustomEvent('stx:state-restored', { detail: { key, value } }));
+      }
+    });
+
+    return true;
+  }
+
+  // Handle HMR update
+  async function handleUpdate(data) {
+    const { file, code, type } = data;
+
+    // Find matching instances
+    const instances = [];
+    __instances.forEach(inst => {
+      if (inst.name === file || file.endsWith(inst.name + '.stx')) {
+        instances.push(inst);
+      }
+    });
+
+    if (instances.length === 0) {
+      console.log('[HMR] No instances for:', file, '- doing full reload');
+      window.location.reload();
+      return;
+    }
+
+    console.log('[HMR] Updating', instances.length, 'instance(s) of:', file);
+
+    for (const instance of instances) {
+      try {
+        // Capture state
+        captureState(instance.id);
+
+        // Run cleanup
+        instance.cleanup?.();
+
+        // Style-only update
+        if (type === 'style') {
+          const styleMatch = code.match(/<style[^>]*>([\\s\\S]*?)<\\/style>/i);
+          if (styleMatch) {
+            let styleEl = document.querySelector('style[data-stx-component="' + instance.id + '"]');
+            if (!styleEl) {
+              styleEl = document.createElement('style');
+              styleEl.setAttribute('data-stx-component', instance.id);
+              document.head.appendChild(styleEl);
+            }
+            styleEl.textContent = styleMatch[1];
+          }
+          continue;
+        }
+
+        // Full update - extract and apply HTML
+        let html = code;
+        html = html.replace(/<script[^>]*>[\\s\\S]*?<\\/script>/gi, '');
+        html = html.replace(/<style[^>]*>[\\s\\S]*?<\\/style>/gi, '');
+        html = html.trim();
+
+        if (instance.element && html) {
+          instance.element.innerHTML = html;
+        }
+
+        // Re-run setup
+        if (instance.setup) {
+          await instance.setup();
+        }
+
+        // Restore state
+        restoreState(instance.id);
+
+        // Dispatch events
+        instance.element?.dispatchEvent(new CustomEvent('stx:hmr-updated', { bubbles: true }));
+
+        console.log('[HMR] Updated:', instance.name);
+      }
+catch (error) {
+        console.error('[HMR] Update failed for', instance.name, error);
+        // Restore previous state on error
+        restoreState(instance.id);
+      }
+    }
+
+    window.dispatchEvent(new CustomEvent('stx:hmr-complete', {
+      detail: { file, count: instances.length }
+    }));
+  }
+
+  // Connect to HMR WebSocket
+  let ws = null;
+  let reconnectTimer = null;
+
+  function connect() {
+    try {
+      ws = new WebSocket('ws://' + window.location.hostname + ':${wsPort}');
+
+      ws.onopen = () => {
+        console.log('[HMR] Connected');
+        clearTimeout(reconnectTimer);
+      };
+
+      ws.onmessage = async (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          if (data.type === 'component-update') {
+            await handleUpdate(data);
+          }
+else if (data.type === 'reload') {
+            // Fall back to full reload
+            window.location.reload();
+          }
+        }
+catch (e) {
+          console.error('[HMR] Message error:', e);
+        }
+      };
+
+      ws.onclose = () => {
+        ws = null;
+        reconnectTimer = setTimeout(connect, 1000);
+      };
+    }
+catch (e) {
+      reconnectTimer = setTimeout(connect, 1000);
+    }
+  }
+
+  // Initialize
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', connect);
+  }
+else {
+    connect();
+  }
+
+  // Expose API
+  window.__stxHMR = {
+    register: registerComponent,
+    unregister: unregisterComponent,
+    captureState,
+    restoreState,
+    refresh: (name) => handleUpdate({ file: name, code: '', type: 'refresh' }),
+    instances: () => Array.from(__instances.values())
+  };
+})();
+</script>
+`;
+}
+export function wrapComponentForHMR(componentId, componentName, html, script) {
+  return `
+<div data-stx-component="${componentId}" data-stx-name="${componentName}">
+  ${html}
+</div>
+<script>
+(function() {
+  const __id = '${componentId}';
+  const __name = '${componentName}';
+  const __element = document.querySelector('[data-stx-component="${componentId}"]');
+
+  let __cleanup = null;
+
+  async function __setup() {
+    ${script}
+  }
+
+  function __render() {
+    return __element?.innerHTML || '';
+  }
+
+  // Register with HMR
+  if (window.__stxHMR) {
+    window.__stxHMR.register(__id, __name, __element, {}, __setup, __render, () => __cleanup?.());
+  }
+
+  // Run setup
+  __setup();
+
+  // Cleanup on removal
+  const observer = new MutationObserver((mutations) => {
+    if (!document.body.contains(__element)) {
+      observer.disconnect();
+      if (window.__stxHMR) {
+        window.__stxHMR.unregister(__id);
+      }
+    }
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+})();
+</script>
+`;
+}
+let globalHMRHandler = null;
+export function getHMRHandler(config) {
+  if (!globalHMRHandler)
+    globalHMRHandler = new ComponentHMRHandler(config);
+  return globalHMRHandler;
+}
+export function resetHMRHandler() {
+  if (globalHMRHandler) {
+    globalHMRHandler.getRegistry().clear();
+    globalHMRHandler = null;
+  }
+}
+export default {
+  ComponentHMRHandler,
+  getHMRHandler,
+  resetHMRHandler,
+  generateHMRClientScript,
+  wrapComponentForHMR
+};