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

package/skills/studiometa-js-toolkit/references/api/decorators/provide.md

@@ -0,0 +1,77 @@
+# @provide
+
+```ts
+provide<T>(key: ContextKey<T>): ValueDecorator<T>
+```
+
+Field sugar over [`$provide()`](../instance-methods.md#provide).
+
+## Usage
+
+```ts
+import {
+  Base,
+  component,
+  createContext,
+  provide,
+  signal,
+  type Signal,
+} from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+@component({ name: 'Counter' })
+class Counter extends Base {
+  @provide(CountContext)
+  count = signal(0);
+
+  increment() {
+    this.count.value += 1;
+  }
+}
+```
+
+The field's value is provided to the subtree, **as it is**. Nothing is wrapped, so the type of the key is the contract from end to end.
+
+## It is instance-scoped
+
+Like `$provide()`, it is never released and dies with the element. A component whose declaration is withdrawn keeps providing until its element goes.
+
+## A plain field or an `accessor`
+
+```ts
+import {
+  Base,
+  component,
+  createContext,
+  provide,
+  signal,
+  type Signal,
+} from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+@component({ name: 'Counter' })
+class Counter extends Base {
+  @provide(CountContext) a = signal(0);
+  @provide(CountContext) accessor b = signal(0);
+}
+```
+
+## The function form
+
+```ts
+import { Base, createContext, signal, type Signal } from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+class Counter extends Base {
+  static config = { name: 'Counter' };
+
+  count = this.$provide(CountContext, signal(0));
+}
+```
+
+Identical behaviour, no build step — and `$provide()` returns the value, which is why the field initializer reads the same way.
+
+## See also
+
+- [`@inject`](inject.md) — the other half
+- [Shared state](../../guide/going-further/sharing-state.md)

package/skills/studiometa-js-toolkit/references/api/decorators/read-write.md

@@ -0,0 +1,93 @@
+# @read and @write
+
+```ts
+read: (value: VoidMethod, context: ClassMethodDecoratorContext) => VoidMethod;
+write: (value: VoidMethod, context: ClassMethodDecoratorContext) => VoidMethod;
+```
+
+Runs the method body in the frame's `read` or `write` phase, cancelled on unmount. They are sugar over [`$read()`](../instance-methods.md#read-and-write) and `$write()`.
+
+## Usage
+
+```ts
+import { Base, component, read, write } from '@studiometa/js-toolkit';
+
+@component({ name: 'Measure' })
+class Measure extends Base {
+  #height = 0;
+
+  @read
+  measure() {
+    this.#height = this.$el.scrollHeight;
+  }
+
+  @write
+  apply() {
+    this.$el.style.setProperty('--height', `${this.#height}px`);
+  }
+}
+```
+
+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.
+
+## They are leaf-method sugar: the phase belongs to the call site
+
+**Decorate a method nobody overrides**
+
+A phase decorator returns a wrapper around the method it decorates, and that wrapper is a property of **that class**. A subclass that overrides the method defines its own, undecorated, and `this.method()` resolves to it — so the base's scheduling disappears and the body runs in whatever phase the caller was in.
+
+A **template method** — a base that schedules work its subclasses implement — schedules at the call site instead:
+
+```js
+// in the base, where the call is
+state.subscribe((value) => this.$write(() => this.update(value)));
+```
+
+The alternative, dispatching a decorated method through something a subclass cannot replace, was refused: it would make a decorator's behaviour depend on inheritance depth, which nothing else in v4 does, to buy a convenience no consumer has asked for.
+
+## Stacking with `@on`
+
+The skip is keyed by the method name, so the two stack in either order — and **the order decides what the listener calls**:
+
+| Written                   | Schedules               |
+| ------------------------- | ----------------------- |
+| `@on(...)` above `@write` | the body of the handler |
+| `@write` above `@on(...)` | direct calls only       |
+
+```ts
+import { Base, component, on, write } from '@studiometa/js-toolkit';
+@component({ name: 'Demo' })
+class Demo extends Base {
+  @on('click')
+  @write
+  paint() {}
+}
+```
+
+**Write `@read` and `@write` closest to the method body.**
+
+## The function form
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Measure extends Base {
+  static config = { name: 'Measure' };
+
+  #height = 0;
+
+  measure() {
+    return this.$read(() => {
+      this.#height = this.$el.scrollHeight;
+    });
+  }
+
+  apply() {
+    return this.$write(() => {
+      this.$el.style.setProperty('--height', `${this.#height}px`);
+    });
+  }
+}
+```
+
+The function form also gives you the [`ScheduledTask`](../scheduler/defaultScheduler.md) handle — its promise and its `cancel()` — which the decorator discards.

package/skills/studiometa-js-toolkit/references/api/diagnostics/DIAGNOSTICS.md

@@ -0,0 +1,137 @@
+# DIAGNOSTICS
+
+A deeply frozen object of every code the framework reports. `ToolkitDiagnosticCode` is the exact union of its strings, plus any `'<namespace>.<name>'` a consumer reports.
+
+```js
+import { DIAGNOSTICS } from '@studiometa/js-toolkit';
+
+DIAGNOSTICS.component.loadFailed; // 'component.load-failed'
+DIAGNOSTICS.responsive.unknownBreakpoint; // 'responsive.unknown-breakpoint'
+```
+
+## `attribute`
+
+| Key                | Code                          | Reported when                                                               |
+| ------------------ | ----------------------------- | --------------------------------------------------------------------------- |
+| `unknownQualifier` | `attribute.unknown-qualifier` | a watched namespace with a finite vocabulary gets an unknown qualifier head |
+
+## `callback`
+
+Every one of these is **reported and continued**: the failing callback is skipped, the others run.
+
+| Key                              | Code                                         |
+| -------------------------------- | -------------------------------------------- |
+| `signalFailed`                   | `callback.signal-failed`                     |
+| `contextSubscriptionFailed`      | `callback.context-subscription-failed`       |
+| `contextTeardownFailed`          | `callback.context-teardown-failed`           |
+| `attributeWatcherFailed`         | `callback.attribute-watcher-failed`          |
+| `serviceFailed`                  | `callback.service-failed`                    |
+| `schedulerTickFailed`            | `callback.scheduler-tick-failed`             |
+| `scheduledTaskFailed`            | `callback.scheduled-task-failed`             |
+| `domUpdateRunnerFailed`          | `callback.dom-update-runner-failed`          |
+| `extendableEventExtensionFailed` | `callback.extendable-event-extension-failed` |
+
+A scheduled task also **rejects its own promise** with the same value.
+
+## `component`
+
+| Key                        | Code                                   | Reported when                                                     |
+| -------------------------- | -------------------------------------- | ----------------------------------------------------------------- |
+| `loadFailed`               | `component.load-failed`                | a lazy import fails — once per name, never retried                |
+| `mountFailed`              | `component.mount-failed`               | a mount fails                                                     |
+| `lifecycleFailed`          | `component.lifecycle-failed`           | `mounted()` or `unmounted()` throws                               |
+| `invalidMountStrategy`     | `component.invalid-mount-strategy`     | a `data-mount` value is unusable — the component stays unmounted  |
+| `invalidFamilyDeclaration` | `component.invalid-family-declaration` | a `config.components` value is neither a `Base` class nor a thunk |
+| `configConflict`           | `component.config-conflict`            | `@component` and `static config` declare one key differently      |
+
+## `event`
+
+| Key                  | Code                         | Reported when                                  |
+| -------------------- | ---------------------------- | ---------------------------------------------- |
+| `invalidEmitPayload` | `event.invalid-emit-payload` | `$emit()` gets a payload that is not an object |
+
+The event still dispatches.
+
+## `manifest`
+
+| Key              | Code                       | Reported when                             |
+| ---------------- | -------------------------- | ----------------------------------------- |
+| `duplicateToken` | `manifest.duplicate-token` | a manifest declares a token already owned |
+
+## `option`
+
+| Key              | Code                     | Reported when                                              |
+| ---------------- | ------------------------ | ---------------------------------------------------------- |
+| `literalDefault` | `option.literal-default` | an `Array` or `Object` default is a literal, not a factory |
+
+The value is then used as declared and **shared** between instances.
+
+## `protocol`
+
+| Key                  | Code                            | Reported when                                                       |
+| -------------------- | ------------------------------- | ------------------------------------------------------------------- |
+| `lateRegistration`   | `protocol.late-registration`    | a negotiated-event listener calls `wrap`/`waitUntil` after dispatch |
+| `unappliedDomUpdate` | `protocol.unapplied-dom-update` | a claimed runner resolves without calling `apply`                   |
+
+In both cases the change still happens.
+
+## `ref`
+
+| Key        | Code           | Reported when                                                                        |
+| ---------- | -------------- | ------------------------------------------------------------------------------------ |
+| `mismatch` | `ref.mismatch` | `config.refs` and `data-ref` disagree on the `[]` suffix — once per instance and ref |
+
+## `registry`
+
+| Key                | Code                          | Reported when                                         |
+| ------------------ | ----------------------------- | ----------------------------------------------------- |
+| `conflict`         | `registry.conflict`           | a name is registered twice — the second is ignored    |
+| `lazyNameMismatch` | `registry.lazy-name-mismatch` | a loaded class's `config.name` differs from its token |
+
+## `responsive`
+
+| Key                 | Code                            | Reported when                                                               |
+| ------------------- | ------------------------------- | --------------------------------------------------------------------------- |
+| `unknownBreakpoint` | `responsive.unknown-breakpoint` | a `:<suffix>` names no configured breakpoint — including the v3 list syntax |
+
+## `scheduler`
+
+| Key                    | Code                               | Reported when                      |
+| ---------------------- | ---------------------------------- | ---------------------------------- |
+| `backgroundPostFailed` | `scheduler.background-post-failed` | a background turn cannot be posted |
+
+## `service`
+
+| Key             | Code                     | Reported when                                                                                        |
+| --------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `missingTarget` | `service.missing-target` | a caller-supplied mixin `target` resolver returns `undefined` or `null` — **no subscription starts** |
+
+## `storage`
+
+| Key                 | Code                         | Reported when                                    |
+| ------------------- | ---------------------------- | ------------------------------------------------ |
+| `accessFailed`      | `storage.access-failed`      | a provider's area is refused or full             |
+| `serializeFailed`   | `storage.serialize-failed`   | serialization throws — **nothing is written**    |
+| `deserializeFailed` | `storage.deserialize-failed` | deserialization throws — the default is returned |
+
+## `swap`
+
+| Key           | Code                | Reported when                                                         |
+| ------------- | ------------------- | --------------------------------------------------------------------- |
+| `selfIgnored` | `swap.self-ignored` | `self` is passed with `append`/`prepend`, or content holds no element |
+
+## Consumer codes
+
+`ToolkitDiagnosticCode` also accepts any `` `${string}.${string}` ``, so a consumer reports on the same channel with its own namespace:
+
+```ts
+import { warn } from '@studiometa/js-toolkit';
+
+warn('carousel.no-slides', 'A Carousel with no slide does nothing.', { component: 'Carousel' });
+```
+
+## Import it on its own
+
+```js
+import { DIAGNOSTICS } from '@studiometa/js-toolkit/DIAGNOSTICS';
+```

package/skills/studiometa-js-toolkit/references/api/diagnostics/EVENTS.md

@@ -0,0 +1,45 @@
+# EVENTS
+
+A deeply frozen object of the events the framework itself dispatches, all namespaced `js-toolkit:`.
+
+```js
+import { EVENTS } from '@studiometa/js-toolkit';
+
+EVENTS.component.mounted; // 'js-toolkit:component:mounted'
+EVENTS.component.unmounted; // 'js-toolkit:component:unmounted'
+EVENTS.dom.update; // 'js-toolkit:dom:update'
+EVENTS.diagnostic; // 'js-toolkit:diagnostic'
+```
+
+## The events
+
+| Constant                     | Name                             | Dispatched from           | Cancelable |
+| ---------------------------- | -------------------------------- | ------------------------- | ---------- |
+| `EVENTS.component.mounted`   | `js-toolkit:component:mounted`   | the element, **bubbling** | no         |
+| `EVENTS.component.unmounted` | `js-toolkit:component:unmounted` | `document`                | no         |
+| `EVENTS.dom.update`          | `js-toolkit:dom:update`          | the given node, bubbling  | no         |
+| `EVENTS.diagnostic`          | `js-toolkit:diagnostic`          | the element or `document` | **yes**    |
+
+See [Instance events](../instance-events.md) for the lifecycle pair, [`domUpdate()`](../dom/domUpdate.md) for the update event, and [Diagnostics](index.md) for the diagnostic.
+
+## The convention
+
+- **Public framework events** use this object and the `js-toolkit:` namespace.
+- **Private framework transports** use module-local namespaced constants and **do not join `EVENTS`** — the context request is one.
+- **Component events** are typed lower-kebab string literals declared through the props type's `$emits` key. They have no namespace: a component event is `open`, not `js-toolkit:open`.
+- 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.
+
+Only what a consumer can usefully listen to is exported. That is the whole rule for whether something belongs here.
+
+## Import it on its own
+
+```js
+import { EVENTS } from '@studiometa/js-toolkit/EVENTS';
+```
+
+The generated subpath keeps the frozen object importable without the root barrel — which matters on a page with no build step, where a barrel import downloads the barrel's whole graph.
+
+## `EVENTS.error` is removed
+
+With **no alias**. `EVENTS.error`, `ToolkitErrorDetail` and `ToolkitErrorStage` are gone; `EVENTS.diagnostic` and the [`DIAGNOSTICS`](DIAGNOSTICS.md) codes replace them.

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

@@ -0,0 +1,58 @@
+# Diagnostics
+
+Everything the framework recovers from is reported on **one** cancelable event, and nothing in core calls `console.warn()` or `console.error()` directly.
+
+## The exports
+
+- [`EVENTS`](EVENTS.md) — the framework event names
+- [`DIAGNOSTICS`](DIAGNOSTICS.md) — every code
+- [`reportDiagnostic(code, message, error, ctx?)`](reportDiagnostic.md) — report an error
+- [`warn(code, message, ctx?)`](warn.md) — report a warning
+
+From inside a component, `$warn()` and `$error()` fill the component name in.
+
+## The detail
+
+```ts
+type ToolkitDiagnosticDetail =
+  | {
+      readonly severity: 'warning';
+      readonly code: ToolkitDiagnosticCode;
+      readonly message: string;
+      readonly component?: string;
+      readonly error?: never;
+    }
+  | {
+      readonly severity: 'error';
+      readonly code: ToolkitDiagnosticCode;
+      readonly message: string;
+      readonly component?: string;
+      readonly error: unknown;
+    };
+```
+
+An **error** detail requires the original caught value; a **warning** carries none. That is a union, not an optional field, so a listener that reads `detail.error` has already narrowed on `severity`.
+
+## Listening
+
+```ts
+import { DIAGNOSTICS, EVENTS, type ToolkitDiagnosticDetail } from '@studiometa/js-toolkit';
+
+declare function monitor(code: string, detail: ToolkitDiagnosticDetail): void;
+document.addEventListener(EVENTS.diagnostic, (rawEvent) => {
+  const event = rawEvent as CustomEvent<ToolkitDiagnosticDetail>;
+  monitor(event.detail.code, event.detail);
+
+  if (event.detail.code === DIAGNOSTICS.responsive.unknownBreakpoint) {
+    event.preventDefault();
+  }
+});
+```
+
+Every diagnostic starts on its relevant connected element, or on `document` when there is none, with `{ bubbles: true, composed: true, cancelable: true }`.
+
+**Dispatch always happens before the default output.** An uncancelled warning calls `console.warn()` once with exactly `[js-toolkit:<code>] <message>`; an uncancelled error calls `reportError(detail.error)` with the original value. `preventDefault()` suppresses **that output only** and changes no framework decision.
+
+## Read next
+
+[Diagnostics](../../guide/going-further/handling-diagnostics.md).

package/skills/studiometa-js-toolkit/references/api/diagnostics/reportDiagnostic.md

@@ -0,0 +1,67 @@
+# reportDiagnostic
+
+```ts
+reportDiagnostic(
+  code: ToolkitDiagnosticCode,
+  message: string,
+  error: unknown,
+  context?: { component?: string; target?: Element },
+): CustomEvent<ToolkitDiagnosticDetail>
+```
+
+Reports an **error** on the diagnostic channel. The original caught value is required.
+
+## Usage
+
+```ts
+import { reportDiagnostic } from '@studiometa/js-toolkit';
+
+try {
+  JSON.parse('{');
+} catch (error) {
+  reportDiagnostic('carousel.bad-config', 'The config attribute is not valid JSON.', error, {
+    component: 'Carousel',
+  });
+}
+```
+
+**Parameters**
+
+- `code` — a namespaced string. Core codes come from [`DIAGNOSTICS`](DIAGNOSTICS.md); a consumer uses its own `'<namespace>.<name>'`.
+- `message` — one sentence, and it should say what to do about it.
+- `error` — **required.** The original value, passed through untouched.
+- `context.component` — the reporting component's name.
+- `context.target` — the element to dispatch from. Defaults to `document`.
+
+**Return value**
+
+- the dispatched event, so a caller can read `defaultPrevented`.
+
+## What happens
+
+1. The event is dispatched — **always before any output** — with `{ bubbles: true, composed: true, cancelable: true }`.
+2. If nothing cancelled it, `reportError(detail.error)` is called with the original value.
+
+`preventDefault()` suppresses that call and nothing else.
+
+## From a component
+
+`$error(code, message, error)` is the same call with the component name filled in:
+
+```js
+this.$error('carousel.bad-config', 'The config attribute is not valid JSON.', error);
+```
+
+## When to report and when to throw
+
+| The failure is               | Do                  |
+| ---------------------------- | ------------------- |
+| something you recovered from | report it           |
+| the caller's to handle       | **throw or reject** |
+
+Core follows the same rule: decorator and manifest-adapter misuse, shared-runtime incompatibility, service startup rollback, caller-owned teardown, `viewTransition()` and `swap()` all throw. A channel is for what was survived.
+
+## See also
+
+- [`warn()`](warn.md) — a warning, with no error value
+- [`captureDiagnostics()`](../test/index.md) — reading the channel in a test

package/skills/studiometa-js-toolkit/references/api/diagnostics/warn.md

@@ -0,0 +1,54 @@
+# warn
+
+```ts
+warn(
+  code: ToolkitDiagnosticCode,
+  message: string,
+  context?: { component?: string; target?: Element },
+): CustomEvent<ToolkitDiagnosticDetail>
+```
+
+Reports a **warning** on the diagnostic channel. A warning carries no error value — that is the difference from [`reportDiagnostic()`](reportDiagnostic.md), and it is a union in the type rather than an optional field.
+
+## Usage
+
+```ts
+import { warn } from '@studiometa/js-toolkit';
+
+warn('carousel.no-slides', 'A Carousel with no slide does nothing. Add `data-component="Slide"`.', {
+  component: 'Carousel',
+});
+```
+
+**Return value**
+
+- the dispatched event, so a caller can read `defaultPrevented`.
+
+## What happens
+
+1. The event is dispatched — **always before any output**.
+2. If nothing cancelled it, `console.warn()` is called **once**, with exactly `[js-toolkit:<code>] <message>`:
+
+```
+[js-toolkit:option.literal-default] Panel: the `tween` option default must be a factory function.
+```
+
+That exact format is what makes the console output greppable and what lets a listener reproduce it.
+
+## From a component
+
+`$warn(code, message)` fills the component name in:
+
+```js
+this.$warn('carousel.no-slides', 'A Carousel with no slide does nothing.');
+```
+
+## Deduplication
+
+Core's own warnings are deduplicated by weak owner plus a misuse key, in a revisioned shared-runtime slot — so a misuse is reported once per instance, per element or per declaration, and it works across independently evaluated copies of the package **without retaining** instances, elements, declarations, runners or manifest inputs.
+
+The public `warn()` does not deduplicate. Call it where the condition is detected once.
+
+## Write a message that says what to do
+
+The framework's own messages name the component, the thing that is wrong and the correction — `option.literal-default` names the option and the factory form to write instead. A warning a reader cannot act on is noise on a channel meant for monitoring.

package/skills/studiometa-js-toolkit/references/api/dom/breakpoints.md

@@ -0,0 +1,81 @@
+# Breakpoints
+
+```ts
+BREAKPOINTS: Readonly<Record<string, string>>
+getBreakpoints(): Record<string, string>
+setBreakpoints(next: Record<string, string>): void
+```
+
+The named breakpoint set is the single source of truth for every responsive spelling in the framework.
+
+## The defaults
+
+```js
+import { BREAKPOINTS, getBreakpoints } from '@studiometa/js-toolkit';
+
+getBreakpoints(); // the current set
+BREAKPOINTS; // the defaults
+```
+
+| Name   | Min width |
+| ------ | --------- |
+| `xxs`  | `0rem`    |
+| `xs`   | `30rem`   |
+| `s`    | `48rem`   |
+| `m`    | `64rem`   |
+| `l`    | `80rem`   |
+| `xl`   | `90rem`   |
+| `xxl`  | `120rem`  |
+| `xxxl` | `160rem`  |
+
+These are the names every `data-component:<name>` and `data-option-<x>:<name>` suffix is checked against.
+
+## Replacing them
+
+```js
+import { setBreakpoints } from '@studiometa/js-toolkit';
+
+setBreakpoints({
+  xs: '0rem',
+  s: '48rem',
+  m: '64rem',
+  l: '80rem',
+  xl: '96rem',
+});
+```
+
+`setBreakpoints()` is the single source of breakpoint truth, and calling it does three things at once:
+
+1. **rebuilds the scoped attribute names** — every `data-component:<name>` and every `data-option-<x>:<name>` spelling;
+2. **replaces that slice of the observer's `attributeFilter`**, draining the records of the previous filter first;
+3. **emits at once** on [`useBreakpoint()`](../services/useBreakpoint.md), so a subscriber sees the new active name immediately.
+
+## The values are in `rem`
+
+And in a media query, `rem` resolves against the **initial** font size, not against the root element. That is deliberate: a breakpoint that moved when a component changed the root font size would not be a breakpoint.
+
+## What uses them
+
+| Feature                                                                        | How                                            |
+| ------------------------------------------------------------------------------ | ---------------------------------------------- |
+| [responsive options](../html/data-option.md#every-option-is-responsive)    | `data-option-x:<name>`, cascading upwards      |
+| [responsive components](../html/data-component.md#responsive-declarations) | `data-component:<name>`, replacing not merging |
+| [`useBreakpoint()`](../services/useBreakpoint.md)                          | the active name, as a service                  |
+
+**A suffix that names no configured breakpoint** gives one `responsive.unknown-breakpoint` warning and is ignored — including the v3 list syntax `:xxs:xs:s`.
+
+## What it costs
+
+- The `MediaQueryList` objects are built **once**.
+- The active name is **memoised for the length of one task**, through `utils/memo`. `setBreakpoints()` and the `change` handler of a running service clear that memo at once.
+- A `matchMedia` subscription opens only for a component that declares [`option<Name>Changed()`](../methods-hooks-options.md); connected elements with a scoped `data-component` share **one** reference-counted subscription. A page with plain declarations and read-only options opens **none**.
+
+The breakpoint service is part of the core graph on every page. What a page pays is the subscriptions it asks for.
+
+**The defaults and Tailwind**
+
+The current default breakpoints are **not** aligned with `@studiometa/tailwind-config`. That alignment is a separate product decision. Call `setBreakpoints()` to match your own scale.
+
+## There is no `defineFeatures()`
+
+Breakpoints are the one configurable feature, and `setBreakpoints()` is it. Attribute names and the attribute prefix are not configurable.