@agions/taroviz 1.11.5 → 2.0.3

package/src/core/utils/__tests__/deepClone.test.ts

@@ -0,0 +1,317 @@
+import { deepClone, deepMerge } from '../deepClone';
+
+describe('deepClone', () => {
+  // Primitives
+  it('clones primitives', () => {
+    expect(deepClone(42)).toBe(42);
+    expect(deepClone('hello')).toBe('hello');
+    expect(deepClone(true)).toBe(true);
+    expect(deepClone(false)).toBe(false);
+    expect(deepClone(0)).toBe(0);
+    expect(deepClone(-1)).toBe(-1);
+    expect(deepClone(3.14)).toBe(3.14);
+  });
+
+  it('handles null and undefined', () => {
+    expect(deepClone(null)).toBe(null);
+    expect(deepClone(undefined)).toBe(undefined);
+  });
+
+  // Objects
+  it('clones plain objects', () => {
+    const obj = { a: 1, b: 'two', c: true };
+    const clone = deepClone(obj);
+    expect(clone).toEqual(obj);
+    expect(clone).not.toBe(obj);
+  });
+
+  it('clones nested objects', () => {
+    const obj = { a: { b: { c: { d: 42 } } } };
+    const clone = deepClone(obj);
+    expect(clone).toEqual(obj);
+    expect(clone).not.toBe(obj);
+    expect(clone.a).not.toBe(obj.a);
+    expect(clone.a.b).not.toBe(obj.a.b);
+  });
+
+  // Arrays
+  it('clones arrays', () => {
+    const arr = [1, 2, 3, [4, 5]];
+    const clone = deepClone(arr);
+    expect(clone).toEqual(arr);
+    expect(clone).not.toBe(arr);
+    expect(clone[3]).not.toBe(arr[3]);
+  });
+
+  it('clones arrays of objects', () => {
+    const arr = [{ a: 1 }, { b: 2 }];
+    const clone = deepClone(arr);
+    expect(clone).toEqual(arr);
+    expect(clone[0]).not.toBe(arr[0]);
+  });
+
+  // Date
+  it('clones Date objects', () => {
+    const date = new Date('2024-01-15');
+    const clone = deepClone(date);
+    expect(clone).toEqual(date);
+    expect(clone).not.toBe(date);
+    expect(clone.getTime()).toBe(date.getTime());
+  });
+
+  // RegExp
+  it('clones RegExp objects', () => {
+    const re = /foo/gi;
+    const clone = deepClone(re);
+    expect(clone.source).toBe('foo');
+    expect(clone.flags).toBe('gi');
+    expect(clone).not.toBe(re);
+  });
+
+  // Functions
+  it('preserves function references', () => {
+    const fn = (x: number) => x * 2;
+    expect(deepClone(fn)).toBe(fn);
+  });
+
+  it('preserves nested function references', () => {
+    const fn = () => 'hello';
+    const obj = { formatter: fn, nested: { callback: fn } };
+    const clone = deepClone(obj);
+    expect(clone.formatter).toBe(fn);
+    expect(clone.nested.callback).toBe(fn);
+    expect(clone).not.toBe(obj);
+    expect(clone.nested).not.toBe(obj.nested);
+  });
+
+  // Map
+  it('clones Map objects', () => {
+    const map = new Map<string, number>([
+      ['a', 1],
+      ['b', 2],
+    ]);
+    const clone = deepClone(map);
+    expect(clone).not.toBe(map);
+    expect(clone.get('a')).toBe(1);
+    expect(clone.get('b')).toBe(2);
+    expect(clone.size).toBe(2);
+  });
+
+  it('clones Map with object keys and values', () => {
+    const key = { id: 1 };
+    const val = { name: 'test' };
+    const map = new Map([[key, val]]);
+    const clone = deepClone(map);
+    expect(clone).not.toBe(map);
+    // Keys are cloned, so we can't look up with the original key
+    const clonedEntries = Array.from(clone.entries());
+    expect(clonedEntries).toHaveLength(1);
+    expect(clonedEntries[0][0]).toEqual(key);
+    expect(clonedEntries[0][0]).not.toBe(key);
+    expect(clonedEntries[0][1]).toEqual(val);
+    expect(clonedEntries[0][1]).not.toBe(val);
+  });
+
+  // Set
+  it('clones Set objects', () => {
+    const set = new Set([1, 2, 3]);
+    const clone = deepClone(set);
+    expect(clone).not.toBe(set);
+    expect(clone.size).toBe(3);
+    expect(clone.has(1)).toBe(true);
+    expect(clone.has(2)).toBe(true);
+    expect(clone.has(3)).toBe(true);
+  });
+
+  it('clones Set with object values', () => {
+    const obj = { a: 1 };
+    const set = new Set([obj]);
+    const clone = deepClone(set);
+    const clonedValues = Array.from(clone.values());
+    expect(clonedValues[0]).toEqual(obj);
+    expect(clonedValues[0]).not.toBe(obj);
+  });
+
+  // Circular references
+  it('handles circular references in objects', () => {
+    const obj: Record<string, unknown> = { a: 1 };
+    obj.self = obj;
+    const clone = deepClone(obj);
+    expect(clone.a).toBe(1);
+    expect(clone.self).toBe(clone);
+    expect(clone).not.toBe(obj);
+  });
+
+  it('handles circular references in arrays', () => {
+    const arr: unknown[] = [1, 2];
+    arr.push(arr);
+    const clone = deepClone(arr);
+    expect(clone[0]).toBe(1);
+    expect(clone[1]).toBe(2);
+    expect(clone[2]).toBe(clone);
+    expect(clone).not.toBe(arr);
+  });
+
+  it('handles cross-reference between objects', () => {
+    const shared = { value: 42 };
+    const obj = { a: shared, b: shared };
+    const clone = deepClone(obj);
+    expect(clone.a).toEqual(shared);
+    expect(clone.b).toEqual(shared);
+    // Both references should point to the same clone
+    expect(clone.a).toBe(clone.b);
+    expect(clone.a).not.toBe(shared);
+  });
+
+  // ECharts-like option objects
+  it('clones ECharts-like option objects', () => {
+    const formatter = (params: { value: number }) => `${params.value}%`;
+    const options = {
+      title: {
+        text: 'Sales',
+        subtext: '2024',
+      },
+      tooltip: {
+        trigger: 'axis' as const,
+        formatter,
+      },
+      xAxis: {
+        type: 'category' as const,
+        data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
+      },
+      yAxis: {
+        type: 'value' as const,
+      },
+      series: [
+        {
+          name: 'Sales',
+          type: 'line' as const,
+          data: [150, 230, 224, 218, 135],
+          label: {
+            show: true,
+            formatter: (params: { value: number }) => `${params.value}`,
+          },
+        },
+      ],
+    };
+
+    const clone = deepClone(options);
+
+    // Structure equality
+    expect(clone).toEqual(options);
+    // Deep copy
+    expect(clone).not.toBe(options);
+    expect(clone.title).not.toBe(options.title);
+    expect(clone.series).not.toBe(options.series);
+    expect(clone.series[0]).not.toBe(options.series[0]);
+    // Function preserved
+    expect(clone.tooltip.formatter).toBe(formatter);
+    expect(clone.series[0].label.formatter).toBe(options.series[0].label.formatter);
+  });
+
+  // Mixed types
+  it('clones complex mixed structures', () => {
+    const obj = {
+      str: 'hello',
+      num: 42,
+      bool: true,
+      nil: null,
+      undef: undefined,
+      date: new Date('2024-06-01'),
+      regex: /test/gi,
+      arr: [1, [2, 3], { a: 4 }],
+      fn: () => 'test',
+      map: new Map([['key', { nested: true }]]),
+      set: new Set([{ x: 1 }, { x: 2 }]),
+      nested: {
+        deep: {
+          deeper: {
+            value: 'bottom',
+          },
+        },
+      },
+    };
+
+    const clone = deepClone(obj);
+
+    expect(clone.str).toBe('hello');
+    expect(clone.num).toBe(42);
+    expect(clone.bool).toBe(true);
+    expect(clone.nil).toBe(null);
+    expect(clone.undef).toBe(undefined);
+    expect(clone.date).toEqual(obj.date);
+    expect(clone.date).not.toBe(obj.date);
+    expect(clone.regex.source).toBe('test');
+    expect(clone.regex).not.toBe(obj.regex);
+    expect(clone.arr).toEqual([1, [2, 3], { a: 4 }]);
+    expect(clone.arr).not.toBe(obj.arr);
+    expect(clone.fn).toBe(obj.fn);
+    expect(clone.map).not.toBe(obj.map);
+    expect(clone.set).not.toBe(obj.set);
+    expect(clone.nested.deep.deeper.value).toBe('bottom');
+    expect(clone.nested).not.toBe(obj.nested);
+  });
+});
+
+describe('deepMerge', () => {
+  it('merges flat objects', () => {
+    const target = { a: 1, b: 2 };
+    const source = { b: 3, c: 4 };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: 3, c: 4 });
+  });
+
+  it('merges nested objects recursively', () => {
+    const target = { a: { x: 1, y: 2 }, b: 1 };
+    const source = { a: { y: 3, z: 4 } };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: { x: 1, y: 3, z: 4 }, b: 1 });
+  });
+
+  it('replaces arrays instead of merging them', () => {
+    const target = { arr: [1, 2, 3] };
+    const source = { arr: [4, 5] };
+    const result = deepMerge(target, source);
+    expect(result.arr).toEqual([4, 5]);
+  });
+
+  it('replaces primitives with source values', () => {
+    const target = { a: 1, b: 'old' };
+    const source = { a: 2, b: 'new' };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 2, b: 'new' });
+  });
+
+  it('preserves function references from source', () => {
+    const fn = () => 'hello';
+    const target = { a: 1 };
+    const source = { formatter: fn };
+    const result = deepMerge(target, source);
+    expect(result.formatter).toBe(fn);
+  });
+
+  it('does not mutate target or source', () => {
+    const target = { a: { x: 1 } };
+    const source = { a: { y: 2 } };
+    deepMerge(target, source);
+    expect(target).toEqual({ a: { x: 1 } });
+    expect(source).toEqual({ a: { y: 2 } });
+  });
+
+  it('merges ECharts-like option objects', () => {
+    const target = {
+      title: { text: 'Chart' },
+      tooltip: { trigger: 'axis' as const },
+      series: [{ type: 'line' as const, data: [1, 2, 3] }],
+    };
+    const source = {
+      title: { subtext: 'Sub' },
+      tooltip: { formatter: (p: { value: number }) => `${p.value}%` },
+    };
+    const result = deepMerge(target, source);
+    expect(result.title).toEqual({ text: 'Chart', subtext: 'Sub' });
+    expect(result.tooltip.trigger).toBe('axis');
+    expect(typeof result.tooltip.formatter).toBe('function');
+    expect(result.series).toEqual([{ type: 'line', data: [1, 2, 3] }]);
+  });
+});

