@ecopages/react 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +12 -22
  2. package/package.json +4 -4
  3. package/src/bundling/bundle.js +16 -9
  4. package/src/client-graph/ast-transform-eco-page.d.ts +14 -1
  5. package/src/client-graph/ast-transform-eco-page.js +60 -13
  6. package/src/client-graph/ast-transform-stripped-imports.js +1 -1
  7. package/src/client-graph/ast-transform-walk-imports.js +1 -1
  8. package/src/client-graph/boundary-plugin.d.ts +19 -0
  9. package/src/client-graph/boundary-plugin.js +51 -12
  10. package/src/client-graph/foreign-boundary-rewrite.d.ts +18 -3
  11. package/src/client-graph/foreign-boundary-rewrite.js +196 -45
  12. package/src/client-graph/foreign-jsx-reach.d.ts +21 -2
  13. package/src/client-graph/foreign-jsx-reach.js +25 -9
  14. package/src/client-graph/foreign-module.d.ts +45 -0
  15. package/src/client-graph/foreign-module.js +132 -0
  16. package/src/client-graph/reachability-client-roots.js +28 -0
  17. package/src/hmr/hmr-strategy.d.ts +3 -0
  18. package/src/hmr/hmr-strategy.js +7 -0
  19. package/src/hydration/browser/foreign-boundary.d.ts +12 -0
  20. package/src/hydration/browser/foreign-boundary.js +19 -0
  21. package/src/hydration/browser/page-hydration-hmr.d.ts +1 -0
  22. package/src/hydration/browser/page-hydration-hmr.js +1 -1
  23. package/src/hydration/browser/page-hydration.d.ts +2 -1
  24. package/src/hydration/browser/page-hydration.js +3 -2
  25. package/src/hydration/hydration-page-entry-source.js +3 -3
  26. package/src/hydration/page-data-manifest.d.ts +22 -1
  27. package/src/hydration/page-data-manifest.js +38 -3
  28. package/src/hydration/page-data-reader.d.ts +2 -1
  29. package/src/hydration/page-data-reader.js +4 -2
  30. package/src/hydration/page-payload.d.ts +6 -15
  31. package/src/hydration/page-payload.js +5 -42
  32. package/src/hydration/serialize-page-data-script.d.ts +4 -4
  33. package/src/hydration/serialize-page-data-script.js +6 -6
  34. package/src/plugin/react.plugin.js +2 -0
  35. package/src/render/component-ownership.d.ts +1 -6
  36. package/src/render/component-ownership.js +0 -3
  37. package/src/render/component-ssr.d.ts +0 -1
  38. package/src/render/component-ssr.js +0 -7
  39. package/src/render/layout-compose.d.ts +16 -8
  40. package/src/render/layout-compose.js +13 -36
  41. package/src/render/react-renderer.js +24 -37
@@ -18,6 +18,14 @@ export type LayoutComposeOptions = {
18
18
  };
19
19
  /** Records which tiers render, so a server render can tell a layout that drops its children. */
20
20
  renderTracker?: LayoutRenderTracker;
21
+ /**
22
+ * The props each layout tier renders with, outer to inner, already resolved on the server.
23
+ *
24
+ * @remarks
25
+ * When given, composition renders tier `i` with `tierProps[i]` and never calls a layout props factory, so the
26
+ * browser needs no request code to reproduce what the server rendered.
27
+ */
28
+ tierProps?: readonly Record<string, unknown>[];
21
29
  };
22
30
  export type LayoutShellEntry = {
23
31
  component: EcoComponent;
@@ -27,18 +35,18 @@ export type ComposablePage<P extends Record<string, unknown> = Record<string, un
27
35
  config?: Pick<EcoComponentConfig, 'layouts' | 'layoutEntries'>;
28
36
  };
29
37
  /**
30
- * Reads request-scoped layout context from serialized page props.
38
+ * Reads the Params and Query of a layout context from serialized page props.
39
+ *
40
+ * @remarks
41
+ * Serialized page props never carry `locals`; a server render passes them in `options.context`.
31
42
  */
32
43
  export declare function resolveLayoutContext(pageProps: Record<string, unknown>): LayoutComposeContext;
33
44
  /**
34
- * Builds layout prop factory context from document-shell layout entries.
45
+ * Resolves props for one layout entry: what its `props` factory returns, or nothing.
35
46
  *
36
47
  * @remarks
37
- * Route-scoped `locals` come from shell layout props, not `pageProps.locals` (pageLocals).
38
- */
39
- export declare function resolveLayoutContextFromShell(pageProps: Record<string, unknown>, shellLayouts: LayoutShellEntry[]): LayoutComposeContext;
40
- /**
41
- * Resolves props for one layout entry, merging shell locals with an optional factory.
48
+ * A layout receives request data only through its factory, so server and browser render a tier from the same
49
+ * props. The factory sees `context.locals`, or empty `locals` when the context has none; the layout does not.
42
50
  */
