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

package/dist/utils/load.js

@@ -0,0 +1,144 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+//#region src/utils/load.ts
+/** Loading a resource, as a promise that settles when the browser is done with it. */
+/**
+* The pending loads for the elements that go in `<head>`, keyed by the URL the
+* browser will actually request — and by the `rel` too, for a link.
+*
+* Two evaluated copies of the package share them: appending an embed twice
+* executes a third-party script twice, which the deduplication exists to
+* prevent, so a module-level map would not be enough.
+*/
+const state = /* @__PURE__ */ getSharedRuntimeSlot("load", 1, () => ({
+	scripts: /* @__PURE__ */ new Map(),
+	links: /* @__PURE__ */ new Map()
+}));
+/** What the browser will request, which is what two calls share or do not. */
+function resolveUrl(src) {
+	return new URL(src, location.href).href;
+}
+/**
+* A real `Error`, so a reporter has a message and `catch` blocks can read one.
+* The load and error events carry no reason, hence the source in the message
+* and the event as the cause.
+*/
+function loadingFailed(src, event) {
+	return new Error(`Failed to load "${src}".`, { cause: event });
+}
+function setAttributes(element, attributes) {
+	for (const [name, value] of Object.entries(attributes)) element.setAttribute(name, value);
+}
+/**
+* Forget a failed load, so a later call can try again — a network blip must not
+* make a URL unloadable for the life of the page. Guarded by identity: only the
+* entry this load owns is dropped.
+*/
+function forget(map, key, owner) {
+	if (map.get(key) === owner) map.delete(key);
+}
+/**
+* Will the browser act on this `rel`? A `<link>` it ignores fires no event at
+* all, so this is the difference between a promise and a leak.
+*/
+function relIsSupported(rel) {
+	const { relList } = document.createElement("link");
+	return rel.split(/\s+/).some((token) => token !== "" && relList.supports(token));
+}
+/**
+* Load an image, resolved once its bitmap is decoded.
+*
+* The element is detached and stays that way: this preloads a URL, it does not
+* put an image on the page. Awaiting `decode()` rather than the load event is
+* the point — assigning the URL to a visible `<img>` afterwards paints in the
+* same frame instead of janking the one after it. The element comes back for
+* its `naturalWidth`/`naturalHeight`.
+*
+* Nothing is deduplicated here: the HTTP cache already does it, and a detached
+* element costs nothing to build.
+* @link https://js-toolkit-v4.studiometa.dev/utils/load.html#loadimage
+*/
+async function loadImage(src) {
+	const image = new Image();
+	const settled = new Promise((resolve, reject) => {
+		image.addEventListener("load", () => resolve(), { once: true });
+		image.addEventListener("error", (event) => reject(loadingFailed(src, event)), { once: true });
+	});
+	image.src = src;
+	if (typeof image.decode === "function") try {
+		await image.decode();
+		return image;
+	} catch {}
+	await settled;
+	return image;
+}
+/**
+* Load a script, appended to `<head>`.
+*
+* There is no target option: a detached `<script>` never runs. Calls are
+* deduplicated by resolved URL, so asking twice for one embed returns the very
+* same promise and executes the third-party code once. A failed load is
+* forgotten, so it can be retried.
+* @link https://js-toolkit-v4.studiometa.dev/utils/load.html#loadscript
+*/
+function loadScript(src, attributes = {}) {
+	const url = resolveUrl(src);
+	const pending = state.scripts.get(url);
+	if (pending) return pending;
+	const promise = new Promise((resolve, reject) => {
+		const script = document.createElement("script");
+		setAttributes(script, attributes);
+		script.addEventListener("load", () => resolve(script), { once: true });
+		script.addEventListener("error", (event) => {
+			forget(state.scripts, url, promise);
+			script.remove();
+			reject(loadingFailed(src, event));
+		}, { once: true });
+		script.src = src;
+		document.head.append(script);
+	});
+	state.scripts.set(url, promise);
+	return promise;
+}
+/**
+* Load a `<link>`, appended to `<head>`.
+*
+* `rel` is required because a `<link>` without one is inert and would never
+* settle. It is also part of the deduplication key, next to the resolved URL:
+* prefetching a URL and loading it as a stylesheet are two intents on one
+* href, and both must happen.
+*
+* **A `rel` the browser ignores resolves at once.** `relList.supports()`
+* answers whether the browser will act on it — Safari ignores `prefetch`
+* entirely — and a hint is best-effort, so an ignored one is a resolved
+* promise over an inert element rather than a promise waiting forever for an
+* event that will never fire. The element is appended either way.
+* @link https://js-toolkit-v4.studiometa.dev/utils/load.html#loadlink
+*/
+function loadLink(href, attributes) {
+	const { rel } = attributes;
+	const key = `${rel}\u0000${resolveUrl(href)}`;
+	const pending = state.links.get(key);
+	if (pending) return pending;
+	const supported = relIsSupported(rel);
+	const promise = new Promise((resolve, reject) => {
+		const link = document.createElement("link");
+		setAttributes(link, attributes);
+		if (supported) {
+			link.addEventListener("load", () => resolve(link), { once: true });
+			link.addEventListener("error", (event) => {
+				forget(state.links, key, promise);
+				link.remove();
+				reject(loadingFailed(href, event));
+			}, { once: true });
+		}
+		link.href = href;
+		document.head.append(link);
+		if (!supported) resolve(link);
+	});
+	state.links.set(key, promise);
+	return promise;
+}
+//#endregion
+export { loadImage, loadLink, loadScript };
+
+//# sourceMappingURL=load.js.map

