@ecopages/core 0.2.0-alpha.37 → 0.2.0-alpha.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-alpha.37",
+  "version": "0.2.0-alpha.38",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.37",
+    "@ecopages/file-system": "0.2.0-alpha.38",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@worker-tools/html-rewriter": "0.1.0-pre.19",

package/src/eco/eco.browser.js

@@ -10,6 +10,10 @@ function createComponentFactory(options) {
 function component(options) {
   return createComponentFactory(options);
 }
+function embed(component2, props, children) {
+  const nextProps = children === void 0 ? props : { ...props, children };
+  return component2(nextProps);
+}
 function html(options) {
   return createComponentFactory(options);
 }
@@ -71,6 +75,7 @@ function staticProps(fn) {
 }
 const eco = {
   component,
+  embed,
   html,
   layout,
   page,

package/src/eco/eco.js

@@ -46,6 +46,26 @@ function createComponentFactory(options) {
 function component(options) {
   return createComponentFactory(options);
 }
+function isMissingForeignChildInterceptionError(error) {
+  return error instanceof Error && error.message.startsWith("[ecopages] Missing foreign-child interception from ");
+}
+function embed(component2, props, children) {
+  const activeRenderContext = getComponentRenderContext();
+  const ecoComponent = component2;
+  const targetIntegration = ecoComponent.config?.integration ?? ecoComponent.config?.__eco?.integration;
+  const componentFile = ecoComponent.config?.__eco?.file ?? "unknown component";
+  const nextProps = children === void 0 ? props : { ...props, children };
+  try {
+    return component2(nextProps);
+  } catch (error) {
+    if (!isMissingForeignChildInterceptionError(error)) {
+      throw error;
+    }
+    throw new Error(
+      `[ecopages] eco.embed() could not hand off the Foreign Child from ${activeRenderContext?.currentIntegration ?? "unknown integration"} to ${targetIntegration ?? "unknown integration"} for ${componentFile}. The active Integration renderer exposed a foreign-child runtime, but it did not intercept this cross-integration render. Ensure mixed-integration Page, Layout, Html, or Component renders install foreign-child handoff before calling eco.embed().`
+    );
+  }
+}
 function html(options) {
   return createComponentFactory(options);
 }
@@ -86,6 +106,7 @@ function staticProps(fn) {
 }
 const eco = {
   component,
+  embed,
   html,
   layout,
   page,

package/src/eco/eco.types.d.ts

@@ -4,6 +4,51 @@
  */
 import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayoutComponent, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
 import type { CacheStrategy } from '../services/cache/cache.types.js';
+/**
+ * Extracts the props type from one eco component.
+ */
+export type PropsOf<TComponent extends EcoComponent> = TComponent extends EcoComponent<infer P, any> ? P : never;
+/**
+ * Extracts the render result type from one eco component.
+ */
+export type ResultOf<TComponent extends EcoComponent> = TComponent extends EcoComponent<any, infer R> ? R : never;
+/**
+ * Narrows an eco component to its callable function signature.
+ *
+ * This is useful for helper modules such as `EcoEmbed` that invoke a component
+ * directly and need to exclude the non-callable metadata shape from the public
+ * type surface.
+ */
+export type CallableComponentOf<TComponent extends EcoComponent> = Extract<TComponent, (props: any, ...args: any[]) => any>;
+/**
+ * Extracts the declared `children` type from one eco component when present.
+ */
+export type ChildrenOf<TComponent extends EcoComponent> = PropsOf<TComponent> extends {
+    children?: infer T;
+} ? T : PropsOf<TComponent> extends {
+    children: infer T;
+} ? T : never;
+/**
+ * Extracts the props accepted by `eco.embed()` before optional `children`
+ * injection.
+ *
+ * When the target component already declares `children`, callers pass the rest
+ * of the props bag here and provide `children` as the third `eco.embed()`
+ * argument or the `EcoEmbed` wrapper children slot.
+ */
+export type EmbedPropsOf<TComponent extends EcoComponent> = 'children' extends keyof PropsOf<TComponent> ? Omit<PropsOf<TComponent>, 'children'> : PropsOf<TComponent>;
+/**
+ * Props accepted by integration-owned `EcoEmbed` adapters.
+ *
+ * The `component` field is narrowed to the callable portion of the target eco
+ * component so JSX wrappers can invoke `eco.embed()` without repeating local
+ * callable-component extraction logic.
+ */
+export type EcoEmbedProps<TComponent extends EcoComponent> = {
+    component: CallableComponentOf<TComponent>;
+    props: EmbedPropsOf<TComponent>;
+    children?: unknown;
+};
 type WithRequiredLocals<K extends keyof RequestLocals> = Omit<RequestLocals, K> & {
     [P in K]-?: Exclude<RequestLocals[P], null | undefined>;
 };
@@ -139,6 +184,16 @@ export interface Eco {
      * @template E - Element/return type (EcoPagesElement for Kita, ReactNode for React)
      */
     component: <P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>) => EcoComponent<P, E>;
+    /**
+     * Render a component explicitly, with an optional `children` argument.
+     *
+     * This is useful when authoring crosses integration boundaries and inline JSX
+     * would otherwise force one file to model multiple JSX namespaces.
+     */
+    embed: {
+        <TComponent extends EcoComponent>(component: CallableComponentOf<TComponent>, props: PropsOf<TComponent>): ResultOf<TComponent>;
+        <TComponent extends EcoComponent>(component: CallableComponentOf<TComponent>, props: EmbedPropsOf<TComponent>, children: ChildrenOf<TComponent> | unknown): ResultOf<TComponent>;
+    };
     /**
      * Create a document shell component for the HTML wrapper.
      */