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

package/skills/studiometa-js-toolkit/references/guide/introduction/managing-components.md

@@ -0,0 +1,229 @@
+# Components
+
+A component is a class that extends `Base`, a name in the registry, and a `data-component` attribute in the markup. All three are needed, and nothing else is.
+
+## Declaring a component
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class Counter extends Base {
+  static config = {
+    name: 'Counter',
+    refs: ['output'],
+    options: { step: { type: Number, default: 1 } },
+  };
+
+  count = 0;
+
+  onClick() {
+    this.count += this.$options.step;
+    this.$refs.output.textContent = String(this.count);
+  }
+}
+
+registerComponent(Counter);
+```
+
+```html
+<button data-component="Counter" data-option-step="5">
+  clicked
+  <span data-ref="output">0</span>
+  times
+</button>
+```
+
+`config.name` is the name the registry uses and the token the markup writes. It is also what gives each instance its [`$id`](../../api/instance-properties.md#id).
+
+## Registering
+
+`registerComponent(ComponentClass)` puts one name in the registry and scans the document for it. `registerComponents(...classes)` does the same for several:
+
+```js
+import { Base, registerComponents } from '@studiometa/js-toolkit';
+
+class Accordion extends Base {
+  static config = { name: 'Accordion' };
+}
+class Slider extends Base {
+  static config = { name: 'Slider' };
+}
+
+registerComponents(Accordion, Slider);
+```
+
+**There is no `createApp()`**
+
+v4 has no root component and no application object. A component is registered, not mounted by a parent, so nothing has to own the page. Register the components a page uses and the registry does the rest.
+
+**One name gives one entry**, as with `customElements.define()`. A second registration under a name already taken gives a `registry.conflict` warning and is ignored.
+
+## Several components on one element
+
+`data-component` holds a whitespace-separated token list, and each token gets its own instance:
+
+```html
+<a href="/next" data-component="Action Analytics Prefetch">Next</a>
+```
+
+The three instances are independent. They share the element and nothing else.
+
+## Nesting
+
+Children are not constructed by their parent. A nested `data-component` is discovered by the same registry, on its own:
+
+```html
+<div data-component="Accordion">
+  <div data-component="AccordionItem">…</div>
+  <div data-component="AccordionItem">…</div>
+</div>
+```
+
+What the parent declares in `config.components` is a **family**, and it does two jobs:
+
+1. registering that family when the parent registers, so one `registerComponent()` call covers a whole tree;
+2. giving the name set that [`on<Child><Event>`](working-with-events.md#child-events) resolution needs.
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base {
+  static config = { name: 'AccordionItem' };
+}
+
+class Accordion extends Base {
+  static config = {
+    name: 'Accordion',
+    components: { AccordionItem },
+  };
+}
+
+// Registers `Accordion` *and* `AccordionItem`.
+registerComponent(Accordion);
+```
+
+A value can also be a thunk, which makes the child its own chunk:
+
+```js
+static config = {
+  name: 'Accordion',
+  components: {
+    AccordionItem: () => import('./AccordionItem.js'),
+  },
+};
+```
+
+The key supplies the name, so the registry knows `AccordionItem` with nothing downloaded. See [Autoloading](../going-further/autoloading.md).
+
+**`config.components` is not ownership**
+
+Declaring a child does not make the parent construct it, does not make the parent's unmount unmount it, and does not restrict where the child may appear. Nesting is DOM ancestry, always.
+
+## Finding other components
+
+There is no `$parent` and no `$children`. A component that needs to reach another one has four channels, in order of preference:
+
+| Direction               | Use                                                                              |
+| ----------------------- | -------------------------------------------------------------------------------- |
+| parent → children       | [`$watchChildren()`](../../api/instance-methods.md#watchchildren) or `$query(name)` |
+| child → parent          | [`$emit()`](../../api/instance-methods.md#emit) and the parent's `on<Child><Event>` |
+| ancestor lookup, ad hoc | [`$closest(name)`](../../api/instance-methods.md#closest) — guard the result        |
+| shared state either way | [provide/inject](../going-further/sharing-state.md)                        |
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Accordion extends Base {
+  static config = { name: 'Accordion', components: {} };
+
+  // A live collection, in document order, kept for the life of this instance.
+  items = this.$watchChildren('AccordionItem');
+
+  closeAll() {
+    for (const item of this.items) item.$el.removeAttribute('data-option-open');
+  }
+}
+```
+
+## Page-wide lookups
+
+Outside a component, four functions answer from the DOM. They keep no registry of instances:
+
+```ts
+import {
+  getInstance,
+  getInstances,
+  getMountedInstances,
+  getUnmountedInstances,
+} from '@studiometa/js-toolkit';
+
+const section = document.querySelector('section')!;
+
+getMountedInstances('Dialog'); // the live ones — safe to call a method on
+getInstances('Dialog', section); // every one built in a region
+getUnmountedInstances('Dialog'); // built, then stood down
+getInstance(section, 'Dialog'); // the one on this element, mounted or not
+getInstances(section); // everything on one element
+```
+
+See the [Registry reference](../../api/registry/index.md) for the full contract of each.
+
+## Extending a component
+
+There is no `withExtraConfig()`. To extend a component with a different config, declare a class. `$config` walks the prototype chain, so `refs`, `options` and `components` merge:
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class AbstractControl extends Base {
+  static config = {
+    name: 'AbstractControl',
+    refs: ['button'],
+  };
+}
+
+class NavigationControl extends AbstractControl {
+  static config = {
+    name: 'NavigationControl',
+    // `refs` merges: ['button', 'compass']
+    refs: ['compass'],
+    options: { showCompass: Boolean },
+  };
+}
+
+registerComponent(NavigationControl);
+```
+
+To extend a class you cannot edit, do it in expression position:
+
+```js
+registerComponent(
+  class extends Vendor {
+    static config = { name: 'CompactVendor', options: { compact: Boolean } };
+  },
+);
+```
+
+## When a component mounts
+
+By default an instance mounts as soon as its element enters the document. `config.mountStrategy` and the `data-mount` attribute change that:
+
+```html
+<div data-component="Map" data-mount="visible"></div>
+<div data-component="Chat" data-mount="interaction:page"></div>
+```
+
+A component that waits has **no instance**: it is invisible to `$query()`, `$closest()`, `$watchChildren()` and `getInstances()`, and it announces nothing. See [Mount strategies](../going-further/mount-strategies.md).
+
+## Responsive declarations
+
+`data-component` takes one breakpoint-scoped companion, so a component can exist at some widths and not others:
+
+```html
+<div
+  data-component="Action Analytics"
+  data-component:xxs="MobileMenu"
+  data-component:m="DesktopMenu"></div>
+```
+
+The unconditional set is always active. The scoped set is resolved by walking from the widest active suffix down to the first attribute present, and it **replaces** rather than merges. A name that stops being declared is unmounted and dropped from the element; a crossing back builds a new instance. See [`data-component`](../../api/html/data-component.md).

package/skills/studiometa-js-toolkit/references/guide/introduction/managing-options.md

@@ -0,0 +1,235 @@
+# Options
+
+An option is a value a component reads from its element. It is declared in `config.options` and written in the markup as `data-option-<name>`.
+
+Two rules carry everything else on this page:
+
+> **An option is an input, never a store.**
+>
+> **Every option is responsive. There is nothing to declare for it.**
+
+## Declaring options
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Slider extends Base {
+  static config = {
+    name: 'Slider',
+    options: {
+      // The short form: just the type.
+      label: String,
+      // The long form: a type and a default.
+      speed: { type: Number, default: 1 },
+      loop: { type: Boolean, default: true },
+      // Array and Object defaults must be factory functions.
+      tween: { type: Object, default: () => ({ ease: 'linear' }) },
+    },
+  };
+
+  mounted() {
+    console.log(this.$options.speed);
+  }
+}
+```
+
+```html
+<div data-component="Slider" data-option-speed="2" data-option-label="Gallery"></div>
+```
+
+The attribute name is the option name in kebab case: `dragThreshold` is `data-option-drag-threshold`.
+
+## `$options` is a read-only view
+
+`buildOptions()` defines every property with a **getter and no setter**. The value is derived from the element and the viewport on each access, and nothing is written in. An assignment throws, because a module is strict code:
+
+```js
+this.$options.open = true;
+// TypeError: Cannot set property open of #<Object> which has only a getter
+```
+
+Two idioms replace the write, and which one you want depends on what the value is.
+
+**The DOM is meant to change** — write the attribute. It is the same statement the markup makes:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Panel extends Base {
+  static config = { name: 'Panel', options: { disabled: Boolean } };
+
+  enable() {
+    this.$el.removeAttribute('data-option-disabled');
+  }
+
+  disable() {
+    this.$el.setAttribute('data-option-disabled', '');
+  }
+}
+```
+
+The next read gives the new value, and [`option<Name>Changed()`](#live-effects) announces it to anyone listening.
+
+**The value was never an input** — keep a private field seeded from the option. The attribute says where the component starts; the field carries where it has got to:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Carousel extends Base {
+  static config = { name: 'Carousel', options: { start: { type: Number, default: 0 } } };
+
+  #index = this.$options.start;
+
+  next() {
+    this.#index += 1;
+  }
+}
+```
+
+An option a component only reads keeps neither: it reads `this.$options.x` where it needs it.
+
+## Defaults
+
+**A primitive can be a default. Every other data type needs a factory function.**
+
+```js
+options: {
+  speed: { type: Number, default: 1 },                       // fine
+  tween: { type: Object, default: () => ({ ease: 'linear' }) }, // required form
+  items: { type: Array, default: () => [] },                    // required form
+}
+```
+
+- `Function` is not an option type, so a `default` that is a function is always a factory.
+- A default is built **once per instance** and then kept. Two instances never share one default.
+- A factory is **lazy**. Nothing is built for an option nobody reads, and a component whose attribute is present never runs its factory.
+- `Array` and `Object` with no declared default get an empty value per instance.
+- A literal object or array default gives one `option.literal-default` warning, naming the component, the option and the correction. The value is then used as declared and **shared** between instances.
+
+A default is the one option value that lives on the instance, so mutating the object a factory built sticks — `this.$options.tween.ease = 'ease-out'` is kept, for that instance. Replacing the option itself does not: `this.$options.tween = {}` throws, like every other write to the view.
+
+## Boolean options read presence
+
+`data-option-open` is on, an absent attribute is the declared default, and 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 -->
+```
+
+Update one from code by adding or removing the attribute:
+
+```js
+flag ? el.setAttribute('data-option-open', '') : el.removeAttribute('data-option-open');
+```
+
+A template must therefore write the attribute conditionally rather than interpolate a boolean into it:
+
+```html
+{# Correct #}
+<div data-component="Panel" {% if isOpen %}data-option-open{% endif %}></div>
+
+{# Wrong — always true #}
+<div data-component="Panel" data-option-open="{{ isOpen }}"></div>
+```
+
+### Turning one off — `data-option-no-<name>`
+
+A boolean option is turned off by an attribute that only has to be there:
+
+```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.
+- It is responsive like every other spelling.
+- 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`.
+
+## Several types
+
+An option can accept several types. Declare the constructors in order:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Sticky extends Base {
+  static config = {
+    name: 'Sticky',
+    options: {
+      // "10" reads as a number; "[10, 20]" reads as an array.
+      offset: [Number, Array],
+    },
+  };
+}
+```
+
+Each parser must give a value of its declared type before the next parser runs. An absent union option uses its declared default, or the empty value of its first type.
+
+## Responsive options
+
+Every option takes a breakpoint suffix, with no flag to declare:
+
+```html
+<div
+  data-component="Grid"
+  data-option-columns="1"
+  data-option-columns:s="2"
+  data-option-columns:l="4"></div>
+```
+
+- **The suffix names one breakpoint and it cascades upwards.** `$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 value is derived on read.** Nothing is stored and nothing is written.
+- A suffix naming no configured breakpoint gives one `responsive.unknown-breakpoint` warning per mount.
+- A `matchMedia` subscription opens **only** for a component that declares `option<Name>Changed()`. A page that only reads options holds no listener.
+
+See [`setBreakpoints()`](../../api/dom/breakpoints.md) to replace the named set.
+
+## Live effects {#live-effects}
+
+A declared method named `option<Name>Changed()` makes that option a live effect. It is how an option that chooses a resource stays correct:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+function connect(url) {
+  return { dispose() {} };
+}
+
+class Feed extends Base {
+  static config = { name: 'Feed', options: { source: String } };
+
+  optionSourceChanged({ value, previousValue, initial }) {
+    const connection = connect(value);
+    // The returned function is the cleanup for *this* value.
+    return () => connection.dispose();
+  }
+}
+```
+
+- The hook runs **before `mounted()`** on each mount cycle, with `initial: true`.
+- Several writes in one mutation batch give **one** change, from the first old raw value to the final DOM value. A write that ends where it started is not a change.
+- The previous cleanup runs before an update. Every active cleanup runs on `$unmount()`.
+- Removal of the attribute applies the declared default.
+- A breakpoint crossing reports through the same hook. A crossing to the same resolved value announces nothing.
+- A component without the convention pays no setup cost.
+
+The payload is an [`OptionChange`](../../api/methods-hooks-options.md):
+
+```ts
+import { Base, type OptionChange } from '@studiometa/js-toolkit';
+
+class Feed extends Base {
+  static config = { name: 'Feed', options: { source: String } };
+
+  optionSourceChanged({ value, previousValue, rawValue, initial }: OptionChange<string>) {
+    console.log(value, previousValue, rawValue, initial);
+  }
+}
+```

package/skills/studiometa-js-toolkit/references/guide/introduction/managing-refs.md

@@ -0,0 +1,174 @@
+# Refs
+
+A ref is an element of a component's own markup, named in the HTML with `data-ref` and declared in `config.refs`.
+
+**Refs are live.** Each `$refs` property reads the DOM on access, so markup put into a component is found with no refresh, and no detached element stays in a list. There is no `$update()`.
+
+## A single ref
+
+```html
+<div data-component="Dialog">
+  <button data-ref="close">Close</button>
+</div>
+```
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Dialog extends Base {
+  static config = {
+    name: 'Dialog',
+    refs: ['close'],
+  };
+
+  mounted() {
+    this.$refs.close.focus();
+  }
+
+  onCloseClick() {
+    this.$el.removeAttribute('data-option-open');
+  }
+}
+```
+
+A plain declaration selects `[data-ref="close"]` and gives the **first** match.
+
+## A list of refs
+
+**A list ref keeps the `[]` in the attribute.** The suffix is part of the name, in the config and in the markup:
+
+```html
+<ul data-component="Tabs">
+  <li><button data-ref="tabs[]">One</button></li>
+  <li><button data-ref="tabs[]">Two</button></li>
+</ul>
+```
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Tabs extends Base {
+  static config = {
+    name: 'Tabs',
+    refs: ['tabs[]'],
+  };
+
+  onTabsClick({ index }) {
+    console.log(`tab ${index} was clicked`);
+  }
+}
+```
+
+`$refs.tabs` is an array. The property name never carries the suffix — `tabs[]` in the declaration, `$refs.tabs` everywhere else.
+
+**The two spellings must agree**
+
+`config.refs: ['tabs[]']` matches `data-ref="tabs[]"` 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.
+
+## Ref boundaries
+
+By default a ref belongs to the **nearest enclosing component**. A ref inside a nested component is that component's, not yours:
+
+```html
+<div data-component="Slider">
+  <button data-ref="next">Slider's own</button>
+  <div data-component="SliderItem">
+    <button data-ref="next">SliderItem's, not Slider's</button>
+  </div>
+</div>
+```
+
+### Naming the owner
+
+A ref can name the component it belongs to, and then it crosses boundaries:
+
+```html
+<div data-component="Slider">
+  <div data-component="SliderItem">
+    <button data-ref="Slider.next">Slider's, from inside a child</button>
+  </div>
+</div>
+```
+
+`Slider.next` passes every boundary **except** another `Slider`, so 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:
+
+| 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[]', …)` |
+
+The namespace goes **before** the suffix: `Component.name[]`.
+
+## Event handlers
+
+`on<Ref><Event>` handlers are **delegated from the root element**, so a ref that appears later needs no new binding:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Todo extends Base {
+  static config = {
+    name: 'Todo',
+    refs: ['items[]', 'input'],
+  };
+
+  // Fires for any `items[]` ref, including the ones added after mount.
+  onItemsClick({ event, target, index }) {
+    console.log(index, target);
+  }
+
+  onInputInput({ target }) {
+    console.log(target.value);
+  }
+}
+```
+
+The payload is `{ event, target, index }`:
+
+- `event` — the DOM event.
+- `target` — the ref element the handler matched, **not** `event.target`.
+- `index` — the position in the list, or `0` for a single ref.
+
+Events that do not bubble — `focus`, `blur`, `scroll`, `mouseenter`, `mouseleave` — are delegated from the **capture** phase, so they are heard all the same.
+
+In TypeScript, annotate the payload with `RefEvent`:
+
+```ts
+import { Base, type RefEvent } from '@studiometa/js-toolkit';
+
+class Todo extends Base {
+  static config = { name: 'Todo', refs: ['input'] };
+
+  onInputInput({ target }: RefEvent<HTMLInputElement>) {
+    console.log(target.value);
+  }
+}
+```
+
+## How the live read works
+
+Ref lookups are cached, and the cache is invalidated by a counter that the framework's own MutationObserver increases. Reading that counter drains the pending records with `takeRecords()`, so the read is current even inside the same task as the mutation. Detached elements are never cached.
+
+The practical consequence: you never refresh anything.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Todo extends Base {
+  static config = { name: 'Todo', refs: ['list', 'items[]'] };
+
+  add(title) {
+    const li = document.createElement('li');
+    li.dataset.ref = 'items[]';
+    li.textContent = title;
+    this.$refs.list.append(li);
+
+    // Already there. No `$update()`, no re-query.
+    console.log(this.$refs.items.length);
+  }
+}
+```