@icen.ai/ui 0.5.0 → 0.8.1

package/dist/behaviors/ai-composer.d.mts

@@ -0,0 +1,137 @@
+import { AiUsage } from './ai-core.js';
+import { PanelSizing } from './popover.js';
+import { AiTodoItem, AiUsageRingOpts } from './ai-panel.js';
+import { AiClient, AiAuditor } from './ai-provider.js';
+
+interface AiProviderModelOption {
+    id: string;
+    label: string;
+    /** 上下文窗口 token 数（如 1_000_000 → 弹层显示 1M） */
+    context?: number;
+}
+interface AiProviderOption {
+    id: string;
+    label: string;
+    /** 单色 SVG 字符串（经 svgIcon 消毒）；缺失时用首字母圆形章（token 色） */
+    icon?: string;
+    models: AiProviderModelOption[];
+}
+interface AiComposerCurrentModel {
+    provider: string;
+    model: string;
+}
+interface AiComposerCommand {
+    name: string;
+    description?: string;
+    /** 参数提示（如 "<path>"），弹层命令行右侧灰色展示 */
+    argsHint?: string;
+}
+/** 引用 kind：内置 4 种 + 开放注册；`string & {}` 保自动补全同时放行 registerRefKind 注册的任意 kind（照 charts.ts ChartTone 手法） */
+type AiComposerRefKind = 'file' | 'folder' | 'doc' | 'agent' | (string & {});
+interface AiComposerRefSource {
+    kind: AiComposerRefKind;
+    id: string;
+    label: string;
+    sub?: string;
+}
+/** 引用 kind 定义（registerRefKind 的注册面）。 */
+interface AiComposerRefDef {
+    /** 分组标题（弹层 group label；未知 kind 兜底为 kind 原文） */
+    label: string;
+    /** 单色 SVG 字符串（经 svgIcon 消毒）；缺省用通用文档图标 */
+    icon?: string;
+    /** 分组排序权重（小者在前）；缺省排在已知 kind 之后（最后） */
+    order?: number;
+}
+/**
+ * 注册（或覆盖）一个引用 kind（第三方扩展入口，照 registerAiKind 的 Map + 兜底模式）。
+ * 注册后弹层分组标题/图标/排序取注册表值；未注册的未知 kind 不再静默丢弃——
+ * 标题用 kind 原文、图标用通用文档图标、排序排最后。
+ */
+declare function registerRefKind(kind: string, def: AiComposerRefDef): void;
+/**
+ * 运行态切换（spec §4.3）：
+ * el 传 composer 容器或其内部任意元素（含发送钮自身），就近解析 [data-ai-composer]。
+ */
+declare function setComposerRunning(el: HTMLElement, running: boolean): void;
+/**
+ * 初始化 root 下的全部 [data-ai-composer]（root 自身匹配时包含自身）。
+ * 幂等；返回销毁函数（复刻 initBackTop 约定）。
+ */
+declare function initAiComposer(root?: ParentNode): () => void;
+/**
+ * 配置模型切换（§8）：工具条出现模型钮，弹层按 provider 分组 + 搜索过滤 + 当前勾选。
+ * current 缺省取第一个 provider 的第一个模型（静默选中，不派事件）。
+ * 选择派 icen:ai-model-change {provider, model, label, context}；
+ * 选中模型的 context 自动成为 setComposerUsage 的 total 默认值（显式 opts.total 优先）。
+ * providers 传空数组 = 清除配置（移除 JS 自动创建的模型钮）。
+ */
+declare function setComposerModels(el: HTMLElement, providers: AiProviderOption[], current?: AiComposerCurrentModel): void;
+/**
+ * 配置斜杠命令（§8）：输入开头 `/` 触发命令弹层（随输入过滤，↑↓/Enter/Tab/Esc）。
+ * 选中派 icen:ai-command {name, args} 并清空输入（命令被拦截执行、不进消息流）。
+ * commands 传空数组 = 清除配置。
+ */
+declare function setComposerCommands(el: HTMLElement, commands: AiComposerCommand[]): void;
+/**
+ * 配置 @ 引用源（§8）：任意位置 token 起点 `@` 触发引用弹层（按 kind 分组：内置
+ * file/folder/doc/agent，可经 registerRefKind 扩展/覆盖；未知 kind 不丢弃——通用文档
+ * 图标 + kind 原文兜底，排序缺省排最后）。
+ * 选中后文本插入 `@label ` + refs chip +1，派 icen:ai-ref {action:'add', ref}；
+ * chip × 移除 chip 并删文本里首个 `@label`，派 {action:'remove', ref}。
+ */
+declare function setComposerRefs(el: HTMLElement, sources: AiComposerRefSource[]): void;
+/**
+ * 配置用量环（§8）：工具条右侧挂 renderAiUsageRing（点击环弹出完整分段分解）。
+ * total 缺省时用选中模型的 context（setComposerModels 闭环）；显式 opts.total 优先。
+ * usage 传 null = 清除配置（移除 JS 自动创建的挂载点）。
+ */
+declare function setComposerUsage(el: HTMLElement, usage: AiUsage | null, opts?: AiUsageRingOpts): void;
+/**
+ * 输入框旁的实时待办（业界模式：plan/todo 是工具调用，实时状态挂在输入区而非对话流）：
+ * chip = 图标 + x/y，状态色随进度（进行中 accent / 全部完成 success / 有失败 warning）；
+ * 点击弹出完整清单（popover + renderAiTodo，只读）。传 null 清除。
+ */
+declare function setComposerTodo(el: HTMLElement, items: AiTodoItem[] | null): void;
+interface AiComposerBindOpts {
+    /**
+     * 传入即托管对话（client 模式）：icen:ai-send → renderAiMessage 用户消息 + running +
+     * client.stream → assistant 消息 + createAiStream 逐 chunk 追加 → done 收尾（meta 自动填
+     * token/成本）；错误 → setError + fail；stop → session.cancel()；排队消息每轮完成自动发送。
+     * 需要 messages 容器。history 由绑定层维护（system 消息可先经 client 直接对话时自带）。
+     */
+    client?: AiClient;
+    /** 消息挂载容器（.ai-chat-scroll 或任意元素；client 模式必填） */
+    messages?: HTMLElement;
+    /**
+     * 用量环自动更新（监听 document 的 icen:ai-done）：
+     * 'context'（默认）= 上下文估算口径（ai-core contextEstimate——环语义正确）；
+     * 'billing' = 请求用量累加（计费视角）；传 AiAuditor 实例 = auditor.summary()。
+     * total 缺省沿用 setComposerModels 的模型 context 闭环。
+     */
+    usage?: {
+        from: 'context' | 'billing' | AiAuditor;
+        total?: number;
+    };
+    /** 运行态自动管理（默认 true）：icen:ai-send → running；icen:ai-done → 解除 */
+    running?: boolean;
+    /**
+     * 三弹层（模型/命令/引用）尺寸的整体程序覆盖（PanelSizing 契约）：
+     * 优先于 composer 根上的 data-panel-*（三弹层共用的用户覆盖面）与各弹层内置默认，
+     * 一次设置对三个弹层同时生效。
+     */
+    popoverSizing?: PanelSizing;
+}
+interface AiComposerBinding {
+    /** 解绑全部监听并中止进行中的托管会话（composer 本身的 init 不受影响） */
+    unbind(): void;
+}
+/**
+ * composer ↔ 消息区 ↔ client ↔ 用量环的闭环绑定（事件驱动，传输会话所有权仍归消费方）。
+ * 不传 client 时为纯状态绑定（send→running、done→解除、环更新），渐进采用。
+ * 注意：running 自动管理依赖 client 派发的 icen:ai-done；无 client 的纯事件用法需
+ * 自行派发该事件或传 running:false。
+ */
+declare function bindComposer(el: HTMLElement, opts?: AiComposerBindOpts): AiComposerBinding;
+
+export { type AiComposerBindOpts, type AiComposerBinding, type AiComposerCommand, type AiComposerCurrentModel, type AiComposerRefDef, type AiComposerRefKind, type AiComposerRefSource, type AiProviderModelOption, type AiProviderOption, bindComposer, initAiComposer, registerRefKind, setComposerCommands, setComposerModels, setComposerRefs, setComposerRunning, setComposerTodo, setComposerUsage };