@agions/taroviz 1.7.0 → 1.10.0

package/src/hooks/useChartSelection.ts

@@ -0,0 +1,350 @@
+/**
+ * useChartSelection - 图表数据点选择/高亮 Hook
+ * 支持单个/批量选择、反选、清除选择，配合 ECharts select 事件
+ *
+ * 特性：
+ * - 支持按 seriesIndex + dataIndex 选择
+ * - 支持按 dataIndex 跨系列批量选择
+ * - 支持反选（invertSelection）
+ * - 支持多选模式（multi）
+ * - 自动绑定图表 select/unselect 事件
+ */
+import { useEffect, useRef, useCallback, useState } from 'react';
+import type { ChartInstance } from './index';
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+/** 单个数据点的选择键 */
+export interface DataPointKey {
+  seriesIndex: number;
+  dataIndex: number;
+}
+
+/** 选择模式 */
+export type SelectionMode = 'single' | 'multiple';
+
+/** 选择事件参数 */
+export interface SelectionEvent {
+  /** 被选中的数据点 */
+  selected: DataPointKey[];
+  /** 取消选择的数据点 */
+  unselected: DataPointKey[];
+}
+
+/** 选择配置选项 */
+export interface UseChartSelectionOptions {
+  /** 选择模式：'single' 单选，'multiple' 多选，默认 'multiple' */
+  mode?: SelectionMode;
+  /** 是否在组件卸载时清除所有选择，默认 true */
+  clearOnUnmount?: boolean;
+  /** 是否启用 Ctrl+Click 多选，默认 true */
+  enableCtrlMultiSelect?: boolean;
+  /** 是否启用 Shift+Click 范围选择，默认 true */
+  enableShiftRangeSelect?: boolean;
+  /** 选择变化时的回调 */
+  onSelectionChange?: (event: SelectionEvent) => void;
+}
+
+/** 选择返回值 */
+export interface UseChartSelectionReturn {
+  /** 当前选中的数据点 */
+  selectedPoints: DataPointKey[];
+  /** 是否存在选中 */
+  hasSelection: boolean;
+  /** 选中数量 */
+  selectionCount: number;
+  /** 选中指定数据点 */
+  select: (key: DataPointKey) => void;
+  /** 取消选中指定数据点 */
+  deselect: (key: DataPointKey) => void;
+  /** 批量选中 */
+  selectMultiple: (keys: DataPointKey[]) => void;
+  /** 批量取消选中 */
+  deselectMultiple: (keys: DataPointKey[]) => void;
+  /** 切换选中状态 */
+  toggle: (key: DataPointKey) => void;
+  /** 反选 */
+  invertSelection: (seriesIndex: number, dataIndices: number[]) => void;
+  /** 全选指定系列 */
+  selectAll: (seriesIndex: number, dataIndices: number[]) => void;
+  /** 清除所有选择 */
+  clearSelection: () => void;
+  /** 判断某点是否被选中 */
+  isSelected: (key: DataPointKey) => boolean;
+}
+
+// ============================================================================
+// 工具函数
+// ============================================================================
+
+/** 生成唯一键字符串 */
+function keyToString(key: DataPointKey): string {
+  return `${key.seriesIndex}:${key.dataIndex}`;
+}
+
+function stringToKey(str: string): DataPointKey {
+  const [seriesIndex, dataIndex] = str.split(':').map(Number);
+  return { seriesIndex, dataIndex };
+}
+
+// ============================================================================
+// Hook 实现
+// ============================================================================
+
+/**
+ * 使用图表数据点选择功能
+ * @param chartInstance 图表实例
+ * @param options 配置选项
+ * @returns 选择控制接口
+ */
+export function useChartSelection(
+  chartInstance: ChartInstance | null,
+  options: UseChartSelectionOptions = {}
+): UseChartSelectionReturn {
+  const {
+    mode = 'multiple',
+    clearOnUnmount = true,
+    enableCtrlMultiSelect = true,
+    enableShiftRangeSelect = true,
+    onSelectionChange,
+  } = options;
+
+  // 选中点集合（字符串键）
+  const [selectedPoints, setSelectedPoints] = useState<DataPointKey[]>([]);
+
+  // Chart instance ref
+  const chartRef = useRef<ChartInstance | null>(null);
+  chartRef.current = chartInstance;
+
+  // 上一次 shift+click 的数据索引（用于范围选择）
+  const lastShiftIndexRef = useRef<number | null>(null);
+
+  // 当前模式 ref（用于事件处理）
+  const modeRef = useRef(mode);
+  modeRef.current = mode;
+
+  // 绑定图表 select/unselect 事件
+  useEffect(() => {
+    const chart = chartRef.current;
+    if (!chart || !chart.on) return;
+
+    const handleSelect = (params: { selected: Record<string, boolean>; type: string }) => {
+      // ECharts 内置 select 会同步更新 legend
+      // 这里我们用 dispatchAction 来实现纯数据点选择
+    };
+
+    // 单击 legend 时清除数据点选择（保持一致性）
+    const handleLegendSelectChanged = (params: { name?: string; selected?: Record<string, boolean> }) => {
+      // 清除选择时的视觉反馈
+    };
+
+    chart.on('selectchanged', (params: unknown) => {
+      // 当图表内部选择变化时同步状态
+      const p = params as {
+        isFromClick?: boolean;
+        selected?: Record<string, boolean>;
+        notSelected?: Record<string, boolean>;
+      };
+      if (p.isFromClick) {
+        // 用户点击了图例，清除所有数据点选择
+        setSelectedPoints([]);
+        onSelectionChange?.({ selected: [], unselected: [] });
+      }
+    });
+
+    return () => {
+      if (chart.off) {
+        chart.off('selectchanged');
+      }
+    };
+  }, [onSelectionChange]);
+
+  // 组件卸载时清除选择
+  useEffect(() => {
+    return () => {
+      if (clearOnUnmount) {
+        const chart = chartRef.current;
+        if (chart?.dispatchAction) {
+          // 清除所有系列的选择状态
+          chart.dispatchAction({ type: 'unselect' });
+        }
+      }
+    };
+  }, [clearOnUnmount]);
+
+  // ─── 私有方法 ───────────────────────────────────────────────────────────────
+
+  /** 触发选择变化回调 */
+  const notifyChange = useCallback(
+    (selected: DataPointKey[], unselected: DataPointKey[]) => {
+      onSelectionChange?.({ selected, unselected });
+    },
+    [onSelectionChange]
+  );
+
+  /** 执行 ECharts dispatchAction */
+  const dispatchSelect = useCallback(
+    (key: DataPointKey, select: boolean) => {
+      const chart = chartRef.current;
+      if (!chart?.dispatchAction) return;
+      chart.dispatchAction({
+        type: select ? 'select' : 'unselect',
+        seriesIndex: key.seriesIndex,
+        dataIndex: key.dataIndex,
+      });
+    },
+    []
+  );
+
+  // ─── Public API ───────────────────────────────────────────────────────────
+
+  const select = useCallback(
+    (key: DataPointKey) => {
+      setSelectedPoints((prev) => {
+        const str = keyToString(key);
+        if (prev.some((p) => keyToString(p) === str)) return prev;
+        const next = mode === 'single' ? [key] : [...prev, key];
+        notifyChange(next, []);
+        return next;
+      });
+      dispatchSelect(key, true);
+    },
+    [mode, notifyChange, dispatchSelect]
+  );
+
+  const deselect = useCallback(
+    (key: DataPointKey) => {
+      setSelectedPoints((prev) => {
+        const str = keyToString(key);
+        const removed = prev.filter((p) => keyToString(p) !== str);
+        notifyChange([], removed);
+        return removed;
+      });
+      dispatchSelect(key, false);
+    },
+    [notifyChange, dispatchSelect]
+  );
+
+  const toggle = useCallback(
+    (key: DataPointKey) => {
+      const str = keyToString(key);
+      if (selectedPoints.some((p) => keyToString(p) === str)) {
+        deselect(key);
+      } else {
+        select(key);
+      }
+    },
+    [selectedPoints, select, deselect]
+  );
+
+  const selectMultiple = useCallback(
+    (keys: DataPointKey[]) => {
+      setSelectedPoints((prev) => {
+        const newPoints = mode === 'single' ? keys : [...prev, ...keys.filter(
+          (k) => !prev.some((p) => keyToString(p) === keyToString(k))
+        )];
+        notifyChange(newPoints, []);
+        return newPoints;
+      });
+      keys.forEach((key) => dispatchSelect(key, true));
+    },
+    [mode, notifyChange, dispatchSelect]
+  );
+
+  const deselectMultiple = useCallback(
+    (keys: DataPointKey[]) => {
+      setSelectedPoints((prev) => {
+        const keySet = new Set(keys.map(keyToString));
+        const removed = prev.filter((p) => keySet.has(keyToString(p)));
+        const remaining = prev.filter((p) => !keySet.has(keyToString(p)));
+        notifyChange([], removed);
+        return remaining;
+      });
+      keys.forEach((key) => dispatchSelect(key, false));
+    },
+    [notifyChange, dispatchSelect]
+  );
+
+  const invertSelection = useCallback(
+    (seriesIndex: number, dataIndices: number[]) => {
+      setSelectedPoints((prev) => {
+        const selectedSet = new Set(prev.filter((p) => p.seriesIndex === seriesIndex).map((p) => p.dataIndex));
+        const toSelect: DataPointKey[] = [];
+        const toDeselect: DataPointKey[] = [];
+
+        dataIndices.forEach((dataIndex) => {
+          const key = { seriesIndex, dataIndex };
+          const str = keyToString(key);
+          if (selectedSet.has(dataIndex)) {
+            toDeselect.push(key);
+          } else {
+            toSelect.push(key);
+          }
+        });
+
+        toDeselect.forEach((k) => dispatchSelect(k, false));
+        toSelect.forEach((k) => dispatchSelect(k, true));
+
+        const newSelected = prev.filter(
+          (p) => !(p.seriesIndex === seriesIndex && selectedSet.has(p.dataIndex))
+        ).concat(toSelect);
+
+        notifyChange(toSelect, toDeselect);
+        return newSelected;
+      });
+    },
+    [notifyChange, dispatchSelect]
+  );
+
+  const selectAll = useCallback(
+    (seriesIndex: number, dataIndices: number[]) => {
+      const keys = dataIndices.map((dataIndex) => ({ seriesIndex, dataIndex }));
+      setSelectedPoints((prev) => {
+        const newPoints = mode === 'single' ? keys : [...prev, ...keys.filter(
+          (k) => !prev.some((p) => keyToString(p) === keyToString(k))
+        )];
+        notifyChange(newPoints, []);
+        return newPoints;
+      });
+      keys.forEach((key) => dispatchSelect(key, true));
+    },
+    [mode, notifyChange, dispatchSelect]
+  );
+
+  const clearSelection = useCallback(() => {
+    const chart = chartRef.current;
+    if (chart?.dispatchAction) {
+      chart.dispatchAction({ type: 'unselect' });
+    }
+    const prev = selectedPoints;
+    setSelectedPoints([]);
+    notifyChange([], prev);
+  }, [selectedPoints, notifyChange]);
+
+  const isSelected = useCallback(
+    (key: DataPointKey) => {
+      const str = keyToString(key);
+      return selectedPoints.some((p) => keyToString(p) === str);
+    },
+    [selectedPoints]
+  );
+
+  return {
+    selectedPoints,
+    hasSelection: selectedPoints.length > 0,
+    selectionCount: selectedPoints.length,
+    select,
+    deselect,
+    selectMultiple,
+    deselectMultiple,
+    toggle,
+    invertSelection,
+    selectAll,
+    clearSelection,
+    isSelected,
+  };
+}
+
+export default useChartSelection;

