@studiometa/js-toolkit 4.0.0-alpha.1 → 4.0.0-alpha.2

package/skills/studiometa-js-toolkit/references/guide/going-further/swapping-content.md

@@ -0,0 +1,92 @@
+# Swapping content
+
+`swap()` replaces the **content** of an element with new markup and resolves once the framework has caught up: the mutation is applied, the new components are mounted and the old ones are unmounted.
+
+## The call
+
+```ts
+import { swap } from '@studiometa/js-toolkit';
+
+async function load(target: Element) {
+  const response = await fetch('/fragment');
+  await swap(target, await response.text());
+  // Every eager component in the new markup has mounted.
+}
+```
+
+`swap(target, content, options?)` returns a promise that resolves after [`whenDOMSettled()`](../../api/dom/whenDOMSettled.md).
+
+## What survives
+
+By default the element **itself** is never replaced, so the caller's reference, its `id` and any instance on it survive. Only its children change.
+
+`content` is a markup string parsed in the parsing context of the target, so `<tr>`, `<li>` and `<option>` survive. It can also be an `Element` or a `DocumentFragment`, read as the incoming counterpart of the target, whose children become the new content.
+
+## The four modes
+
+```js
+import { swap, SWAP_MODES } from '@studiometa/js-toolkit';
+
+await swap(el, html); // 'replace' — the default
+await swap(el, html, { mode: SWAP_MODES.PREPEND });
+await swap(el, html, { mode: SWAP_MODES.APPEND });
+await swap(el, html, { mode: SWAP_MODES.MORPH });
+```
+
+| Mode      | Effect                                              |
+| --------- | --------------------------------------------------- |
+| `replace` | the children are replaced                           |
+| `prepend` | the new content goes before the existing children   |
+| `append`  | the new content goes after them                     |
+| `morph`   | the children are morphed in place, keeping identity |
+
+`prepend` and `append` stay in core because they need the same before-and-after script diff as the other two.
+
+### `morph` keeps identity
+
+Nodes, focus, expandos and instances survive a morph — **but markup that is not sent does not**. Two consequences are morphdom's policy, not `swap()`'s:
+
+- an element the incoming markup does not contain is discarded even from a preserved parent;
+- morphdom syncs the `value` of an input from the incoming markup.
+
+Core passes `childrenOnly: true` without `self`, so **attributes are not synced** on the target: `data-component` and `data-mount` are lifecycle declarations of the target, not content.
+
+## `self` — replacing the element itself
+
+```js
+await swap(el, html, { mode: 'replace', self: true });
+```
+
+This is the axis a caller that matches an element of a response to an element of the page needs: an id-matched section otherwise keeps the classes of the element it replaces.
+
+- With `self`, an `Element` content **is** the replacement rather than a container — the only way its own attributes reach the page. A string or a `DocumentFragment` contributes its first top-level element.
+- `replace` puts the replacement in the place of the target, so the target **leaves** the document.
+- `morph` morphs the target from the replacement without `childrenOnly`, so the element and its identity survive while its attributes are updated.
+- `append` and `prepend` add to the children by definition, so `self` with either is a `swap.self-ignored` warning — as is content that holds no element.
+
+## Scripts
+
+A `<script>` produced by the fragment parser is flagged as already started by the HTML specification and stays inert wherever it is moved. It runs only if it is **recreated**, and a script that was already in the page runs **twice** if it is recreated.
+
+`swap()` owns that rule, once. Script adoption follows whatever ends up in the document, so a replacement carrying a script still runs it exactly once.
+
+## Wrapping the mutation
+
+`wrap` is the whole seam. It receives the single mutation of the swap and decides when it runs:
+
+```ts
+import { swap, viewTransition } from '@studiometa/js-toolkit';
+
+async function load(el: Element, html: string) {
+  await swap(el, html, { wrap: (mutate) => viewTransition(mutate) });
+}
+```
+
+[`domUpdate()`](../../api/dom/domUpdate.md) produces that wrapper and nothing else, so an ancestor can claim the lane. Resilience policy stays with `domUpdate()`.
+
+## What is deliberately not in core
+
+- **Attribute syncing in a default `morph`** — see above.
+- **Transitions, view transitions, history, `id` matching and response parsing.** All of these are caller policy.
+
+`swap()` is a free function, not a `Base` method. `morphdom` is a real, statically imported dependency, and the subpath layout contains the cost: it is reachable through `swap()` only, so a page that never swaps never downloads it.

