ice-render 1.0.3 → 1.0.5

package/dist/types/theme/ICETheme.d.ts

@@ -0,0 +1,382 @@
+/**
+ * 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.
+ *
+ */
+/**
+ * 主题机制：三层 design token + 命名主题 + 优先级链。
+ *
+ * 分层（对齐设计 token 标准）：
+ *   ① base（基础）—— 原始值：色 ramp / spacing / radius / fontSize / fontFamily / fontWeight。
+ *   ② semantic（语义）—— 用途：primary / danger / text / border / palette / motion，引用 base。
+ *   ③ component（组件）—— STYLE_PRESETS 预设，引用 semantic + base。
+ *
+ * 优先级链（对齐 ECharts）：用户 props > 组件 preset > 语义 theme > 基础 default。
+ *
+ * 命名主题：registerTheme(name, theme) 注册，setTheme('dark') 按名切换；内置 default + dark。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export declare const baseTokens: {
+    color: {
+        blue: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        emerald: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        amber: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        red: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        gray: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        violet: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        teal: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        pink: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        indigo: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+    };
+    spacing: {
+        1: number;
+        2: number;
+        3: number;
+        4: number;
+        6: number;
+        8: number;
+        12: number;
+        16: number;
+    };
+    radius: {
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+        full: number;
+    };
+    fontSize: {
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+        '2xl': number;
+        '3xl': number;
+        '4xl': number;
+    };
+    fontFamily: {
+        base: string;
+    };
+    fontWeight: {
+        normal: number;
+        bold: number;
+    };
+};
+export interface ICESemanticTheme {
+    primary: string;
+    success: string;
+    warning: string;
+    danger: string;
+    info: string;
+    text: string;
+    muted: string;
+    hint: string;
+    border: string;
+    background: string;
+    palette: string[];
+    motion: {
+        duration: {
+            fast: number;
+            normal: number;
+            slow: number;
+            slower: number;
+        };
+        easing: {
+            linear: string;
+            out: string;
+            inOut: string;
+            outQuart: string;
+            spring: string;
+            springSoft: string;
+            springSnappy: string;
+        };
+    };
+}
+export interface ICETheme {
+    base: typeof baseTokens;
+    semantic: ICESemanticTheme;
+}
+export declare const DEFAULT_THEME: ICETheme;
+export declare const DARK_THEME: ICETheme;
+/**
+ * 注册命名主题（运行时注入，如多品牌 / 多租户）。
+ */
+export declare function registerTheme(name: string, theme: ICETheme): void;
+/**
+ * 解析主题但**不修改任何全局状态**：
+ * - string：按名查注册表（如 'dark'）；未注册时回退 DEFAULT_THEME。
+ * - object：浅合并到 `base` 的 semantic（兼容旧用法 `setTheme({ primary: ... })`）。
+ *
+ * 这是「实例级主题」的基础：`ICE` 用它把自己持有的主题解析出来，
+ * 不污染模块级当前主题（模块级只作为**默认值**）。
+ */
+export declare function resolveTheme(nameOrTheme: string | Partial<ICESemanticTheme>, base?: ICETheme): ICETheme;
+/**
+ * 切换**模块级默认主题**（全局单例）。
+ *
+ * 注意：这是「本进程默认值」，会影响此后新建的 `ICE` 实例以及未显式设置主题的实例。
+ * 需要多实例/多品牌各自独立时，请用 `ice.setTheme()`（实例级，互不影响）。
+ */
+export declare function setTheme(nameOrTheme: string | Partial<ICESemanticTheme>): ICETheme;
+export declare function getTheme(): ICETheme;
+export declare const STYLE_PRESETS: {
+    [name: string]: (theme: ICETheme) => any;
+};
+declare const _default: {
+    baseTokens: {
+        color: {
+            blue: {
+                50: string;
+                100: string;
+                200: string;
+                300: string;
+                400: string;
+                500: string;
+                600: string;
+                700: string;
+                800: string;
+                900: string;
+            };
+            emerald: {
+                50: string;
+                100: string;
+                200: string;
+                300: string;
+                400: string;
+                500: string;
+                600: string;
+                700: string;
+                800: string;
+                900: string;
+            };
+            amber: {
+                50: string;
+                100: string;
+                200: string;
+                300: string;
+                400: string;
+                500: string;
+                600: string;
+                700: string;
+                800: string;
+                900: string;
+            };
+            red: {
+                50: string;
+                100: string;
+                200: string;
+                300: string;
+                400: string;
+                500: string;
+                600: string;
+                700: string;
+                800: string;
+                900: string;
+            };
+            gray: {
+                50: string;
+                100: string;
+                200: string;
+                300: string;
+                400: string;
+                500: string;
+                600: string;
+                700: string;
+                800: string;
+                900: string;
+            };
+            violet: {
+                50: string;
+                100: string;
+                200: string;
+                300: string;
+                400: string;
+                500: string;
+                600: string;
+                700: string;
+                800: string;
+                900: string;
+            };
+            teal: {
+                50: string;
+                100: string;
+                200: string;
+                300: string;
+                400: string;
+                500: string;
+                600: string;
+                700: string;
+                800: string;
+                900: string;
+            };
+            pink: {
+                50: string;
+                100: string;
+                200: string;
+                300: string;
+                400: string;
+                500: string;
+                600: string;
+                700: string;
+                800: string;
+                900: string;
+            };
+            indigo: {
+                50: string;
+                100: string;
+                200: string;
+                300: string;
+                400: string;
+                500: string;
+                600: string;
+                700: string;
+                800: string;
+                900: string;
+            };
+        };
+        spacing: {
+            1: number;
+            2: number;
+            3: number;
+            4: number;
+            6: number;
+            8: number;
+            12: number;
+            16: number;
+        };
+        radius: {
+            sm: number;
+            md: number;
+            lg: number;
+            xl: number;
+            full: number;
+        };
+        fontSize: {
+            sm: number;
+            md: number;
+            lg: number;
+            xl: number;
+            '2xl': number;
+            '3xl': number;
+            '4xl': number;
+        };
+        fontFamily: {
+            base: string;
+        };
+        fontWeight: {
+            normal: number;
+            bold: number;
+        };
+    };
+    DEFAULT_THEME: ICETheme;
+    DARK_THEME: ICETheme;
+    registerTheme: typeof registerTheme;
+    setTheme: typeof setTheme;
+    getTheme: typeof getTheme;
+    STYLE_PRESETS: {
+        [name: string]: (theme: ICETheme) => any;
+    };
+};
+export default _default;