package/dist/utils/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","names":[],"sources":["../../src/utils/load.ts"],"sourcesContent":["/** Loading a resource, as a promise that settles when the browser is done with it. */\n\nimport { getSharedRuntimeSlot } from '../shared-runtime.js';\n\n/**\n * The pending loads for the elements that go in `<head>`, keyed by the URL the\n * browser will actually request — and by the `rel` too, for a link.\n *\n * Two evaluated copies of the package share them: appending an embed twice\n * executes a third-party script twice, which the deduplication exists to\n * prevent, so a module-level map would not be enough.\n */\nconst state = /* @__PURE__ */ getSharedRuntimeSlot('load', 1, () => ({\n  scripts: new Map<string, Promise<HTMLScriptElement>>(),\n  links: new Map<string, Promise<HTMLLinkElement>>(),\n}));\n\n/** What the browser will request, which is what two calls share or do not. */\nfunction resolveUrl(src: string): string {\n  return new URL(src, location.href).href;\n}\n\n/**\n * A real `Error`, so a reporter has a message and `catch` blocks can read one.\n * The load and error events carry no reason, hence the source in the message\n * and the event as the cause.\n */\nfunction loadingFailed(src: string, event: Event): Error {\n  return new Error(`Failed to load \"${src}\".`, { cause: event });\n}\n\nfunction setAttributes(element: Element, attributes: Record<string, string>): void {\n  for (const [name, value] of Object.entries(attributes)) {\n    element.setAttribute(name, value);\n  }\n}\n\n/**\n * Forget a failed load, so a later call can try again — a network blip must not\n * make a URL unloadable for the life of the page. Guarded by identity: only the\n * entry this load owns is dropped.\n */\nfunction forget<T>(map: Map<string, Promise<T>>, key: string, owner: Promise<T>): void {\n  if (map.get(key) === owner) {\n    map.delete(key);\n  }\n}\n\n/**\n * Will the browser act on this `rel`? A `<link>` it ignores fires no event at\n * all, so this is the difference between a promise and a leak.\n */\nfunction relIsSupported(rel: string): boolean {\n  const { relList } = document.createElement('link');\n  // `supports()` throws on an empty token, and a `rel` may hold several.\n  return rel.split(/\\s+/).some((token) => token !== '' && relList.supports(token));\n}\n\n/**\n * Load an image, resolved once its bitmap is decoded.\n *\n * The element is detached and stays that way: this preloads a URL, it does not\n * put an image on the page. Awaiting `decode()` rather than the load event is\n * the point — assigning the URL to a visible `<img>` afterwards paints in the\n * same frame instead of janking the one after it. The element comes back for\n * its `naturalWidth`/`naturalHeight`.\n *\n * Nothing is deduplicated here: the HTTP cache already does it, and a detached\n * element costs nothing to build.\n * @link https://js-toolkit-v4.studiometa.dev/utils/load.html#loadimage\n */\nexport async function loadImage(src: string): Promise<HTMLImageElement> {\n  const image = new Image();\n\n  const settled = new Promise<void>((resolve, reject) => {\n    image.addEventListener('load', () => resolve(), { once: true });\n    image.addEventListener('error', (event) => reject(loadingFailed(src, event)), { once: true });\n  });\n\n  image.src = src;\n\n  if (typeof image.decode === 'function') {\n    try {\n      await image.decode();\n      return image;\n    } catch {\n      // A rejection is not proof of failure: some cross-origin images reject\n      // with an `EncodingError` and load perfectly. The events are the\n      // authority on whether the load worked, so fall through to them.\n    }\n  }\n\n  await settled;\n  return image;\n}\n\n/**\n * Load a script, appended to `<head>`.\n *\n * There is no target option: a detached `<script>` never runs. Calls are\n * deduplicated by resolved URL, so asking twice for one embed returns the very\n * same promise and executes the third-party code once. A failed load is\n * forgotten, so it can be retried.\n * @link https://js-toolkit-v4.studiometa.dev/utils/load.html#loadscript\n */\nexport function loadScript(\n  src: string,\n  attributes: Record<string, string> = {},\n): Promise<HTMLScriptElement> {\n  const url = resolveUrl(src);\n  const pending = state.scripts.get(url);\n\n  if (pending) {\n    return pending;\n  }\n\n  const promise = new Promise<HTMLScriptElement>((resolve, reject) => {\n    const script = document.createElement('script');\n    setAttributes(script, attributes);\n    script.addEventListener('load', () => resolve(script), { once: true });\n    script.addEventListener(\n      'error',\n      (event) => {\n        forget(state.scripts, url, promise);\n        script.remove();\n        reject(loadingFailed(src, event));\n      },\n      { once: true },\n    );\n    script.src = src;\n    document.head.append(script);\n  });\n\n  state.scripts.set(url, promise);\n\n  return promise;\n}\n\n/**\n * Load a `<link>`, appended to `<head>`.\n *\n * `rel` is required because a `<link>` without one is inert and would never\n * settle. It is also part of the deduplication key, next to the resolved URL:\n * prefetching a URL and loading it as a stylesheet are two intents on one\n * href, and both must happen.\n *\n * **A `rel` the browser ignores resolves at once.** `relList.supports()`\n * answers whether the browser will act on it — Safari ignores `prefetch`\n * entirely — and a hint is best-effort, so an ignored one is a resolved\n * promise over an inert element rather than a promise waiting forever for an\n * event that will never fire. The element is appended either way.\n * @link https://js-toolkit-v4.studiometa.dev/utils/load.html#loadlink\n */\nexport function loadLink(\n  href: string,\n  attributes: { rel: string } & Record<string, string>,\n): Promise<HTMLLinkElement> {\n  const { rel } = attributes;\n  // A NUL cannot appear in a URL, so no `rel` can forge another one's key.\n  const key = `${rel}\\u0000${resolveUrl(href)}`;\n  const pending = state.links.get(key);\n\n  if (pending) {\n    return pending;\n  }\n\n  const supported = relIsSupported(rel);\n\n  const promise = new Promise<HTMLLinkElement>((resolve, reject) => {\n    const link = document.createElement('link');\n    setAttributes(link, attributes);\n\n    if (supported) {\n      link.addEventListener('load', () => resolve(link), { once: true });\n      link.addEventListener(\n        'error',\n        (event) => {\n          forget(state.links, key, promise);\n          link.remove();\n          reject(loadingFailed(href, event));\n        },\n        { once: true },\n      );\n    }\n\n    link.href = href;\n    document.head.append(link);\n\n    if (!supported) {\n      resolve(link);\n    }\n  });\n\n  state.links.set(key, promise);\n\n  return promise;\n}\n"],"mappings":"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"}

package/dist/utils/maths.d.ts

@@ -0,0 +1,122 @@
+//#region src/utils/maths.d.ts
+/** Time-based functions take elapsed milliseconds. */
+/**
+ * The default inertia factor.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#default-damp-factor
+ */
+declare const DEFAULT_DAMP_FACTOR = 0.85;
+/**
+ * The 60 Hz reference frame for damping factors, in milliseconds.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertia-frame
+ */
+declare const INERTIA_FRAME: number;
+/**
+ * Clamp a value in a given range.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#clamp
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Clamp a value in the 0–1 range.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#clamp01
+ */
+declare function clamp01(value: number): number;
+/**
+ * Map a value from one range onto another.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#map
+ */
+declare function map(value: number, inputMin: number, inputMax: number, outputMin: number, outputMax: number): number;
+/**
+ * Interpolate a ratio between two bounds.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#lerp
+ */
+declare function lerp(min: number, max: number, ratio: number): number;
+/**
+ * Wrap a value in a range: it leaves by one bound and comes back by the other.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#wrap
+ */
+declare function wrap(value: number, min: number, max: number): number;
+/**
+ * Fold a value back and forth in a range: it bounces off both bounds.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#fold
+ */
+declare function fold(value: number, min: number, max: number): number;
+/**
+ * Round a value to the given number of decimals.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#round
+ */
+declare function round(value: number, decimals?: number): number;
+/**
+ * The arithmetic mean of the given numbers. An empty list averages to `0`.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#mean
+ */
+declare function mean(numbers: readonly number[]): number;
+/**
+ * The values from `min` up to `max`, one step apart.
+ *
+ * Each value is computed from the index rather than accumulated, so a
+ * fractional step does not drift. A step which is not positive and finite
+ * describes no range and returns an empty array.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#createrange
+ */
+declare function createRange(min: number, max: number, step: number): number[];
+/**
+ * Return the fraction retained after `elapsed` milliseconds.
+ *
+ * Retention is clamped to `[0, 1]`, elapsed time to non-negative values, and non-finite inputs return `0`.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#decayover
+ */
+declare function decayOver(retained: number, elapsed: number): number;
+/**
+ * Return the next time-based damped value and snap within `precision`.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#damp
+ */
+declare function damp(targetValue: number, currentValue: number, factor: number, elapsed: number, precision?: number): number;
+/**
+ * Clamp an inertia damping factor to a finite decaying range.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#clampdampfactor
+ */
+declare function clampDampFactor(factor: number): number;
+/**
+ * Return the velocity fraction retained after elapsed time.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiadecay
+ */
+declare function inertiaDecay(dampFactor: number, elapsed: number): number;
+/**
+ * Return the inertia decay time constant in milliseconds.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiatimeconstant
+ */
+declare function inertiaTimeConstant(dampFactor: number): number;
+/**
+ * Integrate one inertia step exactly for velocity in pixels per millisecond.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiastep
+ */
+declare function inertiaStep(velocity: number, dampFactor: number, elapsed: number): number;
+/**
+ * Return the exact coast destination for velocity in pixels per millisecond. The destination remains invariant during the coast.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiafinalvalue
+ */
+declare function inertiaFinalValue(value: number, velocity: number, dampFactor: number): number;
+/**
+ * Largest stable `stiffness / mass` ratio for {@link SPRING_STEP}.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#max-spring-ratio
+ */
+declare const MAX_SPRING_RATIO: number;
+interface SpringOptions {
+  /** Pull towards the target, per {@link INERTIA_FRAME}. Defaults to `0.1`. */
+  stiffness?: number;
+  /** Velocity retained per {@link INERTIA_FRAME}, the friction. Defaults to `0.6`. */
+  damping?: number;
+  /** Resistance to acceleration. Defaults to `1`. */
+  mass?: number;
+  /** Distance and velocity under which the spring is at rest. Defaults to `1e-4`. */
+  precision?: number;
+}
+/**
+ * Advance a spring by elapsed milliseconds with fixed, bounded substeps. Stiffness-to-mass ratio is clamped for stability.
+ *
+ * Returns the exact target and zero velocity within `precision`.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#spring
+ */
+declare function spring(targetValue: number, currentValue: number, currentVelocity: number, elapsed: number, options?: SpringOptions): [value: number, velocity: number];
+//#endregion
+export { DEFAULT_DAMP_FACTOR, INERTIA_FRAME, MAX_SPRING_RATIO, SpringOptions, clamp, clamp01, clampDampFactor, createRange, damp, decayOver, fold, inertiaDecay, inertiaFinalValue, inertiaStep, inertiaTimeConstant, lerp, map, mean, round, spring, wrap };

package/dist/utils/maths.js

@@ -0,0 +1,177 @@
+//#region src/utils/maths.ts
+/** Time-based functions take elapsed milliseconds. */
+/**
+* The default inertia factor.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#default-damp-factor
+*/
+const DEFAULT_DAMP_FACTOR = .85;
+/**
+* The 60 Hz reference frame for damping factors, in milliseconds.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertia-frame
+*/
+const INERTIA_FRAME = 1e3 / 60;
+/**
+* Clamp a value in a given range.
+* @link https://js-toolkit-v4.studiometa.dev/utils/math.html#clamp
+*/
+function clamp(value, min, max) {
+	if (min < max) return value < min ? min : value > max ? max : value;
+	return value < max ? max : value > min ? min : value;
+}
+/**
+* Clamp a value in the 0–1 range.
+* @link https://js-toolkit-v4.studiometa.dev/utils/math.html#clamp01
+*/
+function clamp01(value) {
+	return clamp(value, 0, 1);
+}
+/**
+* Map a value from one range onto another.
+* @link https://js-toolkit-v4.studiometa.dev/utils/math.html#map
+*/
+function map(value, inputMin, inputMax, outputMin, outputMax) {
+	return (value - inputMin) * (outputMax - outputMin) / (inputMax - inputMin) + outputMin;
+}
+/**
+* Interpolate a ratio between two bounds.
+* @link https://js-toolkit-v4.studiometa.dev/utils/math.html#lerp
+*/
+function lerp(min, max, ratio) {
+	return (1 - ratio) * min + ratio * max;
+}
+/**
+* Wrap a value in a range: it leaves by one bound and comes back by the other.
+* @link https://js-toolkit-v4.studiometa.dev/utils/math.html#wrap
+*/
+function wrap(value, min, max) {
+	const range = max - min;
+	if (!Number.isFinite(range)) return value;
+	return min === max ? min : (range + (value - min) % range) % range + min;
+}
+/**
+* Fold a value back and forth in a range: it bounces off both bounds.
+* @link https://js-toolkit-v4.studiometa.dev/utils/math.html#fold
+*/
+function fold(value, min, max) {
+	const range = max - min;
+	if (!Number.isFinite(range) || range <= 0) return min;
+	const wrapped = wrap(value, min, min + range * 2);
+	return wrapped > max ? 2 * max - wrapped : wrapped;
+}
+/**
+* Round a value to the given number of decimals.
+* @link https://js-toolkit-v4.studiometa.dev/utils/math.html#round
+*/
+function round(value, decimals = 0) {
+	return Number(value.toFixed(decimals));
+}
+/**
+* The arithmetic mean of the given numbers. An empty list averages to `0`.
+* @link https://js-toolkit-v4.studiometa.dev/utils/math.html#mean
+*/
+function mean(numbers) {
+	if (numbers.length === 0) return 0;
+	let sum = 0;
+	for (const value of numbers) sum += value;
+	return sum / numbers.length;
+}
+/**
+* The values from `min` up to `max`, one step apart.
+*
+* Each value is computed from the index rather than accumulated, so a
+* fractional step does not drift. A step which is not positive and finite
+* describes no range and returns an empty array.
+* @link https://js-toolkit-v4.studiometa.dev/utils/math.html#createrange
+*/
+function createRange(min, max, step) {
+	if (!Number.isFinite(step) || step <= 0 || !Number.isFinite(max - min) || max < min) return [];
+	const count = Math.floor((max - min) / step) + 1;
+	return Array.from({ length: count }, (_, index) => min + index * step);
+}
+/**
+* Return the fraction retained after `elapsed` milliseconds.
+*
+* Retention is clamped to `[0, 1]`, elapsed time to non-negative values, and non-finite inputs return `0`.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#decayover
+*/
+function decayOver(retained, elapsed) {
+	if (!Number.isFinite(retained) || !Number.isFinite(elapsed)) return 0;
+	return Math.min(Math.max(retained, 0), 1) ** (Math.max(elapsed, 0) / INERTIA_FRAME);
+}
+/**
+* Return the next time-based damped value and snap within `precision`.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#damp
+*/
+function damp(targetValue, currentValue, factor, elapsed, precision = .01) {
+	if (Math.abs(targetValue - currentValue) < precision) return targetValue;
+	const closed = 1 - decayOver(1 - factor, elapsed);
+	return currentValue + (targetValue - currentValue) * closed;
+}
+/**
+* Clamp an inertia damping factor to a finite decaying range.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#clampdampfactor
+*/
+function clampDampFactor(factor) {
+	if (!Number.isFinite(factor)) return DEFAULT_DAMP_FACTOR;
+	return Math.min(Math.max(factor, 0), .99999);
+}
+/**
+* Return the velocity fraction retained after elapsed time.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiadecay
+*/
+function inertiaDecay(dampFactor, elapsed) {
+	return decayOver(clampDampFactor(dampFactor), elapsed);
+}
+/**
+* Return the inertia decay time constant in milliseconds.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiatimeconstant
+*/
+function inertiaTimeConstant(dampFactor) {
+	return INERTIA_FRAME / Math.log(1 / clampDampFactor(dampFactor));
+}
+/**
+* Integrate one inertia step exactly for velocity in pixels per millisecond.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiastep
+*/
+function inertiaStep(velocity, dampFactor, elapsed) {
+	return velocity * inertiaTimeConstant(dampFactor) * (1 - inertiaDecay(dampFactor, elapsed));
+}
+/**
+* Return the exact coast destination for velocity in pixels per millisecond. The destination remains invariant during the coast.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiafinalvalue
+*/
+function inertiaFinalValue(value, velocity, dampFactor) {
+	return value + velocity * inertiaTimeConstant(dampFactor);
+}
+/** Fixed spring integration step in milliseconds. */
+const SPRING_STEP = INERTIA_FRAME / 4;
+/**
+* Largest stable `stiffness / mass` ratio for {@link SPRING_STEP}.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#max-spring-ratio
+*/
+const MAX_SPRING_RATIO = 4 / (SPRING_STEP / INERTIA_FRAME) ** 2 * .9;
+/**
+* Advance a spring by elapsed milliseconds with fixed, bounded substeps. Stiffness-to-mass ratio is clamped for stability.
+*
+* Returns the exact target and zero velocity within `precision`.
+* @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#spring
+*/
+function spring(targetValue, currentValue, currentVelocity, elapsed, options = {}) {
+	const { stiffness = .1, damping = .6, mass = 1, precision = 1 / 1e4 } = options;
+	if (!Number.isFinite(elapsed) || elapsed <= 0) return [currentValue, currentVelocity];
+	let value = currentValue;
+	let velocity = currentVelocity;
+	const budget = Math.min(elapsed, 10 * INERTIA_FRAME);
+	const retained = decayOver(damping, SPRING_STEP);
+	const pull = (Number.isFinite(stiffness / mass) ? Math.min(Math.max(stiffness / mass, 0), MAX_SPRING_RATIO) : .1) * (SPRING_STEP / INERTIA_FRAME);
+	for (let spent = 0; spent < budget; spent += SPRING_STEP) {
+		velocity = velocity * retained + (targetValue - value) * pull;
+		value += velocity * (SPRING_STEP / INERTIA_FRAME);
+	}
+	if (Math.abs(targetValue - value) < precision && Math.abs(velocity) < precision) return [targetValue, 0];
+	return [value, velocity];
+}
+//#endregion
+export { DEFAULT_DAMP_FACTOR, INERTIA_FRAME, MAX_SPRING_RATIO, clamp, clamp01, clampDampFactor, createRange, damp, decayOver, fold, inertiaDecay, inertiaFinalValue, inertiaStep, inertiaTimeConstant, lerp, map, mean, round, spring, wrap };
+
+//# sourceMappingURL=maths.js.map

package/dist/utils/maths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"maths.js","names":[],"sources":["../../src/utils/maths.ts"],"sourcesContent":["/** Time-based functions take elapsed milliseconds. */\n\n/**\n * The default inertia factor.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#default-damp-factor\n */\nexport const DEFAULT_DAMP_FACTOR = 0.85;\n\n/**\n * The 60 Hz reference frame for damping factors, in milliseconds.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertia-frame\n */\nexport const INERTIA_FRAME = 1000 / 60;\n\n/**\n * Clamp a value in a given range.\n * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#clamp\n */\nexport function clamp(value: number, min: number, max: number): number {\n  if (min < max) {\n    return value < min ? min : value > max ? max : value;\n  }\n  return value < max ? max : value > min ? min : value;\n}\n\n/**\n * Clamp a value in the 0–1 range.\n * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#clamp01\n */\nexport function clamp01(value: number): number {\n  return clamp(value, 0, 1);\n}\n\n/**\n * Map a value from one range onto another.\n * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#map\n */\nexport function map(\n  value: number,\n  inputMin: number,\n  inputMax: number,\n  outputMin: number,\n  outputMax: number,\n): number {\n  return ((value - inputMin) * (outputMax - outputMin)) / (inputMax - inputMin) + outputMin;\n}\n\n/**\n * Interpolate a ratio between two bounds.\n * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#lerp\n */\nexport function lerp(min: number, max: number, ratio: number): number {\n  return (1 - ratio) * min + ratio * max;\n}\n\n/**\n * Wrap a value in a range: it leaves by one bound and comes back by the other.\n * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#wrap\n */\nexport function wrap(value: number, min: number, max: number): number {\n  const range = max - min;\n\n  if (!Number.isFinite(range)) {\n    return value;\n  }\n\n  return min === max ? min : ((range + ((value - min) % range)) % range) + min;\n}\n\n/**\n * Fold a value back and forth in a range: it bounces off both bounds.\n * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#fold\n */\nexport function fold(value: number, min: number, max: number): number {\n  const range = max - min;\n\n  if (!Number.isFinite(range) || range <= 0) {\n    return min;\n  }\n\n  const wrapped = wrap(value, min, min + range * 2);\n  return wrapped > max ? 2 * max - wrapped : wrapped;\n}\n\n/**\n * Round a value to the given number of decimals.\n * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#round\n */\nexport function round(value: number, decimals = 0): number {\n  return Number(value.toFixed(decimals));\n}\n\n/**\n * The arithmetic mean of the given numbers. An empty list averages to `0`.\n * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#mean\n */\nexport function mean(numbers: readonly number[]): number {\n  if (numbers.length === 0) {\n    return 0;\n  }\n\n  let sum = 0;\n  for (const value of numbers) {\n    sum += value;\n  }\n  return sum / numbers.length;\n}\n\n/**\n * The values from `min` up to `max`, one step apart.\n *\n * Each value is computed from the index rather than accumulated, so a\n * fractional step does not drift. A step which is not positive and finite\n * describes no range and returns an empty array.\n * @link https://js-toolkit-v4.studiometa.dev/utils/math.html#createrange\n */\nexport function createRange(min: number, max: number, step: number): number[] {\n  if (!Number.isFinite(step) || step <= 0 || !Number.isFinite(max - min) || max < min) {\n    return [];\n  }\n\n  const count = Math.floor((max - min) / step) + 1;\n  return Array.from({ length: count }, (_, index) => min + index * step);\n}\n\n/**\n * Return the fraction retained after `elapsed` milliseconds.\n *\n * Retention is clamped to `[0, 1]`, elapsed time to non-negative values, and non-finite inputs return `0`.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#decayover\n */\nexport function decayOver(retained: number, elapsed: number): number {\n  if (!Number.isFinite(retained) || !Number.isFinite(elapsed)) {\n    return 0;\n  }\n  return Math.min(Math.max(retained, 0), 1) ** (Math.max(elapsed, 0) / INERTIA_FRAME);\n}\n\n/**\n * Return the next time-based damped value and snap within `precision`.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#damp\n */\nexport function damp(\n  targetValue: number,\n  currentValue: number,\n  factor: number,\n  elapsed: number,\n  precision = 0.01,\n): number {\n  if (Math.abs(targetValue - currentValue) < precision) {\n    return targetValue;\n  }\n  // `1 - factor` is what survives the step, which is what decays.\n  const closed = 1 - decayOver(1 - factor, elapsed);\n  return currentValue + (targetValue - currentValue) * closed;\n}\n\n/**\n * Clamp an inertia damping factor to a finite decaying range.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#clampdampfactor\n */\nexport function clampDampFactor(factor: number): number {\n  if (!Number.isFinite(factor)) {\n    return DEFAULT_DAMP_FACTOR;\n  }\n  return Math.min(Math.max(factor, 0), 0.99999);\n}\n\n/**\n * Return the velocity fraction retained after elapsed time.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiadecay\n */\nexport function inertiaDecay(dampFactor: number, elapsed: number): number {\n  return decayOver(clampDampFactor(dampFactor), elapsed);\n}\n\n/**\n * Return the inertia decay time constant in milliseconds.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiatimeconstant\n */\nexport function inertiaTimeConstant(dampFactor: number): number {\n  return INERTIA_FRAME / Math.log(1 / clampDampFactor(dampFactor));\n}\n\n/**\n * Integrate one inertia step exactly for velocity in pixels per millisecond.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiastep\n */\nexport function inertiaStep(velocity: number, dampFactor: number, elapsed: number): number {\n  return velocity * inertiaTimeConstant(dampFactor) * (1 - inertiaDecay(dampFactor, elapsed));\n}\n\n/**\n * Return the exact coast destination for velocity in pixels per millisecond. The destination remains invariant during the coast.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#inertiafinalvalue\n */\nexport function inertiaFinalValue(value: number, velocity: number, dampFactor: number): number {\n  return value + velocity * inertiaTimeConstant(dampFactor);\n}\n\n/** Fixed spring integration step in milliseconds. */\nconst SPRING_STEP = INERTIA_FRAME / 4;\n\n/**\n * Largest stable `stiffness / mass` ratio for {@link SPRING_STEP}.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#max-spring-ratio\n */\nexport const MAX_SPRING_RATIO = (4 / (SPRING_STEP / INERTIA_FRAME) ** 2) * 0.9;\n\nexport interface SpringOptions {\n  /** Pull towards the target, per {@link INERTIA_FRAME}. Defaults to `0.1`. */\n  stiffness?: number;\n  /** Velocity retained per {@link INERTIA_FRAME}, the friction. Defaults to `0.6`. */\n  damping?: number;\n  /** Resistance to acceleration. Defaults to `1`. */\n  mass?: number;\n  /** Distance and velocity under which the spring is at rest. Defaults to `1e-4`. */\n  precision?: number;\n}\n\n/**\n * Advance a spring by elapsed milliseconds with fixed, bounded substeps. Stiffness-to-mass ratio is clamped for stability.\n *\n * Returns the exact target and zero velocity within `precision`.\n * @link https://js-toolkit-v4.studiometa.dev/utils/motion.html#spring\n */\nexport function spring(\n  targetValue: number,\n  currentValue: number,\n  currentVelocity: number,\n  elapsed: number,\n  options: SpringOptions = {},\n): [value: number, velocity: number] {\n  const { stiffness = 0.1, damping = 0.6, mass = 1, precision = 1 / 1e4 } = options;\n\n  if (!Number.isFinite(elapsed) || elapsed <= 0) {\n    return [currentValue, currentVelocity];\n  }\n\n  let value = currentValue;\n  let velocity = currentVelocity;\n  // Bound catch-up work after long pauses.\n  const budget = Math.min(elapsed, 10 * INERTIA_FRAME);\n  const retained = decayOver(damping, SPRING_STEP);\n  const ratio = Number.isFinite(stiffness / mass)\n    ? Math.min(Math.max(stiffness / mass, 0), MAX_SPRING_RATIO)\n    : 0.1;\n  const pull = ratio * (SPRING_STEP / INERTIA_FRAME);\n\n  for (let spent = 0; spent < budget; spent += SPRING_STEP) {\n    velocity = velocity * retained + (targetValue - value) * pull;\n    value += velocity * (SPRING_STEP / INERTIA_FRAME);\n  }\n\n  if (Math.abs(targetValue - value) < precision && Math.abs(velocity) < precision) {\n    return [targetValue, 0];\n  }\n  return [value, velocity];\n}\n"],"mappings":"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"}

