@intent-framework/dom 0.1.0-alpha.6 → 0.1.0-alpha.8

package/README.md

@@ -22,6 +22,66 @@ npm install @intent-framework/core @intent-framework/dom
 - Opt-in screen-name heading via `showScreenName`
 - Opt-in semantic data attributes via `showSemanticIds`
 
+## renderDom behavior
+
+### Input types
+
+| Ask kind | Renders as |
+|----------|------------|
+| `$.state.text()` / default | `<input type="text">` |
+| `asContact("email")` | `<input type="email">` with `autocomplete="email"` |
+| `asSecret()` | `<input type="password">` |
+| `$.state.boolean()` | `<input type="checkbox">` |
+| `$.state.choice()` with `asChoice()` | `<select>` with `<option>` elements |
+
+### Boolean and choice asks
+
+Boolean asks render as checkboxes. The checked state is synced with the underlying `BooleanState`.
+
+Choice asks render as `<select>` elements. Options are populated from the `ChoiceState` options array. The selected value is synced with the underlying state.
+
+### Blocked reasons
+
+When an action is disabled due to blocked reasons, the renderer adds:
+
+- `disabled` attribute on the button
+- `<p class="intent-blocked-reason" role="alert">` with the first blocked reason text
+- `aria-describedby` on the button pointing to the reason element
+
+When the action becomes enabled, the reason element is removed from the DOM and `aria-describedby` is cleared.
+
+### Single-surface output
+
+When a screen has exactly one surface, the output is backward compatible: a single `<main>` element containing one `<form>` with all asks and actions. No surface name suffix is added to DOM ids.
+
+### Multi-surface output
+
+When a screen has multiple surfaces, each surface renders as a separate `<section>` with `aria-label` set to the surface name. Each section contains its own `<form>` with only the items belonging to that surface.
+
+**DOM id suffixes:** All ask inputs, buttons, hint paragraphs, reason paragraphs, and feedback outputs get a `--<surfaceName>` suffix to avoid id collisions.
+
+**Duplicate controls share state:** The same ask appearing in multiple surfaces shares the underlying state. Typing in one surface updates the input in all surfaces.
+
+**Duplicate action buttons:** The same action appearing in multiple surfaces renders separate buttons, all executing the same `executeAct()` call.
+
+**Per-surface feedback:** Each surface gets its own `<output aria-live="polite">` element. Action feedback is updated independently per surface.
+
+**`data-intent-*` semantic ids:** The `data-intent-ask` and `data-intent-action` attributes remain the same across all copies — they identify the semantic node, not the DOM position.
+
+### Enter key default action
+
+When exactly one primary action exists (or exactly one action total), pressing Enter in any text input triggers that action. The Enter hint ("Press Enter to ...") appears reactively when the default action becomes enabled, and is hidden when disabled. Shift/ Meta/ Ctrl/ Alt + Enter are ignored. Enter is ignored on `<textarea>`, `<select>`, and checkbox inputs.
+
+### Options
+
+```ts
+renderDom(Screen, {
+  target: document.getElementById("root")!,
+  showScreenName: true,        // render screen name as <h1>
+  showSemanticIds: true,       // add data-intent-screen, data-intent-ask, data-intent-action attributes
+})
+```
+
 ## Minimal example
 
 ```ts

package/dist/index.js

@@ -63,15 +63,18 @@ function renderRouter(router, options) {
 
 //#endregion
 //#region src/index.ts
-function getReasonId(actId) {
-	return `${actId}-reason`;
+function getReasonId(actId, suffix = "") {
+	return `${actId}-reason${suffix}`;
 }
-function getEnterHintId(askId) {
-	return `${askId}-enter-hint`;
+function getEnterHintId(askId, suffix = "") {
+	return `${askId}-enter-hint${suffix}`;
 }
 function sanitizeLabel(label) {
 	return label.replace(/\.+$/, "");
 }
+function surfaceSuffix(surfaceName, isMulti) {
+	return isMulti ? `--${surfaceName}` : "";
+}
 function findDefaultAction(acts) {
 	const primaryActs = acts.filter((a) => a.primary);
 	if (primaryActs.length === 1) return primaryActs[0];
@@ -81,19 +84,22 @@ function findDefaultAction(acts) {
 function renderDom(screenDef, options) {
 	const { target, services, showScreenName, showSemanticIds } = options;
 	target.innerHTML = "";
+	const isMulti = screenDef.surfaces.length > 1;
 	const root = buildDom(screenDef, showScreenName, showSemanticIds);
 	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(() => {
+		const unsub = act.enabled.subscribe(() => {
+			for (const surface of screenDef.surfaces) {
+				const suffix = surfaceSuffix(surface.name, isMulti);
+				const form = getSurfaceForm(root, surface, isMulti);
+				if (!form) continue;
+				const button = form.querySelector(`#${act.id}${suffix}`);
+				if (!button) continue;
 				button.disabled = !act.enabled.current;
