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

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

@@ -0,0 +1,217 @@
+# Easings
+
+```js
+import { easeInOutCubic, easeOutQuad } from '@studiometa/js-toolkit/utils';
+
+easeOutQuad(0.5); // 0.75
+```
+
+An `EasingFunction` takes a `0 → 1` progress and returns a shaped `0 → 1` value.
+
+## Choosing one
+
+Eight curves, three directions each. Every `out` and `in-out` is derived from its `in`.
+
+| Curve  | In                            | Out                             | In-out                              |
+| ------ | ----------------------------- | ------------------------------- | ----------------------------------- |
+| linear | [`easeLinear`](#easelinear)   | —                               | —                                   |
+| quad   | [`easeInQuad`](#easeinquad)   | [`easeOutQuad`](#easeoutquad)   | [`easeInOutQuad`](#easeinoutquad)   |
+| cubic  | [`easeInCubic`](#easeincubic) | [`easeOutCubic`](#easeoutcubic) | [`easeInOutCubic`](#easeinoutcubic) |
+| quart  | [`easeInQuart`](#easeinquart) | [`easeOutQuart`](#easeoutquart) | [`easeInOutQuart`](#easeinoutquart) |
+| quint  | [`easeInQuint`](#easeinquint) | [`easeOutQuint`](#easeoutquint) | [`easeInOutQuint`](#easeinoutquint) |
+| sine   | [`easeInSine`](#easeinsine)   | [`easeOutSine`](#easeoutsine)   | [`easeInOutSine`](#easeinoutsine)   |
+| circ   | [`easeInCirc`](#easeincirc)   | [`easeOutCirc`](#easeoutcirc)   | [`easeInOutCirc`](#easeinoutcirc)   |
+| expo   | [`easeInExpo`](#easeinexpo)   | [`easeOutExpo`](#easeoutexpo)   | [`easeInOutExpo`](#easeinoutexpo)   |
+
+## Deriving one
+
+```ts
+createEaseOut(easeIn: EasingFunction): EasingFunction
+createEaseInOut(easeIn: EasingFunction): EasingFunction
+```
+
+Every `out` and `in-out` above is one of these applied to its `in`. Which means a custom curve gets its whole family for two lines:
+
+```ts
+import { createEaseInOut, createEaseOut, type EasingFunction } from '@studiometa/js-toolkit/utils';
+
+const easeInBack: EasingFunction = (progress) => progress * progress * (2.7 * progress - 1.7);
+
+const easeOutBack = createEaseOut(easeInBack);
+const easeInOutBack = createEaseInOut(easeInBack);
+```
+
+That is why only the eight `in` functions are written out and the other sixteen are derived: an `out` is an `in` run backwards, and writing it twice is how the two drift apart.
+
+### createEaseOut
+
+```ts
+createEaseOut(easeIn: EasingFunction): EasingFunction
+```
+
+Mirror an `in` curve into its `out`.
+
+### createEaseInOut
+
+```ts
+createEaseInOut(easeIn: EasingFunction): EasingFunction
+```
+
+Compose an `in` curve into its symmetric `in-out`.
+
+## Using one
+
+```js
+import { easeOutCubic, lerp } from '@studiometa/js-toolkit/utils';
+
+function positionAt(progress) {
+  return lerp(0, 400, easeOutCubic(progress));
+}
+```
+
+An easing shapes a **progress**, so it pairs with a value that already runs `0 → 1`: a [`useScrollProgress()`](../api/services/useScrollProgress.md) subscriber, or a `map()` of anything else.
+
+## They do not animate
+
+There is no clock here — an easing is a pure function of a progress you already have.
+
+- For a value chasing a target frame by frame, use [`damp()` or `smoothTo()`](motion.md).
+- For time-based playback, stagger and sequencing, that is the separate `ui-animation` package. `tween` and `animate` are not shipped.
+
+## The functions
+
+Each takes a `0 → 1` progress and returns the shaped value.
+
+### easeLinear
+
+```ts
+easeLinear(progress: number): number
+```
+
+The identity. It exists so a call site can name "no easing" rather than branch on `undefined`.
+
+### easeInQuad
+
+```ts
+easeInQuad(progress: number): number
+```
+
+### easeOutQuad
+
+```ts
+easeOutQuad(progress: number): number
+```
+
+### easeInOutQuad
+
+```ts
+easeInOutQuad(progress: number): number
+```
+
+### easeInCubic
+
+```ts
+easeInCubic(progress: number): number
+```
+
+### easeOutCubic
+
+```ts
+easeOutCubic(progress: number): number
+```
+
+### easeInOutCubic
+
+```ts
+easeInOutCubic(progress: number): number
+```
+
+### easeInQuart
+
+```ts
+easeInQuart(progress: number): number
+```
+
+### easeOutQuart
+
+```ts
+easeOutQuart(progress: number): number
+```
+
+### easeInOutQuart
+
+```ts
+easeInOutQuart(progress: number): number
+```
+
+### easeInQuint
+
+```ts
+easeInQuint(progress: number): number
+```
+
+### easeOutQuint
+
+```ts
+easeOutQuint(progress: number): number
+```
+
+### easeInOutQuint
+
+```ts
+easeInOutQuint(progress: number): number
+```
+
+### easeInSine
+
+```ts
+easeInSine(progress: number): number
+```
+
+### easeOutSine
+
+```ts
+easeOutSine(progress: number): number
+```
+
+### easeInOutSine
+
+```ts
+easeInOutSine(progress: number): number
+```
+
+### easeInCirc
+
+```ts
+easeInCirc(progress: number): number
+```
+
+### easeOutCirc
+
+```ts
+easeOutCirc(progress: number): number
+```
+
+### easeInOutCirc
+
+```ts
+easeInOutCirc(progress: number): number
+```
+
+### easeInExpo
+
+```ts
+easeInExpo(progress: number): number
+```
+
+### easeOutExpo
+
+```ts
+easeOutExpo(progress: number): number
+```
+
+### easeInOutExpo
+
+```ts
+easeInOutExpo(progress: number): number
+```

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

@@ -0,0 +1,84 @@
+# Focus
+
+```js
+import { saveActiveElement, trapFocus, untrapFocus } from '@studiometa/js-toolkit/utils';
+```
+
+The three calls a modal surface needs.
+
+## Usage
+
+`trapFocus()` takes **the keyboard event**, so it is called from a key handler rather than installing a listener of its own:
+
+```js
+import { Base } from '@studiometa/js-toolkit';
+import { saveActiveElement, trapFocus, untrapFocus } from '@studiometa/js-toolkit/utils';
+
+class Dialog extends Base {
+  static config = { name: 'Dialog' };
+
+  open() {
+    saveActiveElement();
+    this.$el.removeAttribute('hidden');
+  }
+
+  close() {
+    this.$el.setAttribute('hidden', '');
+    untrapFocus();
+  }
+
+  onKeydown(event) {
+    trapFocus(this.$el, event);
+  }
+}
+```
+
+With [`useKey()`](../api/services/useKey.md) the event is in the props:
+
+```js
+mounted() {
+  return useKey(this.$el).subscribe(({ event, TAB, isDown }) => {
+    if (TAB && isDown && event) trapFocus(this.$el, event);
+  });
+}
+```
+
+**This is why the key listeners are not passive**
+
+`trapFocus()` calls `preventDefault()` on the event it is handed, and a passive listener cannot. See [`useKey()`](../api/services/useKey.md#the-listeners-are-neither-passive-nor-capturing).
+
+## The three
+
+### saveActiveElement
+
+```ts
+saveActiveElement(): void
+```
+
+Remembers what had focus, so `untrapFocus()` can give it back.
+
+### trapFocus
+
+```ts
+trapFocus(el: HTMLElement, event: KeyboardEvent): void
+```
+
+Keeps `Tab` and `Shift+Tab` inside `el`.
+
+### untrapFocus
+
+```ts
+untrapFocus(): void
+```
+
+Releases the trap and restores focus to the saved element.
+
+## The saved element is shared across copies
+
+Through the shared runtime, for the same reason the scroll lock counts: **there is one focus per document**. Two independently evaluated copies of the package must not each think they own it.
+
+## `<dialog>` already does some of this
+
+`showModal()` gives the top layer, the backdrop, a focus trap and `Escape`. What it does **not** do is stop the page behind it from scrolling — see [`lockScroll()`](scroll.md#lockscroll).
+
+Reach for these three when the surface is not a native `<dialog>`.

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

@@ -0,0 +1,69 @@
+# History
+
+```js
+import { historyPush, historyReplace, objectToURLSearchParams } from '@studiometa/js-toolkit/utils';
+```
+
+## Writing the URL
+
+```js
+import { historyPush, historyReplace } from '@studiometa/js-toolkit/utils';
+
+historyPush({ path: '/products', search: { page: 2, sort: 'price' } });
+historyReplace({ search: { page: 3 } });
+historyPush({ hash: 'section-2' });
+```
+
+```ts
+interface HistoryOptions {
+  path?: string;
+  search?: URLSearchParams | Record<string, SearchParamInput>;
+  hash?: string;
+}
+```
+
+**Each part is optional, and an omitted part is kept.** `historyReplace({ search })` keeps the path and the hash; `historyPush({ hash })` keeps the path and the query string.
+
+That is the whole reason these exist over `history.pushState()`: rebuilding a URL from `location` by hand is where a filter update loses the hash, or a hash update drops the query string.
+
+### historyPush
+
+```ts
+historyPush(options: HistoryOptions, data?: unknown, title?: string): void
+```
+
+Adds a history entry. This is what makes a state navigable with the back button.
+
+### historyReplace
+
+```ts
+historyReplace(options: HistoryOptions, data?: unknown, title?: string): void
+```
+
+Replaces the current entry. This is what keeps a scroll position or a tab index out of the history.
+
+## Building the query string
+
+### objectToURLSearchParams
+
+```ts
+objectToURLSearchParams(
+  object: Record<string, SearchParamInput>,
+  defaultSearch?: string,
+): URLSearchParams
+```
+
+```js
+import { objectToURLSearchParams } from '@studiometa/js-toolkit/utils';
+
+objectToURLSearchParams({ page: 2, tags: ['a', 'b'], open: true });
+objectToURLSearchParams({ page: 2 }, location.search);
+```
+
+`SearchParamInput` accepts a string, a number, a boolean, `null`, `undefined`, an array of those, or a nested object of those — so a filter state serializes without being flattened first.
+
+`defaultSearch` is the starting point, so the result **merges into** an existing query string instead of replacing it.
+
+## See also
+
+For a URL that is also a store you can read, write and observe, use [`createUrlSearchParamsStorage()`](../api/storage/presets.md) — it is these functions behind a typed key-value surface, with `popstate` wired up.

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

@@ -0,0 +1,53 @@
+# Utils
+
+```js
+import { clamp, damp } from '@studiometa/js-toolkit/utils';
+```
+
+Every one of them also has a subpath of its own:
+
+```js
+import { clamp } from '@studiometa/js-toolkit/utils/clamp';
+```
+
+With a bundler, prefer the barrel — tree-shaking removes what you do not import. From an ESM CDN with no build step, prefer the subpath: there is no bundler to shake the graph.
+
+## The categories
+
+| Category                           | Contents                                                               |
+| ---------------------------------- | ---------------------------------------------------------------------- |
+| [Type guards](is.md)           | `isString`, `isNumber`, `isObject`, `isDefined`, …                     |
+| [Strings](strings.md)          | case conversion, leading and trailing characters                       |
+| [Math](math.md)                | `clamp`, `lerp`, `map`, `wrap`, `fold`, `round`, `mean`, `createRange` |
+| [Easings](easings.md)          | the 24 easing functions, `createEaseOut`, `createEaseInOut`            |
+| [Motion](motion.md)            | `damp`, `spring`, `smoothTo`, the inertia family                       |
+| [CSS](css.md)                  | `transform`, `matrix`, `getOffsetSizes`, `setClassesOrStyles`          |
+| [Transitions](transitions.md)  | `transition`, `enterTransition`, `leaveTransition`                     |
+| [DOM](dom.md)                  | `createElement`, `selectorFor`                                         |
+| [Focus](focus.md)              | `trapFocus`, `untrapFocus`, `saveActiveElement`                        |
+| [Scroll](scroll.md)            | `scrollTo`, `scrollPosition`, `lockScroll`                             |
+| [History](history.md)          | `historyPush`, `historyReplace`, `objectToURLSearchParams`             |
+| [Loading](load.md)             | `loadImage`, `loadScript`, `loadLink`                                  |
+| [Timing](timing.md)            | `debounce`, `throttle`, `wait`, `memo`, `noop`                         |
+| [Objects & random](objects.md) | `deepmerge`, `random`, `randomInt`, `randomItem`                       |
+
+## What v3 shipped and v4 does not
+
+| Removed                                                             | Because                                                                                                |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `tween`, `animate`                                                  | time-based playback moves to a separate `ui-animation` package                                         |
+| `domScheduler`, `useScheduler`                                      | [one scheduler](../api/scheduler/index.md) is the clock                                                          |
+| `Queue`, `SmartQueue`                                               | the scheduler's lanes replace them                                                                     |
+| the collision helpers                                               | not ported                                                                                             |
+| `keyCodes`                                                          | [`useKey()`](../api/services/useKey.md) delivers named booleans, so nothing is left to compare against |
+| `nextTick`, `nextMicrotask`                                         | `await Promise.resolve()` and `queueMicrotask()` say it                                                |
+| `isEmpty`, `isEmptyString`, `isArray`, `isDev`                      | the platform or a one-liner says it                                                                    |
+| `cache`, `memoize`                                                  | [`memo`](timing.md#memo) covers the one case core needed                                           |
+| `addClass`, `removeClass`, `toggleClass`, `addStyle`, `removeStyle` | `classList` and `style` say it                                                                         |
+| `loadIframe`, `loadElement`                                         | not ported                                                                                             |
+
+## How a utility earns its place
+
+**It is judged by consumer need, not by core's own use.** Some of these are not called anywhere in core — they ship because a component author would otherwise write them again, and getting them wrong is easy. `deepmerge` is the clearest case.
+
+The reverse also holds: a function core happens to use internally is not public for that reason alone.

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

@@ -0,0 +1,84 @@
+# Type guards
+
+```js
+import { isDefined, isNumber, isObject, isString } from '@studiometa/js-toolkit/utils';
+```
+
+Each one narrows the type.
+
+## Usage
+
+```ts
+import { isDefined, isObject, isString } from '@studiometa/js-toolkit/utils';
+
+function label(value: unknown): string {
+  if (isString(value)) return value; // string
+  if (isObject(value)) return JSON.stringify(value); // Record<string, unknown>
+  return '';
+}
+
+function first<T>(items: (T | undefined)[]): T[] {
+  return items.filter(isDefined); // T[]
+}
+```
+
+`isDefined` as a `filter` predicate is the case that earns the export: it is the one narrowing TypeScript will not do from a truthiness check.
+
+## The guards
+
+### isNull
+
+```ts
+isNull(value: unknown): value is null
+```
+
+### isDefined
+
+```ts
+isDefined<T>(value: T | undefined): value is T
+```
+
+Narrows `T | undefined` to `T`. Passing it by reference to `filter` is what it is for.
+
+### isString
+
+```ts
+isString(value: unknown): value is string
+```
+
+### isNumber
+
+```ts
+isNumber(value: unknown): value is number
+```
+
+**It rejects `NaN`**, because a `NaN` that passes a number check is a bug that surfaces three functions later.
+
+### isBoolean
+
+```ts
+isBoolean(value: unknown): value is boolean
+```
+
+### isFunction
+
+```ts
+isFunction(value: unknown): value is (...args: unknown[]) => unknown
+```
+
+### isObject
+
+```ts
+isObject(value: unknown): value is Record<string, unknown>
+```
+
+## What is not here
+
+| Not shipped     | Write                               |
+| --------------- | ----------------------------------- |
+| `isArray`       | `Array.isArray(value)`              |
+| `isEmpty`       | the check the caller actually means |
+| `isEmptyString` | `value === ''`                      |
+| `isDev`         | your bundler's own flag             |
+
+A guard earns its place by narrowing something the platform does not, or by being a predicate you pass by reference.

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