@intent-framework/dom 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahyar
+
+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/dist/dom-router.d.ts

@@ -0,0 +1,19 @@
+import type { ScreenDefinition, DefaultScreenServices } from "@intent-framework/core";
+import type { Router, RoutePathArgs } from "@intent-framework/router";
+export type RouterDomHandle<Routes extends Record<string, {
+    path: string;
+}>> = {
+    navigate<Name extends Extract<keyof Routes, string>>(name: Name, ...args: RoutePathArgs<Routes[Name]["path"]>): void;
+    renderPath(pathname: string): void;
+    dispose(): void;
+};
+export type RenderRouterOptions<TServices extends object = DefaultScreenServices> = {
+    target: HTMLElement;
+    window?: Window;
+    notFound?: ScreenDefinition<TServices> | ((pathname: string) => ScreenDefinition<TServices>);
+    services?: Omit<TServices, "navigate" | "route">;
+    showScreenName?: boolean;
+};
+export declare function renderRouter<Routes extends Record<string, {
+    path: string;
+}>, TServices extends object = DefaultScreenServices>(router: Router<Routes, TServices>, options: RenderRouterOptions<TServices>): RouterDomHandle<Routes>;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { ScreenDefinition, DefaultScreenServices } from "@intent-framework/core";
+export type DomRendererOptions<TServices extends object = DefaultScreenServices> = {
+    target: HTMLElement;
+    services?: TServices;
+    showScreenName?: boolean;
+};
+export { renderRouter } from "./dom-router.js";
+export type { RouterDomHandle, RenderRouterOptions } from "./dom-router.js";
+export declare function renderDom<TServices extends object = DefaultScreenServices>(screenDef: ScreenDefinition<TServices>, options: DomRendererOptions<TServices>): () => void;

package/dist/index.js

