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

package/skills/studiometa-js-toolkit/references/api/services/useWindowScroll.md

@@ -0,0 +1,25 @@
+# useWindowScroll
+
+```ts
+useWindowScroll(): Service<ScrollProps>
+```
+
+The page scroll. It names the default case of [`useScroll()`](useScroll.md), and it is the same instance as `useScroll()` and `useScroll(document.documentElement)`.
+
+## Usage
+
+```js
+import { useWindowScroll } from '@studiometa/js-toolkit';
+
+const unsubscribe = useWindowScroll().subscribe(({ y, progressY }) => {
+  document.documentElement.style.setProperty('--scroll-progress', String(progressY));
+});
+```
+
+Props, coalescing and extent observation are [`useScroll()`](useScroll.md)'s.
+
+## Why it exists
+
+`useScroll()` already defaults to the document element, so this export adds no behaviour. It adds a **name**: a call site that means "the page" says so, instead of relying on a reader knowing what the default argument is.
+
+`useWindowSize()` is the same idea for [`useResize()`](useResize.md).

package/skills/studiometa-js-toolkit/references/api/services/useWindowSize.md

@@ -0,0 +1,25 @@
+# useWindowSize
+
+```ts
+useWindowSize(): Service<ResizeProps>
+```
+
+The viewport size. It names the default case of [`useResize()`](useResize.md).
+
+## Usage
+
+```js
+import { useWindowSize } from '@studiometa/js-toolkit';
+
+const unsubscribe = useWindowSize().subscribe(({ width, height, orientation }) => {
+  console.log(width, height, orientation);
+});
+```
+
+Props are [`useResize()`](useResize.md)'s.
+
+## The viewport is not an observed box
+
+A `ResizeObserver` reports the box of the element it observes. For the root element, `clientWidth` and `clientHeight` report the **viewport** and are decoupled from that box, so this service keeps a `resize` listener beside the observer.
+
+That is the difference between asking for the window and asking for an element that happens to be full-width.

package/skills/studiometa-js-toolkit/references/api/storage/createStorage.md

