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

package/dist/utils/transform.d.ts

@@ -0,0 +1,67 @@
+//#region src/utils/transform.d.ts
+/**
+ * CSS transform strings. Both helpers are pure: they format a value and the
+ * caller hands the write to the scheduler.
+ */
+interface TransformProps {
+  x?: number;
+  y?: number;
+  z?: number;
+  rotate?: number;
+  rotateX?: number;
+  rotateY?: number;
+  rotateZ?: number;
+  scale?: number;
+  scaleX?: number;
+  scaleY?: number;
+  scaleZ?: number;
+  skew?: number;
+  skewX?: number;
+  skewY?: number;
+}
+/**
+ * The properties {@link transform} formats, for callers splitting a style patch.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/css.html#transform-props
+ */
+declare const TRANSFORM_PROPS: readonly (keyof TransformProps)[];
+/**
+ * Format a CSS transform.
+ *
+ * The three axes of a translation are one `translate3d`, and the shorthand of
+ * a rotation, a scale or a skew wins over its per-axis properties.
+ *
+ * @example
+ * ```js
+ * transform({ x: 100, scale: 0.5 });
+ * // translate3d(100px, 0px, 0px) scale(0.5)
+ * ```
+ * @link https://js-toolkit-v4.studiometa.dev/utils/css.html#transform
+ */
+declare function transform(props: TransformProps): string;
+interface MatrixProps {
+  /** The scale on the x axis. Defaults to `1`. */
+  scaleX?: number;
+  /** The scale on the y axis. Defaults to `1`. */
+  scaleY?: number;
+  /** The skew on the x axis. Defaults to `0`. */
+  skewX?: number;
+  /** The skew on the y axis. Defaults to `0`. */
+  skewY?: number;
+  /** The translation on the x axis. Defaults to `0`. */
+  translateX?: number;
+  /** The translation on the y axis. Defaults to `0`. */
+  translateY?: number;
+}
+/**
+ * Format a CSS transform matrix.
+ *
+ * @example
+ * ```js
+ * matrix({ scaleX: 0.5, scaleY: 0.5 });
+ * // matrix(0.5, 0, 0, 0.5, 0, 0)
+ * ```
+ * @link https://js-toolkit-v4.studiometa.dev/utils/css.html#matrix
+ */
+declare function matrix(props?: MatrixProps): string;
+//#endregion
+export { MatrixProps, TRANSFORM_PROPS, TransformProps, matrix, transform };

package/dist/utils/transform.js

@@ -0,0 +1,74 @@
+//#region src/utils/transform.ts
+/**
+* The properties {@link transform} formats, for callers splitting a style patch.
+* @link https://js-toolkit-v4.studiometa.dev/utils/css.html#transform-props
+*/
+const TRANSFORM_PROPS = /* @__PURE__ */ Object.freeze([
+	"x",
+	"y",
+	"z",
+	"rotate",
+	"rotateX",
+	"rotateY",
+	"rotateZ",
+	"scale",
+	"scaleX",
+	"scaleY",
+	"scaleZ",
+	"skew",
+	"skewX",
+	"skewY"
+]);
+/**
+* Format a CSS transform.
+*
+* The three axes of a translation are one `translate3d`, and the shorthand of
+* a rotation, a scale or a skew wins over its per-axis properties.
+*
+* @example
+* ```js
+* transform({ x: 100, scale: 0.5 });
+* // translate3d(100px, 0px, 0px) scale(0.5)
+* ```
+* @link https://js-toolkit-v4.studiometa.dev/utils/css.html#transform
+*/
+function transform(props) {
+	const parts = [];
+	if (props.x !== void 0 || props.y !== void 0 || props.z !== void 0) parts.push(`translate3d(${props.x ?? 0}px, ${props.y ?? 0}px, ${props.z ?? 0}px)`);
+	if (props.rotate !== void 0) parts.push(`rotate(${props.rotate}deg)`);
+	else {
+		if (props.rotateX !== void 0) parts.push(`rotateX(${props.rotateX}deg)`);
+		if (props.rotateY !== void 0) parts.push(`rotateY(${props.rotateY}deg)`);
+		if (props.rotateZ !== void 0) parts.push(`rotateZ(${props.rotateZ}deg)`);
+	}
+	if (props.scale !== void 0) parts.push(`scale(${props.scale})`);
+	else {
+		if (props.scaleX !== void 0) parts.push(`scaleX(${props.scaleX})`);
+		if (props.scaleY !== void 0) parts.push(`scaleY(${props.scaleY})`);
+		if (props.scaleZ !== void 0) parts.push(`scaleZ(${props.scaleZ})`);
+	}
+	if (props.skew !== void 0) parts.push(`skew(${props.skew}deg)`);
+	else {
+		if (props.skewX !== void 0) parts.push(`skewX(${props.skewX}deg)`);
+		if (props.skewY !== void 0) parts.push(`skewY(${props.skewY}deg)`);
+	}
+	return parts.join(" ");
+}
+/**
+* Format a CSS transform matrix.
+*
+* @example
+* ```js
+* matrix({ scaleX: 0.5, scaleY: 0.5 });
+* // matrix(0.5, 0, 0, 0.5, 0, 0)
+* ```
+* @link https://js-toolkit-v4.studiometa.dev/utils/css.html#matrix
+*/
+function matrix(props = {}) {
+	const { scaleX = 1, skewY = 0, skewX = 0, scaleY = 1, translateX = 0, translateY = 0 } = props;
+	return `matrix(${scaleX}, ${skewY}, ${skewX}, ${scaleY}, ${translateX}, ${translateY})`;
+}
+//#endregion
+export { TRANSFORM_PROPS, matrix, transform };
+
+//# sourceMappingURL=transform.js.map

