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

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

@@ -0,0 +1,42 @@
+# useBreakpoint
+
+```ts
+useBreakpoint(): Service<{ readonly name: string }>
+```
+
+The active breakpoint name, as a service. It is its **own source** — it is not derived from a resize.
+
+## Usage
+
+```js
+import { useBreakpoint } from '@studiometa/js-toolkit';
+
+const unsubscribe = useBreakpoint().subscribe(({ name }) => {
+  document.documentElement.dataset.breakpoint = name;
+});
+```
+
+## Why it is not part of the resize service
+
+It is backed by `matchMedia` `change` listeners, so it emits **on crossings** and it reports a change of the reader's font size — which a `ResizeObserver` on a box cannot see.
+
+The values are in `rem`, and in a media query `rem` resolves against the **initial** font size, not against the root element.
+
+`ResizeProps` therefore dropped `breakpoints` and `activeBreakpoints`: they were a different measurement wearing the same shape.
+
+## The named set
+
+See [Breakpoints](../dom/breakpoints.md) for `BREAKPOINTS`, `getBreakpoints()` and `setBreakpoints()`.
+
+`setBreakpoints()` replaces the set and emits at once. The `MediaQueryList` objects are built once, and the active name is memoised for the length of one task — `setBreakpoints()` and the `change` handler of a running service clear that memo immediately.
+
+## Who else uses it
+
+- Every responsive **option** resolves through the same active-name read, but a `matchMedia` subscription only opens for a component that declares [`option<Name>Changed()`](../methods-hooks-options.md).
+- Connected elements with a scoped `data-component` declaration share **one** reference-counted subscription to this service. A page with plain declarations opens none.
+
+The breakpoint service is part of the core graph on every page. What it costs is a subscription, and a page that asks for nothing opens none.
+
+## `{ immediate: true }` works here
+
+There is always a current breakpoint.

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

@@ -0,0 +1,119 @@
+# useDrag
+
+```ts
+useDrag(target: HTMLElement | SVGElement, options?: DragOptions): Service<DragProps>
+```
+
+A drag gesture, with an optional inertia phase.
+
+## Props
+
+```ts
+interface DragProps {
+  readonly mode: DragMode;
+  readonly x: number;
+  readonly y: number;
+  readonly deltaX: number;
+  readonly deltaY: number;
+  readonly originX: number;
+  readonly originY: number;
+  readonly distanceX: number;
+  readonly distanceY: number;
+  readonly finalX: number;
+  readonly finalY: number;
+}
+```
+
+`isGrabbing`, `hasInertia` and `target` are removed, and `props.MODES` with them.
+
+## The modes
+
+```js
+import { DRAG_MODES } from '@studiometa/js-toolkit';
+
+DRAG_MODES.IDLE; // 'idle'
+DRAG_MODES.START; // 'start'
+DRAG_MODES.DRAG; // 'drag'
+DRAG_MODES.DROP; // 'drop'
+DRAG_MODES.INERTIA; // 'inertia'
+DRAG_MODES.STOP; // 'stop'
+```
+
+`idle` is new in v4. `DragMode` is derived from the frozen object — that is the pattern for every closed set of strings in the framework.
+
+## Options
+
+```ts
+interface DragOptions {
+  axis?: 'x' | 'y' | 'both';
+  dampFactor?: number;
+  dragThreshold?: number;
+  inertia?: boolean;
+}
+```
+
+The v3 spelling `dragTreshold` is fixed.
+
+## Usage
+
+```js
+import { Base, DRAG_MODES, useDrag } from '@studiometa/js-toolkit';
+
+class Slide extends Base {
+  static config = { name: 'Slide' };
+
+  mounted() {
+    return useDrag(this.$el, { axis: 'x' }).subscribe(({ mode, x, finalX }) => {
+      if (mode === DRAG_MODES.DROP) {
+        this.settle(finalX);
+        return;
+      }
+      this.$el.style.transform = `translateX(${x}px)`;
+    });
+  }
+
+  settle(x) {}
+}
+```
+
+## A gesture the browser can steal is not a gesture
+
+`useDrag` owns both axes by default and writes `touch-action: none`.
+
+| `axis`   | writes  | and                           |
+| -------- | ------- | ----------------------------- |
+| `'both'` | `none`  | —                             |
+| `'x'`    | `pan-y` | every Y movement prop is zero |
+| `'y'`    | `pan-x` | every X movement prop is zero |
+
+It writes **only when the computed value is `auto`**, and it restores the previous inline value when the last service of those options leaves. Services on one target share that ownership.
+
+The click that ends a drag is suppressed from a flag that movement on the owned axis arms and the next `pointerdown` disarms — and only for a **trusted** click with a non-zero `detail`.
+
+## Inertia
+
+With `{ inertia: false }` a drag publishes the **exact projected destination** at `drop`, then goes through `stop` to `idle` with no tick subscription at all.
+
+With inertia, the coast subscribes to `scheduler.tick()`. Decay is expressed in time, not in frames:
+
+- `INERTIA_FRAME` (16.67 ms) is the reference of every factor;
+- `inertiaStep()` integrates the decay across the step, so any sequence of frames sums to `velocity · τ` exactly;
+- the settle position is `value + velocity · τ` with `τ = INERTIA_FRAME / ln(1 / damp)`.
+
+The velocity is sampled as a distance over the interval between events, smoothed, with the interval clamped at both ends. **At the drop, the velocity is decayed by the idle time through the same law** — so a pointer that stopped moving before release does not fling.
+
+## Keying
+
+`useDrag()` keys its axis, inertia, damping and threshold, so two callers asking for the same gesture on the same element share one service. See [`perTarget()`](perTarget.md).
+
+## `{ immediate: true }`
+
+Does nothing outside a gesture: there is no current value between gestures.
+
+## Mixin
+
+```js
+class Slide extends withDrag(Base, { axis: 'x', inertia: false }) {
+  dragged({ mode, x }) {}
+}
+```

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

