@ecopages/core 0.2.0-beta.30 → 0.2.0-beta.32

package/src/route-renderer/orchestration/document-shell/document-shell-render.service.js

@@ -1,148 +1,155 @@
-import {
-  HtmlTransformerService
-} from "../../../services/html/html-transformer.service.js";
+import { HtmlTransformerService, } from '../../../services/html/html-transformer.service.js';
 function resolveDocumentShellLayouts(input) {
-  if (input.layouts && input.layouts.length > 0) {
-    return input.layouts;
-  }
-  return input.layout ? [input.layout] : [];
+    if (input.layouts && input.layouts.length > 0) {
+        return input.layouts;
+    }
+    return input.layout ? [input.layout] : [];
 }
 function resolveComponentIntegrationName(component) {
-  return component.config?.integration ?? component.config?.__eco?.integration ?? "ecopages";
+    return component.config?.integration ?? component.config?.__eco?.integration ?? 'ecopages';
 }
-async function composeSequentialLayoutChildren(context) {
-  if (!context.primaryRender) {
-    throw new Error("[ecopages] composeSequentialLayoutChildren requires primaryRender.");
-  }
-  let children = context.primaryRender.html;
-  const layoutRenders = [];
-  for (const layout of [...context.layouts].reverse()) {
-    const layoutRender = await context.renderComponentWithForeignChildren({
-      component: layout.component,
-      props: layout.props ?? {},
-      children,
-      integrationContext: { rendererCache: context.rendererCache }
-    });
-    layoutRenders.push(layoutRender);
-    children = layoutRender.html;
-  }
-  return {
-    children,
-    layoutRenders
-  };
+/**
+ * Default sequential string-child composition for document shell layers.
+ */
+export async function composeSequentialLayoutChildren(context) {
+    if (!context.primaryRender) {
+        throw new Error('[ecopages] composeSequentialLayoutChildren requires primaryRender.');
+    }
+    let children = context.primaryRender.html;
+    const layoutRenders = [];
+    for (const layout of [...context.layouts].reverse()) {
+        const layoutRender = await context.renderComponentWithForeignChildren({
+            component: layout.component,
+            props: layout.props ?? {},
+            children,
+            integrationContext: { rendererCache: context.rendererCache },
+        });
+        layoutRenders.push(layoutRender);
+        children = layoutRender.html;
+    }
+    return {
+        children,
+        layoutRenders,
+    };
 }
-async function composeDocumentShell(dependencies, input) {
-  const rendererCache = /* @__PURE__ */ new Map();
-  const layouts = resolveDocumentShellLayouts(input);
-  const composeChildren = input.composeChildren ?? composeSequentialLayoutChildren;
-  const usesCustomComposeChildren = input.composeChildren !== void 0;
-  let primaryRender;
-  let children;
-  let layoutRenders;
-  if (usesCustomComposeChildren) {
-    const composed = await composeChildren({
-      primaryComponent: input.primaryComponent,
-      primaryProps: input.primaryProps,
-      layouts,
-      rendererCache,
-      renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren
+/**
+ * Composes page or view content through optional layout and document shells.
+ *
+ * One execution-scoped renderer cache is threaded through every shell layer so
+ * repeated foreign delegation reuses initialized renderers within one render pass.
+ */
+export async function composeDocumentShell(dependencies, input) {
+    const rendererCache = new Map();
+    const layouts = resolveDocumentShellLayouts(input);
+    const composeChildren = input.composeChildren ?? composeSequentialLayoutChildren;
+    const usesCustomComposeChildren = input.composeChildren !== undefined;
+    let primaryRender;
+    let children;
+    let layoutRenders;
+    if (usesCustomComposeChildren) {
+        const composed = await composeChildren({
+            primaryComponent: input.primaryComponent,
+            primaryProps: input.primaryProps,
+            layouts,
+            rendererCache,
+            renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren,
+        });
+        children = composed.children;
+        layoutRenders = composed.layoutRenders;
+        primaryRender = composed.primaryRender ?? {
+            html: typeof composed.children === 'string' ? composed.children : '',
+            assets: [],
+            canAttachAttributes: true,
+            rootTag: 'main',
+            integrationName: resolveComponentIntegrationName(input.primaryComponent),
+        };
+    }
+    else {
+        primaryRender = await dependencies.renderComponentWithForeignChildren({
+            component: input.primaryComponent,
+            props: input.primaryProps,
+            integrationContext: { rendererCache },
+        });
+        const composed = await composeChildren({
+            primaryComponent: input.primaryComponent,
+            primaryProps: input.primaryProps,
+            primaryRender,
+            layouts,
+            rendererCache,
+            renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren,
+        });
+        children = composed.children;
+        layoutRenders = composed.layoutRenders;
+    }
+    const documentRender = await dependencies.renderComponentWithForeignChildren({
+        component: input.htmlTemplate,
+        props: input.documentProps,
+        children,
+        integrationContext: { rendererCache },
     });
-    children = composed.children;
-    layoutRenders = composed.layoutRenders;
-    primaryRender = composed.primaryRender ?? {
-      html: typeof composed.children === "string" ? composed.children : "",
-      assets: [],
-      canAttachAttributes: true,
-      rootTag: "main",
-      integrationName: resolveComponentIntegrationName(input.primaryComponent)
+    dependencies.appendProcessedDependencies(primaryRender.assets, ...layoutRenders.map((layoutRender) => layoutRender.assets), documentRender.assets);
+    return {
+        documentHtml: documentRender.html,
     };
-  } else {
-    primaryRender = await dependencies.renderComponentWithForeignChildren({
-      component: input.primaryComponent,
-      props: input.primaryProps,
-      integrationContext: { rendererCache }
-    });
-    const composed = await composeChildren({
-      primaryComponent: input.primaryComponent,
-      primaryProps: input.primaryProps,
-      primaryRender,
-      layouts,
-      rendererCache,
-      renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren
-    });
-    children = composed.children;
-    layoutRenders = composed.layoutRenders;
-  }
-  const documentRender = await dependencies.renderComponentWithForeignChildren({
-    component: input.htmlTemplate,
-    props: input.documentProps,
-    children,
-    integrationContext: { rendererCache }
-  });
-  dependencies.appendProcessedDependencies(
-    primaryRender.assets,
-    ...layoutRenders.map((layoutRender) => layoutRender.assets),
-    documentRender.assets
-  );
-  return {
-    documentHtml: documentRender.html
-  };
 }
-function applyDocumentShellAttributeStamping(html, stamping, options) {
-  let nextHtml = html;
-  if (options.componentRootAttributes && Object.keys(options.componentRootAttributes).length > 0) {
-    nextHtml = stamping.applyAttributesToFirstBodyElement(nextHtml, options.componentRootAttributes);
-  }
-  if (options.documentAttributes && Object.keys(options.documentAttributes).length > 0) {
-    nextHtml = stamping.applyAttributesToHtmlElement(nextHtml, options.documentAttributes);
-  }
-  return nextHtml;
-}
-async function renderPageDocumentShell(dependencies, input, docType) {
-  const { documentHtml: composedDocumentHtml } = await composeDocumentShell(dependencies, {
-    primaryComponent: input.page.component,
-    primaryProps: input.page.props,
-    layout: input.layout,
-    layouts: input.layouts,
-    composeChildren: input.composeChildren,
-    htmlTemplate: input.htmlTemplate,
-    documentProps: {
-      metadata: input.metadata,
-      pageProps: input.pageProps,
-      ...input.documentProps ?? {}
+/**
+ * Applies optional component-root and document-root attribute stamping before HTML
+ * transformation runs on explicit renderer-owned paths.
+ */
+export function applyDocumentShellAttributeStamping(html, stamping, options) {
+    let nextHtml = html;
+    if (options.componentRootAttributes && Object.keys(options.componentRootAttributes).length > 0) {
+        nextHtml = stamping.applyAttributesToFirstBodyElement(nextHtml, options.componentRootAttributes);
+    }
+    if (options.documentAttributes && Object.keys(options.documentAttributes).length > 0) {
+        nextHtml = stamping.applyAttributesToHtmlElement(nextHtml, options.documentAttributes);
     }
-  });
-  const documentHtml = input.transformDocumentHtml ? input.transformDocumentHtml(composedDocumentHtml) : composedDocumentHtml;
-  return `${docType}${documentHtml}`;
+    return nextHtml;
 }
-async function finalizeDocumentShellHtml(htmlTransformer, options) {
-  const html = applyDocumentShellAttributeStamping(
-    options.html,
-    {
-      applyAttributesToFirstBodyElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToFirstBodyElement(nextHtml, attributes),
-      applyAttributesToHtmlElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToHtmlElement(nextHtml, attributes)
-    },
-    {
-      componentRootAttributes: options.componentRootAttributes,
-      documentAttributes: options.documentAttributes
+/**
+ * Builds the final serialized document HTML for one route page render.
+ */
+export async function renderPageDocumentShell(dependencies, input, docType) {
+    const { documentHtml: composedDocumentHtml } = await composeDocumentShell(dependencies, {
+        primaryComponent: input.page.component,
+        primaryProps: input.page.props,
+        layout: input.layout,
+        layouts: input.layouts,
+        composeChildren: input.composeChildren,
+        htmlTemplate: input.htmlTemplate,
+        documentProps: {
+            metadata: input.metadata,
+            pageProps: input.pageProps,
+            ...(input.documentProps ?? {}),
+        },
+    });
+    const documentHtml = input.transformDocumentHtml
+        ? input.transformDocumentHtml(composedDocumentHtml)
+        : composedDocumentHtml;
+    return `${docType}${documentHtml}`;
+}
+/**
+ * Finalizes already-resolved HTML for explicit renderer-owned paths.
+ *
+ * @remarks
+ * Callers append renderer bootstrap dependencies before invoking this helper.
+ * Stamps document/root attributes and runs HTML transformation after nested
+ * foreign-subtree resolution without routing back through shared route execution.
+ */
+export async function finalizeDocumentShellHtml(htmlTransformer, options) {
+    const html = applyDocumentShellAttributeStamping(options.html, {
+        applyAttributesToFirstBodyElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToFirstBodyElement(nextHtml, attributes),
+        applyAttributesToHtmlElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToHtmlElement(nextHtml, attributes),
+    }, {
+        componentRootAttributes: options.componentRootAttributes,
+        documentAttributes: options.documentAttributes,
+    });
+    const shouldTransform = options.transformHtml ?? !options.partial;
+    if (!shouldTransform) {
+        return html;
     }
-  );
-  const shouldTransform = options.transformHtml ?? !options.partial;
-  if (!shouldTransform) {
-    return html;
-  }
-  const transformedResponse = await htmlTransformer.transform(
-    new Response(html, {
-      headers: { "Content-Type": "text/html" }
-    }),
-    options.htmlContributions
-  );
-  return await transformedResponse.text();
+    const transformedResponse = await htmlTransformer.transform(new Response(html, {
+        headers: { 'Content-Type': 'text/html' },
+    }), options.htmlContributions);
+    return await transformedResponse.text();
 }
-export {
-  applyDocumentShellAttributeStamping,
-  composeDocumentShell,
-  composeSequentialLayoutChildren,
-  finalizeDocumentShellHtml,
-  renderPageDocumentShell
-};

package/src/route-renderer/orchestration/document-shell/layout-shell-props.service.js

@@ -1,31 +1,37 @@
-function resolveLayoutShellProps(context) {
-  return context.locals ? { locals: context.locals } : {};
+/**
+ * Resolves the default shell props passed to a layout tier during route render.
+ */
+export function resolveLayoutShellProps(context) {
+    return context.locals ? { locals: context.locals } : {};
 }
-function resolveLayoutEntryProps(entry, context) {
-  const shellProps = resolveLayoutShellProps(context);
-  if (!entry.props) {
-    return shellProps;
-  }
-  const layoutPropsContext = {
-    params: context.params,
-    query: context.query,
-    locals: context.locals
-  };
-  return {
-    ...shellProps,
-    ...entry.props(layoutPropsContext)
-  };
+/**
+ * Resolves props for one layout entry, merging shell props with an optional factory.
+ */
+export function resolveLayoutEntryProps(entry, context) {
+    const shellProps = resolveLayoutShellProps(context);
+    if (!entry.props) {
+        return shellProps;
+    }
+    const layoutPropsContext = {
+        params: context.params,
+        query: context.query,
+        locals: context.locals,
+    };
+    return {
+        ...shellProps,
+        ...entry.props(layoutPropsContext),
+    };
 }
-function resolvePageLayoutComponents(layouts) {
-  return layouts && layouts.length > 0 ? layouts : [];
+/**
+ * Reads the normalized layout stack from a page component config.
+ */
+export function resolvePageLayoutComponents(layouts) {
+    return layouts && layouts.length > 0 ? layouts : [];
 }
-function resolveInnermostPageLayout(layouts) {
-  const stack = resolvePageLayoutComponents(layouts);
-  return stack[stack.length - 1];
+/**
+ * Returns the innermost layout component from a normalized page layout stack.
+ */
+export function resolveInnermostPageLayout(layouts) {
+    const stack = resolvePageLayoutComponents(layouts);
+    return stack[stack.length - 1];
 }
-export {
-  resolveInnermostPageLayout,
-  resolveLayoutEntryProps,
-  resolveLayoutShellProps,
-  resolvePageLayoutComponents
-};