@nativele/ts-dom 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -10,6 +10,38 @@ 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.4.0
+
+### Lists of components
+
+- `<template data-each="todos" data-key="id" data-prop="todo"><todo-row role="listitem"></todo-row></template>` and `this.lists.todos.items = todos`: each item is one component that receives its item as a property, matched by key. An element is kept for a key that stays (moved with `moveBefore`), created for a new key and removed for a key that is gone; reading `items` returns the items in document order.
+- `tsc` checks the assigned items against the property type the item component declares and the `data-key` field (a string or a number). An item component defined in a scanned folder must be exported and listed in `ts-dom-tags.ts`, otherwise the assignment is a type error that names the cause; only components from outside the scanned folders get a loose type.
+- New codegen rules `each-binding-incomplete`, `invalid-each-binding` and `each-binding-root`, and runtime errors with a `Fix:` hint for what types cannot see (`invalid-items`, `invalid-item`, `missing-key`, `duplicate-key`, `list-not-bound`, `unknown-prop`). A wrong `data-prop` throws before the list changes.
+- The accessibility check `list-structure` accepts a custom element with `role="listitem"` as a list item.
+- `replace()` stays for lists of plain elements, and `data-each` still cannot be nested: a list inside an item is that component's own list.
+
+### Vite dev server
+
+- Editing a template regenerates its `x.html.ts` and reloads the page once if a page uses it; a save that changes nothing does not reload. This works under Vite and Vite+ (which reports changed files by relative path).
+- Deleting a template removes its generated module, and adding or removing a `define()` updates `ts-dom-tags.ts` and the child imports of the templates.
+- A generated module rewritten by something else (`ts-dom gen --watch`, a checkout) reloads the page through Vite; duplicate change events and identical rewrites by other dev servers no longer reload it twice.
+- `dirs` are resolved against Vite's `root` instead of the working directory. The `define()` scan is cached and redone only when a `.ts` file with a `define()` changes. Messages go to the logger of the server that saw the change.
+
+### Fixes
+
+- The accessibility messages say "natively" again where it had been replaced by "ts-domy".
+
+### Breaking changes
+
+- The Vite plugin's `dirs` are relative to Vite's `root`; a project whose `root` differs from the working directory must adjust them.
+- A project whose item component class is not exported, or whose `ts-dom-tags.ts` is stale, now gets a type error on `items`.
+
+## 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 +69,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

@@ -31,11 +31,34 @@ define("user-card", UserCard);
 
 If the HTML uses a name that `state` does not have, or `data-on-click` points to a method that does not exist, `tsc` reports an error.
 
