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

package/skills/studiometa-js-toolkit/references/guide/going-further/typing-components.md

@@ -0,0 +1,190 @@
+# TypeScript
+
+`Base` takes an optional props type. It types `$refs` and `$options`, and it checks the event names and payloads of `$emit()`.
+
+## The props type
+
+```ts
+import { Base } from '@studiometa/js-toolkit';
+
+class Slider extends Base<{
+  $el: HTMLDivElement;
+  $refs: {
+    next: HTMLButtonElement;
+    items: HTMLElement[];
+  };
+  $options: {
+    speed: number;
+    loop: boolean;
+  };
+  $emits: {
+    goto: { index: number };
+    stop: void;
+  };
+}> {
+  static config = {
+    name: 'Slider',
+    refs: ['next', 'items[]'],
+    options: {
+      speed: { type: Number, default: 1 },
+      loop: { type: Boolean, default: true },
+    },
+  };
+
+  mounted() {
+    this.$refs.next.disabled = true;
+    this.$refs.items[0];
+    this.$options.speed;
+    this.$emit('goto', { index: 1 });
+    this.$emit('stop');
+  }
+}
+```
+
+Four keys, all optional:
+
+| Key        | Types                                                     |
+| ---------- | --------------------------------------------------------- |
+| `$el`      | the root element                                          |
+| `$refs`    | each declared ref — an array for a list ref               |
+| `$options` | each declared option                                      |
+| `$emits`   | each event name to its payload object, or `void` for none |
+
+`$emits` replaces the runtime `config.emits` of v3. **Nothing of it stays in the bundle.**
+
+## Extending a component
+
+A component can take a props parameter of its own. This is how one component extends another:
+
+```ts
+import { Base, type BaseConfig, type BaseProps } from '@studiometa/js-toolkit';
+
+interface ActionProps extends BaseProps {
+  $options: { target: string };
+}
+
+class Action<T extends BaseProps = BaseProps> extends Base<ActionProps & T> {
+  // Annotated, so a subclass is free to declare a different config.
+  static config: BaseConfig = {
+    name: 'Action',
+    options: { target: String },
+  };
+
+  mounted() {
+    this.$options.target; // string
+  }
+}
+
+class SafeAction extends Action<{ $options: { confirm: boolean } }> {
+  static config = {
+    name: 'SafeAction',
+    options: { confirm: Boolean },
+  };
+
+  mounted() {
+    this.$options.target; // still string
+    this.$options.confirm; // boolean
+  }
+}
+```
+
+Each prop is read as an intersection with its default, such as `T['$options'] & Record<string, unknown>`.
+
+**The price of the intersection**
+
+An option or a ref a component does **not** declare reads as `unknown`, or as `HTMLElement | HTMLElement[]`, rather than as an error. Declared props keep their exact types. This is the cost of making extension work, and it was chosen deliberately over a conditional type.
+
+`$options` is read through the same intersection and then mapped to `Readonly<…>`, which has one price of its own: a mapped type over a props parameter is deferred, so inside a class **generic in its props** a declared option is a usable value of its declared type rather than a type identical to it. Reading it, passing it and annotating it all work; asserting its identity, or assigning one option to a variable inferred from another, needs an annotation.
+
+`src/props.spec.ts` holds the assertions, and `npm run lint:types` enforces them.
+
+## Handler payloads
+
+A method named by convention is **not typed by convention** — the name is resolved at runtime. Annotate the payload:
+
+```ts
+import { Base, type DelegatedEvent, type GlobalEvent, type RefEvent } from '@studiometa/js-toolkit';
+
+class Child extends Base<{ $emits: { open: { height: number } } }> {
+  static config = { name: 'Child' };
+}
+class Parent extends Base {
+  static config = { name: 'Parent', components: { Child }, refs: ['dots[]'] };
+
+  onChildOpen({ target, payload }: DelegatedEvent<Child, 'open'>) {}
+
+  onDotsClick({ target, index }: RefEvent<HTMLButtonElement>) {}
+
+  onWindowResize({ event, target }: GlobalEvent<UIEvent>) {}
+}
+```
+
+The [`@on` decorator](../../api/decorators/on.md) does not remove the annotation — it **checks** it. The decorator derives the payload type its target implies and the method signature has to match, so a wrong annotation is a type error rather than a silent mismatch:
+
+```ts
+import { Base, component, on, type DelegatedEvent } from '@studiometa/js-toolkit';
+
+class Child extends Base<{ $emits: { open: { height: number } } }> {
+  static config = { name: 'Child' };
+}
+@component({ name: 'Parent', components: { Child } })
+class Parent extends Base {
+  @on(Child, 'open')
+  onOpen({ payload }: DelegatedEvent<Child, 'open'>) {
+    payload.height; // number
+  }
+}
+```
+
+A decorator cannot infer a method's own parameters — the method signature is checked _against_ what the decorator expects, not derived from it. Annotate the payload either way; with `@on` the annotation is verified against a real target.
+
+## Config typing
+
+`$config` walks the prototype chain and merges every config it finds, so an intermediate class must not narrow the type its subclasses need.
+
+Left alone, `static config = { … }` infers a **literal** type, and every subclass has to match it — a subclass that adds an option gets `Class static side 'typeof SafeAction' incorrectly extends base class static side 'typeof Action'`. Annotate the intermediate class instead:
+
+```ts
+import { Base, type BaseConfig } from '@studiometa/js-toolkit';
+
+class AbstractControl extends Base {
+  static config: BaseConfig = {
+    name: 'AbstractControl',
+    refs: ['button'],
+  };
+}
+```
+
+## Compiler options
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "experimentalDecorators": false,
+    "useDefineForClassFields": true,
+    "strict": true
+  }
+}
+```
+
+Stage-3 decorators need no flag on TypeScript 5. `experimentalDecorators` must be **off**.
+
+## JSDoc
+
+The props type works from JSDoc too, for a project with no `.ts` files:
+
+```js
+/**
+ * @extends {Base<{ $refs: { output: HTMLElement }, $options: { step: number } }>}
+ */
+class Counter extends Base {
+  static config = {
+    name: 'Counter',
+    refs: ['output'],
+    options: { step: { type: Number, default: 1 } },
+  };
+}
+```

package/skills/studiometa-js-toolkit/references/guide/going-further/using-decorators.md

@@ -0,0 +1,168 @@
+# Decorators
+
+**Every decorator is a thin wrapper over a function API that works without it.** No engine ships stage-3 decorators, so a page that loads the package from an ESM CDN keeps `registerComponent`, `$provide`, `$watchChildren`, `$read`, `$write` and the `on<Child><Event>` method names.
+
+Decorators are sugar. They are never a requirement.
+
+## The six
+
+| Decorator                           | Wraps                                   | Notes                                                                           |
+| ----------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
+| `@component({ name })`              | `static config` + `registerComponent()` | Registers as soon as the class is defined.                                      |
+| `@on(target, type)` / `@on(type)`   | the `on<Child><Event>` names            | The target is a name or a value.                                                |
+| `@provide(key)` / `@inject(key)`    | `$provide()` / `$inject()`              | The shape of Lit's `@provide` and `@consume`.                                   |
+| `@children(nameOrClass, callbacks)` | `$watchChildren()`                      | Exact name, or constructor and subclasses. Callbacks are bound to the instance. |
+| `@read` / `@write`                  | `$read()` / `$write()`                  | Runs the method body in that phase, cancelled on unmount.                       |
+
+Each value decorator works on a plain field and on an `accessor` field.
+
+## A component with decorators
+
+```ts
+import {
+  Base,
+  children,
+  component,
+  on,
+  type ChildrenCollection,
+  type DelegatedEvent,
+} from '@studiometa/js-toolkit';
+
+@component({ name: 'AccordionItem' })
+class AccordionItem extends Base<{ $emits: { open: void } }> {
+  @on('click')
+  toggle() {
+    this.$emit('open');
+  }
+}
+
+@component({ name: 'Accordion', components: { AccordionItem } })
+class Accordion extends Base {
+  @children(AccordionItem)
+  items!: ChildrenCollection<AccordionItem>;
+
+  @on(AccordionItem, 'open')
+  closeOthers({ target }: DelegatedEvent<AccordionItem, 'open'>) {
+    for (const item of this.items) {
+      if (item !== target) item.$el.removeAttribute('data-option-open');
+    }
+  }
+}
+```
+
+## `@component` and `static config` merge
+
+They merge in a class initializer, which runs after the fields and inside the class definition, so `registerComponent()` on the next line reads the finished config. The rules are the rules of `$config`: `refs` union, `options` and `components` merge entry by entry, a declared value overrides.
+
+A key both sides declare differently is reported as `component.config-conflict`.
+
+**The decorator is applied last**, so it registers a finished class.
+
+## `@on` — a name or a value
+
+```ts
+import { Base, component, on } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base {
+  static config = { name: 'AccordionItem' };
+}
+@component({ name: 'Demo', components: { AccordionItem }, refs: ['dots[]'] })
+class Demo extends Base {
+  @on('click') a(event: MouseEvent) {} // own element, typed from HTMLElementEventMap
+  @on('submit') b(event: SubmitEvent) {} // idem
+  @on('dots[]', 'click') c() {} // a ref, named as declared
+  @on('AccordionItem', 'open') d() {} // a child, by name — imports nothing
+  @on(AccordionItem, 'open') e() {} // a child, by class — the class is the type
+  @on(window, 'load') f() {} // a global
+  @on(document, 'click') g() {} // a global
+}
+```
+
+- **The one-argument form types its event from `HTMLElementEventMap`**, so `@on('click')` hands over a `MouseEvent` and `@on('submit')` a `SubmitEvent`. A name outside that map is a component event, whose detail only its emitter knows, so the handler declares the type it expects: `@on('content') inject(event: CustomEvent<{ content: string }>)`.
+- **A class resolves to its merged `config.name`** and lands on the same delegated entry as the string form. The class is the type, so `target` is the component and `payload` comes from its `$emits`.
+- **A lazy child needs the string form.** `@on('Child', 'open')` imports nothing; a thunk is not a target and both the overloads and the runtime refuse it.
+- **A name is a child or a ref**, resolved children-first, so the handler is typed as `DelegatedEvent` or `RefEvent`.
+- **A ref is named as it is declared**: `@on('dots[]', 'click')` for `config.refs: ['dots[]']`. A mismatched `@on('dots', 'click')` warns at bind time when the other spelling is declared. A name that matches nothing stays silent.
+- **A global target goes through the same binding `onWindow<Event>` uses**: bubble phase, one listener per mount cycle, removed by `$unmount()`. `@on(window, 'click')` types the event from `WindowEventMap` and falls back to `Event`.
+- **Nothing is reserved in its string space**: `'Window'` means the child and `window` means the global.
+- **Any other `EventTarget` is refused**, by the overloads and by a `TypeError`. A decorator is evaluated once, at class definition, so an arbitrary target can only be a module-scope value.
+
+## `@read` and `@write`
+
+They are **leaf-method sugar: the phase belongs to the call site.**
+
+```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`);
+  }
+}
+```
+
+**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.
+
+### Stacking with `@on`
+
+The skip is keyed by the method name, so `@on` and `@read`/`@write` stack in either order. The order decides what the listener calls:
+
+- a phase decorator written **below** the `@on`, nearest the method, schedules the body of the handler;
+- one written **above** it schedules direct calls only.
+
+Write `@read` and `@write` closest to the method body.
+
+## Build setup
+
+Vite 8 transforms TypeScript with Oxc, which passes decorators through untouched. The package itself compiles them with `@rollup/plugin-swc` and `decoratorVersion: '2023-11'`, filtered to the files that contain a decorator. See [Installation](../introduction/installation.md#with-a-build-step).
+
+## The same component, without any of them
+
+```ts
+import { Base, registerComponent, type DelegatedEvent } from '@studiometa/js-toolkit';
+
+class AccordionItem extends Base<{ $emits: { open: void } }> {
+  static config = { name: 'AccordionItem' };
+
+  onClick() {
+    this.$emit('open');
+  }
+}
+
+class Accordion extends Base {
+  static config = {
+    name: 'Accordion',
+    components: { AccordionItem },
+  };
+
+  items = this.$watchChildren(AccordionItem);
+
+  onAccordionItemOpen({ target }: DelegatedEvent<AccordionItem, 'open'>) {
+    for (const item of this.items) {
+      if (item !== target) item.$el.removeAttribute('data-option-open');
+    }
+  }
+}
+
+registerComponent(Accordion);
+```

package/skills/studiometa-js-toolkit/references/guide/going-further/using-storage.md

@@ -0,0 +1,125 @@
+# Storage
+
+`createStorage()` is a typed, observable key-value store over a `StorageProvider`. **One seam, six adapters.**
+
+## The store
+
+```ts
+import { createLocalStorage } from '@studiometa/js-toolkit';
+
+interface Prefs {
+  theme: 'light' | 'dark';
+  seen: string[];
+}
+
+const prefs = createLocalStorage<Prefs>({ prefix: 'app:' });
+
+prefs.set('theme', 'dark');
+prefs.get('theme'); // 'light' | 'dark' | undefined
+prefs.get('theme', 'light'); // 'light' | 'dark'
+prefs.has('seen');
+prefs.keys();
+prefs.delete('seen');
+prefs.clear();
+```
+
+`createStorage()` owns everything a consumer thinks of as storage: key namespacing through `prefix`, serialization in both directions, a `Signal` per key created on the first subscription, and the reference-counted wiring that keeps keys in sync. **A provider moves strings only.**
+
+## Observing a key
+
+```ts
+import { createLocalStorage } from '@studiometa/js-toolkit';
+
+interface Prefs {
+  theme: 'light' | 'dark';
+}
+const prefs = createLocalStorage<Prefs>();
+const unsubscribe = prefs.subscribe(
+  'theme',
+  (value) => {
+    document.documentElement.dataset.theme = value ?? 'light';
+  },
+  { immediate: true },
+);
+```
+
+`destroy()` releases every subscription and the shared listeners at once.
+
+In a component, hand the unsubscribe back from `mounted()`:
+
+```js
+mounted() {
+  return prefs.subscribe('theme', (value) => this.apply(value));
+}
+```
+
+## The six adapters
+
+| Adapter                                                   | Backed by                                              |
+| --------------------------------------------------------- | ------------------------------------------------------ |
+| `localStorageProvider`                                    | `localStorage`                                         |
+| `sessionStorageProvider`                                  | `sessionStorage`                                       |
+| `memoryStorageProvider` / `createMemoryStorageProvider()` | a `Map`                                                |
+| `createFallbackProvider(...providers)`                    | reads from the first that holds the key, writes to all |
+| `urlSearchParamsProvider`                                 | `location.search`                                      |
+| `urlSearchParamsInHashProvider`                           | `location.hash`, read as search params                 |
+
+The two URL adapters rebuild the whole location on each write, so a search write keeps the hash and a hash write keeps the query string. They take one option, `push`, which chooses `history.pushState` over the default `replaceState`.
+
+Four presets remove an argument from every call site: `createLocalStorage()`, `createSessionStorage()`, `createUrlSearchParamsStorage()` and `createUrlSearchParamsInHashStorage()`.
+
+**A factory exists only where its product has state**
+
+`createMemoryStorageProvider()` holds a `Map`. `createFallbackProvider()` and the two URL factories take arguments. There is no `createLocalStorageProvider()` — the instance is enough.
+
+## Failures are diagnostics, never throws
+
+**A built-in provider reports its own failures and never throws.** A full quota or a refused storage area becomes a `storage.access-failed` diagnostic and the method returns its fallback: `null`, `false`, `[]` or `undefined`. It reports once per operation, not once per area.
+
+The store's own failures have their own codes:
+
+- `storage.serialize-failed` — nothing is written.
+- `storage.deserialize-failed` — the default is returned.
+
+`types.ts` states the same contract for a custom provider.
+
+## Syncing with the outside
+
+`syncEvents` is a list of window event names and nothing more. A provider declares how a change made outside this instance announces itself:
+
+| Provider          | `syncEvents`             |
+| ----------------- | ------------------------ |
+| web storage       | `storage` (another tab)  |
+| URL search params | `popstate`               |
+| URL hash          | `popstate`, `hashchange` |
+
+`createStorage()` subscribes **one shared, reference-counted listener per name** while at least one key is observed, and re-reads every observed key when it fires. The event carries no usable state, so the subscriber re-reads.
+
+**A known gap**
+
+A provider whose changes arrive on a `BroadcastChannel` or through an observer has no way to announce them yet.
+
+## A custom backend
+
+Six synchronous string methods, plus an optional `syncEvents`:
+
+```ts
+import { createStorage, type StorageProvider } from '@studiometa/js-toolkit';
+
+const cookieProvider: StorageProvider = {
+  get: (key) => new URLSearchParams(document.cookie.replaceAll('; ', '&')).get(key),
+  set: (key, value) => {
+    document.cookie = `${key}=${value};path=/`;
+  },
+  remove: (key) => {
+    document.cookie = `${key}=;path=/;max-age=0`;
+  },
+  has: (key) => document.cookie.includes(`${key}=`),
+  keys: () => [...new URLSearchParams(document.cookie.replaceAll('; ', '&')).keys()],
+  clear: () => {},
+};
+
+const store = createStorage({ provider: cookieProvider });
+```
+
+One storage instance runs in Node over the memory provider, which is what `test/package-node-consumer.js` exercises.

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

@@ -0,0 +1,163 @@
+# Getting Started
+
+`@studiometa/js-toolkit` v4 is a data-attributes driven micro-framework. You write classes, you add `data-*` attributes to your HTML, and one registry mounts the two together.
+
+One sentence carries the whole design:
+
+> **The registry is the framework. The DOM is the component tree.**
+
+An instance exists because its element is in the document **and** its class is registered. Nothing else creates or unmounts an instance.
+
+## Installation
+
+```bash
+npm install @studiometa/js-toolkit@next
+```
+
+## Hello world
+
+Declare the component in the markup with `data-component`, and expose the elements it needs with `data-ref`:
+
+```html
+<div data-component="Hello">
+  <button data-ref="btn">Say hello</button>
+</div>
+<script type="module" src="./main.js"></script>
+```
+
+Write the class, and register it:
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+
+class Hello extends Base {
+  static config = {
+    name: 'Hello',
+    refs: ['btn'],
+  };
+
+  onBtnClick() {
+    alert('Hello, world!');
+  }
+}
+
+registerComponent(Hello);
+```
+
+That is the whole setup. `registerComponent()` puts the name in the registry, and every `[data-component="Hello"]` element in the document gets an instance — including the elements added to the page afterwards, by a template, a `fetch` or another component.
+
+## The four things to know
+
+### 1. Mount and unmount follow the element
+
+The element enters the document, the instance mounts. The element leaves, the instance unmounts and stays on its element, ready for a re-insertion. A **move** is one unmount and one mount of the same instance, exactly like `disconnectedCallback` and `connectedCallback` on a custom element.
+
+There is no third state. A component never declares that its work is over.
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Once extends Base {
+  static config = { name: 'Once' };
+
+  hasLoaded = false;
+
+  mounted() {
+    if (this.hasLoaded) return;
+    // … the work that must run once per element
+    this.hasLoaded = true;
+  }
+}
+```
+
+Read more in [Lifecycle](introduction/lifecycle-hooks.md).
+
+### 2. Refs are live, and handlers are delegated
+
+Each `$refs` property reads the DOM on access, so markup that arrives later is found with no refresh and no `$update()`. `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 List extends Base {
+  static config = {
+    name: 'List',
+    refs: ['items[]'], // the `[]` is part of the attribute: data-ref="items[]"
+  };
+
+  onItemsClick({ index }) {
+    console.log(`clicked item ${index}`);
+  }
+}
+```
+
+Read more in [Refs](introduction/managing-refs.md).
+
+### 3. Options are a read-only view over the attributes
+
+An option is an **input**, never a store. Every property of `$options` is a getter that derives its value from the element and the viewport on each access.
+
+```html
+<div data-component="Grid" data-option-columns="1" data-option-columns:l="4"></div>
+```
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Grid extends Base {
+  static config = {
+    name: 'Grid',
+    options: {
+      columns: { type: Number, default: 1 },
+    },
+  };
+
+  mounted() {
+    console.log(this.$options.columns); // 1, or 4 from the `l` breakpoint up
+  }
+}
+```
+
+Every option is responsive with no flag to declare, and to change one you write the attribute. Read more in [Options](introduction/managing-options.md).
+
+### 4. Children announce themselves, parents listen
+
+A child never reaches for its parent. It emits, and the parent hears it through the `on<Child><Event>` convention, resolved against the names in `config.components`:
+
+```ts
+import { Base, type DelegatedEvent } from '@studiometa/js-toolkit';
+
+class SliderItem extends Base<{ $emits: { select: { index: number } } }> {
+  static config = { name: 'SliderItem' };
+
+  onClick() {
+    this.$emit('select', { index: 0 });
+  }
+}
+
+class Slider extends Base {
+  static config = {
+    name: 'Slider',
+    components: { SliderItem },
+  };
+
+  onSliderItemSelect({ payload }: DelegatedEvent<SliderItem, 'select'>) {
+    console.log(payload.index);
+  }
+}
+```
+
+`$emit()` dispatches a real, bubbling `CustomEvent`, so a plain listener hears it too.
+
+**A handler named by convention is not typed by convention**
+
+The `on<Child><Event>` name is resolved at runtime, so TypeScript cannot infer the parameter for you. Annotate it with `DelegatedEvent`, `RefEvent` or `GlobalEvent`. The [`@on` decorator](../api/decorators/on.md) does not remove the annotation either — it checks it against a real target.
+
+Read more in [Events](introduction/working-with-events.md).
+
+## Where to go next
+
+- [Installation](introduction/installation.md) — build tools, CDN and the subpath layout.
+- [Components](introduction/managing-components.md) — declaring, registering and nesting components.
+- [Philosophy](concepts/philosophy.md) — why one registry, and what was removed to get it.
+- [Migrating from v3](migration/v3-to-v4.md) — every breaking change, with the replacement for each.