@@ -0,0 +1,126 @@
+# createStorage
+
+```ts
+createStorage<T extends object = Record<string, unknown>>(options?: StorageOptions): StorageInstance<T>
+```
+
+A typed, observable key-value store.
+
+```ts
+interface StorageOptions {
+  provider?: StorageProvider;
+  serializer?: StorageSerializer;
+  prefix?: string;
+}
+```
+
+## Usage
+
+```ts
+import { createStorage, memoryStorageProvider } from '@studiometa/js-toolkit';
+
+interface Prefs {
+  theme: 'light' | 'dark';
+  seen: string[];
+}
+
+const prefs = createStorage<Prefs>({
+  provider: memoryStorageProvider,
+  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();
+prefs.destroy();
+```
+
+## The instance
+
+```ts
+interface StorageInstance<T extends object = Record<string, unknown>> {
+  get<K extends keyof T>(key: K): T[K] | undefined;
+  get<K extends keyof T>(key: K, defaultValue: T[K]): T[K];
+  set<K extends keyof T>(key: K, value: T[K]): void;
+  delete<K extends keyof T>(key: K): void;
+  has<K extends keyof T>(key: K): boolean;
+  keys(): (keyof T)[];
+  clear(): void;
+  subscribe<K extends keyof T>(
+    key: K,
+    callback: (value: T[K] | undefined) => void,
+    options?: { immediate?: boolean },
+  ): () => void;
+  destroy(): void;
+}
+```
+
+The two `get` overloads are the whole difference between "it may not be there" and "here is what to use if it is not".
+
+## Observing a key
+
+```ts
+import { createStorage } from '@studiometa/js-toolkit';
+
+interface Prefs {
+  theme: 'light' | 'dark';
+}
+const prefs = createStorage<Prefs>();
+const unsubscribe = prefs.subscribe(
+  'theme',
+  (value) => {
+    document.documentElement.dataset.theme = value ?? 'light';
+  },
+  { immediate: true },
+);
+```
+
+A [`Signal`](../context/signal.md) is created **per key, on the first subscription**, so a store nobody observes holds nothing.
+
+In a component, hand the unsubscribe back from `mounted()`:
+
+```js
+mounted() {
+  return prefs.subscribe('theme', (value) => this.apply(value));
+}
+```
+
+## `destroy()`
+
+Releases every subscription and the shared sync listeners at once. A store that outlives the page needs no call; a store scoped to a component does.
+
+## `prefix`
+
+Namespaces every key in the underlying provider, so two stores can share one backing area without colliding. The prefix is the store's business — a provider never sees an unprefixed key and never adds one.
+
+## `serializer`
+
+```ts
+interface StorageSerializer {
+  serialize(value: unknown): string;
+  deserialize(value: string): unknown;
+}
+```
+
+Defaults to `jsonSerializer`. Failures are reported, not thrown:
+
+- `storage.serialize-failed` — **nothing is written**;
+- `storage.deserialize-failed` — the default is returned.
+
+## Syncing with the outside
+
+`syncEvents` on the provider is a list of window event names and nothing more. `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 rather than trusting a payload.
+
+**A known gap**
+
+A provider whose changes arrive on a `BroadcastChannel` or through an observer has no way to announce them yet.
+
+## In Node
+
+One storage instance runs in Node over the memory provider, which is what `test/package-node-consumer.js` exercises. Nothing in the store touches `window` unless a provider's `syncEvents` asks for it.

package/skills/studiometa-js-toolkit/references/api/storage/index.md

@@ -0,0 +1,33 @@
+# Storage
+
+**One seam, six adapters.** `createStorage()` is a typed, observable key-value store over a `StorageProvider`.
+
+## The exports
+
+- [`createStorage(options?)`](createStorage.md) — the store
+- [Presets](presets.md) — `createLocalStorage()`, `createSessionStorage()`, `createUrlSearchParamsStorage()`, `createUrlSearchParamsInHashStorage()`
+- [Providers](providers.md) — the six adapters, and how to write one
+
+## The division of labour
+
+**`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 observed keys in sync.
+
+**A provider moves strings only** — six synchronous methods, plus an optional list of window event names.
+
+```
+consumer  →  StorageInstance<T>   typed, observable, prefixed, serialized
+                    ↓
+             StorageProvider      get/set/remove/has/keys/clear + syncEvents
+                    ↓
+              localStorage, a Map, location.search, …
+```
+
+That is why a custom backend is six small methods, and why one storage instance runs in Node over the memory provider.
+
+## Failures are diagnostics, never throws
+
+A built-in provider turns a full quota or a refused area into a `storage.access-failed` diagnostic and returns the method's fallback: `null`, `false`, `[]` or `undefined`. The store's own failures are `storage.serialize-failed` — after which nothing is written — and `storage.deserialize-failed` — after which the default is returned.
+
+## Read next
+
+[Storage](../../guide/going-further/using-storage.md).

package/skills/studiometa-js-toolkit/references/api/storage/presets.md

@@ -0,0 +1,58 @@
+# Storage presets
+
+Four presets that each remove an argument from every call site.
+
+```ts
+createLocalStorage<T>(options?): StorageInstance<T>
+createSessionStorage<T>(options?): StorageInstance<T>
+createUrlSearchParamsStorage<T>(options?): StorageInstance<T>
+createUrlSearchParamsInHashStorage<T>(options?): StorageInstance<T>
+```
+
+Their options are [`createStorage()`](createStorage.md)'s **without `provider`** — the preset supplies it. The two URL presets also take `push`.
+
+## Usage
+
+```ts
+import {
+  createLocalStorage,
+  createSessionStorage,
+  createUrlSearchParamsInHashStorage,
+  createUrlSearchParamsStorage,
+} from '@studiometa/js-toolkit';
+
+interface Prefs {
+  theme: 'light' | 'dark';
+}
+
+createLocalStorage<Prefs>({ prefix: 'app:' });
+createSessionStorage<Prefs>();
+createUrlSearchParamsStorage<Prefs>({ push: true });
+createUrlSearchParamsInHashStorage<Prefs>();
+```
+
+## `push`
+
+The two URL presets choose `history.pushState` over the default `replaceState`:
+
+| `push`  | Each write                 |
+| ------- | -------------------------- |
+| `false` | replaces the current entry |
+| `true`  | adds a history entry       |
+
+`true` is what makes a filter state navigable with the back button. `false` is what keeps a scroll position or a tab index out of the history.
+
+## Which URL preset
+
+| Preset                                 | Reads and writes           | Survives                                 |
+| -------------------------------------- | -------------------------- | ---------------------------------------- |
+| `createUrlSearchParamsStorage()`       | `location.search`          | a share, a bookmark, the server          |
+| `createUrlSearchParamsInHashStorage()` | `location.hash`, as params | a share and a bookmark, never the server |
+
+Both rebuild the **whole location** on each write, so a search write keeps the hash and a hash write keeps the query string.
+
+## Why only these four
+
+**A factory exists only where its product has state.** These four each replace an argument at every call site, which is worth an export. `createLocalStorageProvider()` and `createSessionStorageProvider()` are **removed** — the instances say the same thing with nothing to call.
+
+See [Providers](providers.md).

