@ecopages/react 0.2.0-alpha.14 → 0.2.0-alpha.15

package/src/services/react-page-payload.service.js

@@ -0,0 +1,67 @@
+import { LocalsAccessError } from "@ecopages/core/errors/locals-access-error";
+class ReactPagePayloadService {
+  /**
+   * Creates the canonical page-props payload used by router hydration.
+   *
+   * React pages embedded in a non-React HTML shell still need to expose the same
+   * page-data contract as fully React-owned documents so navigation and hydration
+   * can read one shared document payload consistently.
+   */
+  buildRouterPageDataScript(pageProps) {
+    const safeJson = JSON.stringify(pageProps || {}).replace(/</g, "\\u003c");
+    return `<script id="__ECO_PAGE_DATA__" type="application/json">${safeJson}<\/script>`;
+  }
+  /**
+   * Builds the serialized page-props payload embedded into the final HTML.
+   *
+   * The document payload is intentionally narrower than the full server render
+   * input: only routing data, public page props, and explicitly allowed locals are
+   * exposed to the browser.
+   */
+  buildSerializedPageProps(options) {
+    return {
+      ...options.pageProps,
+      params: options.params,
+      query: options.query,
+      ...options.safeLocals && { locals: options.safeLocals }
+    };
+  }
+  /**
+   * Safely extracts the declared subset of locals for client-side hydration.
+   *
+   * On dynamic pages with `cache: 'dynamic'`, middleware populates `locals` with
+   * request-scoped data (e.g., session). Only keys explicitly declared via
+   * `Page.requires` are serialized to the client so sensitive request-only data
+   * is not leaked into hydration payloads by default.
+   *
+   * On static pages, `locals` is a Proxy that throws `LocalsAccessError` on access
+   * to prevent accidental use. This method safely detects that case and returns
+   * `undefined` instead of throwing.
+   */
+  getSerializableLocals(locals, requiredLocals) {
+    try {
+      if (!locals) {
+        return void 0;
+      }
+      const requiredKeys = requiredLocals ? Array.isArray(requiredLocals) ? requiredLocals : [requiredLocals] : [];
+      if (requiredKeys.length === 0) {
+        return void 0;
+      }
+      const serializedLocals = Object.fromEntries(
+        requiredKeys.filter((key) => Object.prototype.hasOwnProperty.call(locals, key)).map((key) => [key, locals[key]])
+      );
+      if (Object.keys(serializedLocals).length > 0) {
+        return serializedLocals;
+      }
+      return void 0;
+    } catch (error) {
+      if (error instanceof LocalsAccessError) {
+        return void 0;
+      }
+      throw error;
+    }
+  }
+}
+export {
+  ReactPagePayloadService
+};

package/src/utils/component-config-traversal.d.ts

@@ -0,0 +1,36 @@
+import type { EcoComponent, EcoComponentConfig } from '@ecopages/core';
+/**
+ * Walks a component config tree once, including nested layout configs and
+ * dependency component configs.
+ *
+ * The shared React integration code performs several different analyses over the
+ * same config graph. Centralizing the traversal keeps cycle handling and graph
+ * shape assumptions in one place instead of repeating them in the renderer and
+ * services.
+ */
+export declare function walkConfigTree(config: EcoComponentConfig | undefined, visitor: (config: EcoComponentConfig) => void, visited?: Set<EcoComponentConfig>): void;
+/**
+ * Walks a forest of root component configs using one shared visited set.
+ *
+ * This is useful when a page contributes multiple config roots, such as a page
+ * config plus a resolved layout config, and duplicate nested nodes should still
+ * be processed only once.
+ */
+export declare function walkConfigForest(configs: Iterable<EcoComponentConfig | undefined>, visitor: (config: EcoComponentConfig) => void): void;
+/**
+ * Collects values from a config tree while preserving the shared traversal and
+ * cycle protection behavior used across the React integration.
+ */
+export declare function collectFromConfigTree<T>(config: EcoComponentConfig | undefined, collector: (config: EcoComponentConfig) => T[]): T[];
+/**
+ * Collects values from multiple config roots with one shared visited set.
+ */
+export declare function collectFromConfigForest<T>(configs: Iterable<EcoComponentConfig | undefined>, collector: (config: EcoComponentConfig) => T[]): T[];
+/**
+ * Returns true when any node in the config tree matches the predicate.
+ */
+export declare function someInConfigTree(config: EcoComponentConfig | undefined, predicate: (config: EcoComponentConfig) => boolean): boolean;
+/**
+ * Reads config roots from partial components while tolerating undefined config.
+ */
+export declare function getComponentConfigs(components: Partial<EcoComponent>[]): Array<EcoComponentConfig | undefined>;

package/src/utils/component-config-traversal.js

