@nativele/ts-dom 0.5.4 → 0.6.0

package/docs/lists.md

@@ -0,0 +1,150 @@
+# Lists
+
+Part of the [Nativele](../README.md) documentation.
+
+## Example: Todo list (lists, event delegation, `hit.key`)
+
+```html
+<form data-on-submit="add">
+  <input data-ref="input" aria-label="New todo" />
+  <button type="submit">Add</button>
+</form>
+<ul>
+  <template data-each="items">
+    <li>
+      <input type="checkbox" data-ref="check" data-on-change="toggle" />
+      <span>{{ title }}</span>
+      <button type="button" data-on-click="removeItem">Delete</button>
+    </li>
+  </template>
+</ul>
+<p>{{ remaining }} left</p>
+```
+
+```ts
+import { Component, define } from "@nativele/ts-dom";
+import type { EventHit } from "@nativele/ts-dom";
+import tpl from "./todo-list.html.js";
+
+interface Item {
+  id: number;
+  title: string;
+  done: boolean;
+}
+
+export class TodoList extends Component(tpl, {
+  state: { items: [] as Item[] },
+  derive: { remaining: (s) => s.items.filter((i) => !i.done).length },
+}) {
+  #nextId = 1;
+
+  add(e: Event): void {
+    e.preventDefault();
+    const title = this.refs.input.value.trim();
+    this.refs.input.value = "";
+    if (title) this.set((s) => ({ items: [...s.items, { id: this.#nextId++, title, done: false }] }));
+  }
+  toggle(_e: Event, hit: EventHit): void {
+    this.set((s) => ({ items: s.items.map((i) => (i.id === hit.key ? { ...i, done: !i.done } : i)) }));
+  }
+  removeItem(_e: Event, hit: EventHit): void {
+    this.set((s) => ({ items: s.items.filter((i) => i.id !== hit.key) }));
+  }
+
+  // Automatic binding handles {{ remaining }}; the list is filled here.
+  override render(view: { items: readonly Item[] }, changed: ReadonlySet<"items">): void {
+    if (!changed.has("items")) return;
+    this.lists.items.replace(
+      view.items,
+      (i) => i.id,
+      (i, { text, refs }) => {
+        text.title = i.title;
+        refs.check.checked = i.done;
+        refs.check.setAttribute("aria-label", `Done: ${i.title}`);
+      },
+      { skipUnchanged: true },
+    );
+  }
+}
+define("todo-list", TodoList);
+```
+
+- The `<template>` with `data-each` is the list item; automatic binding does not handle lists, so the list is filled in `render` with `replace`.
+- Events use delegation: for `data-on-change` and `data-on-click` inside a list item, the `hit.key` they receive is that item's key.
+- `{{ remaining }}` is a derived value and updates automatically.
+
+## Lists
+
+There are two ways to fill a list, and one rule decides between them: **an item that has anything of its own (state, events, a nested list) is a component, filled with `items =`; an item that is a few texts and `data-if` is plain elements, filled with `replace()`.** The README's second example shows the first, and the example at the top of this page the second.
+
+### 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<Todo, "id">) { /* hit.key is the item's id, typed Todo["id"]; hit.item is the Todo */ }
+```
+
+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 }`. Each item component receives its whole item through that one property; to give it more (whether it is selected, its rank), map the items to objects that carry it before assigning, for example `items.map((t) => ({ ...t, selected: t.id === selectedId }))`. 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`); a component from outside the scanned directories has no item type to check against, so the list accepts an object literal or a type alias with the `id` field, but rejects items typed by an interface (`Index signature for type 'string' is missing in type 'Tag'`): map them to new objects (`items.map((t) => ({ ...t }))`), or bring the component's tag map into the program (a component package exports it from its entry). 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">
+    <li><span>{{ label }}</span> <b data-if="hot">🔥</b></li>
+  </template>
+</ul>
+```
+
+```ts
+this.lists.tags.replace(
+  tags,
+  (t) => t.id, // key
+  (t, { text, refs, show, el }) => {
+    text.label = t.label;
+    show("hot", t.hot === true);
+  },
+);
+```
+
+| Method | Description |
+|---|---|
+| `replace(items, key, update, opts?)` | Keyed reconciliation: remove the extra items, create the missing ones, reorder in sequence, and call `update` for each item. With `opts.skipUnchanged: true`, `update` is skipped when the item reference is the same as last time (off by default: it is safe only when you use immutable updates; if you mutate objects directly, the view stays on the old value) |
+| `upsert(key, item, update)` | Add (at the end) or update a single item |
+| `remove(key)` | Remove a single item |
+| `clear()` | Clear everything |
+| `has(key)` / `get(key)` / `size` | Queries |
+
+`replace` only does one-dimensional key matching; the DOM nodes of existing items are kept and moved, and subtrees are not compared. The content of an item is entirely decided by your `update`.
+
+Notes:
+
+- `data-ref`, holes, and `data-if` inside an item belong to that item and do not appear in the component-level `refs` / `text`.
+- `data-if` cannot be placed on an item's root element; wrap it in one more layer.
+- `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.
+
+### Moving items, connecting and subscriptions
+
+- In a browser with `moveBefore`, a moved item stays connected: neither `disconnected()` nor `connected()` runs, and its focus, scroll position and subscriptions are untouched.
+- Without it (older browsers, and DOM implementations for tests such as happy-dom and jsdom), a moved item is removed and inserted again: `disconnected()` runs and releases everything registered with `bind`, `on` and `onCleanup`, then `connected()` runs again, and a focused input in it loses focus. Its element, props and state stay the same.
+- So subscribe in `connected()` (`this.bind(store, ...)`, `this.on(...)`), not in the constructor or a field initializer: then the subscription is made again after a move in every browser. A subscription made in the constructor is released by the first move and never comes back.
+- Data that every item needs (a theme, the current user, a registry) belongs in a `createStore` that the item component binds in `connected()`, not copied into every item object.
+
+### Order of list updates
+
+Assigning `items` sets the `data-prop` property of a new item before its element goes into the document, so the item component is connected with its item already set and its first render shows it. `replace()` and `upsert()` put a new item's element into the document first and then call `update`, so a child component placed in such an item is connected before the parent has set its properties; there, build per-item state when the child first receives data (for example in a property setter), and guard a render in `connected()` with the data it needs.

package/docs/performance.md

@@ -0,0 +1,24 @@
+# Performance
+
+Part of the [Nativele](../README.md) documentation.
+
+## Performance
+
+`npm run bench` runs a large list benchmark in real Chrome and prints this table. Each item shows one text; the times are the median of 5 runs and count script execution only (no layout or paint). They were measured on one machine (Chrome on WSL), so read them as proportions, not absolute numbers. "Direct DOM" is a hand-written keyed list with plain DOM calls, the floor any library adds to.
+
+| Approach | Items | Create | Update 10% | Reverse | Remove half | Append 1,000 |
+|---|---|---|---|---|---|---|
+| Components (`items =`) | 1,000 | 15.4 ms | 0.5 ms | 1.8 ms | 1.1 ms | 14.6 ms |
+| Components (`items =`) | 5,000 | 80.5 ms | 1.6 ms | 10 ms | 5.4 ms | 17.6 ms |
+| Components (`items =`) | 10,000 | 160.6 ms | 3.2 ms | 21 ms | 11.3 ms | 16 ms |
+| Plain elements (`replace()`) | 1,000 | 2.8 ms | 0.1 ms | 0.7 ms | 0.2 ms | 2.9 ms |
+| Plain elements (`replace()`) | 5,000 | 15.8 ms | 0.7 ms | 4.3 ms | 1.7 ms | 3.7 ms |
+| Plain elements (`replace()`) | 10,000 | 42 ms | 1.4 ms | 8.6 ms | 3.3 ms | 4.4 ms |
+| Direct DOM (baseline) | 1,000 | 0.8 ms | 0.2 ms | 1 ms | 0.3 ms | 0.8 ms |
+| Direct DOM (baseline) | 5,000 | 4 ms | 0.8 ms | 4.3 ms | 1.6 ms | 1.1 ms |
+| Direct DOM (baseline) | 10,000 | 8.7 ms | 1.7 ms | 10.9 ms | 3.9 ms | 1.6 ms |
+
+- Creating component items costs about 15 µs per item, because each item is a custom element with its own template, refs and lifecycle; plain elements cost about 3–4 µs and direct DOM about 1 µs.
+- Once the items exist, updating, reordering and removing them stay within about two times of direct DOM: only items that are a new object are touched, and kept elements are moved, not rebuilt.
+- A frame has about 16 ms. A list of a few thousand component items is comfortable; for tens of thousands, use plain elements with `replace()`, show a page or a window of the list at a time, or keep component items for the rows that need state and events.
+- Event delegation adds no listeners as the list grows.

package/docs/recipes.md

@@ -0,0 +1,189 @@
+# Recipes
+
+Patterns for common screens, built only from the library's own pieces. Every snippet comes from [examples/recipes](../examples/recipes), a contacts screen that `npm run check` type-checks and a real Chrome test drives.
+
+## Loading and error states
+
+Keep the request status as a union, derive one boolean per state you show, and let `data-if` show the matching block. `set` renders synchronously, so each step of the request shows at once.
+
+```ts
+// contacts.ts: a shared store, so several components can show the same data
+export type Status = "idle" | "loading" | "error" | "ready";
+export const contacts = createStore({ status: "idle" as Status, error: "", items: [] as readonly Contact[], nextId: 1 });
+
+export async function loadContacts(): Promise<void> {
+  contacts.set((s) => ({ ...s, status: "loading", error: "" }));
+  try {
+    const res = await fetch("/api/contacts");
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const items = (await res.json()) as Contact[];
+    contacts.set((s) => ({ ...s, status: "ready", items }));
+  } catch (e) {
+    contacts.set((s) => ({ ...s, status: "error", error: e instanceof Error ? e.message : String(e) }));
+  }
+}
+```
+
+```html
+<!-- contact-app.html -->
+<p data-if="loading">Loading...</p>
+<p role="alert" data-if="failed">Could not load: {{ error }} <button type="button" data-on-click="retry">Retry</button></p>
+```
+
+```ts
+// contact-app.ts
+export class ContactApp extends Component(tpl, {
+  state: { status: "idle", error: "", contacts: [], query: "" } as State,
+  derive: {
+    loading: (s) => s.status === "loading",
+    failed: (s) => s.status === "error",
+    // ...
+  },
+}) {
+  override connected(): void {
+    this.bind(contacts, (c) => this.set({ status: c.status, error: c.error, contacts: c.items }));
+    if (contacts.get().status === "idle") void loadContacts();
+  }
+  retry(): void {
+    void loadContacts();
+  }
+}
+```
+
+A store's `set` replaces the whole value, unlike a component's `this.set`, which merges; spread the rest yourself as above.
+
+## Showing data from a store
+
+When a component has `state`, `props` or `derive`, every `{{ hole }}` and `data-if` in its template must be one of them, and tsc reports any other name as `missing-binding`. To show a value from a store, `bind` the store and copy what the template shows into state:
+
+```html
+<!-- contact-stats.html -->
+<p>{{ total }} contacts</p>
+```
+
+```ts
+export class ContactStats extends Component(tpl, { state: { total: 0 } }) {
+  override connected(): void {
+    this.bind(contacts, (c) => this.set({ total: c.items.length }));
+  }
+}
+```
+
+The state holds only what this component shows; `bind` keeps it current and unsubscribes when the element leaves the page. A component with no options at all can write `this.text.total = ...` in the `bind` callback instead.
+
+## A filtered list
+
+Derive the visible items and assign them in `render`, guarded by the derived name: `changed` lists the derived values that changed as well as state and props. When two derived values need the same calculation, put it in a plain function, because a derived value cannot read another one.
+
+```ts
+const matching = (s: DeepReadonly<State>) => s.contacts.filter((c) => c.name.toLowerCase().includes(s.query.toLowerCase()));
+
+export class ContactApp extends Component(tpl, {
+  state: { status: "idle", error: "", contacts: [], query: "" } as State,
+  derive: {
+    visible: (s) => matching(s),
+    empty: (s) => s.status === "ready" && matching(s).length === 0,
+  },
+}) {
+  search(): void {
+    this.set({ query: this.refs.search.value });
+  }
+  override render(view: { visible: readonly Contact[] }, changed: ReadonlySet<"visible">): void {
+    if (changed.has("visible")) this.lists.visible.items = view.visible;
+  }
+}
+```
+
+Annotate `changed` with the names you check, not `ReadonlySet<string>`: a misspelled name, or one that is not state, a prop or a derived value, is then a tsc error.
+
+## Events from list items
+
+Name the item type and its key field in the handler's `EventHit`, and `hit.key` and `hit.item` are typed without a cast:
+
+```ts
+removeRow(_e: Event, hit: EventHit<Contact, "id">): void {
+  removeContact(hit.key); // number
+}
+```
+
+Use this form only for handlers on elements inside list items; elsewhere `hit.key` and `hit.item` are `undefined`.
+
+## A modal dialog
+
+Put a native `<dialog>` in the child's template and give the child a public method that opens it. The parent calls the method through its typed ref: a command (open, focus, reset) goes down as a method call, data goes down as props, and results come up as events.
+
+```html
+<!-- contact-form.html -->
+<dialog data-ref="dialog" aria-labelledby="contact-form-title">
+  <form data-ref="form" data-on-submit="submit" novalidate>
+    <h2 id="contact-form-title">New contact</h2>
+    ...
+    <button type="submit">Add</button>
+    <button type="button" data-on-click="cancel">Cancel</button>
+  </form>
+</dialog>
+```
+
+```ts
+// contact-form.ts
+export class ContactForm extends Component(tpl, {
+  state: { nameError: "", emailError: "" },
+  emits: { "contact-add": event<{ name: string; email: string }>() },
+}) {
+  open(): void {
+    this.refs.form.reset();
+    this.clearErrors();
+    this.refs.dialog.showModal();
+  }
+  cancel(): void {
+    this.refs.dialog.close();
+  }
+}
+```
+
+```html
+<!-- contact-app.html -->
+<button type="button" data-on-click="openForm">Add contact</button>
+<contact-form data-ref="form" data-on-contact-add="addRow"></contact-form>
+```
+
+```ts
+// contact-app.ts
+openForm(): void {
+  this.refs.form.open(); // refs.form is typed as ContactForm
+}
+addRow(e: Event): void {
+  const { name, email } = (e as EmitEvent<ContactForm, "contact-add">).detail;
+  addContact(name, email);
+}
+```
+
+## Form validation
+
+Keep each message in state, show it with `data-if`, and clear the messages as the user types. `novalidate` leaves validation to this code, and `role="alert"` announces the messages.
+
+```html
+<label>Name <input data-ref="name" name="name" data-on-input="clearErrors" /></label>
+<p role="alert" data-if="nameError">{{ nameError }}</p>
+<label>Email <input data-ref="email" name="email" type="email" data-on-input="clearErrors" /></label>
+<p role="alert" data-if="emailError">{{ emailError }}</p>
+```
+
+```ts
+clearErrors(): void {
+  this.set({ nameError: "", emailError: "" });
+}
+submit(e: Event): void {
+  e.preventDefault();
+  const name = this.refs.name.value.trim();
+  const email = this.refs.email.value.trim();
+  const nameError = name ? "" : "Name is required";
+  const emailError = /^\S+@\S+\.\S+$/.test(email) ? "" : "Enter a valid email";
+  this.set({ nameError, emailError });
+  if (nameError || emailError) return;
+  this.emit("contact-add", { name, email });
+  this.refs.dialog.close();
+}
+```
+
+For larger forms, a schema library can produce the messages; the component still keeps them in state and shows them the same way. The `nativele-zod` Skill (`npx ts-dom skills nativele-zod`) does it with Zod or Valibot, including nested and array fields. Two details hold for any form: `aria-invalid` must be `"true"` (an empty `aria-invalid=""` counts as not invalid), and validating on blur needs `data-on-focusout` on the form, because `blur` does not bubble.

package/docs/templates.md

@@ -0,0 +1,73 @@
+# Templates
+
+Part of the [Nativele](../README.md) documentation.
+
+## HTML Syntax
+
+There are only a few kinds of markup, plus one kind of hole.
+
+| Markup | Meaning | TS side |
+|---|---|---|
+| `data-ref="name"` | Get the element; the type is derived from the tag | `this.refs.name` |
+| `data-if="name"` | Conditional block, **hidden by default** (removed from the DOM); shown only when TS says so | `this.show("name", bool)` |
+| `<template data-each="name">` | List; the content must be exactly one root element | `this.lists.name` |
+| `<slot name="x">` | Slot | The user provides child nodes with `slot="x"` |
+| `{{ name }}` | Text hole; the same name may appear in multiple places | `this.text.name = value`, or bound automatically from `state` |
+| `data-on-click="method"` | Event: calls the component method of that name (event names must be lowercase) | `method(e, hit)`, see [Events](components.md#events-data-on-) |
+
+Rules for holes:
+
+- A hole must be a single identifier. `{{ data.name }}` and `{{ a + 1 }}` cause an error at codegen time.
+- Holes are only for text nodes; they are not supported inside attributes (`title="{{ x }}"` is an error). When needed, get the element with `data-ref` and set it in TS.
+- Content inside `<style>` and `<script>` is not treated as holes.
+- A value of `null`, `undefined`, or `false` is displayed as an empty string.
+
+A hidden `data-if` block is kept in memory, not destroyed: `refs` and holes inside it stay usable while it is hidden, so you can fill a form before showing it, and showing it again puts back the same elements with their state.
+
+## How Types Are Generated
+
+Next to each `x.html`, an `x.html.ts` is generated (a `ts-dom-tags.ts` is generated as well, see [Composition](components.md#composition-using-multiple-components-together)); add `*.html.ts` and `ts-dom-tags.ts` to `.gitignore`, since both are rebuilt by `ts-dom gen`. It is a real TS module that contains both the parsed markup of this template (as data that the runtime turns into DOM nodes with DOM calls, so no HTML string is parsed in the browser) and its schema, so `tsc` can compile and check it directly.
+
+```ts
+// user-card.html.ts (auto-generated)
+import { template } from "@nativele/ts-dom";
+import type { El } from "@nativele/ts-dom";
+export default template<{
+  refs: { "toggle": El<"button"> };
+  lists: { "tags": { refs: Record<never, never>; text: "label"; ifs: "hot" } };
+  ifs: "admin";
+  slots: "extra";
+  text: "name";
+}>([["h2", {}, ["Hello, {{ name }}!"]], /* ... */]);
+```
+
+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`.
+
+## Templates Without a Component
+
+`tpl.instantiate()` builds a template without a custom element and returns the same typed handles a component has: `root` (a `DocumentFragment`), `refs`, `lists`, `text` and `show`. Use it for small pieces created in code, such as a menu item added to a list:
+
+```ts
+import itemTpl from "./menu-item.html.js";
+
+function menuItem(label: string): HTMLLIElement {
+  const view = itemTpl.instantiate();
+  view.text.label = label;
+  view.refs.button.addEventListener("click", () => select(label));
+  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.
+
+## 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.
+- Translations: ts-dom has no i18n. Write the translated string into a hole, `this.text.title = t("title")`, or into `render()` for attributes; the HTML stays free of words if you want it that way.
+- Icons: ts-dom does not manage icons. Make an icon a custom element of your own that builds its SVG with `createElementNS` from whatever source you use, and place it in a template as a child component:
+
+```html
+<app-icon name="send" class="size-4"></app-icon>
+```