@agions/taroviz 1.11.1 → 2.0.3

package/src/charts/common/BaseChartWrapper.tsx

@@ -36,8 +36,8 @@ function buildAriaLabel(chartType: string, option: unknown): string {
 }
 
 // ─── Keyboard navigation step sizes ───────────────────────────────────────
-const ZOOM_STEP = 5;   // % per key press
-const PAN_STEP = 10;   // % pan per arrow key
+const ZOOM_STEP = 5; // % per key press
+const PAN_STEP = 10; // % pan per arrow key
 
 const BaseChartWrapper: React.FC<BaseChartProps & { chartType: string }> = ({
   option,
@@ -60,80 +60,77 @@ const BaseChartWrapper: React.FC<BaseChartProps & { chartType: string }> = ({
   const containerRef = useRef<HTMLDivElement>(null);
   const isMountedRef = useRef(true);
   const cleanupRef = useRef<(() => void) | null>(null);
-  const tableId = useId();          // unique id for aria-describedby
+  const tableId = useId(); // unique id for aria-describedby
   const seriesData = useMemo(() => extractSeriesData(option), [option]);
   const ariaLabel = useMemo(() => buildAriaLabel(chartType, option), [chartType, option]);
 
-  // Keyboard handler for zoom/pan — attached to the chart container
-  const handleKeyDown = useCallback(
-    (e: React.KeyboardEvent<HTMLDivElement>) => {
-      const instance = chartInstance.current;
-      if (!instance) return;
+  // Keyboard _handler for zoom/pan — attached to the chart container
+  const handleKeyDown = useCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
+    const instance = chartInstance.current;
+    if (!instance) return;
 
-      // ECharts dataZoom dispatch — works for any chart with dataZoom axis
-      const dispatchZoom = (startDelta: number, endDelta: number) => {
-        instance.dispatchAction({ type: 'dataZoom', startDelta, endDelta });
-      };
+    // ECharts dataZoom dispatch — works for any chart with dataZoom axis
+    const dispatchZoom = (startDelta: number, endDelta: number) => {
+      instance.dispatchAction({ type: 'dataZoom', startDelta, endDelta });
+    };
 
-      // Home = reset zoom to full range
-      if (e.key === 'Home') {
-        e.preventDefault();
-        instance.dispatchAction({ type: 'dataZoom', start: 0, end: 100 });
-        return;
-      }
+    // Home = reset zoom to full range
+    if (e.key === 'Home') {
+      e.preventDefault();
+      instance.dispatchAction({ type: 'dataZoom', start: 0, end: 100 });
+      return;
+    }
 
-      switch (e.key) {
-        case '+':
-        case '=': {
-          e.preventDefault();
-          // Zoom in (narrow range) — decrease end by ZOOM_STEP
-          const end = instance.getOption() as { dataZoom?: Array<{ start?: number; end?: number }> };
-          const dz = end?.dataZoom?.[0];
-          if (dz) {
-            const newEnd = Math.max(0, (dz.end ?? 100) - ZOOM_STEP);
-            const newStart = Math.max(0, (dz.start ?? 0) - ZOOM_STEP);
-            instance.dispatchAction({ type: 'dataZoom', start: newStart, end: newEnd });
-          }
-          break;
-        }
-        case '-':
-        case '_': {
-          e.preventDefault();
-          // Zoom out (expand range) — increase end by ZOOM_STEP
-          const end = instance.getOption() as { dataZoom?: Array<{ start?: number; end?: number }> };
-          const dz = end?.dataZoom?.[0];
-          if (dz) {
-            const newEnd = Math.min(100, (dz.end ?? 100) + ZOOM_STEP);
-            const newStart = Math.min((dz.start ?? 0) + ZOOM_STEP, newEnd);
-            instance.dispatchAction({ type: 'dataZoom', start: newStart, end: newEnd });
-          }
-          break;
-        }
-        case 'ArrowLeft': {
-          e.preventDefault();
-          dispatchZoom(-PAN_STEP, 0);
-          break;
-        }
-        case 'ArrowRight': {
-          e.preventDefault();
-          dispatchZoom(PAN_STEP, 0);
-          break;
-        }
-        case 'ArrowUp': {
-          e.preventDefault();
-          dispatchZoom(0, -PAN_STEP);
-          break;
+    switch (e.key) {
+      case '+':
+      case '=': {
+        e.preventDefault();
+        // Zoom in (narrow range) — decrease end by ZOOM_STEP
+        const end = instance.getOption() as { dataZoom?: Array<{ start?: number; end?: number }> };
+        const dz = end?.dataZoom?.[0];
+        if (dz) {
+          const newEnd = Math.max(0, (dz.end ?? 100) - ZOOM_STEP);
+          const newStart = Math.max(0, (dz.start ?? 0) - ZOOM_STEP);
+          instance.dispatchAction({ type: 'dataZoom', start: newStart, end: newEnd });
         }
-        case 'ArrowDown': {
-          e.preventDefault();
-          dispatchZoom(0, PAN_STEP);
-          break;
+        break;
+      }
+      case '-':
+      case '_': {
+        e.preventDefault();
+        // Zoom out (expand range) — increase end by ZOOM_STEP
+        const end = instance.getOption() as { dataZoom?: Array<{ start?: number; end?: number }> };
+        const dz = end?.dataZoom?.[0];
+        if (dz) {
+          const newEnd = Math.min(100, (dz.end ?? 100) + ZOOM_STEP);
+          const newStart = Math.min((dz.start ?? 0) + ZOOM_STEP, newEnd);
+          instance.dispatchAction({ type: 'dataZoom', start: newStart, end: newEnd });
         }
-        // No default — let other keys pass through for accessibility tools
+        break;
       }
-    },
-    []
-  );
+      case 'ArrowLeft': {
+        e.preventDefault();
+        dispatchZoom(-PAN_STEP, 0);
+        break;
+      }
+      case 'ArrowRight': {
+        e.preventDefault();
+        dispatchZoom(PAN_STEP, 0);
+        break;
+      }
+      case 'ArrowUp': {
+        e.preventDefault();
+        dispatchZoom(0, -PAN_STEP);
+        break;
+      }
+      case 'ArrowDown': {
+        e.preventDefault();
+        dispatchZoom(0, PAN_STEP);
+        break;
+      }
+      // No default — let other keys pass through for accessibility tools
+    }
+  }, []);
 
   // Use memo to cache adapter config
   const adapterConfig = useMemo(() => {
@@ -164,8 +161,12 @@ const BaseChartWrapper: React.FC<BaseChartProps & { chartType: string }> = ({
           chartInstance.current = instance;
 
           if (onEvents) {
-            Object.entries(onEvents).forEach(([eventName, handler]) => {
-              (instance as unknown as { on: Function }).on(eventName, handler);
+            Object.entries(onEvents).forEach(([_eventName, _handler]) => {
+              (
+                instance as unknown as {
+                  on: (_event: string, _handler: (..._args: unknown[]) => void) => void;
+                }
+              ).on(_eventName, _handler);
             });
           }
 
@@ -180,6 +181,7 @@ const BaseChartWrapper: React.FC<BaseChartProps & { chartType: string }> = ({
       });
 
       const adapter = await getAdapter(initConfig);
+      const adapterRef = adapter; // store for cleanup
 
       if (!isMountedRef.current) {
         return;
@@ -188,13 +190,15 @@ const BaseChartWrapper: React.FC<BaseChartProps & { chartType: string }> = ({
       adapter.init();
 
       cleanupRef.current = () => {
-        if (chartInstance.current) {
+        adapterRef.dispose?.();
+        const instance = chartInstance.current;
+        if (instance) {
           if (onEvents) {
-            Object.entries(onEvents).forEach(([eventName]) => {
-              (chartInstance.current as unknown as { off: Function }).off(eventName);
+            Object.entries(onEvents).forEach(([_eventName]) => {
+              (instance as unknown as { off: (_event: string) => void }).off(_eventName);
             });
           }
-          chartInstance.current.dispose();
+          instance.dispose();
           chartInstance.current = null;
         }
       };
@@ -262,25 +266,29 @@ const BaseChartWrapper: React.FC<BaseChartProps & { chartType: string }> = ({
         <thead>
           <tr>
             {seriesData.map((s, i) => (
-              <th key={i} scope="col">{s.name}</th>
+              <th key={i} scope="col">
+                {s.name}
+              </th>
             ))}
           </tr>
         </thead>
         <tbody>
           {/* Render up to 20 rows to avoid overwhelming screen readers */}
-          {Array.from({ length: Math.min(20, seriesData[0]?.data.length ?? 0) }).map((_, rowIdx) => (
-            <tr key={rowIdx}>
-              {seriesData.map((s, colIdx) => (
-                <td key={colIdx}>{String(s.data[rowIdx] ?? '')}</td>
-              ))}
-            </tr>
-          ))}
+          {Array.from({ length: Math.min(20, seriesData[0]?.data.length ?? 0) }).map(
+            (_, rowIdx) => (
+              <tr key={rowIdx}>
+                {seriesData.map((s, colIdx) => (
+                  <td key={colIdx}>{String(s.data[rowIdx] ?? '')}</td>
+                ))}
+              </tr>
+            )
+          )}
         </tbody>
       </table>
 
       {/*
         Chart container with role="application" + keyboard navigation.
-        role="application" tells assistive tech to pass through keyboard events.
+        role="application" tells assistive tech to pass through keyboard _events.
         aria-describedby links to the hidden data table above.
       */}
       <div

package/src/charts/common/__mocks__/BaseChartWrapper.tsx

@@ -0,0 +1,17 @@
+/**
+ * BaseChartWrapper 自动 mock
+ * 放在 __mocks__ 目录中，测试文件只需写 jest.mock('../common/BaseChartWrapper') 即可自动加载本 mock
+ */
+import React from 'react';
+
+const MockBaseChartWrapper = (props: Record<string, unknown>) => (
+  <div
+    data-testid="base-chart-wrapper"
+    className={`taroviz-${props.chartType as string} ${(props.className as string) || ''}`}
+    style={{ width: props.width as string, height: props.height as string }}
+  >
+    <div data-testid="chart-option">{JSON.stringify(props.option)}</div>
+  </div>
+);
+
+export default MockBaseChartWrapper;

package/src/charts/createChartComponent.tsx

@@ -0,0 +1,36 @@
+/**
+ * 图表组件创建辅助函数
+ * 为每个图表类型生成带正确 Props 类型的组件
+ */
+
+import React, { memo } from 'react';
+import type { EChartsOption } from 'echarts';
+import BaseChartWrapper from './common/BaseChartWrapper';
+import type { BaseChartProps } from './types';
+
+/**
+ * 创建图表组件
+ * @param displayName 组件名称
+ * @param chartType ECharts 图表类型
+ * @param needOptionCast 是否需要 option 类型转换（用于 boxplot、parallel 等）
+ * @returns 带 displayName 的 memo 组件
+ */
+export function createChartComponent<P extends BaseChartProps = BaseChartProps>(
+  displayName: string,
+  chartType: string,
+  needOptionCast = false
+): React.FC<P> {
+  const Chart: React.FC<P> = memo((props) => (
+    <BaseChartWrapper
+      {...(props as unknown as BaseChartProps)}
+      option={
+        needOptionCast
+          ? ((props as { option?: EChartsOption }).option as EChartsOption)
+          : (props as unknown as BaseChartProps).option
+      }
+      chartType={chartType}
+    />
+  ));
+  Chart.displayName = displayName;
+  return Chart;
+}

package/src/charts/createOptionChartComponent.tsx

@@ -0,0 +1,32 @@
+/**
+ * Factory for charts that follow the buildXxxOption + render pattern.
+ * Eliminates the repeated null-check + BaseChart wrapper code.
+ */
+import React from 'react';
+import BaseChart from '@/core/components/BaseChart';
+import type { BaseChartProps } from './types';
+
+interface OptionBuilderProps {
+  optionMerge?: Record<string, unknown>;
+}
+
+/**
+ * Creates a chart component from a buildOption function.
+ * @param displayName Component display name
+ * @param buildOption Function that builds ECharts option from props, returns null if invalid
+ */
+export function createOptionChartComponent<Props extends OptionBuilderProps>(
+  displayName: string,
+  buildOption: (props: Props) => Record<string, unknown> | null
+): React.FC<Props & Omit<BaseChartProps, 'option' | 'data'>> {
+  const Component: React.FC<Props & Omit<BaseChartProps, 'option' | 'data'>> = (props) => {
+    const { optionMerge, ...rest } = props;
+    const option = buildOption(props as Props);
+    if (!option) {
+      return null;
+    }
+    return <BaseChart option={option as any} {...(rest as BaseChartProps)} />;
+  };
+  Component.displayName = displayName;
+  return Component;
+}

package/src/charts/funnel/__tests__/index.test.tsx

@@ -0,0 +1,99 @@
+/**
+ * FunnelChart 组件测试
+ */
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import FunnelChart from '../index';
+
+// 使用正确的 mock 方式，参考 parallel 图表的测试
+jest.mock('../../common/BaseChartWrapper');
+jest.mock('echarts/charts', () => ({ FunnelChart: jest.fn() }));
+
+describe('FunnelChart', () => {
+  const mockData = [
+    { value: 100, name: '访问' },
+    { value: 80, name: '咨询' },
+    { value: 60, name: '订单' },
+    { value: 40, name: '成交' },
+    { value: 20, name: '退款' },
+  ];
+
+  it('应该渲染漏斗图组件', () => {
+    render(<FunnelChart data={mockData} width={600} height={400} />);
+
+    expect(screen.getByTestId('base-chart-wrapper')).toBeInTheDocument();
+  });
+
+  it('应该传递正确的 option 到 BaseChart', () => {
+    render(<FunnelChart data={mockData} width={600} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series).toBeDefined();
+    expect(option.series.type).toBe('funnel');
+    expect(option.series.data).toEqual(mockData);
+    expect(option.series.sort).toBe('descending');
+  });
+
+  it('当 data 为空时应该返回 null', () => {
+    const { container } = render(<FunnelChart data={[]} width={600} height={400} />);
+
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('应该支持自定义 sort 排序', () => {
+    render(<FunnelChart data={mockData} sort="ascending" width={600} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.sort).toBe('ascending');
+  });
+
+  it('应该支持自定义 align 对齐', () => {
+    render(<FunnelChart data={mockData} align="center" width={600} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.align).toBe('center');
+  });
+
+  it('应该支持自定义 gap 间隙', () => {
+    render(<FunnelChart data={mockData} gap={10} width={600} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.gap).toBe(10);
+  });
+
+  it('应该支持自定义 min/max 高度', () => {
+    render(<FunnelChart data={mockData} min={10} max={120} width={600} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.min).toBe(10);
+    expect(option.series.max).toBe(120);
+  });
+
+  it('应该支持 optionMerge 自定义配置', () => {
+    const customTitle = { title: { text: '漏斗图标题', left: 'center' } };
+
+    render(<FunnelChart data={mockData} optionMerge={customTitle} width={600} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.title).toEqual(customTitle.title);
+  });
+});

package/src/charts/funnel/index.tsx

@@ -1,14 +1,64 @@
 /**
- * FunnelChart组件
+ * TaroViz 漏斗图组件
+ *
+ * 基于 ECharts funnel 系列实现漏斗图可视化
  */
-import React, { memo } from 'react';
-import BaseChartWrapper from '../common/BaseChartWrapper';
-import { FunnelChartProps } from '../types';
-import '@/core/echarts';
-
-const FunnelChart: React.FC<FunnelChartProps> = memo((props) => (
-  <BaseChartWrapper {...props} chartType="funnel-chart" />
-));
-FunnelChart.displayName = 'FunnelChart';
+import { createOptionChartComponent } from '@/charts/createOptionChartComponent';
+import type { FunnelChartProps } from './types';
+// 类型 FunnelDataItem 通过下方 export type 导出供外部使用
+
+/**
+ * 构建漏斗图 ECharts option
+ */
+function buildFunnelOption(props: FunnelChartProps) {
+  const { data, sort, align, gap, min, max, optionMerge } = props;
+
+  // 验证数据
+  if (!data || data.length === 0) {
+    console.warn('[TaroViz] FunnelChart: data is required');
+    return null;
+  }
+
+  // 构建漏斗图 series
+  const series = {
+    type: 'funnel' as const,
+    data: data,
+    sort: sort || 'descending',
+    align: align || 'left',
+    gap: gap || 2,
+    min: min || 0,
+    max: max || 100,
+    label: {
+      show: true,
+      position: 'inside',
+    },
+    emphasis: {
+      itemStyle: {
+        shadowBlur: 10,
+        shadowColor: 'rgba(0, 0, 0, 0.5)',
+      },
+    },
+  };
+
+  const option: any = {
+    tooltip: {
+      trigger: 'item',
+      formatter: (params: any) => {
+        if (!params || !params.data) return '';
+        return `<b>${params.data.name}</b><br/>值: ${params.data.value}`;
+      },
+    },
+    series,
+  };
+
+  // 合并自定义配置
+  if (optionMerge) {
+    Object.assign(option, optionMerge);
+  }
+
+  return option;
+}
+
+const FunnelChart = createOptionChartComponent<FunnelChartProps>('FunnelChart', buildFunnelOption);
 
 export default FunnelChart;

package/src/charts/funnel/types.ts

@@ -0,0 +1,6 @@
+/**
+ * TaroViz 漏斗图类型定义
+ *
+ * 从主 types 文件导入基础类型，只导出组件特有的类型
+ */
+export type { FunnelChartProps, FunnelDataItem, FunnelLabel } from '../types';

package/src/charts/graph/__tests__/index.test.tsx

@@ -1,47 +1,116 @@
 /**
- * @version v1.5.0
+ * GraphChart 组件测试
  */
-
 import React from 'react';
-import { render } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
 import GraphChart from '../index';
 
+// 使用正确的 mock 方式，参考 parallel 图表的测试
+jest.mock('../../common/BaseChartWrapper');
+jest.mock('echarts/charts', () => ({ GraphChart: jest.fn() }));
+
 describe('GraphChart', () => {
-  it('renders without crashing', () => {
-    const { container } = render(<GraphChart />);
-    expect(container).toBeTruthy();
+  const mockNodes = [
+    { id: '1', name: '节点 A', value: 10 },
+    { id: '2', name: '节点 B', value: 20 },
+    { id: '3', name: '节点 C', value: 30 },
+    { id: '4', name: '节点 D', value: 40 },
+  ];
+
+  const mockLinks = [
+    { source: '1', target: '2', value: 5 },
+    { source: '2', target: '3', value: 8 },
+    { source: '3', target: '4', value: 12 },
+  ];
+
+  it('应该渲染关系图组件', () => {
+    render(<GraphChart nodes={mockNodes} links={mockLinks} width={600} height={400} />);
+
+    expect(screen.getByTestId('base-chart-wrapper')).toBeInTheDocument();
+  });
+
+  it('应该传递正确的 option 到 BaseChart', () => {
+    render(<GraphChart nodes={mockNodes} links={mockLinks} width={600} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series).toBeDefined();
+    expect(option.series.type).toBe('graph');
+    expect(option.series.data).toEqual(mockNodes);
+    expect(option.series.links).toEqual(mockLinks);
   });
 
-  it('renders with custom className', () => {
-    const { container } = render(<GraphChart className="test-graph" />);
-    // BaseChartWrapper renders a fragment with a hidden accessibility table (first child)
-    // and the actual chart div (last child), so we query the last child for className
-    const chartDiv = container.lastChild;
-    expect(chartDiv).toHaveClass('test-graph');
+  it('当 nodes 为空时应该返回 null', () => {
+    const { container } = render(
+      <GraphChart nodes={[]} links={mockLinks} width={600} height={400} />
+    );
+
+    expect(container.firstChild).toBeNull();
   });
 
-  it('renders with custom width and height', () => {
-    const { container } = render(<GraphChart width={500} height={400} />);
-    // BaseChartWrapper renders a fragment with a hidden accessibility table (first child)
-    // and the actual chart div (last child), so we query the last child for styles
-    const chartDiv = container.lastChild;
-    expect(chartDiv).toHaveStyle({ width: '500px', height: '400px' });
+  it('应该支持自定义 layout', () => {
+    render(
+      <GraphChart nodes={mockNodes} links={mockLinks} layout="circular" width={600} height={400} />
+    );
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.layout).toBe('circular');
   });
 
-  it('renders with basic option', () => {
-    const option = {
-      series: [
-        {
-          type: 'graph' as const,
-          nodes: [
-            { id: '1', name: 'Node 1' },
-            { id: '2', name: 'Node 2' },
-          ],
-          links: [{ source: '1', target: '2' }],
-        },
-      ],
-    };
-    const { container } = render(<GraphChart option={option} />);
-    expect(container).toBeTruthy();
+  it('应该支持自定义 force 配置', () => {
+    render(
+      <GraphChart
+        nodes={mockNodes}
+        links={mockLinks}
+        layout="force"
+        force={{ repulsion: 200, edgeLength: 100 }}
+        width={600}
+        height={400}
+      />
+    );
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.force).toEqual({ repulsion: 200, edgeLength: 100 });
+  });
+
+  it('应该支持 draggable 配置', () => {
+    render(
+      <GraphChart nodes={mockNodes} links={mockLinks} draggable={true} width={600} height={400} />
+    );
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.draggable).toBe(true);
+  });
+
+  it('应该支持 optionMerge 自定义配置', () => {
+    const customTitle = { title: { text: '关系图标题', left: 'center' } };
+
+    render(
+      <GraphChart
+        nodes={mockNodes}
+        links={mockLinks}
+        optionMerge={customTitle}
+        width={600}
+        height={400}
+      />
+    );
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.title).toEqual(customTitle.title);
   });
 });