nhanh-pure-function 4.3.0 → 4.4.0

package/dist/Math/index.d.ts

@@ -61,3 +61,11 @@ export declare const _Math_Degree: Math;
  * @returns 曲线上的点
  */
 export declare function _Math_GetBezierCurveNodes(nodes: [number, number][], progress: 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,88 @@
+/**
+ * 全局快捷键管理：支持组合键、多步序列、作用域与输入框上下文过滤。
+ *
+ * @example
+ * ```ts
+ * const shortcuts = new _Utility_ShortcutManager();
+ * shortcuts.bind("control+s,control+shift+s", {
+ *   callback: (e) => { e.preventDefault(); save(); },
+ *   sequenceDelimiter: ",",
+ *   chordDelimiter: "+",
+ * });
+ * ```
+ */
+/** `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;
+}
+/**
+ * 在 `window` 上监听键盘与鼠标事件，按配置触发快捷键回调。
+ */
+export declare class _Utility_ShortcutManager {
+    /** 最近一次 `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;
+    /** 移除所有监听、清空状态，实例不可再使用 */
+    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