ice-render 1.0.3 → 1.0.5

package/dist/types/graphic/ICEDotPath.d.mts

@@ -0,0 +1,99 @@
+import ICEPath from './ICEPath.mjs';
+/**
+ * @class ICEDotPath
+ *
+ * 基于一系列点进行绘制的路径。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default abstract class ICEDotPath extends ICEPath {
+    /**
+     * @cfg
+     * {
+     *   dots: [],       //点状路径的点集
+     *   closePath:true, //是否闭合
+     * }
+     *
+     * @param props
+     */
+    constructor(props: any);
+    /**
+     * @overwrite
+     * @method calcComponentParams
+     * - 计算组件最原始的宽高和位置，此时没有经过任何变换，也没有移动坐标原点。
+     * - 在计算组件的原始尺寸时还没有确定原点坐标，所以只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
+     * - 此方法不能依赖原点位置和 transform 矩阵。
+     * - 此方法会在 render() 中调用，所以不需要在构造函数中调用。
+     * - 此方法中不能使用 setState() ，如果需要修改状态，直接赋值，如：this.state.width = 100;
+     * - 子类可以覆盖此方法，实现自己的计算逻辑。
+     * @returns
+     */
+    protected calcComponentParams(): {
+        width: any;
+        height: any;
+    };
+    /**
+     * 精确命中判定：点是否位于点集构成的多边形内部（射线法）。
+     * dots 在 calcLocalOrigin() 之后是「以 origin 为原点」的本地坐标，与 containsLocalPoint 的参数空间一致。
+     * @overwrite
+     */
+    protected containsLocalPoint(localX: number, localY: number): boolean;
+    /**
+     * 点状路径在重新计算本地原点坐标之后，需要移动内部所有点的位置。
+     *
+     * 关键：这里**只补「目标平移量 − 已应用平移量」的差额**。
+     * 旧实现每次都无条件平移 -origin，导致每 compose 一次 dots 就再偏移一个原点
+     * （实测连续三次 compose，dots 依次偏移 1/2/3 个原点），因此调用方必须严格保证
+     * 「compose 之前先重算 dots（calcDots）」——这正是局部重绘 / 包围盒刷新等路径
+     * 必须显式配对调用 `calcComponentParams()` 的原因，也是「跳过重量测」优化无法落地的原因。
+     * 记录已应用量之后，重复 compose 变成幂等操作（差额为 0）。
+     *
+     * @overwrite
+     * @returns
+     */
+    protected calcLocalOrigin(): any;
+    /**
+     * @returns
+     */
+    protected createPathObject(): any;
+    /**
+     * dots 上已应用的平移量（当前 dots 相对「绝对本地坐标」的偏移），供 calcLocalOrigin() 做幂等补偿。
+     * 见 calcLocalOrigin() 的说明。
+     */
+    protected __dotsShiftX: number;
+    protected __dotsShiftY: number;
+    /**
+     * dots 重建的**唯一入口**：先把「已应用平移量」归零（__calcDots() 产出的是**绝对**本地坐标），
+     * 再交给子类实现。
+     *
+     * 子类请覆盖 `__calcDots()`，**不要**覆盖本方法——否则幂等补偿会失效。
+     *
+     * 计算路径上的关键点：
+     * - 默认的坐标原点是 (0,0) 位置。
+     * - 这些点没有经过 transform 矩阵变换。
+     * - this.calcComponentParams() 会依赖此方法来计算位置和尺寸，此时还没有确定原点坐标，所以 __calcDots() 内部不能依赖原点坐标，只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
+     * @returns
+     */
+    protected calcDots(): any;
+    /**
+     * 子类实现：按**绝对**本地坐标（未减去原点）填充 `state.dots`。
+     * @returns
+     */
+    protected __calcDots(): any;
+    /**
+     * 确保 dots 已计算：反序列化时 dots 属缓存值不会被序列化，反序列化后 dots 为空，
+     * 在 render 之前若访问 dots（如 getMinBoundingBox → calc4VertexPoints）会取到空数组导致报错。
+     * 这里在 dots 缺失时惰性触发 calcDots 补齐。
+     */
+    protected ensureDots(): void;
+    /**
+     *
+     * 计算4个顶点：
+     * - 相对于组件本地的坐标系，原点位于左上角，没有经过矩阵变换。
+     * - 返回值用于计算组件的原始 width/height 。
+     *
+     * @returns
+     */
+    protected calc4VertexPoints(): any[][];
+    protected getTransformedDots(): any[];
+}