package/skills/studiometa-js-toolkit/references/api/storage/providers.md

@@ -0,0 +1,109 @@
+# Storage providers
+
+A provider moves **strings only**.
+
+```ts
+interface StorageProvider {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+  has(key: string): boolean;
+  keys(): string[];
+  clear(): void;
+  syncEvents?: readonly string[];
+}
+```
+
+## The six adapters
+
+| Adapter                                                                           | Backed by                                              | `syncEvents`             |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |
+| `localStorageProvider`                                                            | `localStorage`                                         | `storage`                |
+| `sessionStorageProvider`                                                          | `sessionStorage`                                       | `storage`                |
+| `memoryStorageProvider` / `createMemoryStorageProvider()`                         | a `Map`                                                | —                        |
+| `createFallbackProvider(...providers)`                                            | reads from the first that holds the key, writes to all | the union                |
+| `urlSearchParamsProvider` / `createUrlSearchParamsProvider(options?)`             | `location.search`                                      | `popstate`               |
+| `urlSearchParamsInHashProvider` / `createUrlSearchParamsInHashProvider(options?)` | `location.hash`, as params                             | `popstate`, `hashchange` |
+
+```ts
+import {
+  createFallbackProvider,
+  createMemoryStorageProvider,
+  createStorage,
+  localStorageProvider,
+  memoryStorageProvider,
+} from '@studiometa/js-toolkit';
+
+// Try localStorage, fall back to memory when it is refused.
+createStorage({
+  provider: createFallbackProvider(localStorageProvider, memoryStorageProvider),
+});
+
+// A private Map, not the shared singleton.
+createStorage({ provider: createMemoryStorageProvider() });
+```
+
+**The memory singleton is shared**
+
+`memoryStorageProvider` is one `Map` for the whole page. Two stores over it see each other's keys unless they use different prefixes. For a store per component, use `createMemoryStorageProvider()`.
+
+## `createFallbackProvider()`
+
+Reads from the **first provider that holds the key** and writes to **all** of them. That is what makes "use localStorage where it works, memory where it does not" one line rather than a branch at every call site.
+
+## A factory exists only where its product has state
+
+| Has state or arguments                          | Does not                   |
+| ----------------------------------------------- | -------------------------- |
+| `createMemoryStorageProvider()` — a `Map`       | `localStorageProvider`     |
+| `createFallbackProvider(...)`                   | `sessionStorageProvider`   |
+| `createUrlSearchParamsProvider(options?)`       | `memoryStorageProvider`    |
+| `createUrlSearchParamsInHashProvider(options?)` | the two bare URL instances |
+
+`createLocalStorageProvider()` and `createSessionStorageProvider()` are removed; the instances stay.
+
+## A built-in provider never throws
+
+`guard()` turns a full quota or a refused area into a `storage.access-failed` diagnostic and returns the method's fallback:
+
+| Method                   | Fallback    |
+| ------------------------ | ----------- |
+| `get`                    | `null`      |
+| `has`                    | `false`     |
+| `keys`                   | `[]`        |
+| `set`, `remove`, `clear` | `undefined` |
+
+It reports **once per operation**, not once per area. **The area is resolved per call, inside the guard**, because the getter itself throws when storage is denied — `localStorage` in a blocked third-party frame throws on access, not on use.
+
+`types.ts` states the same contract for a custom provider: report, return the fallback, do not throw.
+
+## The URL adapters
+
+They **rebuild the whole location on each write**, so a search write keeps the hash and a hash write keeps the query string. Their one option is `push`, which chooses `history.pushState` over the default `replaceState`.
+
+## Writing your own
+
+```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 });
+```
+
+Six synchronous string methods. Namespacing, serialization, signals and sync wiring are [`createStorage()`](createStorage.md)'s — do none of it here.
+
+## Tested at the seam
+
+`providers.spec.ts` drives each adapter through the six methods for real, including a `setItem` that throws, an area getter that throws, `push` against `history.length`, and the `syncEvents` names of each adapter.

