sard 1.0.0 → 1.0.2

package/utils/regexp.d.ts

@@ -0,0 +1 @@
+export declare function escapeRegExp(str: string): string;

package/utils/regexp.js

@@ -0,0 +1,6 @@
+//#region packages/sard/utils/regexp.ts
+function escapeRegExp(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+export { escapeRegExp };

package/utils/scroller/Friction.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 惯性衰减模拟器。用于计算带有指数衰减阻尼的滚动位置和速度。
+ *
+ * 该模型假定速度随时间按 `damping^t` 衰减，位置则是该速度衰减曲线的积分。
+ *
+ * 所有 API 单位：位置 px，速度 px/s，时间 s。
+ */
+export declare class Friction {
+    /** 阻尼因子，通常小于 1。越接近 1，衰减越慢。 */
+    private damping;
+    /** 运动起始位置（px）。 */
+    private x;
+    /** 运动起始速度（px/s）。 */
+    private v;
+    /** 记录 `set()` 调用时的时间戳（毫秒）。 */
+    private startTime;
+    /**
+     * @param damping 阻尼因子，用于控制速度指数衰减的底数。
+     */
+    constructor(damping: number);
+    /**
+     * 初始化当前位置和速度，并重置时间基准。
+     *
+     * @param x 初始位置（px）
+     * @param v 初始速度（px/s）
+     */
+    set(x: number, v: number): void;
+    /**
+     * 在知道目标终点位置时，反向计算需要的初速度。
+     * 该方法使用固定时间窗（100 秒）进行估算。
+     *
+     * @param endX 目标终点位置（px）
+     */
+    setVelocityByEnd(endX: number): void;
+    /**
+     * 计算 `time` 秒后的位置（px）。
+     *
+     * 如果未传入 `time`，则根据当前时间和 `startTime` 计算经过时间。
+     *
+     * @param time 经过时间（s）
+     * @returns 位置值（px）
+     */
+    position(time?: number): number;
+    /**
+     * 计算 `time` 秒后的速度（px/s）。
+     *
+     * 如果未传入 `time`，则使用当前时间与 `startTime` 的差值。
+     *
+     * @param time 经过时间（s）
+     * @returns 速度值（px/s）
+     */
+    velocity(time?: number): number;
+    /**
+     * 解析时间并计算衰减因子 `damping^time`。
+     */
+    private resolveDecay;
+    /**
+     * 判断惯性滚动是否已基本停止。
+     *
+     * @returns 当当前速度绝对值小于 3 px/s 时返回 true
+     */
+    done(): boolean;
+    /**
+     * 重新配置阻尼因子，并保持当前位置与当前速度不变。
+     *
+     * @param newDamping 新的阻尼因子
+     */
+    reconfigure(newDamping: number): void;
+    /**
+     * 返回可用于调试或 UI 控制的配置对象。
+     */
+    configuration(): {
+        label: string;
+        read: () => number;
+        write: (value: number) => void;
+        min: number;
+        max: number;
+        step: number;
+    }[];
+}

package/utils/scroller/Friction.js

@@ -0,0 +1,116 @@
+//#region packages/sard/utils/scroller/Friction.ts
+/**
+* 惯性衰减模拟器。用于计算带有指数衰减阻尼的滚动位置和速度。
+*
+* 该模型假定速度随时间按 `damping^t` 衰减，位置则是该速度衰减曲线的积分。
+*
+* 所有 API 单位：位置 px，速度 px/s，时间 s。
+*/
+var Friction = class {
+	/** 阻尼因子，通常小于 1。越接近 1，衰减越慢。 */
+	damping;
+	/** 运动起始位置（px）。 */
+	x;
+	/** 运动起始速度（px/s）。 */
+	v;
+	/** 记录 `set()` 调用时的时间戳（毫秒）。 */
+	startTime;
+	/**
+	* @param damping 阻尼因子，用于控制速度指数衰减的底数。
+	*/
+	constructor(damping) {
+		this.damping = damping;
+		this.x = 0;
+		this.v = 0;
+		this.startTime = 0;
+	}
+	/**
+	* 初始化当前位置和速度，并重置时间基准。
+	*
+	* @param x 初始位置（px）
+	* @param v 初始速度（px/s）
+	*/
+	set(x, v) {
+		this.x = x;
+		this.v = v;
+		this.startTime = Date.now();
+	}
+	/**
+	* 在知道目标终点位置时，反向计算需要的初速度。
+	* 该方法使用固定时间窗（100 秒）进行估算。
+	*
+	* @param endX 目标终点位置（px）
+	*/
+	setVelocityByEnd(endX) {
+		this.v = (endX - this.x) * Math.log(this.damping) / (Math.pow(this.damping, 100) - 1);
+	}
+	/**
+	* 计算 `time` 秒后的位置（px）。
+	*
+	* 如果未传入 `time`，则根据当前时间和 `startTime` 计算经过时间。
+	*
+	* @param time 经过时间（s）
+	* @returns 位置值（px）
+	*/
+	position(time) {
+		const decay = this.resolveDecay(time);
+		const logD = Math.log(this.damping);
+		return this.x + this.v * decay / logD - this.v / logD;
+	}
+	/**
+	* 计算 `time` 秒后的速度（px/s）。
+	*
+	* 如果未传入 `time`，则使用当前时间与 `startTime` 的差值。
+	*
+	* @param time 经过时间（s）
+	* @returns 速度值（px/s）
+	*/
+	velocity(time) {
+		return this.v * this.resolveDecay(time);
+	}
+	/**
+	* 解析时间并计算衰减因子 `damping^time`。
+	*/
+	resolveDecay(time) {
+		if (time === void 0) time = (Date.now() - this.startTime) / 1e3;
+		return Math.pow(this.damping, time);
+	}
+	/**
+	* 判断惯性滚动是否已基本停止。
+	*
+	* @returns 当当前速度绝对值小于 3 px/s 时返回 true
+	*/
+	done() {
+		return Math.abs(this.velocity()) < 3;
+	}
+	/**
+	* 重新配置阻尼因子，并保持当前位置与当前速度不变。
+	*
+	* @param newDamping 新的阻尼因子
+	*/
+	reconfigure(newDamping) {
+		const curX = this.position();
+		const curV = this.velocity();
+		this.damping = newDamping;
+		this.set(curX, curV);
+	}
+	/**
+	* 返回可用于调试或 UI 控制的配置对象。
+	*/
+	configuration() {
+		return [{
+			label: "Friction",
+			read: () => {
+				return this.damping;
+			},
+			write: (value) => {
+				this.reconfigure(value);
+			},
+			min: .001,
+			max: .1,
+			step: .001
+		}];
+	}
+};
+//#endregion
+export { Friction };

package/utils/scroller/Scroll.d.ts

@@ -0,0 +1,52 @@
+import { Friction } from './Friction';
+import { Spring } from './Spring';
+/**
+ * 组合的滚动模型，支持惯性衰减和边界弹簧回弹。
+ */
+export declare class Scroll {
+    /** 滚动最大有效范围，用于越界判断 */
+    extent: number;
+    /** 惯性摩擦模型 */
+    friction: Friction;
+    /** 边界回弹弹簧模型 */
+    spring: Spring;
+    /** 记录滚动开始时间戳 */
+    startTime: number;
+    /** 当前是否正在弹簧回弹 */
+    private springing;
+    /** 弹簧回弹时的位置偏移量 */
+    private springOffset;
+    /** 缓存上次速度计算对应的时间 */
+    private lastTime?;
+    /** 缓存上次速度结果 */
+    private lastDx?;
+    constructor(extent: number, friction?: Friction, spring?: Spring);
+    /**
+     * 直接进入 snap 状态，将当前滚动位置使用弹簧动画对齐到目标位置。
+     */
+    snap(e: number, t: number): void;
+    /**
+     * 设置滚动初始位置和速度，并根据是否越界切换到弹簧回弹模式。
+     */
+    set(e: number, t: number): void;
+    /**
+     * 计算当前时间点的位置，如果超出边界则切换到弹簧回弹模式。
+     */
+    position(e: number): number;
+    /**
+     * 计算当前时间点的速度。
+     */
+    velocity(e: number): number;
+    /**
+     * 判断滚动是否结束。
+     */
+    done(): boolean;
+    /**
+     * 将 friction 的初速度按目标终点反推。
+     */
+    setVelocityByEnd(e: number): void;
+    /**
+     * 返回 friction 与 spring 的调试配置项。
+     */
+    configuration(): any[];
+}

package/utils/scroller/Scroll.js

@@ -0,0 +1,110 @@
+import { Friction } from "./Friction.js";
+import { Spring } from "./Spring.js";
+//#region packages/sard/utils/scroller/Scroll.ts
+/**
+* 组合的滚动模型，支持惯性衰减和边界弹簧回弹。
+*/
+var Scroll = class {
+	/** 滚动最大有效范围，用于越界判断 */
+	extent;
+	/** 惯性摩擦模型 */
+	friction;
+	/** 边界回弹弹簧模型 */
+	spring;
+	/** 记录滚动开始时间戳 */
+	startTime;
+	/** 当前是否正在弹簧回弹 */
+	springing;
+	/** 弹簧回弹时的位置偏移量 */
+	springOffset;
+	/** 缓存上次速度计算对应的时间 */
+	lastTime;
+	/** 缓存上次速度结果 */
+	lastDx;
+	constructor(extent, friction, spring) {
+		this.extent = extent;
+		this.friction = friction || new Friction(.01);
+		this.spring = spring || new Spring(1, 90, 20);
+		this.startTime = 0;
+		this.springing = false;
+		this.springOffset = 0;
+	}
+	/**
+	* 直接进入 snap 状态，将当前滚动位置使用弹簧动画对齐到目标位置。
+	*/
+	snap(e, t) {
+		this.springOffset = 0;
+		this.springing = true;
+		this.spring.snap(e);
+		this.spring.setEnd(t);
+	}
+	/**
+	* 设置滚动初始位置和速度，并根据是否越界切换到弹簧回弹模式。
+	*/
+	set(e, t) {
+		this.friction.set(e, t);
+		if (e > 0 && t >= 0) {
+			this.springOffset = 0;
+			this.springing = true;
+			this.spring.snap(e);
+			this.spring.setEnd(0);
+		} else if (e < -this.extent && t <= 0) {
+			this.springOffset = 0;
+			this.springing = true;
+			this.spring.snap(e);
+			this.spring.setEnd(-this.extent);
+		} else this.springing = false;
+		this.startTime = (/* @__PURE__ */ new Date()).getTime();
+	}
+	/**
+	* 计算当前时间点的位置，如果超出边界则切换到弹簧回弹模式。
+	*/
+	position(e) {
+		if (!this.startTime) return 0;
+		if (!e) e = ((/* @__PURE__ */ new Date()).getTime() - this.startTime) / 1e3;
+		if (this.springing) return this.spring.position() + this.springOffset;
+		let t = this.friction.position(e);
+		const n = this.velocity(e);
+		if (t > 0 && n >= 0 || t < -this.extent && n <= 0) {
+			this.springing = true;
+			this.spring.setEnd(0, n);
+			if (t < -this.extent) this.springOffset = -this.extent;
+			else this.springOffset = 0;
+			t = this.spring.position() + this.springOffset;
+		}
+		return t;
+	}
+	/**
+	* 计算当前时间点的速度。
+	*/
+	velocity(e) {
+		let t;
+		if (this.lastTime === e) t = this.lastDx;
+		else t = this.springing ? this.spring.velocity(e) : this.friction.velocity(e);
+		this.lastTime = e;
+		this.lastDx = t;
+		return t;
+	}
+	/**
+	* 判断滚动是否结束。
+	*/
+	done() {
+		return this.springing ? this.spring.done() : this.friction.done();
+	}
+	/**
+	* 将 friction 的初速度按目标终点反推。
+	*/
+	setVelocityByEnd(e) {
+		this.friction.setVelocityByEnd(e);
+	}
+	/**
+	* 返回 friction 与 spring 的调试配置项。
+	*/
+	configuration() {
+		const e = this.friction.configuration();
+		e.push(...this.spring.configuration());
+		return e;
+	}
+};
+//#endregion
+export { Scroll };

package/utils/scroller/Spring.d.ts

@@ -0,0 +1,66 @@
+interface Solution {
+    _t?: number;
+    _powER1T?: number;
+    _powER2T?: number;
+    position: (e: number) => number;
+    velocity: (e: number) => number;
+}
+/**
+ * 弹簧模型，用于产生回弹动画和边界恢复效果。
+ */
+export declare class Spring {
+    /** 质量，用于计算阻尼系统 */
+    private mass;
+    /** 弹簧常数 */
+    private stiffness;
+    /** 阻尼系数 */
+    private damping;
+    /** 当前解析解对象 */
+    private solution;
+    /** 当前弹簧目标位置 */
+    private endPosition;
+    /** 记录弹簧运动开始时间戳 */
+    private startTime;
+    constructor(mass: number, stiffness: number, damping: number);
+    /**
+     * 求解弹簧位移/速度的解析解。
+     */
+    solve(displacement: number, velocity: number): Solution;
+    /**
+     * 返回当前时间点的弹簧位置。
+     */
+    position(e?: number): number;
+    /**
+     * 返回当前时间点的弹簧速度。
+     */
+    velocity(e?: number): number;
+    /**
+     * 更新弹簧目标位置和初始状态。
+     */
+    setEnd(end: number, initVel?: number, time?: number): void;
+    /**
+     * 直接跳转到指定终点并停止当前弹簧运动。
+     */
+    snap(end: number): void;
+    /**
+     * 判断弹簧是否已接近目标位置且速度很小。
+     */
+    done(e?: number): boolean;
+    /**
+     * 重新配置弹簧参数，并保持当前运动状态连续。
+     */
+    reconfigure(mass: number, stiffness: number, damping: number): void;
+    getStiffness(): number;
+    getDamping(): number;
+    /**
+     * 返回弹簧参数的调试配置项。
+     */
+    configuration(): {
+        label: string;
+        read: () => number;
+        write: (value: number) => void;
+        min: number;
+        max: number;
+    }[];
+}
+export {};

package/utils/scroller/Spring.js

@@ -0,0 +1,204 @@
+//#region packages/sard/utils/scroller/Spring.ts
+function near(e, t, n) {
+	return e > t - n && e < t + n;
+}
+function nearZero(e, t) {
+	return near(e, 0, t);
+}
+/**
+* 弹簧模型，用于产生回弹动画和边界恢复效果。
+*/
+var Spring = class {
+	/** 质量，用于计算阻尼系统 */
+	mass;
+	/** 弹簧常数 */
+	stiffness;
+	/** 阻尼系数 */
+	damping;
+	/** 当前解析解对象 */
+	solution;
+	/** 当前弹簧目标位置 */
+	endPosition;
+	/** 记录弹簧运动开始时间戳 */
+	startTime;
+	constructor(mass, stiffness, damping) {
+		this.mass = mass;
+		this.stiffness = stiffness;
+		this.damping = damping;
+		this.solution = null;
+		this.endPosition = 0;
+		this.startTime = 0;
+	}
+	/**
+	* 求解弹簧位移/速度的解析解。
+	*/
+	solve(displacement, velocity) {
+		const c = this.damping;
+		const m = this.mass;
+		const k = this.stiffness;
+		const discriminant = c * c - 4 * m * k;
+		if (discriminant === 0) {
+			const root = -c / (2 * m);
+			const amp1 = displacement;
+			const amp2 = velocity / (root * displacement);
+			return {
+				position: function(e) {
+					return (amp1 + amp2 * e) * Math.pow(Math.E, root * e);
+				},
+				velocity: function(e) {
+					const t = Math.pow(Math.E, root * e);
+					return root * (amp1 + amp2 * e) * t + amp2 * t;
+				}
+			};
+		}
+		if (discriminant > 0) {
+			const root1 = (-c - Math.sqrt(discriminant)) / (2 * m);
+			const root2 = (-c + Math.sqrt(discriminant)) / (2 * m);
+			const amp2 = (velocity - root1 * displacement) / (root2 - root1);
+			const amp1 = displacement - amp2;
+			return {
+				position: function(e) {
+					let t;
+					let n;
+					if (e === this._t) {
+						t = this._powER1T;
+						n = this._powER2T;
+					}
+					this._t = e;
+					if (!t) t = this._powER1T = Math.pow(Math.E, root1 * e);
+					if (!n) n = this._powER2T = Math.pow(Math.E, root2 * e);
+					return amp1 * t + amp2 * n;
+				},
+				velocity: function(e) {
+					let t;
+					let n;
+					if (e === this._t) {
+						t = this._powER1T;
+						n = this._powER2T;
+					}
+					this._t = e;
+					if (!t) t = this._powER1T = Math.pow(Math.E, root1 * e);
+					if (!n) n = this._powER2T = Math.pow(Math.E, root2 * e);
+					return amp1 * root1 * t + amp2 * root2 * n;
+				}
+			};
+		}
+		const dampedFreq = Math.sqrt(4 * m * k - c * c) / (2 * m);
+		const decayRate = -c / 2 * m;
+		const amp1 = displacement;
+		const amp2 = (velocity - decayRate * displacement) / dampedFreq;
+		return {
+			position: function(e) {
+				return Math.pow(Math.E, decayRate * e) * (amp1 * Math.cos(dampedFreq * e) + amp2 * Math.sin(dampedFreq * e));
+			},
+			velocity: function(e) {
+				const t = Math.pow(Math.E, decayRate * e);
+				const n = Math.cos(dampedFreq * e);
+				const i = Math.sin(dampedFreq * e);
+				return t * (amp2 * dampedFreq * n - amp1 * dampedFreq * i) + decayRate * t * (amp2 * i + amp1 * n);
+			}
+		};
+	}
+	/**
+	* 返回当前时间点的弹簧位置。
+	*/
+	position(e) {
+		if (e === void 0) e = ((/* @__PURE__ */ new Date()).getTime() - this.startTime) / 1e3;
+		return this.solution ? this.endPosition + this.solution.position(e) : 0;
+	}
+	/**
+	* 返回当前时间点的弹簧速度。
+	*/
+	velocity(e) {
+		if (e === void 0) e = ((/* @__PURE__ */ new Date()).getTime() - this.startTime) / 1e3;
+		return this.solution ? this.solution.velocity(e) : 0;
+	}
+	/**
+	* 更新弹簧目标位置和初始状态。
+	*/
+	setEnd(end, initVel, time) {
+		if (!time) time = (/* @__PURE__ */ new Date()).getTime();
+		if (end !== this.endPosition || !nearZero(initVel, .4)) {
+			initVel = initVel || 0;
+			let curPos = this.endPosition;
+			if (this.solution) {
+				if (nearZero(initVel, .4)) initVel = this.solution.velocity((time - this.startTime) / 1e3);
+				curPos = this.solution.position((time - this.startTime) / 1e3);
+				if (nearZero(initVel, .4)) initVel = 0;
+				if (nearZero(curPos, .4)) curPos = 0;
+				curPos += this.endPosition;
+			}
+			if (!(this.solution && nearZero(curPos - end, .4) && nearZero(initVel, .4))) {
+				this.endPosition = end;
+				this.solution = this.solve(curPos - this.endPosition, initVel);
+				this.startTime = time;
+			}
+		}
+	}
+	/**
+	* 直接跳转到指定终点并停止当前弹簧运动。
+	*/
+	snap(end) {
+		this.startTime = (/* @__PURE__ */ new Date()).getTime();
+		this.endPosition = end;
+		this.solution = {
+			position: function() {
+				return 0;
+			},
+			velocity: function() {
+				return 0;
+			}
+		};
+	}
+	/**
+	* 判断弹簧是否已接近目标位置且速度很小。
+	*/
+	done(e) {
+		if (!e) e = (/* @__PURE__ */ new Date()).getTime();
+		return near(this.position(), this.endPosition, .4) && nearZero(this.velocity(), .4);
+	}
+	/**
+	* 重新配置弹簧参数，并保持当前运动状态连续。
+	*/
+	reconfigure(mass, stiffness, damping) {
+		this.mass = mass;
+		this.stiffness = stiffness;
+		this.damping = damping;
+		if (!this.done()) {
+			this.solution = this.solve(this.position() - this.endPosition, this.velocity());
+			this.startTime = (/* @__PURE__ */ new Date()).getTime();
+		}
+	}
+	getStiffness() {
+		return this.stiffness;
+	}
+	getDamping() {
+		return this.damping;
+	}
+	/**
+	* 返回弹簧参数的调试配置项。
+	*/
+	configuration() {
+		function setStiffness(spring, value) {
+			spring.reconfigure(1, value, spring.getDamping());
+		}
+		function setDamping(spring, value) {
+			spring.reconfigure(1, spring.getStiffness(), value);
+		}
+		return [{
+			label: "Spring Constant",
+			read: this.getStiffness.bind(this),
+			write: setStiffness.bind(this, this),
+			min: 100,
+			max: 1e3
+		}, {
+			label: "Damping",
+			read: this.getDamping.bind(this),
+			write: setDamping.bind(this, this),
+			min: 1,
+			max: 500
+		}];
+	}
+};
+//#endregion
+export { Spring };

package/utils/scroller/index.d.ts

@@ -0,0 +1,3 @@
+export { Friction } from './Friction';
+export { Spring } from './Spring';
+export { useScroller, type ScrollerOptions } from './useScroller';

package/utils/scroller/index.js

@@ -0,0 +1,4 @@
+import { Friction } from "./Friction.js";
+import { Spring } from "./Spring.js";
+import { useScroller } from "./useScroller.js";
+export { Friction, Spring, useScroller };

package/utils/scroller/useEasingAnimation.d.ts

@@ -0,0 +1,5 @@
+import { type Ref } from 'vue';
+export declare function useEasingAnimation(target: Ref<number>): {
+    play: (value: number, duration: number) => Promise<void>;
+    pause: () => void;
+};

package/utils/scroller/useEasingAnimation.js

@@ -0,0 +1,32 @@
+import { withResolvers } from "../polyfill.js";
+import { onUnmounted } from "vue";
+import { createAnimation } from "lwa";
+//#region packages/sard/utils/scroller/useEasingAnimation.ts
+function useEasingAnimation(target) {
+	let tl;
+	let promiseWithResolvers;
+	const play = (value, duration) => {
+		tl?.pause();
+		promiseWithResolvers = withResolvers();
+		tl = createAnimation(target, { value }, {
+			duration,
+			easing: "easeOutCubic",
+			complete() {
+				promiseWithResolvers.resolve();
+			}
+		});
+		return promiseWithResolvers.promise;
+	};
+	const pause = () => {
+		tl?.pause();
+	};
+	onUnmounted(() => {
+		pause();
+	});
+	return {
+		play,
+		pause
+	};
+}
+//#endregion
+export { useEasingAnimation };

package/utils/scroller/useScrollAnimation.d.ts

@@ -0,0 +1,12 @@
+import type { Scroll } from './Scroll';
+/**
+ * 创建一个基于 requestAnimationFrame 的动画循环。
+ *
+ * @param scroll 滚动模型
+ * @param onScroll 每帧更新时回调
+ * @param onEnd 动画结束时回调
+ */
+export declare function useScrollAnimation(scroll: Scroll): {
+    play: (_onScroll: () => void, _onEnd: (scroll: Scroll) => void) => void;
+    pause: () => void;
+};