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

package/dist/hydration-runtime.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Unified Hydration Runtime for Islands Architecture
+ *
+ * Replaces the per-strategy inline scripts with a single runtime that handles
+ * all hydration strategies. Injected once per page when islands are present.
+ *
+ * The runtime:
+ * 1. Component registry — maps names to dynamic imports
+ * 2. hydrateIsland(element) — loads component, reads props, calls hydrate/mount
+ * 3. Strategy dispatcher — sets up triggers per data-strategy attribute
+ * 4. initIslands() — processes all .stx-island:not(.hydrated) on DOMContentLoaded
+ *
+ * @module hydration-runtime
+ */
+export interface IslandMeta {
+    id: string;
+    component: string;
+    strategy: string;
+    props: Record<string, unknown>;
+}
+/**
+ * Generate the unified hydration bootstrap script.
+ *
+ * This replaces the per-island inline scripts with a single runtime
+ * that reads data-strategy attributes and sets up appropriate triggers.
+ */
+export declare function generateHydrationBootstrap(): string;
+/**
+ * Generate a component manifest script block that registers
+ * all discovered island component names with their import paths.
+ *
+ * @param islands - Map of component name to import path
+ */
+export declare function generateComponentManifest(islands: Map<string, string>): string;
+/**
+ * Extract component name from inner content of an island.
+ * Looks for PascalCase or kebab-case component tags.
+ */
+export declare function extractComponentName(content: string): string | null;
+/**
+ * Extract bound props from component content.
+ * Parses :prop="value" bindings.
+ */
+export declare function extractBoundProps(content: string, context: Record<string, unknown>): Record<string, unknown>;

package/dist/hydration-runtime.js

