@ant-design/agentic-ui 2.0.6 → 2.0.10

package/dist/plugins/chart/AreaChart/index.d.ts

@@ -2,26 +2,94 @@ import React from 'react';
 import { ChartContainerProps } from '../components';
 import { StatisticConfigType } from '../hooks/useChartStatistic';
 import { ChartDataItem } from '../utils';
+/**
+ * 面积图数据项类型
+ *
+ * 继承自 ChartDataItem，用于面积图的数据表示。
+ *
+ * @typedef {ChartDataItem} AreaChartDataItem
+ * @since 1.0.0
+ */
 export type AreaChartDataItem = ChartDataItem;
+/**
+ * 面积图配置项接口
+ *
+ * 定义了面积图的配置选项，包括数据集、主题、图例、网格等设置。
+ *
+ * @interface AreaChartConfigItem
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const config: AreaChartConfigItem = {
+ *   datasets: [data1, data2],
+ *   theme: 'light',
+ *   showLegend: true,
+ *   legendPosition: 'top',
+ *   showGrid: true,
+ *   xAxisLabel: '时间',
+ *   yAxisLabel: '数值'
+ * };
+ * ```
+ */
 export interface AreaChartConfigItem {
+    /** 数据集数组 */
     datasets: Array<(string | {
         x: number;
         y: number;
     })[]>;
+    /** 图表主题 */
     theme?: 'light' | 'dark';
+    /** 是否显示图例 */
     showLegend?: boolean;
+    /** 图例位置 */
     legendPosition?: 'top' | 'left' | 'bottom' | 'right';
+    /** 图例水平对齐方式 */
     legendAlign?: 'start' | 'center' | 'end';
+    /** 是否显示网格线 */
     showGrid?: boolean;
+    /** X轴标签 */
     xAxisLabel?: string;
+    /** Y轴标签 */
     yAxisLabel?: string;
+    /** X轴最小值 */
     xAxisMin?: number;
+    /** X轴最大值 */
     xAxisMax?: number;
+    /** Y轴最小值 */
     yAxisMin?: number;
+    /** Y轴最大值 */
     yAxisMax?: number;
+    /** X轴步长 */
     xAxisStep?: number;
+    /** Y轴步长 */
     yAxisStep?: number;
 }