-				const reasonId = getReasonId(act.id);
+				const reasonId = getReasonId(act.id, suffix);
 				let reasonEl = form.querySelector(`#${reasonId}`);
 				if (!act.enabled.current && act.blockedReasons.length > 0) {
 					button.setAttribute("aria-describedby", reasonId);
@@ -109,18 +115,27 @@ function renderDom(screenDef, options) {
 					button.removeAttribute("aria-describedby");
 					if (reasonEl) reasonEl.remove();
 				}
-			});
-			unsubscribers.push(unsub);
-		}
+			}
+		});
+		unsubscribers.push(unsub);
 	}
 	for (const act of screenDef.acts) {
 		const unsub = act.onStatusChange(() => {
-			updateFeedback(act, output);
+			for (const surface of screenDef.surfaces) {
+				const suffix = surfaceSuffix(surface.name, isMulti);
+				const form = getSurfaceForm(root, surface, isMulti);
+				if (!form) continue;
+				const output = form.querySelector(`#feedback-output${suffix}`);
+				if (output) updateFeedback(act, output);
+			}
 		});
 		unsubscribers.push(unsub);
 	}
-	for (const act of screenDef.acts) {
-		const button = form.querySelector(`#${act.id}`);
+	for (const act of screenDef.acts) for (const surface of screenDef.surfaces) {
+		const suffix = surfaceSuffix(surface.name, isMulti);
+		const form = getSurfaceForm(root, surface, isMulti);
+		if (!form) continue;
+		const button = form.querySelector(`#${act.id}${suffix}`);
 		if (button) button.addEventListener("click", () => {
 			if (act.enabled.current) runtime.executeAct(act);
 		});
@@ -129,52 +144,88 @@ function renderDom(screenDef, options) {
 	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");
+			for (const surface of screenDef.surfaces) {
+				const suffix = surfaceSuffix(surface.name, isMulti);
+				const form = getSurfaceForm(root, surface, isMulti);
+				if (!form) continue;
+				for (const item of surface.items) {
+					if (!("state" in item)) continue;
+					const ask = item;
+					const input = form.querySelector(`#${ask.id}${suffix}`);
+					const hint = form.querySelector(`#${getEnterHintId(ask.id, suffix)}`);
+					if (input && hint) {
+						const hintId = getEnterHintId(ask.id, suffix);
+						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;
-				if (input.tagName === "SELECT") return;
-				if (input.type === "checkbox") 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));
+	for (const surface of screenDef.surfaces) {
+		const suffix = surfaceSuffix(surface.name, isMulti);
+		const form = getSurfaceForm(root, surface, isMulti);
+		if (!form) continue;
+		for (const item of surface.items) {
+			if (!("state" in item)) continue;
+			const ask = item;
+			const input = form.querySelector(`#${ask.id}${suffix}`);
+			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;
+					if (input.tagName === "SELECT") return;
+					if (input.type === "checkbox") 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));
+			}
 		}
 	}
+	for (const ask of screenDef.asks) {
+		const unsub = ask.subscribe(() => {
+			for (const surface of screenDef.surfaces) {
+				const suffix = surfaceSuffix(surface.name, isMulti);
+				const form = getSurfaceForm(root, surface, isMulti);
+				if (!form) continue;
+				const control = form.querySelector(`#${ask.id}${suffix}`);
+				if (!control) continue;
+				if (typeof ask.state.value === "boolean") control.checked = ask.state.value;
+				else if (ask.kind === "choice") control.value = ask.state.value;
+				else control.value = ask.state.value;
+			}
+		});
+		unsubscribers.push(unsub);
+	}
 	return () => {
 		for (const unsub of unsubscribers) unsub();
 		runtime.dispose();
 	};
 }
