@c9up/aurora 0.1.3

package/src/render.ts

@@ -0,0 +1,378 @@
+/**
+ * Render a `TemplateResult` to the DOM and keep it reactive.
+ *
+ * `render(template, container)` clones the parsed `<template>`, walks to
+ * each slot, attaches the corresponding value (with `effect()` for any
+ * reactive expression), and appends the result to the container. The
+ * returned dispose function tears down every effect and removes the
+ * mounted nodes.
+ */
+
+import { readComponentLifecycle } from "./component.js";
+import { getTemplate } from "./html.js";
+import { effect, isSignal } from "./reactive.js";
+import {
+	type AttrSlot,
+	type BooleanAttrSlot,
+	type EffectCallback,
+	type EventSlot,
+	isTemplateResult,
+	type NodePath,
+	type PropSlot,
+	type Slot,
+	type TemplateResult,
+	type TextSlot,
+} from "./types.js";
+
+export type Disposer = () => void;
+
+/**
+ * Mount a TemplateResult into `container`. Returns a `Disposer` that
+ * stops every reactive effect and removes the mounted nodes. Calling it
+ * twice is a no-op.
+ */
+export function render(
+	result: TemplateResult,
+	container: Element | DocumentFragment,
+): Disposer {
+	const cleanups: Disposer[] = [];
+	const mountedNodes: ChildNode[] = [];
+	const mountHooks: Array<EffectCallback> = [];
+
+	const fragment = mount(result, cleanups, mountedNodes, mountHooks);
+	container.appendChild(fragment);
+
+	// `onMount` hooks fire after the fragment is live in the document so
+	// callbacks that measure / focus / observe see a real DOM. A returned
+	// cleanup function joins the unmount queue.
+	for (const hook of mountHooks) {
+		try {
+			const teardown = hook();
+			if (typeof teardown === "function") cleanups.push(teardown);
+		} catch {
+			/* swallow — one bad onMount should not block sibling components */
+		}
+	}
+
+	let disposed = false;
+	return () => {
+		if (disposed) return;
+		disposed = true;
+		for (const c of cleanups.splice(0)) c();
+		for (const node of mountedNodes) node.remove();
+	};
+}
+
+/**
+ * Pending multi-slot attribute group — collected during the per-slot
+ * pass so the renderer can wire a single effect per `(element, attr)`
+ * after every contributing value is known.
+ */
+interface MultiAttrGroup {
+	el: Element;
+	name: string;
+	staticParts: readonly string[];
+	/** Source-ordered values from each contributing slot. */
+	values: unknown[];
+}
+
+/**
+ * Build a fragment for a TemplateResult and register cleanups.
+ *
+ * @internal Exported so `hydrate.ts` can client-render a reactive
+ * nested-template subtree when the signal changes after hydration
+ * (the swap path — see `hydrateTextSlot`).
+ */
+export function mount(
+	result: TemplateResult,
+	cleanups: Disposer[],
+	mounted: ChildNode[],
+	mountHooks: Array<EffectCallback>,
+): DocumentFragment {
+	const tpl = getTemplate(result.strings);
+	const fragment = tpl.element.content.cloneNode(true) as DocumentFragment;
+
+	// Forward any component()-attached lifecycle from this result.
+	const lifecycle = readComponentLifecycle(result);
+	if (lifecycle) {
+		for (const hook of lifecycle.mountHooks) mountHooks.push(hook);
+		for (const c of lifecycle.cleanups) cleanups.push(c);
+	}
+
+	// Multi-slot attrs need every contributing value before we can join
+	// the final string. Collect them in a first pass, attach effects
+	// after.
+	const multiGroups = new Map<string, MultiAttrGroup>();
+
+	for (let i = 0; i < tpl.slots.length; i++) {
+		const slot = tpl.slots[i];
+		const node = resolvePath(fragment, slot.path);
+		if (slot.kind === "attr" && slot.staticParts !== undefined) {
+			collectMultiAttr(slot, node as Element, result.values[i], multiGroups);
+		} else {
+			applySlot(slot, node, result.values[i], cleanups, mounted, mountHooks);
+		}
+	}
+
+	for (const group of multiGroups.values()) {
+		applyMultiAttrGroup(group, cleanups);
+	}
+
+	for (const child of Array.from(fragment.childNodes)) {
+		mounted.push(child);
+	}
+	return fragment;
+}
+
+function resolvePath(root: ParentNode, path: NodePath): Node {
+	let node: Node = root;
+	for (const i of path) node = node.childNodes[i];
+	return node;
+}
+
+function applySlot(
+	slot: Slot,
+	node: Node,
+	value: unknown,
+	cleanups: Disposer[],
+	mounted: ChildNode[],
+	mountHooks: Array<EffectCallback>,
+): void {
+	switch (slot.kind) {
+		case "text":
+			applyTextSlot(
+				slot,
+				node as Comment,
+				value,
+				cleanups,
+				mounted,
+				mountHooks,
+			);
+			return;
+		case "attr":
+			applyAttrSlot(slot, node as Element, value, cleanups);
+			return;
+		case "boolean-attr":
+			applyBooleanAttrSlot(slot, node as Element, value, cleanups);
+			return;
+		case "prop":
+			applyPropSlot(slot, node as Element, value, cleanups);
+			return;
+		case "event":
+			applyEventSlot(slot, node as Element, value, cleanups);
+			return;
+	}
+}
+
+/**
+ * Text slot — replace the marker comment with whatever the value
+ * resolves to. The anchor comment stays in place; new content is
+ * inserted before it, and each re-render swaps out only the nodes it
+ * previously inserted.
+ */
+function applyTextSlot(
+	_slot: TextSlot,
+	anchor: Comment,
+	value: unknown,
+	cleanups: Disposer[],
+	mounted: ChildNode[],
+	mountHooks: Array<EffectCallback>,
+): void {
+	let currentNodes: ChildNode[] = [];
+	// Per-render disposers for whatever the slot currently shows. A
+	// reactive slot that swaps a nested TemplateResult for another must
+	// dispose the OLD subtree's effects + event listeners — otherwise
+	// they'd live in the shared `cleanups` array until the whole root
+	// disposes, leaking a stale subscription/listener on every branch
+	// change. We hand `localCleanups` (not `cleanups`) to the per-render
+	// mount and tear it down at the top of each `set()`.
+	let localCleanups: Disposer[] = [];
+
+	function disposeLocal(): void {
+		for (const d of localCleanups) d();
+		localCleanups = [];
+	}
+
+	function set(newValue: unknown): void {
+		disposeLocal();
+		for (const n of currentNodes) n.remove();
+		currentNodes = [];
+		const nodes = renderValueIntoNodes(
+			newValue,
+			localCleanups,
+			mounted,
+			mountHooks,
+		);
+		const parent = anchor.parentNode;
+		if (!parent) return;
+		for (const n of nodes) {
+			parent.insertBefore(n, anchor);
+			currentNodes.push(n);
+		}
+	}
+
+	if (isSignal(value) || typeof value === "function") {
+		const dispose = effect(() => {
+			set((value as () => unknown)());
+		});
+		// Root disposal tears down the slot's own effect AND whatever
+		// subtree is currently mounted.
+		cleanups.push(() => {
+			dispose();
+			disposeLocal();
+		});
+	} else {
+		set(value);
+		// Static value never re-runs, but its subtree (e.g. a one-shot
+		// nested template) still needs to be disposed with the root.
+		cleanups.push(disposeLocal);
+	}
+}
+
+function renderValueIntoNodes(
+	value: unknown,
+	cleanups: Disposer[],
+	mounted: ChildNode[],
+	mountHooks: Array<EffectCallback>,
+): ChildNode[] {
+	if (value === null || value === undefined || value === false) return [];
+	if (Array.isArray(value)) {
+		const out: ChildNode[] = [];
+		for (const item of value) {
+			out.push(...renderValueIntoNodes(item, cleanups, mounted, mountHooks));
+		}
+		return out;
+	}
+	if (isTemplateResult(value)) {
+		const frag = mount(value, cleanups, mounted, mountHooks);
+		return Array.from(frag.childNodes);
+	}
+	if (value instanceof Node) {
+		return [value as ChildNode];
+	}
+	return [document.createTextNode(String(value))];
+}
+
+function applyAttrSlot(
+	slot: AttrSlot,
+	el: Element,
+	value: unknown,
+	cleanups: Disposer[],
+): void {
+	function apply(v: unknown): void {
+		if (v === null || v === undefined || v === false) {
+			el.removeAttribute(slot.name);
+		} else if (v === true) {
+			el.setAttribute(slot.name, "");
+		} else {
+			el.setAttribute(slot.name, String(v));
+		}
+	}
+	if (isSignal(value) || typeof value === "function") {
+		const dispose = effect(() => apply((value as () => unknown)()));
+		cleanups.push(dispose);
+	} else {
+		apply(value);
+	}
+}
+
+function collectMultiAttr(
+	slot: AttrSlot,
+	el: Element,
+	value: unknown,
+	groups: Map<string, MultiAttrGroup>,
+): void {
+	if (!slot.staticParts) return;
+	const key = `${slot.name}::${(slot.path as readonly number[]).join(".")}`;
+	let group = groups.get(key);
+	if (!group) {
+		group = {
+			el,
+			name: slot.name,
+			staticParts: slot.staticParts,
+			values: [],
+		};
+		groups.set(key, group);
+	}
+	group.values.push(value);
+}
+
+function applyMultiAttrGroup(
+	group: MultiAttrGroup,
+	cleanups: Disposer[],
+): void {
+	function join(): string {
+		let out = group.staticParts[0] ?? "";
+		for (let i = 0; i < group.values.length; i++) {
+			const v = resolveReactive(group.values[i]);
+			out += v == null || v === false ? "" : String(v);
+			out += group.staticParts[i + 1] ?? "";
+		}
+		return out;
+	}
+
+	const hasReactive = group.values.some(
+		(v) => isSignal(v) || typeof v === "function",
+	);
+	if (hasReactive) {
+		const dispose = effect(() => {
+			group.el.setAttribute(group.name, join());
+		});
+		cleanups.push(dispose);
+	} else {
+		group.el.setAttribute(group.name, join());
+	}
+}
+
+function resolveReactive(value: unknown): unknown {
+	if (isSignal(value)) return value();
+	if (typeof value === "function") return (value as () => unknown)();
+	return value;
+}
+
+function applyBooleanAttrSlot(
+	slot: BooleanAttrSlot,
+	el: Element,
+	value: unknown,
+	cleanups: Disposer[],
+): void {
+	function apply(v: unknown): void {
+		if (v) el.setAttribute(slot.name, "");
+		else el.removeAttribute(slot.name);
+	}
+	if (isSignal(value) || typeof value === "function") {
+		const dispose = effect(() => apply((value as () => unknown)()));
+		cleanups.push(dispose);
+	} else {
+		apply(value);
+	}
+}
+
+function applyPropSlot(
+	slot: PropSlot,
+	el: Element,
+	value: unknown,
+	cleanups: Disposer[],
+): void {
+	function apply(v: unknown): void {
+		(el as unknown as Record<string, unknown>)[slot.name] = v;
+	}
+	if (isSignal(value) || typeof value === "function") {
+		const dispose = effect(() => apply((value as () => unknown)()));
+		cleanups.push(dispose);
+	} else {
+		apply(value);
+	}
+}
+
+function applyEventSlot(
+	slot: EventSlot,
+	el: Element,
+	value: unknown,
+	cleanups: Disposer[],
+): void {
+	if (typeof value !== "function") return;
+	const handler = value as EventListener;
+	el.addEventListener(slot.event, handler);
+	cleanups.push(() => el.removeEventListener(slot.event, handler));
+}

