@qingwu-ui/scroll-fab 0.9.0-beta.1 → 0.9.0-beta.3

package/dist/index.mjs

@@ -73,19 +73,28 @@ S16("<path d=\"m9 18 6-6-6-6\"/>");
 //#endregion
 //#region src/scroll-fab.ts
 /** 青梧UI ScrollFab 悬浮滚动栏：默认“滚动到底部”，桌面悬停/触屏按住绕满描边一圈翻转为“返回顶部”，点击（轻点）直接执行当前模式动作 */
+const SVG_NS = "http://www.w3.org/2000/svg";
 const RADIUS = 21;
+const FALLBACK_PATH_LEN = 100;
 const DEFAULT_LABEL_BOTTOM = "滚动到底部（悬停或按住绕圈可切换为返回顶部）";
 const DEFAULT_LABEL_TOP = "返回顶部（悬停或按住绕圈可切换为滚动到底部）";
+const STATIC_LABEL_BOTTOM = "滚动到底部";
+const STATIC_LABEL_TOP = "返回顶部";
 function easeInOutCubic(p) {
 	return p < .5 ? 4 * p * p * p : 1 - (-2 * p + 2) ** 3 / 2;
 }
+function isLenisInstance(v) {
+	return typeof v === "object" && v !== null && typeof v.scrollTo === "function";
+}
 var ScrollFab = class {
 	el;
 	ring;
 	track;
+	fillPath = null;
 	icon;
 	len;
 	targetEl;
+	shape;
 	ringMs;
 	decayMs;
 	cancelPx;
@@ -93,7 +102,18 @@ var ScrollFab = class {
 	labelBottom;
 	labelTop;
 	onModeChange;
-	mode = "to-bottom";
+	onLenisReady;
+	onScroll;
+	modes;
+	single;
+	threshold;
+	/** 外部注入：宿主实例，组件永不销毁 */
+	externalLenis = null;
+	/** 自建配置：null = 不走 lenis；true 形态也归一成对象 */
+	ownLenisConfig = null;
+	ownLenis = null;
+	ownLenisPromise = null;
+	mode;
 	progress = 0;
 	hovering = false;
 	pressing = false;
@@ -104,41 +124,79 @@ var ScrollFab = class {
 	ringRaf = null;
 	lastTs = null;
 	scrollRaf = null;
+	lenisLoopRaf = null;
+	lenisScrolling = false;
+	lenisDest = null;
 	flashTimer = null;
 	tapResetTimer = null;
 	touchTap = false;
 	ro = null;
+	actionSeq = 0;
+	destroyed = false;
+	emitRaf = null;
+	lastPct = -1;
 	constructor(options = {}) {
 		this.targetEl = options.target ?? null;
+		this.shape = options.shape ?? null;
 		this.ringMs = Math.max(100, Math.min(5e3, options.ringDuration ?? 800));
 		this.decayMs = Math.max(100, options.decayDuration ?? 300);
 		this.cancelPx = Math.max(4, options.cancelThreshold ?? 10);
 		this.animate = options.animate ?? true;
-		this.labelBottom = options.ariaLabelToBottom ?? DEFAULT_LABEL_BOTTOM;
-		this.labelTop = options.ariaLabelToTop ?? DEFAULT_LABEL_TOP;
+		this.threshold = Math.max(0, options.showThreshold ?? 0);
 		this.onModeChange = options.onModeChange;
+		this.onLenisReady = options.onLenisReady;
+		this.onScroll = options.onScroll;
+		this.modes = this.normalizeModes(options.modes);
+		this.single = this.modes.length === 1;
+		this.mode = this.modes[0];
+		this.labelBottom = options.ariaLabelToBottom ?? (this.single ? STATIC_LABEL_BOTTOM : DEFAULT_LABEL_BOTTOM);
+		this.labelTop = options.ariaLabelToTop ?? (this.single ? STATIC_LABEL_TOP : DEFAULT_LABEL_TOP);
+		if (isLenisInstance(options.lenis)) this.externalLenis = options.lenis;
+		else if (options.lenis != null && options.lenis !== false) {
+			const cfg = options.lenis === true ? {} : options.lenis;
+			this.ownLenisConfig = {
+				smoothWheel: false,
+				...cfg
+			};
+		}
 		this.el = document.createElement("button");
 		this.el.type = "button";
 		this.el.className = `qsf-root${options.className ? ` ${options.className}` : ""}`;
 		this.el.dataset.mode = this.mode;
-		this.el.setAttribute("aria-label", this.labelBottom);
+		if (this.shape) this.el.dataset.shape = "on";
+		this.el.setAttribute("aria-label", this.mode === "to-bottom" ? this.labelBottom : this.labelTop);
 		this.el.style.setProperty("--qsf-size", `${Math.max(44, options.size ?? 48)}px`);
 		if (options.zIndex != null) this.el.style.setProperty("--qsf-z", String(options.zIndex));
 		if (options.position?.right != null) this.el.style.setProperty("--qsf-right", `${options.position.right}px`);
 		if (options.position?.bottom != null) this.el.style.setProperty("--qsf-bottom", `${options.position.bottom}px`);
 		if (options.position?.left != null) this.el.style.setProperty("--qsf-left", `${options.position.left}px`);
 		if (options.position?.top != null) this.el.style.setProperty("--qsf-top", `${options.position.top}px`);
-		const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+		const svg = document.createElementNS(SVG_NS, "svg");
 		svg.setAttribute("class", "qsf-svg");
-		svg.setAttribute("viewBox", "0 0 48 48");
+		svg.setAttribute("viewBox", this.shape?.viewBox ?? "0 0 48 48");
 		svg.setAttribute("aria-hidden", "true");
-		this.track = this.makeCircle("qsf-track");
-		this.ring = this.makeCircle("qsf-bar");
-		svg.append(this.track, this.ring);
-		let len = 2 * Math.PI * RADIUS;
+		if (this.shape) {
+			this.fillPath = document.createElementNS(SVG_NS, "path");
+			this.fillPath.setAttribute("class", "qsf-shape-fill");
+			this.fillPath.setAttribute("d", this.shape.fill);
+			this.track = this.makePath("qsf-track", this.shape.outline);
+			this.ring = this.makePath("qsf-bar", this.shape.outline);
+			if (this.shape.outlineTransform) {
+				this.track.setAttribute("transform", this.shape.outlineTransform);
+				this.ring.setAttribute("transform", this.shape.outlineTransform);
+			}
+			svg.append(this.fillPath, this.track, this.ring);
+		} else {
+			this.track = this.makeCircle("qsf-track");
+			this.ring = this.makeCircle("qsf-bar");
+			svg.append(this.track, this.ring);
+		}
+		let len;
+		if (this.shape) len = FALLBACK_PATH_LEN;
+		else len = 2 * Math.PI * RADIUS;
 		try {
 			const measured = this.ring.getTotalLength();
-			if (Number.isFinite(measured)) len = measured;
+			if (Number.isFinite(measured) && measured > 0) len = measured;
 		} catch {}
 		this.len = len;
 		this.ring.style.strokeDasharray = String(this.len);
@@ -151,12 +209,14 @@ var ScrollFab = class {
 		else this.icon.innerHTML = ICON_CHEVRON_DOWN;
 		this.el.append(svg, this.icon);
 		document.body.append(this.el);
-		this.el.addEventListener("pointerenter", this.onEnter);
-		this.el.addEventListener("pointerleave", this.onLeave);
-		this.el.addEventListener("pointerdown", this.onDown);
-		this.el.addEventListener("pointermove", this.onMove);
-		this.el.addEventListener("pointerup", this.onUp);
-		this.el.addEventListener("pointercancel", this.onCancel);
+		if (!this.single) {
+			this.el.addEventListener("pointerenter", this.onEnter);
+			this.el.addEventListener("pointerleave", this.onLeave);
+			this.el.addEventListener("pointerdown", this.onDown);
+			this.el.addEventListener("pointermove", this.onMove);
+			this.el.addEventListener("pointerup", this.onUp);
+			this.el.addEventListener("pointercancel", this.onCancel);
+		}
 		this.el.addEventListener("keydown", this.onKey);
 		this.el.addEventListener("click", this.onClick);
 		window.addEventListener("resize", this.onRecheck);
@@ -166,48 +226,73 @@ var ScrollFab = class {
 			this.ro.observe(this.targetEl ?? document.documentElement);
 		}
 		this.syncVisible();
+		this.emitScroll();
 	}
 	/** 当前模式 */
 	get currentMode() {
 		return this.mode;
 	}
-	/** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估） */
+	/** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估），并强制补发一次进度 */
 	refresh() {
-		this.onRecheck();
+		this.syncVisible();
+		this.lastPct = -1;
+		this.emitScroll();
 	}
 	scrollToBottom() {
 		this.animateScroll("bottom");
 	}
 	scrollToTop() {
-		this.scrollTo(0);
+		this.animateScroll("top");
 	}
 	destroy() {
-		this.el.removeEventListener("pointerenter", this.onEnter);
-		this.el.removeEventListener("pointerleave", this.onLeave);
-		this.el.removeEventListener("pointerdown", this.onDown);
-		this.el.removeEventListener("pointermove", this.onMove);
-		this.el.removeEventListener("pointerup", this.onUp);
-		this.el.removeEventListener("pointercancel", this.onCancel);
+		this.destroyed = true;
+		if (!this.single) {
+			this.el.removeEventListener("pointerenter", this.onEnter);
+			this.el.removeEventListener("pointerleave", this.onLeave);
+			this.el.removeEventListener("pointerdown", this.onDown);
+			this.el.removeEventListener("pointermove", this.onMove);
+			this.el.removeEventListener("pointerup", this.onUp);
+			this.el.removeEventListener("pointercancel", this.onCancel);
+		}
 		this.el.removeEventListener("keydown", this.onKey);
 		this.el.removeEventListener("click", this.onClick);
 		window.removeEventListener("resize", this.onRecheck);
 		(this.targetEl ?? window).removeEventListener("scroll", this.onRecheck);
 		this.ro?.disconnect();
 		this.cancelScroll();
+		this.stopLenisLoop();
+		this.ownLenis?.destroy?.();
+		this.ownLenis = null;
 		if (this.ringRaf != null) cancelAnimationFrame(this.ringRaf);
 		this.ringRaf = null;
+		if (this.emitRaf != null) cancelAnimationFrame(this.emitRaf);
+		this.emitRaf = null;
 		if (this.flashTimer != null) clearTimeout(this.flashTimer);
 		if (this.tapResetTimer != null) clearTimeout(this.tapResetTimer);
 		this.el.remove();
 	}
+	/** 规范化 modes：缺省双模式；去重、过滤非法值；结果为空直接抛错 */
+	normalizeModes(input) {
+		if (!input) return ["to-bottom", "to-top"];
+		const out = [];
+		for (const m of input) if ((m === "to-bottom" || m === "to-top") && !out.includes(m)) out.push(m);
+		if (out.length === 0) throw new TypeError("ScrollFab: modes 至少需要一个有效模式（'to-bottom' | 'to-top'）");
+		return out;
+	}
 	makeCircle(cls) {
-		const c = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+		const c = document.createElementNS(SVG_NS, "circle");
 		c.setAttribute("class", cls);
 		c.setAttribute("cx", "24");
 		c.setAttribute("cy", "24");
 		c.setAttribute("r", String(RADIUS));
 		return c;
 	}
+	makePath(cls, d) {
+		const p = document.createElementNS(SVG_NS, "path");
+		p.setAttribute("class", cls);
+		p.setAttribute("d", d);
+		return p;
+	}
 	onEnter = (e) => {
 		if (e.pointerType !== "mouse") return;
 		this.hovering = true;
@@ -267,9 +352,12 @@ var ScrollFab = class {
 		this.doAction();
 	};
 	onKey = (e) => {
-		if (e.repeat || e.key !== "Enter" && e.key !== " ") return;
+		if (e.repeat || e.key !== "ArrowUp" && e.key !== "ArrowDown") return;
+		if (this.single) return;
+		const want = e.key === "ArrowUp" ? "to-top" : "to-bottom";
+		if (want === this.mode) return;
 		e.preventDefault();
-		this.setMode(this.mode === "to-bottom" ? "to-top" : "to-bottom");
+		this.setMode(want);
 	};
 	holding() {
 		return this.hovering || this.pressing;
@@ -321,12 +409,110 @@ var ScrollFab = class {
 		this.animateScroll(this.mode === "to-bottom" ? "bottom" : "top");
 	}
 	animateScroll(dest) {
+		++this.actionSeq;
 		this.cancelScroll();
 		if (!this.animate || this.reducedMotion()) {
 			this.setScrollPos(this.targetPos(dest));
 			return;
 		}
-		this.attachInterrupt();
+		if (this.externalLenis) {
+			this.scrollWithLenis(this.externalLenis, dest, false);
+			return;
+		}
+		if (this.ownLenisConfig) {
+			const seq = ++this.actionSeq;
+			this.resolveOwnLenis().then((lenis) => {
+				if (this.destroyed || seq !== this.actionSeq) return;
+				if (lenis) this.scrollWithLenis(lenis, dest, true);
+				else this.animateRaf(dest);
+			});
+			return;
+		}
+		this.animateRaf(dest);
+	}
+	/** 首次点击时动态 import lenis 并自建实例；未安装（或加载失败）→ null 永久回退 rAF */
+	resolveOwnLenis() {
+		if (this.ownLenis) return Promise.resolve(this.ownLenis);
+		if (this.ownLenisPromise) return this.ownLenisPromise;
+		this.ownLenisPromise = import("lenis").then((mod) => {
+			const LenisCtor = mod.default ?? mod;
+			const cfg = { ...this.ownLenisConfig };
+			if (this.targetEl) cfg.wrapper = this.targetEl;
+			this.ownLenis = new LenisCtor(cfg);
+			this.onLenisReady?.(this.ownLenis);
+			return this.ownLenis;
+		}).catch(() => {
+			this.ownLenisConfig = null;
+			this.ownLenisPromise = null;
+			return null;
+		});
+		return this.ownLenisPromise;
+	}
+	/**
+	* 用 Lenis 执行程序滚动。
+	* 自建实例（own）：组件自跑 raf loop（Lenis 需外部驱动 raf），保留 wheel/touch/keydown 打断与到底追击；
+	* 外部实例：宿主自带 raf loop 与手势处理，组件只发 scrollTo，不追击不打断。
+	*/
+	scrollWithLenis(lenis, dest, own) {
+		const immediate = !this.animate || this.reducedMotion();
+		const target = this.targetPos(dest);
+		this.lenisDest = dest;
+		if (own) {
+			lenis.start?.();
+			lenis.scrollTo(target, {
+				immediate,
+				onComplete: () => this.endLenisScroll()
+			});
+			if (!immediate) {
+				this.lenisScrolling = true;
+				this.attachInterrupt();
+				this.startLenisLoop(lenis, dest);
+			} else this.endLenisScroll();
+		} else {
+			lenis.scrollTo(target, { immediate });
+			this.lenisDest = null;
+		}
+	}
+	/** 自建实例的 raf 驱动 + 懒加载到底追击（对齐内置 rAF 语义） */
+	startLenisLoop(lenis, dest) {
+		let lastEnd = this.targetPos(dest);
+		const loop = (time) => {
+			if (!this.lenisScrolling) return;
+			if (dest === "bottom") {
+				const live = this.targetPos("bottom");
+				if (Math.abs(live - lastEnd) > 2) {
+					lastEnd = live;
+					lenis.scrollTo(live, {
+						force: true,
+						onComplete: () => this.endLenisScroll()
+					});
+				}
+			}
+			lenis.raf?.(time);
+			this.lenisLoopRaf = requestAnimationFrame(loop);
+		};
+		this.lenisLoopRaf = requestAnimationFrame(loop);
+	}
+	stopLenisLoop() {
+		if (this.lenisLoopRaf != null) {
+			cancelAnimationFrame(this.lenisLoopRaf);
+			this.lenisLoopRaf = null;
+		}
+	}
+	/** 打断自建 Lenis 程序滚动：stop 冻结动画（下次发起前 start 复位） */
+	onLenisInterrupt = () => {
+		if (!this.lenisScrolling) return;
+		this.ownLenis?.stop?.();
+		this.endLenisScroll();
+	};
+	endLenisScroll() {
+		this.lenisScrolling = false;
+		this.lenisDest = null;
+		this.stopLenisLoop();
+		this.detachInterrupt();
+	}
+	animateRaf(dest) {
+		this.attachRafInterrupt();
 		let init = false;
 		let start = 0;
 		let end = 0;
@@ -353,7 +539,7 @@ var ScrollFab = class {
 			if (p < 1) this.scrollRaf = requestAnimationFrame(step);
 			else {
 				this.scrollRaf = null;
-				this.detachInterrupt();
+				this.detachRafInterrupt();
 			}
 		};
 		this.scrollRaf = requestAnimationFrame(step);
@@ -367,15 +553,33 @@ var ScrollFab = class {
 	interruptSource() {
 		return this.targetEl ?? window;
 	}
+	/** 自建 Lenis 路线的打断监听 */
 	attachInterrupt() {
 		const src = this.interruptSource();
 		for (const ev of [
 			"wheel",
 			"touchstart",
 			"keydown"
-		]) src.addEventListener(ev, this.onInterrupt, { passive: true });
+		]) src.addEventListener(ev, this.onLenisInterrupt, { passive: true });
 	}
 	detachInterrupt() {
+		const src = this.interruptSource();
+		for (const ev of [
+			"wheel",
+			"touchstart",
+			"keydown"
+		]) src.removeEventListener(ev, this.onLenisInterrupt);
+	}
+	/** 内置 rAF 路线的打断监听 */
+	attachRafInterrupt() {
+		const src = this.interruptSource();
+		for (const ev of [
+			"wheel",
+			"touchstart",
+			"keydown"
+		]) src.addEventListener(ev, this.onInterrupt, { passive: true });
+	}
+	detachRafInterrupt() {
 		const src = this.interruptSource();
 		for (const ev of [
 			"wheel",
@@ -388,7 +592,16 @@ var ScrollFab = class {
 			cancelAnimationFrame(this.scrollRaf);
 			this.scrollRaf = null;
 		}
-		this.detachInterrupt();
+		if (this.lenisScrolling) this.endLenisScroll();
+		const src = this.interruptSource();
+		for (const ev of [
+			"wheel",
+			"touchstart",
+			"keydown"
+		]) {
+			src.removeEventListener(ev, this.onInterrupt);
+			src.removeEventListener(ev, this.onLenisInterrupt);
+		}
 	}
 	maxScroll() {
 		if (this.targetEl) return Math.max(0, this.targetEl.scrollHeight - this.targetEl.clientHeight);
@@ -405,14 +618,28 @@ var ScrollFab = class {
 		if (this.targetEl) this.targetEl.scrollTop = v;
 		else window.scrollTo(0, v);
 	}
-	scrollTo(v) {
-		this.animateScroll(v === 0 ? "top" : "bottom");
-	}
 	onRecheck = () => {
 		this.syncVisible();
+		this.scheduleScroll();
 	};
 	syncVisible() {
-		this.el.hidden = this.maxScroll() <= 1;
+		this.el.hidden = this.maxScroll() <= 1 || this.scrollPos() < this.threshold;
+	}
+	/** rAF 节流：一帧内多次重估只吐一次；按钮隐藏期间照常调度 */
+	scheduleScroll() {
+		if (this.emitRaf != null || this.destroyed) return;
+		this.emitRaf = requestAnimationFrame(() => {
+			this.emitRaf = null;
+			this.emitScroll();
+		});
+	}
+	emitScroll() {
+		if (this.destroyed) return;
+		const max = this.maxScroll();
+		const pct = max <= 0 ? 0 : Math.min(1, Math.max(0, this.scrollPos() / max));
+		if (pct === this.lastPct) return;
+		this.lastPct = pct;
+		this.onScroll?.(pct);
 	}
 };
 //#endregion