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

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

@@ -0,0 +1,49 @@
+# Registry
+
+The registry is the only code that constructs an instance. It holds one entry per name and one controller per element/component pair.
+
+## Registering
+
+- [`registerComponent(Ctor)`](registerComponent.md) — one eager entry, and its declared family
+- [`registerComponents(...ctors)`](registerComponents.md) — several at once
+- [`registerManifest(entries)`](registerManifest.md) — lazy entries in the same map
+
+## Building a manifest
+
+- [`defineManifest(options)`](defineManifest.md) — derive tokens from module paths
+- [`fromMetaGlob(glob)`](fromMetaGlob.md) — a Vite `import.meta.glob` result
+- [`fromWebpackContext(context)`](fromWebpackContext.md) — a webpack context
+
+## Looking instances up
+
+Four functions answer from the DOM. They keep **no registry of instances**.
+
+| Function                                                  | Population                                 |
+| --------------------------------------------------------- | ------------------------------------------ |
+| [`getInstances()`](getInstances.md)                   | every instance that exists, mounted or not |
+| [`getMountedInstances()`](getMountedInstances.md)     | the live ones — safe to call a method on   |
+| [`getUnmountedInstances()`](getUnmountedInstances.md) | built, then stood down                     |
+| [`getInstance(el, name)`](getInstance.md)             | the one on this element                    |
+
+```js
+getMountedInstances('Dialog').forEach((dialog) => dialog.close());
+getInstances('Dialog', section);
+getUnmountedInstances('Dialog');
+getInstance(el, 'Dialog');
+getInstances(el);
+```
+
+The three plural forms take the same two overloads: a **name** with an optional `ParentNode` root, or an **element**.
+
+- **A matching element with no instance is skipped, and that is the whole narrowing.** `selectorFor(name)` over-matches on purpose — it lists the responsive spellings of `data-component` too — and the instance-map read removes an inactive declaration, because a breakpoint-withdrawn component is destroyed _and_ deleted from the map.
+- `root` is a `ParentNode` and the call is `querySelectorAll`, so an element root searches its **descendants** and never matches itself.
+- **The element overload is the only form that reaches a detached element**, since `querySelectorAll()` does not see one. Pass the detached root as `root` when a name lookup has to reach inside it.
+- **There is no `getMountedInstance`.** The singular returns one object, so a caller reads `.$isMounted` on it.
+
+## In tests
+
+`resetRegistry()` is re-exported from [`/test`](../test/index.md) and drops every registration. It is not part of a page's vocabulary.
+
+## Read next
+
+[The registry](../../guide/concepts/the-registry.md) explains the entry, the controller and the one scheduling algorithm that covers eager, lazy and conditional mounting.

package/skills/studiometa-js-toolkit/references/api/registry/registerComponent.md