package/dist/utils/transform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.js","names":[],"sources":["../../src/utils/transform.ts"],"sourcesContent":["/**\n * CSS transform strings. Both helpers are pure: they format a value and the\n * caller hands the write to the scheduler.\n */\n\nexport interface TransformProps {\n  x?: number;\n  y?: number;\n  z?: number;\n  rotate?: number;\n  rotateX?: number;\n  rotateY?: number;\n  rotateZ?: number;\n  scale?: number;\n  scaleX?: number;\n  scaleY?: number;\n  scaleZ?: number;\n  skew?: number;\n  skewX?: number;\n  skewY?: number;\n}\n\n/**\n * The properties {@link transform} formats, for callers splitting a style patch.\n * @link https://js-toolkit-v4.studiometa.dev/utils/css.html#transform-props\n */\nexport const TRANSFORM_PROPS = /* @__PURE__ */ Object.freeze([\n  'x',\n  'y',\n  'z',\n  'rotate',\n  'rotateX',\n  'rotateY',\n  'rotateZ',\n  'scale',\n  'scaleX',\n  'scaleY',\n  'scaleZ',\n  'skew',\n  'skewX',\n  'skewY',\n]) as readonly (keyof TransformProps)[];\n\n/**\n * Format a CSS transform.\n *\n * The three axes of a translation are one `translate3d`, and the shorthand of\n * a rotation, a scale or a skew wins over its per-axis properties.\n *\n * @example\n * ```js\n * transform({ x: 100, scale: 0.5 });\n * // translate3d(100px, 0px, 0px) scale(0.5)\n * ```\n * @link https://js-toolkit-v4.studiometa.dev/utils/css.html#transform\n */\nexport function transform(props: TransformProps): string {\n  const parts: string[] = [];\n\n  if (props.x !== undefined || props.y !== undefined || props.z !== undefined) {\n    parts.push(`translate3d(${props.x ?? 0}px, ${props.y ?? 0}px, ${props.z ?? 0}px)`);\n  }\n\n  if (props.rotate !== undefined) {\n    parts.push(`rotate(${props.rotate}deg)`);\n  } else {\n    if (props.rotateX !== undefined) parts.push(`rotateX(${props.rotateX}deg)`);\n    if (props.rotateY !== undefined) parts.push(`rotateY(${props.rotateY}deg)`);\n    if (props.rotateZ !== undefined) parts.push(`rotateZ(${props.rotateZ}deg)`);\n  }\n\n  if (props.scale !== undefined) {\n    parts.push(`scale(${props.scale})`);\n  } else {\n    if (props.scaleX !== undefined) parts.push(`scaleX(${props.scaleX})`);\n    if (props.scaleY !== undefined) parts.push(`scaleY(${props.scaleY})`);\n    if (props.scaleZ !== undefined) parts.push(`scaleZ(${props.scaleZ})`);\n  }\n\n  if (props.skew !== undefined) {\n    parts.push(`skew(${props.skew}deg)`);\n  } else {\n    if (props.skewX !== undefined) parts.push(`skewX(${props.skewX}deg)`);\n    if (props.skewY !== undefined) parts.push(`skewY(${props.skewY}deg)`);\n  }\n\n  return parts.join(' ');\n}\n\nexport interface MatrixProps {\n  /** The scale on the x axis. Defaults to `1`. */\n  scaleX?: number;\n  /** The scale on the y axis. Defaults to `1`. */\n  scaleY?: number;\n  /** The skew on the x axis. Defaults to `0`. */\n  skewX?: number;\n  /** The skew on the y axis. Defaults to `0`. */\n  skewY?: number;\n  /** The translation on the x axis. Defaults to `0`. */\n  translateX?: number;\n  /** The translation on the y axis. Defaults to `0`. */\n  translateY?: number;\n}\n\n/**\n * Format a CSS transform matrix.\n *\n * @example\n * ```js\n * matrix({ scaleX: 0.5, scaleY: 0.5 });\n * // matrix(0.5, 0, 0, 0.5, 0, 0)\n * ```\n * @link https://js-toolkit-v4.studiometa.dev/utils/css.html#matrix\n */\nexport function matrix(props: MatrixProps = {}): string {\n  const { scaleX = 1, skewY = 0, skewX = 0, scaleY = 1, translateX = 0, translateY = 0 } = props;\n  return `matrix(${scaleX}, ${skewY}, ${skewX}, ${scaleY}, ${translateX}, ${translateY})`;\n}\n"],"mappings":";;;;;AA0BA,MAAa,kBAAkC,uBAAO,OAAO;CAC3D;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;;;;;;;;;;;;;AAeD,SAAgB,UAAU,OAA+B;CACvD,MAAM,QAAkB,CAAC;CAEzB,IAAI,MAAM,MAAM,KAAA,KAAa,MAAM,MAAM,KAAA,KAAa,MAAM,MAAM,KAAA,GAChE,MAAM,KAAK,eAAe,MAAM,KAAK,EAAE,MAAM,MAAM,KAAK,EAAE,MAAM,MAAM,KAAK,EAAE,IAAI;CAGnF,IAAI,MAAM,WAAW,KAAA,GACnB,MAAM,KAAK,UAAU,MAAM,OAAO,KAAK;MAClC;EACL,IAAI,MAAM,YAAY,KAAA,GAAW,MAAM,KAAK,WAAW,MAAM,QAAQ,KAAK;EAC1E,IAAI,MAAM,YAAY,KAAA,GAAW,MAAM,KAAK,WAAW,MAAM,QAAQ,KAAK;EAC1E,IAAI,MAAM,YAAY,KAAA,GAAW,MAAM,KAAK,WAAW,MAAM,QAAQ,KAAK;CAC5E;CAEA,IAAI,MAAM,UAAU,KAAA,GAClB,MAAM,KAAK,SAAS,MAAM,MAAM,EAAE;MAC7B;EACL,IAAI,MAAM,WAAW,KAAA,GAAW,MAAM,KAAK,UAAU,MAAM,OAAO,EAAE;EACpE,IAAI,MAAM,WAAW,KAAA,GAAW,MAAM,KAAK,UAAU,MAAM,OAAO,EAAE;EACpE,IAAI,MAAM,WAAW,KAAA,GAAW,MAAM,KAAK,UAAU,MAAM,OAAO,EAAE;CACtE;CAEA,IAAI,MAAM,SAAS,KAAA,GACjB,MAAM,KAAK,QAAQ,MAAM,KAAK,KAAK;MAC9B;EACL,IAAI,MAAM,UAAU,KAAA,GAAW,MAAM,KAAK,SAAS,MAAM,MAAM,KAAK;EACpE,IAAI,MAAM,UAAU,KAAA,GAAW,MAAM,KAAK,SAAS,MAAM,MAAM,KAAK;CACtE;CAEA,OAAO,MAAM,KAAK,GAAG;AACvB;;;;;;;;;;;AA2BA,SAAgB,OAAO,QAAqB,CAAC,GAAW;CACtD,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,MAAM;CACzF,OAAO,UAAU,OAAO,IAAI,MAAM,IAAI,MAAM,IAAI,OAAO,IAAI,WAAW,IAAI,WAAW;AACvF"}