package/dist/types/graphic/ICEDotPath.d.ts

@@ -1,63 +1,99 @@
-import ICEPath from './ICEPath';
-/**
- * @class ICEDotPath
- *
- * 基于一系列点进行绘制的路径。
- *
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-export default abstract class ICEDotPath extends ICEPath {
-    /**
-     * @cfg
-     * {
-     *   dots: [],       //点状路径的点集
-     *   closePath:true, //是否闭合
-     * }
-     *
-     * @param props
-     */
-    constructor(props: any);
-    /**
-     * @overwrite
-     * @method calcComponentParams
-     * - 计算组件最原始的宽高和位置，此时没有经过任何变换，也没有移动坐标原点。
-     * - 在计算组件的原始尺寸时还没有确定原点坐标，所以只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
-     * - 此方法不能依赖原点位置和 transform 矩阵。
-     * - 此方法会在 render() 中调用，所以不需要在构造函数中调用。
-     * - 此方法中不能使用 setState() ，如果需要修改状态，直接赋值，如：this.state.width = 100;
-     * - 子类可以覆盖此方法，实现自己的计算逻辑。
-     * @returns
-     */
-    protected calcComponentParams(): {
-        width: any;
-        height: any;
-    };
-    /**
-     * 点状路径在重新计算本地原点坐标之后，需要移动内部所有点的位置。
-     * @overwrite
-     * @returns
-     */
-    protected calcLocalOrigin(): number[];
-    /**
-     * @returns
-     */
-    protected createPathObject(): Path2D;
-    /**
-     * 计算路径上的关键点:
-     * - 默认的坐标原点是 (0,0) 位置。
-     * - 这些点没有经过 transform 矩阵变换。
-     * - this.calcComponentParams() 会依赖此方法来计算位置和尺寸，此时还没有确定原点坐标，所以 calcDots() 方法内部不能依赖原点坐标，只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
-     * @returns
-     */
-    protected calcDots(): any;
-    /**
-     *
-     * 计算4个顶点：
-     * - 相对于组件本地的坐标系，原点位于左上角，没有经过矩阵变换。
-     * - 返回值用于计算组件的原始 width/height 。
-     *
-     * @returns
-     */
-    protected calc4VertexPoints(): any[][];
-    protected getTransformedDots(): any[];
-}
+import ICEPath from './ICEPath';
+/**
+ * @class ICEDotPath
+ *
+ * 基于一系列点进行绘制的路径。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default abstract class ICEDotPath extends ICEPath {
+    /**
+     * @cfg
+     * {
+     *   dots: [],       //点状路径的点集
+     *   closePath:true, //是否闭合
+     * }
+     *
+     * @param props
+     */
+    constructor(props: any);
+    /**
+     * @overwrite
+     * @method calcComponentParams
+     * - 计算组件最原始的宽高和位置，此时没有经过任何变换，也没有移动坐标原点。
+     * - 在计算组件的原始尺寸时还没有确定原点坐标，所以只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
+     * - 此方法不能依赖原点位置和 transform 矩阵。
+     * - 此方法会在 render() 中调用，所以不需要在构造函数中调用。
+     * - 此方法中不能使用 setState() ，如果需要修改状态，直接赋值，如：this.state.width = 100;
+     * - 子类可以覆盖此方法，实现自己的计算逻辑。
+     * @returns
+     */
+    protected calcComponentParams(): {
+        width: any;
+        height: any;
+    };
+    /**
+     * 精确命中判定：点是否位于点集构成的多边形内部（射线法）。
+     * dots 在 calcLocalOrigin() 之后是「以 origin 为原点」的本地坐标，与 containsLocalPoint 的参数空间一致。
+     * @overwrite
+     */
+    protected containsLocalPoint(localX: number, localY: number): boolean;
+    /**
+     * 点状路径在重新计算本地原点坐标之后，需要移动内部所有点的位置。
+     *
+     * 关键：这里**只补「目标平移量 − 已应用平移量」的差额**。
+     * 旧实现每次都无条件平移 -origin，导致每 compose 一次 dots 就再偏移一个原点
+     * （实测连续三次 compose，dots 依次偏移 1/2/3 个原点），因此调用方必须严格保证
+     * 「compose 之前先重算 dots（calcDots）」——这正是局部重绘 / 包围盒刷新等路径
+     * 必须显式配对调用 `calcComponentParams()` 的原因，也是「跳过重量测」优化无法落地的原因。
+     * 记录已应用量之后，重复 compose 变成幂等操作（差额为 0）。
+     *
+     * @overwrite
+     * @returns
+     */
+    protected calcLocalOrigin(): any;
+    /**
+     * @returns
+     */
+    protected createPathObject(): any;
+    /**
+     * dots 上已应用的平移量（当前 dots 相对「绝对本地坐标」的偏移），供 calcLocalOrigin() 做幂等补偿。
+     * 见 calcLocalOrigin() 的说明。
+     */
+    protected __dotsShiftX: number;
+    protected __dotsShiftY: number;
+    /**
+     * dots 重建的**唯一入口**：先把「已应用平移量」归零（__calcDots() 产出的是**绝对**本地坐标），
+     * 再交给子类实现。
+     *
+     * 子类请覆盖 `__calcDots()`，**不要**覆盖本方法——否则幂等补偿会失效。
+     *
+     * 计算路径上的关键点：
+     * - 默认的坐标原点是 (0,0) 位置。
+     * - 这些点没有经过 transform 矩阵变换。
+     * - this.calcComponentParams() 会依赖此方法来计算位置和尺寸，此时还没有确定原点坐标，所以 __calcDots() 内部不能依赖原点坐标，只能基于组件本地坐标系的左上角 (0,0) 点进行计算。
+     * @returns
+     */
+    protected calcDots(): any;
+    /**
+     * 子类实现：按**绝对**本地坐标（未减去原点）填充 `state.dots`。
+     * @returns
+     */
+    protected __calcDots(): any;
+    /**
+     * 确保 dots 已计算：反序列化时 dots 属缓存值不会被序列化，反序列化后 dots 为空，
+     * 在 render 之前若访问 dots（如 getMinBoundingBox → calc4VertexPoints）会取到空数组导致报错。
+     * 这里在 dots 缺失时惰性触发 calcDots 补齐。
+     */
+    protected ensureDots(): void;
+    /**
+     *
+     * 计算4个顶点：
+     * - 相对于组件本地的坐标系，原点位于左上角，没有经过矩阵变换。
+     * - 返回值用于计算组件的原始 width/height 。
+     *
+     * @returns
+     */
+    protected calc4VertexPoints(): any[][];
+    protected getTransformedDots(): any[];
+}