@@ -0,0 +1,93 @@
+# registerComponent
+
+```ts
+registerComponent(ComponentClass: BaseConstructor): void
+```
+
+Registers a component and its merged family, then scans the document for matching elements.
+
+## Usage
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class Slider extends Base {
+  static config = { name: 'Slider' };
+}
+
+registerComponent(Slider);
+```
+
+**Parameters**
+
+- `ComponentClass` — a class extending `Base`, with a `config.name`.
+
+**Return value**
+
+- `void`. It is a registration, not an instantiation: the elements that match get their instances through the ordinary pipeline, and there is no list of instances to hand back. Use [`getInstances()`](getInstances.md) if you need them.
+
+## It registers the family too
+
+`config.components` is walked in one loop, so one call covers a whole tree:
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base {
+  static config = { name: 'AccordionItem' };
+}
+
+class Accordion extends Base {
+  static config = {
+    name: 'Accordion',
+    components: { AccordionItem },
+  };
+}
+
+// Registers both.
+registerComponent(Accordion);
+```
+
+A thunk in `config.components` is **deferred** rather than resolved, and becomes a lazy entry of the same registry under its key. See [Autoloading](../../guide/going-further/autoloading.md).
+
+## The name comes from the merged config
+
+Like the instance's `$id` and the instance-map key it publishes itself under. A subclass that extends a component with extra config and forgets to rename therefore **collides** with the name it inherited, rather than registering under `undefined`.
+
+## One name, one entry
+
+As with `customElements.define()`. A second registration under a name already taken gives a `registry.conflict` warning and is ignored.
+
+The exception is a lazy child declared by several parents: that is the normal case, and it is **first wins, quietly**. A token two components genuinely claim is caught by the class-name check when the import lands.
+
+## Registering a class you cannot edit
+
+Do it in expression position:
+
+```js
+registerComponent(
+  class extends Vendor {
+    static config = { name: 'CompactVendor', options: { compact: Boolean } };
+  },
+);
+```
+
+## What it does not do
+
+- **It does not construct anything itself.** The registry does, when the DOM and the mount strategy agree.
+- **It does not take a name or a selector.** `config.name` is the only name, and arbitrary selectors are removed.
+- **It does not take a promise or a thunk.** Use [`registerManifest()`](registerManifest.md) for a lazy entry.
+- **It has no inverse on a page.** `resetRegistry()` exists for tests only — see [`/test`](../test/index.md).
+
+## `@component`
+
+The decorator writes `static config` and calls this function in one step:
+
+```ts
+import { Base, component } from '@studiometa/js-toolkit';
+
+@component({ name: 'Slider', refs: ['next'] })
+class Slider extends Base {}
+```
+
+See [`@component`](../decorators/component.md).

package/skills/studiometa-js-toolkit/references/api/registry/registerComponents.md

@@ -0,0 +1,37 @@
+# registerComponents
+
+```ts
+registerComponents(...classes: BaseConstructor[]): void
+```
+
+[`registerComponent()`](registerComponent.md) for several classes, in order.
+
+## Usage
+
+```js
+import { Base, registerComponents } from '@studiometa/js-toolkit';
+
+class Accordion extends Base {
+  static config = { name: 'Accordion' };
+}
+class Slider extends Base {
+  static config = { name: 'Slider' };
+}
+class TodoList extends Base {
+  static config = { name: 'TodoList' };
+}
+
+registerComponents(Accordion, Slider, TodoList);
+```
+
+This is the whole bootstrap of a page. There is no `createApp()` and no root component: each of these registers its own declared family, and every registered name auto-mounts through the single MutationObserver.
+
+**Parameters**
+
+- `...classes` — classes extending `Base`.
+
+**Return value**
+
+- `void`.
+
+Order matters only for collisions: the first registration of a name wins and the second gives a `registry.conflict` warning.

package/skills/studiometa-js-toolkit/references/api/registry/registerManifest.md

@@ -0,0 +1,72 @@
+# registerManifest
+
+```ts
+registerManifest(entries: ComponentManifest): void
+```
+
+Registers lazy component entries in the same registry the eager classes use.
+
+## Usage
+
+```js
+import { registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest({
+  Accordion: () => import('./components/Accordion.js'),
+  Slider: () => import('./components/Slider.js'),
+  Map: { load: () => import('./components/Map.js'), mountStrategy: 'visible' },
+});
+```
+
+## Types
+
+```ts
+type ComponentManifest = Record<string, ComponentImporter | ComponentManifestEntry>;
+
+type ComponentImporter = () => Promise<unknown>;
+
+interface ComponentManifestEntry {
+  load: ComponentImporter;
+  mountStrategy?: MountStrategy;
+}
+```
+
+An entry is either the importer itself, or an object with `load` and an optional `mountStrategy`.
+
+## The contract
+
+- **One name, one entry**, across eager classes and manifests alike. A token an eager class or an earlier manifest owns gives a `manifest.duplicate-token` warning and is ignored.
+- **No dependency and no bundler knowledge.** The value is a function that returns a promise. `import.meta.glob`, `import.meta.webpackContext` and a generated manifest all produce that shape, and core names none of them.
+- **The class is resolved out of the imported module for you**, so a hand-written entry is `Slider: () => import('./Slider.js')` with nothing to unwrap.
+- **The registry stays the only constructor.** The import ends in [`registerComponent()`](registerComponent.md); autoload never touches `new`, the instance map or a mount hook.
+- **One import per name, one failure report per name.** A failure emits one `component.load-failed` diagnostic and is never retried.
+- **A class whose `config.name` differs from its token** gives a `registry.lazy-name-mismatch` warning.
+- **An unloaded declaration is invisible** to `$query()`, `$closest()`, `$watchChildren()` and `getInstances()`, because nothing is constructed at discovery.
+
+## The mount strategy chain
+
+```
+data-mount  >  manifest entry mountStrategy  >  'eager'
+```
+
+The entry's strategy stands in the middle slot for the `config.mountStrategy` of a class that cannot be read yet. Once the class registers, the chain reads `config.mountStrategy` and the entry is deleted from the map.
+
+There is **no `data-load`**: deferring the import and deferring the mount are one decision. See [Autoloading](../../guide/going-further/autoloading.md).
+
+## `whenDOMSettled()` covers an eager lazy component
+
+The import promise joins the lifecycle-work set for the **eager** trigger only, so [`swap()`](../dom/swap.md) waits for download, registration and mount — and still never waits on a viewport, an idle callback, an interaction or a media query.
+
+## From a glob
+
+```js
+import { defineManifest, fromMetaGlob, registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  }),
+);
+```
+
+See [`defineManifest()`](defineManifest.md).

