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

package/dist/index.cjs

@@ -0,0 +1,420 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region ../../icon/icons.ts
+const S = (d) => `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${d}</svg>`;
+const S16 = (d) => `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${d}</svg>`;
+const S18 = (d) => `<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${d}</svg>`;
+const S36 = (d) => `<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${d}</svg>`;
+S("<rect x=\"3\" y=\"4\" width=\"18\" height=\"18\" rx=\"2\"/><path d=\"M8 2v4M16 2v4M3 10h18\"/>");
+S("<rect x=\"3\" y=\"4\" width=\"18\" height=\"18\" rx=\"2\" ry=\"2\"/><line x1=\"16\" y1=\"2\" x2=\"16\" y2=\"6\"/><line x1=\"8\" y1=\"2\" x2=\"8\" y2=\"6\"/><line x1=\"3\" y1=\"10\" x2=\"21\" y2=\"10\"/><line x1=\"8\" y1=\"14\" x2=\"8.01\" y2=\"14\"/>");
+S("<circle cx=\"11\" cy=\"11\" r=\"8\"/><path d=\"m21 21-4.35-4.35\"/>");
+S("<path d=\"M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4\"/><polyline points=\"17 8 12 3 7 8\"/><line x1=\"12\" y1=\"3\" x2=\"12\" y2=\"15\"/>");
+S("<path d=\"M12 16V4\"/><path d=\"m6 9 6-5 6 5\"/><path d=\"M4 20h16\"/>");
+S("<path d=\"M3 7h18M3 12h18M3 17h18\"/>");
+S("<path d=\"M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9\"/><path d=\"M10.3 21a1.94 1.94 0 0 0 3.4 0\"/>");
+S("<line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\"/><line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\"/>");
+S("<polyline points=\"20 6 9 17 4 12\"/>");
+S("<line x1=\"12\" y1=\"5\" x2=\"12\" y2=\"19\"/><line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\"/>");
+S("<line x1=\"5\" y1=\"12\" x2=\"19\" y2=\"12\"/>");
+S("<path d=\"M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z\"/>");
+S("<path d=\"M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7\"/><path d=\"M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z\"/>");
+S("<path d=\"M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z\"/><polyline points=\"14 2 14 8 20 8\"/>");
+S("<path d=\"M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z\"/>");
+S("<circle cx=\"12\" cy=\"12\" r=\"10\"/><line x1=\"12\" y1=\"16\" x2=\"12\" y2=\"12\"/><line x1=\"12\" y1=\"8\" x2=\"12.01\" y2=\"8\"/>");
+S("<path d=\"M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z\"/><line x1=\"12\" y1=\"9\" x2=\"12\" y2=\"13\"/><line x1=\"12\" y1=\"17\" x2=\"12.01\" y2=\"17\"/>");
+S("<polyline points=\"3 6 5 6 21 6\"/><path d=\"M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2\"/><line x1=\"10\" y1=\"11\" x2=\"10\" y2=\"17\"/><line x1=\"14\" y1=\"11\" x2=\"14\" y2=\"17\"/>");
+S("<path d=\"M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4\"/><polyline points=\"7 10 12 15 17 10\"/><line x1=\"12\" y1=\"15\" x2=\"12\" y2=\"3\"/>");
+S("<rect x=\"9\" y=\"9\" width=\"13\" height=\"13\" rx=\"2\" ry=\"2\"/><path d=\"M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1\"/>");
+S("<path d=\"M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z\"/><circle cx=\"12\" cy=\"12\" r=\"3\"/>");
+S("<polygon points=\"12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2\"/>");
+S("<path d=\"M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z\"/>");
+S("<path d=\"M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6\"/><polyline points=\"15 3 21 3 21 9\"/><line x1=\"10\" y1=\"14\" x2=\"21\" y2=\"3\"/>");
+S("<path d=\"M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4\"/><path d=\"M9 18c-4.51 2-5-2-7-2\"/>");
+S16("<path d=\"m15 18-6-6 6-6\"/>");
+S16("<path d=\"m9 18 6-6-6-6\"/>");
+S("<polyline points=\"18 15 12 9 6 15\"/>");
+const ICON_CHEVRON_DOWN = S("<polyline points=\"6 9 12 15 18 9\"/>");
+S("<polyline points=\"16 18 22 12 16 6\"/><polyline points=\"8 6 2 12 8 18\"/>");
+S("<polyline points=\"15 3 21 3 21 9\"/><polyline points=\"9 21 3 21 3 15\"/><line x1=\"21\" y1=\"3\" x2=\"14\" y2=\"10\"/><line x1=\"3\" y1=\"21\" x2=\"10\" y2=\"14\"/>");
+S("<polyline points=\"4 8 4 3 9 3\"/><polyline points=\"20 16 20 21 15 21\"/><line x1=\"4\" y1=\"3\" x2=\"11\" y2=\"10\"/><line x1=\"20\" y1=\"21\" x2=\"13\" y2=\"14\"/>");
+S("<circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"M12 6v6l4 2\"/>");
+S("<polyline points=\"4 7 4 4 20 4 20 7\"/><line x1=\"9\" y1=\"20\" x2=\"15\" y2=\"20\"/><line x1=\"12\" y1=\"4\" x2=\"12\" y2=\"20\"/>");
+S("<path d=\"M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2\"/><circle cx=\"9\" cy=\"7\" r=\"4\"/><path d=\"M23 21v-2a4 4 0 0 0-3-3.87\"/><path d=\"M16 3.13a4 4 0 0 1 0 7.75\"/>");
+S("<path d=\"M12 1a3 3 0 0 0-3 3v8a3 3 0 0 0 6 0V4a3 3 0 0 0-3-3z\"/><path d=\"M19 10v2a7 7 0 0 1-14 0v-2\"/><line x1=\"12\" y1=\"19\" x2=\"12\" y2=\"23\"/><line x1=\"8\" y1=\"23\" x2=\"16\" y2=\"23\"/>");
+S("<path d=\"M9 18V5l12-2v13\"/><circle cx=\"6\" cy=\"18\" r=\"3\"/><circle cx=\"18\" cy=\"16\" r=\"3\"/>");
+S("<polygon points=\"23 7 16 12 23 17 23 7\"/><rect x=\"1\" y=\"5\" width=\"15\" height=\"14\" rx=\"2\" ry=\"2\"/>");
+S("<rect x=\"3\" y=\"3\" width=\"18\" height=\"18\" rx=\"2\" ry=\"2\"/><circle cx=\"8.5\" cy=\"8.5\" r=\"1.5\"/><polyline points=\"21 15 16 10 5 21\"/>");
+S("<circle cx=\"12\" cy=\"12\" r=\"5\"/><line x1=\"12\" y1=\"1\" x2=\"12\" y2=\"3\"/><line x1=\"12\" y1=\"21\" x2=\"12\" y2=\"23\"/><line x1=\"4.22\" y1=\"4.22\" x2=\"5.64\" y2=\"5.64\"/><line x1=\"18.36\" y1=\"18.36\" x2=\"19.78\" y2=\"19.78\"/><line x1=\"1\" y1=\"12\" x2=\"3\" y2=\"12\"/><line x1=\"21\" y1=\"12\" x2=\"23\" y2=\"12\"/><line x1=\"4.22\" y1=\"19.78\" x2=\"5.64\" y2=\"18.36\"/><line x1=\"18.36\" y1=\"5.64\" x2=\"19.78\" y2=\"4.22\"/>");
+S("<path d=\"M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z\"/>");
+S("<rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\"/><path d=\"M9 3v18\"/><path d=\"m14 9-3 3 3 3\"/>");
+S("<line x1=\"8\" y1=\"6\" x2=\"21\" y2=\"6\"/><line x1=\"8\" y1=\"12\" x2=\"21\" y2=\"12\"/><line x1=\"8\" y1=\"18\" x2=\"21\" y2=\"18\"/><line x1=\"3\" y1=\"6\" x2=\"3.01\" y2=\"6\"/><line x1=\"3\" y1=\"12\" x2=\"3.01\" y2=\"12\"/><line x1=\"3\" y1=\"18\" x2=\"3.01\" y2=\"18\"/>");
+S("<path d=\"M12 2l2.4 7.2h7.6l-6 4.8 2.4 7.2-6.4-4.8-6.4 4.8 2.4-7.2-6-4.8h7.6z\"/>");
+S("<polygon points=\"13 2 3 14 12 14 11 22 21 10 12 10 13 2\"/>");
+S("<polyline points=\"23 4 23 10 17 10\"/><polyline points=\"1 20 1 14 7 14\"/><path d=\"M3.51 9a9 9 0 0 1 14.85-3.36L23 10M1 14l4.64 4.36A9 9 0 0 0 20.49 15\"/>");
+S("<polyline points=\"1 4 1 10 7 10\"/><path d=\"M3.51 15a9 9 0 1 0 2.13-9.36L1 10\"/>");
+S("<circle cx=\"12\" cy=\"12\" r=\"3\"/><path d=\"M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z\"/>");
+S("<path d=\"M3 3v5h5\"/><path d=\"M3.05 13A9 9 0 1 0 6.11 6.11L3 8\"/><path d=\"M12 7v5l4 2\"/>");
+S("<line x1=\"22\" y1=\"2\" x2=\"11\" y2=\"13\"/><polygon points=\"22 2 15 22 11 13 2 9 22 2\"/>");
+S("<path d=\"M5 8l6 6\"/><path d=\"M4 14l6-6 2-3\"/><path d=\"M2 5h12\"/><path d=\"M7 2h1\"/><path d=\"M22 22l-5-10-5 10\"/><path d=\"M14 18h6\"/>");
+S("<path d=\"M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z\"/><polyline points=\"14 2 14 8 20 8\"/><line x1=\"16\" y1=\"13\" x2=\"8\" y2=\"13\"/><line x1=\"16\" y1=\"17\" x2=\"8\" y2=\"17\"/><polyline points=\"10 9 9 9 8 9\"/>");
+S("<path d=\"M17 3a2.828 2.828 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5L17 3z\"/>");
+S("<circle cx=\"12\" cy=\"12\" r=\"1\"/><path d=\"M20 12a8 8 0 1 1-8-8\"/><path d=\"m16 2 4 4-4 4\"/>");
+S("<path d=\"M20.59 13.41l-7.17 7.17a2 2 0 0 1-2.83 0L2 12V2h10l8.59 8.59a2 2 0 0 1 0 2.82z\"/><line x1=\"7\" y1=\"7\" x2=\"7.01\" y2=\"7\"/>");
+S("<circle cx=\"9\" cy=\"12\" r=\"1\"/><circle cx=\"15\" cy=\"12\" r=\"1\"/><circle cx=\"9\" cy=\"6\" r=\"1\"/><circle cx=\"15\" cy=\"6\" r=\"1\"/><circle cx=\"9\" cy=\"18\" r=\"1\"/><circle cx=\"15\" cy=\"18\" r=\"1\"/>");
+S("<rect x=\"2\" y=\"2\" width=\"8\" height=\"8\" rx=\"1\"/><rect x=\"14\" y=\"2\" width=\"8\" height=\"8\" rx=\"1\"/><rect x=\"2\" y=\"14\" width=\"8\" height=\"8\" rx=\"1\"/><rect x=\"14\" y=\"14\" width=\"8\" height=\"8\" rx=\"1\"/>");
+S("<circle cx=\"12\" cy=\"12\" r=\"10\"/><line x1=\"2\" y1=\"12\" x2=\"22\" y2=\"12\"/><path d=\"M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z\"/>");
+S("<path d=\"M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48\"/>");
+S36("<path d=\"M12 16V4\"/><path d=\"m6 9 6-5 6 5\"/><path d=\"M4 20h16\"/>");
+const S18c = (d) => `<svg class="qs-ico" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${d}</svg>`;
+const S20c = (d) => `<svg class="qw-cal-svg" xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${d}</svg>`;
+S18c("<circle cx=\"11\" cy=\"11\" r=\"7\"/><path d=\"m20 20-3.2-3.2\"/>");
+S18("<path d=\"M4 7h16M4 12h16M4 17h16\"/>");
+S20c("<rect x=\"3\" y=\"4\" width=\"18\" height=\"18\" rx=\"2\"/><path d=\"M8 2v4M16 2v4M3 10h18\"/>");
+S16("<path d=\"m15 18-6-6 6-6\"/>");
+S16("<path d=\"m9 18 6-6-6-6\"/>");
+//#endregion
+//#region src/scroll-fab.ts
+/** 青梧UI ScrollFab 悬浮滚动栏：默认“滚动到底部”，桌面悬停/触屏按住绕满描边一圈翻转为“返回顶部”，点击（轻点）直接执行当前模式动作 */
+const RADIUS = 21;
+const DEFAULT_LABEL_BOTTOM = "滚动到底部（悬停或按住绕圈可切换为返回顶部）";
+const DEFAULT_LABEL_TOP = "返回顶部（悬停或按住绕圈可切换为滚动到底部）";
+function easeInOutCubic(p) {
+	return p < .5 ? 4 * p * p * p : 1 - (-2 * p + 2) ** 3 / 2;
+}
+var ScrollFab = class {
+	el;
+	ring;
+	track;
+	icon;
+	len;
+	targetEl;
+	ringMs;
+	decayMs;
+	cancelPx;
+	animate;
+	labelBottom;
+	labelTop;
+	onModeChange;
+	mode = "to-bottom";
+	progress = 0;
+	hovering = false;
+	pressing = false;
+	flipped = false;
+	pointerId = null;
+	startX = 0;
+	startY = 0;
+	ringRaf = null;
+	lastTs = null;
+	scrollRaf = null;
+	flashTimer = null;
+	tapResetTimer = null;
+	touchTap = false;
+	ro = null;
+	constructor(options = {}) {
+		this.targetEl = options.target ?? 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.onModeChange = options.onModeChange;
+		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);
+		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");
+		svg.setAttribute("class", "qsf-svg");
+		svg.setAttribute("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;
+		try {
+			const measured = this.ring.getTotalLength();
+			if (Number.isFinite(measured)) len = measured;
+		} catch {}
+		this.len = len;
+		this.ring.style.strokeDasharray = String(this.len);
+		this.renderRing();
+		this.icon = document.createElement("span");
+		this.icon.className = "qsf-icon";
+		this.icon.setAttribute("aria-hidden", "true");
+		if (options.content != null) if (typeof options.content === "string") this.icon.innerHTML = options.content;
+		else this.icon.append(options.content);
+		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);
+		this.el.addEventListener("keydown", this.onKey);
+		this.el.addEventListener("click", this.onClick);
+		window.addEventListener("resize", this.onRecheck);
+		(this.targetEl ?? window).addEventListener("scroll", this.onRecheck, { passive: true });
+		if (typeof ResizeObserver === "function") {
+			this.ro = new ResizeObserver(this.onRecheck);
+			this.ro.observe(this.targetEl ?? document.documentElement);
+		}
+		this.syncVisible();
+	}
+	/** 当前模式 */
+	get currentMode() {
+		return this.mode;
+	}
+	/** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估） */
+	refresh() {
+		this.onRecheck();
+	}
+	scrollToBottom() {
+		this.animateScroll("bottom");
+	}
+	scrollToTop() {
+		this.scrollTo(0);
+	}
+	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.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();
+		if (this.ringRaf != null) cancelAnimationFrame(this.ringRaf);
+		this.ringRaf = null;
+		if (this.flashTimer != null) clearTimeout(this.flashTimer);
+		if (this.tapResetTimer != null) clearTimeout(this.tapResetTimer);
+		this.el.remove();
+	}
+	makeCircle(cls) {
+		const c = document.createElementNS("http://www.w3.org/2000/svg", "circle");
+		c.setAttribute("class", cls);
+		c.setAttribute("cx", "24");
+		c.setAttribute("cy", "24");
+		c.setAttribute("r", String(RADIUS));
+		return c;
+	}
+	onEnter = (e) => {
+		if (e.pointerType !== "mouse") return;
+		this.hovering = true;
+		this.kickRing();
+	};
+	onLeave = (e) => {
+		if (e.pointerType !== "mouse") return;
+		this.hovering = false;
+		this.flipped = false;
+	};
+	onDown = (e) => {
+		if (e.button !== 0 || this.pointerId !== null) return;
+		if (e.pointerType === "mouse") return;
+		e.preventDefault();
+		this.touchTap = true;
+		if (this.tapResetTimer != null) clearTimeout(this.tapResetTimer);
+		this.pointerId = e.pointerId;
+		this.startX = e.clientX;
+		this.startY = e.clientY;
+		this.pressing = true;
+		this.flipped = false;
+		this.kickRing();
+	};
+	onMove = (e) => {
+		if (e.pointerId !== this.pointerId || !this.pressing) return;
+		if (Math.hypot(e.clientX - this.startX, e.clientY - this.startY) > this.cancelPx) {
+			this.pressing = false;
+			this.pointerId = null;
+			this.flipped = false;
+		}
+	};
+	onUp = (e) => {
+		if (e.pointerId !== this.pointerId) return;
+		this.pointerId = null;
+		this.pressing = false;
+		const consumed = this.flipped;
+		this.flipped = false;
+		this.tapResetTimer = setTimeout(() => {
+			this.touchTap = false;
+			this.tapResetTimer = null;
+		}, 400);
+		if (consumed) return;
+		this.doAction();
+	};
+	onCancel = (e) => {
+		if (e.pointerId !== this.pointerId) return;
+		this.pointerId = null;
+		this.pressing = false;
+		this.flipped = false;
+	};
+	onClick = (e) => {
+		if (this.touchTap) {
+			e.preventDefault();
+			e.stopPropagation();
+			return;
+		}
+		this.doAction();
+	};
+	onKey = (e) => {
+		if (e.repeat || e.key !== "Enter" && e.key !== " ") return;
+		e.preventDefault();
+		this.setMode(this.mode === "to-bottom" ? "to-top" : "to-bottom");
+	};
+	holding() {
+		return this.hovering || this.pressing;
+	}
+	kickRing() {
+		if (this.ringRaf != null) return;
+		this.lastTs = null;
+		this.ringRaf = requestAnimationFrame(this.stepRing);
+	}
+	stepRing = (ts) => {
+		const dt = this.lastTs == null ? 0 : ts - this.lastTs;
+		this.lastTs = ts;
+		if (this.holding()) {
+			if (!this.flipped) {
+				this.progress = Math.min(1, this.progress + dt / this.ringMs);
+				if (this.progress >= 1) this.completeRing();
+			}
+		} else this.progress = Math.max(0, this.progress - dt / this.decayMs);
+		this.renderRing();
+		if (this.holding() || this.progress > 0) this.ringRaf = requestAnimationFrame(this.stepRing);
+		else this.ringRaf = null;
+	};
+	/** 绕满一圈 = 纯模式翻转（不附带任何滚动） */
+	completeRing() {
+		this.flipped = true;
+		const next = this.mode === "to-bottom" ? "to-top" : "to-bottom";
+		this.setMode(next);
+		this.el.classList.add("is-complete");
+		if (this.flashTimer != null) clearTimeout(this.flashTimer);
+		this.flashTimer = setTimeout(() => {
+			this.el.classList.remove("is-complete");
+			this.flashTimer = null;
+		}, 350);
+	}
+	renderRing() {
+		const vis = this.progress > 0;
+		this.track.toggleAttribute("hidden", !vis);
+		this.ring.toggleAttribute("hidden", !vis);
+		this.ring.style.strokeDashoffset = String(this.len * (1 - this.progress));
+	}
+	setMode(mode) {
+		if (mode === this.mode) return;
+		this.mode = mode;
+		this.el.dataset.mode = mode;
+		this.el.setAttribute("aria-label", mode === "to-bottom" ? this.labelBottom : this.labelTop);
+		this.onModeChange?.(mode);
+	}
+	doAction() {
+		this.animateScroll(this.mode === "to-bottom" ? "bottom" : "top");
+	}
+	animateScroll(dest) {
+		this.cancelScroll();
+		if (!this.animate || this.reducedMotion()) {
+			this.setScrollPos(this.targetPos(dest));
+			return;
+		}
+		this.attachInterrupt();
+		let init = false;
+		let start = 0;
+		let end = 0;
+		let t0 = 0;
+		let dur = 0;
+		const step = (ts) => {
+			if (!init) {
+				init = true;
+				start = this.scrollPos();
+				end = this.targetPos(dest);
+				t0 = ts;
+				dur = Math.min(1200, Math.max(400, Math.abs(end - start) / 3));
+			} else if (dest === "bottom") {
+				const live = this.targetPos(dest);
+				if (Math.abs(live - end) > 2) {
+					end = live;
+					start = this.scrollPos();
+					t0 = ts;
+					dur = Math.min(1200, Math.max(400, Math.abs(end - start) / 3));
+				}
+			}
+			const p = Math.min(1, (ts - t0) / dur);
+			this.setScrollPos(start + (end - start) * easeInOutCubic(p));
+			if (p < 1) this.scrollRaf = requestAnimationFrame(step);
+			else {
+				this.scrollRaf = null;
+				this.detachInterrupt();
+			}
+		};
+		this.scrollRaf = requestAnimationFrame(step);
+	}
+	reducedMotion() {
+		return typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+	}
+	onInterrupt = () => {
+		this.cancelScroll();
+	};
+	interruptSource() {
+		return this.targetEl ?? window;
+	}
+	attachInterrupt() {
+		const src = this.interruptSource();
+		for (const ev of [
+			"wheel",
+			"touchstart",
+			"keydown"
+		]) src.addEventListener(ev, this.onInterrupt, { passive: true });
+	}
+	detachInterrupt() {
+		const src = this.interruptSource();
+		for (const ev of [
+			"wheel",
+			"touchstart",
+			"keydown"
+		]) src.removeEventListener(ev, this.onInterrupt);
+	}
+	cancelScroll() {
+		if (this.scrollRaf != null) {
+			cancelAnimationFrame(this.scrollRaf);
+			this.scrollRaf = null;
+		}
+		this.detachInterrupt();
+	}
+	maxScroll() {
+		if (this.targetEl) return Math.max(0, this.targetEl.scrollHeight - this.targetEl.clientHeight);
+		return Math.max(0, document.documentElement.scrollHeight - window.innerHeight);
+	}
+	targetPos(dest) {
+		return dest === "bottom" ? this.maxScroll() : 0;
+	}
+	scrollPos() {
+		if (this.targetEl) return this.targetEl.scrollTop;
+		return window.scrollY || document.documentElement.scrollTop || 0;
+	}
+	setScrollPos(v) {
+		if (this.targetEl) this.targetEl.scrollTop = v;
+		else window.scrollTo(0, v);
+	}
+	scrollTo(v) {
+		this.animateScroll(v === 0 ? "top" : "bottom");
+	}
+	onRecheck = () => {
+		this.syncVisible();
+	};
+	syncVisible() {
+		this.el.hidden = this.maxScroll() <= 1;
+	}
+};
+//#endregion
+exports.ScrollFab = ScrollFab;

