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

package/skills/studiometa-js-toolkit/references/api/context/subscribeContext.md

@@ -0,0 +1,71 @@
+# subscribeContext
+
+```ts
+subscribeContext<T>(el: Element, key: ContextKey<T>, onProvide: ContextCallback<T>): () => void
+```
+
+The subscription behaviour of the WICG context protocol: **every** answer, as providers come and go.
+
+## Usage
+
+```ts
+import { Base, createContext, subscribeContext } from '@studiometa/js-toolkit';
+
+interface GroupApi {
+  join(peer: Base): () => void;
+}
+const DisclosureGroupContext = createContext<GroupApi>('disclosure-group');
+class Disclosure extends Base {
+  static config = { name: 'Disclosure' };
+
+  group?: GroupApi;
+
+  mounted() {
+    return subscribeContext(this.$el, DisclosureGroupContext, (group) => {
+      this.group = group;
+      const leave = group.join(this);
+
+      // The teardown for *this* value.
+      return () => {
+        leave();
+        this.group = undefined;
+      };
+    });
+  }
+}
+```
+
+**Parameters**
+
+- `onProvide` — **required**. It runs synchronously for each answer and receives the value and the same unsubscribe function the helper returns.
+
+**Return value**
+
+- the unsubscribe function. Call it from `mounted()`'s return value to get an unmount-scoped lifetime.
+
+## A new answer replaces; it never accumulates
+
+The callback can return a teardown for the value it received. That teardown runs:
+
+- before the next **different** value;
+- on unsubscribe.
+
+**An identical value is not an answer**, so nothing runs and nothing is torn down.
+
+That is what lets a member move between groups correctly: `join()` returns its own `leave`, the teardown calls it, and a member that moves to a nearer group leaves the old one first.
+
+## When it fires
+
+**The trigger is the mount announcement**, not a broadcast from the provider, and it runs after `mounted()`.
+
+The optional `context-subscription` module keeps **one** listener on the document, attached on the first subscription and never at import time.
+
+Two `contains()` calls bound the cost per mount: the new provider must contain the consumer, and it must sit inside the provider that answers it now. **A mount that changes nothing checks nothing.**
+
+## What it holds
+
+**The registry holds nothing.** A subscription is anchored on its consumer element through a `WeakMap`, and the iterable index holds `WeakRef`s that the sweep prunes.
+
+Callback and teardown failures are isolated — `callback.context-subscription-failed` and `callback.context-teardown-failed` — so one consumer cannot stop the shared sweep.
+
+`context.ts` and the `Base` graph import **none** of this optional state, so a page that never subscribes pays for none of it.

package/skills/studiometa-js-toolkit/references/api/decorators/children.md

