ice-render 1.0.3 → 1.0.5

package/dist/types/event/EventBus.d.mts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import ICEEventTarget from './ICEEventTarget.mjs';
+/**
+ * @class EventBus
+ * @singleton
+ *
+ * EventBus 事件总线。
+ *
+ * - canvas 标签内部没有事件机制，ICE 借助于 EventBus 把原生 DOM 事件转发到 canvas 内部(mouse/keyboard/touch)，在转发过程中可能会把原生 DOM 事件转换成 ICEEvent 。
+ * - EventBus 是 ICEEventTarget 的实现类。
+ * - EventBus 是全局单例，同一个 ICE 实例上只能有一个事件总线的实例。
+ * - ICE 内部几乎所有机制都依赖事件总线来实现。
+ * - requestAnimationFrame 会利用事件总线触发 FRAME 事件。
+ *
+ * @see ICEEventTaregt
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class EventBus extends ICEEventTarget {
+    constructor(props?: any);
+}
+export default EventBus;

package/dist/types/event/EventBus.d.ts

@@ -1,27 +1,27 @@
-/**
- * Copyright (c) 2022 大漠穷秋.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-import ICEEventTarget from './ICEEventTarget';
-/**
- * @class EventBus
- * @singleton
- *
- * EventBus 事件总线。
- *
- * - canvas 标签内部没有事件机制，ICE 借助于 EventBus 把原生 DOM 事件转发到 canvas 内部(mouse/keyboard/touch)，在转发过程中可能会把原生 DOM 事件转换成 ICEEvent 。
- * - EventBus 是 ICEEventTarget 的实现类。
- * - EventBus 是全局单例，同一个 ICE 实例上只能有一个事件总线的实例。
- * - ICE 内部几乎所有机制都依赖事件总线来实现。
- * - requestAnimationFrame 会利用事件总线触发 FRAME 事件。
- *
- * @see ICEEventTaregt
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-declare class EventBus extends ICEEventTarget {
-    constructor(props?: any);
-}
-export default EventBus;
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+import ICEEventTarget from './ICEEventTarget';
+/**
+ * @class EventBus
+ * @singleton
+ *
+ * EventBus 事件总线。
+ *
+ * - canvas 标签内部没有事件机制，ICE 借助于 EventBus 把原生 DOM 事件转发到 canvas 内部(mouse/keyboard/touch)，在转发过程中可能会把原生 DOM 事件转换成 ICEEvent 。
+ * - EventBus 是 ICEEventTarget 的实现类。
+ * - EventBus 是全局单例，同一个 ICE 实例上只能有一个事件总线的实例。
+ * - ICE 内部几乎所有机制都依赖事件总线来实现。
+ * - requestAnimationFrame 会利用事件总线触发 FRAME 事件。
+ *
+ * @see ICEEventTaregt
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class EventBus extends ICEEventTarget {
+    constructor(props?: any);
+}
+export default EventBus;

package/dist/types/event/ICEEvent.d.mts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * @class ICEEvent
+ *
+ * - 在 ICE 中，所有事件都会被转化成 ICEEvent 进行处理。
+ * - ICEEvent 用来模拟 W3C 定义的 Event 接口，ICE 自定义的事件也使用此实现，事件对象上能获取到的属性不同。
+ * - 从原始 DOM 事件转发出来的 ICEEvent 实例包含 Event 接口上所定义的所有属性，ICE 内部代码创建的 ICEEvent 实例上只包含很少的自定义属性。
+ * - 如果事件是从原始 DOM 事件包装而来，那么ICEEvent 实例的 originalEvent 属性是原始 DOM 事件对象，否则 originalEvent 属性为 null。
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Event
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEEvent implements Event {
+    originalEvent: any;
+    param: any;
+    constructor(evt?: any, data?: any);
+    bubbles: boolean;
+    cancelBubble: boolean;
+    cancelable: boolean;
+    composed: boolean;
+    currentTarget: EventTarget;
+    defaultPrevented: boolean;
+    eventPhase: number;
+    isTrusted: boolean;
+    returnValue: boolean;
+    srcElement: EventTarget;
+    target: EventTarget;
+    timeStamp: number;
+    type: string;
+    composedPath(): EventTarget[];
+    initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
+    preventDefault(): void;
+    stopImmediatePropagation(): void;
+    stopPropagation(): void;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+    readonly CAPTURING_PHASE: 1;
+    readonly NONE: 0;
+}
+export default ICEEvent;

package/dist/types/event/ICEEvent.d.ts

@@ -1,46 +1,46 @@
-/**
- * Copyright (c) 2022 大漠穷秋.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-/**
- * @class ICEEvent
- *
- * - 在 ICE 中，所有事件都会被转化成 ICEEvent 进行处理。
- * - ICEEvent 用来模拟 W3C 定义的 Event 接口，ICE 自定义的事件也使用此实现，事件对象上能获取到的属性不同。
- * - 从原始 DOM 事件转发出来的 ICEEvent 实例包含 Event 接口上所定义的所有属性，ICE 内部代码创建的 ICEEvent 实例上只包含很少的自定义属性。
- * - 如果事件是从原始 DOM 事件包装而来，那么ICEEvent 实例的 originalEvent 属性是原始 DOM 事件对象，否则 originalEvent 属性为 null。
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/Event
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-declare class ICEEvent implements Event {
-    originalEvent: any;
-    param: any;
-    constructor(evt?: any, data?: any);
-    bubbles: boolean;
-    cancelBubble: boolean;
-    cancelable: boolean;
-    composed: boolean;
-    currentTarget: EventTarget;
-    defaultPrevented: boolean;
-    eventPhase: number;
-    isTrusted: boolean;
-    returnValue: boolean;
-    srcElement: EventTarget;
-    target: EventTarget;
-    timeStamp: number;
-    type: string;
-    composedPath(): EventTarget[];
-    initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
-    preventDefault(): void;
-    stopImmediatePropagation(): void;
-    stopPropagation(): void;
-    AT_TARGET: number;
-    BUBBLING_PHASE: number;
-    CAPTURING_PHASE: number;
-    NONE: number;
-}
-export default ICEEvent;
+/**
+ * Copyright (c) 2022 大漠穷秋.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * @class ICEEvent
+ *
+ * - 在 ICE 中，所有事件都会被转化成 ICEEvent 进行处理。
+ * - ICEEvent 用来模拟 W3C 定义的 Event 接口，ICE 自定义的事件也使用此实现，事件对象上能获取到的属性不同。
+ * - 从原始 DOM 事件转发出来的 ICEEvent 实例包含 Event 接口上所定义的所有属性，ICE 内部代码创建的 ICEEvent 实例上只包含很少的自定义属性。
+ * - 如果事件是从原始 DOM 事件包装而来，那么ICEEvent 实例的 originalEvent 属性是原始 DOM 事件对象，否则 originalEvent 属性为 null。
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Event
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEEvent implements Event {
+    originalEvent: any;
+    param: any;
+    constructor(evt?: any, data?: any);
+    bubbles: boolean;
+    cancelBubble: boolean;
+    cancelable: boolean;
+    composed: boolean;
+    currentTarget: EventTarget;
+    defaultPrevented: boolean;
+    eventPhase: number;
+    isTrusted: boolean;
+    returnValue: boolean;
+    srcElement: EventTarget;
+    target: EventTarget;
+    timeStamp: number;
+    type: string;
+    composedPath(): EventTarget[];
+    initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
+    preventDefault(): void;
+    stopImmediatePropagation(): void;
+    stopPropagation(): void;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+    readonly CAPTURING_PHASE: 1;
+    readonly NONE: 0;
+}
+export default ICEEvent;

package/dist/types/event/ICEEventTarget.d.mts

@@ -0,0 +1,106 @@
+/**
+ * @class ICEEventTarget
+ *
+ * - canvas 标签内部没有事件机制，模仿 W3C 定义的 EventTaregt 接口，为 Canvas 内部的组件添加事件机制。
+ * - ICE 内部的大部分组件都是 ICEEventTarget 的子类。
+ * - 部分 API 名称模仿 jQuery ，方便使用者调用。
+ *
+ * TODO:需要完整模拟 W3C 和 jQuery 提供的事件接口，在 API 名称和调用逻辑上保持完全一致。
+ *
+ * listeners 的结构：
+ * {
+ *    "click":[
+ *        {
+ *          callback:fn1,
+ *          scope:window
+ *        },
+ *        {
+ *          callback:fn2,
+ *          scope:component-1
+ *        }
+ *     ],
+ *    "mousemove":[
+ *        {
+ *          callback:fn1,
+ *          scope:window
+ *        },
+ *        {
+ *          callback:fn2,
+ *          scope:component-1
+ *        }
+ *     ]
+ * }
+ *
+ * @abstract
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
+ */
+declare abstract class ICEEventTarget {
+    protected listeners: any;
+    protected suspendedEventNames: any;
+    constructor();
+    /**
+     * @method on
+     * 添加事件监听
+     * @param eventName
+     * @param fn
+     * @param scope
+     */
+    on(eventName: string, fn: (...args: any[]) => any, scope?: any): void;
+    /**
+     * @method off
+     * 删除事件监听
+     * @param eventName
+     * @param fn
+     * @param scope
+     * @returns
+     */
+    off(eventName: string, fn: (...args: any[]) => any, scope?: any): void;
+    /**
+     * @method dispatchEvent
+     *
+     * 触发事件。
+     *
+     * 所有事件都会被转换成 ICEEvent 实例。
+     *
+     * @param eventName
+     * @param originalEvent
+     * @param param
+     * @returns
+     */
+    trigger(eventName: string, originalEvent?: any, param?: {}): boolean;
+    /**
+     * @method once
+     * 一次性事件，触发一次就自动删除自己。
+     * @param eventName
+     * @param fn
+     */
+    once(eventName: string, fn: (...args: any[]) => any, scope?: any): void;
+    /**
+     * @method suspend
+     * 挂起事件。
+     * @param eventName
+     */
+    suspend(eventName: string): void;
+    /**
+     * @method resume
+     * 恢复事件。
+     * @param eventName
+     */
+    resume(eventName: string): void;
+    /**
+     * @method purgeEvents
+     * 清除所有事件。
+     */
+    purgeEvents(): void;
+    /**
+     * @method hasListener
+     * 查询是否带有某个事件监听器。
+     * @param eventName
+     * @param fn
+     * @param scope
+     * @returns
+     */
+    hasListener(eventName: string, fn: (...args: any[]) => any, scope?: any): boolean;
+}
+export default ICEEventTarget;