package/skills/studiometa-js-toolkit/references/api/scheduler/defaultScheduler.md

@@ -0,0 +1,104 @@
+# defaultScheduler
+
+The one scheduler instance. Duplicate copies of the package reuse the canonical one through the shared runtime.
+
+```ts
+class Scheduler {
+  get phase(): SchedulerPhase;
+  tick(callback: TickCallback): () => void;
+  read<T>(fn: () => T): ScheduledTask<T>;
+  write<T>(fn: () => T): ScheduledTask<T>;
+  whenIdle(): Promise<void>;
+}
+```
+
+## `read()` and `write()`
+
+```ts
+import { defaultScheduler } from '@studiometa/js-toolkit';
+
+const el = document.body;
+async function resize() {
+  const box = await defaultScheduler.read(() => el.getBoundingClientRect()).promise;
+  await defaultScheduler.write(() => {
+    el.style.height = `${box?.height}px`;
+  }).promise;
+}
+```
+
+Both return a handle:
+
+```ts
+interface ScheduledTask<T = unknown> {
+  promise: Promise<T | undefined>;
+  cancel(): void;
+}
+```
+
+- The promise resolves with the **return value of the task**, so a read hands its measurement back.
+- `cancel()` is idempotent, and a cancelled task's promise never resolves with a value.
+- **Queued execution only.** There is no synchronous escape.
+
+### The thrash rule
+
+| Scheduled from | Runs in        |
+| -------------- | -------------- |
+| a `read`       | the same frame |
+| a `write`      | the next frame |
+
+Each queue array is **swapped for an empty one when its phase starts**, so a task scheduled into the running phase lands in the next frame's batch. The `write` batch is taken after the reads run.
+
+## `tick()`
+
+```js
+import { defaultScheduler } from '@studiometa/js-toolkit';
+
+const unsubscribe = defaultScheduler.tick(({ time, delta }) => {
+  console.log(time, delta);
+});
+```
+
+```ts
+interface TickProps {
+  readonly time: DOMHighResTimeStamp;
+  readonly delta: number;
+}
+```
+
+- Tick callbacks run at the **start** of the flush, before `read`, so what they schedule belongs to the same frame.
+- **The subscription is the only handle, and it keeps the loop alive.** The scheduler requests the next frame when a queue inside the frame is not empty, or when a tick subscriber stays. **There is no permanent rAF loop.**
+- Tick subscribers are **not queued work**, so `whenIdle()` ignores them.
+- A tick callback that throws is reported as `callback.scheduler-tick-failed` and skipped, never unsubscribed.
+- **`delta` is clamped to `[1, 40]` ms**, and the first tick after the loop wakes reports `1000/60`. `time` stays the raw rAF timestamp.
+
+For a subscription that comes and goes within a cycle, use [`toggle()`](../services/toggle.md) rather than subscribing and unsubscribing by hand.
+
+## `whenIdle()`
+
+```js
+await defaultScheduler.whenIdle();
+```
+
+Resolves at the end of a flush **and** at the end of a background drain, because it counts background tasks too.
+
+It is one half of the timing recipe the [`/test`](../test/index.md) helpers encode — the other half is the mutation observer's delivery latency, which is why `whenIdle()` alone is not enough to know a component has mounted.
+
+## `phase`
+
+```ts
+type SchedulerPhase = 'idle' | 'tick' | 'read' | 'write' | 'background';
+```
+
+Reading it is a diagnostic, not a control. Code that branches on the phase is usually code that should schedule instead.
+
+## The background lane
+
+It posts its own turns through `scheduler.postTask({ priority: 'background' })`, and falls back to a `MessageChannel` message. Each turn runs a **5 ms slice** measured from the start of the drain, then gives the thread back and posts the next turn.
+
+**Background work alone never requests an animation frame.**
+
+A failure to post is reported as `scheduler.background-post-failed`.
+
+## Error isolation
+
+One try/catch per task. A task that throws is reported as `callback.scheduled-task-failed`, **rejects its own promise with the same value**, and is dropped. The flush continues and the scheduler never deadlocks.

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