43
51
  export declare function resolveLayoutEntryProps(entry: EcoPageLayoutEntry, context: LayoutComposeContext): Record<string, unknown>;
44
52
  /**
@@ -58,7 +66,7 @@ export declare function composeLayoutPageTree<P extends Record<string, unknown>>
58
66
  * Builds a layout tree from explicit document-shell layout entries.
59
67
  *
60
68
  * @remarks
61
- * Use when the route renderer passes per-tier props (e.g. route `locals` on the layout tier).
69
+ * Use when the route renderer passes per-tier props, which the server resolved from each entry's `props` factory.
62
70
  * Shell `entry.props` are authoritative; page config normalization is not required.
63
71
  */
64
72
  export declare function composeLayoutPageTreeFromShell<P extends Record<string, unknown>>(Page: ComposablePage<P>, pageProps: P, shellLayouts: LayoutShellEntry[], options?: LayoutComposeOptions): ReactElement;
@@ -13,7 +13,10 @@ function toReactComponent(component) {
13
13
  return component;
14
14
  }
15
15
  /**
16
- * Reads request-scoped layout context from serialized page props.
16
+ * Reads the Params and Query of a layout context from serialized page props.
17
+ *
18
+ * @remarks
19
+ * Serialized page props never carry `locals`; a server render passes them in `options.context`.
17
20
  */
