nhanh-pure-function 4.3.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,9 +55,23 @@ 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 半轴之比
+ * @param progress 曲线参数，通常取 [0, 1]，表示沿椭圆一周的位置
+ * @param normalizeToUnitSquare 为 true 时将坐标归一化到 [0,1]×[0,1]（外接矩形内）
+ * @returns 椭圆上的点 [x, y]
+ */
+export declare function _Math_GetEllipsePoints(aspectRatio: number, progress: number, normalizeToUnitSquare?: boolean): [number, number];

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

@@ -0,0 +1,2 @@
+export * from './undoRedoHistory';
+export * from './shortcutKey';

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

@@ -0,0 +1,98 @@
+/** `bind` 时传入的配置项 */
+interface ShortcutOptions {
+    /** 匹配成功后的回调 */
+    callback: (event: KeyboardEvent) => void;
+    /** 多步序列之间的分隔符，默认 `","` */
+    sequenceDelimiter?: string;
+    /** 单步组合键内各键的分隔符，默认 `"+"` */
+    chordDelimiter?: string;
+    /** CSS 选择器，仅在匹配元素内生效；未设置则全局生效 */
+    scope?: string;
+    /** `scope` 的判定依据：`click` 用最近点击目标，`hover` 用最近悬停目标 */
+    scopeType?: "click" | "hover";
+    /** 多步序列中，相邻两步之间的最大间隔（毫秒），默认 `5000` */
+    timeout?: number;
+    /** 为 `true` 时，在 input / textarea / contentEditable 内也响应快捷键 */
+    enableInInput?: boolean;
+    /**
+     * 是否允许长按按键时重复触发回调，默认 `false`。
+     * 适用于如 `+`、`-`、方向键等需要连续操作的场景。
+     */
+    allowRepeat?: boolean;
+    /**
+     * 允许重复触发时的最小时间间隔（毫秒）。
+     * 由于操作系统的原生长按触发频率不可控且通常极高，利用该属性对重复事件进行节流。
+     */
+    repeatInterval?: number;
+}
+/**
+ * 全局快捷键管理器
+ *
+ * ⚠️ **注意**：本组件会在全局 `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"` 使用 */
+    private lastHoverDom?;
+    /** 当前仍按下的键（已 normalize），顺序与物理按下顺序一致 */
+    private downKeys;
+    /** 注册表：`bind` 时的原始 `key` 字符串 → 运行时绑定 */
+    private bindings;
+    /** 为 `true` 时在控制台输出 keydown / keyup 日志 */
+    private debug;
+    constructor(debug?: boolean);
+    /**
+     * 注册快捷键。
+     * @param key 配置字符串，如 `"control+a"` 或 `"g,i"`（两步序列）
+     * @param options 回调与其它选项
+     */
+    bind(key: string | string[], options: ShortcutOptions): void;
+    /** 移除指定 `key` 的绑定并清理其超时定时器 */
+    unbind(key: string): void;
+    /**
+     * 彻底销毁当前实例，清空所有快捷键绑定，并移除全局 window 事件监听器。
+     *
+     * ⚠️ **调用时机**：在单页应用（如 Vue/React 组件卸载）或不需要快捷键时**务必调用**。
+     */
+    destroy(): void;
+    private handleMouseOver;
+    private handleMouseDown;
+    /** 窗口失焦时清空按下状态，避免 `keyup` 未触发导致的状态残留 */
+    private clearKeys;
+    private handleKeyDown;
+    private handleKeyUp;
+    /**
+     * 遍历所有绑定：校验作用域与输入上下文后，用数组匹配当前步骤；
+     * 完全匹配则推进序列或触发回调，前缀匹配则等待，否则重置。
+     */
+    private checkBindings;
+    /** 启动多步序列超时；超时未按下一步则重置 `currentIndex` */
+    private startSequenceTimer;
+    private resetBinding;
+    private isValidScope;
+    /**
+     * 默认在可编辑控件内禁用快捷键，避免与浏览器/输入法默认行为冲突。
+     */
+    private isValidContext;
+    /**
+     * 将配置串与 `KeyboardEvent.key` 统一为小写别名，便于与 `event.key` 比较。
+     * 例如 `ctrl` → `control`，`cmd` → `meta`。
+     */
+    private normalizeKey;
+    /** 当前按下键与预期组合键在长度与顺序上完全一致 */
+    private isExactMatch;
+    /**
+     * 当前按下键是预期组合键的有序前缀（尚缺后续键）。
+     * 使用逐元素比较，避免字符串 `startsWith` 误匹配（如 `"S"` 匹配 `"Shift,a"`）。
+     */
+    private isPrefixMatch;
+}
+export {};

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

