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

package/src/vis/boxplot/README.md

@@ -0,0 +1,168 @@
+# Boxplot
+
+A boxplot (box-and-whisker plot) component for displaying statistical distribution data, built with G2 5.0.
+
+## Usage
+
+```ts
+import { Boxplot } from '@antv/gpt-vis/ai';
+
+const boxplot = Boxplot({
+  container: '#container',
+  width: 600,
+  height: 400,
+});
+
+boxplot.render({
+  data: [
+    { category: '班级A', value: 15 },
+    { category: '班级A', value: 18 },
+    { category: '班级A', value: 22 },
+    { category: '班级A', value: 27 },
+    { category: '班级A', value: 35 },
+    { category: '班级B', value: 10 },
+    { category: '班级B', value: 14 },
+    { category: '班级B', value: 19 },
+    { category: '班级B', value: 23 },
+    { category: '班级B', value: 30 },
+  ],
+});
+
+boxplot.destroy();
+```
+
+## Configuration
+
+### Constructor Options (BoxplotOptions)
+
+| 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 (BoxplotConfig)
+
+| 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 BoxplotDataItem = {
+  category: string; // Category name (required)
+  value: number; // Data value (required)
+  group?: string; // Group name for grouped boxplots (optional)
+};
+```
+
+### Style Options
+
+```ts
+style?: {
+  backgroundColor?: string;  // Background color
+  palette?: string[];        // Color palette
+  startAtZero?: boolean;     // Whether Y-axis starts at zero
+}
+```
+
+## Examples
+
+### Basic Example
+
+```ts
+boxplot.render({
+  data: [
+    { category: '班级A', value: 15 },
+    { category: '班级A', value: 18 },
+    { category: '班级A', value: 22 },
+    { category: '班级A', value: 27 },
+    { category: '班级A', value: 35 },
+    { category: '班级B', value: 10 },
+    { category: '班级B', value: 14 },
+    { category: '班级B', value: 19 },
+    { category: '班级B', value: 23 },
+    { category: '班级B', value: 30 },
+  ],
+  title: '成绩分布',
+});
+```
+
+### With Theme
+
+```ts
+boxplot.render({
+  data: [
+    { category: '实验组1', value: 12 },
+    { category: '实验组1', value: 15 },
+    { category: '实验组1', value: 20 },
+    { category: '实验组1', value: 25 },
+    { category: '实验组1', value: 30 },
+  ],
+  theme: 'academy',
+  title: '实验数据分布',
+});
+```
+
+### With Custom Styles
+
+```ts
+boxplot.render({
+  data: [
+    { category: '股票A', value: 50 },
+    { category: '股票A', value: 55 },
+    { category: '股票A', value: 60 },
+    { category: '股票A', value: 65 },
+    { category: '股票A', value: 70 },
+  ],
+  title: '金融数据分布',
+  style: {
+    palette: ['#FF9800', '#2196F3'],
+    backgroundColor: '#F5F5F5',
+  },
+});
+```
+
+### Grouped Boxplot
+
+```ts
+boxplot.render({
+  data: [
+    { category: 'Adelie', group: 'MALE', value: 181 },
+    { category: 'Adelie', group: 'FEMALE', value: 186 },
+    { category: 'Adelie', group: 'MALE', value: 190 },
+    { category: 'Adelie', group: 'FEMALE', value: 181 },
+    { category: 'Adelie', group: 'MALE', value: 191 },
+    { category: 'Chinstrap', group: 'MALE', value: 195 },
+    { category: 'Chinstrap', group: 'FEMALE', value: 191 },
+    { category: 'Chinstrap', group: 'MALE', value: 198 },
+  ],
+  title: '帕尔默企鹅身高性别差异',
+});
+```
+
+### Start at Zero
+
+```ts
+boxplot.render({
+  data: [
+    { category: '班级A', value: 15 },
+    { category: '班级A', value: 18 },
+    { category: '班级A', value: 22 },
+  ],
+  style: {
+    startAtZero: true,
+  },
+});
+```
+
+## Methods
+
+- `render(config: BoxplotConfig): void` - Render or update the chart
+- `destroy(): void` - Destroy the chart instance and clean up resources

package/src/vis/boxplot/index.ts

@@ -0,0 +1,162 @@
+import { Chart } from '@antv/g2';
+import type { VisualizationOptions } from '../../types';
+import { getBackgroundColor, getThemeColors, getThemeObject } from '../../util/theme';
+
+/**
+ * BoxplotDataItem is the type for each data item in the boxplot chart.
+ */
+export type BoxplotDataItem = {
+  category: string;
+  value: number;
+  group?: string;
+};
+
+/**
+ * BoxplotConfig defines the configuration for rendering the boxplot chart.
+ */
+export interface BoxplotConfig {
+  type?: 'boxplot';
+  data: BoxplotDataItem[];
+  theme?: 'default' | 'academy' | 'dark';
+  title?: string;
+  axisXTitle?: string;
+  axisYTitle?: string;
+  style?: {
+    backgroundColor?: string;
+    palette?: string[];
+    startAtZero?: boolean;
+  };
+}
+
+/**
+ * BoxplotInstance represents a boxplot chart instance with render and destroy.
+ */
+export interface BoxplotInstance {
+  render: (config: BoxplotConfig) => void;
+  destroy: () => void;
+}
+
+/**
+ * Boxplot chart component using G2 5.0.
+ *
+ * @example
+ * ```ts
+ * const boxplot = Boxplot({
+ *   container: '#container',
+ *   width: 600,
+ *   height: 400,
+ * });
+ *
+ * boxplot.render({
+ *   type: 'boxplot',
+ *   data: [
+ *     { category: '班级A', value: 15 },
+ *     { category: '班级A', value: 18 },
+ *     { category: '班级A', value: 22 },
+ *     { category: '班级A', value: 27 },
+ *     { category: '班级A', value: 35 },
+ *   ],
+ *   theme: 'academy'
+ * });
+ *
+ * boxplot.destroy();
+ * ```
+ */
+export const Boxplot = (options: VisualizationOptions): BoxplotInstance => {
+  const { container, width, height, theme: chartTheme = 'default' } = options;
+  let chart: Chart | null = null;
+
+  /**
+   * Render the boxplot chart with the given configuration.
+   */
+  const render = (config: BoxplotConfig): 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 boxplot
+    const hasGroupField = (data || [])[0]?.group !== undefined;
+    let encode = {};
+
+    if (hasGroupField) {
+      encode = {
+        x: 'category',
+        y: 'value',
+        color: 'group',
+        series: 'group',
+      };
+    } else {
+      encode = {
+        x: 'category',
+        y: 'value',
+        color: 'category',
+      };
+    }
+
+    // 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: 'boxplot',
+      data,
+      title: title ?? '',
+      encode: encode,
+      axis: {
+        x: {
+          title: axisXTitle || false,
+        },
+        y: {
+          title: axisYTitle || false,
+        },
+      },
+      scale: {
+        x: { paddingInner: 0.6, paddingOuter: 0.3 },
+        series: { paddingInner: 0.3, paddingOuter: 0.1 },
+        y: { nice: true, zero: startAtZero },
+        color: { range: colors },
+      },
+      style: { stroke: 'black' },
+      legend: {
+        color: hasGroupField ? { position: 'top' } : false,
+      },
+      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/column/README.md

@@ -0,0 +1,158 @@
+# Column
+
+A vertical column chart component for comparing categorical data, built with G2 5.0.
+
+## Usage
+
+```ts
+import { Column } from '@antv/gpt-vis/ai';
+
+const column = Column({
+  container: '#container',
+  width: 600,
+  height: 400,
+});
+
+column.render({
+  data: [
+    { category: '2015 年', value: 80 },
+    { category: '2016 年', value: 140 },
+    { category: '2017 年', value: 220 },
+  ],
+  title: '海底捞公司外卖收入',
+  axisXTitle: '年份',
+  axisYTitle: '金额 （百万元）',
+});
+
+column.destroy();
+```
+
+## Configuration
+
+### Constructor Options (ColumnOptions)
+
+| 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 (ColumnConfig)
+
+| Property   | Type    | Default   | Description                            |
+| ---------- | ------- | --------- | -------------------------------------- |
+| data       | Array   | -         | Chart data array                       |
+| type       | string  | 'column'  | Chart type identifier                  |
+| group      | boolean | false     | Enable grouping (requires group field) |
+| stack      | boolean | false     | Enable stacking (requires group field) |
+| title      | string  | -         | Chart title                            |
+| axisXTitle | string  | -         | X-axis title                           |
+| axisYTitle | string  | -         | Y-axis title                           |
+| theme      | string  | 'default' | Color theme                            |
+| style      | object  | -         | Chart style configuration              |
+
+### Data Structure
+
+```ts
+type ColumnDataItem = {
+  category: string; // Category name
+  value: number; // Numeric value
+  group?: string; // Optional group name for grouped or stacked charts
+};
+```
+
+### Style Options
+
+| Property        | Type     | Default | Description                                 |
+| --------------- | -------- | ------- | ------------------------------------------- |
+| backgroundColor | string   | -       | Background color of the chart               |
+| palette         | string[] | -       | Array of colors for the chart color palette |
+
+## Examples
+
+### Basic Column Chart
+
+```ts
+column.render({
+  data: [
+    { category: '第一产业', value: 7200.0 },
+    { category: '第二产业', value: 36600.0 },
+    { category: '第三产业', value: 41000.0 },
+  ],
+  axisXTitle: 'title',
+  axisYTitle: 'industrial',
+});
+```
+
+### Grouped Column Chart
+
+```ts
+column.render({
+  data: [
+    { category: '北京', value: 825.6, group: '油车' },
+    { category: '北京', value: 60.2, group: '新能源汽车' },
+    { category: '上海', value: 450, group: '油车' },
+    { category: '上海', value: 95, group: '新能源汽车' },
+    { category: '深圳', value: 506, group: '油车' },
+    { category: '深圳', value: 76.7, group: '新能源汽车' },
+  ],
+  group: true,
+  title: '油车与新能源汽车售卖量',
+  axisXTitle: '城市',
+  axisYTitle: '售卖量 （万辆）',
+});
+```
+
+### Stacked Column Chart
+
+```ts
+column.render({
+  data: [
+    { category: '北京', value: 825.6, group: '油车' },
+    { category: '北京', value: 60.2, group: '新能源汽车' },
+    { category: '上海', value: 450, group: '油车' },
+    { category: '上海', value: 95, group: '新能源汽车' },
+    { category: '深圳', value: 506, group: '油车' },
+    { category: '深圳', value: 76.7, group: '新能源汽车' },
+  ],
+  stack: true,
+  title: '油车与新能源汽车售卖量',
+  axisXTitle: '城市',
+  axisYTitle: '售卖量 （万辆）',
+});
+```
+
+### With Theme
+
+```ts
+column.render({
+  data: [
+    { category: '2015 年', value: 80 },
+    { category: '2016 年', value: 140 },
+    { category: '2017 年', value: 220 },
+  ],
+  theme: 'dark',
+  title: '海底捞公司外卖收入',
+});
+```
+
+### With Custom Styles
+
+```ts
+column.render({
+  data: [
+    { category: '2015 年', value: 80 },
+    { category: '2016 年', value: 140 },
+    { category: '2017 年', value: 220 },
+  ],
+  style: {
+    palette: ['#FF6B6B', '#4ECDC4', '#45B7D1'],
+    backgroundColor: '#F5F5F5',
+  },
+});
+```
+
+## Methods
+
+- `render(config: ColumnConfig): void` - Render or update the chart
+- `destroy(): void` - Destroy the chart instance and clean up resources

package/src/vis/column/index.ts

@@ -0,0 +1,185 @@
+import { Chart } from '@antv/g2';
+import type { VisualizationOptions } from '../../types';
+import { getBackgroundColor, getThemeColors, getThemeObject } from '../../util/theme';
+
+/**
+ * ColumnDataItem is the type for each data item in the column chart.
+ */
+export type ColumnDataItem = {
+  category: string;
+  value: number;
+  group?: string;
+};
+
+/**
+ * ColumnConfig defines the configuration for rendering the column chart.
+ */
+export interface ColumnConfig {
+  type?: 'column';
+  data: ColumnDataItem[];
+  group?: boolean;
+  stack?: boolean;
+  title?: string;
+  axisXTitle?: string;
+  axisYTitle?: string;
+  theme?: 'default' | 'academy' | 'dark';
+  style?: {
+    backgroundColor?: string;
+    palette?: string[];
+  };
+}
+
+/**
+ * ColumnInstance represents a column chart instance with render and destroy methods.
+ */
+export interface ColumnInstance {
+  render: (config: ColumnConfig) => void;
+  destroy: () => void;
+}
+
+/**
+ * Column chart component using G2 5.0.
+ *
+ * @example
+ * ```ts
+ * const column = Column({
+ *   container: '#container',
+ *   width: 600,
+ *   height: 400,
+ * });
+ *
+ * column.render({
+ *   type: 'column',
+ *   data: [
+ *     { category: '2015 年', value: 80 },
+ *     { category: '2016 年', value: 140 },
+ *     { category: '2017 年', value: 220 },
+ *   ],
+ *   title: '海底捞公司外卖收入',
+ *   axisXTitle: '年份',
+ *   axisYTitle: '金额 （百万元）',
+ * });
+ *
+ * column.destroy();
+ * ```
+ */
+export const Column = (options: VisualizationOptions): ColumnInstance => {
+  const { container, width, height, theme: chartTheme = 'default' } = options;
+  let chart: Chart | null = null;
+
+  /**
+   * Render the column chart with the given configuration.
+   */
+  const render = (config: ColumnConfig): void => {
+    const {
+      data = [],
+      theme = chartTheme,
+      title,
+      axisXTitle,
+      axisYTitle,
+      group = false,
+      stack = false,
+      style = {},
+    } = config;
+
+    // Clean up previous chart if exists
+    if (chart) {
+      chart.destroy();
+    }
+
+    const hasGroupField = data.length > 0 && data[0]?.group !== undefined;
+    const colors = style.palette || getThemeColors(theme);
+    const backgroundColor = style.backgroundColor || getBackgroundColor(theme);
+
+    // Create chart
+    chart = new Chart({
+      container,
+      width,
+      height,
+      autoFit: true,
+    });
+
+    // Configure chart encode and transform based on group/stack
+    let encode: any = {};
+    let transform: any = [];
+    let radiusStyle: any = {};
+
+    // Set radius style for default theme
+    if (theme === 'default') {
+      radiusStyle = { radiusTopLeft: 4, radiusTopRight: 4 };
+    }
+
+    // Configure transforms based on group/stack flags
+    if (hasGroupField && group) {
+      transform = [{ type: 'dodgeX' }];
+    }
+
+    if (hasGroupField && stack) {
+      transform = [{ type: 'stackY' }];
+    }
+
+    // Configure encode based on whether data has group field
+    if (hasGroupField) {
+      encode = { x: 'category', y: 'value', color: 'group' };
+    } else {
+      encode = { x: 'category', y: 'value', color: 'category' };
+    }
+
+    // Configure scale
+    const scaleConfig: any = {
+      y: { nice: true },
+      ...(style.palette?.length ? { 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: 'interval',
+      data,
+      title: title ?? '',
+      encode,
+      transform,
+      scale: scaleConfig,
+      axis: {
+        x: { title: axisXTitle || false },
+        y: { title: axisYTitle || false },
+      },
+      legend: hasGroupField ? { color: { position: 'top' } } : false,
+      tooltip: {
+        items: [
+          (d: any) => ({
+            name: axisYTitle || d.category,
+            value: d.value,
+          }),
+        ],
+      },
+      style: {
+        ...radiusStyle,
+        columnWidthRatio: 0.8,
+      },
+      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,
+  };
+};