@antv/gpt-vis 0.6.0 → 1.0.0-beta.1

package/src/vis/violin/index.ts

@@ -0,0 +1,216 @@
+import { Chart } from '@antv/g2';
+import type { VisualizationOptions } from '../../types';
+import { getBackgroundColor, getThemeColors, getThemeObject } from '../../util/theme';
+
+/**
+ * ViolinDataItem is the type for each data item in the violin chart.
+ */
+export type ViolinDataItem = {
+  category: string;
+  value: number;
+  group?: string;
+};
+
+/**
+ * ViolinConfig defines the configuration for rendering the violin chart.
+ */
+export interface ViolinConfig {
+  type?: 'violin';
+  data: ViolinDataItem[];
+  theme?: 'default' | 'academy' | 'dark';
+  title?: string;
+  axisXTitle?: string;
+  axisYTitle?: string;
+  style?: {
+    backgroundColor?: string;
+    palette?: string[];
+    startAtZero?: boolean;
+  };
+}
+
+/**
+ * ViolinInstance represents a violin chart instance with render and destroy.
+ */
+export interface ViolinInstance {
+  render: (config: ViolinConfig) => void;
+  destroy: () => void;
+}
+
+/**
+ * Violin chart component using G2 5.0.
+ *
+ * @example
+ * ```ts
+ * const violin = Violin({
+ *   container: '#container',
+ *   width: 600,
+ *   height: 400,
+ * });
+ *
+ * violin.render({
+ *   type: 'violin',
+ *   data: [
+ *     { category: '班级A', value: 15 },
+ *     { category: '班级A', value: 18 },
+ *     { category: '班级A', value: 22 },
+ *     { category: '班级A', value: 27 },
+ *     { category: '班级A', value: 35 },
+ *   ],
+ *   theme: 'academy'
+ * });
+ *
+ * violin.destroy();
+ * ```
+ */
+export const Violin = (options: VisualizationOptions): ViolinInstance => {
+  const { container, width, height, theme: chartTheme = 'default' } = options;
+  let chart: Chart | null = null;
+
+  /**
+   * Render the violin chart with the given configuration.
+   */
+  const render = (config: ViolinConfig): void => {
+    const { data = [], theme = chartTheme, title, axisXTitle, axisYTitle, style = {} } = config;
+
+    // Clean up previous chart if exists
+    if (chart) {
+      chart.destroy();
+    }
+
+    // Get colors from style.palette or theme defaults
+    const colors = style.palette || getThemeColors(theme);
+    const backgroundColor = style.backgroundColor || getBackgroundColor(theme);
+    const startAtZero = style.startAtZero || false;
+
+    // Determine if data has group field for grouped violin plot
+    const hasGroupField = (data || [])[0]?.group !== undefined;
+
+    // Create chart
+    chart = new Chart({
+      container,
+      width,
+      height,
+      autoFit: true,
+    });
+
+    // Configure chart children for violin plot
+    // Violin plot is composed of density plot + boxplot overlay
+    let children = [];
+
+    if (hasGroupField) {
+      // Grouped violin plot: density by category and group
+      children = [
+        {
+          type: 'density',
+          data: {
+            transform: [{ type: 'kde', field: 'value', groupBy: ['category', 'group'] }],
+          },
+          encode: {
+            x: 'category',
+            y: 'y',
+            color: 'group',
+            series: 'group',
+            size: 'size',
+          },
+          scale: {
+            y: { nice: true },
+            color: { range: colors },
+          },
+        },
+        {
+          type: 'boxplot',
+          encode: {
+            x: 'category',
+            y: 'value',
+            series: 'group',
+            color: 'group',
+            shape: 'violin',
+          },
+          style: { opacity: 0.5, strokeOpacity: 0.5, point: false },
+          scale: {
+            y: { nice: true },
+            color: { range: colors },
+          },
+        },
+      ];
+    } else {
+      // Simple violin plot: density by category only
+      children = [
+        {
+          type: 'density',
+          data: {
+            transform: [{ type: 'kde', field: 'value', groupBy: ['category'], size: 20 }],
+          },
+          encode: {
+            x: 'category',
+            y: 'y',
+            color: 'category',
+            size: 'size',
+          },
+          scale: {
+            y: { nice: true },
+            color: { range: colors },
+          },
+        },
+        {
+          type: 'boxplot',
+          encode: {
+            x: 'category',
+            y: 'value',
+            color: 'category',
+            shape: 'violin',
+          },
+          style: { opacity: 0.5, strokeOpacity: 0.5, point: false },
+          scale: {
+            y: { nice: true },
+            color: { range: colors },
+          },
+        },
+      ];
+    }
+
+    // Configure chart options
+    // Note: Using 'any' type due to G2's complex type system with transformations
+    // This is consistent with how G2 5.0 is used elsewhere in the codebase
+    const chartOptions: any = {
+      type: 'view',
+      data,
+      title: title ?? '',
+      axis: {
+        x: {
+          title: axisXTitle || false,
+        },
+        y: {
+          title: axisYTitle || false,
+        },
+      },
+      scale: {
+        y: { nice: true, zero: startAtZero },
+      },
+      children: children,
+      legend: {
+        color: hasGroupField ? { position: 'top' } : false,
+      },
+      ...(backgroundColor ? { viewStyle: { viewFill: backgroundColor } } : {}),
+      theme: getThemeObject(theme),
+    };
+
+    chart.options(chartOptions);
+    chart.render();
+  };
+
+  /**
+   * Destroy the chart instance and clean up resources.
+   */
+  const destroy = (): void => {
+    if (chart) {
+      chart.destroy();
+      chart = null;
+    }
+  };
+
+  return {
+    render,
+    destroy,
+  };
+};