@@ -0,0 +1,54 @@
+function walkConfigTree(config, visitor, visited = /* @__PURE__ */ new Set()) {
+  if (!config || visited.has(config)) {
+    return;
+  }
+  visited.add(config);
+  visitor(config);
+  if (config.layout?.config) {
+    walkConfigTree(config.layout.config, visitor, visited);
+  }
+  for (const component of config.dependencies?.components ?? []) {
+    walkConfigTree(component.config, visitor, visited);
+  }
+}
+function walkConfigForest(configs, visitor) {
+  const visited = /* @__PURE__ */ new Set();
+  for (const config of configs) {
+    walkConfigTree(config, visitor, visited);
+  }
+}
+function collectFromConfigTree(config, collector) {
+  const values = [];
+  walkConfigTree(config, (node) => {
+    values.push(...collector(node));
+  });
+  return values;
+}
+function collectFromConfigForest(configs, collector) {
+  const values = [];
+  walkConfigForest(configs, (node) => {
+    values.push(...collector(node));
+  });
+  return values;
+}
+function someInConfigTree(config, predicate) {
+  let matched = false;
+  walkConfigTree(config, (node) => {
+    if (matched) {
+      return;
+    }
+    matched = predicate(node);
+  });
+  return matched;
+}
+function getComponentConfigs(components) {
+  return components.map((component) => component.config);
+}
+export {
+  collectFromConfigForest,
+  collectFromConfigTree,
+  getComponentConfigs,
+  someInConfigTree,
+  walkConfigForest,
+  walkConfigTree
+};

package/src/utils/declared-modules.d.ts

@@ -29,7 +29,7 @@ export declare function normalizeDeclaredModuleSources(modules?: string[]): stri
  * Recursively walks a component config tree (including layouts and nested
  * `dependencies.components`) to collect all declared module sources.
  */
-export declare function collectDeclaredModulesInConfig(config: EcoComponentConfig | undefined, visited?: Set<EcoComponentConfig>): string[];
+export declare function collectDeclaredModulesInConfig(config: EcoComponentConfig | undefined): string[];
 /**
  * Collects declared module sources from an already imported page module.
  */

package/src/utils/declared-modules.js

@@ -1,3 +1,4 @@
+import { collectFromConfigTree } from "./component-config-traversal.js";
 function parseDeclaredModuleSource(value) {
   const source = value.trim();
   if (source.length === 0) return void 0;
@@ -16,21 +17,8 @@ function normalizeDeclaredModuleSources(modules) {
   }
   return Array.from(seen);
 }