@@ -0,0 +1,88 @@
+interface _Utility_UndoRedoConfig<T> {
+    /** 存储上限；`0` 或负数表示无限制。超出时自动淘汰最早的记录。默认为 50 */
+    maxSize?: number;
+    /** 自定义克隆/结构共享函数。若不传，则默认直接引用赋值 */
+    clone?: (value: T) => T;
+    /** 初始状态快照 */
+    initialState?: T;
+}
+interface _Utility_UndoRedoRecord<T> {
+    /** 历史快照数据 */
+    state: T;
+    /** 记录产生的时间戳 */
+    timestamp: number;
+}
+/** 订阅者回调函数类型 */
+type _Utility_UndoRedoListener<T> = (current: Readonly<T> | undefined) => void;
+/**
+ * 通用历史记录状态机
+ */
+export declare class _Utility_UndoRedoHistory<T> {
+    private stack;
+    private _index;
+    private _maxSize;
+    private cloneFn;
+    private listeners;
+    constructor(config?: _Utility_UndoRedoConfig<T>);
+    /** 获取最大存储上限 */
+    get maxSize(): number;
+    /** 动态调整最大存储上限，超出时自动裁剪 */
+    set maxSize(value: number);
+    /** 当前所处的历史记录索引位置 */
+    get index(): number;
+    /** 历史栈中的总记录数 */
+    get length(): number;
+    /** 历史栈是否为空 */
+    get isEmpty(): boolean;
+    /** 当前游标处的只读状态快照；栈为空时返回 `undefined` */
+    get current(): Readonly<T> | undefined;
+    /** 是否可以执行撤销（Undo） */
+    get canUndo(): boolean;
+    /** 是否可以执行重做（Redo） */
+    get canRedo(): boolean;
+    /** 剩余可撤销的步数 */
+    get undoCount(): number;
+    /** 剩余可重做的步数 */
+    get redoCount(): number;
+    /**
+     * 记录一个新状态。
+     * 会自动裁剪掉当前索引之后的“未来（Redo）”分支，并处理容量超限。
+     */
+    push(state: T): void;
+    /**
+     * 仅更新当前位置的快照，不产生新的历史节点，不裁剪未来分支。
+     * 常用于高频连续变更的中间状态同步
+     */
+    replace(state: T): void;
+    /**
+     * 撤销一步
+     * @returns 是否撤销成功
+     */
+    undo(): boolean;
+    /**
+     * 重进一步
+     * @returns 是否重进成功
+     */
+    redo(): boolean;
+    /**
+     * 跳转到指定的历史索引位置
+     */
+    jump(index: number): boolean;
+    /**
+     * 清空所有历史记录并重置状态
+     */
+    clear(): void;
+    /**
+     * 支持多重事件监听。返回一个取消订阅的函数，便于在组件销毁时规避内存泄漏。
+     */
+    subscribe(listener: _Utility_UndoRedoListener<T>): () => void;
+    /**
+     * 返回整个历史栈的外部只读镜像，专门用于调试、分析或序列化暂存，防止内部数据被篡改。
+     */
+    snapshot(): readonly Readonly<_Utility_UndoRedoRecord<T>>[];
+    /** 内部超出容量时的核心裁剪逻辑 */
+    private trimOverflow;
+    /** 统一通知所有订阅者 */
+    private notify;
+}
+export {};

package/dist/Utility/index.d.ts

@@ -1,3 +1,4 @@
+export * from './Runtime';
 /**
  * 寻找空闲时机执行传入方法
  * @param callback  需执行的方法

package/dist/Valid/index.d.ts

@@ -71,7 +71,7 @@ export declare function _Valid_CheckConnectionWithXHR(url: string): Promise<unkn
  */
 export declare class _Valid_FileTypeChecker {
     private static cachedEntries;
-    constructor();
+    private constructor();
     /**
      * 检查给定URL的文件类型
      * @param {string} url - 文件的URL