@@ -0,0 +1,92 @@
+# @children
+
+```ts
+children<T extends Base>(name: string, callbacks?: WatchChildrenCallbacks<T>): ValueDecorator<ChildrenCollection<T>>
+children<T extends BaseConstructor>(ComponentClass: T, callbacks?: WatchChildrenCallbacks<InstanceType<T>>): ValueDecorator<ChildrenCollection<InstanceType<T>>>
+```
+
+Field sugar over [`$watchChildren()`](../instance-methods.md#watchchildren).
+
+## Usage
+
+```ts
+import { Base, children, component, type ChildrenCollection } from '@studiometa/js-toolkit';
+
+class SliderItem extends Base {
+  static config = { name: 'SliderItem' };
+}
+@component({ name: 'Slider', components: { SliderItem } })
+class Slider extends Base {
+  // Exact `config.name`.
+  @children('SliderItem')
+  items!: ChildrenCollection<Base>;
+
+  // Also every named subclass, through `instanceof`.
+  @children(SliderItem)
+  allItems!: ChildrenCollection<SliderItem>;
+
+  reset() {
+    for (const item of this.items) {
+      item.$el.removeAttribute('data-option-active');
+    }
+  }
+}
+```
+
+The collection is **live**, in document order whatever the mount order is.
+
+## Callbacks
+
+```ts
+import { Base, children, component, type ChildrenCollection } from '@studiometa/js-toolkit';
+
+class SliderItem extends Base {
+  static config = { name: 'SliderItem' };
+}
+@component({ name: 'Slider', components: { SliderItem } })
+class Slider extends Base {
+  @children(SliderItem, {
+    added(item) {
+      // `this` is the Slider instance.
+      this.reindex();
+    },
+    removed(item) {
+      this.reindex();
+    },
+  })
+  items!: ChildrenCollection<SliderItem>;
+
+  reindex() {}
+}
+```
+
+**The callbacks are bound to the instance**, which is the one thing this form gives over the function form.
+
+## It is instance-scoped
+
+The subscription stays active through unmount and mount cycles, for the whole life of the watching instance. It is never released and dies with the element.
+
+The initial sweep is deferred to a microtask, because a field initializer runs before the element is in place; the announcement listeners attach at once, so nothing is missed.
+
+## The function form
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class SliderItem extends Base {
+  static config = { name: 'SliderItem' };
+}
+
+class Slider extends Base {
+  static config = { name: 'Slider', components: { SliderItem } };
+
+  items = this.$watchChildren(SliderItem, {
+    added: (item) => this.reindex(),
+    removed: (item) => this.reindex(),
+  });
+
+  reindex() {}
+}
+```
+
+Identical behaviour, no build step. Note the arrow functions: the function form does not bind the callbacks for you.

package/skills/studiometa-js-toolkit/references/api/decorators/component.md

@@ -0,0 +1,75 @@
+# @component
+
+```ts
+component(config: BaseConfig): (value, context) => void
+```
+
+Writes `static config` and calls [`registerComponent()`](../registry/registerComponent.md), in one step.
+
+## Usage
+
+```ts
+import { Base, component } from '@studiometa/js-toolkit';
+
+@component({
+  name: 'Slider',
+  refs: ['next', 'items[]'],
+  options: { speed: { type: Number, default: 1 } },
+})
+class Slider extends Base {
+  onNextClick() {}
+}
+```
+
+The class is registered **as soon as it is defined**, so there is no separate registration line to forget.
+
+## It merges with `static config`
+
+```ts
+import { Base, component } from '@studiometa/js-toolkit';
+
+@component({ name: 'Slider', refs: ['next'] })
+class Slider extends Base {
+  static config = { name: 'Slider', options: { speed: Number } };
+}
+```
+
+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`:
+
+| Key                     | Merge rule     |
+| ----------------------- | -------------- |
+| `refs`                  | union          |
+| `options`, `components` | entry by entry |
+| a declared scalar       | overrides      |
+
+A key both sides declare **differently** is reported as `component.config-conflict`.
+
+## It is applied last
+
+Among stacked class decorators, `@component` is applied last, so it registers a finished class. That is what lets a service mixin decorator sit under it:
+
+```ts
+import { Base, component, withScroll } from '@studiometa/js-toolkit';
+
+@component({ name: 'Header' })
+@withScroll()
+class Header extends Base {
+  scrolled() {}
+}
+```
+
+## The function form
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class Slider extends Base {
+  static config = { name: 'Slider', refs: ['next'] };
+}
+
+registerComponent(Slider);
+```
+
+Identical behaviour, no build step.

package/skills/studiometa-js-toolkit/references/api/decorators/index.md

@@ -0,0 +1,41 @@
+# Decorators
+
+**Sugar, never a requirement.** No engine ships stage-3 decorators, so every decorator here is a thin wrapper over a function API that works without it.
+
+| Decorator                                        | Wraps                                   |
+| ------------------------------------------------ | --------------------------------------- |
+| [`@component(config)`](component.md)         | `static config` + `registerComponent()` |
+| [`@on(target, type)`](on.md)                 | the `on<Child><Event>` names            |
+| [`@provide(key)`](provide.md)                | `$provide()`                            |
+| [`@inject(key)`](inject.md)                  | `$inject()`                             |
+| [`@children(nameOrClass, cb?)`](children.md) | `$watchChildren()`                      |
+| [`@read` / `@write`](read-write.md)          | `$read()` / `$write()`                  |
+
+The service mixins have a decorator form too — see [Mixins](../services/mixins.md).
+
+## A page with no build step keeps everything
+
+`registerComponent`, `$provide`, `$watchChildren`, `$read`, `$write` and the `on<Child><Event>` method names are all there is. A page loaded from an ESM CDN uses the same framework with none of this file's contents.
+
+## Each value decorator works on a plain field or an `accessor`
+
+```ts
+import { Base, component, inject, createContext } from '@studiometa/js-toolkit';
+
+const Key = createContext<number>('key');
+@component({ name: 'Demo' })
+class Demo extends Base {
+  @inject(Key) a?: number;
+  @inject(Key) accessor b: number | undefined;
+}
+```
+
+## Build setup
+
+Vite 8 transforms TypeScript with Oxc, which passes decorators through untouched, so a transform has to compile them. TypeScript 5 needs `experimentalDecorators: false`. See [Installation](../../guide/introduction/installation.md#with-a-build-step).
+
+The package itself compiles them with `@rollup/plugin-swc` and `decoratorVersion: '2023-11'`, filtered to the files that contain a decorator.
+
+## Read next
+
+[Decorators](../../guide/going-further/using-decorators.md) walks the whole set, including how they stack and why the phase decorators are leaf-method sugar.

package/skills/studiometa-js-toolkit/references/api/decorators/inject.md

@@ -0,0 +1,73 @@
+# @inject
+
+```ts
+inject<T>(key: ContextKey<T>): ValueObserver<T | undefined>
+```
+
+Field sugar over [`$inject()`](../instance-methods.md#inject). **It asks once, at construction.**
+
+## Usage
+
+```ts
+import { Base, component, createContext, inject, type Signal } from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+@component({ name: 'Output' })
+class Output extends Base {
+  @inject(CountContext)
+  count?: Signal<number>;
+
+  mounted() {
+    // The request may not have been answered yet.
+    return this.count?.subscribe((value) => {
+      this.$el.textContent = String(value);
+    });
+  }
+}
+```
+
+The field type includes `undefined`, because the request is asynchronous and the value lands when a provider answers.
+
+## When to use it, and when not
+
+| Situation                                                      | Reach for                                                  |
+| -------------------------------------------------------------- | ---------------------------------------------------------- |
+| the value is there for the whole life of the instance          | `@inject`                                                  |
+| the consumer must be able to wait through several mount cycles | `$inject()` from `mounted()`                               |
+| the answer is optional and there is a fallback                 | `$injectSync()`                                            |
+| the provider comes and goes                                    | [`subscribeContext()`](../context/subscribeContext.md) |
+
+**`@inject` asks once, at construction.** `$inject()` from `mounted()` is unmount-scoped: `$unmount()` cancels the pending request, and a new mount asks again. That difference is the whole reason both exist.
+
+## A plain field or an `accessor`
+
+```ts
+import { Base, component, createContext, inject, type Signal } from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+@component({ name: 'Output' })
+class Output extends Base {
+  @inject(CountContext) a?: Signal<number>;
+  @inject(CountContext) accessor b: Signal<number> | undefined;
+}
+```
+
+## The function form
+
+```ts
+import { Base, createContext, type Signal } from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+class Output extends Base {
+  static config = { name: 'Output' };
+
+  async mounted() {
+    const count = await this.$inject(CountContext);
+    return count.subscribe((value) => {
+      this.$el.textContent = String(value);
+    });
+  }
+}
+```
+
+The `await` form has no `undefined` to handle, which is usually the better trade.

package/skills/studiometa-js-toolkit/references/api/decorators/on.md

@@ -0,0 +1,149 @@
+# @on
+
+```ts
+on(type: string)
+on(target: typeof window | typeof document, type: string)
+on(child: BaseConstructor | string, type: string)
+```
+
+Binds a method to an event source, in place of the `on<X><Event>` naming convention.
+
+## Every form
+
+```ts
+import {
+  Base,
+  component,
+  on,
+  type DelegatedEvent,
+  type GlobalEvent,
+  type RefEvent,
+} from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base<{ $emits: { open: { height: number } } }> {
+  static config = { name: 'AccordionItem' };
+}
+@component({ name: 'Demo', components: { AccordionItem }, refs: ['dots[]'] })
+class Demo extends Base {
+  // The component's own element, typed from HTMLElementEventMap.
+  @on('click') a(event: MouseEvent) {}
+  @on('submit') b(event: SubmitEvent) {}
+
+  // A ref, named as it is declared.
+  @on('dots[]', 'click') c({ index }: RefEvent) {}
+
+  // A child, by name — imports nothing, and the payload stays `unknown`.
+  @on('AccordionItem', 'open') d({ payload }: DelegatedEvent<AccordionItem>) {}
+
+  // A child, by class — the class is the type, so the payload is typed.
+  @on(AccordionItem, 'open') e({ payload }: DelegatedEvent<AccordionItem, 'open'>) {}
+
+  // A global.
+  @on(window, 'resize') f({ event }: GlobalEvent<UIEvent>) {}
+  @on(document, 'click') g({ event }: GlobalEvent<MouseEvent>) {}
+}
+```
+
+## The one-argument form
+
+It 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:
+
+```ts
+import { Base, component, on } from '@studiometa/js-toolkit';
+@component({ name: 'Slot' })
+class Slot extends Base {
+  @on('content')
+  inject(event: CustomEvent<{ content: string }>) {
+    this.$el.innerHTML = event.detail.content;
+  }
+}
+```
+
+## 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[]']`. The rule is one rule — the declaration spelling refers to the entry, and the property spelling is used where a name is derived from it.
+
+A mismatched `@on('dots', 'click')` gives a warning at bind time when the other spelling is declared. A name that matches nothing stays **silent**.
+
+## A class resolves to its merged `config.name`
+
+It lands on the same delegated entry as the string form, so the two behave identically **at runtime**. They differ in what they can type:
+
+| Form                           | `target`        | `payload`               |
+| ------------------------------ | --------------- | ----------------------- |
+| `@on(AccordionItem, 'open')`   | `AccordionItem` | typed from its `$emits` |
+| `@on('AccordionItem', 'open')` | the annotation  | `unknown`               |
+
+**Only the class form carries the payload type**, because only it has the class to read `$emits` from. The string form's event name is a plain `string` as far as the type system is concerned, so annotate it as `DelegatedEvent<AccordionItem>` and narrow the payload yourself:
+
+```ts
+import { Base, component, on, type DelegatedEvent } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base<{ $emits: { open: { height: number } } }> {
+  static config = { name: 'AccordionItem' };
+}
+@component({ name: 'Accordion', components: { AccordionItem } })
+class Accordion extends Base {
+  @on('AccordionItem', 'open')
+  byName({ payload }: DelegatedEvent<AccordionItem>) {
+    (payload as { height: number }).height;
+  }
+
+  @on(AccordionItem, 'open')
+  byClass({ payload }: DelegatedEvent<AccordionItem, 'open'>) {
+    payload.height; // number, with no cast
+  }
+}
+```
+
+**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 — so a lazy child is exactly the case that trades the typed payload for the deferred import.
+
+## Globals
+
+`@on(window, 'click')` types the event from `WindowEventMap` and falls back to `Event`. It goes through the same binding `onWindow<Event>` uses: **bubble phase, one listener per mount cycle, removed by `$unmount()`**.
+
+**Nothing is reserved in its string space.** `@on('Window', 'resize')` means the child named `Window`; `@on(window, 'resize')` means the global. That is the escape from the reserved `onWindow` prefix.
+
+## Any other `EventTarget` is refused
+
+By the overloads, and by a `TypeError` at runtime. A decorator is evaluated once, at class definition, so an arbitrary target could only ever be a module-scope value — and binding a component's lifetime to one would be a leak with no way to see it.
+
+## It checks the annotation; it does not replace it
+
+A decorator cannot infer a method's own parameters: the method signature is checked **against** what the decorator expects. So annotate the payload either way — with `@on`, the annotation is verified against a real target instead of being taken on trust.
+
+## Stacking
+
+The skip is keyed by the **method name**, so `@on` stacks with itself and with `@read`/`@write` in either order:
+
+```ts
+import { Base, component, on, write } from '@studiometa/js-toolkit';
+
+class Child extends Base {
+  static config = { name: 'Child' };
+}
+@component({ name: 'Demo', components: { Child } })
+class Demo extends Base {
+  // One method, two events.
+  @on('Child', 'open')
+  @on('Child', 'close')
+  track() {}
+
+  // A phase decorator nearest the method schedules the handler's body.
+  @on('click')
+  @write
+  paint() {}
+}
+```
+
+See [`@read` / `@write`](read-write.md).
+
+## The function form
+
+The `on<X><Event>` method names. Identical behaviour, no build step. See [Events hooks](../methods-hooks-events.md).

package/skills/studiometa-js-toolkit/references/api/decorators/provide.md

@@ -0,0 +1,77 @@
+# @provide
+
+```ts
+provide<T>(key: ContextKey<T>): ValueDecorator<T>
+```
+
+Field sugar over [`$provide()`](../instance-methods.md#provide).
+
+## Usage
+
+```ts
+import {
+  Base,
+  component,
+  createContext,
+  provide,
+  signal,
+  type Signal,
+} from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+@component({ name: 'Counter' })
+class Counter extends Base {
+  @provide(CountContext)
+  count = signal(0);
+
+  increment() {
+    this.count.value += 1;
+  }
+}
+```
+
+The field's value is provided to the subtree, **as it is**. Nothing is wrapped, so the type of the key is the contract from end to end.
+
+## It is instance-scoped
+
+Like `$provide()`, it is never released and dies with the element. A component whose declaration is withdrawn keeps providing until its element goes.
+
+## A plain field or an `accessor`
+
+```ts
+import {
+  Base,
+  component,
+  createContext,
+  provide,
+  signal,
+  type Signal,
+} from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+@component({ name: 'Counter' })
+class Counter extends Base {
+  @provide(CountContext) a = signal(0);
+  @provide(CountContext) accessor b = signal(0);
+}
+```
+
+## The function form
+
+```ts
+import { Base, createContext, signal, type Signal } from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+class Counter extends Base {
+  static config = { name: 'Counter' };
+
+  count = this.$provide(CountContext, signal(0));
+}
+```
+
+Identical behaviour, no build step — and `$provide()` returns the value, which is why the field initializer reads the same way.
+
+## See also
+
+- [`@inject`](inject.md) — the other half
+- [Shared state](../../guide/going-further/sharing-state.md)

package/skills/studiometa-js-toolkit/references/api/decorators/read-write.md

@@ -0,0 +1,93 @@
+# @read and @write
+
+```ts
+read: (value: VoidMethod, context: ClassMethodDecoratorContext) => VoidMethod;
+write: (value: VoidMethod, context: ClassMethodDecoratorContext) => VoidMethod;
+```
+
+Runs the method body in the frame's `read` or `write` phase, cancelled on unmount. They are sugar over [`$read()`](../instance-methods.md#read-and-write) and `$write()`.
+
+## Usage
+
+```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`);
+  }
+}
+```
+
+Every read runs before every write, once, before paint. A `read` scheduled from a `write` runs in the **next** frame; a `write` scheduled from a `read` runs in the **same** frame.
+
+## They are leaf-method sugar: the phase belongs to the call site
+
+**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, to buy a convenience no consumer has asked for.
+
+## Stacking with `@on`
+
+The skip is keyed by the method name, so the two stack in either order — and **the order decides what the listener calls**:
+
+| Written                   | Schedules               |
+| ------------------------- | ----------------------- |
+| `@on(...)` above `@write` | the body of the handler |
+| `@write` above `@on(...)` | direct calls only       |
+
+```ts
+import { Base, component, on, write } from '@studiometa/js-toolkit';
+@component({ name: 'Demo' })
+class Demo extends Base {
+  @on('click')
+  @write
+  paint() {}
+}
+```
+
+**Write `@read` and `@write` closest to the method body.**
+
+## The function form
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Measure extends Base {
+  static config = { name: 'Measure' };
+
+  #height = 0;
+
+  measure() {
+    return this.$read(() => {
+      this.#height = this.$el.scrollHeight;
+    });
+  }
+
+  apply() {
+    return this.$write(() => {
+      this.$el.style.setProperty('--height', `${this.#height}px`);
+    });
+  }
+}
+```
+
+The function form also gives you the [`ScheduledTask`](../scheduler/defaultScheduler.md) handle — its promise and its `cancel()` — which the decorator discards.