add Tween class

Author: Rich-Harris

packages/svelte/src/motion/private.d.ts

@@ -1,4 +1,4 @@
-export interface TickContext<T> {
+export interface TickContext {
 	inv_mass: number;
 	dt: number;
 	opts: {

packages/svelte/src/motion/spring.js

@@ -12,7 +12,7 @@ import { deferred, noop } from '../internal/shared/utils.js';
 
 /**
  * @template T
- * @param {TickContext<T>} ctx
+ * @param {TickContext} ctx
  * @param {T} last_value
  * @param {T} current_value
  * @param {T} target_value
@@ -108,7 +108,7 @@ export function spring(value, opts = {}) {
 					return false;
 				}
 				inv_mass = Math.min(inv_mass + inv_mass_recovery_rate, 1);
-				/** @type {TickContext<T>} */
+				/** @type {TickContext} */
 				const ctx = {
 					inv_mass,
 					opts: spring,
@@ -152,7 +152,7 @@ export function spring(value, opts = {}) {
  * <script>
  * 	import { Spring } from 'svelte/motion';
  *
- * 	const spring = new Spring({ x: 0, y: 0 });
+ * 	const spring = new Spring(0);
  * </script>
  *
  * <input type="range" bind:value={spring.target} />
@@ -234,7 +234,7 @@ export class Spring {
 			this.#task ??= loop((now) => {
 				this.#inverse_mass = Math.min(this.#inverse_mass + inv_mass_recovery_rate, 1);
 
-				/** @type {import('./private').TickContext<T>} */
+				/** @type {import('./private').TickContext} */
 				const ctx = {
 					inv_mass: this.#inverse_mass,
 					opts: {
@@ -263,7 +263,7 @@ export class Spring {
 	}
 
 	/**
-	 * Sets `spring.target` to `value` and returns a `Promise` if and when `spring.current` catches up to it.
+	 * Sets `spring.target` to `value` and returns a `Promise` that resolves if and when `spring.current` catches up to it.
 	 *
 	 * If `options.instant` is `true`, `spring.current` immediately matches `spring.target`.
 	 *

packages/svelte/src/motion/tweened.js

@@ -6,6 +6,8 @@ import { raf } from '../internal/client/timing.js';
 import { loop } from '../internal/client/loop.js';
 import { linear } from '../easing/index.js';
 import { is_date } from './utils.js';
+import { set, source } from '../internal/client/reactivity/sources.js';
+import { get, render_effect } from 'svelte/internal/client';
 
 /**
  * @template T
@@ -152,3 +154,136 @@ export function tweened(value, defaults = {}) {
 		subscribe: store.subscribe
 	};
 }
+
+/**
+ * A wrapper for a value that tweens smoothly to its target value. Changes to `tween.target` will cause `tween.current` to
+ * move towards it over time, taking account of the `delay`, `duration` and `easing` options.
+ *
+ * ```svelte
+ * <script>
+ * 	import { Tween } from 'svelte/motion';
+ *
+ * 	const tween = new Tween(0);
+ * </script>
+ *
+ * <input type="range" bind:value={tween.target} />
+ * <input type="range" bind:value={tween.current} disabled />
+ * ```
+ * @template T
+ */
+export class Tween {
+	#current = source(/** @type {T} */ (undefined));
+	#target = source(/** @type {T} */ (undefined));
+
+	/** @type {TweenedOptions<T>} */
+	#defaults;
+
+	/** @type {import('../internal/client/types').Task | null} */
+	#task = null;
+
+	/**
+	 * @param {T} value
+	 * @param {TweenedOptions<T>} options
+	 */
+	constructor(value, options = {}) {
+		this.#current.v = this.#target.v = value;
+		this.#defaults = options;
+	}
+
+	/**
+	 * Create a tween whose value is bound to the return value of `fn`. This must be called
+	 * inside an effect root (for example, during component initialisation).
+	 *
+	 * ```svelte
+	 * <script>
+	 * 	import { Tween } from 'svelte/motion';
+	 *
+	 * 	let { number } = $props();
+	 *
+	 * 	const tween = Tween.of(() => number);
+	 * </script>
+	 * ```
+	 * @template U
+	 * @param {() => U} fn
+	 * @param {TweenedOptions<U>} [options]
+	 */
+	static of(fn, options) {
+		const tween = new Tween(fn(), options);
+
+		render_effect(() => {
+			tween.set(fn());
+		});
+
+		return tween;
+	}
+
+	/**
+	 * Sets `tween.target` to `value` and returns a `Promise` that resolves if and when `tween.current` catches up to it.
+	 *
+	 * If `options` are provided, they will override the tween's defaults.
+	 * @param {T} value
+	 * @param {TweenedOptions<T>} [options]
+	 * @returns
+	 */
+	set(value, options) {
+		set(this.#target, value);
+
+		let previous_value = this.#current.v;
+		let previous_task = this.#task;
+
+		let started = false;
+		let {
+			delay = 0,
+			duration = 400,
+			easing = linear,
+			interpolate = get_interpolator
+		} = { ...this.#defaults, ...options };
+
+		const start = raf.now() + delay;
+
+		/** @type {(t: number) => T} */
+		let fn;
+
+		this.#task = loop((now) => {
+			if (now < start) {
+				return true;
+			}
+
+			if (!started) {
+				started = true;
+
+				fn = interpolate(/** @type {any} */ (previous_value), value);
+
+				if (typeof duration === 'function') {
+					duration = duration(/** @type {any} */ (previous_value), value);
+				}
+
+				previous_task?.abort();
+			}
+
+			const elapsed = now - start;
+
+			if (elapsed > /** @type {number} */ (duration)) {
+				set(this.#current, value);
+				return false;
+			}
+
+			set(this.#current, fn(easing(elapsed / /** @type {number} */ (duration))));
+			return true;
+		});
+
+		return this.#task.promise;
+	}
+
+	get current() {
+		return get(this.#current);
+	}
+
+	get target() {
+		return get(this.#target);
+	}
+
+	set target(v) {
+		this.set(v);
+	}
+}

packages/svelte/types/index.d.ts

@@ -1697,7 +1697,7 @@ declare module 'svelte/motion' {
 	 * <script>
 	 * 	import { Spring } from 'svelte/motion';
 	 *
-	 * 	const spring = new Spring({ x: 0, y: 0 });
+	 * 	const spring = new Spring(0);
 	 * </script>
 	 *
 	 * <input type="range" bind:value={spring.target} />
@@ -1732,7 +1732,7 @@ declare module 'svelte/motion' {
 			precision?: number;
 		} | undefined);
 		/**
-		 * Sets `spring.target` to `value` and returns a `Promise` if and when `spring.current` catches up to it.
+		 * Sets `spring.target` to `value` and returns a `Promise` that resolves if and when `spring.current` catches up to it.
 		 *
 		 * If `options.instant` is `true`, `spring.current` immediately matches `spring.target`.
 		 *
@@ -1761,6 +1761,51 @@ declare module 'svelte/motion' {
 	 *
 	 * */
 	export function tweened<T>(value?: T | undefined, defaults?: TweenedOptions<T> | undefined): TweenedStore<T>;
+	/**
+	 * A wrapper for a value that tweens smoothly to its target value. Changes to `tween.target` will cause `tween.current` to
+	 * move towards it over time, taking account of the `delay`, `duration` and `easing` options.
+	 *
+	 * ```svelte
+	 * <script>
+	 * 	import { Tween } from 'svelte/motion';
+	 *
+	 * 	const tween = new Tween(0);
+	 * </script>
+	 *
+	 * <input type="range" bind:value={tween.target} />
+	 * <input type="range" bind:value={tween.current} disabled />
+	 * ```
+	 * */
+	export class Tween<T> {
+		/**
+		 * Create a tween whose value is bound to the return value of `fn`. This must be called
+		 * inside an effect root (for example, during component initialisation).
+		 *
+		 * ```svelte
+		 * <script>
+		 * 	import { Tween } from 'svelte/motion';
+		 *
+		 * 	let { number } = $props();
+		 *
+		 * 	const tween = Tween.of(() => number);
+		 * </script>
+		 * ```
+		 * 
+		 */
+		static of<U>(fn: () => U, options?: TweenedOptions<U> | undefined): Tween<U>;
+		
+		constructor(value: T, options?: TweenedOptions<T>);
+		/**
+		 * Sets `tween.target` to `value` and returns a `Promise` that resolves if and when `tween.current` catches up to it.
+		 *
+		 * If `options` are provided, they will override the tween's defaults.
+		 * */
+		set(value: T, options?: TweenedOptions<T> | undefined): Promise<void>;
+		get current(): T;
+		set target(v: T);
+		get target(): T;
+		#private;
+	}
 
 	export {};
 }