+## The Short Version
+
+Six things cover most components:
+
+1. **HTML only names things**: `{{ name }}` (text), `data-ref="x"` (an element you need), `data-if="x"` (shown or not), `<template data-each="x">` (a list), `data-on-click="method"` (an event), `<slot>`. There are no expressions; compute in TypeScript.
+2. **Run `npx ts-dom gen` before `tsc`** whenever a `.html` changes. It writes the typed `x.html.ts` that `import tpl from "./x.html.js"` needs; until then `tsc` can only say the module is missing.
+3. **Data lives in the class**: `state` (yours), `props` (the parent's), `derive` (computed). Change state only with `this.set()`; `{{ }}` and `data-if` with the same name update by themselves.
+4. **Everything else goes in `render(view, changed)`**: lists, attributes, focus. A list of components is one assignment, `if (changed.has("todos")) this.lists.todos.items = view.todos`, with `data-key` and `data-prop` on its `<template data-each>`.
+5. **Props go down, events go up**: the parent sets props; the child calls `this.emit("name", detail)` and the parent handles it with `data-on-name` on the child's tag.
+6. **A handler is a public method** `(event, hit)`; inside a list item `hit.key` is the item's key.
+
+## Rules for AI Agents
+
+Paste these into your project's agent instructions (`AGENTS.md`, `CLAUDE.md` or similar):
+
+- Write the `.html` and the `.ts` of a component together; never edit `x.html.ts` or `ts-dom-tags.ts`, which `ts-dom gen` writes.
+- After changing any `.html`, run `npx ts-dom gen && npx tsc`, then fix every error the types report (a missing name in `state`, a missing handler method) instead of casting it away.
+- Import templates as `./x.html.js`.
+- No expressions in HTML: put computed values in `derive`, and change state only with `this.set()`.
+- Every diagnostic from `ts-dom gen` and `ts-dom lint` ends with a `Fix:` hint; follow it. `npx ts-dom rules` lists all rule ids, and `npx ts-dom lint --a11y` also checks accessibility.
+- A `data-each` list cannot be nested: put the inner list in its own `.html` as a child component.
+- For a list of components, write `data-key` and `data-prop` on the `<template data-each>`, give the item component `role="listitem"` inside `<ul>` or `<ol>`, assign `this.lists.x.items = ...` with new objects for changed items (never mutate an assigned item), and let `tsc` check the items.
+
 ## Quick Start
 
 ```sh
 npm i -D typescript && npm i @nativele/ts-dom
-npx ts-dom gen      # generate x.html.ts (fully typed) for every x.html
+npx ts-dom gen      # generate x.html.ts (fully typed) for every x.html; run it again after every .html change
 npx tsc             # type-check and compile; no Vite or other bundler needed
 ```
 
@@ -297,6 +320,8 @@ export default defineConfig({
 });
 ```
 
+While the dev server runs, the plugin keeps the generated files in step: adding or editing a template regenerates its `x.html.ts` and reloads the page once if a page uses it (a save that changes nothing does not reload), deleting a template removes its `x.html.ts`, and adding or removing a `define()` updates `ts-dom-tags.ts` and the child imports of the templates. `dirs` are relative to Vite's `root`. The page reloads rather than hot-swapping the component because a custom element tag can be defined only once, so a new class cannot replace the running one.
+
 When installing, we recommend installing `vite-plus` first and then `ts-dom` (when both are installed in the same npm run, `vite` may not be hoisted to the top level).
 
 ### Lint (optional)
@@ -352,7 +377,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,18 +681,47 @@ 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
 
+There are two ways to fill a list. Use components when an item has anything of its own (state, events, a nested list), and `replace()` for small items made of plain elements.
+
+### Items as components: `items = ...`
+
+Name the field that identifies an item and the property that receives it, on the `<template data-each>`; the item is one custom element:
+
+```html
+<ul>
+  <template data-each="todos" data-key="id" data-prop="todo">
+    <todo-row role="listitem" data-on-toggled="toggle"></todo-row>
+  </template>
+</ul>
+```
+
+```ts
+render(view, changed) {
+  if (changed.has("todos")) this.lists.todos.items = view.todos;
+}
+toggle(_e: Event, hit: EventHit) { /* hit.key is the item's id */ }
+```
+
+Assigning `items` keeps the element of each key that stays (moved with `moveBefore` where the browser has it, so focus and state survive), creates one for a new key, removes the ones that are gone, and sets `todo` on each element whose item is not the same object as last time. Use immutable updates: changing a field of an object you already assigned and assigning the same object again does not update the item component, because props are compared by reference; assign a new object instead, for example `{ ...todo, done: true }`. The item component declares `todo` in its `props`, shows it however it likes, and tells the parent with `emit`; the parent reads `hit.key` in the handler. Reading `items` returns what was last assigned. `tsc` checks the assignment: each item must have the type of the `todo` property that `<todo-row>` declares and a `data-key` field (`id`), and the item component must declare the `data-prop` property; a list without `data-key` and `data-prop` takes no items. This relies on the component being registered in `ts-dom-tags.ts` (an exported `define("todo-row", TodoRow)` in a scanned directory). When the component is defined in a scanned directory but its class is not exported, or `ts-dom-tags.ts` does not list it yet, the assignment is a type error that says so (`itemComponentClassNotExported`, `itemComponentMissingFromTagMap`); only a component from outside the scanned directories accepts any item with the `id` field. At runtime, assigning throws when the value is not an array of objects, when an item has no string or number `id`, when two items share one, or when the template has no `data-key` and `data-prop`.
+
+Inside a `<ul>` or `<ol>` the item component needs `role="listitem"`, because a custom element is not an `<li>`; the accessibility check (`list-structure`) asks for it. `data-each` cannot be nested, on purpose: an item is one component, so a list inside an item is that component's own `data-each`. Every template then holds one level, with its own `refs`, `text` and event handling.
+
+### Items as plain elements: `replace()`
+
 ```html
 <ul>
   <template data-each="tags">
@@ -704,6 +758,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 +778,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`, an incomplete or invalid `data-key` / `data-prop`, a `data-key` list whose item is not one custom element, `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).
@@ -777,7 +835,7 @@ npx ts-dom lint --a11y [--strict]
 | `heading-empty` | `h1`–`h6` must not be empty |
 | `aria-role` | `role` must be a valid ARIA role |
 | `aria-attr` | `aria-*` must be a valid ARIA attribute |
-| `role-tabindex` | A non-ts-domy-focusable element with an interactive role (button, tab, checkbox…) needs `tabindex` |
+| `role-tabindex` | A non-natively-focusable element with an interactive role (button, tab, checkbox…) needs `tabindex` |
 | `tabindex-positive` | Do not use a `tabindex` greater than 0 |
 | `hidden-focusable` | A focusable element must not have `aria-hidden="true"` |
 | `label-for` | `<label for>` must point to an `id` that exists in the template |

package/README.zh-TW.md

@@ -31,11 +31,34 @@ define("user-card", UserCard);
 
 HTML 用了 `state` 沒有的名稱、`data-on-click` 指向不存在的方法，`tsc` 都會報錯。
 
