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

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

@@ -0,0 +1,105 @@
+# swap
+
+```ts
+swap(target: Element, content: SwapContent, options?: SwapOptions): Promise<void>
+```
+
+Replaces the **content** of an element and resolves once the framework has caught up.
+
+```ts
+type SwapContent = string | Element | DocumentFragment;
+
+interface SwapOptions {
+  mode?: 'replace' | 'prepend' | 'append' | 'morph';
+  wrap?: (mutate: () => void) => void | Promise<unknown>;
+  self?: boolean;
+}
+```
+
+## Usage
+
+```ts
+import { swap } from '@studiometa/js-toolkit';
+
+async function load(target: Element) {
+  const response = await fetch('/fragment');
+  await swap(target, await response.text());
+  // The mutation is applied, the new components are mounted, the old ones unmounted.
+}
+```
+
+The returned promise resolves after [`whenDOMSettled()`](whenDOMSettled.md).
+
+## What survives
+
+**By default the element itself is never replaced**, so the caller's reference, its `id` and any instance on it survive. Only its children change.
+
+`content` as a **string** is parsed in the parsing context of the target, so `<tr>`, `<li>` and `<option>` survive. As an `Element` or a `DocumentFragment` it is read as the incoming counterpart of the target, and its **children** become the new content.
+
+## The modes
+
+```js
+import { SWAP_MODES } from '@studiometa/js-toolkit';
+
+SWAP_MODES.REPLACE; // 'replace' — the default
+SWAP_MODES.PREPEND; // 'prepend'
+SWAP_MODES.APPEND; // 'append'
+SWAP_MODES.MORPH; // 'morph'
+```
+
+`SwapMode` is derived from the frozen object — the pattern for every closed set of strings in the framework.
+
+`prepend` and `append` stay in core because they need the same before-and-after script diff as the other two.
+
+### `morph`
+
+Identity survives — nodes, focus, expandos, instances — **but markup that is not sent does not.** Two consequences are morphdom's policy, not `swap()`'s:
+
+- an element the incoming markup does not contain is discarded even from a preserved parent;
+- morphdom syncs the `value` of an input from the incoming markup.
+
+**Attributes are not synced on the target.** Core passes `childrenOnly: true` without `self`, because `data-component` and `data-mount` are lifecycle declarations of the target, not content.
+
+## `self`
+
+Replaces the target element **itself**, attributes included, instead of its children:
+
+```js
+await swap(el, html, { mode: 'replace', self: true });
+```
+
+It is the axis a caller that matches an element of a response to an element of the page needs: an id-matched section otherwise keeps the classes of the element it replaces.
+
+- With `self`, an `Element` content **is** the replacement rather than a container — the only way its own attributes reach the page. A string or a `DocumentFragment` contributes its **first top-level element**.
+- `replace` puts the replacement in the place of the target, so the target **leaves** the document.
+- `morph` morphs the target from the replacement without `childrenOnly`, so the element and its identity survive while its attributes are updated.
+- `append` and `prepend` add to the children by definition, so `self` with either is a `swap.self-ignored` warning — as is content holding no element.
+
+## Scripts
+
+A `<script>` produced by the fragment parser is flagged as **already started** by the HTML specification and stays inert wherever it is moved. It runs only if it is **recreated** — and a script that was already in the page runs **twice** if it is recreated.
+
+`swap()` owns that rule, once. Script adoption follows whatever ends up in the document, so a replacement carrying a script still runs it exactly once.
+
+## `wrap`
+
+The whole seam. It receives the single mutation of the swap and decides when it runs:
+
+```ts
+import { swap, viewTransition } from '@studiometa/js-toolkit';
+
+async function load(el: Element, html: string) {
+  await swap(el, html, { wrap: (mutate) => viewTransition(mutate) });
+}
+```
+
+[`domUpdate()`](domUpdate.md) produces that wrapper and nothing else, so an ancestor can claim the lane. **Resilience policy stays with `domUpdate()`** — `swap()` itself throws rather than swallowing.
+
+## What is deliberately not in core
+
+- **Attribute syncing in a default `morph`** — see above.
+- **Transitions, view transitions, history, `id` matching and response parsing.** All caller policy.
+
+## It is a free function
+
+Not a `Base` method. `morphdom` is a real, statically imported dependency, and the subpath layout contains the cost: it is reachable through `swap()` only, so a page that never swaps never downloads it.

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

