infographic-for-react 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +87 -4
  2. package/README.zh-CN.md +114 -4
  3. package/dist/index.d.mts +8 -7
  4. package/dist/index.d.ts +8 -7
  5. package/dist/index.js +338 -208
  6. package/dist/index.js.map +1 -1
  7. package/dist/index.mjs +339 -209
  8. package/dist/index.mjs.map +1 -1
  9. package/package.json +3 -1
package/README.md CHANGED
@@ -27,9 +27,92 @@ npm install infographic-for-react @antv/infographic
27
27
 
28
28
  ## Quick Start
29
29
 
30
- ### Basic Usage
30
+ ### String DSL (Recommended for Static Templates)
31
31
 
32
- The simplest way to use `Infographic` is to pass a `dsl` prop with the template name and data configuration.
32
+ Use the native infographic string DSL syntax for a concise, template-based approach.
33
+
34
+ ```tsx
35
+ import { Infographic } from 'infographic-for-react';
36
+
37
+ function App() {
38
+ const dslString = `
39
+ infographic sales-dashboard
40
+ theme
41
+ palette #f00 #0f0 #00f
42
+ data
43
+ title Q1 Growth Highlights
44
+ items
45
+ - label MAU
46
+ value 12.3
47
+ - label Revenue
48
+ value 4.5
49
+ `;
50
+
51
+ return (
52
+ <Infographic
53
+ dsl={dslString}
54
+ width={600}
55
+ height={400}
56
+ />
57
+ );
58
+ }
59
+ ```
60
+
61
+ > **Note**: When using string DSL, the `overrides` and `beforeRender` props are ignored. Use object DSL if you need these features.
62
+
63
+ ### Children DSL (Recommended for Most Use Cases)
64
+
65
+ For a more declarative and React-like syntax, pass DSL as the component's children. This is particularly useful for static templates and provides better readability with preserved formatting.
66
+
67
+ > **⚠️ Important**: When using children DSL, you **must** wrap DSL content in a template literal `{}` to preserve newlines and indentation. This prevents React from collapsing whitespace.
68
+
69
+ ```tsx
70
+ import { Infographic } from 'infographic-for-react';
71
+
72
+ function App() {
73
+ return (
74
+ <Infographic width={600} height={400}>
75
+ {`infographic list-row-simple-horizontal-arrow
76
+ data
77
+ items
78
+ - label Step 1
79
+ desc Start
80
+ - label Step 2
81
+ desc In Progress
82
+ - label Step 3
83
+ desc Complete
84
+ `}
85
+ </Infographic>
86
+ );
87
+ }
88
+ ```
89
+
90
+ ```tsx
91
+ // You can also use template literals for dynamic content with variable interpolation
92
+ function App() {
93
+ const title = 'My Dashboard';
94
+ const items = [
95
+ { label: 'MAU', value: 12.3 },
96
+ { label: 'Revenue', value: 4.5 },
97
+ ];
98
+
99
+ return (
100
+ <Infographic>
101
+ {`infographic sales-dashboard
102
+ data
103
+ title ${title}
104
+ items
105
+ ${items.map((item) => ` - label ${item.label}\n value ${item.value}`).join('\n')}`}
106
+ </Infographic>
107
+ );
108
+ }
109
+ ```
110
+
111
+ > **Note**: When using children DSL, the `overrides` and `beforeRender` props are ignored. Use object DSL if you need these features. The `dsl` prop is also ignored when children are provided (children take precedence).
112
+
113
+ ### Basic Usage (Object DSL)
114
+
115
+ Use object DSL for full TypeScript type safety and access to advanced features like `overrides` and `beforeRender` hooks.
33
116
 
34
117
  ```tsx
35
118
  import { Infographic } from 'infographic-for-react';
@@ -69,7 +152,7 @@ function App() {
69
152
 
70
153
  ### DSL Overrides
71
154
 
72
- Use the `overrides` prop to selectively modify DSL values by path without recreating the entire DSL object. This is useful for dynamic updates or theming.
155
+ Use the `overrides` prop to selectively modify DSL values by path without recreating entire DSL object. This is useful for dynamic updates or theming. **Only works with object DSL**.
73
156
 
74
157
  ```tsx