package/dist/types/util/ImageCache.d.mts

@@ -0,0 +1,19 @@
+import ICE from '../ICE.mjs';
+/**
+ * @class ImageCache 图片缓存器
+ *
+ * 以图片的 url 作为 key，图片对象作为 value，缓存图片。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class ImageCache {
+    private ice;
+    static readonly CACHE_SIZE = 100;
+    imageCache: Map<any, any>;
+    constructor(ice: ICE);
+    setImage(url: string): {
+        loaded: boolean;
+        image: any;
+    };
+    private loaded;
+}

package/dist/types/util/ImageCache.d.ts

@@ -1,17 +1,19 @@
-import ICE from '../ICE';
-/**
- * @class ImageCache
- * 图片缓存类
- * @author 大漠穷秋<damoqiongqiu@126.com>
- */
-export default class ImageCache {
-    private ice;
-    static readonly CACHE_SIZE = 100;
-    imageCache: Map<any, any>;
-    constructor(ice: ICE);
-    setImage(url: string): {
-        loaded: boolean;
-        image: any;
-    };
-    private loaded;
-}
+import ICE from '../ICE';
+/**
+ * @class ImageCache 图片缓存器
+ *
+ * 以图片的 url 作为 key，图片对象作为 value，缓存图片。
+ *
+ * @author 大漠穷秋<damoqiongqiu@126.com>
+ */
+export default class ImageCache {
+    private ice;
+    static readonly CACHE_SIZE = 100;
+    imageCache: Map<any, any>;
+    constructor(ice: ICE);
+    setImage(url: string): {
+        loaded: boolean;
+        image: any;
+    };
+    private loaded;
+}

