@ecopages/react 0.2.0-beta.3 → 0.2.0-beta.30
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.
- package/README.md +168 -6
- package/package.json +51 -26
- package/src/bundling/bootstrap-package-paths.d.ts +5 -0
- package/src/bundling/bootstrap-package-paths.js +6 -0
- package/src/{services/react-bundle.service.d.ts → bundling/bundle.d.ts} +21 -8
- package/src/{services/react-bundle.service.js → bundling/bundle.js} +53 -21
- package/src/bundling/discover-layout-runtime-modules.d.ts +32 -0
- package/src/bundling/discover-layout-runtime-modules.js +180 -0
- package/src/bundling/runtime-alias-map.d.ts +10 -0
- package/src/{utils/react-runtime-alias-map.js → bundling/runtime-alias-map.js} +13 -2
- package/src/{services/react-runtime-bundle.service.d.ts → bundling/runtime-bundle.d.ts} +30 -5
- package/src/{services/react-runtime-bundle.service.js → bundling/runtime-bundle.js} +104 -8
- package/src/bundling/runtime-mode.d.ts +9 -0
- package/src/bundling/runtime-mode.js +6 -0
- package/src/bundling/runtime-modules.d.ts +29 -0
- package/src/bundling/runtime-modules.js +38 -0
- package/src/client-graph/ast-transform.d.ts +18 -0
- package/src/{utils/client-graph-boundary-plugin.js → client-graph/ast-transform.js} +15 -232
- package/src/{utils/client-graph-boundary-cache.d.ts → client-graph/boundary-cache.d.ts} +0 -5
- package/src/{utils/client-graph-boundary-cache.js → client-graph/boundary-cache.js} +1 -3
- package/src/{utils/client-graph-boundary-plugin.d.ts → client-graph/boundary-plugin.d.ts} +4 -13
- package/src/client-graph/boundary-plugin.js +107 -0
- package/src/{utils → client-graph}/component-config-traversal.js +4 -2
- package/src/{utils → client-graph}/reachability-analyzer.d.ts +2 -2
- package/src/{utils → client-graph}/reachability-analyzer.js +4 -1
- package/src/client-graph/specifier-classification.d.ts +75 -0
- package/src/client-graph/specifier-classification.js +155 -0
- package/src/{react-hmr-strategy.d.ts → hmr/hmr-strategy.d.ts} +19 -6
- package/src/{react-hmr-strategy.js → hmr/hmr-strategy.js} +154 -133
- package/src/{services/react-hmr-page-metadata-cache.d.ts → hmr/page-metadata-cache.d.ts} +5 -1
- package/src/{services/react-hmr-page-metadata-cache.js → hmr/page-metadata-cache.js} +8 -2
- package/src/hydration/assert-no-bare-ecopages-imports.d.ts +4 -0
- package/src/hydration/assert-no-bare-ecopages-imports.js +7 -0
- package/src/hydration/bootstrap-imports.d.ts +25 -0
- package/src/hydration/bootstrap-imports.js +23 -0
- package/src/{services/react-hydration-asset.service.d.ts → hydration/hydration-asset.d.ts} +33 -33
- package/src/{services/react-hydration-asset.service.js → hydration/hydration-asset.js} +63 -56
- package/src/hydration/hydration-scripts.d.ts +100 -0
- package/src/hydration/hydration-scripts.js +350 -0
- package/src/{utils → hydration}/hydration-scripts.test.browser.js +11 -5
- package/src/hydration/page-data-manifest.d.ts +58 -0
- package/src/hydration/page-data-manifest.js +53 -0
- package/src/hydration/page-data-reader.d.ts +31 -0
- package/src/hydration/page-data-reader.js +64 -0
- package/src/hydration/page-payload.d.ts +67 -0
- package/src/hydration/page-payload.js +104 -0
- package/src/hydration/serialize-page-data-script.d.ts +27 -0
- package/src/hydration/serialize-page-data-script.js +31 -0
- package/src/{services/react-mdx-config-dependency.service.d.ts → mdx/mdx-config-dependency.d.ts} +5 -5
- package/src/{services/react-mdx-config-dependency.service.js → mdx/mdx-config-dependency.js} +8 -10
- package/src/mdx/mdx-loader-plugin.d.ts +2 -0
- package/src/mdx/mdx-loader-plugin.js +11 -0
- package/src/page/page-module.d.ts +46 -0
- package/src/page/page-module.js +72 -0
- package/src/{react.plugin.d.ts → plugin/react.plugin.d.ts} +8 -3
- package/src/{react.plugin.js → plugin/react.plugin.js} +78 -54
- package/src/plugin/react.types.d.ts +149 -0
- package/src/render/component-ownership.d.ts +50 -0
- package/src/render/component-ownership.js +23 -0
- package/src/render/component-ssr.d.ts +113 -0
- package/src/render/component-ssr.js +202 -0
- package/src/render/errors.d.ts +16 -0
- package/src/render/errors.js +18 -0
- package/src/render/layout-compose.d.ts +66 -0
- package/src/render/layout-compose.js +106 -0
- package/src/render/react-renderer.d.ts +138 -0
- package/src/render/react-renderer.js +481 -0
- package/src/render/react-runtime.d.ts +13 -0
- package/src/render/react-runtime.js +21 -0
- package/src/render/unified-layout-composition.d.ts +53 -0
- package/src/render/unified-layout-composition.js +89 -0
- package/src/react-renderer.d.ts +0 -233
- package/src/react-renderer.js +0 -622
- package/src/react.types.d.ts +0 -88
- package/src/services/pages-index.d.ts +0 -64
- package/src/services/pages-index.js +0 -73
- package/src/services/react-page-module.service.d.ts +0 -88
- package/src/services/react-page-module.service.js +0 -166
- package/src/services/react-page-payload.service.d.ts +0 -46
- package/src/services/react-page-payload.service.js +0 -67
- package/src/utils/hydration-scripts.d.ts +0 -92
- package/src/utils/hydration-scripts.js +0 -358
- package/src/utils/react-mdx-loader-plugin.d.ts +0 -3
- package/src/utils/react-mdx-loader-plugin.js +0 -45
- package/src/utils/react-runtime-alias-map.d.ts +0 -8
- /package/src/{utils → app}/client-only.d.ts +0 -0
- /package/src/{utils → app}/client-only.js +0 -0
- /package/src/{utils → app}/dynamic.d.ts +0 -0
- /package/src/{utils → app}/dynamic.js +0 -0
- /package/src/{utils → app}/dynamic.test.browser.d.ts +0 -0
- /package/src/{utils → app}/dynamic.test.browser.js +0 -0
- /package/src/{utils/react-dom-runtime-interop-plugin.d.ts → bundling/runtime-interop-plugin.d.ts} +0 -0
- /package/src/{utils/react-dom-runtime-interop-plugin.js → bundling/runtime-interop-plugin.js} +0 -0
- /package/src/{utils → client-graph}/component-config-traversal.d.ts +0 -0
- /package/src/{utils → client-graph}/declared-modules.d.ts +0 -0
- /package/src/{utils → client-graph}/declared-modules.js +0 -0
- /package/src/{declarations.d.ts → contracts/declarations.d.ts} +0 -0
- /package/src/{router-adapter.d.ts → contracts/router-adapter.d.ts} +0 -0
- /package/src/{router-adapter.js → contracts/router-adapter.js} +0 -0
- /package/src/{utils → hmr}/hmr-scripts.d.ts +0 -0
- /package/src/{utils → hmr}/hmr-scripts.js +0 -0
- /package/src/{utils → hydration}/hydration-scripts.test.browser.d.ts +0 -0
- /package/src/{react.constants.d.ts → plugin/react.constants.d.ts} +0 -0
- /package/src/{react.constants.js → plugin/react.constants.js} +0 -0
- /package/src/{react.types.js → plugin/react.types.js} +0 -0
- /package/src/{eco-embed.d.ts → render/eco-embed.d.ts} +0 -0
- /package/src/{eco-embed.js → render/eco-embed.js} +0 -0
- /package/src/{utils → render}/html-boundary.d.ts +0 -0
- /package/src/{utils → render}/html-boundary.js +0 -0
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
|
|
2
|
+
import type { CompileOptions } from '@mdx-js/mdx';
|
|
3
|
+
import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
|
|
4
|
+
import type { HmrPageMetadataCache } from '../hmr/page-metadata-cache.js';
|
|
5
|
+
import type { ReactPluginRuntimeModule, ResolvedReactPluginRuntimeModule } from '../bundling/runtime-modules.js';
|
|
6
|
+
/**
|
|
7
|
+
* MDX configuration options for the React plugin.
|
|
8
|
+
*/
|
|
9
|
+
export type ReactMdxOptions = {
|
|
10
|
+
/**
|
|
11
|
+
* Whether to enable MDX support.
|
|
12
|
+
* @default false
|
|
13
|
+
*/
|
|
14
|
+
enabled: boolean;
|
|
15
|
+
/**
|
|
16
|
+
* Compiler options for MDX.
|
|
17
|
+
* @default undefined
|
|
18
|
+
*/
|
|
19
|
+
compilerOptions?: Omit<CompileOptions, 'jsxImportSource' | 'jsxRuntime'>;
|
|
20
|
+
/**
|
|
21
|
+
* Remark plugins.
|
|
22
|
+
* @default undefined
|
|
23
|
+
*/
|
|
24
|
+
remarkPlugins?: CompileOptions['remarkPlugins'];
|
|
25
|
+
/**
|
|
26
|
+
* Rehype plugins.
|
|
27
|
+
* @default undefined
|
|
28
|
+
*/
|
|
29
|
+
rehypePlugins?: CompileOptions['rehypePlugins'];
|
|
30
|
+
/**
|
|
31
|
+
* Recma plugins.
|
|
32
|
+
* @default undefined
|
|
33
|
+
*/
|
|
34
|
+
recmaPlugins?: CompileOptions['recmaPlugins'];
|
|
35
|
+
/**
|
|
36
|
+
* Custom extensions to be treated as MDX files.
|
|
37
|
+
* @default ['.mdx']
|
|
38
|
+
*/
|
|
39
|
+
extensions?: string[];
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* Options for the React plugin.
|
|
43
|
+
*/
|
|
44
|
+
export type ReactPluginOptions = {
|
|
45
|
+
extensions?: string[];
|
|
46
|
+
dependencies?: AssetDefinition[];
|
|
47
|
+
/**
|
|
48
|
+
* When true, always emit the page browser graph / hydration assets for React
|
|
49
|
+
* page entries, even when the page does not declare `dependencies.modules`
|
|
50
|
+
* and no router adapter is configured.
|
|
51
|
+
*
|
|
52
|
+
* @remarks
|
|
53
|
+
* This does not skip the client-graph AST boundary. Server-only
|
|
54
|
+
* `eco.page(...)` options such as `middleware` and `requires` are still
|
|
55
|
+
* stripped from browser bundles.
|
|
56
|
+
*
|
|
57
|
+
* With a router adapter, page hydration is already always enabled, so this
|
|
58
|
+
* option is redundant for SPA apps.
|
|
59
|
+
*
|
|
60
|
+
* @default false
|
|
61
|
+
*/
|
|
62
|
+
explicitGraph?: boolean;
|
|
63
|
+
/**
|
|
64
|
+
* Router adapter for SPA navigation.
|
|
65
|
+
* When provided, pages with layouts will be wrapped in the router for client-side navigation.
|
|
66
|
+
* @example
|
|
67
|
+
* ```ts
|
|
68
|
+
* import { ecoRouter } from '@ecopages/react-router';
|
|
69
|
+
* reactPlugin({ router: ecoRouter() })
|
|
70
|
+
* ```
|
|
71
|
+
*/
|
|
72
|
+
router?: ReactRouterAdapter;
|
|
73
|
+
/**
|
|
74
|
+
* Optional shared browser runtime vendors.
|
|
75
|
+
*
|
|
76
|
+
* With `router`, npm packages reachable from `eco.layout()` **render graphs**
|
|
77
|
+
* under the app's configured `layouts/` and `components/` directories are
|
|
78
|
+
* discovered automatically and registered as shared vendors (alongside React
|
|
79
|
+
* and React DOM). This prevents duplicate module instances when persisted
|
|
80
|
+
* layouts stay mounted across SPA navigation.
|
|
81
|
+
*
|
|
82
|
+
* Without `router`, only explicit entries here are vendored.
|
|
83
|
+
*
|
|
84
|
+
* @remarks
|
|
85
|
+
* Discovery follows client reachability from each layout's `render` path,
|
|
86
|
+
* resolves relative and tsconfig path aliases, and collects npm package roots
|
|
87
|
+
* imported from provider/context modules in that graph (for example files named
|
|
88
|
+
* `query-provider.tsx` or modules using `QueryClientProvider` / `createContext`).
|
|
89
|
+
* It does not vendor every npm dependency reachable from shell or page UI.
|
|
90
|
+
*
|
|
91
|
+
* Layouts that mount shared runtime state should set `runtimeProvider: true` in
|
|
92
|
+
* `eco.layout({ ... })`. Flagged layouts become the only discovery roots and
|
|
93
|
+
* vendor every reachable npm package in that layout graph. When no layout opts
|
|
94
|
+
* in, discovery falls back to scanning all layouts with provider-scoped npm
|
|
95
|
+
* collection.
|
|
96
|
+
*
|
|
97
|
+
* @example
|
|
98
|
+
* ```ts
|
|
99
|
+
* export const QueryRootLayout = eco.layout({
|
|
100
|
+
* runtimeProvider: true,
|
|
101
|
+
* render: ({ children }) => <QueryProvider>{children}</QueryProvider>,
|
|
102
|
+
* });
|
|
103
|
+
*
|
|
104
|
+
* reactPlugin({
|
|
105
|
+
* router: ecoRouter(),
|
|
106
|
+
* });
|
|
107
|
+
* ```
|
|
108
|
+
*
|
|
109
|
+
* @example Advanced vendor config
|
|
110
|
+
* ```ts
|
|
111
|
+
* runtimeModules: [
|
|
112
|
+
* { specifier: '@acme/ui', outputName: 'acme-ui', externals: ['react'] },
|
|
113
|
+
* ]
|
|
114
|
+
* ```
|
|
115
|
+
*/
|
|
116
|
+
runtimeModules?: ReactPluginRuntimeModule[];
|
|
117
|
+
/**
|
|
118
|
+
* MDX configuration for handling .mdx files within the React plugin.
|
|
119
|
+
* When enabled, MDX files are treated as React pages with full router support.
|
|
120
|
+
* @example
|
|
121
|
+
* ```ts
|
|
122
|
+
* reactPlugin({
|
|
123
|
+
* router: ecoRouter(),
|
|
124
|
+
* mdx: {
|
|
125
|
+
* enabled: true,
|
|
126
|
+
* extensions: ['.mdx', '.md'],
|
|
127
|
+
* remarkPlugins: [remarkGfm],
|
|
128
|
+
* rehypePlugins: [[rehypePrettyCode, { theme: '...' }]],
|
|
129
|
+
* }
|
|
130
|
+
* })
|
|
131
|
+
* ```
|
|
132
|
+
*/
|
|
133
|
+
mdx?: ReactMdxOptions;
|
|
134
|
+
};
|
|
135
|
+
export type ReactRendererConfig = {
|
|
136
|
+
routerAdapter?: ReactRouterAdapter;
|
|
137
|
+
runtimeModules?: ResolvedReactPluginRuntimeModule[];
|
|
138
|
+
mdxCompilerOptions?: CompileOptions;
|
|
139
|
+
mdxExtensions?: string[];
|
|
140
|
+
hmrPageMetadataCache?: HmrPageMetadataCache;
|
|
141
|
+
/**
|
|
142
|
+
* When true, always emit page browser graph / hydration assets for React pages.
|
|
143
|
+
*
|
|
144
|
+
* @remarks
|
|
145
|
+
* Mapped from the public `explicitGraph` plugin option. Does not skip the
|
|
146
|
+
* client-graph AST strip of server-only `eco.page(...)` options.
|
|
147
|
+
*/
|
|
148
|
+
forceBrowserGraph?: boolean;
|
|
149
|
+
};
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Ownership helpers for deciding whether a component stays in the React render lane.
|
|
3
|
+
*/
|
|
4
|
+
import type { EcoComponent, EcoComponentConfig, EcoPagesElement } from '@ecopages/core';
|
|
5
|
+
import type { FunctionComponent } from 'react';
|
|
6
|
+
export type SerializableProps = Record<string, unknown>;
|
|
7
|
+
export type ReactRenderableComponent<P extends SerializableProps = SerializableProps> = FunctionComponent<P> & {
|
|
8
|
+
config?: EcoComponentConfig;
|
|
9
|
+
requires?: string | readonly string[];
|
|
10
|
+
};
|
|
11
|
+
export type RequiresAwareComponent = {
|
|
12
|
+
requires?: string | readonly string[];
|
|
13
|
+
};
|
|
14
|
+
/**
|
|
15
|
+
* Reads the declared integration name for a component or layout.
|
|
16
|
+
*
|
|
17
|
+
* @remarks
|
|
18
|
+
* Honors both the explicit `config.integration` override and injected
|
|
19
|
+
* `config.__eco.integration` metadata because pages can arrive through authored
|
|
20
|
+
* config as well as build-time component metadata.
|
|
21
|
+
*/
|
|
22
|
+
export declare function getComponentIntegration(component?: {
|
|
23
|
+
config?: EcoComponentConfig;
|
|
24
|
+
} | null): string | undefined;
|
|
25
|
+
/**
|
|
26
|
+
* Returns whether a component should stay inside the React render lane.
|
|
27
|
+
*
|
|
28
|
+
* @remarks
|
|
29
|
+
* Components without explicit integration metadata are treated as React-owned
|
|
30
|
+
* because this renderer only receives them after the route pipeline has already
|
|
31
|
+
* selected the React integration.
|
|
32
|
+
*/
|
|
33
|
+
export declare function isReactManagedComponent(component: {
|
|
34
|
+
config?: EcoComponentConfig;
|
|
35
|
+
} | null | undefined, reactIntegrationName: string): boolean;
|
|
36
|
+
export declare function getComponentRequires(component?: (EcoComponent & RequiresAwareComponent) | null): string | readonly string[] | undefined;
|
|
37
|
+
/**
|
|
38
|
+
* Commits a framework-agnostic component to React semantics.
|
|
39
|
+
*
|
|
40
|
+
* @remarks
|
|
41
|
+
* Core keeps `EcoComponent` broad so integrations can share the same public surface;
|
|
42
|
+
* once the React renderer is executing, `createElement()` needs a concrete React
|
|
43
|
+
* component signature.
|
|
44
|
+
*/
|
|
45
|
+
export declare function asReactComponent<P extends SerializableProps>(component: unknown): ReactRenderableComponent<P>;
|
|
46
|
+
/**
|
|
47
|
+
* Commits a mixed-shell component to the string-returning contract required by
|
|
48
|
+
* non-React layouts and HTML templates.
|
|
49
|
+
*/
|
|
50
|
+
export declare function asNonReactShellComponent<P extends SerializableProps>(component: unknown): (props: P) => EcoPagesElement | Promise<EcoPagesElement>;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
function getComponentIntegration(component) {
|
|
2
|
+
return component?.config?.integration ?? component?.config?.__eco?.integration;
|
|
3
|
+
}
|
|
4
|
+
function isReactManagedComponent(component, reactIntegrationName) {
|
|
5
|
+
const integration = getComponentIntegration(component);
|
|
6
|
+
return integration === void 0 || integration === reactIntegrationName;
|
|
7
|
+
}
|
|
8
|
+
function getComponentRequires(component) {
|
|
9
|
+
return component?.requires;
|
|
10
|
+
}
|
|
11
|
+
function asReactComponent(component) {
|
|
12
|
+
return component;
|
|
13
|
+
}
|
|
14
|
+
function asNonReactShellComponent(component) {
|
|
15
|
+
return component;
|
|
16
|
+
}
|
|
17
|
+
export {
|
|
18
|
+
asNonReactShellComponent,
|
|
19
|
+
asReactComponent,
|
|
20
|
+
getComponentIntegration,
|
|
21
|
+
getComponentRequires,
|
|
22
|
+
isReactManagedComponent
|
|
23
|
+
};
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* React component SSR helpers: renderToString, foreign-subtree HTML, island attributes.
|
|
3
|
+
*/
|
|
4
|
+
import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement } from '@ecopages/core';
|
|
5
|
+
import type { ProcessedAsset } from '@ecopages/core/services/asset-processing-service';
|
|
6
|
+
import type { IntegrationRenderer } from '@ecopages/core/route-renderer/orchestration/integration-renderer';
|
|
7
|
+
import type { ReactNode } from 'react';
|
|
8
|
+
import { type HydrationAssetService } from '../hydration/hydration-asset.js';
|
|
9
|
+
import { type SerializableProps } from './component-ownership.js';
|
|
10
|
+
import type { ReactRuntimeModules } from './react-runtime.js';
|
|
11
|
+
export type ReactComponentRenderContext = {
|
|
12
|
+
componentInstanceId?: string;
|
|
13
|
+
};
|
|
14
|
+
export type ReactForeignSubtreeResolutionContext = {
|
|
15
|
+
rendererCache: Map<string, IntegrationRenderer<any>>;
|
|
16
|
+
componentInstanceScope?: string;
|
|
17
|
+
nextForeignSubtreeId: number;
|
|
18
|
+
queuedResolutions: Array<{
|
|
19
|
+
token: string;
|
|
20
|
+
component: EcoComponent;
|
|
21
|
+
props: Record<string, unknown>;
|
|
22
|
+
componentInstanceId: string;
|
|
23
|
+
}>;
|
|
24
|
+
rawChildrenToken?: string;
|
|
25
|
+
rawChildrenHtml?: string;
|
|
26
|
+
};
|
|
27
|
+
export declare function buildHydrationProps(props: SerializableProps | undefined): SerializableProps;
|
|
28
|
+
/**
|
|
29
|
+
* Renders a non-React layout or HTML template and enforces that mixed shells
|
|
30
|
+
* return serialized HTML.
|
|
31
|
+
*/
|
|
32
|
+
export declare function renderNonReactShellComponent<P extends SerializableProps>(Component: (props: P) => EcoPagesElement | Promise<EcoPagesElement>, props: P, label: 'Layout' | 'HtmlTemplate' | 'Component'): Promise<string>;
|
|
33
|
+
/**
|
|
34
|
+
* Renders one React component while preserving already-resolved child HTML.
|
|
35
|
+
*
|
|
36
|
+
* @remarks
|
|
37
|
+
* When nested foreign-subtree resolution has already produced child HTML, the child
|
|
38
|
+
* payload must remain raw SSR output rather than a React string child, otherwise
|
|
39
|
+
* React would escape it. This helper renders a unique token through React and swaps
|
|
40
|
+
* that token back to the resolved HTML afterward.
|
|
41
|
+
*/
|
|
42
|
+
export declare function renderComponentHtml(options: {
|
|
43
|
+
input: ComponentRenderInput;
|
|
44
|
+
context: ReactComponentRenderContext;
|
|
45
|
+
runtimeContext?: ReactForeignSubtreeResolutionContext;
|
|
46
|
+
runtime: ReactRuntimeModules;
|
|
47
|
+
normalizeUnresolvedMarkerArtifactHtml: (html: string) => string;
|
|
48
|
+
}): string;
|
|
49
|
+
export declare function toReactNode(children: unknown, integrationName: string): ReactNode;
|
|
50
|
+
/**
|
|
51
|
+
* Restores raw child HTML placeholders stored on the foreign-subtree runtime context.
|
|
52
|
+
*
|
|
53
|
+
* @remarks
|
|
54
|
+
* Queued foreign-subtree resolution may render children through a fragment path before
|
|
55
|
+
* nested integration tokens are resolved. React must never see resolved child HTML as a
|
|
56
|
+
* normal string child or it would escape it.
|
|
57
|
+
*/
|
|
58
|
+
export declare function restoreRuntimeChildHtml(html: string, runtimeContext: ReactForeignSubtreeResolutionContext | undefined): string;
|
|
59
|
+
export declare function renderQueuedChildrenToHtml(options: {
|
|
60
|
+
children: unknown;
|
|
61
|
+
runtimeContext: ReactForeignSubtreeResolutionContext;
|
|
62
|
+
queuedResolutionsByToken: Map<string, ReactForeignSubtreeResolutionContext['queuedResolutions'][number]>;
|
|
63
|
+
resolveToken: (token: string) => Promise<string>;
|
|
64
|
+
runtime: ReactRuntimeModules;
|
|
65
|
+
integrationName: string;
|
|
66
|
+
normalizeUnresolvedMarkerArtifactHtml: (html: string) => string;
|
|
67
|
+
resolveQueuedTokens: (html: string, queuedResolutionsByToken: Map<string, ReactForeignSubtreeResolutionContext['queuedResolutions'][number]>, resolveToken: (token: string) => Promise<string>) => Promise<string>;
|
|
68
|
+
}): Promise<string | undefined>;
|
|
69
|
+
export declare function renderReactQueuedForeignSubtreeChildren(options: {
|
|
70
|
+
children: unknown;
|
|
71
|
+
currentRuntimeContext: ReactForeignSubtreeResolutionContext;
|
|
72
|
+
queuedResolutionsByToken: Map<string, ReactForeignSubtreeResolutionContext['queuedResolutions'][number]>;
|
|
73
|
+
resolveToken: (token: string) => Promise<string>;
|
|
74
|
+
runtime: ReactRuntimeModules;
|
|
75
|
+
integrationName: string;
|
|
76
|
+
normalizeUnresolvedMarkerArtifactHtml: (html: string) => string;
|
|
77
|
+
resolveQueuedTokens: (html: string, queuedResolutionsByToken: Map<string, ReactForeignSubtreeResolutionContext['queuedResolutions'][number]>, resolveToken: (token: string) => Promise<string>) => Promise<string>;
|
|
78
|
+
}): Promise<{
|
|
79
|
+
assets: ProcessedAsset[];
|
|
80
|
+
html?: string;
|
|
81
|
+
}>;
|
|
82
|
+
export declare function renderForeignComponentWithSerializedHtml(options: {
|
|
83
|
+
input: ComponentRenderInput;
|
|
84
|
+
runtimeContext: ReactForeignSubtreeResolutionContext | undefined;
|
|
85
|
+
integrationName: string;
|
|
86
|
+
canResolveAssets: boolean;
|
|
87
|
+
processComponentDependencies: (components: EcoComponent[]) => Promise<ProcessedAsset[]>;
|
|
88
|
+
dedupeProcessedAssets: (assets: ProcessedAsset[]) => ProcessedAsset[];
|
|
89
|
+
getRootTagName: (html: string) => string | undefined;
|
|
90
|
+
resolveQueuedForeignSubtreeHtml: (html: string, runtimeContext: ReactForeignSubtreeResolutionContext | undefined) => Promise<{
|
|
91
|
+
assets: ProcessedAsset[];
|
|
92
|
+
html: string;
|
|
93
|
+
}>;
|
|
94
|
+
}): Promise<ComponentRenderResult>;
|
|
95
|
+
export declare function renderReactManagedComponent(options: {
|
|
96
|
+
input: ComponentRenderInput;
|
|
97
|
+
runtimeContext: ReactForeignSubtreeResolutionContext | undefined;
|
|
98
|
+
runtime: ReactRuntimeModules;
|
|
99
|
+
integrationName: string;
|
|
100
|
+
normalizeUnresolvedMarkerArtifactHtml: (html: string) => string;
|
|
101
|
+
resolveQueuedForeignSubtreeHtml: (html: string, runtimeContext: ReactForeignSubtreeResolutionContext | undefined) => Promise<{
|
|
102
|
+
assets: ProcessedAsset[];
|
|
103
|
+
html: string;
|
|
104
|
+
}>;
|
|
105
|
+
getRootTagName: (html: string) => string | undefined;
|
|
106
|
+
dedupeProcessedAssets: (assets: ProcessedAsset[]) => ProcessedAsset[];
|
|
107
|
+
hydrationAssetService: HydrationAssetService;
|
|
108
|
+
canBuildIslandAssets: boolean;
|
|
109
|
+
}): Promise<ComponentRenderResult>;
|
|
110
|
+
export declare function createForeignSubtreeRuntimeContext(options: {
|
|
111
|
+
rendererCache: Map<string, IntegrationRenderer<any>>;
|
|
112
|
+
componentInstanceScope?: string;
|
|
113
|
+
}): ReactForeignSubtreeResolutionContext;
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
import { isValidElement } from "react";
|
|
2
|
+
import { hasSingleRootElement } from "./html-boundary.js";
|
|
3
|
+
import { getIslandComponentKey } from "../hydration/hydration-asset.js";
|
|
4
|
+
import { asNonReactShellComponent, asReactComponent } from "./component-ownership.js";
|
|
5
|
+
import { ReactRenderError } from "./errors.js";
|
|
6
|
+
function buildHydrationProps(props) {
|
|
7
|
+
if (!props || !Object.prototype.hasOwnProperty.call(props, "locals")) {
|
|
8
|
+
return props ?? {};
|
|
9
|
+
}
|
|
10
|
+
const { locals: _locals, ...hydrationProps } = props;
|
|
11
|
+
return hydrationProps;
|
|
12
|
+
}
|
|
13
|
+
async function renderNonReactShellComponent(Component, props, label) {
|
|
14
|
+
const output = await Component(props);
|
|
15
|
+
if (typeof output === "string") {
|
|
16
|
+
return output;
|
|
17
|
+
}
|
|
18
|
+
throw new ReactRenderError(`${label} must return a string when used as a mixed shell for React pages.`);
|
|
19
|
+
}
|
|
20
|
+
function renderComponentHtml(options) {
|
|
21
|
+
const { input, context, runtimeContext, runtime, normalizeUnresolvedMarkerArtifactHtml } = options;
|
|
22
|
+
const { react, reactDomServer } = runtime;
|
|
23
|
+
if (input.children === void 0) {
|
|
24
|
+
return normalizeUnresolvedMarkerArtifactHtml(
|
|
25
|
+
reactDomServer.renderToString(react.createElement(asReactComponent(input.component), input.props))
|
|
26
|
+
);
|
|
27
|
+
}
|
|
28
|
+
if (isValidElement(input.children)) {
|
|
29
|
+
return normalizeUnresolvedMarkerArtifactHtml(
|
|
30
|
+
reactDomServer.renderToString(
|
|
31
|
+
react.createElement(asReactComponent(input.component), input.props, input.children)
|
|
32
|
+
)
|
|
33
|
+
);
|
|
34
|
+
}
|
|
35
|
+
const resolvedChildHtml = typeof input.children === "string" ? input.children : String(input.children ?? "");
|
|
36
|
+
const rawChildrenToken = `__ECO_RAW_HTML_CHILD_${context.componentInstanceId ?? "component"}__`;
|
|
37
|
+
if (runtimeContext) {
|
|
38
|
+
runtimeContext.rawChildrenToken = rawChildrenToken;
|
|
39
|
+
runtimeContext.rawChildrenHtml = resolvedChildHtml;
|
|
40
|
+
}
|
|
41
|
+
const html = reactDomServer.renderToString(
|
|
42
|
+
react.createElement(asReactComponent(input.component), input.props, rawChildrenToken)
|
|
43
|
+
);
|
|
44
|
+
return normalizeUnresolvedMarkerArtifactHtml(html.split(rawChildrenToken).join(resolvedChildHtml));
|
|
45
|
+
}
|
|
46
|
+
function toReactNode(children, integrationName) {
|
|
47
|
+
if (children === null || typeof children === "string" || typeof children === "number" || typeof children === "boolean" || isValidElement(children) || Array.isArray(children)) {
|
|
48
|
+
return children;
|
|
49
|
+
}
|
|
50
|
+
throw new TypeError(`[ecopages] ${integrationName} renderer expected a React node child.`);
|
|
51
|
+
}
|
|
52
|
+
function restoreRuntimeChildHtml(html, runtimeContext) {
|
|
53
|
+
if (!runtimeContext?.rawChildrenToken || runtimeContext.rawChildrenHtml === void 0) {
|
|
54
|
+
return html;
|
|
55
|
+
}
|
|
56
|
+
return html.split(runtimeContext.rawChildrenToken).join(runtimeContext.rawChildrenHtml);
|
|
57
|
+
}
|
|
58
|
+
async function renderQueuedChildrenToHtml(options) {
|
|
59
|
+
const {
|
|
60
|
+
children,
|
|
61
|
+
runtimeContext,
|
|
62
|
+
queuedResolutionsByToken,
|
|
63
|
+
resolveToken,
|
|
64
|
+
runtime,
|
|
65
|
+
integrationName,
|
|
66
|
+
normalizeUnresolvedMarkerArtifactHtml,
|
|
67
|
+
resolveQueuedTokens
|
|
68
|
+
} = options;
|
|
69
|
+
if (children === void 0) {
|
|
70
|
+
return void 0;
|
|
71
|
+
}
|
|
72
|
+
const { react, reactDomServer } = runtime;
|
|
73
|
+
let html = normalizeUnresolvedMarkerArtifactHtml(
|
|
74
|
+
reactDomServer.renderToString(
|
|
75
|
+
react.createElement(react.Fragment, null, toReactNode(children, integrationName))
|
|
76
|
+
)
|
|
77
|
+
);
|
|
78
|
+
html = restoreRuntimeChildHtml(html, runtimeContext);
|
|
79
|
+
return await resolveQueuedTokens(html, queuedResolutionsByToken, resolveToken);
|
|
80
|
+
}
|
|
81
|
+
async function renderReactQueuedForeignSubtreeChildren(options) {
|
|
82
|
+
const { currentRuntimeContext, ...rest } = options;
|
|
83
|
+
const renderedHtml = await renderQueuedChildrenToHtml({
|
|
84
|
+
...rest,
|
|
85
|
+
runtimeContext: currentRuntimeContext
|
|
86
|
+
});
|
|
87
|
+
if (renderedHtml === void 0) {
|
|
88
|
+
return { assets: [] };
|
|
89
|
+
}
|
|
90
|
+
return {
|
|
91
|
+
assets: [],
|
|
92
|
+
html: renderedHtml
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
async function renderForeignComponentWithSerializedHtml(options) {
|
|
96
|
+
const {
|
|
97
|
+
input,
|
|
98
|
+
runtimeContext,
|
|
99
|
+
integrationName,
|
|
100
|
+
canResolveAssets,
|
|
101
|
+
processComponentDependencies,
|
|
102
|
+
dedupeProcessedAssets,
|
|
103
|
+
getRootTagName,
|
|
104
|
+
resolveQueuedForeignSubtreeHtml
|
|
105
|
+
} = options;
|
|
106
|
+
let props = input.props;
|
|
107
|
+
if (input.children !== void 0) {
|
|
108
|
+
props = {
|
|
109
|
+
...input.props,
|
|
110
|
+
children: typeof input.children === "string" ? input.children : String(input.children ?? "")
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
const html = await renderNonReactShellComponent(
|
|
114
|
+
asNonReactShellComponent(input.component),
|
|
115
|
+
props,
|
|
116
|
+
"Component"
|
|
117
|
+
);
|
|
118
|
+
const hasDependencies = Boolean(input.component.config?.dependencies);
|
|
119
|
+
const assets = hasDependencies && canResolveAssets ? await processComponentDependencies([input.component]) : void 0;
|
|
120
|
+
const queuedForeignSubtreeResolution = await resolveQueuedForeignSubtreeHtml(html, runtimeContext);
|
|
121
|
+
const mergedAssets = dedupeProcessedAssets([...assets ?? [], ...queuedForeignSubtreeResolution.assets]);
|
|
122
|
+
return {
|
|
123
|
+
html: queuedForeignSubtreeResolution.html,
|
|
124
|
+
canAttachAttributes: true,
|
|
125
|
+
rootTag: getRootTagName(queuedForeignSubtreeResolution.html),
|
|
126
|
+
integrationName,
|
|
127
|
+
assets: mergedAssets.length > 0 ? mergedAssets : void 0
|
|
128
|
+
};
|
|
129
|
+
}
|
|
130
|
+
async function renderReactManagedComponent(options) {
|
|
131
|
+
const {
|
|
132
|
+
input,
|
|
133
|
+
runtimeContext,
|
|
134
|
+
runtime,
|
|
135
|
+
integrationName,
|
|
136
|
+
normalizeUnresolvedMarkerArtifactHtml,
|
|
137
|
+
resolveQueuedForeignSubtreeHtml,
|
|
138
|
+
getRootTagName,
|
|
139
|
+
dedupeProcessedAssets,
|
|
140
|
+
hydrationAssetService,
|
|
141
|
+
canBuildIslandAssets
|
|
142
|
+
} = options;
|
|
143
|
+
const componentConfig = input.component.config;
|
|
144
|
+
const context = {
|
|
145
|
+
componentInstanceId: input.integrationContext?.componentInstanceId
|
|
146
|
+
};
|
|
147
|
+
const hasResolvedChildHtml = input.children !== void 0;
|
|
148
|
+
let html = renderComponentHtml({
|
|
149
|
+
input,
|
|
150
|
+
context,
|
|
151
|
+
runtimeContext,
|
|
152
|
+
runtime,
|
|
153
|
+
normalizeUnresolvedMarkerArtifactHtml
|
|
154
|
+
});
|
|
155
|
+
const queuedForeignSubtreeResolution = await resolveQueuedForeignSubtreeHtml(html, runtimeContext);
|
|
156
|
+
html = queuedForeignSubtreeResolution.html;
|
|
157
|
+
const canAttachAttributes = hasSingleRootElement(html);
|
|
158
|
+
const rootTag = getRootTagName(html);
|
|
159
|
+
const componentFile = componentConfig?.__eco?.file;
|
|
160
|
+
let rootAttributes;
|
|
161
|
+
let assets;
|
|
162
|
+
if (canAttachAttributes && componentFile && context.componentInstanceId && canBuildIslandAssets && !hasResolvedChildHtml) {
|
|
163
|
+
const componentInstanceId = context.componentInstanceId;
|
|
164
|
+
assets = await hydrationAssetService.buildComponentRenderAssets(componentFile, componentConfig);
|
|
165
|
+
rootAttributes = {
|
|
166
|
+
"data-eco-component-id": componentInstanceId,
|
|
167
|
+
"data-eco-component-key": getIslandComponentKey(componentFile, componentConfig),
|
|
168
|
+
"data-eco-props": btoa(JSON.stringify(buildHydrationProps(input.props)))
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
const mergedAssets = dedupeProcessedAssets([...assets ?? [], ...queuedForeignSubtreeResolution.assets]);
|
|
172
|
+
return {
|
|
173
|
+
html,
|
|
174
|
+
canAttachAttributes,
|
|
175
|
+
rootTag,
|
|
176
|
+
integrationName,
|
|
177
|
+
rootAttributes,
|
|
178
|
+
assets: mergedAssets.length > 0 ? mergedAssets : void 0
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
function createForeignSubtreeRuntimeContext(options) {
|
|
182
|
+
return {
|
|
183
|
+
rendererCache: options.rendererCache,
|
|
184
|
+
componentInstanceScope: options.componentInstanceScope,
|
|
185
|
+
nextForeignSubtreeId: 0,
|
|
186
|
+
queuedResolutions: [],
|
|
187
|
+
rawChildrenToken: void 0,
|
|
188
|
+
rawChildrenHtml: void 0
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
export {
|
|
192
|
+
buildHydrationProps,
|
|
193
|
+
createForeignSubtreeRuntimeContext,
|
|
194
|
+
renderComponentHtml,
|
|
195
|
+
renderForeignComponentWithSerializedHtml,
|
|
196
|
+
renderNonReactShellComponent,
|
|
197
|
+
renderQueuedChildrenToHtml,
|
|
198
|
+
renderReactManagedComponent,
|
|
199
|
+
renderReactQueuedForeignSubtreeChildren,
|
|
200
|
+
restoreRuntimeChildHtml,
|
|
201
|
+
toReactNode
|
|
202
|
+
};
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Errors thrown by the React integration renderer and bundling paths.
|
|
3
|
+
*/
|
|
4
|
+
/**
|
|
5
|
+
* Error thrown when an error occurs while rendering a React component.
|
|
6
|
+
*/
|
|
7
|
+
export declare class ReactRenderError extends Error {
|
|
8
|
+
constructor(message: string);
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Error thrown when an error occurs while bundling a React component.
|
|
12
|
+
*/
|
|
13
|
+
export declare class BundleError extends Error {
|
|
14
|
+
readonly logs: string[];
|
|
15
|
+
constructor(message: string, logs: string[]);
|
|
16
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
class ReactRenderError extends Error {
|
|
2
|
+
constructor(message) {
|
|
3
|
+
super(message);
|
|
4
|
+
this.name = "ReactRenderError";
|
|
5
|
+
}
|
|
6
|
+
}
|
|
7
|
+
class BundleError extends Error {
|
|
8
|
+
logs;
|
|
9
|
+
constructor(message, logs) {
|
|
10
|
+
super(message);
|
|
11
|
+
this.name = "BundleError";
|
|
12
|
+
this.logs = logs;
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
export {
|
|
16
|
+
BundleError,
|
|
17
|
+
ReactRenderError
|
|
18
|
+
};
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import * as bundledReact from 'react';
|
|
2
|
+
import type { FunctionComponent, ReactElement } from 'react';
|
|
3
|
+
import type { EcoComponent, EcoDeclaredComponent, EcoPageLayoutEntry, LayoutPropsContext } from '@ecopages/core';
|
|
4
|
+
import type { EcoComponentConfig } from '@ecopages/core';
|
|
5
|
+
export type LayoutComposeContext = LayoutPropsContext;
|
|
6
|
+
export type ReactRuntime = typeof bundledReact;
|
|
7
|
+
export type LayoutComposeOptions = {
|
|
8
|
+
context?: LayoutComposeContext;
|
|
9
|
+
/** @remarks Pass the app-resolved React runtime during SSR so composition matches `renderToString`. */
|
|
10
|
+
react?: ReactRuntime;
|
|
11
|
+
/**
|
|
12
|
+
* Optional resolver that substitutes cached layout instances and React keys
|
|
13
|
+
* for SPA layout persistence.
|
|
14
|
+
*/
|
|
15
|
+
resolvePersistedTier?: (layout: EcoComponent, index: number) => {
|
|
16
|
+
layout: EcoComponent;
|
|
17
|
+
key?: string;
|
|
18
|
+
};
|
|
19
|
+
};
|
|
20
|
+
export type LayoutShellEntry = {
|
|
21
|
+
component: EcoComponent;
|
|
22
|
+
props?: Record<string, unknown>;
|
|
23
|
+
};
|
|
24
|
+
export type ComposablePage<P extends Record<string, unknown> = Record<string, unknown>> = FunctionComponent<P> & {
|
|
25
|
+
config?: Pick<EcoComponentConfig, 'layouts' | 'layoutEntries'>;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Reads request-scoped layout context from serialized page props.
|
|
29
|
+
*/
|
|
30
|
+
export declare function resolveLayoutContext(pageProps: Record<string, unknown>): LayoutComposeContext;
|
|
31
|
+
/**
|
|
32
|
+
* Builds layout prop factory context from document-shell layout entries.
|
|
33
|
+
*
|
|
34
|
+
* @remarks
|
|
35
|
+
* Route-scoped `locals` come from shell layout props, not `pageProps.locals` (pageLocals).
|
|
36
|
+
*/
|
|
37
|
+
export declare function resolveLayoutContextFromShell(pageProps: Record<string, unknown>, shellLayouts: LayoutShellEntry[]): LayoutComposeContext;
|
|
38
|
+
/**
|
|
39
|
+
* Resolves props for one layout entry, merging shell locals with an optional factory.
|
|
40
|
+
*/
|
|
41
|
+
export declare function resolveLayoutEntryProps(entry: EcoPageLayoutEntry, context: LayoutComposeContext): Record<string, unknown>;
|
|
42
|
+
/**
|
|
43
|
+
* @remarks
|
|
44
|
+
* Eco page components are wider than React layout composition input; runtime checks narrow callables.
|
|
45
|
+
*/
|
|
46
|
+
export declare function assertComposablePage(Page: unknown): ComposablePage;
|
|
47
|
+
/**
|
|
48
|
+
* Builds the client or SSR React tree for a page and its outer→inner layout stack.
|
|
49
|
+
*
|
|
50
|
+
* @remarks
|
|
51
|
+
* Layout prop factories receive `LayoutPropsContext`. For SSR, pass `options.react` from the
|
|
52
|
+
* app-resolved runtime. Client code can omit it and use the bundled React import.
|
|
53
|
+
*/
|
|
54
|
+
export declare function composeLayoutPageTree<P extends Record<string, unknown>>(Page: ComposablePage<P>, pageProps: P, options?: LayoutComposeOptions): ReactElement;
|
|
55
|
+
/**
|
|
56
|
+
* Builds a layout tree from explicit document-shell layout entries.
|
|
57
|
+
*
|
|
58
|
+
* @remarks
|
|
59
|
+
* Use when the route renderer passes per-tier props (e.g. route `locals` on the layout tier).
|
|
60
|
+
* Shell `entry.props` are authoritative; page config normalization is not required.
|
|
61
|
+
*/
|
|
62
|
+
export declare function composeLayoutPageTreeFromShell<P extends Record<string, unknown>>(Page: ComposablePage<P>, pageProps: P, shellLayouts: LayoutShellEntry[], options?: LayoutComposeOptions): ReactElement;
|
|
63
|
+
/**
|
|
64
|
+
* Normalizes page config layout metadata to an outer→inner component list.
|
|
65
|
+
*/
|
|
66
|
+
export declare function normalizePageLayoutComponents(layouts?: EcoDeclaredComponent[]): EcoDeclaredComponent[];
|