package/src/vis/waterfall/README.md

@@ -0,0 +1,178 @@
+# Waterfall
+
+A waterfall chart component for displaying cumulative effects of sequential values, built with G2 5.0.
+
+## Usage
+
+```ts
+import { Waterfall } from '@antv/gpt-vis/ai';
+
+const waterfall = Waterfall({
+  container: '#container',
+  width: 600,
+  height: 400,
+});
+
+waterfall.render({
+  data: [
+    { category: '期初利润', value: 100 },
+    { category: '销售收入', value: 80 },
+    { category: '运营成本', value: -50 },
+    { category: '税费', value: -20 },
+    { category: '总计', isTotal: true },
+  ],
+});
+
+waterfall.destroy();
+```
+
+## Configuration
+
+### Constructor Options (WaterfallOptions)
+
+| Property  | Type                  | Default | Description                   |
+| --------- | --------------------- | ------- | ----------------------------- |
+| container | string \| HTMLElement | -       | Container element or selector |
+| width     | number                | 640     | Chart width in pixels         |
+| height    | number                | 480     | Chart height in pixels        |
+
+### Render Config (WaterfallConfig)
+
+| Property   | Type   | Default   | Description               |
+| ---------- | ------ | --------- | ------------------------- |
+| data       | Array  | -         | Chart data array          |
+| theme      | string | 'default' | Color theme               |
+| title      | string | -         | Chart title               |
+| axisXTitle | string | -         | X-axis title              |
+| axisYTitle | string | -         | Y-axis title              |
+| style      | object | -         | Chart style configuration |
+
+### Data Structure
+
+```ts
+type WaterfallDataItem = {
+  category: string; // Step or category name (required)
+  value?: number; // Increment or decrement value (optional)
+  isIntermediateTotal?: boolean; // Whether it's an intermediate total (optional)
+  isTotal?: boolean; // Whether it's the final total (optional)
+};
+```
+
+### Style Options
+
+```ts
+style?: {
+  backgroundColor?: string;  // Background color
+  palette?: {
+    positiveColor?: string;  // Color for positive values (default: '#FF4D4F')
+    negativeColor?: string;  // Color for negative values (default: '#2EBB59')
+    totalColor?: string;     // Color for total bars (default: '#1783FF')
+  };
+}
+```
+
+## Examples
+
+### Basic Example
+
+```ts
+waterfall.render({
+  data: [
+    { category: '期初利润', value: 100 },
+    { category: '销售收入', value: 80 },
+    { category: '运营成本', value: -50 },
+    { category: '税费', value: -20 },
+    { category: '总计', isTotal: true },
+  ],
+});
+```
+
+### With Theme
+
+```ts
+waterfall.render({
+  data: [
+    { category: '基础预算', value: 500 },
+    { category: '市场投入', value: 120 },
+    { category: '采购优化', value: -60 },
+    { category: '运营效率', value: -30 },
+    { category: '总利润', isTotal: true },
+  ],
+  theme: 'dark',
+  title: '预算执行情况',
+});
+```
+
+### With Custom Colors
+
+```ts
+waterfall.render({
+  data: [
+    { category: 'Q1 收入', value: 1000 },
+    { category: 'Q2 收入', value: 1200 },
+    { category: '成本', value: -800 },
+    { category: '净利润', isTotal: true },
+  ],
+  title: '季度财务报告',
+  style: {
+    palette: {
+      positiveColor: '#52c41a',
+      negativeColor: '#f5222d',
+      totalColor: '#1890ff',
+    },
+  },
+});
+```
+
+### With Intermediate Total
+
+```ts
+waterfall.render({
+  data: [
+    { category: '基础预算', value: 500 },
+    { category: '市场投入', value: 120 },
+    { category: '总投入', isIntermediateTotal: true },
+    { category: '采购优化', value: -60 },
+    { category: '运营效率', value: -30 },
+    { category: '总利润', isTotal: true },
+  ],
+  title: '预算分析',
+});
+```
+
+### With Axis Titles
+
+```ts
+waterfall.render({
+  data: [
+    { category: '期初', value: 100 },
+    { category: '收入', value: 80 },
+    { category: '支出', value: -50 },
+    { category: '期末', isTotal: true },
+  ],
+  axisXTitle: '项目',
+  axisYTitle: '金额（万元）',
+  title: '财务流水',
+});
+```
+
+### With Background Color
+
+```ts
+waterfall.render({
+  data: [
+    { category: '初始', value: 50 },
+    { category: '增长', value: 30 },
+    { category: '减少', value: -10 },
+    { category: '最终', isTotal: true },
+  ],
+  style: {
+    backgroundColor: '#f0f2f5',
+  },
+});
+```
+
+## Methods
+
+- `render(config: WaterfallConfig): void` - Render or update the chart
+- `destroy(): void` - Destroy the chart instance and clean up resources

