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

package/skills/studiometa-js-toolkit/references/api/instance-properties.md

@@ -0,0 +1,90 @@
+# Instance properties
+
+## `$el`
+
+```ts
+readonly $el: HTMLElement
+```
+
+The element the instance is bound to. Typed by the props type's `$el` key.
+
+## `$id` {#id}
+
+```ts
+readonly $id: string
+```
+
+`<ComponentName>-<sequence>`, where the name comes from the resolved config and the sequence increases once for each constructed instance.
+
+The id exists **before the field initializers of derived classes run**, and it does not change through unmount and mount cycles. Core never copies it to a DOM `id`.
+
+```js
+// 'Slider-3'
+```
+
+## `$refs`
+
+```ts
+readonly $refs: Refs<T>
+```
+
+A live view over the declared refs. **Each property reads the DOM on access**, so markup put into the component is found with no refresh and no detached element stays in a list. There is no `$update()`.
+
+A single declaration gives the first match; a `name[]` declaration gives an array. The property name never carries the suffix.
+
+Lookups are cached, and the cache is invalidated by a counter the framework's MutationObserver increases; reading that counter drains the pending records with `takeRecords()`. Detached elements are never cached.
+
+See [Refs](../guide/introduction/managing-refs.md).
+
+## `$options`
+
+```ts
+readonly $options: Readonly<Options<T>>
+```
+
+A **read-only view** over the declared options. Every property is defined with a getter and no setter, so the value is derived from the element and the viewport on each access, and an assignment throws:
+
+```js
+this.$options.open = true;
+// TypeError: Cannot set property open of #<Object> which has only a getter
+```
+
+Every option is responsive, resolved by walking from the active breakpoint down to the base value.
+
+The one exception to "nothing is stored": a **default** built by a factory lives on the instance, so mutating it sticks for that instance. Replacing the option itself still throws.
+
+See [Options](../guide/introduction/managing-options.md).
+
+## `$config`
+
+```ts
+get $config(): BaseConfig
+```
+
+The merged config, walked along the prototype chain. `refs`, `options` and `components` merge; scalar keys are the most derived class's.
+
+See [Configuration](configuration.md).
+
+## `$isMounted`
+
+```ts
+get $isMounted(): boolean
+```
+
+`true` between `mounted()` and the next `$unmount()`.
+
+There is deliberately no `getMountedInstance()`: a caller holding one instance reads this instead.
+
+## `$services`
+
+```ts
+readonly $services: { readonly [K in Hook]: Toggle }
+```
+
+Present only on a class built with a [service mixin](methods-hooks-services.md). One [`Toggle`](services/toggle.md) per bound hook, which is what `{ manual: true }` is for. Stacked mixins accumulate their keys.
+
+## Fixed, not fields
+
+`$el`, `$id`, `$options` and `$refs` are **fixed properties**, defined non-writable in the constructor. An assignment throws in a module rather than replacing what every other part of the framework reads: the element, the id, and the two live views.
+
+`readonly` states it for a reader with a build step; the property descriptor states it for everyone else. They stay enumerable, so an instance still reads as one in a console or a `JSON.stringify`.

package/skills/studiometa-js-toolkit/references/api/methods-hooks-events.md