+## 精簡版
+
+六件事涵蓋大多數元件：
+
+1. **HTML 只放名稱**：`{{ name }}`（文字）、`data-ref="x"`（需要用到的元素）、`data-if="x"`（顯示與否）、`<template data-each="x">`（清單）、`data-on-click="method"`（事件）、`<slot>`。沒有表達式，需要計算就在 TypeScript 做。
+2. **`.html` 有改動就先跑 `npx ts-dom gen` 再跑 `tsc`**：它會產生 `import tpl from "./x.html.js"` 需要的型別檔 `x.html.ts`；在那之前 `tsc` 只會告訴你找不到模組。
+3. **資料放在類別裡**：`state`（自己的）、`props`（父元件給的）、`derive`（算出來的）。state 只用 `this.set()` 改；同名的 `{{ }}` 與 `data-if` 會自己更新。
+4. **其他都寫在 `render(view, changed)`**：清單、屬性、焦點。元件組成的清單只要一次指派，`if (changed.has("todos")) this.lists.todos.items = view.todos`，並在 `<template data-each>` 上寫 `data-key` 與 `data-prop`。
+5. **props 往下、事件往上**：父元件設定 props；子元件呼叫 `this.emit("name", detail)`，父元件在子元件的標籤上用 `data-on-name` 處理。
+6. **處理方法是公開方法** `(event, hit)`；在清單項目內 `hit.key` 就是該項目的 key。
+
+## 給 AI agent 的規則
+
+把這些貼進專案的 agent 指引檔（`AGENTS.md`、`CLAUDE.md` 等）：
+
+- 元件的 `.html` 與 `.ts` 一起寫；不要編輯 `x.html.ts` 與 `ts-dom-tags.ts`，它們是 `ts-dom gen` 產生的。
+- 改了任何 `.html` 之後，執行 `npx ts-dom gen && npx tsc`，然後把型別回報的每個錯誤（`state` 少了某個名稱、少了處理方法）修好，不要用型別斷言蓋掉。
+- 範本一律以 `./x.html.js` 匯入。
+- HTML 裡不放表達式：計算值放進 `derive`，state 只用 `this.set()` 改。
+- `ts-dom gen` 與 `ts-dom lint` 的每則診斷結尾都有 `Fix:` 提示，照做。`npx ts-dom rules` 列出所有規則編號，`npx ts-dom lint --a11y` 另外檢查無障礙。
+- `data-each` 清單不能巢狀：把內層清單放進自己的 `.html`，當成子元件。
+- 元件組成的清單：在 `<template data-each>` 寫 `data-key` 與 `data-prop`，在 `<ul>` 或 `<ol>` 裡的項目元件加 `role="listitem"`，以 `this.lists.x.items = ...` 指派，變動的項目要給新物件（不要就地修改已指派的物件），並讓 `tsc` 檢查項目型別。
+
 ## 快速開始
 
 ```sh
 npm i -D typescript && npm i @nativele/ts-dom
-npx ts-dom gen      # 為每個 x.html 產生 x.html.ts（含型別）
+npx ts-dom gen      # 為每個 x.html 產生 x.html.ts（含型別）；每次改了 .html 都要再跑一次
 npx tsc             # 型別檢查並編譯；不需要 Vite 或其他 bundler
 ```
 
@@ -299,7 +322,9 @@ export default defineConfig({
 });
 ```
 
-安裝時建議先裝 `vite-plus`，再裝 `ts-dom`（npm 同一次安裝時可能不會把 `vite` 提升到頂層）。
+dev server 執行期間，外掛會讓產生檔保持同步：新增或編輯範本會重新產生它的 `x.html.ts`，若有頁面用到就重新載入一次（存檔但內容沒變不會重載）；刪除範本會移除它的 `x.html.ts`；新增或移除 `define()` 會更新 `ts-dom-tags.ts` 與範本的子元件匯入。`dirs` 相對於 Vite 的 `root`。這裡是重新載入而不是熱替換元件，因為同一個自訂元素標籤只能定義一次，新的類別無法取代正在執行的那個。
+
+安裝時建議先裝 `vite-plus`，再裝 `@nativele/ts-dom`（npm 同一次安裝時可能不會把 `vite` 提升到頂層）。
 
 ### Lint（選用）
 
@@ -354,7 +379,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,18 +683,47 @@ 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>` 也不會投影；需要這些時請用元件。
 
 ## 清單
 
