@antv/gpt-vis 1.0.0-beta.2 → 1.0.1

package/README.zh-CN.md

@@ -1,42 +1,42 @@
 <img src="https://gw.alipayobjects.com/zos/antfincdn/R8sN%24GNdh6/language.svg" width="18"> [English](./README.md) | 简体中文
 
-<h1 align="center">GPT-Vis，为 AI 而生的可视化方案</h1>
+<div align="center">
+  <img src="https://github.com/eosphoros-ai/GPT-Vis/assets/17919400/c8804ffb-d3d6-45d3-846f-cf217681ab05" height="70" />
+</div>
+
+<h1 align="center">GPT-Vis</h1>
 
 <div align="center">
-<img src="https://github.com/eosphoros-ai/GPT-Vis/assets/17919400/c8804ffb-d3d6-45d3-846f-cf217681ab05" height="70">
 
-面向 LLM 时代的 AI 原生可视化组件，为 AI 驱动应用设计的框架无关可视化库。
+面向 LLM 时代的 AI 原生可视化库，框架无关，开箱即用。
 
 [![npm version](https://img.shields.io/npm/v/@antv/gpt-vis.svg)](https://www.npmjs.com/package/@antv/gpt-vis)
 [![npm downloads](https://img.shields.io/npm/dm/@antv/gpt-vis.svg)](https://www.npmjs.com/package/@antv/gpt-vis)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 <p align="center">
-  <a href="https://gpt-vis.antv.vision" target="_blank">📖 文档</a> •
-  <a href="/skills/chart-visualization" target="_blank">🤖 图表技能</a> •
-  <a href="/knowledges" target="_blank">🧠 知识库</a> •
-  <a href="https://www.tbox.cn/share/202504APmv6c00373739?platform=WebService" target="_blank">🎮 在线体验</a> •
-  <a href="https://github.com/antvis/mcp-server-chart" target="_blank">🔌 MCP 服务器</a>
+  <a href="https://gpt-vis.antv.vision" target="_blank">📖 文档</a> ·
+  <a href="https://gpt-vis.antv.vision/examples" target="_blank">🎨 图表示例</a> ·
+  <a href="https://github.com/antvis/mcp-server-chart" target="_blank">🔌 MCP 服务</a> ·
+  <a href="/skills/chart-visualization" target="_blank">🧩 图表技能</a>
 </p>
 
 </div>
 
 <div align="center">
-  <video src="https://github.com/user-attachments/assets/b8eb4a89-b0ed-4a39-8fab-316161949446" />
+  <img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*yNtZT47dH1kAAAAAgBAAAAgAemJ7AQ/fmt.webp" width="100%" alt="GPT-Vis Hero Image" />
 </div>
 
 <br/>
 
-> **📢 Version 1.0 预览版**: 为 AI 优化的全新架构。正式版预计 **2026 年 3 月 21 日**发布。
-
-## ✨ 核心特性
+## ✨ 特性
 
-- **🚀 框架无关**: 支持原生 JavaScript、React、Vue、Angular 或任何框架
-- **✍️ 自然语法**: 简单的类 Markdown 语法，LLM 可以轻松生成
-- **🌊 流式支持**: 内置支持 AI 模型的流式输出
-- **🛡️ 容错性**: 优雅处理不完整或格式错误数据
-- **📊 20+ 图表类型**: 统计图表、关系图表和高级可视化图表
-- **🧠 智能默认值**: 自动数据检测、智能配色方案、自适应布局
+- 🚀 **框架无关** — 原生 JavaScript、React、Vue、Angular，任何框架均可使用
+- ✍️ **类 Markdown 语法** — LLM 可以直接生成的简洁语法，易学易用
+- 🌊 **流式渲染** — 原生支持 AI 模型流式输出，边生成边渲染
+- 🛡️ **高容错** — 优雅处理不完整、格式异常的数据，适配 AI 生成内容的不确定性
+- 📊 **26 种图表** — 统计图表、关系图表、文本可视化，覆盖主流场景
+- 🎨 **主题系统** — 内置亮色、暗色、学术三套主题，支持自定义配色
 
 ## 🚀 快速开始
 
@@ -57,7 +57,7 @@ const gptVis = new GPTVis({
   height: 400,
 });
 
-// 使用类 Markdown 语法渲染
+// 类 Markdown 的可视化语法
 const visSyntax = `
 vis line
 data
@@ -72,7 +72,11 @@ data
 gptVis.render(visSyntax);
 ```
 
-### 流式支持
+### 流式渲染
+
+AI 模型边生成、图表边渲染，无需等待完整响应：
+
+<img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*_xY7Q6QyuZ4AAAAAWeAAAAgAemJ7AQ/original" width="100%" />
 
 ```javascript
 import { GPTVis, isVisSyntax } from '@antv/gpt-vis';
@@ -90,18 +94,20 @@ function onToken(token) {
 
 ## 📚 语法指南
 
-### 基本结构
+`render()` 支持两种输入格式：vis 语法（适合 LLM 流式生成）和 JSON 对象（适合程序化调用）。
+
+### Vis 语法
+
+类 Markdown 的声明式语法，LLM 无需学习复杂 API 即可生成：
 
 ```
 vis [图表类型]
 [属性] [值]
 data
-  - [键] [值]
+  - [字段] [值]
 ```
 
-### 示例
-
-**简单图表:**
+**饼图：**
 
 ```
 vis pie
@@ -113,7 +119,29 @@ data
 innerRadius 0.6
 ```
 
-**带样式:**
+**主题：**
+
+内置三套主题，通过 `theme` 属性切换：
+
+| 主题         | 标识      | 背景色 | 色板                                                  |
+| ------------ | --------- | ------ | ----------------------------------------------------- |
+| 默认（亮色） | `default` | `#FFF` | `#1783FF` `#F08F56` `#D580FF` `#00C9C9` `#7863FF` ... |
+| 暗色         | `dark`    | `#000` | `#1783FF` `#F08F56` `#D580FF` `#00C9C9` `#7863FF` ... |
+| 学术         | `academy` | `#FFF` | `#4e79a7` `#f28e2c` `#e15759` `#76b7b2` `#59a14f` ... |
+
+```
+vis line
+data
+  - time 2020
+    value 100
+  - time 2021
+    value 120
+theme dark
+```
+
+**自定义样式：**
+
+通过 `style` 设置线宽、自定义配色等：
 
 ```
 vis line
@@ -129,17 +157,89 @@ style
     - #5AD8A6
 ```
 
-**层次数据:**
+**包含空格的值用引号包裹：**
 
 ```
-vis mind-map
+vis pie
 data
-  - name 项目
+  - category "Q1 销售额"
+    value 30
+  - category "Q2 销售额"
+    value 25
+```
+
+**层级数据：**
+
+```
+vis mindmap
+data
+  - name 项目规划
     children
-      - name 阶段一
-      - name 阶段二
+      - name 第一阶段
+      - name 第二阶段
+```
+
+### JSON 对象
+
+也支持直接传入 JSON 对象，适合程序化调用：
+
+```javascript
+gptVis.render({
+  type: 'pie',
+  data: [
+    { category: 'Android', value: 72 },
+    { category: 'iOS', value: 28 },
+  ],
+});
 ```
 
+## 📊 图表类型
+
+支持 26 种图表，覆盖统计分析、关系网络、文本可视化三大类。
+
+### 统计图表（18 种）
+
+| 图表     | 类型标识     |
+| -------- | ------------ |
+| 折线图   | `line`       |
+| 面积图   | `area`       |
+| 柱状图   | `column`     |
+| 条形图   | `bar`        |
+| 饼图     | `pie`        |
+| 散点图   | `scatter`    |
+| 雷达图   | `radar`      |
+| 漏斗图   | `funnel`     |
+| 瀑布图   | `waterfall`  |
+| 双轴图   | `dual-axes`  |
+| 直方图   | `histogram`  |
+| 箱线图   | `boxplot`    |
+| 小提琴图 | `violin`     |
+| 韦恩图   | `venn`       |
+| 桑基图   | `sankey`     |
+| 树图     | `treemap`    |
+| 词云     | `word-cloud` |
+| 水波图   | `liquid`     |
+
+### 关系图表（6 种）
+
+| 图表       | 类型标识             |
+| ---------- | -------------------- |
+| 流程图     | `flow-diagram`       |
+| 网络图     | `network-graph`      |
+| 思维导图   | `mindmap`            |
+| 缩进树     | `indented-tree`      |
+| 组织架构图 | `organization-chart` |
+| 鱼骨图     | `fishbone-diagram`   |
+
+### 文本可视化（2 种）
+
+| 图表     | 类型标识  |
+| -------- | --------- |
+| 表格     | `table`   |
+| 文本摘要 | `summary` |
+
+查看全部示例 → [图表示例](https://gpt-vis.antv.vision/examples)
+
 ## 🔧 框架集成
 
 <details>
@@ -191,25 +291,22 @@ function ChartComponent({ visSyntax }) {
 </template>
 
 <script setup>
-import { ref, onMounted, onUnmounted, watch } from 'vue';
+import { ref, watch, onUnmounted } from 'vue';
 import { GPTVis } from '@antv/gpt-vis';
 
 const props = defineProps(['visSyntax']);
 const chartRef = ref(null);
 let gptVis = null;
 
-onMounted(() => {
-  gptVis = new GPTVis({ container: chartRef.value, width: 600, height: 400 });
-  gptVis.render(props.visSyntax);
-});
-
 watch(
   () => props.visSyntax,
-  (newSyntax) => {
-    if (gptVis) {
-      gptVis.render(newSyntax);
+  (syntax) => {
+    if (!gptVis) {
+      gptVis = new GPTVis({ container: chartRef.value, width: 600, height: 400 });
     }
+    gptVis.render(syntax);
   },
+  { immediate: true },
 );
 
 onUnmounted(() => gptVis?.destroy());
@@ -218,18 +315,160 @@ onUnmounted(() => gptVis?.destroy());
 
 </details>
 
-## 🧠 知识库
+<details>
+<summary><strong>Markdown 渲染器（marked）</strong></summary>
+
+GPT-Vis 的 vis 语法天然兼容 Markdown code fence，可以与任何 Markdown 渲染器集成。以下示例使用 `marked` + `marked-highlight`，普通代码块走语法高亮，`vis` 代码块自动渲染为交互式图表。
 
-GPT-Vis 包含全面的[知识库](https://github.com/antvis/GPT-Vis/tree/main/knowledges)，帮助 LLM 理解何时使用每种图表类型以及如何构建数据结构。在 200+ 场景中评估，准确率超过 90%。
+**安装依赖：**
 
-## 🤝 贡献
+```bash
+npm install @antv/gpt-vis marked marked-highlight highlight.js
+```
+
+**完整示例：**
+
+```javascript
+import { Marked } from 'marked';
+import { markedHighlight } from 'marked-highlight';
+import hljs from 'highlight.js';
+import { GPTVis } from '@antv/gpt-vis';
 
-> **⚠️ AI 生成代码策略**: 本项目仅合并 AI 生成的代码。
+class GPTVisElement extends HTMLElement {
+  connectedCallback() {
+    const syntax = decodeURIComponent(this.dataset.syntax);
+    this._instance = new GPTVis({ container: this });
+    this._instance.render(syntax);
+  }
+  disconnectedCallback() {
+    this._instance?.destroy();
+  }
+}
+if (!customElements.get('gpt-vis')) {
+  customElements.define('gpt-vis', GPTVisElement);
+}
+
+const marked = new Marked(
+  markedHighlight({
+    langPrefix: 'hljs language-',
+    highlight(code, lang) {
+      if (lang?.startsWith('vis')) return code;
+      const language = hljs.getLanguage(lang) ? lang : 'plaintext';
+      return hljs.highlight(code, { language }).value;
+    },
+  }),
+  {
+    renderer: {
+      code({ text, lang }) {
+        if (lang?.startsWith('vis')) {
+          const syntax = encodeURIComponent(lang + '\n' + text);
+          return `<gpt-vis data-syntax="${syntax}" style="min-height:300px"></gpt-vis>`;
+        }
+        return false;
+      },
+    },
+  },
+);
+
+const markdown = `# My Report
+
+\`\`\`vis bar
+data
+  - category Python
+    value 28.1
+  - category JavaScript
+    value 18.5
+  - category Java
+    value 15.6
+  - category "C/C++"
+    value 12.3
+title 2024 Programming Language Popularity
+\`\`\`
+`;
+
+document.getElementById('content').innerHTML = marked.parse(markdown);
+```
+
+</details>
+
+## 🧩 Shadcn/ui
+
+通过 shadcn CLI 将 GPT-Vis React 组件直接复制到你的项目中 — 完全源代码控制，高度可定制。
+
+### 基础组件
+
+通用的 `GPTVis` 组件，支持全部 26 种图表类型的 vis 语法字符串或 JSON 配置对象：
+
+```bash
+npx shadcn@latest add @gpt-vis/gpt-vis
+```
+
+```tsx
+import { GPTVis } from '@/components/ui/gpt-vis';
+
+<GPTVis
+  content="vis line
+data
+  - time 2020
+    value 100
+  - time 2021
+    value 120
+  - time 2022
+    value 150
+title 销售趋势"
+  theme="academy"
+/>;
+```
+
+### 类型化图表组件
+
+每种图表类型都有独立的组件，提供类型安全的 `config` 属性 — 仅支持 JSON，带 TypeScript 类型校验：
+
+```bash
+npx shadcn@latest add @gpt-vis/line
+```
+
+```tsx
+import { Line } from '@/components/ui/line';
+
+<Line
+  config={{
+    data: [
+      { time: '2020', value: 100 },
+      { time: '2021', value: 120 },
+      { time: '2022', value: 150 },
+    ],
+    title: '销售趋势',
+    axisXTitle: '年份',
+  }}
+  height={400}
+/>;
+```
+
+全部 26 种图表类型均可用，按名称安装即可：
+
+```bash
+npx shadcn@latest add @gpt-vis/pie
+npx shadcn@latest add @gpt-vis/bar
+npx shadcn@latest add @gpt-vis/mindmap
+# ...等等
+```
+
+每个类型化组件自动将基础 `GPTVis` 组件作为依赖安装。`width`、`height`、`theme`、`wrapper`、`locale`、`className`、`containerStyle` 等属性在所有组件中保持一致。
+
+## 🤖 AI 生态
+
+GPT-Vis 提供完整的 AI 集成方案：
+
+- **[MCP 服务](https://github.com/antvis/mcp-server-chart)** — 通过 Model Context Protocol 让 AI 模型直接调用可视化能力
+- **[图表技能](https://github.com/antvis/GPT-Vis/tree/main/skills/chart-visualization)** — 为 AI 助手提供图表推荐与生成能力，支持语法模式和代码模式两种输出
+
+## 🤝 贡献
 
-贡献方式：
+> **AI 生成代码策略**：本项目仅合并 AI 生成的代码。
 
-1. 提交 Issue 描述问题或功能
-2. 标记 @copilot 生成实现
+1. 提交 Issue 描述问题或需求
+2. 标记 @copilot 生成实现方案
 3. 提交包含 AI 生成代码的 PR
 
 ## 📄 开源协议

package/dist/cjs/gpt-vis/index.js

@@ -118,7 +118,7 @@ var _GPTVis = class {
         this.wrapperInstance = (0, import_vis_wrapper.createVisWrapper)(this.options.container, {
           chartType: type,
           syntax: config,
-          locale: this.options.locale || "zh-CN"
+          locale: this.options.locale || "en-US"
         });
       } else {
         this.wrapperInstance.update(config);

package/dist/cjs/types/index.d.ts

@@ -2,11 +2,12 @@
  * Common visualization options for all chart components.
  * Defines the container and dimensions for rendering visualizations.
  */
+export type VisualizationTheme = 'default' | 'light' | 'dark' | 'academy';
 export interface VisualizationOptions {
     container: string | HTMLElement;
     width?: number;
     height?: number;
-    theme?: 'default' | 'light' | 'dark' | 'academy';
+    theme?: VisualizationTheme;
     wrapper?: boolean;
     locale?: string;
 }

package/dist/cjs/util/animation.d.ts

@@ -0,0 +1,2 @@
+export type ChartEnterAnimation = 'fadeIn' | 'pathIn' | 'growInX' | 'growInY' | 'waveIn';
+export declare const getChartAnimation: (hasRendered: boolean, enterType?: ChartEnterAnimation) => false | Record<string, unknown>;

package/dist/cjs/util/animation.js

@@ -0,0 +1,38 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/util/animation.ts
+var animation_exports = {};
+__export(animation_exports, {
+  getChartAnimation: () => getChartAnimation
+});
+module.exports = __toCommonJS(animation_exports);
+var prefersReducedMotion = () => typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+var getChartAnimation = (hasRendered, enterType) => {
+  if (hasRendered || prefersReducedMotion())
+    return false;
+  return {
+    enter: enterType ? { type: enterType } : {},
+    update: { type: null },
+    exit: { type: null }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getChartAnimation
+});

package/dist/cjs/util/components.d.ts

@@ -0,0 +1,15 @@
+export type ChartLocale = 'en-US' | 'zh-CN';
+export type CartesianXAxisOptions = {
+    xLabels?: unknown[];
+    chartWidth?: number;
+};
+export type CartesianAxisOptions = CartesianXAxisOptions & {
+    axisXTitle?: string | false;
+    axisYTitle?: string | false;
+};
+export declare const resolveChartLocale: (locale?: string) => ChartLocale;
+export declare const getCartesianLayout: ({ xLabels, chartWidth, }: CartesianXAxisOptions) => Record<string, number>;
+export declare const getCartesianAxis: ({ axisXTitle, axisYTitle, xLabels, chartWidth, }: CartesianAxisOptions) => Record<'x' | 'y', Record<string, unknown>>;
+export declare const getColorLegend: (visible: boolean) => false | {
+    color: Record<string, never>;
+};

package/dist/cjs/util/components.js

@@ -0,0 +1,94 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/util/components.ts
+var components_exports = {};
+__export(components_exports, {
+  getCartesianAxis: () => getCartesianAxis,
+  getCartesianLayout: () => getCartesianLayout,
+  getColorLegend: () => getColorLegend,
+  resolveChartLocale: () => resolveChartLocale
+});
+module.exports = __toCommonJS(components_exports);
+var DEFAULT_CHART_WIDTH = 640;
+var AXIS_HORIZONTAL_PADDING = 96;
+var ANGLED_LABEL_MARGIN_RIGHT_MIN = 32;
+var ANGLED_LABEL_MARGIN_RIGHT_MAX = 64;
+var ANGLED_LABEL_EDGE_GAP = 8;
+var estimateLabelWidth = (value) => Array.from(String(value ?? "")).reduce(
+  (width, character) => width + ((character.codePointAt(0) ?? 0) > 255 ? 12 : 7),
+  0
+);
+var shouldUseAngledXAxisLabels = (labels, chartWidth = DEFAULT_CHART_WIDTH) => {
+  if (!(labels == null ? void 0 : labels.length))
+    return false;
+  const uniqueLabels = Array.from(new Set(labels.map((label) => String(label ?? ""))));
+  if (uniqueLabels.length <= 1)
+    return false;
+  const availableWidth = Math.max(chartWidth - AXIS_HORIZONTAL_PADDING, 240);
+  const estimatedWidth = uniqueLabels.reduce(
+    (total, label) => total + Math.max(28, estimateLabelWidth(label) + 16),
+    0
+  );
+  return estimatedWidth > availableWidth;
+};
+var resolveChartLocale = (locale) => (locale == null ? void 0 : locale.toLowerCase().startsWith("zh")) ? "zh-CN" : "en-US";
+var getCartesianLayout = ({
+  xLabels,
+  chartWidth
+}) => {
+  if (!shouldUseAngledXAxisLabels(xLabels, chartWidth))
+    return {};
+  const tailLabel = xLabels == null ? void 0 : xLabels[xLabels.length - 1];
+  const labelWidth = estimateLabelWidth(tailLabel);
+  const projectedHalfWidth = (labelWidth + 12) * Math.SQRT1_2 / 2;
+  return {
+    marginRight: Math.min(
+      ANGLED_LABEL_MARGIN_RIGHT_MAX,
+      Math.max(
+        ANGLED_LABEL_MARGIN_RIGHT_MIN,
+        Math.ceil(projectedHalfWidth + ANGLED_LABEL_EDGE_GAP)
+      )
+    )
+  };
+};
+var getCartesianAxis = ({
+  axisXTitle,
+  axisYTitle,
+  xLabels,
+  chartWidth
+}) => {
+  const useAngledXAxisLabels = shouldUseAngledXAxisLabels(xLabels, chartWidth);
+  return {
+    x: {
+      title: axisXTitle || false,
+      ...useAngledXAxisLabels ? { labelTransform: "rotate(45)", labelAutoRotate: false } : {}
+    },
+    y: {
+      title: axisYTitle || false
+    }
+  };
+};
+var getColorLegend = (visible) => visible ? { color: {} } : false;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getCartesianAxis,
+  getCartesianLayout,
+  getColorLegend,
+  resolveChartLocale
+});

package/dist/cjs/util/crosshair-axis-labels.d.ts

@@ -0,0 +1,9 @@
+import { type Chart } from '@antv/g2';
+import type { VisualizationTheme } from '../types';
+/**
+ * Bridges G2 tooltip crosshairs to axis value tags.
+ *
+ * G2 does not currently expose axis tags for tooltip crosshairs, so this adapter
+ * reads the rule geometry created by G2 5.4 and renders labels with LineCrosshair.
+ */
+export declare const bindCrosshairAxisLabels: (chart: Chart, theme: VisualizationTheme) => (() => void);