@nativele/ts-dom 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -10,6 +10,61 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 - Adding a lint rule is a minor change; lint rules are warnings or opt-in and do not count as breaking.
 - Before every release run `npm run verify:pack` (`publint` and `attw`), `tsc`, the unit tests, the browser tests, `npm run smoke` and `npm run smoke:no-bundler`; all of them run in `.github/workflows/ci.yml`.
 
+## 0.5.4
+
+The guides, the Skills and the tools agree with each other: wrong statements in the guides are fixed, facts the Skills repeated now live in the guides, and the tools report the traps the Skill trials hit instead of staying silent.
+
+### New checks
+
+- `ts-dom doctor` reports `typecheck-before-gen` (warning): a package.json script, with its `pre` script and the scripts it runs through `npm run` (or pnpm, yarn, bun), that runs `tsc`, `vue-tsc`, `svelte-check` or `ng build`/`serve`/`test` before any `ts-dom gen` or `ts-dom check` while `.gitignore` leaves out `*.html.ts`; on a clean checkout it fails with TS2307. A `tsc -p` whose config covers none of the scanned folders is skipped.
+- `ts-dom doctor` reports `framework-template` (error): an `.html` in a scanned folder that a TypeScript file names as an Angular `templateUrl`. The `invalid-hole` and `no-importer` hints now also say that the folder may not be meant to be scanned.
+- `formatter-whitespace` also reports generated files written with `preserve` while a package.json script or the Vite config asks for `--whitespace=collapse`, with the command to regenerate them.
+- `vite-plugin-missing` also reports a `vitest.config.*` that replaces the Vite config for Vitest without the `tsDom()` plugin and without importing `./vite.config`.
+
+### Fixes
+
+- The Vite plugin warns (`dir-not-found`) when a `tsDom({ dirs })` entry does not exist under Vite's `root`, instead of skipping it silently.
+- A generated `ts-dom-tags.ts` in a subfolder that is not itself scanned (left over after components moved) is an orphan: `gen` deletes it, and `gen --check`, `check --no-write` and `doctor` report it as `stale-generated`.
+- A `tsc` error located in a generated `x.html.ts` or `ts-dom-tags.ts` now says to run `ts-dom gen` or delete the leftover file, not to change the TypeScript there.
+- `ts-dom check` leaves out `tsc` errors inside the body of a class it already reported for a contract error (for example an implicit `any` on a `bind` callback's parameter next to a `{{ hole }}` that names nothing).
+- `ts-dom --help` lists `--include`, `--exclude` and `--whitespace` under `check` and `doctor`, which accept them.
+
+### Documentation
+
+- `docs/components.md` gains:
+  - Light DOM slots and children managed by a framework;
+  - when a Light or Shadow component builds its content;
+  - the `props` and `"~emits"` members that framework declarations use;
+  - `EmitEvent` with an undeclared name;
+  - `ReadableStore`.
+- Five framework Skills link to the slot section instead of repeating it.
+- Corrected:
+  - the import map in `docs/design.md`;
+  - the generated files being "already in `.gitignore`" (a project adds them itself);
+  - duplicate and misplaced reordering notes;
+  - `llms.txt` lists every guide.
+- The Skills agree on one build-script rule: a project whose type check is plain `tsc` runs `ts-dom check` before the bundler, and a framework type checker gets `ts-dom gen` in front. The README Skill tables show the right tiers.
+- `test/skills.test.ts` checks the README Skill tables against each Skill's tier, and every link and anchor in the READMEs, `llms.txt`, the guides and the Skills.
+- `docs/tooling.md`: the new checks; the bare specifier to map is `@nativele/ts-dom`; the Vite plugin generates when the build, the dev server or Vitest starts, never type-checks, prints rejected templates only in the terminal, and sends a full reload to every client; a run without `--whitespace` keeps each file's recorded mode; `check` runs `tsc` once per referenced project of a solution-style tsconfig.
+
+## 0.5.3
+
+How to lay out an app with several pages: a new architecture guide, an Official Skill that applies it, and a medium example app checked in CI. Building the example found a codegen bug with several scanned folders, fixed here.
+
+### Guide and Skill
+
+- New guide `docs/architecture.md`:
+  - feature folders with their components, stores and tests, and a shared folder whose components' interface is their props and events;
+  - pages as custom elements mounted by an external router: route params as props, leaving a page, lazy page modules;
+  - where state lives at each level, and the split between unit, real-browser and end-to-end tests;
+  - one scanned folder for the generated files, checks and tsconfig.
+- New `nativele-architecture` (Official): the procedure for starting a multi-page Nativele app or restructuring one into this layout. The recommended router uses the Navigation API and `URLPattern` with no dependency; universal-router is the alternative. It covers the abort check after a lazy `import()` and the test split.
+- Its example, a project tracker with lazy pages, shared components, feature and app-wide stores, unit, browser and end-to-end tests, runs in CI.
+
+### Fixes
+
+- When several folders are scanned (`ts-dom gen a b`, `ts-dom check a b`, `ts-dom doctor a b`, the Vite plugin's `dirs`), each folder was generated on its own, so a template in one folder that used a component defined in another got no import of it and the build silently left the component out, while the types still passed. The folders now share their `define()` calls: the template imports the child by its relative path, `gen --check` and `doctor` agree with what `gen` writes, and the Vite plugin keeps the imports across folders when a template is saved or a `define()` is added or removed. A tag defined with different classes in two scanned folders is now reported as `duplicate-define` at the second `define()` call.
+
 ## 0.5.2
 
 Skills for the libraries a Nativele app most often sits next to: state stores, testing, data fetching, form validation and Tailwind CSS. Each was accepted through agent trials, and the trials found two bugs in the library, fixed here.

package/README.md

@@ -63,10 +63,11 @@ npx ts-dom skills add nativele-core    # copy it into .claude/skills/ (when the
 | `nativele-core` | building components: the `ts-dom check` loop, templates, state, lists, data flow |
 | `nativele-react` | Nativele components in React 19: props, events, children and slots, lifecycle, TSX types |
 | `nativele-vue` | Nativele components in Vue 3: props, events, `v-model`, slots, `<KeepAlive>`, template types |
-| `nativele-svelte` | Nativele components in Svelte 5: props, events, slots, template types |
+| `nativele-svelte` | Nativele components in Svelte 5: props, events, slots, template types (Experimental) |
 | `nativele-angular` | Nativele components in Angular: bindings, change detection, the build, content projection (Experimental) |
+| `nativele-architecture` | app layout: feature folders, shared components and stores, pages mounted by a router, lazy pages, the test split |
 | `nativele-vite` | Nativele in a Vite app: the plugin and `root`, multi-page builds, hot updates |
-| `nativele-integration` | Nativele components in a framework without its own Skill (Preact, Solid, ...): properties, events, slots, lifecycle, template types (Experimental) |
+| `nativele-integration` | Nativele components in a framework without its own Skill (Preact, Solid, ...): properties, events, slots, lifecycle, template types |
 | `nativele-state-management` | where state lives; `createStore`, and Zustand, Redux Toolkit or nanostores through `bind` |
 | `nativele-testing` | component tests with Vitest, real-browser tests |
 | `nativele-tanstack-query` | data fetching with `@tanstack/query-core` (Experimental) |
@@ -228,6 +229,7 @@ The full guide is in English:
 - [Components and data flow: state, props, derive, events, composition, stores](https://github.com/Pixmi/nativele/blob/main/docs/components.md)
 - [Recipes: loading and error states, store data, filtered lists, dialogs, form validation](https://github.com/Pixmi/nativele/blob/main/docs/recipes.md)
 - [Lists: lists of components with `items =`, plain lists with `replace()`, moving items](https://github.com/Pixmi/nativele/blob/main/docs/lists.md)
+- [Architecture: feature folders, shared components and stores, pages mounted by a router, where state lives, testing strategy](https://github.com/Pixmi/nativele/blob/main/docs/architecture.md)
 - [Setup, checks and lint: installation, Vite, oxlint, `ts-dom check`, `ts-dom doctor`, accessibility](https://github.com/Pixmi/nativele/blob/main/docs/tooling.md)
 - [Performance: the large list benchmark](https://github.com/Pixmi/nativele/blob/main/docs/performance.md)
 - [Design: principles, deliberate decisions, limitations](https://github.com/Pixmi/nativele/blob/main/docs/design.md)

package/README.zh-TW.md

@@ -63,10 +63,11 @@ npx ts-dom skills add nativele-core    # 複製到 .claude/skills/（專案有 .
 | `nativele-core` | 開發元件：`ts-dom check` 循環、範本、state、清單、資料流 |
 | `nativele-react` | 在 React 19 中使用 Nativele 元件：props、事件、子元素與 slot、生命週期、TSX 型別 |
 | `nativele-vue` | 在 Vue 3 中使用 Nativele 元件：props、事件、`v-model`、slot、`<KeepAlive>`、範本型別 |
-| `nativele-svelte` | 在 Svelte 5 中使用 Nativele 元件：props、事件、slot、範本型別 |
+| `nativele-svelte` | 在 Svelte 5 中使用 Nativele 元件：props、事件、slot、範本型別（Experimental） |
 | `nativele-angular` | 在 Angular 中使用 Nativele 元件：綁定、變更偵測、建置流程、內容投影（Experimental） |
+| `nativele-architecture` | 應用的結構：功能資料夾、共用元件與 store、由 router 掛載的頁面、延遲載入、測試分層 |
 | `nativele-vite` | 在 Vite 應用中使用 Nativele：外掛與 `root`、多頁建置、熱更新 |
-| `nativele-integration` | 在沒有專屬 Skill 的框架（Preact、Solid 等）中使用 Nativele 元件：property、事件、slot、生命週期、範本型別（Experimental） |
+| `nativele-integration` | 在沒有專屬 Skill 的框架（Preact、Solid 等）中使用 Nativele 元件：property、事件、slot、生命週期、範本型別 |
 | `nativele-state-management` | 狀態放在哪裡；`createStore`，以及透過 `bind` 接上 Zustand、Redux Toolkit、nanostores |
 | `nativele-testing` | 用 Vitest 做元件測試、真實瀏覽器測試 |
 | `nativele-tanstack-query` | 用 `@tanstack/query-core` 取資料（Experimental） |
@@ -228,6 +229,7 @@ define("task-board", TaskBoard);
 - [Components and data flow: state, props, derive, events, composition, stores](https://github.com/Pixmi/nativele/blob/main/docs/components.md)
 - [Recipes: loading and error states, store data, filtered lists, dialogs, form validation](https://github.com/Pixmi/nativele/blob/main/docs/recipes.md)
 - [Lists: lists of components with `items =`, plain lists with `replace()`, moving items](https://github.com/Pixmi/nativele/blob/main/docs/lists.md)
+- [Architecture: feature folders, shared components and stores, pages mounted by a router, where state lives, testing strategy](https://github.com/Pixmi/nativele/blob/main/docs/architecture.md)
 - [Setup, checks and lint: installation, Vite, oxlint, `ts-dom check`, `ts-dom doctor`, accessibility](https://github.com/Pixmi/nativele/blob/main/docs/tooling.md)
 - [Performance: the large list benchmark](https://github.com/Pixmi/nativele/blob/main/docs/performance.md)
 - [Design: principles, deliberate decisions, limitations](https://github.com/Pixmi/nativele/blob/main/docs/design.md)

package/dist/{a11y-CV3nBgBn.mjs → a11y-CiEJj_e6.mjs}

@@ -1,6 +1,6 @@
 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 { dirname, join, relative, resolve, sep } from "node:path";
 import { parseFragment } from "parse5";
 // src/lib/codegen.ts
 /** Every diagnostic that `ts-dom gen` can report while analyzing a template. */
@@ -29,7 +29,7 @@ const CODEGEN_RULES = {
 	"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"
+	"duplicate-define": "a custom element tag can be defined only once across the scanned directories"
 };
 const RESERVED_ELEMENT_NAMES = /* @__PURE__ */ new Set([
 	"annotation-xml",
@@ -104,7 +104,7 @@ function analyze(html) {
 				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);
+				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 }}. If the file is another framework's template, this folder is not meant to be scanned: scan only the folder with the Nativele templates, or leave the file out with --exclude.`, at);
 			}
 		}
 	}
@@ -406,13 +406,15 @@ function nonCodeRanges(code) {
 	return out;
 }
 /**
-* Scan a directory for every `define("my-tag", MyClass)` call.
+* Scan one or more directories for every `define("my-tag", MyClass)` call; a file under two of them is read once.
 * 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) {
+function scanDefines(dirs) {
 	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 files = /* @__PURE__ */ new Map();
+	for (const dir of typeof dirs === "string" ? [dirs] : dirs) for (const f of listTs(dir)) if (!files.has(resolve(f))) files.set(resolve(f), f);
+	for (const file of files.values()) {
 		const code = readFileSync(file, "utf8");
 		const skip = nonCodeRanges(code);
 		const inCode = (pos) => !skip.some(([a, b]) => pos >= a && pos < b);
@@ -422,12 +424,15 @@ function scanDefines(dir) {
 			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"));
+			const before = code.slice(0, m.index);
 			defs.push({
 				tag,
 				className,
 				file,
 				exported: named || isDefault,
-				isDefault
+				isDefault,
+				line: before.split("\n").length,
+				col: m.index - before.lastIndexOf("\n")
 			});
 		}
 	}
@@ -437,6 +442,30 @@ const relImport = (fromDir, file) => {
 	const r = relative(fromDir, file).split(sep).join("/").replace(/\.ts$/, ".js");
 	return r.startsWith(".") ? r : `./${r}`;
 };
+/**
+* A tag that two of the directories define with different classes, reported at its second define() call.
+* A tag defined twice within one directory is reported by `generateTags` instead.
+*/
+function crossDirDuplicates(dirs) {
+	const byTag = /* @__PURE__ */ new Map();
+	for (const d of scanDefines(dirs)) byTag.set(d.tag, [...byTag.get(d.tag) ?? [], d]);
+	const inside = (dir, file) => resolve(file).startsWith(resolve(dir) + sep);
+	const out = [];
+	for (const [tag, defs] of byTag) {
+		const [first, second] = defs;
+		if (defs.length < 2 || dirs.some((dir) => defs.every((d) => inside(dir, d.file)))) continue;
+		const at = (d) => `${relative(process.cwd(), d.file)}:${d.line ?? 1}`;
+		out.push({
+			file: second.file,
+			line: second.line ?? 1,
+			col: second.col ?? 1,
+			severity: "error",
+			rule: "duplicate-define",
+			message: `The tag <${tag}> is defined more than once in the scanned folders (${at(first)} and ${at(second)}), so the second define() fails at runtime. Fix: each custom element name can be defined only once; rename one of them.`
+		});
+	}
+	return out;
+}
 /** 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) => ({
@@ -488,11 +517,11 @@ function renderTags(dir) {
 /**
 * 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`.
+* `scanned` are all the directories of the run: a ts-dom-tags.ts in a subfolder is an orphan unless that subfolder is one of them.
 */
-function planGenerated(dir, options = {}) {
+function planGenerated(dir, options = {}, defs = scanDefines(dir), scanned = [dir]) {
 	const files = /* @__PURE__ */ new Map();
 	const errors = [];
-	const defs = scanDefines(dir);
 	for (const f of listHtml(dir)) {
 		if (!isSelected(dir, f, options)) continue;
 		try {
@@ -510,26 +539,26 @@ function planGenerated(dir, options = {}) {
 		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);
+	for (const f of listGenerated(dir, scanned)) 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;
+function staleGenerated(dir, options = {}, defs, scanned) {
+	return checkGenerated(dir, options, defs, scanned).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);
+function checkGenerated(dir, options = {}, defs, scanned) {
+	const plan = planGenerated(dir, options, defs, scanned);
 	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"
+				reason: file === join(dir, TAGS_FILE) ? "outdated" : "orphan"
 			});
 		} else if (prev === null) out.push({
 			file,
@@ -545,21 +574,24 @@ function checkGenerated(dir, options = {}) {
 		errors: plan.errors
 	};
 }
-function listGenerated(dir) {
+function listGenerated(dir, scanned, top = true) {
 	const out = [];
+	const ownTags = top || scanned.some((d) => resolve(d) === resolve(dir));
 	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);
+		if (statSync(full).isDirectory()) out.push(...listGenerated(full, scanned, false));
+		else if ((name.endsWith(".html.ts") || name === TAGS_FILE && !ownTags) && 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. */
-function generateAll(dir, options = {}) {
+/**
+* Generate every `x.html.ts` (and the tag map) under a directory; collects all errors and throws them together.
+* `defs` are the define() calls templates import child components from (default: those under `dir`).
+*/
+function generateAll(dir, options = {}, defs = scanDefines(dir), scanned = [dir]) {
 	const written = [];
 	const errors = [];
-	const defs = scanDefines(dir);
 	for (const f of listHtml(dir)) {
 		if (!isSelected(dir, f, options)) continue;
 		try {
@@ -576,7 +608,22 @@ 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);
+	for (const f of listGenerated(dir, scanned)) if (!existsSync(f.slice(0, -3))) unlinkSync(f);
+	if (errors.length) throw new CodegenError(errors.join("\n"));
+	return written;
+}
+/** `generateAll` for every directory, with the define() calls of all of them: a template imports a child component defined in another directory. */
+function generateDirs(dirs, options = {}) {
+	const defs = scanDefines(dirs);
+	const written = [];
+	const errors = [];
+	for (const dir of dirs) try {
+		written.push(...generateAll(dir, options, defs, dirs));
+	} catch (e) {
+		if (e instanceof CodegenError) errors.push(e.message);
+		else throw e;
+	}
+	for (const d of crossDirDuplicates(dirs)) errors.push(formatDiagnostics(d.file, [d]));
 	if (errors.length) throw new CodegenError(errors.join("\n"));
 	return written;
 }
@@ -586,11 +633,10 @@ function watchAll(dirs, opts = {}) {
 	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(() => {
+			clearTimeout(timers.get("tags"));
+			timers.set("tags", setTimeout(() => {
 				try {
-					for (const f of generateAll(dir, opts)) opts.onGenerate?.(f);
+					for (const f of generateDirs(dirs, opts)) opts.onGenerate?.(f);
 				} catch (e) {
 					if (e instanceof CodegenError) opts.onError?.(e.message);
 					else throw e;
@@ -604,7 +650,7 @@ function watchAll(dirs, opts = {}) {
 		timers.set(file, setTimeout(() => {
 			try {
 				if (!existsSync(file) || !isSelected(dir, file, opts) || isFullPage(readFileSync(file, "utf8"))) return;
-				opts.onGenerate?.(generateFile(file, opts, dir));
+				opts.onGenerate?.(generateFile(file, opts, scanDefines(dirs)));
 			} catch (e) {
 				if (e instanceof CodegenError) opts.onError?.(e.message);
 				else throw e;
@@ -814,4 +860,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 { 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 };
+export { staleGenerated as _, analyze as a, formatDiagnostics as c, isFullPage as d, isSelected as f, scanDefines as g, renderTags as h, CodegenError as i, generateDirs as l, listTs as m, checkA11y as n, checkGenerated as o, listHtml as p, CODEGEN_RULES as r, crossDirDuplicates as s, A11Y_RULES as t, generateFile as u, watchAll as v };