@@ -0,0 +1,64 @@
+# useInView
+
+```ts
+useInView(target: Element, init?: IntersectionObserverInit): Service<InViewProps>
+```
+
+An `IntersectionObserver` as a service.
+
+## Props
+
+```ts
+interface InViewProps {
+  readonly isInView: boolean;
+  readonly entry: IntersectionObserverEntry | null;
+}
+```
+
+## Usage
+
+```js
+import { Base, useInView } from '@studiometa/js-toolkit';
+
+class Reveal extends Base {
+  static config = { name: 'Reveal' };
+
+  mounted() {
+    return useInView(this.$el, { threshold: 0.25 }).subscribe(({ isInView }) => {
+      this.$el.classList.toggle('is-in-view', isInView);
+    });
+  }
+}
+```
+
+## Keying
+
+`useInView()` keys **every `IntersectionObserverInit` field**, and gives an object root a stable weak identity so two callers passing the same root element share one service.
+
+The options are read by meaning, not by spelling: keys are sorted at every depth and the ones holding `undefined` are dropped, so `{ threshold: 0.5, rootMargin: '0px' }` and `{ rootMargin: '0px', threshold: 0.5 }` are the same service.
+
+**Nothing groups observers across targets.**
+
+## `{ immediate: true }` is the default here
+
+`withInView` defaults it to `true`, because "am I in view" has a current answer and a consumer that has to wait for the first crossing to find out would be wrong on load.
+
+## This is not a mount strategy
+
+`useInView` and `withInView` observe a component that is **already mounted**. They do not replace `data-mount="visible"` or `data-mount="in-view"`, which decide whether the instance exists at all.
+
+| Want                                           | Use                          |
+| ---------------------------------------------- | ---------------------------- |
+| the component to exist only once seen          | `data-mount="visible"`       |
+| the component to come and go with the viewport | `data-mount="in-view"`       |
+| a mounted component to react to crossings      | `useInView()` / `withInView` |
+
+See [Mount strategies](../../guide/going-further/mount-strategies.md).
+
+## Mixin
+
+```js
+class Reveal extends withInView(Base, { threshold: 0.25 }) {
+  intersected({ isInView }) {}
+}
+```

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