+填清單有兩種方式。項目有自己的東西（狀態、事件、內層清單）就用元件；只是幾個純元素組成的小項目就用 `replace()`。
+
+### 項目是元件：`items = ...`
+
+在 `<template data-each>` 上寫出識別項目的欄位名稱與接收項目的屬性名稱，項目是一個自訂元素：
+
+```html
+<ul>
+  <template data-each="todos" data-key="id" data-prop="todo">
+    <todo-row role="listitem" data-on-toggled="toggle"></todo-row>
+  </template>
+</ul>
+```
+
+```ts
+render(view, changed) {
+  if (changed.has("todos")) this.lists.todos.items = view.todos;
+}
+toggle(_e: Event, hit: EventHit) { /* hit.key 就是該項目的 id */ }
+```
+
+指派 `items` 時：key 還在的項目保留原本的元素（瀏覽器支援時用 `moveBefore` 搬動，所以焦點與狀態不會丟）、新 key 建立元素、消失的 key 移除，並對「與上次不是同一個物件」的項目設定元素的 `todo` 屬性。請用不可變更新：就地修改已指派過的物件欄位再指派同一個物件，項目元件不會更新，因為 props 以參考比較；請改指派新物件，例如 `{ ...todo, done: true }`。項目元件在自己的 `props` 宣告 `todo`，愛怎麼顯示都可以，用 `emit` 通知父元件，父元件在處理方法裡讀 `hit.key`。讀取 `items` 會回傳最近一次指派的內容。`tsc` 會檢查這個指派：每個項目要符合 `<todo-row>` 宣告的 `todo` 屬性型別並帶有 `data-key` 欄位（`id`），項目元件必須宣告 `data-prop` 指定的屬性；沒有 `data-key` 與 `data-prop` 的清單不接受指派。這要靠元件註冊在 `ts-dom-tags.ts`（掃描目錄內有匯出的 `define("todo-row", TodoRow)`）。元件定義在掃描目錄內、但類別沒有匯出，或 `ts-dom-tags.ts` 還沒列出它時，指派會是型別錯誤並說明原因（`itemComponentClassNotExported`、`itemComponentMissingFromTagMap`）；只有掃描目錄以外的元件，才接受任何帶有 `id` 欄位的項目。執行期則在指派的不是物件陣列、項目沒有字串或數字的 `id`、兩個項目 key 重複、或範本沒有 `data-key` 與 `data-prop` 時丟錯。
+
+在 `<ul>` 或 `<ol>` 裡，項目元件要加 `role="listitem"`，因為自訂元素不是 `<li>`；無障礙檢查（`list-structure`）會要求這點。`data-each` 刻意不能巢狀：一個項目就是一個元件，項目裡的清單就是該元件自己的 `data-each`。這樣每套範本都只有一層，有自己的 `refs`、`text` 與事件處理。
+
+### 項目是純元素：`replace()`
+
 ```html
 <ul>
   <template data-each="tags">
@@ -706,6 +760,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 +780,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-key` 與 `data-prop` 不完整或不合法、有 `data-key` 的清單其項目不是單一自訂元素、`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-Bn9pDvWV.mjs}

@@ -21,12 +21,27 @@ 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)",
 	"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 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 = () => ({
@@ -51,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(),
@@ -66,6 +82,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));
 	};
@@ -157,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);
@@ -176,6 +218,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++) {
@@ -231,15 +282,22 @@ 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} };
   ifs: ${union(a.scope.ifs)};
   slots: ${union(a.slots)};
+  rootElement: ${rootElementType(html)};
   text: ${union(a.scope.text)};
   events: ${union(a.events)};
 }`;
@@ -276,7 +334,7 @@ function generateFile(htmlPath, options = {}, 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);
+	const next = generateModule(html, options, imports, known);
 	let prev = "";
 	try {
 		prev = readFileSync(out, "utf8");
@@ -476,10 +534,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}`));
@@ -607,10 +665,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.`);
@@ -621,8 +679,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",

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-Bn9pDvWV.mjs";
+import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-CqWk4U5P.mjs";
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 // src/cli.ts

package/dist/index.d.mts

@@ -3,7 +3,48 @@ interface ListSchema {
   refs: Record<string, Element>;
   text: string;
   ifs: string;
+  /**
+   * Set for a list whose items are components (`data-key` and `data-prop`): the item tag, the property that receives the item, the field that identifies it,
+   * and where codegen found the component: defined and exported in a scanned directory, defined there without export, or not found (a component from elsewhere).
+   */
+  item?: {
+    tag: string;
+    prop: string;
+    key: string;
+    source?: "local" | "unexported" | "external";
+  };
 }