package/src/route.ts

@@ -0,0 +1,96 @@
+/**
+ * `auroraRoute` — Ream route handler that SSR-renders an aurora
+ * component and ships the markup plus the bytes needed for client-side
+ * hydration.
+ *
+ * Usage:
+ *
+ *   import { auroraRoute } from '@c9up/aurora/provider'
+ *   router.get('/dashboard', auroraRoute({
+ *     entry: '/app/pages/dashboard.client.js',
+ *     render: () => Dashboard({ user: ... })
+ *   }))
+ *
+ * The handler:
+ *   1. invokes `render()` and stringifies the result via @c9up/aurora's SSR
+ *   2. wraps the markup in the page shell from `shell` (default: a minimal
+ *      <!doctype html> document)
+ *   3. embeds a `<script type="module">` that imports the user-supplied
+ *      `entry` module — the client bundle is expected to call
+ *      `hydrate(document.getElementById('aurora-root'), factory)` itself.
+ */
+
+import { renderToString } from "./ssr.js";
+import type { TemplateResult } from "./types.js";
+
+/**
+ * Structural slice of Ream's HttpContext — the response surface we need.
+ * Declaring it locally keeps aurora's bundle free of a `@c9up/ream`
+ * import; any framework whose context exposes `response.header()` and
+ * `response.send()` satisfies this contract via structural subtyping.
+ */
+export interface AuroraResponse {
+	status(code: number): AuroraResponse;
+	header(name: string, value: string): AuroraResponse;
+	send(data: string): void;
+}
+export interface AuroraHttpContext {
+	request: unknown;
+	response: AuroraResponse;
+}
+
+/** Configuration for a single auroraRoute call. */
+export interface AuroraRouteConfig {
+	/**
+	 * SSR factory. Called once per request. Returning a TemplateResult is
+	 * the common case; returning a Promise<TemplateResult> works too
+	 * (data-loading components).
+	 */
+	render: (ctx: AuroraHttpContext) => TemplateResult | Promise<TemplateResult>;
+	/**
+	 * Path to the ES module the browser should import to hydrate. The
+	 * value is inlined into a `<script type="module" src="...">` tag —
+	 * make sure the route exists on the Ream router (typically served
+	 * statically). Defaults to `/aurora-client.js`.
+	 */
+	entry?: string;
+	/**
+	 * Page shell. Defaults to a minimal HTML5 doctype with a `<div
+	 * id="aurora-root">` that wraps the SSR markup. Apps swap in their
+	 * own to control `<head>` (title, meta, fonts, css).
+	 */
+	shell?: (body: string, entry: string) => string;
+}
+
+const DEFAULT_SHELL = (body: string, entry: string): string =>
+	`<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<title>Aurora</title>
+</head>
+<body>
+<div id="aurora-root">${body}</div>
+<script type="module" src="${entry}"></script>
+</body>
+</html>`;
+
+/**
+ * Build a Ream-compatible route handler that SSR-renders the given
+ * factory and serves the full HTML document.
+ */
+export function auroraRoute(
+	config: AuroraRouteConfig,
+): (ctx: AuroraHttpContext) => Promise<void> {
+	const entry = config.entry ?? "/aurora-client.js";
+	const shell = config.shell ?? DEFAULT_SHELL;
+
+	return async (ctx) => {
+		const tree = await config.render(ctx);
+		const body = renderToString(tree);
+		const html = shell(body, entry);
+		ctx.response.header("content-type", "text/html; charset=utf-8");
+		ctx.response.send(html);
+	};
+}