package/src/vis/waterfall/index.ts

@@ -0,0 +1,258 @@
+import { Chart } from '@antv/g2';
+import type { VisualizationOptions } from '../../types';
+import { getBackgroundColor, getThemeObject } from '../../util/theme';
+
+/**
+ * WaterfallDataItem is the type for each data item in the waterfall chart.
+ */
+export type WaterfallDataItem = {
+  category: string;
+  value?: number;
+  isIntermediateTotal?: boolean;
+  isTotal?: boolean;
+};
+
+/**
+ * WaterfallPalette defines custom colors for positive, negative, total bars.
+ */
+export interface WaterfallPalette {
+  positiveColor?: string;
+  negativeColor?: string;
+  totalColor?: string;
+}
+
+/**
+ * WaterfallConfig defines the configuration for rendering the waterfall chart.
+ */
+export interface WaterfallConfig {
+  type?: 'waterfall';
+  data: WaterfallDataItem[];
+  theme?: 'default' | 'academy' | 'dark';
+  title?: string;
+  axisXTitle?: string;
+  axisYTitle?: string;
+  style?: {
+    backgroundColor?: string;
+    palette?: WaterfallPalette;
+  };
+}
+
+/**
+ * WaterfallInstance represents a waterfall chart instance with render/destroy.
+ */
+export interface WaterfallInstance {
+  render: (config: WaterfallConfig) => void;
+  destroy: () => void;
+}
+
+// Default colors for waterfall chart
+const DEFAULT_POSITIVE_COLOR = '#FF4D4F';
+const DEFAULT_NEGATIVE_COLOR = '#2EBB59';
+const DEFAULT_TOTAL_COLOR = '#1783FF';
+
+/**
+ * Transform waterfall data to add __start__ and __end__ fields
+ * for proper rendering of stacked intervals
+ */
+function transformWaterfallData(data: WaterfallDataItem[]) {
+  let cumulative = 0;
+  let lastIntermediateTotalEnd = 0;
+  let totalSum = 0;
+
+  return data.map((item) => {
+    const value = item.value || 0;
+    let start: number;
+    let end: number;
+
+    if (item.isTotal) {
+      start = 0;
+      end = totalSum;
+    } else if (item.isIntermediateTotal) {
+      start = lastIntermediateTotalEnd;
+      end = cumulative;
+      lastIntermediateTotalEnd = end;
+    } else {
+      start = cumulative;
+      end = cumulative + value;
+      cumulative = end;
+      totalSum += value;
+    }
+
+    return {
+      ...item,
+      __start__: start,
+      __end__: end,
+      __value__: item.isTotal ? totalSum : item.isIntermediateTotal ? end - start : value,
+    };
+  });
+}
+
+/**
+ * Generate link data for connecting waterfall bars
+ * Each link connects the end of the previous bar to the start of the current bar
+ */
+function generateLinkData(data: any[]) {
+  return data.reduce((result: any[], current: any, index: number) => {
+    if (index > 0) {
+      const previous = data[index - 1];
+      result.push({
+        x: [previous.category, current.category],
+        y: current.isTotal || current.isIntermediateTotal ? current.__end__ : current.__start__,
+      });
+    }
+    return result;
+  }, []);
+}
+
+/**
+ * Waterfall chart component using G2 5.0.
+ *
+ * @example
+ * ```ts
+ * const waterfall = Waterfall({
+ *   container: '#container',
+ *   width: 600,
+ *   height: 400,
+ * });
+ *
+ * waterfall.render({
+ *   type: 'waterfall',
+ *   data: [
+ *     { category: '期初利润', value: 100 },
+ *     { category: '销售收入', value: 80 },
+ *     { category: '运营成本', value: -50 },
+ *     { category: '税费', value: -20 },
+ *     { category: '总计', isTotal: true },
+ *   ],
+ *   theme: 'academy'
+ * });
+ *
+ * waterfall.destroy();
+ * ```
+ */
+export const Waterfall = (options: VisualizationOptions): WaterfallInstance => {
+  const { container, width, height, theme: chartTheme = 'default' } = options;
+  let chart: Chart | null = null;
+
+  /**
+   * Render the waterfall chart with the given configuration.
+   */
+  const render = (config: WaterfallConfig): void => {
+    const { data = [], theme = chartTheme, title, axisXTitle, axisYTitle, style = {} } = config;
+
+    // Clean up previous chart if exists
+    if (chart) {
+      chart.destroy();
+    }
+
+    // Get colors from style.palette or defaults
+    const backgroundColor = style.backgroundColor || getBackgroundColor(theme);
+    const palette = style.palette || {};
+    const positiveColor = palette.positiveColor || DEFAULT_POSITIVE_COLOR;
+    const negativeColor = palette.negativeColor || DEFAULT_NEGATIVE_COLOR;
+    const totalColor = palette.totalColor || DEFAULT_TOTAL_COLOR;
+
+    // Transform data to include __start__ and __end__ fields
+    const transformedData = transformWaterfallData(data);
+
+    // Generate link data for connecting lines
+    const linkData = generateLinkData(transformedData);
+
+    // Create chart
+    chart = new Chart({
+      container,
+      width,
+      height,
+      autoFit: true,
+    });
+
+    // Configure chart options
+    // Note: Using 'any' type due to G2's complex type system with transformations
+    // This is consistent with how G2 5.0 is used elsewhere in the codebase
+    const chartOptions: any = {
+      type: 'view',
+      data: transformedData,
+      title: title ?? '',
+      marginRight: 28,
+      axis: {
+        x: {
+          title: axisXTitle || false,
+        },
+        y: {
+          title: axisYTitle || false,
+          labelFormatter: '~s',
+        },
+      },
+      scale: {
+        y: { nice: true },
+      },
+      children: [
+        {
+          type: 'interval',
+          data: transformedData,
+          encode: { x: 'category', y: ['__start__', '__end__'], color: 'category' },
+          style: {
+            maxWidth: 60,
+            stroke: '#666',
+            radius: 4,
+            fill: (d: any) => {
+              return d.isTotal || d.isIntermediateTotal
+                ? totalColor
+                : d.__value__ > 0
+                  ? positiveColor
+                  : negativeColor;
+            },
+          },
+          labels: [
+            {
+              text: '__value__',
+              position: 'inside',
+              fontSize: 10,
+              transform: [{ type: 'overflowHide' }],
+              formatter: '~s',
+              fill: '#000',
+              fontWeight: 600,
+              stroke: '#fff',
+            },
+          ],
+        },
+        {
+          type: 'link',
+          data: linkData,
+          encode: {
+            x: 'x',
+            y: 'y',
+          },
+          zIndex: -1,
+          style: {
+            stroke: '#ccc',
+            lineDash: [4, 2],
+            lineWidth: 1,
+          },
+          tooltip: false,
+        },
+      ],
+      legend: false,
+      ...(backgroundColor ? { viewStyle: { viewFill: backgroundColor } } : {}),
+      theme: getThemeObject(theme),
+    };
+
+    chart.options(chartOptions);
+    chart.render();
+  };
+
+  /**
+   * Destroy the chart instance and clean up resources.
+   */
+  const destroy = (): void => {
+    if (chart) {
+      chart.destroy();
+      chart = null;
+    }
+  };
+
+  return {
+    render,
+    destroy,
+  };
+};