@nativele/ts-dom 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -10,6 +10,90 @@ 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.5.0
+
+Nativele is a light, composable UI layer that grows its integrations through Skills instead of through the library. This version ships the first Skills and the command that delivers them, types `changed` and list event handlers more precisely, and adds recipes for common screens.
+
+### Skills
+
+- New `skills/` folder with the specification every Skill follows (versions it was verified with, set-up, a complete example, known limitations, verification commands; Official, Community and Experimental tiers) and a template for contributors. The package ships every `SKILL.md`.
+- `nativele-core`: building components with Nativele, the `ts-dom check` loop and the rules an agent must follow (it replaces the README's "Rules for AI Agents").
+- `nativele-react`: Nativele components in React 19, verified with React 19.3.1, Vite 8.3.5 and TypeScript 7.0.2: props as properties (define before render), `on<event-name>` handlers, children and slots (`shadow: true` or stable wrappers; Light DOM slots with changing React children are unsafe), lifecycle under StrictMode, and a TSX declaration that types every component's props and events from `ts-dom-tags.ts`. Its example project runs in a separate workflow (`skills.yml`) when a Skill or the library changes and once a month.
+- `ts-dom skills` lists the Skills shipped with the installed version (tier, verified date and versions, and whether it is stale: older than six months or not covering the installed version); `ts-dom skills <name>` prints one; `ts-dom skills add <name...>` copies Skills into `.claude/skills/` when the project has `.claude`, otherwise into `.agents/skills/` (`--to=<dir>` for another folder). `--json` prints the list as data.
+- `ts-dom doctor` suggests the Skills whose dependencies the project has (`skill-available`) and reports a project copy that differs from the shipped one (`skill-outdated`). Both are `info` and never change the exit code.
+
+### Components
+
+- `changed` in `render(view, changed)` also holds the derived values whose value changed (all of them on the first render), so `if (changed.has("visible")) this.lists.visible.items = view.visible` works for a derived list. Its type includes the derived names; annotate it with the names you check (`ReadonlySet<"items" | "visible">`) and tsc reports a misspelled name. The examples and guides no longer use `ReadonlySet<string>`.
+- `EventHit<Item, KeyField>`: naming the item type and its key field (`hit: EventHit<Todo, "id">`) types `hit.item` as `Todo` and `hit.key` as `Todo["id"]`, with no cast.
+
+### Lint
+
+- New lint rule `unguarded-input-value` (in the `data-flow` group, and `ts-dom/unguarded-input-value` on its own): a `render()` that writes an `<input>`, `<textarea>` or `<select>` value without comparing it first, which moves the caret while the user types.
+
+### Documentation
+
+- New guide `docs/recipes.md` with `examples/recipes` and a real Chrome test: loading and error states from a shared store, showing store data in a component with state, a filtered list, events from list items, a modal dialog opened through a typed ref, and form validation.
+- The guides say that `store.set` replaces the value (a component's `this.set` merges), that a component with `state`, `props` or `derive` shows store data by copying it into state, that a hidden `data-if` block keeps its elements and refs, and that Vite needs `"type": "module"` in `package.json`.
+- The README's "Rules for AI Agents" becomes "Nativele Skills".
+- The project's agent instructions are `AGENTS.md`, in English, and state the direction: a light UI foundation layer for larger applications, with integrations delivered as Skills.
+- The README is now the introduction (the short version, Nativele Skills, a quick start with two examples, the example apps), and the full guide lives in `docs/`: templates, components and data flow, lists, recipes, setup and checks, performance, design, and developing Nativele. The guide is in English only; `README.zh-TW.md` mirrors the README. The components guide gains a table of the common DOM operations in `render` (text, `data-if` against `hidden`, attributes, classes, form values, lists).
+- The README opens with a banner and the line "Designed for AI agents. Driven by TypeScript. Defined in vanilla HTML."; the package description, `llms.txt` and the repository description use the same wording, and describe the library as one for building web components rather than a UI library (it ships no ready-made components).
+- The setup guide, the README and `ts-dom --help` say which commands write files: `ts-dom check` rewrites the generated files first, `ts-dom check --no-write` and `ts-dom gen --check` write nothing.
+
+### Breaking changes
+
+- `changed` in `render` now also holds derived names. Code that reads `changed.size` or iterates it sees more names; `changed.has(...)` checks on state and props behave as before.
+- `EventHit` is now a type alias instead of an interface, so it can no longer be extended with `interface X extends EventHit`; intersect it instead (`EventHit & { ... }`).
+
+## 0.4.6
+
+Released together with 0.4.1 to 0.4.5, which were not published on their own.
+
+- `ts-dom rules --explain=<id>` explains any rule id: why it exists (tied to the principle it protects), a wrong example and the fix. `ts-dom rules --json` prints every rule as data. Every rule id has an explanation; a test keeps them in step.
+- The README's Checks section says which tool checks what: a formatter such as oxfmt for well-formed markup and layout (it reports misnested tags that the library's parser would silently repair), `ts-dom gen` for the template rules, `tsc` for names and types, lint for usage, data flow and accessibility, `ts-dom doctor` for the set-up, and `ts-dom check` for all of them at once.
+
+## 0.4.5
+
+Not published on its own; it ships with 0.4.6.
+
+- Every rule id of `unused-markup`, `data-flow` and `a11y` is also a lint rule of its own (`ts-dom/unused-ref`, `ts-dom/missing-handler`, ...), so a project can enable rules one by one with their own severity. The three group rules stay.
+- `missing-handler` offers a suggestion that adds the method to the component class.
+- In the editor, the Oxc extension for VS Code (`oxlint --lsp`) shows the findings and offers the quick fix; `oxlint --fix-suggestions` applies it from the command line. Both are covered by tests that run the oxlint shipped with Vite+.
+- Each template is analyzed once per file text and template text, however many rules ask for it.
+
+## 0.4.4
+
+Not published on its own; it ships with 0.4.6.
+
+- `ts-dom doctor [dirs...]` checks the project set-up: a tsconfig with `strict`, the DOM lib, a module resolution other than `classic` and an `include` covering the template folders (read through `extends`: relative paths, packages and arrays; a solution-style tsconfig through its references); the runtime package being resolvable; templates imported as `./x.html` instead of `./x.html.js`; stale generated files; the Vite and oxlint plugins being configured; and a formatter (oxfmt, Prettier) set up while templates keep their whitespace. Page entries and `dist` are not counted as templates, and a folder that does not exist is reported. Stable rule ids, a `Fix:` per issue, `--json`, exit code 1 on errors.
+
+## 0.4.3
+
+Not published on its own; it ships with 0.4.6.
+
+- `ts-dom check [dirs...]` runs everything in one pass for agents and CI: template diagnostics, generated files (regenerated, or reported as stale with `--no-write`), the project's own `tsc` (TypeScript 5, 6 or 7), and the lint rules (`--a11y` adds accessibility). TypeScript errors from the template contract point at the template line and column (`missing-binding`, `missing-handler`), item component problems get their own rule ids, and errors that only follow from a broken class (the ones naming that class) are left out. A tag defined twice is reported, and a tsc that does not run to completion (no tsconfig, a bad option) is reported as `tsc-failed` instead of passing silently. A solution-style tsconfig (`"files": []` with `references`) is checked through its referenced projects, a folder that does not exist is reported as `dir-not-found`, and every plain tsc error carries a `Fix:` hint. `--json` prints the issues as data; `--strict` fails on warnings.
+- The README, the rules for AI agents and `llms.txt` use `ts-dom check` as the command to run after a change.
+
+## 0.4.2
+
+Not published on its own; it ships with 0.4.6.
+
+- `ts-dom gen --check` writes nothing and lists generated files that are missing, outdated or orphaned (a deleted template) and the errors that would make `ts-dom gen` fail, with exit code 1 if there are any; `--json` prints them as data. `ts-dom gen` removes an orphaned generated module. A module generated with whitespace `collapse` records it, and a later `gen`, `gen --check`, `check` or `doctor` without the option keeps that mode (`--whitespace=preserve` switches back).
+
+## 0.4.1
+
+Not published on its own; it ships with 0.4.6.
+
+- `npm run bench` measures lists of 1,000 to 10,000 items in real Chrome (create, update 10%, reverse, remove half, append) for component items, plain elements and a direct DOM baseline; the README's Performance section shows the results and when to choose which.
+- Assigning `items` sets the prop of a new item before its element goes into the document, so the item component is connected with its item already set and renders once instead of first rendering without it. `replace()` and `upsert()` keep inserting first.
+- README: a fourth example, a list of components (add, remove, sort, toggle, events up from the item), the one-line rule for choosing between `items =` and `replace()`, and how moving an item affects `connected()` and subscriptions with and without `moveBefore`. The introduction and the package description say what the library is built for: type safety and AI coding agents, which can correct their own mistakes from `tsc` errors and the `Fix:` hints of every diagnostic.
+- `state`, `props`, the `view` passed to `render` and the argument of `derive` functions are typed `DeepReadonly` (class instances with private members keep their own type) (exported, with `PropAccessors`): changing an array or object inside them in place is a `tsc` error, since the list and child props compare by reference and would not update. `set()` accepts read-only values. A parent can still assign a child's props.
+
+### Breaking changes
+
+- Code that annotates `render`'s `view`, or a helper that takes the state, with mutable array types (`Item[]`) must use read-only ones (`readonly Item[]` or `DeepReadonly<State>`), and code that changes state objects in place no longer compiles.
+
 ## 0.4.0
 
 ### Lists of components