@ilha/astro 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# `@ilha/astro`
+
+An [Astro](https://astro.build) integration that renders and hydrates [Ilha](https://github.com/ilhajs/ilha) islands as Astro components.
+
+---
+
+## Installation
+
+```bash
+bun add @ilha/astro
+```
+
+---
+
+## Usage
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import ilha from "@ilha/astro";
+
+export default defineConfig({
+  integrations: [ilha()],
+});
+```
+
+Then use any Ilha island as an Astro component, with a [client directive](https://docs.astro.build/en/reference/directives-reference/#client-directives) to control hydration:
+
+```astro
+---
+import { Counter } from "../islands/counter";
+---
+
+<Counter client:load start={10} />
+```
+
+## How it works
+
+- **Server-side:** the component is rendered with [`.hydratable()`](https://github.com/ilhajs/ilha), which wraps the island's SSR output in a `[data-ilha]` element carrying serialized props and a state snapshot.
+- **Client-side:** on hydration, the renderer finds that `[data-ilha]` element inside Astro's island wrapper and calls the island's own `.mount()` — no re-render, no flicker, `.onMount()` is skipped since the snapshot already matches the DOM.
+
+Because hydration is driven entirely by Ilha's own `data-ilha-*` attributes, every [Astro client directive](https://docs.astro.build/en/reference/directives-reference/#client-directives) (`client:load`, `client:idle`, `client:visible`, `client:media`, `client:only`) works as expected.
+
+## Notes
+
+- Ilha islands don't support Astro's `<slot />` / children forwarding — render everything through the island's own `.render()` function and props.
+- `client:only` skips SSR entirely and mounts fresh in the browser, matching Astro's usual behavior for other framework renderers.

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: (element: HTMLElement) => (Component: unknown, props: Record<string, unknown>, slotted: Record<string, string>, _metadata: Record<string, string>) => Promise<void>;
+export default _default;

package/dist/client.js

@@ -0,0 +1,30 @@
+//#region src/client.ts
+function isMountable(Component) {
+	return !!Component && typeof Component.mount === "function";
+}
+var client_default = (element) => async (Component, props, slotted, _metadata) => {
+	if (!element.hasAttribute("ssr")) {
+		if (isMountable(Component)) {
+			const unmount = Component.mount(element, props);
+			element.addEventListener("astro:unmount", () => unmount(), { once: true });
+		}
+		return;
+	}
+	if (isMountable(Component)) {
+		const host = element.querySelector("[data-ilha]") ?? element;
+		const unmount = Component.mount(host);
+		element.addEventListener("astro:unmount", () => unmount(), { once: true });
+		return;
+	}
+	if (typeof Component !== "function") return;
+	const merged = { ...props };
+	for (const [name, value] of Object.entries(slotted ?? {})) merged[name === "default" ? "children" : name] = value;
+	try {
+		Component(merged);
+	} catch {
+		throw new Error(`[@ilha/astro] Failed to bind client component — expected a function that can re-run against SSR markup.`);
+	}
+};
+
+//#endregion
+export { client_default as default };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { AstroIntegration, AstroRenderer } from "astro";
+export declare function getRenderer(): AstroRenderer;
+export default function ilhaIntegration(): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,19 @@
+//#region src/index.ts
+function getRenderer() {
+	return {
+		name: "@ilha/astro",
+		clientEntrypoint: "@ilha/astro/client.js",
+		serverEntrypoint: "@ilha/astro/server.js"
+	};
+}
+function ilhaIntegration() {
+	return {
+		name: "@ilha/astro",
+		hooks: { "astro:config:setup": ({ addRenderer }) => {
+			addRenderer(getRenderer());
+		} }
+	};
+}
+
+//#endregion
+export { ilhaIntegration as default, getRenderer };

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import type { NamedSSRLoadedRendererValue } from "astro";
+declare const renderer: NamedSSRLoadedRendererValue;
+export default renderer;

package/dist/server.js

@@ -0,0 +1,69 @@
+//#region src/server.ts
+const ISLAND = Symbol.for("ilha.island");
+const RAW = Symbol.for("ilha.raw");
+function isIsland(Component) {
+	return typeof Component === "function" && ISLAND in Component;
+}
+function isRawHtml(value) {
+	return !!(value && typeof value === "object" && RAW in value);
+}
+function toRawHtml(value) {
+	return {
+		[RAW]: true,
+		value: String(value)
+	};
+}
+function isAstroRenderable(value) {
+	return !!value && typeof value === "object" && !isRawHtml(value) && typeof value.render === "function";
+}
+async function resolveAstroRenderable(value) {
+	let out = "";
+	await value.render({ write(chunk) {
+		if (chunk != null) out += String(chunk);
+	} });
+	return out;
+}
+async function resolvePropValue(value) {
+	if (isAstroRenderable(value)) return toRawHtml(await resolveAstroRenderable(value));
+	if (Array.isArray(value)) return Promise.all(value.map(resolvePropValue));
+	return value;
+}
+async function resolveProps(props) {
+	const resolved = {};
+	for (const [key, value] of Object.entries(props)) resolved[key] = await resolvePropValue(value);
+	return resolved;
+}
+async function renderPlainComponent(Component, props, slots) {
+	const merged = await resolveProps(props);
+	for (const [name, value] of Object.entries(slots)) merged[name === "default" ? "children" : name] = toRawHtml(value);
+	const result = Component(merged);
+	if (typeof result === "string") return result;
+	if (isRawHtml(result)) return result.value;
+}
+async function check(Component, props, slots) {
+	if (isIsland(Component)) return true;
+	if (typeof Component !== "function") return false;
+	try {
+		return await renderPlainComponent(Component, props, slots) !== void 0;
+	} catch {
+		return false;
+	}
+}
+async function renderToStaticMarkup(Component, props, slots, metadata) {
+	if (isIsland(Component)) return { html: await Component.hydratable(await resolveProps(props), {
+		name: metadata?.displayName ?? "IlhaIsland",
+		snapshot: true,
+		skipOnMount: true
+	}) };
+	const html = await renderPlainComponent(Component, props, slots);
+	if (html === void 0) throw new Error(`[@ilha/astro] Unable to render "${metadata?.displayName ?? "component"}" — expected an ilha island or a function returning ilha RawHtml/string.`);
+	return { html };
+}
+const renderer = {
+	name: "@ilha/astro",
+	check,
+	renderToStaticMarkup
+};
+
+//#endregion
+export { renderer as default };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ilha/astro",
+  "version": "0.1.0",
+  "description": "Astro integration for Ilha islands",
+  "keywords": [
+    "astro-component",
+    "astro-integration",
+    "frontend",
+    "ilha",
+    "island-architecture",
+    "islands",
+    "ssr",
+    "withastro"
+  ],
+  "homepage": "https://github.com/ilhajs/ilha/tree/main/packages/astro#readme",
+  "bugs": {
+    "url": "https://github.com/ilhajs/ilha/issues"
+  },
+  "license": "MIT",
+  "author": "Ryuz <ryuzer@proton.me>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ilhajs/ilha.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client.js": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./server.js": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown && tsc -p tsconfig.build.json",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "astro": "^7.1.3",
+    "ilha": "^0.9.5"
+  },
+  "peerDependencies": {
+    "astro": "^7.0.0",
+    "ilha": ">=0.9.5"
+  }
+}