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

package/dist/partial-hydration.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Partial Hydration Module (Islands Architecture)
+ *
+ * Enables selective hydration of interactive components, leaving static
+ * content as plain HTML. This dramatically reduces JavaScript bundle size
+ * and improves page load performance.
+ *
+ * Hydration Strategies:
+ * - @client:load - Hydrate immediately on page load
+ * - @client:idle - Hydrate when browser is idle (requestIdleCallback)
+ * - @client:visible - Hydrate when component enters viewport (IntersectionObserver)
+ * - @client:media - Hydrate when media query matches
+ * - @client:only - Only render on client (no SSR)
+ * - @client:hover - Hydrate on first hover/focus
+ * - @client:event - Hydrate on custom event
+ *
+ * @example
+ * ```html
+ * @client:visible(rootMargin: '100px')
+ *   <InteractiveCarousel :items="items" />
+ * @endclient
+ * ```
+ */
+export type HydrationStrategy = 'load' | 'idle' | 'visible' | 'media' | 'only' | 'hover' | 'event';
+export interface HydrationOptions {
+    /** Strategy for when to hydrate */
+    strategy: HydrationStrategy;
+    /** Priority for idle hydration (default: 'low') */
+    priority?: 'high' | 'low';
+    /** Root margin for intersection observer (visible strategy) */
+    rootMargin?: string;
+    /** Threshold for intersection observer */
+    threshold?: number | number[];
+    /** Media query string (media strategy) */
+    media?: string;
+    /** Event name to listen for (event strategy) */
+    event?: string;
+    /** Timeout in ms before forcing hydration */
+    timeout?: number;
+    /** Placeholder content while loading */
+    placeholder?: string;
+    /** Whether to preserve server HTML until hydration */
+    preserveServerHTML?: boolean;
+}
+export interface IslandComponent {
+    /** Unique identifier for the island */
+    id: string;
+    /** Component name or path */
+    component: string;
+    /** Props to pass to the component */
+    props: Record<string, unknown>;
+    /** Hydration options */
+    options: HydrationOptions;
+    /** Server-rendered HTML */
+    serverHTML: string;
+    /** Whether the island has been hydrated */
+    hydrated: boolean;
+}
+export interface IslandRegistry {
+    /** All registered islands */
+    islands: Map<string, IslandComponent>;
+    /** Register an island */
+    register: (island: IslandComponent) => void;
+    /** Get an island by ID */
+    get: (id: string) => IslandComponent | undefined;
+    /** Hydrate an island */
+    hydrate: (id: string) => Promise<void>;
+    /** Hydrate all islands */
+    hydrateAll: () => Promise<void>;
+}
+/**
+ * Create a registry for managing island components
+ */
+export declare function createIslandRegistry(): IslandRegistry;
+/**
+ * Process all partial hydration directives
+ */
+export declare function processPartialHydrationDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Generate CSS for partial hydration
+ */
+export declare function generatePartialHydrationCSS(): string;
+/**
+ * Manually hydrate an island by ID
+ */
+export declare function hydrateIsland(islandId: string): void;
+/**
+ * Hydrate all islands with a specific strategy
+ */
+export declare function hydrateByStrategy(strategy: HydrationStrategy): void;
+/**
+ * Hydrate all pending islands
+ */
+export declare function hydrateAll(): void;
+/**
+ * Check if an island is hydrated
+ */
+export declare function isHydrated(islandId: string): boolean;
+/**
+ * Wait for an island to be hydrated
+ */
+export declare function onHydrated(islandId: string): Promise<void>;
+/**
+ * Mark content as static (never hydrate)
+ */
+export declare function processStaticDirectives(template: string): string;
+/**
+ * Generate island manifest for client
+ */
+export declare function generateIslandManifest(islands: IslandComponent[]): string;
+declare const _default: {
+    processPartialHydrationDirectives: typeof processPartialHydrationDirectives;
+    processStaticDirectives: typeof processStaticDirectives;
+    generatePartialHydrationCSS: typeof generatePartialHydrationCSS;
+    generateIslandManifest: typeof generateIslandManifest;
+    createIslandRegistry: typeof createIslandRegistry;
+    hydrateIsland: typeof hydrateIsland;
+    hydrateByStrategy: typeof hydrateByStrategy;
+    hydrateAll: typeof hydrateAll;
+    isHydrated: typeof isHydrated;
+    onHydrated: typeof onHydrated;
+};
+export default _default;

package/dist/partial-hydration.js

