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

package/skills/studiometa-js-toolkit/references/api/configuration.md

@@ -0,0 +1,169 @@
+# Configuration
+
+`static config` declares everything the framework needs to know about a component before an instance exists.
+
+```ts
+interface BaseConfig {
+  name: string;
+  components?: Record<string, BaseConstructor | ComponentImporter>;
+  refs?: string[];
+  options?: Record<string, OptionDefinition>;
+  mountStrategy?: MountStrategy;
+}
+```
+
+## `config.name`
+
+**Required.** The name the registry registers under, the token `data-component` writes, and the prefix of every instance's [`$id`](instance-properties.md#id).
+
+The name comes from the **merged** config, so a subclass that extends a component and forgets to rename registers under the name it inherited — and collides — rather than under `undefined`.
+
+## `config.refs`
+
+The refs the component declares. A list ref keeps its `[]`:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Tabs extends Base {
+  static config = {
+    name: 'Tabs',
+    refs: ['list', 'tabs[]', 'panels[]'],
+  };
+}
+```
+
+See [Refs](../guide/introduction/managing-refs.md) and [`data-ref`](html/data-ref.md).
+
+## `config.options`
+
+Each entry is a type, a tuple of types, or an object with `type` and `default`:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Slider extends Base {
+  static config = {
+    name: 'Slider',
+    options: {
+      label: String, // short form
+      speed: { type: Number, default: 1 }, // primitive default
+      loop: { type: Boolean, default: true },
+      tween: { type: Object, default: () => ({}) }, // factory required
+      offset: [Number, Array], // a union, in order
+    },
+  };
+}
+```
+
+The five option types are `String`, `Number`, `Boolean`, `Array` and `Object`. `Function` is not one, which is what makes a function `default` unambiguously a factory.
+
+See [Options](../guide/introduction/managing-options.md) and [`data-option-<name>`](html/data-option.md).
+
+## `config.components`
+
+The declared **family**. It does two jobs, and neither is ownership:
+
+1. it registers those names when this component registers, so one `registerComponent()` call covers a whole tree;
+2. it gives the name set that `on<Child><Event>` resolution needs.
+
+```js
+static config = {
+  name: 'Accordion',
+  components: {
+    AccordionItem, // a class
+    Icon: () => import('./Icon.js'), // a thunk — its own chunk
+  },
+};
+```
+
+- **The key supplies the name**, so a lazy child is a name the registry knows with nothing downloaded.
+- A thunk is deferred rather than resolved, and becomes a lazy entry of the same registry.
+- **First wins, quietly.** Several parents declaring the same lazy child is the normal case.
+- A value written with `class` that does not extend `Base` is reported as `component.invalid-family-declaration`, where it is declared.
+
+See [Autoloading](../guide/going-further/autoloading.md).
+
+## `config.mountStrategy`
+
+The component's default answer to _when_. Any element overrides it with `data-mount`:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Map extends Base {
+  static config = {
+    name: 'Map',
+    mountStrategy: 'visible',
+  };
+}
+```
+
+See [Mount strategies](../guide/going-further/mount-strategies.md) and [`data-mount`](html/data-mount.md).
+
+## Merging along the prototype chain
+
+`$config` walks the prototype chain and merges every config it finds:
+
+| Key             | Merge rule                  |
+| --------------- | --------------------------- |
+| `refs`          | union                       |
+| `options`       | entry by entry              |
+| `components`    | entry by entry              |
+| `name`          | the most derived class wins |
+| `mountStrategy` | the most derived class wins |
+
+A subclass that states a `components` key again wins for **that key only**.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class AbstractControl extends Base {
+  static config = {
+    name: 'AbstractControl',
+    refs: ['button'],
+    options: { label: String },
+  };
+}
+
+class NavigationControl extends AbstractControl {
+  static config = {
+    name: 'NavigationControl',
+    refs: ['compass'], // merged: ['button', 'compass']
+    options: { showCompass: Boolean }, // merged with `label`
+  };
+}
+```
+
+An intermediate class should declare `static config: BaseConfig`, or let TypeScript infer a literal type every subclass matches.
+
+**The registry reads the merged config too**, before any instance exists, through `resolveConfig()`. That is how it knows the mount strategy of a pair, the family to register, and the name a class registers under.
+
+## There is no `withExtraConfig()`
+
+To extend a component with a different config, declare a class. To extend one you cannot edit, do it in expression position:
+
+```js
+registerComponent(
+  class extends Vendor {
+    static config = { name: 'CompactVendor', options: { compact: Boolean } };
+  },
+);
+```
+
+## `@component()`
+
+The decorator writes `static config` and calls `registerComponent()` in one step, and the two forms merge:
+
+```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()` reads the finished config. A key both sides declare differently is reported as `component.config-conflict`.
+
+See [`@component`](decorators/component.md).

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

