@nativele/ts-dom 0.4.0 → 0.5.0

package/skills/_template/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: nativele-<tool>
+description: "What the Skill lets an agent do, and when to use it (the dependencies or files that call for it)."
+metadata:
+  tier: experimental
+  nativele: ">=0.5.0 <0.6.0"
+  verified: "YYYY-MM-DD"
+  tools: "<tool>@<exact version> <other tool>@<exact version>"
+  author: "<your name or GitHub handle>"
+  detects: "<package.json dependency names, space-separated>"
+---
+
+# Nativele + <tool>
+
+## When to use
+
+- The situation, and the signals (dependencies, files) that call for this Skill.
+- When not to use it.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | x.y.z |
+| <tool> | x.y.z |
+
+Verified on YYYY-MM-DD. With a different major version of <tool>, treat every step as unverified.
+
+## Set-up
+
+1. Numbered steps with the exact commands and file contents.
+
+## Example
+
+The complete, minimal working example: every file it needs.
+
+## Known limitations
+
+1. What does not work or needs care, and what to do instead.
+
+## Verify
+
+```sh
+npx ts-dom check     # expect: ts-dom check: no issues
+npx tsc --noEmit     # expect: no errors
+```
+
+What to check in the browser or with a test.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+
+## See also
+
+- Links to the guides in https://github.com/Pixmi/nativele/tree/main/docs for the facts used.

package/skills/nativele-core/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: nativele-core
+description: "Build and change web components with Nativele (@nativele/ts-dom): the write-check-fix loop, templates, state, lists and data flow. Use whenever a project depends on @nativele/ts-dom and you add or change an .html template or a component."
+metadata:
+  tier: official
+  nativele: ">=0.5.0 <0.6.0"
+  verified: "2026-11-05"
+  tools: "typescript@7.0.2"
+  author: "Nativele maintainers"
+  detects: "@nativele/ts-dom"
+---
+
+# Nativele core
+
+## When to use
+
+- The project depends on `@nativele/ts-dom` and you write or change a component: an `x.html` template with its `x.ts` class.
+- Not for using Nativele components from a framework (React, Vue, ...): see the integration Skills (`npx ts-dom skills`), which build on this one.
+
+A component is two files. The HTML holds structure and names (`{{ name }}`, `data-ref`, `data-if`, `data-each`, `data-on-*`), never expressions; the TypeScript class holds state and behavior. `ts-dom gen` turns each `x.html` into a typed `x.html.ts`, and `tsc` checks that the two files agree.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.0 |
+| typescript | 7.0.2 |
+
+Verified on 2026-11-05 by the library's own CI, which type-checks, lints and runs every example in the repository in real Chrome.
+
+## Set-up
+
+1. `npm i @nativele/ts-dom` and `npm i -D typescript`.
+2. `tsconfig.json` with `"strict": true`, `"lib"` including `"DOM"`, and `"moduleResolution"` `"NodeNext"` or `"bundler"`; its `include` must cover the folders with templates.
+3. With Vite, add `tsDom()` from `@nativele/ts-dom/vite` to `plugins` and set `"type": "module"` in `package.json`. Without a bundler, `ts-dom gen` plus `tsc` is enough.
+4. Run `npx ts-dom doctor` once; fix every error and warning it reports. Its `info` lines name the other Skills that fit the project.
+
+## The loop
+
+1. Write the `.html` and the `.ts` of a component together. Import the template as `./x.html.js`.
+2. Run `npx ts-dom check` (add `--json` to read the result as data). It regenerates the generated files, runs `tsc`, points template contract errors at the template line and column, and runs the lint rules. Use `--no-write` where the working tree must not change.
+3. Fix every issue by its `Fix:` hint. Never cast a type error away, and never edit `x.html.ts` or `ts-dom-tags.ts`: they are generated.
+4. `npx ts-dom rules --explain=<id>` explains any rule id from a diagnostic, with a wrong and a right example.
+5. Repeat until `ts-dom check` prints `no issues`.
+
+## Rules
+
+- No expressions in HTML: `{{ name }}` is a single identifier. Compute in `derive` (or in TypeScript) and fill a named hole.
+- Change state only with `this.set()`. Rendering is synchronous; `this.batch()` combines updates.
+- Once a component has `state`, `props` or `derive`, every `{{ hole }}` and `data-if` must name one of them. Show store data by copying it into state in the `bind` callback.
+- `store.set` replaces the whole value; a component's `this.set` merges. Spread the rest yourself: `store.set((s) => ({ ...s, status: "loading" }))`.
+- Lists, attributes and focus go in `render(view, changed)`. `changed` holds the state, prop and derived names that changed; annotate it with the names you check (`changed: ReadonlySet<"items" | "visible">`), never `ReadonlySet<string>`.
+- Props go down (the parent sets them), events go up (`emit`, handled with `data-on-<event>` on the child tag). `emit` does not bubble; data needed several levels away goes in a shared `createStore` that the components `bind`.
+- State, props and the view are deeply read-only: replace objects instead of changing them (`{ ...todo, done: true }`).
+- A `data-each` list cannot be nested: the inner list belongs to its own item 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 = ...` in `render`, and type item handlers as `hit: EventHit<Item, "id">`.
+- Do not name a handler or prop like a DOM or Nativele member (`remove`, `click`, `title`, `render`, ...); `ts-dom check` reports it.
+
+## Known limitations
+
+- Holes are text only; attributes are set in TypeScript through `data-ref`.
+- A derived value cannot read another derived value; share the calculation as a plain function.
+- `data-if` removes the element from the page (its state is kept in memory); to hide an element while it keeps focus or media playback, set `this.refs.x.hidden` in `render`.
+- Nativele has no router, data fetching, form validation library, styling system or global state manager by design; use the project's tools for those, and see the other Skills for how they connect.
+
+## Verify
+
+```sh
+npx ts-dom check --strict    # expect: ts-dom check: no issues
+npx ts-dom doctor            # expect: ts-dom doctor: the set-up looks right (info lines are suggestions)
+npx tsc --noEmit             # expect: no errors
+```
+
+Then exercise the changed component in a real browser (the project's own test runner, or the browser).
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Cannot find module './x.html.js'` | the generated file is missing | run `npx ts-dom check` (or `ts-dom gen`) |
+| `missing-binding` at a template line | a hole or `data-if` name that state, props and derive do not have | add the field, or rename the hole |
+| A list stays empty | `render` never assigns it, or guards it with a name that is not in `changed` | assign `this.lists.x.items` in `render`, guarded by the name of what it shows |
+| A child component does not update | an object prop was changed in place | pass a new object |
+| No types in a parent's `refs.child` | the child class is not exported, or is defined outside the scanned folders | `export class`, and keep it in a folder `ts-dom gen` scans |
+
+## See also
+
+- Templates: https://github.com/Pixmi/nativele/blob/main/docs/templates.md
+- Components and data flow: https://github.com/Pixmi/nativele/blob/main/docs/components.md
+- Lists: https://github.com/Pixmi/nativele/blob/main/docs/lists.md
+- Recipes (loading states, dialogs, forms, store data): https://github.com/Pixmi/nativele/blob/main/docs/recipes.md
+- Setup, checks and lint: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md