package/skills/studiometa-js-toolkit/references/guide/going-further/testing-components.md

@@ -0,0 +1,137 @@
+# Testing
+
+`@studiometa/js-toolkit/test` ships the nine helpers a component test cannot write for itself.
+
+## Why a subpath exists
+
+**The timing recipe is not derivable.** "Has this component mounted and finished its writes?" is answered by five rounds of a 10 ms timer followed by `defaultScheduler.whenIdle()`, and those two numbers encode the mount observer's delivery latency and the scheduler's lane order.
+
+Neither half works alone: `whenIdle()` can resolve before the observer has reported the element, and a timer can return between two lanes. `defaultScheduler` and `nextFrame` were already public, so the pieces shipped and the recipe did not.
+
+**It depends on no test framework.** Nothing in the module imports a runner, an assertion library or a spy; it reads the DOM and the scheduler only, so it runs under Vitest, under Playwright and on a plain browser page. That is also why it is not on the root barrel: a page has no use for it.
+
+## A first test
+
+```js
+import { afterAll, expect, test } from 'vitest';
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+import { mount, resetDom, resetRegistry, waitFor } from '@studiometa/js-toolkit/test';
+
+class Counter extends Base {
+  static config = { name: 'Counter', refs: ['output'] };
+
+  count = 0;
+
+  onClick() {
+    this.count += 1;
+    this.$refs.output.textContent = String(this.count);
+  }
+}
+
+registerComponent(Counter);
+
+test('it counts clicks', async () => {
+  const root = await mount(`
+    <button data-component="Counter">
+      <span data-ref="output">0</span>
+    </button>
+  `);
+
+  root.querySelector('button').click();
+
+  await waitFor(() => root.querySelector('[data-ref="output"]').textContent === '1');
+});
+
+afterAll(async () => {
+  await resetDom();
+  resetRegistry();
+});
+```
+
+## The helpers
+
+| Helper                           | What it does                                                           |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| `mount(html)`                    | inserts the markup and resolves once the eager components have mounted |
+| `settle()`                       | resolves once the framework has caught up                              |
+| `frames(count?)`                 | awaits animation frames                                                |
+| `waitFor(predicate, options?)`   | polls until the predicate is truthy, and returns that value            |
+| `countRequestedFrames(during)`   | counts the `requestAnimationFrame()` calls made during `during`        |
+| `captureDiagnostics(target?)`    | collects diagnostics and silences their console output                 |
+| `recordEvents(target, ...types)` | records events in order, with their payloads                           |
+| `resetDom()`                     | empties the document body and lets the teardown run                    |
+| `resetRegistry()`                | drops every registration                                               |
+
+See the [full reference](../../api/test/index.md).
+
+## `mount()` returns the wrapper
+
+It returns the `div` it created, **never** the markup's own root, so a fragment of several siblings works and `querySelector()` has a stable handle. `.firstElementChild` is one property away.
+
+## `waitFor()` is a guard and a query
+
+It returns the predicate's truthy value, which makes the same call either:
+
+```js
+// a guard
+await waitFor(() => el.classList.contains('is-open'));
+
+// or a query
+const panel = await waitFor(() => root.querySelector('.panel'));
+```
+
+It polls on a 10 ms cadence and drains the scheduler between attempts. On timeout it throws — with the caller's `message`, or one naming the timeout.
+
+## Transitions: poll, never `settle()`
+
+**A transition's end state is asserted by polling.** A method that starts a transition does not hand it back, and a kept end state lands only after `nextFrame()`, the `from` and `active` states, and either a `transitionend` or one more frame. `settle()` is generous rather than deterministic, which is a flake that passes alone and fails under load.
+
+**Polling for an _absence_ is wrong** for the mirror-image reason: `leaveTransition()` clears the other direction's `to` state synchronously, so the poll passes before anything has happened.
+
+## `recordEvents()` keeps the order
+
+A component's contract is "`open` came before `opened`, and `opened` carried the height it measured", and a call-counting spy throws both away:
+
+```js
+const recording = recordEvents(el, 'open', 'opened');
+
+el.querySelector('button').click();
+
+await waitFor(() => recording.events.length === 2);
+expect(recording.events.map(({ type }) => type)).toEqual(['open', 'opened']);
+expect(recording.events[1].detail).toEqual({ height: 120 });
+
+recording.stop();
+```
+
+Recording several types into one array is the only place their relative order is visible. `$emit` dispatches synchronously but is almost never _called_ synchronously, so the count is awaited with `waitFor`, not read.
+
+## `resetRegistry()` — where the call belongs
+
+It is the inverse `registerComponent()` deliberately lacks, and it is **coarse on purpose**: the element→controller map is a `WeakMap`, so nothing can walk it to dispose live triggers, and a `querySelectorAll()` sweep would still miss detached elements.
+
+Clearing everything works because the mutation-observer path already disposes a controller as its element leaves the DOM — hence the call belongs **after** `resetDom()`.
+
+**Never in an `afterEach`**
+
+Spec files register at module top level, so `resetRegistry()` in an `afterEach` silently unregisters everything for every later test in the file. Put it in an `afterAll`, or call it and register again straight away:
+
+```js
+afterEach(async () => {
+  await resetDom();
+  resetRegistry();
+  registerComponents(Subject, Emitter);
+});
+```
+
+## `countRequestedFrames()` patches a global
+
+It swaps `globalThis.requestAnimationFrame` for a counting wrapper that forwards to the original, and restores it in a `finally` — so it comes back whether `during` returns or throws.
+
+It is here despite the patch because the assertion it serves, "this did not schedule a frame per event", has no other seam: the framework's own scheduler makes the calls, so there is nothing of the component's for a spy to sit on.
+
+**Two concurrent calls would nest their wrappers. Do not.**
+
+## What is deliberately not in it
+
+An instance lookup — `getInstance()` and `getInstances()` on the root barrel answer it — fetch stubs, and pointer sequences. Each is either specific to one spec or already served by `vi.fn()` and `@vitest/browser`'s `userEvent`.