@@ -0,0 +1,105 @@
+# useKey
+
+```ts
+useKey(target?: Document | Element | Window): Service<KeyProps>
+```
+
+The keyboard as a service, one instance per target, defaulting to the document.
+
+## Props
+
+```ts
+interface KeyProps {
+  readonly event: KeyboardEvent | null;
+  readonly triggered: number;
+  readonly isDown: boolean;
+  readonly isUp: boolean;
+  // plus one boolean per named key
+  readonly ENTER: boolean;
+  readonly SPACE: boolean;
+  readonly TAB: boolean;
+  readonly ESC: boolean;
+  readonly LEFT: boolean;
+  readonly UP: boolean;
+  readonly RIGHT: boolean;
+  readonly DOWN: boolean;
+}
+```
+
+## Usage
+
+```js
+import { Base, useKey } from '@studiometa/js-toolkit';
+
+class Dialog extends Base {
+  static config = { name: 'Dialog' };
+
+  mounted() {
+    return useKey().subscribe(({ ESC, isDown }) => {
+      if (ESC && isDown) this.$el.removeAttribute('data-option-open');
+    });
+  }
+}
+```
+
+A region rather than the document:
+
+```js
+import { Base, useKey } from '@studiometa/js-toolkit';
+
+class Menu extends Base {
+  static config = { name: 'Menu' };
+
+  mounted() {
+    return useKey(this.$el).subscribe(({ DOWN, isDown }) => {
+      if (DOWN && isDown) this.focusNext();
+    });
+  }
+
+  focusNext() {}
+}
+```
+
+**An element target is what removes the `hasFocus` bookkeeping** a document-only service forces on a consumer.
+
+## The eight names
+
+The eight names of v3 are kept, resolved from `KeyboardEvent.key` rather than from the deprecated `keyCode`:
+
+| Name    | `event.key`  |
+| ------- | ------------ |
+| `ENTER` | `Enter`      |
+| `SPACE` | `' '`        |
+| `TAB`   | `Tab`        |
+| `ESC`   | `Escape`     |
+| `LEFT`  | `ArrowLeft`  |
+| `UP`    | `ArrowUp`    |
+| `RIGHT` | `ArrowRight` |
+| `DOWN`  | `ArrowDown`  |
+
+The constant that maps them is **module-internal**: the names reach a consumer as props, so nothing is left to compare against. The flags are a mapped type over that constant, so the props cannot drift from it.
+
+**Why they are an exception**
+
+Props are flat and nothing derivable is a field — and each of these compares `event.key` against a named value, so nothing about them is unavailable from `event`. They are kept for call-site parity with v3, where `keyed({ ESC })` is how components read the keyboard.
+
+## `triggered` counts repeats of _one_ key
+
+A keydown whose key matches the previous event's **while that key is still down** increments it. A different key, or any keyup, sets it back to `1`.
+
+v3 incremented on any two consecutive keydowns, so holding `A` and then pressing `B` reported `2`.
+
+## The listeners are neither passive nor capturing
+
+- **Not passive**, because `trapFocus()` and every keyboard shortcut call `preventDefault()` on the event the subscriber is handed, and a passive listener cannot.
+- **No capture**, unlike the pointer service, because a descendant that handles its own keys and stops the propagation is **respected** rather than overheard.
+
+## Mixin
+
+```js
+class Dialog extends withKey(Base) {
+  keyed({ ESC, isDown }) {}
+}
+```
+
+`withKey` takes the document default too, as `withScroll` and `withResize` do for their own page-wide source. A region is `withKey(Base, { target: (instance) => instance.$refs.wrapper })`.

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

@@ -0,0 +1,45 @@
+# useMediaQuery
+
+```ts
+useMediaQuery(query: string): Service<{ readonly matches: boolean }>
+```
+
+The `matchMedia` engine, exposed. One instance per query string.
+
+## Usage
+
+```js
+import { useMediaQuery } from '@studiometa/js-toolkit';
+
+const wide = useMediaQuery('(min-width: 64rem)');
+
+// `props()` answers with no subscription, because asking a MediaQueryList is a read.
+if (wide.props().matches) {
+  // …
+}
+
+const unsubscribe = wide.subscribe(({ matches }) => {
+  console.log(matches);
+});
+```
+
+**Parameters**
+
+- `query` — any media query string.
+
+## `props()` needs no subscription
+
+Asking a `MediaQueryList` whether it matches **is a read**, so this service can answer without starting anything. Emissions are crossings.
+
+That makes it the one service where `props()` outside a subscription is not a compromise.
+
+## Where it is used
+
+`data-mount="media:<query>"` is this service, which is why that strategy is **reversible**: a crossing out unmounts the instance and a crossing back mounts it again.
+
+See [Mount strategies](../../guide/going-further/mount-strategies.md).
+
+## See also
+
+- [`usePrefersReducedMotion()`](usePrefersReducedMotion.md) — the named case
+- [`useBreakpoint()`](useBreakpoint.md) — the named breakpoint set

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

