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

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
+```

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