@@ -0,0 +1,427 @@
+import { generateHydrationBootstrap, extractComponentName, extractBoundProps } from "./hydration-runtime.js";
+export function createIslandRegistry() {
+  const islands = new Map;
+  return {
+    islands,
+    register(island) {
+      islands.set(island.id, island);
+    },
+    get(id) {
+      return islands.get(id);
+    },
+    async hydrate(id) {
+      const island = islands.get(id);
+      if (!island || island.hydrated)
+        return;
+      island.hydrated = !0;
+      if (typeof window < "u" && typeof window.dispatchEvent === "function")
+        window.dispatchEvent(new CustomEvent("stx:hydrate", {
+          detail: { id, component: island.component }
+        }));
+    },
+    async hydrateAll() {
+      const promises = Array.from(islands.values()).filter((island) => !island.hydrated).map((island) => this.hydrate(island.id));
+      await Promise.all(promises);
+    }
+  };
+}
+function generateLoadHydration(islandId) {
+  return `
+    <script data-hydrate="${islandId}">
+      (function() {
+        const island = document.querySelector('[data-island="${islandId}"]');
+        if (!island) return;
+
+        // Immediately hydrate
+        island.classList.add('hydrated');
+        island.dispatchEvent(new CustomEvent('stx:hydrated', { bubbles: true }));
+      })();
+    </script>
+  `;
+}
+function generateIdleHydration(islandId, options) {
+  const timeout = options.timeout || 2000, priority = options.priority || "low";
+  return `
+    <script data-hydrate="${islandId}">
+      (function() {
+        const island = document.querySelector('[data-island="${islandId}"]');
+        if (!island) return;
+
+        function hydrate() {
+          if (island.classList.contains('hydrated')) return;
+          island.classList.add('hydrated');
+          island.dispatchEvent(new CustomEvent('stx:hydrated', { bubbles: true }));
+        }
+
+        if ('requestIdleCallback' in window) {
+          const idleOptions = { timeout: ${timeout} };
+          ${priority === "high" ? "requestIdleCallback(hydrate, idleOptions);" : `
+          // Low priority: wait for multiple idle periods
+          let idleCount = 0;
+          function waitForIdle() {
+            requestIdleCallback((deadline) => {
+              if (deadline.didTimeout || ++idleCount >= 2) {
+                hydrate();
+              }
+else {
+                waitForIdle();
+              }
+            }, idleOptions);
+          }
+          waitForIdle();
+          `}
+        }
+else {
+          // Fallback for browsers without requestIdleCallback
+          setTimeout(hydrate, ${timeout});
+        }
+      })();
+    </script>
+  `;
+}
+function generateVisibleHydration(islandId, options) {
+  const rootMargin = options.rootMargin || "0px", threshold = options.threshold || 0;
+  return `
+    <script data-hydrate="${islandId}">
+      (function() {
+        const island = document.querySelector('[data-island="${islandId}"]');
+        if (!island) return;
+
+        function hydrate() {
+          if (island.classList.contains('hydrated')) return;
+          island.classList.add('hydrated');
+          island.dispatchEvent(new CustomEvent('stx:hydrated', { bubbles: true }));
+        }
+
+        if ('IntersectionObserver' in window) {
+          const observer = new IntersectionObserver((entries) => {
+            entries.forEach((entry) => {
+              if (entry.isIntersecting) {
+                observer.disconnect();
+                hydrate();
+              }
+            });
+          }, {
+            rootMargin: '${rootMargin}',
+            threshold: ${JSON.stringify(threshold)}
+          });
+
+          observer.observe(island);
+        }
+else {
+          // Fallback: hydrate on load
+          hydrate();
+        }
+      })();
+    </script>
+  `;
+}
+function generateMediaHydration(islandId, options) {
+  const media = options.media || "(min-width: 768px)";
+  return `
+    <script data-hydrate="${islandId}">
+      (function() {
+        const island = document.querySelector('[data-island="${islandId}"]');
+        if (!island) return;
+
+        function hydrate() {
+          if (island.classList.contains('hydrated')) return;
+          island.classList.add('hydrated');
+          island.dispatchEvent(new CustomEvent('stx:hydrated', { bubbles: true }));
+        }
+
+        const mediaQuery = window.matchMedia('${media}');
+
+        function handleMediaChange(e) {
+          if (e.matches) {
+            mediaQuery.removeEventListener('change', handleMediaChange);
+            hydrate();
+          }
+        }
+
+        if (mediaQuery.matches) {
+          hydrate();
+        }
+else {
+          mediaQuery.addEventListener('change', handleMediaChange);
+        }
+      })();
+    </script>
+  `;
+}
+function generateHoverHydration(islandId) {
+  return `
+    <script data-hydrate="${islandId}">
+      (function() {
+        const island = document.querySelector('[data-island="${islandId}"]');
+        if (!island) return;
+
+        function hydrate() {
+          if (island.classList.contains('hydrated')) return;
+          island.classList.add('hydrated');
+          island.dispatchEvent(new CustomEvent('stx:hydrated', { bubbles: true }));
+        }
+
+        // Hydrate on first interaction
+        const events = ['mouseenter', 'focusin', 'touchstart'];
+        const handler = () => {
+          events.forEach(e => island.removeEventListener(e, handler));
+          hydrate();
+        };
+
+        events.forEach(e => island.addEventListener(e, handler, { once: true, passive: true }));
+      })();
+    </script>
+  `;
+}
+function generateEventHydration(islandId, options) {
+  const eventName = options.event || "stx:activate";
+  return `
+    <script data-hydrate="${islandId}">
+      (function() {
+        const island = document.querySelector('[data-island="${islandId}"]');
+        if (!island) return;
+
+        function hydrate() {
+          if (island.classList.contains('hydrated')) return;
+          island.classList.add('hydrated');
+          island.dispatchEvent(new CustomEvent('stx:hydrated', { bubbles: true }));
+        }
+
+        // Listen for custom event
+        window.addEventListener('${eventName}', function handler(e) {
+          if (!e.detail || e.detail.id === '${islandId}' || e.detail.id === '*') {
+            window.removeEventListener('${eventName}', handler);
+            hydrate();
+          }
+        });
+      })();
+    </script>
+  `;
+}
+export function processPartialHydrationDirectives(template, context = {}, _filePath) {
+  let result = template, hasIslands = !1;
+  const hasClientDirectives = /@client:(load|idle|visible|media|only|hover|event)/i.test(template);
+  result = processClientDirective(result, "load", context);
+  result = processClientDirective(result, "idle", context);
+  result = processClientDirective(result, "visible", context);
+  result = processClientDirective(result, "media", context);
+  result = processClientOnly(result);
+  result = processClientDirective(result, "hover", context);
+  result = processClientDirective(result, "event", context);
+  hasIslands = hasClientDirectives && result !== template;
+  if (hasIslands)
+    result += `
+` + generateHydrationBootstrap();
+  return result;
+}
+function processClientDirective(template, strategy, _context) {
+  const regex = new RegExp(`@client:${strategy}(?:\\s*\\(([^)]*)\\))?\\s*([\\s\\S]*?)@endclient`, "gi");
+  return template.replace(regex, (_, optionsStr, content) => {
+    let options = { strategy };
+    if (optionsStr)
+      try {
+        const optionPairs = optionsStr.split(",").map((s) => s.trim());
+        for (const pair of optionPairs) {
+          const [key, value] = pair.split(":").map((s) => s.trim());
+          if (key && value) {
+            const cleanValue = value.replace(/^['"]|['"]$/g, "");
+            options[key] = cleanValue;
+          }
+        }
+      } catch {}
+    const islandId = `island-${Math.random().toString(36).substring(2, 9)}`, componentName = extractComponentName(content.trim()), boundProps = extractBoundProps(content.trim(), _context), dataAttrs = [];
+    if (options.rootMargin)
+      dataAttrs.push(`data-root-margin="${options.rootMargin}"`);
+    if (options.threshold !== void 0)
+      dataAttrs.push(`data-threshold="${options.threshold}"`);
+    if (options.media)
+      dataAttrs.push(`data-media="${options.media}"`);
+    if (options.event)
+      dataAttrs.push(`data-event="${options.event}"`);
+    if (componentName)
+      dataAttrs.push(`data-component="${componentName}"`);
+    const propsBlock = Object.keys(boundProps).length > 0 ? `
+  <script type="application/json" data-island-props="${islandId}">${JSON.stringify(boundProps)}</script>` : "";
+    let hydrationScript = "";
+    switch (strategy) {
+      case "load":
+        hydrationScript = generateLoadHydration(islandId);
+        break;
+      case "idle":
+        hydrationScript = generateIdleHydration(islandId, options);
+        break;
+      case "visible":
+        hydrationScript = generateVisibleHydration(islandId, options);
+        break;
+      case "media":
+        hydrationScript = generateMediaHydration(islandId, options);
+        break;
+      case "hover":
+        hydrationScript = generateHoverHydration(islandId);
+        break;
+      case "event":
+        hydrationScript = generateEventHydration(islandId, options);
+        break;
+    }
+    return `
+      <div data-island="${islandId}"
+           data-strategy="${strategy}"
+           ${dataAttrs.join(`
+           `)}
+           class="stx-island"
+           style="contents;">
+        ${content.trim()}${propsBlock}
+      </div>
+      ${hydrationScript}
+    `;
+  });
+}
+function processClientOnly(template) {
+  const regex = /@client:only\s*([\s\S]*?)@endclient/gi;
+  return template.replace(regex, (_, content) => {
+    const islandId = `island-only-${Math.random().toString(36).substring(2, 9)}`;
+    return `
+      <div data-island="${islandId}"
+           data-strategy="only"
+           class="stx-island stx-client-only">
+        <!-- Client-only content will be rendered here -->
+        <template data-client-content>${content.trim()}</template>
+      </div>
+      <script data-hydrate="${islandId}">
+        (function() {
+          const island = document.querySelector('[data-island="${islandId}"]');
+          if (!island) return;
+
+          const template = island.querySelector('template[data-client-content]');
+          if (template) {
+            island.innerHTML = template.innerHTML;
+            island.classList.add('hydrated');
+          }
+        })();
+      </script>
+    `;
+  });
+}
+export function generatePartialHydrationCSS() {
+  return `
+    /* Island base styles */
+    .stx-island {
+      display: contents;
+    }
+
+    /* Pre-hydration state */
+    .stx-island:not(.hydrated) {
+      /* Optional: add loading indicator */
+    }
+
+    /* Hydrated state */
+    .stx-island.hydrated {
+      /* Island is now interactive */
+    }
+
+    /* Client-only placeholder */
+    .stx-client-only:not(.hydrated) {
+      min-height: 50px;
+      background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+      background-size: 200% 100%;
+      animation: island-shimmer 1.5s infinite;
+    }
+
+    @keyframes island-shimmer {
+      0% { background-position: 200% 0; }
+      100% { background-position: -200% 0; }
+    }
+
+    /* Hydration transition */
+    .stx-island {
+      transition: opacity 0.2s ease-out;
+    }
+
+    .stx-island:not(.hydrated) {
+      opacity: 0.7;
+    }
+
+    .stx-island.hydrated {
+      opacity: 1;
+    }
+  `;
+}
+export function hydrateIsland(islandId) {
+  if (typeof window > "u")
+    return;
+  const island = document.querySelector(`[data-island="${islandId}"]`);
+  if (!island || island.classList.contains("hydrated"))
+    return;
+  island.classList.add("hydrated");
+  island.dispatchEvent(new CustomEvent("stx:hydrated", { bubbles: !0 }));
+}
+export function hydrateByStrategy(strategy) {
+  if (typeof window > "u")
+    return;
+  document.querySelectorAll(`[data-strategy="${strategy}"]:not(.hydrated)`).forEach((island) => {
+    island.classList.add("hydrated");
+    island.dispatchEvent(new CustomEvent("stx:hydrated", { bubbles: !0 }));
+  });
+}
+export function hydrateAll() {
+  if (typeof window > "u")
+    return;
+  document.querySelectorAll(".stx-island:not(.hydrated)").forEach((island) => {
+    island.classList.add("hydrated");
+    island.dispatchEvent(new CustomEvent("stx:hydrated", { bubbles: !0 }));
+  });
+}
+export function isHydrated(islandId) {
+  if (typeof window > "u")
+    return !1;
+  return document.querySelector(`[data-island="${islandId}"]`)?.classList.contains("hydrated") ?? !1;
+}
+export function onHydrated(islandId) {
+  return new Promise((resolve) => {
+    if (typeof window > "u") {
+      resolve();
+      return;
+    }
+    const island = document.querySelector(`[data-island="${islandId}"]`);
+    if (!island) {
+      resolve();
+      return;
+    }
+    if (island.classList.contains("hydrated")) {
+      resolve();
+      return;
+    }
+    island.addEventListener("stx:hydrated", () => resolve(), { once: !0 });
+  });
+}
+export function processStaticDirectives(template) {
+  return template.replace(/@static\s*([\s\S]*?)@endstatic/gi, (_, content) => {
+    return `<div class="stx-static">${content.trim()}</div>`;
+  });
+}
+export function generateIslandManifest(islands) {
+  const manifest = islands.map((island) => ({
+    id: island.id,
+    component: island.component,
+    strategy: island.options.strategy,
+    props: island.props
+  }));
+  return `
+    <script type="application/json" id="stx-island-manifest">
+      ${JSON.stringify(manifest)}
+    </script>
+  `;
+}
+export default {
+  processPartialHydrationDirectives,
+  processStaticDirectives,
+  generatePartialHydrationCSS,
+  generateIslandManifest,
+  createIslandRegistry,
+  hydrateIsland,
+  hydrateByStrategy,
+  hydrateAll,
+  isHydrated,
+  onHydrated
+};