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

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    |

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.