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

package/skills/studiometa-js-toolkit/references/guide/introduction/using-services.md

@@ -0,0 +1,218 @@
+# Services
+
+A service is a shared source of props that components subscribe to. It is **lazy and reference-counted**: the source starts on the first subscriber and stops on the last, so with no subscriber there is no listener, no observer and no frame.
+
+## The sources
+
+| Service                                                                       | Hook             | Props                                                                        |
+| ----------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------- |
+| [`useRaf()`](../../api/services/useRaf.md)                                       | `ticked`         | `time`, `delta`                                                              |
+| [`useScroll(target?)`](../../api/services/useScroll.md)                          | `scrolled`       | `x`, `y`, `deltaX/Y`, `maxX/Y`, `progressX/Y`, `directionX/Y`, `isScrolling` |
+| [`useResize(target?)`](../../api/services/useResize.md)                          | `resized`        | `width`, `height`, `ratio`, `orientation`                                    |
+| [`usePointer(target?)`](../../api/services/usePointer.md)                        | `moved`          | `event`, `isDown`, `x`, `y`, `deltaX/Y`, `maxX/Y`, `progressX/Y`             |
+| [`useDrag(target, options?)`](../../api/services/useDrag.md)                     | `dragged`        | `mode`, `x`, `y`, `deltaX/Y`, `originX/Y`, `distanceX/Y`, `finalX/Y`         |
+| [`useKey(target?)`](../../api/services/useKey.md)                                | `keyed`          | `event`, `triggered`, `isDown`, `isUp`, plus one boolean per named key       |
+| [`useInView(target, init?)`](../../api/services/useInView.md)                    | `intersected`    | `isInView`, `entry`                                                          |
+| [`useMutation(target, init?)`](../../api/services/useMutation.md)                | `mutated`        | `records`                                                                    |
+| [`useScrollProgress(target, options?)`](../../api/services/useScrollProgress.md) | `scrolledInView` | `startX/Y`, `endX/Y`, `currentX/Y`, `progressX/Y`                            |
+| [`useBreakpoint()`](../../api/services/useBreakpoint.md)                         | —                | `name`                                                                       |
+| [`useMediaQuery(query)`](../../api/services/useMediaQuery.md)                    | —                | `matches`                                                                    |
+
+`useWindowScroll()` and `useWindowSize()` name the default cases. `usePrefersReducedMotion()` is the named media query.
+
+## Subscribing by hand
+
+Every service has the same two-method surface, so subscribing is one line and the release is what `mounted()` returns:
+
+```js
+import { Base, useScroll } from '@studiometa/js-toolkit';
+
+class Header extends Base {
+  static config = { name: 'Header' };
+
+  mounted() {
+    return useScroll().subscribe(({ directionY, y }) => {
+      this.$el.classList.toggle('is-hidden', directionY > 0 && y > 100);
+    });
+  }
+}
+```
+
+`subscribe(callback, options?)` returns the unsubscribe function. `props()` reads the current props with no subscription.
+
+### Asking for the first delivery
+
+```js
+useScroll().subscribe(callback, { immediate: true });
+```
+
+The sources that have a current value honour it; the ones that do not, do nothing. The frame tick has no current value between two frames, the pointer has none before it is seen, and a drag has none outside a gesture. Only the new subscriber is called, and the first props of a run carry no movement.
+
+## Mixins — the declarative form
+
+A mixin binds one subscription per mount cycle, under the one method name the service owns:
+
+```js
+import { Base, withScroll } from '@studiometa/js-toolkit';
+
+class Header extends withScroll(Base) {
+  static config = { name: 'Header' };
+
+  scrolled({ directionY }) {
+    this.$el.classList.toggle('is-hidden', directionY > 0);
+  }
+}
+```
+
+The mixins are `withRaf`, `withScroll`, `withResize`, `withScrollProgress`, `withPointer`, `withDrag`, `withInView`, `withMutation` and `withKey`.
+
+**A mixin never occupies a lifecycle hook**
+
+`mounted()` and `unmounted()` belong to the component author. The subscription rides on the framework's own `$mount()`/`$unmount()` pair, so a class that mixes a service in and writes its own `mounted()` **without** `super.mounted()` still subscribes.
+
+The subscription therefore starts once the whole of `mounted()` has run — including an `immediate` first delivery, which reaches a component that is fully set up — and is released before `unmounted()`.
+
+### Scoping a mixin to a ref
+
+```js
+import { Base, withResize } from '@studiometa/js-toolkit';
+
+class Panel extends withResize(Base, { target: (instance) => instance.$refs.inner }) {
+  static config = { name: 'Panel' };
+
+  resized({ width }) {
+    console.log(width);
+  }
+}
+```
+
+A resolver that comes back with `undefined` or `null` reports `service.missing-target` and starts **no** subscription — because a renamed ref arrives here as nothing, and a service with a default target would otherwise observe the wrong thing and look like it worked.
+
+### Suspending a hook
+
+`{ manual: true }` declares the hook without running it. `$services.<hook>` is the switch:
+
+```js
+import { Base, withRaf } from '@studiometa/js-toolkit';
+
+class SliderItem extends withRaf(Base, { manual: true }) {
+  static config = { name: 'SliderItem' };
+
+  ticked({ delta }) {
+    // declared, not running
+  }
+
+  start() {
+    this.$services.ticked.start();
+  }
+
+  stop() {
+    this.$services.ticked.stop();
+  }
+}
+```
+
+### One hook per class, and that is the limit
+
+A mixin binds **one** subscription, under one name, per mount cycle. A component whose subscriptions are one per markup declaration — an attribute-driven set, with its own modifiers and its own threshold, known only when the element is read — has no method to name and no fixed count. It calls `subscribe()` itself and returns the release from `mounted()`. That is the intended path, not a workaround.
+
+`on<Event>` has the same shape: a handler name belongs to the class, while a set of events can be data.
+
+## Two combinators
+
+### `toggle()` — a subscription you can switch
+
+```js
+import { Base, toggle, useRaf } from '@studiometa/js-toolkit';
+
+class SliderItem extends Base {
+  static config = { name: 'SliderItem' };
+
+  #frame = toggle(() => useRaf().subscribe(({ delta }) => this.follow(delta)));
+
+  mounted() {
+    // `stop` is bound, so it is a cleanup as it is.
+    return this.#frame.stop;
+  }
+
+  follow(delta) {}
+
+  onSelected() {
+    this.#frame.start();
+  }
+
+  onSettled() {
+    this.#frame.stop();
+  }
+}
+```
+
+`start()` is idempotent and `stop()` is safe to repeat. It works on a `Signal`, on a bare listener, and outside a component.
+
+### `until()` — a one-shot wait
+
+```js
+import { until, useScroll } from '@studiometa/js-toolkit';
+
+async function afterScroll() {
+  const props = await until(useScroll(), ({ isScrolling }) => !isScrolling);
+  console.log(props.y);
+}
+```
+
+It resolves on the first update that matches, releases the subscription **before** it resolves, and resolves with a copy of the props. It resolves at once when the current props already match.
+
+## The props contract
+
+- **Props are flat, one field per axis, and nothing derivable is a field.** `lastX` is `x - deltaX`; `changedX` is `deltaX !== 0`. The grouped objects of v3 (`last`, `delta`, `max`, `progress`, `direction`, `changed`) are gone.
+- **`directionX` and `directionY` are `-1 | 0 | 1`** — one signed value that multiplies.
+- **Every field is `readonly`, and the props object belongs to its service.** It is valid for the duration of the call that received it. Use `{ ...props }` to keep one.
+
+## One instance per target and per options
+
+Services are keyed in a `WeakMap` by target **and** by the meaning of their options, so two callers asking for the same thing share one source:
+
+```js
+import { useInView } from '@studiometa/js-toolkit';
+
+const el = document.body;
+
+// The same service — the key is read by meaning, not by spelling.
+useInView(el, { threshold: 0.5, rootMargin: '0px' });
+useInView(el, { rootMargin: '0px', threshold: 0.5 });
+```
+
+Nothing groups observers across targets.
+
+## No service owns a loop
+
+The raf service and an active drag inertia subscribe to `scheduler.tick()`. The scroll service coalesces its events into one `read` per frame. The resize service is a `ResizeObserver`. See [The scheduler](../going-further/scheduling-work.md).
+
+## Writing your own
+
+`createService()` is the whole primitive. Give it a `props` reader and a `start` function that returns its teardown:
+
+```ts
+import { createService, perTarget } from '@studiometa/js-toolkit';
+
+interface FocusProps {
+  readonly hasFocus: boolean;
+}
+
+const useFocus = perTarget((target: Element) =>
+  createService<FocusProps>({
+    props: () => ({ hasFocus: target.contains(document.activeElement) }),
+    start(emit) {
+      const onChange = () => emit({ hasFocus: target.contains(document.activeElement) });
+      document.addEventListener('focusin', onChange);
+      document.addEventListener('focusout', onChange);
+      return () => {
+        document.removeEventListener('focusin', onChange);
+        document.removeEventListener('focusout', onChange);
+      };
+    },
+  }),
+);
+```
+
+`perTarget()` gives it the one-instance-per-target caching every built-in service has. See [`createService()`](../../api/services/createService.md) and [`createServiceMixin()`](../../api/services/createServiceMixin.md).