@@ -0,0 +1,96 @@
+# watchAttributeNamespace
+
+```ts
+watchAttributeNamespace(
+  el: Element,
+  namespace: string,
+  bind: AttributeNamespaceBinder,
+  options?: { qualifiers?: readonly string[]; component?: string },
+): () => void
+```
+
+The mechanism for a namespace whose names **cannot be enumerated**. Declare the prefix, hand over a binder, and get the per-element observation, the keyed bindings and the teardown.
+
+```ts
+interface AttributeNamespaceDeclaration {
+  qualifier: string;
+  value: string;
+  attribute: string;
+}
+
+type AttributeNamespaceBinder = (declaration: AttributeNamespaceDeclaration) => (() => void) | void;
+```
+
+## Usage
+
+```js
+import { watchAttributeNamespace } from '@studiometa/js-toolkit';
+
+mounted() {
+  return watchAttributeNamespace(this.$el, 'data-on', ({ qualifier, value }) =>
+    new ActionEvent(this, qualifier, value).attach(),
+  );
+}
+```
+
+`Base` has no wrapper and owns no cleanup. A component calls it from `mounted()` and returns its cleanup.
+
+## One binding per attribute, keyed by the name that produced it
+
+That is what lets **one** code path cover all three shapes a change takes:
+
+| Change  | Effect                          |
+| ------- | ------------------------------- |
+| added   | attach, with nothing to release |
+| changed | release, then attach            |
+| removed | release, with nothing to attach |
+
+A memoised parse cannot express the middle one — and rewriting an attribute in place is not hypothetical: `swap({ mode: 'morph' })` does it, and so does any templating around the element.
+
+**The binder returns that binding's release**, or nothing when the declaration produced no binding. Returning nothing leaves nothing held, so a malformed value costs no bookkeeping.
+
+## Declaration order survives a rewrite
+
+The bindings are a `Map` keyed by attribute, and `set` on a key already there keeps its position — so a consumer applying its bindings in order is not reordered by an edit.
+
+## Validating the qualifier's head
+
+```js
+watchAttributeNamespace(el, 'data-bind', bind, {
+  qualifiers: ['class', 'prop', 'attr', 'style', 'text', 'html'],
+  component: 'Bind',
+});
+```
+
+Given a finite vocabulary, an unknown head warns **once per element and per name** with `attribute.unknown-qualifier` and binds nothing — so `data-bind:prpo.value` stops being an attribute that silently does nothing.
+
+Omitted, the vocabulary is **open** and anything binds, which is the only honest answer for `data-on`, whose qualifiers are any DOM event.
+
+## The qualifier and its parts
+
+```
+data-<namespace>:<qualifier>[.<part>…]
+```
+
+**A dot splits the qualifier, and core reads none of it.** Whether the first part names what a binding writes to (`data-bind:prop.value`) or modifies how it fires (`data-on:click.prevent`) is the business of whoever declared the namespace.
+
+Core reads the qualifier's **head** only, to check it against the vocabulary you handed over, and never past it.
+
+> Core owns when a declaration is re-parsed and how the attribute is observed. The namespace's owner owns what the string means.
+
+## It is built on `watchAttributes()`
+
+So its records join the one mutation engine's queue and are reported from the same batch: [`whenDOMSettled()`](whenDOMSettled.md), and therefore [`swap()`](swap.md), covers a namespaced declaration the way it covers a mount.
+
+## When a namespace does not need this
+
+If the whole set of names can be listed in advance, it belongs in the one page-wide `attributeFilter` instead:
+
+| Namespace               | Names                                       | Mechanism                 |
+| ----------------------- | ------------------------------------------- | ------------------------- |
+| `data-option-columns`   | `attribute × breakpoint` — enumerable       | the one `attributeFilter` |
+| `data-component`        | fixed plus one per breakpoint — enumerable  | the one `attributeFilter` |
+| `data-on`, `data-track` | any DOM event — open                        | **this**                  |
+| `data-bind`             | finite head, open name — **not** enumerable | **this**                  |
+
+`data-bind` is the case that shows why "finite or open" is the wrong axis on its own: its binding types are finite, but the class, property or attribute name after the dot is not. See [The attribute grammar](../../guide/concepts/attribute-grammar.md).

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