package/dist/utils/transition.d.ts

@@ -0,0 +1,61 @@
+import { OptionDefinition } from "../Base.js";
+//#region src/utils/transition.d.ts
+/**
+ * CSS transition helpers for class names or inline styles. Apply `from`, then
+ * `active` and `to`, and resolve after `transitionend` or on the next frame when no transition runs.
+ */
+type ClassesOrStyles = string | string[] | Partial<CSSStyleDeclaration>;
+interface TransitionStyles {
+  from?: ClassesOrStyles;
+  active?: ClassesOrStyles;
+  to?: ClassesOrStyles;
+}
+/** @link https://js-toolkit-v4.studiometa.dev/utils/css.html#setclassesorstyles */
+declare function setClassesOrStyles(el: HTMLElement, value: ClassesOrStyles | undefined, method?: 'add' | 'remove'): void;
+/**
+ * Run a CSS transition on an element.
+ *
+ * A transition started while another one runs on the same element interrupts
+ * it: the interrupted one removes what it applied and resolves, so a caller
+ * awaiting it is never left waiting for an end which will not come.
+ *
+ * @param mode Whether the `to` state is kept or removed at the end.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#transition
+ */
+declare function transition(el: HTMLElement, nameOrStyles: string | TransitionStyles, mode?: 'keep' | 'remove'): Promise<void>;
+/**
+ * Shared transition option definitions.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#transition-options
+ */
+declare const TRANSITION_OPTIONS: Record<string, OptionDefinition>;
+/**
+ * The resolved values of {@link TRANSITION_OPTIONS}.
+ *
+ * This must be a type alias to satisfy the `Record<string, unknown>` constraint.
+ */
+type TransitionOptions = {
+  enterFrom: string;
+  enterActive: string;
+  enterTo: string;
+  enterKeep: boolean;
+  leaveFrom: string;
+  leaveActive: string;
+  leaveTo: string;
+  leaveKeep: boolean;
+};
+/**
+ * Run the enter transition on an element.
+ *
+ * The opposite direction's `to` classes are cleared first: with `enterKeep` or
+ * `leaveKeep` they are still on the element from the last transition, and a
+ * `to` state left behind fights the one being applied.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#entertransition
+ */
+declare function enterTransition(el: HTMLElement, options: TransitionOptions): Promise<void>;
+/**
+ * Run the leave transition on an element.
+ * @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#leavetransition
+ */
+declare function leaveTransition(el: HTMLElement, options: TransitionOptions): Promise<void>;
+//#endregion
+export { ClassesOrStyles, TRANSITION_OPTIONS, TransitionOptions, TransitionStyles, enterTransition, leaveTransition, setClassesOrStyles, transition };

