@yahoo/uds-create-config 5.19.1 → 5.20.0

package/dist/entities/system/css-timing.js

@@ -0,0 +1,247 @@
+import { bezierCss, bezierPoints, cssOfMotionEasing, curveOfCssKeyword } from "./easings.js";
+//#region src/entities/system/css-timing.ts
+/**
+* A `motion/react` transition as the CSS timing that plays closest to it: a spring as a duration and
+* a `linear()` easing sampled from the same equations `motion/react` runs, and a tween's named or
+* bezier easing as its CSS spelling.
+*
+* The spring is a port of `motion-dom`'s generator (`animation/generators/spring.mjs`), with the
+* rest thresholds it uses for a value that moves less than 5: a CSS transition plays one curve over
+* a property's whole change, so the curve runs over progress from 0 to 1. Its duration is found and
+* its curve sampled as `spring().toString()` does.
+*/
+const DEFAULTS = {
+	stiffness: 100,
+	damping: 10,
+	mass: 1,
+	durationMs: 800,
+	bounce: .3,
+	restSpeed: .01,
+	restDelta: .005,
+	minDuration: .01,
+	maxDuration: 10,
+	minDamping: .05,
+	maxDamping: 1
+};
+/** The step a settle time is searched in, and the spacing of `linear()`'s points, in milliseconds. */
+const DURATION_STEP = 50;
+const POINT_SPACING = 30;
+const MAX_DURATION = 2e4;
+const clamp = ({ min, max, value }) => Math.min(Math.max(value, min), max);
+const angularFrequency = ({ undamped, ratio }) => undamped * Math.sqrt(1 - ratio * ratio);
+/** Stiffness and damping for a spring given as `duration` and `bounce`, as Framer resolves it. */
+function findSpring({ durationMs, bounce, mass }) {
+	const ratio = clamp({
+		min: DEFAULTS.minDamping,
+		max: DEFAULTS.maxDamping,
+		value: 1 - bounce
+	});
+	const duration = clamp({
+		min: DEFAULTS.minDuration,
+		max: DEFAULTS.maxDuration,
+		value: durationMs / 1e3
+	});
+	const safeMin = .001;
+	let envelope;
+	let derivative;
+	if (ratio < 1) {
+		envelope = (frequency) => {
+			const decay = frequency * ratio;
+			return safeMin - decay / angularFrequency({
+				undamped: frequency,
+				ratio
+			}) * Math.exp(-decay * duration);
+		};
+		derivative = (frequency) => {
+			const decay = frequency * ratio;
+			const e = ratio ** 2 * frequency ** 2 * duration;
+			const f = Math.exp(-decay * duration);
+			const g = angularFrequency({
+				undamped: frequency ** 2,
+				ratio
+			});
+			return (-envelope(frequency) + safeMin > 0 ? -1 : 1) * (-e * f) / g;
+		};
+	} else {
+		envelope = (frequency) => -safeMin + Math.exp(-frequency * duration) * (frequency * duration + 1);
+		derivative = (frequency) => Math.exp(-frequency * duration) * (-frequency * duration * duration);
+	}
+	let frequency = 5 / duration;
+	for (let i = 1; i < 12; i++) frequency -= envelope(frequency) / derivative(frequency);
+	if (Number.isNaN(frequency)) return {
+		stiffness: DEFAULTS.stiffness,
+		damping: DEFAULTS.damping
+	};
+	const stiffness = frequency ** 2 * mass;
+	return {
+		stiffness,
+		damping: ratio * 2 * Math.sqrt(mass * stiffness)
+	};
+}
+/**
+* The spring's physics, and the duration it was given when it was resolved from one. Stiffness,
+* damping or mass take precedence over `duration` and `bounce`, as they do in `motion/react`.
+*/
+function physicsOf(options) {
+	const physical = options.stiffness !== void 0 || options.damping !== void 0 || options.mass !== void 0;
+	const timed = options.duration !== void 0 || options.bounce !== void 0;
+	if (physical || !timed) return {
+		stiffness: options.stiffness ?? DEFAULTS.stiffness,
+		damping: options.damping ?? DEFAULTS.damping,
+		mass: options.mass ?? DEFAULTS.mass
+	};
+	if (options.visualDuration !== void 0) {
+		const root = 2 * Math.PI / (options.visualDuration * 1.2);
+		const stiffness = root * root;
+		return {
+			stiffness,
+			damping: 2 * clamp({
+				min: .05,
+				max: 1,
+				value: 1 - (options.bounce ?? 0)
+			}) * Math.sqrt(stiffness),
+			mass: DEFAULTS.mass
+		};
+	}
+	const durationMs = options.duration !== void 0 ? options.duration * 1e3 : DEFAULTS.durationMs;
+	return {
+		...findSpring({
+			durationMs,
+			bounce: options.bounce ?? DEFAULTS.bounce,
+			mass: DEFAULTS.mass
+		}),
+		mass: DEFAULTS.mass,
+		fixedDurationMs: clamp({
+			min: DEFAULTS.minDuration * 1e3,
+			max: DEFAULTS.maxDuration * 1e3,
+			value: durationMs
+		})
+	};
+}
+/** The spring's progress from 0 to 1 at `t` milliseconds, and whether it has come to rest there. */
+function springCurve({ stiffness, damping, mass, fixedDurationMs }) {
+	const ratio = damping / (2 * Math.sqrt(stiffness * mass));
+	const undamped = Math.sqrt(stiffness / mass) / 1e3;
+	let position;
+	let velocity;
+	if (ratio < 1) {
+		const frequency = angularFrequency({
+			undamped,
+			ratio
+		});
+		const a = ratio * undamped / frequency;
+		const sinCoefficient = ratio * undamped * a + frequency;
+		const cosCoefficient = ratio * undamped - a * frequency;
+		position = (t) => 1 - Math.exp(-ratio * undamped * t) * (a * Math.sin(frequency * t) + Math.cos(frequency * t));
+		velocity = (t) => Math.exp(-ratio * undamped * t) * (sinCoefficient * Math.sin(frequency * t) + cosCoefficient * Math.cos(frequency * t));
+	} else if (ratio === 1) {
+		position = (t) => 1 - Math.exp(-undamped * t) * (1 + undamped * t);
+		velocity = (t) => Math.exp(-undamped * t) * (undamped * undamped * t);
+	} else {
+		const damped = undamped * Math.sqrt(ratio * ratio - 1);
+		const p = ratio * undamped / damped;
+		const sinhCoefficient = ratio * undamped * p - damped;
+		const coshCoefficient = ratio * undamped - p * damped;
+		position = (t) => {
+			const capped = Math.min(damped * t, 300);
+			return 1 - Math.exp(-ratio * undamped * t) * (ratio * undamped * Math.sinh(capped) + damped * Math.cosh(capped)) / damped;
+		};
+		velocity = (t) => {
+			const capped = Math.min(damped * t, 300);
+			return Math.exp(-ratio * undamped * t) * (sinhCoefficient * Math.sinh(capped) + coshCoefficient * Math.cosh(capped));
+		};
+	}
+	return (t) => {
+		const current = position(t);
+		const done = fixedDurationMs !== void 0 ? t >= fixedDurationMs : Math.abs(velocity(t) * 1e3) <= DEFAULTS.restSpeed && Math.abs(1 - current) <= DEFAULTS.restDelta;
+		return {
+			value: done ? 1 : current,
+			done
+		};
+	};
+}
+/** A progress curve sampled into CSS `linear()`, one point per {@link POINT_SPACING} milliseconds. */
+function linearEasing({ curve, duration }) {
+	const count = Math.max(Math.round(duration / POINT_SPACING), 2);
+	return `linear(${Array.from({ length: count }, (_, i) => Math.round(curve(i / (count - 1)) * 1e4) / 1e4).join(", ")})`;
+}
+/** A spring as the CSS duration and `linear()` easing that play it. */
+function springTiming(options) {
+	const at = springCurve(physicsOf(options));
+	let duration = 0;
+	while (!at(duration).done && duration < MAX_DURATION) duration += DURATION_STEP;
+	return {
+		duration,
+		easing: linearEasing({
+			curve: (progress) => at(duration * progress).value,
+			duration
+		})
+	};
+}
+/** A cubic Bézier easing from 0 to 1, solved for x by bisection. */
+function cubicBezier([x1, y1, x2, y2]) {
+	const at = (t, [a, b]) => ((1 - 3 * b + 3 * a) * t + (3 * b - 6 * a)) * t * t + 3 * a * t;
+	return (progress) => {
+		if (progress <= 0 || progress >= 1) return progress <= 0 ? 0 : 1;
+		let lower = 0;
+		let upper = 1;
+		let t = progress;
+		for (let i = 0; i < 24; i++) {
+			if (at(t, [x1, x2]) > progress) upper = t;
+			else lower = t;
+			t = (lower + upper) / 2;
+		}
+		return at(t, [y1, y2]);
+	};
+}
+const reverse = (easing) => (p) => 1 - easing(1 - p);
+const mirror = (easing) => (p) => p <= .5 ? easing(2 * p) / 2 : (2 - easing(2 * (1 - p))) / 2;
+const backIn = reverse(cubicBezier([
+	.33,
+	1.53,
+	.69,
+	.99
+]));
+const circIn = (p) => 1 - Math.sin(Math.acos(p));
+function anticipate(p) {
+	if (p >= 1) return 1;
+	if (p < .5) return .5 * backIn(p * 2);
+	return .5 * (2 - 2 ** (-10 * (p * 2 - 1)));
+}
+/** The easings `motion/react` names that CSS has no keyword or Bézier for, as curves to sample. */
+const SAMPLED_EASINGS = {
+	backIn,
+	backInOut: mirror(backIn),
+	circIn,
+	circOut: reverse(circIn),
+	circInOut: mirror(circIn),
+	anticipate
+};
+/**
+* A tween's `ease` as CSS: a name `motion/react` gives, a curve of four numbers, or a CSS easing as it
+* stands. `undefined` for anything else, such as a list of easings, one per keyframe.
+*/
+function cssEasing({ ease, duration }) {
+	if (Array.isArray(ease) && ease.length === 4 && ease.every((n) => typeof n === "number")) return bezierCss(ease);
+	if (typeof ease !== "string") return void 0;
+	const name = ease.trim();
+	const named = cssOfMotionEasing(name);
+	if (named !== void 0) return named;
+	if (Object.hasOwn(SAMPLED_EASINGS, name)) return linearEasing({
+		curve: SAMPLED_EASINGS[name],
+		duration
+	});
+	return name.length > 0 ? name : void 0;
+}
+/**
+* A CSS easing as the curve it plays, for `linear`, a keyword or a `cubic-bezier()`. `undefined` for
+* any other, such as a `linear()` with points or a `var()`.
+*/
+function easingCurve(easing) {
+	const text = easing.trim();
+	if (text === "linear") return (progress) => progress;
+	const curve = curveOfCssKeyword(text) ?? bezierPoints(text);
+	return curve ? cubicBezier(curve) : void 0;
+}
+//#endregion
+export { cssEasing, easingCurve, linearEasing, springTiming };

