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

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.

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

@@ -0,0 +1,144 @@
+# Installation
+
+```bash
+npm install @studiometa/js-toolkit@next
+```
+
+**The `next` tag is not optional yet**
+
+4.0 is still a prerelease, so it publishes to the `next` dist-tag. Plain `npm install @studiometa/js-toolkit` installs 3.x, which is a different framework — the tag is what selects this one. `next` becomes `latest` when 4.0.0 ships.
+
+## Importing
+
+The root barrel carries everything a page normally needs:
+
+```js
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+```
+
+Utilities live on `/utils`:
+
+```js
+import { clamp, damp } from '@studiometa/js-toolkit/utils';
+```
+
+Test helpers live on `/test`:
+
+```js
+import { mount, settle } from '@studiometa/js-toolkit/test';
+```
+
+### One subpath per export
+
+Every public export also has a subpath of its own — 197 of them. The barrel is convenient; the subpath is precise:
+
+```js
+import { Base } from '@studiometa/js-toolkit/Base';
+import { useScroll } from '@studiometa/js-toolkit/useScroll';
+import { clamp } from '@studiometa/js-toolkit/utils/clamp';
+```
+
+Which one to reach for depends on how the code is delivered:
+
+- **With a bundler**, prefer the barrel. Tree-shaking removes what you do not import, and the barrel keeps the import lines short.
+- **From an ESM CDN, with no build step**, prefer the subpath. There is no bundler to shake the graph, so a barrel import downloads the barrel's whole module graph before the first line of your code runs.
+
+The subpath layout is what keeps a dependency contained. `morphdom` is reachable through [`swap()`](../../api/dom/swap.md) only, so a page that never swaps content never downloads it.
+
+## No build step
+
+v4 needs no compiler. Every decorator is sugar over a function that works without it, so a page loaded from an ESM CDN keeps the whole framework:
+
+```html
+<script type="module">
+  import { Base } from 'https://esm.sh/@studiometa/js-toolkit@next/Base';
+  import { registerComponent } from 'https://esm.sh/@studiometa/js-toolkit@next/registerComponent';
+
+  class Counter extends Base {
+    static config = { name: 'Counter', refs: ['output'] };
+
+    count = 0;
+
+    onClick() {
+      this.count += 1;
+      this.$refs.output.textContent = String(this.count);
+    }
+  }
+
+  registerComponent(Counter);
+</script>
+```
+
+## With a build step
+
+### Vite
+
+Nothing to configure for the framework itself. Vite 8 transforms TypeScript with Oxc, which passes decorators through untouched — so if you use the [decorators](../going-further/using-decorators.md), add a transform that compiles them:
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import swc from '@rollup/plugin-swc';
+
+export default defineConfig({
+  plugins: [
+    {
+      ...swc({ swc: { jsc: { target: 'es2022', transform: { decoratorVersion: '2023-11' } } } }),
+      // Compile only the files that contain a decorator.
+      enforce: 'pre',
+    },
+  ],
+});
+```
+
+### TypeScript
+
+Stage-3 decorators need no flag on TypeScript 5. Turn `experimentalDecorators` **off**:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "experimentalDecorators": false,
+    "useDefineForClassFields": true,
+    "strict": true
+  }
+}
+```
+
+See [TypeScript](../going-further/typing-components.md) for how to type a component's refs, options and events.
+
+## Autoloading
+
+A page that declares its components in the markup does not have to import them all up front. Map each `data-component` token to a dynamic import and the registry downloads a chunk when an element needs it:
+
+```js
+import { registerManifest } from '@studiometa/js-toolkit';
+
+registerManifest({
+  Accordion: () => import('./components/Accordion.js'),
+  Map: { load: () => import('./components/Map.js'), mountStrategy: 'visible' },
+});
+```
+
+See [Autoloading](../going-further/autoloading.md).
+
+## Agent skills
+
+The package ships the `studiometa-js-toolkit` [agent skill](https://agentskills.io). It teaches coding agents the v4 API and holds the documentation of the installed version, so an agent does not write v3 code. Link it into your project with the [`skills` CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills experimental_sync
+```
+
+The command links the skills of your dependencies from `node_modules` into the agent folders (`.agents/skills/`, `.claude/skills/`…). `@studiometa/ui` asks the CLI for this skill too, so a project that only lists `@studiometa/ui` also gets it.
+
+Without npm, install the skills from this website. It publishes them at `/.well-known/agent-skills/index.json`, as the [Agent Skills Discovery](https://specification.website/spec/agent-readiness/agent-skills-discovery/) convention defines:
+
+```bash
+npx skills add https://js-toolkit-v4.studiometa.dev
+```
+
+These skills match the version that this website documents, which can differ from the version that your project installs. Prefer `npx skills experimental_sync` in a project that installs the package.

package/skills/studiometa-js-toolkit/references/guide/introduction/lifecycle-hooks.md

@@ -0,0 +1,174 @@
+# Lifecycle
+
+**`mount` and `unmount` are the whole lifecycle.** There is no third, permanent notion: a component never declares that its work is over, and nothing marks an instance as never mountable again.
+
+## The two notions
+
+| Notion           | What it is                        | Effect                                                                                                             |
+| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **disconnected** | The element left the document.    | The registry calls `$unmount()`. The instance **stays on its element**, and a re-inserted element mounts it again. |
+| **unmount**      | The reversible opposite of mount. | Unbinds the cycle's listeners, runs the `mounted()` cleanups, cancels the scheduled tasks, calls `unmounted()`.    |
+
+A **move** gives one removal record and one addition record: the instance is unmounted and then mounted again, with the same identity, and the state of the cycle starts over. This is the behaviour of `disconnectedCallback` and `connectedCallback` for custom elements.
+
+**Unmounting a parent does not unmount its children.** Each element answers for itself.
+
+## `mounted()` and `unmounted()`
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Player extends Base {
+  static config = { name: 'Player' };
+
+  mounted() {
+    console.log('the element is in the document');
+  }
+
+  unmounted() {
+    console.log('the element left, or the declaration was withdrawn');
+  }
+}
+```
+
+## `mounted()` returns its cleanup
+
+`mounted()` can return a function, or an array of functions, sync or async. They run on the next `$unmount()`:
+
+```js
+import { Base, useScroll } from '@studiometa/js-toolkit';
+
+class Header extends Base {
+  static config = { name: 'Header' };
+
+  mounted() {
+    // `subscribe()` returns its own unsubscribe — hand it straight back.
+    return useScroll().subscribe(({ directionY }) => {
+      this.$el.classList.toggle('is-hidden', directionY > 0);
+    });
+  }
+}
+```
+
+Several cleanups: return an array.
+
+```js
+import { Base, useResize, useScroll } from '@studiometa/js-toolkit';
+
+class Sticky extends Base {
+  static config = { name: 'Sticky' };
+
+  mounted() {
+    return [useScroll().subscribe(() => {}), useResize().subscribe(() => {})];
+  }
+}
+```
+
+An async `mounted()` works the same way:
+
+```ts
+import { Base, createContext, type Signal } from '@studiometa/js-toolkit';
+
+const CountContext = createContext<Signal<number>>('count');
+
+class TodoCount extends Base {
+  static config = { name: 'TodoCount' };
+
+  async mounted() {
+    const signal = await this.$inject(CountContext);
+    // Released on unmount, even if the await resolved after it.
+    return signal.subscribe((count) => {
+      this.$el.textContent = String(count);
+    });
+  }
+}
+```
+
+If an async `mounted()` resolves **after** the unmount, the cleanup runs immediately.
+
+`unmounted()` stays available for the cases the returned cleanup does not fit.
+
+## What is unmount-scoped, and what is not
+
+| Registered in                             | Scope            | Released by                        |
+| ----------------------------------------- | ---------------- | ---------------------------------- |
+| a `mounted()` return value                | the mount cycle  | the next `$unmount()`              |
+| a pending `$inject()` request             | the mount cycle  | the next `$unmount()`              |
+| `on<X><Event>` handlers, service mixins   | the mount cycle  | the next `$unmount()`              |
+| `$read()` / `$write()` tasks              | the mount cycle  | the next `$unmount()` cancels them |
+| `$provide()` in a field initializer       | the **instance** | nothing — it dies with the element |
+| `$watchChildren()` in a field initializer | the **instance** | nothing — it dies with the element |
+
+A component whose declaration is withdrawn therefore keeps providing context until its element goes.
+
+## "Do this once per element"
+
+Because `$unmount()` leaves the instance on its element, **a plain field survives every move, re-insertion and `swap()` that preserves the element**. "Once per element" is instance state, not a lifecycle decision:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+
+class Reveal extends Base {
+  static config = { name: 'Reveal' };
+
+  hasRevealed = false;
+
+  mounted() {
+    if (this.hasRevealed) return;
+    this.$el.classList.add('is-revealed');
+    this.hasRevealed = true;
+  }
+}
+```
+
+What a field does **not** survive is an element that is genuinely replaced — which is exactly when the work should run again.
+
+## Withdrawing a declaration
+
+When an element stops declaring a component — the token leaves `data-component`, or a responsive declaration stops matching — the registry unmounts the instance and **drops it from the element**, so declaring the name again builds a new one.
+
+That is the registry rearranging its own bookkeeping. The instance only ever sees `$unmount()`.
+
+## Announcements
+
+Every instance dispatches a framework event on mount and on unmount, carrying itself in the payload:
+
+```ts
+import { EVENTS, type LifecycleEventDetail } from '@studiometa/js-toolkit';
+
+document.addEventListener(EVENTS.component.mounted, (event) => {
+  const { instance } = (event as CustomEvent<LifecycleEventDetail>).detail;
+  console.log(`${instance.$id} mounted`);
+});
+```
+
+- The **mount** event bubbles from the element, so any ancestor can follow its descendants with no declaration.
+- The **unmount** event dispatches from `document`, because the element can already be detached.
+- An instance that is scheduled but **not mounted** announces nothing.
+
+See [`$watchChildren()`](../../api/instance-methods.md#watchchildren) for the component-level API built on this.
+
+## Waiting for the DOM to settle
+
+`whenDOMSettled()` is the completion boundary for morphing, fetch updates and breakpoint crossings. It drains the pending mutation records, follows the mutation chains of eager lifecycle work, and resolves after the eager mounts and the teardown:
+
+```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.
+}
+```
+
+It does **not** wait for visibility, interaction, idle or media conditions, and it does not await the promises returned by `mounted()`. [`swap()`](../../api/dom/swap.md) awaits it for you.
+
+## Manual mounting
+
+`$mount()` and `$unmount()` are public, and calling them is legitimate — but on a page the registry does it, and doing it yourself is nearly always a sign that a [mount strategy](../going-further/mount-strategies.md) is the answer instead.
+
+```js
+instance.$unmount(); // reversible, the instance stays on its element
+instance.$mount(); // a new cycle, same identity
+```