@ecopages/kitajs 0.2.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `@ecopages/kitajs` are documented here.
+
+> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
+
+## [UNRELEASED] — TBD
+
+### Features
+
+- Aligned KitaJS renderer with full orchestration mode — removed legacy rendering path (`fc07bdb0`).
+
+### Refactoring
+
+- **Type safety improvements** — Enhanced type safety for component signatures; test component creation helpers are now more accurately typed (`574657eb`).
+- Ambient module declarations cleaned up (`5f46ecc5`).
+- Updated test suite for esbuild adapter and Node.js runtime compatibility (`31a44458`).
+
+### Tests
+
+- Updated integration tests to align with the new orchestration model.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Andrea Zanenghi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# Ecopages KitaJs Integration Plugin
+
+The `@ecopages/kitajs` package provides seamless integration with [Kita](https://kitajs.org/html/), enabling effortless rendering of JSX templates. This integration represents a minimalistic layer within the broader Ecopages integration plugin system, designed to enhance the platform's flexibility and ease of use.
+
+## Install
+
+```bash
+bunx jsr add @ecopages/kitajs
+```
+
+## Usage
+
+Incorporating this integration into your project is straightforward. Simply import and include the `kitajsPlugin` in your Ecopages configuration as shown below:
+
+```ts
+import { ConfigBuilder } from '@ecopages/core';
+import { kitajsPlugin } from '@ecopages/kitajs';
+
+const config = await new ConfigBuilder()
+	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
+	.setIntegrations([kitajsPlugin()])
+	.build();
+
+export default config;
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@ecopages/kitajs",
+  "version": "0.2.0-alpha.1",
+  "description": "Kitajs plugin for Ecopages",
+  "keywords": [
+    "ecopages",
+    "kitajs",
+    "plugin"
+  ],
+  "license": "MIT",
+  "main": "./src/kitajs.plugin.js",
+  "types": "./src/kitajs.plugin.d.ts",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ecopages/ecopages.git",
+    "directory": "packages/integrations/kitajs"
+  },
+  "peerDependencies": {
+    "@ecopages/core": "0.2.0-alpha.1",
+    "@kitajs/html": "^4.1.0",
+    "@kitajs/ts-html-plugin": "^4.0.1"
+  }
+}

package/src/kitajs-renderer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * This module contains the Kita.js renderer
+ * @module
+ */
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
+/**
+ * A renderer for the Kita.js integration.
+ * It renders a page using the HtmlTemplate and Page components.
+ */
+export declare class KitaRenderer extends IntegrationRenderer<EcoPagesElement> {
+    name: string;
+    /**
+     * Renders a Kita component boundary for component-level orchestration.
+     *
+     * Includes component-scoped dependency assets when declared.
+     */
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
+    renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
+}

package/src/kitajs-renderer.js

@@ -0,0 +1,85 @@
+import { IntegrationRenderer } from "@ecopages/core/route-renderer/integration-renderer";
+import { PLUGIN_NAME } from "./kitajs.plugin.js";
+class KitaRenderer extends IntegrationRenderer {
+  name = PLUGIN_NAME;
+  /**
+   * Renders a Kita component boundary for component-level orchestration.
+   *
+   * Includes component-scoped dependency assets when declared.
+   */
+  async renderComponent(input) {
+    const component = input.component;
+    const props = input.children === void 0 ? input.props : { ...input.props, children: input.children };
+    const content = await component(props);
+    const html = String(content);
+    const hasDependencies = Boolean(input.component.config?.dependencies);
+    const canResolveAssets = typeof this.assetProcessingService?.processDependencies === "function";
+    const assets = hasDependencies && canResolveAssets ? await this.processComponentDependencies([input.component]) : void 0;
+    return {
+      html,
+      canAttachAttributes: true,
+      rootTag: this.getRootTagName(html),
+      integrationName: this.name,
+      assets
+    };
+  }
+  async render({
+    params,
+    query,
+    props,
+    locals,
+    pageLocals,
+    metadata,
+    Page,
+    Layout,
+    HtmlTemplate
+  }) {
+    try {
+      const pageContent = await Page({ params, query, ...props, locals: pageLocals });
+      const children = Layout && typeof Layout === "function" ? await Layout({ children: pageContent, locals }) : pageContent;
+      const body = await HtmlTemplate({
+        metadata,
+        pageProps: props ?? {},
+        children
+      });
+      return this.DOC_TYPE + body;
+    } catch (error) {
+      throw this.createRenderError("Error rendering page", error);
+    }
+  }
+  async renderToResponse(view, props, ctx) {
+    try {
+      const Layout = view.config?.layout;
+      const viewFn = view;
+      const pageContent = await viewFn(props);
+      if (ctx.partial) {
+        return this.createHtmlResponse(pageContent, ctx);
+      }
+      const children = Layout ? await Layout({ children: pageContent }) : pageContent;
+      const HtmlTemplate = await this.getHtmlTemplate();
+      const metadata = view.metadata ? await view.metadata({
+        params: {},
+        query: {},
+        props,
+        appConfig: this.appConfig
+      }) : this.appConfig.defaultMetadata;
+      await this.prepareViewDependencies(view, Layout);
+      const html = this.DOC_TYPE + await HtmlTemplate({
+        metadata,
+        pageProps: props,
+        children: children ?? ""
+      });
+      const transformedResponse = await this.htmlTransformer.transform(
+        new Response(html, {
+          headers: { "Content-Type": "text/html" }
+        })
+      );
+      return this.createHtmlResponse(transformedResponse.body ?? "", ctx);
+    } catch (error) {
+      throw this.createRenderError("Error rendering view", error);
+    }
+  }
+}
+export {
+  KitaRenderer
+};

package/src/kitajs-renderer.ts

@@ -0,0 +1,130 @@
+/**
+ * This module contains the Kita.js renderer
+ * @module
+ */
+
+import type {
+	ComponentRenderInput,
+	ComponentRenderResult,
+	EcoComponent,
+	EcoPagesElement,
+	IntegrationRendererRenderOptions,
+	RouteRendererBody,
+} from '@ecopages/core';
+import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
+import { PLUGIN_NAME } from './kitajs.plugin.ts';
+
+/** Narrows an EcoComponent to its KitaJS callable signature. */
+type KitaViewFn<P> = (props: P) => Promise<EcoPagesElement> | EcoPagesElement;
+
+/** KitaJS layout function signature. */
+type KitaLayoutFn = (props: { children: EcoPagesElement } & Record<string, unknown>) => Promise<EcoPagesElement>;
+
+/**
+ * A renderer for the Kita.js integration.
+ * It renders a page using the HtmlTemplate and Page components.
+ */
+export class KitaRenderer extends IntegrationRenderer<EcoPagesElement> {
+	name = PLUGIN_NAME;
+
+	/**
+	 * Renders a Kita component boundary for component-level orchestration.
+	 *
+	 * Includes component-scoped dependency assets when declared.
+	 */
+	override async renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult> {
+		const component = input.component as KitaViewFn<Record<string, unknown>>;
+		const props = input.children === undefined ? input.props : { ...input.props, children: input.children };
+		const content = await component(props);
+		const html = String(content);
+		const hasDependencies = Boolean(input.component.config?.dependencies);
+		const canResolveAssets = typeof this.assetProcessingService?.processDependencies === 'function';
+		const assets =
+			hasDependencies && canResolveAssets
+				? await this.processComponentDependencies([input.component])
+				: undefined;
+
+		return {
+			html,
+			canAttachAttributes: true,
+			rootTag: this.getRootTagName(html),
+			integrationName: this.name,
+			assets,
+		};
+	}
+
+	async render({
+		params,
+		query,
+		props,
+		locals,
+		pageLocals,
+		metadata,
+		Page,
+		Layout,
+		HtmlTemplate,
+	}: IntegrationRendererRenderOptions): Promise<RouteRendererBody> {
+		try {
+			const pageContent = await Page({ params, query, ...props, locals: pageLocals });
+			const children =
+				Layout && typeof Layout === 'function' ? await Layout({ children: pageContent, locals }) : pageContent;
+			const body = await HtmlTemplate({
+				metadata,
+				pageProps: props ?? {},
+				children,
+			});
+
+			return this.DOC_TYPE + body;
+		} catch (error) {
+			throw this.createRenderError('Error rendering page', error);
+		}
+	}
+
+	async renderToResponse<P = Record<string, unknown>>(
+		view: EcoComponent<P>,
+		props: P,
+		ctx: RenderToResponseContext,
+	): Promise<Response> {
+		try {
+			const Layout = view.config?.layout as KitaLayoutFn | undefined;
+
+			const viewFn = view as KitaViewFn<P>;
+			const pageContent = await viewFn(props);
+
+			if (ctx.partial) {
+				return this.createHtmlResponse(pageContent, ctx);
+			}
+
+			const children = Layout ? await Layout({ children: pageContent }) : pageContent;
+
+			const HtmlTemplate = await this.getHtmlTemplate();
+			const metadata = view.metadata
+				? await view.metadata({
+						params: {},
+						query: {},
+						props: props as Record<string, unknown>,
+						appConfig: this.appConfig,
+					})
+				: this.appConfig.defaultMetadata;
+			await this.prepareViewDependencies(view, Layout as EcoComponent | undefined);
+
+			const html =
+				this.DOC_TYPE +
+				(await HtmlTemplate({
+					metadata,
+					pageProps: props as Record<string, unknown>,
+					children: children ?? '',
+				}));
+
+			const transformedResponse = await this.htmlTransformer.transform(
+				new Response(html, {
+					headers: { 'Content-Type': 'text/html' },
+				}),
+			);
+
+			return this.createHtmlResponse(transformedResponse.body ?? '', ctx);
+		} catch (error) {
+			throw this.createRenderError('Error rendering view', error);
+		}
+	}
+}

package/src/kitajs.plugin.d.ts

@@ -0,0 +1,20 @@
+import { IntegrationPlugin, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
+import { KitaRenderer } from './kitajs-renderer.js';
+/**
+ * The name of the Kita.js plugin
+ */
+export declare const PLUGIN_NAME = "kitajs";
+/**
+ * The Kita.js plugin class
+ * This plugin provides support for Kita.js components in Ecopages
+ */
+export declare class KitaHtmlPlugin extends IntegrationPlugin {
+    renderer: typeof KitaRenderer;
+    constructor(options?: Omit<IntegrationPluginConfig, 'name'>);
+}
+/**
+ * Factory function to create a Kita.js plugin instance.
+ * @param options Configuration options for the Kita.js plugin
+ * @returns A new KitaHtmlPlugin instance
+ */
+export declare function kitajsPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): KitaHtmlPlugin;

package/src/kitajs.plugin.js

@@ -0,0 +1,21 @@
+import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
+import { KitaRenderer } from "./kitajs-renderer.js";
+const PLUGIN_NAME = "kitajs";
+class KitaHtmlPlugin extends IntegrationPlugin {
+  renderer = KitaRenderer;
+  constructor(options) {
+    super({
+      name: PLUGIN_NAME,
+      extensions: [".kita.tsx"],
+      ...options
+    });
+  }
+}
+function kitajsPlugin(options) {
+  return new KitaHtmlPlugin(options);
+}
+export {
+  KitaHtmlPlugin,
+  PLUGIN_NAME,
+  kitajsPlugin
+};

package/src/kitajs.plugin.ts

@@ -0,0 +1,32 @@
+import { IntegrationPlugin, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
+import { KitaRenderer } from './kitajs-renderer.ts';
+
+/**
+ * The name of the Kita.js plugin
+ */
+export const PLUGIN_NAME = 'kitajs';
+
+/**
+ * The Kita.js plugin class
+ * This plugin provides support for Kita.js components in Ecopages
+ */
+export class KitaHtmlPlugin extends IntegrationPlugin {
+	renderer = KitaRenderer;
+
+	constructor(options?: Omit<IntegrationPluginConfig, 'name'>) {
+		super({
+			name: PLUGIN_NAME,
+			extensions: ['.kita.tsx'],
+			...options,
+		});
+	}
+}
+
+/**
+ * Factory function to create a Kita.js plugin instance.
+ * @param options Configuration options for the Kita.js plugin
+ * @returns A new KitaHtmlPlugin instance
+ */
+export function kitajsPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): KitaHtmlPlugin {
+	return new KitaHtmlPlugin(options);
+}