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

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 }) {}
+}
+```

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

@@ -0,0 +1,60 @@
+# useResize
+
+```ts
+useResize(target?: Element): Service<ResizeProps>
+```
+
+The size of one element. With no target it is the document element, which reports the viewport.
+
+## Props
+
+```ts
+interface ResizeProps {
+  readonly width: number;
+  readonly height: number;
+  readonly ratio: number;
+  readonly orientation: 'square' | 'landscape' | 'portrait';
+}
+```
+
+`breakpoints` and `activeBreakpoints` are removed — [`useBreakpoint()`](useBreakpoint.md) is their own source now.
+
+## Usage
+
+```js
+import { Base, useResize } from '@studiometa/js-toolkit';
+
+class Grid extends Base {
+  static config = { name: 'Grid' };
+
+  mounted() {
+    return useResize(this.$el).subscribe(({ width, orientation }) => {
+      this.$el.classList.toggle('is-narrow', width < 480);
+    });
+  }
+}
+```
+
+## A `ResizeObserver` does not see the viewport
+
+It reports the **box of the observed element**, which is what catches a zoom or a scrollbar. For the root element, `clientWidth` and `clientHeight` report the viewport and are decoupled from the observed box — so the viewport service keeps a `resize` listener as well.
+
+That is why `useResize()` with no target and `useResize(someElement)` are not the same kind of measurement, even though they share a props shape.
+
+## `{ immediate: true }` works here
+
+An element has a current size between deliveries.
+
+## Mixin
+
+```js
+class Grid extends withResize(Base) {
+  resized({ width }) {}
+}
+```
+
+`withResize` defaults to the page-wide source, as `withScroll` does. Scope it with `{ target: (instance) => instance.$el }`.
+
+## See also
+
+[`useWindowSize()`](useWindowSize.md) — the named default case.

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

@@ -0,0 +1,88 @@
+# useScroll
+
+```ts
+useScroll(target?: Element | Window): Service<ScrollProps>
+```
+
+Scroll position, movement and direction for one scroller. With no target it is the document element; `useScroll(document.documentElement)` is the window service.
+
+## Props
+
+```ts
+interface ScrollProps {
+  readonly x: number;
+  readonly y: number;
+  readonly deltaX: number;
+  readonly deltaY: number;
+  readonly maxX: number;
+  readonly maxY: number;
+  readonly progressX: number;
+  readonly progressY: number;
+  readonly directionX: -1 | 0 | 1;
+  readonly directionY: -1 | 0 | 1;
+  readonly isScrolling: boolean;
+}
+```
+
+Nothing derivable is a field: `lastX` is `x - deltaX`, and `changedX` is `deltaX !== 0`.
+
+## Usage
+
+```js
+import { Base, useScroll } from '@studiometa/js-toolkit';
+
+class Header extends Base {
+  static config = { name: 'Header' };
+
+  mounted() {
+    return useScroll().subscribe(({ y, directionY }) => {
+      this.$el.classList.toggle('is-hidden', directionY > 0 && y > 100);
+    });
+  }
+}
+```
+
+A region rather than the page:
+
+```js
+import { Base, useScroll } from '@studiometa/js-toolkit';
+
+class Panel extends Base {
+  static config = { name: 'Panel', refs: ['scroller'] };
+
+  mounted() {
+    return useScroll(this.$refs.scroller).subscribe(({ progressY }) => {
+      this.$el.style.setProperty('--progress', String(progressY));
+    });
+  }
+}
+```
+
+## One `read` per frame
+
+The service **coalesces its scroll events into one `read` per frame**, so a page scrolling at speed measures once per frame rather than once per event.
+
+## Extents are observed, not sampled once
+
+The service watches the scroller **and its element children** with a `ResizeObserver`, plus a `childList` MutationObserver to keep that set correct: `1 + n` observed boxes per scroller, lazy and released with the last subscriber.
+
+That is what keeps `maxY` and `progressY` correct when content is added, removed or resized.
+
+## `{ immediate: true }` works here
+
+A scroller has a current position between deliveries, so the first delivery is honoured. The first props of a run carry **no movement**: the deltas are zero and `directionX`/`directionY` are `0`.
+
+## Mixin
+
+```js
+class Header extends withScroll(Base) {
+  scrolled({ y, directionY }) {}
+}
+```
+
+`withScroll` defaults to the page-wide source. A region is `withScroll(Base, { target: (instance) => instance.$refs.scroller })`.
+
+## See also
+
+- [`useWindowScroll()`](useWindowScroll.md) — the named default case
+- [`useScrollProgress()`](useScrollProgress.md) — an element's progress through the viewport

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

@@ -0,0 +1,88 @@
+# useScrollProgress
+
+```ts
+useScrollProgress(target: Element, options?: { offset?: string }): Service<ScrollProgressProps>
+```
+
+An element's progress through the viewport as it scrolls.
+
+## Props
+
+```ts
+interface ScrollProgressProps {
+  readonly startX: number;
+  readonly startY: number;
+  readonly endX: number;
+  readonly endY: number;
+  readonly currentX: number;
+  readonly currentY: number;
+  readonly progressX: number;
+  readonly progressY: number;
+}
+```
+
+`start` and `end` are the scroll positions at which the progress is `0` and `1`; `current` is where the scroller is now.
+
+## Usage
+
+```js
+import { Base, useScrollProgress } from '@studiometa/js-toolkit';
+
+class Parallax extends Base {
+  static config = { name: 'Parallax' };
+
+  mounted() {
+    return useScrollProgress(this.$el).subscribe(({ progressY }) => {
+      this.$el.style.setProperty('--progress', String(progressY));
+    });
+  }
+}
+```
+
+## The `offset` option
+
+One string holding **two edge pairs**, separated by a `/`:
+
+```
+"<target> <viewport> / <target> <viewport>"
+```
+
+The first pair is where the progress is `0`, the second where it is `1`. In each pair, the first token is an edge of the **target** and the second an edge of the **viewport**.
+
+The default is:
+
+```js
+useScrollProgress(el, { offset: 'start end / end start' });
+```
+
+which reads as "0 when the target's start meets the viewport's end, 1 when the target's end meets the viewport's start" — the element travelling the full height of the viewport.
+
+Each token is one of:
+
+| Token                            | Means                            |
+| -------------------------------- | -------------------------------- |
+| `start`                          | the leading edge                 |
+| `center`                         | the middle                       |
+| `end`                            | the trailing edge                |
+| `50%`                            | a fraction of the box            |
+| `120px`                          | an absolute offset from the edge |
+| `20vh`, `10vw`, `5vmin`, `5vmax` | a viewport unit                  |
+| a number                         | a fraction, as `0.5`             |
+
+A token that parses as nothing falls back to the edge.
+
+The **resolved** offset is part of the service's key, so two callers asking for the same range on the same element share one service.
+
+## Mixin
+
+```js
+class Parallax extends withScrollProgress(Base, { offset: 'center end / center start' }) {
+  scrolledInView({ progressY }) {}
+}
+```
+
+The hook is named `scrolledInView`.
+
+## Smoothing a progress value
+
+Progress props carry no frame delta, and [`damp()`](../../utils/math.md) takes the elapsed time as a required argument — decay is expressed in time, not in frames. So either take the delta from a [`useRaf()`](useRaf.md) tick, or use [`smoothTo()`](../../utils/motion.md), which owns its own frame subscription and releases it when the value arrives.