@intent-framework/dom 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -0,0 +1,65 @@
+# @intent-framework/dom
+
+DOM materializer for Intent screens and router.
+
+## Install
+
+```sh
+pnpm add @intent-framework/core@0.1.0-alpha.1 @intent-framework/dom@0.1.0-alpha.1
+```
+
+```sh
+npm install @intent-framework/core@0.1.0-alpha.1 @intent-framework/dom@0.1.0-alpha.1
+```
+
+## What it provides
+
+- `renderDom()` — materialize a screen into semantic HTML
+- `renderRouter()` — materialize a router into navigable DOM pages
+- Real HTML labels, inputs, buttons, and `aria-live` output
+- Reactive action enablement and blocked reasons
+- Enter key triggers the default action when unambiguous
+- Opt-in screen-name heading via `showScreenName`
+- Opt-in semantic data attributes via `showSemanticIds`
+
+## Minimal example
+
+```ts
+import { screen } from "@intent-framework/core"
+import { renderDom } from "@intent-framework/dom"
+
+const InviteMember = screen("InviteMember", $ => {
+  const email = $.state.text("email")
+
+  const emailAsk = $.ask("Email", email)
+    .required()
+    .validate(value => value.includes("@") ? true : "Enter a valid email")
+
+  const invite = $.act("Invite member")
+    .primary()
+    .when(emailAsk.valid, "Enter a valid email first")
+
+  $.surface("main").contains(emailAsk, invite)
+})
+
+const cleanup = renderDom(InviteMember, {
+  target: document.getElementById("root")!,
+})
+```
+
+The renderer produces real DOM — labels, inputs, buttons, and an `aria-live` output. No JSX required.
+
+## Where this fits
+
+DOM is a renderer for Intent screens. It depends on `@intent-framework/core` and can optionally integrate with `@intent-framework/router` via `renderRouter()`. It is not the source of truth — the screen definition is.
+
+## Learn more
+
+- [Root README](../../README.md) — project overview and philosophy
+- [Quickstart](../../docs/Quickstart.md) — step-by-step guide with DOM rendering
+- [Semantic DOM Debugging](../../docs/Semantic-DOM-Debugging.md) — how `showSemanticIds` maps `inspectScreen()` IDs to DOM data attributes
+- [Canonical runnable example](../../examples/canonical-invite) — matches the Quickstart one-to-one
+
+## Status
+
+Experimental alpha. Version `0.1.0-alpha.1`. APIs may change. Not recommended for production use.

package/dist/dom-router.d.ts

@@ -13,6 +13,7 @@ export type RenderRouterOptions<TServices extends object = DefaultScreenServices
     notFound?: ScreenDefinition<TServices> | ((pathname: string) => ScreenDefinition<TServices>);
     services?: Omit<TServices, "navigate" | "route">;
     showScreenName?: boolean;
+    showSemanticIds?: boolean;
 };
 export declare function renderRouter<Routes extends Record<string, {
     path: string;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type DomRendererOptions<TServices extends object = DefaultScreenServices>
     target: HTMLElement;
     services?: TServices;
     showScreenName?: boolean;
+    showSemanticIds?: boolean;
 };
 export { renderRouter } from "./dom-router.js";
 export type { RouterDomHandle, RenderRouterOptions } from "./dom-router.js";

package/dist/index.js

@@ -1,8 +1,8 @@
-import { createScreenRuntime } from "@intent-framework/core";
+import { createScreenRuntime, inspectScreen } from "@intent-framework/core";
 
 //#region src/dom-router.ts
 function renderRouter(router, options) {
-	const { showScreenName } = options;
+	const { showScreenName, showSemanticIds } = options;
 	const win = options.window ?? window;
 	let currentCleanup;
 	const navigate = (name, ...args) => {
@@ -30,7 +30,8 @@ function renderRouter(router, options) {
 			currentCleanup = renderDom(match.screen, {
 				target: options.target,
 				services: mergedServices,
-				showScreenName
+				showScreenName,
+				showSemanticIds
 			});
 			return;
 		}
@@ -39,7 +40,8 @@ function renderRouter(router, options) {
 			currentCleanup = renderDom(screen, {
 				target: options.target,
 				services: mergedServices,
-				showScreenName
+				showScreenName,
+				showSemanticIds
 			});
 		} else options.target.textContent = "Not found";
 	}
@@ -77,9 +79,9 @@ function findDefaultAction(acts) {
 	return void 0;
 }
 function renderDom(screenDef, options) {
-	const { target, services, showScreenName } = options;
+	const { target, services, showScreenName, showSemanticIds } = options;
 	target.innerHTML = "";
-	const root = buildDom(screenDef, showScreenName);
+	const root = buildDom(screenDef, showScreenName, showSemanticIds);
 	target.appendChild(root);
 	const runtime = createScreenRuntime(screenDef, { services });
 	runtime.start();
@@ -169,10 +171,19 @@ function renderDom(screenDef, options) {
 		runtime.dispose();
 	};
 }
-function buildDom(screenDef, showScreenName) {
+function buildDom(screenDef, showScreenName, showSemanticIds) {
+	let inspected;
+	let askSemanticIds;
+	let actSemanticIds;
+	if (showSemanticIds) {
+		inspected = inspectScreen(screenDef);
+		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 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;
@@ -187,10 +198,18 @@ function buildDom(screenDef, showScreenName) {
 		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 input = createInputForAsk(ask);
 		input.id = ask.id;
 		input.name = ask.id;
+		if (showSemanticIds && askSemanticIds) {
+			const sid = askSemanticIds.get(ask.id);
+			if (sid) input.setAttribute("data-intent-ask", sid);
+		}
 		if (ask.required) input.required = true;
 		if (ask.kind === "contact" && ask.contactKind) input.setAttribute("autocomplete", ask.contactKind);
 		input.addEventListener("input", () => {
@@ -225,6 +244,10 @@ function buildDom(screenDef, showScreenName) {
 		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);
+		}
 		if (act.primary) button.className = "primary";
 		if (!act.enabled.current) {
 			button.disabled = true;

package/package.json

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