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

package/skills/studiometa-js-toolkit/references/api/html/data-option.md

@@ -0,0 +1,106 @@
+# `data-option-<name>`
+
+Sets the value of one declared option.
+
+```html
+<div data-component="Slider" data-option-speed="2"></div>
+```
+
+The name is the option name in **kebab case**: `dragThreshold` is `data-option-drag-threshold`.
+
+## An option's name is inside its namespace
+
+Every declared option owns the attribute built for it, so `data-option-` is a namespace _family_ rather than a namespace. It is `data-option-columns:s`, never `data-option:columns:s`.
+
+That is what keeps the page-wide `attributeFilter` precise: the set of names is enumerable _because_ it comes from a declaration, so no option costs a second observer.
+
+## The five types
+
+| Declared  | `data-option-x="…"` | Reads as   |
+| --------- | ------------------- | ---------- |
+| `String`  | `"hello"`           | `'hello'`  |
+| `Number`  | `"2"`               | `2`        |
+| `Boolean` | presence only       | `true`     |
+| `Array`   | `"[1, 2]"`          | `[1, 2]`   |
+| `Object`  | `'{"a": 1}'`        | `{ a: 1 }` |
+
+A union is declared in order — `[Number, Array]` reads `"10"` as a number and `"[10, 20]"` as an array. Each parser must give a value of its declared type before the next runs.
+
+An absent attribute gives the declared default, or the empty value of the first declared type.
+
+## A boolean reads presence
+
+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 -->
+```
+
+A template must write the attribute conditionally rather than interpolate a boolean:
+
+```html
+{# Correct #}
+<div data-component="Panel" {% if isOpen %}data-option-open{% endif %}></div>
+```
+
+### `data-option-no-<name>` turns one off
+
+```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.
+- **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`, so no attribute an author writes means two things.
+
+The cost is paid by boolean options only: each adds its negated name, plus one scoped spelling per breakpoint, to the observer's filter.
+
+## Every option is responsive
+
+There is nothing to declare for it. **The suffix names one breakpoint and it cascades upwards:**
+
+```html
+<div
+  data-component="Grid"
+  data-option-columns="1"
+  data-option-columns:s="2"
+  data-option-columns:l="4"></div>
+```
+
+`$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 negated spelling is responsive too
+
+One cascade, from the active breakpoint down. At each level the value-carrying spelling is read first, then the negation, and the first hit wins — so a narrower breakpoint turns an option back **on**, and at one breakpoint an explicit value outranks a flag:
+
+```html
+<div data-component="Panel" data-option-no-x data-option-x:l="true"></div>
+```
+
+**A suffix must name a configured breakpoint**
+
+An unknown suffix gives one `responsive.unknown-breakpoint` warning per mount.
+
+## Writing one from code
+
+`$options` is read-only, so the way to change a value is to write the attribute — the same statement the markup makes:
+
+```js
+this.$el.setAttribute('data-option-speed', '4');
+this.$el.removeAttribute('data-option-disabled');
+flag ? el.setAttribute('data-option-open', '') : el.removeAttribute('data-option-open');
+```
+
+The next read gives the new value, and [`option<Name>Changed()`](../methods-hooks-options.md) announces it.
+
+Several writes in one batch give **one** change, from the value before the first write to the value at the end. A write that ends where it started is not a change.
+
+See [Options](../../guide/introduction/managing-options.md).

package/skills/studiometa-js-toolkit/references/api/html/data-ref.md

@@ -0,0 +1,63 @@
+# `data-ref`
+
+Marks an element as a named part of a component.
+
+```html
+<div data-component="Dialog">
+  <button data-ref="close">Close</button>
+</div>
+```
+
+The name must also be declared in [`config.refs`](../configuration.md#config-refs).
+
+## A single ref
+
+```html
+<button data-ref="close"></button>
+```
+
+`config.refs: ['close']` gives `$refs.close`, the **first** match.
+
+## A list
+
+**The `[]` is part of the attribute:**
+
+```html
+<button data-ref="tabs[]"></button>
+<button data-ref="tabs[]"></button>
+```
+
+`config.refs: ['tabs[]']` gives `$refs.tabs` as an array.
+
+A list declaration matches the suffixed attribute **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.
+
+## Naming the owner
+
+By default a ref belongs to the **nearest enclosing component**. The prefixed form crosses every boundary except another component of that name:
+
+```html
+<div data-component="Slider">
+  <div data-component="SliderItem">
+    <button data-ref="Slider.next">Slider's, from inside a child</button>
+  </div>
+</div>
+```
+
+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. The namespace goes **before** the suffix:
+
+| 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[]', …)` |
+
+## It is live
+
+`$refs` reads the DOM on access, so a `data-ref` element added later is found with no refresh, and a detached one never stays in a list. There is no `$update()`.
+
+`on<Ref><Event>` handlers are delegated from the component's root element, so a ref that appears later needs no new binding. Events that do not bubble — `focus`, `blur`, `scroll`, `mouseenter`, `mouseleave` — are delegated from the capture phase.
+
+See [Refs](../../guide/introduction/managing-refs.md).

package/skills/studiometa-js-toolkit/references/api/html/index.md

@@ -0,0 +1,32 @@
+# HTML
+
+Four attributes are the whole markup surface of the framework.
+
+| Attribute                                  | Declares                                         |
+| ------------------------------------------ | ------------------------------------------------ |
+| [`data-component`](data-component.md)  | which components this element runs               |
+| [`data-mount`](data-mount.md)          | when they mount                                  |
+| [`data-ref`](data-ref.md)              | that this element is a named part of a component |
+| [`data-option-<name>`](data-option.md) | the value of one declared option                 |
+
+Every one of them follows the same grammar:
+
+```
+data-<namespace>[:<qualifier>[.<part>…]]
+```
+
+**The colon selects one member of the vocabulary the namespace declares**, which is why an attribute the framework reads holds at most one colon. See [The attribute grammar](../../guide/concepts/attribute-grammar.md).
+
+## What is not an attribute
+
+- `data-load` — the mount and the import are one decision, so `data-mount` says it.
+- `<tk-name>` tag sugar and lowercase arbitrary-selector registrations — removed.
+- A breakpoint **list** suffix such as `:xxs:xs:s` — a suffix names one breakpoint and cascades.
+- A range form or a breakpoint-list form — neither exists.
+
+## Watching your own
+
+`attributeFilter` takes exact names and the DOM has no wildcard, so the engine cannot see an attribute the framework cannot name. Two opt-ins cover the rest:
+
+- [`watchAttributes()`](../dom/watchAttributes.md) — every attribute of one element.
+- [`watchAttributeNamespace()`](../dom/watchAttributeNamespace.md) — a namespace whose names cannot be enumerated, with keyed bindings.

package/skills/studiometa-js-toolkit/references/api/index.md

@@ -0,0 +1,73 @@
+# Base class
+
+Every component extends `Base`. It carries the element, the live views over its markup, the lifecycle, the event conventions and the scheduling handles — and nothing else. `Base` knows nothing about services, view transitions or storage.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Component extends Base {
+  static config = {
+    name: 'Component',
+  };
+}
+```
+
+## Sections
+
+- [Configuration](configuration.md) — `static config` and how it merges
+- [Lifecycle hooks](methods-hooks-lifecycle.md) — `mounted()` and `unmounted()`
+- [Options hooks](methods-hooks-options.md) — `option<Name>Changed()`
+- [Events hooks](methods-hooks-events.md) — `on<Event>`, `on<Ref><Event>`, `on<Child><Event>`, `onWindow<Event>`, `onDocument<Event>`
+- [Services hooks](methods-hooks-services.md) — `ticked()`, `scrolled()`, `resized()` and the rest
+- [Instance properties](instance-properties.md) — `$el`, `$id`, `$refs`, `$options`, `$config`, `$isMounted`
+- [Instance methods](instance-methods.md) — `$mount()`, `$emit()`, `$query()`, `$provide()`, `$read()` and the rest
+- [Instance events](instance-events.md) — what an instance dispatches
+
+## The constructor
+
+```ts
+new Base(el: HTMLElement)
+```
+
+**Do not call it.** The registry is the only code that constructs an instance, and an instance built by hand is not in the element's instance map, so nothing finds it and nothing unmounts it.
+
+A component's own constructor is a legitimate place for field initializers, and two registrations belong there because they are **instance-scoped** rather than unmount-scoped:
+
+```js
+import { Base, createContext } from '@studiometa/js-toolkit';
+
+const Ctx = createContext('ctx');
+class Slider extends Base {
+  static config = { name: 'Slider', components: {} };
+
+  // Never released. Both die with the element.
+  api = this.$provide(Ctx, { goNext: () => {} });
+  items = this.$watchChildren('SliderItem');
+}
+```
+
+## Fixed properties
+
+`$el`, `$id`, `$options` and `$refs` are **fixed properties of the instance**, not fields it happens to hold. They are defined non-writable in the constructor, so an assignment throws in a module rather than replacing what every other part of the framework reads.
+
+`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.
+
+## The typed surface
+
+`Base` takes an optional props type with four optional keys — `$el`, `$refs`, `$options` and `$emits`. See [TypeScript](../guide/going-further/typing-components.md).
+
+```ts
+import { Base } from '@studiometa/js-toolkit';
+
+class Slider extends Base<{
+  $refs: { next: HTMLButtonElement };
+  $options: { speed: number };
+  $emits: { goto: { index: number }; stop: void };
+}> {
+  static config = {
+    name: 'Slider',
+    refs: ['next'],
+    options: { speed: { type: Number, default: 1 } },
+  };
+}
+```

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

@@ -0,0 +1,75 @@
+# Instance events
+
+Everything an instance dispatches is a real DOM event, so a plain `addEventListener` hears all of it.
+
+## Component events
+
+`$emit(name, payload?)` dispatches on `$el`:
+
+| Property     | Value                         |
+| ------------ | ----------------------------- |
+| `bubbles`    | `true`                        |
+| `cancelable` | `true`                        |
+| `detail`     | the payload object, or `null` |
+
+Names are typed lower-kebab string literals declared through the props type's `$emits` key. There is no namespace: a component event is `open`, not `js-toolkit:open`.
+
+```js
+el.addEventListener('goto', (event) => {
+  console.log(event.detail.index);
+});
+```
+
+## Lifecycle announcements
+
+Every instance announces its own mount and unmount, carrying itself in the payload:
+
+```ts
+interface LifecycleEventDetail {
+  instance: Base;
+}
+```
+
+| Event                            | Constant                     | Dispatched from           |
+| -------------------------------- | ---------------------------- | ------------------------- |
+| `js-toolkit:component:mounted`   | `EVENTS.component.mounted`   | the element — **bubbles** |
+| `js-toolkit:component:unmounted` | `EVENTS.component.unmounted` | `document`                |
+
+```ts
+import { EVENTS, type LifecycleEventDetail } from '@studiometa/js-toolkit';
+
+document.addEventListener(EVENTS.component.mounted, (rawEvent) => {
+  const event = rawEvent as CustomEvent<LifecycleEventDetail>;
+  console.log(`${event.detail.instance.$id} mounted`);
+});
+```
+
+The unmount event dispatches from `document` because the element can already be detached. That is also what lets one lazy, realm-shared listener serve every [`$watchChildren()`](instance-methods.md#watchchildren) watcher while the document holds nothing but weak references to them — a listener per watcher would make every watching component immortal.
+
+**An instance that is scheduled but not mounted announces nothing.**
+
+## Diagnostics
+
+`js-toolkit:diagnostic` — `EVENTS.diagnostic` — starts on the relevant connected element, or on `document` when there is none, with `{ bubbles: true, composed: true, cancelable: true }`.
+
+`preventDefault()` suppresses the default console output only. See [Diagnostics](diagnostics/index.md).
+
+## Negotiated events
+
+`js-toolkit:dom:update` — `EVENTS.dom.update` — is dispatched by [`domUpdate()`](dom/domUpdate.md), and [`emitExtendable()`](dom/emitExtendable.md) dispatches the name its caller gives.
+
+Both are bubbling and **non-cancelable**: the step is announced, not proposed. Their detail carries a `wrap()` or a `waitUntil()` valid only while the event dispatches.
+
+They have **no `Base` path** and are absent from `$emits`, so the negotiation code and the optional view-transition import stay out of the `Base` graph. Plain DOM code uses the same functions with no instance.
+
+## Private transports
+
+The context request is a bubbling, **module-private** event and is deliberately not part of public `EVENTS`. Framework internals that need a transport use module-local namespaced constants; only what a consumer can usefully listen to is exported.
+
+## The convention, in full
+
+- Public framework events use the deeply frozen `EVENTS` object and the `js-toolkit:` namespace.
+- Private framework transports use module-local constants and do not join `EVENTS`.
+- Component events use typed lower-kebab string literals from `$emits`.
+- A payload is **one object** in `CustomEvent.detail`, or the platform value `null`.
+- Diagnostic events are cancelable, so monitoring can suppress the default output only.

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

@@ -0,0 +1,267 @@
+# Instance methods
+
+## `$mount()`
+
+```ts
+$mount(): this
+```
+
+Starts a mount cycle. On a page the registry calls it; calling it yourself is legitimate but nearly always a sign that a [mount strategy](../guide/going-further/mount-strategies.md) is the answer instead.
+
+## `$unmount()`
+
+```ts
+$unmount(): this
+```
+
+The reversible opposite of mount. It unbinds the cycle's listeners, runs the `mounted()` cleanups, cancels the instance's scheduled tasks, calls `unmounted()` and announces the change.
+
+**The instance stays on its element**, so `$mount()` can start a new cycle with the same identity.
+
+## `$emit()` {#emit}
+
+```ts
+$emit<K extends EmitName<T>>(event: K, ...payload: EmitArgs<T, K>): CustomEvent<EmitDetail<T, K>>
+```
+
+Dispatches a bubbling, cancelable `CustomEvent` on `$el`, with the payload as `detail`.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Dialog extends Base {
+  static config = { name: 'Dialog' };
+
+  close() {
+    const event = this.$emit('close');
+    if (event.defaultPrevented) return;
+    this.$el.removeAttribute('data-option-open');
+  }
+
+  goto(index) {
+    this.$emit('goto', { index });
+  }
+}
+```
+
+- The payload is **one object**, or nothing. An omitted payload leaves `detail` at the platform value `null`.
+- A value that is not an object is refused by the type and reported as `event.invalid-emit-payload`. The event still dispatches.
+- Nothing in the framework is gated on cancellation.
+
+Declare the names and payloads through the props type's `$emits` key. See [Events](../guide/introduction/working-with-events.md).
+
+## `$on()` {#on}
+
+```ts
+$on(type: string, listener: EventListener, options?: AddEventListenerOptions): () => void
+```
+
+Adds a listener on `$el` and **returns its own remover**, which makes it a `mounted()` cleanup as it is:
+
+```js
+mounted() {
+  return this.$on('transitionend', this.handleEnd, { once: true });
+}
+```
+
+Reach for it when the event name is data rather than a method name, or when you need listener options.
+
+## `$off()`
+
+```ts
+$off(type: string, listener: EventListener, options?: AddEventListenerOptions): void
+```
+
+## `$query()` {#query}
+
+```ts
+$query<T extends Base = Base>(name: string): T[]
+```
+
+Every **mounted** instance of `name` among the descendants of `$el`, in document order. A flat array at any depth, not a keyed object.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Slider extends Base {
+  static config = { name: 'Slider' };
+
+  reset() {
+    for (const item of this.$query('SliderItem')) {
+      item.$el.removeAttribute('data-option-active');
+    }
+  }
+}
+```
+
+For a collection kept over time rather than queried each time, prefer [`$watchChildren()`](#watchchildren).
+
+## `$closest()` {#closest}
+
+```ts
+$closest<T extends Base = Base>(name: string): T | null
+```
+
+The nearest ancestor instance of `name`, or `null`.
+
+**Always guard it**
+
+It is resolved on every access and returns `null` when no matching ancestor instance has been constructed. Whether an ancestor is resolvable from a child's own `mounted()` depends on mount order, so never dereference it unguarded there.
+
+```js
+this.$closest('Slider')?.goNext();
+```
+
+A child that reaches for its parent is usually a child that should `$emit()` instead.
+
+## `$watchChildren()` {#watchchildren}
+
+```ts
+$watchChildren<T extends Base>(name: string, callbacks?: WatchChildrenCallbacks<T>): ChildrenCollection<T>
+$watchChildren<T extends BaseConstructor>(ComponentClass: T, callbacks?: WatchChildrenCallbacks<InstanceType<T>>): ChildrenCollection<InstanceType<T>>
+```
+
+A **live collection** of descendant instances, in document order whatever the mount order is.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class SliderItem extends Base {
+  static config = { name: 'SliderItem' };
+}
+
+class Slider extends Base {
+  static config = { name: 'Slider', components: { SliderItem } };
+
+  // Exact `config.name`.
+  items = this.$watchChildren('SliderItem', {
+    added(item) {},
+    removed(item) {},
+  });
+
+  // Also every named subclass, through `instanceof`.
+  allItems = this.$watchChildren(SliderItem);
+}
+```
+
+```ts
+interface ChildrenCollection<T extends Base = Base> extends Iterable<T> {
+  readonly size: number;
+  readonly items: T[];
+}
+```
+
+- **The string overload** looks up the exact `config.name`.
+- **The constructor overload** walks the descendant elements in document order, reads their instance maps, keeps the instances where `instance instanceof ComponentClass`, excludes the watching instance, and removes duplicates.
+- Callbacks passed to the decorator form are bound to the instance.
+
+**It is instance-scoped, not unmount-scoped**
+
+The subscription stays active through unmount and mount cycles, for the whole life of the watching instance, which is why the call belongs in a field initializer. It is never released and dies with the element.
+
+The initial sweep is deferred to a microtask, because the call is usually a field initializer; the announcement listeners attach at once, so nothing is missed. No global instance registry is added — unmounted instances announce from `document`, so one lazy, realm-shared listener serves every watcher and the document holds nothing but weak references.
+
+## `$provide()`
+
+```ts
+$provide<V>(key: ContextKey<V>, value: V): V
+```
+
+Provides a value to the subtree and returns it, so the call is a field initializer. **The value is provided as it is** — nothing is wrapped.
+
+```js
+import { Base, createContext, signal } from '@studiometa/js-toolkit';
+
+const SliderContext = createContext('slider');
+class Slider extends Base {
+  static config = { name: 'Slider' };
+
+  api = this.$provide(SliderContext, {
+    state: signal({ index: 0 }),
+    goNext: () => {},
+  });
+}
+```
+
+Instance-scoped: never released, and it dies with the element. A component whose declaration is withdrawn keeps providing until its element goes.
+
+## `$inject()`
+
+```ts
+$inject<V>(key: ContextKey<V>): Promise<V>
+```
+
+Resolves with the nearest provided value. **When nothing provides, it never settles** — a missing provider means "not yet", not "no".
+
+```js
+async mounted() {
+  const api = await this.$inject(SliderContext);
+  return api.state.subscribe((state) => this.render(state));
+}
+```
+
+The pending request is **unmount-scoped**: `$unmount()` cancels it, and a new mount runs `mounted()` again and asks again.
+
+## `$injectSync()`
+
+```ts
+$injectSync<V>(key: ContextKey<V>): V | undefined
+```
+
+The value, synchronously, or `undefined`. For the case where the answer is optional and the caller has a fallback.
+
+## `$read()` and `$write()`
+
+```ts
+$read<T>(fn: () => T): ScheduledTask<T>
+$write<T>(fn: () => T): ScheduledTask<T>
+```
+
+Schedules a layout read or a DOM write in the frame's matching phase, tied to this instance. `$unmount()` cancels the pending ones.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Reveal extends Base {
+  static config = { name: 'Reveal' };
+
+  async mounted() {
+    const box = await this.$read(() => this.$el.getBoundingClientRect()).promise;
+    this.$write(() => {
+      this.$el.style.setProperty('--height', `${box?.height}px`);
+    });
+  }
+}
+```
+
+```ts
+interface ScheduledTask<T = unknown> {
+  promise: Promise<T | undefined>;
+  cancel(): void;
+}
+```
+
+Every read runs before every write, once, before paint. A `read` scheduled from a `write` runs in the next frame; a `write` scheduled from a `read` runs in the same frame. See [The scheduler](../guide/going-further/scheduling-work.md).
+
+## `$warn()` and `$error()`
+
+```ts
+$warn(code: ToolkitDiagnosticCode, message: string): void
+$error(code: ToolkitDiagnosticCode, message: string, error: unknown): void
+```
+
+Report on the [diagnostic channel](../guide/going-further/handling-diagnostics.md) with this component's name filled in.
+
+```js
+this.$warn('carousel.no-slides', 'A Carousel with no slide does nothing.');
+```
+
+## What does not exist
+
+| Not in v4      | Use instead                              |
+| -------------- | ---------------------------------------- |
+| `$parent`      | `$closest(name)`                         |
+| `$children`    | `$watchChildren(name)` or `$query(name)` |
+| `$root`        | `$closest(name)` with the real name      |
+| `$update()`    | nothing — refs are live                  |
+| `$terminate()` | nothing — there is no permanent state    |