package/dist/index.d.cts

@@ -0,0 +1,111 @@
+//#region src/types.d.ts
+type ScrollFabMode = "to-bottom" | "to-top";
+/** 悬浮位置（px）；bottom 缺省时自动叠加 safe-area，显式传入则按原值生效 */
+interface ScrollFabPosition {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+interface ScrollFabOptions {
+  /** 滚动容器，null（默认）为 window */
+  target?: HTMLElement | null;
+  /** 本体直径 px，默认 48，内部钳制最小 44（触控命中区） */
+  size?: number;
+  /** 绕满一圈的时长 ms（桌面悬停推进 / 触屏按住推进），默认 800 */
+  ringDuration?: number;
+  /** 离开/松手后描边衰减倒转的时长 ms，默认 300 */
+  decayDuration?: number;
+  /** 触屏按住期间指针位移超过该值（px）视为放弃描边、放行页面手势，默认 10 */
+  cancelThreshold?: number;
+  /** 中心内容自定义：HTML 字符串或节点，缺省为方向箭头 */
+  content?: string | HTMLElement;
+  /** 悬浮位置，默认右下 right 24 / bottom 24（含 safe-area） */
+  position?: ScrollFabPosition;
+  /** z-index，默认 9999 */
+  zIndex?: number;
+  /** 附加类名 */
+  className?: string;
+  /** 动画开关，关闭或 prefers-reduced-motion 时程序滚动瞬时到位，默认 true */
+  animate?: boolean;
+  /** 模式①（滚动到底部）无障碍标签 */
+  ariaLabelToBottom?: string;
+  /** 模式②（返回顶部）无障碍标签 */
+  ariaLabelToTop?: string;
+  /** 模式翻转回调 */
+  onModeChange?: (mode: ScrollFabMode) => void;
+}
+//#endregion
+//#region src/scroll-fab.d.ts
+declare class ScrollFab {
+  readonly el: HTMLButtonElement;
+  private readonly ring;
+  private readonly track;
+  private readonly icon;
+  private readonly len;
+  private readonly targetEl;
+  private readonly ringMs;
+  private readonly decayMs;
+  private readonly cancelPx;
+  private readonly animate;
+  private readonly labelBottom;
+  private readonly labelTop;
+  private readonly onModeChange?;
+  private mode;
+  private progress;
+  private hovering;
+  private pressing;
+  private flipped;
+  private pointerId;
+  private startX;
+  private startY;
+  private ringRaf;
+  private lastTs;
+  private scrollRaf;
+  private flashTimer;
+  private tapResetTimer;
+  private touchTap;
+  private ro;
+  constructor(options?: ScrollFabOptions);
+  /** 当前模式 */
+  get currentMode(): ScrollFabMode;
+  /** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估） */
+  refresh(): void;
+  scrollToBottom(): void;
+  scrollToTop(): void;
+  destroy(): void;
+  private makeCircle;
+  private onEnter;
+  private onLeave;
+  private onDown;
+  private onMove;
+  private onUp;
+  private onCancel;
+  private onClick;
+  private onKey;
+  private holding;
+  private kickRing;
+  private stepRing;
+  /** 绕满一圈 = 纯模式翻转（不附带任何滚动） */
+  private completeRing;
+  private renderRing;
+  private setMode;
+  private doAction;
+  private animateScroll;
+  private reducedMotion;
+  private onInterrupt;
+  private interruptSource;
+  private attachInterrupt;
+  private detachInterrupt;
+  private cancelScroll;
+  private maxScroll;
+  private targetPos;
+  private scrollPos;
+  private setScrollPos;
+  private scrollTo;
+  private onRecheck;
+  private syncVisible;
+}
+//#endregion
+export { ScrollFab, type ScrollFabMode, type ScrollFabOptions, type ScrollFabPosition };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/scroll-fab.ts"],"mappings":";KAAY;;UAGK;EACf;EACA;EACA;EACA;;UAGe;;EAEf,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;EAEA,mBAAmB;;EAEnB,WAAW;;EAEX;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,gBAAgB,MAAM;;;;cCvBX;WACF,IAAI;mBAEI;mBACA;mBACA;mBACA;mBAEA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;UAET;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;EAER,YAAY,UAAS;;MA4EjB,eAAe;;EAKnB;EAIA;EAIA;EAIA;UAoBQ;UAeA;UAMA;UAMA;UAeA;UAUA;UAeA;UAOA;UAUA;UAQA;UAIA;UAMA;;UAoBA;UAYA;UAOA;UAUA;UAIA;UAwCA;UAMA;UAIA;UAIA;UAMA;UAMA;UAUA;UAKA;UAIA;UAKA;UAKA;UAIA;UAIA"}

package/dist/index.d.mts

@@ -0,0 +1,111 @@
+//#region src/types.d.ts
+type ScrollFabMode = "to-bottom" | "to-top";
+/** 悬浮位置（px）；bottom 缺省时自动叠加 safe-area，显式传入则按原值生效 */
+interface ScrollFabPosition {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+interface ScrollFabOptions {
+  /** 滚动容器，null（默认）为 window */
+  target?: HTMLElement | null;
+  /** 本体直径 px，默认 48，内部钳制最小 44（触控命中区） */
+  size?: number;
+  /** 绕满一圈的时长 ms（桌面悬停推进 / 触屏按住推进），默认 800 */
+  ringDuration?: number;
+  /** 离开/松手后描边衰减倒转的时长 ms，默认 300 */
+  decayDuration?: number;
+  /** 触屏按住期间指针位移超过该值（px）视为放弃描边、放行页面手势，默认 10 */
+  cancelThreshold?: number;
+  /** 中心内容自定义：HTML 字符串或节点，缺省为方向箭头 */
+  content?: string | HTMLElement;
+  /** 悬浮位置，默认右下 right 24 / bottom 24（含 safe-area） */
+  position?: ScrollFabPosition;
+  /** z-index，默认 9999 */
+  zIndex?: number;
+  /** 附加类名 */
+  className?: string;
+  /** 动画开关，关闭或 prefers-reduced-motion 时程序滚动瞬时到位，默认 true */
+  animate?: boolean;
+  /** 模式①（滚动到底部）无障碍标签 */
+  ariaLabelToBottom?: string;
+  /** 模式②（返回顶部）无障碍标签 */
+  ariaLabelToTop?: string;
+  /** 模式翻转回调 */
+  onModeChange?: (mode: ScrollFabMode) => void;
+}
+//#endregion
+//#region src/scroll-fab.d.ts
+declare class ScrollFab {
+  readonly el: HTMLButtonElement;
+  private readonly ring;
+  private readonly track;
+  private readonly icon;
+  private readonly len;
+  private readonly targetEl;
+  private readonly ringMs;
+  private readonly decayMs;
+  private readonly cancelPx;
+  private readonly animate;
+  private readonly labelBottom;
+  private readonly labelTop;
+  private readonly onModeChange?;
+  private mode;
+  private progress;
+  private hovering;
+  private pressing;
+  private flipped;
+  private pointerId;
+  private startX;
+  private startY;
+  private ringRaf;
+  private lastTs;
+  private scrollRaf;
+  private flashTimer;
+  private tapResetTimer;
+  private touchTap;
+  private ro;
+  constructor(options?: ScrollFabOptions);
+  /** 当前模式 */
+  get currentMode(): ScrollFabMode;
+  /** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估） */
+  refresh(): void;
+  scrollToBottom(): void;
+  scrollToTop(): void;
+  destroy(): void;
+  private makeCircle;
+  private onEnter;
+  private onLeave;
+  private onDown;
+  private onMove;
+  private onUp;
+  private onCancel;
+  private onClick;
+  private onKey;
+  private holding;
+  private kickRing;
+  private stepRing;
+  /** 绕满一圈 = 纯模式翻转（不附带任何滚动） */
+  private completeRing;
+  private renderRing;
+  private setMode;
+  private doAction;
+  private animateScroll;
+  private reducedMotion;
+  private onInterrupt;
+  private interruptSource;
+  private attachInterrupt;
+  private detachInterrupt;
+  private cancelScroll;
+  private maxScroll;
+  private targetPos;
+  private scrollPos;
+  private setScrollPos;
+  private scrollTo;
+  private onRecheck;
+  private syncVisible;
+}
+//#endregion
+export { ScrollFab, type ScrollFabMode, type ScrollFabOptions, type ScrollFabPosition };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/scroll-fab.ts"],"mappings":";KAAY;;UAGK;EACf;EACA;EACA;EACA;;UAGe;;EAEf,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;EAEA,mBAAmB;;EAEnB,WAAW;;EAEX;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA,gBAAgB,MAAM;;;;cCvBX;WACF,IAAI;mBAEI;mBACA;mBACA;mBACA;mBAEA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;UAET;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;EAER,YAAY,UAAS;;MA4EjB,eAAe;;EAKnB;EAIA;EAIA;EAIA;UAoBQ;UAeA;UAMA;UAMA;UAeA;UAUA;UAeA;UAOA;UAUA;UAQA;UAIA;UAMA;;UAoBA;UAYA;UAOA;UAUA;UAIA;UAwCA;UAMA;UAIA;UAIA;UAMA;UAMA;UAUA;UAKA;UAIA;UAKA;UAKA;UAIA;UAIA"}