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

package/skills/studiometa-js-toolkit/references/utils/load.md

@@ -0,0 +1,59 @@
+# Loading
+
+```js
+import { loadImage, loadLink, loadScript } from '@studiometa/js-toolkit/utils';
+```
+
+Three promises over three tags. Each resolves with the **element** it created, so a caller can read the loaded image's natural size, or keep the script tag to remove it later.
+
+## Usage
+
+```js
+import { loadImage, loadLink, loadScript } from '@studiometa/js-toolkit/utils';
+
+async function load() {
+  const img = await loadImage('/hero.webp');
+
+  await loadScript('https://example.com/widget.js', { async: '', crossorigin: 'anonymous' });
+
+  await loadLink('/print.css', { rel: 'stylesheet', media: 'print' });
+}
+```
+
+### loadImage
+
+```ts
+loadImage(src: string): Promise<HTMLImageElement>
+```
+
+### loadScript
+
+```ts
+loadScript(src: string, attributes?: Record<string, string>): Promise<HTMLScriptElement>
+```
+
+### loadLink
+
+```ts
+loadLink(href: string, attributes: { rel: string; [key: string]: string }): Promise<HTMLLinkElement>
+```
+
+## Where they belong
+
+A third-party widget, a heavy stylesheet or a decorative image is exactly what a deferred mount is for. Reach for these **inside** a component whose mount is already deferred, rather than as a substitute for deferring it:
+
+```html
+<div data-component="Widget" data-mount="interaction:page"></div>
+```
+
+```js
+mounted() {
+  return loadScript('https://example.com/widget.js').then(() => this.init());
+}
+```
+
+The [mount strategy](../guide/going-further/mount-strategies.md) decides _when_, and these decide _what_.
+
+## What is not here
+
+`loadIframe` and `loadElement` are not ported. An iframe is one `createElement()` and one `load` listener, and a generic element loader had no caller that a specific one did not serve better.

package/skills/studiometa-js-toolkit/references/utils/math.md

@@ -0,0 +1,129 @@
+# Math
+
+```js
+import { clamp, lerp, map } from '@studiometa/js-toolkit/utils';
+```
+
+Values in, values out. For anything with a time dimension — damping, springs, inertia — see [Motion](motion.md).
+
+## Ranges
+
+```js
+import { clamp, clamp01 } from '@studiometa/js-toolkit/utils';
+
+clamp(15, 0, 10); // 10
+clamp(-5, 0, 10); // 0
+clamp01(1.5); // 1
+```
+
+### clamp
+
+```ts
+clamp(value: number, min: number, max: number): number
+```
+
+Keep a value inside a range.
+
+### clamp01
+
+```ts
+clamp01(value: number): number
+```
+
+Keep a value inside `0 → 1`. It is the case that comes up in every progress calculation, so it has its own name and no arguments to get the wrong way round.
+
+## Interpolation
+
+```js
+import { lerp, map } from '@studiometa/js-toolkit/utils';
+
+lerp(0, 100, 0.5); // 50
+map(5, 0, 10, 0, 100); // 50
+```
+
+### lerp
+
+```ts
+lerp(min: number, max: number, ratio: number): number
+```
+
+Interpolate between two values by a `0 → 1` ratio.
+
+### map
+
+```ts
+map(value: number, inputMin: number, inputMax: number, outputMin: number, outputMax: number): number
+```
+
+Re-scale one range onto another. It is `lerp` with the input range worked out for you.
+
+## Wrapping and folding
+
+```js
+import { fold, wrap } from '@studiometa/js-toolkit/utils';
+
+wrap(11, 0, 10); // 1  — it comes back round
+fold(11, 0, 10); // 9  — it bounces back
+```
+
+Two behaviours, two names, no flag.
+
+### wrap
+
+```ts
+wrap(value: number, min: number, max: number): number
+```
+
+A carousel that loops: past the end, it comes back round to the start.
+
+### fold
+
+```ts
+fold(value: number, min: number, max: number): number
+```
+
+A value that reverses at the edges rather than looping.
+
+## Rounding and averaging
+
+```js
+import { mean, round } from '@studiometa/js-toolkit/utils';
+
+round(1.2345, 2); // 1.23
+mean([1, 2, 3, 4]); // 2.5
+```
+
+### round
+
+```ts
+round(value: number, decimals?: number): number
+```
+
+Round to a number of decimals.
+
+### mean
+
+```ts
+mean(numbers: readonly number[]): number
+```
+
+The arithmetic mean of a list.
+
+## Series
+
+### createRange
+
+```ts
+createRange(min: number, max: number, step: number): number[]
+```
+
+```js
+import { createRange } from '@studiometa/js-toolkit/utils';
+
+createRange(0, 1, 0.25); // [0, 0.25, 0.5, 0.75, 1]
+```
+
+## See also
+
+- [Easings](easings.md) — shaping a `0 → 1` progress
+- [Motion](motion.md) — everything with an elapsed time