package/dist/entities/system/easings.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The easings both runtimes name, in one table: `motion/react`'s names (`easeOut`), CSS's keywords
+ * (`ease-out`), and the Bézier curve each one is. A JS preset's `ease` is read to CSS through it, a CSS
+ * easing to `motion/react`'s through it, and a conversion between runtimes goes through both.
+ */
+/** A cubic Bézier curve's four control-point coordinates. */
+export type BezierCurve = readonly [number, number, number, number];
+/** The names `motion/react` gives easings that are no Bézier curve, which CSS plays as a sampled
+ *  `linear()`. */
+export declare const SAMPLED_MOTION_EASINGS: readonly ["backIn", "backInOut", "circIn", "circOut", "circInOut", "anticipate"];
+export type SampledMotionEasing = (typeof SAMPLED_MOTION_EASINGS)[number];
+/** Every easing name `motion/react` reads. */
+export declare const MOTION_EASING_NAMES: ReadonlySet<string>;
+export declare const CUBIC_BEZIER: RegExp;
+/** A `cubic-bezier()`'s four numbers, or `undefined` for any other text. */
+export declare function bezierPoints(text: string): BezierCurve | undefined;
+export declare const bezierCss: (curve: readonly number[]) => string;
+/**
+ * A `motion/react` easing name as CSS: `linear`, or the `cubic-bezier()` it is. `undefined` for a name
+ * with no curve (the sampled ones) and for anything else.
+ */
+export declare function cssOfMotionEasing(name: string): string | undefined;
+/**
+ * A CSS keyword as `motion/react` takes it: its name, or the curve where `motion/react` has no name
+ * for it (`ease`). `undefined` for anything that is no keyword.
+ */
+export declare function motionOfCssKeyword(keyword: string): string | BezierCurve | undefined;
+/** A CSS keyword's curve, `undefined` for `linear` and for anything that is no keyword. */
+export declare function curveOfCssKeyword(keyword: string): BezierCurve | undefined;