package/dist/utils/transition.js

@@ -0,0 +1,134 @@
+import { nextFrame } from "../scheduler.js";
+//#region src/utils/transition.ts
+const runs = /* @__PURE__ */ new WeakMap();
+function toClassList(value) {
+	return (Array.isArray(value) ? value : value.split(" ")).filter(Boolean);
+}
+/** @link https://js-toolkit-v4.studiometa.dev/utils/css.html#setclassesorstyles */
+function setClassesOrStyles(el, value, method = "add") {
+	if (!value) return;
+	if (typeof value === "string" || Array.isArray(value)) {
+		el.classList[method](...toClassList(value));
+		return;
+	}
+	for (const [property, propertyValue] of Object.entries(value)) el.style[property] = method === "add" ? propertyValue : "";
+}
+function hasTransition(el) {
+	const { transitionDuration } = window.getComputedStyle(el);
+	return Boolean(transitionDuration) && transitionDuration !== "0s";
+}
+/**
+* Run a CSS transition on an element.
+*
+* A transition started while another one runs on the same element interrupts
+* it: the interrupted one removes what it applied and resolves, so a caller
+* awaiting it is never left waiting for an end which will not come.
+*
+* @param mode Whether the `to` state is kept or removed at the end.
+* @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#transition
+*/
+async function transition(el, nameOrStyles, mode = "remove") {
+	const classesOrStyles = typeof nameOrStyles === "string" ? {
+		from: `${nameOrStyles}-from`,
+		active: `${nameOrStyles}-active`,
+		to: `${nameOrStyles}-to`
+	} : {
+		from: "",
+		active: "",
+		to: "",
+		...nameOrStyles
+	};
+	runs.get(el)?.abort();
+	let onEnd = null;
+	let settle;
+	const ended = new Promise((resolve) => {
+		settle = resolve;
+	});
+	/** Drop the listener, the `active` state and, unless kept, the `to` state. */
+	function end(endMode) {
+		if (runs.get(el) === run) runs.delete(el);
+		if (onEnd) {
+			el.removeEventListener("transitionend", onEnd);
+			onEnd = null;
+		}
+		if (endMode === "remove") setClassesOrStyles(el, classesOrStyles.to, "remove");
+		setClassesOrStyles(el, classesOrStyles.active, "remove");
+	}
+	const run = {
+		aborted: false,
+		abort() {
+			run.aborted = true;
+			end("remove");
+			settle();
+		}
+	};
+	runs.set(el, run);
+	setClassesOrStyles(el, classesOrStyles.from);
+	await nextFrame();
+	if (run.aborted) return;
+	setClassesOrStyles(el, classesOrStyles.active);
+	if (hasTransition(el)) {
+		onEnd = () => settle();
+		el.addEventListener("transitionend", onEnd);
+	}
+	setClassesOrStyles(el, classesOrStyles.from, "remove");
+	setClassesOrStyles(el, classesOrStyles.to);
+	if (!onEnd) nextFrame().then(() => settle());
+	await ended;
+	if (run.aborted) return;
+	end(mode);
+}
+/**
+* Shared transition option definitions.
+* @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#transition-options
+*/
+const TRANSITION_OPTIONS = {
+	enterFrom: String,
+	enterActive: String,
+	enterTo: String,
+	enterKeep: Boolean,
+	leaveFrom: String,
+	leaveActive: String,
+	leaveTo: String,
+	leaveKeep: Boolean
+};
+function removeClasses(el, classes) {
+	const list = classes.split(" ").filter(Boolean);
+	if (list.length > 0) el.classList.remove(...list);
+}
+/**
+* Run the enter transition on an element.
+*
+* The opposite direction's `to` classes are cleared first: with `enterKeep` or
+* `leaveKeep` they are still on the element from the last transition, and a
+* `to` state left behind fights the one being applied.
+* @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#entertransition
+*/
+async function enterTransition(el, options) {
+	const { enterFrom, enterActive, enterTo, enterKeep, leaveTo } = options;
+	removeClasses(el, leaveTo);
+	await nextFrame();
+	await transition(el, {
+		from: enterFrom,
+		active: enterActive,
+		to: enterTo
+	}, enterKeep ? "keep" : "remove");
+}
+/**
+* Run the leave transition on an element.
+* @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#leavetransition
+*/
+async function leaveTransition(el, options) {
+	const { leaveFrom, leaveActive, leaveTo, leaveKeep, enterTo } = options;
+	removeClasses(el, enterTo);
+	await nextFrame();
+	await transition(el, {
+		from: leaveFrom,
+		active: leaveActive,
+		to: leaveTo
+	}, leaveKeep ? "keep" : "remove");
+}
+//#endregion
+export { TRANSITION_OPTIONS, enterTransition, leaveTransition, setClassesOrStyles, transition };
+
+//# sourceMappingURL=transition.js.map