package/skills/studiometa-js-toolkit/references/utils/motion.md

@@ -0,0 +1,218 @@
+# Motion
+
+```js
+import { damp, smoothTo, spring } from '@studiometa/js-toolkit/utils';
+```
+
+Everything here takes a **time**, not a frame count.
+
+> **Decay is expressed in time, not in frames.** `INERTIA_FRAME` (16.67 ms) is the reference of every factor.
+
+That is what makes a factor mean the same thing at 60 Hz and at 120 Hz, and it is why `damp()` takes the elapsed time as a **required** argument.
+
+## Damping
+
+### damp
+
+```ts
+damp(targetValue: number, currentValue: number, factor: number, elapsed: number, precision?: number): number
+```
+
+```js
+import { useRaf } from '@studiometa/js-toolkit';
+import { damp } from '@studiometa/js-toolkit/utils';
+let current = 0;
+let target = 100;
+
+useRaf().subscribe(({ delta }) => {
+  current = damp(target, current, 0.1, delta);
+});
+```
+
+`factor` is **the fraction of the gap that closes per reference frame**, so it is stable for every value a caller can pass. `precision` defaults to `0.01`: below it, the value snaps to the target.
+
+**v3's `damp()` had no `elapsed`**
+
+```js
+damp(current, target, 0.1); // [!code --]
+damp(target, current, 0.1, delta); // [!code ++]
+```
+
+A factor without a time is a factor that means something different on every display.
+
+### clampDampFactor
+
+```ts
+clampDampFactor(factor: number): number
+```
+
+Keeps a factor in the usable range.
+
+### decayOver
+
+```ts
+decayOver(retained: number, elapsed: number): number
+```
+
+The decay of an elapsed time.
+
+## Springs
+
+### spring
+
+```ts
+spring(
+  targetValue: number,
+  currentValue: number,
+  currentVelocity: number,
+  elapsed: number,
+  options?: { stiffness?: number; damping?: number; mass?: number; precision?: number },
+): [value: number, velocity: number]
+```
+
+```js
+import { useRaf } from '@studiometa/js-toolkit';
+import { spring } from '@studiometa/js-toolkit/utils';
+let value = 0;
+let velocity = 0;
+
+useRaf().subscribe(({ delta }) => {
+  [value, velocity] = spring(100, value, velocity, delta, { stiffness: 0.1, damping: 0.8 });
+});
+```
+
+It returns the pair, because a spring's state **is** the value and its velocity — hiding the velocity would make the next step wrong.
+
+**It integrates on a fixed step of a quarter frame**, however long the real frame is, so `stiffness`, `damping` and `mass` keep their meaning and the duration is real. `stiffness / mass` is clamped to `MAX_SPRING_RATIO`, from which that step is derived.
+
+`precision` defaults to `1e-4`.
+
+## Smoothing
+
+### smoothTo
+
+```ts
+smoothTo(start?: number, options?: SmoothToOptions): SmoothTo
+smoothTo<K extends string>(start: Record<K, number>, options?: SmoothToOptions): SmoothToRecord<K>
+```
+
+**A `toggle()` over `useRaf()`**: one subscription however many times the target is set, started when the value has somewhere to go, released when it arrives.
+
+```js
+import { smoothTo } from '@studiometa/js-toolkit/utils';
+
+const x = smoothTo(0, { damping: 0.85 });
+
+x(400); // set a target, read the smoothed value
+x(); // read it
+x.raw(); // the target, unsmoothed
+x.add(50); // move the target
+x.jump(0); // set value and target at once — no travel, no frame
+x.isMoving; // still travelling?
+
+const unsubscribe = x.subscribe((value) => {
+  document.body.style.setProperty('--x', `${value}px`);
+});
+
+x.destroy(); // release the frame subscription and every subscriber
+```
+
+#### Several channels on one subscription
+
+```js
+import { smoothTo } from '@studiometa/js-toolkit/utils';
+
+const view = smoothTo({ x: 0, y: 0, scale: 1 });
+
+view({ x: 100, y: 50 }); // only these two are re-aimed; `scale` keeps travelling
+view.jump({ scale: 1 }); // reset one channel with no travel
+view.isMoving; // true while *any* channel moves
+```
+
+**The keys are the consumer's own** — a scale, an opacity or a progress as readily as a coordinate. One frame subscription, one settled state (the loop stops when the **last** channel arrives), and one subscriber call per frame carrying the whole record.
+
+**The record handed out is the same object every frame**
+
+As a service hands the same props. Treat it as read-only, and copy it with `{ ...values }` to keep one.
+
+The mode — `spring`, `stiffness`, `mass` — belongs to the **instance**, not the channel.
+
+#### `damping` accepts a function
+
+```js
+smoothTo({ x: 0, y: 0 }, { damping: (key) => (key === 'x' ? 0.9 : 0.7) });
+```
+
+It is read on **every frame and for every channel**, which matters for three reasons:
+
+1. **A component's factor is an option**, and `$options` is a live view over attributes — so a factor captured once would freeze an attribute the framework keeps live.
+2. It expresses a factor that depends on the **direction of travel**: read the current value and decide.
+3. It gives one channel of a record a different rate from its neighbour.
+
+A number stays a number.
+
+#### `precision`
+
+Defaults to the default of the function each mode wraps — `0.01` damping, `1e-4` springing — so converting a raw `damp()` call to the helper does not move where it snaps.
+
+## Inertia
+
+The family a coast is built from, and what [`useDrag()`](../api/services/useDrag.md) uses.
+
+**`inertiaStep()` integrates the decay across the step**, so any sequence of frames sums to `velocity · τ` exactly — a coast lands in the same place whatever the frame rate did on the way. `inertiaFinalValue()` is what lets a carousel know which slide a fling is heading for **before** the coast starts.
+
+### inertiaDecay
+
+```ts
+inertiaDecay(dampFactor: number, elapsed: number): number
+```
+
+`decayOver` with the tighter clamp a coast needs.
+
+### inertiaTimeConstant
+
+```ts
+inertiaTimeConstant(dampFactor: number): number
+```
+
+`τ = INERTIA_FRAME / ln(1 / damp)`.
+
+### inertiaStep
+
+```ts
+inertiaStep(velocity: number, dampFactor: number, elapsed: number): number
+```
+
+The distance travelled across the step.
+
+### inertiaFinalValue
+
+```ts
+inertiaFinalValue(value: number, velocity: number, dampFactor: number): number
+```
+
+Where it will come to rest: `value + velocity · τ`.
+
+## Constants
+
+### INERTIA_FRAME
+
+```ts
+const INERTIA_FRAME: number;
+```
+
+`16.67` — the reference frame, in milliseconds.
+
+### DEFAULT_DAMP_FACTOR
+
+```ts
+const DEFAULT_DAMP_FACTOR = 0.85;
+```
+
+### MAX_SPRING_RATIO
+
+```ts
+const MAX_SPRING_RATIO: number;
+```
+
+The clamp on `stiffness / mass`.

