@nativele/ts-dom 0.5.0 → 0.5.2

package/skills/nativele-vue/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: nativele-vue
+description: "Use Nativele web components inside a Vue 3 app: telling the template compiler which tags are custom elements, passing props, listening to events, replacing v-model, children and slots, lifecycle with v-for, v-if and KeepAlive, and SFC template types. Use when a project depends on vue and @nativele/ts-dom."
+metadata:
+  tier: official
+  nativele: ">=0.5.1 <0.6.0"
+  verified: "2026-11-05"
+  tools: "vue@3.5.44 vite@8.3.6 @vitejs/plugin-vue@6.0.10 vue-tsc@3.3.14 typescript@6.0.3 @vue/tsconfig@0.9.1"
+  author: "Nativele maintainers"
+  detects: "vue"
+---
+
+# Nativele + Vue
+
+## When to use
+
+- The project renders with Vue 3 single-file components and wants to use components written with Nativele (`@nativele/ts-dom`), for example a design-system layer or widgets shared with non-Vue pages.
+- Signals: `vue` and `@nativele/ts-dom` in `package.json`, `.vue` templates that render Nativele tags (`<nv-info-card>`).
+- The starting point is a working Vue app, such as the one `npm create vite@latest -- --template vue-ts` makes. This Skill does not set Vue or Vite up.
+- Not for Vue 2, and not for Vue's own `defineCustomElement` (that turns Vue components into custom elements; this Skill goes the other way). Not for writing the Nativele components themselves: use `nativele-core` (`npx ts-dom skills add nativele-core`).
+
+Nativele components are native custom elements. Vue renders them like any other element; nothing wraps them.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.1 |
+| vue | 3.5.44 |
+| vite | 8.3.6 |
+| @vitejs/plugin-vue | 6.0.10 |
+| vue-tsc | 3.3.14 |
+| typescript | 6.0.3 |
+| @vue/tsconfig | 0.9.1 |
+
+Verified on 2026-11-05 in Google Chrome 148, starting from `create-vite` 9.3.4 with the `vue-ts` template, with the example project in the Nativele repository (`skills/nativele-vue/example`), which CI runs again when the example or the library changes and once a month. With a different major version of Vue, treat every step as unverified.
+
+## Set-up
+
+1. Keep the Nativele components in their own folder, for example `src/nv/`, each as `x.html` plus `x.ts`, written with the core Skill (`npx ts-dom skills add nativele-core`). Give every Nativele tag one prefix that no Vue component uses, for example `nv-` (`define("nv-info-card", InfoCard)`); step 4 depends on it.
+2. Install: `npm i @nativele/ts-dom`.
+3. Keep `"strict": true` for that folder. In the `vue-ts` template, `tsconfig.app.json` extends `@vue/tsconfig/tsconfig.dom.json`, which already sets it; if the project turned it off, turn it on there. Nativele's type checks depend on it.
+4. Add the Nativele Vite plugin, and tell Vue's template compiler that the tags with the prefix are custom elements:
+
+   ```ts
+   // vite.config.ts
+   import vue from "@vitejs/plugin-vue";
+   import { defineConfig } from "vite";
+   import { tsDom } from "@nativele/ts-dom/vite";
+
+   export default defineConfig({
+     plugins: [tsDom({ dirs: ["src/nv"] }), vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("nv-") } } })],
+   });
+   ```
+
+   Match the prefix only, never every hyphenated tag (limitation 1). Pass the same folder to every `ts-dom` command (`npx ts-dom check src/nv`), so there is one `ts-dom-tags.ts`, in `src/nv`.
+
+5. Add `*.html.ts` and `ts-dom-tags.ts` to `.gitignore`: `ts-dom` writes them, and they are not committed.
+6. Import every Nativele component module in `src/main.ts`, before `createApp(...).mount(...)`:
+
+   ```ts
+   // src/main.ts
+   import "./nv/info-card.js";
+   import "./nv/text-field.js";
+   import { createApp } from "vue";
+   import App from "./App.vue";
+
+   createApp(App).mount("#app");
+   ```
+
+   Vue sets a binding as a property only when the element already has that property, which is true only after `define()` has run (limitation 2).
+
+7. Add the template type declaration below as `src/nativele-vue.d.ts` (the template's `tsconfig.app.json` already includes `src/**/*.ts`). It reads the tag map that `ts-dom gen` writes (`ts-dom-tags.ts`), so every exported component gets typed props and events in SFC templates, and new components need no edit:
+
+   ```ts
+   // src/nativele-vue.d.ts
+   import type { HTMLAttributes } from "vue";
+
+   type NativeleTag = Extract<keyof HTMLElementTagNameMap, `${string}-${string}`>;
+   type Camelize<S extends string> = S extends `${infer A}-${infer B}` ? `${A}${Capitalize<Camelize<B>>}` : S;
+   type NativeleProps<E> = E extends { readonly props: infer P } ? { [K in keyof P & keyof E]?: E[K] } : unknown;
+   type NativeleEvents<E> = E extends { readonly "~emits"?: infer M }
+     ? { [K in keyof NonNullable<M> & string as `on${Capitalize<Camelize<K>>}`]?: (event: CustomEvent<NonNullable<M>[K]>) => void }
+     : unknown;
+   type NativeleComponents = {
+     [K in NativeleTag]: new () => {
+       $props: HTMLAttributes & NativeleProps<HTMLElementTagNameMap[K]> & NativeleEvents<HTMLElementTagNameMap[K]>;
+     };
+   };
+
+   declare module "vue" {
+     interface GlobalComponents extends NativeleComponents {}
+   }
+   ```
+
+   The component class must be exported and passed to `define()` in a folder that `ts-dom gen` scans, so it appears in `ts-dom-tags.ts`. A template ref is typed from the same map: `useTemplateRef<HTMLElementTagNameMap["nv-info-card"]>("card")`.
+
+The generated files are not committed, so on a clean checkout the type check in `npm run build` runs before anything has written them and fails with `TS2307: Cannot find module './x.html.js'`. Generate them first: `"build": "ts-dom gen src/nv && vue-tsc -b && vite build"` (the template's script with `ts-dom gen src/nv &&` in front).
+
+## Example
+
+A Nativele component with props and an event:
+
+```html
+<!-- src/nv/info-card.html -->
+<span>{{ label }}</span>
+<b>{{ count }}</b>
+<i data-ref="itemName"></i>
+<button type="button" data-on-click="pick">pick</button>
+```
+
+```ts
+// src/nv/info-card.ts
+import { Component, define, event } from "@nativele/ts-dom";
+import tpl from "./info-card.html.js";
+
+export interface Item {
+  id: number;
+  name: string;
+}
+
+export class InfoCard extends Component(tpl, {
+  props: { label: "", count: 0, item: null as Item | null },
+  emits: { "item-select": event<{ id: number }>() },
+}) {
+  pick(): void {
+    const item = this.props.item;
+    if (item) this.emit("item-select", { id: item.id });
+  }
+  override render(view: { item: Item | null }): void {
+    this.refs.itemName.textContent = view.item ? view.item.name : "-";
+  }
+}
+define("nv-info-card", InfoCard);
+```
+
+A field that takes the place of `v-model`: a `value` prop down, a `value-change` event up.
+
+```html
+<!-- src/nv/text-field.html -->
+<input data-ref="input" data-on-input="onInput" />
+```
+
+```ts
+// src/nv/text-field.ts
+import { Component, define, event } from "@nativele/ts-dom";
+import tpl from "./text-field.html.js";
+
+export class TextField extends Component(tpl, {
+  props: { value: "" },
+  emits: { "value-change": event<{ value: string }>() },
+}) {
+  onInput(): void {
+    this.emit("value-change", { value: this.refs.input.value });
+  }
+  override render(view: { value: string }): void {
+    if (this.refs.input.value !== view.value) this.refs.input.value = view.value;
+  }
+}
+define("nv-text-field", TextField);
+```
+
+Used from a Vue component:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import type { Item } from "./nv/info-card.js";
+
+const count = ref(0);
+const item = ref<Item>({ id: 1, name: "apple" });
+const picked = ref<number[]>([]);
+const text = ref("");
+</script>
+
+<template>
+  <nv-info-card label="Fruit" :count="count" :item="item" @item-select="(e) => picked.push(e.detail.id)" />
+  <nv-text-field :value="text" @value-change="(e) => (text = e.detail.value)" />
+</template>
+```
+
+- `label`, `count` and `item` arrive as properties; the object is the same object Vue passed, and the element has no `item` attribute. Changing them from Vue state re-renders the Nativele component.
+- `@item-select` uses the exact event name; `e.detail` is typed from the component's `emits`.
+
+Children and slots: a `shadow: true` component takes Vue children directly; a Light DOM component (the default) takes one stable element per slot, with Vue changing only what is inside it.
+
+```html
+<!-- src/nv/shadow-card.html (and the same in src/nv/light-card.html) -->
+<h2><slot name="title">Untitled</slot></h2>
+<div><slot></slot></div>
+```
+
+```ts
+// src/nv/shadow-card.ts
+export class ShadowCard extends Component(tpl, { shadow: true }) {}
+define("nv-shadow-card", ShadowCard);
+
+// src/nv/light-card.ts
+export class LightCard extends Component(tpl) {}
+define("nv-light-card", LightCard);
+```
+
+```vue
+<nv-shadow-card>
+  <span v-if="showTitle" slot="title">{{ title }}</span>
+  <p v-for="r in rows" :key="r.id">{{ r.text }}</p>
+</nv-shadow-card>
+
+<nv-light-card>
+  <div slot="title"><span v-if="showTitle">{{ title }}</span></div>
+  <div><p v-for="r in rows" :key="r.id">{{ r.text }}</p></div>
+</nv-light-card>
+```
+
+## Known limitations
+
+1. **`isCustomElement` must match only the Nativele tags.** With `(tag) => tag.includes("-")`, every kebab-case Vue component (an SFC used as `<hello-box>`, `<router-view>`) stops resolving: it renders as an empty unknown element, with no warning. Use the prefix from step 1. Without `isCustomElement` at all, Nativele tags still render and work, but Vue logs `[Vue warn]: Failed to resolve component: nv-info-card` for each tag in development.
+2. **Define before mount.** Import every Nativele module before `mount()` (step 6). A `:item` binding on an element that is not defined yet becomes the attribute `item="[object Object]"`, and the component gets `null` after `define()` runs. When a module really is loaded later (a dynamic `import()`), bind object props with the property modifier, `.item="item"` (or `:item.prop="item"`): the property is kept and the component takes it over when it is defined.
+3. **camelCase prop names in templates.** Write Nativele props as they are declared: `:selectedItem="item"`, `:maxCount="3"`. Vue sets a kebab-case binding (`:selected-item`) as an attribute, because the element has no property of that name: a number or string still converts from the attribute, an object or array arrives as `"[object Object]"` and the prop stays `null`. `vue-tsc` does not report this (limitation 8).
+4. **Exact event names.** On a custom element, Vue listens to the event name exactly as written after `@`: `@item-select` hears `item-select`, `@pickedOne` hears `pickedOne`, and `@itemSelect` never hears `item-select`. Name events in kebab-case and write that name. Nativele events do not bubble by default, so the listener goes on the element that emits.
+5. **`v-model` does not work on a Nativele component.** It compiles, `vue-tsc` accepts it and Vue logs no warning; it writes the first value into the element, but typing never updates the Vue state. Use a prop and an event, as `nv-text-field` above: `:value="text" @value-change="(e) => (text = e.detail.value)"`. In the component, compare before writing the input's value, so the cursor does not jump (see "A Small Reminder About Form Inputs" in the components guide).
+6. **Light DOM slots and Vue children do not mix.** In the default Light DOM mode, Nativele moves the host's children into its slot positions. When Vue later inserts, removes or reorders those children (`v-if`, `v-for`), the update throws (`Cannot read properties of null (reading 'insertBefore')`, `Cannot set properties of null (setting '__vnode')`) and the slots show the wrong children. Use `shadow: true`, or one stable element per slot as in the example. A stable but empty wrapper still fills its slot, so the slot's fallback content does not show; when the fallback matters, use `shadow: true`.
+7. **Lifecycle follows the DOM.** When a keyed `v-for` reorders Nativele elements, Vue moves the same element with `insertBefore`: it runs `disconnected()` then `connected()`, keeps its props and its Light DOM slot children, and `bind` subscriptions end and start again. `<KeepAlive>` deactivation takes the element out of the document (`disconnected()`, no store updates while inactive); activation puts the same element back (`connected()`, and `bind` calls back at once with the current value). `v-if` removal runs `disconnected()` and ends the subscriptions. So subscribe in `connected()`, as the lists guide says for moved items.
+8. **What `vue-tsc` checks.** With the declaration from step 7, it reports a wrong prop type (`count="1"` on a number prop), a wrong object shape and a wrong use of `e.detail`. It does not report an unknown prop name, an unknown tag with the prefix, a kebab-case prop name, `v-model`, or an event name whose case differs from the declared one. In a template, mark an expected error with `<!-- @vue-expect-error -->`; `// @ts-expect-error` is rendered as text and suppresses nothing.
+9. Not verified: server-side rendering and hydration, Nuxt, `<Transition>` around Nativele elements, and Vue versions other than 3.5.
+
+## Verify
+
+Run in the project:
+
+```sh
+npx ts-dom check src/nv      # expect: ts-dom check: no issues
+npx ts-dom doctor src/nv     # expect: ts-dom doctor: the set-up looks right (info lines are suggestions)
+npx vue-tsc -b               # expect: no output
+npx vite build               # expect: built
+```
+
+`ts-dom check` runs `vue-tsc` instead of `tsc` when `vue-tsc` is installed, so it also reports type errors in `.vue` files.
+
+Prove that the declaration types props: keep a `.vue` file that the app never imports (the example uses `src/TypesCheck.vue`) with one wrong case per kind under `<!-- @vue-expect-error -->`:
+
+```vue
+<template>
+  <!-- @vue-expect-error count is a number -->
+  <nv-info-card count="1" />
+  <!-- @vue-expect-error item has the wrong shape -->
+  <nv-info-card :item="{ id: '1' }" />
+  <!-- @vue-expect-error detail is { id: number } -->
+  <nv-info-card @item-select="(e) => e.detail.name" />
+</template>
+```
+
+`vue-tsc -b` passes only while each of these is an error; if the declaration stops working, it reports `TS2578: Unused '@ts-expect-error' directive`.
+
+In the browser, against the dev server (production builds drop Vue warnings), check that an element with an object prop has no attribute for it (`el.getAttributeNames()`) and that `el.item` is the object, that the listener runs once per event, that a kebab-case Vue component still renders, and that there are no errors or `[Vue warn]` lines in the console. The example project's [`verify.mjs`](https://github.com/Pixmi/nativele/blob/main/skills/nativele-vue/example/verify.mjs) does these checks with Playwright, plus the `v-model` replacement, a component defined after mount, children that Vue reorders, adds and removes in both slot modes, and the lifecycle under `v-for`, `<KeepAlive>` and `v-if`. A Light DOM component has no `<slot>` elements once rendered; read a slot with `el.assignedNodes(name)`, where `""` is the default slot, and compare elements only, because Vue leaves comment and empty text nodes among the children.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `TS2307: Cannot find module './x.html.js'` from `npm run build` on a clean checkout | `vue-tsc -b` runs before the generated files exist | start the script with `ts-dom gen src/nv &&` |
+| `[Vue warn]: Failed to resolve component: nv-info-card` | `isCustomElement` is missing, or does not match the tag | set it as in step 4, with the prefix your tags use |
+| A kebab-case Vue component (`<hello-box>`, `<router-view>`) renders as an empty element, with no warning | `isCustomElement` matches every hyphenated tag | match only the Nativele prefix (`tag.startsWith("nv-")`) |
+| An object prop shows `[object Object]`, or the element has an attribute holding it | the element was not defined when Vue rendered it, or the prop is written in kebab-case | import the module before `mount()`; write `:selectedItem`, not `:selected-item`; for a module loaded later, use `.item` |
+| The event listener never runs | the name after `@` differs from the emitted name (`@itemSelect` for `item-select`) | write the exact event name |
+| The Vue value bound with `v-model` never changes | `v-model` does not work on custom elements like this | a prop plus an event (limitation 5) |
+| `Cannot read properties of null (reading 'insertBefore')` or `(setting '__vnode')`, children in the wrong slot | Vue changed children of a Light DOM component with slots | `shadow: true`, or a stable element per slot |
+| `TS7006: Parameter 'e' implicitly has an 'any' type` in an `@item-select` handler, wrong props not reported | the declaration is missing, or the component class is not exported | add `src/nativele-vue.d.ts`, export the class, run `ts-dom gen` |
+| `TS1117: An object literal cannot have multiple properties with the same name` | two spellings of one event on the same element (`@picked-one` and `@pickedOne` are both `onPickedOne` in the types) | keep one, with the exact event name |
+| `ts-dom check` reports `TS2307: Cannot find module './App.vue'` | `vue-tsc` is not installed, so `ts-dom check` runs plain `tsc` | keep `vue-tsc` in `devDependencies` |
+| `ts-dom check` reports `unused-ref` | a `data-ref` the class never reads | use it in the class or remove the attribute |
+
+## See also
+
+- Components, props and events: https://github.com/Pixmi/nativele/blob/main/docs/components.md#data-flow-props-down-events-up
+- Form inputs written from `render`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#a-small-reminder-about-form-inputs
+- Slots, Light DOM and Shadow DOM: https://github.com/Pixmi/nativele/blob/main/docs/components.md#light-default-and-shadow
+- Moved elements, connecting and subscriptions: https://github.com/Pixmi/nativele/blob/main/docs/lists.md#moving-items-connecting-and-subscriptions
+- Setup, the Vite plugin and checks: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md

package/skills/nativele-zod/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: nativele-zod
+description: "Validate a form inside a Nativele component with Zod 4 (or Valibot 1): read the values on submit and on blur, safeParse, map issue paths (also nested and array fields) to per-field messages in state shown with data-if, set aria-invalid and aria-describedby, focus the first invalid field, and emit the parsed data typed with z.infer. Use when a project depends on zod or valibot and @nativele/ts-dom."
+metadata:
+  tier: experimental
+  nativele: ">=0.5.2 <0.6.0"
+  verified: "2026-11-05"
+  tools: "zod@4.6.7 valibot@1.5.0 vite@8.3.6 typescript@7.0.2 create-vite@9.3.4"
+  author: "Nativele maintainers"
+  detects: "zod valibot"
+---
+
+# Nativele + Zod
+
+## When to use
+
+- An app that already uses Nativele (`@nativele/ts-dom`) validates a form inside a Nativele component with a schema library: on submit, and optionally when a field loses focus.
+- Signals: `zod` (or `valibot`) and `@nativele/ts-dom` in `package.json`, a component template with a `<form>`.
+- The form has more than a few fields, nested groups (`address.city`), or a repeated field (a list of guest emails). For two or three fields, the hand-written checks in the form validation recipe are enough (See also).
+- Not for learning Zod or Valibot: this Skill covers only how their result reaches a Nativele component. Not for setting up Nativele in Vite (`npx ts-dom skills add nativele-vite`) or writing components in general (`npx ts-dom skills add nativele-core`).
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.2 |
+| zod | 4.6.7 (the procedure was also run with 3.25.76, with the schema changes in limitation 10) |
+| valibot | 1.5.0 (limitation 11) |
+| vite | 8.3.6 |
+| typescript | 7.0.2 |
+| create-vite (`vanilla-ts` template, the starting point) | 9.3.4 |
+
+Verified on 2026-11-05 in Google Chrome 148, with Playwright against both the Vite dev server and `vite preview` of the production build, in a fresh `npm create vite@latest -- --template vanilla-ts` app set up with Nativele by the `nativele-vite` Skill (components in `src/nv/`). Zod 4 is the current major and the one these steps use. With a different major version of Zod or Valibot, treat every step as unverified.
+
+## Set-up
+
+Start from a Vite app that already uses Nativele, with the components in `src/nv/` and `npx ts-dom check src/nv` passing.
+
+1. `npm i zod`.
+2. Keep the schema in its own module next to the component, together with one function that runs `safeParse` and turns the issues into a map from path to message (`signup.ts` in the Example). The component imports only that function and the inferred type, so it never handles Zod objects, and a schema change touches one file.
+3. In the template, give every input a `name` equal to its path in the schema, with dots for nested fields (`name="address.city"`), and the same `name` for every input of an array field (`name="guests"`). After each field, put one message element with an `id`, a `data-if` and a hole, both named `<field>Error` (`<p id="signup-city-error" data-if="cityError">{{ cityError }}</p>`). Add `novalidate` to the `<form>` so the browser does not show its own messages first.
+4. In the component, keep all messages in one state field, `errors`, a map from the dot path to the message, and add one `derive` entry per message element that reads its path (`cityError: (s) => s.errors["address.city"] ?? ""`). Holes and `data-if` take a single name, never a path, so the derived names are what the template sees, and one `set({ errors })` updates every message at once.
+5. Read the values in the handler with `FormData`, building the object the schema expects field by field (limitation 2), and pass it to the function from step 2:
+   - on `submit`: `preventDefault()`, validate, `set({ errors })`, then focus the first `[aria-invalid=true]` in the form (rendering is synchronous, so the attributes are already set); when valid, clear `errors` and `emit` the parsed data;
+   - on `focusout` of the form (optional): validate the whole form and copy only the message of the field that lost focus;
+   - on `input` of the form: clear the message of the field being edited.
+6. In `render`, set `aria-invalid` and `aria-describedby` on each input from `view.errors`, and fill the messages of array items in the list's `replace` callback.
+7. Declare the event with the inferred output type: `emits: { "signup-submit": event<Signup>() }`, where `type Signup = z.infer<typeof SignupSchema>`. The parent then gets the parsed values (here `age` is a `number`), and `emit` with the raw form values is a tsc error.
+
+## Example
+
+The example links each message by `id`. For a form that can appear more than once on a page, link them with refs instead (limitation 6).
+
+```ts
+// src/nv/signup.ts
+import { z } from "zod";
+
+export const SignupSchema = z.object({
+  name: z.string().trim().min(1, "Name is required"),
+  email: z.email("Enter a valid email"),
+  age: z.string().min(1, "Age is required").pipe(z.coerce.number<string>("Enter a number").int("Whole years only").min(18, "You must be 18 or older")),
+  address: z.object({ city: z.string().trim().min(1, "City is required") }),
+  guests: z.array(z.email("Enter a valid email")).max(3, "At most 3 guests"),
+  terms: z.boolean().refine((v) => v, "Accept the terms"),
+});
+
+export type Signup = z.infer<typeof SignupSchema>;
+export type Errors = Readonly<Record<string, string>>;
+
+export function validateSignup(input: unknown): { ok: true; data: Signup } | { ok: false; errors: Errors } {
+  const result = SignupSchema.safeParse(input);
+  if (result.success) return { ok: true, data: result.data };
+  const errors: Record<string, string> = {};
+  for (const issue of result.error.issues) errors[issue.path.join(".")] ??= issue.message;
+  return { ok: false, errors };
+}
+```
+
+```html
+<!-- src/nv/signup-form.html -->
+<form data-ref="form" data-on-submit="submit" data-on-focusout="check" data-on-input="clearError" novalidate>
+  <label>Name <input data-ref="name" name="name" autocomplete="name" /></label>
+  <p id="signup-name-error" data-if="nameError">{{ nameError }}</p>
+  <label>Email <input data-ref="email" name="email" type="email" /></label>
+  <p id="signup-email-error" data-if="emailError">{{ emailError }}</p>
+  <label>Age <input data-ref="age" name="age" inputmode="numeric" /></label>
+  <p id="signup-age-error" data-if="ageError">{{ ageError }}</p>
+  <label>City <input data-ref="city" name="address.city" /></label>
+  <p id="signup-city-error" data-if="cityError">{{ cityError }}</p>
+  <ul>
+    <template data-each="guests">
+      <li>
+        <label>Guest email <input data-ref="guest" name="guests" /></label>
+        <button type="button" data-on-click="removeGuest">Remove</button>
+        <span data-ref="guestMsg" data-if="invalid">{{ message }}</span>
+      </li>
+    </template>
+  </ul>
+  <p id="signup-guests-error" data-if="guestsError">{{ guestsError }}</p>
+  <button type="button" data-on-click="addGuest">Add guest</button>
+  <label><input data-ref="terms" name="terms" type="checkbox" /> I accept the terms</label>
+  <p id="signup-terms-error" data-if="termsError">{{ termsError }}</p>
+  <button type="submit">Sign up</button>
+</form>
+```
+
+```ts
+// src/nv/signup-form.ts
+import { Component, define, event } from "@nativele/ts-dom";
+import type { DeepReadonly, EventHit } from "@nativele/ts-dom";
+import { validateSignup, type Errors, type Signup } from "./signup.js";
+import tpl from "./signup-form.html.js";
+
+interface State {
+  errors: Errors;
+  guests: readonly { id: number }[];
+}
+
+function readForm(form: HTMLFormElement): unknown {
+  const data = new FormData(form);
+  return {
+    name: data.get("name"),
+    email: data.get("email"),
+    age: data.get("age"),
+    address: { city: data.get("address.city") },
+    guests: data.getAll("guests"),
+    terms: data.has("terms"),
+  };
+}
+
+function pathOf(form: HTMLFormElement, input: HTMLInputElement): string {
+  if (input.name !== "guests") return input.name;
+  return `guests.${[...form.querySelectorAll("[name=guests]")].indexOf(input)}`;
+}
+
+export class SignupForm extends Component(tpl, {
+  state: { errors: {}, guests: [] } as State,
+  derive: {
+    nameError: (s) => s.errors["name"] ?? "",
+    emailError: (s) => s.errors["email"] ?? "",
+    ageError: (s) => s.errors["age"] ?? "",
+    cityError: (s) => s.errors["address.city"] ?? "",
+    guestsError: (s) => s.errors["guests"] ?? "",
+    termsError: (s) => s.errors["terms"] ?? "",
+  },
+  emits: { "signup-submit": event<Signup>() },
+}) {
+  #nextGuest = 1;
+
+  addGuest(): void {
+    this.set((s) => ({ guests: [...s.guests, { id: this.#nextGuest++ }], errors: {} }));
+  }
+
+  removeGuest(_e: Event, hit: EventHit<{ id: number }, "id">): void {
+    this.set((s) => ({ guests: s.guests.filter((g) => g.id !== hit.key), errors: {} }));
+  }
+
+  submit(e: Event): void {
+    e.preventDefault();
+    const result = validateSignup(readForm(this.refs.form));
+    if (!result.ok) {
+      this.set({ errors: result.errors });
+      this.refs.form.querySelector<HTMLElement>("[aria-invalid=true]")?.focus();
+      return;
+    }
+    this.set({ errors: {} });
+    this.emit("signup-submit", result.data);
+  }
+
+  check(e: Event): void {
+    if (!(e.target instanceof HTMLInputElement) || e.target.type === "checkbox") return;
+    const path = pathOf(this.refs.form, e.target);
+    const result = validateSignup(readForm(this.refs.form));
+    const message = result.ok ? "" : (result.errors[path] ?? "");
+    this.set((s) => ({ errors: { ...s.errors, [path]: message } }));
+  }
+
+  clearError(e: Event): void {
+    if (!(e.target instanceof HTMLInputElement)) return;
+    const path = pathOf(this.refs.form, e.target);
+    if (this.state.errors[path]) this.set((s) => ({ errors: { ...s.errors, [path]: "" } }));
+  }
+
+  override render(view: DeepReadonly<State>): void {
+    const mark = (input: HTMLInputElement, path: string, id: string) => {
+      const invalid = Boolean(view.errors[path]);
+      input.ariaInvalid = invalid ? "true" : null;
+      if (invalid) input.setAttribute("aria-describedby", id);
+      else input.removeAttribute("aria-describedby");
+    };
+    mark(this.refs.name, "name", "signup-name-error");
+    mark(this.refs.email, "email", "signup-email-error");
+    mark(this.refs.age, "age", "signup-age-error");
+    mark(this.refs.city, "address.city", "signup-city-error");
+    mark(this.refs.terms, "terms", "signup-terms-error");
+    this.lists.guests.replace(
+      view.guests.map((g, i) => ({ id: g.id, message: view.errors[`guests.${i}`] ?? "" })),
+      (g) => g.id,
+      (g, { text, show, refs }) => {
+        text.message = g.message;
+        show("invalid", g.message !== "");
+        refs.guest.ariaInvalid = g.message ? "true" : null;
+        refs.guest.ariaDescribedByElements = g.message ? [refs.guestMsg] : null;
+      },
+    );
+  }
+}
+define("signup-form", SignupForm);
+```
+
+The page that uses it (`index.html` has `<signup-form></signup-form>` and `<pre id="out"></pre>`):
+
+```ts
+// src/main.ts
+import "./nv/signup-form.ts";
+import type { EmitEvent } from "@nativele/ts-dom";
+import type { SignupForm } from "./nv/signup-form.ts";
+
+document.querySelector("signup-form")!.addEventListener("signup-submit", (e) => {
+  const data = (e as EmitEvent<SignupForm, "signup-submit">).detail;
+  document.querySelector("#out")!.textContent = JSON.stringify(data);
+});
+```
+
+A file the app never imports, kept so `ts-dom check` proves the event carries the parsed type:
+
+```ts
+// src/nv/types-check.ts
+import type { z } from "zod";
+import type { EmitEvent } from "@nativele/ts-dom";
+import type { Signup, SignupSchema } from "./signup.js";
+import type { SignupForm } from "./signup-form.js";
+
+declare const submitted: EmitEvent<SignupForm, "signup-submit">;
+declare const raw: z.input<typeof SignupSchema>;
+export const age: number = submitted.detail.age;
+// @ts-expect-error the form's raw input has age as a string, not the parsed number
+export const parsed: Signup = raw;
+```
+
+What it does, as checked in the browser:
+
+- Submitting the empty form shows every message (`Name is required`, `Enter a valid email`, `Age is required`, `City is required`, `Accept the terms`), sets `aria-invalid="true"` and `aria-describedby` on each invalid input, and focuses the name field. Chrome's accessibility tree then reports the name input as invalid with the description `Name is required`.
+- Typing in a field removes only that field's message and its two attributes. Submitting again focuses the next invalid field in document order.
+- Leaving a field shows its message (`bad` in email shows `Enter a valid email`; age `abc`, `17` and `18.5` show `Enter a number`, `You must be 18 or older` and `Whole years only`).
+- An invalid second guest shows `Enter a valid email` inside that list item only; four guests show `At most 3 guests` under the list.
+- A valid submit clears every message and emits `{ name, email, age: 36, address: { city }, guests: [...], terms: true }`, with `age` a number.
+
+## Known limitations
+
+1. **One derived name per message.** A hole and a `data-if` take a single identifier, so `{{ errors.name }}` is a template error. Keep the map in state and add a `derive` entry per message element; a name used in the template that is not in `derive` is a `missing-binding` tsc error, which `ts-dom check` reports.
+2. **Build the input object from `FormData` by hand.** In Chrome, `FormData.get` returns the string (`""` for an empty input) or `null` for a name the form does not have, which Zod reports as `Invalid input: expected string, received null`. `Object.fromEntries(new FormData(form))` looks shorter but loses data: repeated names keep only the last value (`guests` became one string), an unchecked checkbox is missing and a checked one is `"on"`, and nested names stay flat keys (`"address.city"`). So read each field: `get` for single values, `getAll` for repeated names, `has` for a checkbox, and nest the object as the schema does. Reading `this.refs.x.value` in a handler works as well; the `unguarded-input-value` lint rule reports only a `render()` that writes a control's value without comparing it first, and neither reading values nor writing them in a handler (`form.reset()` after submit) is reported. This procedure writes no value in `render`.
+3. **Numbers from text inputs.** `z.coerce.number()` turns `""` into `0` (in Zod 4.6.7 and 3.25.76 alike), so an empty age fails with `Too small: expected number to be >=18` instead of a "required" message, or passes when `0` is allowed. Check the string first and coerce after: `z.string().min(1, "Age is required").pipe(z.coerce.number<string>("Enter a number")...)`. Without the `<string>` type argument, Zod 4's `pipe` is a tsc error (`TS2345 ... Type 'unknown' is not assignable to type 'string'`). Zod reports a non-number such as `abc` with the coerce message (`Enter a number`).
+4. **Nested fields** (paths with more than one segment): name the input with the dot path (`name="address.city"`), nest the value in `readForm`, and key the map with `issue.path.join(".")`, so the input name, the issue path and the map key are the same string. Do not use `z.flattenError(error)` (or Zod 3's `error.flatten()`): its `fieldErrors` keep only the first path segment, so `address.city` comes back under `address`.
+5. **Array fields**: an issue inside an array has the index in its path (`guests.1`); one about the array itself (`.max(3)`) has the field name only (`guests`). Show item messages in the `replace` callback of the list, by index, and the array message in its own element under the list. `pathOf` maps a repeated input to its index in document order, which is the order `getAll` returns. Adding or removing an item shifts the indexes, so the example clears `errors` then. An item's elements are not in the component's `refs`, so its input gets `aria-invalid` in the callback, and its description is set with `ariaDescribedByElements`, because an id inside a `data-each` template repeats for every item (`id-in-list`). In Zod 4 a failing `.max()` (or `.min()`) on the array hides the issues of its items: with four guests and `.max(3)`, an empty guest gets no message until the list is short enough; disable the add button at the limit so the case cannot arise.
+6. **Ids repeat when the component is on a page more than once.** In the default Light DOM, each instance renders the same `id`s, and `aria-describedby="signup-name-error"` then finds the first one in the document. For a form that can appear more than once, drop the ids, put a `data-ref` on the message element (`<p data-ref="nameMsg" data-if="nameError">`) and set `this.refs.name.ariaDescribedByElements = view.nameError ? [this.refs.nameMsg] : null` in `render`. This was verified with two instances in Chrome 148 (each input described by its own message; at the component level, unlike in a list item, a ref on a `data-if` element is there even while the block is hidden), and TypeScript 7 types the property; other browsers were not checked.
+7. **Blur does not bubble.** Use `data-on-focusout` on the `<form>`, which receives every field's blur; `e.target` is the field. Validate the whole form and take only that field's message, so checks that read more than one field still apply. The example skips checkboxes on blur, because tabbing past an unchecked box would show its message too early.
+8. **`aria-invalid` needs the value `"true"`.** `toggleAttribute("aria-invalid", on)` writes `aria-invalid=""`, which Chrome's accessibility tree reports as not invalid. Set `input.ariaInvalid = invalid ? "true" : null`. Whether a screen reader announces the message was not checked; the accessibility tree shows each invalid input with its message as the description.
+9. **Checks across fields**: `.refine((d) => d.password === d.confirm, { message: "Passwords differ", path: ["confirm"] })` puts the message under `confirm`. Give such a refinement a `path`; without one its path is empty and the map key is `""`, which no field shows. In Zod 4 the object-level `refine` runs only when every failing field failed a check on a value of the right type (`too_small`, `invalid_format`, a field's own `refine`); a field that fails with `invalid_value` or `invalid_type` stops it, and the cross-field message is missing until that field is fixed. Those are `z.literal(...)` (an unchecked `z.literal(true)` box), `z.enum([...])` given an empty `<select>`, and `z.coerce.number()` given text. Write them so they fail with a check instead: a box as `z.boolean().refine((v) => v, "...")`, a select as `z.string().min(1, "Choose a role").pipe(z.enum([...]))`, a number as in the example (checked with `safeParse` in Node). Valibot's `v.forward(v.partialCheck(...))` does not have this problem.
+10. **Zod 4 vs Zod 3.** These steps use Zod 4. The same component, `verify.mjs` and `issue.path.join(".")` passed with Zod 3.25.76 after these schema changes:
+
+    | In the schema | Zod 4.6.7 | Zod 3.25.76 |
+    |---|---|---|
+    | email | `z.email("...")` | `z.string().email("...")` (`z.email` does not exist) |
+    | coerced number message | `z.coerce.number<string>("...")` | `z.coerce.number({ invalid_type_error: "..." })` (no type argument: `TS2558`) |
+    | message of a literal | `z.literal(true, "...")` | `z.literal(true, { errorMap: () => ({ message: "..." }) })` (a string is `TS2559`) |
+    | flattening issues | `z.flattenError(error)`, only the first segment (limitation 4) | `error.flatten()`, the same |
+
+    `safeParse`, `result.error.issues`, `issue.path`, `issue.message` and `z.infer` were used the same way in both.
+
+11. **Valibot 1.5.0 fits the same procedure.** Only `signup.ts` changes; the component, template and `verify.mjs` passed unchanged:
+
+    ```ts
+    // src/nv/signup.ts with Valibot
+    import * as v from "valibot";
+
+    export const SignupSchema = v.object({
+      name: v.pipe(v.string(), v.trim(), v.minLength(1, "Name is required")),
+      email: v.pipe(v.string("Enter a valid email"), v.email("Enter a valid email")),
+      age: v.pipe(v.string(), v.minLength(1, "Age is required"), v.transform(Number), v.number("Enter a number"), v.integer("Whole years only"), v.minValue(18, "You must be 18 or older")),
+      address: v.object({ city: v.pipe(v.string(), v.trim(), v.minLength(1, "City is required")) }),
+      guests: v.pipe(v.array(v.pipe(v.string(), v.email("Enter a valid email"))), v.maxLength(3, "At most 3 guests")),
+      terms: v.literal(true, "Accept the terms"),
+    });
+
+    export type Signup = v.InferOutput<typeof SignupSchema>;
+    export type Errors = Readonly<Record<string, string>>;
+
+    export function validateSignup(input: unknown): { ok: true; data: Signup } | { ok: false; errors: Errors } {
+      const result = v.safeParse(SignupSchema, input);
+      if (result.success) return { ok: true, data: result.output };
+      const errors: Record<string, string> = {};
+      for (const issue of result.issues) errors[v.getDotPath(issue) ?? ""] ??= issue.message;
+      return { ok: false, errors };
+    }
+    ```
+
+    For the `types-check.ts` file, use `v.InferInput<typeof SignupSchema>` instead of `z.input`. Valibot's issue path is a list of objects, not keys; `v.getDotPath(issue)` gives the same dot path (`address.city`, `guests.1`). The parsed data is `result.output`, the type `v.InferOutput`. A check across fields is `v.forward(v.partialCheck([["password"], ["confirm"]], (d) => d.password === d.confirm, "Passwords differ"), ["confirm"])` on the object's `v.pipe` (checked in Node). The production bundle of this example page was 26.42 kB (9.55 kB gzip) with Valibot and 106.08 kB (31.88 kB gzip) with Zod 4.
+12. Not verified: Zod Mini, the `zod/v4` entry of Zod 3.25, async refinements (`safeParseAsync`), `<select multiple>`, file inputs, forms inside a `shadow: true` component, the `role="alert"` of the recipe together with `aria-describedby`, screen reader output, and browsers other than Chrome.
+
+## Verify
+
+Run in the project:
+
+```sh
+npx ts-dom check src/nv    # expect: ts-dom check: no issues (types-check.ts included)
+npx ts-dom lint src/nv --a11y   # expect: ts-dom lint: no issues
+npm run build              # expect: ts-dom check: no issues, then ✓ built
+```
+
+The `@ts-expect-error` in `types-check.ts` and the check below rely on a field whose parsed type differs from its input (here `age`, a string that becomes a number); for a schema without such a transform, input and output types are equal and the directive is reported as unused (`TS2578`), so drop it. Change `event<Signup>()` to `event<z.input<typeof SignupSchema>>()` once to see the type check work: `ts-dom check` must then report `TS2345` at the `emit` (and `TS6133` for the schema's output type, now unused, when `noUnusedLocals` is on) (`Type 'number' is not assignable to type 'string'` for `age`) and `TS2322` in `types-check.ts`.
+
+In the browser, against `npm run dev` and against `npx vite preview` of the build, check with a test (Playwright or by hand). Submit with Enter or `form.requestSubmit()` in a test: a message that appears when a field loses focus can move the submit button, and a mouse click aimed at it then misses.
+
+- submitting the empty form shows one message per field, sets `aria-invalid="true"` and `aria-describedby` on those inputs, and focuses the first of them;
+- typing in a field removes only its message and both attributes; submitting again focuses the next invalid field;
+- leaving a field with a wrong value shows its message;
+- a wrong item in an array field shows its message in that item only, the item's input is invalid and described by that message in the accessibility tree, and an array-level issue shows under the list;
+- a valid submit emits the parsed values (numbers as numbers), clears every message, and the console has no errors or warnings.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `ts-dom check`: `[missing-binding] "nameMessage" is used by {{ nameMessage }} ... declares no state, prop or derived value of that name`, followed by many `TS7006 ... implicitly has an 'any' type` errors | a hole or `data-if` name that is not a `derive` entry; the other errors follow from it | add the `derive` entry (`nameMessage: (s) => s.errors["name"] ?? ""`) and check again |
+| `ts-dom gen`: `[invalid-hole]` | `{{ errors.name }}` in the template | use the derived name (`{{ nameError }}`) |
+| A nested field never shows its message | the map was built with `z.flattenError` / `error.flatten()`, or the input `name` is not the dot path | key by `issue.path.join(".")` and name the input `address.city` |
+| Every message shows, but the submitted object has one guest instead of all | `Object.fromEntries(new FormData(form))` | `data.getAll("guests")` |
+| An empty number field passes, or fails with `Too small: expected number to be >=...` | `z.coerce.number()` turns `""` into `0` | `z.string().min(1, "...").pipe(z.coerce.number<string>(...))` |
+| tsc `TS2345 ... '_zod.input' are incompatible ... Type 'unknown' is not assignable to type 'string'` on a `pipe` | `z.coerce.number()` without the `<string>` type argument after `z.string()` | `z.coerce.number<string>()` |
+| A field shows `Invalid input: expected string, received null` | `readForm` reads a name the form does not have | match the `get` names to the inputs' `name` attributes |
+| The accessibility tree reports the field as not invalid although its message shows | `aria-invalid=""` from `toggleAttribute` | `input.ariaInvalid = invalid ? "true" : null` |
+| Nothing focuses on submit | the focus query runs before `set`, or `aria-invalid` is not `"true"` | call `set({ errors })` first, then query `[aria-invalid=true]` |
+| The blur message never shows | `data-on-blur` on the form (blur does not bubble) | `data-on-focusout` on the form |
+| After switching Zod versions, the dev server still runs the old one (Zod 4 messages from a Zod 3 schema) | Vite keeps its pre-bundled copy until it restarts | restart `npm run dev`; it prints `Re-optimizing dependencies because lockfile has changed` |
+
+## See also
+
+- The form validation recipe this extends (messages in state, `data-if`, clearing on input): https://github.com/Pixmi/nativele/blob/main/docs/recipes.md#form-validation
+- `state`, `derive`, `render` and `changed`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#data-and-view-state-optional
+- `emits`, `event<T>()` and `EmitEvent`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#data-flow-props-down-events-up
+- Event delegation, `focusout` and blur: https://github.com/Pixmi/nativele/blob/main/docs/components.md#events-data-on-
+- Writing form control values in `render` (`unguarded-input-value`): https://github.com/Pixmi/nativele/blob/main/docs/components.md#a-small-reminder-about-form-inputs
+- Lists, `replace` and `show` in items: https://github.com/Pixmi/nativele/blob/main/docs/lists.md#items-as-plain-elements-replace
+- Setting up Nativele in the Vite app: `npx ts-dom skills nativele-vite`