@nativele/ts-dom 0.3.0 → 0.4.6

package/dist/{a11y-CeZcA10z.mjs → a11y-wWL9rie7.mjs}

@@ -21,6 +21,9 @@ const CODEGEN_RULES = {
 	"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-binding-incomplete": "data-key and data-prop go together on a data-each template",
+	"invalid-each-binding": "data-key and data-prop must each be a single identifier",
+	"each-binding-root": "with data-key and data-prop the item must be one custom element",
 	"each-root-count": "a data-each template needs exactly one root element",
 	"document-tag": "<html>, <head> and <body> cannot be in a template (the browser drops them from fragments)",
 	"forbidden-tag": "<script> cannot be in a template (it would run code)",
@@ -28,6 +31,17 @@ const CODEGEN_RULES = {
 	"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 RESERVED_ELEMENT_NAMES = /* @__PURE__ */ new Set([
+	"annotation-xml",
+	"color-profile",
+	"font-face",
+	"font-face-src",
+	"font-face-uri",
+	"font-face-format",
+	"font-face-name",
+	"missing-glyph"
+]);
+const isCustomElementName = (tag) => /^[a-z][a-z0-9._]*-[a-z0-9._-]*$/.test(tag) && !RESERVED_ELEMENT_NAMES.has(tag);
 const URL_ATTRS = /^(href|src|action|formaction|xlink:href)$/i;
 const HTML_NS = "http://www.w3.org/1999/xhtml";
 const newScope = () => ({
@@ -52,6 +66,7 @@ function analyze(html) {
 		scope: newScope(),
 		lists: /* @__PURE__ */ new Map(),
 		slots: /* @__PURE__ */ new Set(),
+		boundLists: /* @__PURE__ */ new Map(),
 		events: /* @__PURE__ */ new Set(),
 		eventSites: [],
 		customTags: /* @__PURE__ */ new Set(),
@@ -169,6 +184,21 @@ function analyze(html) {
 				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 key = attr$1(n, "data-key");
+					const prop = attr$1(n, "data-prop");
+					if (key === void 0 !== (prop === void 0)) report("each-binding-incomplete", "error", `data-each="${each}" has ${key === void 0 ? "data-prop" : "data-key"} but not ${key === void 0 ? "data-key" : "data-prop"}. Fix: write both, e.g. <template data-each="${each}" data-key="id" data-prop="item">, or neither to fill the items yourself with replace().`, n);
+					else if (key !== void 0 && prop !== void 0) {
+						if (!IDENT.test(key.trim()) || !IDENT.test(prop.trim())) report("invalid-each-binding", "error", `data-key="${key}" and data-prop="${prop}" must each be a single identifier: the item field that identifies it, and the property of the item element that receives the item. Fix: write data-key="id" data-prop="item".`, n);
+						else if (items.length === 1 && isEl$1(items[0])) {
+							const root = items[0];
+							if (root.namespaceURI === HTML_NS && isCustomElementName(root.tagName)) a.boundLists.set(each, {
+								tag: root.tagName,
+								prop: prop.trim(),
+								key: key.trim()
+							});
+							else report("each-binding-root", "error", `data-each="${each}" has data-key and data-prop, so each item is one component that receives the item as a property, but its root is <${root.tagName}>. Fix: make the item a custom element such as <${each}-row></${each}-row> and put the item's markup in that component's own .html.`, n);
+						}
+					}
 					const s = newScope();
 					a.lists.set(each, s);
 					mark(`each:${each}`, n);
@@ -197,6 +227,14 @@ function rootElementType(html) {
 	const el = elements[0];
 	return el.namespaceURI === HTML_NS ? `El<${JSON.stringify(el.tagName)}>` : "SVGElement";
 }
+/** The whitespace mode an existing generated module was written with; "preserve" when there is none. */
+function recordedWhitespace(out) {
+	try {
+		return readFileSync(out, "utf8").split("\n", 3).includes(COLLAPSE_MARK) ? "collapse" : "preserve";
+	} catch {
+		return "preserve";
+	}
+}
 function globToRegExp(glob) {
 	let re = "";
 	for (let i = 0; i < glob.length; i++) {
@@ -252,10 +290,16 @@ function toNodes(parent, collapse = false) {
 * 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 = []) {
+function generateModule(html, options = {}, imports = [], defs = []) {
 	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 lists = [...a.lists].map(([n, s]) => {
+		const bound = a.boundLists.get(n);
+		const def = bound && defs.find((d) => d.tag === bound.tag);
+		const source = !def ? "external" : def.exported ? "local" : "unexported";
+		const item = bound ? `; item: { tag: ${q(bound.tag)}; prop: ${q(bound.prop)}; key: ${q(bound.key)}; source: ${q(source)} }` : "";
+		return `${q(n)}: { refs: ${obj(s.refs)}; text: ${union(s.text)}; ifs: ${union(s.ifs)}${item} }`;
+	}).join("; ");
 	const type = `{
   refs: ${obj(a.scope.refs)};
   lists: { ${lists} };
@@ -266,8 +310,9 @@ function generateModule(html, options = {}, imports = []) {
   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)};
+	const side = imports.map((i) => `import ${q(i)};\n`).join("");
+	return `// Generated by ts-dom. Do not edit.${options.whitespace === "collapse" ? `\n${COLLAPSE_MARK}` : ""}
+${side}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"))});
 `;
 }
@@ -284,21 +329,31 @@ 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) {
+/** What `generateFile` would write for a template, without writing it; throws CodegenError when the template has error diagnostics. */
+function renderFile(htmlPath, options = {}, defs) {
 	const html = readFileSync(htmlPath, "utf8");
+	if (options.whitespace === void 0) options = {
+		...options,
+		whitespace: recordedWhitespace(modulePathFor(htmlPath))
+	};
 	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);
+	return {
+		out: modulePathFor(htmlPath),
+		next: generateModule(html, options, imports, known)
+	};
+}
+/**
+* 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 { out, next } = renderFile(htmlPath, options, defs);
 	let prev = "";
 	try {
 		prev = readFileSync(out, "utf8");
@@ -309,7 +364,7 @@ function generateFile(htmlPath, options = {}, defs) {
 function listHtml(dir) {
 	const out = [];
 	for (const name of readdirSync(dir)) {
-		if (name === "node_modules") continue;
+		if (name === "node_modules" || name === "dist") 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);
@@ -318,6 +373,7 @@ function listHtml(dir) {
 }
 const TAGS_FILE = "ts-dom-tags.ts";
 const TAGS_HEADER = "// Generated by ts-dom. Do not edit.";
+const COLLAPSE_MARK = "// whitespace: collapse";
 function listTs(dir) {
 	const out = [];
 	for (const name of readdirSync(dir)) {
@@ -395,6 +451,20 @@ function scanTags(dir) {
 * so that `refs.x` for `<tag data-ref="x">` in a template is fully typed (props, methods and emitted events).
 */
 function generateTags(dir) {
+	const { out, next } = renderTags(dir);
+	if (next === null) {
+		if (existsSync(out) && readFileSync(out, "utf8").startsWith(TAGS_HEADER)) unlinkSync(out);
+		return null;
+	}
+	let prev = "";
+	try {
+		prev = readFileSync(out, "utf8");
+	} catch {}
+	if (prev !== next) writeFileSync(out, next);
+	return out;
+}
+/** What `generateTags` would write, without writing it; `next` is null when the directory defines no exported component. */
+function renderTags(dir) {
 	const defs = scanTags(dir);
 	const out = join(dir, TAGS_FILE);
 	const seen = /* @__PURE__ */ new Map();
@@ -403,19 +473,86 @@ function generateTags(dir) {
 		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;
-	}
+	if (!defs.length) return {
+		out,
+		next: 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 = "";
+	return {
+		out,
+		next: `${TAGS_HEADER}\n${imports.join("\n")}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n${entries.join("\n")}\n  }\n}\n\nexport {};\n`
+	};
+}
+/**
+* Everything `generateAll` would write for a directory, in memory: generated path to content, or null for a file that should not exist.
+* Templates with error diagnostics are left out and their messages returned in `errors`.
+*/
+function planGenerated(dir, options = {}) {
+	const files = /* @__PURE__ */ new Map();
+	const errors = [];
+	const defs = scanDefines(dir);
+	for (const f of listHtml(dir)) {
+		if (!isSelected(dir, f, options)) continue;
+		try {
+			const { out, next } = renderFile(f, options, defs);
+			files.set(out, next);
+		} catch (e) {
+			if (e instanceof CodegenError) errors.push(e.message);
+			else throw e;
+		}
+	}
 	try {
-		prev = readFileSync(out, "utf8");
-	} catch {}
-	if (prev !== next) writeFileSync(out, next);
+		const tags = renderTags(dir);
+		files.set(tags.out, tags.next);
+	} catch (e) {
+		if (e instanceof CodegenError) errors.push(e.message);
+		else throw e;
+	}
+	for (const f of listGenerated(dir)) if (!files.has(f) && !existsSync(f.slice(0, -3))) files.set(f, null);
+	return {
+		files,
+		errors
+	};
+}
+/** Generated files under `dir` that differ from what `ts-dom gen` would write now. */
+function staleGenerated(dir, options = {}) {
+	return checkGenerated(dir, options).stale;
+}
+/** `staleGenerated`, plus the errors that would make `ts-dom gen` fail (template diagnostics, a tag defined twice). */
+function checkGenerated(dir, options = {}) {
+	const plan = planGenerated(dir, options);
+	const out = [];
+	for (const [file, next] of plan.files) {
+		const prev = existsSync(file) ? readFileSync(file, "utf8") : null;
+		if (next === null) {
+			if (prev !== null && prev.startsWith(TAGS_HEADER)) out.push({
+				file,
+				reason: file.endsWith(".html.ts") ? "orphan" : "outdated"
+			});
+		} else if (prev === null) out.push({
+			file,
+			reason: "missing"
+		});
+		else if (prev !== next) out.push({
+			file,
+			reason: "outdated"
+		});
+	}
+	return {
+		stale: out.sort((a, b) => a.file.localeCompare(b.file)),
+		errors: plan.errors
+	};
+}
+function listGenerated(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(...listGenerated(full));
+		else if (name.endsWith(".html.ts") && readFileSync(full, "utf8").startsWith(TAGS_HEADER)) out.push(full);
+	}
 	return out;
 }
 /** Generate every `x.html.ts` (and the tag map) under a directory; collects all errors and throws them together. */
@@ -439,6 +576,7 @@ function generateAll(dir, options = {}) {
 		if (e instanceof CodegenError) errors.push(e.message);
 		else throw e;
 	}
+	for (const f of listGenerated(dir)) if (!existsSync(f.slice(0, -3))) unlinkSync(f);
 	if (errors.length) throw new CodegenError(errors.join("\n"));
 	return written;
 }
@@ -498,10 +636,10 @@ const A11Y_RULES = {
 	"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>.",
+	"list-structure": "Invalid list structure. Fix: <ul>/<ol> may only contain <li> (or a custom element with role=\"listitem\"), 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."
+	"click-semantics": "data-on-click is on an element that is not natively 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}`));
@@ -629,10 +767,10 @@ function checkA11y(html, ignore = []) {
 		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 (role && INTERACTIVE_ROLES.has(role) && !focusable(el) && tabindex === void 0 && !managed) report("role-tabindex", el, `<${tag} role="${role}"> is not natively 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 (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 natively 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.`);
@@ -643,8 +781,16 @@ function checkA11y(html, ignore = []) {
 			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>.`);
+				for (const item of c.content.childNodes) if (isEl(item)) listItemProblem(item, tag, "The root element of a data-each item");
+			} else listItemProblem(c, tag, `A child of <${tag}>`);
+		}
+		function listItemProblem(item, listTag, what) {
+			if (item.tagName === "li") return;
+			if (item.tagName.includes("-")) {
+				if (attr(item, "role") !== "listitem") report("list-structure", item, `${what} inside <${listTag}> is the component <${item.tagName}>, which has no list item role. Fix: add role="listitem" to <${item.tagName}>, or make its root an <li>.`);
+				return;
+			}
+			report("list-structure", item, `${what} inside <${listTag}> must be <li> or a custom element with role="listitem", found <${item.tagName}>. Fix: use <li> as the item root.`);
 		}
 		if (tag === "li" && parent && ![
 			"ul",
@@ -668,4 +814,4 @@ function checkA11y(html, ignore = []) {
 	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 };
+export { watchAll as _, analyze as a, generateAll as c, isSelected as d, listHtml as f, staleGenerated as g, scanDefines as h, CodegenError as i, generateFile as l, renderTags as m, checkA11y as n, checkGenerated as o, listTs as p, CODEGEN_RULES as r, formatDiagnostics as s, A11Y_RULES as t, isFullPage as u };