package/dist/types/event/ICEEventTarget.d.ts

@@ -1,106 +1,106 @@
-/**
- * @class ICEEventTarget
- *
- * - canvas 标签内部没有事件机制，模仿 W3C 定义的 EventTaregt 接口，为 Canvas 内部的组件添加事件机制。
- * - ICE 内部的大部分组件都是 ICEEventTarget 的子类。
- * - 部分 API 名称模仿 jQuery ，方便使用者调用。
- *
- * TODO:需要完整模拟 W3C 和 jQuery 提供的事件接口，在 API 名称和调用逻辑上保持完全一致。
- *
- * listeners 的结构：
- * {
- *    "click":[
- *        {
- *          callback:fn1,
- *          scope:window
- *        },
- *        {
- *          callback:fn2,
- *          scope:component-1
- *        }
- *     ],
- *    "mousemove":[
- *        {
- *          callback:fn1,
- *          scope:window
- *        },
- *        {
- *          callback:fn2,
- *          scope:component-1
- *        }
- *     ]
- * }
- *
- * @abstract
- * @author 大漠穷秋<damoqiongqiu@126.com>
- * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
- */
-declare abstract class ICEEventTarget {
-    protected listeners: any;
-    protected suspendedEventNames: any;
-    constructor();
-    /**
-     * @method on
-     * 添加事件监听
-     * @param eventName
-     * @param fn
-     * @param scope
-     */
-    on(eventName: string, fn: Function, scope?: any): void;
-    /**
-     * @method off
-     * 删除事件监听
-     * @param eventName
-     * @param fn
-     * @param scope
-     * @returns
-     */
-    off(eventName: string, fn: Function, scope?: any): void;
-    /**
-     * @method once
-     * 一次性事件，触发一次就自动删除自己。
-     * @param eventName
-     * @param fn
-     */
-    once(eventName: string, fn: Function, scope?: any): void;
-    /**
-     * @method dispatchEvent
-     *
-     * 触发事件。
-     *
-     * 所有事件都会被转换成 ICEEvent 实例。
-     *
-     * @param eventName
-     * @param originalEvent
-     * @param param
-     * @returns
-     */
-    trigger(eventName: string, originalEvent?: any, param?: {}): boolean;
-    /**
-     * @method suspend
-     * 挂起事件。
-     * @param eventName
-     */
-    suspend(eventName: string): void;
-    /**
-     * @method resume
-     * 恢复事件。
-     * @param eventName
-     */
-    resume(eventName: string): void;
-    /**
-     * @method purgeEvents
-     * 清除所有事件。
-     */
-    purgeEvents(): void;
-    /**
-     * @method hasListener
-     * 查询是否带有某个事件监听器。
-     * @param eventName
-     * @param fn
-     * @param scope
-     * @returns
-     */
-    hasListener(eventName: string, fn: Function, scope?: any): boolean;
-}
-export default ICEEventTarget;
+/**
+ * @class ICEEventTarget
+ *
+ * - canvas 标签内部没有事件机制，模仿 W3C 定义的 EventTaregt 接口，为 Canvas 内部的组件添加事件机制。
+ * - ICE 内部的大部分组件都是 ICEEventTarget 的子类。
+ * - 部分 API 名称模仿 jQuery ，方便使用者调用。
+ *
+ * TODO:需要完整模拟 W3C 和 jQuery 提供的事件接口，在 API 名称和调用逻辑上保持完全一致。
+ *
+ * listeners 的结构：
+ * {
+ *    "click":[
+ *        {
+ *          callback:fn1,
+ *          scope:window
+ *        },
+ *        {
+ *          callback:fn2,
+ *          scope:component-1
+ *        }
+ *     ],
+ *    "mousemove":[
+ *        {
+ *          callback:fn1,
+ *          scope:window
+ *        },
+ *        {
+ *          callback:fn2,
+ *          scope:component-1
+ *        }
+ *     ]
+ * }
+ *
+ * @abstract
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
+ */
+declare abstract class ICEEventTarget {
+    protected listeners: any;
+    protected suspendedEventNames: any;
+    constructor();
+    /**
+     * @method on
+     * 添加事件监听
+     * @param eventName
+     * @param fn
+     * @param scope
+     */
+    on(eventName: string, fn: (...args: any[]) => any, scope?: any): void;
+    /**
+     * @method off
+     * 删除事件监听
+     * @param eventName
+     * @param fn
+     * @param scope
+     * @returns
+     */
+    off(eventName: string, fn: (...args: any[]) => any, scope?: any): void;
+    /**
+     * @method dispatchEvent
+     *
+     * 触发事件。
+     *
+     * 所有事件都会被转换成 ICEEvent 实例。
+     *
+     * @param eventName
+     * @param originalEvent
+     * @param param
+     * @returns
+     */
+    trigger(eventName: string, originalEvent?: any, param?: {}): boolean;
+    /**
+     * @method once
+     * 一次性事件，触发一次就自动删除自己。
+     * @param eventName
+     * @param fn
+     */
+    once(eventName: string, fn: (...args: any[]) => any, scope?: any): void;
+    /**
+     * @method suspend
+     * 挂起事件。
+     * @param eventName
+     */
+    suspend(eventName: string): void;
+    /**
+     * @method resume
+     * 恢复事件。
+     * @param eventName
+     */
+    resume(eventName: string): void;
+    /**
+     * @method purgeEvents
+     * 清除所有事件。
+     */
+    purgeEvents(): void;
+    /**
+     * @method hasListener
+     * 查询是否带有某个事件监听器。
+     * @param eventName
+     * @param fn
+     * @param scope
+     * @returns
+     */
+    hasListener(eventName: string, fn: (...args: any[]) => any, scope?: any): boolean;
+}
+export default ICEEventTarget;