package/dist/utils/transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition.js","names":[],"sources":["../../src/utils/transition.ts"],"sourcesContent":["import type { OptionDefinition } from '../Base.js';\nimport { nextFrame } from '../scheduler.js';\n\n/**\n * CSS transition helpers for class names or inline styles. Apply `from`, then\n * `active` and `to`, and resolve after `transitionend` or on the next frame when no transition runs.\n */\n\nexport type ClassesOrStyles = string | string[] | Partial<CSSStyleDeclaration>;\n\nexport interface TransitionStyles {\n  from?: ClassesOrStyles;\n  active?: ClassesOrStyles;\n  to?: ClassesOrStyles;\n}\n\n/** The run in progress on an element, which a new one interrupts. */\ninterface TransitionRun {\n  aborted: boolean;\n  abort: () => void;\n}\n\nconst runs = new WeakMap<HTMLElement, TransitionRun>();\n\nfunction toClassList(value: string | string[]): string[] {\n  return (Array.isArray(value) ? value : value.split(' ')).filter(Boolean);\n}\n\n/** @link https://js-toolkit-v4.studiometa.dev/utils/css.html#setclassesorstyles */\nexport function setClassesOrStyles(\n  el: HTMLElement,\n  value: ClassesOrStyles | undefined,\n  method: 'add' | 'remove' = 'add',\n): void {\n  if (!value) {\n    return;\n  }\n  if (typeof value === 'string' || Array.isArray(value)) {\n    el.classList[method](...toClassList(value));\n    return;\n  }\n  for (const [property, propertyValue] of Object.entries(value)) {\n    // Removing an inline style means resetting it, not deleting the key.\n    el.style[property as never] = (method === 'add' ? propertyValue : '') as never;\n  }\n}\n\nfunction hasTransition(el: HTMLElement): boolean {\n  const { transitionDuration } = window.getComputedStyle(el);\n  return Boolean(transitionDuration) && transitionDuration !== '0s';\n}\n\n/**\n * Run a CSS transition on an element.\n *\n * A transition started while another one runs on the same element interrupts\n * it: the interrupted one removes what it applied and resolves, so a caller\n * awaiting it is never left waiting for an end which will not come.\n *\n * @param mode Whether the `to` state is kept or removed at the end.\n * @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#transition\n */\nexport async function transition(\n  el: HTMLElement,\n  nameOrStyles: string | TransitionStyles,\n  mode: 'keep' | 'remove' = 'remove',\n): Promise<void> {\n  const classesOrStyles: TransitionStyles =\n    typeof nameOrStyles === 'string'\n      ? {\n          from: `${nameOrStyles}-from`,\n          active: `${nameOrStyles}-active`,\n          to: `${nameOrStyles}-to`,\n        }\n      : { from: '', active: '', to: '', ...nameOrStyles };\n\n  runs.get(el)?.abort();\n\n  let onEnd: (() => void) | null = null;\n  let settle: () => void;\n  const ended = new Promise<void>((resolve) => {\n    settle = resolve;\n  });\n\n  /** Drop the listener, the `active` state and, unless kept, the `to` state. */\n  function end(endMode: 'keep' | 'remove'): void {\n    if (runs.get(el) === run) {\n      runs.delete(el);\n    }\n    if (onEnd) {\n      el.removeEventListener('transitionend', onEnd);\n      onEnd = null;\n    }\n    if (endMode === 'remove') {\n      setClassesOrStyles(el, classesOrStyles.to, 'remove');\n    }\n    setClassesOrStyles(el, classesOrStyles.active, 'remove');\n  }\n\n  const run: TransitionRun = {\n    aborted: false,\n    abort() {\n      run.aborted = true;\n      end('remove');\n      settle();\n    },\n  };\n  runs.set(el, run);\n\n  setClassesOrStyles(el, classesOrStyles.from);\n  await nextFrame();\n  if (run.aborted) return;\n\n  setClassesOrStyles(el, classesOrStyles.active);\n\n  if (hasTransition(el)) {\n    onEnd = () => settle();\n    el.addEventListener('transitionend', onEnd);\n  }\n  setClassesOrStyles(el, classesOrStyles.from, 'remove');\n  setClassesOrStyles(el, classesOrStyles.to);\n  if (!onEnd) {\n    void nextFrame().then(() => settle());\n  }\n\n  await ended;\n  if (run.aborted) return;\n\n  end(mode);\n}\n\n/**\n * Shared transition option definitions.\n * @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#transition-options\n */\nexport const TRANSITION_OPTIONS: Record<string, OptionDefinition> = {\n  enterFrom: String,\n  enterActive: String,\n  enterTo: String,\n  enterKeep: Boolean,\n  leaveFrom: String,\n  leaveActive: String,\n  leaveTo: String,\n  leaveKeep: Boolean,\n};\n\n/**\n * The resolved values of {@link TRANSITION_OPTIONS}.\n *\n * This must be a type alias to satisfy the `Record<string, unknown>` constraint.\n */\nexport type TransitionOptions = {\n  enterFrom: string;\n  enterActive: string;\n  enterTo: string;\n  enterKeep: boolean;\n  leaveFrom: string;\n  leaveActive: string;\n  leaveTo: string;\n  leaveKeep: boolean;\n};\n\nfunction removeClasses(el: HTMLElement, classes: string): void {\n  const list = classes.split(' ').filter(Boolean);\n  if (list.length > 0) {\n    el.classList.remove(...list);\n  }\n}\n\n/**\n * Run the enter transition on an element.\n *\n * The opposite direction's `to` classes are cleared first: with `enterKeep` or\n * `leaveKeep` they are still on the element from the last transition, and a\n * `to` state left behind fights the one being applied.\n * @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#entertransition\n */\nexport async function enterTransition(el: HTMLElement, options: TransitionOptions): Promise<void> {\n  const { enterFrom, enterActive, enterTo, enterKeep, leaveTo } = options;\n  removeClasses(el, leaveTo);\n  await nextFrame();\n  await transition(\n    el,\n    { from: enterFrom, active: enterActive, to: enterTo },\n    enterKeep ? 'keep' : 'remove',\n  );\n}\n\n/**\n * Run the leave transition on an element.\n * @link https://js-toolkit-v4.studiometa.dev/utils/transitions.html#leavetransition\n */\nexport async function leaveTransition(el: HTMLElement, options: TransitionOptions): Promise<void> {\n  const { leaveFrom, leaveActive, leaveTo, leaveKeep, enterTo } = options;\n  removeClasses(el, enterTo);\n  await nextFrame();\n  await transition(\n    el,\n    { from: leaveFrom, active: leaveActive, to: leaveTo },\n    leaveKeep ? 'keep' : 'remove',\n  );\n}\n"],"mappings":";;AAsBA,MAAM,uBAAO,IAAI,QAAoC;AAErD,SAAS,YAAY,OAAoC;CACvD,QAAQ,MAAM,QAAQ,KAAK,IAAI,QAAQ,MAAM,MAAM,GAAG,EAAA,CAAG,OAAO,OAAO;AACzE;;AAGA,SAAgB,mBACd,IACA,OACA,SAA2B,OACrB;CACN,IAAI,CAAC,OACH;CAEF,IAAI,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GAAG;EACrD,GAAG,UAAU,OAAO,CAAC,GAAG,YAAY,KAAK,CAAC;EAC1C;CACF;CACA,KAAK,MAAM,CAAC,UAAU,kBAAkB,OAAO,QAAQ,KAAK,GAE1D,GAAG,MAAM,YAAsB,WAAW,QAAQ,gBAAgB;AAEtE;AAEA,SAAS,cAAc,IAA0B;CAC/C,MAAM,EAAE,uBAAuB,OAAO,iBAAiB,EAAE;CACzD,OAAO,QAAQ,kBAAkB,KAAK,uBAAuB;AAC/D;;;;;;;;;;;AAYA,eAAsB,WACpB,IACA,cACA,OAA0B,UACX;CACf,MAAM,kBACJ,OAAO,iBAAiB,WACpB;EACE,MAAM,GAAG,aAAa;EACtB,QAAQ,GAAG,aAAa;EACxB,IAAI,GAAG,aAAa;CACtB,IACA;EAAE,MAAM;EAAI,QAAQ;EAAI,IAAI;EAAI,GAAG;CAAa;CAEtD,KAAK,IAAI,EAAE,CAAC,EAAE,MAAM;CAEpB,IAAI,QAA6B;CACjC,IAAI;CACJ,MAAM,QAAQ,IAAI,SAAe,YAAY;EAC3C,SAAS;CACX,CAAC;;CAGD,SAAS,IAAI,SAAkC;EAC7C,IAAI,KAAK,IAAI,EAAE,MAAM,KACnB,KAAK,OAAO,EAAE;EAEhB,IAAI,OAAO;GACT,GAAG,oBAAoB,iBAAiB,KAAK;GAC7C,QAAQ;EACV;EACA,IAAI,YAAY,UACd,mBAAmB,IAAI,gBAAgB,IAAI,QAAQ;EAErD,mBAAmB,IAAI,gBAAgB,QAAQ,QAAQ;CACzD;CAEA,MAAM,MAAqB;EACzB,SAAS;EACT,QAAQ;GACN,IAAI,UAAU;GACd,IAAI,QAAQ;GACZ,OAAO;EACT;CACF;CACA,KAAK,IAAI,IAAI,GAAG;CAEhB,mBAAmB,IAAI,gBAAgB,IAAI;CAC3C,MAAM,UAAU;CAChB,IAAI,IAAI,SAAS;CAEjB,mBAAmB,IAAI,gBAAgB,MAAM;CAE7C,IAAI,cAAc,EAAE,GAAG;EACrB,cAAc,OAAO;EACrB,GAAG,iBAAiB,iBAAiB,KAAK;CAC5C;CACA,mBAAmB,IAAI,gBAAgB,MAAM,QAAQ;CACrD,mBAAmB,IAAI,gBAAgB,EAAE;CACzC,IAAI,CAAC,OACH,UAAe,CAAC,CAAC,WAAW,OAAO,CAAC;CAGtC,MAAM;CACN,IAAI,IAAI,SAAS;CAEjB,IAAI,IAAI;AACV;;;;;AAMA,MAAa,qBAAuD;CAClE,WAAW;CACX,aAAa;CACb,SAAS;CACT,WAAW;CACX,WAAW;CACX,aAAa;CACb,SAAS;CACT,WAAW;AACb;AAkBA,SAAS,cAAc,IAAiB,SAAuB;CAC7D,MAAM,OAAO,QAAQ,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO;CAC9C,IAAI,KAAK,SAAS,GAChB,GAAG,UAAU,OAAO,GAAG,IAAI;AAE/B;;;;;;;;;AAUA,eAAsB,gBAAgB,IAAiB,SAA2C;CAChG,MAAM,EAAE,WAAW,aAAa,SAAS,WAAW,YAAY;CAChE,cAAc,IAAI,OAAO;CACzB,MAAM,UAAU;CAChB,MAAM,WACJ,IACA;EAAE,MAAM;EAAW,QAAQ;EAAa,IAAI;CAAQ,GACpD,YAAY,SAAS,QACvB;AACF;;;;;AAMA,eAAsB,gBAAgB,IAAiB,SAA2C;CAChG,MAAM,EAAE,WAAW,aAAa,SAAS,WAAW,YAAY;CAChE,cAAc,IAAI,OAAO;CACzB,MAAM,UAAU;CAChB,MAAM,WACJ,IACA;EAAE,MAAM;EAAW,QAAQ;EAAa,IAAI;CAAQ,GACpD,YAAY,SAAS,QACvB;AACF"}

package/dist/viewTransition.d.ts

@@ -0,0 +1,17 @@
+//#region src/viewTransition.d.ts
+type ViewTransitionUpdate = () => void | Promise<void>;
+/**
+ * Run a DOM update inside a batched, native view transition.
+ *
+ * Updates queued in the same flush batch into a single
+ * `document.startViewTransition()` call; batches are serialized behind the
+ * promise tail. The batch flushes in the scheduler's `write` phase, so it
+ * coordinates with pending writes. Falls back to running the update without
+ * animation when the API is unavailable.
+ *
+ * @returns Resolved once the transition has finished.
+ * @link https://js-toolkit-v4.studiometa.dev/api/scheduler/viewTransition.html
+ */
+declare function viewTransition(update: ViewTransitionUpdate): Promise<void>;
+//#endregion
+export { ViewTransitionUpdate, viewTransition };

package/dist/viewTransition.js

@@ -0,0 +1,52 @@
+import { defaultScheduler } from "./scheduler.js";
+//#region src/viewTransition.ts
+let vtQueue = [];
+let vtIsScheduled = false;
+let vtTail = Promise.resolve();
+/**
+* Run a DOM update inside a batched, native view transition.
+*
+* Updates queued in the same flush batch into a single
+* `document.startViewTransition()` call; batches are serialized behind the
+* promise tail. The batch flushes in the scheduler's `write` phase, so it
+* coordinates with pending writes. Falls back to running the update without
+* animation when the API is unavailable.
+*
+* @returns Resolved once the transition has finished.
+* @link https://js-toolkit-v4.studiometa.dev/api/scheduler/viewTransition.html
+*/
+function viewTransition(update) {
+	return new Promise((resolve, reject) => {
+		vtQueue.push({
+			update,
+			resolve,
+			reject
+		});
+		if (!vtIsScheduled) {
+			vtIsScheduled = true;
+			defaultScheduler.write(flushViewTransitions);
+		}
+	});
+}
+function flushViewTransitions() {
+	const batch = vtQueue;
+	vtQueue = [];
+	vtIsScheduled = false;
+	vtTail = vtTail.then(() => runViewTransitionBatch(batch));
+}
+async function runViewTransitionBatch(batch) {
+	const runAll = async () => {
+		for (const { update } of batch) await update();
+	};
+	try {
+		if (typeof document.startViewTransition === "function") await document.startViewTransition(runAll).finished;
+		else await runAll();
+		for (const { resolve } of batch) resolve();
+	} catch (error) {
+		for (const { reject } of batch) reject(error);
+	}
+}
+//#endregion
+export { viewTransition };
+
+//# sourceMappingURL=viewTransition.js.map

package/dist/viewTransition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewTransition.js","names":[],"sources":["../src/viewTransition.ts"],"sourcesContent":["import { defaultScheduler } from './scheduler.js';\n\nexport type ViewTransitionUpdate = () => void | Promise<void>;\n\ninterface ViewTransitionItem {\n  update: ViewTransitionUpdate;\n  resolve: () => void;\n  reject: (reason: unknown) => void;\n}\n\nlet vtQueue: ViewTransitionItem[] = [];\nlet vtIsScheduled = false;\nlet vtTail = Promise.resolve();\n\n/**\n * Run a DOM update inside a batched, native view transition.\n *\n * Updates queued in the same flush batch into a single\n * `document.startViewTransition()` call; batches are serialized behind the\n * promise tail. The batch flushes in the scheduler's `write` phase, so it\n * coordinates with pending writes. Falls back to running the update without\n * animation when the API is unavailable.\n *\n * @returns Resolved once the transition has finished.\n * @link https://js-toolkit-v4.studiometa.dev/api/scheduler/viewTransition.html\n */\nexport function viewTransition(update: ViewTransitionUpdate): Promise<void> {\n  return new Promise((resolve, reject) => {\n    vtQueue.push({ update, resolve, reject });\n    if (!vtIsScheduled) {\n      vtIsScheduled = true;\n      defaultScheduler.write(flushViewTransitions);\n    }\n  });\n}\n\nfunction flushViewTransitions(): void {\n  const batch = vtQueue;\n  vtQueue = [];\n  vtIsScheduled = false;\n\n  // Every flush appends one batch to the same tail. Two later flushes waiting\n  // for one running transition therefore stay ordered instead of resuming\n  // together when that transition finishes.\n  vtTail = vtTail.then(() => runViewTransitionBatch(batch));\n}\n\nasync function runViewTransitionBatch(batch: ViewTransitionItem[]): Promise<void> {\n  const runAll = async () => {\n    for (const { update } of batch) {\n      await update();\n    }\n  };\n\n  try {\n    if (typeof document.startViewTransition === 'function') {\n      await document.startViewTransition(runAll).finished;\n    } else {\n      await runAll();\n    }\n    for (const { resolve } of batch) resolve();\n  } catch (error) {\n    for (const { reject } of batch) reject(error);\n  }\n}\n"],"mappings":";;AAUA,IAAI,UAAgC,CAAC;AACrC,IAAI,gBAAgB;AACpB,IAAI,SAAS,QAAQ,QAAQ;;;;;;;;;;;;;AAc7B,SAAgB,eAAe,QAA6C;CAC1E,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,QAAQ,KAAK;GAAE;GAAQ;GAAS;EAAO,CAAC;EACxC,IAAI,CAAC,eAAe;GAClB,gBAAgB;GAChB,iBAAiB,MAAM,oBAAoB;EAC7C;CACF,CAAC;AACH;AAEA,SAAS,uBAA6B;CACpC,MAAM,QAAQ;CACd,UAAU,CAAC;CACX,gBAAgB;CAKhB,SAAS,OAAO,WAAW,uBAAuB,KAAK,CAAC;AAC1D;AAEA,eAAe,uBAAuB,OAA4C;CAChF,MAAM,SAAS,YAAY;EACzB,KAAK,MAAM,EAAE,YAAY,OACvB,MAAM,OAAO;CAEjB;CAEA,IAAI;EACF,IAAI,OAAO,SAAS,wBAAwB,YAC1C,MAAM,SAAS,oBAAoB,MAAM,CAAC,CAAC;OAE3C,MAAM,OAAO;EAEf,KAAK,MAAM,EAAE,aAAa,OAAO,QAAQ;CAC3C,SAAS,OAAO;EACd,KAAK,MAAM,EAAE,YAAY,OAAO,OAAO,KAAK;CAC9C;AACF"}