@@ -0,0 +1,46 @@
+# createContext
+
+```ts
+createContext<T = unknown>(description?: string): ContextKey<T>
+```
+
+Creates a typed injection key.
+
+## Usage
+
+```ts
+import { createContext, type Signal } from '@studiometa/js-toolkit';
+
+interface SliderApi {
+  state: Signal<{ index: number }>;
+  goNext(): void;
+}
+
+export const SliderContext = createContext<SliderApi>('slider');
+```
+
+**Parameters**
+
+- `description` (`string`, optional) — for debugging only.
+
+**Return value**
+
+- `ContextKey<T>` — an opaque value carrying the phantom type `T`.
+
+## Why a value and not a string
+
+**The identity of the key is what resolves.** Two keys with the same description are two different keys, so nothing collides — and the type parameter is what makes `$inject(key)` give a typed value with no cast at the call site.
+
+Declare the key beside the interface it carries, and export both:
+
+```ts
+// slider-context.ts
+export interface SliderApi { … }
+export const SliderContext = createContext<SliderApi>('slider');
+```
+
+Provider and consumer then import one module and agree by construction.
+
+## The default is `unknown`
+
+`createContext('name')` with no type parameter gives `ContextKey<unknown>`, so `$inject()` resolves with `unknown` and the consumer has to narrow. Give it the type.

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

@@ -0,0 +1,67 @@
+# createGroup
+
+```ts
+createGroup<T extends GroupMember = GroupMember>(): Group<T>
+```
+
+A membership set whose members list is a reactive value.
+
+```ts
+interface Group<T extends GroupMember = GroupMember> {
+  readonly members: Signal<readonly T[]>;
+  join(member: T): () => void;
+}
+```
+
+A `GroupMember` is anything with a `readonly $el: Element` — which every `Base` instance is.
+
+## Usage
+
+The coordinator owns the membership and gives out the ways in:
+
+```ts
+import { Base, createContext, createGroup, type Signal } from '@studiometa/js-toolkit';
+
+interface GroupApi {
+  members: Signal<readonly Base[]>;
+  join(peer: Base): () => void;
+  open(peer: Base): void;
+}
+const DisclosureGroupContext = createContext<GroupApi>('disclosure-group');
+class DisclosureGroup extends Base {
+  static config = { name: 'DisclosureGroup' };
+
+  #peers = createGroup<Base>();
+
+  api = this.$provide(DisclosureGroupContext, {
+    members: this.#peers.members, // the members to read, in document order
+    join: (peer: Base) => this.#peers.join(peer), // returns the leave function
+    open: (peer: Base) => this.open(peer), // the invariant stays here
+  });
+
+  mounted() {
+    // The membership is a value: re-check the invariant on each change.
+    return this.#peers.members.subscribe((members) => this.enforce(members));
+  }
+
+  open(peer: Base) {}
+
+  enforce(members: readonly Base[]) {}
+}
+```
+
+A member joins the nearest group whenever that group appears — see [`subscribeContext()`](subscribeContext.md).
+
+## What it does, and what it does not
+
+- **`join()` returns its own `leave`**, so a member that moves to a nearer group leaves the old one first.
+- **The membership is a value.** A coordinator subscribes to it and re-checks its invariant on each change, rather than being called back on a mutation.
+- **Document order is the tie-breaker**, so the markup decides which peer keeps its state.
+- **Nothing sweeps disconnected members.** The teardown of the member removes it.
+- **It names no group and resolves no scope.** Scope comes from nearest-provider-wins, so a nested group takes its own members only.
+
+The helper holds a `Set` and a [`Signal`](signal.md), and nothing else. That is the whole implementation.
+
+## It replaces `withGroup`
+
+`withGroup` is not ported. A group is a provided value now, so its scope is the provider's subtree rather than a name in a global table — and a nested group is a nested provider, with nothing to configure.

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