package/dist/types/event/input-normalize.d.mts

@@ -0,0 +1,75 @@
+/**
+ * 输入归一化：把 mouse / pointer / touch 三类原生输入统一成引擎内部消费的字段。
+ *
+ * 背景：
+ * - 组件、拖拽、变换手柄、对齐吸附、命中检测都只读 `evt.offsetX/offsetY/movementX/movementY`。
+ * - 触摸事件（TouchEvent）上没有 offsetX/offsetY/movementX，PointerEvent 上 movementX 在部分
+ *   运行时也不可靠；并且全局监听下 `offsetX` 是相对「事件目标元素」而非 canvas。
+ *
+ * 因此：在事件边界（DOMEventDispatcher）统一归一化一次，上层代码零改动即可同时支持
+ * 鼠标 / 触控笔 / 触摸；坐标一律由 `clientX - canvasRect.left` 得到，滚动/缩放后仍正确。
+ *
+ * 本模块只含纯函数，不依赖 DOM 与引擎实例，便于 jest 直接单测。
+ */
+/** 归一化后的输入点（坐标单位：canvas 逻辑像素，尚未扣除视口）。 */
+export interface NormalizedInput {
+    /** canvas 内 x（= clientX - rect.left） */
+    x: number;
+    /** canvas 内 y（= clientY - rect.top） */
+    y: number;
+    clientX: number;
+    clientY: number;
+    /** 屏幕像素位移；原生 movementX/Y 优先，缺失时用「与上一次坐标的差」 */
+    movementX: number;
+    movementY: number;
+    pointerType: string;
+    pointerId: number;
+    button: number;
+    buttons: number;
+    isPrimary: boolean;
+    isTouch: boolean;
+    /** 修饰键：变换手柄靠它做「Shift 等比 / 角度吸附」这类约束，必须显式透传 */
+    shiftKey: boolean;
+    ctrlKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+}
+export interface RectLike {
+    left: number;
+    top: number;
+}
+/** 是否为 touch* 事件（TouchEvent 系）。 */
+export declare function isTouchEvent(evt: any): boolean;
+/**
+ * 从任意原生事件解出「屏幕坐标点」。
+ * - touch*：取 touches[0]，touchend 时 touches 为空则回退 changedTouches[0]
+ * - pointer/mouse：直接用 clientX/clientY
+ * - 键盘等无坐标事件：返回 null
+ */
+export declare function resolveClientPoint(evt: any): {
+    clientX: number;
+    clientY: number;
+} | null;
+/**
+ * 归一化一次输入事件。
+ *
+ * @param evt  原生事件（mouse / pointer / touch）
+ * @param rect canvas 的 getBoundingClientRect()（缺失时按 (0,0) 处理）
+ * @param prev 上一次归一化结果，用于在缺少原生 movement 时补算位移
+ * @returns 归一化结果；无坐标的事件（键盘等）返回 null
+ */
+export declare function normalizeInput(evt: any, rect: RectLike | null, prev?: NormalizedInput | null): NormalizedInput | null;
+/**
+ * 把归一化结果写回事件对象（ICEEvent 是普通对象，可直接写）。
+ *
+ * - `offsetX/offsetY` 沿用旧字段名，值改为「canvas 内坐标」，修掉全局监听下
+ *   相对子元素、以及滚动后 rect 过期导致的命中偏移。
+ * - `movementX/movementY` 统一为屏幕像素位移，触摸拖拽因此可用。
+ */
+export declare function applyNormalizedInput(target: any, input: NormalizedInput): void;
+/**
+ * 原生事件名 → 组件层沿用的「鼠标语义」事件名。
+ * pointer/touch 通道要映射成 mouse 名，既有组件与控制面板才能零改动复用。
+ * 返回 null 表示无需映射（click/dblclick/contextmenu/wheel/keyboard 等本身即语义名）。
+ */
+export declare function toLegacyMouseName(nativeType: string): string | null;