-function collectDeclaredModulesInConfig(config, visited = /* @__PURE__ */ new Set()) {
-  if (!config || visited.has(config)) {
-    return [];
-  }
-  visited.add(config);
-  const declarations = normalizeDeclaredModuleSources(config.dependencies?.modules);
-  if (config.layout?.config) {
-    declarations.push(...collectDeclaredModulesInConfig(config.layout.config, visited));
-  }
-  for (const component of config.dependencies?.components ?? []) {
-    if (component.config) {
-      declarations.push(...collectDeclaredModulesInConfig(component.config, visited));
-    }
-  }
-  return declarations;
+function collectDeclaredModulesInConfig(config) {
+  return collectFromConfigTree(config, (node) => normalizeDeclaredModuleSources(node.dependencies?.modules));
 }
 function collectPageDeclaredModulesFromModule(pageModule) {
   const declarations = [

package/src/utils/dynamic.test.browser.d.ts

@@ -0,0 +1 @@
+export {};

package/src/utils/dynamic.test.browser.js

@@ -0,0 +1,33 @@
+import { jsx } from "react/jsx-runtime";
+import { Suspense } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+import { dynamic } from "./dynamic.js";
+function createDeferredImport() {
+  let resolve;
+  const promise = new Promise((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return {
+    promise,
+    resolve
+  };
+}
+describe("dynamic", () => {
+  afterEach(() => {
+    cleanup();
+  });
+  it("returns a browser lazy component that resolves through Suspense", async () => {
+    const deferredImport = createDeferredImport();
+    const DynamicComponent = dynamic(() => deferredImport.promise);
+    render(
+      /* @__PURE__ */ jsx(Suspense, { fallback: /* @__PURE__ */ jsx("span", { children: "Loading dynamic component" }), children: /* @__PURE__ */ jsx(DynamicComponent, {}) })
+    );
+    expect(screen.getByText("Loading dynamic component")).toBeTruthy();
+    deferredImport.resolve({
+      default: () => /* @__PURE__ */ jsx("span", { children: "Dynamic content" })
+    });
+    expect(await screen.findByText("Dynamic content")).toBeTruthy();
+    expect(screen.queryByText("Loading dynamic component")).toBeNull();
+  });
+});

package/src/utils/hydration-scripts.test.browser.d.ts

@@ -0,0 +1 @@
+export {};

package/src/utils/hydration-scripts.test.browser.js

@@ -0,0 +1,126 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createHydrationScript } from "./hydration-scripts.js";
+const routerAdapter = {
+  name: "eco-router",
+  bundle: {
+    importPath: "/assets/router.js",
+    outputName: "router",
+    externals: []
+  },
+  importMapKey: "@ecopages/react-router",
+  components: {
+    router: "EcoRouter",
+    pageContent: "PageContent"
+  },
+  getRouterProps: (page, props) => `{ page: ${page}, pageProps: ${props} }`
+};
+function createModuleUrl(source) {
+  return `data:text/javascript;base64,${btoa(source)}`;
+}
+async function importModule(moduleUrl) {
+  await import(
+    /* @vite-ignore */
+    moduleUrl
+  );
+}
+function createRuntimeModules() {
+  const reactImportPath = createModuleUrl("export const createElement = (...args) => ({ args });");
+  const reactDomClientImportPath = createModuleUrl(`
+export const hydrateRoot = (container, tree, options) => {
+  const runtime = window.__ECO_REACT_HYDRATION_TEST__;
+  runtime.hydrateCalls.push({
+    containerTag: container.tagName,
+    hasRecoverableErrorHandler: typeof options?.onRecoverableError === "function",
+    tree,
+  });
+
+  return {
+    render() {},
+    unmount() {
+      runtime.unmountCount += 1;
+    },
+  };
+};
+`);
+  const importPath = createModuleUrl("export default function Page() { return null; }");
+  const routerImportPath = createModuleUrl(`
+export function EcoRouter(props) {
+  return props;
+}
+
+export function PageContent() {
+  return null;
+}
+`);
+  return {
+    importPath,
+    reactImportPath,
+    reactDomClientImportPath,
+    routerImportPath
+  };
+}
+describe("createHydrationScript browser execution", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    const testWindow = window;
+    delete testWindow.__ECO_PAGES__;
+    delete testWindow.__ECO_REACT_HYDRATION_TEST__;
+  });
+  it("registers router ownership and cleanup when the browser hydration bootstrap runs", async () => {
+    const runtimeModules = createRuntimeModules();
+    const testWindow = window;
+    testWindow.__ECO_REACT_HYDRATION_TEST__ = {
+      hydrateCalls: [],
+      claimedOwners: [],
+      releasedOwners: [],
+      registrations: [],
+      unmountCount: 0
+    };
+    testWindow.__ECO_PAGES__ = {
+      navigation: {
+        getOwnerState: () => ({
+          owner: "html",
+          canHandleSpaNavigation: false
+        }),
+        register: (registration) => {
+          testWindow.__ECO_REACT_HYDRATION_TEST__?.registrations.push(registration);
+        },
+        claimOwnership: (owner) => {
+          testWindow.__ECO_REACT_HYDRATION_TEST__?.claimedOwners.push(owner);
+        },
+        releaseOwnership: (owner) => {
+          testWindow.__ECO_REACT_HYDRATION_TEST__?.releasedOwners.push(owner);
+        }
+      }
+    };
+    document.body.innerHTML = `<script id="__ECO_PAGE_DATA__" type="application/json">${JSON.stringify({
+      title: "Hello React",
+      locals: { theme: "dark" }
+    })}<\/script>`;
+    const script = createHydrationScript({
+      ...runtimeModules,
+      isDevelopment: true,
+      isMdx: false,
+      router: routerAdapter
+    });
+    await importModule(createModuleUrl(script));
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.hydrateCalls).toHaveLength(1);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.hydrateCalls[0]?.containerTag).toBe("BODY");
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.hydrateCalls[0]?.hasRecoverableErrorHandler).toBe(true);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.claimedOwners).toEqual(["react-router"]);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.registrations).toHaveLength(1);
+    expect(typeof testWindow.__ECO_PAGES__?.react?.cleanupPageRoot).toBe("function");
+    expect(testWindow.__ECO_PAGES__?.page).toEqual({
+      module: runtimeModules.importPath,
+      props: {
+        title: "Hello React",
+        locals: { theme: "dark" }
+      }
+    });
+    await testWindow.__ECO_PAGES__?.react?.cleanupPageRoot?.();
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.unmountCount).toBe(1);
+    expect(testWindow.__ECO_REACT_HYDRATION_TEST__?.releasedOwners).toEqual(["react-router"]);
+    expect(testWindow.__ECO_PAGES__?.page).toBeUndefined();
+    expect(testWindow.__ECO_PAGES__?.react?.pageRoot).toBeNull();
+  });
+});