75
158
  import { Infographic } from 'infographic-for-react';
@@ -152,7 +235,7 @@ function App() {
152
235
 
153
236
  ### Pre/Post Render Hooks
154
237
 
155
- Use `beforeRender` to preprocess the DSL before rendering, and `afterRender` to perform actions after the infographic is rendered (e.g., logging, analytics, custom post-processing).
238
+ Use `beforeRender` to preprocess DSL before rendering, and `afterRender` to perform actions after infographic is rendered (e.g., logging, analytics, custom post-processing). **Only works with object DSL**.
156
239
 
157
240
  ```tsx
158
241
  import { Infographic } from 'infographic-for-react';
package/README.zh-CN.md CHANGED
@@ -27,9 +27,92 @@ npm install infographic-for-react @antv/infographic
27
27
 
28
28
  ## 快速开始
29
29
 
30
- ### 基础用法
30
+ ### 字符串 DSL
31
31
 
32
- 使用 `Infographic` 最简单的方式是传入包含模板名称和数据配置的 `dsl` 属性。
32
+ 使用原生信息图表的字符串 DSL 语法，这种方式更简洁，适合基于模板的配置。
33
+
34
+ ```tsx
35
+ import { Infographic } from 'infographic-for-react';
36
+
37
+ function App() {
38
+ const dslString = `
39
+ infographic 销售仪表盘
40
+ theme
41
+ palette #f00 #0f0 #00f
42
+ data
43
+ title 第一季度增长亮点
44
+ items
45
+ - label 月活跃用户
46
+ value 12.3
47
+ - label 营收
48
+ value 4.5
49
+ `;
50
+
51
+ return (
52
+ <Infographic
53
+ dsl={dslString}
54
+ width={600}
55
+ height={400}
56
+ />
57
+ );
58
+ }
59
+ ```
60
+
61
+ > **注意**：使用字符串 DSL 时，`overrides` 和 `beforeRender` 属性会被忽略。如需使用这些功能，请使用对象 DSL。
62
+
63
+ ### Children DSL（推荐大多数场景）
64
+
65
+ 为了获得更符合 React 风格的语法，你可以将 DSL 作为组件的 children 传递。这种方式特别适合静态模板，并且能更好地保留格式和缩进。
66
+
67
+ > **⚠️ 重要提示**：使用 children DSL 时，**必须**使用模板字符串 `{}` 包裹 DSL 内容，以保留换行和缩进。这样可以防止 React 合并空白字符。
68
+
69
+ ```tsx
70
+ import { Infographic } from 'infographic-for-react';
71
+
72
+ function App() {
73
+ return (
74
+ <Infographic width={600} height={400}>
75
+ {`infographic list-row-simple-horizontal-arrow
76
+ data
77
+ items
78
+ - label 步骤 1
79
+ desc 开始
80
+ - label 步骤 2
81
+ desc 进行中
82
+ - label 步骤 3
83
+ desc 完成
84
+ `}
85
+ </Infographic>
86
+ );
87
+ }
88
+ ```
89
+
90
+ ```tsx
91
+ // 你也可以使用模板字符串来动态生成内容，支持变量插值
92
+ function App() {
93
+ const title = '我的仪表盘';
94
+ const items = [
95
+ { label: '月活跃用户', value: 12.3 },
96
+ { label: '营收', value: 4.5 },
97
+ ];
98
+
99
+ return (
100
+ <Infographic>
101
+ {`infographic 销售仪表盘
102
+ data
103
+ title ${title}
104
+ items
105
+ ${items.map((item) => ` - label ${item.label}\n value ${item.value}`).join('\n')}`}
106
+ </Infographic>
107
+ );
108
+ }
109
+ ```
110
+
111
+ > **注意**：使用 children DSL 时，`overrides` 和 `beforeRender` 属性会被忽略。如需使用这些功能，请使用对象 DSL。当提供 children 时，`dsl` 属性也会被忽略（children 优先级更高）。
112
+
113
+ ### 基础用法（对象 DSL）
114
+
115
+ 使用对象 DSL 获得完整的 TypeScript 类型支持和 `overrides`、`beforeRender` 钩子等高级功能。
33
116
 
34
117
  ```tsx
35
118
  import { Infographic } from 'infographic-for-react';
@@ -69,7 +152,34 @@ function App() {
69
152
 
70
153
  ### DSL 覆盖
71
154
 
72
- 使用 `overrides` 属性可以通过路径选择性地修改 DSL 值，而无需重新创建整个 DSL 对象。这对于动态更新或主题切换非常有用。
155
+ 使用 `overrides` 属性可以通过路径选择性地修改 DSL 值，而无需重新创建整个 DSL 对象。这对于动态更新或主题切换非常有用。**仅适用于对象 DSL**。
156
+
157
+ ```tsx
158
+ import { Infographic } from 'infographic-for-react';
159
+
160
+ function App() {
161
+ const overrides = [
162
+ { path: 'data.items[0].value', value: 200 },
163
+ ];
164
+
165
+ return (
166
+ <Infographic>
167
+ {`infographic 销售仪表盘
168
+ data
169
+ title ${title}
170
+ items
171
+ ${items.map((item) => ` - label ${item.label}\n value ${item.value}`).join('\n')}`}
172
+ </Infographic>
173
+ );
174
+ }
175
+ ```
176
+
177
+ > **注意**：使用 children DSL 时，`overrides` 和 `beforeRender` 属性会被忽略。如需使用这些功能，请使用对象 DSL。当提供 children 时，`dsl` 属性也会被忽略（children 优先级更高）。
178
+
179
+
180
+ ### DSL 覆盖
181
+
182
+ 使用 `overrides` 属性可以通过路径选择性地修改 DSL 值，而无需重新创建整个 DSL 对象。这对于动态更新或主题切换非常有用。**仅适用于对象 DSL**。
73
183
 
74
184
  ```tsx
75
185
  import { Infographic } from 'infographic-for-react';
@@ -152,7 +262,7 @@ function App() {
152
262
 
153
263
  ### 渲染前/后钩子
154
264
 
155
- 使用 `beforeRender` 在渲染前预处理 DSL，使用 `afterRender` 在信息图表渲染后执行操作（如日志记录、分析、自定义后处理）。
265
+ 使用 `beforeRender` 在渲染前预处理 DSL，使用 `afterRender` 在信息图表渲染后执行操作（如日志记录、分析、自定义后处理）。**仅适用于对象 DSL**。
156
266
 
157
267
  ```tsx
158
268
  import { Infographic } from 'infographic-for-react';
package/dist/index.d.mts CHANGED
@@ -26,7 +26,7 @@ interface DSLObject extends Partial<InfographicOptions> {
26
26
  palette?: Palette;
27
27
  themeConfig?: ThemeConfig;
28
28
  }
29
- type DSLInput = DSLObject;
29
+ type DSLInput = string | DSLObject;
30
30
  interface DSLOverride {
31
31
  path: string;
32
32
  value: unknown;
@@ -48,6 +48,7 @@ interface ComposeTemplateOptions {
48
48
  overrides?: DSLOverride[];
49
49
  }
50
50
  interface InfographicProps {
51
+ children?: string;
51
52
  dsl?: DSLInput;
52
53
  overrides?: DSLOverride[];
53
54
  theme?: string;
@@ -69,8 +70,8 @@ interface InfographicRef {
69
70
  destroy: () => void;
70
71
  }
71
72
  interface RendererInstance {
72
- render: (options?: Partial<InfographicOptions>) => void;
73
- update: (options: Partial<InfographicOptions>) => void;
73
+ render: (options?: string | Partial<InfographicOptions>) => void;
74
+ update: (options: string | Partial<InfographicOptions>) => void;
74
75
  toDataURL: (options?: ExportOptions) => Promise<string>;
75
76
  getTypes: () => string | undefined;
76
77
  destroy: () => void;
@@ -98,9 +99,11 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryS
98
99
  render(): string | number | boolean | react_jsx_runtime.JSX.Element | Iterable<ReactNode> | null | undefined;
99
100
  }
100
101
 
102
+ declare function useInfographic(containerRef: React.RefObject<HTMLElement>, props: InfographicProps): InfographicRef;
103
+
101
104
  declare function useRenderer(containerRef: React.RefObject<HTMLElement>): {
102
- render: (options: Partial<InfographicOptions>) => Promise<void>;
103
- update: (options: Partial<InfographicOptions>) => void;
105
+ render: (options: string | Partial<InfographicOptions>) => Promise<void>;
106
+ update: (options: string | Partial<InfographicOptions>) => void;
104
107
  toDataURL: (options?: ExportOptions) => Promise<string>;
105
108
  getTypes: () => string | undefined;
106
109
  destroy: () => void;
@@ -109,8 +112,6 @@ declare function useRenderer(containerRef: React.RefObject<HTMLElement>): {
109
112
  isReady: boolean;
110
113
  };
111
114
 
112
- declare function useInfographic(containerRef: React.RefObject<HTMLElement>, props: InfographicProps): InfographicRef;
113
-
114
115
  declare function applyOverrides(base: DSLObject, overrides: DSLOverride[]): DSLObject;
115
116
  declare function mergeDSL(dsl1: DSLObject, dsl2: DSLObject): DSLObject;
116
117
 
package/dist/index.d.ts CHANGED
@@ -26,7 +26,7 @@ interface DSLObject extends Partial<InfographicOptions> {
26
26
  palette?: Palette;
27
27
  themeConfig?: ThemeConfig;
28
28
  }
29
- type DSLInput = DSLObject;
29
+ type DSLInput = string | DSLObject;
30
30
  interface DSLOverride {
31
31
  path: string;
32
32
  value: unknown;
@@ -48,6 +48,7 @@ interface ComposeTemplateOptions {
48
48
  overrides?: DSLOverride[];
49
49
  }
50
50
  interface InfographicProps {
51
+ children?: string;
51
52
  dsl?: DSLInput;
52
53
  overrides?: DSLOverride[];
53
54
  theme?: string;
@@ -69,8 +70,8 @@ interface InfographicRef {
69
70
  destroy: () => void;
70
71
  }
71
72
  interface RendererInstance {
72
- render: (options?: Partial<InfographicOptions>) => void;
73
- update: (options: Partial<InfographicOptions>) => void;
73
+ render: (options?: string | Partial<InfographicOptions>) => void;
74
+ update: (options: string | Partial<InfographicOptions>) => void;
74
75
  toDataURL: (options?: ExportOptions) => Promise<string>;
75
76
  getTypes: () => string | undefined;
76
77
  destroy: () => void;
@@ -98,9 +99,11 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryS
98
99
  render(): string | number | boolean | react_jsx_runtime.JSX.Element | Iterable<ReactNode> | null | undefined;
99
100
  }
100
101
 
102
+ declare function useInfographic(containerRef: React.RefObject<HTMLElement>, props: InfographicProps): InfographicRef;
103
+
101
104
  declare function useRenderer(containerRef: React.RefObject<HTMLElement>): {
102
- render: (options: Partial<InfographicOptions>) => Promise<void>;
103
- update: (options: Partial<InfographicOptions>) => void;
105
+ render: (options: string | Partial<InfographicOptions>) => Promise<void>;
106
+ update: (options: string | Partial<InfographicOptions>) => void;
104
107
  toDataURL: (options?: ExportOptions) => Promise<string>;
105
108
  getTypes: () => string | undefined;
106
109
  destroy: () => void;
@@ -109,8 +112,6 @@ declare function useRenderer(containerRef: React.RefObject<HTMLElement>): {
109
112
  isReady: boolean;
110
113
  };
111
114
 
112
- declare function useInfographic(containerRef: React.RefObject<HTMLElement>, props: InfographicProps): InfographicRef;
113
-
114
115
  declare function applyOverrides(base: DSLObject, overrides: DSLOverride[]): DSLObject;
115
116
  declare function mergeDSL(dsl1: DSLObject, dsl2: DSLObject): DSLObject;
116
117