nhanh-pure-function 4.4.0 → 4.6.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/Browser/index.d.ts

@@ -1,5 +1,5 @@
 import { PaperType, WindowTarget } from '../Constant';
-export * from './Runtime';
+export * from './modules';
 /**
  * 获取帧率
  * @param {(fps , frameTime)=>void} callback callback( 帧率 , 每帧时间 )

package/dist/Element/index.d.ts

@@ -1,5 +1,5 @@
 import { DragOption, LocalDragOptions, UiLibrary } from './type';
-export * from './Runtime';
+export * from './modules';
 /**
  * 滚动结束监听器
  * @param {(trigger: "vertical" | "horizontal") => void} callback

package/dist/Element/modules/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 → modules}/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

@@ -32,6 +32,19 @@ export declare function _Math_PointToLineDistance(point: [number, number], lineS
  * @returns [起点坐标[x,y], 终点坐标[x,y]]
  */
 export declare function _Math_GetArcPoints(x: number, y: number, radius: number, startAngle: number, endAngle: number, axisX?: number, axisY?: number): [[number, number], [number, number]];
+/**
+ * 计算两个经纬度坐标之间的直线距离（单位：米）。
+ *
+ * 先将经纬度通过 Mercator 投影转换为平面坐标（米），
+ * 再计算二维平面欧几里得距离，适用于短距离近似计算。
+ *
+ * @param lng1 第一个点的经度（度），范围 [-180, 180]
+ * @param lat1 第一个点的纬度（度），范围 [-85.05, 85.05]
+ * @param lng2 第二个点的经度（度），范围 [-180, 180]
+ * @param lat2 第二个点的纬度（度），范围 [-85.05, 85.05]
+ * @returns 两点间的距离（米）
+ */
+export declare function _Math_CalculateDistanceLngLat(lng1: number, lat1: number, lng2: number, lat2: number): number;
 /** 计算平面直角坐标系中两点的距离 */
 export declare function _Math_CalculateDistance2D(x1: number, y1: number, x2: number, y2: number): number;
 /** 获取两点的中点 */
