@antv/gpt-vis 1.0.0 → 1.0.2

package/README.md

@@ -24,7 +24,7 @@ AI-native visualization library for the LLM era. Framework-agnostic, ready to us
 </div>
 
 <div align="center">
-  <img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*k21VQY6NgAwAAAAAWAAAAAgAemJ7AQ/fmt.avif" width="100%" />
+  <img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*yNtZT47dH1kAAAAAgBAAAAgAemJ7AQ/fmt.webp" width="100%" alt="GPT-Vis Hero Image" />
 </div>
 
 <br/>
@@ -57,19 +57,14 @@ const gptVis = new GPTVis({
   height: 400,
 });
 
-// Markdown-like visualization syntax
-const visSyntax = `
-vis line
-data
-  - time 2020
-    value 100
-  - time 2021
-    value 120
-  - time 2022
-    value 150
-`;
-
-gptVis.render(visSyntax);
+gptVis.render({
+  type: 'line',
+  data: [
+    { time: '2020', value: 100 },
+    { time: '2021', value: 120 },
+    { time: '2022', value: 150 },
+  ],
+});
 ```
 
 ### Streaming Rendering
@@ -94,9 +89,73 @@ function onToken(token) {
 
 ## 📚 Syntax Guide
 
-`render()` supports two input formats: vis syntax (ideal for LLM streaming) and JSON objects (ideal for programmatic use).
+`render()` supports two input formats: JSON objects (ideal for programmatic use) and DSL syntax (ideal for LLM streaming).
 
-### Vis Syntax
+### Object Config
+
+Pass JSON objects directly for programmatic chart creation:
+
+**Line chart:**
+
+```javascript
+gptVis.render({
+  type: 'line',
+  data: [
+    { time: '2020', value: 100 },
+    { time: '2021', value: 120 },
+    { time: '2022', value: 150 },
+  ],
+});
+```
+
+**Pie chart:**
+
+```javascript
+gptVis.render({
+  type: 'pie',
+  data: [
+    { category: 'Android', value: 72 },
+    { category: 'iOS', value: 28 },
+  ],
+  innerRadius: 0.6,
+});
+```
+
+**Themes:**
+
+Three built-in themes, switchable via the `theme` property:
+
+| Theme           | Identifier | Background | Palette                                               |
+| --------------- | ---------- | ---------- | ----------------------------------------------------- |
+| Default (Light) | `default`  | `#FFF`     | `#1783FF` `#F08F56` `#D580FF` `#00C9C9` `#7863FF` ... |
+| Dark            | `dark`     | `#000`     | `#1783FF` `#F08F56` `#D580FF` `#00C9C9` `#7863FF` ... |
+| Academy         | `academy`  | `#FFF`     | `#4e79a7` `#f28e2c` `#e15759` `#76b7b2` `#59a14f` ... |
+
+```javascript
+gptVis.render({
+  type: 'line',
+  data: [
+    { time: '2020', value: 100 },
+    { time: '2021', value: 120 },
+  ],
+  theme: 'dark',
+});
+```
+
+**Custom Styles:**
+
+```javascript
+gptVis.render({
+  type: 'line',
+  data: [
+    { time: '2020', value: 100 },
+    { time: '2021', value: 120 },
+  ],
+  style: { lineWidth: 3, palette: ['#5B8FF9', '#5AD8A6'] },
+});
+```
+
+### DSL Syntax
 
 Declarative markdown-like syntax that LLMs can generate without learning complex APIs:
 
@@ -121,14 +180,6 @@ innerRadius 0.6
 
 **Themes:**
 
-Three built-in themes, switchable via the `theme` property:
-
-| Theme           | Identifier | Background | Palette                                               |
-| --------------- | ---------- | ---------- | ----------------------------------------------------- |
-| Default (Light) | `default`  | `#FFF`     | `#1783FF` `#F08F56` `#D580FF` `#00C9C9` `#7863FF` ... |
-| Dark            | `dark`     | `#000`     | `#1783FF` `#F08F56` `#D580FF` `#00C9C9` `#7863FF` ... |
-| Academy         | `academy`  | `#FFF`     | `#4e79a7` `#f28e2c` `#e15759` `#76b7b2` `#59a14f` ... |
-
 ```
 vis line
 data
@@ -179,18 +230,21 @@ data
       - name Phase 2
 ```
 
-### JSON Objects
-
-Also supports passing JSON objects directly, ideal for programmatic use:
+**Render DSL syntax:**
 
 ```javascript
-gptVis.render({
-  type: 'pie',
-  data: [
-    { category: 'Android', value: 72 },
-    { category: 'iOS', value: 28 },
-  ],
-});
+const visSyntax = `
+vis line
+data
+  - time 2020
+    value 100
+  - time 2021
+    value 120
+  - time 2022
+    value 150
+`;
+
+gptVis.render(visSyntax);
 ```
 
 ## 📊 Chart Types
@@ -391,6 +445,71 @@ document.getElementById('content').innerHTML = marked.parse(markdown);
 
 </details>
 
