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

package/src/vis/area/README.md

@@ -0,0 +1,143 @@
+# Area
+
+An area chart component for visualizing trends and total changes over time, built with G2 5.0.
+
+## Usage
+
+```ts
+import { Area } from '@antv/gpt-vis/ai';
+
+const area = Area({
+  container: '#container',
+  width: 600,
+  height: 400,
+});
+
+area.render({
+  data: [
+    { time: '1 月', value: 23.895 },
+    { time: '2 月', value: 23.695 },
+    { time: '3 月', value: 23.655 },
+  ],
+  title: '1月到3月股票价格的变化',
+  axisXTitle: '月份',
+  axisYTitle: '价格',
+});
+
+area.destroy();
+```
+
+## Configuration
+
+### Constructor Options (AreaOptions)
+
+| 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 (AreaConfig)
+
+| Property   | Type    | Default   | Description                            |
+| ---------- | ------- | --------- | -------------------------------------- |
+| data       | Array   | -         | Chart data array                       |
+| type       | string  | 'area'    | Chart type identifier                  |
+| 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 AreaDataItem = {
+  time: string | number; // Time or category value
+  value: number; // Numeric value
+  group?: string; // Optional group name for multi-area 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 |
+| lineWidth       | number   | 2       | Width of the area border line in pixels     |
+
+## Examples
+
+### Basic Area Chart
+
+```ts
+area.render({
+  data: [
+    { time: 2015, value: 7200.0 },
+    { time: 2016, value: 3660.0 },
+    { time: 2017, value: 4100.0 },
+  ],
+  axisXTitle: 'year',
+  axisYTitle: 'value',
+});
+```
+
+### Stacked Area Chart
+
+```ts
+area.render({
+  data: [
+    { time: '2019年', value: 150, group: '北京' },
+    { time: '2020年', value: 160, group: '北京' },
+    { time: '2021年', value: 145, group: '北京' },
+    { time: '2019年', value: 100, group: '广州' },
+    { time: '2020年', value: 110, group: '广州' },
+    { time: '2021年', value: 105, group: '广州' },
+    { time: '2019年', value: 90, group: '上海' },
+    { time: '2020年', value: 85, group: '上海' },
+    { time: '2021年', value: 80, group: '上海' },
+  ],
+  stack: true,
+  title: '城市空气污染指数变化',
+  axisXTitle: '年份',
+  axisYTitle: '空气污染指数',
+});
+```
+
+### With Theme
+
+```ts
+area.render({
+  data: [
+    { time: '1 月', value: 23.895 },
+    { time: '2 月', value: 23.695 },
+    { time: '3 月', value: 23.655 },
+  ],
+  theme: 'dark',
+  title: '股票价格变化',
+});
+```
+
+### With Custom Styles
+
+```ts
+area.render({
+  data: [
+    { time: '1 月', value: 23.895 },
+    { time: '2 月', value: 23.695 },
+    { time: '3 月', value: 23.655 },
+  ],
+  style: {
+    palette: ['#FF6B6B', '#4ECDC4', '#45B7D1'],
+    lineWidth: 3,
+    backgroundColor: '#F5F5F5',
+  },
+});
+```
+
+## Methods
+
+- `render(config: AreaConfig): void` - Render or update the chart
+- `destroy(): void` - Destroy the chart instance and clean up resources

package/src/vis/area/index.ts

@@ -0,0 +1,212 @@
+import { Chart } from '@antv/g2';
+import type { VisualizationOptions } from '../../types';
+import { getBackgroundColor, getThemeColors, getThemeObject } from '../../util/theme';
+
+/**
+ * AreaDataItem is the type for each data item in the area chart.
+ */
+export type AreaDataItem = {
+  time: string | number;
+  value: number;
+  group?: string;
+};
+
+/**
+ * AreaConfig defines the configuration for rendering the area chart.
+ */
+export interface AreaConfig {
+  type?: 'area';
+  data: AreaDataItem[];
+  stack?: boolean;
+  title?: string;
+  axisXTitle?: string;
+  axisYTitle?: string;
+  theme?: 'default' | 'academy' | 'dark';
+  style?: {
+    backgroundColor?: string;
+    palette?: string[];
+    lineWidth?: number;
+  };
+}
+
+/**
+ * AreaInstance represents an area chart instance with render and destroy methods.
+ */
+export interface AreaInstance {
+  render: (config: AreaConfig) => void;
+  destroy: () => void;
+}
+
+const getLinearGradientColor = (color: string) =>
+  `linear-gradient(-90deg, white 0%, ${color} 100%)`;
+const DEFAULT_COLOR = '#3A95FF';
+
+/**
+ * Area chart component using G2 5.0.
+ *
+ * @example
+ * ```ts
+ * const area = Area({
+ *   container: '#container',
+ *   width: 600,
+ *   height: 400,
+ * });
+ *
+ * area.render({
+ *   type: 'area',
+ *   data: [
+ *     { time: '1 月', value: 23.895 },
+ *     { time: '2 月', value: 23.695 },
+ *     { time: '3 月', value: 23.655 },
+ *   ],
+ *   title: '1月到3月股票价格的变化',
+ *   axisXTitle: '月份',
+ *   axisYTitle: '价格',
+ * });
+ *
+ * area.destroy();
+ * ```
+ */
+export const Area = (options: VisualizationOptions): AreaInstance => {
+  const { container, width, height, theme: chartTheme = 'default' } = options;
+  let chart: Chart | null = null;
+
+  /**
+   * Render the area chart with the given configuration.
+   */
+  const render = (config: AreaConfig): void => {
+    const {
+      data = [],
+      theme = chartTheme,
+      title,
+      axisXTitle,
+      axisYTitle,
+      stack = false,
+      style = {},
+    } = config;
+
+    // Clean up previous chart if exists
+    if (chart) {
+      chart.destroy();
+    }
+
+    const { lineWidth = 2 } = style;
+    const hasGroupField = data.length > 0 && data[0]?.group !== undefined;
+    const colors = style.palette || getThemeColors(theme);
+    const backgroundColor = style.backgroundColor || getBackgroundColor(theme);
+    const fillColor = getLinearGradientColor(colors[0] || DEFAULT_COLOR);
+
+    // Create chart
+    chart = new Chart({
+      container,
+      width,
+      height,
+      autoFit: true,
+    });
+
+    // Configure chart encode and transform based on stack and group
+    let encode: any = {};
+    let transform: any = [];
+    const scaleConfig: any = { y: { nice: true } };
+    let children: any = [];
+
+    if (hasGroupField && stack) {
+      // Stacked area chart
+      encode = { x: 'time', y: 'value', color: 'group' };
+      transform = [{ type: 'stackY' }];
+      scaleConfig.color = { range: colors };
+      children = [
+        {
+          type: 'area',
+          style: { fillOpacity: 0.6 },
+        },
+        {
+          type: 'line',
+          style: { lineWidth, strokeOpacity: 0.6 },
+        },
+      ];
+    } else if (hasGroupField) {
+      // Multi-line area chart (not stacked)
+      encode = { x: 'time', y: 'value', color: 'group' };
+      scaleConfig.color = { range: colors };
+      children = [
+        {
+          type: 'area',
+          style: { fillOpacity: 0.6 },
+        },
+        {
+          type: 'line',
+          style: { lineWidth, strokeOpacity: 0.6 },
+        },
+      ];
+    } else {
+      // Single area chart
+      encode = { x: 'time', y: 'value' };
+      children = [
+        {
+          type: 'area',
+          style: {
+            fillOpacity: 0.6,
+            fill: fillColor,
+          },
+        },
+        {
+          type: 'line',
+          style: {
+            lineWidth,
+            strokeOpacity: 0.6,
+            ...(style.palette ? { stroke: colors[0] } : {}),
+          },
+        },
+      ];
+    }
+
+    // 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 ?? '',
+      encode,
+      transform,
+      children,
+      scale: scaleConfig,
+      axis: {
+        x: { title: axisXTitle || false },
+        y: { title: axisYTitle || false },
+      },
+      legend: hasGroupField ? { color: { position: 'top' } } : false,
+      tooltip: {
+        items: [
+          (d: any) => ({
+            name: axisYTitle || d.time,
+            value: d.value,
+          }),
+        ],
+      },
+      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/bar/README.md

@@ -0,0 +1,158 @@
+# Bar
+
+A horizontal bar chart component for comparing categorical data, built with G2 5.0.
+
+## Usage
+
+```ts
+import { Bar } from '@antv/gpt-vis/ai';
+
+const bar = Bar({
+  container: '#container',
+  width: 600,
+  height: 400,
+});
+
+bar.render({
+  data: [
+    { category: '2015 年', value: 80 },
+    { category: '2016 年', value: 140 },
+    { category: '2017 年', value: 220 },
+  ],
+  title: '海底捞公司外卖收入',
+  axisXTitle: '年份',
+  axisYTitle: '金额 （百万元）',
+});
+
+bar.destroy();
+```
+
+## Configuration
+
+### Constructor Options (BarOptions)
+
+| 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 (BarConfig)
+
+| Property   | Type    | Default   | Description                            |
+| ---------- | ------- | --------- | -------------------------------------- |
+| data       | Array   | -         | Chart data array                       |
+| type       | string  | 'bar'     | 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 BarDataItem = {
+  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 Bar Chart
+
+```ts
+bar.render({
+  data: [
+    { category: '第一产业', value: 7200.0 },
+    { category: '第二产业', value: 36600.0 },
+    { category: '第三产业', value: 41000.0 },
+  ],
+  axisXTitle: 'name',
+  axisYTitle: 'industrial',
+});
+```
+
+### Grouped Bar Chart
+
+```ts
+bar.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 Bar Chart
+
+```ts
+bar.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
+bar.render({
+  data: [
+    { category: '2015 年', value: 80 },
+    { category: '2016 年', value: 140 },
+    { category: '2017 年', value: 220 },
+  ],
+  theme: 'academy',
+  title: '海底捞公司外卖收入',
+});
+```
+
+### With Custom Styles
+
+```ts
+bar.render({
+  data: [
+    { category: '2015 年', value: 80 },
+    { category: '2016 年', value: 140 },
+    { category: '2017 年', value: 220 },
+  ],
+  style: {
+    palette: ['#FF6B6B', '#4ECDC4', '#45B7D1'],
+    backgroundColor: '#F5F5F5',
+  },
+});
+```
+
+## Methods
+
+- `render(config: BarConfig): void` - Render or update the chart
+- `destroy(): void` - Destroy the chart instance and clean up resources

package/src/vis/bar/index.ts

@@ -0,0 +1,186 @@
+import { Chart } from '@antv/g2';
+import type { VisualizationOptions } from '../../types';
+import { getBackgroundColor, getThemeColors, getThemeObject } from '../../util/theme';
+
+/**
+ * BarDataItem is the type for each data item in the bar chart.
+ */
+export type BarDataItem = {
+  category: string;
+  value: number;
+  group?: string;
+};
+
+/**
+ * BarConfig defines the configuration for rendering the bar chart.
+ */
+export interface BarConfig {
+  type?: 'bar';
+  data: BarDataItem[];
+  group?: boolean;
+  stack?: boolean;
+  title?: string;
+  axisXTitle?: string;
+  axisYTitle?: string;
+  theme?: 'default' | 'academy' | 'dark';
+  style?: {
+    backgroundColor?: string;
+    palette?: string[];
+  };
+}
+
+/**
+ * BarInstance represents a bar chart instance with render and destroy methods.
+ */
+export interface BarInstance {
+  render: (config: BarConfig) => void;
+  destroy: () => void;
+}
+
+/**
+ * Bar chart component using G2 5.0.
+ *
+ * @example
+ * ```ts
+ * const bar = Bar({
+ *   container: '#container',
+ *   width: 600,
+ *   height: 400,
+ * });
+ *
+ * bar.render({
+ *   type: 'bar',
+ *   data: [
+ *     { category: '2015 年', value: 80 },
+ *     { category: '2016 年', value: 140 },
+ *     { category: '2017 年', value: 220 },
+ *   ],
+ *   title: '海底捞公司外卖收入',
+ *   axisXTitle: '年份',
+ *   axisYTitle: '金额 （百万元）',
+ * });
+ *
+ * bar.destroy();
+ * ```
+ */
+export const Bar = (options: VisualizationOptions): BarInstance => {
+  const { container, width, height, theme: chartTheme = 'default' } = options;
+  let chart: Chart | null = null;
+
+  /**
+   * Render the bar chart with the given configuration.
+   */
+  const render = (config: BarConfig): 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,
+      coordinate: { transform: [{ type: 'transpose' }] },
+      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,
+  };
+};