@chatbi-v/xcml 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1006 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1, { ReactNode } from 'react';
+export { parse, stringify } from 'yaml';
+
+/**
+ * XCML 组件规范定义 (Metadata Registry)
+ * 职责：显式标注所有组件的可选属性，支持自动化表单生成、校验及 AI 意图映射。
+ */
+/** 属性数据类型 */
+type XCMLPropertyType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'enum' | 'any';
+/** 属性功能分类 */
+type XCMLPropertyCategory = 'required' | 'optional' | 'layout' | 'interaction' | 'style';
+/**
+ * 单个属性的详细定义
+ */
+interface XCMLPropertyDefinition {
+    /** 属性名 */
+    name: string;
+    /** 数据类型 */
+    type: XCMLPropertyType;
+    /** 属性描述（用于文档或 Tooltip） */
+    description: string;
+    /** 功能分类 */
+    category?: XCMLPropertyCategory;
+    /** 是否必填 */
+    required?: boolean;
+    /** 默认值 */
+    default?: any;
+    /** 属性转换器：在渲染前对属性值进行最后一次加工（如字符串转数字） */
+    transform?: (value: any, context: any) => any;
+    /** 枚举类型的可选值列表 */
+    options?: string[];
+    /** 动态可见性判断：根据其他属性值决定当前属性是否显示 */
+    visibleIf?: (props: Record<string, any>) => boolean;
+    /** 对象的子属性定义 (仅当 type 为 'object' 时有效) */
+    properties?: XCMLPropertyDefinition[];
+    /** 数组项的属性定义 (仅当 type 为 'array' 且项为对象时有效) */
+    items?: XCMLPropertyDefinition[];
+    /** 数组项的基本类型 (仅当 type 为 'array' 且项为基本类型时有效) */
+    itemType?: XCMLPropertyType;
+}
+/**
+ * 组件完整 Schema 定义
+ */
+interface XCMLComponentSchema {
+    /** 组件标签名 (如 xcml:metric) */
+    tag: string;
+    /** 组件中文标题 */
+    title: string;
+    /** 组件功能描述 */
+    description: string;
+    /** 标签属性定义 (Attributes) */
+    props: XCMLPropertyDefinition[];
+    /** 标签体数据定义 (Body Data) */
+    body?: XCMLPropertyDefinition[];
+    /** 示例配置，用于编辑器快速生成代码 */
+    example?: {
+        /** 示例属性 */
+        props?: Record<string, any>;
+        /** 示例 Body 数据 */
+        body?: Record<string, any>;
+        /** 当 Body 为纯字符串时，默认映射到的属性名（如 'content'） */
+        contentProp?: string;
+    };
+}
+/**
+ * 通用组件属性定义
+ * 所有 XCML 组件都会自动继承这些属性，无需在每个组件中重复定义
+ */
+declare const COMMON_PROPS: XCMLPropertyDefinition[];
+declare const XCML_SCHEMAS: Record<string, XCMLComponentSchema>;
+
+/**
+ * XCML 基础组件属性定义
+ * 所有 XCML 组件都应继承此接口，以确保通用样式的统一透传
+ */
+interface XCMLBaseProps {
+    /** 唯一标识符，用于事件总线(xcmlBus)定位组件 */
+    id?: string;
+    /** 视觉主题，可选值如 'light', 'dark', 'ocean' 等 */
+    theme?: string;
+    /** 变体样式，用于区分同组件的不同视觉呈现 */
+    variant?: string;
+    /** 组件尺寸 */
+    size?: 'small' | 'middle' | 'large';
+    /** 自定义 Tailwind 类名 */
+    className?: string;
+    /** 自定义内联样式 */
+    style?: React$1.CSSProperties;
+    /** 手动指定加载状态 */
+    loading?: boolean;
+    /**
+     * 数据流状态
+     * - loading: 初始加载中
+     * - streaming: 正在接收流式数据
+     * - done: 加载完成
+     * - error: 发生错误
+     */
+    streamStatus?: 'loading' | 'streaming' | 'done' | 'error';
+    /** 错误信息对象 */
+    error?: Error | null;
+    /** 原始 XCML AST 节点引用 */
+    node?: any;
+}
+/**
+ * XCML 基础组件接口
+ * 定义了组件应实现的通用方法与元数据
+ *
+ * @example
+ * ```tsx
+ * const MyComponent: XCMLBaseComponent<Props> = (props) => { ... }
+ * MyComponent.schema = mySchema;
+ * ```
+ */
+interface XCMLBaseComponent<P = {}> extends React$1.FC<P & XCMLBaseProps> {
+    /**
+     * 组件元数据定义 (Schema)
+     * 用于自动化的属性提取、文档生成及工作台交互
+     */
+    schema: XCMLComponentSchema;
+}
+/**
+ * 通用样式提取工具
+ * 从组件 Props 中提取出 XCMLBaseProps 定义的通用样式属性，便于透传给 Wrapper
+ *
+ * @param props - 组件接收到的所有属性
+ * @returns 仅包含基础样式的属性对象
+ */
+declare function extractBaseStyles(props: Record<string, any>): Partial<XCMLBaseProps>;
+
+/**
+ * XCML 内部通用工具函数
+ */
+/**
+ * 核心 Hook：从 XCML 节点中提取并合并属性与数据
+ *
+ * 治理原则：
+ * 1. 优先级：显式标签属性 (Props) > 标签体数据 (Body Data) > Schema 默认值 (Defaults)。
+ * 2. 智能解析：自动识别 Body 中的 JSON 字符串并解析。
+ * 3. 结构适配：根据 Schema 将 Body 中的数组或原始值映射到正确的属性名上。
+ *
+ * @param node - XCML AST 节点模型
+ * @param schema - 组件的规范定义
+ * @returns 合并后的全量属性对象
+ *
+ * @template T - 组件特有的属性类型
+ */
+declare function useXCMLNode<T = Record<string, any>>(node: any, schema?: XCMLComponentSchema): T & XCMLBaseProps;
+/**
+ * 增强型数组解析工具
+ *
+ * 支持以下格式：
+ * 1. 标准 JSON 数组: `["a", "b"]`
+ * 2. 非标单引号数组: `['a', 'b']`
+ * 3. 逗号分隔字符串: `a, b, c` 或 `a，b，c`
+ *
+ * @param val - 待解析的原始值
+ * @returns 归一化后的字符串数组
+ */
+declare const parseArrayProp: (val: any) => string[];
+/**
+ * 渲染器别名生成工具
+ *
+ * 职责：
+ * 为组件创建标准 `xcml:` 前缀的映射，并根据别名表生成冗余映射。
+ * 注意：`x-` 前缀的兼容性由 Markdown 渲染引擎在运行时通过 `normalizeTagName` 自动处理。
+ *
+ * @param baseMap - 基础渲染器映射表 { tagName: Renderer }
+ * @param aliases - 别名映射表 { tagName: [alias1, alias2] }
+ * @returns 补全后的渲染器映射表
+ */
+declare function createRenderersWithAliases(baseMap: Record<string, (node: any, key: string | number) => any>, aliases?: Record<string, string[]>): Record<string, (node: any, key: string | number) => any>;
+/**
+ * XCML 独立渲染函数
+ * 职责：接收 XCML 节点数据，返回对应的 React 组件
+ */
+declare const renderXCML: (node: any, key?: string | number) => any;
+/**
+ * 结构化数据校验工具
+ *
+ * 职责：
+ * 根据 Schema 定义，对 XCML 节点的 Props 和 Body 进行合规性检查。
+ * 用于编辑器实时报错提示或数据入库前的安全检查。
+ *
+ * @param node - 待校验的 XCML 节点
+ * @param schema - 该组件对应的规范定义
+ * @returns 校验结果对象，包含是否合法及详细错误列表
+ */
+declare function validateXCMLNode(node: any, schema: XCMLComponentSchema): {
+    valid: boolean;
+    errors: string[];
+};
+
+/**
+ * XCML 组件通用业务逻辑 Hook
+ *
+ * 职责：
+ * 1. 自动调用 `useXCMLNode` 进行属性 (Props) 与数据 (Body) 的智能合并。
+ * 2. 统一计算 `loading` 状态，支持多种标记方式（外部注入、节点状态、data-属性）。
+ * 3. 统一提取基础样式属性，确保所有组件在不同主题下的视觉一致性。
+ *
+ * @param props - 组件接收到的原始属性
+ * @param schema - 组件的 Schema 定义，用于指导属性合并与默认值注入
+ * @returns 包含合并后的数据 `merged`、基础样式 `baseProps` 及加载状态 `isLoading`
+ *
+ * @example
+ * ```tsx
+ * const { merged, baseProps, isLoading } = useXCMLComponent(props, cardSchema);
+ * ```
+ */
+declare function useXCMLComponent<P extends object>(props: P & XCMLBaseProps, schema?: XCMLComponentSchema): {
+    merged: P & XCMLBaseProps;
+    baseProps: XCMLBaseProps;
+    isLoading: boolean | undefined;
+    streamStatus: any;
+};
+
+/**
+ * XCML 架构说明 (Architecture Guide)
+ *
+ * 1. Schema 定义 (./schemas/):
+ *    定义组件的 tag、props、example 等元数据。
+ *    每个组件拥有独立的 schema 文件，便于维护 and 扩展。
+ *    这是组件的“身份证”，用于工作台展示 and 数据校验。
+ *
+ * 2. 核心逻辑 (./index.ts):
+ *    处理 XCML 标签的预处理、解析、数据转换及事件通信 (xcmlBus)。
+ *
+ * 3. 渲染层 (../renderers/):
+ *    - basic: 基础组件 (Metric, Table, List)
+ *    - antv: 图表组件 (基于 @ant-design/plots)
+ *    - cards: 复合业务组件 (InsightCard, ThoughtChain)
+ *
+ * 如何扩展新组件：
+ * 1. 在 core/schemas/ 目录下创建新的 schema 文件并导出。
+ * 2. 在 core/schema.ts 的 XCML_SCHEMAS 注册表中引入并注册该 schema。
+ * 3. 在对应的 renderers 目录下创建 React 组件实现。
+ * 4. 在 renderers 的工厂方法中导出该组件的渲染函数。
+ */
+/**
+ * XCML 核心类型与事件总线
+ */
+/**
+ * 标签归一化：将任意格式的标签名统一转换为不带前缀的纯名称
+ * @param tag - 原始标签名 (如 xcml:metric, x-metric)
+ * @returns 归一化后的名称 (如 metric)
+ */
+declare function normalizeTagName(tag: string): string;
+/**
+ * 转换为 x- 前缀格式（用于 HTML 渲染）
+ */
+declare function toXTag(tag: string): string;
+/**
+ * 转换为 xcml: 前缀格式（用于 Schema 匹配）
+ */
+declare function toXCMLTag(tag: string): string;
+type XCMLRenderer = (node: any, key: string | number) => any;
+interface XCMLContext {
+    theme: string;
+    whitelist?: {
+        link?: string[];
+        image?: string[];
+    };
+}
+type XCMLPlugin = (ast: any, ctx: XCMLContext) => any;
+/**
+ * XCML 事件总线
+ * 职责：实现渲染层组件与宿主页面之间的双向通信。
+ *
+ * 支持的内置事件：
+ * - refresh: 请求组件重新加载数据
+ * - update: 外部向组件注入新数据
+ * - resize: 通知组件重绘图表尺寸
+ * - export: 触发组件导出操作 (图片/CSV)
+ */
+declare class XCMLEventBus {
+    /** 监听器映射：事件名到监听函数数组 */
+    private listeners;
+    /** 注册事件监听器 */
+    on(event: string, handler: (payload?: any) => void): void;
+    /** 触发事件 */
+    emit(event: string, payload?: any): void;
+    /** 刷新方法：按 id 或全部刷新 */
+    refresh(id?: string): void;
+    /** 更新方法：按 id 注入数据 */
+    update(id: string, payload: any): void;
+    /** 重绘尺寸 */
+    resize(id?: string): void;
+    /** 导出方法：导出指定类型 */
+    export(id: string, type: string): void;
+}
+/**
+ * 事件总线单例：供渲染器与页面交互使用
+ */
+declare const xcmlBus: XCMLEventBus;
+/**
+ * 智能数据解析引擎
+ *
+ * 职责：
+ * 根据 `data-format` 属性将文本块解析为 JavaScript 对象/数组。
+ *
+ * 特性：
+ * 1. 支持 JSON / JSONC (带注释的 JSON)。
+ * 2. 支持 YAML (由于 YAML 格式更宽容，常作为 JSON 解析失败后的 Fallback)。
+ * 3. 支持 CSV / TSV 自动转换（含简单的类型识别）。
+ * 4. 支持 NDJSON (每行一个 JSON 对象)。
+ *
+ * @param text - 待解析的文本内容
+ * @param format - 指定的数据格式
+ * @returns 解析后的对象或数组
+ */
+declare function parseInlineData(text: string, format?: 'json' | 'jsonc' | 'yaml' | 'csv' | 'tsv' | 'ndjson'): any;
+/**
+ * 安全校验占位：后续接入 Ajv Schema 校验与白名单过滤
+ */
+declare function validateDataSchema(_component: string, data: any): boolean;
+
+/**
+ * 规范化数据对象：根据 Schema 定义，将属性中可能的 JSON 字符串解析为对象/数组
+ * 解决双重序列化问题 (Double Serialization)
+ */
+declare function normalizeNodeData(tag: string, data: any): any;
+/**
+ * 核心逻辑：属性与数据智能合并
+ *
+ * 职责：
+ * 将解析出的标签属性 (attrs) 与标签体数据 (bodyData) 根据 Schema 定义进行智能分流。
+ *
+ * 核心策略：
+ * 1. 结构化匹配：如果 bodyData 是对象，将其字段分流到 Props 或 Body 属性中。
+ * 2. 类型适配：如果 bodyData 是数组，根据 Schema 查找对应的数组字段（默认为 `data`）。
+ * 3. preferBody 模式：为了生成更简洁的 XCML 标签，支持将所有业务属性强制压缩到 Body 的 JSON 中。
+ *
+ * @param tagName - 标签名
+ * @param attrs - 标签上的属性集合
+ * @param bodyData - 标签体内的解析后数据
+ * @param options - 合并配置
+ * @returns 分流后的 { props, body } 对象
+ */
+declare function mergePropsAndBody(tagName: string, attrs: Record<string, any>, bodyData: any, options?: {
+    preferBody?: boolean;
+}): {
+    props: any;
+    body: any;
+};
+/**
+ * 序列化引擎：将内存中的节点模型转换为 XCML 标签字符串
+ *
+ * 治理要求：
+ * 遵循“全量 Body 化”协定，除了技术性属性（id, className）外，
+ * 所有业务属性一律序列化为 Body 中的 JSON，以提高 Markdown 的可读性和容错率。
+ *
+ * @param node - 待转换的节点模型
+ * @returns 格式化后的 XCML 字符串
+ */
+declare function stringifyToXCML(node: {
+    tag?: string;
+    type?: string;
+    props?: Record<string, any>;
+    body?: any;
+}): string;
+/**
+ * 简单的 XCML 解析器，用于工作台同步
+ * 仅处理单个根节点
+ */
+declare function parseXCML(xcml: string): {
+    tag: string;
+    props: Record<string, any>;
+    body: any;
+} | null;
+
+/**
+ * 统一节点模型转换器
+ *
+ * 职责：
+ * 接收原始的 DOM 元素信息（标签名、属性、文本内容），将其转换为 XCML AST 节点。
+ * 这是连接 Markdown 解析层与 XCML 渲染层的关键桥梁。
+ *
+ * @param name - 标签名
+ * @param attrs - DOM 属性集合
+ * @param bodyText - 标签体内的原始文本
+ * @returns 标准化的 XCML AST 节点对象
+ */
+declare function toXCMLNodeFromElement(name: string, attrs: Record<string, any>, bodyText: string): {
+    type: string;
+    props: any;
+    body: any;
+    __source: string;
+};
+/**
+ * 预处理 XCML 内容：
+ * 0. 流式优化与归一化
+ * 1. 忽略代码块中的标签
+ * 2. 转义未闭合的标签
+ * 3. 修复属性格式
+ * 4. 剔除未识别的 x- 标签 (如果提供了 knownTags)
+ */
+declare function preprocessXCML(md: string, knownTags?: string[]): string;
+
+interface XCMLProps {
+    content?: string;
+    stream?: AsyncIterable<string>;
+    renderers?: Record<string, (node: any, key: string | number) => React$1.ReactNode>;
+    className?: string;
+    style?: React$1.CSSProperties;
+    openLinksInNewTab?: boolean;
+    dompurifyConfig?: Record<string, any>;
+    /**
+     * 是否启用悬停查看组件源码功能
+     * @default false
+     */
+    enableHoverSource?: boolean;
+    /**
+     * 主题配置，用于 Mermaid 等图表
+     */
+    theme?: string;
+}
+/**
+ * XCML 核心渲染组件 (XCMLMarkdown)
+ *
+ * 职责：
+ * 1. 内容预处理：利用 `preprocessXCML` 处理不规范标签，并支持通过 `data-xcml-raw` 保护原始 Markdown 内容。
+ * 2. 动态组件映射：将 `x-*` 标签自动关联到 `renderers` 中定义的业务渲染器。
+ * 3. 增强 Markdown 功能：集成 Mermaid 图表、自动生成目录 (TOC) 锚点、处理 DOM 嵌套合法性（如 P 标签内嵌 Div）。
+ * 4. 交互体验：支持流式输出中间态显示、源码悬浮查看、链接新窗口打开等。
+ *
+ * @example
+ * ```tsx
+ * <XCMLMarkdown
+ *   content="<x-card>Hello</x-card>"
+ *   renderers={{ 'x-card': CardRenderer }}
+ * />
+ * ```
+ */
+declare function XCMLMarkdown(props: XCMLProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * AntV 渲染器全局配置选项
+ */
+interface AntVRendererOptions {
+    /** 主题名称，如 'light', 'dark' */
+    theme?: string;
+}
+/**
+ * AntV 图表组件属性定义
+ *
+ * @description 所有的属性（除了 type 和 data）都将直接透传给 @ant-design/plots 的对应组件。
+ */
+interface ChartProps {
+    /**
+     * 图表类型，对应 @ant-design/plots 的组件名（如 'line', 'pie', 'column' 等）。
+     * 系统会自动进行 PascalCase 转换（如 'word-cloud' -> 'WordCloud'）。
+     */
+    type: string;
+    /**
+     * 图表数据。
+     * - 如果是 Array: 映射为 AntV 的 data 属性。
+     * - 如果是 Object: 视为完整的 AntV 配置对象，将与其它属性合并。
+     * - 如果是 Number: 针对进度类图表，自动映射为 percent 属性。
+     */
+    data?: any;
+    /**
+     * 其他 AntV 配置项，如 xField, yField, seriesField, color, legend 等。
+     */
+    [key: string]: any;
+}
+/**
+ * 动态加载的图表组件类型定义
+ */
+type ChartComponent = React.ComponentType<any>;
+
+/**
+ * 图表策略接口
+ */
+interface ChartStrategy {
+    /** 策略对应的图表类型 (如 'line', 'column') */
+    type: string;
+    /** 该图表类型的独立 Schema 定义 */
+    schema: XCMLComponentSchema;
+    /** 获取 AntV 组件 */
+    getComponent: () => React$1.ComponentType<Record<string, any>>;
+    /** 属性转换/规范化 */
+    transformProps?: (props: Record<string, any>) => Record<string, any>;
+}
+/**
+ * 坐标轴配置
+ */
+interface ChartAxisConfig {
+    title?: string | {
+        text?: string;
+        style?: Record<string, string | number>;
+    };
+    label?: {
+        autoHide?: boolean;
+        autoRotate?: boolean;
+        style?: Record<string, string | number>;
+    };
+    grid?: {
+        line?: {
+            style?: Record<string, string | number>;
+        };
+    };
+    line?: {
+        style?: Record<string, string | number>;
+    };
+    tickLine?: {
+        style?: Record<string, string | number>;
+    };
+}
+/**
+ * 标签配置
+ */
+interface ChartLabelConfig {
+    text?: string;
+    position?: 'top' | 'bottom' | 'left' | 'right' | 'inside' | 'outside' | 'center';
+    offset?: number;
+    content?: string | ((data: Record<string, any>) => string);
+    formatter?: (val: string | number) => string;
+    style?: Record<string, string | number>;
+    [key: string]: string | number | boolean | undefined | Record<string, any> | ((...args: unknown[]) => unknown);
+}
+/**
+ * 图例配置
+ */
+interface ChartLegendConfig {
+    position?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    layout?: 'horizontal' | 'vertical';
+    title?: {
+        text?: string;
+        style?: Record<string, string | number>;
+    };
+    marker?: {
+        symbol?: string;
+        style?: Record<string, string | number>;
+    };
+}
+/**
+ * 基础图表属性定义
+ */
+interface BaseChartProps {
+    /** 图表类型 */
+    type: string;
+    /** 图表数据 */
+    data: Record<string, any>[];
+    /** 宽度 */
+    width?: number;
+    /** 高度 */
+    height?: number;
+    /** 是否自适应 */
+    autoFit?: boolean;
+    /** 主题 */
+    theme?: string;
+    /** 标题配置 */
+    title?: string | {
+        text?: string;
+        style?: Record<string, string | number>;
+    };
+    /** 标签配置 (支持单标签对象或多标签数组) */
+    label?: boolean | ChartLabelConfig | ChartLabelConfig[];
+    /** 标签配置别名 (支持多标签数组) */
+    labels?: ChartLabelConfig[];
+    /** 坐标轴配置 */
+    axis?: boolean | {
+        x?: ChartAxisConfig;
+        y?: ChartAxisConfig;
+    };
+    /** 图例配置 */
+    legend?: boolean | ChartLegendConfig;
+    /** 交互配置 */
+    interaction?: Record<string, any>;
+    /** 动画配置 */
+    animation?: Record<string, any>;
+    /** 原生 AntV 配置透传 (最高优先级) */
+    __native__?: Record<string, any>;
+    /** 空态占位 */
+    emptyPlaceholder?: ReactNode;
+    /** 错误态占位 */
+    errorPlaceholder?: (err: Error, reset: () => void) => ReactNode;
+    /** 其他透传属性 */
+    [key: string]: string | number | boolean | undefined | Record<string, any> | string[] | number[] | Record<string, any>[] | ReactNode | ((...args: unknown[]) => unknown);
+}
+
+/**
+ * 折线图 XCML Schema 定义
+ */
+declare const lineChartSchema: XCMLComponentSchema;
+
+/**
+ * 折线图属性定义
+ */
+interface LineChartProps extends BaseChartProps {
+    type: 'line';
+    xField: string;
+    yField: string;
+    colorField?: string;
+    seriesField?: string;
+}
+/**
+ * 折线图策略实现
+ */
+declare const lineStrategy: ChartStrategy;
+
+/**
+ * 柱状图 XCML Schema 定义
+ */
+declare const columnChartSchema: XCMLComponentSchema;
+
+/**
+ * 柱状图属性定义
+ */
+interface ColumnChartProps extends BaseChartProps {
+    type: 'column';
+    xField: string;
+    yField: string;
+    colorField?: string;
+    seriesField?: string;
+    group?: boolean | Record<string, string | number | boolean>;
+    isRange?: boolean;
+}
+/**
+ * 柱状图策略实现
+ */
+declare const columnStrategy: ChartStrategy;
+
+/**
+ * 饼图 XCML Schema 定义
+ */
+declare const pieChartSchema: XCMLComponentSchema;
+
+/**
+ * 饼图属性定义
+ */
+interface PieChartProps extends BaseChartProps {
+    type: 'pie';
+    angleField: string;
+    colorField: string;
+}
+/**
+ * 饼图策略实现
+ */
+declare const pieStrategy: ChartStrategy;
+
+/**
+ * 双轴图 XCML Schema 定义
+ */
+declare const dualAxesChartSchema: XCMLComponentSchema;
+
+/**
+ * 双轴图子图层配置
+ */
+interface DualAxesChildConfig {
+    type: 'interval' | 'line' | 'area' | 'point';
+    yField: string;
+    colorField?: string;
+    seriesField?: string;
+    shapeField?: string;
+    group?: boolean;
+    style?: Record<string, any>;
+    interaction?: Record<string, any>;
+    data?: Record<string, any>[];
+    axis?: Record<string, any>;
+    label?: boolean | ChartLabelConfig;
+    [key: string]: string | number | boolean | undefined | Record<string, any> | string[] | number[] | Record<string, any>[] | ((...args: unknown[]) => unknown);
+}
+/**
+ * 双轴图属性定义
+ */
+interface DualAxesChartProps extends BaseChartProps {
+    type: 'dual-axes';
+    xField: string;
+    children: DualAxesChildConfig[];
+}
+/**
+ * 双轴图策略实现
+ */
+declare const dualAxesStrategy: ChartStrategy;
+
+/**
+ * 漏斗图 XCML Schema 定义
+ */
+declare const funnelChartSchema: XCMLComponentSchema;
+
+/**
+ * 漏斗图属性定义
+ */
+interface FunnelChartProps extends BaseChartProps {
+    type: 'funnel';
+    xField: string;
+    yField: string;
+}
+/**
+ * 漏斗图策略实现
+ */
+declare const funnelStrategy: ChartStrategy;
+
+declare const strategies: Record<string, ChartStrategy>;
+/**
+ * 根据类型获取图表策略
+ */
+declare function getChartStrategy(type: string): ChartStrategy | null;
+
+/**
+ * AntV 通用图表 XCML Schema 定义
+ * 职责：作为图表组件的通用容器入口，聚合各子图表的属性定义，支持在工作台中根据 type 动态切换。
+ */
+declare const chartSchema: XCMLComponentSchema;
+
+/**
+ * 深度合并工具函数
+ */
+declare function deepMerge<T extends Record<string, any>>(target: T, source: Record<string, any>): T;
+/**
+ * Schema 驱动的属性清洗器
+ * 根据 Schema 定义的规则 (visibleIf, default, transform) 处理属性
+ *
+ * @param props 原始属性
+ * @param schema 组件 Schema
+ * @returns 清洗后的属性
+ */
+declare function cleanPropsBySchema(props: Record<string, any>, schema?: XCMLComponentSchema): Record<string, any>;
+/**
+ * 构建最终图表配置
+ */
+declare function buildConfig(props: BaseChartProps): Record<string, any>;
+/**
+ * 空态占位组件
+ */
+declare const DefaultEmptyPlaceholder: () => react_jsx_runtime.JSX.Element;
+/**
+ * 错误态占位组件
+ */
+declare const DefaultErrorPlaceholder: ({ error, reset }: {
+    error: Error;
+    reset: () => void;
+}) => react_jsx_runtime.JSX.Element;
+
+/**
+ * AntV 图表加载器 (基于 withXCMLCard 重构)
+ */
+declare const AntVChartLoader: React$1.ForwardRefExoticComponent<Omit<any, "ref"> & React$1.RefAttributes<any>>;
+
+/**
+ * XCML 图表组件 (对外导出，供编排使用)
+ */
+declare const XCMLChart: React$1.FC<BaseChartProps & {
+    node?: any;
+}>;
+
+declare const themeLight: {
+    defaultColor: string;
+    colors10: string[];
+    styleSheet: {
+        backgroundColor: string;
+    };
+    components: {
+        axis: {
+            common: {
+                label: {
+                    style: {
+                        fillOpacity: number;
+                        fontSize: number;
+                    };
+                };
+                title: {
+                    style: {
+                        fontSize: number;
+                        fillOpacity: number;
+                    };
+                };
+                grid: {
+                    line: {
+                        style: {
+                            stroke: string;
+                            lineWidth: number;
+                            lineDash: number[];
+                            strokeOpacity: number;
+                        };
+                    };
+                };
+            };
+        };
+        tooltip: {
+            style: {
+                backgroundColor: string;
+                boxShadow: string;
+                color: string;
+                borderRadius: string;
+                padding: string;
+                border: string;
+                backdropFilter: string;
+            };
+        };
+        legend: {
+            common: {
+                itemStates: {
+                    active: {
+                        labelStyle: {
+                            fontWeight: number;
+                            fill: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+declare const themeDark: {
+    defaultColor: string;
+    colors10: string[];
+    styleSheet: {
+        backgroundColor: string;
+    };
+    components: {
+        axis: {
+            common: {
+                label: {
+                    style: {
+                        fill: string;
+                        fontSize: number;
+                    };
+                };
+                title: {
+                    style: {
+                        fill: string;
+                        fontSize: number;
+                    };
+                };
+                grid: {
+                    line: {
+                        style: {
+                            stroke: string;
+                            lineWidth: number;
+                            lineDash: number[];
+                        };
+                    };
+                };
+            };
+        };
+        tooltip: {
+            style: {
+                backgroundColor: string;
+                boxShadow: string;
+                color: string;
+                borderRadius: string;
+                padding: string;
+                border: string;
+                backdropFilter: string;
+            };
+        };
+        legend: {
+            common: {
+                labelStyle: {
+                    fill: string;
+                };
+            };
+        };
+    };
+};
+declare const themeMap: Record<string, any>;
+declare function getTheme(themeName?: string): any;
+
+/**
+ * 图表渲染器：将 xcml:chart 数据映射到 AntV Plots
+ */
+declare function createAntVRenderers(options?: AntVRendererOptions): Record<string, (node: any, key: string | number) => any>;
+
+/**
+ * XCML 通用卡片包装器属性定义
+ */
+interface XCMLCardWrapperProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** 卡片标题 */
+    title?: React$1.ReactNode;
+    /** 卡片左上角图标 */
+    icon?: React$1.ReactNode;
+    /** 卡片主体内容 */
+    children?: React$1.ReactNode;
+    /** 数据来源（透传属性） */
+    source?: string;
+    /** 摘要内容（透传属性） */
+    summary?: React$1.ReactNode;
+    /** 容器变体: 'card' (默认带边框阴影) | 'plain' (纯文字，无边框) */
+    variant?: string;
+    /** 视觉主题 */
+    theme?: string;
+    /** 是否支持悬停时的浮起阴影效果 */
+    hoverable?: boolean;
+    /** 原始 XCML 节点数据 */
+    node?: Record<string, any>;
+    /** 关联的 DOM 节点引用 */
+    domNode?: HTMLElement | null;
+    /** 数据流式加载状态 */
+    streamStatus?: string;
+}
+/**
+ * XCML 通用卡片包装器 (Themed Container)
+ *
+ * 职责：
+ * 1. 提供全局一致的容器样式：圆角、边框、阴影、外边距。
+ * 2. 渲染统一的标题栏布局，支持图标与悬停装饰条。
+ * 3. 拦截并清理内部业务属性，防止非法的 XCML 属性透传到原生 DOM 节点引起 React 警告。
+ *
+ * 设计风格：
+ * 参考现代 AI 助手 UI 规范，强调微阴影（shadow-card）与圆润度（rounded-xl）。
+ */
+declare const XCMLCardWrapper: React$1.FC<XCMLCardWrapperProps>;
+
+/**
+ * withXCMLCard 高阶组件配置项
+ */
+interface WithXCMLCardOptions<P> {
+    /**
+     * 组件 Schema 定义
+     * 用于 `useXCMLComponent` 自动进行属性映射与默认值注入
+     */
+    schema?: XCMLComponentSchema;
+    /**
+     * 自定义获取标题逻辑
+     * @default merged.label || merged.title
+     */
+    getTitle?: (mergedProps: P) => string | undefined;
+    /**
+     * 自定义获取图标逻辑
+     * @default merged.icon
+     */
+    getIcon?: (mergedProps: P) => React$1.ReactNode;
+    /**
+     * 自定义获取变体逻辑 (card | plain)
+     * @default merged.variant || 'card'
+     */
+    getVariant?: (mergedProps: P) => string;
+    /**
+     * 自定义加载态渲染内容
+     * 如果提供此函数，则忽略骨架屏配置
+     */
+    renderLoading?: (mergedProps: P) => React$1.ReactNode;
+    /**
+     * 是否支持骨架屏渲染
+     * @default true
+     */
+    skeleton?: boolean | {
+        rows?: number;
+    };
+}
+/**
+ * XCML 渲染器增强高阶组件 (HOC)
+ *
+ * 职责：
+ * 1. 状态集成：利用 `useXCMLComponent` 统一管理 Props 合并、数据流状态及加载判断。
+ * 2. 视觉规范：自动包裹 `XCMLCardWrapper`，确保所有组件拥有统一的容器样式、标题栏和主题表现。
+ * 3. 容错治理：处理标题防御（如 LLM 生成了数组或对象形式的标题）及旧版属性兼容。
+ * 4. 体验优化：内置 Ant Design 骨架屏加载态。
+ *
+ * @param Component - 业务渲染器组件
+ * @param options - 配置参数
+ *
+ * @example
+ * ```tsx
+ * export default withXCMLCard(MyTable, { schema: tableSchema });
+ * ```
+ */
+declare function withXCMLCard<P extends object>(Component: React$1.ComponentType<P>, options?: WithXCMLCardOptions<P & XCMLBaseProps>): React$1.ForwardRefExoticComponent<Omit<any, "ref"> & React$1.RefAttributes<any>>;
+
+/**
+ * 基础渲染器集合：metric/table/card/list/toc
+ * 说明：UI 基于 @ant-design/x，若组件名存在差异，将以简化实现占位
+ */
+interface BasicRenderersOptions {
+    theme?: string;
+}
+declare function createBasicRenderers(options?: BasicRenderersOptions): Record<string, (node: any, key: string | number) => any>;
+
+interface ExtendedRenderersOptions {
+    theme?: string;
+}
+declare function createExtendedRenderers(options?: ExtendedRenderersOptions): Record<string, (node: any, key: string | number) => any>;
+
+type Theme = "dark" | "light" | "system" | "ocean" | "sunset" | "lavender" | "rose" | "amber" | "midnight" | "forest" | "slate" | "crimson" | "cyan";
+type ThemeProviderProps = {
+    children: React.ReactNode;
+    defaultTheme?: Theme;
+    /**
+     * Explicitly set the theme (Controlled mode).
+     */
+    theme?: Theme;
+    /**
+     * Primary color for the theme (e.g., #6366f1)
+     */
+    primaryColor?: string;
+    storageKey?: string;
+    /**
+     * Whether to apply the theme only to the container instead of the document root
+     * @default true
+     */
+    scoped?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+};
+type ThemeProviderState = {
+    theme: Theme;
+    setTheme: (theme: Theme) => void;
+};
+declare function ThemeProvider({ children, defaultTheme, theme: controlledTheme, primaryColor, // Indigo 500 default
+storageKey, scoped, className, style, ...props }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+declare const useTheme: () => ThemeProviderState;
+
+export { AntVChartLoader, type AntVRendererOptions, type BaseChartProps, type BasicRenderersOptions, COMMON_PROPS, type ChartAxisConfig, type ChartComponent, type ChartLabelConfig, type ChartLegendConfig, type ChartProps, type ChartStrategy, type ColumnChartProps, DefaultEmptyPlaceholder, DefaultErrorPlaceholder, type DualAxesChartProps, type DualAxesChildConfig, type ExtendedRenderersOptions, type FunnelChartProps, type LineChartProps, type PieChartProps, type Theme, ThemeProvider, type XCMLBaseComponent, type XCMLBaseProps, XCMLCardWrapper, XCMLChart, type XCMLComponentSchema, type XCMLContext, XCMLEventBus, XCMLMarkdown, type XCMLPlugin, type XCMLPropertyCategory, type XCMLPropertyDefinition, type XCMLPropertyType, type XCMLProps, type XCMLRenderer, XCML_SCHEMAS, buildConfig, chartSchema, cleanPropsBySchema, columnChartSchema, columnStrategy, createAntVRenderers, createBasicRenderers, createExtendedRenderers, createRenderersWithAliases, deepMerge, dualAxesChartSchema, dualAxesStrategy, extractBaseStyles, funnelChartSchema, funnelStrategy, getChartStrategy, getTheme, lineChartSchema, lineStrategy, mergePropsAndBody, normalizeNodeData, normalizeTagName, parseArrayProp, parseInlineData, parseXCML, pieChartSchema, pieStrategy, preprocessXCML, renderXCML, strategies, stringifyToXCML, themeDark, themeLight, themeMap, toXCMLNodeFromElement, toXCMLTag, toXTag, useTheme, useXCMLComponent, useXCMLNode, validateDataSchema, validateXCMLNode, withXCMLCard, xcmlBus };