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

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

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

@@ -0,0 +1,176 @@
+# Strings
+
+```js
+import { camelCase, kebabCase, pascalCase } from '@studiometa/js-toolkit/utils';
+```
+
+## Case
+
+```js
+import { camelCase, kebabCase, pascalCase } from '@studiometa/js-toolkit/utils';
+
+pascalCase('drag-threshold'); // 'DragThreshold'
+camelCase('drag-threshold'); // 'dragThreshold'
+kebabCase('dragThreshold'); // 'drag-threshold'
+```
+
+These are the functions the framework itself uses: `kebabCase` turns `dragThreshold` into `data-option-drag-threshold`, and `pascalCase` turns an option name into `optionDragThresholdChanged`.
+
+**Four of them are memoised**
+
+`pascalCase`, `camelCase`, `kebabCase` and `snakeCase` are `memo`-wrapped, because the framework converts the **same** names on every option read and every handler resolution. `lowerCase`, `upperCase` and `capitalize` are not — they are single-pass and there is nothing to cache.
+
+### lowerCase
+
+```ts
+lowerCase(string: string): string
+```
+
+### upperCase
+
+```ts
+upperCase(string: string): string
+```
+
+### capitalize
+
+```ts
+capitalize(string: string): string
+```
+
+### pascalCase
+
+```ts
+pascalCase(string: string): string
+```
+
+`'foo bar'` → `'FooBar'`. Memoised.
+
+### camelCase
+
+```ts
+camelCase(string: string): string
+```
+
+`'foo bar'` → `'fooBar'`. Memoised.
+
+### kebabCase
+
+```ts
+kebabCase(string: string): string
+```
+
+`'fooBar'` → `'foo-bar'`. Memoised.
+
+### snakeCase
+
+```ts
+snakeCase(string: string): string
+```
+
+`'fooBar'` → `'foo_bar'`. Memoised.
+
+## Leading and trailing characters
+
+```js
+import {
+  withLeadingCharacters,
+  withoutTrailingCharactersRecursive,
+} from '@studiometa/js-toolkit/utils';
+
+withLeadingCharacters('bar', 'foo'); // 'foobar'
+withLeadingCharacters('foobar', 'foo'); // 'foobar' — already there
+withoutTrailingCharactersRecursive('path///', '/'); // 'path'
+```
+
+The **recursive** pair exists because a URL joined from parts collects separators, and removing one is not the same as removing them all.
+
+### withLeadingCharacters
+
+```ts
+withLeadingCharacters(string: string, characters: string): string
+```
+
+Adds them if absent.
+
+### withoutLeadingCharacters
+
+```ts
+withoutLeadingCharacters(string: string, characters: string): string
+```
+
+Removes them once.
+
+### withoutLeadingCharactersRecursive
+
+```ts
+withoutLeadingCharactersRecursive(string: string, characters: string): string
+```
+
+Removes them as long as they are there.
+
+### withTrailingCharacters
+
+```ts
+withTrailingCharacters(string: string, characters: string): string
+```
+
+Adds them if absent.
+
+### withoutTrailingCharacters
+
+```ts
+withoutTrailingCharacters(string: string, characters: string): string
+```
+
+Removes them once.
+
+### withoutTrailingCharactersRecursive
+
+```ts
+withoutTrailingCharactersRecursive(string: string, characters: string): string
+```
+
+Removes them as long as they are there.
+
+## Slashes
+
+The four named cases, for the one separator every path uses. Each is the matching `*Characters` function with `'/'` filled in, which is what makes a call site readable at a glance.
+
+```js
+import {
+  withLeadingSlash,
+  withoutLeadingSlash,
+  withoutTrailingSlash,
+  withTrailingSlash,
+} from '@studiometa/js-toolkit/utils';
+
+withLeadingSlash('about'); // '/about'
+withoutLeadingSlash('/about'); // 'about'
+withTrailingSlash('/about'); // '/about/'
+withoutTrailingSlash('/about/'); // '/about'
+```
+
+### withLeadingSlash
+
+```ts
+withLeadingSlash(string: string): string
+```
+
+### withoutLeadingSlash
+
+```ts
+withoutLeadingSlash(string: string): string
+```
+
+### withTrailingSlash
+
+```ts
+withTrailingSlash(string: string): string
+```
+
+### withoutTrailingSlash
+
+```ts
+withoutTrailingSlash(string: string): string
+```

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