@@ -0,0 +1,69 @@
+# Shared state
+
+provide/inject in core, with the shape of Vue and the mechanics of the WICG context protocol.
+
+## The functions
+
+| Function                                                       | Does                                          |
+| -------------------------------------------------------------- | --------------------------------------------- |
+| [`createContext(description?)`](createContext.md)          | a typed key                                   |
+| [`signal(initialValue)`](signal.md)                        | a reactive value                              |
+| [`provideContext(el, key, value)`](provideContext.md)      | provide on an element                         |
+| [`provideRootContext(key, create)`](provideRootContext.md) | provide page-wide, created at most once       |
+| [`injectContext(el, key)`](injectContext.md)               | a promise for the nearest value               |
+| [`injectContextSync(el, key)`](injectContextSync.md)       | the nearest value, or `undefined`             |
+| [`subscribeContext(el, key, cb)`](subscribeContext.md)     | every answer, as providers come and go        |
+| [`createGroup()`](createGroup.md)                          | a membership set with a reactive members list |
+
+From inside a component, `$provide()`, `$inject()` and `$injectSync()` are the same three, with the element filled in. The [`@provide`](../decorators/provide.md) and [`@inject`](../decorators/inject.md) decorators are field sugar over them.
+
+## The model
+
+- **The injection key is typed**, so strings cannot collide.
+- **The scope is the subtree**, and the nearest provider wins.
+- **The value is provided as it is.** Nothing is wrapped, so the type of the key is the contract from end to end. A reactive value is a provided `Signal`. A command surface is a provided object.
+
+```ts
+import { Base, createContext, signal, type Signal } from '@studiometa/js-toolkit';
+
+interface SliderApi {
+  state: Signal<{ index: number; total: number }>;
+  goNext(): void;
+}
+const SliderContext = createContext<SliderApi>('slider');
+class Slider extends Base {
+  static config = { name: 'Slider' };
+
+  api = this.$provide(SliderContext, {
+    state: signal({ index: 0, total: 0 }), // what changes
+    goNext: () => {}, // what a control can command
+  });
+}
+```
+
+## Two ways to ask
+
+| Form               | Resolves                          | When nothing provides                                 |
+| ------------------ | --------------------------------- | ----------------------------------------------------- |
+| `$inject(key)`     | a promise, awaited in `mounted()` | it never settles: a missing provider means "not yet". |
+| `$injectSync(key)` | the value, synchronously          | `undefined`: the caller falls back or does nothing.   |
+
+The pending request of the async form is **unmount-scoped**. A new mount runs `mounted()` again and asks again. The `@inject` field decorator asks once, at construction; a consumer that can wait through several cycles calls `$inject()` from `mounted()`.
+
+## The mechanics
+
+The consumer dispatches a bubbling, **module-private** `js-toolkit:context:request` event carrying a key, a callback and a subscription marker. It is deliberately not part of public `EVENTS`.
+
+The nearest **mounted** provider answers and stops propagation. `provideContext()` replays the requests that have no first answer yet, which is what makes mount order irrelevant. `injectContext()` and `$inject()` are one-shot.
+
+Duplicate bundles share the basic provider and pending-request state through the `context` shared-runtime slot at schema revision 2. The optional owner map, weak index and listener flag use the `context-subscription` slot at revision 1 — and `context.ts` and the `Base` graph import none of that optional state.
+
+## Scopes
+
+`$provide()` in a field initializer is **instance-scoped**: it is never released and dies with the element. A component whose declaration is withdrawn keeps providing until its element goes.
+
+A **root** provider cannot be disposed and it outlives the instance that asked first, because it is page state. `withGroup` is not ported.
+
+## Read next
+
+[Shared state](../../guide/going-further/sharing-state.md) walks the whole pattern, from a coordinator's provided API to a member joining the nearest group.

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