package/src/core/utils/__tests__/index.test.ts

@@ -92,7 +92,8 @@ describe('Data Processing Utilities', () => {
 
     it('should limit execution to once per interval', () => {
       const mockFn = jest.fn();
-      const throttledFn = throttle(mockFn, 100);
+      // 使用 leading=true, trailing=false 来匹配简单 throttle 行为
+      const throttledFn = throttle(mockFn, 100, { leading: true, trailing: false });
 
       throttledFn();
       expect(mockFn).toHaveBeenCalledTimes(1);

package/src/core/utils/chartInstances.ts

@@ -83,3 +83,16 @@ export function resizeAllCharts(): void {
     }
   });
 }
+
+/**
+ * Dispose and remove stale chart instances (those whose DOM container is gone)
+ * Call periodically or from ErrorBoundary componentDidCatch
+ */
+export function disposeStaleCharts(): void {
+  Object.keys(CHART_INSTANCES).forEach((id) => {
+    const instance = CHART_INSTANCES[id];
+    if (!instance || instance.isDisposed()) {
+      delete CHART_INSTANCES[id];
+    }
+  });
+}

package/src/core/utils/common.ts

@@ -1,3 +1,15 @@
+/**
+ * Environment detection utilities
+ *
+ * Backward-compatible re-exports that delegate to the unified detectRuntime()
+ * in ./runtime.ts. New code should import detectRuntime() directly.
+ */
+
+import { detectRuntime as _detectRuntime } from './runtime';
+
+export { detectRuntime, resetRuntimeCache } from './runtime';
+export type { RuntimeInfo, MiniAppType } from './runtime';
+
 /**
  * 获取DOM元素
  * @param selector 选择器或DOM元素
@@ -21,14 +33,12 @@ export const isBrowser = typeof window !== 'undefined' && typeof document !== 'u
  * @returns 是否为NodeJS环境
  */
 export const isNode = (() => {
-  // 更可靠的环境检测：检查是否是真正的 Node.js 环境
-  // 而不是打包后的代码（如 webpack 定义的 process.env）
   try {
     return (
       typeof process !== 'undefined' &&
-      process.versions &&
-      process.versions.node &&
-      Object.prototype.toString.call(globalThis.process) === '[object process]'
+      (process as any).versions &&
+      (process as any).versions.node &&
+      Object.prototype.toString.call((globalThis as any).process) === '[object process]'
     );
   } catch {
     return false;
@@ -40,39 +50,13 @@ export const isNode = (() => {
  * @returns 是否为React Native环境
  */
 export const isReactNative =
-  typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+  typeof navigator !== 'undefined' && (navigator as any).product === 'ReactNative';
 
 /**
  * 是否为小程序环境
+ *
+ * Delegates to detectRuntime() for unified detection.
+ * Cached internally — repeated calls are cheap.
  * @returns 是否为小程序环境
  */
-export const isMiniApp = (): boolean => {
-  // 使用类型断言来安全地检查全局变量
-  const globalObj =
-    typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : {};
-  const win = globalObj as Window & {
-    wx?: unknown;
-    my?: unknown;
-    swan?: unknown;
-    tt?: unknown;
-    jd?: unknown;
-  };
-
-  if (typeof win.wx !== 'undefined') {
-    return true;
-  }
-  if (typeof win.my !== 'undefined') {
-    return true;
-  }
-  if (typeof win.swan !== 'undefined') {
-    return true;
-  }
-  if (typeof win.tt !== 'undefined') {
-    return true;
-  }
-  if (typeof win.jd !== 'undefined') {
-    return true;
-  }
-
-  return false;
-};
+export const isMiniApp = (): boolean => _detectRuntime().isMiniApp;

package/src/core/utils/deepClone.ts

@@ -0,0 +1,114 @@
+/**
+ * Hand-written deep clone utility for ECharts option objects.
+ * Handles all JS types, circular references, and preserves function references.
+ */
+export function deepClone<T>(value: T, seen?: WeakMap<object, unknown>): T {
+  // primitives, null, undefined
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object' && typeof value !== 'function') return value;
+  // preserve function references
+  if (typeof value === 'function') return value;
+
+  // circular reference handling
+  if (!seen) seen = new WeakMap();
+  if (seen.has(value as object)) return seen.get(value as object) as T;
+
+  // Date
+  if (value instanceof Date) {
+    const d = new Date(value.getTime());
+    seen.set(value as object, d);
+    return d as unknown as T;
+  }
+
+  // RegExp
+  if (value instanceof RegExp) {
+    const r = new RegExp(value.source, value.flags);
+    seen.set(value as object, r);
+    return r as unknown as T;
+  }
+
+  // Map
+  if (value instanceof Map) {
+    const m = new Map();
+    seen.set(value as object, m);
+    value.forEach((v, k) => {
+      m.set(deepClone(k, seen), deepClone(v, seen));
+    });
+    return m as unknown as T;
+  }
+
+  // Set
+  if (value instanceof Set) {
+    const s = new Set();
+    seen.set(value as object, s);
+    value.forEach((v) => {
+      s.add(deepClone(v, seen));
+    });
+    return s as unknown as T;
+  }
+
+  // Array
+  if (Array.isArray(value)) {
+    const arr: unknown[] = [];
+    seen.set(value as object, arr);
+    for (let i = 0; i < value.length; i++) {
+      arr[i] = deepClone(value[i], seen);
+    }
+    return arr as unknown as T;
+  }
+
+  // Plain object
+  const clone = {} as Record<string, unknown>;
+  seen.set(value as object, clone);
+  for (const key of Object.keys(value as object)) {
+    clone[key] = deepClone((value as Record<string, unknown>)[key], seen);
+  }
+  return clone as T;
+}
+
+/**
+ * Deep merge source into target. Returns a new object.
+ * Arrays are replaced, not merged. Objects are merged recursively.
+ */
+export function deepMerge<T extends Record<string, unknown>, U extends Record<string, unknown>>(
+  target: T,
+  source: U
+): T & U {
+  const result: Record<string, unknown> = {};
+
+  // Copy all target keys
+  for (const key of Object.keys(target)) {
+    result[key] = deepClone(target[key]);
+  }
+
+  // Merge source keys
+  for (const key of Object.keys(source)) {
+    const tVal = result[key];
+    const sVal = source[key];
+
+    if (
+      tVal !== null &&
+      tVal !== undefined &&
+      sVal !== null &&
+      sVal !== undefined &&
+      typeof tVal === 'object' &&
+      typeof sVal === 'object' &&
+      !Array.isArray(tVal) &&
+      !Array.isArray(sVal) &&
+      !(tVal instanceof Date) &&
+      !(tVal instanceof RegExp) &&
+      !(tVal instanceof Map) &&
+      !(tVal instanceof Set) &&
+      !(sVal instanceof Date) &&
+      !(sVal instanceof RegExp) &&
+      !(sVal instanceof Map) &&
+      !(sVal instanceof Set)
+    ) {
+      result[key] = deepMerge(tVal as Record<string, unknown>, sVal as Record<string, unknown>);
+    } else {
+      result[key] = deepClone(sVal);
+    }
+  }
+
+  return result as T & U;
+}

package/src/core/utils/download.ts

@@ -37,55 +37,49 @@ export function generateFormattedFilename(name: string, format: string): string
 }
 
 /**
- * 下载 Blob 对象
- * @param blob Blob 数据
+ * 触发浏览器下载的通用函数
+ * @param href 下载链接
  * @param filename 文件名
+ * @param cleanup 可选的清理回调（如 revokeObjectURL）
  */
-export function downloadBlob(blob: Blob, filename: string): void {
-  const url = URL.createObjectURL(blob);
+function triggerDownload(href: string, filename: string, cleanup?: () => void): void {
+  if (typeof document === 'undefined') return;
   const link = document.createElement('a');
-  link.href = url;
+  link.href = href;
   link.download = filename;
   link.style.display = 'none';
-
   document.body.appendChild(link);
   link.click();
-
-  // 延迟清理，确保下载对话框已打开
   const timerId = setTimeout(() => {
-    if (link.parentNode) {
-      document.body.removeChild(link);
-    }
-    URL.revokeObjectURL(url);
+    if (link.parentNode) document.body.removeChild(link);
+    cleanup?.();
+    // Auto-remove from timers array
+    const idx = timers.indexOf(timerId);
+    if (idx !== -1) timers.splice(idx, 1);
   }, 100);
   timers.push(timerId);
 }
 
+/**
+ * 下载 Blob 对象
+ * @param blob Blob 数据
+ * @param filename 文件名
+ */
+export function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  triggerDownload(url, filename, () => URL.revokeObjectURL(url));
+}
+
 /**
  * 下载数据 URL
  * @param dataUrl 数据 URL
  * @param filename 文件名
  */
 export function downloadDataUrl(dataUrl: string, filename: string): void {
-  const link = document.createElement('a');
-  link.href = dataUrl;
-  link.download = filename;
-  link.style.display = 'none';
-
-  document.body.appendChild(link);
-  link.click();
-
-  // 延迟清理
-  const timerId = setTimeout(() => {
-    if (link.parentNode) {
-      document.body.removeChild(link);
-    }
-  }, 100);
-  timers.push(timerId);
+  triggerDownload(dataUrl, filename);
 }
 
 /**
- * 下载文件（支持 string | Blob）
  * 下载文件（支持 string | Blob）
  * @param data 数据（string 或 Blob）
  * @param filename 文件名

package/src/core/utils/drillDown.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /**
  * DrillDown - 数据下钻工具
  * 支持点击图表数据项时，自动下钻到更细粒度的数据视图

package/src/core/utils/events.ts

@@ -0,0 +1,12 @@
+/**
+ * 事件名称常量定义
+ */
+export const events = {
+  click: 'click',
+  mousemove: 'mousemove',
+  mouseup: 'mouseup',
+  mousedown: 'mousedown',
+  mouseover: 'mouseover',
+  mouseout: 'mouseout',
+  globalout: 'globalout',
+};

package/src/core/utils/export/ExportUtils.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /**
  * TaroViz 图表导出工具
  * 支持导出为 PNG、JPEG、SVG、PDF 等格式
@@ -18,7 +19,7 @@ type ExportImageType = 'png' | 'jpeg' | 'svg' | 'webp' | 'gif';
 /**
  * getDataURL 方法参数（基于 ECharts 官方类型，扩展 webp/gif 支持）
  */
-interface EChartsDataURLOptions {
+interface __EChartsDataURLOptions {
   type?: ExportImageType;
   pixelRatio?: number;
   backgroundColor?: string;

package/src/core/utils/format.ts

@@ -0,0 +1,44 @@
+/**
+ * 格式化数值
+ * @param value 要格式化的数值
+ * @param digits 小数位数
+ * @param options 配置选项
+ * @returns 格式化后的字符串
+ */
+export function formatNumber(
+  value: number,
+  digits: number = 2,
+  options: {
+    useGrouping?: boolean;
+    locale?: string;
+  } = {}
+): string {
+  const { useGrouping = true, locale = 'zh-CN' } = options;
+
+  return new Intl.NumberFormat(locale, {
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+    useGrouping,
+  }).format(value);
+}
+
+/**
+ * 获取颜色的对比色
+ * @param color 十六进制颜色值
+ * @returns 对比色
+ */
+export function getContrastColor(color: string): string {
+  // 移除#前缀
+  const hex = color.replace('#', '');
+
+  // 转换为RGB
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+
+  // 计算亮度
+  const brightness = (r * 299 + g * 587 + b * 114) / 1000;
+
+  // 根据亮度返回黑色或白色
+  return brightness > 128 ? '#000000' : '#FFFFFF';
+}