@@ -0,0 +1,195 @@
+export function generateHydrationBootstrap() {
+  return `<script data-stx-hydration-runtime>
+(function() {
+  'use strict';
+
+  var stxIslands = window.__stxIslands = window.__stxIslands || {
+    _registry: {},
+    _hydrated: new Set(),
+
+    register: function(name, loader) {
+      this._registry[name] = loader;
+    },
+
+    hydrateIsland: function(el) {
+      var id = el.getAttribute('data-island');
+      if (!id || this._hydrated.has(id)) return Promise.resolve();
+      this._hydrated.add(id);
+
+      var componentName = el.getAttribute('data-component');
+      var propsScript = el.querySelector('script[data-island-props="' + id + '"]');
+      var props = {};
+      if (propsScript) {
+        try { props = JSON.parse(propsScript.textContent || '{}'); }
+catch (e) {}
+      }
+
+      var loader = componentName ? this._registry[componentName] : null;
+
+      if (loader) {
+        return Promise.resolve(typeof loader === 'function' ? loader() : loader)
+          .then(function(mod) {
+            var comp = mod && mod.default ? mod.default : mod;
+            if (comp && comp.hydrate) {
+              return comp.hydrate(el, props);
+            }
+else if (comp && comp.mount) {
+              return comp.mount(el, props);
+            }
+          })
+          .then(function() {
+            el.classList.add('hydrated');
+            el.dispatchEvent(new CustomEvent('stx:hydrated', { bubbles: true }));
+          })
+          .catch(function(err) {
+            console.error('[stx] Hydration failed for island:', id, err);
+            el.classList.add('hydrated');
+            el.dispatchEvent(new CustomEvent('stx:hydrated', { bubbles: true }));
+          });
+      }
+
+      // No loader registered \u2014 just mark as hydrated (CSS-only island)
+      el.classList.add('hydrated');
+      el.dispatchEvent(new CustomEvent('stx:hydrated', { bubbles: true }));
+      return Promise.resolve();
+    },
+
+    _setupStrategy: function(el) {
+      var self = this;
+      var strategy = el.getAttribute('data-strategy') || 'load';
+
+      switch (strategy) {
+        case 'load':
+          self.hydrateIsland(el);
+          break;
+
+        case 'idle':
+          if ('requestIdleCallback' in window) {
+            requestIdleCallback(function() { self.hydrateIsland(el); }, { timeout: 2000 });
+          }
+else {
+            setTimeout(function() { self.hydrateIsland(el); }, 200);
+          }
+          break;
+
+        case 'visible':
+          if ('IntersectionObserver' in window) {
+            var rootMargin = el.getAttribute('data-root-margin') || '0px';
+            var threshold = parseFloat(el.getAttribute('data-threshold') || '0') || 0;
+            var obs = new IntersectionObserver(function(entries) {
+              entries.forEach(function(entry) {
+                if (entry.isIntersecting) {
+                  obs.disconnect();
+                  self.hydrateIsland(el);
+                }
+              });
+            }, { rootMargin: rootMargin, threshold: threshold });
+            obs.observe(el);
+          }
+else {
+            self.hydrateIsland(el);
+          }
+          break;
+
+        case 'media':
+          var mediaQuery = el.getAttribute('data-media') || '(min-width: 768px)';
+          var mq = window.matchMedia(mediaQuery);
+          if (mq.matches) {
+            self.hydrateIsland(el);
+          }
+else {
+            var handler = function(e) {
+              if (e.matches) {
+                mq.removeEventListener('change', handler);
+                self.hydrateIsland(el);
+              }
+            };
+            mq.addEventListener('change', handler);
+          }
+          break;
+
+        case 'hover':
+          var events = ['mouseenter', 'focusin', 'touchstart'];
+          var hoverHandler = function() {
+            events.forEach(function(e) { el.removeEventListener(e, hoverHandler); });
+            self.hydrateIsland(el);
+          };
+          events.forEach(function(e) {
+            el.addEventListener(e, hoverHandler, { once: true, passive: true });
+          });
+          break;
+
+        case 'event':
+          var eventName = el.getAttribute('data-event') || 'stx:activate';
+          window.addEventListener(eventName, function evtHandler(e) {
+            if (!e.detail || e.detail.id === el.getAttribute('data-island') || e.detail.id === '*') {
+              window.removeEventListener(eventName, evtHandler);
+              self.hydrateIsland(el);
+            }
+          });
+          break;
+
+        case 'only':
+          var tmpl = el.querySelector('template[data-client-content]');
+          if (tmpl) {
+            el.innerHTML = tmpl.innerHTML;
+          }
+          el.classList.add('hydrated');
+          break;
+
+        default:
+          self.hydrateIsland(el);
+      }
+    },
+
+    initIslands: function() {
+      var self = this;
+      var islands = document.querySelectorAll('.stx-island:not(.hydrated)');
+      islands.forEach(function(el) {
+        self._setupStrategy(el);
+      });
+    }
+  };
+
+  // Auto-init on DOMContentLoaded
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function() { stxIslands.initIslands(); });
+  }
+else {
+    stxIslands.initIslands();
+  }
+})();
+</script>`;
+}
+export function generateComponentManifest(islands) {
+  if (islands.size === 0)
+    return "";
+  return `<script data-stx-island-manifest>
+(function() {
+  if (!window.__stxIslands) return;
+${Array.from(islands.entries()).map(([name, importPath]) => `  window.__stxIslands.register('${name}', function() { return import('${importPath}'); });`).join(`
+`)}
+})();
+</script>`;
+}
+export function extractComponentName(content) {
+  const pascalMatch = content.match(/<([A-Z][a-zA-Z0-9]+)[\s/>]/);
+  if (pascalMatch)
+    return pascalMatch[1];
+  const kebabMatch = content.match(/<([a-z][a-z0-9]*-[a-z0-9-]+)[\s/>]/);
+  if (kebabMatch)
+    return kebabMatch[1];
+  return null;
+}
+export function extractBoundProps(content, context) {
+  const props = {}, bindingRegex = /:([a-zA-Z_][\w-]*)\s*=\s*"([^"]+)"/g;
+  let match;
+  while ((match = bindingRegex.exec(content)) !== null) {
+    const propName = match[1], expr = match[2];
+    if (expr in context)
+      props[propName] = context[expr];
+    else
+      props[propName] = expr;
+  }
+  return props;
+}