@@ -55,12 +68,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 半轴之比
@@ -69,3 +88,77 @@ export declare function _Math_GetBezierCurveNodes(nodes: [number, number][], pro
  * @returns 椭圆上的点 [x, y]
  */
 export declare function _Math_GetEllipsePoints(aspectRatio: number, progress: number, normalizeToUnitSquare?: boolean): [number, number];
+/**
+ * 将数值钳制在指定区间内。
+ * @param value 输入值
+ * @param min 下限
+ * @param max 上限
+ * @returns 钳制后的值
+ */
+export declare function _Math_Clamp(value: number, min: number, max: number): number;
+/**
+ * 线性插值。
+ * @param a 起始值
+ * @param b 结束值
+ * @param t 插值参数，[0, 1]
+ * @returns 插值结果
+ */
+export declare function _Math_Lerp(a: number, b: number, t: number): number;
+/**
+ * 逆线性插值：计算 value 在 [a, b] 区间的位置比例。
+ * @param a 区间下限
+ * @param b 区间上限
+ * @param value 当前值
+ * @returns 比例 t，0 表示在 a，1 表示在 b
+ */
+export declare function _Math_InverseLerp(a: number, b: number, value: number): number;
+/**
+ * 将 value 从 [fromMin, fromMax] 区间映射到 [toMin, toMax] 区间。
+ * @param value 输入值
+ * @param fromMin 源区间下限
+ * @param fromMax 源区间上限
+ * @param toMin 目标区间下限
+ * @param toMax 目标区间上限
+ * @returns 映射后的值
+ */
+export declare function _Math_Remap(value: number, fromMin: number, fromMax: number, toMin: number, toMax: number): number;
+/**
+ * 角度转弧度。
+ * @param deg 角度（度）
+ * @returns 弧度
+ */
+export declare function _Math_DegToRad(deg: number): number;
+/**
+ * 弧度转角度。
+ * @param rad 弧度
+ * @returns 角度（度）
+ */
+export declare function _Math_RadToDeg(rad: number): number;
+/**
+ * 将角度归一化到指定范围。
+ * @param angle 输入角度（度）
+ * @param signed 为 true 时归一化到 [-180, 180)，默认 false 归一化到 [0, 360)
+ * @returns 归一化后的角度
+ */
+export declare function _Math_NormalizeAngle(angle: number, signed?: boolean): number;
+/**
+ * 判断点是否在矩形内（含边界）。
+ * @param px 点 X 坐标
+ * @param py 点 Y 坐标
+ * @param rx 矩形左上角 X
+ * @param ry 矩形左上角 Y
+ * @param rw 矩形宽度
+ * @param rh 矩形高度
+ * @returns true 表示点在矩形内
+ */
+export declare function _Math_IsPointInRect(px: number, py: number, rx: number, ry: number, rw: number, rh: number): boolean;
+/**
+ * 判断点是否在圆形内（含边界）。
+ * @param px 点 X 坐标
+ * @param py 点 Y 坐标
+ * @param cx 圆心 X
+ * @param cy 圆心 Y
+ * @param radius 圆半径
+ * @returns true 表示点在圆内
+ */
+export declare function _Math_IsPointInCircle(px: number, py: number, cx: number, cy: number, radius: number): boolean;

package/dist/Types/index.d.ts

@@ -37,3 +37,12 @@ export type _Type_DeepPartial<T> = {
 export type _Type_Mutable<T> = {
     -readonly [P in keyof T]: T[P];
 };
+/**
+ * 递归地将类型中的所有只读（readonly）属性转换为可写（writable）属性
+ * @template T - 要处理的基础类型
+ * @description 与TypeScript内置的Writable不同，DeepWritable会对嵌套对象进行递归处理，
+ *              使所有层级的属性都变为可写。适用于需要修改对象属性的场景，但需要确保对象不会被其他地方引用。
+ */
+export type _Type_DeepWritable<T> = {
+    -readonly [P in keyof T]: _Type_DeepWritable<T[P]>;
+};

package/dist/Utility/index.d.ts

@@ -1,4 +1,5 @@
-export * from './Runtime';
+import { _Type_DeepWritable } from '../Types';
+export * from './modules';
 /**
  * 寻找空闲时机执行传入方法
  * @param callback  需执行的方法
@@ -73,7 +74,7 @@ export declare function _Utility_RotateList<T>(list: T[]): T[][];
  * @param {any} val - 需要克隆的值
  * @returns {any} - 克隆后的值
  */
-export declare function _Utility_Clone<T>(val: T): T;
+export declare function _Utility_Clone<T>(val: T): _Type_DeepWritable<T>;
 /**
  * 函数装饰器：精准测量并记录目标函数的执行耗时（单位：毫秒）
  *
@@ -100,86 +101,3 @@ export declare function _Utility_TimeConsumption<T extends Function>(func: T, co
  * @returns 实际暂停的毫秒数
  */
 export declare function _Utility_Sleep(ms: number): number;
-/**
- * 颜色转换工具。
- * 支持输入：hex/rgb/hsl/hsv，统一解析后输出指定格式。
- */
-export declare class _Utility_ColorConverter {
-    private constructor();
-    private static readonly DEFAULT_ALPHA;
-    /**
-     * 数值钳制，确保在合法区间内。
-     */
-    private static clamp;
-    private static normalizeHue;
-    /**
-     * 根据色相分段与色度参数生成 RGB（0-255）。
-     */
-    private static chromaToRgb;
-    private static resolveAlpha;
-    private static toRoundedRgbString;
-    /**
-     * HSL 转 RGB。
-     * h: 0-360, s/l: 0-100
-     */
-    private static hslToRgb;
-    /**
-     * HSV 转 RGB。
-     * h: 0-360, s/v: 0-100
-     */
-    private static hsvToRgb;
-    /**
-     * 解析任意受支持的颜色格式并标准化为 RGBA。
-     */
-    private static parseColor;
-    /**
-     * 十进制颜色分量转两位十六进制字符串。
-     */
-    private static toHexPart;
-    /**
-     * RGB 转 HSL。
-     * 返回 h:0-360, s/l:0-100
-     */
-    private static rgbToHsl;
-    /**
-     * RGB 转 HSV。
-     * 返回 h:0-360, s/v:0-100
-     */
-    private static rgbToHsv;
-    /**
-     * 转换为 HEX（#RRGGBB）。
-     */
-    static toHex(color: string): string;
-    /**
-     * 转换为 HEXA（#RRGGBBAA）。
-     * alpha 不传时保留输入颜色中的透明度（默认 1）。
-     */
-    static toHexa(color: string, alpha?: number): string;
-    /**
-     * 转换为 RGB（rgb(r, g, b)）。
-     */
-    static toRgb(color: string): string;
-    /**
-     * 转换为 RGBA（rgba(r, g, b, a)）。
-     * alpha 不传时保留输入颜色中的透明度（默认 1）。
-     */
-    static toRgba(color: string, alpha?: number): string;
-    /**
-     * 转换为 HSL（hsl(h, s%, l%)）。
-     */
-    static toHsl(color: string): string;
-    /**
-     * 转换为 HSLA（hsla(h, s%, l%, a)）。
-     * alpha 不传时保留输入颜色中的透明度（默认 1）。
-     */
-    static toHsla(color: string, alpha?: number): string;
-    /**
-     * 转换为 HSV（hsv(h, s%, v%)）。
-     */
-    static toHsv(color: string): string;
-    /**
-     * 转换为 HSVA（hsva(h, s%, v%, a)）。
-     * alpha 不传时保留输入颜色中的透明度（默认 1）。
-     */
-    static toHsva(color: string, alpha?: number): string;
-}

package/dist/Utility/modules/colorConverter.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 颜色转换工具。
+ * 支持输入：hex/rgb/hsl/hsv，统一解析后输出指定格式。
+ */
+export declare class _Utility_ColorConverter {
+    private constructor();
+    private static readonly DEFAULT_ALPHA;
+    /**
+     * 数值钳制，确保在合法区间内。
+     */
+    private static clamp;
+    private static normalizeHue;
+    /**
+     * 根据色相分段与色度参数生成 RGB（0-255）。
+     */
+    private static chromaToRgb;
+    private static resolveAlpha;
+    private static toRoundedRgbString;
+    /**
+     * HSL 转 RGB。
+     * h: 0-360, s/l: 0-100
+     */
+    private static hslToRgb;
+    /**
+     * HSV 转 RGB。
+     * h: 0-360, s/v: 0-100
+     */
+    private static hsvToRgb;
+    /**
+     * 解析任意受支持的颜色格式并标准化为 RGBA。
+     */
+    private static parseColor;
+    /**
+     * 十进制颜色分量转两位十六进制字符串。
+     */
+    private static toHexPart;
+    /**
+     * RGB 转 HSL。
+     * 返回 h:0-360, s/l:0-100
+     */
+    private static rgbToHsl;
+    /**
+     * RGB 转 HSV。
+     * 返回 h:0-360, s/v:0-100
+     */
+    private static rgbToHsv;
+    /**
+     * 转换为 HEX（#RRGGBB）。
+     */
+    static toHex(color: string): string;
+    /**
+     * 转换为 HEXA（#RRGGBBAA）。
+     * alpha 不传时保留输入颜色中的透明度（默认 1）。
+     */
+    static toHexa(color: string, alpha?: number): string;
+    /**
+     * 转换为 RGB（rgb(r, g, b)）。
+     */
+    static toRgb(color: string): string;
+    /**
+     * 转换为 RGBA（rgba(r, g, b, a)）。
+     * alpha 不传时保留输入颜色中的透明度（默认 1）。
+     */
+    static toRgba(color: string, alpha?: number): string;
+    /**
+     * 转换为 HSL（hsl(h, s%, l%)）。
+     */
+    static toHsl(color: string): string;
+    /**
+     * 转换为 HSLA（hsla(h, s%, l%, a)）。
+     * alpha 不传时保留输入颜色中的透明度（默认 1）。
+     */
+    static toHsla(color: string, alpha?: number): string;
+    /**
+     * 转换为 HSV（hsv(h, s%, v%)）。
+     */
+    static toHsv(color: string): string;
+    /**
+     * 转换为 HSVA（hsva(h, s%, v%, a)）。
+     * alpha 不传时保留输入颜色中的透明度（默认 1）。
+     */
+    static toHsva(color: string, alpha?: number): string;
+    /**
+     * 返回解析后的 RGBA 对象。
+     * @param color 任意受支持的颜色字符串（hex/rgb/hsl/hsv）
+     * @returns {{ r: number; g: number; b: number; a: number }} RGBA 分量，r/g/b 范围 0-255，a 范围 0-1
+     */
+    static toRgbaObject(color: string): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    /**
+     * 判断两个颜色是否在允许的色差范围内（基于 RGB 欧几里得距离）。
+     * @param colorA 第一个颜色字符串
+     * @param colorB 第二个颜色字符串
+     * @param threshold 允许的最大色差值，范围约 0（完全相同）到 442（黑白最大距离），含 alpha 时上限约 510
+     * @param includeAlpha 是否将 alpha 差值纳入计算，默认 true；启用时 alpha 差值会缩放到 0-255 参与距离
+     * @returns true 表示在允许色差内
+     */
+    static isWithinColorDifference(colorA: string, colorB: string, threshold: number, includeAlpha?: boolean): boolean;
+    /**
+     * 混合两个颜色（在 RGBA 空间线性插值）。
+     * @param colorA 起始颜色
+     * @param colorB 终点颜色
+     * @param ratio 混合比例，0 = 完全 A，1 = 完全 B
+     * @returns 混合后的 rgba 字符串
+     */
+    static mix(colorA: string, colorB: string, ratio: number): string;
+    /**
+     * 转换为灰度（基于 ITU-R BT.709 权重）。
+     * @param color 任意受支持的颜色字符串
+     * @returns 灰度 rgb 字符串
+     */
+    static toGrayscale(color: string): string;
+    /**
+     * 计算 WCAG 2.0 相对亮度。
+     * @param color 任意受支持的颜色字符串
+     * @returns 相对亮度值，范围 [0, 1]
+     */
+    static luminance(color: string): number;
+    /**
+     * 计算 WCAG 2.0 对比度。
+     * @param colorA 第一个颜色
+     * @param colorB 第二个颜色
+     * @returns 对比度值，范围 [1, 21]
+     */
+    static contrastRatio(colorA: string, colorB: string): number;
+    /**
+     * 设置透明度并返回 rgba 字符串。
+     * @param color 任意受支持的颜色字符串
+     * @param alpha 目标透明度，范围 [0, 1]
+     * @returns rgba 字符串
+     */
+    static withAlpha(color: string, alpha: number): string;
+}

package/dist/Utility/{Runtime → modules}/index.d.ts

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

package/dist/Utility/{Runtime → modules}/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;