+type ItemOf<L> = L extends {
+  item: {
+    tag: infer T;
+    prop: infer P;
+  };
+} ? T extends keyof HTMLElementTagNameMap ? P extends keyof HTMLElementTagNameMap[T] ? NonNullable<HTMLElementTagNameMap[T][P]> : {
+  dataPropNotOnItemComponent: P;
+} : L extends {
+  item: {
+    source: "local";
+  };
+} ? {
+  itemComponentMissingFromTagMap: T;
+  fix: "run ts-dom gen so ts-dom-tags.ts lists it";
+} : L extends {
+  item: {
+    source: "unexported";
+  };
+} ? {
+  itemComponentClassNotExported: T;
+  fix: "export the class passed to define() so its type can be read";
+} : {
+  [field: string]: unknown;
+} : never;
+type KeyField<L> = L extends {
+  item: {
+    key: infer K extends string;
+  };
+} ? { [Q in K]: string | number; } : unknown;
+/** What `items` takes for a list: the type of the item component's `data-prop` property, with the `data-key` field. */
+type ListItem<L> = ItemOf<L> & KeyField<L>;
 type TextOf<N extends string> = { [K in N]: TextValue; };
 /** The per-item context passed to update(). */
 interface ItemContext<L extends ListSchema> {
@@ -31,9 +72,19 @@ export declare class List<L extends ListSchema = ListSchema> {
   private readonly proto;
   /** Called when a new item is created (the component uses it to register data-on-* inside the item) */
   private readonly onCreate?;
+  private readonly binding?;
   constructor(anchor: Comment, proto: Element,
   /** Called when a new item is created (the component uses it to register data-on-* inside the item) */
-  onCreate?: ((el: Element) => void) | undefined);
+  onCreate?: ((el: Element) => void) | undefined, binding?: {
+    readonly key: string;
+    readonly prop: string;
+  } | undefined);
+  /**
+   * The items shown, in order. Assigning shows them: an element is kept for each key that stays, created for a new key and removed for a key that is gone, and the `data-prop` property receives each item that is not the same object as last time.
+   * @throws When the template has no `data-key` and `data-prop`, when the value is not an array of objects, when an item has no string or number `data-key` field, or when two items have the same key
+   */
+  get items(): readonly ListItem<L>[];
+  set items(items: readonly ListItem<L>[]);
   /** From any node inside an item, find the key and data of the item it belongs to (used by event handlers). */
   itemOf(node: Node | null): {
     key: PropertyKey;
@@ -68,6 +119,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 +128,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`. */
@@ -239,4 +295,4 @@ type CheckHandlers<I> = I extends {
  * component as a public method, otherwise tsc reports an error that lists the missing names (`missingHandlers`).
  */
 export declare function define<C extends abstract new (...args: never[]) => HTMLElement>(name: string, ctor: C & CheckHandlers<InstanceType<C>>): void;
-export type { ComponentInstance, ComponentOptions, DataOptions, El, EmitEvent, EventDecl, EventHit, ItemContext, ListSchema, ReadableStore, ReplaceOptions, Schema, StatefulInstance, Store, Template, TemplateInstance, TextOf, TextValue, Update, View };
+export type { ComponentInstance, ComponentOptions, DataOptions, El, EmitEvent, EventDecl, EventHit, ItemContext, ListItem, ListSchema, ReadableStore, ReplaceOptions, Schema, StatefulInstance, Store, Template, TemplateInstance, TextOf, TextValue, Update, View };

package/dist/index.mjs

@@ -208,13 +208,44 @@ var List = class {
 	anchor;
 	proto;
 	onCreate;
+	binding;
 	#items = /* @__PURE__ */ new Map();
 	#byEl = /* @__PURE__ */ new WeakMap();
-	constructor(anchor, proto, onCreate) {
+	constructor(anchor, proto, onCreate, binding) {
 		this.anchor = anchor;
 		this.proto = proto;
 		this.onCreate = onCreate;
+		this.binding = binding;
 	}
+	/**
+	* The items shown, in order. Assigning shows them: an element is kept for each key that stays, created for a new key and removed for a key that is gone, and the `data-prop` property receives each item that is not the same object as last time.
+	* @throws When the template has no `data-key` and `data-prop`, when the value is not an array of objects, when an item has no string or number `data-key` field, or when two items have the same key
+	*/
+	get items() {
+		return [...this.#items.values()].sort((a, b) => a.el.compareDocumentPosition(b.el) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1).map((entry) => entry.item);
+	}
+	set items(items) {
+		if (!this.binding) throw new Error("[list-not-bound] this list has no data-key and data-prop, so its items cannot be assigned. Fix: add them to the <template data-each>, e.g. data-key=\"id\" data-prop=\"item\", or call replace().");
+		if (!Array.isArray(items)) throw new Error(`[invalid-items] items must be an array of objects, but got ${items === null ? "null" : typeof items}. Fix: assign an array, for example items = view.todos ?? [].`);
+		if (items.length) this.#checkProp();
+		this.replace(items, this.#keyOf, this.#assign, { skipUnchanged: true });
+	}
+	#checkProp() {
+		const prop = this.binding?.prop;
+		const tag = this.proto.localName;
+		if (!customElements.get(tag)) return;
+		if (!(prop in (this.#items.values().next().value?.el ?? document.importNode(this.proto, false)))) throw new Error(`[unknown-prop] <${tag}> has no "${prop}" property (data-prop). Fix: declare ${prop} in the component's props, or change data-prop.`);
+	}
+	#keyOf = (item) => {
+		const field = this.binding?.key;
+		if (typeof item !== "object" || item === null) throw new Error(`[invalid-item] an item is ${item === null ? "null" : typeof item}, but items must be objects with a "${field}" field (data-key). Fix: pass objects, or fill a list of plain values with replace().`);
+		const key = item[field];
+		if (typeof key !== "string" && typeof key !== "number") throw new Error(`[missing-key] an item has no usable "${field}" field (data-key): it is ${key === void 0 ? "missing" : typeof key}. Fix: give every item a string or number ${field}, or change data-key.`);
+		return key;
+	};
+	#assign = (item, { el }) => {
+		el[this.binding?.prop] = item;
+	};
 	/** From any node inside an item, find the key and data of the item it belongs to (used by event handlers). */
 	itemOf(node) {
 		for (let n = node; n; n = n.parentNode) {
@@ -272,13 +303,13 @@ var List = class {
 	}
 	#run(entry, key, item, update, skip = false) {
 		if (skip && !entry.fresh && Object.is(entry.item, item)) return;
-		entry.item = item;
-		entry.fresh = false;
 		this.#byEl.set(entry.el, {
 			key,
 			item
 		});
 		update(item, entry);