+## 🧩 Shadcn/ui
+
+Copy GPT-Vis React components directly into your project via shadcn CLI — full source control, fully customizable.
+
+### Base Component
+
+The universal `GPTVis` component accepts vis syntax strings or config objects for all 26 chart types:
+
+```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 Sales Trend"
+  theme="academy"
+/>;
+```
+
+### Typed Chart Components
+
+Each chart type has its own component with a typed `config` prop — JSON only, chart-specific TypeScript validation:
+
+```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: 'Sales Trend',
+    axisXTitle: 'Year',
+  }}
+  height={400}
+/>;
+```
+
+All 26 chart types are available. Install any by name:
+
+```bash
+npx shadcn@latest add @gpt-vis/pie
+npx shadcn@latest add @gpt-vis/bar
+npx shadcn@latest add @gpt-vis/mindmap
+# ...and more
+```
+
+Each typed component automatically bundles the base `GPTVis` component as a dependency. Props like `width`, `height`, `theme`, `wrapper`, `locale`, `className`, and `containerStyle` are the same across all components.
+
 ## 🤖 AI Ecosystem
 
 GPT-Vis provides a complete AI integration solution:

package/README.zh-CN.md

@@ -24,7 +24,7 @@
 </div>
 
 <div align="center">
-  <img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*k21VQY6NgAwAAAAAWAAAAAgAemJ7AQ/fmt.avif" width="100%" />
+  <img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*yNtZT47dH1kAAAAAgBAAAAgAemJ7AQ/fmt.webp" width="100%" alt="GPT-Vis Hero Image" />
 </div>
 
 <br/>
@@ -57,19 +57,14 @@ const gptVis = new GPTVis({
   height: 400,
 });
 
-// 类 Markdown 的可视化语法
-const visSyntax = `
-vis line
-data
-  - time 2020
-    value 100
-  - time 2021
-    value 120
-  - time 2022
-    value 150
-`;
-
-gptVis.render(visSyntax);
+gptVis.render({
+  type: 'line',
+  data: [
+    { time: '2020', value: 100 },
+    { time: '2021', value: 120 },
+    { time: '2022', value: 150 },
+  ],
+});
 ```
 
 ### 流式渲染
@@ -94,9 +89,73 @@ function onToken(token) {
 
 ## 📚 语法指南
 
-`render()` 支持两种输入格式：vis 语法（适合 LLM 流式生成）和 JSON 对象（适合程序化调用）。
+`render()` 支持两种输入格式：对象配置（适合程序化调用）和 DSL 语法（适合 LLM 流式生成）。
 
-### Vis 语法
+### 对象配置
+
+直接传入 JSON 对象，适合程序化图表创建：
+
+**折线图：**
+
+```javascript
+gptVis.render({
+  type: 'line',
+  data: [
+    { time: '2020', value: 100 },
+    { time: '2021', value: 120 },
+    { time: '2022', value: 150 },
+  ],
+});
+```
+
+**饼图：**
+
+```javascript
+gptVis.render({
+  type: 'pie',
+  data: [
+    { category: 'Android', value: 72 },
+    { category: 'iOS', value: 28 },
+  ],
+  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` ... |
+
+```javascript
+gptVis.render({
+  type: 'line',
+  data: [
+    { time: '2020', value: 100 },
+    { time: '2021', value: 120 },
+  ],
+  theme: 'dark',
+});
+```
+
+**自定义样式：**
+
+```javascript
+gptVis.render({
+  type: 'line',
+  data: [
+    { time: '2020', value: 100 },
+    { time: '2021', value: 120 },
+  ],
+  style: { lineWidth: 3, palette: ['#5B8FF9', '#5AD8A6'] },
+});
+```
+
+### DSL 语法
 
 类 Markdown 的声明式语法，LLM 无需学习复杂 API 即可生成：
 
@@ -121,14 +180,6 @@ 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
@@ -179,18 +230,21 @@ data
       - name 第二阶段
 ```
 
-### JSON 对象
-
-也支持直接传入 JSON 对象，适合程序化调用：
+**使用 DSL 语法渲染：**
 
 ```javascript
-gptVis.render({
-  type: 'pie',
-  data: [
-    { category: 'Android', value: 72 },
-    { category: 'iOS', value: 28 },
-  ],
-});
+const visSyntax = `
+vis line
+data
+  - time 2020
+    value 100
+  - time 2021
+    value 120
+  - time 2022
+    value 150
+`;
+
+gptVis.render(visSyntax);
 ```
 
 ## 📊 图表类型
@@ -391,6 +445,71 @@ 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 集成方案：

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,15 @@
+import { type Chart } from '@antv/g2';
+import type { VisualizationTheme } from '../types';
+export type CrosshairAxisLabelsOptions = {
+    showXLabel?: boolean;
+    useStandaloneYLabel?: boolean;
+    yAxisPosition?: 'left' | 'right';
+    yField?: string;
+};
+/**
+ * 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, { showXLabel, useStandaloneYLabel, yAxisPosition, yField, }?: CrosshairAxisLabelsOptions) => (() => void);