package/skills/studiometa-js-toolkit/references/utils/objects.md

@@ -0,0 +1,68 @@
+# Objects & random
+
+```js
+import { deepmerge, random, randomInt, randomItem } from '@studiometa/js-toolkit/utils';
+```
+
+## Merging
+
+### deepmerge
+
+```ts
+deepmerge(...layers: Record<string, unknown>[]): Record<string, unknown>
+```
+
+```js
+import { deepmerge } from '@studiometa/js-toolkit/utils';
+
+deepmerge({ tween: { ease: 'linear', duration: 300 } }, { tween: { ease: 'ease-out' } });
+// { tween: { ease: 'ease-out', duration: 300 } }
+```
+
+Later layers win, at every depth. Plain objects merge; anything else — an array, a `Date`, an element, a class instance — **replaces**.
+
+That last rule is the one worth knowing: an array is a value, not a structure to merge, because merging two arrays by index is almost never what a caller meant.
+
+**It ships for the consumer, not for core**
+
+A utility is judged by consumer need, not by whether core calls it. Layering a default config under an author's config is the case every component author meets, and getting the array rule wrong is exactly how a hand-rolled merge misbehaves.
+
+## Random
+
+```js
+import { random, randomInt, randomItem } from '@studiometa/js-toolkit/utils';
+
+random(10); // 0 → 10
+random(5, 10); // 5 → 10
+randomInt(10); // an integer, 0 → 10
+randomItem(['a', 'b', 'c']);
+```
+
+**One argument is a maximum; two are a range.**
+
+### random
+
+```ts
+random(a: number, b?: number): number
+```
+
+A float in the range.
+
+### randomInt
+
+```ts
+randomInt(a: number, b?: number): number
+```
+
+An integer in the range, bounds inclusive.
+
+### randomItem
+
+```ts
+randomItem<T>(items: readonly T[]): T | undefined
+randomItem(items: string): string | undefined
+```
+
+One item from an array, or one character from a string.
+
+The return includes `undefined` because an empty input has no item to give — and a signature that pretended otherwise would put the bug three lines later.

package/skills/studiometa-js-toolkit/references/utils/scroll.md