@@ -0,0 +1,111 @@
+# Timing
+
+```js
+import { debounce, memo, throttle, wait } from '@studiometa/js-toolkit/utils';
+```
+
+## Rate limiting
+
+```js
+import { debounce, throttle } from '@studiometa/js-toolkit/utils';
+
+const search = debounce((term) => console.log(term), 300); // after the last call
+const track = throttle((y) => console.log(y), 100); // at most once per delay
+```
+
+**Not for scroll, resize, pointer or frame work**
+
+The services already coalesce: the scroll service batches its events into **one `read` per frame**, and the resize service is a `ResizeObserver`. A `throttle` on top of that is a second, worse rate limiter.
+
+Reach for these for what the framework does not own — a `fetch` per keystroke, an analytics call, a `localStorage` write.
+
+### debounce
+
+```ts
+debounce<Args>(fn: (...args: Args) => void, delay?: number): (...args: Args) => void
+```
+
+Runs once, after the calls stop.
+
+### throttle
+
+```ts
+throttle<Args>(fn: (...args: Args) => void, delay?: number): (...args: Args) => void
+```
+
+Runs at most once per `delay`.
+
+## Waiting
+
+### wait
+
+```ts
+wait(delay?: number): Promise<void>
+```
+
+```js
+import { wait } from '@studiometa/js-toolkit/utils';
+
+async function pause() {
+  await wait(300);
+}
+```
+
+`await wait()` with no argument is one turn of the event loop.
+
+For a frame rather than a timer, use [`nextFrame()`](../api/scheduler/nextFrame.md). For "the framework has caught up", use [`whenDOMSettled()`](../api/dom/whenDOMSettled.md) — a timer is the wrong tool for both, and the reason the [test helpers](../api/test/index.md) exist at all.
+
+## Memoisation
+
+### memo
+
+```ts
+memo<Args extends [] | [key: unknown], Value>(fn: (...args: Args) => Value): Memo<Args, Value>
+```
+
+```js
+import { memo } from '@studiometa/js-toolkit/utils';
+
+const expensive = memo((key) => key.toString().repeat(2));
+
+expensive('a'); // computed
+expensive('a'); // cached
+```
+
+**Zero or one argument, and that argument is the key.** That is the whole surface, and it is deliberate: a memo keyed on several arguments needs a key strategy, and a key strategy is a decision the caller should make visibly rather than inherit.
+
+It is what the four memoised [string converters](strings.md) are built on, and what memoises the active breakpoint name for the length of one task.
+
+`cache` and `memoize` from v3 are not shipped — this covers the one case core needed.
+
+## Placeholders
+
+They earn their place as **defaults**: a parameter defaulting to `noop` removes an `if` from every call site, and one defaulting to `noopValue` removes it from a transform pipeline. Both are one shared function, so a default costs no allocation per call.
+
+```js
+import { noop, noopValue } from '@studiometa/js-toolkit/utils';
+
+const onDone = noop; // a callback that does nothing
+const identity = noopValue; // a transform that changes nothing
+```
+
+### noop
+
+```ts
+noop(): void
+```
+
+### noopValue
+
+```ts
+noopValue<T>(value: T): T
+```
+
+## What is not here
+
+| Not shipped                    | Write                                                      |
+| ------------------------------ | ---------------------------------------------------------- |
+| `nextTick`                     | `await Promise.resolve()`                                  |
+| `nextMicrotask`                | `queueMicrotask(fn)`                                       |
+| `Queue`, `SmartQueue`          | the [scheduler](../api/scheduler/index.md)'s lanes                   |
+| `domScheduler`, `useScheduler` | [`defaultScheduler`](../api/scheduler/defaultScheduler.md) |