+function getSurfaceForm(root, surface, isMulti) {
+	if (isMulti) {
+		const section = root.querySelector(`#${surface.id}`);
+		return section ? section.querySelector("form") : null;
+	}
+	return root.querySelector("form");
+}
 function buildDom(screenDef, showScreenName, showSemanticIds) {
 	let inspected;
 	let askSemanticIds;
@@ -184,118 +235,171 @@ function buildDom(screenDef, showScreenName, showSemanticIds) {
 		askSemanticIds = new Map(inspected.asks.map((a) => [a.id, a.semanticId]));
 		actSemanticIds = new Map(inspected.acts.map((a) => [a.id, a.semanticId]));
 	}
-	const surface = screenDef.surfaces[0];
+	const isMulti = screenDef.surfaces.length > 1;
 	const main = document.createElement("main");
-	if (surface) main.id = surface.id;
 	if (showSemanticIds && inspected) main.setAttribute("data-intent-screen", inspected.semanticId);
 	if (showScreenName) {
 		const heading = document.createElement("h1");
 		heading.textContent = screenDef.name;
 		main.appendChild(heading);
 	}
+	if (isMulti) for (const surface of screenDef.surfaces) {
+		const section = buildSurface(screenDef, surface, showSemanticIds, askSemanticIds, actSemanticIds, isMulti);
+		main.appendChild(section);
+	}
+	else if (screenDef.surfaces.length === 1) {
+		const surface = screenDef.surfaces[0];
+		main.id = surface.id;
+		const form = buildForm(screenDef, surface, showSemanticIds, askSemanticIds, actSemanticIds, isMulti);
+		main.appendChild(form);
+	}
+	return main;
+}
+function buildSurface(screenDef, surface, showSemanticIds, askSemanticIds, actSemanticIds, isMulti) {
+	const section = document.createElement("section");
+	section.id = surface.id;
+	section.setAttribute("aria-label", surface.name);
+	const form = buildForm(screenDef, surface, showSemanticIds, askSemanticIds, actSemanticIds, isMulti);
+	section.appendChild(form);
+	return section;
+}
+function buildForm(screenDef, surface, showSemanticIds, askSemanticIds, actSemanticIds, isMulti) {
+	const isMultiSurface = isMulti ?? screenDef.surfaces.length > 1;
+	const suffix = surfaceSuffix(surface.name, isMultiSurface);
 	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;
-		if (showSemanticIds && askSemanticIds) {
-			const sid = askSemanticIds.get(ask.id);
-			if (sid) label.setAttribute("data-intent-ask", sid);
-		}
-		container.appendChild(label);
-		const control = createInputForAsk(ask);
-		control.id = ask.id;
-		control.name = ask.id;
-		if (showSemanticIds && askSemanticIds) {
-			const sid = askSemanticIds.get(ask.id);
-			if (sid) control.setAttribute("data-intent-ask", sid);
-		}
-		if (ask.required) control.required = true;
-		if (ask.kind === "contact" && ask.contactKind) control.setAttribute("autocomplete", ask.contactKind);
-		if (typeof ask.state.value === "boolean") {
-			const stateObj = ask.state;
-			control.checked = stateObj.value;
-			control.addEventListener("change", () => {
-				stateObj.set(control.checked);
-			});
-		} else if (ask.kind === "choice") {
-			const stateObj = ask.state;
-			const select = control;
-			for (const opt of stateObj.options) {
-				const option = document.createElement("option");
-				option.value = opt;
-				option.textContent = opt;
-				select.appendChild(option);
-			}
-			select.value = stateObj.value;
-			select.addEventListener("change", () => {
-				stateObj.set(select.value);
+	if (isMultiSurface) {
+		for (const item of surface.items) if ("state" in item) buildAskControl(form, screenDef, item, suffix, showSemanticIds, askSemanticIds);
+		else if ("handler" in item) buildActionButton(form, item, suffix, showSemanticIds, actSemanticIds);
+	} else {
+		const surfaceAskIds = /* @__PURE__ */ new Set();
+		const surfaceActIds = /* @__PURE__ */ new Set();
+		const orderedItems = [];
+		for (const item of surface.items) if ("state" in item) {
+			const ask = item;
+			surfaceAskIds.add(ask.id);
+			orderedItems.push({
+				kind: "ask",
+				node: ask
 			});
-		} else {
-			const textInput = control;
-			textInput.addEventListener("input", () => {
-				const stateObj = ask.state;
-				if (typeof stateObj.set === "function") stateObj.set(textInput.value);
+		} else if ("handler" in item) {
+			const act = item;
+			surfaceActIds.add(act.id);
+			orderedItems.push({
+				kind: "act",
+				node: act
 			});
 		}
-		container.appendChild(control);
-		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 = control.getAttribute("aria-describedby");
-				if (existing) control.setAttribute("aria-describedby", `${existing} ${hintId}`);
-				else control.setAttribute("aria-describedby", hintId);
-			}
+		for (const ask of screenDef.asks) if (!surfaceAskIds.has(ask.id)) orderedItems.push({
+			kind: "ask",
+			node: ask
+		});
+		for (const act of screenDef.acts) if (!surfaceActIds.has(act.id)) orderedItems.push({
+			kind: "act",
+			node: act
+		});
+		for (const item of orderedItems) if (item.kind === "ask") buildAskControl(form, screenDef, item.node, suffix, showSemanticIds, askSemanticIds);
+		else buildActionButton(form, item.node, suffix, showSemanticIds, actSemanticIds);
+	}
+	const output = document.createElement("output");
+	output.id = `feedback-output${suffix}`;
+	output.setAttribute("aria-live", "polite");
+	form.appendChild(output);
+	return form;
+}
+function buildAskControl(form, screenDef, ask, suffix, showSemanticIds, askSemanticIds) {
+	const container = document.createElement("div");
+	container.className = "ask-group";
+	const label = document.createElement("label");
+	label.textContent = ask.label;
+	label.htmlFor = `${ask.id}${suffix}`;
+	if (showSemanticIds && askSemanticIds) {
+		const sid = askSemanticIds.get(ask.id);
+		if (sid) label.setAttribute("data-intent-ask", sid);
+	}
+	container.appendChild(label);
+	const control = createInputForAsk(ask);
+	control.id = `${ask.id}${suffix}`;
+	control.name = `${ask.id}${suffix}`;
+	if (showSemanticIds && askSemanticIds) {
+		const sid = askSemanticIds.get(ask.id);
+		if (sid) control.setAttribute("data-intent-ask", sid);
+	}
+	if (ask.required) control.required = true;
+	if (ask.kind === "contact" && ask.contactKind) control.setAttribute("autocomplete", ask.contactKind);
+	const stateObj = ask.state;
+	if (typeof ask.state.value === "boolean") {
+		control.checked = stateObj.value;
+		control.addEventListener("change", () => {
+			stateObj.set(control.checked);
+		});
+	} else if (ask.kind === "choice") {
+		const select = control;
+		const options = stateObj.options;
+		for (const opt of options) {
+			const option = document.createElement("option");
+			option.value = opt;
+			option.textContent = opt;
+			select.appendChild(option);
 		}
-		form.appendChild(container);
+		select.value = stateObj.value;
+		select.addEventListener("change", () => {
+			stateObj.set(select.value);
+		});
+	} else {
+		const textInput = control;
+		textInput.addEventListener("input", () => {
+			if (typeof stateObj.set === "function") stateObj.set(textInput.value);
+		});
 	}
-	for (const act of screenDef.acts) {
-		const button = document.createElement("button");
-		button.id = act.id;
-		button.type = "button";
-		button.textContent = act.label;
-		if (showSemanticIds && actSemanticIds) {
-			const sid = actSemanticIds.get(act.id);
-			if (sid) button.setAttribute("data-intent-action", sid);
+	container.appendChild(control);
+	if (ask.hintText) {
+		const hint = document.createElement("p");
+		hint.id = `${ask.id}-hint${suffix}`;
+		hint.textContent = ask.hintText;
+		container.appendChild(hint);
+	}
+	const defaultAction = findDefaultAction(screenDef.acts);
+	if (defaultAction) {
+		const hintId = getEnterHintId(ask.id, suffix);
+		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 = control.getAttribute("aria-describedby");
+			if (existing) control.setAttribute("aria-describedby", `${existing} ${hintId}`);
+			else control.setAttribute("aria-describedby", hintId);
 		}
-		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.className = "intent-blocked-reason";
-				reasonEl.setAttribute("role", "alert");
-				reasonEl.textContent = act.blockedReasons[0];
-				form.appendChild(reasonEl);
-			}
+	}
+	form.appendChild(container);
+}
+function buildActionButton(form, act, suffix, showSemanticIds, actSemanticIds) {
+	const button = document.createElement("button");
+	button.id = `${act.id}${suffix}`;
+	button.type = "button";
+	button.textContent = act.label;
+	if (showSemanticIds && actSemanticIds) {
+		const sid = actSemanticIds.get(act.id);
+		if (sid) button.setAttribute("data-intent-action", sid);
+	}
+	if (act.primary) button.className = "primary";
+	if (!act.enabled.current) {
+		button.disabled = true;
+		if (act.blockedReasons.length > 0) {
+			const reasonId = getReasonId(act.id, suffix);
+			button.setAttribute("aria-describedby", reasonId);
+			const reasonEl = document.createElement("p");
+			reasonEl.id = reasonId;
+			reasonEl.className = "intent-blocked-reason";
+			reasonEl.setAttribute("role", "alert");
+			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;
+	form.appendChild(button);
 }
 function updateFeedback(act, output) {
 	const msg = act.feedback && act.statusMessage ? act.statusMessage : "";

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "description": "DOM materializer for Intent screens and router",
   "license": "MIT",
   "repository": {
@@ -26,8 +26,8 @@
     "dist"
   ],
   "dependencies": {
-    "@intent-framework/core": "^0.1.0-alpha.6",
-    "@intent-framework/router": "^0.1.0-alpha.6"
+    "@intent-framework/core": "^0.1.0-alpha.8",
+    "@intent-framework/router": "^0.1.0-alpha.8"
   },
   "devDependencies": {
     "jsdom": "^29.1.1",