@@ -0,0 +1,27 @@
+# Scheduler
+
+One frame-aligned scheduler is the clock of the framework. It replaces `domScheduler`, the `RafService` loop, `SmartQueue` and the view-transition scheduler of `@studiometa/ui`.
+
+```
+frame start (rAF)
+  1. tick        — fan out to the subscribers of the clock
+  2. read        — measure: layout reads only
+  3. write       — mutate: DOM writes only
+style / layout / paint
+
+between frames, on its own turns
+  background     — time-sliced lane: mount and update lifecycle work,
+                   mutation-record processing, manifest loading
+```
+
+## The exports
+
+- [`defaultScheduler`](defaultScheduler.md) — the instance, with `tick`, `read`, `write`, `whenIdle` and `phase`
+- [`nextFrame()`](nextFrame.md) — await one frame
+- [`viewTransition(update)`](viewTransition.md) — a batched native view transition
+
+From a component, `$read()` and `$write()` tie tasks to the instance so unmount cancels them. See [Instance methods](../instance-methods.md#read-and-write).
+
+## Read next
+
+[The scheduler](../../guide/going-further/scheduling-work.md) explains the lanes, the thrash rule and why `afterWrite` is gone.

package/skills/studiometa-js-toolkit/references/api/scheduler/nextFrame.md

@@ -0,0 +1,31 @@
+# nextFrame
+
+```ts
+nextFrame(): Promise<void>
+```
+
+Resolves on the next animation frame.
+
+## Usage
+
+```ts
+import { nextFrame } from '@studiometa/js-toolkit';
+
+async function afterOneFrame(el: HTMLElement) {
+  el.classList.add('is-entering');
+  await nextFrame();
+  el.classList.add('is-active');
+}
+```
+
+## What it is for
+
+Letting the browser see a style before the next one is applied — the two-step every CSS transition needs. `transition()`, `enterTransition()` and `leaveTransition()` are built on exactly this.
+
+## What it is not
+
+It does **not** mean "after paint". rAF callbacks run **before** style, layout and paint, so no phase inside a frame can read post-layout geometry. `afterWrite` is removed for that reason.
+
+To measure after a layout has happened, measure in the `read` phase of the next frame — [`defaultScheduler.read()`](defaultScheduler.md) or `$read()` — or use a `ResizeObserver`.
+
+For a test that needs several frames, [`frames(count?)`](../test/index.md) is the same idea with a count.

package/skills/studiometa-js-toolkit/references/api/scheduler/viewTransition.md

@@ -0,0 +1,53 @@
+# viewTransition
+
+```ts
+viewTransition(update: () => void | Promise<void>): Promise<void>
+```
+
+Runs a DOM update inside a native view transition, with a progressive-enhancement contract: where the platform has no `startViewTransition`, the update simply runs.
+
+## Usage
+
+```ts
+import { viewTransition } from '@studiometa/js-toolkit';
+
+async function replace(el: Element, html: string) {
+  await viewTransition(() => {
+    el.innerHTML = html;
+  });
+}
+```
+
+## Batching
+
+**Updates queued in the same flush batch into one `startViewTransition()` call**, so a backdrop and a panel animate as one transition rather than two fighting each other.
+
+Each later batch is appended to **one promise tail**, so several flushes during one running transition stay serialized instead of interleaving.
+
+The scheduler flushes the pending `write` tasks **before the snapshot**, so a pending write is part of the "before" state rather than landing mid-transition. Writes scheduled _inside_ the update callback run within the transition.
+
+## It is standalone
+
+`Base` has no view-transition method and no import of one. The helper is a free function, and the whole view-transition graph stays out of the `Base` module graph — a page that never calls it never downloads it.
+
+## Composing it
+
+It is a `DomUpdateRunner`, so an ancestor can claim a [negotiated update](../dom/domUpdate.md) with it:
+
+```js
+this.$on(EVENTS.dom.update, ({ detail }) => detail.wrap(viewTransition));
+```
+
+and it is a `SwapWrap`, so a [`swap()`](../dom/swap.md) can play as one transition:
+
+```js
+await swap(el, html, { wrap: (mutate) => viewTransition(mutate) });
+```
+
+Neither is the default. **The ancestor chooses the lane, because it knows whether the region animates.**
+
+## `exit`, `layout` and `layoutId`
+
+They are not an animation engine's job. Native view transitions solve them, which is why this is in core while `tween` and `animate` are not shipped at all.
+
+`@studiometa/ui` keeps a declarative `ViewTransition` component, rebuilt on this helper.

package/skills/studiometa-js-toolkit/references/api/services/createService.md

@@ -0,0 +1,95 @@
+# createService
+
+```ts
+createService<T, R = void>(definition: ServiceDefinition<T>): Service<T, R>
+```
+
+The primitive every built-in service is built on.
+
+## The definition
+
+```ts
+interface ServiceDefinition<T> {
+  props: () => T;
+  hasProps?: () => boolean;
+  start: (emit: (props: T) => void) => Unsubscribe;
+}
+```
+
+| Field      | Does                                                                                |
+| ---------- | ----------------------------------------------------------------------------------- |
+| `props`    | reads the current props                                                             |
+| `hasProps` | says whether there **is** a current value, which is what `{ immediate: true }` asks |
+| `start`    | starts the source on the first subscriber, and returns its teardown                 |
+
+## Usage
+
+```ts
+import { createService } from '@studiometa/js-toolkit';
+
+interface OnlineProps {
+  readonly isOnline: boolean;
+}
+
+const useOnline = createService<OnlineProps>({
+  props: () => ({ isOnline: navigator.onLine }),
+  start(emit) {
+    const publish = () => emit({ isOnline: navigator.onLine });
+    window.addEventListener('online', publish);
+    window.addEventListener('offline', publish);
+    return () => {
+      window.removeEventListener('online', publish);
+      window.removeEventListener('offline', publish);
+    };
+  },
+});
+```
+
+## What you get for free
+
+- **Lazy and reference-counted.** `start` runs on the first subscriber and its teardown on the last. With no subscriber there is no listener, no observer and no frame.
+- **Symmetric subscriptions.** `subscribe(callback)` returns the unsubscribe function. A subscription is a **record**, not a key in a set, so two holders of one function are two subscribers.
+- **A safe fan-out.** The fan-out walks a snapshot and each record carries an `isActive` flag, so a subscriber that unsubscribes during a delivery is not called.
+- **Error isolation.** A subscriber that throws is skipped and reported as `callback.service-failed`.
+
+Publishing is **re-entrant**, so any code that changes state after a publication must check first that the service is still alive.
+
+## `hasProps`
+
+Omit it and the service is assumed to have a current value. Declare it when it does not:
+
+```ts
+import { createService } from '@studiometa/js-toolkit';
+
+interface BatchProps {
+  readonly records: readonly unknown[];
+}
+let current: readonly unknown[] = [];
+createService<BatchProps>({
+  props: () => ({ records: current }),
+  hasProps: () => current.length > 0, // nothing to deliver between batches
+  start: (emit) => () => {},
+});
+```
+
+This is what makes `{ immediate: true }` honest: the frame tick has no current value between two frames, the pointer has none before it is seen, a drag has none outside a gesture, and a mutation service has none between batches.
+
+## What a callback may return
+
+`R` is a type parameter, so a service can require its callbacks to return something. `useRaf()` uses it to enforce `RafRender`:
+
+```ts
+type RafService = Service<RafProps, void | RafRender>;
+```
+
+## Scoping it to a target
+
+Wrap it in [`perTarget()`](perTarget.md) to get one instance per target and per options, keyed in a `WeakMap` — the caching every built-in service has.
+
+## Making a mixin over it
+
+See [`createServiceMixin()`](createServiceMixin.md).
+
+**A consumer's service is owned by the consumer**
+
+The shared runtime coordinates the **built-in** service caches across duplicate copies of the package. A `createService()` or `perTarget()` call of a consumer stays owned by that consumer.

package/skills/studiometa-js-toolkit/references/api/services/createServiceMixin.md

@@ -0,0 +1,81 @@
+# createServiceMixin
+
+```ts
+createServiceMixin<Instance, Target, Options extends object = object>(
+  definition: ServiceMixinDefinition<Target, Options>,
+): ServiceMixin<Instance, Target, Options>
+```
+
+Builds the mixin-and-decorator pair over a service. Every built-in `with*` is one of these.
+
+## The definition
+
+```ts
+interface ServiceMixinDefinition<Target, Options> {
+  hook: string;
+  target: (instance: Base) => Target;
+  defaultImmediate?: boolean;
+  use: (target: Target, options: Options) => Service<unknown, unknown>;
+  handleResult?: (instance: Base, result: unknown) => void;
+}
+```
+
+| Field              | Does                                                                      |
+| ------------------ | ------------------------------------------------------------------------- |
+| `hook`             | the one method name the service owns                                      |
+| `target`           | the default target resolver                                               |
+| `defaultImmediate` | whether the first delivery is asked for unless the caller says otherwise  |
+| `use`              | calls the service factory                                                 |
+| `handleResult`     | does something with what the hook returned — `withRaf` schedules a render |
+
+## Usage
+
+```ts
+import { createService, createServiceMixin, perTarget } from '@studiometa/js-toolkit';
+
+interface FocusProps {
+  readonly hasFocus: boolean;
+}
+const useFocus = perTarget((target: Element) =>
+  createService<FocusProps>({
+    props: () => ({ hasFocus: target.contains(document.activeElement) }),
+    start: () => () => {},
+  }),
+);
+interface FocusHook {
+  focused?(props: FocusProps): void;
+}
+
+export const withFocus = createServiceMixin<FocusHook, Element>({
+  hook: 'focused',
+  target: (instance) => instance.$el,
+  use: (target) => useFocus(target),
+});
+```
+
+```js
+class Field extends withFocus(Base) {
+  focused({ hasFocus }) {}
+}
+```
+
+## `use` receives the service's options only
+
+`target`, `manual` and `immediate` are removed before `use` is called and they are absent from its `Options` type — which is why `use: (target, options) => useDrag(target, options)` is correct and needs no filtering.
+
+## Override `$mount()`, not `mounted()`
+
+`createServiceMixin()` overrides `$mount()` and `$unmount()`, which is what lets a component write its own `mounted()` without `super.mounted()` and still subscribe.
+
+**The rule is about what a mixin overrides, not who wrote it.** A userland mixin that puts its work in `mounted()` needs its subclasses to call `super.mounted()`. The way not to need that is to override `$mount()` — or to use this function, which already does.
+
+## What it gives the class
+
+- the hook, bound for each mount cycle;
+- `$services.<hook>` as a [`Toggle`](toggle.md), typed through `ServiceHandles<'<hook>'>`;
+- the two call forms, mixin and class decorator;
+- the `service.missing-target` check on a caller-supplied resolver.
+
+## One hook per class
+
+A mixin names one hook and binds one subscription per cycle. That is its limit, and a component with a dynamic set of subscriptions calls `subscribe()` itself. See [Mixins](mixins.md).