@ant-design/agentic-ui 2.0.5 → 2.0.8

package/dist/MarkdownEditor/editor/Editor.js

@@ -598,7 +598,7 @@ var SlateMarkdownEditor = (props) => {
   };
   const elementRenderElement = useCallback(
     (eleProps) => {
-      var _a2, _b2, _c2, _d2;
+      var _a2, _b2, _c2, _d2, _e;
       const defaultDom = /* @__PURE__ */ React.createElement(
         ErrorBoundary,
         {
@@ -638,7 +638,8 @@ var SlateMarkdownEditor = (props) => {
           LazyElement,
           {
             placeholderHeight: (_c2 = props.lazy) == null ? void 0 : _c2.placeholderHeight,
-            rootMargin: (_d2 = props.lazy) == null ? void 0 : _d2.rootMargin
+            rootMargin: (_d2 = props.lazy) == null ? void 0 : _d2.rootMargin,
+            renderPlaceholder: (_e = props.lazy) == null ? void 0 : _e.renderPlaceholder
           },
           renderedDom
         );

package/dist/MarkdownEditor/editor/components/LazyElement/index.d.ts

@@ -11,6 +11,24 @@ export interface LazyElementProps {
     rootMargin?: string;
     /** 占位符样式 */
     placeholderStyle?: React.CSSProperties;
+    /** 自定义占位符渲染函数 */
+    renderPlaceholder?: (props: {
+        /** 占位符高度 */
+        height: number;
+        /** 占位符样式 */
+        style: React.CSSProperties;
+        /** 元素是否即将进入视口 */
+        isIntersecting: boolean;
+        /** 元素在文档中的位置信息 */
+        elementInfo?: {
+            /** 元素类型 */
+            type: string;
+            /** 元素在文档中的索引 */
+            index: number;
+            /** 元素总数量 */
+            total: number;
+        };
+    }) => React.ReactNode;
 }
 /**
  * LazyElement 组件 - 懒加载元素包裹器
@@ -26,12 +44,26 @@ export interface LazyElementProps {
  * @param {number} [props.placeholderHeight=100] - 占位符高度
  * @param {string} [props.rootMargin='200px'] - 提前加载的距离
  * @param {React.CSSProperties} [props.placeholderStyle] - 自定义占位符样式
+ * @param {Function} [props.renderPlaceholder] - 自定义占位符渲染函数
  *
  * @example
  * ```tsx
+ * // 基本使用
  * <LazyElement placeholderHeight={150} rootMargin="300px">
  *   <div>这是需要懒加载的内容</div>
  * </LazyElement>
+ *
+ * // 自定义占位符渲染
+ * <LazyElement
+ *   placeholderHeight={150}
+ *   renderPlaceholder={({ height, style, isIntersecting }) => (
+ *     <div style={style}>
+ *       <div>加载中... {isIntersecting ? '(即将显示)' : ''}</div>
+ *     </div>
+ *   )}
+ * >
+ *   <div>这是需要懒加载的内容</div>
+ * </LazyElement>
  * ```
  *
  * @returns {React.ReactElement} 渲染的懒加载元素

package/dist/MarkdownEditor/editor/components/LazyElement/index.js

@@ -21,11 +21,13 @@ var LazyElement = ({
   children,
   placeholderHeight = 25,
   rootMargin = "200px",
-  placeholderStyle
+  placeholderStyle,
+  renderPlaceholder
 }) => {
   const containerRef = useRef(null);
   const [isVisible, setIsVisible] = useState(false);
   const [hasRendered, setHasRendered] = useState(false);
+  const [isIntersecting, setIsIntersecting] = useState(false);
   useEffect(() => {
     const container = containerRef.current;
     if (!container)
@@ -33,6 +35,7 @@ var LazyElement = ({
     const observer = new IntersectionObserver(
       (entries) => {
         entries.forEach((entry) => {
+          setIsIntersecting(entry.isIntersecting);
           if (entry.isIntersecting) {
             setIsVisible(true);
             setHasRendered(true);
@@ -53,13 +56,21 @@ var LazyElement = ({
   if (hasRendered || isVisible) {
     return /* @__PURE__ */ React.createElement("div", { ref: containerRef }, children);
   }
+  const computedPlaceholderStyle = __spreadValues({
+    minHeight: placeholderHeight
+  }, placeholderStyle);
+  if (renderPlaceholder) {
+    return /* @__PURE__ */ React.createElement("div", { ref: containerRef, "aria-hidden": "true" }, renderPlaceholder({
+      height: placeholderHeight,
+      style: computedPlaceholderStyle,
+      isIntersecting
+    }));
+  }
   return /* @__PURE__ */ React.createElement(
     "div",
     {
       ref: containerRef,
-      style: __spreadValues({
-        minHeight: placeholderHeight
-      }, placeholderStyle),
+      style: computedPlaceholderStyle,
       "aria-hidden": "true"
     }
   );

package/dist/MarkdownEditor/types.d.ts

@@ -147,11 +147,24 @@ export type MarkdownEditorProps = {
      *
      * @example
      * ```tsx
+     * // 基本懒加载配置
      * lazy={{
      *   enable: true,
      *   placeholderHeight: 100,
      *   rootMargin: '200px'
      * }}
+     *
+     * // 自定义占位符渲染
+     * lazy={{
+     *   enable: true,
+     *   placeholderHeight: 120,
+     *   rootMargin: '300px',
+     *   renderPlaceholder: ({ height, style, isIntersecting }) => (
+     *     <div style={style}>
+     *       <div>加载中... {isIntersecting ? '(即将显示)' : ''}</div>
+     *     </div>
+     *   )
+     * }}
      * ```
      */
     lazy?: {
@@ -168,6 +181,27 @@ export type MarkdownEditorProps = {
          * 支持所有 IntersectionObserver rootMargin 的值
          */
         rootMargin?: string;
+        /**
+         * 自定义占位符渲染函数
+         * 允许开发者自定义懒加载时的占位符显示内容
+         */
+        renderPlaceholder?: (props: {
+            /** 占位符高度 */
+            height: number;
+            /** 占位符样式 */
+            style: React.CSSProperties;
+            /** 元素是否即将进入视口 */
+            isIntersecting: boolean;
+            /** 元素在文档中的位置信息 */
+            elementInfo?: {
+                /** 元素类型 */
+                type: string;
+                /** 元素在文档中的索引 */
+                index: number;
+                /** 元素总数量 */
+                total: number;
+            };
+        }) => React.ReactNode;
     };
     /**
      * 样式

package/dist/MarkdownInputField/MarkdownInputField.js

@@ -285,7 +285,11 @@ var MarkdownInputField = (_a) => {
           onMouseEnter: () => setHover(true),
           onMouseLeave: () => setHover(false),
           onKeyDown: (e) => {
+            var _a3;
             const { triggerSendKey = "Enter" } = props;
+            if ((_a3 = markdownEditorRef == null ? void 0 : markdownEditorRef.current) == null ? void 0 : _a3.store.inputComposition) {
+              return;
+            }
             if (triggerSendKey === "Enter" && e.key === "Enter" && !(e.ctrlKey || e.metaKey)) {
               e.stopPropagation();
               e.preventDefault();

package/dist/MarkdownInputField/SendActions/index.js

@@ -72,7 +72,7 @@ var SendActions = ({
             var _a;
             (_a = attachment == null ? void 0 : attachment.onFileMapChange) == null ? void 0 : _a.call(attachment, fileMap2);
           },
-          disabled: !fileUploadDone
+          disabled: !fileUploadDone || (attachment == null ? void 0 : attachment.disabled)
         })
       ) : null,
       voiceRecognizer ? /* @__PURE__ */ React.createElement(

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.5",
+  "version": "2.0.8",
   "description": "面向智能体的 UI 组件库，提供多步推理可视化、工具调用展示、任务执行协同等 Agentic UI 能力",
   "repository": "git@github.com:ant-design/agentic-ui.git",
   "license": "MIT",