package/dist/types/util/data-util.d.mts

@@ -0,0 +1,43 @@
+/**
+ * 按照指定的路径获取 Object 上的值
+ */
+export declare function getVal(object: any, path: string): any;
+/** 使所有组件的可见性缓存失效。display 变化与树结构变化时必须调用。 */
+export declare function bumpVisibilityEpoch(): void;
+/** 当前可见性代际号（供 `ICEComponent` 做惰性缓存比对）。 */
+export declare function getVisibilityEpoch(): number;
+/**
+ * 组件是否「最终可见」：自身与**所有祖先**的 `display` 都为真。
+ *
+ * `state.display = false` 的语义是整棵子树都不渲染（见 `ICEComponent` 的 props 文档），
+ * 但渲染队列是把树拉平后逐个入队的，只看组件自身会让「隐藏父容器」失效。
+ *
+ * 优先走组件上的 `isEffectivelyVisible()`（含父链遍历，顶层走 O(1) 快路径）；
+ * 传入的是外部轻量对象（无该方法）时退化为只看自身，与 `DOMEventDispatcher`
+ * 既有的鸭子类型契约（只需 `state` / `containsPoint`）保持一致。
+ */
+export declare function isEffectivelyVisible(component: any): boolean;
+/**
+ * 拉平「组件层 + 工具层」，得到全部组件的平铺数组（z 序未排）。
+ *
+ * 命中检测、无障碍快照、主题热切换、按 id 找组件都需要这一份全集，集中在这里避免各处重复
+ * `flattenTree(childNodes).concat(flattenTree(toolNodes))`。
+ *
+ * 注意：**不**复用渲染器的 `componentQueue` 缓存 —— 它在「刚改结构、本帧尚未渲染」时是旧的
+ * （首帧之前更是空的），而命中必须立刻反映最新结构。一次 flatten 远比点错目标便宜。
+ */
+export declare function flattenAllComponents(ice: any, result?: any[]): any[];
+/**
+ * 命中扫描：在**世界坐标** (wx, wy) 上找出最上层的可交互组件；无命中返回 null。
+ *
+ * 这是画布点击（`DOMEventDispatcher`）与应用层主动命中（`ICE.hitTest`）**唯一**的实现 ——
+ * 以前有两份几乎相同的代码各自演化，容易出现「点得到但 hitTest 找不到」这类不一致。
+ *
+ * 语义：
+ * - 按 zIndex 升序扫描、后者覆盖前者 → 命中 z 序最高的组件；
+ * - 跳过 `isControlPanel`（控制面板本体是覆盖层，不作为命中目标）；
+ * - 跳过 `interactive:false` 与「最终不可见」（祖先 display:false）的组件；
+ * - 复用渲染快照的世界盒做 O(1) 预筛（含 paint pad 与容差）；无快照时不预筛，正确性优先。
+ */
+export declare function hitTestComponents(ice: any, wx: number, wy: number, tolerance: number): any;
+export declare function flattenTree(result?: any[], childNodes?: any[], level?: number, pid?: any): any[];

package/dist/types/util/data-util.d.ts