package/dist/entities/system/easings.js

@@ -0,0 +1,99 @@
+//#region src/entities/system/easings.ts
+const NAMED_EASINGS = [
+	{
+		motion: "linear",
+		css: "linear"
+	},
+	{
+		motion: "easeIn",
+		css: "ease-in",
+		curve: [
+			.42,
+			0,
+			1,
+			1
+		]
+	},
+	{
+		motion: "easeOut",
+		css: "ease-out",
+		curve: [
+			0,
+			0,
+			.58,
+			1
+		]
+	},
+	{
+		motion: "easeInOut",
+		css: "ease-in-out",
+		curve: [
+			.42,
+			0,
+			.58,
+			1
+		]
+	},
+	{
+		css: "ease",
+		curve: [
+			.25,
+			.1,
+			.25,
+			1
+		]
+	},
+	{
+		motion: "backOut",
+		curve: [
+			.33,
+			1.53,
+			.69,
+			.99
+		]
+	}
+];
+/** The names `motion/react` gives easings that are no Bézier curve, which CSS plays as a sampled
+*  `linear()`. */
+const SAMPLED_MOTION_EASINGS = [
+	"backIn",
+	"backInOut",
+	"circIn",
+	"circOut",
+	"circInOut",
+	"anticipate"
+];
+/** Every easing name `motion/react` reads. */
+const MOTION_EASING_NAMES = new Set([...NAMED_EASINGS.flatMap((easing) => easing.motion === void 0 ? [] : [easing.motion]), ...SAMPLED_MOTION_EASINGS]);
+const CUBIC_BEZIER = /^cubic-bezier\(\s*([^,\s]+)\s*,\s*([^,\s]+)\s*,\s*([^,\s]+)\s*,\s*([^,\s)]+)\s*\)$/;
+/** A `cubic-bezier()`'s four numbers, or `undefined` for any other text. */
+function bezierPoints(text) {
+	const points = CUBIC_BEZIER.exec(text.trim())?.slice(1).map(Number);
+	if (!points?.every(Number.isFinite)) return void 0;
+	return points;
+}
+const bezierCss = (curve) => `cubic-bezier(${curve.join(", ")})`;
+/**
+* A `motion/react` easing name as CSS: `linear`, or the `cubic-bezier()` it is. `undefined` for a name
+* with no curve (the sampled ones) and for anything else.
+*/
+function cssOfMotionEasing(name) {
+	const easing = NAMED_EASINGS.find((entry) => entry.motion === name);
+	if (!easing) return void 0;
+	return easing.curve ? bezierCss(easing.curve) : easing.css;
+}
+/**
+* A CSS keyword as `motion/react` takes it: its name, or the curve where `motion/react` has no name
+* for it (`ease`). `undefined` for anything that is no keyword.
+*/
+function motionOfCssKeyword(keyword) {
+	const easing = NAMED_EASINGS.find((entry) => entry.css === keyword);
+	if (!easing) return void 0;
+	return easing.motion ?? easing.curve;
+}
+/** A CSS keyword's curve, `undefined` for `linear` and for anything that is no keyword. */
+function curveOfCssKeyword(keyword) {
+	return NAMED_EASINGS.find((entry) => entry.css === keyword)?.curve;
+}
+//#endregion
+export { MOTION_EASING_NAMES, bezierCss, bezierPoints, cssOfMotionEasing, curveOfCssKeyword, motionOfCssKeyword };