package/skills/studiometa-js-toolkit/references/guide/going-further/typing-components.md

@@ -0,0 +1,190 @@
+# TypeScript
+
+`Base` takes an optional props type. It types `$refs` and `$options`, and it checks the event names and payloads of `$emit()`.
+
+## The props type
+
+```ts
+import { Base } from '@studiometa/js-toolkit';
+
+class Slider extends Base<{
+  $el: HTMLDivElement;
+  $refs: {
+    next: HTMLButtonElement;
+    items: HTMLElement[];
+  };
+  $options: {
+    speed: number;
+    loop: boolean;
+  };
+  $emits: {
+    goto: { index: number };
+    stop: void;
+  };
+}> {
+  static config = {
+    name: 'Slider',
+    refs: ['next', 'items[]'],
+    options: {
+      speed: { type: Number, default: 1 },
+      loop: { type: Boolean, default: true },
+    },
+  };
+
+  mounted() {
+    this.$refs.next.disabled = true;
+    this.$refs.items[0];
+    this.$options.speed;
+    this.$emit('goto', { index: 1 });
+    this.$emit('stop');
+  }
+}
+```
+
+Four keys, all optional:
+
+| Key        | Types                                                     |
+| ---------- | --------------------------------------------------------- |
+| `$el`      | the root element                                          |
+| `$refs`    | each declared ref — an array for a list ref               |
+| `$options` | each declared option                                      |
+| `$emits`   | each event name to its payload object, or `void` for none |
+
+`$emits` replaces the runtime `config.emits` of v3. **Nothing of it stays in the bundle.**
+
+## Extending a component
+
+A component can take a props parameter of its own. This is how one component extends another:
+
+```ts
+import { Base, type BaseConfig, type BaseProps } from '@studiometa/js-toolkit';
+
+interface ActionProps extends BaseProps {
+  $options: { target: string };
+}
+
+class Action<T extends BaseProps = BaseProps> extends Base<ActionProps & T> {
+  // Annotated, so a subclass is free to declare a different config.
+  static config: BaseConfig = {
+    name: 'Action',
+    options: { target: String },
+  };
+
+  mounted() {
+    this.$options.target; // string
+  }
+}
+
+class SafeAction extends Action<{ $options: { confirm: boolean } }> {
+  static config = {
+    name: 'SafeAction',
+    options: { confirm: Boolean },
+  };
+
+  mounted() {
+    this.$options.target; // still string
+    this.$options.confirm; // boolean
+  }
+}
+```
+
+Each prop is read as an intersection with its default, such as `T['$options'] & Record<string, unknown>`.
+
+**The price of the intersection**
+
+An option or a ref a component does **not** declare reads as `unknown`, or as `HTMLElement | HTMLElement[]`, rather than as an error. Declared props keep their exact types. This is the cost of making extension work, and it was chosen deliberately over a conditional type.
+
+`$options` is read through the same intersection and then mapped to `Readonly<…>`, which has one price of its own: a mapped type over a props parameter is deferred, so inside a class **generic in its props** a declared option is a usable value of its declared type rather than a type identical to it. Reading it, passing it and annotating it all work; asserting its identity, or assigning one option to a variable inferred from another, needs an annotation.
+
+`src/props.spec.ts` holds the assertions, and `npm run lint:types` enforces them.
+
+## Handler payloads
+
+A method named by convention is **not typed by convention** — the name is resolved at runtime. Annotate the payload:
+
+```ts
+import { Base, type DelegatedEvent, type GlobalEvent, type RefEvent } from '@studiometa/js-toolkit';
+
+class Child extends Base<{ $emits: { open: { height: number } } }> {
+  static config = { name: 'Child' };
+}
+class Parent extends Base {
+  static config = { name: 'Parent', components: { Child }, refs: ['dots[]'] };
+
+  onChildOpen({ target, payload }: DelegatedEvent<Child, 'open'>) {}
+
+  onDotsClick({ target, index }: RefEvent<HTMLButtonElement>) {}
+
+  onWindowResize({ event, target }: GlobalEvent<UIEvent>) {}
+}
+```
+
+The [`@on` decorator](../../api/decorators/on.md) does not remove the annotation — it **checks** it. The decorator derives the payload type its target implies and the method signature has to match, so a wrong annotation is a type error rather than a silent mismatch:
+
+```ts
+import { Base, component, on, type DelegatedEvent } from '@studiometa/js-toolkit';
+
+class Child extends Base<{ $emits: { open: { height: number } } }> {
+  static config = { name: 'Child' };
+}
+@component({ name: 'Parent', components: { Child } })
+class Parent extends Base {
+  @on(Child, 'open')
+  onOpen({ payload }: DelegatedEvent<Child, 'open'>) {
+    payload.height; // number
+  }
+}
+```
+
+A decorator cannot infer a method's own parameters — the method signature is checked _against_ what the decorator expects, not derived from it. Annotate the payload either way; with `@on` the annotation is verified against a real target.
+
+## Config typing
+
+`$config` walks the prototype chain and merges every config it finds, so an intermediate class must not narrow the type its subclasses need.
+
+Left alone, `static config = { … }` infers a **literal** type, and every subclass has to match it — a subclass that adds an option gets `Class static side 'typeof SafeAction' incorrectly extends base class static side 'typeof Action'`. Annotate the intermediate class instead:
+
+```ts
+import { Base, type BaseConfig } from '@studiometa/js-toolkit';
+
+class AbstractControl extends Base {
+  static config: BaseConfig = {
+    name: 'AbstractControl',
+    refs: ['button'],
+  };
+}
+```
+
+## Compiler options
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "experimentalDecorators": false,
+    "useDefineForClassFields": true,
+    "strict": true
+  }
+}
+```
+
+Stage-3 decorators need no flag on TypeScript 5. `experimentalDecorators` must be **off**.
+
+## JSDoc
+
+The props type works from JSDoc too, for a project with no `.ts` files:
+
+```js
+/**
+ * @extends {Base<{ $refs: { output: HTMLElement }, $options: { step: number } }>}
+ */
+class Counter extends Base {
+  static config = {
+    name: 'Counter',
+    refs: ['output'],
+    options: { step: { type: Number, default: 1 } },
+  };
+}
+```

package/skills/studiometa-js-toolkit/references/guide/going-further/using-decorators.md

@@ -0,0 +1,168 @@
+# Decorators
+
+**Every decorator is a thin wrapper over a function API that works without it.** No engine ships stage-3 decorators, so a page that loads the package from an ESM CDN keeps `registerComponent`, `$provide`, `$watchChildren`, `$read`, `$write` and the `on<Child><Event>` method names.
+
+Decorators are sugar. They are never a requirement.
+
+## The six
+
+| Decorator                           | Wraps                                   | Notes                                                                           |
+| ----------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
+| `@component({ name })`              | `static config` + `registerComponent()` | Registers as soon as the class is defined.                                      |
+| `@on(target, type)` / `@on(type)`   | the `on<Child><Event>` names            | The target is a name or a value.                                                |
+| `@provide(key)` / `@inject(key)`    | `$provide()` / `$inject()`              | The shape of Lit's `@provide` and `@consume`.                                   |
+| `@children(nameOrClass, callbacks)` | `$watchChildren()`                      | Exact name, or constructor and subclasses. Callbacks are bound to the instance. |
+| `@read` / `@write`                  | `$read()` / `$write()`                  | Runs the method body in that phase, cancelled on unmount.                       |
+
+Each value decorator works on a plain field and on an `accessor` field.
+
+## A component with decorators
+
+```ts
+import {
+  Base,
+  children,
+  component,
+  on,
+  type ChildrenCollection,
+  type DelegatedEvent,
+} from '@studiometa/js-toolkit';
+
+@component({ name: 'AccordionItem' })
+class AccordionItem extends Base<{ $emits: { open: void } }> {
+  @on('click')
+  toggle() {
+    this.$emit('open');
+  }
+}
+
+@component({ name: 'Accordion', components: { AccordionItem } })
+class Accordion extends Base {
+  @children(AccordionItem)
+  items!: ChildrenCollection<AccordionItem>;
+
+  @on(AccordionItem, 'open')
+  closeOthers({ target }: DelegatedEvent<AccordionItem, 'open'>) {
+    for (const item of this.items) {
+      if (item !== target) item.$el.removeAttribute('data-option-open');
+    }
+  }
+}
+```
+
+## `@component` and `static config` merge
+
+They merge in a class initializer, which runs after the fields and inside the class definition, so `registerComponent()` on the next line reads the finished config. The rules are the rules of `$config`: `refs` union, `options` and `components` merge entry by entry, a declared value overrides.
+
+A key both sides declare differently is reported as `component.config-conflict`.
+
+**The decorator is applied last**, so it registers a finished class.
+
+## `@on` — a name or a value
+
+```ts
+import { Base, component, on } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base {
+  static config = { name: 'AccordionItem' };
+}
+@component({ name: 'Demo', components: { AccordionItem }, refs: ['dots[]'] })
+class Demo extends Base {
+  @on('click') a(event: MouseEvent) {} // own element, typed from HTMLElementEventMap
+  @on('submit') b(event: SubmitEvent) {} // idem
+  @on('dots[]', 'click') c() {} // a ref, named as declared
+  @on('AccordionItem', 'open') d() {} // a child, by name — imports nothing
+  @on(AccordionItem, 'open') e() {} // a child, by class — the class is the type
+  @on(window, 'load') f() {} // a global
+  @on(document, 'click') g() {} // a global
+}
+```
+
+- **The one-argument form types its event from `HTMLElementEventMap`**, so `@on('click')` hands over a `MouseEvent` and `@on('submit')` a `SubmitEvent`. A name outside that map is a component event, whose detail only its emitter knows, so the handler declares the type it expects: `@on('content') inject(event: CustomEvent<{ content: string }>)`.
+- **A class resolves to its merged `config.name`** and lands on the same delegated entry as the string form. The class is the type, so `target` is the component and `payload` comes from its `$emits`.
+- **A lazy child needs the string form.** `@on('Child', 'open')` imports nothing; a thunk is not a target and both the overloads and the runtime refuse it.
+- **A name is a child or a ref**, resolved children-first, so the handler is typed as `DelegatedEvent` or `RefEvent`.
+- **A ref is named as it is declared**: `@on('dots[]', 'click')` for `config.refs: ['dots[]']`. A mismatched `@on('dots', 'click')` warns at bind time when the other spelling is declared. A name that matches nothing stays silent.
+- **A global target goes through the same binding `onWindow<Event>` uses**: bubble phase, one listener per mount cycle, removed by `$unmount()`. `@on(window, 'click')` types the event from `WindowEventMap` and falls back to `Event`.
+- **Nothing is reserved in its string space**: `'Window'` means the child and `window` means the global.
+- **Any other `EventTarget` is refused**, by the overloads and by a `TypeError`. A decorator is evaluated once, at class definition, so an arbitrary target can only be a module-scope value.
+
+## `@read` and `@write`
+
+They are **leaf-method sugar: the phase belongs to the call site.**
+
+```ts
+import { Base, component, read, write } from '@studiometa/js-toolkit';
+
+@component({ name: 'Measure' })
+class Measure extends Base {
+  #height = 0;
+
+  @read
+  measure() {
+    this.#height = this.$el.scrollHeight;
+  }
+
+  @write
+  apply() {
+    this.$el.style.setProperty('--height', `${this.#height}px`);
+  }
+}
+```
+
+**Decorate a method nobody overrides**
+
+A phase decorator returns a wrapper around the method it decorates, and that wrapper is a property of **that class**. A subclass that overrides the method defines its own, undecorated, and `this.method()` resolves to it — so the base's scheduling disappears and the body runs in whatever phase the caller was in.
+
+A **template method** — a base that schedules work its subclasses implement — schedules at the call site instead:
+
+```js
+// in the base, where the call is
+state.subscribe((value) => this.$write(() => this.update(value)));
+```
+
+The alternative, dispatching a decorated method through something a subclass cannot replace, was refused: it would make a decorator's behaviour depend on inheritance depth, which nothing else in v4 does.
+
+### Stacking with `@on`
+
+The skip is keyed by the method name, so `@on` and `@read`/`@write` stack in either order. The order decides what the listener calls:
+
+- a phase decorator written **below** the `@on`, nearest the method, schedules the body of the handler;
+- one written **above** it schedules direct calls only.
+
+Write `@read` and `@write` closest to the method body.
+
+## Build setup
+
+Vite 8 transforms TypeScript with Oxc, which passes decorators through untouched. The package itself compiles them with `@rollup/plugin-swc` and `decoratorVersion: '2023-11'`, filtered to the files that contain a decorator. See [Installation](../introduction/installation.md#with-a-build-step).
+
+## The same component, without any of them
+
+```ts
+import { Base, registerComponent, type DelegatedEvent } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base<{ $emits: { open: void } }> {
+  static config = { name: 'AccordionItem' };
+
+  onClick() {
+    this.$emit('open');
+  }
+}
+
+class Accordion extends Base {
+  static config = {
+    name: 'Accordion',
+    components: { AccordionItem },
+  };
+
+  items = this.$watchChildren(AccordionItem);
+
+  onAccordionItemOpen({ target }: DelegatedEvent<AccordionItem, 'open'>) {
+    for (const item of this.items) {
+      if (item !== target) item.$el.removeAttribute('data-option-open');
+    }
+  }
+}
+
+registerComponent(Accordion);
+```