@yahoo/uds-create-config 5.19.1 → 5.21.0

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

@@ -0,0 +1,445 @@
+import { isPlainObject } from "../../framework/utils/field-path.js";
+import { createSliceMemo } from "../../framework/memo.js";
+import { cssEasing, easingCurve, linearEasing, springTiming } from "./css-timing.js";
+import { stateVariantNames } from "./motion-variants.js";
+import { resolvePresetValue } from "./motion-presets.js";
+//#region src/entities/system/css-motion.ts
+/** The states a CSS preset changes to. `initial` is where it starts, so nothing transitions to it. */
+const CSS_MOTION_STATES = [
+	"animate",
+	"exit",
+	"whileHover",
+	"whileTap",
+	"whileFocus"
+];
+/** `motion/react`'s transform values, which move on a spring by default. */
+const TRANSFORM_VALUES = new Set([
+	"transformPerspective",
+	"x",
+	"y",
+	"z",
+	"translateX",
+	"translateY",
+	"translateZ",
+	"scale",
+	"scaleX",
+	"scaleY",
+	"rotate",
+	"rotateX",
+	"rotateY",
+	"rotateZ",
+	"skew",
+	"skewX",
+	"skewY"
+]);
+/** Keys of a transition that don't say how a value moves, so one holding only these takes the default. */
+const ORCHESTRATION_KEYS = new Set([
+	"when",
+	"delay",
+	"delayChildren",
+	"staggerChildren",
+	"staggerDirection",
+	"repeat",
+	"repeatType",
+	"repeatDelay",
+	"from",
+	"elapsed"
+]);
+/** Keys of a state's values that are not values. */
+const STATE_META_KEYS = new Set(["transition", "transitionEnd"]);
+const CSS_TIME = /^(-?(?:\d+(?:\.\d*)?|\.\d+))(ms|s)$/;
+/** A time in milliseconds: a number is seconds, as `motion/react` reads it, and a CSS time is read as
+*  written. `undefined` for a string that is no plain time, such as a `var()`. */
+function milliseconds(value) {
+	if (typeof value === "number") return value * 1e3;
+	if (typeof value !== "string") return void 0;
+	const time = CSS_TIME.exec(value.trim());
+	if (!time) return void 0;
+	return time[2] === "ms" ? Number(time[1]) : Number(time[1]) * 1e3;
+}
+/** A time as CSS: whole milliseconds, or the string as written when it is no plain time. */
+function cssTime(value) {
+	const ms = milliseconds(value);
+	if (ms !== void 0) return `${Math.round(ms)}ms`;
+	return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+}
+const numberOf = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+/** `motion/react`'s default for a value with no transition of its own (`getDefaultTransition`). */
+function defaultTransition({ key, value }) {
+	if (Array.isArray(value) && value.length > 2) return {
+		type: "keyframes",
+		duration: .8
+	};
+	if (TRANSFORM_VALUES.has(key)) {
+		if (!key.startsWith("scale")) return {
+			type: "spring",
+			stiffness: 500,
+			damping: 25
+		};
+		const target = Array.isArray(value) ? value.at(-1) : value;
+		return {
+			type: "spring",
+			stiffness: 550,
+			damping: Number(target) === 0 ? 2 * Math.sqrt(550) : 30
+		};
+	}
+	return {
+		type: "keyframes",
+		ease: [
+			.25,
+			.1,
+			.35,
+			1
+		],
+		duration: .3
+	};
+}
+/**
+* The transition one value moves on, as `motion/react`'s `getValueTransition` picks it, and the path
+* it was written at.
+*/
+function valueTransition({ transition, at, key, value }) {
+	let picked = transition;
+	let pickedAt = at;
+	for (const field of [key, "default"]) {
+		const own = transition?.[field];
+		if (!isPlainObject(own)) continue;
+		picked = own;
+		pickedAt = `${at}.${field}`;
+		break;
+	}
+	if (Object.keys(picked ?? {}).some((field) => !ORCHESTRATION_KEYS.has(field))) return {
+		transition: picked,
+		at: pickedAt
+	};
+	return {
+		transition: {
+			...defaultTransition({
+				key,
+				value
+			}),
+			...picked?.delay !== void 0 ? { delay: picked.delay } : {}
+		},
+		at: pickedAt
+	};
+}
+/** One value's resolved transition as CSS, reporting an easing it can't spell. */
+function timingOf({ transition, at, report }) {
+	const delay = cssTime(transition.delay);
+	const withDelay = (timing) => delay !== void 0 && delay !== "0ms" ? {
+		...timing,
+		delay
+	} : timing;
+	if (transition.type === "spring") {
+		const spring = springTiming({
+			stiffness: numberOf(transition.stiffness),
+			damping: numberOf(transition.damping),
+			mass: numberOf(transition.mass),
+			bounce: numberOf(transition.bounce),
+			duration: numberOf(transition.duration),
+			visualDuration: numberOf(transition.visualDuration)
+		});
+		return withDelay({
+			duration: cssTime(transition.playFor) ?? `${spring.duration}ms`,
+			easing: spring.easing
+		});
+	}
+	const duration = cssTime(transition.duration ?? .3) ?? "300ms";
+	const durationMs = milliseconds(duration) ?? 300;
+	let easing;
+	if (typeof transition.easing === "string") easing = transition.easing.trim();
+	else if (transition.ease !== void 0) {
+		easing = cssEasing({
+			ease: transition.ease,
+			duration: durationMs
+		});
+		if (easing === void 0) report({
+			at: `${at}.ease`,
+			problem: "easing"
+		});
+	}
+	return withDelay({
+		duration,
+		easing: easing ?? "cubic-bezier(0, 0, 0.58, 1)"
+	});
+}
+/** The timing of each value a destination sets. */
+function timingsFor({ target, transition, at, report }) {
+	const out = {};
+	for (const [key, value] of Object.entries(target)) {
+		if (STATE_META_KEYS.has(key)) continue;
+		const picked = valueTransition({
+			transition,
+			at,
+			key,
+			value
+		});
+		const timing = timingOf({
+			...picked,
+			report
+		});
+		const hold = heldFor({
+			value,
+			times: picked.transition.times
+		});
+		if (hold === void 0) out[key] = timing;
+		else if (ACCELERATED_VALUES.has(key)) out[key] = heldWhole({
+			timing,
+			hold
+		});
+		else out[key] = held({
+			timing,
+			hold
+		});
+	}
+	return out;
+}
+/**
+* The share of a keyframe list's time it holds its first value before it moves, for a list that
+* holds and then moves to its last (`[0.7, 0.7, 1]`), which a transition plays as a delay. Its
+* `times` say where the move starts; without them the keyframes are evenly spaced. `undefined` for
+* any other value.
+*/
+function heldFor({ value, times }) {
+	if (!holdsThenMoves(value)) return void 0;
+	const start = value.length - 2;
+	if (Array.isArray(times) && times.length === value.length && typeof times[start] === "number") return times[start];
+	return start / (value.length - 1);
+}
+/** Whether a value is a keyframe list that holds its first value and then moves to its last. */
+function holdsThenMoves(value) {
+	if (!Array.isArray(value) || value.length < 3) return false;
+	const first = JSON.stringify(value[0]);
+	return value.slice(1, -1).every((step) => JSON.stringify(step) === first);
+}
+/**
+* The values `motion/react` hands to the browser's own animations (`acceleratedValues`), which ease a
+* keyframe list as a whole: the keyframes sit at their `times`, and the easing runs over all of them.
+* Every other value it animates itself, easing each keyframe to the next on its own.
+*/
+const ACCELERATED_VALUES = new Set([
+	"opacity",
+	"clipPath",
+	"filter",
+	"transform"
+]);
+/**
+* A hold eased as a whole, as the browser plays an accelerated value's keyframes: the full duration,
+* on a curve that stays at the start until the easing passes the hold and then moves in a line to
+* the end. An easing that is no curve, such as a `linear()` from a spring, waits out the hold instead.
+*/
+function heldWhole({ timing, hold }) {
+	const curve = easingCurve(timing.easing);
+	const duration = milliseconds(timing.duration);
+	if (!curve || duration === void 0) return held({
+		timing,
+		hold
+	});
+	return {
+		...timing,
+		easing: linearEasing({
+			curve: (progress) => Math.max(0, (curve(progress) - hold) / (1 - hold)),
+			duration
+		})
+	};
+}
+/** A timing that waits out the hold: its delay grows by the held share and its duration shrinks. */
+function held({ timing, hold }) {
+	const duration = milliseconds(timing.duration);
+	if (duration === void 0) return timing;
+	const delay = (milliseconds(timing.delay) ?? 0) + duration * hold;
+	return {
+		...timing,
+		duration: `${Math.round(duration * (1 - hold))}ms`,
+		delay: `${Math.round(delay)}ms`
+	};
+}
+/** Whether a CSS preset animates states, rather than only playing keyframes. */
+function hasStates(body) {
+	return body.variants !== void 0 || body.initial !== void 0 || CSS_MOTION_STATES.some((state) => body[state] !== void 0);
+}
+/** A spring's time as the spring reads it, in seconds: a token's value has been read to seconds
+*  already, and a CSS time is converted. */
+function springSeconds(value) {
+	if (typeof value === "number") return value;
+	const ms = milliseconds(value);
+	return ms === void 0 ? void 0 : ms / 1e3;
+}
+/**
+* A CSS timing as the reader below takes it, which is how `motion/react` writes one: a spring easing
+* as `type: 'spring'` with its fields, and a value's own timing under its name. A `duration` beside a
+* spring is how long the curve plays, `playFor`, since a spring's own `duration` is its settle time.
+*/
+function readable(timing) {
+	const { properties, easing, duration, ...rest } = timing;
+	const out = { ...rest };
+	if (isPlainObject(easing) && isPlainObject(easing.spring)) {
+		const spring = easing.spring;
+		out.type = "spring";
+		for (const key of [
+			"stiffness",
+			"damping",
+			"mass",
+			"bounce"
+		]) if (spring[key] !== void 0) out[key] = spring[key];
+		for (const key of ["duration", "visualDuration"]) {
+			const seconds = springSeconds(spring[key]);
+			if (seconds !== void 0) out[key] = seconds;
+		}
+		if (duration !== void 0) out.playFor = duration;
+	} else {
+		if (easing !== void 0) out.easing = easing;
+		if (duration !== void 0) out.duration = duration;
+	}
+	for (const [key, value] of Object.entries(isPlainObject(properties) ? properties : {})) if (isPlainObject(value)) out[key] = readable(value);
+	return out;
+}
+/** A preset's own transition, or a destination's, with its tokens read to values. */
+function resolvedTransition({ config, value, at, report }) {
+	if (!isPlainObject(value)) return void 0;
+	const resolved = resolvePresetValue({
+		config,
+		value,
+		at,
+		report
+	});
+	return isPlainObject(resolved?.value) ? readable(resolved.value) : void 0;
+}
+function transitionsOf({ config, body, report }) {
+	const shared = resolvedTransition({
+		config,
+		value: body.transition,
+		at: "transition",
+		report
+	});
+	const destination = ({ target, at }) => {
+		const own = resolvedTransition({
+			config,
+			value: target.transition,
+			at: `${at}.transition`,
+			report
+		});
+		return timingsFor({
+			target,
+			transition: own ?? shared,
+			at: own ? `${at}.transition` : "transition",
+			report
+		});
+	};
+	const every = {};
+	const variants = {};
+	for (const [name, target] of Object.entries(isPlainObject(body.variants) ? body.variants : {})) {
+		if (!isPlainObject(target)) continue;
+		Object.assign(every, target);
+		variants[name] = destination({
+			target,
+			at: `variants.${name}`
+		});
+	}
+	const states = {};
+	for (const state of CSS_MOTION_STATES) {
+		const target = body[state];
+		if (!isPlainObject(target)) continue;
+		Object.assign(every, target);
+		states[state] = destination({
+			target,
+			at: state
+		});
+	}
+	return {
+		values: timingsFor({
+			target: every,
+			transition: shared,
+			at: "transition",
+			report
+		}),
+		variants,
+		states
+	};
+}
+/** Every value in a preset's states written as a keyframe list. */
+function keyframeLists({ preset, body }) {
+	const targets = [...Object.entries(isPlainObject(body.variants) ? body.variants : {}).map(([name, target]) => [`variants.${name}`, target]), ...CSS_MOTION_STATES.map((state) => [state, body[state]])];
+	const out = [];
+	for (const [at, target] of targets) {
+		if (!isPlainObject(target)) continue;
+		for (const [key, value] of Object.entries(target)) if (Array.isArray(value) && value.length > 1 && !holdsThenMoves(value)) out.push({
+			preset,
+			at: `${at}.${key}`
+		});
+	}
+	return out;
+}
+const resolveCssMotionPresets = createSliceMemo({
+	kinds: [
+		"motion",
+		"token",
+		"settings",
+		"font"
+	],
+	compute: (config) => {
+		const transitions = {};
+		const lists = [];
+		const tokens = [];
+		const reported = /* @__PURE__ */ new Set();
+		const report = (entry) => {
+			const key = JSON.stringify([
+				entry.preset,
+				entry.at,
+				entry.token,
+				entry.problem
+			]);
+			if (reported.has(key)) return;
+			reported.add(key);
+			tokens.push(entry);
+		};
+		for (const preset of config.list("motion")) {
+			const body = preset.toJSON();
+			if (body.runtime !== "css") continue;
+			if (!hasStates(body)) continue;
+			lists.push(...keyframeLists({
+				preset: preset.path,
+				body
+			}));
+			transitions[preset.path] = transitionsOf({
+				config,
+				body,
+				report: (problem) => report({
+					preset: preset.path,
+					...problem
+				})
+			});
+		}
+		return {
+			transitions,
+			keyframeLists: lists,
+			tokens
+		};
+	}
+});
+/** Every CSS preset that animates states, by path, with the timing of each value per destination. */
+function cssMotionTransitions(config) {
+	return resolveCssMotionPresets(config).transitions;
+}
+/**
+* How long a CSS preset's `exit` takes, in milliseconds: the longest of its values' durations and
+* delays as the element changes to its exit state. `0` for a preset with no exit, and a timing that is
+* no plain time (a `var()`) counts as none.
+*/
+function cssMotionExitDuration({ config, preset }) {
+	const transitions = cssMotionTransitions(config)[preset];
+	const exit = (config.resolve("motion", preset)?.toJSON())?.exit;
+	if (!transitions || exit === void 0) return 0;
+	const timings = isPlainObject(exit) ? [transitions.states.exit ?? {}] : stateVariantNames(exit).map((name) => transitions.variants[name] ?? {});
+	return Math.max(0, ...timings.flatMap((group) => Object.values(group).map((timing) => (milliseconds(timing.duration) ?? 0) + (milliseconds(timing.delay) ?? 0))));
+}
+/** Every value a CSS preset's states write as a keyframe list, for the build to report. */
+function cssMotionKeyframeLists(config) {
+	return resolveCssMotionPresets(config).keyframeLists;
+}
+/** The tokens CSS presets' transitions name that come to no value, and the easings CSS can't spell. */
+function cssMotionTokens(config) {
+	return resolveCssMotionPresets(config).tokens;
+}
+//#endregion
+export { CSS_MOTION_STATES, cssMotionExitDuration, cssMotionKeyframeLists, cssMotionTokens, cssMotionTransitions };

package/dist/entities/system/css-timing.d.ts

@@ -0,0 +1,40 @@
+//#region src/entities/system/css-timing.d.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.
+ */
+/** The spring fields `motion/react` reads. Times are in seconds, as a transition writes them. */
+interface SpringOptions {
+  readonly stiffness?: number;
+  readonly damping?: number;
+  readonly mass?: number;
+  readonly bounce?: number;
+  readonly duration?: number;
+  readonly visualDuration?: number;
+}
+/** A CSS timing: the duration in milliseconds and the easing function. */
+interface SpringTiming {
+  readonly duration: number;
+  readonly easing: string;
+}
+/** A spring as the CSS duration and `linear()` easing that play it. */
+declare function springTiming(options: SpringOptions): SpringTiming;
+/**
+ * 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.
+ */
+declare function cssEasing({
+  ease,
+  duration
+}: {
+  ease: unknown; /** The tween's duration in milliseconds, which sets how many points a sampled easing gets. */
+  duration: number;
+}): string | undefined;
+//#endregion
+export { SpringOptions, SpringTiming, cssEasing, springTiming };