@icen.ai/ui 0.8.1 → 0.10.0

package/dist/react.d.mts

@@ -0,0 +1,91 @@
+import { RefObject, CSSProperties, ReactElement, FC } from 'react';
+import { IcenEventMap } from './behaviors/events.js';
+import { ChartSpec, ChartHandle } from './behaviors/charts.js';
+import { TableOptions, TableHandle } from './behaviors/datatable.js';
+export { TableColumn } from './behaviors/datatable.js';
+import { AiMessageModel } from './behaviors/ai-chat.js';
+export { AiMessageHandle } from './behaviors/ai-chat.js';
+import { AiToolCallHandle } from './behaviors/ai-tool.js';
+import { AiProviderOption, AiComposerCurrentModel, AiComposerBindOpts } from './behaviors/ai-composer.js';
+import { AiClient } from './behaviors/ai-provider.js';
+import { AiToolCallModel } from './behaviors/ai-core.js';
+export { AiContent, AiContentPart, AiStatus, AiUsage } from './behaviors/ai-core.js';
+import './behaviors/mentions.js';
+import './behaviors/suggestions.js';
+import './behaviors/kb-core.js';
+import './behaviors/icons.js';
+import './behaviors/popover.js';
+import './behaviors/ai-panel.js';
+import './behaviors/context-menu.js';
+
+/**
+ * 生命周期接线原语：mount 时调 init，返回的清理函数在 unmount / deps 变化时执行。
+ * init 本体需幂等（库内 init* 全部满足）；SSR 下 effect 不上服务端，天然安全。
+ */
+declare function useIcenInit(init: (root?: HTMLElement | Document) => (() => void) | void, deps?: unknown[]): void;
+/**
+ * 事件桥原语：onIcen 的 React 形态。within 传 RefObject（组件根）时只收子树事件；
+ * 缺省全局（广播事件 icen:ai-done / icen:ai-usage 只经 [document, window]，
+ * 要收广播必须缺省 within）。handler 收 (detail, event)。
+ */
+declare function useIcenEvent<K extends keyof IcenEventMap>(type: K, handler: (detail: IcenEventMap[K], event: CustomEvent<IcenEventMap[K]>) => void, opts?: {
+    within?: RefObject<HTMLElement | null>;
+}): void;
+interface IcenComponentProps<Opts, Handle> {
+    /** 组件契约（纯 JSON；库内 opts 全部 JSON 可序列化，变化经 JSON.stringify 稳定比较） */
+    opts: Opts;
+    className?: string;
+    style?: CSSProperties;
+    /** eventRoot=true 时经此回调透出子树内全部 icen:* 事件（type 为事件名，detail 为契约 detail） */
+    onEvent?: (type: string, detail: unknown) => void;
+    /** 透出命令式句柄（ChartHandle / TableHandle / AiToolCallHandle…） */
+    handleRef?: RefObject<Handle | null>;
+}
+interface IcenComponentConfig<Opts, Handle> {
+    create: (el: HTMLElement, opts: Opts) => Handle;
+    /** 缺省：opts 变化时 destroy + 重建（同一容器元素） */
+    update?: (handle: Handle, opts: Opts) => void;
+    destroy: (handle: Handle) => void;
+    /** true 时把子树内 icen:* 事件经 onEvent 透出 */
+    eventRoot?: boolean;
+    /** 容器元素默认类（如 'icen-chart'；与用户 className 合并） */
+    defaultClass?: string;
+}
+/**
+ * 薄封装工厂：声明式 props 进，同一个命令式内核出。
+ * mount → create；opts 变 → update 或 destroy+重建；unmount → destroy。
+ */
+declare function createIcenComponent<Opts, Handle>(cfg: IcenComponentConfig<Opts, Handle>): FC<IcenComponentProps<Opts, Handle>>;
+/** 图表：renderChart 封装；spec 变化走 handle.update（原地重渲，保留事件委托） */
+declare const Chart: FC<IcenComponentProps<ChartSpec, ChartHandle>>;
+/** 数据表：createTable 封装；opts 变化 destroy + 重建（同容器） */
+declare const DataTable: FC<IcenComponentProps<TableOptions<Record<string, unknown>>, TableHandle<Record<string, unknown>>>>;
+/** AI 消息：renderAiMessage 快照渲染（append 进容器）；model 变化 = 清空容器 + 重渲 */
+declare const AiMessage: FC<IcenComponentProps<AiMessageModel, HTMLElement>>;
+/** 工具调用卡：renderAiToolCall 封装；model 变化走 handle.update（增量 patch 重渲） */
+declare const AiToolCall: FC<IcenComponentProps<AiToolCallModel, AiToolCallHandle>>;
+interface AiComposerModels {
+    providers: AiProviderOption[];
+    current?: AiComposerCurrentModel;
+}
+interface AiComposerProps {
+    /** createAiClient(...) 句柄；缺省 = 纯状态绑定（send/stop/环事件照常） */
+    client?: AiClient;
+    /** 模型切换弹层配置 */
+    models?: AiComposerModels;
+    /** 用量环口径（缺省不接管环；from:'context' 为环的正确口径） */
+    usage?: AiComposerBindOpts['usage'];
+    /** client 全托管时的消息挂载容器（client 模式必填才有意义；缺省降级纯状态绑定） */
+    messagesRef?: RefObject<HTMLElement | null>;
+    /** icen:ai-send 透出（纯状态绑定模式下接发送） */
+    onSend?: (text: string) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * AI 输入台：内部 initAiComposer + setComposerModels + bindComposer。
+ * unmount 调 binding.unbind() + init 销毁函数。DOM 契约为 ai-composer.css 头注释的标记骨架。
+ */
+declare function AiComposer(props: AiComposerProps): ReactElement;
+
+export { AiClient, AiComposer, AiComposerBindOpts, AiComposerCurrentModel, type AiComposerModels, type AiComposerProps, AiMessage, AiMessageModel, AiProviderOption, AiToolCall, AiToolCallHandle, AiToolCallModel, Chart, ChartHandle, ChartSpec, DataTable, type IcenComponentConfig, type IcenComponentProps, TableHandle, TableOptions, createIcenComponent, useIcenEvent, useIcenInit };