@nativele/ts-dom 0.0.0-stage → 0.2.1

package/dist/a11y-DZvViTVA.mjs

@@ -0,0 +1,649 @@
+import { i as RESERVED_NAMES, n as IDENT, r as holeName, t as HOLE_ANY } from "./holes-DTBtTZF_.mjs";
+import { existsSync, readFileSync, readdirSync, statSync, unlinkSync, watch, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { parseFragment } from "parse5";
+// src/lib/codegen.ts
+/** Every diagnostic that `ts-dom gen` can report while analyzing a template. */
+const CODEGEN_RULES = {
+	"invalid-hole": "a {{ hole }} must be a single identifier (no paths or expressions)",
+	"attr-hole": "{{ }} is only supported in text, not in attributes",
+	"invalid-event-name": "the event name in data-on-<event> must be lowercase",
+	"invalid-handler": "data-on-* must be a plain method name (no calls or expressions)",
+	"reserved-handler": "the handler name would override a DOM or ts-dom member",
+	"empty-ref": "data-ref must not be empty",
+	"duplicate-ref": "data-ref names must be unique within a scope",
+	"empty-if": "data-if must not be empty",
+	"if-on-item-root": "data-if cannot be on the root element of a data-each item",
+	"slot-in-list": "<slot> cannot be inside a data-each template",
+	"style-not-top-level": "<style> must be a top-level element of the template",
+	"duplicate-slot": "slot names should be unique (warning)",
+	"each-not-template": "data-each only works on <template>",
+	"empty-each": "data-each must not be empty",
+	"nested-each": "data-each templates cannot be nested",
+	"duplicate-each": "data-each names must be unique",
+	"each-root-count": "a data-each template needs exactly one root element",
+	"forbidden-tag": "<script> cannot be in a template (it would run code)",
+	"forbidden-attribute": "on* event attributes and srcdoc cannot be in a template (they run code or are blocked by Trusted Types)",
+	"unsafe-url": "href / src / action / formaction cannot start with javascript:",
+	"duplicate-define": "a custom element tag can be defined only once per scanned directory"
+};
+const URL_ATTRS = /^(href|src|action|formaction|xlink:href)$/i;
+const HTML_NS = "http://www.w3.org/1999/xhtml";
+const newScope = () => ({
+	refs: /* @__PURE__ */ new Map(),
+	text: /* @__PURE__ */ new Set(),
+	ifs: /* @__PURE__ */ new Set()
+});
+const attr$1 = (el, name) => el.attrs.find((a) => a.name === name)?.value;
+const isEl$1 = (n) => "tagName" in n;
+const isRaw = (n) => n.tagName === "style" || n.tagName === "script";
+const locOf = (n) => {
+	const loc = n.sourceCodeLocation;
+	return {
+		line: loc?.startLine ?? 1,
+		col: loc?.startCol ?? 1
+	};
+};
+/** Scan an HTML template for data-ref / data-each / data-if / <slot name> / {{ name }} / data-on-* and collect diagnostics. */
+function analyze(html) {
+	const root = parseFragment(html, { sourceCodeLocationInfo: true });
+	const a = {
+		scope: newScope(),
+		lists: /* @__PURE__ */ new Map(),
+		slots: /* @__PURE__ */ new Set(),
+		events: /* @__PURE__ */ new Set(),
+		eventSites: [],
+		customTags: /* @__PURE__ */ new Set(),
+		customUses: [],
+		locs: /* @__PURE__ */ new Map(),
+		diagnostics: []
+	};
+	const report = (rule, severity, message, n) => {
+		a.diagnostics.push({
+			rule,
+			severity,
+			message,
+			...locOf(n)
+		});
+	};
+	const mark = (key, n) => {
+		if (!a.locs.has(key)) a.locs.set(key, locOf(n));
+	};
+	function holesIn(value, scope, listName, at) {
+		for (const m of value.matchAll(HOLE_ANY)) {
+			const name = holeName(m[1] ?? "");
+			if (name) {
+				scope.text.add(name);
+				mark(listName ? `text:${listName}/${name}` : `text:${name}`, at);
+			} else {
+				const inner = (m[1] ?? "").trim();
+				report("invalid-hole", "error", `{{ ${inner} }} is not a valid hole: a hole must be a single identifier, paths and expressions are not supported. Fix: compute the value in TypeScript (state, derive or this.text) and use a named hole such as {{ name }}.`, at);
+			}
+		}
+	}
+	function walk(parent, scope, listName, itemRoot = false, top = false) {
+		const children = "content" in parent && parent.nodeName === "template" ? parent.content.childNodes : parent.childNodes;
+		for (const n of children) {
+			if (n.nodeName === "#text") {
+				const p = n.parentNode;
+				if (!(p && isEl$1(p) && isRaw(p))) holesIn(n.value, scope, listName, n);
+				continue;
+			}
+			if (!isEl$1(n)) continue;
+			const tag = n.tagName;
+			const isCustom = tag.includes("-") && n.namespaceURI === HTML_NS;
+			if (isCustom) a.customTags.add(tag);
+			for (const at of n.attrs) if (at.value.includes("{{")) report("attr-hole", "error", `Attribute ${at.name} contains {{ }}, which is only supported in text. Fix: add data-ref to the element and set the attribute from TypeScript (e.g. this.refs.x.setAttribute(...)).`, n);
+			if (tag === "script" && n.namespaceURI === HTML_NS) report("forbidden-tag", "error", "<script> cannot be in a template. Fix: put the code in TypeScript and attach it with a data-on-* handler or a component.", n);
+			for (const at of n.attrs) if (/^on/i.test(at.name) || at.name === "srcdoc") report("forbidden-attribute", "error", `${at.name} cannot be in a template: it runs code or is blocked when Trusted Types is enforced. Fix: ${at.name === "srcdoc" ? "load the document with a component that sets it from TypeScript" : `use data-on-${at.name.slice(2).toLowerCase()}="method" and a public method`}.`, n);
+			else if (URL_ATTRS.test(at.name) && /^\s*javascript:/i.test(at.value)) report("unsafe-url", "error", `${at.name}="${at.value}" starts with javascript:, which runs code. Fix: use a data-on-click handler, or a real URL.`, n);
+			const handlers = [];
+			for (const at of n.attrs) {
+				if (!at.name.startsWith("data-on-")) continue;
+				const type = at.name.slice(8);
+				const method = at.value.trim();
+				if (!/^[a-z][\w-]*$/.test(type)) report("invalid-event-name", "error", `${at.name} has an invalid event name. Fix: use a lowercase event name such as data-on-click or data-on-field-input (HTML attributes are case-insensitive).`, n);
+				else if (!IDENT.test(method)) report("invalid-handler", "error", `${at.name}="${at.value}" must be a plain method name; expressions, calls and paths are not supported. Fix: write data-on-${type}="methodName" and read extra data in the method from hit.el.dataset (data-* attributes).`, n);
+				else if (RESERVED_NAMES.has(method)) report("reserved-handler", "error", `${at.name}="${method}" would override a built-in DOM method or a ts-dom member of the same name on the element. Fix: rename the method (for example remove -> removeItem, click -> onClick).`, n);
+				else {
+					a.events.add(method);
+					mark(`event:${method}`, n);
+					a.eventSites.push({
+						event: type,
+						method,
+						tag,
+						attrs: n.attrs.map((x) => x.name)
+					});
+					handlers.push(type);
+				}
+			}
+			if (isCustom) a.customUses.push({
+				tag,
+				attrs: n.attrs.map((x) => x.name),
+				events: handlers,
+				...locOf(n)
+			});
+			const ref = attr$1(n, "data-ref");
+			if (ref !== void 0) {
+				if (!ref.trim()) report("empty-ref", "error", "data-ref is empty. Fix: give it a name, e.g. data-ref=\"title\".", n);
+				else if (scope.refs.has(ref)) report("duplicate-ref", "error", `data-ref="${ref}" is used more than once in the same scope, so this.refs.${ref} would be ambiguous. Fix: use a different name (names inside different data-each templates may repeat).`, n);
+				else {
+					scope.refs.set(ref, n.namespaceURI === HTML_NS ? `El<${JSON.stringify(tag)}>` : "SVGElement");
+					mark(listName ? `ref:${listName}/${ref}` : `ref:${ref}`, n);
+				}
+			}
+			const cond = attr$1(n, "data-if");
+			if (cond !== void 0) {
+				if (!cond.trim()) report("empty-if", "error", "data-if is empty. Fix: give it a name, e.g. data-if=\"open\".", n);
+				else if (itemRoot) report("if-on-item-root", "error", `data-if="${cond}" is on the root element of data-each="${listName}". Removing the root would break the list ordering. Fix: wrap the content in one more element and put data-if on the inner element.`, n);
+				else {
+					scope.ifs.add(cond);
+					mark(listName ? `if:${listName}/${cond}` : `if:${cond}`, n);
+				}
+			}
+			if (tag === "slot" && listName) report("slot-in-list", "error", `<slot> is inside data-each="${listName}". The list repeats the slot but the user provides its content only once. Fix: move the slot outside the list, or fill each item from TypeScript in the update callback.`, n);
+			if (tag === "style" && n.namespaceURI === HTML_NS && !top) report("style-not-top-level", "error", "<style> must be a top-level element of the template (not nested in another element, <template data-each> or a data-if element). Fix: move it to the first level of the HTML file.", n);
+			if (tag === "slot") {
+				const name = attr$1(n, "name") ?? "";
+				if (a.slots.has(name)) report("duplicate-slot", "warning", `slot "${name}" appears more than once; only one of them can receive the content. Fix: give each slot a distinct name.`, n);
+				a.slots.add(name);
+			}
+			const each = attr$1(n, "data-each");
+			if (each !== void 0 && tag !== "template") report("each-not-template", "error", `data-each is on <${tag}> but it only works on <template>. Fix: write <template data-each="${each || "items"}"><li>...</li></template>.`, n);
+			if (tag === "template" && each !== void 0) {
+				if (!each.trim()) report("empty-each", "error", "data-each is empty. Fix: give it a name, e.g. <template data-each=\"items\">.", n);
+				else if (listName) report("nested-each", "error", `data-each="${each}" is nested inside data-each="${listName}". Lists cannot be nested; an inner list belongs to its own template. Fix: move the inner list and its item markup into a separate .html file (a child component with its own data-each) and use that component's tag inside the outer item.`, n);
+				else if (a.lists.has(each)) report("duplicate-each", "error", `data-each="${each}" is used more than once, so this.lists.${each} would be ambiguous. Fix: use a different name.`, n);
+				else {
+					const items = n.content.childNodes.filter((c) => isEl$1(c) || c.nodeName === "#text" && c.value.trim());
+					if (items.length !== 1 || !isEl$1(items[0])) report("each-root-count", "error", `data-each="${each}" must contain exactly one root element (found ${items.length} root nodes). Fix: wrap the item content in a single element such as <li>.`, n);
+					const s = newScope();
+					a.lists.set(each, s);
+					mark(`each:${each}`, n);
+					walk(n, s, each, true, false);
+				}
+				continue;
+			}
+			walk(n, scope, listName, false, false);
+		}
+	}
+	walk(root, a.scope, null, false, true);
+	return a;
+}
+const q = (s) => JSON.stringify(s);
+const union = (xs) => {
+	const arr = [...new Set(xs)];
+	return arr.length ? arr.map(q).join(" | ") : "never";
+};
+const obj = (m) => `{ ${[...m].map(([n, t]) => `${q(n)}: ${t}`).join("; ")} }`;
+function globToRegExp(glob) {
+	let re = "";
+	for (let i = 0; i < glob.length; i++) {
+		const c = glob[i];
+		if (c === "*" && glob[i + 1] === "*") {
+			const slash = glob[i + 2] === "/";
+			re += slash ? "(?:.*/)?" : ".*";
+			i += slash ? 2 : 1;
+		} else if (c === "*") re += "[^/]*";
+		else if (c === "?") re += "[^/]";
+		else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^${re}$`);
+}
+/** Whether `file` (under `dir`) is one of the templates `options.include` / `options.exclude` select. */
+function isSelected(dir, file, options = {}) {
+	const rel = relative(dir, file).split(sep).join("/");
+	const hit = (globs) => globs.some((g) => globToRegExp(g).test(rel));
+	return (!options.include?.length || hit(options.include)) && !(options.exclude?.length && hit(options.exclude));
+}
+const KEEPS_WHITESPACE = /* @__PURE__ */ new Set([
+	"pre",
+	"textarea",
+	"style",
+	"script"
+]);
+function toNodes(parent, collapse = false) {
+	const children = "content" in parent && parent.nodeName === "template" ? parent.content.childNodes : parent.childNodes;
+	const out = [];
+	for (const n of children) if (n.nodeName === "#text") {
+		const value = n.value;
+		if (!collapse) out.push(value);
+		else if (!(/^\s*$/.test(value) && value.includes("\n"))) out.push(value.replace(/\s+/g, " "));
+	} else if (n.nodeName === "#comment") out.push(["#comment", n.data]);
+	else if (isEl$1(n)) {
+		const attrs = Object.fromEntries(n.attrs.map((a) => [a.name, a.value]));
+		const inner = toNodes(n, collapse && !KEEPS_WHITESPACE.has(n.tagName));
+		out.push(n.namespaceURI === HTML_NS ? [
+			n.tagName,
+			attrs,
+			inner
+		] : [
+			n.tagName,
+			attrs,
+			inner,
+			n.namespaceURI
+		]);
+	}
+	return out;
+}
+/**
+* Generate `x.html.ts`: a real TypeScript module that contains both the template markup (as DOM-building data, never parsed from a string at runtime) and its types.
+* tsc (or any bundler) can compile it directly: no plugin and no allowArbitraryExtensions needed.
+* Consumers import it as `import tpl from "./x.html.js"` (TypeScript maps it to x.html.ts).
+*/
+function generateModule(html, options = {}, imports = []) {
+	const runtime = options.runtime ?? "@nativele/ts-dom";
+	const a = analyze(html);
+	const lists = [...a.lists].map(([n, s]) => `${q(n)}: { refs: ${obj(s.refs)}; text: ${union(s.text)}; ifs: ${union(s.ifs)} }`).join("; ");
+	const type = `{
+  refs: ${obj(a.scope.refs)};
+  lists: { ${lists} };
+  ifs: ${union(a.scope.ifs)};
+  slots: ${union(a.slots)};
+  text: ${union(a.scope.text)};
+  events: ${union(a.events)};
+}`;
+	const needsEl = type.includes("El<");
+	return `// Generated by ts-dom. Do not edit.
+${imports.map((i) => `import ${q(i)};\n`).join("")}import { template } from ${q(runtime)};
+${needsEl ? `import type { El } from ${q(runtime)};\n` : ""}export default template<${type}>(${JSON.stringify(toNodes(parseFragment(html), options.whitespace === "collapse"))});
+`;
+}
+/** x.html → x.html.ts */
+function modulePathFor(htmlPath) {
+	return `${htmlPath}.ts`;
+}
+/** A full page (starting with a doctype or <html>) is a page entry, not a template. */
+function isFullPage(html) {
+	return /^\s*(<!--[\s\S]*?-->\s*)*<(!doctype|html)\b/i.test(html);
+}
+/** `file:line:col severity [rule] message` — one line per diagnostic. */
+function formatDiagnostics(file, ds) {
+	return ds.map((d) => `${file}:${d.line}:${d.col} ${d.severity} [${d.rule}] ${d.message}`).join("\n");
+}
+var CodegenError = class extends Error {};
+/**
+* Generate a single `x.html.ts`; throws CodegenError (and writes nothing) when there are error diagnostics.
+* `defs` is either a directory to scan or a precomputed scan result: custom elements used by the template
+* are imported automatically from the modules that define them.
+*/
+function generateFile(htmlPath, options = {}, defs) {
+	const html = readFileSync(htmlPath, "utf8");
+	const analysis = analyze(html);
+	const errors = analysis.diagnostics.filter((d) => d.severity === "error");
+	if (errors.length) throw new CodegenError(formatDiagnostics(htmlPath, errors));
+	const known = typeof defs === "string" ? scanDefines(defs) : defs ?? [];
+	const here = dirname(htmlPath);
+	const imports = [...new Set(known.filter((d) => analysis.customTags.has(d.tag)).map((d) => relImport(here, d.file)))].sort();
+	const out = modulePathFor(htmlPath);
+	const next = generateModule(html, options, imports);
+	let prev = "";
+	try {
+		prev = readFileSync(out, "utf8");
+	} catch {}
+	if (prev !== next) writeFileSync(out, next);
+	return out;
+}
+function listHtml(dir) {
+	const out = [];
+	for (const name of readdirSync(dir)) {
+		if (name === "node_modules") continue;
+		const full = join(dir, name);
+		if (statSync(full).isDirectory()) out.push(...listHtml(full));
+		else if (name.endsWith(".html") && !isFullPage(readFileSync(full, "utf8"))) out.push(full);
+	}
+	return out;
+}
+const TAGS_FILE = "ts-dom-tags.ts";
+const TAGS_HEADER = "// Generated by ts-dom. Do not edit.";
+function listTs(dir) {
+	const out = [];
+	for (const name of readdirSync(dir)) {
+		if (name === "node_modules" || name === "dist") continue;
+		const full = join(dir, name);
+		if (statSync(full).isDirectory()) out.push(...listTs(full));
+		else if (name.endsWith(".ts") && !name.endsWith(".d.ts") && !name.endsWith(".html.ts") && name !== TAGS_FILE) out.push(full);
+	}
+	return out;
+}
+/** Ranges [start, end) of the string literals, template literals and comments of a piece of TypeScript source. */
+function nonCodeRanges(code) {
+	const out = [];
+	for (let i = 0; i < code.length; i++) {
+		const c = code[i];
+		if (c === "\"" || c === "'" || c === "`") {
+			const start = i;
+			for (i++; i < code.length && code[i] !== c; i++) if (code[i] === "\\") i++;
+			out.push([start, i + 1]);
+		} else if (c === "/" && code[i + 1] === "/") {
+			const end = code.indexOf("\n", i);
+			out.push([i, end < 0 ? code.length : end]);
+			i = end < 0 ? code.length : end;
+		} else if (c === "/" && code[i + 1] === "*") {
+			const end = code.indexOf("*/", i + 2);
+			out.push([i, end < 0 ? code.length : end + 2]);
+			i = end < 0 ? code.length : end + 1;
+		}
+	}
+	return out;
+}
+/**
+* Scan a directory for every `define("my-tag", MyClass)` call.
+* Calls that only appear inside a string or a comment (for example sample code in a test or in documentation) are ignored.
+*/
+function scanDefines(dir) {
+	const defs = [];
+	const re = /\bdefine\(\s*(["'])([a-z][a-z0-9]*(?:-[a-z0-9]+)+)\1\s*,\s*([A-Za-z_$][\w$]*)\s*\)/g;
+	for (const file of listTs(dir)) {
+		const code = readFileSync(file, "utf8");
+		const skip = nonCodeRanges(code);
+		const inCode = (pos) => !skip.some(([a, b]) => pos >= a && pos < b);
+		const has = (re) => [...code.matchAll(re)].some((m) => inCode(m.index));
+		for (const m of code.matchAll(re)) {
+			if (!inCode(m.index)) continue;
+			const [, , tag, className] = m;
+			const named = has(new RegExp(`export\\s+class\\s+${className}\\b`, "g")) || has(new RegExp(`export\\s*\\{[^}]*\\b${className}\\b[^}]*\\}`, "g"));
+			const isDefault = has(new RegExp(`export\\s+default\\s+class\\s+${className}\\b`, "g"));
+			defs.push({
+				tag,
+				className,
+				file,
+				exported: named || isDefault,
+				isDefault
+			});
+		}
+	}
+	return defs.sort((a, b) => a.tag.localeCompare(b.tag));
+}
+const relImport = (fromDir, file) => {
+	const r = relative(fromDir, file).split(sep).join("/").replace(/\.ts$/, ".js");
+	return r.startsWith(".") ? r : `./${r}`;
+};
+/** Scan `define("my-tag", MyClass)` calls and return the components a type can be generated for (the class must be exported). */
+function scanTags(dir) {
+	return scanDefines(dir).filter((d) => d.exported).map((d) => ({
+		tag: d.tag,
+		className: d.className,
+		from: relImport(dir, d.file),
+		isDefault: d.isDefault
+	}));
+}
+/**
+* Generate `ts-dom-tags.ts`: register every `define("tag", Class)` component in HTMLElementTagNameMap
+* so that `refs.x` for `<tag data-ref="x">` in a template is fully typed (props, methods and emitted events).
+*/
+function generateTags(dir) {
+	const defs = scanTags(dir);
+	const out = join(dir, TAGS_FILE);
+	const seen = /* @__PURE__ */ new Map();
+	for (const d of defs) {
+		const prev = seen.get(d.tag);
+		if (prev && (prev.from !== d.from || prev.className !== d.className)) throw new CodegenError(`${dir}: [duplicate-define] the tag <${d.tag}> is defined more than once (${prev.from} and ${d.from}). Fix: each custom element name can be defined only once; rename one of them.`);
+		seen.set(d.tag, d);
+	}
+	if (!defs.length) {
+		if (existsSync(out) && readFileSync(out, "utf8").startsWith(TAGS_HEADER)) unlinkSync(out);
+		return null;
+	}
+	const alias = (d) => `Tag${[...seen.keys()].indexOf(d.tag)}`;
+	const imports = [...seen.values()].map((d) => `import type { ${d.isDefault ? "default" : d.className} as ${alias(d)} } from ${JSON.stringify(d.from)};`);
+	const entries = [...seen.values()].map((d) => `    ${JSON.stringify(d.tag)}: ${alias(d)};`);
+	const next = `${TAGS_HEADER}\n${imports.join("\n")}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n${entries.join("\n")}\n  }\n}\n\nexport {};\n`;
+	let prev = "";
+	try {
+		prev = readFileSync(out, "utf8");
+	} catch {}
+	if (prev !== next) writeFileSync(out, next);
+	return out;
+}
+/** Generate every `x.html.ts` (and the tag map) under a directory; collects all errors and throws them together. */
+function generateAll(dir, options = {}) {
+	const written = [];
+	const errors = [];
+	const defs = scanDefines(dir);
+	for (const f of listHtml(dir)) {
+		if (!isSelected(dir, f, options)) continue;
+		try {
+			written.push(generateFile(f, options, defs));
+		} catch (e) {
+			if (e instanceof CodegenError) errors.push(e.message);
+			else throw e;
+		}
+	}
+	try {
+		const tags = generateTags(dir);
+		if (tags) written.push(tags);
+	} catch (e) {
+		if (e instanceof CodegenError) errors.push(e.message);
+		else throw e;
+	}
+	if (errors.length) throw new CodegenError(errors.join("\n"));
+	return written;
+}
+/** Watch .html (and define() calls in .ts) under the directories and regenerate; returns a stop function. Errors go to onError and never stop the watcher. */
+function watchAll(dirs, opts = {}) {
+	const timers = /* @__PURE__ */ new Map();
+	const watchers = dirs.map((dir) => watch(dir, { recursive: true }, (_event, name) => {
+		if (!name || name.includes("node_modules")) return;
+		if (name.endsWith(".ts") && !name.endsWith(".html.ts") && !name.endsWith(".d.ts") && !name.endsWith(TAGS_FILE)) {
+			const key = `${dir}:tags`;
+			clearTimeout(timers.get(key));
+			timers.set(key, setTimeout(() => {
+				try {
+					for (const f of generateAll(dir, opts)) opts.onGenerate?.(f);
+				} catch (e) {
+					if (e instanceof CodegenError) opts.onError?.(e.message);
+					else throw e;
+				}
+			}, 100));
+			return;
+		}
+		if (!name.endsWith(".html")) return;
+		const file = join(dir, name);
+		clearTimeout(timers.get(file));
+		timers.set(file, setTimeout(() => {
+			try {
+				if (!existsSync(file) || !isSelected(dir, file, opts) || isFullPage(readFileSync(file, "utf8"))) return;
+				opts.onGenerate?.(generateFile(file, opts, dir));
+			} catch (e) {
+				if (e instanceof CodegenError) opts.onError?.(e.message);
+				else throw e;
+			}
+		}, 50));
+	}));
+	return () => {
+		for (const w of watchers) w.close();
+		for (const t of timers.values()) clearTimeout(t);
+	};
+}
+// src/lib/a11y.ts
+/** Every check, by rule id (usable in `ignore`). The text is the default message: what is wrong and how to fix it. */
+const A11Y_RULES = {
+	"img-alt": "<img> has no alt attribute, so screen readers cannot describe it. Fix: add alt=\"description\", or alt=\"\" if the image is purely decorative.",
+	"control-name": "This control has no accessible name. Fix: add text, a {{ hole }}, a <slot>, aria-label or aria-labelledby.",
+	"form-label": "This form control has no label. Fix: wrap it in a <label>, add <label for=\"id\">, or add aria-label.",
+	"iframe-title": "<iframe> has no title. Fix: add a title attribute (or aria-label) that describes its content.",
+	"dialog-name": "<dialog> has no accessible name. Fix: add aria-label or aria-labelledby.",
+	"heading-empty": "This heading is empty. Fix: add text or a {{ hole }}, or remove the heading element.",
+	"aria-role": "This role is not a valid ARIA role. Fix: use a role from the WAI-ARIA specification (check the spelling).",
+	"aria-attr": "This is not a valid ARIA attribute. Fix: check the spelling against the WAI-ARIA attribute list.",
+	"role-tabindex": "An element with an interactive role must be focusable. Fix: add tabindex=\"0\" (and handle keyboard events), or use a native element such as <button>.",
+	"tabindex-positive": "A positive tabindex disturbs the natural focus order. Fix: use tabindex=\"0\" or \"-1\".",
+	"hidden-focusable": "A focusable element has aria-hidden=\"true\", so keyboard users can reach something screen readers cannot see. Fix: remove aria-hidden, or make the element non-focusable.",
+	"label-for": "<label for> points to an id that does not exist in this template. Fix: add the matching id to the control, or wrap the control in the label instead.",
+	"id-in-list": "An id inside a data-each template is repeated for every item. Fix: use data-ref or a class instead of an id.",
+	"duplicate-id": "This id is used more than once in the template. Fix: make every id unique.",
+	"aria-idref": "This ARIA attribute refers to an id that does not exist in this template. Fix: add the id, or ignore this rule if it refers to an element outside the component.",
+	"heading-order": "Heading levels are skipped. Fix: do not jump levels (for example h1 straight to h3); use the next level down.",
+	"table-header": "<table> has no <th> header cells. Fix: add <th> cells, or set role=\"presentation\" if the table is only used for layout.",
+	"list-structure": "Invalid list structure. Fix: <ul>/<ol> may only contain <li>, and <li> must be inside <ul>, <ol> or <menu>.",
+	"landmark-label": "There are several landmarks of the same kind. Fix: give each <nav> / <aside> a distinct aria-label.",
+	"redundant-role": "The role repeats the element's native role. Fix: remove the role attribute.",
+	"click-semantics": "data-on-click is on an element that is not ts-domy operable, so keyboard and assistive technology users cannot use it. Fix: use <button> or <a href>, or add an interactive role plus tabindex and keyboard handling."
+};
+const ROLES = new Set(`alert alertdialog application article banner blockquote button caption cell checkbox code columnheader combobox complementary contentinfo definition deletion dialog directory document emphasis feed figure form generic grid gridcell group heading img insertion link list listbox listitem log main mark marquee math menu menubar menuitem menuitemcheckbox menuitemradio meter navigation none note option paragraph presentation progressbar radio radiogroup region row rowgroup rowheader scrollbar search searchbox separator slider spinbutton status strong subscript superscript switch tab table tablist tabpanel term textbox time timer toolbar tooltip tree treegrid treeitem`.split(" "));
+const ARIA_ATTRS = new Set(`activedescendant atomic autocomplete braillelabel brailleroledescription busy checked colcount colindex colindextext colspan controls current describedby description details disabled dropeffect errormessage expanded flowto grabbed haspopup hidden invalid keyshortcuts label labelledby level live modal multiline multiselectable orientation owns placeholder posinset pressed readonly relevant required roledescription rowcount rowindex rowindextext rowspan selected setsize sort valuemax valuemin valuenow valuetext`.split(" ").map((n) => `aria-${n}`));
+const INTERACTIVE_ROLES = new Set("button link checkbox switch tab menuitem menuitemcheckbox menuitemradio option radio textbox combobox slider spinbutton searchbox".split(" "));
+const IDREF_ATTRS = [
+	"aria-labelledby",
+	"aria-describedby",
+	"aria-controls",
+	"aria-owns",
+	"aria-flowto",
+	"aria-details",
+	"aria-errormessage",
+	"aria-activedescendant"
+];
+const IMPLICIT_ROLE = {
+	button: "button",
+	nav: "navigation",
+	ul: "list",
+	ol: "list",
+	li: "listitem",
+	img: "img",
+	main: "main",
+	aside: "complementary",
+	form: "form",
+	table: "table",
+	article: "article",
+	hr: "separator",
+	dialog: "dialog",
+	h1: "heading",
+	h2: "heading",
+	h3: "heading",
+	h4: "heading",
+	h5: "heading",
+	h6: "heading"
+};
+const NO_LABEL_INPUT = /* @__PURE__ */ new Set([
+	"hidden",
+	"submit",
+	"reset",
+	"button",
+	"image"
+]);
+const isEl = (n) => "tagName" in n;
+const attr = (el, name) => el.attrs.find((a) => a.name === name)?.value;
+const has = (el, name) => el.attrs.some((a) => a.name === name);
+const nonEmpty = (v) => v !== void 0 && v.trim() !== "";
+const kids = (el) => el.tagName === "template" ? el.content.childNodes : el.childNodes;
+function focusable(el) {
+	const t = el.tagName;
+	if (t === "button" || t === "select" || t === "textarea" || t === "summary") return true;
+	if (t === "a") return has(el, "href");
+	if (t === "input") return attr(el, "type")?.toLowerCase() !== "hidden";
+	return false;
+}
+/** Whether an element may contain readable content: text, holes, slots, TypeScript-managed elements, named descendants. */
+function hasContent(el) {
+	for (const c of kids(el)) if (c.nodeName === "#text") {
+		if (c.value.trim()) return true;
+	} else if (isEl(c)) {
+		if (c.tagName === "style" || c.tagName === "script") continue;
+		if (c.tagName === "slot" || has(c, "data-ref")) return true;
+		if (nonEmpty(attr(c, "aria-label")) || nonEmpty(attr(c, "title"))) return true;
+		if (c.tagName === "img" && nonEmpty(attr(c, "alt"))) return true;
+		if (hasContent(c)) return true;
+	}
+	return false;
+}
+const named = (el) => nonEmpty(attr(el, "aria-label")) || nonEmpty(attr(el, "aria-labelledby")) || nonEmpty(attr(el, "title"));
+/** Check a template for ARIA and basic accessibility problems. Returns warnings and never throws. */
+function checkA11y(html, ignore = []) {
+	const root = parseFragment(html, { sourceCodeLocationInfo: true });
+	const out = [];
+	const skip = new Set(ignore);
+	const ids = /* @__PURE__ */ new Map();
+	const labelFor = [];
+	const all = [];
+	(function collect(parent, domParent, inList, inLabel) {
+		for (const n of parent.childNodes) {
+			if (!isEl(n)) continue;
+			const list = inList || n.tagName === "template" && has(n, "data-each");
+			const label = inLabel || n.tagName === "label";
+			all.push({
+				el: n,
+				parent: domParent,
+				inList,
+				inLabel
+			});
+			const id = attr(n, "id");
+			if (nonEmpty(id)) ids.set(id, (ids.get(id) ?? 0) + 1);
+			if (n.tagName === "label" && nonEmpty(attr(n, "for"))) labelFor.push({
+				id: attr(n, "for"),
+				el: n
+			});
+			if (n.tagName === "template") collect(n.content, domParent, list, label);
+			else collect(n, n, list, label);
+		}
+	})(root, null, false, false);
+	const report = (rule, el, detail) => {
+		if (skip.has(rule)) return;
+		const loc = el.sourceCodeLocation;
+		out.push({
+			rule,
+			severity: "warning",
+			message: detail ?? A11Y_RULES[rule],
+			line: loc?.startLine ?? 1,
+			col: loc?.startCol ?? 1
+		});
+	};
+	let lastHeading = 0;
+	const landmarks = all.filter((x) => (x.el.tagName === "nav" || x.el.tagName === "aside") && attr(x.el, "role") !== "presentation");
+	const descendants = (el) => kids(el).flatMap((c) => isEl(c) ? [c, ...descendants(c)] : []);
+	for (const { el, parent, inList, inLabel } of all) {
+		const tag = el.tagName;
+		const managed = has(el, "data-ref");
+		const role = attr(el, "role")?.trim().split(/\s+/)[0];
+		if (tag === "img" && !has(el, "alt") && !managed && role !== "presentation" && role !== "none") report("img-alt", el);
+		if ((tag === "button" || tag === "summary" || tag === "a" && has(el, "href")) && !managed && !named(el) && !hasContent(el)) report("control-name", el, `<${tag}> has no accessible name. Fix: add text, a {{ hole }}, a <slot>, aria-label or aria-labelledby.`);
+		if ((tag === "select" || tag === "textarea" || tag === "input" && !NO_LABEL_INPUT.has((attr(el, "type") ?? "text").toLowerCase())) && !managed && !named(el) && !inLabel) {
+			const id = attr(el, "id");
+			if (!(nonEmpty(id) && labelFor.some((l) => l.id === id))) report("form-label", el, `<${tag}> has no label. Fix: wrap it in a <label>, add <label for="id"> with a matching id, or add aria-label.`);
+		}
+		if (tag === "iframe" && !managed && !named(el)) report("iframe-title", el);
+		if (tag === "dialog" && !managed && !nonEmpty(attr(el, "aria-label")) && !nonEmpty(attr(el, "aria-labelledby"))) report("dialog-name", el);
+		if (/^h[1-6]$/.test(tag) && !managed && !nonEmpty(attr(el, "aria-label")) && !hasContent(el)) report("heading-empty", el, `<${tag}> is empty. Fix: add text or a {{ hole }}, or remove the heading element.`);
+		if (role !== void 0 && !ROLES.has(role) && !role.startsWith("doc-") && !role.startsWith("graphics-")) report("aria-role", el, `role="${role}" is not a valid ARIA role. Fix: check the spelling against the WAI-ARIA roles.`);
+		for (const a of el.attrs) if (a.name.startsWith("aria-") && !ARIA_ATTRS.has(a.name)) report("aria-attr", el, `${a.name} is not a valid ARIA attribute. Fix: check the spelling against the WAI-ARIA attributes.`);
+		const tabindex = attr(el, "tabindex");
+		if (role && INTERACTIVE_ROLES.has(role) && !focusable(el) && tabindex === void 0 && !managed) report("role-tabindex", el, `<${tag} role="${role}"> is not ts-domy focusable. Fix: add tabindex="0" and handle keyboard events, or use a native element such as <button>.`);
+		if (tabindex !== void 0 && Number(tabindex) > 0) report("tabindex-positive", el, `tabindex="${tabindex}" disturbs the natural focus order. Fix: use tabindex="0" or "-1".`);
+		if (attr(el, "aria-hidden") === "true" && (focusable(el) || tabindex !== void 0 && Number(tabindex) >= 0)) report("hidden-focusable", el);
+		if (has(el, "data-on-click") && !focusable(el) && tag !== "label" && !(role && INTERACTIVE_ROLES.has(role) && tabindex !== void 0)) report("click-semantics", el, `data-on-click is on <${tag}>, which is not ts-domy operable, so keyboard and assistive technology users cannot use it. Fix: use <button> or <a href>, or add an interactive role plus tabindex and keyboard handling.`);
+		if (/^h[1-6]$/.test(tag)) {
+			const level = Number(tag[1]);
+			if (lastHeading && level > lastHeading + 1) report("heading-order", el, `<${tag}> skips a heading level (the previous heading is h${lastHeading}). Fix: use h${lastHeading + 1} here, or restructure the headings.`);
+			lastHeading = level;
+		}
+		if (tag === "table" && !managed && role !== "presentation" && role !== "none" && !descendants(el).some((d) => d.tagName === "th")) report("table-header", el);
+		if (tag === "ul" || tag === "ol" || tag === "menu") for (const c of kids(el)) {
+			if (!isEl(c) || c.tagName === "slot" || c.tagName === "script") continue;
+			if (c.tagName === "template") {
+				if (!has(c, "data-each")) continue;
+				for (const item of c.content.childNodes) if (isEl(item) && item.tagName !== "li") report("list-structure", item, `The root element of a data-each item inside <${tag}> must be <li>, found <${item.tagName}>. Fix: use <li> as the item root.`);
+			} else if (c.tagName !== "li") report("list-structure", c, `<${tag}> may only contain <li> children, found <${c.tagName}>. Fix: wrap the content in <li>.`);
+		}
+		if (tag === "li" && parent && ![
+			"ul",
+			"ol",
+			"menu",
+			"slot"
+		].includes(parent.tagName) && !["list", "menu"].includes(attr(parent, "role") ?? "")) report("list-structure", el, `<li> must be inside <ul>, <ol> or <menu>, found inside <${parent.tagName}>. Fix: change the parent element, or use a different element instead of <li>.`);
+		if ((tag === "nav" || tag === "aside") && landmarks.length > 1 && landmarks.filter((l) => l.el.tagName === tag).length > 1 && !named(el) && !managed) report("landmark-label", el, `There are several <${tag}> landmarks in this template. Fix: give each one a distinct aria-label.`);
+		if (role && (IMPLICIT_ROLE[tag] === role || tag === "a" && has(el, "href") && role === "link")) report("redundant-role", el, `<${tag}> already has the role "${role}". Fix: remove the redundant role attribute.`);
+		if (!managed) for (const name of IDREF_ATTRS) {
+			const v = attr(el, name);
+			if (!nonEmpty(v)) continue;
+			for (const ref of v.trim().split(/\s+/)) if (!ids.has(ref)) report("aria-idref", el, `${name}="${ref}" refers to an id that does not exist in this template. Fix: add the id here, or add "aria-idref" to the ignore list if it points to an element outside the component.`);
+		}
+		const id = attr(el, "id");
+		if (nonEmpty(id)) {
+			if (inList) report("id-in-list", el, `id="${id}" is inside a data-each template and would repeat for every item. Fix: use data-ref or a class instead.`);
+			if ((ids.get(id) ?? 0) > 1) report("duplicate-id", el, `id="${id}" is used more than once in this template. Fix: make every id unique.`);
+		}
+	}
+	for (const { id, el } of labelFor) if (!ids.has(id)) report("label-for", el, `<label for="${id}"> points to an id that does not exist in this template. Fix: add id="${id}" to the control, or wrap the control in the label.`);
+	return out.sort((a, b) => a.line - b.line || a.col - b.col);
+}
+export { analyze as a, generateFile as c, listHtml as d, scanDefines as f, CodegenError as i, isFullPage as l, checkA11y as n, formatDiagnostics as o, watchAll as p, CODEGEN_RULES as r, generateAll as s, A11Y_RULES as t, isSelected as u };

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}