@@ -0,0 +1,56 @@
+# watchAttributes
+
+```ts
+watchAttributes(el: Element, callback: (change: AttributeChange) => void): () => void
+```
+
+Observes **every** attribute of one element, through a second, unfiltered observer.
+
+```ts
+interface AttributeChange {
+  name: string;
+  value: string | null;
+  previousValue: string | null;
+}
+```
+
+## Why it exists
+
+`attributeFilter` takes exact names and the DOM has no wildcard, so the engine cannot see an attribute the framework cannot name. This is the opt-in, and **the page pays for the elements that ask**.
+
+## Usage
+
+```js
+import { Base, watchAttributes } from '@studiometa/js-toolkit';
+
+class Bindings extends Base {
+  static config = { name: 'Bindings' };
+
+  mounted() {
+    return watchAttributes(this.$el, ({ name, value, previousValue }) => {
+      if (!name.startsWith('data-my-')) return;
+      // …
+    });
+  }
+}
+```
+
+**The caller owns it.** The helper returns one idempotent cleanup and knows nothing about `Base`: a component calls it from `mounted()` and returns the cleanup.
+
+## The contract
+
+- **The records join the shared queue.** They are drained wherever the engine drains its own, [`whenDOMSettled()`](whenDOMSettled.md) included, and they are reported from the same background task — as the last step of the batch.
+- **A callback runs after the framework work of the batch.** So a component that stops its watcher during the same batch in which its own declaration is withdrawn hears nothing about the attribute change.
+- **Changes are coalesced**, with the rule of [`option<Name>Changed()`](../methods-hooks-options.md): several writes in one batch give one change, from the value before the first write to the value at the end, and a write that ends where it started is not a change.
+- **The payload covers the element's whole attribute set**, framework names included, with raw strings and `null` for an absent attribute. **A caller narrows by prefix.**
+- A failing callback is reported as `callback.attribute-watcher-failed`, so one watcher cannot stop another.
+
+## What to reach for instead
+
+| Want                                         | Use                                                           |
+| -------------------------------------------- | ------------------------------------------------------------- |
+| a declared option                            | [`option<Name>Changed()`](../methods-hooks-options.md)    |
+| a whole namespace, with keyed bindings       | [`watchAttributeNamespace()`](watchAttributeNamespace.md) |
+| a subtree, character data, or a foreign node | [`useMutation()`](../services/useMutation.md)             |
+
+A declared option is already in the one page-wide filter, and costs no second observer.

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