package/dist/entities/system/motion-convert.d.ts

@@ -0,0 +1,42 @@
+//#region src/entities/system/motion-convert.d.ts
+/** One field a conversion leaves out, plays differently, or can't carry over. */
+interface MotionConversionNote {
+  /** Where the field sits, as a dotted path: `transition.opacity.repeat`. */
+  readonly at: string;
+  readonly reason: string;
+}
+interface MotionConversion {
+  /** The preset as the other runtime takes it. `undefined` when the conversion is refused. */
+  readonly body?: Record<string, unknown>;
+  /** Fields the other runtime has no counterpart for, left out. */
+  readonly dropped: readonly MotionConversionNote[];
+  /** Fields carried over that the other runtime plays differently than written. */
+  readonly approximated: readonly MotionConversionNote[];
+  /** Fields the other runtime can't represent, which refuse the conversion. */
+  readonly refused: readonly MotionConversionNote[];
+}
+type MotionRuntime = 'css' | 'js';
+type Body = Record<string, unknown>;
+/** `body` as the `to` runtime takes it, with what the conversion left out, changed or refused. */
+declare function convertMotion({
+  body,
+  to
+}: {
+  body: Body;
+  to: MotionRuntime;
+}): MotionConversion;
+/** What `motion/convert-plan` answers: the conversion `motion/convert` would make, and where it
+ *  would write it. */
+interface MotionConversionPlan {
+  readonly path: string;
+  readonly to: MotionRuntime;
+  /** The linked system the preset is borrowed from, whose link the conversion is written to. */
+  readonly link?: string;
+  readonly dropped: readonly MotionConversionNote[];
+  readonly approximated: readonly MotionConversionNote[];
+  readonly refused: readonly MotionConversionNote[];
+  /** Why the conversion would be refused. `undefined` when it would go through. */
+  readonly blocked?: string;
+}
+//#endregion
+export { MotionConversion, MotionConversionNote, MotionConversionPlan, MotionRuntime, convertMotion };