@@ -0,0 +1,69 @@
+# useMutation
+
+```ts
+useMutation(target: Node, init?: MutationObserverInit): Service<MutationProps>
+```
+
+A general `MutationObserver` as a service, for "tell me when anything under this node changes".
+
+## Props
+
+```ts
+interface MutationProps {
+  readonly records: readonly MutationRecord[];
+}
+```
+
+The default observation is `{ childList: true, subtree: true }`.
+
+## Usage
+
+```js
+import { Base, useMutation } from '@studiometa/js-toolkit';
+
+class Counter extends Base {
+  static config = { name: 'Counter', refs: ['list'] };
+
+  mounted() {
+    return useMutation(this.$el, { childList: true }).subscribe(({ records }) => {
+      this.$el.dataset.count = String(this.$el.children.length);
+    });
+  }
+}
+```
+
+## Reach for something narrower first
+
+| Want                                         | Use                                                                  |
+| -------------------------------------------- | -------------------------------------------------------------------- |
+| one attribute of one element                 | [`watchAttributes()`](../dom/watchAttributes.md)                 |
+| a whole namespace of attributes              | [`watchAttributeNamespace()`](../dom/watchAttributeNamespace.md) |
+| what the framework already reconciles        | the registry — it is already watching                                |
+| a subtree, character data, or a foreign node | **this**                                                             |
+
+## It keeps nothing after the delivery
+
+`props()` is **empty between deliveries**, so `{ immediate: true }` waits for a real batch rather than inventing one. That is the honest answer for a service whose value _is_ a batch.
+
+## Platform timing, not framework order
+
+This service delivers on the **platform's** timing. A subscriber that needs the framework's order awaits `whenDOMSettled()` in its callback:
+
+```js
+useMutation(el).subscribe(async () => {
+  await whenDOMSettled();
+  // the new components have mounted
+});
+```
+
+## Keying
+
+Its key is a **canonical init**, through `resolveInit()`, which keeps the DOM contract rather than sorting the object blindly. See [`perTarget()`](perTarget.md).
+
+## Mixin
+
+```js
+class Counter extends withMutation(Base, { childList: true }) {
+  mutated({ records }) {}
+}
+```

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

@@ -0,0 +1,91 @@
+# usePointer
+
+```ts
+usePointer(): Service<PointerProps>
+usePointer(target: Element): Service<ElementPointerProps>
+```
+
+The pointer, in the viewport or in a box.
+
+## Props
+
+```ts
+interface PointerProps {
+  readonly event: PointerEvent | null;
+  readonly isDown: boolean;
+  readonly x: number;
+  readonly y: number;
+  readonly deltaX: number;
+  readonly deltaY: number;
+  readonly maxX: number;
+  readonly maxY: number;
+  readonly progressX: number;
+  readonly progressY: number;
+}
+
+interface ElementPointerProps extends PointerProps {
+  readonly relativeX: number;
+  readonly relativeY: number;
+  readonly relativeProgressX: number;
+  readonly relativeProgressY: number;
+}
+```
+
+`isGrabbing` is removed. `usePointer()` uses **pointer events only** and follows one `pointerId` at a time.
+
+## Usage
+
+```js
+import { Base, usePointer } from '@studiometa/js-toolkit';
+
+class Cursor extends Base {
+  static config = { name: 'Cursor' };
+
+  mounted() {
+    return usePointer().subscribe(({ x, y }) => {
+      this.$el.style.transform = `translate(${x}px, ${y}px)`;
+    });
+  }
+}
+```
+
+## The pointer in a box
+
+`usePointer(el)` is one lazy service per target, and its props add the four `relative*` fields beside the viewport ones:
+
+```js
+import { Base, usePointer } from '@studiometa/js-toolkit';
+
+class Tilt extends Base {
+  static config = { name: 'Tilt' };
+
+  mounted() {
+    return usePointer(this.$el).subscribe(({ relativeProgressX, relativeProgressY }) => {
+      this.$el.style.setProperty('--tilt-x', String(relativeProgressX * 2 - 1));
+      this.$el.style.setProperty('--tilt-y', String(relativeProgressY * 2 - 1));
+    });
+  }
+}
+```
+
+**The targeted service subscribes to the singleton**, so one set of document listeners serves every target however many boxes are being watched.
+
+## When the box is measured
+
+On demand, and kept until a `scroll` (captured at the document), a `resize`, or the target's `ResizeObserver` can have moved it.
+
+**The layout box is the frame of reference**, so a transform the consumer applies from its own callback does not invalidate it — which is exactly what a tilt or a parallax needs.
+
+## `{ immediate: true }`
+
+Does nothing before the pointer has been seen: there is no current value to deliver, which is what `hasProps()` says.
+
+## Mixin
+
+```js
+class Tilt extends withPointer(Base) {
+  moved({ relativeProgressX }) {}
+}
+```
+
+`withPointer` defaults its target to `$el`.

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

