nhanh-pure-function 4.4.0 → 4.5.0

package/dist/Animate/index.d.ts

@@ -10,11 +10,11 @@ export declare function _Animate_Schedule(callback: (schedule: number) => void,
  * @param initialMin - 振荡器初始最小值
  * @param initialMax - 振荡器初始最大值
  * @param initialSteps - 从最小值到最大值所需的动画步数
- * @param callback - 每帧更新时的回调函数，接收当前振荡值
+ * @param callback - 每帧回调 `(value, direction)`：`value` 为经 `precision` 处理后的当前值；`direction` 为本帧步进方向（`1` 朝向 `max`，`-1` 朝向 `min`），触边翻转后传入
  * @param precision - 数值精度（保留小数位数，默认4位）
  * @returns 振荡器控制对象，包含播放/暂停/参数更新等方法
  */
-export declare function _Animate_CreateOscillator(initialMin: number, initialMax: number, initialSteps: number, callback: (value: number) => void, precision?: number): {
+export declare function _Animate_CreateOscillator(initialMin: number, initialMax: number, initialSteps: number, callback: (value: number, direction: 1 | -1) => void, precision?: number): {
     /** 启动/继续动画 */
     play(target?: number): void;
     /** 暂停动画 */

package/dist/Element/Runtime/drop.d.ts

@@ -0,0 +1,45 @@
+/** 自定义拖拽校验与提取器 */
+export interface CustomDropValidator {
+    /**
+     * 悬停拦截：拖拽进入/悬停时触发。
+     * 此时出于安全策略无法读取文件内容，仅能通过暴露的 types 判断是否允许拖入。
+     */
+    matchTypes: (types: readonly string[]) => boolean;
+    /**
+     * 精确提取：拖拽放下（drop）时触发。
+     * 遍历 dataTransfer.items 的每一项，返回 true 代表将该项提取并交由回调处理。
+     */
+    matchItem: (item: DataTransferItem) => boolean;
+}
+/** 拖放区接受的拖拽数据类型 */
+export type DropTargetType = "text" | "file" | "image" | "video" | "audio" | "application" | `.${string}` | `${string}/${string}` | (string & {}) | CustomDropValidator;
+/** 单一拖放规则配置 */
+export interface DropZoneRule {
+    /** 允许传入单一类型或多种类型组合的数组 */
+    targetType?: DropTargetType | DropTargetType[];
+    /** 拖放回调 */
+    dropCallback: (data: any[]) => void;
+    /** 当前规则匹配成功时的激活回调 */
+    activeCallback?: (active: boolean) => void;
+}
+/** 注册拖放区时的配置 */
+export type DropZoneOption = {
+    /** 拖放区元素 */
+    dom: HTMLElement | string;
+    /** 拖放区全局激活回调（只要有任意规则匹配就会触发） */
+    activeCallback?: (active: boolean) => void;
+} & (DropZoneRule | {
+    /** 多规则配置（允许对不同类型独立处理） */
+    rules: DropZoneRule[];
+});
+export declare class _Element_DropZoneManager {
+    private entries;
+    private extractRules;
+    add(config: DropZoneOption): void;
+    delete(dom: HTMLElement | string): void;
+    destroy(): void;
+    private onDragEnter;
+    private onDragLeave;
+    private onDragOver;
+    private onDrop;
+}

package/dist/Element/Runtime/index.d.ts

@@ -1,2 +1,3 @@
-/** Element 模块内依赖 DOM / 运行时的工具集合（全屏等）；新文件在此 `export *` 即可。 */
+/** Element 模块内依赖 DOM / 运行时的工具集合（全屏、拖放等）；新文件在此 `export *` 即可。 */
+export * from './drop';
 export * from './fullscreen';

package/dist/Math/index.d.ts

@@ -55,12 +55,18 @@ export declare function _Math_GetBoundaryIntersection(startPoint: [number, numbe
  */
 export declare const _Math_Degree: Math;
 /**
- * 根据控制点与参数 t，用 De Casteljau 计算 Bézier 曲线上的点。
+ * 根据控制点与参数 t，用 De Casteljau 计算 Bézier 曲线上的点和方向弧度。
+ *
+ * 【为什么可以这样获取方向】
+ * 根据 De Casteljau 算法的特性，当循环降维到倒数第二层（只剩最后 2 个点）时，
+ * 这两点连线的方向 [p1 - p0] 刚好就是曲线在该点处的切线向量。
+ * 此时使用 Math.atan2 即可直接换算出切线方向的弧度，无需单独执行求导公式。
+ *
  * @param nodes 控制点
  * @param progress 曲线参数，通常取 [0, 1]
- * @returns 曲线上的点
+ * @returns 曲线上的点和方向 [x, y, radian]
  */
-export declare function _Math_GetBezierCurveNodes(nodes: [number, number][], progress: number): [number, number];
+export declare function _Math_GetBezierCurveNodes(nodes: [number, number][], progress: number): [number, number, number];
 /**
  * 根据宽高比与参数 progress，计算椭圆上的点（中心在原点）。
  * @param aspectRatio 宽高比（width / height），即 X 半轴与 Y 半轴之比

package/dist/Utility/Runtime/shortcutKey.d.ts

@@ -1,16 +1,3 @@
-/**
- * 全局快捷键管理：支持组合键、多步序列、作用域与输入框上下文过滤。
- *
- * @example
- * ```ts
- * const shortcuts = new _Utility_ShortcutManager();
- * shortcuts.bind("control+s,control+shift+s", {
- *   callback: (e) => { e.preventDefault(); save(); },
- *   sequenceDelimiter: ",",
- *   chordDelimiter: "+",
- * });
- * ```
- */
 /** `bind` 时传入的配置项 */
 interface ShortcutOptions {
     /** 匹配成功后的回调 */
@@ -27,11 +14,30 @@ interface ShortcutOptions {
     timeout?: number;
     /** 为 `true` 时，在 input / textarea / contentEditable 内也响应快捷键 */
     enableInInput?: boolean;
+    /**
+     * 是否允许长按按键时重复触发回调，默认 `false`。
+     * 适用于如 `+`、`-`、方向键等需要连续操作的场景。
+     */
+    allowRepeat?: boolean;
+    /**
+     * 允许重复触发时的最小时间间隔（毫秒）。
+     * 由于操作系统的原生长按触发频率不可控且通常极高，利用该属性对重复事件进行节流。
+     */
+    repeatInterval?: number;
 }
 /**
- * 在 `window` 上监听键盘与鼠标事件，按配置触发快捷键回调。
+ * 全局快捷键管理器
+ *
+ * ⚠️ **注意**：本组件会在全局 `window` 上绑定多个事件监听器。
+ * 为了防止内存泄漏及非预期的快捷键触发，**在组件卸载或页面关闭时，必须显式调用 `.destroy()` 方法**。
+ *
+ * @example
+ * const manager = new _Utility_ShortcutManager();
+ * // 离开页面时
+ * manager.destroy();
  */
 export declare class _Utility_ShortcutManager {
+    private static activeInstances;
     /** 最近一次 `mousedown` 的目标，供 `scopeType: "click"` 使用 */
     private lastClickDom?;
     /** 最近一次 `mouseover` 的目标，供 `scopeType: "hover"` 使用 */
@@ -51,7 +57,11 @@ export declare class _Utility_ShortcutManager {
     bind(key: string | string[], options: ShortcutOptions): void;
     /** 移除指定 `key` 的绑定并清理其超时定时器 */
     unbind(key: string): void;
-    /** 移除所有监听、清空状态，实例不可再使用 */
+    /**
+     * 彻底销毁当前实例，清空所有快捷键绑定，并移除全局 window 事件监听器。
+     *
+     * ⚠️ **调用时机**：在单页应用（如 Vue/React 组件卸载）或不需要快捷键时**务必调用**。
+     */
     destroy(): void;
     private handleMouseOver;
     private handleMouseDown;