@@ -0,0 +1,266 @@
+import { createScreenRuntime } from "@intent-framework/core";
+
+//#region src/dom-router.ts
+function renderRouter(router, options) {
+	const { showScreenName } = options;
+	const win = options.window ?? window;
+	let currentCleanup;
+	const navigate = (name, ...args) => {
+		const routerPath = router.path;
+		const path = routerPath(name, args[0]);
+		win.history.pushState(null, "", path);
+		renderPath(path);
+	};
+	function renderPath(pathname) {
+		currentCleanup?.();
+		currentCleanup = void 0;
+		options.target.innerHTML = "";
+		const match = router.match(pathname);
+		const route = match.found ? {
+			name: match.name,
+			path: match.path,
+			params: match.params
+		} : void 0;
+		const mergedServices = {
+			...options.services,
+			navigate,
+			route
+		};
+		if (match.found) {
+			currentCleanup = renderDom(match.screen, {
+				target: options.target,
+				services: mergedServices,
+				showScreenName
+			});
+			return;
+		}
+		if (options.notFound) {
+			const screen = typeof options.notFound === "function" ? options.notFound(pathname) : options.notFound;
+			currentCleanup = renderDom(screen, {
+				target: options.target,
+				services: mergedServices,
+				showScreenName
+			});
+		} else options.target.textContent = "Not found";
+	}
+	renderPath(win.location.pathname);
+	function onPopState() {
+		renderPath(win.location.pathname);
+	}
+	win.addEventListener("popstate", onPopState);
+	return {
+		navigate,
+		renderPath,
+		dispose() {
+			currentCleanup?.();
+			currentCleanup = void 0;
+			win.removeEventListener("popstate", onPopState);
+		}
+	};
+}
+
+//#endregion
+//#region src/index.ts
+function getReasonId(actId) {
+	return `${actId}-reason`;
+}
+function getEnterHintId(askId) {
+	return `${askId}-enter-hint`;
+}
+function sanitizeLabel(label) {
+	return label.replace(/\.+$/, "");
+}
+function findDefaultAction(acts) {
+	const primaryActs = acts.filter((a) => a.primary);
+	if (primaryActs.length === 1) return primaryActs[0];
+	if (acts.length === 1) return acts[0];
+	return void 0;
+}
+function renderDom(screenDef, options) {
+	const { target, services, showScreenName } = options;
+	target.innerHTML = "";
+	const root = buildDom(screenDef, showScreenName);
+	target.appendChild(root);
+	const runtime = createScreenRuntime(screenDef, { services });
+	runtime.start();
+	const form = target.querySelector("form");
+	const output = target.querySelector("output#feedback-output");
+	const unsubscribers = [];
+	for (const act of screenDef.acts) {
+		const button = form.querySelector(`#${act.id}`);
+		if (button) {
+			const unsub = act.enabled.subscribe(() => {
+				button.disabled = !act.enabled.current;
+				const reasonId = getReasonId(act.id);
+				let reasonEl = form.querySelector(`#${reasonId}`);
+				if (!act.enabled.current && act.blockedReasons.length > 0) {
+					button.setAttribute("aria-describedby", reasonId);
+					if (!reasonEl) {
+						reasonEl = document.createElement("p");
+						reasonEl.id = reasonId;
+						form.appendChild(reasonEl);
+					}
+					reasonEl.textContent = act.blockedReasons[0];
+				} else {
+					button.removeAttribute("aria-describedby");
+					if (reasonEl) reasonEl.remove();
+				}
+			});
+			unsubscribers.push(unsub);
+		}
+	}
+	for (const act of screenDef.acts) {
+		const unsub = act.onStatusChange(() => {
+			updateFeedback(act, output);
+		});
+		unsubscribers.push(unsub);
+	}
+	for (const act of screenDef.acts) {
+		const button = form.querySelector(`#${act.id}`);
+		if (button) button.addEventListener("click", () => {
+			if (act.enabled.current) runtime.executeAct(act);
+		});
+	}
+	const defaultActionForHint = findDefaultAction(screenDef.acts);
+	if (defaultActionForHint) {
+		const unsub = defaultActionForHint.enabled.subscribe(() => {
+			const isEnabled = defaultActionForHint.enabled.current;
+			for (const ask of screenDef.asks) {
+				const input = form.querySelector(`#${ask.id}`);
+				const hint = form.querySelector(`#${getEnterHintId(ask.id)}`);
+				if (input && hint) {
+					const hintId = getEnterHintId(ask.id);
+					if (isEnabled) {
+						hint.style.display = "";
+						const existing = input.getAttribute("aria-describedby") || "";
+						const ids = existing.split(/\s+/).filter(Boolean);
+						if (!ids.includes(hintId)) ids.push(hintId);
+						input.setAttribute("aria-describedby", ids.join(" "));
+					} else {
+						hint.style.display = "none";
+						const existing = input.getAttribute("aria-describedby") || "";
+						const ids = existing.split(/\s+/).filter(Boolean).filter((id) => id !== hintId);
+						if (ids.length > 0) input.setAttribute("aria-describedby", ids.join(" "));
+						else input.removeAttribute("aria-describedby");
+					}
+				}
+			}
+		});
+		unsubscribers.push(unsub);
+	}
+	for (const ask of screenDef.asks) {
+		const input = form.querySelector(`#${ask.id}`);
+		if (input) {
+			const onKeyDown = (event) => {
+				if (event.key !== "Enter") return;
+				if (event.shiftKey || event.metaKey || event.ctrlKey || event.altKey) return;
+				if (input.tagName === "TEXTAREA") return;
+				const defaultAction = findDefaultAction(screenDef.acts);
+				if (!defaultAction || !defaultAction.enabled.current) return;
+				event.preventDefault();
+				runtime.executeAct(defaultAction);
+			};
+			input.addEventListener("keydown", onKeyDown);
+			unsubscribers.push(() => input.removeEventListener("keydown", onKeyDown));
+		}
+	}
+	return () => {
+		for (const unsub of unsubscribers) unsub();
+		runtime.dispose();
+	};
+}
+function buildDom(screenDef, showScreenName) {
+	const surface = screenDef.surfaces[0];
+	const main = document.createElement("main");
+	if (surface) main.id = surface.id;
+	if (showScreenName) {
+		const heading = document.createElement("h1");
+		heading.textContent = screenDef.name;
+		main.appendChild(heading);
+	}
+	const form = document.createElement("form");
+	form.setAttribute("method", "POST");
+	form.setAttribute("novalidate", "");
+	for (const ask of screenDef.asks) {
+		const container = document.createElement("div");
+		container.className = "ask-group";
+		const label = document.createElement("label");
+		label.textContent = ask.label;
+		label.htmlFor = ask.id;
+		container.appendChild(label);
+		const input = createInputForAsk(ask);
+		input.id = ask.id;
+		input.name = ask.id;
+		if (ask.required) input.required = true;
+		if (ask.kind === "contact" && ask.contactKind) input.setAttribute("autocomplete", ask.contactKind);
+		input.addEventListener("input", () => {
+			const stateObj = ask.state;
+			if (typeof stateObj.set === "function") stateObj.set(input.value);
+		});
+		container.appendChild(input);
+		if (ask.hintText) {
+			const hint = document.createElement("p");
+			hint.id = `${ask.id}-hint`;
+			hint.textContent = ask.hintText;
+			container.appendChild(hint);
+		}
+		const defaultAction = findDefaultAction(screenDef.acts);
+		if (defaultAction) {
+			const hintId = getEnterHintId(ask.id);
+			const hint = document.createElement("p");
+			hint.id = hintId;
+			hint.textContent = `Press Enter to ${sanitizeLabel(defaultAction.label)}.`;
+			if (!defaultAction.enabled.current) hint.style.display = "none";
+			container.appendChild(hint);
+			if (defaultAction.enabled.current) {
+				const existing = input.getAttribute("aria-describedby");
+				if (existing) input.setAttribute("aria-describedby", `${existing} ${hintId}`);
+				else input.setAttribute("aria-describedby", hintId);
+			}
+		}
+		form.appendChild(container);
+	}
+	for (const act of screenDef.acts) {
+		const button = document.createElement("button");
+		button.id = act.id;
+		button.type = "button";
+		button.textContent = act.label;
+		if (act.primary) button.className = "primary";
+		if (!act.enabled.current) {
+			button.disabled = true;
+			if (act.blockedReasons.length > 0) {
+				const reasonId = getReasonId(act.id);
+				button.setAttribute("aria-describedby", reasonId);
+				const reasonEl = document.createElement("p");
+				reasonEl.id = reasonId;
+				reasonEl.textContent = act.blockedReasons[0];
+				form.appendChild(reasonEl);
+			}
+		}
+		form.appendChild(button);
+	}
+	const output = document.createElement("output");
+	output.id = "feedback-output";
+	output.setAttribute("aria-live", "polite");
+	form.appendChild(output);
+	main.appendChild(form);
+	return main;
+}
+function updateFeedback(act, output) {
+	const msg = act.feedback && act.statusMessage ? act.statusMessage : "";
+	if (msg) output.textContent = msg;
+	else output.textContent = "";
+}
+function createInputForAsk(ask) {
+	const input = document.createElement("input");
+	if (ask.kind === "contact" && ask.contactKind === "email") input.type = "email";
+	else if (ask.kind === "secret") input.type = "password";
+	else if (ask.kind === "choice") {
+		input.type = "text";
+		input.setAttribute("role", "combobox");
+	} else input.type = "text";
+	return input;
+}
+
+//#endregion
+export { renderDom, renderRouter };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@intent-framework/dom",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.1.0-alpha.0",
+  "description": "DOM materializer for Intent screens and router",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intent-framework/intent.git",
+    "directory": "packages/dom"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@intent-framework/core": "0.1.0-alpha.0",
+    "@intent-framework/router": "0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "jsdom": "^29.1.1",
+    "tsdown": "^0.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc -b",
+    "lint": "tsc -b"
+  }
+}