@agions/taroviz 1.1.0 → 1.2.0

package/src/hooks/__tests__/index.test.tsx

@@ -0,0 +1,333 @@
+import { renderHook } from '@testing-library/react';
+import React from 'react';
+
+import {
+  useChart,
+  useOption,
+  useResize,
+  useEvents,
+  useLoading,
+  useChartTheme,
+  useChartData,
+} from '../index';
+
+// Mock dependencies
+jest.mock('../../adapters', () => ({
+  getAdapter: jest.fn(() => ({
+    setComponent: jest.fn(),
+    setOption: jest.fn(),
+    resize: jest.fn(),
+    on: jest.fn(),
+    off: jest.fn(),
+    showLoading: jest.fn(),
+    hideLoading: jest.fn(),
+    dispose: jest.fn(),
+  })),
+}));
+
+describe('React Hooks', () => {
+  describe('useChart', () => {
+    it('should initialize chart instance when ref is available', () => {
+      const chartRef = { current: document.createElement('div') };
+
+      const { result, rerender } = renderHook(
+        (ref: React.RefObject<HTMLElement>) => useChart(ref),
+        { initialProps: chartRef }
+      );
+
+      rerender(chartRef);
+
+      expect(result.current[0]).not.toBeNull();
+    });
+
+    it('should return null when ref is not available', () => {
+      const chartRef = { current: null };
+
+      const { result } = renderHook((ref: React.RefObject<HTMLElement>) => useChart(ref), {
+        initialProps: chartRef,
+      });
+
+      expect(result.current[0]).toBeNull();
+    });
+  });
+
+  describe('useOption', () => {
+    it('should call setOption when instance and option are provided', () => {
+      const mockInstance = {
+        setOption: jest.fn(),
+      };
+
+      const option = { xAxis: { type: 'category' }, yAxis: { type: 'value' }, series: [] };
+
+      renderHook(
+        ({ instance, option }: { instance: any; option: any }) => useOption(instance, option),
+        {
+          initialProps: { instance: mockInstance, option },
+        }
+      );
+
+      expect(mockInstance.setOption).toHaveBeenCalledWith(option);
+    });
+
+    it('should not call setOption when instance is null', () => {
+      const mockInstance = {
+        setOption: jest.fn(),
+      };
+
+      const option = { xAxis: { type: 'category' }, yAxis: { type: 'value' }, series: [] };
+
+      renderHook(
+        ({ instance, option }: { instance: any; option: any }) => useOption(instance, option),
+        {
+          initialProps: { instance: null, option },
+        }
+      );
+
+      expect(mockInstance.setOption).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('useResize', () => {
+    it('should add resize event listener when instance is provided', () => {
+      const mockInstance = {
+        resize: jest.fn(),
+      };
+
+      // Create spies and save original methods
+      const originalAddEventListener = window.addEventListener;
+      const originalRemoveEventListener = window.removeEventListener;
+      const addEventListenerSpy = jest.spyOn(window, 'addEventListener');
+      const removeEventListenerSpy = jest.spyOn(window, 'removeEventListener');
+
+      const { unmount } = renderHook((instance: any) => useResize(instance), {
+        initialProps: mockInstance,
+      });
+
+      expect(addEventListenerSpy).toHaveBeenCalledWith('resize', expect.any(Function));
+
+      unmount();
+
+      expect(removeEventListenerSpy).toHaveBeenCalledWith('resize', expect.any(Function));
+
+      // Restore original methods to ensure test isolation
+      window.addEventListener = originalAddEventListener;
+      window.removeEventListener = originalRemoveEventListener;
+    });
+
+    it('should not add resize event listener when instance is null', () => {
+      // Create spies and save original methods
+      const originalAddEventListener = window.addEventListener;
+      const addEventListenerSpy = jest.spyOn(window, 'addEventListener');
+
+      // Render the hook with null instance
+      renderHook((instance: any) => useResize(instance), { initialProps: null });
+
+      // Check that the event listener was not added
+      expect(addEventListenerSpy).not.toHaveBeenCalledWith('resize', expect.any(Function));
+
+      // Restore original method to ensure test isolation
+      window.addEventListener = originalAddEventListener;
+    });
+  });
+
+  describe('useEvents', () => {
+    it('should bind events when instance and events are provided', () => {
+      const mockInstance = {
+        on: jest.fn(),
+        off: jest.fn(),
+      };
+
+      const events = {
+        click: jest.fn(),
+        mouseover: jest.fn(),
+      };
+
+      const { unmount } = renderHook(
+        ({ instance, events }: { instance: any; events: any }) => useEvents(instance, events),
+        {
+          initialProps: { instance: mockInstance, events },
+        }
+      );
+
+      expect(mockInstance.on).toHaveBeenCalledTimes(2);
+      expect(mockInstance.on).toHaveBeenCalledWith('click', events.click);
+      expect(mockInstance.on).toHaveBeenCalledWith('mouseover', events.mouseover);
+
+      unmount();
+
+      expect(mockInstance.off).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not bind events when instance is null', () => {
+      const mockInstance = {
+        on: jest.fn(),
+      };
+
+      const events = {
+        click: jest.fn(),
+      };
+
+      renderHook(
+        ({ instance, events }: { instance: any; events: any }) => useEvents(instance, events),
+        {
+          initialProps: { instance: null, events },
+        }
+      );
+
+      expect(mockInstance.on).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('useLoading', () => {
+    it('should call showLoading when loading is true', () => {
+      const mockInstance = {
+        showLoading: jest.fn(),
+        hideLoading: jest.fn(),
+      };
+
+      renderHook(
+        ({ instance, loading }: { instance: any; loading: boolean }) =>
+          useLoading(instance, loading),
+        {
+          initialProps: { instance: mockInstance, loading: true },
+        }
+      );
+
+      expect(mockInstance.showLoading).toHaveBeenCalled();
+      expect(mockInstance.hideLoading).not.toHaveBeenCalled();
+    });
+
+    it('should call hideLoading when loading is false', () => {
+      const mockInstance = {
+        showLoading: jest.fn(),
+        hideLoading: jest.fn(),
+      };
+
+      renderHook(
+        ({ instance, loading }: { instance: any; loading: boolean }) =>
+          useLoading(instance, loading),
+        {
+          initialProps: { instance: mockInstance, loading: false },
+        }
+      );
+
+      expect(mockInstance.hideLoading).toHaveBeenCalled();
+      expect(mockInstance.showLoading).not.toHaveBeenCalled();
+    });
+
+    it('should not call loading methods when instance is null', () => {
+      const mockInstance = {
+        showLoading: jest.fn(),
+        hideLoading: jest.fn(),
+      };
+
+      renderHook(
+        ({ instance, loading }: { instance: any; loading: boolean }) =>
+          useLoading(instance, loading),
+        {
+          initialProps: { instance: null, loading: true },
+        }
+      );
+
+      expect(mockInstance.showLoading).not.toHaveBeenCalled();
+      expect(mockInstance.hideLoading).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('useChartTheme', () => {
+    it('should return dark theme when darkMode is true', () => {
+      const { result } = renderHook(
+        ({ theme, darkMode }: { theme: string; darkMode: boolean }) =>
+          useChartTheme(theme, darkMode),
+        {
+          initialProps: { theme: 'default', darkMode: true },
+        }
+      );
+
+      expect(result.current).toBe('dark');
+    });
+
+    it('should return original theme when darkMode is false', () => {
+      const { result } = renderHook(
+        ({ theme, darkMode }: { theme: string; darkMode: boolean }) =>
+          useChartTheme(theme, darkMode),
+        {
+          initialProps: { theme: 'default', darkMode: false },
+        }
+      );
+
+      expect(result.current).toBe('default');
+    });
+
+    it('should return theme object when theme is an object', () => {
+      const customTheme = { backgroundColor: '#000' };
+
+      const { result } = renderHook(
+        ({ theme, darkMode }: { theme: Record<string, any>; darkMode: boolean }) =>
+          useChartTheme(theme, darkMode),
+        {
+          initialProps: { theme: customTheme, darkMode: true },
+        }
+      );
+
+      expect(result.current).toBe(customTheme);
+    });
+  });
+
+  describe('useChartData', () => {
+    it('should return transformed data when data is provided', () => {
+      const data = [
+        { name: 'A', value: 10 },
+        { name: 'B', value: 20 },
+      ];
+      const transformer = jest.fn((d: any[]) => ({
+        series: [{ data: d.map((item: any) => item.value) }],
+      }));
+
+      const { result } = renderHook(
+        ({ data, transformer }: { data: any[]; transformer: (data: any[]) => any }) =>
+          useChartData(data, transformer),
+        {
+          initialProps: { data, transformer },
+        }
+      );
+
+      expect(transformer).toHaveBeenCalledWith(data);
+      expect(result.current).toEqual({
+        series: [{ data: [10, 20] }],
+      });
+    });
+
+    it('should return empty series when data is empty', () => {
+      const data: any[] = [];
+      const transformer = jest.fn();
+
+      const { result } = renderHook(
+        ({ data, transformer }: { data: any[]; transformer: (data: any[]) => any }) =>
+          useChartData(data, transformer),
+        {
+          initialProps: { data, transformer },
+        }
+      );
+
+      expect(transformer).not.toHaveBeenCalled();
+      expect(result.current).toEqual({ series: [] });
+    });
+
+    it('should return empty series when data is null', () => {
+      const data = null as any;
+      const transformer = jest.fn();
+
+      const { result } = renderHook(
+        ({ data, transformer }: { data: any[] | null; transformer: (data: any[]) => any }) =>
+          useChartData(data, transformer),
+        {
+          initialProps: { data, transformer },
+        }
+      );
+
+      expect(transformer).not.toHaveBeenCalled();
+      expect(result.current).toEqual({ series: [] });
+    });
+  });
+});

package/src/hooks/index.ts

@@ -0,0 +1,214 @@
+/**
+ * TaroViz React Hooks
+ * 提供与图表相关的React Hooks
+ */
+import { useState, useEffect, useMemo } from 'react';
+
+import { getAdapter } from '../adapters';
+import { EventHandler } from '../core';
+
+// 通用图表配置类型
+interface ChartOptions {
+  [key: string]: any;
+}
+
+// 通用图表实例类型
+interface ChartInstance {
+  setOption: (option: any, notMerge?: boolean) => void;
+  resize: () => void;
+  on: (event: string, handler: EventHandler) => void;
+  off: (event: string, handler?: EventHandler) => void;
+  showLoading: (opts?: any) => void;
+  hideLoading: () => void;
+  dispose: () => void;
+  [key: string]: any;
+}
+
+/**
+ * 使用图表Hook
+ * @param chartRef 图表容器的引用
+ * @returns [图表实例, setInstance]
+ */
+export function useChart(chartRef: React.RefObject<HTMLElement>) {
+  const [instance, setInstance] = useState<ChartInstance | null>(null);
+
+  useEffect(() => {
+    if (chartRef.current && !instance) {
+      // 使用默认配置初始化适配器
+      const adapter = getAdapter({});
+
+      // 注意：Adapter接口可能没有直接定义setComponent方法
+      // 但多数适配器实现中都有这个方法，我们可以通过类型断言使用
+      if (typeof (adapter as any).setComponent === 'function') {
+        (adapter as any).setComponent(chartRef.current);
+      }
+
+      // 初始化并保存实例
+      const chartInstance = adapter as unknown as ChartInstance;
+      setInstance(chartInstance);
+    }
+
+    return () => {
+      if (instance) {
+        try {
+          instance.dispose();
+        } catch (e) {
+          console.warn('Failed to dispose chart instance:', e);
+        }
+      }
+    };
+  }, [chartRef, instance]);
+
+  return [instance, setInstance] as const;
+}
+
+/**
+ * 设置图表选项Hook
+ * @param instance 图表实例
+ * @param option 图表选项
+ * @param deps 依赖数组
+ */
+export function useOption(instance: ChartInstance | null, option: ChartOptions, deps: any[] = []) {
+  useEffect(() => {
+    if (instance && option) {
+      try {
+        instance.setOption(option);
+      } catch (e) {
+        console.warn('Failed to set chart option:', e);
+      }
+    }
+  }, [instance, option, ...deps]);
+}
+
+/**
+ * 图表自适应Hook
+ * @param instance 图表实例
+ */
+export function useResize(instance: ChartInstance | null) {
+  useEffect(() => {
+    if (!instance) {
+      return;
+    }
+
+    const handleResize = () => {
+      try {
+        instance.resize();
+      } catch (e) {
+        console.warn('Failed to resize chart:', e);
+      }
+    };
+
+    window.addEventListener('resize', handleResize);
+
+    return () => {
+      window.removeEventListener('resize', handleResize);
+    };
+  }, [instance]);
+}
+
+/**
+ * 图表事件Hook
+ * @param instance 图表实例
+ * @param events 事件对象
+ */
+export function useEvents(instance: ChartInstance | null, events: Record<string, EventHandler>) {
+  useEffect(() => {
+    if (!instance) {
+      return;
+    }
+
+    const eventEntries = Object.entries(events);
+
+    // 绑定事件
+    eventEntries.forEach(([eventName, handler]) => {
+      try {
+        instance.on(eventName, handler);
+      } catch (e) {
+        console.warn(`Failed to bind event ${eventName}:`, e);
+      }
+    });
+
+    // 清理事件
+    return () => {
+      eventEntries.forEach(([eventName, handler]) => {
+        try {
+          instance.off(eventName, handler);
+        } catch (e) {
+          console.warn(`Failed to unbind event ${eventName}:`, e);
+        }
+      });
+    };
+  }, [instance, events]);
+}
+
+/**
+ * 图表加载状态Hook
+ * @param instance 图表实例
+ * @param loading 是否加载中
+ */
+export function useLoading(instance: ChartInstance | null, loading: boolean) {
+  useEffect(() => {
+    if (!instance) {
+      return;
+    }
+
+    try {
+      if (loading) {
+        instance.showLoading();
+      } else {
+        instance.hideLoading();
+      }
+    } catch (e) {
+      console.warn('Failed to set chart loading state:', e);
+    }
+  }, [instance, loading]);
+}
+
+/**
+ * 使用图表主题
+ * @param theme 主题名称或配置
+ * @param darkMode 是否为暗黑模式
+ * @returns 处理后的主题
+ */
+export function useChartTheme(theme: string | Record<string, any>, darkMode = false) {
+  return useMemo(() => {
+    if (typeof theme === 'string') {
+      return darkMode ? 'dark' : theme;
+    }
+
+    return theme;
+  }, [theme, darkMode]);
+}
+
+/**
+ * 使用图表数据变更
+ * @param data 数据源
+ * @param transformer 数据转换函数
+ * @returns 转换后的图表选项
+ */
+export function useChartData<T = any>(data: T[] | null, transformer: (data: T[]) => ChartOptions) {
+  return useMemo(() => {
+    if (!data || data.length === 0) {
+      return { series: [] };
+    }
+
+    return transformer(data);
+  }, [data, transformer]);
+}
+
+// 导出版本号
+export const version = '1.1.1';
+
+// 导出所有hooks到默认导出对象
+const hooks = {
+  useChart,
+  useOption,
+  useResize,
+  useEvents,
+  useLoading,
+  useChartTheme,
+  useChartData,
+};
+
+// 为了同时支持具名导入和默认导入
+export default hooks;

package/src/index.ts

@@ -0,0 +1,75 @@
+/**
+ * TaroViz - 基于 Taro 和 ECharts 的多端图表组件库
+ * @version 1.1.1
+ */
+
+// 核心组件
+export type { ChartProps } from './core/components/BaseChart';
+export { default as BaseChart } from './core/components/BaseChart';
+
+// 核心类型
+export type {
+  EChartsType,
+  EChartsOption,
+  AnimationEasing,
+  RendererType,
+  ChartEventCallback,
+  ChartEventHandlers,
+  ThemeType,
+  RenderOptimizationConfig,
+  Adapter,
+  AdapterConfig,
+} from './core/types';
+
+// 核心工具函数
+export {
+  events,
+  deepMerge,
+  debounce,
+  throttle,
+  getEnvironment,
+  formatNumber,
+  getContrastColor,
+  uuid,
+  shortId,
+  prefixedId,
+} from './core/utils';
+
+// 图表组件
+export { default as LineChart } from './charts/line';
+export { default as BarChart } from './charts/bar';
+export { default as PieChart } from './charts/pie';
+export { default as ScatterChart } from './charts/scatter';
+export { default as RadarChart } from './charts/radar';
+export { default as HeatmapChart } from './charts/heatmap';
+export { default as GaugeChart } from './charts/gauge';
+export { default as FunnelChart } from './charts/funnel';
+
+// 适配器
+export { getAdapter, detectPlatform, getEnv } from './adapters';
+export { default as H5Adapter } from './adapters/h5';
+export { default as WeappAdapter } from './adapters/weapp';
+
+// 主题
+export type { BuiltinTheme, ThemeOptions } from './themes';
+export { defaultTheme, darkTheme, getTheme, registerTheme } from './themes';
+
+// 编辑器
+export { ThemeEditor } from './editor';
+
+// Hooks
+export {
+  useChart,
+  useOption,
+  useResize,
+  useEvents,
+  useLoading,
+  useChartTheme,
+  useChartData,
+} from './hooks';
+
+/**
+ * 库信息
+ */
+export const name = 'taroviz';
+export const version = '1.1.1';