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

package/src/vis/sankey/index.ts

@@ -0,0 +1,144 @@
+import { Chart } from '@antv/g2';
+import type { VisualizationOptions } from '../../types';
+import { getBackgroundColor, getThemeColors, getThemeObject } from '../../util/theme';
+
+/**
+ * SankeyDataItem is the type for each data item in the sankey chart.
+ */
+export type SankeyDataItem = {
+  source: string;
+  target: string;
+  value: number;
+};
+
+/**
+ * SankeyConfig defines the configuration for rendering the sankey chart.
+ */
+export interface SankeyConfig {
+  type?: 'sankey';
+  data: SankeyDataItem[];
+  nodeAlign?: 'left' | 'center' | 'right' | 'justify';
+  theme?: 'default' | 'academy' | 'dark';
+  title?: string;
+  style?: {
+    backgroundColor?: string;
+    palette?: string[];
+  };
+}
+
+/**
+ * SankeyInstance represents a sankey chart instance with render and destroy methods.
+ */
+export interface SankeyInstance {
+  render: (config: SankeyConfig) => void;
+  destroy: () => void;
+}
+
+/**
+ * Sankey chart component using G2 5.0.
+ *
+ * @example
+ * ```ts
+ * const sankey = Sankey({
+ *   container: '#container',
+ *   width: 600,
+ *   height: 400,
+ * });
+ *
+ * sankey.render({
+ *   type: 'sankey',
+ *   data: [
+ *     { source: '煤炭', target: '发电厂', value: 120 },
+ *     { source: '天然气', target: '发电厂', value: 80 },
+ *     { source: '发电厂', target: '工业', value: 100 },
+ *   ],
+ *   nodeAlign: 'justify',
+ *   theme: 'academy'
+ * });
+ *
+ * sankey.destroy();
+ * ```
+ */
+export const Sankey = (options: VisualizationOptions): SankeyInstance => {
+  const { container, width, height, theme: chartTheme = 'default' } = options;
+  let chart: Chart | null = null;
+
+  /**
+   * Render the sankey chart with the given configuration.
+   */
+  const render = (config: SankeyConfig): void => {
+    const { data = [], nodeAlign = 'center', theme = chartTheme, title, 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);
+
+    // 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: 'sankey',
+      data: {
+        value: data,
+        transform: [
+          {
+            type: 'custom',
+            callback: (data: SankeyDataItem[]) => ({
+              links: data,
+            }),
+          },
+        ],
+      },
+      layout: {
+        nodeAlign,
+        nodePadding: 0.01,
+      },
+      title: title ?? '',
+      scale: {
+        color: { range: colors },
+      },
+      style: {
+        labelSpacing: 2,
+        nodeLineWidth: 1,
+        linkFillOpacity: 0.3,
+      },
+      viewStyle: {
+        viewFill: backgroundColor,
+      },
+      theme: getThemeObject(theme),
+      legend: false,
+      tooltip: false,
+    };
+
+    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/scatter/README.md

@@ -0,0 +1,145 @@
+# Scatter
+
+A scatter chart component for visualizing the relationship between two numerical variables, built with G2 5.0.
+
+## Usage
+
+```ts
+import { Scatter } from '@antv/gpt-vis/ai';
+
+const scatter = Scatter({
+  container: '#container',
+  width: 600,
+  height: 400,
+});
+
+scatter.render({
+  data: [
+    { x: 10, y: 15 },
+    { x: 20, y: 25 },
+    { x: 30, y: 35 },
+    { x: 40, y: 45 },
+  ],
+});
+
+scatter.destroy();
+```
+
+## Configuration
+
+### Constructor Options (ScatterOptions)
+
+| 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 (ScatterConfig)
+
+| Property | Type   | Default   | Description               |
+| -------- | ------ | --------- | ------------------------- |
+| type     | string | 'scatter' | Chart type                |
+| data     | Array  | -         | Chart data array          |
+| theme    | string | 'default' | Color theme               |
+| title    | string | -         | Chart title               |
+| style    | object | -         | Chart style configuration |
+
+### Data Structure
+
+```ts
+type ScatterDataItem = {
+  x: number; // X-axis value
+  y: number; // Y-axis value
+  group?: string; // Optional: group for multiple series
+};
+```
+
+### Style Options
+
+```ts
+style?: {
+  backgroundColor?: string; // Background color
+  palette?: string[]; // Color palette for groups
+}
+```
+
+## Examples
+
+### Basic Scatter Chart
+
+```ts
+scatter.render({
+  data: [
+    { x: 10, y: 15 },
+    { x: 20, y: 25 },
+    { x: 30, y: 35 },
+    { x: 40, y: 45 },
+  ],
+});
+```
+
+### With Title
+
+```ts
+scatter.render({
+  data: [
+    { x: 10, y: 15 },
+    { x: 20, y: 25 },
+    { x: 30, y: 35 },
+    { x: 40, y: 45 },
+  ],
+  title: 'Advertisement vs Sales',
+});
+```
+
+### With Groups
+
+```ts
+scatter.render({
+  data: [
+    { x: 25, y: 5000, group: 'A' },
+    { x: 35, y: 7000, group: 'A' },
+    { x: 45, y: 10000, group: 'A' },
+    { x: 30, y: 6000, group: 'B' },
+    { x: 40, y: 8000, group: 'B' },
+    { x: 50, y: 11000, group: 'B' },
+  ],
+});
+```
+
+### With Academy Theme
+
+```ts
+scatter.render({
+  data: [
+    { x: 10, y: 15 },
+    { x: 20, y: 25 },
+    { x: 30, y: 35 },
+    { x: 40, y: 45 },
+  ],
+  theme: 'academy',
+});
+```
+
+### With Custom Styles
+
+```ts
+scatter.render({
+  data: [
+    { x: 10, y: 15, group: 'Group A' },
+    { x: 20, y: 25, group: 'Group A' },
+    { x: 30, y: 35, group: 'Group B' },
+    { x: 40, y: 45, group: 'Group B' },
+  ],
+  style: {
+    palette: ['#FF6B6B', '#4ECDC4', '#45B7D1'],
+    backgroundColor: '#F8F9FA',
+  },
+});
+```
+
+## Methods
+
+- `render(config: ScatterConfig): void` - Render or update the chart
+- `destroy(): void` - Destroy the chart instance and clean up resources

package/src/vis/scatter/index.ts

@@ -0,0 +1,147 @@
+import { Chart } from '@antv/g2';
+import type { VisualizationOptions } from '../../types';
+import { getBackgroundColor, getThemeColors, getThemeObject } from '../../util/theme';
+
+/**
+ * ScatterDataItem is the type for each data item in the scatter chart.
+ */
+export type ScatterDataItem = {
+  x: number;
+  y: number;
+  group?: string;
+};
+
+/**
+ * ScatterConfig defines the configuration for rendering the scatter chart.
+ */
+export interface ScatterConfig {
+  type?: 'scatter';
+  data: ScatterDataItem[];
+  title?: string;
+  theme?: 'default' | 'academy' | 'dark';
+  style?: {
+    backgroundColor?: string;
+    palette?: string[];
+  };
+}
+
+/**
+ * ScatterInstance represents a scatter chart instance with render and destroy methods.
+ */
+export interface ScatterInstance {
+  render: (config: ScatterConfig) => void;
+  destroy: () => void;
+}
+
+/**
+ * Scatter chart component using G2 5.0.
+ *
+ * @example
+ * ```ts
+ * const scatter = Scatter({
+ *   container: '#container',
+ *   width: 600,
+ *   height: 400,
+ * });
+ *
+ * scatter.render({
+ *   type: 'scatter',
+ *   data: [
+ *     { x: 10, y: 15 },
+ *     { x: 20, y: 25 },
+ *     { x: 30, y: 35 },
+ *     { x: 40, y: 45 },
+ *   ],
+ * });
+ *
+ * scatter.destroy();
+ * ```
+ */
+export const Scatter = (options: VisualizationOptions): ScatterInstance => {
+  const { container, width, height, theme: chartTheme = 'default' } = options;
+  let chart: Chart | null = null;
+
+  /**
+   * Render the scatter chart with the given configuration.
+   */
+  const render = (config: ScatterConfig): void => {
+    const { data = [], theme = chartTheme, title, 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);
+
+    // Check if data has group field
+    const hasGroupField = data.length > 0 && data[0]?.group !== undefined;
+
+    // Create chart
+    chart = new Chart({
+      container,
+      width,
+      height,
+      autoFit: true,
+    });
+
+    // Configure chart encode based on whether there's a group field
+    let encode: any = {};
+    const scaleConfig: any = {
+      y: { nice: true },
+    };
+
+    if (hasGroupField) {
+      encode = { x: 'x', y: 'y', color: 'group' };
+      scaleConfig.color = { range: colors };
+    } else {
+      encode = { x: 'x', y: 'y', color: () => 'all' };
+    }
+
+    // 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: 'point',
+      data,
+      title: title ?? '',
+      encode,
+      legend: hasGroupField ? { color: { position: 'top' } } : false,
+      scale: scaleConfig,
+      style: {
+        lineWidth: 1,
+      },
+      tooltip: {
+        title: (d: any) => (d?.group ? d.group : false),
+        items: [
+          { channel: 'x', name: 'x' },
+          { channel: 'y', name: 'y' },
+        ],
+      },
+      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/summary/README.md

@@ -0,0 +1,272 @@
+# Summary
+
+A narrative text visualization component for creating data interpretation reports and summaries with semantic entity annotations, built with AntV T8.
+
+## What is Summary
+
+Summary is a text visualization component that transforms data into structured narrative text using **T8 Syntax** - a declarative Markdown-like language for creating data narratives. Instead of traditional charts, Summary presents insights through natural language with semantically annotated data entities.
+
+**Key Features:**
+
+- **LLM-Friendly**: Simple syntax ideal for AI-generated content
+- **Semantic Annotations**: Mark metrics, trends, and comparisons with meaning
+- **Built-in Visualizations**: Mini charts embedded in text
+- **Professional Styling**: Consistent, report-quality appearance
+- **Theme Support**: Light and dark themes
+
+## Usage
+
+```ts
+import { Summary } from '@antv/gpt-vis/ai';
+
+const summary = Summary({
+  container: '#container',
+  theme: 'light', // optional, default 'light'
+});
+
+summary.render(`
+  # Sales Report
+  
+  Total sales reached [¥1,234,567](metric_value, origin=1234567) this quarter,
+  showing a [15.2% increase](ratio_value, origin=0.152, assessment="positive") 
+  compared to last quarter.
+`);
+
+summary.destroy();
+```
+
+## Configuration
+
+### Constructor Options (SummaryOptions)
+
+| Property  | Type                  | Default | Description                   |
+| --------- | --------------------- | ------- | ----------------------------- |
+| container | string \| HTMLElement | -       | Container element or selector |
+| theme     | 'light' \| 'dark'     | 'light' | Visual theme                  |
+| width     | number                | -       | Container width in pixels     |
+| height    | number                | -       | Container height in pixels    |
+
+### Render Config
+
+The `render()` method accepts a **T8 Syntax** string (see T8 Syntax Reference below).
+
+```ts
+type SummaryConfig = string; // T8 Syntax string
+```
+
+## T8 Syntax Reference
+
+T8 Syntax is a Markdown-like language for creating narrative text with semantic entity annotations.
+
+### Document Structure
+
+#### Headings
+
+Use standard Markdown heading syntax:
+
+```
+# Level 1 Heading (Main Title)
+## Level 2 Heading (Section)
+### Level 3 Heading (Subsection)
+```
+
+#### Paragraphs
+
+Regular text paragraphs are separated by blank lines:
+
+```
+This is the first paragraph.
+
+This is the second paragraph.
+```
+
+#### Lists
+
+**Unordered Lists:**
+
+```
+- First item
+- Second item
+- Third item
+```
+
+**Ordered Lists:**
+
+```
+1. First step
+2. Second step
+3. Third step
+```
+
+### Text Formatting
+
+- **Bold**: `This is **bold text**`
+- **Italic**: `This is *italic text*`
+- **Underline**: `This is __underlined text__`
+- **Links**: `Visit [our website](https://example.com)`
+
+### Entity Annotation Syntax
+
+The core feature of T8 Syntax is **entity annotation** - marking data points with semantic meaning.
+
+#### Basic Syntax
+
+```
+[displayText](entityType)
+```
+
+**Example:**
+
+```
+The [sales revenue](metric_name) reached [¥1.5 million](metric_value).
+```
+
+#### With Metadata
+
+```
+[displayText](entityType, key1=value1, key2=value2)
+```
+
+**Example:**
+
+```
+Revenue grew by [15.3%](ratio_value, origin=0.153, assessment="positive").
+```
+
+### Entity Types
+
+| Entity Type          | Description                | Example                                 |
+| -------------------- | -------------------------- | --------------------------------------- |
+| `metric_name`        | Name of a metric or KPI    | `[revenue](metric_name)`                |
+| `metric_value`       | Primary metric value       | `[¥1.5M](metric_value, origin=1500000)` |
+| `other_metric_value` | Secondary metric value     | `[avg: $120](other_metric_value)`       |
+| `delta_value`        | Absolute change            | `[+1,200](delta_value)`                 |
+| `ratio_value`        | Percentage change          | `[+15.3%](ratio_value, origin=0.153)`   |
+| `contribute_ratio`   | Contribution percentage    | `[45%](contribute_ratio, origin=0.45)`  |
+| `trend_desc`         | Trend description          | `[rising](trend_desc)`                  |
+| `dim_value`          | Dimensional value/category | `[North America](dim_value)`            |
+| `time_desc`          | Time period                | `[Q3 2024](time_desc)`                  |
+| `proportion`         | Proportion or ratio        | `[3 out of 5](proportion, origin=0.6)`  |
+
+### Metadata Fields
+
+#### `origin` (number)
+
+The raw numerical value behind the displayed text.
+
+**Examples:**
+
+- `[¥1.5M](metric_value, origin=1500000)`
+- `[23.7%](ratio_value, origin=0.237)`
+
+#### `assessment` (string)
+
+Evaluates whether a change is positive, negative, or neutral.
+
+**Valid values:** `"positive"`, `"negative"`, `"equal"`, `"neutral"`
+
+**Examples:**
+
+- `[increased 15%](ratio_value, assessment="positive")`
+- `[dropped 8%](ratio_value, assessment="negative")`
+
+#### `unit` (string)
+
+The unit of measurement for the value.
+
+**Example:**
+
+- `[150](metric_value, unit="units")`
+
+## Examples
+
+### Basic Report
+
+```ts
+summary.render(`
+  # Q4 Sales Report
+  
+  ## Overview
+  Total [revenue](metric_name) reached [¥5,234,567](metric_value, origin=5234567),
+  representing a [15.2% increase](ratio_value, origin=0.152, assessment="positive") 
+  compared to Q3.
+  
+  ## Key Metrics
+  - New customers: [1,234](metric_value, origin=1234)
+  - Retention rate: [89.5%](ratio_value, origin=0.895)
+  - Average order: [¥4,567](metric_value, origin=4567)
+`);
+```
+
+### With Multiple Sections
+
+```ts
+summary.render(`
+  # Market Analysis Report
+  
+  ## Executive Summary
+  [Global smartphone shipments](metric_name) reached [1.2 billion units](metric_value, origin=1200000000)
+  in [2024](time_desc), showing a [modest decline of 2.1%](ratio_value, origin=-0.021, assessment="negative").
+  
+  ## Regional Performance
+  
+  ### Asia-Pacific
+  [Asia-Pacific](dim_value) remains the largest market with [680M units](metric_value, origin=680000000),
+  accounting for [56.7%](contribute_ratio, origin=0.567) of global sales.
+  
+  ### North America
+  [North America](dim_value) showed [steady growth](trend_desc, assessment="positive") 
+  with [220M units](metric_value, origin=220000000).
+`);
+```
+
+### Dark Theme
+
+```ts
+const summaryDark = Summary({
+  container: '#container',
+  theme: 'dark',
+});
+
+summaryDark.render(`
+  # Sales Performance
+  Revenue reached [¥2.5M](metric_value, origin=2500000), up [18%](ratio_value, origin=0.18, assessment="positive").
+`);
+```
+
+## Methods
+
+- `render(syntax: string): void` - Render narrative text using T8 Syntax
+- `destroy(): void` - Destroy the component and clean up resources
+
+## Best Practices
+
+### Content Guidelines
+
+1. **Use Natural Language**: Write fluent, readable prose
+2. **Annotate All Data**: Mark every metric, percentage, and value
+3. **Provide Context**: Explain significance, not just numbers
+4. **Structure Clearly**: Use headings and sections logically
+5. **Add Metadata**: Include `origin`, `assessment` for richer visualization
+
+### Entity Annotation Tips
+
+✅ **DO annotate:**
+
+- All numeric values and percentages
+- Metric names and KPIs
+- Time periods and geographic regions
+- Trends and changes
+- Comparisons and contributions
+
+❌ **DON'T annotate:**
+
+- Generic text without data meaning
+- Connecting phrases
+- Context without measurable concepts
+
+## References
+
+- [T8 GitHub Repository](https://github.com/antvis/T8)
+- [T8 Documentation](https://github.com/antvis/T8/blob/main/site/en/tutorial/quick-start.md)
+- [T8 Skill Guide](https://github.com/antvis/chart-visualization-skills/blob/master/skills/narrative-text-visualization/SKILL.md)