+		entry.item = item;
+		entry.fresh = false;
 	}
 	remove(key) {
 		const entry = this.#items.get(key);
@@ -296,7 +327,7 @@ var List = class {
 		const next = /* @__PURE__ */ new Set();
 		for (const it of items) {
 			const k = key(it);
-			if (next.has(k)) throw new Error(`[duplicate-key] replace() received two items with the key ${String(k)}, so one element cannot show both. Fix: make key() return a unique value for each item.`);
+			if (next.has(k)) throw new Error(`[duplicate-key] two items have the key ${String(k)}, so one element cannot show both. Fix: make the key unique for each item (the key() you pass to replace(), or the data-key field).`);
 			next.add(k);
 		}
 		for (const k of this.#items.keys()) if (!next.has(k)) this.remove(k);
@@ -332,7 +363,12 @@ function mountTemplate(frag, onItem) {
 		if (!proto) throw new Error(`[each-root-count] data-each="${name}" needs exactly one root element. Fix: wrap the item content in a single element such as <li>.`);
 		const anchor = document.createComment(`each:${name}`);
 		t.replaceWith(anchor);
-		lists[name] = new List(anchor, proto, onItem);
+		const key = t.getAttribute("data-key")?.trim();
+		const prop = t.getAttribute("data-prop")?.trim();
+		lists[name] = new List(anchor, proto, onItem, key && prop ? {
+			key,
+			prop
+		} : void 0);
 	}
 	const refs = {};
 	for (const el of frag.querySelectorAll("[data-ref]")) refs[el.getAttribute("data-ref")] = el;
@@ -357,7 +393,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 +760,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-CqWk4U5P.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-Bn9pDvWV.mjs";
 import { readFileSync } from "node:fs";
 import { basename, dirname, relative } from "node:path";
 // src/lib/lint.ts
@@ -98,7 +98,7 @@ function unusedMarkup(html, code) {
 	for (const n of dynText || stateful ? [] : a.scope.text) if (!used(`text\\.${esc(n)}\\b|text\\[\\s*["']${esc(n)}["']`)) add("unused-text", `{{ ${n} }} is never filled and will render empty. Fix: assign this.text.${n} = value, or declare "${n}" in state/props/derive so it binds automatically.`, `text:${n}`);
 	for (const [list, s] of a.lists) {
 		if (!dynLists && !used(`lists\\.${esc(list)}\\b|lists\\[\\s*["']${esc(list)}["']`)) {
-			add("unused-list", `data-each="${list}" is never rendered, so the list stays empty. Fix: call this.lists.${list}.replace(items, (item) => item.id, (item, ctx) => { ... }), for example inside render().`, `each:${list}`);
+			add("unused-list", `data-each="${list}" is never rendered, so the list stays empty. Fix: ${a.boundLists.has(list) ? `assign this.lists.${list}.items = items` : `call this.lists.${list}.replace(items, (item) => item.id, (item, ctx) => { ... })`}, for example inside render().`, `each:${list}`);
 			continue;
 		}
 		const items = [

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-Bn9pDvWV.mjs";
+import { a as dataFlow, i as contractsFor, l as templateCode, r as componentClasses, u as unusedMarkup } from "./lint-CqWk4U5P.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 // src/lib/oxlint-plugin.ts

package/dist/vite-plugin.d.mts

@@ -1,5 +1,5 @@
 export interface TsDomPluginOptions {
-  /** Directories to scan for .html files and generate .html.ts into. Default: ["src"] */
+  /** Directories to scan for .html files and generate .html.ts into, relative to Vite's root. Default: ["src"] */
   dirs?: string[];
   /** Module name the generated files import the runtime from. Default: "@nativele/ts-dom" */
   runtime?: string;
@@ -14,6 +14,24 @@ export interface TsDomPluginOptions {
     ignore?: string[];
   };
 }
+interface Logger {
+  error(m: string): void;
+  warn(m: string): void;
+}
+interface HotServer {
+  config: {
+    logger: Logger;
+  };
+  moduleGraph: {
+    getModulesByFile(f: string): Set<unknown> | undefined;
+    invalidateModule(m: unknown): void;
+  };
+  ws: {
+    send(payload: {
+      type: "full-reload";
+    }): void;
+  };
+}
 /**
  * Optional Vite plugin: generates `.html.ts` when the build starts and regenerates it while the dev server runs.
  * ts-dom does not depend on it: `ts-dom gen` (or `--watch`) together with tsc is enough.
@@ -21,6 +39,9 @@ export interface TsDomPluginOptions {
 export declare function tsDom(opts?: TsDomPluginOptions): {
   name: string;
   enforce: "pre";
+  configResolved(config: {
+    root: string;
+  }): void;
   buildStart(this: {
     error(m: string): never;
     warn(m: string): void;
@@ -31,10 +52,12 @@ export declare function tsDom(opts?: TsDomPluginOptions): {
       on(ev: string, fn: (f: string) => void): void;
     };
     config: {
-      logger: {
-        error(m: string): void;
-        warn(m: string): void;
-      };
+      logger: Logger;
     };
   }): void;
-};
+  handleHotUpdate(ctx: {
+    file: string;
+    server: HotServer;
+  }): never[] | undefined;
+};
+export {};

package/dist/vite-plugin.mjs

@@ -1,7 +1,10 @@
-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 { existsSync, readFileSync } from "node:fs";
+import { c as generateFile, d as listHtml, f as scanDefines, i as CodegenError, l as isFullPage, n as checkA11y, o as formatDiagnostics, s as generateAll, u as isSelected } from "./a11y-Bn9pDvWV.mjs";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { resolve, sep } from "node:path";
 // src/lib/vite-plugin.ts
+const GENERATED_HEADER = "// Generated by ts-dom.";
+const slashes = (file) => file.split(sep).join("/");
+const read = (file) => existsSync(file) ? readFileSync(file, "utf8") : null;
 /**
 * Optional Vite plugin: generates `.html.ts` when the build starts and regenerates it while the dev server runs.
 * ts-dom does not depend on it: `ts-dom gen` (or `--watch`) together with tsc is enough.
@@ -13,8 +16,20 @@ function tsDom(opts = {}) {
 		include: opts.include,
 		exclude: opts.exclude
 	};
-	const dirs = opts.dirs ?? ["src"];
 	const a11y = opts.a11y === true ? {} : opts.a11y || null;
+	let dirs = (opts.dirs ?? ["src"]).map((d) => resolve(d));
+	const shown = /* @__PURE__ */ new Map();
+	const defsByDir = /* @__PURE__ */ new Map();
+	const defsOf = (dir) => {
+		let defs = defsByDir.get(dir);
+		if (!defs) defsByDir.set(dir, defs = existsSync(dir) ? scanDefines(dir) : []);
+		return defs;
+	};
+	const isDefineFile = (file) => {
+		const dir = dirOf(file);
+		return dir !== void 0 && defsOf(dir).some((d) => resolve(d.file) === file);
+	};
+	const dirOf = (file) => dirs.find((d) => file.startsWith(d + sep));
 	const warnA11y = (warn) => {
 		if (!a11y) return;
 		for (const d of dirs) {
@@ -25,9 +40,57 @@ function tsDom(opts = {}) {
 			}
 		}
 	};
+	/** Regenerate one template. Returns whether its generated module changed. */
+	const regenerate = (file, logger) => {
+		const dir = dirOf(file);
+		const html = read(file);
+		if (!dir || html === null || file.includes(`${sep}node_modules${sep}`) || isFullPage(html) || !isSelected(dir, file, generate)) return false;
+		const out = `${file}.ts`;
+		const before = read(out);
+		try {
+			generateFile(file, generate, defsOf(dir));
+		} catch (e) {
+			if (e instanceof CodegenError) logger.error(e.message);
+			else throw e;
+			return false;
+		}
+		if (a11y) for (const diag of checkA11y(html, a11y.ignore)) logger.warn(formatDiagnostics(file, [diag]));
+		return read(out) !== before;
+	};
+	/** Regenerate a directory after a define() call may have changed: the tag map and the child imports of every template. */
+	const regenerateDir = (dir, logger) => {
+		const before = new Map(listHtml(dir).map((f) => [`${f}.ts`, read(`${f}.ts`)]));
+		try {
+			generateAll(dir, generate);
+		} catch (e) {
+			if (e instanceof CodegenError) logger.error(e.message);
+			else throw e;
+		}
+		defsByDir.set(dir, scanDefines(dir));
+		for (const [out, content] of before) {
+			const now = read(out);
+			if (now !== null && now !== content) shown.set(out, now);
+		}
+	};
+	const removeGenerated = (file) => {
+		const out = `${file}.ts`;
+		if (dirOf(file) && read(out)?.startsWith(GENERATED_HEADER)) unlinkSync(out);
+	};
+	const reload = (server, out) => {
+		const now = read(out);
+		if (now === null || shown.get(out) === now) return;
+		shown.set(out, now);
+		const loaded = server.moduleGraph.getModulesByFile(slashes(out));
+		if (!loaded?.size) return;
+		for (const m of loaded) server.moduleGraph.invalidateModule(m);
+		server.ws.send({ type: "full-reload" });
+	};
 	return {
 		name: "ts-dom",
 		enforce: "pre",
+		configResolved(config) {
+			dirs = (opts.dirs ?? ["src"]).map((d) => resolve(config.root, d));
+		},
 		buildStart() {
 			try {
 				for (const d of dirs) if (existsSync(d)) generateAll(d, generate);
@@ -38,24 +101,40 @@ function tsDom(opts = {}) {
 			warnA11y((m) => this.warn(m));
 		},
 		configureServer(server) {
-			const regen = (file) => {
-				if (!file.endsWith(".html") || file.includes("node_modules") || !existsSync(file)) return;
-				const html = readFileSync(file, "utf8");
-				if (isFullPage(html)) return;
-				const dir = dirs.find((d) => file.startsWith(resolve(d) + sep));
-				if (!dir || !isSelected(resolve(dir), file, generate)) return;
-				try {
-					generateFile(file, generate, dir);
-					if (a11y) for (const diag of checkA11y(html, a11y.ignore)) server.config.logger.warn(formatDiagnostics(file, [diag]));
-				} catch (e) {
-					if (e instanceof CodegenError) server.config.logger.error(e.message);
-					else throw e;
-				}
-			};
+			const logger = server.config.logger;
 			server.watcher.add(dirs);
-			server.watcher.on("change", regen);
-			server.watcher.on("add", regen);
+			server.watcher.on("add", (f) => {
+				const file = resolve(f);
+				const dir = dirOf(file);
+				if (file.endsWith(".html")) regenerate(file, logger);
+				else if (dir && isSourceTs(file) && read(file)?.includes("define(")) regenerateDir(dir, logger);
+			});
+			server.watcher.on("unlink", (f) => {
+				const file = resolve(f);
+				const dir = dirOf(file);
+				if (file.endsWith(".html")) removeGenerated(file);
+				else if (dir && isDefineFile(file)) regenerateDir(dir, logger);
+			});
+		},
+		handleHotUpdate(ctx) {
+			const file = resolve(ctx.file);
+			const logger = ctx.server.config.logger;
+			if (file.endsWith(".html.ts")) {
+				const now = read(file);
+				if (now !== null && shown.get(file) === now) return [];
+				if (now !== null) shown.set(file, now);
+				return;
+			}
+			if (file.endsWith(".html")) {
+				if (!dirOf(file)) return;
+				if (regenerate(file, logger)) reload(ctx.server, `${file}.ts`);
+				return [];
+			}
+			const dir = dirOf(file);
+			if (!dir || !isSourceTs(file)) return;
+			if (read(file)?.includes("define(") || isDefineFile(file)) regenerateDir(dir, logger);
 		}
 	};
 }
+const isSourceTs = (file) => file.endsWith(".ts") && !file.endsWith(".d.ts") && !file.endsWith(".html.ts") && !file.endsWith(`${sep}ts-dom-tags.ts`);
 export { tsDom };

package/llms.txt

@@ -65,7 +65,17 @@ 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.
+
+## Lists
+- Items that are components: `<template data-each="todos" data-key="id" data-prop="todo"><todo-row></todo-row></template>`, then `this.lists.todos.items = view.todos` (inside `render`, guarded by `changed.has("todos")`). Keeps the element of each key, creates and removes the rest, sets the `todo` prop of each changed item; `hit.key` in handlers. The item component declares `todo` in its `props`; `tsc` checks the items against that prop type and the `data-key` field; an item component defined in a scanned folder must be exported and listed in `ts-dom-tags.ts` (run `ts-dom gen`), otherwise the assignment is a type error that names the problem.
+- Items that are plain elements: `<template data-each="x">` with `this.lists.x.replace(items, keyFn, (item, { text, show }) => ...)`.
+- `data-each` is never nested: a list inside an item is the item component's own `data-each`.
+
+## Rules for agents
+- Never edit `x.html.ts` or `ts-dom-tags.ts` (generated). After any `.html` change run `npx ts-dom gen && npx tsc` and fix every type error instead of casting it away. Until `gen` has run, `tsc` only reports that `./x.html.js` is missing.
+- No expressions in HTML; computed values go in `derive`. Change state only with `this.set()`. Lists, attributes and focus go in `render(view, changed)`; check `changed.has("items")` before rebuilding a list.
+- Props go down (parent sets them), events go up (`emit`, handled with `data-on-<event>` on the child tag). `data-each` cannot be nested: make the inner list its own component.
 
 ## Setup
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativele/ts-dom",
-  "version": "0.2.1",
+  "version": "0.4.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",