package/dist/types/graphic/ICEImage.d.mts

@@ -0,0 +1,17 @@
+/**
+ * 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 ICEComponent from './ICEComponent.mjs';
+/**
+ * @class ICEImage
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEImage extends ICEComponent {
+    constructor(props?: any);
+    protected doRender(): void;
+}
+export default ICEImage;

package/dist/types/graphic/ICEImage.d.ts

@@ -1,17 +1,17 @@
-/**
- * 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 ICEComponent from './ICEComponent';
-/**
- * @class ICEImage
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-declare class ICEImage extends ICEComponent {
-    constructor(props?: any);
-    protected doRender(): void;
-}
-export default ICEImage;
+/**
+ * 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 ICEComponent from './ICEComponent';
+/**
+ * @class ICEImage
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEImage extends ICEComponent {
+    constructor(props?: any);
+    protected doRender(): void;
+}
+export default ICEImage;

package/dist/types/graphic/ICEPath.d.mts

@@ -0,0 +1,39 @@
+import ICEComponent from './ICEComponent.mjs';
+/**
+ * @abstract
+ * @class ICEPath 路径
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare abstract class ICEPath extends ICEComponent {
+    path2D: any;
+    /**
+     * @cfg
+     * {
+     *   dots:[]  //可选参数，路径上的点。
+     * }
+     * @param props
+     */
+    constructor(props?: any);
+    /**
+     * @method doRender
+     * @overwrite
+     */
+    protected doRender(): void;
+    private __flowRegistered;
+    /**
+     * 蚂蚁线流动依赖持续重绘：注册一个 loop 动画，让 AnimationManager 每帧 setState 触发 dirty。
+     * 真正的流动位置由 doRender 里的 Date.now() 计算，动画本身只负责"每帧重绘"。
+     */
+    private __ensureFlowAnimation;
+    /**
+     * 把 polyfill 记录的命令重放到 ctx 当前路径（beginPath + 命令序列 + closePath）。
+     */
+    private replayPath;
+    /**
+     * @method createPathObject
+     * 创建路径对象（原生 Path2D 或 PolyfillPath2D），子类需要提供具体实现，此方法仅创建对象实例，不会立即绘制到画布上，绘制过程由 Renderer 进行调度。
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Path2D/Path2D
+     */
+    protected abstract createPathObject(): any;
+}
+export default ICEPath;

