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

package/skills/studiometa-js-toolkit/references/guide/introduction/managing-options.md

@@ -0,0 +1,235 @@
+# Options
+
+An option is a value a component reads from its element. It is declared in `config.options` and written in the markup as `data-option-<name>`.
+
+Two rules carry everything else on this page:
+
+> **An option is an input, never a store.**
+>
+> **Every option is responsive. There is nothing to declare for it.**
+
+## Declaring options
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Slider extends Base {
+  static config = {
+    name: 'Slider',
+    options: {
+      // The short form: just the type.
+      label: String,
+      // The long form: a type and a default.
+      speed: { type: Number, default: 1 },
+      loop: { type: Boolean, default: true },
+      // Array and Object defaults must be factory functions.
+      tween: { type: Object, default: () => ({ ease: 'linear' }) },
+    },
+  };
+
+  mounted() {
+    console.log(this.$options.speed);
+  }
+}
+```
+
+```html
+<div data-component="Slider" data-option-speed="2" data-option-label="Gallery"></div>
+```
+
+The attribute name is the option name in kebab case: `dragThreshold` is `data-option-drag-threshold`.
+
+## `$options` is a read-only view
+
+`buildOptions()` defines every property with a **getter and no setter**. The value is derived from the element and the viewport on each access, and nothing is written in. An assignment throws, because a module is strict code:
+
+```js
+this.$options.open = true;
+// TypeError: Cannot set property open of #<Object> which has only a getter
+```
+
+Two idioms replace the write, and which one you want depends on what the value is.
+
+**The DOM is meant to change** — write the attribute. It is the same statement the markup makes:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Panel extends Base {
+  static config = { name: 'Panel', options: { disabled: Boolean } };
+
+  enable() {
+    this.$el.removeAttribute('data-option-disabled');
+  }
+
+  disable() {
+    this.$el.setAttribute('data-option-disabled', '');
+  }
+}
+```
+
+The next read gives the new value, and [`option<Name>Changed()`](#live-effects) announces it to anyone listening.
+
+**The value was never an input** — keep a private field seeded from the option. The attribute says where the component starts; the field carries where it has got to:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Carousel extends Base {
+  static config = { name: 'Carousel', options: { start: { type: Number, default: 0 } } };
+
+  #index = this.$options.start;
+
+  next() {
+    this.#index += 1;
+  }
+}
+```
+
+An option a component only reads keeps neither: it reads `this.$options.x` where it needs it.
+
+## Defaults
+
+**A primitive can be a default. Every other data type needs a factory function.**
+
+```js
+options: {
+  speed: { type: Number, default: 1 },                       // fine
+  tween: { type: Object, default: () => ({ ease: 'linear' }) }, // required form
+  items: { type: Array, default: () => [] },                    // required form
+}
+```
+
+- `Function` is not an option type, so a `default` that is a function is always a factory.
+- A default is built **once per instance** and then kept. Two instances never share one default.
+- A factory is **lazy**. Nothing is built for an option nobody reads, and a component whose attribute is present never runs its factory.
+- `Array` and `Object` with no declared default get an empty value per instance.
+- A literal object or array default gives one `option.literal-default` warning, naming the component, the option and the correction. The value is then used as declared and **shared** between instances.
+
+A default is the one option value that lives on the instance, so mutating the object a factory built sticks — `this.$options.tween.ease = 'ease-out'` is kept, for that instance. Replacing the option itself does not: `this.$options.tween = {}` throws, like every other write to the view.
+
+## Boolean options read presence
+
+`data-option-open` is on, an absent attribute is the declared default, and the string the attribute carries is **never read** — the way `disabled` and `checked` work on the platform:
+
+```html
+<div data-component="Panel" data-option-open></div>
+<!-- true -->
+<div data-component="Panel" data-option-open="false"></div>
+<!-- true — the value says nothing -->
+<div data-component="Panel"></div>
+<!-- the declared default -->
+```
+
+Update one from code by adding or removing the attribute:
+
+```js
+flag ? el.setAttribute('data-option-open', '') : el.removeAttribute('data-option-open');
+```
+
+A template must therefore write the attribute conditionally rather than interpolate a boolean into it:
+
+```html
+{# Correct #}
+<div data-component="Panel" {% if isOpen %}data-option-open{% endif %}></div>
+
+{# Wrong — always true #}
+<div data-component="Panel" data-option-open="{{ isOpen }}"></div>
+```
+
+### Turning one off — `data-option-no-<name>`
+
+A boolean option is turned off by an attribute that only has to be there:
+
+```html
+<div data-component="Dialog" data-option-no-trap-focus></div>
+```
+
+- It is how an option declared `default: true` is turned off, since removing an attribute that is not there says nothing.
+- **Only an option that can hold `false` has one** — a declared `Boolean`, or a union containing it. A `String` option has nothing to turn off, so `data-option-no-label` is not an attribute and the observer never watches for it.
+- **Presence is the whole statement.** `data-option-no-x="false"` is not a double negative; it is the same flag.
+- It is responsive like every other spelling.
+- An option whose own name starts with `no` negates independently: `noSort` owns `data-option-no-sort`, and its off spelling doubles the prefix, `data-option-no-no-sort`.
+
+## Several types
+
+An option can accept several types. Declare the constructors in order:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Sticky extends Base {
+  static config = {
+    name: 'Sticky',
+    options: {
+      // "10" reads as a number; "[10, 20]" reads as an array.
+      offset: [Number, Array],
+    },
+  };
+}
+```
+
+Each parser must give a value of its declared type before the next parser runs. An absent union option uses its declared default, or the empty value of its first type.
+
+## Responsive options
+
+Every option takes a breakpoint suffix, with no flag to declare:
+
+```html
+<div
+  data-component="Grid"
+  data-option-columns="1"
+  data-option-columns:s="2"
+  data-option-columns:l="4"></div>
+```
+
+- **The suffix names one breakpoint and it cascades upwards.** `$options.columns` walks from the active breakpoint down to the base value and gives the first attribute present. v3 spelled a set (`:xs:s`); v4 does not.
+- **The separator is a colon**, because an option name in kebab case can contain a dash.
+- **The value is derived on read.** Nothing is stored and nothing is written.
+- A suffix naming no configured breakpoint gives one `responsive.unknown-breakpoint` warning per mount.
+- A `matchMedia` subscription opens **only** for a component that declares `option<Name>Changed()`. A page that only reads options holds no listener.
+
+See [`setBreakpoints()`](../../api/dom/breakpoints.md) to replace the named set.
+
+## Live effects {#live-effects}
+
+A declared method named `option<Name>Changed()` makes that option a live effect. It is how an option that chooses a resource stays correct:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+function connect(url) {
+  return { dispose() {} };
+}
+
+class Feed extends Base {
+  static config = { name: 'Feed', options: { source: String } };
+
+  optionSourceChanged({ value, previousValue, initial }) {
+    const connection = connect(value);
+    // The returned function is the cleanup for *this* value.
+    return () => connection.dispose();
+  }
+}
+```
+
+- The hook runs **before `mounted()`** on each mount cycle, with `initial: true`.
+- Several writes in one mutation batch give **one** change, from the first old raw value to the final DOM value. A write that ends where it started is not a change.
+- The previous cleanup runs before an update. Every active cleanup runs on `$unmount()`.
+- Removal of the attribute applies the declared default.
+- A breakpoint crossing reports through the same hook. A crossing to the same resolved value announces nothing.
+- A component without the convention pays no setup cost.
+
+The payload is an [`OptionChange`](../../api/methods-hooks-options.md):
+
+```ts
+import { Base, type OptionChange } from '@studiometa/js-toolkit';
+
+class Feed extends Base {
+  static config = { name: 'Feed', options: { source: String } };
+
+  optionSourceChanged({ value, previousValue, rawValue, initial }: OptionChange<string>) {
+    console.log(value, previousValue, rawValue, initial);
+  }
+}
+```

package/skills/studiometa-js-toolkit/references/guide/introduction/managing-refs.md

@@ -0,0 +1,174 @@
+# Refs
+
+A ref is an element of a component's own markup, named in the HTML with `data-ref` and declared in `config.refs`.
+
+**Refs are live.** Each `$refs` property reads the DOM on access, so markup put into a component is found with no refresh, and no detached element stays in a list. There is no `$update()`.
+
+## A single ref
+
+```html
+<div data-component="Dialog">
+  <button data-ref="close">Close</button>
+</div>
+```
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Dialog extends Base {
+  static config = {
+    name: 'Dialog',
+    refs: ['close'],
+  };
+
+  mounted() {
+    this.$refs.close.focus();
+  }
+
+  onCloseClick() {
+    this.$el.removeAttribute('data-option-open');
+  }
+}
+```
+
+A plain declaration selects `[data-ref="close"]` and gives the **first** match.
+
+## A list of refs
+
+**A list ref keeps the `[]` in the attribute.** The suffix is part of the name, in the config and in the markup:
+
+```html
+<ul data-component="Tabs">
+  <li><button data-ref="tabs[]">One</button></li>
+  <li><button data-ref="tabs[]">Two</button></li>
+</ul>
+```
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Tabs extends Base {
+  static config = {
+    name: 'Tabs',
+    refs: ['tabs[]'],
+  };
+
+  onTabsClick({ index }) {
+    console.log(`tab ${index} was clicked`);
+  }
+}
+```
+
+`$refs.tabs` is an array. The property name never carries the suffix — `tabs[]` in the declaration, `$refs.tabs` everywhere else.
+
+**The two spellings must agree**
+
+`config.refs: ['tabs[]']` matches `data-ref="tabs[]"` and nothing else. The opposite mistake — the suffix missing from the attribute — gives one `ref.mismatch` warning per instance and per ref, naming the component and both spellings.
+
+## Ref boundaries
+
+By default a ref belongs to the **nearest enclosing component**. A ref inside a nested component is that component's, not yours:
+
+```html
+<div data-component="Slider">
+  <button data-ref="next">Slider's own</button>
+  <div data-component="SliderItem">
+    <button data-ref="next">SliderItem's, not Slider's</button>
+  </div>
+</div>
+```
+
+### Naming the owner
+
+A ref can name the component it belongs to, and then it crosses boundaries:
+
+```html
+<div data-component="Slider">
+  <div data-component="SliderItem">
+    <button data-ref="Slider.next">Slider's, from inside a child</button>
+  </div>
+</div>
+```
+
+`Slider.next` passes every boundary **except** another `Slider`, so the nearest `Slider` wins and a nested `Slider` shadows its parent.
+
+The namespace is written in the markup only, never in `config.refs`, and the name elsewhere never carries it:
+
+| markup                     | `config.refs` | property     | handler       | decorator          |
+| -------------------------- | ------------- | ------------ | ------------- | ------------------ |
+| `data-ref="next"`          | `'next'`      | `$refs.next` | `onNextClick` | `@on('next', …)`   |
+| `data-ref="Slider.next"`   | `'next'`      | `$refs.next` | `onNextClick` | `@on('next', …)`   |
+| `data-ref="dots[]"`        | `'dots[]'`    | `$refs.dots` | `onDotsClick` | `@on('dots[]', …)` |
+| `data-ref="Slider.dots[]"` | `'dots[]'`    | `$refs.dots` | `onDotsClick` | `@on('dots[]', …)` |
+
+The namespace goes **before** the suffix: `Component.name[]`.
+
+## Event handlers
+
+`on<Ref><Event>` handlers are **delegated from the root element**, so a ref that appears later needs no new binding:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Todo extends Base {
+  static config = {
+    name: 'Todo',
+    refs: ['items[]', 'input'],
+  };
+
+  // Fires for any `items[]` ref, including the ones added after mount.
+  onItemsClick({ event, target, index }) {
+    console.log(index, target);
+  }
+
+  onInputInput({ target }) {
+    console.log(target.value);
+  }
+}
+```
+
+The payload is `{ event, target, index }`:
+
+- `event` — the DOM event.
+- `target` — the ref element the handler matched, **not** `event.target`.
+- `index` — the position in the list, or `0` for a single ref.
+
+Events that do not bubble — `focus`, `blur`, `scroll`, `mouseenter`, `mouseleave` — are delegated from the **capture** phase, so they are heard all the same.
+
+In TypeScript, annotate the payload with `RefEvent`:
+
+```ts
+import { Base, type RefEvent } from '@studiometa/js-toolkit';
+
+class Todo extends Base {
+  static config = { name: 'Todo', refs: ['input'] };
+
+  onInputInput({ target }: RefEvent<HTMLInputElement>) {
+    console.log(target.value);
+  }
+}
+```
+
+## How the live read works
+
+Ref lookups are cached, and the cache is invalidated by a counter that the framework's own MutationObserver increases. Reading that counter drains the pending records with `takeRecords()`, so the read is current even inside the same task as the mutation. Detached elements are never cached.
+
+The practical consequence: you never refresh anything.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Todo extends Base {
+  static config = { name: 'Todo', refs: ['list', 'items[]'] };
+
+  add(title) {
+    const li = document.createElement('li');
+    li.dataset.ref = 'items[]';
+    li.textContent = title;
+    this.$refs.list.append(li);
+
+    // Already there. No `$update()`, no re-query.
+    console.log(this.$refs.items.length);
+  }
+}
+```

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).