18
21
  export function resolveLayoutContext(pageProps) {
19
22
  const context = {};
@@ -23,45 +26,17 @@ export function resolveLayoutContext(pageProps) {
23
26
  if (pageProps.query !== undefined) {
24
27
  context.query = pageProps.query;
25
28
  }
26
- if (pageProps.locals !== undefined) {
27
- context.locals = pageProps.locals;
28
- }
29
29
  return context;
30
30
  }
31
31
  /**
32
- * Builds layout prop factory context from document-shell layout entries.
32
+ * Resolves props for one layout entry: what its `props` factory returns, or nothing.
33
33
  *
34
34
  * @remarks
35
- * Route-scoped `locals` come from shell layout props, not `pageProps.locals` (pageLocals).
36
- */
37
- export function resolveLayoutContextFromShell(pageProps, shellLayouts) {
38
- const context = {};
39
- if (pageProps.params !== undefined) {
40
- context.params = pageProps.params;
41
- }
42
- if (pageProps.query !== undefined) {
43
- context.query = pageProps.query;
44
- }
45
- for (const entry of shellLayouts) {
46
- if (entry.props !== undefined && Object.prototype.hasOwnProperty.call(entry.props, 'locals')) {
47
- context.locals = entry.props.locals;
48
- break;
49
- }
50
- }
51
- return context;
52
- }
53
- /**
54
- * Resolves props for one layout entry, merging shell locals with an optional factory.
35
+ * A layout receives request data only through its factory, so server and browser render a tier from the same
36
+ * props. The factory sees `context.locals`, or empty `locals` when the context has none; the layout does not.
55
37
  */
56
38
  export function resolveLayoutEntryProps(entry, context) {
57
- const shellProps = context.locals ? { locals: context.locals } : {};
58
- if (!entry.props) {
59
- return shellProps;
60
- }
61
- return {
62
- ...shellProps,
63
- ...entry.props(context),
64
- };
39
+ return entry.props ? entry.props({ ...context, locals: context.locals ?? {} }) : {};
65
40
  }
66
41
  /**
67
42
  * @remarks
@@ -90,7 +65,9 @@ export function composeLayoutPageTree(Page, pageProps, options) {
90
65
  if (layoutEntries && layoutEntries.length > 0) {
91
66
  return [...layoutEntries].reverse().reduce((children, entry, reverseIndex) => {
92
67
  const index = layoutEntries.length - 1 - reverseIndex;
93
- const layoutProps = resolveLayoutEntryProps(entry, context);
68
+ const layoutProps = options?.tierProps
69
+ ? (options.tierProps[index] ?? {})
70
+ : resolveLayoutEntryProps(entry, context);
94
71
  const tier = resolvePersistedTier?.(entry.component, index);
95
72
  const Layout = toTrackedReactComponent(tier?.layout ?? entry.component, index, tracker);
96
73
  const elementProps = tier?.key ? { key: tier.key, ...layoutProps } : layoutProps;
@@ -99,9 +76,9 @@ export function composeLayoutPageTree(Page, pageProps, options) {
99
76
  }
100
77
  const layouts = Page.config?.layouts;
101
78
  if (layouts && layouts.length > 0) {
102
- const layoutProps = context.locals ? { locals: context.locals } : {};
103
79
  return [...layouts].reverse().reduce((children, Layout, reverseIndex) => {
104
80
  const index = layouts.length - 1 - reverseIndex;
81
+ const layoutProps = options?.tierProps?.[index] ?? {};
105
82
  const tier = resolvePersistedTier?.(Layout, index);
106
83
  const ResolvedLayout = toTrackedReactComponent(tier?.layout ?? Layout, index, tracker);
107
84
  const elementProps = tier?.key ? { key: tier.key, ...layoutProps } : layoutProps;
@@ -118,7 +95,7 @@ function toTrackedReactComponent(component, index, tracker) {
118
95
  * Builds a layout tree from explicit document-shell layout entries.
119
96
  *
120
97
  * @remarks
121
- * Use when the route renderer passes per-tier props (e.g. route `locals` on the layout tier).
98
+ * Use when the route renderer passes per-tier props, which the server resolved from each entry's `props` factory.
122
99
  * Shell `entry.props` are authoritative; page config normalization is not required.
123
100
  */
124
101
  export function composeLayoutPageTreeFromShell(Page, pageProps, shellLayouts, options) {
@@ -12,7 +12,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
12
12
  import { buildIslandHostAttributes, getComponentIdentity } from '@ecopages/core';
13
13
  import { createIntegrationRenderer, selectHydrationIslandEntries, } from '@ecopages/core/integration';
14
14
  import { ECO_DOCUMENT_OWNER_ATTRIBUTE } from '@ecopages/core/client';
15
- import { ensurePageConfigLayouts, moveMdxMetadataOntoPage } from '@ecopages/core/integration';
15
+ import { ensurePageConfigLayouts, moveMdxMetadataOntoPage, resolveRenderLayouts } from '@ecopages/core/integration';
16
16
  import { hasSingleRootElement } from './html-boundary.js';
17
17
  import { toRootRelativePath } from '@ecopages/core/build';
18
18
  import { getIslandComponentKey } from '../hydration/hydration-asset.js';
@@ -24,12 +24,12 @@ import { PageModuleService } from '../page/page-module.js';
24
24
  import { PagePayloadService } from '../hydration/page-payload.js';
25
25
  import { HydrationAssetService } from '../hydration/hydration-asset.js';
26
26
  import {} from '@ecopages/core/integration';
27
- import { asNonReactShellComponent, getComponentRequires, isReactManagedComponent } from './component-ownership.js';
28
- import { buildHydrationProps, renderComponentHtml, renderNonReactShellComponent, restoreRuntimeChildHtml, replaceForeignSubtreeTokens, toReactNode, wrapForeignSubtreeTokens, } from './component-ssr.js';
27
+ import { asNonReactShellComponent, isReactManagedComponent } from './component-ownership.js';
28
+ import { renderComponentHtml, renderNonReactShellComponent, restoreRuntimeChildHtml, replaceForeignSubtreeTokens, toReactNode, wrapForeignSubtreeTokens, } from './component-ssr.js';
29
29
  import { BundleError, ReactRenderError } from './errors.js';
30
30
  import { renderReactHtml, resolveReactRuntimeModules, runWithRenderBudget, } from './react-runtime.js';
31
31
  import { composeReactLayoutPageTree, shouldUseUnifiedReactLayoutComposition } from './unified-layout-composition.js';
32
- import { assertComposablePage, resolveLayoutContextFromShell } from './layout-compose.js';
32
+ import { assertComposablePage } from './layout-compose.js';
33
33
  import { LayoutRenderTracker } from './layout-render-tracker.js';
34
34
  export { BundleError, ReactRenderError } from './errors.js';
35
35
  const ReactIntegrationRenderer = createIntegrationRenderer(REACT_PLUGIN_NAME);
@@ -184,17 +184,25 @@ export class ReactRenderer extends ReactIntegrationRenderer {
184
184
  html = restoreRuntimeChildHtml(html, runtimeContext);
185
185
  return await resolveTokens(html);
186
186
  }
187
- buildPagePayload(options) {
188
- const safeLocals = this.pagePayloadService.getSerializableLocals(options.locals, getComponentRequires(options.Page));
187
+ buildPagePayload(renderOptions) {
188
+ const layoutTiers = renderOptions.layoutEntries?.length
189
+ ? resolveRenderLayouts(renderOptions, {
190
+ layout: renderOptions.Layout,
191
+ layoutEntries: renderOptions.layoutEntries,
192
+ params: renderOptions.params,
193
+ query: renderOptions.query,
194
+ locals: renderOptions.locals,
195
+ }).map((layout) => layout.props ?? {})
196
+ : undefined;
189
197
  return {
190
- pageModuleUrl: this.pagePayloadService.resolvePageModuleUrl(options.pagePackage, {
198
+ pageModuleUrl: this.pagePayloadService.resolvePageModuleUrl(renderOptions.pagePackage, {
191
199
  routerEnabled: Boolean(this.routerAdapter),
192
200
  }),
193
201
  pageProps: this.pagePayloadService.buildSerializedPageProps({
194
- pageProps: options.pageProps,
195
- params: options.params,
196
- query: options.query,
197
- safeLocals,
202
+ pageProps: renderOptions.pageProps,
203
+ params: renderOptions.params,
204
+ query: renderOptions.query,
205
+ layoutTiers,
198
206
  }),
199
207
  };
200
208
  }
@@ -268,7 +276,7 @@ export class ReactRenderer extends ReactIntegrationRenderer {
268
276
  integrationName: this.name,
269
277
  componentInstanceId: context.componentInstanceId,
270
278
  componentKey: getIslandComponentKey(toRootRelativePath(this.appConfig.rootDir, componentFile), componentConfig),
271
- props: buildHydrationProps(input.props),
279
+ props: input.props,
272
280
  });
273
281
  html = `<eco-island style="display:contents">${html}</eco-island>`;
274
282
  }
@@ -343,9 +351,9 @@ export class ReactRenderer extends ReactIntegrationRenderer {
343
351
  const runtime = this.getReactRuntimeModules();
344
352
  const renderTracker = new LayoutRenderTracker();
345
353
  const tree = composeReactLayoutPageTree(pageComponent, page.props, shellEntries, {
346
- context: resolveLayoutContextFromShell(page.props, shellEntries),
347
354
  react: runtime.react,
348
355
  renderTracker,
356
+ tierProps: shellEntries.map((entry) => entry.props ?? {}),
349
357
  });
350
358
  const runtimeInput = {
351
359
  component: page.component,
@@ -379,14 +387,7 @@ export class ReactRenderer extends ReactIntegrationRenderer {
379
387
  return (context) => this.composeReactLayoutPageChildrenForShell(page, context);
380
388
  }
381
389
  buildDocumentShellProps(options) {
382
- const pagePayload = this.buildPagePayload({
383
- Page: options.Page,
384
- pageProps: options.pageProps,
385
- params: options.params,
386
- query: options.query,
387
- locals: options.locals,
388
- pagePackage: options.pagePackage,
389
- });
390
+ const pagePayload = this.buildPagePayload(options);
390
391
  return {
391
392
  pageProps: pagePayload.pageProps,
392
393
  documentProps: pagePayload.pageModuleUrl ? { pageModuleUrl: pagePayload.pageModuleUrl } : undefined,
@@ -400,14 +401,7 @@ export class ReactRenderer extends ReactIntegrationRenderer {
400
401
  return this.buildRouterlessPageDataContributions(renderOptions);
401
402
  if (isReactManagedComponent(renderOptions.HtmlTemplate, this.name))
402
403
  return undefined;
403
- const pagePayload = this.buildPagePayload({
404
- Page: renderOptions.Page,
405
- pageProps: renderOptions.pageProps,
406
- params: renderOptions.params,
407
- query: renderOptions.query,
408
- locals: renderOptions.locals,
409
- pagePackage: renderOptions.pagePackage,
410
- });
404
+ const pagePayload = this.buildPagePayload(renderOptions);
411
405
  return this.pagePayloadService.buildNonReactDocumentContributions({
412
406
  htmlTemplate: renderOptions.HtmlTemplate,
413
407
  pageProps: pagePayload.pageProps,
@@ -427,14 +421,7 @@ export class ReactRenderer extends ReactIntegrationRenderer {
427
421
  buildRouterlessPageDataContributions(renderOptions) {
428
422
  if (!this.hydratesPageTree(renderOptions.Page))
429
423
  return undefined;
430
- const pagePayload = this.buildPagePayload({
431
- Page: renderOptions.Page,
432
- pageProps: renderOptions.pageProps,
433
- params: renderOptions.params,
434
- query: renderOptions.query,
435
- locals: renderOptions.locals,
436
- pagePackage: renderOptions.pagePackage,
437
- });
424
+ const pagePayload = this.buildPagePayload(renderOptions);
438
425
  return [
439
426
  {
440
427
  placement: 'head-append',