package/dist/types/graphic/ICEPath.d.ts

@@ -1,39 +1,39 @@
-/**
- * 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 ICEComponent from './ICEComponent';
-/**
- * @class ICEPath
- *
- * 路径
- *
- * @abstract
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-declare abstract class ICEPath extends ICEComponent {
-    path2D: Path2D;
-    /**
-     * @cfg
-     * {
-     *   dots:[]  //可选参数，路径上的点。
-     * }
-     * @param props
-     */
-    constructor(props?: any);
-    /**
-     * @method doRender
-     * @overwrite
-     */
-    protected doRender(): void;
-    /**
-     * @method createPathObject
-     * 创建 Path2D 对象，子类需要提供具体实现，此方法仅创建对象实例，不会立即绘制到画布上，绘制过程由 Renderer 进行调度。
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Path2D/Path2D
-     */
-    protected abstract createPathObject(): Path2D;
-}
-export default ICEPath;
+import ICEComponent from './ICEComponent';
+/**
+ * @abstract
+ * @class ICEPath 路径
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare abstract class ICEPath extends ICEComponent {
+    path2D: any;
+    /**
+     * @cfg
+     * {
+     *   dots:[]  //可选参数，路径上的点。
+     * }
+     * @param props
+     */
+    constructor(props?: any);
+    /**
+     * @method doRender
+     * @overwrite
+     */
+    protected doRender(): void;
+    private __flowRegistered;
+    /**
+     * 蚂蚁线流动依赖持续重绘：注册一个 loop 动画，让 AnimationManager 每帧 setState 触发 dirty。
+     * 真正的流动位置由 doRender 里的 Date.now() 计算，动画本身只负责"每帧重绘"。
+     */
+    private __ensureFlowAnimation;
+    /**
+     * 把 polyfill 记录的命令重放到 ctx 当前路径（beginPath + 命令序列 + closePath）。
+     */
+    private replayPath;
+    /**
+     * @method createPathObject
+     * 创建路径对象（原生 Path2D 或 PolyfillPath2D），子类需要提供具体实现，此方法仅创建对象实例，不会立即绘制到画布上，绘制过程由 Renderer 进行调度。
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Path2D/Path2D
+     */
+    protected abstract createPathObject(): any;
+}
+export default ICEPath;

package/dist/types/graphic/container/ICEGroup.d.mts

