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

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

@@ -0,0 +1,60 @@
+# useResize
+
+```ts
+useResize(target?: Element): Service<ResizeProps>
+```
+
+The size of one element. With no target it is the document element, which reports the viewport.
+
+## Props
+
+```ts
+interface ResizeProps {
+  readonly width: number;
+  readonly height: number;
+  readonly ratio: number;
+  readonly orientation: 'square' | 'landscape' | 'portrait';
+}
+```
+
+`breakpoints` and `activeBreakpoints` are removed — [`useBreakpoint()`](useBreakpoint.md) is their own source now.
+
+## Usage
+
+```js
+import { Base, useResize } from '@studiometa/js-toolkit';
+
+class Grid extends Base {
+  static config = { name: 'Grid' };
+
+  mounted() {
+    return useResize(this.$el).subscribe(({ width, orientation }) => {
+      this.$el.classList.toggle('is-narrow', width < 480);
+    });
+  }
+}
+```
+
+## A `ResizeObserver` does not see the viewport
+
+It reports the **box of the observed element**, which is what catches a zoom or a scrollbar. For the root element, `clientWidth` and `clientHeight` report the viewport and are decoupled from the observed box — so the viewport service keeps a `resize` listener as well.
+
+That is why `useResize()` with no target and `useResize(someElement)` are not the same kind of measurement, even though they share a props shape.
+
+## `{ immediate: true }` works here
+
+An element has a current size between deliveries.
+
+## Mixin
+
+```js
+class Grid extends withResize(Base) {
+  resized({ width }) {}
+}
+```
+
+`withResize` defaults to the page-wide source, as `withScroll` does. Scope it with `{ target: (instance) => instance.$el }`.
+
+## See also
+
+[`useWindowSize()`](useWindowSize.md) — the named default case.

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

@@ -0,0 +1,88 @@
+# useScroll
+
+```ts
+useScroll(target?: Element | Window): Service<ScrollProps>
+```
+
+Scroll position, movement and direction for one scroller. With no target it is the document element; `useScroll(document.documentElement)` is the window service.
+
+## Props
+
+```ts
+interface ScrollProps {
+  readonly x: number;
+  readonly y: number;
+  readonly deltaX: number;
+  readonly deltaY: number;
+  readonly maxX: number;
+  readonly maxY: number;
+  readonly progressX: number;
+  readonly progressY: number;
+  readonly directionX: -1 | 0 | 1;
+  readonly directionY: -1 | 0 | 1;
+  readonly isScrolling: boolean;
+}
+```
+
+Nothing derivable is a field: `lastX` is `x - deltaX`, and `changedX` is `deltaX !== 0`.
+
+## Usage
+
+```js
+import { Base, useScroll } from '@studiometa/js-toolkit';
+
+class Header extends Base {
+  static config = { name: 'Header' };
+
+  mounted() {
+    return useScroll().subscribe(({ y, directionY }) => {
+      this.$el.classList.toggle('is-hidden', directionY > 0 && y > 100);
+    });
+  }
+}
+```
+
+A region rather than the page:
+
+```js
+import { Base, useScroll } from '@studiometa/js-toolkit';
+
+class Panel extends Base {
+  static config = { name: 'Panel', refs: ['scroller'] };
+
+  mounted() {
+    return useScroll(this.$refs.scroller).subscribe(({ progressY }) => {
+      this.$el.style.setProperty('--progress', String(progressY));
+    });
+  }
+}
+```
+
+## One `read` per frame
+
+The service **coalesces its scroll events into one `read` per frame**, so a page scrolling at speed measures once per frame rather than once per event.
+
+## Extents are observed, not sampled once
+
+The service watches the scroller **and its element children** with a `ResizeObserver`, plus a `childList` MutationObserver to keep that set correct: `1 + n` observed boxes per scroller, lazy and released with the last subscriber.
+
+That is what keeps `maxY` and `progressY` correct when content is added, removed or resized.
+
+## `{ immediate: true }` works here
+
+A scroller has a current position between deliveries, so the first delivery is honoured. The first props of a run carry **no movement**: the deltas are zero and `directionX`/`directionY` are `0`.
+
+## Mixin
+
+```js
+class Header extends withScroll(Base) {
+  scrolled({ y, directionY }) {}
+}
+```
+
+`withScroll` defaults to the page-wide source. A region is `withScroll(Base, { target: (instance) => instance.$refs.scroller })`.
+
+## See also
+
+- [`useWindowScroll()`](useWindowScroll.md) — the named default case
+- [`useScrollProgress()`](useScrollProgress.md) — an element's progress through the viewport

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

@@ -0,0 +1,88 @@
+# useScrollProgress
+
+```ts
+useScrollProgress(target: Element, options?: { offset?: string }): Service<ScrollProgressProps>
+```
+
+An element's progress through the viewport as it scrolls.
+
+## Props
+
+```ts
+interface ScrollProgressProps {
+  readonly startX: number;
+  readonly startY: number;
+  readonly endX: number;
+  readonly endY: number;
+  readonly currentX: number;
+  readonly currentY: number;
+  readonly progressX: number;
+  readonly progressY: number;
+}
+```
+
+`start` and `end` are the scroll positions at which the progress is `0` and `1`; `current` is where the scroller is now.
+
+## Usage
+
+```js
+import { Base, useScrollProgress } from '@studiometa/js-toolkit';
+
+class Parallax extends Base {
+  static config = { name: 'Parallax' };
+
+  mounted() {
+    return useScrollProgress(this.$el).subscribe(({ progressY }) => {
+      this.$el.style.setProperty('--progress', String(progressY));
+    });
+  }
+}
+```
+
+## The `offset` option
+
+One string holding **two edge pairs**, separated by a `/`:
+
+```
+"<target> <viewport> / <target> <viewport>"
+```
+
+The first pair is where the progress is `0`, the second where it is `1`. In each pair, the first token is an edge of the **target** and the second an edge of the **viewport**.
+
+The default is:
+
+```js
+useScrollProgress(el, { offset: 'start end / end start' });
+```
+
+which reads as "0 when the target's start meets the viewport's end, 1 when the target's end meets the viewport's start" — the element travelling the full height of the viewport.
+
+Each token is one of:
+
+| Token                            | Means                            |
+| -------------------------------- | -------------------------------- |
+| `start`                          | the leading edge                 |
+| `center`                         | the middle                       |
+| `end`                            | the trailing edge                |
+| `50%`                            | a fraction of the box            |
+| `120px`                          | an absolute offset from the edge |
+| `20vh`, `10vw`, `5vmin`, `5vmax` | a viewport unit                  |
+| a number                         | a fraction, as `0.5`             |
+
+A token that parses as nothing falls back to the edge.
+
+The **resolved** offset is part of the service's key, so two callers asking for the same range on the same element share one service.
+
+## Mixin
+
+```js
+class Parallax extends withScrollProgress(Base, { offset: 'center end / center start' }) {
+  scrolledInView({ progressY }) {}
+}
+```
+
+The hook is named `scrolledInView`.
+
+## Smoothing a progress value
+
+Progress props carry no frame delta, and [`damp()`](../../utils/math.md) takes the elapsed time as a required argument — decay is expressed in time, not in frames. So either take the delta from a [`useRaf()`](useRaf.md) tick, or use [`smoothTo()`](../../utils/motion.md), which owns its own frame subscription and releases it when the value arrives.

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.