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

package/README.md

@@ -0,0 +1,96 @@
+# @qingwu-ui/scroll-fab
+
+[青梧UI](https://github.com/apricotdream/qingwu-ui) 的 **悬浮滚动栏** —— 框架无关，纯 DOM + CSS，零强依赖。
+
+- **绕圈翻转**：桌面悬停 / 触屏按住推进描边进度，绕满一圈在「滚动到底部 / 返回顶部」间纯切换（不附带滚动），未绕满移开/松手则描边衰减倒转
+- **点击与描边正交**：轻点恒直接执行当前模式动作；触屏绕满后的释放被消费，避免同一手势既翻转又滚动
+- **Lenis 可插拔**：内置 rAF 缓动，可选接入 [Lenis](https://github.com/darkroomengineering/lenis)（未安装静默回退）
+- **异形形状**：银杏叶等自定义外形，进度描边沿外扩轮廓完全包裹
+- 程序滚动支持 wheel / touch / keydown 打断、懒加载变长追击
+- 移动端一等支持：Pointer Events 单路径、ghost click 抑制、safe-area 定位、44px 命中下限
+- 尊重 `prefers-reduced-motion`；window 与自定义容器双支持
+
+## 安装
+
+```bash
+npm install @qingwu-ui/scroll-fab
+# 可选：启用 Lenis 平滑滚动
+npm install lenis
+```
+
+## 使用
+
+```ts
+import { ScrollFab } from "@qingwu-ui/scroll-fab";
+import "@qingwu-ui/scroll-fab/style.css";
+
+// 零配置：右下角圆形悬浮栏
+const fab = new ScrollFab();
+
+// 销毁
+fab.destroy();
+```
+
+### 接入 Lenis
+
+```ts
+// ① 自建实例（仅驱动按钮程序滚动，不劫持页面滚轮）
+new ScrollFab({
+  lenis: true,
+  onLenisReady: (lenis) => console.log("Lenis 就绪", lenis),
+});
+
+// ② 透传 Lenis 配置（target 容器自动映射为 wrapper）
+new ScrollFab({ lenis: { duration: 1.1 } });
+
+// ③ 复用宿主已有的 Lenis 实例（组件永不销毁它）
+const lenis = new Lenis();
+new ScrollFab({ lenis });
+```
+
+未安装 `lenis` 时自动回退内置 rAF，无任何报错。
+
+### 异形形状（银杏叶等）
+
+进度要「完全包裹」形状必须用双 path：`fill` 是叶片实体，`outline` 是外扩一圈的闭合轮廓（SVG 描边居中于路径，单 path 会有一半笔画压进形状内部）。
+
+```ts
+const LEAF = "M24 46 L23.2 34 C16 33 9 28 7 20 Z /* …完整 path d… */";
+
+new ScrollFab({
+  shape: {
+    fill: LEAF,
+    outline: LEAF, // 与 fill 同形
+    outlineTransform: "translate(24 24) scale(1.13) translate(-24 -24)",
+  },
+});
+```
+
+异形模式下圆形外壳自动退场（背景/边框/圆角），阴影改用 `drop-shadow` 跟随叶片真实形状；命中区仍为矩形以保证 44px 触控目标。
+
+## API
+
+```ts
+new ScrollFab(options?: ScrollFabOptions): ScrollFab
+
+interface ScrollFabOptions {
+  target?: HTMLElement | null;          // 滚动容器，默认 window
+  size?: number;                        // 直径 px，默认 48（最小 44）
+  ringDuration?: number;                // 绕圈时长 ms，默认 800
+  decayDuration?: number;               // 衰减倒转 ms，默认 300
+  cancelThreshold?: number;             // 触屏位移放弃阈值 px，默认 10
+  content?: string | HTMLElement;       // 中心内容，默认方向箭头
+  position?: ScrollFabPosition;         // 悬浮位置，默认右下 24/24
+  zIndex?: number;                      // 默认 9999
+  className?: string;
+  animate?: boolean;                    // 默认 true
+  lenis?: boolean | ScrollFabLenisConfig | LenisLike;
+  shape?: ScrollFabShape;
+  onLenisReady?: (lenis: LenisLike) => void;
+  ariaLabelToBottom?: string;
+  ariaLabelToTop?: string;
+  onModeChange?: (mode: "to-bottom" | "to-top") => void;
+}
+```
+
+实例方法：`scrollToBottom()` / `scrollToTop()` / `refresh()` / `destroy()`；只读属性 `currentMode`、`el`。

package/dist/index.cjs

@@ -74,19 +74,26 @@ 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 = "返回顶部（悬停或按住绕圈可切换为滚动到底部）";
 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;
@@ -94,6 +101,13 @@ var ScrollFab = class {
 	labelBottom;
 	labelTop;
 	onModeChange;
+	onLenisReady;
+	/** 外部注入：宿主实例，组件永不销毁 */
+	externalLenis = null;
+	/** 自建配置：null = 不走 lenis；true 形态也归一成对象 */
+	ownLenisConfig = null;
+	ownLenis = null;
+	ownLenisPromise = null;
 	mode = "to-bottom";
 	progress = 0;
 	hovering = false;
@@ -105,12 +119,18 @@ 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;
 	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);
@@ -118,10 +138,20 @@ var ScrollFab = class {
 		this.labelBottom = options.ariaLabelToBottom ?? DEFAULT_LABEL_BOTTOM;
 		this.labelTop = options.ariaLabelToTop ?? DEFAULT_LABEL_TOP;
 		this.onModeChange = options.onModeChange;
+		this.onLenisReady = options.onLenisReady;
+		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;
+		if (this.shape) this.el.dataset.shape = "on";
 		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));
@@ -129,17 +159,32 @@ var ScrollFab = class {
 		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);
@@ -180,9 +225,10 @@ var ScrollFab = class {
 		this.animateScroll("bottom");
 	}
 	scrollToTop() {
-		this.scrollTo(0);
+		this.animateScroll("top");
 	}
 	destroy() {
+		this.destroyed = true;
 		this.el.removeEventListener("pointerenter", this.onEnter);
 		this.el.removeEventListener("pointerleave", this.onLeave);
 		this.el.removeEventListener("pointerdown", this.onDown);
@@ -195,6 +241,9 @@ var ScrollFab = class {
 		(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.flashTimer != null) clearTimeout(this.flashTimer);
@@ -202,13 +251,19 @@ var ScrollFab = class {
 		this.el.remove();
 	}
 	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;
@@ -322,12 +377,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;
@@ -354,7 +507,7 @@ var ScrollFab = class {
 			if (p < 1) this.scrollRaf = requestAnimationFrame(step);
 			else {
 				this.scrollRaf = null;
-				this.detachInterrupt();
+				this.detachRafInterrupt();
 			}
 		};
 		this.scrollRaf = requestAnimationFrame(step);
@@ -368,15 +521,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",
@@ -389,7 +560,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);
@@ -406,9 +586,6 @@ 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();
 	};

package/dist/index.d.cts

@@ -7,6 +7,46 @@ interface ScrollFabPosition {
   bottom?: number;
   left?: number;
 }
+/** Lenis 实例的最小结构性类型（组件不硬依赖 lenis 包，按结构识别） */
+interface LenisLike {
+  scrollTo: (target: number | string | HTMLElement, options?: Record<string, unknown>) => void;
+  raf?: (time: number) => void;
+  destroy?: () => void;
+  start?: () => void;
+  stop?: () => void;
+  on?: (event: string, callback: (...args: unknown[]) => void) => void;
+  off?: (event: string, callback: (...args: unknown[]) => void) => void;
+  isScrolling?: boolean;
+}
+/** 内部自建 Lenis 时的构造配置（lenis 官方选项子集，允许透传其他字段） */
+interface ScrollFabLenisConfig {
+  wrapper?: HTMLElement | Window;
+  content?: HTMLElement;
+  duration?: number;
+  easing?: (t: number) => number;
+  /** 默认强制 false：自建实例不劫持用户滚轮，只驱动按钮触发的程序滚动；显式置 true 则接管全局 */
+  smoothWheel?: boolean;
+  smoothTouch?: boolean;
+  wheelMultiplier?: number;
+  touchMultiplier?: number;
+  [key: string]: unknown;
+}
+/**
+ * 异形按钮形状（如银杏叶）。
+ * 双 path 才能保证进度描边「完全包裹」：fill 是叶片实体，outline 是外扩一圈的闭合轮廓，
+ * SVG 描边居中于路径，单条 path 必有一半笔画压进形状内部。
+ * outline 的起点约定在 12 点钟方向（描边顺时针推进）。
+ */
+interface ScrollFabShape {
+  /** SVG viewBox，默认 "0 0 48 48"；自定义 path 建议按 48×48 绘制 */
+  viewBox?: string;
+  /** 形状实体 path d（被填充） */
+  fill: string;
+  /** 外扩进度轮廓 path d（track + 进度描边沿它走）；可与 fill 同形再配 outlineTransform 外扩 */
+  outline: string;
+  /** 作用于 outline path 的 SVG transform，如 "translate(24 24) scale(1.1) translate(-24 -24)" */
+  outlineTransform?: string;
+}
 interface ScrollFabOptions {
   /** 滚动容器，null（默认）为 window */
   target?: HTMLElement | null;
@@ -28,6 +68,18 @@ interface ScrollFabOptions {
   className?: string;
   /** 动画开关，关闭或 prefers-reduced-motion 时程序滚动瞬时到位，默认 true */
   animate?: boolean;
+  /**
+   * Lenis 平滑滚动（lenis 为 optional peerDependency，未安装静默回退内置 rAF）：
+   * - 传 Lenis 实例：复用宿主实例，组件不负责销毁；
+   * - true：点击时动态 import lenis 并自建实例（仅驱动按钮程序滚动，不劫持滚轮）；
+   * - 传配置对象：自建实例并透传配置（target 容器自动映射为 wrapper）；
+   * - false / 缺省：内置 rAF 缓动。
+   */
+  lenis?: boolean | ScrollFabLenisConfig | LenisLike;
+  /** 异形形状（银杏叶等）；传入后圆形外壳消失，进度沿外扩轮廓包裹 */
+  shape?: ScrollFabShape;
+  /** 自建 Lenis 实例就绪回调（外部实例注入时不触发），与 onEditorReady 模式对齐 */
+  onLenisReady?: (lenis: LenisLike) => void;
   /** 模式①（滚动到底部）无障碍标签 */
   ariaLabelToBottom?: string;
   /** 模式②（返回顶部）无障碍标签 */
@@ -39,11 +91,13 @@ interface ScrollFabOptions {
 //#region src/scroll-fab.d.ts
 declare class ScrollFab {
   readonly el: HTMLButtonElement;
-  private readonly ring;
-  private readonly track;
+  private ring;
+  private track;
+  private fillPath;
   private readonly icon;
-  private readonly len;
+  private len;
   private readonly targetEl;
+  private readonly shape;
   private readonly ringMs;
   private readonly decayMs;
   private readonly cancelPx;
@@ -51,6 +105,13 @@ declare class ScrollFab {
   private readonly labelBottom;
   private readonly labelTop;
   private readonly onModeChange?;
+  private readonly onLenisReady?;
+  /** 外部注入：宿主实例，组件永不销毁 */
+  private externalLenis;
+  /** 自建配置：null = 不走 lenis；true 形态也归一成对象 */
+  private ownLenisConfig;
+  private ownLenis;
+  private ownLenisPromise;
   private mode;
   private progress;
   private hovering;
@@ -62,10 +123,15 @@ declare class ScrollFab {
   private ringRaf;
   private lastTs;
   private scrollRaf;
+  private lenisLoopRaf;
+  private lenisScrolling;
+  private lenisDest;
   private flashTimer;
   private tapResetTimer;
   private touchTap;
   private ro;
+  private actionSeq;
+  private destroyed;
   constructor(options?: ScrollFabOptions);
   /** 当前模式 */
   get currentMode(): ScrollFabMode;
@@ -75,6 +141,7 @@ declare class ScrollFab {
   scrollToTop(): void;
   destroy(): void;
   private makeCircle;
+  private makePath;
   private onEnter;
   private onLeave;
   private onDown;
@@ -92,20 +159,38 @@ declare class ScrollFab {
   private setMode;
   private doAction;
   private animateScroll;
+  /** 首次点击时动态 import lenis 并自建实例；未安装（或加载失败）→ null 永久回退 rAF */
+  private resolveOwnLenis;
+  /**
+   * 用 Lenis 执行程序滚动。
+   * 自建实例（own）：组件自跑 raf loop（Lenis 需外部驱动 raf），保留 wheel/touch/keydown 打断与到底追击；
+   * 外部实例：宿主自带 raf loop 与手势处理，组件只发 scrollTo，不追击不打断。
+   */
+  private scrollWithLenis;
+  /** 自建实例的 raf 驱动 + 懒加载到底追击（对齐内置 rAF 语义） */
+  private startLenisLoop;
+  private stopLenisLoop;
+  /** 打断自建 Lenis 程序滚动：stop 冻结动画（下次发起前 start 复位） */
+  private onLenisInterrupt;
+  private endLenisScroll;
+  private animateRaf;
   private reducedMotion;
   private onInterrupt;
   private interruptSource;
+  /** 自建 Lenis 路线的打断监听 */
   private attachInterrupt;
   private detachInterrupt;
+  /** 内置 rAF 路线的打断监听 */
+  private attachRafInterrupt;
+  private detachRafInterrupt;
   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 };
+export { type LenisLike, ScrollFab, type ScrollFabLenisConfig, type ScrollFabMode, type ScrollFabOptions, type ScrollFabPosition, type ScrollFabShape };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/scroll-fab.ts"],"mappings":";KAAY;;UAGK;EACf;EACA;EACA;EACA;;;UAIe;EACf,WACE,0BAA0B,aAC1B,UAAU;EAEZ,OAAO;EACP;EACA;EACA;EACA,MAAM,eAAe,cAAc;EACnC,OAAO,eAAe,cAAc;EACpC;;;UAIe;EACf,UAAU,cAAc;EACxB,UAAU;EACV;EACA,UAAU;;EAEV;EACA;EACA;EACA;GACC;;;;;;;;UASc;;EAEf;;EAEA;;EAEA;;EAEA;;UAGe;;EAEf,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;EAEA,mBAAmB;;EAEnB,WAAW;;EAEX;;EAEA;;EAEA;;;;;;;;EAQA,kBAAkB,uBAAuB;;EAEzC,QAAQ;;EAER,gBAAgB,OAAO;;EAEvB;;EAEA;;EAEA,gBAAgB,MAAM;;;;cCjEX;WACF,IAAI;UAEL;UACA;UACA;mBACS;UACT;mBAES;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;;UAGT;;UAEA;UACA;UACA;UAEA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;UACA;EAER,YAAY,UAAS;;MA2GjB,eAAe;;EAKnB;EAIA;EAIA;EAIA;UAyBQ;UASA;UAaA;UAMA;UAMA;UAeA;UAUA;UAeA;UAOA;UAUA;UAQA;UAIA;UAMA;;UAoBA;UAYA;UAOA;UAUA;UAIA;;UAyBA;;;;;;UA6BA;;UA6BA;UAqBA;;UAQA;UAMA;UASA;UAmCA;UAMA;UAIA;;UAKA;UAMA;;UAOA;UAMA;UAMA;UAeA;UAKA;UAIA;UAKA;UAKA;UAIA"}