@@ -0,0 +1,41 @@
+# whenDOMSettled
+
+```ts
+whenDOMSettled(): Promise<void>
+```
+
+The completion boundary for morphing, fetch updates and breakpoint crossings.
+
+## Usage
+
+```ts
+import { whenDOMSettled } from '@studiometa/js-toolkit';
+
+async function replace(el: Element, html: string) {
+  el.innerHTML = html;
+  await whenDOMSettled();
+  // Every eager component in the new markup has mounted.
+}
+```
+
+[`swap()`](swap.md) awaits it for you.
+
+## What it waits for
+
+- it **drains the pending mutation records**;
+- it **follows the mutation chains of eager lifecycle work**, so markup a `mounted()` inserts is covered too;
+- it resolves after the eager mounts **and the teardown**.
+
+An **eager lazy** component is covered: the import promise joins the lifecycle-work set for the eager trigger only, so an awaited `swap()` waits for download, registration and mount.
+
+Breakpoint work runs through the background lane, so a crossing's teardown, import and mount work is covered as well.
+
+## What it does not wait for
+
+- **visibility, interaction, idle or media conditions.** A component with `data-mount="visible"` has not mounted when this resolves, and that is the point: waiting on a viewport would mean never resolving on a page that is not scrolled.
+- **the promises returned by `mounted()`.** An async `mounted()` is the component's own business.
+
+## Where else it appears
+
+- `watchAttributes()` records join the same queue, so a namespaced declaration is covered the way a mount is.
+- A [`useMutation()`](../services/useMutation.md) subscriber that needs the framework's order rather than the platform's awaits this in its callback.

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

@@ -0,0 +1,105 @@
+# `data-component`
+
+Declares which components run on an element. **The instance exists because this attribute is here and the name is registered.**
+
+## One component
+
+```html
+<div data-component="Slider"></div>
+```
+
+The token is the component's `config.name`.
+
+## Several components
+
+The value is a whitespace-separated token list, and each token gets its own instance:
+
+```html
+<a href="/next" data-component="Action Analytics Prefetch">Next</a>
+```
+
+The instances are independent. They share the element and nothing else.
+
+## On native elements
+
+`data-component` improves a native element rather than replacing it:
+
+```html
+<form data-component="Fetch">…</form>
+<details data-component="Disclosure">…</details>
+<a href="/page" data-component="Prefetch">…</a>
+<tr data-component="Row">…</tr>
+```
+
+## Nesting
+
+A nested declaration is discovered by the same registry, on its own. Nesting is DOM ancestry, never ownership:
+
+```html
+<div data-component="Accordion">
+  <div data-component="AccordionItem">…</div>
+  <div data-component="AccordionItem">…</div>
+</div>
+```
+
+Unmounting the parent does not unmount the children.
+
+## Responsive declarations
+
+One breakpoint-scoped companion attribute exists, with the spelling of responsive options:
+
+```html
+<div
+  data-component="Action Analytics"
+  data-component:xxs="MobileMenu MobileSearch"
+  data-component:m="DesktopMenu DesktopSearch"></div>
+```
+
+- The plain token set is **always active**.
+- At the active breakpoint the registry walks from the widest active suffix **down** and takes the first attribute present.
+- That value is the **complete** responsive set. A wider value **replaces** every lower value; it does not merge with it.
+- An empty value is a **stop**, so a name can be removed above a breakpoint.
+- The effective declaration is the **union** of the unconditional set and the selected responsive set, without duplicates.
+
+`TabletFeature` below runs at `s` and `m`, and is removed at `l`:
+
+```html
+<div data-component="Base" data-component:s="TabletFeature" data-component:l=""></div>
+```
+
+### What a crossing does
+
+A crossing compares the effective set against the element's current state:
+
+| Case                      | Effect                                                                |
+| ------------------------- | --------------------------------------------------------------------- |
+| a name is in both         | it keeps its controller and its instance — nothing happens            |
+| a name is no longer there | `$unmount()`, then the instance is dropped from the element           |
+| a name is new             | the normal pipeline: mount strategy, `data-mount`, lazy entry, events |
+
+A crossing back gives a **new** identity, because the DOM stopped declaring that one. An inactive lazy declaration imports nothing.
+
+Connected elements with a scoped declaration share **one** reference-counted `useBreakpoint()` subscription. A page with plain declarations opens none. Breakpoint work runs through the background lane, so `whenDOMSettled()` covers the teardown, import and mount work of a crossing.
+
+**A suffix must name a configured breakpoint**
+
+An unknown suffix is ignored with one `responsive.unknown-breakpoint` warning. That includes the v3 list syntax `data-component:xxs:xs:s`.
+
+See [`setBreakpoints()`](../dom/breakpoints.md).
+
+## Changing it from code
+
+The attribute is live. Adding a token mounts a new instance; removing one unmounts and drops it:
+
+```js
+el.dataset.component = 'Slider Analytics';
+await whenDOMSettled();
+```
+
+## Where the instances go
+
+Each instance is published on the element under `Symbol.for('@studiometa/js-toolkit/instances')`. That map is not public API — [`getInstance()`](../registry/getInstance.md) and its three siblings are. In a console:
+
+```js
+$0[Symbol.for('@studiometa/js-toolkit/instances')];
+```

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