+/**
+ * 面积图组件属性接口
+ *
+ * 定义了面积图组件的所有属性，继承自 ChartContainerProps。
+ * 支持数据配置、样式设置、交互功能等。
+ *
+ * @interface AreaChartProps
+ * @extends ChartContainerProps
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const props: AreaChartProps = {
+ *   title: '销售趋势',
+ *   data: [
+ *     { x: '2024-01', y: 100, type: '产品A' },
+ *     { x: '2024-02', y: 150, type: '产品A' }
+ *   ],
+ *   width: 800,
+ *   height: 400,
+ *   showLegend: true,
+ *   showGrid: true
+ * };
+ * ```
+ */
 export interface AreaChartProps extends ChartContainerProps {
     /** 图表标题 */
     title?: string;
@@ -62,5 +130,32 @@ export interface AreaChartProps extends ChartContainerProps {
     /** ChartStatistic组件配置：object表示单个配置，array表示多个配置 */
     statistic?: StatisticConfigType;
 }
+/**
+ * 面积图组件
+ *
+ * 基于 Chart.js 和 react-chartjs-2 实现的面积图组件。
+ * 支持数据可视化、交互、配置、统计等功能。
+ *
+ * @component
+ * @param {AreaChartProps} props - 组件属性
+ * @returns {React.ReactElement} 面积图组件
+ *
+ * @example
+ * ```tsx
+ * <AreaChart
+ *   title="销售趋势"
+ *   data={[
+ *     { x: '2024-01', y: 100, type: '产品A' },
+ *     { x: '2024-02', y: 150, type: '产品A' }
+ *   ]}
+ *   width={800}
+ *   height={400}
+ *   showLegend={true}
+ *   showGrid={true}
+ * />
+ * ```
+ *
+ * @since 1.0.0
+ */
 declare const AreaChart: React.FC<AreaChartProps>;
 export default AreaChart;

package/dist/plugins/chart/AreaChart/index.js

@@ -57,15 +57,25 @@ ChartJS.register(
 );
 var defaultColors = [
   "#1677ff",
+  // 蓝色
   "#8954FC",
+  // 紫色
   "#15e7e4",
+  // 青色
   "#F45BB5",
+  // 粉色
   "#00A6FF",
+  // 天蓝色
   "#33E59B",
+  // 绿色
   "#D666E4",
+  // 紫红色
   "#6151FF",
+  // 靛蓝色
   "#BF3C93",
+  // 深粉色
   "#005EE0"
+  // 深蓝色
 ];
 var hexToRgba = (hex, alpha) => {
   const sanitized = hex.replace("#", "");

package/dist/plugins/chart/BarChart/index.d.ts

@@ -3,26 +3,73 @@ import React from 'react';
 import { ChartContainerProps } from '../components';
 import { StatisticConfigType } from '../hooks/useChartStatistic';
 import { ChartDataItem } from '../utils';
+/**
+ * 柱状图数据项类型
+ *
+ * 继承自 ChartDataItem，用于柱状图的数据表示。
+ *
+ * @typedef {ChartDataItem} BarChartDataItem
+ * @since 1.0.0
+ */
 export type BarChartDataItem = ChartDataItem;
+/**
+ * 柱状图配置项接口
+ *
+ * 定义了柱状图的配置选项，包括数据集、主题、图例、网格等设置。
+ *
+ * @interface BarChartConfigItem
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const config: BarChartConfigItem = {
+ *   datasets: [data1, data2],
+ *   theme: 'light',
+ *   showLegend: true,
+ *   legendPosition: 'top',
+ *   showGrid: true,
+ *   xAxisLabel: '类别',
+ *   yAxisLabel: '数值',
+ *   stacked: false,
+ *   indexAxis: 'x'
+ * };
+ * ```
+ */
 export interface BarChartConfigItem {
+    /** 数据集数组 */
     datasets: Array<(string | {
         x: number;
         y: number;
     })[]>;
+    /** 图表主题 */
     theme?: 'light' | 'dark';
+    /** 是否显示图例 */
     showLegend?: boolean;
+    /** 图例位置 */
     legendPosition?: 'top' | 'left' | 'bottom' | 'right';
+    /** 图例水平对齐方式 */
     legendAlign?: 'start' | 'center' | 'end';
+    /** 是否显示网格线 */
     showGrid?: boolean;
+    /** X轴标签 */
     xAxisLabel?: string;
+    /** Y轴标签 */
     yAxisLabel?: string;
+    /** X轴最小值 */
     xAxisMin?: number;
+    /** X轴最大值 */
     xAxisMax?: number;
+    /** Y轴最小值 */
     yAxisMin?: number;
+    /** Y轴最大值 */
     yAxisMax?: number;
+    /** X轴步长 */
     xAxisStep?: number;
+    /** Y轴步长 */
     yAxisStep?: number;
+    /** 是否堆叠显示 */
     stacked?: boolean;
+    /** 索引轴方向 */
     indexAxis?: 'x' | 'y';
 }
 export interface BarChartProps extends ChartContainerProps {

package/dist/plugins/chart/DonutChart/index.d.ts

@@ -1,5 +1,33 @@
 import React from 'react';
 import type { DonutChartProps } from './types';
 export type { DonutChartConfig, DonutChartData, DonutChartProps, } from './types';
+/**
+ * 环形图组件
+ *
+ * 基于 Chart.js 和 react-chartjs-2 实现的环形图（甜甜圈图）组件。
+ * 支持饼图和环形图两种样式，提供数据可视化、交互、配置、统计等功能。
+ *
+ * @component
+ * @param {DonutChartProps} props - 组件属性
+ * @returns {React.ReactElement} 环形图组件
+ *
+ * @example
+ * ```tsx
+ * <DonutChart
+ *   title="销售占比"
+ *   data={[
+ *     { label: '产品A', value: 30 },
+ *     { label: '产品B', value: 50 },
+ *     { label: '产品C', value: 20 }
+ *   ]}
+ *   configs={[{ chartStyle: 'donut', showLegend: true }]}
+ *   width={400}
+ *   height={400}
+ *   showToolbar={true}
+ * />
+ * ```
+ *
+ * @since 1.0.0
+ */
 declare const DonutChart: React.FC<DonutChartProps>;
 export default DonutChart;

package/dist/plugins/chart/components/ChartToolBar/ChartToolBar.d.ts

@@ -1,12 +1,70 @@
 import { default as React } from 'react';
+/**
+ * @fileoverview 图表工具栏组件文件
+ *
+ * 该文件提供了图表工具栏组件的实现，用于显示图表标题、数据时间、下载按钮等。
+ *
+ * @author md-editor
+ * @version 1.0.0
+ * @since 2024
+ */
+/**
+ * 图表工具栏属性接口
+ *
+ * 定义了图表工具栏组件的所有属性。
+ *
+ * @interface ChartToolBarProps
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const props: ChartToolBarProps = {
+ *   title: '销售数据',
+ *   dataTime: '2024-01-01 00:00:00',
+ *   theme: 'light',
+ *   onDownload: () => console.log('下载图表'),
+ *   extra: <Button>自定义按钮</Button>
+ * };
+ * ```
+ */
 export interface ChartToolBarProps {
+    /** 图表标题 */
     title?: string;
+    /** 数据时间 */
     dataTime?: string;
+    /** 自定义CSS类名 */
     className?: string;
+    /** 图表主题 */
     theme?: 'light' | 'dark';
+    /** 下载回调函数 */
     onDownload?: () => void;
+    /** 额外内容 */
     extra?: React.ReactNode;
+    /** 过滤器内容 */
     filter?: React.ReactNode;
 }
+/**
+ * 图表工具栏组件
+ *
+ * 用于显示图表标题、数据时间、下载按钮等工具栏内容。
+ * 支持主题切换、自定义内容、下载功能等。
+ *
+ * @component
+ * @param {ChartToolBarProps} props - 组件属性
+ * @returns {React.ReactElement | null} 图表工具栏组件，当没有标题和额外内容时返回 null
+ *
+ * @example
+ * ```tsx
+ * <ChartToolBar
+ *   title="销售数据"
+ *   dataTime="2024-01-01 00:00:00"
+ *   theme="light"
+ *   onDownload={() => console.log('下载图表')}
+ *   extra={<Button>自定义按钮</Button>}
+ * />
+ * ```
+ *
+ * @since 1.0.0
+ */
 declare const ChartToolBar: React.FC<ChartToolBarProps>;
 export default ChartToolBar;

package/dist/plugins/chart/const.d.ts

@@ -1 +1,26 @@
+/**
+ * @fileoverview 图表插件常量定义文件
+ *
+ * 该文件定义了图表插件中使用的各种常量，包括默认颜色列表等。
+ *
+ * @author md-editor
+ * @version 1.0.0
+ * @since 2024
+ */
+/**
+ * 默认颜色列表
+ *
+ * 用于图表数据系列的颜色配置，提供10种预定义的颜色。
+ * 这些颜色经过精心挑选，确保在图表中具有良好的视觉效果和对比度。
+ *
+ * @constant
+ * @type {string[]}
+ * @default
+ * @example
+ * // 使用默认颜色列表
+ * const colors = defaultColorList;
+ * console.log(colors[0]); // '#1677ff'
+ *
+ * @since 1.0.0
+ */
 export declare const defaultColorList: string[];

package/dist/plugins/chart/const.js

@@ -1,15 +1,25 @@
 // src/plugins/chart/const.ts
 var defaultColorList = [
   "#1677ff",
+  // 蓝色
   "#15e7e4",
+  // 青色
   "#8954FC",
+  // 紫色
   "#F45BB5",
+  // 粉色
   "#00A6FF",
+  // 天蓝色
   "#33E59B",
+  // 绿色
   "#D666E4",
+  // 紫红色
   "#6151FF",
+  // 靛蓝色
   "#BF3C93",
+  // 深粉色
   "#005EE0"
+  // 深蓝色
 ];
 export {
   defaultColorList

package/dist/plugins/chart/index.d.ts

@@ -1,5 +1,19 @@
 import React from 'react';
 import { RenderElementProps } from 'slate-react';
+/**
+ * @fileoverview 图表插件主入口文件
+ *
+ * 该文件提供了完整的图表功能，包括：
+ * - 多种图表类型的组件（饼图、柱状图、折线图、面积图等）
+ * - 图表渲染和配置功能
+ * - 数据处理和格式化工具
+ * - 图表属性工具栏
+ * - 图表标记和容器组件
+ *
+ * @author md-editor
+ * @version 1.0.0
+ * @since 2024
+ */
 export { ChartAttrToolBar } from './ChartAttrToolBar';
 export * from './ChartMark';
 export { ChartRender } from './ChartRender';

package/dist/plugins/chart/utils.d.ts

@@ -7,6 +7,38 @@
  *          如果输入值为空或格式化过程中发生错误，则返回原始值。
  */
 export declare const stringFormatNumber: (value: string | number) => string | number;
+/**
+ * 防抖函数
+ *
+ * 创建一个防抖函数，该函数会在调用后等待指定的延迟时间，
+ * 如果在延迟时间内再次调用，则重新开始计时。
+ * 常用于限制函数调用频率，如搜索输入、窗口调整等场景。
+ *
+ * @param {Function} func - 要防抖的函数
+ * @param {number} delay - 延迟时间（毫秒）
+ * @returns {Function} 防抖后的函数，包含以下方法：
+ *   - `flush()`: 立即执行函数并清除定时器
+ *   - `cancel()`: 取消延迟执行
+ *
+ * @example
+ * ```typescript
+ * const debouncedSearch = debounce((query: string) => {
+ *   console.log('搜索:', query);
+ * }, 300);
+ *
+ * // 调用防抖函数
+ * debouncedSearch('hello');
+ * debouncedSearch('world'); // 只有这个会执行
+ *
+ * // 立即执行
+ * debouncedSearch.flush();
+ *
+ * // 取消执行
+ * debouncedSearch.cancel();
+ * ```
+ *
+ * @since 1.0.0
+ */
 export declare function debounce(func: {
     (): void;
     apply?: any;
@@ -16,68 +48,201 @@ export declare function debounce(func: {
     cancel(): void;
 };
 /**
- * 数据项接口，用于图表数据处理
+ * 图表数据项接口
+ *
+ * 定义了图表中单个数据项的结构，用于统一各种图表类型的数据格式。
+ * 支持多种图表类型的数据表示，包括分类、类型、坐标等信息。
+ *
+ * @interface ChartDataItem
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * const dataItem: ChartDataItem = {
+ *   x: '2024-01',
+ *   y: 100,
+ *   category: '销售',
+ *   type: '产品A',
+ *   xtitle: '月份',
+ *   ytitle: '销售额',
+ *   filterLabel: 'Q1'
+ * };
+ * ```
  */
 export interface ChartDataItem {
-    /** 数据类别 */
+    /** 数据类别，用于数据分组和筛选 */
     category?: string;
-    /** 数据类型 */
+    /** 数据类型，用于区分不同的数据系列 */
     type?: string;
-    /** X轴值 */
+    /** X轴值，可以是数字或字符串 */
     x: number | string;
-    /** Y轴值 */
+    /** Y轴值，可以是数字或字符串 */
     y: number | string;
-    /** X轴标题 */
+    /** X轴标题，用于显示轴标签 */
     xtitle?: string;
-    /** Y轴标题 */
+    /** Y轴标题，用于显示轴标签 */
     ytitle?: string;
-    /** 筛选标签 */
+    /** 筛选标签，用于数据筛选和过滤 */
     filterLabel?: string;
 }
 /**
- * 归一化 x 轴值，将字符串数字转换为数字，避免重复标签
- * @param value - 原始 x 轴值
- * @returns 归一化后的值
+ * 归一化 X 轴值
+ *
+ * 将字符串数字转换为数字类型，避免重复标签问题。
+ * 如果输入已经是数字，直接返回；如果是字符串，尝试转换为数字。
+ * 转换失败时返回原始值。
+ *
+ * @param {number | string} value - 原始 X 轴值
+ * @returns {number | string} 归一化后的值
+ *
+ * @example
+ * ```typescript
+ * normalizeXValue(123); // 123
+ * normalizeXValue('456'); // 456
+ * normalizeXValue('abc'); // 'abc'
+ * normalizeXValue(''); // ''
+ * ```
+ *
+ * @since 1.0.0
  */
 export declare const normalizeXValue: (value: number | string) => number | string;
 /**
- * 比较两个 x 轴值的大小，用于排序
- * @param a - 第一个值
- * @param b - 第二个值
- * @returns 比较结果
+ * 比较两个 X 轴值的大小
+ *
+ * 用于对 X 轴值进行排序，支持数字和字符串的混合比较。
+ * 比较规则：
+ * 1. 数字优先于字符串
+ * 2. 数字按数值大小比较
+ * 3. 字符串按字典序比较
+ *
+ * @param {number | string} a - 第一个值
+ * @param {number | string} b - 第二个值
+ * @returns {number} 比较结果：负数表示 a < b，0 表示 a = b，正数表示 a > b
+ *
+ * @example
+ * ```typescript
+ * compareXValues(1, 2); // -1
+ * compareXValues('a', 'b'); // -1
+ * compareXValues(1, 'a'); // -1 (数字优先)
+ * compareXValues('a', 1); // 1 (数字优先)
+ * ```
+ *
+ * @since 1.0.0
  */
 export declare const compareXValues: (a: number | string, b: number | string) => number;
 /**
- * 检查两个 x 轴值是否相等
- * @param a - 第一个值
- * @param b - 第二个值
- * @returns 是否相等
+ * 检查两个 X 轴值是否相等
+ *
+ * 比较两个 X 轴值是否相等，支持数字和字符串的混合比较。
+ * 先对值进行归一化处理，然后进行比较。
+ *
+ * @param {number | string} a - 第一个值
+ * @param {number | string} b - 第二个值
+ * @returns {boolean} 是否相等
+ *
+ * @example
+ * ```typescript
+ * isXValueEqual(1, 1); // true
+ * isXValueEqual('1', 1); // true
+ * isXValueEqual('a', 'a'); // true
+ * isXValueEqual(1, 2); // false
+ * ```
+ *
+ * @since 1.0.0
  */
 export declare const isXValueEqual: (a: number | string, b: number | string) => boolean;
 /**
- * 从数据中提取并排序 x 轴值
- * @param data - 图表数据数组
- * @returns 排序后的唯一 x 轴值数组
+ * 从数据中提取并排序 X 轴值
+ *
+ * 从图表数据数组中提取所有唯一的 X 轴值，并进行排序。
+ * 先对值进行归一化处理，然后去重并排序。
+ *
+ * @param {ChartDataItem[]} data - 图表数据数组
+ * @returns {Array<number | string>} 排序后的唯一 X 轴值数组
+ *
+ * @example
+ * ```typescript
+ * const data = [
+ *   { x: '2024-01', y: 100 },
+ *   { x: '2024-02', y: 200 },
+ *   { x: '2024-01', y: 150 }, // 重复值
+ *   { x: 3, y: 300 }
+ * ];
+ * const sortedValues = extractAndSortXValues(data);
+ * // ['2024-01', '2024-02', 3]
+ * ```
+ *
+ * @since 1.0.0
  */
 export declare const extractAndSortXValues: (data: ChartDataItem[]) => Array<number | string>;
 /**
- * 根据 x 轴值查找对应的数据点
- * @param data - 数据数组
- * @param type - 数据类型
- * @param xValue - x 轴值
- * @returns 匹配的数据点，如果未找到返回 undefined
+ * 根据 X 轴值查找对应的数据点
+ *
+ * 在数据数组中查找指定 X 轴值对应的数据点。
+ * 可以指定数据类型进行精确匹配。
+ *
+ * @param {ChartDataItem[]} data - 数据数组
+ * @param {number | string} xValue - X 轴值
+ * @param {string} [type] - 数据类型，可选
+ * @returns {ChartDataItem | undefined} 匹配的数据点，如果未找到返回 undefined
+ *
+ * @example
+ * ```typescript
+ * const data = [
+ *   { x: '2024-01', y: 100, type: 'A' },
+ *   { x: '2024-01', y: 200, type: 'B' },
+ *   { x: '2024-02', y: 300, type: 'A' }
+ * ];
+ *
+ * // 查找所有类型
+ * findDataPointByXValue(data, '2024-01'); // 第一个匹配项
+ *
+ * // 查找指定类型
+ * findDataPointByXValue(data, '2024-01', 'B'); // { x: '2024-01', y: 200, type: 'B' }
+ * ```
+ *
+ * @since 1.0.0
  */
 export declare const findDataPointByXValue: (data: ChartDataItem[], xValue: number | string, type?: string) => ChartDataItem | undefined;
 /**
  * 将值转换为数字
- * @param val - 要转换的值
- * @param fallback - 转换失败时的默认值
- * @returns 转换后的数字
+ *
+ * 安全地将任意值转换为数字类型，转换失败时返回默认值。
+ * 如果输入已经是有效的数字，直接返回；否则尝试转换。
+ *
+ * @param {any} val - 要转换的值
+ * @param {number} fallback - 转换失败时的默认值
+ * @returns {number} 转换后的数字
+ *
+ * @example
+ * ```typescript
+ * toNumber('123', 0); // 123
+ * toNumber(456, 0); // 456
+ * toNumber('abc', 0); // 0
+ * toNumber(null, 100); // 100
+ * ```
+ *
+ * @since 1.0.0
  */
 export declare const toNumber: (val: any, fallback: number) => number;
 /**
  * 检查值是否不为空
- * @param val - 要检查的值
- * @returns 是否不为空
+ *
+ * 检查值是否不为 null 和 undefined。
+ * 用于数据验证和条件判断。
+ *
+ * @param {any} val - 要检查的值
+ * @returns {boolean} 是否不为空
+ *
+ * @example
+ * ```typescript
+ * isNotEmpty('hello'); // true
+ * isNotEmpty(0); // true
+ * isNotEmpty(''); // true
+ * isNotEmpty(null); // false
+ * isNotEmpty(undefined); // false
+ * ```
+ *
+ * @since 1.0.0
  */
 export declare const isNotEmpty: (val: any) => boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ant-design/agentic-ui",
-  "version": "2.0.6",
+  "version": "2.0.10",
   "description": "面向智能体的 UI 组件库，提供多步推理可视化、工具调用展示、任务执行协同等 Agentic UI 能力",
   "repository": "git@github.com:ant-design/agentic-ui.git",
   "license": "MIT",