package/src/hooks/usePerformance.ts

@@ -0,0 +1,291 @@
+/**
+ * usePerformance - 图表性能监控 Hook
+ * 提供实时性能指标监控和报告功能
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { PerformanceAnalyzer, PerformanceMetricType, PerformanceMetric } from '../core/utils/performance';
+
+/**
+ * 性能监控配置
+ */
+export interface UsePerformanceOptions {
+  /** 是否启用监控 */
+  enabled?: boolean;
+  /** 采样间隔 (ms) */
+  sampleInterval?: number;
+  /** 是否显示实时 FPS */
+  showFPS?: boolean;
+  /** FPS 告警阈值 */
+  fpsWarningThreshold?: number;
+  /** FPS 严重告警阈值 */
+  fpsCriticalThreshold?: number;
+  /** 自动启动 */
+  autoStart?: boolean;
+}
+
+/**
+ * 性能指标状态
+ */
+export interface PerformanceState {
+  /** 当前 FPS */
+  fps: number;
+  /** 平均 FPS */
+  avgFps: number;
+  /** 最低 FPS */
+  minFps: number;
+  /** 最高 FPS */
+  maxFps: number;
+  /** FPS 状态: normal | warning | critical */
+  fpsStatus: 'normal' | 'warning' | 'critical';
+  /** 帧率历史 */
+  fpsHistory: number[];
+  /** 是否正在监控 */
+  isMonitoring: boolean;
+}
+
+/**
+ * 性能监控返回值
+ */
+export interface UsePerformanceReturn {
+  /** 性能状态 */
+  state: PerformanceState;
+  /** 开始监控 */
+  start: () => void;
+  /** 停止监控 */
+  stop: () => void;
+  /** 重置统计数据 */
+  reset: () => void;
+  /** 获取性能报告 */
+  getReport: () => PerformanceMetric[];
+  /** FPS 告警回调 */
+  onFpsWarning?: (fps: number) => void;
+}
+
+/**
+ * 使用图表性能监控
+ * @param options 配置选项
+ * @returns 性能监控接口
+ */
+export function usePerformance(options: UsePerformanceOptions = {}): UsePerformanceReturn {
+  const {
+    enabled = true,
+    sampleInterval = 1000,
+    showFPS = true,
+    fpsWarningThreshold = 30,
+    fpsCriticalThreshold = 15,
+    autoStart = true,
+  } = options;
+
+  // Refs
+  const analyzerRef = useRef<PerformanceAnalyzer | null>(null);
+  const fpsHistoryRef = useRef<number[]>([]);
+  const animationFrameRef = useRef<number | null>(null);
+  const lastFrameTimeRef = useRef<number>(0);
+  const fpsAccumulatorRef = useRef<{ frames: number; lastTime: number }>({ frames: 0, lastTime: 0 });
+
+  // State
+  const [state, setState] = useState<PerformanceState>({
+    fps: 60,
+    avgFps: 60,
+    minFps: 60,
+    maxFps: 60,
+    fpsStatus: 'normal',
+    fpsHistory: [],
+    isMonitoring: false,
+  });
+
+  /**
+   * 计算 FPS 状态
+   */
+  const calculateFpsStatus = useCallback(
+    (fps: number): 'normal' | 'warning' | 'critical' => {
+      if (fps <= fpsCriticalThreshold) return 'critical';
+      if (fps <= fpsWarningThreshold) return 'warning';
+      return 'normal';
+    },
+    [fpsWarningThreshold, fpsCriticalThreshold]
+  );
+
+  /**
+   * 更新 FPS 计算
+   */
+  const updateFps = useCallback(() => {
+    if (!enabled) return;
+
+    const now = performance.now();
+    const delta = now - lastFrameTimeRef.current;
+    lastFrameTimeRef.current = now;
+
+    // 累积帧数
+    fpsAccumulatorRef.current.frames++;
+
+    // 每秒计算一次 FPS
+    if (now - fpsAccumulatorRef.current.lastTime >= 1000) {
+      const fps = Math.round((fpsAccumulatorRef.current.frames * 1000) / (now - fpsAccumulatorRef.current.lastTime));
+      const history = fpsHistoryRef.current;
+
+      // 更新历史
+      history.push(fps);
+      if (history.length > 60) {
+        history.shift();
+      }
+
+      // 计算统计数据
+      const avgFps = Math.round(history.reduce((a, b) => a + b, 0) / history.length);
+      const minFps = Math.min(...history);
+      const maxFps = Math.max(...history);
+
+      setState(prev => ({
+        ...prev,
+        fps,
+        avgFps,
+        minFps,
+        maxFps,
+        fpsStatus: calculateFpsStatus(fps),
+        fpsHistory: [...history],
+      }));
+
+      // 重置计数器
+      fpsAccumulatorRef.current.frames = 0;
+      fpsAccumulatorRef.current.lastTime = now;
+    }
+
+    // 继续下一帧
+    animationFrameRef.current = requestAnimationFrame(updateFps);
+  }, [enabled, calculateFpsStatus]);
+
+  /**
+   * 开始监控
+   */
+  const start = useCallback(() => {
+    if (!enabled) return;
+
+    // Prevent starting multiple RAF loops
+    if (animationFrameRef.current !== null) return;
+
+    // 初始化分析器
+    if (!analyzerRef.current) {
+      analyzerRef.current = PerformanceAnalyzer.getInstance({
+        enabled: true,
+        sampleInterval,
+        autoStart: false,
+      });
+    }
+
+    analyzerRef.current.start();
+
+    // 重置 FPS 计算
+    fpsAccumulatorRef.current = { frames: 0, lastTime: performance.now() };
+    lastFrameTimeRef.current = performance.now();
+    fpsHistoryRef.current = [];
+
+    // 开始 FPS 监控循环
+    animationFrameRef.current = requestAnimationFrame(updateFps);
+
+    setState(prev => ({ ...prev, isMonitoring: true }));
+  }, [enabled, sampleInterval, updateFps]);
+
+  /**
+   * 停止监控
+   */
+  const stop = useCallback(() => {
+    // 停止 FPS 监控
+    if (animationFrameRef.current !== null) {
+      cancelAnimationFrame(animationFrameRef.current);
+      animationFrameRef.current = null;
+    }
+
+    // 停止分析器
+    analyzerRef.current?.stop();
+
+    setState(prev => ({ ...prev, isMonitoring: false }));
+  }, []);
+
+  /**
+   * 重置统计数据
+   */
+  const reset = useCallback(() => {
+    PerformanceAnalyzer.resetInstance();
+    fpsHistoryRef.current = [];
+    setState(prev => ({
+      ...prev,
+      fps: 60,
+      avgFps: 60,
+      minFps: 60,
+      maxFps: 60,
+      fpsStatus: 'normal',
+      fpsHistory: [],
+    }));
+  }, []);
+
+  /**
+   * 获取性能报告
+   */
+  const getReport = useCallback((): PerformanceMetric[] => {
+    if (!analyzerRef.current) return [];
+
+    try {
+      const report = analyzerRef.current.getAllMetrics?.();
+      if (!report) return [];
+      return Array.from(report.values()).flat();
+    } catch {
+      return [];
+    }
+  }, []);
+
+  // 自动启动
+  useEffect(() => {
+    if (autoStart && enabled) {
+      start();
+    }
+
+    return () => {
+      stop();
+    };
+  }, [autoStart, enabled, start, stop]);
+
+  return {
+    state,
+    start,
+    stop,
+    reset,
+    getReport,
+  };
+}
+
+/**
+ * 轻量级 FPS 监控 Hook
+ * 用于实时显示图表 FPS
+ */
+export function useFpsMonitor(): number {
+  const [fps, setFps] = useState(60);
+  const frameCountRef = useRef(0);
+  const lastTimeRef = useRef(performance.now());
+
+  useEffect(() => {
+    let animationId: number;
+
+    const tick = () => {
+      frameCountRef.current++;
+      const now = performance.now();
+      const elapsed = now - lastTimeRef.current;
+
+      if (elapsed >= 1000) {
+        const currentFps = Math.round((frameCountRef.current * 1000) / elapsed);
+        setFps(currentFps);
+        frameCountRef.current = 0;
+        lastTimeRef.current = now;
+      }
+
+      animationId = requestAnimationFrame(tick);
+    };
+
+    animationId = requestAnimationFrame(tick);
+
+    return () => cancelAnimationFrame(animationId);
+  }, []);
+
+  return fps;
+}
+
+export default usePerformance;