@@ -0,0 +1,69 @@
+# `data-mount`
+
+Overrides, for one element, **when** its components mount.
+
+```html
+<div data-component="Map" data-mount="visible"></div>
+```
+
+## The values
+
+| Value                    | Mounts when                            | Reversible |
+| ------------------------ | -------------------------------------- | ---------- |
+| `eager`                  | the element enters the document        | no         |
+| `visible[:<rootMargin>]` | it first intersects the viewport       | no         |
+| `in-view[:<rootMargin>]` | it intersects the viewport             | **yes**    |
+| `idle`                   | the main thread becomes idle           | no         |
+| `interaction`            | the user first aims at **it**          | no         |
+| `interaction:page`       | the user first interacts with the page | no         |
+| `media:<query>`          | the query is not empty and it matches  | **yes**    |
+
+```html
+<div data-component="Hero" data-mount="eager"></div>
+<div data-component="Gallery" data-mount="visible:200px"></div>
+<div data-component="Video" data-mount="in-view:-10% 0px"></div>
+<div data-component="Analytics" data-mount="idle"></div>
+<div data-component="Tooltip" data-mount="interaction"></div>
+<div data-component="Chat" data-mount="interaction:page"></div>
+<div data-component="Parallax" data-mount="media:(min-width: 64rem)"></div>
+```
+
+## The grammar
+
+The accepted values are exactly `eager`, `visible`, `visible:`, `visible:<rootMargin>`, `in-view`, `in-view:`, `in-view:<rootMargin>`, `idle`, `interaction`, `interaction:`, `interaction:page` and `media:<non-empty query>`.
+
+- A viewport suffix is passed straight through as `IntersectionObserverInit.rootMargin`.
+- The empty suffix behaves as the bare strategy.
+- `page` is the only scope the interaction strategy takes.
+- There is **no** threshold, no root element, no JSON options and no second attribute.
+
+## Precedence
+
+```
+data-mount  >  manifest entry mountStrategy  >  config.mountStrategy  >  'eager'
+```
+
+**Several components on one element share that element's `data-mount`.** A component that needs its own policy declares `config.mountStrategy` instead.
+
+## Invalid values
+
+An unknown value, an empty media query, or a `rootMargin` the browser refuses leaves the component **unmounted** and dispatches one cancelable `js-toolkit:diagnostic` with the code `component.invalid-mount-strategy`, the severity `error`, the component name and the original error.
+
+The inert controller stays current while the declaration does not change, so it is not reported again; a corrected attribute replaces it. A failed strategy cannot stop the rest of a reconciliation.
+
+## It is live
+
+A change to `data-mount` disposes the old strategy and applies the final one. Controller identity guards a queued callback of a disposed strategy.
+
+```js
+el.dataset.mount = 'eager';
+await whenDOMSettled();
+```
+
+## A waiting component has no instance
+
+It is invisible to `$query()`, `$closest()`, `$watchChildren()` and `getInstances()`, and it announces nothing. There is nothing to guard against.
+
+Once it has mounted and been stood down again — which only `in-view` and `media:` do — the instance exists and is unmounted, which is what [`getUnmountedInstances()`](../registry/getUnmountedInstances.md) answers.
+
+See [Mount strategies](../../guide/going-further/mount-strategies.md) for the full behaviour of each value.

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