package/skills/studiometa-js-toolkit/references/guide/introduction/working-with-events.md

@@ -0,0 +1,251 @@
+# Events
+
+Everything a component announces is a real DOM event, and everything it listens to is delegated from its own root element.
+
+## The conventions
+
+| Method name         | Listens to                                    | Payload                      |
+| ------------------- | --------------------------------------------- | ---------------------------- |
+| `on<Event>`         | the component's own element                   | the raw event                |
+| `on<Ref><Event>`    | a declared ref, delegated                     | `{ event, target, index }`   |
+| `on<Child><Event>`  | a component in `config.components`, delegated | `{ event, target, payload }` |
+| `onWindow<Event>`   | `window`                                      | `{ event, target }`          |
+| `onDocument<Event>` | `document`                                    | `{ event, target }`          |
+
+Every one of them is bound for the **mount cycle** and removed by `$unmount()`.
+
+## The component's own element
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Toggle extends Base {
+  static config = { name: 'Toggle' };
+
+  onClick(event) {
+    event.preventDefault();
+    this.$el.classList.toggle('is-active');
+  }
+}
+```
+
+## Refs
+
+See [Refs](managing-refs.md#event-handlers). The payload's `target` is the ref element the handler matched, not `event.target`, and `index` is its position in a list ref.
+
+## `$emit()` — a native event
+
+`$emit(name, payload?)` dispatches a bubbling, cancelable `CustomEvent`. `detail` **is** the payload:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Dialog extends Base {
+  static config = { name: 'Dialog' };
+
+  open() {
+    // No payload: `detail` is the platform value `null`.
+    this.$emit('open');
+  }
+
+  goto(index) {
+    // One optional object, and `detail` is that object.
+    this.$emit('goto', { index });
+  }
+}
+```
+
+- It **bubbles**, so any ancestor hears it — a component, or a plain `addEventListener`.
+- It is **cancelable**, and `$emit()` returns the event, so the emitter can read `event.defaultPrevented`.
+- The payload is **one object**, or nothing. A value that is not an object is refused by the type and reported at runtime as `event.invalid-emit-payload`. The event still dispatches.
+
+Nothing in the framework is gated on cancellation. It is a channel for component code.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Dialog extends Base {
+  static config = { name: 'Dialog' };
+
+  close() {
+    const event = this.$emit('close');
+    if (event.defaultPrevented) return;
+    this.$el.removeAttribute('data-option-open');
+  }
+}
+```
+
+### Typing the events a component emits
+
+`$emits` in the props type maps each name to its payload object, or to `void` for an event with no payload:
+
+```ts
+import { Base } from '@studiometa/js-toolkit';
+
+class Slider extends Base<{
+  $emits: {
+    goto: { index: number };
+    stop: void;
+  };
+}> {
+  static config = { name: 'Slider' };
+
+  mounted() {
+    this.$emit('goto', { index: 2 });
+    this.$emit('stop');
+  }
+}
+```
+
+`$emits` replaces the runtime `config.emits` of v3. Nothing of it stays in the bundle.
+
+## Child events {#child-events}
+
+A parent hears a child through `on<Child><Event>`, resolved against the names in `config.components`:
+
+```ts
+import { Base, type DelegatedEvent } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base<{ $emits: { open: { height: number } } }> {
+  static config = { name: 'AccordionItem' };
+
+  onClick() {
+    this.$emit('open', { height: this.$el.scrollHeight });
+  }
+}
+
+class Accordion extends Base {
+  static config = {
+    name: 'Accordion',
+    components: { AccordionItem },
+  };
+
+  onAccordionItemOpen({ target, payload }: DelegatedEvent<AccordionItem, 'open'>) {
+    console.log(`${target.$id} opened to ${payload.height}px`);
+  }
+}
+```
+
+How it works:
+
+- **One listener per event type** on the parent's root element.
+- The handler walks from `event.target` up to `this.$el`, reads the instance map of each element, and calls `on<Name><Event>` for the **first mounted instance** that matches.
+- A child inserted later needs no new binding.
+- Events that do not bubble, `mouseenter` and `mouseleave` included, are delegated from the **capture** phase.
+
+**`config.components` is what disambiguates the name**
+
+A method name alone is ambiguous: `onSliderDragStart` is `SliderDrag` + `start`, or `Slider` + `drag-start`. The name set from `config.components` is what decides. A child that is not declared there is not resolved.
+
+A lazy child works the same way — the string key is the name, so nothing is downloaded to resolve a handler:
+
+```js
+static config = {
+  name: 'Accordion',
+  components: { AccordionItem: () => import('./AccordionItem.js') },
+};
+```
+
+## Global handlers
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class ClickOutside extends Base {
+  static config = { name: 'ClickOutside' };
+
+  onDocumentClick({ event }) {
+    if (!event.composedPath().includes(this.$el)) {
+      this.$emit('click-outside', { event });
+    }
+  }
+
+  onWindowResize() {
+    this.$el.removeAttribute('data-option-open');
+  }
+}
+```
+
+- **Scope: the mount cycle.** `$unmount()` removes the listener and a new mount binds it again.
+- **Phase: bubble, always.** `onDocumentClick` hears what `document.addEventListener('click', …)` hears. To hear a descendant's non-bubbling event, use `on<Ref><Event>`.
+- **The two prefixes are reserved**, and they match before children and refs. `onWindowResize` binds to `window` even in a component whose `config.components` holds a `Window`. To reach a child with that name, use `@on('Window', 'resize')`.
+- The rule is about method names only. `onClick` and `onDocumentClick` are different names and both can exist; a click on the element fires both.
+- The payload is `{ event, target }`, where `target` is the global the handler names. There is no `payload` and no `index`.
+
+## `$on()` and `$off()`
+
+For an event whose name is data rather than a method name, listen by hand and return the cleanup:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Watcher extends Base {
+  static config = { name: 'Watcher', options: { events: Array } };
+
+  mounted() {
+    // `$on()` returns its own remover.
+    return this.$options.events.map((type) => this.$on(type, () => console.log(type)));
+  }
+}
+```
+
+## Negotiated events
+
+Two helpers let a component announce a step **before** it happens so an ancestor can take part. They are not `Base` methods and they are absent from `$emits`:
+
+| mode          | asks for   | registers with | keeps                 | on failure                     |
+| ------------- | ---------- | -------------- | --------------------- | ------------------------------ |
+| **take over** | the action | `wrap(runner)` | one runner, last wins | the mutation is applied anyway |
+| **delay**     | the moment | `waitUntil(x)` | many, all are awaited | the step happens anyway        |
+
+```js
+import { Base, EVENTS, domUpdate, emitExtendable, viewTransition } from '@studiometa/js-toolkit';
+
+class Panel extends Base {
+  static config = { name: 'Panel' };
+
+  // Take over: the code that mutates announces instead of mutating.
+  async render(fragment) {
+    await domUpdate(this.$el, () => this.$el.replaceChildren(fragment));
+  }
+
+  // Delay: the choreography announces its step and waits.
+  async close() {
+    await emitExtendable(this.$el, 'close');
+    this.$el.removeAttribute('data-option-open');
+  }
+
+  mounted() {
+    return [
+      this.$on(EVENTS.dom.update, (event) => event.detail.wrap(viewTransition)),
+      this.$on('close', (event) => event.detail.waitUntil(this.leave())),
+    ];
+  }
+
+  leave() {
+    return Promise.resolve();
+  }
+}
+```
+
+- **`defaultPrevented` is ignored.** The step is announced, not proposed.
+- **A registration is valid only while the event dispatches.** A listener that keeps the function and calls it later is warned (`protocol.late-registration`) and ignored.
+- **The work of the emitter always completes.** A runner that throws, rejects, or never calls `apply` loses the animation, never the change.
+- **An unclaimed `domUpdate()` is synchronous.** With no listener the mutation runs before the returned promise exists.
+
+See [`domUpdate()`](../../api/dom/domUpdate.md) and [`emitExtendable()`](../../api/dom/emitExtendable.md).
+
+## Framework events
+
+`EVENTS` is a deeply frozen object of the events the framework itself dispatches, all namespaced `js-toolkit:`:
+
+```js
+import { EVENTS } from '@studiometa/js-toolkit';
+
+EVENTS.component.mounted; // 'js-toolkit:component:mounted'
+EVENTS.component.unmounted; // 'js-toolkit:component:unmounted'
+EVENTS.dom.update; // 'js-toolkit:dom:update'
+EVENTS.diagnostic; // 'js-toolkit:diagnostic'
+```
+
+Component events are typed lower-kebab string literals declared through `$emits`. Private framework transports — the context request, for one — use module-local constants and are deliberately **not** in `EVENTS`.