@nativele/ts-dom 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -10,6 +10,12 @@ 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.3.0
+
+- `ts-dom gen` rejects `<html>`, `<head>` and `<body>` inside a template (rule `document-tag`) instead of silently dropping them; a file that starts with `<!doctype html>` or `<html>` is still a page entry whatever its name.
+- `tpl.instantiate().rootElement` is the template's only top-level element, typed by its tag; the type has it only for a template with exactly one top-level element (generated `x.html.ts` files carry a `rootElement` field, so regenerate them with `ts-dom gen`).
+- Non-bubbling events such as media events (`canplay`, `loadeddata`, ...), `close`, `cancel` and `invalid` now reach `data-on-*` handlers; they were listened for in the bubble phase and never fired.
+
 ## 0.2.1
 
 - Releases are published through npm Trusted Publishing: the release workflow stages the version without an npm token, and a maintainer approves it on npm. No library code changes.
@@ -37,7 +43,6 @@ First release.
 - `whitespace: "collapse"` (CLI `--whitespace=collapse`, Vite plugin option) collapses whitespace runs and drops line-break-only text between tags; the default keeps text as written.
 - `replace()` throws `[duplicate-key]` for two items with the same key and leaves the list untouched. `EventHit<Item>` types `hit.item` when the handler annotates it. `bind` accepts any source with `get` and `subscribe` (`ReadableStore`).
 - `ts-dom gen --include=<glob> --exclude=<glob>` (and the Vite plugin options) generate only the selected templates, for migrating a project in steps.
-
 ### Composition
 
 - Child components used in a template are imported automatically by the generated `x.html.ts`; HTML is the only source of dependencies.

package/README.md

@@ -352,7 +352,7 @@ export default template<{
 }>([["h2", {}, ["Hello, {{ name }}!"]], /* ... */]);
 ```
 
-Whole-page documents (starting with `<!doctype>` or `<html>`, such as `index.html`) are page entry points, not templates, and are not processed.
+Whole-page documents are page entry points, not templates, and are not processed. A file is a page when its content starts with `<!doctype html>` or `<html>` (comments before it are fine); the file name does not matter, so `index.html`, `main.html` and `login.html` all work. A template is a fragment of a component, so `<html>`, `<head>` and `<body>` are rejected in it (rule `document-tag`): the browser would drop them from the fragment and whatever you put on them would have no effect. To keep a file out of generation in another way, use `--exclude`.
 
 ## HTML Syntax
 
@@ -656,14 +656,16 @@ const off = store.subscribe((s) => console.log(s)); // returns an unsubscribe fu
 ```ts
 import itemTpl from "./menu-item.html.js";
 