@@ -0,0 +1,58 @@
+# injectContext
+
+```ts
+injectContext<T>(el: Element, key: ContextKey<T>): { promise: Promise<T>; cancel: () => void }
+```
+
+Asks the nearest provider for a value, once.
+
+## Usage
+
+```ts
+import { createContext, injectContext } from '@studiometa/js-toolkit';
+
+const Key = createContext<number>('answer');
+const el = document.body;
+const { promise, cancel } = injectContext(el, Key);
+```
+
+**Return value**
+
+- `promise` — resolves with the nearest provided value.
+- `cancel` — withdraws the request.
+
+## It never settles when nothing provides
+
+**A missing provider means "not yet", not "no".** The request stays pending, and it resolves when a provider appears and replays it — which is what makes mount order irrelevant.
+
+If you need an answer now, or none, use [`injectContextSync()`](injectContextSync.md).
+
+## From a component
+
+`$inject()` is the same call with the element filled in, and it returns the promise directly:
+
+```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 pending request is unmount-scoped**
+
+`$unmount()` cancels it, and a new mount runs `mounted()` again and asks again. That is why `mounted()` is the right place: a component that outlives several cycles asks once per cycle, and never holds a request for a scope it has left.
+
+The [`@inject`](../decorators/inject.md) field decorator asks once, at construction, instead.
+
+## It is one-shot
+
+`injectContext()` and `$inject()` resolve with the **first** answer and stop. To follow providers as they come and go, use [`subscribeContext()`](subscribeContext.md).

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

@@ -0,0 +1,44 @@
+# injectContextSync
+
+```ts
+injectContextSync<T>(el: Element, key: ContextKey<T>): T | undefined
+```
+
+The nearest provided value, synchronously, or `undefined`.
+
+## Usage
+
+```ts
+import { createContext, injectContextSync } from '@studiometa/js-toolkit';
+
+const Key = createContext<number>('answer');
+const el = document.body;
+const value = injectContextSync(el, Key);
+
+if (value === undefined) {
+  // no provider — fall back, or do nothing
+}
+```
+
+## When to reach for it
+
+When the answer is **optional and the caller has a fallback**. `undefined` means "no provider right now", which is a different statement from `$inject()`'s "not yet".
+
+The canonical pair is a look-up-or-create:
+
+```ts
+import { createContext, injectContextSync, provideRootContext } from '@studiometa/js-toolkit';
+
+const DataChannels = createContext<Map<string, unknown>>('channels');
+const el = document.body;
+const channels =
+  injectContextSync(el, DataChannels) ?? provideRootContext(DataChannels, () => new Map());
+```
+
+## From a component
+
+`$injectSync(key)` is the same call with the element filled in.
+
+**It answers for right now**
+
+A provider that mounts later is not seen, because there is no request left pending. If mount order is not something you control, use [`injectContext()`](injectContext.md) or [`subscribeContext()`](subscribeContext.md).

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

@@ -0,0 +1,61 @@
+# provideContext
+
+```ts
+provideContext<T>(el: Element, key: ContextKey<T>, value: T): { value: T; dispose: () => void }
+```
+
+Provides a value to the subtree of `el`.
+
+## Usage
+
+```ts
+import { createContext, provideContext } from '@studiometa/js-toolkit';
+
+const Key = createContext<number>('answer');
+const el = document.body;
+const { value, dispose } = provideContext(el, Key, 42);
+```
+
+**Parameters**
+
+- `el` — the element that owns the scope.
+- `key` — a [`ContextKey`](createContext.md).
+- `value` — provided **as it is**. Nothing is wrapped.
+
+**Return value**
+
+- `value` — the value, so the call can be an expression.
+- `dispose` — stops answering for this key on this element.
+
+## From a component
+
+`$provide()` is the same call with the element filled in, and it returns the value directly so it reads as a field initializer:
+
+```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));
+}
+```
+
+**`$provide()` is instance-scoped**
+
+It is never released, and it dies with the instance or its element. A component whose declaration is withdrawn keeps providing until its element goes — which is why the call belongs in the constructor or a field initializer, not in `mounted()`.
+
+## Nearest wins
+
+The scope is the subtree, and a nearer provider shadows a further one by answering first and stopping propagation.
+
+## It replays pending requests
+
+A consumer that asked before any provider existed has a pending request with no first answer. `provideContext()` **replays those requests**, which is what makes mount order irrelevant: a child that mounts before its coordinator still gets its answer when the coordinator arrives.
+
+Only a **mounted** provider answers.
+
+## Page-wide
+
+For state that belongs to the page rather than to a subtree, use [`provideRootContext()`](provideRootContext.md).

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

@@ -0,0 +1,42 @@
+# provideRootContext
+
+```ts
+provideRootContext<T>(key: ContextKey<T>, create: () => T): T
+```
+
+Provides a value on `document.documentElement`, making the page-wide case the **outermost scope of the same mechanism**.
+
+## Usage
+
+```ts
+import { createContext, injectContextSync, provideRootContext } from '@studiometa/js-toolkit';
+
+const DataChannels = createContext<Map<string, unknown>>('channels');
+const el = document.body;
+// Scoped or page-wide, resolved the same way, nearest first.
+const channels =
+  injectContextSync(el, DataChannels) ?? provideRootContext(DataChannels, () => new Map());
+```
+
+**Parameters**
+
+- `key` — a [`ContextKey`](createContext.md).
+- `create` — a factory, run **at most once per key**.
+
+**Return value**
+
+- `T` — the value, created or already there.
+
+## Why it is the same mechanism
+
+Because the value sits on `document.documentElement`, a request from anywhere reaches it by bubbling, and **a nearer provider still wins** through `stopPropagation`. There is no separate global registry and no second lookup path.
+
+## Lazy, and once
+
+`create` runs at most once per key, and **nothing is created at import time**. A page that never asks for a key never builds its value.
+
+## It cannot be disposed
+
+A root provider outlives the instance that asked for it first, because it is page state. That is the point: the first component to need a page-wide channel should not own its lifetime.
+
+This is what replaces `withGroup`, which is not ported. For a scoped set of peers, use [`createGroup()`](createGroup.md) with an ordinary [`provideContext()`](provideContext.md).

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

@@ -0,0 +1,85 @@
+# signal
+
+```ts
+signal<T>(initialValue: T): Signal<T>
+```
+
+A reactive value. The accessor is `.value`.
+
+```ts
+interface Signal<T = unknown> {
+  value: T;
+  subscribe(callback: (value: T) => void, options?: { immediate?: boolean }): () => void;
+}
+```
+
+## Usage
+
+```ts
+import { signal } from '@studiometa/js-toolkit';
+
+const count = signal(0);
+
+const unsubscribe = count.subscribe((value) => console.log(value), { immediate: true });
+
+count.value = 1;
+count.value += 1;
+
+unsubscribe();
+```
+
+**Parameters**
+
+- `initialValue` (`T`).
+
+**Return value**
+
+- `Signal<T>`. `subscribe()` returns the unsubscribe function.
+
+## A write settles synchronously, and the newest value wins
+
+The delivery loop re-reads the value after each callback. If the value moved, the loop **abandons the round and starts again on the new value**, so a subscriber that was not reached yet skips the old value entirely.
+
+Delivery stays in the same task. There is no batching and no microtask.
+
+**A subscriber that writes on every delivery live-locks the loop**
+
+Each write restarts the round, so the loop never finishes. Guard the write, or move it out of the subscriber.
+
+## It is a factory over a closure
+
+There is no class and no proxy. `signal()` closes over the value and a subscriber set, which is why it is the right thing to _provide_: the value crossing a context boundary is the signal itself, and the type of the key says so.
+
+```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));
+
+  increment() {
+    this.count.value += 1;
+  }
+}
+
+class CounterOutput extends Base {
+  static config = { name: 'CounterOutput' };
+
+  async mounted() {
+    const count = await this.$inject(CountContext);
+    return count.subscribe((value) => {
+      this.$el.textContent = String(value);
+    });
+  }
+}
+```
+
+## Failures
+
+A subscriber that throws is isolated and reported as `callback.signal-failed`, so one subscriber cannot stop the others.
+
+## `toggle()` works on it
+
+[`toggle(subscribe)`](../services/toggle.md) takes anything that returns its own unsubscribe function, a `Signal` included.