package/skills/studiometa-js-toolkit/references/api/test/index.md

@@ -0,0 +1,214 @@
+# Test helpers
+
+```js
+import { mount, settle, waitFor } from '@studiometa/js-toolkit/test';
+```
+
+Nine helpers a component test cannot write for itself.
+
+## Why the subpath exists
+
+**The timing recipe is not derivable.** "Has this component mounted and finished its writes?" is answered by five rounds of a 10 ms timer followed by `defaultScheduler.whenIdle()`, and those two numbers encode the mount observer's delivery latency and the scheduler's lane order.
+
+Neither half works alone: `whenIdle()` can resolve before the observer has reported the element, and a timer can return between two lanes. `defaultScheduler` and `nextFrame` were already public, so the pieces shipped and the recipe did not.
+
+**It depends on no test framework.** Nothing in the module imports a runner, an assertion library or a spy; it reads the DOM and the scheduler only, so it runs under Vitest, under Playwright and on a plain browser page. That is also why it is not on the root barrel: a page has no use for it, and the root export count stays what it was.
+
+## `mount()`
+
+```ts
+mount(html: string): Promise<HTMLElement>
+```
+
+Inserts the markup and resolves once the eager components have mounted.
+
+```js
+const root = await mount(`
+  <button data-component="Counter">
+    <span data-ref="output">0</span>
+  </button>
+`);
+```
+
+**It returns the wrapper `div` it created**, never the markup's own root, so a fragment of several siblings works and `querySelector()` has a stable handle. `.firstElementChild` is one property away.
+
+## `settle()`
+
+```ts
+settle(): Promise<void>
+```
+
+Resolves once the framework has caught up — the same recipe `mount()` uses.
+
+**Not for a transition's end state**
+
+`settle()` is generous rather than deterministic. See [Transitions](#transitions) below.
+
+## `frames()`
+
+```ts
+frames(count?: number): Promise<void>
+```
+
+Awaits animation frames. `nextFrame()` with a count.
+
+## `waitFor()`
+
+```ts
+waitFor<T>(predicate: () => T | false | null | undefined, options?: { timeout?: number; message?: string }): Promise<T>
+```
+
+Polls until the predicate is truthy and **returns that value**, which makes the same call either a guard or a query:
+
+```js
+// a guard
+await waitFor(() => el.classList.contains('is-open'));
+
+// a query
+const panel = await waitFor(() => root.querySelector('.panel'));
+```
+
+It polls on a **10 ms cadence and drains the scheduler between attempts**. On timeout it throws — with the caller's `message`, or one naming the timeout.
+
+## `captureDiagnostics()`
+
+```ts
+captureDiagnostics(target?: EventTarget): { codes: string[]; entries: ToolkitDiagnosticDetail[]; stop(): void }
+```
+
+```js
+const diagnostics = captureDiagnostics();
+// … exercise the component
+expect(diagnostics.codes).toContain('ref.mismatch');
+diagnostics.stop();
+```
+
+**It reads the channel, and asserting on `console.warn` does not.** A recovered failure is reported on a cancelable event whose _default behaviour_ is the console line; a spy on that line cannot see the code, the severity or the reporting component, and it passes for the wrong diagnostic.
+
+The helper **cancels each event as it arrives**, which is the same act that suppresses the sink — so collecting and silencing are one step, not two, and no spy is involved.
+
+`target` defaults to `document`, which sees everything a connected element reported, because diagnostics bubble and compose.
+
+## `recordEvents()`
+
+```ts
+recordEvents(target: EventTarget, ...types: string[]): { events: { type: string; detail: unknown }[]; stop(): void }
+```
+
+```js
+const recording = recordEvents(el, 'open', 'opened');
+
+el.querySelector('button').click();
+
+await waitFor(() => recording.events.length === 2);
+expect(recording.events.map(({ type }) => type)).toEqual(['open', 'opened']);
+expect(recording.events[1].detail).toEqual({ height: 120 });
+
+recording.stop();
+```
+
+**It keeps the order and the payloads.** A component's contract is "`open` came before `opened`, and `opened` carried the height it measured", and a call-counting spy throws both away.
+
+Recording several types into one array is the only place their **relative order** is visible. The richer `{ type, detail }` shape ships because a caller wanting names alone can map, and the reverse is impossible.
+
+`$emit` dispatches synchronously but is almost never _called_ synchronously, so the count is awaited with `waitFor`, not read.
+
+## `countRequestedFrames()`
+
+```ts
+countRequestedFrames(during: () => Promise<void> | void): Promise<number>
+```
+
+```js
+const frames = await countRequestedFrames(async () => {
+  for (let i = 0; i < 10; i += 1) el.dispatchEvent(new Event('scroll'));
+  await settle();
+});
+expect(frames).toBeLessThan(3);
+```
+
+**It patches a global, and says so.** It swaps `globalThis.requestAnimationFrame` for a counting wrapper that forwards to the original, and restores it in a `finally` — so it comes back whether `during` returns or throws.
+
+It is here despite the patch because the assertion it serves, "this did not schedule a frame per event", has no other seam: the framework's own scheduler makes the calls, so there is nothing of the component's for a spy to sit on.
+
+**Two concurrent calls would nest their wrappers. Do not.**
+
+## `resetDom()`
+
+```ts
+resetDom(): Promise<void>
+```
+
+Empties the document body and lets the teardown run.
+
+## `resetRegistry()`
+
+```ts
+resetRegistry(): void
+```
+
+**The inverse `registerComponent()` deliberately lacks.** A page registers once and keeps it; a test suite is the one caller for which a page-wide registry surviving `resetDom()` is wrong, and the workaround it forces is a counter minting `Widget-1`, `Widget-2`.
+
+It is **coarse on purpose**: the element→controller map is a `WeakMap`, so it cannot be enumerated, nothing can walk it to dispose live triggers, and a `querySelectorAll()` sweep would still miss detached elements. Clearing everything works because the mutation-observer path already disposes a controller as its element leaves the DOM — **hence the call belongs after `resetDom()`**.
+
+Two things it does not do: it cannot clear that `WeakMap`, so empty the DOM first; and it does not narrow the attribute filter the shared observer built from everything ever registered — an extra watched attribute costs a reconciliation pass that finds no owner, and nothing more.
+
+**Never in an `afterEach`**
+
+Spec files register at module top level, so this in an `afterEach` silently unregisters everything for every later test in the file. Put it in an `afterAll`, or call it and register again straight away:
+
+```js
+afterEach(async () => {
+  await resetDom();
+  resetRegistry();
+  registerComponents(Subject, Emitter);
+});
+```
+
+## Transitions {#transitions}
+
+**A transition's end state is asserted by polling, never by `settle()`.** A method that starts a transition does not hand it back, and a kept end state lands only after `nextFrame()`, the `from` and `active` states, and either a `transitionend` or one more frame. `settle()` is generous rather than deterministic, which is a flake that passes alone and fails under load.
+
+**Polling for an _absence_ is wrong** for the mirror-image reason: `leaveTransition()` clears the other direction's `to` state synchronously, so the poll passes before anything has happened.
+
+## What is deliberately not in it
+
+An instance lookup — [`getInstance()`](../registry/getInstance.md) and [`getInstances()`](../registry/getInstances.md) on the root barrel answer it — fetch stubs, and pointer sequences. Each is either specific to one spec or already served by `vi.fn()` and `@vitest/browser`'s `userEvent`.
+
+## A full example
+
+```js
+import { afterAll, expect, test } from 'vitest';
+import { Base, registerComponent } from '@studiometa/js-toolkit';
+import { mount, resetDom, resetRegistry, waitFor } from '@studiometa/js-toolkit/test';
+
+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);
+
+test('it counts clicks', async () => {
+  const root = await mount(`
+    <button data-component="Counter">
+      <span data-ref="output">0</span>
+    </button>
+  `);
+
+  root.querySelector('button').click();
+
+  await waitFor(() => root.querySelector('[data-ref="output"]').textContent === '1');
+});
+
+afterAll(async () => {
+  await resetDom();
+  resetRegistry();
+});
+```