package/dist/hydration.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Serialize state for client hydration
+ * Called during server-side rendering
+ */
+export declare function serializeState(state: Partial<HydrationState>): string;
+/**
+ * Generate the state injection script for server-rendered HTML
+ */
+export declare function generateStateScript(state: Partial<HydrationState>): string;
+/**
+ * Generate event bindings data attribute
+ */
+export declare function generateEventBindings(events: EventBinding[]): string;
+/**
+ * Extract and parse state from server-rendered HTML
+ */
+export declare function extractState(): HydrationState | null;
+/**
+ * Generate the hydration runtime script for embedding in HTML
+ */
+export declare function generateHydrationScript(state?: Partial<HydrationState>): string;
+/**
+ * Get or create the hydration runtime
+ */
+export declare function getHydrationRuntime(options?: HydrationOptions): HydrationRuntime;
+/**
+ * Start hydration (convenience function)
+ */
+export declare function hydrate(options?: HydrationOptions): Promise<void>;
+/**
+ * Generate hydration CSS
+ */
+export declare function generateHydrationCSS(): string;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
+/**
+ * STX Hydration Runtime
+ *
+ * Comprehensive client-side hydration system that bridges server-rendered
+ * HTML with client-side interactivity. Similar to React's hydrateRoot or
+ * Vue's createSSRApp.
+ *
+ * ## Features
+ *
+ * - Full page hydration with state restoration
+ * - Selective/partial hydration (islands architecture)
+ * - Event handler binding from server-rendered HTML
+ * - Integration with stx reactivity system
+ * - Seamless SPA router integration
+ * - Progressive enhancement support
+ * - Error boundaries for hydration failures
+ *
+ * ## Usage
+ *
+ * Server-side (stx template):
+ * ```html
+ * <script>
+ * const count = 0
+ * const user = { name: 'Alice' }
+ * </script>
+ *
+ * <button @click="count++">Count: {{ count }}</button>
+ * <p>Hello, {{ user.name }}</p>
+ * ```
+ *
+ * The framework automatically:
+ * 1. Renders HTML on server
+ * 2. Serializes state and embeds in HTML
+ * 3. Client loads, hydrates, binds events
+ * 4. Page becomes interactive
+ *
+ * @module hydration
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface HydrationState {
+  refs: Record<string, unknown>
+  reactive: Record<string, unknown>
+  props: Record<string, unknown>
+  routeParams: Record<string, string>
+  stores: Record<string, unknown>
+  meta: {
+    title?: string
+    description?: string
+    url?: string
+  }
+  timestamp: number
+  checksum?: string
+}
+export declare interface HydrationOptions {
+  root?: string | HTMLElement
+  strict?: boolean
+  onHydrating?: () => void
+  onHydrated?: () => void
+  onError?: (error: Error) => void
+  performance?: boolean
+  timeout?: number
+}
+export declare interface EventBinding {
+  type: string
+  handler: string
+  modifiers?: string[]
+  preventDefault?: boolean
+  stopPropagation?: boolean
+}
+export declare interface ComponentHydrationConfig {
+  id: string
+  name: string
+  strategy: 'eager' | 'lazy' | 'idle' | 'visible' | 'interaction'
+  props: Record<string, unknown>
+  events: EventBinding[]
+}
+/**
+ * Main hydration class
+ */
+export declare class HydrationRuntime {
+  constructor(options?: HydrationOptions);
+  hydrate(): Promise<void>;
+  get hydrated(): boolean;
+  getState(): HydrationState | null;
+  hydrateById(componentId: string): Promise<void>;
+}
+// =============================================================================
+// Exports
+// =============================================================================
+export default {
+  HydrationRuntime,
+  serializeState,
+  generateStateScript,
+  generateHydrationScript,
+  generateHydrationCSS,
+  extractState,
+  getHydrationRuntime,
+  hydrate,
+};