package/dist/utils/memo.d.ts

@@ -1,6 +1,16 @@
+//#region src/utils/memo.d.ts
+/** A memoised function with explicit cache invalidation. */
+interface Memo<Args extends unknown[], Value> {
+  (...args: Args): Value;
+  /** Clear all cached results. */
+  clear(): void;
+}
 /**
- * Memoize the result of a function with a single argument indefinitely.
- * This is a simpler implementation of the `memoize` function.
- * @link https://js-toolkit.studiometa.dev/utils/memo.html
+ * Cache a function's result per argument, until told to forget.
+ *
+ * @param fn The function to memoise. It takes one argument, or none.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#memo
  */
-export declare function memo<T extends (...args: unknown[]) => unknown>(fn: T): T;
+declare function memo<Args extends [] | [key: unknown], Value>(fn: (...args: Args) => Value): Memo<Args, Value>;
+//#endregion
+export { Memo, memo };

package/dist/utils/memo.js

@@ -1,14 +1,35 @@
+//#region src/utils/memo.ts
+/** Whether a value can be a `WeakMap` key. */
+function isWeakKey(value) {
+	return typeof value === "object" && value !== null || typeof value === "function";
+}
+/**
+* Cache a function's result per argument, until told to forget.
+*
+* @param fn The function to memoise. It takes one argument, or none.
+* @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#memo
+*/
 function memo(fn) {
-  const cache = /* @__PURE__ */ new Map();
-  return function cached(...args) {
-    const key = args.join("");
-    if (!cache.has(key)) {
-      cache.set(key, fn(...args));
-    }
-    return cache.get(key);
-  };
+	let primitives;
+	let objects;
+	const cached = (...args) => {
+		const key = args[0];
+		if (isWeakKey(key)) {
+			objects ??= /* @__PURE__ */ new WeakMap();
+			if (!objects.has(key)) objects.set(key, fn(...args));
+			return objects.get(key);
+		}
+		primitives ??= /* @__PURE__ */ new Map();
+		if (!primitives.has(key)) primitives.set(key, fn(...args));
+		return primitives.get(key);
+	};
+	cached.clear = () => {
+		primitives?.clear();
+		objects = void 0;
+	};
+	return cached;
 }