@@ -1,19 +1,43 @@
-/**
- * 按照指定的路径获取 Object 上的值
- * @param {*} object
- * @param {*} path
- * @returns
- */
-export function getVal(object: any, path: any): any;
-/**
- * @method flattenTree
- *
- * 把 tree 形结构拉平成数组结构。
- *
- * @param result
- * @param childNodes
- * @param level
- * @param pid
- * @returns
- */
-export function flattenTree(result?: any[], childNodes?: any[], level?: number, pid?: any): any[];
+/**
+ * 按照指定的路径获取 Object 上的值
+ */
+export declare function getVal(object: any, path: string): any;
+/** 使所有组件的可见性缓存失效。display 变化与树结构变化时必须调用。 */
+export declare function bumpVisibilityEpoch(): void;
+/** 当前可见性代际号（供 `ICEComponent` 做惰性缓存比对）。 */
+export declare function getVisibilityEpoch(): number;
+/**
+ * 组件是否「最终可见」：自身与**所有祖先**的 `display` 都为真。
+ *
+ * `state.display = false` 的语义是整棵子树都不渲染（见 `ICEComponent` 的 props 文档），
+ * 但渲染队列是把树拉平后逐个入队的，只看组件自身会让「隐藏父容器」失效。
+ *
+ * 优先走组件上的 `isEffectivelyVisible()`（含父链遍历，顶层走 O(1) 快路径）；
+ * 传入的是外部轻量对象（无该方法）时退化为只看自身，与 `DOMEventDispatcher`
+ * 既有的鸭子类型契约（只需 `state` / `containsPoint`）保持一致。
+ */
+export declare function isEffectivelyVisible(component: any): boolean;
+/**
+ * 拉平「组件层 + 工具层」，得到全部组件的平铺数组（z 序未排）。
+ *
+ * 命中检测、无障碍快照、主题热切换、按 id 找组件都需要这一份全集，集中在这里避免各处重复
+ * `flattenTree(childNodes).concat(flattenTree(toolNodes))`。
+ *
+ * 注意：**不**复用渲染器的 `componentQueue` 缓存 —— 它在「刚改结构、本帧尚未渲染」时是旧的
+ * （首帧之前更是空的），而命中必须立刻反映最新结构。一次 flatten 远比点错目标便宜。
+ */
+export declare function flattenAllComponents(ice: any, result?: any[]): any[];
+/**
+ * 命中扫描：在**世界坐标** (wx, wy) 上找出最上层的可交互组件；无命中返回 null。
+ *
+ * 这是画布点击（`DOMEventDispatcher`）与应用层主动命中（`ICE.hitTest`）**唯一**的实现 ——
+ * 以前有两份几乎相同的代码各自演化，容易出现「点得到但 hitTest 找不到」这类不一致。
+ *
+ * 语义：
+ * - 按 zIndex 升序扫描、后者覆盖前者 → 命中 z 序最高的组件；
+ * - 跳过 `isControlPanel`（控制面板本体是覆盖层，不作为命中目标）；
+ * - 跳过 `interactive:false` 与「最终不可见」（祖先 display:false）的组件；
+ * - 复用渲染快照的世界盒做 O(1) 预筛（含 paint pad 与容差）；无快照时不预筛，正确性优先。
+ */
+export declare function hitTestComponents(ice: any, wx: number, wy: number, tolerance: number): any;
+export declare function flattenTree(result?: any[], childNodes?: any[], level?: number, pid?: any): any[];

package/dist/types/util/gl-matrix-skew.d.mts

@@ -0,0 +1,14 @@
+/**
+ * !gl-matrix 的当前版本中没有提供 skew 函数，需要手动合 https://github.com/toji/gl-matrix/pull/293
+ * @see https://github.com/talltyler/gl-matrix/commit/7c408d649073f6240f4694041ceb2af5f5284658
+ */
+/**
+ * Skew (shear) a mat2d by the given angle
+ *
+ * @param {mat2d} out the receiving matrix
+ * @param {mat2d} a the matrix to skew
+ * @param {Number} radX the angle to skew the matrix by (X axis)
+ * @param {Number} radY the angle to skew the matrix by (Y axis)
+ * @returns {mat2d} out
+ */
+export declare function skew(out: any, a: any, radX: number, radY: number): any;

package/dist/types/util/gl-matrix-skew.d.ts

@@ -1,14 +1,14 @@
-/**
- * !gl-matrix 的当前版本中没有提供 skew 函数，需要手动合 https://github.com/toji/gl-matrix/pull/293
- * @see https://github.com/talltyler/gl-matrix/commit/7c408d649073f6240f4694041ceb2af5f5284658
- */
-/**
- * Skew (shear) a mat2d by the given angle
- *
- * @param {mat2d} out the receiving matrix
- * @param {mat2d} a the matrix to skew
- * @param {Number} rad the angle to skew the matrix by
- * @param {Number} rad the angle to skew the matrix by
- * @returns {mat2d} out
- */
-export function skew(out: mat2d, a: mat2d, radX: any, radY: any): mat2d;
+/**
+ * !gl-matrix 的当前版本中没有提供 skew 函数，需要手动合 https://github.com/toji/gl-matrix/pull/293
+ * @see https://github.com/talltyler/gl-matrix/commit/7c408d649073f6240f4694041ceb2af5f5284658
+ */
+/**
+ * Skew (shear) a mat2d by the given angle
+ *
+ * @param {mat2d} out the receiving matrix
+ * @param {mat2d} a the matrix to skew
+ * @param {Number} radX the angle to skew the matrix by (X axis)
+ * @param {Number} radY the angle to skew the matrix by (Y axis)
+ * @returns {mat2d} out
+ */
+export declare function skew(out: any, a: any, radX: number, radY: number): any;

