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

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

@@ -0,0 +1,98 @@
+# CSS
+
+```js
+import { matrix, transform } from '@studiometa/js-toolkit/utils';
+```
+
+## Transforms
+
+### transform
+
+```ts
+transform(props: TransformProps): string
+```
+
+```js
+import { transform } from '@studiometa/js-toolkit/utils';
+
+transform({ x: 10, y: 20, scale: 1.5, rotate: 45 });
+```
+
+Builds a `transform` value from named parts, so a component composes a transform instead of assembling a string. `TransformProps` takes `x`, `y`, `z`, `rotate`, `rotateX`, `rotateY`, `rotateZ`, `scale`, `scaleX`, `scaleY`, `scaleZ`, `skew` and the rest of the family.
+
+**The order is fixed by `TRANSFORM_PROPS`, not by the object.** Transform functions do not commute, so two components building "the same" transform from differently-ordered literals must still get the same matrix.
+
+### matrix
+
+```ts
+matrix(props?: MatrixProps): string
+```
+
+```js
+import { matrix } from '@studiometa/js-toolkit/utils';
+
+matrix({ scaleX: 2, translateX: 10 });
+```
+
+A `matrix()` string. Reach for it when a value has to be interpolated as a matrix rather than as separate functions.
+
+### TRANSFORM_PROPS
+
+```ts
+const TRANSFORM_PROPS: readonly (keyof TransformProps)[];
+```
+
+The ordered list of keys `transform()` reads.
+
+## Measuring
+
+### getOffsetSizes
+
+```ts
+getOffsetSizes(element: HTMLElement): { x, y, width, height, top, right, bottom, left }
+```
+
+```js
+import { getOffsetSizes } from '@studiometa/js-toolkit/utils';
+
+const box = getOffsetSizes(document.body);
+```
+
+The element's box from its **offset** properties rather than from `getBoundingClientRect()` — so a transform the component itself applied does not move the measurement.
+
+That is exactly what a drag or a tilt needs: the layout box is the frame of reference, and the transform is the output.
+
+**It is a layout read**
+
+Call it from the `read` phase — [`$read()`](../api/instance-methods.md#read-and-write) — so it batches with every other measurement of the frame.
+
+## Applying
+
+### setClassesOrStyles
+
+```ts
+setClassesOrStyles(
+  el: HTMLElement,
+  value: string | string[] | Partial<CSSStyleDeclaration> | undefined,
+  method?: 'add' | 'remove',
+): void
+```
+
+```js
+import { setClassesOrStyles } from '@studiometa/js-toolkit/utils';
+
+const el = document.body;
+
+setClassesOrStyles(el, 'is-active'); // a class
+setClassesOrStyles(el, ['is-active', 'is-open']); // several
+setClassesOrStyles(el, { opacity: '0' }); // inline styles
+setClassesOrStyles(el, 'is-active', 'remove'); // undo it
+```
+
+Applies a value that may be **either** classes or inline styles, which is what lets [`transition()`](transitions.md) take one option in both forms.
+
+An `undefined` value does nothing, so a caller with an optional state does not have to branch.
+
+## What is not here
+
+`addClass`, `removeClass`, `toggleClass`, `addStyle`, `removeStyle` and `animate` are not shipped. `el.classList` and `el.style` say the first five, and time-based playback belongs to the separate `ui-animation` package.

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

@@ -0,0 +1,54 @@
+# DOM
+
+```js
+import { createElement, selectorFor } from '@studiometa/js-toolkit/utils';
+```
+
+## createElement
+
+```ts
+createElement(tag?, children?): HTMLElement
+createElement(tag?, attributes?, children?): HTMLElement
+```
+
+```js
+import { createElement } from '@studiometa/js-toolkit/utils';
+
+createElement('div');
+createElement('p', 'Hello');
+createElement('ul', [createElement('li', 'One'), createElement('li', 'Two')]);
+createElement('button', { class: 'btn', data: { component: 'Action' } }, 'Send');
+```
+
+**Parameters**
+
+- `tag` — defaults to `'div'`, and the return type follows it: `createElement('input')` gives an `HTMLInputElement`.
+- `attributes` — plain attributes, plus a `data` object whose keys become `data-*`.
+- `children` — a string, a `Node`, or an array of either.
+
+The `data` key is why this exists rather than three lines of `document.createElement`: building an element that carries `data-component` and a few `data-option-*` is the common case, and spelling each `setAttribute()` out loses the shape.
+
+## selectorFor
+
+```ts
+selectorFor(name: string): string
+```
+
+```js
+import { selectorFor } from '@studiometa/js-toolkit/utils';
+
+selectorFor('Dialog');
+```
+
+The CSS selector that matches every element declaring a component name — **including the responsive `data-component:<breakpoint>` spellings**.
+
+It is the **one place** that writes the name-to-selector contract, which is why it is public: a consumer that queries for components must match what the registry matches, and a hand-written `[data-component="X"]` misses the scoped declarations.
+
+**It over-matches on purpose**
+
+A responsive declaration that is not active still matches the selector. That is why the four [instance lookups](../api/registry/getInstances.md) read the element's instance map afterwards: **a matching element with no instance is skipped, and that is the whole narrowing.**
+
+## See also
+
+- [CSS](css.md) — `getOffsetSizes`, `transform`, `matrix`
+- [`swap()`](../api/dom/swap.md) — replacing content, with the framework waiting

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.