-export {
-  memo
-};
-//# sourceMappingURL=memo.js.map
+//#endregion
+export { memo };
+
+//# sourceMappingURL=memo.js.map

package/dist/utils/memo.js.map

@@ -1,7 +1 @@
-{
-  "version": 3,
-  "sources": ["../../../packages/js-toolkit/utils/memo.ts"],
-  "sourcesContent": ["/**\n * Memoize the result of a function with a single argument indefinitely.\n * This is a simpler implementation of the `memoize` function.\n * @link https://js-toolkit.studiometa.dev/utils/memo.html\n */\nexport function memo<T extends (...args: unknown[]) => unknown>(fn: T): T {\n  const cache = new Map<string, ReturnType<T>>();\n\n  // @ts-ignore\n  return function cached(...args) {\n    const key = args.join('');\n    if (!cache.has(key)) {\n      cache.set(key, fn(...args) as ReturnType<T>);\n    }\n    return cache.get(key);\n  };\n}\n"],
-  "mappings": "AAKO,SAAS,KAAgD,IAAU;AACxE,QAAM,QAAQ,oBAAI,IAA2B;AAG7C,SAAO,SAAS,UAAU,MAAM;AAC9B,UAAM,MAAM,KAAK,KAAK,EAAE;AACxB,QAAI,CAAC,MAAM,IAAI,GAAG,GAAG;AACnB,YAAM,IAAI,KAAK,GAAG,GAAG,IAAI,CAAkB;AAAA,IAC7C;AACA,WAAO,MAAM,IAAI,GAAG;AAAA,EACtB;AACF;",
-  "names": []
-}
+{"version":3,"file":"memo.js","names":[],"sources":["../../src/utils/memo.ts"],"sourcesContent":["/** A memoised function with explicit cache invalidation. */\nexport interface Memo<Args extends unknown[], Value> {\n  (...args: Args): Value;\n  /** Clear all cached results. */\n  clear(): void;\n}\n\n/** Whether a value can be a `WeakMap` key. */\nfunction isWeakKey(value: unknown): value is WeakKey {\n  return (typeof value === 'object' && value !== null) || typeof value === 'function';\n}\n\n/**\n * Cache a function's result per argument, until told to forget.\n *\n * @param fn The function to memoise. It takes one argument, or none.\n * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#memo\n */\nexport function memo<Args extends [] | [key: unknown], Value>(\n  fn: (...args: Args) => Value,\n): Memo<Args, Value> {\n  // Allocate only the store required by the key type.\n  let primitives: Map<unknown, Value> | undefined;\n  let objects: WeakMap<WeakKey, Value> | undefined;\n\n  const cached = (...args: Args): Value => {\n    const key = args[0];\n    // `has()` distinguishes a cached `undefined` result from a miss.\n    if (isWeakKey(key)) {\n      objects ??= new WeakMap();\n      if (!objects.has(key)) {\n        objects.set(key, fn(...args));\n      }\n      return objects.get(key) as Value;\n    }\n    primitives ??= new Map();\n    if (!primitives.has(key)) {\n      primitives.set(key, fn(...args));\n    }\n    return primitives.get(key) as Value;\n  };\n\n  cached.clear = (): void => {\n    primitives?.clear();\n    // `WeakMap` has no `clear()`.\n    objects = undefined;\n  };\n\n  return cached;\n}\n"],"mappings":";;AAQA,SAAS,UAAU,OAAkC;CACnD,OAAQ,OAAO,UAAU,YAAY,UAAU,QAAS,OAAO,UAAU;AAC3E;;;;;;;AAQA,SAAgB,KACd,IACmB;CAEnB,IAAI;CACJ,IAAI;CAEJ,MAAM,UAAU,GAAG,SAAsB;EACvC,MAAM,MAAM,KAAK;EAEjB,IAAI,UAAU,GAAG,GAAG;GAClB,4BAAY,IAAI,QAAQ;GACxB,IAAI,CAAC,QAAQ,IAAI,GAAG,GAClB,QAAQ,IAAI,KAAK,GAAG,GAAG,IAAI,CAAC;GAE9B,OAAO,QAAQ,IAAI,GAAG;EACxB;EACA,+BAAe,IAAI,IAAI;EACvB,IAAI,CAAC,WAAW,IAAI,GAAG,GACrB,WAAW,IAAI,KAAK,GAAG,GAAG,IAAI,CAAC;EAEjC,OAAO,WAAW,IAAI,GAAG;CAC3B;CAEA,OAAO,cAAoB;EACzB,YAAY,MAAM;EAElB,UAAU,KAAA;CACZ;CAEA,OAAO;AACT"}