-function menuItem(label: string): HTMLElement {
+function menuItem(label: string): HTMLLIElement {
   const view = itemTpl.instantiate();
   view.text.label = label;
   view.refs.button.addEventListener("click", () => select(label));
-  return view.root.firstElementChild as HTMLElement;
+  return view.rootElement; // typed by the template's top-level tag
 }
 ```
 
+`rootElement` is the template's only top-level element (a top-level `<style>` does not count); it exists in the type only when the template has exactly one, so a template that later gains a second root element makes `tsc` report the use.
+
 There is no host element, so `data-on-*` attributes do nothing here (listen on `refs`) and `<slot>` is not projected; use a component when you need those.
 
 ## Lists
@@ -704,6 +706,10 @@ Notes:
 - `data-each` cannot be nested. Split it into two templates: put the inner list in its own `.html` (a child component with its own `data-each`) and use that component's tag inside the outer item.
 - `<slot>` cannot be placed inside an item.
 
+### Order of list updates
+
+`replace()` and `upsert()` put a new item's element into the document first and then call `update`, so a child component placed in an item is connected before the parent has set its properties. Build per-item state in the child when it first receives data (for example in a property setter), and guard a render in `connected()` with the data it needs.
+
 ## Trusted Types, Translations and Icons
 
 - Trusted Types: pages that enforce `require-trusted-types-for 'script'` work with no policy, because `ts-dom gen` writes the markup as data and the runtime builds it with DOM calls. Your own code must avoid `innerHTML` too.
@@ -720,7 +726,7 @@ Notes:
 
 Four complementary checks. **Every message has a stable rule id and explains what is wrong, why, and how to fix it**; `npx ts-dom rules` lists all rules.
 
-1. **codegen diagnostics** (`ts-dom gen` and the Vite plugin, with line and column numbers; on errors they abort and write no files): duplicate `data-ref`, `data-each` without a single root element, `data-each` not on a `<template>`, nested `data-each`, `data-if` on an item root element, `<slot>` inside an item, `<style>` not at the first level, invalid holes, holes inside attributes, invalid `data-on-*` (including names that collide with DOM or ts-dom members), and markup that runs code or Trusted Types blocks: `<script>`, `on*` attributes, `srcdoc`, and `javascript:` URLs.
+1. **codegen diagnostics** (`ts-dom gen` and the Vite plugin, with line and column numbers; on errors they abort and write no files): duplicate `data-ref`, `data-each` without a single root element, `data-each` not on a `<template>`, nested `data-each`, `data-if` on an item root element, `<slot>` inside an item, `<style>` not at the first level, invalid holes, holes inside attributes, invalid `data-on-*` (including names that collide with DOM or ts-dom members), `<html>`, `<head>` and `<body>` inside a template, and markup that runs code or Trusted Types blocks: `<script>`, `on*` attributes, `srcdoc`, and `javascript:` URLs.
 2. **tsc**: an error when TypeScript uses a name the HTML does not declare (`this.refs.nope`, `this.show("nope", true)`); all constraints between `state`, `props`, `derive`, `emits` and the HTML (see "Data Flow"); child component prop names and types; `define()` checks that the methods for `data-on-*` exist.
 3. **Runtime**: `Component()` and components, at definition, connection, and use, throw errors that carry a `[rule id]` and a fix for the same problems.
 4. **lint** (`ts-dom/unused-markup`, `ts-dom/data-flow`, `ts-dom/a11y`): markup declared in the HTML but never used (errors, with the HTML location), data flow suggestions and child component contracts (warnings), ARIA (warnings).

package/README.zh-TW.md

@@ -354,7 +354,7 @@ export default template<{
 }>([["h2", {}, ["Hello, {{ name }}!"]], /* ... */]);
 ```
 
-整頁文件（以 `<!doctype>` 或 `<html>` 開頭，例如 `index.html`）是頁面入口，不是範本，不會被處理。
+整頁文件是頁面入口，不是範本，不會被處理。判斷依據是檔案內容：以 `<!doctype html>` 或 `<html>` 開頭（前面可以有註解）就是頁面，與檔名無關，所以 `index.html`、`main.html`、`login.html` 都可以。範本是元件的片段，因此其中的 `<html>`、`<head>`、`<body>` 會被拒絕（規則 `document-tag`）：瀏覽器會把它們從片段中丟掉，放在上面的任何東西都不會有效果。想用別的方式讓檔案不被處理，可以用 `--exclude`。
 
 ## HTML 語法
 
@@ -658,14 +658,16 @@ const off = store.subscribe((s) => console.log(s)); // 回傳取消函式
 ```ts
 import itemTpl from "./menu-item.html.js";
 
-function menuItem(label: string): HTMLElement {
+function menuItem(label: string): HTMLLIElement {
   const view = itemTpl.instantiate();
   view.text.label = label;
   view.refs.button.addEventListener("click", () => select(label));
-  return view.root.firstElementChild as HTMLElement;
+  return view.rootElement; // 型別由範本第一層的標籤決定
 }
 ```
 
+`rootElement` 是範本第一層唯一的元素（第一層的 `<style>` 不算）；只有範本剛好一個根元素時型別上才有它，所以範本日後多出第二個根元素時，`tsc` 會在使用處報錯。
+
 這種用法沒有宿主元素，所以 `data-on-*` 不會生效（請在 `refs` 上自行監聽），`<slot>` 也不會投影；需要這些時請用元件。
 
 ## 清單
@@ -706,6 +708,10 @@ this.lists.tags.replace(
 - `data-each` 不能巢狀，要分成兩套模板：把內層清單放進自己的 `.html`（有自己 `data-each` 的子元件），在外層項目裡使用該元件的標籤。
 - `<slot>` 不能放在項目內。
 
+### 清單更新的順序
+
+`replace()` 與 `upsert()` 會先把新項目的元素放進文件，再呼叫 `update`，所以放在項目內的子元件會在父元件設定屬性之前就已經連接。每列自己的狀態請等子元件第一次拿到資料時再建立（例如在屬性的 setter 裡），`connected()` 裡的渲染要先確認需要的資料已經存在。
+
 ## Trusted Types、翻譯與圖示
 
 - Trusted Types：啟用 `require-trusted-types-for 'script'` 的頁面不需要設定任何 policy 就能用，因為 `ts-dom gen` 把標記寫成資料，執行期只用 DOM 呼叫建立。你自己的程式碼也要避免 `innerHTML`。
@@ -722,7 +728,7 @@ this.lists.tags.replace(
 
 四道檢查，互補。**每一則訊息都有穩定的規則代號，並說明哪裡錯、為什麼、怎麼修**；`npx ts-dom rules` 列出全部規則。
 
-1. **codegen 診斷**（`ts-dom gen` 與 Vite 外掛，帶行列號，有錯誤時中斷、不寫檔）：重複的 `data-ref`、`data-each` 沒有單一根元素、`data-each` 不在 `<template>` 上、`data-each` 巢狀、`data-if` 在項目根元素、`<slot>` 在項目內、`<style>` 不在第一層、不合法的洞、屬性內的洞、不合法的 `data-on-*`（含與 DOM 或 ts-dom 成員同名），以及會執行程式碼或被 Trusted Types 擋下的標記：`<script>`、`on*` 屬性、`srcdoc`、`javascript:` 網址。
+1. **codegen 診斷**（`ts-dom gen` 與 Vite 外掛，帶行列號，有錯誤時中斷、不寫檔）：重複的 `data-ref`、`data-each` 沒有單一根元素、`data-each` 不在 `<template>` 上、`data-each` 巢狀、`data-if` 在項目根元素、`<slot>` 在項目內、`<style>` 不在第一層、不合法的洞、屬性內的洞、不合法的 `data-on-*`（含與 DOM 或 ts-dom 成員同名），範本內的 `<html>`、`<head>`、`<body>`，以及會執行程式碼或被 Trusted Types 擋下的標記：`<script>`、`on*` 屬性、`srcdoc`、`javascript:` 網址。
 2. **tsc**：TypeScript 使用了 HTML 沒有宣告的名稱就報錯（`this.refs.nope`、`this.show("nope", true)`）；`state`、`props`、`derive`、`emits` 與 HTML 之間的所有約束（見「資料流」）；子元件 prop 的名稱與型別；`define()` 檢查 `data-on-*` 的方法存在。
 3. **執行期**：`Component()` 與元件在定義、連接與使用時，對同樣的問題丟出帶 `[規則代號]` 與修正方式的錯誤。
 4. **lint**（`ts-dom/unused-markup`、`ts-dom/data-flow`、`ts-dom/a11y`）：HTML 宣告了卻沒被使用的標記（錯誤，附 HTML 位置）、資料流建議與子元件契約（警告）、ARIA（警告）。

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

@@ -22,6 +22,7 @@ const CODEGEN_RULES = {
 	"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",
+	"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)",
 	"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:",
@@ -66,6 +67,17 @@ function analyze(html) {
 			...locOf(n)
 		});
 	};
+	const blanked = html.replace(/<!--[\s\S]*?-->/g, (c) => c.replace(/[^\n]/g, " "));
+	for (const m of blanked.matchAll(/<(html|head|body)(?=[\s/>])/gi)) {
+		const before = blanked.slice(0, m.index);
+		a.diagnostics.push({
+			rule: "document-tag",
+			severity: "error",
+			message: `<${m[1]?.toLowerCase()}> cannot be in a template: a template is a fragment of a component, and the browser drops <html>, <head> and <body> from fragments, so nothing you put on them has any effect. Fix: remove the tag and keep its content. If this file is a whole page, start it with <!doctype html> and it is treated as a page entry and skipped (or leave it out with --exclude).`,
+			line: before.split("\n").length,
+			col: m.index - before.lastIndexOf("\n")
+		});
+	}
 	const mark = (key, n) => {
 		if (!a.locs.has(key)) a.locs.set(key, locOf(n));
 	};
@@ -176,6 +188,15 @@ const union = (xs) => {
 	return arr.length ? arr.map(q).join(" | ") : "never";
 };
 const obj = (m) => `{ ${[...m].map(([n, t]) => `${q(n)}: ${t}`).join("; ")} }`;
+/** The type of the template's only top-level element (a `<style>` does not count); `never` when there is not exactly one, or other text sits beside it. */
+function rootElementType(html) {
+	const tops = parseFragment(html).childNodes.filter((n) => n.nodeName !== "#comment" && !(n.nodeName === "#text" && !n.value.trim()));
+	const elements = tops.filter((n) => isEl$1(n) && !(n.tagName === "style" && n.namespaceURI === HTML_NS) && !(n.tagName === "template" && n.attrs.some((a) => a.name === "data-each")));
+	const others = tops.filter((n) => !(isEl$1(n) && (n.tagName === "style" || n.tagName === "template")));
+	if (elements.length !== 1 || others.length !== 1) return "never";
+	const el = elements[0];
+	return el.namespaceURI === HTML_NS ? `El<${JSON.stringify(el.tagName)}>` : "SVGElement";
+}
 function globToRegExp(glob) {
 	let re = "";
 	for (let i = 0; i < glob.length; i++) {
@@ -240,6 +261,7 @@ function generateModule(html, options = {}, imports = []) {
   lists: { ${lists} };
   ifs: ${union(a.scope.ifs)};
   slots: ${union(a.slots)};
+  rootElement: ${rootElementType(html)};
   text: ${union(a.scope.text)};
   events: ${union(a.events)};
 }`;

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { d as listHtml, i as CodegenError, n as checkA11y, p as watchAll, r as CODEGEN_RULES, s as generateAll, t as A11Y_RULES } from "./a11y-DZvViTVA.mjs";
-import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-B7SIRo0c.mjs";
+import { d as listHtml, i as CodegenError, n as checkA11y, p as watchAll, r as CODEGEN_RULES, s as generateAll, t as A11Y_RULES } from "./a11y-CeZcA10z.mjs";
+import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-DS-IOjkf.mjs";
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 // src/cli.ts

package/dist/index.d.mts

@@ -68,6 +68,8 @@ interface Schema {
   events: string;
   ifs: string;
   slots: string;
+  /** The template's only top-level element (a `<style>` does not count), or `never` when there is not exactly one. */
+  rootElement: Element;
 }
 /**
  * A template's parsed markup, written by codegen: a string is a text node, `["#comment", text]` a comment,
@@ -75,7 +77,10 @@ interface Schema {
  */
 type TemplateNode = string | readonly [tag: string, attrs: Readonly<Record<string, string>>, children: readonly TemplateNode[], ns?: string] | readonly ["#comment", string];
 /** A template built without a component: the nodes, and the typed handles to the places the template names. */
-interface TemplateInstance<S extends Schema> {
+type TemplateInstance<S extends Schema> = TemplateInstanceBase<S> & ([S["rootElement"]] extends [never] ? unknown : {
+  readonly rootElement: S["rootElement"];
+});
+interface TemplateInstanceBase<S extends Schema> {
   /** The built nodes; insert it (or its children) where it should show. */
   readonly root: DocumentFragment;
   /** The elements marked with `data-ref`. */

package/dist/index.mjs

@@ -357,7 +357,33 @@ const NON_BUBBLING = /* @__PURE__ */ new Set([
 	"load",
 	"error",
 	"scroll",
-	"toggle"
+	"scrollend",
+	"toggle",
+	"beforetoggle",
+	"cancel",
+	"close",
+	"invalid",
+	"abort",
+	"canplay",
+	"canplaythrough",
+	"durationchange",
+	"emptied",
+	"ended",
+	"loadeddata",
+	"loadedmetadata",
+	"loadstart",
+	"pause",
+	"play",
+	"playing",
+	"progress",
+	"ratechange",
+	"seeked",
+	"seeking",
+	"stalled",
+	"suspend",
+	"timeupdate",
+	"volumechange",
+	"waiting"
 ]);
 function Component(tpl, opts = {}) {
 	const shadow = opts.shadow === true;
@@ -698,10 +724,13 @@ function template(nodes) {
 		build: () => buildNodes(nodes),
 		instantiate() {
 			const root = buildNodes(nodes);
+			const tops = [...root.children].filter((el) => el.localName !== "style" && !(el instanceof HTMLTemplateElement && el.hasAttribute("data-each")));
+			const rootElement = tops.length === 1 ? tops[0] : void 0;
 			const { refs, lists, text, conds } = mountTemplate(root);
 			conds.hideAll();
 			return {
 				root,
+				rootElement,
 				refs,
 				lists,
 				text,

package/dist/{lint-B7SIRo0c.mjs → lint-DS-IOjkf.mjs}

@@ -1,4 +1,4 @@
-import { a as analyze, d as listHtml, f as scanDefines } from "./a11y-DZvViTVA.mjs";
+import { a as analyze, d as listHtml, f as scanDefines } from "./a11y-CeZcA10z.mjs";
 import { readFileSync } from "node:fs";
 import { basename, dirname, relative } from "node:path";
 // src/lib/lint.ts

package/dist/oxlint-plugin.mjs

@@ -1,5 +1,5 @@
-import { n as checkA11y } from "./a11y-DZvViTVA.mjs";
-import { a as dataFlow, i as contractsFor, l as templateCode, r as componentClasses, u as unusedMarkup } from "./lint-B7SIRo0c.mjs";
+import { n as checkA11y } from "./a11y-CeZcA10z.mjs";
+import { a as dataFlow, i as contractsFor, l as templateCode, r as componentClasses, u as unusedMarkup } from "./lint-DS-IOjkf.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 // src/lib/oxlint-plugin.ts

package/dist/vite-plugin.mjs

@@ -1,4 +1,4 @@
-import { c as generateFile, d as listHtml, i as CodegenError, l as isFullPage, n as checkA11y, o as formatDiagnostics, s as generateAll, u as isSelected } from "./a11y-DZvViTVA.mjs";
+import { c as generateFile, d as listHtml, i as CodegenError, l as isFullPage, n as checkA11y, o as formatDiagnostics, s as generateAll, u as isSelected } from "./a11y-CeZcA10z.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve, sep } from "node:path";
 // src/lib/vite-plugin.ts

package/llms.txt

@@ -65,7 +65,7 @@ define("my-counter", MyCounter);
 ```
 
 ## Template without a component
-`const view = tpl.instantiate()` returns `{ root: DocumentFragment, refs, lists, text, show }` typed like a component, for pieces created in code. No host: `data-on-*` is inert (use `refs.x.addEventListener`) and `<slot>` is not projected.
+`const view = tpl.instantiate()` returns `{ root: DocumentFragment, rootElement, refs, lists, text, show }` typed like a component (`rootElement` exists in the type only when the template has exactly one top-level element, `<style>` excluded), for pieces created in code. No host: `data-on-*` is inert (use `refs.x.addEventListener`) and `<slot>` is not projected.
 
 ## Setup
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativele/ts-dom",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A TypeScript-driven, HTML-first UI library. Bind HTML to TypeScript: HTML describes the structure, TypeScript owns behavior and state, and the DOM is the single source of truth. Fully typed, no virtual DOM, no bundler required.",
   "keywords": [
     "html",