package/skills/nativele-react/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: nativele-react
+description: "Use Nativele web components inside a React 19 app: passing props, receiving events, children and slots, lifecycle, and TSX types. Use when a project depends on react and @nativele/ts-dom."
+metadata:
+  tier: official
+  nativele: ">=0.5.0 <0.6.0"
+  verified: "2026-11-05"
+  tools: "react@19.3.1 react-dom@19.3.1 @types/react@19.3.0 @types/react-dom@19.3.0 vite@8.3.5 @vitejs/plugin-react@6.2.1 typescript@7.0.2"
+  author: "Nativele maintainers"
+  detects: "react"
+---
+
+# Nativele + React
+
+## When to use
+
+- The project renders with React 19 and wants to use components written with Nativele (`@nativele/ts-dom`), for example a design-system layer or widgets shared with non-React pages.
+- Signals: `react` and `@nativele/ts-dom` in `package.json`, `.tsx` files that render tags with a hyphen (`<info-card>`).
+- Not for React 18 or earlier: React 18 sets every prop on a custom element as an attribute and does not attach `on...` handlers to custom events. The steps below are verified only with React 19.
+
+Nativele components are native custom elements. React renders them like any other tag; nothing wraps them.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.0 |
+| react, react-dom | 19.3.1 |
+| @types/react, @types/react-dom | 19.3.0 |
+| vite | 8.3.5 |
+| @vitejs/plugin-react | 6.2.1 |
+| typescript | 7.0.2 |
+
+Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nativele repository (`skills/nativele-react/example`), which CI runs again when the Skill or the library changes and once a month. With a different major version of React, 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` (see the core Skill or the guides).
+2. Install: `npm i @nativele/ts-dom`.
+3. Add the Nativele Vite plugin next to the React plugin, pointing at that folder:
+
+   ```ts
+   // vite.config.ts
+   import { defineConfig } from "vite";
+   import react from "@vitejs/plugin-react";
+   import { tsDom } from "@nativele/ts-dom/vite";
+
+   export default defineConfig({ plugins: [tsDom({ dirs: ["src/nv"] }), react()] });
+   ```
+
+4. Import every Nativele component module in the entry file, before React renders anything:
+
+   ```tsx
+   // src/main.tsx
+   import "./nv/info-card.js";
+   import "./nv/shadow-card.js";
+   // then createRoot(...).render(...)
+   ```
+
+   React 19 sets a value as a property only when the element is already defined; before that it writes an attribute, and an object prop becomes the text `"[object Object]"`.
+
+5. Add the TSX declaration below as `src/nativele-react.d.ts`. It reads the tag map that `ts-dom gen` writes (`ts-dom-tags.ts`), so every exported component gets typed props and events, and new components need no edit:
+
+   ```ts
+   // src/nativele-react.d.ts
+   import type { DetailedHTMLProps, HTMLAttributes } from "react";
+
+   type NativeleTag = Extract<keyof HTMLElementTagNameMap, `${string}-${string}`>;
+   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${K}`]?: (event: CustomEvent<NonNullable<M>[K]>) => void }
+     : unknown;
+   type NativeleElementProps<E extends HTMLElement> = Omit<DetailedHTMLProps<HTMLAttributes<E>, E>, keyof NativeleProps<E>> &
+     NativeleProps<E> &
+     NativeleEvents<E>;
+   type NativeleIntrinsics = { [K in NativeleTag]: NativeleElementProps<HTMLElementTagNameMap[K]> };
+
+   declare module "react" {
+     namespace JSX {
+       interface IntrinsicElements extends NativeleIntrinsics {}
+     }
+   }
+   ```
+
+   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`.
+
+## 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("info-card", InfoCard);
+```
+
+Used from React:
+
+```tsx
+<info-card label={label} count={count} item={item} onitem-select={(e) => select(e.detail.id)} />
+```
+
+- `label`, `count` and `item` arrive as properties; the object is the same object React passed. Changing them from React state re-renders the Nativele component.
+- The event handler prop is `on` followed by the exact event name: `onitem-select`. `e.detail` is typed from the component's `emits`.
+
+A component with slots that receives React children: give it `shadow: true`, then pass children directly.
+
+```ts
+// src/nv/shadow-card.ts
+export class ShadowCard extends Component(tpl, { shadow: true }) {}
+define("shadow-card", ShadowCard);
+```
+
+```tsx
+<shadow-card>
+  {showTitle && <span slot="title">{title}</span>}
+  {rows.map((r) => <p key={r.id}>{r.text}</p>)}
+</shadow-card>
+```
+
+## Known limitations
+
+1. **Define before render.** Import every Nativele module before React first renders its tag (step 4). Otherwise props become attributes and object props are lost.
+2. **Event prop names.** Only `on` plus the exact event name works (`onitem-select`); `onItemSelect` and `onItem-select` never fire. Nativele events do not bubble by default, so put the handler on the element that emits. A ref with `addEventListener` in `useEffect` also works (remove it in the cleanup).
+3. **Light DOM slots and React children do not mix.** In the default Light DOM mode, Nativele moves the host's children into its slot positions. When React later inserts, removes or reorders those children it fails (`insertBefore`/`removeChild` errors that unmount the root) or leaves nodes outside the slot. Changing text in place and appending at the end happen to work, but do not rely on that. Use one of:
+   - `shadow: true` on the component (children can then change freely), or
+   - one stable React element per slot, and let React change only what is inside it:
+
+     ```tsx
+     <light-card>
+       <div slot="title">{showTitle && <span>{title}</span>}</div>
+       <div>{rows.map((r) => <p key={r.id}>{r.text}</p>)}</div>
+     </light-card>
+     ```
+
+     A stable but empty wrapper still fills its slot, so the slot's fallback content does not show.
+4. **New objects for changed props.** A Nativele component compares props by reference; pass a new object when the data changes (React state updates usually do).
+5. **TSX types need the declaration** in step 5; without it, every Nativele tag is `TS2339: Property 'info-card' does not exist on type 'JSX.IntrinsicElements'`. Check it with a `.tsx` that has a wrong prop under `// @ts-expect-error`, because `skipLibCheck` can hide mistakes inside the declaration itself.
+6. Not verified: server-side rendering, form controls inside Nativele components submitting with a React form, and React versions other than 19.3.
+
+React StrictMode is fine: it runs effects twice but does not insert the custom element twice, so `connected()` runs once, and `bind` subscriptions are released when React unmounts the element.
+
+## 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
+npx tsc --noEmit             # expect: no errors (keep one @ts-expect-error case per component kind)
+npx vite build               # expect: built
+```
+
+In the browser, render a component with an object prop and an event handler, and check that the element has no `item` attribute (`el.getAttributeNames()`), that `el.item` is the object, and that the handler fires once per click. The example project's `verify.mjs` does these checks with Playwright, plus children that React reorders, adds and removes inside a `shadow: true` component and inside stable wrappers in a Light DOM component.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| An object prop shows `[object Object]` or is missing | the component was rendered before `define()` ran | import the component module in the entry file before rendering |
+| The event handler never runs | the prop name is camelCased (`onItemSelect`) | use `on` plus the exact event name (`onitem-select`) |
+| `insertBefore`/`removeChild` errors, the React root disappears | React children changed inside a Light DOM component with slots | use `shadow: true`, or stable wrapper elements per slot |
+| `TS2339: Property 'x-y' does not exist on type 'JSX.IntrinsicElements'` | the declaration file is missing, or the component class is not exported | add `src/nativele-react.d.ts`, export the class, run `ts-dom gen` |
+| `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
+- Slots, Light DOM and Shadow DOM: https://github.com/Pixmi/nativele/blob/main/docs/components.md#light-default-and-shadow
+- Setup and checks: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md