package/dist/utils/noop.d.ts

@@ -1,10 +1,14 @@
+//#region src/utils/noop.d.ts
+/** Placeholders for an optional callback, so a caller never branches on one. */
 /**
- * No operation function.
- *
- * @return {void}
+ * Do nothing, whatever it is called with.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#noop
  */
-export declare function noop(): void;
+declare function noop(): void;
 /**
- * No operation function which return the given value unaltered.
+ * Return the value unaltered: the identity of a transform chain.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#noopvalue
  */
-export declare function noopValue<T>(value: T): T;
+declare function noopValue<T>(value: T): T;
+//#endregion
+export { noop, noopValue };

package/dist/utils/noop.js

@@ -1,10 +1,18 @@
-function noop() {
-}
+//#region src/utils/noop.ts
+/** Placeholders for an optional callback, so a caller never branches on one. */
+/**
+* Do nothing, whatever it is called with.
+* @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#noop
+*/
+function noop() {}
+/**
+* Return the value unaltered: the identity of a transform chain.
+* @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#noopvalue
+*/
 function noopValue(value) {
-  return value;
+	return value;
 }
-export {
-  noop,
-  noopValue
-};
-//# sourceMappingURL=noop.js.map
+//#endregion
+export { noop, noopValue };
+
+//# sourceMappingURL=noop.js.map