package/dist/types/util/lang.d.mts

@@ -0,0 +1,28 @@
+/**
+ * 轻量工具集：替代 lodash 的 7 个函数（isNil/isString/isUndefined/isEmpty/round/merge/cloneDeep）。
+ *
+ * 引擎的 props/state 是纯 JSON 可序列化数据（plain object + array + 原始类型），
+ * 因此这里的 cloneDeep/merge 只需针对 plain-object/array 递归，语义与 lodash 对齐：
+ * - merge 递归合并嵌套对象、数组/原始类型直接覆盖、跳过 undefined 源值、原地修改 target。
+ * - cloneDeep 深拷贝 plain object/array。
+ */
+export declare function isNil(value: any): boolean;
+export declare function isString(value: any): value is string;
+export declare function isUndefined(value: any): value is undefined;
+export declare function isEmpty(value: any): boolean;
+/**
+ * 四舍五入到指定小数位（与 lodash round 同款实现，用科学计数法规避浮点精度问题）。
+ */
+export declare function round(value: number, precision?: number): number;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * 深合并（对齐 lodash merge）：递归合并嵌套对象；数组/原始类型/null 直接覆盖；
+ * 跳过 undefined 源值；原地修改 target。支持多源：merge(target, ...sources)。
+ * 返回类型为 target 与所有 source 的交集（与 lodash 一致）。
+ */
+export declare function merge<T, S extends any[]>(target: T, ...sources: S): T & UnionToIntersection<S[number]>;
+/**
+ * 深拷贝 plain object/array（对齐 lodash cloneDeep 对纯 JSON 数据的行为）。
+ */
+export declare function cloneDeep<T>(value: T): T;
+export {};

package/dist/types/util/lang.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 轻量工具集：替代 lodash 的 7 个函数（isNil/isString/isUndefined/isEmpty/round/merge/cloneDeep）。
+ *
+ * 引擎的 props/state 是纯 JSON 可序列化数据（plain object + array + 原始类型），
+ * 因此这里的 cloneDeep/merge 只需针对 plain-object/array 递归，语义与 lodash 对齐：
+ * - merge 递归合并嵌套对象、数组/原始类型直接覆盖、跳过 undefined 源值、原地修改 target。
+ * - cloneDeep 深拷贝 plain object/array。
+ */
+export declare function isNil(value: any): boolean;
+export declare function isString(value: any): value is string;
+export declare function isUndefined(value: any): value is undefined;
+export declare function isEmpty(value: any): boolean;
+/**
+ * 四舍五入到指定小数位（与 lodash round 同款实现，用科学计数法规避浮点精度问题）。
+ */
+export declare function round(value: number, precision?: number): number;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * 深合并（对齐 lodash merge）：递归合并嵌套对象；数组/原始类型/null 直接覆盖；
+ * 跳过 undefined 源值；原地修改 target。支持多源：merge(target, ...sources)。
+ * 返回类型为 target 与所有 source 的交集（与 lodash 一致）。
+ */
+export declare function merge<T, S extends any[]>(target: T, ...sources: S): T & UnionToIntersection<S[number]>;
+/**
+ * 深拷贝 plain object/array（对齐 lodash cloneDeep 对纯 JSON 数据的行为）。
+ */
+export declare function cloneDeep<T>(value: T): T;
+export {};

package/dist/types/util/uuid.d.mts

@@ -0,0 +1 @@
+export declare function uuid(): string;

package/dist/types/util/uuid.d.ts

@@ -1 +1 @@
-export function uuid(): any;
+export declare function uuid(): string;