package/src/themes/__tests__/index.test.ts

@@ -1,4 +1,4 @@
-import { getTheme, registerTheme, defaultTheme, darkTheme } from '../index';
+import { getTheme, registerTheme, defaultTheme, darkTheme, getThemeByName } from '../index';
 
 describe('Theme System', () => {
   describe('getTheme', () => {
@@ -11,7 +11,7 @@ describe('Theme System', () => {
       const result = getTheme({ darkMode: true });
       expect(result.darkMode).toBe(true);
       expect(result.theme).toBe('dark');
-      expect(result.backgroundColor).toBe('#0f1117');
+      expect(result.backgroundColor).toBe('#1a1a2e');
     });
 
     it('should merge custom options with defaultTheme', () => {
@@ -50,16 +50,10 @@ describe('Theme System', () => {
   });
 
   describe('registerTheme', () => {
-    it('should log when registering a theme', () => {
-      // Mock console.log
-      const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
-
+    it('should register a theme', () => {
       registerTheme('custom-theme', { backgroundColor: '#123' });
-
-      expect(consoleSpy).toHaveBeenCalledWith('Registering theme: custom-theme');
-
-      // Restore console.log
-      consoleSpy.mockRestore();
+      const result = getThemeByName('custom-theme');
+      expect(result?.backgroundColor).toBe('#123');
     });
   });
 
@@ -70,8 +64,8 @@ describe('Theme System', () => {
       expect(defaultTheme).toHaveProperty('colors');
       expect(Array.isArray(defaultTheme.colors)).toBe(true);
       expect(defaultTheme.colors).toHaveLength(9);
-      expect(defaultTheme).toHaveProperty('backgroundColor', 'transparent');
-      expect(defaultTheme).toHaveProperty('textColor', '#333');
+      expect(defaultTheme).toHaveProperty('backgroundColor', '#ffffff');
+      expect(defaultTheme).toHaveProperty('textColor', '#333333');
       expect(defaultTheme).toHaveProperty('fontFamily');
     });
   });