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

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,22 +68,48 @@ 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;
   /** 模式②（返回顶部）无障碍标签 */
   ariaLabelToTop?: string;
   /** 模式翻转回调 */
   onModeChange?: (mode: ScrollFabMode) => void;
+  /**
+   * 启用的模式集合（按数组顺序）；缺省 ["to-bottom", "to-top"]。
+   * 初始模式取首项；只传一个即为单模式（无绕环翻转、无描边、静态 aria 文案）；空数组/全非法抛 TypeError。
+   */
+  modes?: ScrollFabMode[];
+  /** 显示所需的最小已滚动距离 px：scrollPos < 该值时按钮隐藏（默认 0，行为不变）；负数按 0 */
+  showThreshold?: number;
+  /**
+   * 滚动进度回调：0..1 小数（maxScroll 为 0 时吐 0），scroll/resize/程序滚动时 rAF 节流触发，
+   * 按钮隐藏期间照常吐，构造完成与 refresh() 后各补发一次。
+   */
+  onScroll?: (pct: number) => void;
 }
 //#endregion
 //#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 +117,17 @@ declare class ScrollFab {
   private readonly labelBottom;
   private readonly labelTop;
   private readonly onModeChange?;
+  private readonly onLenisReady?;
+  private readonly onScroll?;
+  private readonly modes;
+  private readonly single;
+  private readonly threshold;
+  /** 外部注入：宿主实例，组件永不销毁 */
+  private externalLenis;
+  /** 自建配置：null = 不走 lenis；true 形态也归一成对象 */
+  private ownLenisConfig;
+  private ownLenis;
+  private ownLenisPromise;
   private mode;
   private progress;
   private hovering;
@@ -62,19 +139,29 @@ 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;
+  private emitRaf;
+  private lastPct;
   constructor(options?: ScrollFabOptions);
   /** 当前模式 */
   get currentMode(): ScrollFabMode;
-  /** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估） */
+  /** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估），并强制补发一次进度 */
   refresh(): void;
   scrollToBottom(): void;
   scrollToTop(): void;
   destroy(): void;
+  /** 规范化 modes：缺省双模式；去重、过滤非法值；结果为空直接抛错 */
+  private normalizeModes;
   private makeCircle;
+  private makePath;
   private onEnter;
   private onLeave;
   private onDown;
@@ -92,20 +179,41 @@ 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;
+  /** rAF 节流：一帧内多次重估只吐一次；按钮隐藏期间照常调度 */
+  private scheduleScroll;
+  private emitScroll;
 }
 //#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;;;;;EAKtB,QAAQ;;EAER;;;;;EAKA,YAAY;;;;cC3ED;WACF,IAAI;UAEL;UACA;UACA;mBACS;UACT;mBAES;mBACA;mBACA;mBACA;mBACA;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;UACA;UACA;EAER,YAAY,UAAS;;MA2HjB,eAAe;;EAKnB;EAMA;EAIA;EAIA;;UA8BQ;UAcA;UASA;UAcA;UAMA;UAMA;UAeA;UAUA;UAeA;UAOA;UAUA;UAYA;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;UAKA;;UAKA;UAQA"}

package/dist/index.d.mts

@@ -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,22 +68,48 @@ 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;
   /** 模式②（返回顶部）无障碍标签 */
   ariaLabelToTop?: string;
   /** 模式翻转回调 */
   onModeChange?: (mode: ScrollFabMode) => void;
+  /**
+   * 启用的模式集合（按数组顺序）；缺省 ["to-bottom", "to-top"]。
+   * 初始模式取首项；只传一个即为单模式（无绕环翻转、无描边、静态 aria 文案）；空数组/全非法抛 TypeError。
+   */
+  modes?: ScrollFabMode[];
+  /** 显示所需的最小已滚动距离 px：scrollPos < 该值时按钮隐藏（默认 0，行为不变）；负数按 0 */
+  showThreshold?: number;
+  /**
+   * 滚动进度回调：0..1 小数（maxScroll 为 0 时吐 0），scroll/resize/程序滚动时 rAF 节流触发，
+   * 按钮隐藏期间照常吐，构造完成与 refresh() 后各补发一次。
+   */
+  onScroll?: (pct: number) => void;
 }
 //#endregion
 //#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 +117,17 @@ declare class ScrollFab {
   private readonly labelBottom;
   private readonly labelTop;
   private readonly onModeChange?;
+  private readonly onLenisReady?;
+  private readonly onScroll?;
+  private readonly modes;
+  private readonly single;
+  private readonly threshold;
+  /** 外部注入：宿主实例，组件永不销毁 */
+  private externalLenis;
+  /** 自建配置：null = 不走 lenis；true 形态也归一成对象 */
+  private ownLenisConfig;
+  private ownLenis;
+  private ownLenisPromise;
   private mode;
   private progress;
   private hovering;
@@ -62,19 +139,29 @@ 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;
+  private emitRaf;
+  private lastPct;
   constructor(options?: ScrollFabOptions);
   /** 当前模式 */
   get currentMode(): ScrollFabMode;
-  /** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估） */
+  /** 内容懒加载等外部高度变化后可显式触发重估（滚动/resize 时也会自动重估），并强制补发一次进度 */
   refresh(): void;
   scrollToBottom(): void;
   scrollToTop(): void;
   destroy(): void;
+  /** 规范化 modes：缺省双模式；去重、过滤非法值；结果为空直接抛错 */
+  private normalizeModes;
   private makeCircle;
+  private makePath;
   private onEnter;
   private onLeave;
   private onDown;
@@ -92,20 +179,41 @@ 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;
+  /** rAF 节流：一帧内多次重估只吐一次；按钮隐藏期间照常调度 */
+  private scheduleScroll;
+  private emitScroll;
 }
 //#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.mts.map

package/dist/index.d.mts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.mts","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;;;;;EAKtB,QAAQ;;EAER;;;;;EAKA,YAAY;;;;cC3ED;WACF,IAAI;UAEL;UACA;UACA;mBACS;UACT;mBAES;mBACA;mBACA;mBACA;mBACA;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;UACA;UACA;EAER,YAAY,UAAS;;MA2HjB,eAAe;;EAKnB;EAMA;EAIA;EAIA;;UA8BQ;UAcA;UASA;UAcA;UAMA;UAMA;UAeA;UAUA;UAeA;UAOA;UAUA;UAYA;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;UAKA;;UAKA;UAQA"}