package/dist/utils/noop.js.map

@@ -1,7 +1 @@
-{
-  "version": 3,
-  "sources": ["../../../packages/js-toolkit/utils/noop.ts"],
-  "sourcesContent": ["/**\n * No operation function.\n *\n * @return {void}\n */\nexport function noop() {}\n\n/**\n * No operation function which return the given value unaltered.\n */\nexport function noopValue<T>(value: T): T {\n  return value;\n}\n"],
-  "mappings": "AAKO,SAAS,OAAO;AAAC;AAKjB,SAAS,UAAa,OAAa;AACxC,SAAO;AACT;",
-  "names": []
-}
+{"version":3,"file":"noop.js","names":[],"sources":["../../src/utils/noop.ts"],"sourcesContent":["/** Placeholders for an optional callback, so a caller never branches on one. */\n\n/**\n * Do nothing, whatever it is called with.\n * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#noop\n */\nexport function noop(): void {}\n\n/**\n * Return the value unaltered: the identity of a transform chain.\n * @link https://js-toolkit-v4.studiometa.dev/utils/timing.html#noopvalue\n */\nexport function noopValue<T>(value: T): T {\n  return value;\n}\n"],"mappings":";;;;;;AAMA,SAAgB,OAAa,CAAC;;;;;AAM9B,SAAgB,UAAa,OAAa;CACxC,OAAO;AACT"}