package/src/server/renderPage.ts

@@ -0,0 +1,135 @@
+/**
+ * `renderPage` — server-side helper that turns a page name + props into
+ * a full HTML document, ready to ship from a route handler.
+ *
+ * The output carries everything the browser needs to hydrate against
+ * the SSR markup with zero app-side scripting:
+ *
+ *   <head>
+ *     ...
+ *     <script type="importmap">
+ *       { "imports": { "@c9up/aurora": "/_assets/aurora/index.js" } }
+ *     </script>
+ *   </head>
+ *   <body>
+ *     <div id="aurora-root">…SSR markup…</div>
+ *     <script id="aurora-page-data" type="application/json">{…}</script>
+ *     <script type="module">
+ *       import { hydrate } from '@c9up/aurora'
+ *       import Page from '/_assets/pages/ProjectPage.js'
+ *       const data = JSON.parse(document.getElementById('aurora-page-data').textContent)
+ *       hydrate(document.getElementById('aurora-root'), () => Page(data.props))
+ *     </script>
+ *   </body>
+ */
+
+import type { Pages } from "../Pages.js";
+import { renderToString } from "../ssr.js";
+
+/**
+ * Structural slice of the host framework's response. Same shape
+ * `auroraRoute()` uses — keeps aurora free of a `@c9up/ream` import.
+ */
+export interface RenderResponse {
+	status(code: number): RenderResponse;
+	header(name: string, value: string): RenderResponse;
+	send(body: string): void;
+}
+export interface RenderHttpContext {
+	request: unknown;
+	response: RenderResponse;
+}
+
+export interface RenderPageOptions {
+	/**
+	 * Importmap entries injected into `<head>`. Defaults to mapping
+	 * `@c9up/aurora` to `/_assets/aurora/index.js`. Override to point
+	 * at a different mount or to add app-side aliases.
+	 */
+	importmap?: Record<string, string>;
+	/**
+	 * Extra markup spliced into `<head>` after the importmap. Use to
+	 * inject `<title>`, meta tags, stylesheets.
+	 */
+	headExtra?: string;
+	/**
+	 * Outer language tag on the `<html>` element. Defaults to `en`.
+	 */
+	lang?: string;
+	/**
+	 * Mount root id for the SSR + hydrated tree. Defaults to
+	 * `aurora-root`. Matches the id the client-side hydrate script
+	 * targets.
+	 */
+	rootId?: string;
+}
+
+export async function renderPage<P>(
+	ctx: RenderHttpContext,
+	pages: Pages,
+	name: string,
+	props: P,
+	options: RenderPageOptions = {},
+): Promise<void> {
+	const factory = await pages.resolve(name);
+	// The factory must be invoked the SAME way client-side for hydrate
+	// to find matching slots — `Page(props)` is the contract.
+	const tree = await factory(props as never);
+	const body = renderToString(tree);
+
+	const importmap = {
+		"@c9up/aurora": "/_assets/aurora/index.js",
+		...options.importmap,
+	};
+	const rootId = options.rootId ?? "aurora-root";
+	const lang = options.lang ?? "en";
+	const pageUrl = pages.urlFor(name);
+
+	const doc = `<!doctype html>
+<html lang="${escapeAttr(lang)}">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<script type="importmap">${JSON.stringify({ imports: importmap })}</script>
+${options.headExtra ?? ""}
+</head>
+<body>
+<div id="${escapeAttr(rootId)}">${body}</div>
+<script id="aurora-page-data" type="application/json">${escapeJsonForScript({
+		name,
+		props,
+		url: pageUrl,
+		rootId,
+	})}</script>
+<script type="module">
+import { hydrate } from '@c9up/aurora'
+import Page from ${JSON.stringify(pageUrl)}
+const data = JSON.parse(document.getElementById('aurora-page-data').textContent)
+hydrate(document.getElementById(data.rootId), () => Page(data.props))
+</script>
+</body>
+</html>`;
+
+	ctx.response.header("content-type", "text/html; charset=utf-8");
+	ctx.response.send(doc);
+}
+
+function escapeAttr(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/</g, "&lt;");
+}
+
+/**
+ * Escape a JSON payload for safe embedding inside a `<script>` block.
+ * The HTML parser closes the script on `</script>` regardless of JSON
+ * quoting, so we slash-escape the `/`. We also escape `<!--` and `-->`
+ * to dodge HTML-comment interpretation inside the script body.
+ */
+function escapeJsonForScript(value: unknown): string {
+	return JSON.stringify(value)
+		.replace(/<\/(script)/gi, "<\\/$1")
+		.replace(/<!--/g, "<\\!--")
+		.replace(/-->/g, "--\\>");
+}