infographic-for-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lyw405
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# infographic-for-react
+
+> React components for @antv/infographic - a declarative, component-based wrapper for infographic generation.
+
+[中文文档](./README.zh-CN.md)
+
+[![npm version](https://img.shields.io/npm/v/infographic-for-react.svg)](https://www.npmjs.com/package/infographic-for-react)
+
+## Features
+
+- **🎯 Declarative API** - Use React components to render infographics with familiar patterns
+- **⚡ Lightweight** - Thin wrapper around the core infographic engine with minimal overhead
+- **🔧 Customizable** - Override DSL values with path-based API, apply themes and palettes
+- **🪝 Extensible** - `beforeRender` / `afterRender` hooks for custom preprocessing/postprocessing
+- **📦 Export Ready** - Built-in export to SVG/PNG data URLs
+- **🛡️ Error Handling** - Built-in error boundaries and error recovery
+- **🎨 Fully Typed** - Full TypeScript support with type-safe APIs
+
+## Installation
+
+```bash
+# Install infographic-for-react and its peer dependency @antv/infographic
+npm install infographic-for-react @antv/infographic
+```
+
+> **Note**: `@antv/infographic` is a peer dependency and must be installed separately. If you use npm v7+, it will be installed automatically, but we recommend explicitly installing it to ensure compatibility.
+
+## Quick Start
+
+### Basic Usage
+
+The simplest way to use `Infographic` is to pass a `dsl` prop with the template name and data configuration.
+
+```tsx
+import { Infographic } from 'infographic-for-react';
+
+function App() {
+  return (
+    <Infographic
+      dsl={{
+        template: 'template-name',
+        theme: 'light',
+        palette: 'antv',
+        data: {
+          title: 'My Infographic',
+          desc: 'Optional description',
+          items: [
+            {
+              label: 'Item 1',
+              value: 100,
+              desc: 'Item description',
+              icon: 'mingcute/diamond-2-fill',
+              illus: 'creative-experiment',
+              time: '2021',
+              children: [
+                ...,
+              ],
+            },
+            ...,
+          ],
+        },
+      }}
+      width={600}
+      height={400}
+    />
+  );
+}
+```
+
+### DSL Overrides
+
+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.
+
+```tsx
+import { Infographic } from 'infographic-for-react';
+
+function App() {
+  const overrides = [
+    { path: 'data.items[0].value', value: 200 },
+  ];
+
+  return (
+    <Infographic
+      dsl={{
+        template: 'template-name',
+        theme: 'light',
+        palette: 'antv',
+        data: {
+          title: 'My Infographic',
+          desc: 'Optional description',
+          items: [
+            {
+              label: 'Item 1',
+              value: 100,
+              desc: 'Item description',
+              icon: 'mingcute/diamond-2-fill',
+              illus: 'creative-experiment',
+              time: '2021',
+              children: [
+                ...,
+              ],
+            },
+            { label: 'Item 2', value: 200 },
+          ],
+        },
+      }}
+      overrides={overrides}
+      width={600}
+      height={400}
+    />
+  );
+}
+```
+
+### Using Hooks
+
+```tsx
+import { useInfographic } from 'infographic-for-react';
+import { useRef } from 'react';
+
+function App() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const infographic = useInfographic(containerRef, {
+    dsl: {
+      data: {
+        title: 'My Infographic',
+        items: [
+          { label: 'Item 1', value: 100 },
+        ],
+      },
+    },
+    onRender: (result) => console.log('Rendered:', result),
+  });
+
+  const handleExport = async () => {
+    const dataURL = await infographic.toDataURL({ type: 'svg' });
+    const link = document.createElement('a');
+    link.href = dataURL;
+    link.download = 'infographic.svg';
+    link.click();
+  };
+
+  return (
+    <div>
+      <button onClick={handleExport}>Export SVG</button>
+      <div ref={containerRef} style={{ width: 600, height: 400 }} />
+    </div>
+  );
+}
+```
+
+### Pre/Post Render Hooks
+
+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).
+
+```tsx
+import { Infographic } from 'infographic-for-react';
+import type { DSLObject } from 'infographic-for-react';
+
+function App() {
+  const beforeRender = (dsl: DSLObject): DSLObject => {
+    return {
+      ...dsl,
+      title: 'Processed: ' + dsl.title,
+    };
+  };
+
+  const afterRender = async (result) => {
+    console.log('Rendered element:', result.node);
+    console.log('Element count:', result.node.children.length);
+  };
+
+  return (
+    <Infographic
+      dsl={{
+        data: {
+          title: 'My Infographic',
+          items: [{ label: 'Item 1', value: 100 }],
+        },
+      }}
+      beforeRender={beforeRender}
+      afterRender={afterRender}
+    />
+  );
+}
+```
+
+## API Reference
+
+See [API.md](./docs/API.md) for detailed API documentation.
+
+[中文文档](./docs/API.zh-CN.md) is also available.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+## License
+
+[MIT](LICENSE) © lyw405
+
+## Repository
+
+[GitHub](https://github.com/lyw405/infographic-for-react)

package/README.zh-CN.md

@@ -0,0 +1,228 @@
+# infographic-for-react
+
+> React 组件库 for @antv/infographic - 基于组件化的声明式信息图表生成封装。
+
+[English documentation](./README.md)
+
+[![npm version](https://img.shields.io/npm/v/infographic-for-react.svg)](https://www.npmjs.com/package/infographic-for-react)
+
+## 特性
+
+- **🎯 声明式 API** - 使用熟悉的 React 组件模式渲染信息图表
+- **⚡ 轻量级** - 核心信息图表引擎的轻量级封装，开销最小
+- **🔧 可定制** - 基于路径的 API 覆盖 DSL 值，应用主题和调色板
+- **🪝 可扩展** - `beforeRender` / `afterRender` 钩子用于自定义预处理/后处理
+- **📦 导出就绪** - 内置导出为 SVG/PNG 数据 URL
+- **🛡️ 错误处理** - 内置错误边界和错误恢复
+- **🎨 完整类型** - 完整的 TypeScript 支持和类型安全 API
+
+## 安装
+
+```bash
+# 安装 infographic-for-react 及其 peer dependency @antv/infographic
+npm install infographic-for-react @antv/infographic
+```
+
+> **注意**：`@antv/infographic` 是 peer dependency，需要单独安装。如果你使用 npm v7+，它会自动安装，但我们建议显式安装以确保兼容性。
+
+## 快速开始
+
+### 基础用法
+
+使用 `Infographic` 最简单的方式是传入包含模板名称和数据配置的 `dsl` 属性。
+
+```tsx
+import { Infographic } from 'infographic-for-react';
+
+function App() {
+  return (
+    <Infographic
+      dsl={{
+        template: '模板名称',
+        theme: 'light',
+        palette: 'antv',
+        data: {
+          title: '我的信息图表',
+          desc: '可选描述',
+          items: [
+            {
+              label: '项目 1',
+              value: 100,
+              desc: '项目描述',
+              icon: 'mingcute/diamond-2-fill',
+              illus: 'creative-experiment',
+              time: '2021',
+              children: [
+                ...
+              ],
+            },
+            { label: '项目 2', value: 200 },
+          ],
+        },
+      }}
+      width={600}
+      height={400}
+    />
+  );
+}
+```
+
+### DSL 覆盖
+
+使用 `overrides` 属性可以通过路径选择性地修改 DSL 值，而无需重新创建整个 DSL 对象。这对于动态更新或主题切换非常有用。
+
+```tsx
+import { Infographic } from 'infographic-for-react';
+
+function App() {
+  const overrides = [
+    { path: 'data.items[0].value', value: 200 },
+  ];
+
+  return (
+    <Infographic
+      dsl={{
+        template: '模板名称',
+        theme: 'light',
+        palette: 'antv',
+        data: {
+          title: '我的信息图表',
+          desc: '可选描述',
+          items: [
+            {
+              label: '项目 1',
+              value: 100,
+              desc: '项目描述',
+              icon: 'mingcute/diamond-2-fill',
+              illus: 'creative-experiment',
+              time: '2021',
+              children: [
+                ...,
+              ],
+            },
+            { label: '项目 2', value: 200 },
+          ],
+        },
+      }}
+      overrides={overrides}
+      width={600}
+      height={400}
+    />
+  );
+}
+```
+
+### 使用 Hooks
+
+```tsx
+import { useInfographic } from 'infographic-for-react';
+import { useRef } from 'react';
+
+function App() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const infographic = useInfographic(containerRef, {
+    dsl: {
+      data: {
+        title: '我的信息图表',
+        items: [
+          { label: '项目 1', value: 100 },
+        ],
+      },
+    },
+    onRender: (result) => console.log('已渲染:', result),
+  });
+
+  const handleExport = async () => {
+    const dataURL = await infographic.toDataURL({ type: 'svg' });
+    const link = document.createElement('a');
+    link.href = dataURL;
+    link.download = 'infographic.svg';
+    link.click();
+  };
+
+  return (
+    <div>
+      <button onClick={handleExport}>导出 SVG</button>
+      <div ref={containerRef} style={{ width: 600, height: 400 }} />
+    </div>
+  );
+}
+```
+
+### 渲染前/后钩子
+
+使用 `beforeRender` 在渲染前预处理 DSL，使用 `afterRender` 在信息图表渲染后执行操作（如日志记录、分析、自定义后处理）。
+
+```tsx
+import { Infographic } from 'infographic-for-react';
+import type { DSLObject } from 'infographic-for-react';
+
+function App() {
+  const beforeRender = (dsl: DSLObject): DSLObject => {
+    return {
+      ...dsl,
+      title: '已处理: ' + dsl.title,
+    };
+  };
+
+  const afterRender = async (result) => {
+    console.log('渲染的元素:', result.node);
+    console.log('元素数量:', result.node.children.length);
+  };
+
+  return (
+    <Infographic
+      dsl={{
+        title: '我的信息图表',
+        data: {
+          title: '数据标题',
+          items: [{ label: '项目 1', value: 100 }],
+        },
+      }}
+      beforeRender={beforeRender}
+      afterRender={afterRender}
+    />
+  );
+}
+```
+
+## API 参考
+
+详细 API 文档请参阅 [API.zh-CN.md](./docs/API.zh-CN.md)。
+
+[English documentation](./docs/API.md) is also available.
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 构建
+npm run build
+
+# 运行测试
+npm test
+
+# 类型检查
+npm run typecheck
+
+# 代码检查
+npm run lint
+
+# 格式化代码
+npm run format
+```
+
+## 贡献
+
+欢迎贡献！提交 PR 之前请阅读我们的贡献指南。
+
+## 许可证
+
+[MIT](LICENSE) © lyw405
+
+## 仓库地址
+
+[GitHub](https://github.com/lyw405/infographic-for-react)

package/dist/index.d.mts

@@ -0,0 +1,119 @@
+import React$1, { Component, ReactNode, ErrorInfo } from 'react';
+import { InfographicOptions, Palette, ThemeConfig, ExportOptions } from '@antv/infographic';
+export { ExportOptions, InfographicOptions, Palette, SyntaxError, ThemeConfig } from '@antv/infographic';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface DSLItem {
+    label: string;
+    desc?: string;
+    icon?: string;
+    illus?: string;
+    value?: number;
+    time?: string;
+    children?: DSLItem[];
+}
+interface DSLData {
+    title: string;
+    desc?: string;
+    items: DSLItem[];
+}
+interface DSLTheme {
+    name: string;
+    palette: string;
+}
+interface DSLObject extends Partial<InfographicOptions> {
+    data: DSLData;
+    palette?: Palette;
+    themeConfig?: ThemeConfig;
+}
+type DSLInput = DSLObject;
+interface DSLOverride {
+    path: string;
+    value: unknown;
+}
+type PreRenderHook = (dsl: DSLObject) => DSLObject | Promise<DSLObject>;
+interface InfographicRenderResult {
+    node: SVGSVGElement;
+    options: Partial<InfographicOptions>;
+}
+interface InfographicError {
+    type: 'syntax' | 'render' | 'runtime';
+    message: string;
+    dsl?: string;
+    details?: string | Error | unknown;
+}
+type PostRenderHook = (result: InfographicRenderResult) => void | Promise<void>;
+interface ComposeTemplateOptions {
+    templates: DSLObject[];
+    overrides?: DSLOverride[];
+}
+interface InfographicProps {
+    dsl?: DSLInput;
+    overrides?: DSLOverride[];
+    theme?: string;
+    palette?: Palette;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+    editable?: boolean;
+    beforeRender?: PreRenderHook;
+    afterRender?: PostRenderHook;
+    onRender?: (result: InfographicRenderResult) => void;
+    onError?: (error: InfographicError) => void;
+    onLoad?: (result: InfographicRenderResult) => void;
+}
+interface InfographicRef {
+    toDataURL: (options?: ExportOptions) => Promise<string>;
+    getTypes: () => string | undefined;
+    update: (options: DSLInput) => Promise<void>;
+    destroy: () => void;
+}
+interface RendererInstance {
+    render: (options?: Partial<InfographicOptions>) => void;
+    update: (options: Partial<InfographicOptions>) => void;
+    toDataURL: (options?: ExportOptions) => Promise<string>;
+    getTypes: () => string | undefined;
+    destroy: () => void;
+    on: (event: string, listener: (...args: any[]) => void) => void;
+    off: (event: string, listener: (...args: any[]) => void) => void;
+}
+
+declare const Infographic: React$1.ForwardRefExoticComponent<InfographicProps & React$1.RefAttributes<InfographicRef>>;
+
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode | ((error: Error, errorInfo: ErrorInfo) => ReactNode);
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error?: Error;
+    errorInfo?: ErrorInfo;
+}
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    handleReset: () => void;
+    render(): string | number | boolean | react_jsx_runtime.JSX.Element | Iterable<ReactNode> | null | undefined;
+}
+
+declare function useRenderer(containerRef: React.RefObject<HTMLElement>): {
+    render: (options: Partial<InfographicOptions>) => Promise<void>;
+    update: (options: Partial<InfographicOptions>) => void;
+    toDataURL: (options?: ExportOptions) => Promise<string>;
+    getTypes: () => string | undefined;
+    destroy: () => void;
+    on: (event: string, listener: (...args: any[]) => void) => void;
+    off: (event: string, listener: (...args: any[]) => void) => void;
+    isReady: boolean;
+};
+
+declare function useInfographic(containerRef: React.RefObject<HTMLElement>, props: InfographicProps): InfographicRef;
+
+declare function applyOverrides(base: DSLObject, overrides: DSLOverride[]): DSLObject;
+declare function mergeDSL(dsl1: DSLObject, dsl2: DSLObject): DSLObject;
+
+declare function composeTemplates(options: ComposeTemplateOptions): DSLObject;
+
+export { type ComposeTemplateOptions, type DSLData, type DSLInput, type DSLItem, type DSLObject, type DSLOverride, type DSLTheme, ErrorBoundary, Infographic, type InfographicError, type InfographicProps, type InfographicRef, type InfographicRenderResult, type PostRenderHook, type PreRenderHook, type RendererInstance, applyOverrides, composeTemplates, mergeDSL, useInfographic, useRenderer };

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+import React$1, { Component, ReactNode, ErrorInfo } from 'react';
+import { InfographicOptions, Palette, ThemeConfig, ExportOptions } from '@antv/infographic';
+export { ExportOptions, InfographicOptions, Palette, SyntaxError, ThemeConfig } from '@antv/infographic';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface DSLItem {
+    label: string;
+    desc?: string;
+    icon?: string;
+    illus?: string;
+    value?: number;
+    time?: string;
+    children?: DSLItem[];
+}
+interface DSLData {
+    title: string;
+    desc?: string;
+    items: DSLItem[];
+}
+interface DSLTheme {
+    name: string;
+    palette: string;
+}
+interface DSLObject extends Partial<InfographicOptions> {
+    data: DSLData;
+    palette?: Palette;
+    themeConfig?: ThemeConfig;
+}
+type DSLInput = DSLObject;
+interface DSLOverride {
+    path: string;
+    value: unknown;
+}
+type PreRenderHook = (dsl: DSLObject) => DSLObject | Promise<DSLObject>;
+interface InfographicRenderResult {
+    node: SVGSVGElement;
+    options: Partial<InfographicOptions>;
+}
+interface InfographicError {
+    type: 'syntax' | 'render' | 'runtime';
+    message: string;
+    dsl?: string;
+    details?: string | Error | unknown;
+}
+type PostRenderHook = (result: InfographicRenderResult) => void | Promise<void>;
+interface ComposeTemplateOptions {
+    templates: DSLObject[];
+    overrides?: DSLOverride[];
+}
+interface InfographicProps {
+    dsl?: DSLInput;
+    overrides?: DSLOverride[];
+    theme?: string;
+    palette?: Palette;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+    editable?: boolean;
+    beforeRender?: PreRenderHook;
+    afterRender?: PostRenderHook;
+    onRender?: (result: InfographicRenderResult) => void;
+    onError?: (error: InfographicError) => void;
+    onLoad?: (result: InfographicRenderResult) => void;
+}
+interface InfographicRef {
+    toDataURL: (options?: ExportOptions) => Promise<string>;
+    getTypes: () => string | undefined;
+    update: (options: DSLInput) => Promise<void>;
+    destroy: () => void;
+}
+interface RendererInstance {
+    render: (options?: Partial<InfographicOptions>) => void;
+    update: (options: Partial<InfographicOptions>) => void;
+    toDataURL: (options?: ExportOptions) => Promise<string>;
+    getTypes: () => string | undefined;
+    destroy: () => void;
+    on: (event: string, listener: (...args: any[]) => void) => void;
+    off: (event: string, listener: (...args: any[]) => void) => void;
+}
+
+declare const Infographic: React$1.ForwardRefExoticComponent<InfographicProps & React$1.RefAttributes<InfographicRef>>;
+
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode | ((error: Error, errorInfo: ErrorInfo) => ReactNode);
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error?: Error;
+    errorInfo?: ErrorInfo;
+}
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    handleReset: () => void;
+    render(): string | number | boolean | react_jsx_runtime.JSX.Element | Iterable<ReactNode> | null | undefined;
+}
+
+declare function useRenderer(containerRef: React.RefObject<HTMLElement>): {
+    render: (options: Partial<InfographicOptions>) => Promise<void>;
+    update: (options: Partial<InfographicOptions>) => void;
+    toDataURL: (options?: ExportOptions) => Promise<string>;
+    getTypes: () => string | undefined;
+    destroy: () => void;
+    on: (event: string, listener: (...args: any[]) => void) => void;
+    off: (event: string, listener: (...args: any[]) => void) => void;
+    isReady: boolean;
+};
+
+declare function useInfographic(containerRef: React.RefObject<HTMLElement>, props: InfographicProps): InfographicRef;
+
+declare function applyOverrides(base: DSLObject, overrides: DSLOverride[]): DSLObject;
+declare function mergeDSL(dsl1: DSLObject, dsl2: DSLObject): DSLObject;
+
+declare function composeTemplates(options: ComposeTemplateOptions): DSLObject;
+
+export { type ComposeTemplateOptions, type DSLData, type DSLInput, type DSLItem, type DSLObject, type DSLOverride, type DSLTheme, ErrorBoundary, Infographic, type InfographicError, type InfographicProps, type InfographicRef, type InfographicRenderResult, type PostRenderHook, type PreRenderHook, type RendererInstance, applyOverrides, composeTemplates, mergeDSL, useInfographic, useRenderer };