@@ -0,0 +1,149 @@
+# Events hooks
+
+Five naming conventions bind a method to an event source. All five are bound for the **mount cycle** and removed by `$unmount()`.
+
+| 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 }`          |
+
+## Resolution order
+
+`onWindow` and `onDocument` are **reserved prefixes** and match first. After them a name is resolved **children-first**, then 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 on one component; a click on the element fires both.
+
+## `on<Event>`
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Toggle extends Base {
+  static config = { name: 'Toggle' };
+
+  onClick(event) {
+    event.preventDefault();
+  }
+}
+```
+
+The event name is the method name after `on`, in lower case: `onPointerDown` is `pointerdown`.
+
+## `on<Ref><Event>`
+
+```ts
+import { Base, type RefEvent } from '@studiometa/js-toolkit';
+
+class Tabs extends Base {
+  static config = { name: 'Tabs', refs: ['tabs[]'] };
+
+  onTabsClick({ event, target, index }: RefEvent<HTMLButtonElement>) {
+    console.log(index, target.textContent);
+  }
+}
+```
+
+```ts
+interface RefEvent<T extends HTMLElement = HTMLElement> {
+  event: Event;
+  target: T;
+  index: number;
+}
+```
+
+`target` is the **ref element** the handler matched, not `event.target`. `index` is the position in a list ref, or `0` for a single ref.
+
+The ref is named as it is **declared**: `onTabsClick` for `config.refs: ['tabs[]']`.
+
+## `on<Child><Event>`
+
+```ts
+import { Base, type DelegatedEvent } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base<{ $emits: { open: { height: number } } }> {
+  static config = { name: 'AccordionItem' };
+}
+
+class Accordion extends Base {
+  static config = { name: 'Accordion', components: { AccordionItem } };
+
+  onAccordionItemOpen({ event, target, payload }: DelegatedEvent<AccordionItem, 'open'>) {
+    console.log(target.$id, payload.height);
+  }
+}
+```
+
+```ts
+interface DelegatedEvent<T extends Base = Base, K extends string = string> {
+  event: Event;
+  target: T;
+  payload: EmitDetail<PropsOf<T>, K>;
+}
+```
+
+`target` is the child **instance**. `payload` is `event.detail`, typed from the child's `$emits`.
+
+**`config.components` is what disambiguates the name**
+
+`onSliderDragStart` is `SliderDrag` + `start`, or `Slider` + `drag-start`. The name set from `config.components` decides. A child that is not declared there is not resolved.
+
+A lazy child works the same way, because the key is the name and nothing has to be downloaded to resolve a handler.
+
+## `onWindow<Event>` and `onDocument<Event>`
+
+```ts
+import { Base, type GlobalEvent } from '@studiometa/js-toolkit';
+
+class ClickOutside extends Base {
+  static config = { name: 'ClickOutside' };
+
+  onDocumentClick({ event }: GlobalEvent<MouseEvent>) {
+    if (!event.composedPath().includes(this.$el)) {
+      this.$el.removeAttribute('data-option-open');
+    }
+  }
+}
+```
+
+```ts
+interface GlobalEvent<T extends Event = Event> {
+  event: T;
+  target: Window | Document;
+}
+```
+
+- **Phase: bubble, always.** `onDocumentClick` hears what `document.addEventListener('click', …)` hears. To hear a descendant's non-bubbling event, use `on<Ref><Event>`.
+- `target` is the global the handler names. There is no `payload` and no `index`.
+- Listener options such as `once` and `passive` are not part of this. Use [`$on()`](instance-methods.md#on) for those.
+
+## Delegation
+
+Ref and child handlers are delegated from `this.$el`:
+
+- **One listener per event type** on the 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 ref or a child inserted later needs **no new binding**.
+- Events that do not bubble — `focus`, `blur`, `scroll`, `mouseenter`, `mouseleave` — are delegated from the **capture** phase.
+
+## Typing
+
+A method named by convention is **not typed by convention**: the name is resolved at runtime, so annotate the payload with `RefEvent`, `DelegatedEvent` or `GlobalEvent`.
+
+The [`@on` decorator](decorators/on.md) checks that annotation against a real target instead of leaving it unverified.
+
+## Dynamic sets of events
+
+A handler name belongs to the class. When the set of events is **data** — one subscription per markup declaration, with its own modifiers — bind it yourself and own the cleanup:
+
+```js
+mounted() {
+  return this.$options.events.map((type) => this.$on(type, this.handle));
+}
+```
+
+That is the intended path, not a workaround.

package/skills/studiometa-js-toolkit/references/api/methods-hooks-lifecycle.md

@@ -0,0 +1,90 @@
+# Lifecycle hooks
+
+```ts
+mounted(): MountedReturn
+unmounted(): void
+```
+
+```ts
+type MountedReturn = void | (() => void) | MountedReturn[] | Promise<MountedReturn>;
+```
+
+Both are meant to be overridden and neither needs a `super` call.
+
+## `mounted()`
+
+Runs when the element is in the document and the component's mount conditions are met. It runs **after** every `option<Name>Changed()` hook of the same cycle.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Player extends Base {
+  static config = { name: 'Player' };
+
+  mounted() {
+    this.$el.setAttribute('aria-live', 'polite');
+  }
+}
+```
+
+### It returns its cleanup
+
+A function, an array of functions, sync or async. They run on the next `$unmount()`:
+
+```js
+import { Base, useScroll } from '@studiometa/js-toolkit';
+
+class Header extends Base {
+  static config = { name: 'Header' };
+
+  mounted() {
+    return useScroll().subscribe(({ directionY }) => {
+      this.$el.classList.toggle('is-hidden', directionY > 0);
+    });
+  }
+}
+```
+
+If an async `mounted()` resolves **after** the unmount, the cleanup runs immediately.
+
+## `unmounted()`
+
+Runs at the end of `$unmount()`, after the cycle's listeners are unbound, the `mounted()` cleanups have run and the scheduled tasks are cancelled.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Player extends Base {
+  static config = { name: 'Player' };
+
+  unmounted() {
+    this.$el.removeAttribute('aria-live');
+  }
+}
+```
+
+It stays available for the cases the returned cleanup does not fit. When both exist, the returned cleanup runs first.
+
+## What triggers each
+
+| Cause                                       | Calls                                         |
+| ------------------------------------------- | --------------------------------------------- |
+| the element enters the document             | `mounted()`                                   |
+| a mount strategy's condition becomes true   | `mounted()`                                   |
+| the element leaves the document             | `unmounted()`                                 |
+| the component token leaves `data-component` | `unmounted()`, then the instance is dropped   |
+| a breakpoint withdraws the declaration      | `unmounted()`, then the instance is dropped   |
+| a reversible strategy's condition ends      | `unmounted()`                                 |
+| the node is **moved**                       | `unmounted()` then `mounted()`, same identity |
+
+**Unmounting a parent does not unmount its children.**
+
+## What is not a lifecycle hook
+
+- **`updated()` does not exist.** For an option that chooses a resource, use [`option<Name>Changed()`](methods-hooks-options.md). For an attribute the framework does not read, use [`watchAttributes()`](dom/watchAttributes.md).
+- **There is no permanent state.** A component never declares that its work is over. "Once per element" is a plain field — see [Lifecycle](../guide/introduction/lifecycle-hooks.md#do-this-once-per-element).
+- **A service mixin never occupies either hook.** It overrides `$mount()`/`$unmount()`, so a class that writes its own `mounted()` without `super.mounted()` still subscribes.
+
+## Failures
+
+A hook that throws is reported once as `component.lifecycle-failed` and the cycle continues. It does not stop the other instances in the same batch.

package/skills/studiometa-js-toolkit/references/api/methods-hooks-options.md

@@ -0,0 +1,96 @@
+# Options hooks
+
+```ts
+option<Name>Changed(change: OptionChange): OptionChangedReturn
+```
+
+A declared method named after an option makes that option a **live effect**. A component without the convention pays no setup cost and reads its options directly.
+
+## Usage
+
+```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 cleanup for *this* value.
+    return () => connection.dispose();
+  }
+}
+```
+
+The method name is the option name in pascal case: `dragThreshold` is `optionDragThresholdChanged`.
+
+## The payload
+
+```ts
+interface OptionChange<T = unknown> {
+  name: string;
+  value: T;
+  previousValue: T | undefined;
+  rawValue: string | null;
+  previousRawValue: string | null;
+  initial: boolean;
+}
+```
+
+| Field              | Meaning                                               |
+| ------------------ | ----------------------------------------------------- |
+| `name`             | the option name                                       |
+| `value`            | the parsed value now                                  |
+| `previousValue`    | the parsed value before, `undefined` on the first run |
+| `rawValue`         | the raw attribute string, `null` when absent          |
+| `previousRawValue` | the raw string before, `null` when it was absent      |
+| `initial`          | `true` on the first run of a mount cycle              |
+
+```ts
+import { Base, type OptionChange } from '@studiometa/js-toolkit';
+
+class Feed extends Base {
+  static config = { name: 'Feed', options: { source: String } };
+
+  optionSourceChanged({ value, previousValue, initial }: OptionChange<string>) {
+    console.log(value, previousValue, initial);
+  }
+}
+```
+
+## The return value
+
+```ts
+type OptionChangedReturn = void | (() => void);
+```
+
+Return a function to release what this value acquired. The previous cleanup runs **before** an update, and every active cleanup runs on `$unmount()`.
+
+## When it runs
+
+- **Before `mounted()`**, on each mount cycle, with `initial: true`.
+- On an attribute change, once the batch is processed.
+- On a **breakpoint crossing** that changes the resolved raw value.
+- Removal of the attribute applies the declared default, which is a change like any other.
+- A new mount starts each effect again with `initial: true`.
+
+## Coalescing
+
+Several writes to one attribute in one 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 comparison uses raw strings, so a breakpoint crossing and an attribute write are the same kind of event. A crossing to the same resolved value announces nothing, and a write to `data-option-columns:s` while the viewport is at `l` announces nothing.
+
+## What it costs
+
+**A `matchMedia` subscription opens only for a component that declares one of these hooks.** `$unmount()` releases it. A page that only reads options holds no listener at all.
+
+## Not for arbitrary attributes
+
+This hook is for **declared options**. For an attribute the framework does not read, use [`watchAttributes()`](dom/watchAttributes.md), which shares the same coalescing rule and the same batch.

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

@@ -0,0 +1,164 @@
+# Services hooks
+
+A service mixin binds one subscription per mount cycle, under the **one method name the service owns**. There is no `hook` option.
+
+| Mixin                | Hook             | Props type            |
+| -------------------- | ---------------- | --------------------- |
+| `withRaf`            | `ticked`         | `RafProps`            |
+| `withScroll`         | `scrolled`       | `ScrollProps`         |
+| `withResize`         | `resized`        | `ResizeProps`         |
+| `withPointer`        | `moved`          | `PointerProps`        |
+| `withDrag`           | `dragged`        | `DragProps`           |
+| `withKey`            | `keyed`          | `KeyProps`            |
+| `withInView`         | `intersected`    | `InViewProps`         |
+| `withMutation`       | `mutated`        | `MutationProps`       |
+| `withScrollProgress` | `scrolledInView` | `ScrollProgressProps` |
+
+## Usage
+
+```js
+import { Base, withScroll } from '@studiometa/js-toolkit';
+
+class Header extends withScroll(Base) {
+  static config = { name: 'Header' };
+
+  scrolled({ y, directionY, isScrolling }) {
+    this.$el.classList.toggle('is-hidden', directionY > 0 && y > 100);
+  }
+}
+```
+
+Mixins stack, and their `$services` keys accumulate:
+
+```js
+import { Base, withRaf, withResize } from '@studiometa/js-toolkit';
+
+class Parallax extends withRaf(withResize(Base)) {
+  static config = { name: 'Parallax' };
+
+  #height = 0;
+
+  resized({ height }) {
+    this.#height = height;
+  }
+
+  ticked({ delta }) {
+    // …
+  }
+}
+```
+
+## A mixin never occupies a lifecycle hook
+
+`mounted()` and `unmounted()` belong to the component author, so **nothing has to be chained**. A class that mixes a service in and writes its own `mounted()` without `super.mounted()` still subscribes: the framework's own `$mount()`/`$unmount()` pair carries the subscription.
+
+The consequences are worth knowing:
+
+- The subscription starts **once the whole of `mounted()` has run** — including an `immediate` first delivery, which therefore reaches a component that is fully set up.
+- It is released **before `unmounted()`**, exactly where the mount cleanup used to release it.
+- `$unmount()` releases unconditionally, so a manual subscription started outside a mount cycle is released too.
+
+**A userland mixin still chains**
+
+The rule is about what the mixin **overrides**, not about who wrote it. A mixin that puts its work in `mounted()` needs its subclasses to call `super.mounted()` — and the way not to need that is to override `$mount()`.
+
+## Mixin options
+
+```ts
+interface ServiceMixinOptions<Target, Host = Base> {
+  target?: (instance: Host) => Target;
+  manual?: boolean;
+  immediate?: boolean;
+}
+```
+
+**The options of a mixin are not the options of the service.** `target`, `manual` and `immediate` describe the subscription. They are removed before the underlying `use*()` call and they are absent from its options type.
+
+A service's own options are passed in the same object and forwarded:
+
+```js
+class Slide extends withDrag(Base, { axis: 'x', inertia: false, immediate: true }) {}
+```
+
+### `target`
+
+```js
+withResize(Base, { target: (instance) => instance.$refs.inner });
+```
+
+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.
+
+A service whose **own** default target is nothing, like `withRaf`, is untouched.
+
+**The resolver is typed against the host as declared**
+
+A mixin is applied while the extends clause of its class is still being evaluated, so `withDrag(Base, …)` types its resolver against `Base`. A component reaching further names the shape it needs — `(instance as Base & { readonly target: HTMLElement }).target` — which is an assertion rather than a check. That is why core checks the result at runtime.
+
+### `manual`
+
+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 }) {}
+
+  onSelected() {
+    this.$services.ticked.start();
+  }
+
+  onSettled() {
+    this.$services.ticked.stop();
+  }
+}
+```
+
+`$services` is declared in the type as `ServiceHandles<'ticked'>`, so the key completes and a wrong name is a type error. Each handle is a [`Toggle`](services/toggle.md).
+
+### `immediate`
+
+Asks for the first delivery at subscribe time. The sources with a current value honour it; the ones without do nothing. `withInView` defaults it to `true`.
+
+## `ticked` can return a render function
+
+`withRaf` is the one hook whose return value is used: return a function and it runs in the `write` phase of the same frame.
+
+```js
+import { Base, withRaf } from '@studiometa/js-toolkit';
+
+class Follower extends withRaf(Base) {
+  static config = { name: 'Follower' };
+
+  ticked({ delta }) {
+    const x = this.measure(delta);
+    return () => {
+      this.$el.style.transform = `translateX(${x}px)`;
+    };
+  }
+
+  measure(delta) {
+    return delta;
+  }
+}
+```
+
+The raf service collects the render functions of its callbacks and cancels a render whose subscriber left between the two phases.
+
+## One hook per class, and that is the limit
+
+A mixin binds one subscription, under one name, for each mount cycle. A component whose subscriptions are **one per markup declaration** — one per attribute, 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:
+
+```js
+mounted() {
+  return useScroll(this.$refs.panel).subscribe((props) => {});
+}
+```
+
+`on<Event>` has the same shape: a handler name belongs to the class, while a set of events can be data. Neither limit is about a build step — `withRaf(Base)` is an ordinary call, and the name is fixed by how the class is written.
+
+## Failures
+
+A subscriber that throws is skipped and reported as `callback.service-failed`. Core dispatches the diagnostic first and calls `reportError()` only when no listener cancelled the event.

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

@@ -0,0 +1,57 @@
+# defineManifest
+
+```ts
+defineManifest({ modules, mountStrategy }: DefineManifestOptions): ComponentManifest
+```
+
+Turns a map of module paths into a [manifest](registerManifest.md), deriving each `data-component` token from its path.
+
+## Usage
+
+```js
+import { defineManifest, fromMetaGlob, registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  }),
+);
+```
+
+**Parameters**
+
+- `modules` (`ModuleRecord`) — a map of path to importer, from [`fromMetaGlob()`](fromMetaGlob.md), [`fromWebpackContext()`](fromWebpackContext.md), or written by hand.
+- `mountStrategy` (`MountStrategy`, optional) — a package-wide default.
+
+**Return value**
+
+- `ComponentManifest`, ready for `registerManifest()`.
+
+## Token derivation
+
+The token is the file's base name, and **`index` falls back to the parent directory**:
+
+| Path                           | Token    |
+| ------------------------------ | -------- |
+| `./components/Slider.js`       | `Slider` |
+| `./components/Slider/index.js` | `Slider` |
+| `./components/nav/Menu.js`     | `Menu`   |
+
+Duplicate tokens give a warning and **keep the first path**.
+
+## The package-wide strategy
+
+```js
+defineManifest({
+  modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  mountStrategy: 'visible',
+});
+```
+
+Entry wrappers are emitted **only when the strategy is not `eager`**, so the default costs nothing in the output.
+
+Any element still overrides it with `data-mount`, and a class's own `config.mountStrategy` takes over once it has loaded.
+
+## What it is not
+
+It carries the importer and the strategy, and nothing else. Informational metadata — `packageName`, `subpath`, `exportName`, `group`, `styles`, `integrations` — belongs in the output type of a generator, not in core.

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

@@ -0,0 +1,33 @@
+# fromMetaGlob
+
+```ts
+fromMetaGlob(glob: Record<string, unknown>): ModuleRecord
+```
+
+Adapts a Vite `import.meta.glob()` result for [`defineManifest()`](defineManifest.md).
+
+## Usage
+
+```js
+import { defineManifest, fromMetaGlob, registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest(
+  defineManifest({
+    modules: fromMetaGlob(import.meta.glob('./components/*/index.js')),
+  }),
+);
+```
+
+**Parameters**
+
+- `glob` — the object `import.meta.glob()` returns, mapping each path to a lazy importer.
+
+**Return value**
+
+- `ModuleRecord` — a map of path to importer.
+
+**Use the lazy form**
+
+`import.meta.glob(pattern)` is lazy and gives one importer per path, which is the point. `import.meta.glob(pattern, { eager: true })` downloads everything up front, so a manifest built from it defers nothing — and the adapter **throws a `TypeError`** naming the first path that is not an importer function, rather than building a manifest that silently does nothing lazily.
+
+The adapter adds **no bundler dependency**. It reads a plain object of functions, and core names Vite nowhere.