@@ -0,0 +1,42 @@
+# usePrefersReducedMotion
+
+```ts
+usePrefersReducedMotion(): Service<{ readonly matches: boolean }>
+```
+
+`(prefers-reduced-motion: reduce)` as a named service.
+
+## Usage
+
+```js
+import { Base, usePrefersReducedMotion } from '@studiometa/js-toolkit';
+
+class Carousel extends Base {
+  static config = { name: 'Carousel' };
+
+  mounted() {
+    return usePrefersReducedMotion().subscribe(({ matches }) => {
+      matches ? this.stopAutoplay() : this.startAutoplay();
+    });
+  }
+
+  startAutoplay() {}
+  stopAutoplay() {}
+}
+```
+
+## Why it is a service and not a read
+
+**The preference changes while the page is open.** A read at load time is a snapshot that goes stale, and the user who turns reduced motion on mid-visit is exactly the user who most wants it honoured.
+
+`props()` answers with no subscription, like every [`useMediaQuery()`](useMediaQuery.md) instance — so a one-off check is still one line. Subscribe when the component should follow the change.
+
+## Mounting on the preference instead
+
+To decide whether a component exists at all, use the mount strategy:
+
+```html
+<div data-component="Parallax" data-mount="media:(prefers-reduced-motion: no-preference)"></div>
+```
+
+That strategy is **reversible**, so turning the preference on unmounts the component and turning it off mounts it again. `withMountWhenPrefersMotion` is deleted.

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

@@ -0,0 +1,91 @@
+# useRaf
+
+```ts
+useRaf(): Service<RafProps, void | RafRender>
+```
+
+The frame clock as a service. It has nothing to scope, so there is one instance.
+
+## Props
+
+```ts
+interface RafProps {
+  readonly time: DOMHighResTimeStamp;
+  readonly delta: number;
+}
+```
+
+`delta` is clamped to `[1, 40]` ms, and the first tick after the loop wakes reports `1000/60`. `time` stays the raw rAF timestamp.
+
+## Usage
+
+```js
+import { Base, useRaf } from '@studiometa/js-toolkit';
+
+class Ticker extends Base {
+  static config = { name: 'Ticker' };
+
+  mounted() {
+    return useRaf().subscribe(({ delta }) => {
+      // …
+    });
+  }
+}
+```
+
+## A callback can return a render function
+
+`useRaf` is the one service whose callback return value is used. Return a function and it runs in the frame's `write` phase:
+
+```js
+import { Base, useRaf } from '@studiometa/js-toolkit';
+
+class Follower extends Base {
+  static config = { name: 'Follower' };
+
+  mounted() {
+    return useRaf().subscribe(({ delta }) => {
+      const x = this.$el.offsetLeft + delta;
+      return () => {
+        this.$el.style.transform = `translateX(${x}px)`;
+      };
+    });
+  }
+}
+```
+
+The service collects the render functions of its callbacks and **cancels a render whose subscriber left between the two phases**.
+
+## It does not own a loop
+
+It subscribes to `scheduler.tick()`. The scheduler requests the next frame while a tick subscriber stays, so there is no permanent rAF loop and no loop of the service's own.
+
+`{ immediate: true }` does nothing here: the frame tick has **no current value between two frames**, which is what its `hasProps()` says.
+
+## Switching it on and off
+
+```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() {
+    return this.#frame.stop;
+  }
+
+  follow(delta) {}
+}
+```
+
+See [`toggle()`](toggle.md), and `withRaf(Base, { manual: true })` in [Mixins](mixins.md).
+
+## Mixin
+
+```js
+class Follower extends withRaf(Base) {
+  ticked({ delta }) {}
+}
+```