@@ -0,0 +1,128 @@
+# Scroll
+
+```js
+import { lockScroll, scrollPosition, scrollTo } from '@studiometa/js-toolkit/utils';
+```
+
+## Scrolling to a target
+
+**The two halves are separate because callers need them separately.** `scrollPosition()` measures and returns; `scrollTo()` calls it and moves.
+
+A carousel asks which slide is nearest three times for every time it travels — and in v3, asking meant scrolling.
+
+```js
+import { scrollPosition, scrollTo } from '@studiometa/js-toolkit/utils';
+
+const el = document.body;
+
+// Where would we end up?
+const { top, left } = scrollPosition(el, { align: 'center' });
+
+// Go there.
+scrollTo(el, { align: 'center', offset: -80 });
+scrollTo('#section', { axis: 'y' });
+scrollTo(0);
+scrollTo({ top: 200 });
+```
+
+### scrollPosition
+
+```ts
+scrollPosition(target: ScrollToTarget, options?: ScrollPositionOptions): ScrollPosition
+```
+
+Measures and returns `{ top, left }` without moving anything.
+
+### scrollTo
+
+```ts
+scrollTo(target: ScrollToTarget, options?: ScrollToOptions): ScrollPosition
+```
+
+Calls `scrollPosition()` and moves there, returning the same result.
+
+`behavior` defaults to `'smooth'`, or to `'instant'` when the reader has asked for less motion — so honouring the preference is the default rather than a call site's responsibility.
+
+### The target
+
+```ts
+type ScrollToTarget = string | Element | number | Partial<{ left: number; top: number }>;
+```
+
+A selector, an element, a number, or a position. **A number or a position names its own destination**, so `align` does not apply to it.
+
+### The options
+
+```ts
+interface ScrollPositionOptions {
+  rootElement?: Element | Window; // what scrolls. Defaults to the window.
+  axis?: 'x' | 'y' | 'both'; // which axes a target that names none may move. Defaults to 'y'.
+  offset?: number; // pixels to stop short. Defaults to 0.
+  align?: ScrollAlign | { x?: ScrollAlign; y?: ScrollAlign };
+}
+
+interface ScrollToOptions extends ScrollPositionOptions {
+  behavior?: ScrollBehavior;
+}
+```
+
+**`align` is `'start' | 'center' | 'end'`, or one per axis**, and it applies to an **element** target only.
+
+**The names are physical, like `axis`**
+
+`x` and `y`, not the platform's `inline` and `block`. Nothing here maps a writing mode, and borrowing that vocabulary without the mapping would promise what `compute-scroll-into-view` promises and does not deliver.
+
+What the arithmetic gets right: **the viewport is the client box**, so a scrollbar gutter is out of it with no special case, and **the destination is clamped to the scroll range** — centring the first slide asks for a negative offset and gets `0`.
+
+### SCROLL_AXES
+
+```ts
+const SCROLL_AXES: Readonly<{ x: 'x'; y: 'y'; both: 'both' }>;
+```
+
+### SCROLL_ALIGNMENTS
+
+```ts
+const SCROLL_ALIGNMENTS: Readonly<{ start: 'start'; center: 'center'; end: 'end' }>;
+```
+
+### A dependency was measured and refused
+
+`compute-scroll-into-view` is 1.4 kB and walks **every** scrolling ancestor — which is what v4's single `rootElement` contract declines, and what a boundary option already cancels. Its own source leaves writing modes unimplemented and reads no `scroll-padding`, so the real delta over core was about twenty lines.
+
+## Locking the page
+
+### lockScroll
+
+```ts
+lockScroll(target?: HTMLElement): () => void
+```
+
+```js
+import { lockScroll } from '@studiometa/js-toolkit/utils';
+
+const release = lockScroll();
+// … the modal is open
+release();
+```
+
+**It counts.** A modal surface is not alone on a page: a dialog opened from inside a drawer is two holders, and the one that closes first must not put the scroll back under the one still open.
+
+- The **first** lock saves the inline value it found.
+- The **last** release puts exactly that value back.
+- The ones between only move the count.
+
+**The release is idempotent**, so a surface calls it on close and again on unmount without counting twice — and a component unmounted while open owes the page its scroll, which is what the second call is for.
+
+**The count is shared across evaluated copies of the package**, through the same runtime slot the focus helpers use, for the same reason: there is one scroll per document.
+
+It is **`overflow: hidden` and nothing else**. No `paddingRight` compensation: `scrollbar-gutter: stable` is the page's own answer and it does not mis-handle fixed children. iOS Safari remains unreliable, which is the argument for having one function rather than a copy per component.
+
+**A native `<dialog>` needs it too**
+
+`showModal()` gives the top layer, the backdrop, a focus trap and `Escape`. It does **not** stop the page behind it scrolling.
+
+## See also
+
+- [`useScroll()`](../api/services/useScroll.md) — scroll position as a service
+- [`useScrollProgress()`](../api/services/useScrollProgress.md) — an element's progress through the viewport