@@ -0,0 +1,101 @@
+import ICEComponent from '../ICEComponent.mjs';
+import ICERect from '../shape/ICERect.mjs';
+import type ICELayoutManager from '../../layout/ICELayoutManager.mjs';
+/**
+ * @class ICEGroup 容器型组件
+ *
+ * - ICEGroup 可以带有子组件，所有容器型的组件都应该继承 ICEGroup
+ * - ICEGroup 可以包含自身，利用此组件可以构造出树形的组件结构。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+declare class ICEGroup extends ICERect {
+    parentNode: any;
+    childNodes: any[];
+    private __childSet;
+    layoutManager: ICELayoutManager;
+    private __layoutExplicit;
+    /** 挂起的重排请求（一帧内合并；`doRender` 时消费）。 */
+    private __layoutRequested;
+    /** 正在执行布局：期间子项的位置/尺寸变化不再反向请求重排，避免自激循环。 */
+    private __layingOut;
+    constructor(props: any);
+    /**
+     * 设置布局策略（对齐 Swing 的 container.setLayout）。
+     * 设置后立即执行一次布局，并把布局传播给「未显式设置布局」的容器型子组件（子容器默认继承父层布局）。
+     */
+    setLayout(manager: ICELayoutManager): void;
+    /**
+     * 递归禁用所有后代组件的手动变换（transformable=false）。
+     * 一旦设定了具体 layout，子组件位置由布局代码决定，用户不可再手动变换。
+     */
+    private __disableTransformRecursively;
+    /**
+     * 把布局策略传播给「未显式设置布局」的容器型后代：
+     * - 直接/间接子容器若没有显式布局，则继承当前布局并递归向下传播；
+     * - 遇到显式设置了布局的子容器则跳过（它的后代由它自己 setLayout 时传播）。
+     */
+    private __propagateLayout;
+    /**
+     * 批量挂载/删除期间抑制逐次布局（避免 O(n²)），结束后统一排一次。
+     */
+    private __inBatch;
+    /**
+     * 执行布局：先测量子组件，再交给布局策略排布。
+     *
+     * 测量这一步是必要的：布局策略读的是 `child.state.width/height`，而它们要等首次渲染
+     * 才算出来（文本更是要量测字形）。旧实现不做测量，于是「首次布局拿到的全是 0/哨兵值」。
+     */
+    doLayout(): void;
+    /**
+     * 请求重排：**下一帧执行**，一帧内多次请求只排一次。
+     *
+     * 触发来源是「子项改了 width/height」—— 布局结果依赖子项尺寸，尺寸变了必须重排，
+     * 否则会出现「改了某个子项的大小，兄弟节点还停在老位置」。
+     * 旧实现只在 `setLayout()` / `addChild()` 时排一次，子项尺寸变化完全不会触发重排。
+     *
+     * 合并到下一帧是因为：逐个 setState 立刻重排会退化成 O(n²)（布局本身又要 setState 子项位置）。
+     */
+    requestLayout(): void;
+    /** 容器内容的首选尺寸（转发布局策略；未设置布局时返回 [0,0]）。 */
+    getPreferredSize(): [number, number];
+    protected doRender(): void;
+    protected initEvents(): void;
+    /**
+     * @method afterAddHandler 当 ICEGroup 被添加到 ICE 实例中后触发的事件
+     * !注意：在调用 ICEGroup.addChild() 方法时， ICEGroup 自身可能还没有被添加到 ICE 实例中去。所以此时 child.ctx, child.evtBus 都可能为空。
+     * !所以这里需要用事件来同步一次子节点的事件。
+     */
+    protected afterAddHandler(): void;
+    protected syncChildEvents(child: any): void;
+    /**
+     * @method addChild 添加子节点
+     *
+     * 添加子节点有两种情况：
+     * - 情况一：ICEGroup 自身已经被添加到了 ICE 实例中，此时可以直接调用 this.syncChildEvents(child); 来触发子节点上的事件。
+     * - 情况二：ICEGroup 自身还没有被添加到 ICE 实例中，此时需要用 ICE_EVENT_NAME_CONSTS.AFTER_ADD 事件来触发子节点上的事件。
+     * !注意：在调用 ICEGroup.addChild() 方法时， ICEGroup 自身可能还没有被添加到 ICE 实例中去。所以此时 child.ctx, child.evtBus 都可能为空。
+     * @param child
+     */
+    addChild(child: ICEComponent, markDirty?: boolean): void;
+    addChildren(arr: Array<ICEComponent>): void;
+    removeChild(child: ICEComponent, markDirty?: boolean): void;
+    removeChildren(arr: Array<ICEComponent>): void;
+    /**
+     * @overwrite
+     * @method setState
+     * setState 仅仅修改参数，不会立即导致重新渲染，需要等待 FrameManager 调度，最小延迟时间约为 1/60=16.67 ms 。
+     * @param newState
+     */
+    setState(newState: any): void;
+    /**
+     * @overwrite
+     * @method destory
+     * 销毁组件
+     * - FIXME:立即停止组件上的所有动画效果
+     * - 需要清理绑定的事件
+     * - 带有子节点的组件需要先销毁子节点，然后再销毁自身。
+     */
+    destory(): void;
+}
+export default ICEGroup;