@icen.ai/ui 0.8.0 → 0.9.0

package/dist/behaviors/events.d.mts

@@ -0,0 +1,523 @@
+import { ChartEventDetail } from './charts.js';
+import { AiUsage } from './ai-core.js';
+import { AiDoneEventDetail } from './ai-provider.js';
+import { AiComposerRefSource } from './ai-composer.js';
+import { KbCitation, KbSegmentConfig, KbRetrievalQuery, KbFilterNode, KbCheckpointScope, KbSandboxMessage, KbChainStep, KbAclEntry, KbIdentity, KbAclDecision, KbAccessRequest, KbRole, KbAuditChannel, KbHygieneIssue } from './kb-core.js';
+import './popover.js';
+import './ai-panel.js';
+
+interface IcenGestureDetail {
+    /** 手势命中源：最近的 [data-gestures] 宿主 */
+    source: HTMLElement;
+    /** 原始 DOM 事件（click / contextmenu / pointerdown / mouseup…） */
+    originalEvent: Event;
+    /** 视口坐标（指针手势） */
+    x: number;
+    y: number;
+    /** 划词文本（仅 icen:text-select） */
+    text?: string;
+}
+type IcenPolicy = (e: CustomEvent<IcenGestureDetail>) => void;
+/** 手势层事件名（策略层只认这五种，编译期收死）。 */
+type IcenGestureEvent = 'icen:click' | 'icen:dblclick' | 'icen:contextmenu' | 'icen:longpress' | 'icen:text-select';
+/**
+ * 全库事件注册表：事件名 → detail 契约。onIcen 推断、emitIcen 校验，双侧同表。
+ * 新增事件必须在此登记（模板签名兜底只留给宿主自定义事件）。
+ */
+interface IcenEventMap {
+    'icen:click': IcenGestureDetail;
+    'icen:dblclick': IcenGestureDetail;
+    'icen:contextmenu': IcenGestureDetail;
+    'icen:longpress': IcenGestureDetail;
+    'icen:text-select': IcenGestureDetail;
+    'icen:chart-hover': ChartEventDetail;
+    'icen:chart-click': ChartEventDetail;
+    'icen:chart-dblclick': ChartEventDetail;
+    'icen:chart-contextmenu': ChartEventDetail;
+    'icen:chart-legend-toggle': {
+        key: string;
+        seriesIndex: number;
+        hidden: boolean;
+    };
+    'icen:chart-legend-visibility': {
+        visible: boolean;
+    };
+    'icen:tab-change': {
+        tab: HTMLElement | null;
+        panel: HTMLElement | null;
+        index: number;
+    };
+    'icen:tags-change': {
+        tags: string[];
+    };
+    'icen:otp-complete': {
+        code: string;
+    };
+    'icen:slider-input': {
+        value?: number;
+        lo?: number;
+        hi?: number;
+    };
+    'icen:slider-change': {
+        value?: number;
+        lo?: number;
+        hi?: number;
+    };
+    'icen:switch-change': {
+        el: HTMLElement;
+        checked: boolean;
+    };
+    'icen:check-change': {
+        el: HTMLElement;
+        checked: boolean | 'mixed';
+    };
+    'icen:stepper-change': {
+        el: HTMLElement;
+        value: number;
+        delta: number;
+    };
+    'icen:segmented-change': {
+        el: HTMLElement;
+        value: string;
+        index: number;
+    };
+    'icen:step-change': {
+        step: HTMLElement;
+        index: number;
+    };
+    'icen:rating-change': {
+        el: HTMLElement;
+        value: number;
+    };
+    'icen:page-change': {
+        page: number;
+    };
+    'icen:sort-change': {
+        th: HTMLElement;
+        key: string;
+        dir: 'asc' | 'desc' | null;
+    };
+    'icen:nav-select': {
+        item: HTMLElement;
+        index: number;
+    };
+    'icen:sidebar-toggle': {
+        group: HTMLElement;
+        open: boolean;
+    };
+    'icen:sidebar-collapse': {
+        collapsed: boolean;
+    };
+    'icen:split-change': {
+        value: number;
+    };
+    'icen:copy-success': {
+        text: string;
+    };
+    'icen:copy-error': {
+        text: string;
+        reason: string;
+    };
+    'icen:back-top': Record<string, never>;
+    'icen:modal-open': {
+        id: string;
+    };
+    'icen:modal-close': {
+        id: string;
+    };
+    'icen:command-palette-open': Record<string, never>;
+    'icen:command-palette-close': Record<string, never>;
+    'icen:menu-select': {
+        source: HTMLElement;
+        item: HTMLElement;
+        value: string;
+        label: string;
+    };
+    'icen:select-change': {
+        value: string;
+        values: string[];
+        label: string;
+    };
+    'icen:date-change': {
+        value: string;
+        date: Date | null;
+    };
+    'icen:accordion-toggle': {
+        item: HTMLElement;
+        index: number;
+        open: boolean;
+    };
+    'icen:tree-select': {
+        node: HTMLElement;
+    };
+    'icen:tree-toggle': {
+        node: HTMLElement;
+        open: boolean;
+    };
+    'icen:carousel-change': {
+        index: number;
+        count: number;
+    };
+    'icen:theme-change': {
+        preset: string;
+        dark: boolean;
+        style: string;
+    };
+    'icen:table-sort-change': {
+        key: string;
+        dir: 'asc' | 'desc';
+    };
+    'icen:table-page-change': {
+        page: number;
+        pageSize: number;
+    };
+    'icen:table-page-size-change': {
+        pageSize: number;
+    };
+    'icen:table-filter-change': {
+        key: string;
+        values: string[];
+    };
+    'icen:table-search-change': {
+        query: string;
+    };
+    'icen:table-selection-change': {
+        selected: unknown[];
+    };
+    'icen:table-row-click': {
+        row: unknown;
+        index: number;
+    };
+    'icen:table-row-toggle': {
+        row: unknown;
+        index: number;
+        expanded: boolean;
+    };
+    'icen:table-columns-change': {
+        hidden: string[];
+    };
+    'icen:table-export': {
+        count: number;
+    };
+    'icen:upload': {
+        files: File[];
+    };
+    'icen:upload-error': {
+        file: File | null;
+        reason: string;
+    };
+    'icen:upload-remove': {
+        file: File;
+    };
+    'icen:ai-toggle': {
+        el: HTMLElement;
+        open: boolean;
+    };
+    'icen:ai-copy': {
+        el: HTMLElement;
+    };
+    'icen:ai-retry': {
+        el: HTMLElement;
+    };
+    'icen:ai-approve': {
+        id: string;
+        kind: string;
+    };
+    'icen:ai-reject': {
+        id: string;
+        kind: string;
+    };
+    'icen:ai-diff-accept': {
+        path: string;
+    };
+    'icen:ai-diff-reject': {
+        path: string;
+    };
+    'icen:ai-send': {
+        text: string;
+    };
+    'icen:ai-stop': Record<string, never>;
+    'icen:ai-queue': {
+        text: string;
+    };
+    'icen:ai-dequeue': {
+        index: number;
+    };
+    'icen:ai-attach': {
+        files: File[];
+    };
+    'icen:ai-model-change': {
+        provider: string;
+        model: string;
+        label: string;
+        context?: number;
+    };
+    'icen:ai-command': {
+        name: string;
+        args: string;
+    };
+    'icen:ai-ref': {
+        action: 'add' | 'remove';
+        ref: AiComposerRefSource;
+    };
+    'icen:ai-todo-toggle': {
+        index: number;
+        status: string;
+    };
+    'icen:ai-audit-clear': Record<string, never>;
+    'icen:ai-context-open': Record<string, never>;
+    'icen:ai-context-close': Record<string, never>;
+    'icen:ai-tool-call': {
+        name: string;
+        input: unknown;
+        el: HTMLElement;
+    };
+    'icen:ai-tool-result': {
+        name: string;
+        ok: boolean;
+        el: HTMLElement;
+        error?: string;
+        count: number;
+    };
+    'icen:ai-tool-evict': {
+        name: string;
+        el: HTMLElement;
+    };
+    'icen:ai-usage': AiUsage;
+    'icen:ai-done': AiDoneEventDetail;
+    'icen:ai-thread-select': {
+        key: string;
+    };
+    'icen:ai-thread-action': {
+        action: 'rename' | 'pin' | 'archive' | 'delete' | 'move';
+        key: string;
+    };
+    'icen:ai-feedback': {
+        value: 1 | -1 | 0;
+        reason?: string;
+        el?: HTMLElement;
+    };
+    'icen:ai-branch-change': {
+        index: number;
+        count: number;
+    };
+    'icen:kb-citation-open': {
+        citation: KbCitation;
+    };
+    'icen:kb-source-open': {
+        source: KbCitation;
+    };
+    'icen:kb-passage-jump': {
+        citation: KbCitation;
+    };
+    'icen:kb-passage-close': Record<string, never>;
+    'icen:kb-pipeline-toggle': {
+        el: HTMLElement;
+        open: boolean;
+    };
+    'icen:kb-pipeline-rerun': {
+        documentId: string;
+    };
+    'icen:kb-chunk-toggle': {
+        chunkId: string;
+        available: boolean;
+    };
+    'icen:kb-chunk-edit': {
+        chunkId: string;
+    };
+    'icen:kb-chunk-remove': {
+        chunkId: string;
+    };
+    'icen:kb-chunk-add': {
+        documentId: string;
+    };
+    'icen:kb-chunk-search': {
+        mode: 'text' | 'vector';
+        query: string;
+    };
+    'icen:kb-segment-change': {
+        config: KbSegmentConfig;
+    };
+    'icen:kb-connector-sync': {
+        connectorId: string;
+    };
+    'icen:kb-connector-reauth': {
+        connectorId: string;
+    };
+    'icen:kb-connector-schedule': {
+        connectorId: string;
+        schedule: string;
+    };
+    'icen:kb-metadata-change': {
+        action: 'define' | 'bind' | 'remove';
+        key: string;
+    };
+    'icen:kb-qa-change': {
+        op: 'add' | 'edit' | 'remove';
+        index: number;
+    };
+    'icen:kb-qa-import': {
+        source: string;
+    };
+    'icen:kb-retrieval-run': {
+        query: KbRetrievalQuery;
+    };
+    'icen:kb-filter-change': {
+        node: KbFilterNode | null;
+        valid: boolean;
+    };
+    'icen:kb-rerank-toggle': {
+        enabled: boolean;
+        model?: string;
+    };
+    'icen:kb-hittest-add': {
+        question: string;
+    };
+    'icen:kb-hittest-run': Record<string, never>;
+    'icen:kb-sql-edit': {
+        sql: string;
+    };
+    'icen:kb-sql-rerun': {
+        sql: string;
+    };
+    'icen:kb-clarify-answer': {
+        id?: string;
+        value: string;
+        label: string;
+    };
+    'icen:kb-verified-open': {
+        assetId: string;
+    };
+    'icen:kb-explain-toggle': {
+        el: HTMLElement;
+        open: boolean;
+    };
+    'icen:kb-trace-select': {
+        spanId: string;
+    };
+    'icen:kb-trace-toggle': {
+        spanId: string;
+        open: boolean;
+    };
+    'icen:kb-review-assign': {
+        taskId: string;
+        assignee: string;
+    };
+    'icen:kb-review-score': {
+        taskId: string;
+        name: string;
+        value: string | number;
+    };
+    'icen:kb-review-submit': {
+        taskId: string;
+    };
+    'icen:kb-gap-action': {
+        query: string;
+        action: 'create-doc' | 'add-synonym';
+    };
+    'icen:kb-eval-compare': {
+        runA: string;
+        runB: string;
+    };
+    'icen:kb-canvas-ai': {
+        instruction: string;
+        selection?: {
+            text: string;
+        };
+    };
+    'icen:kb-canvas-version': {
+        versionId: string;
+    };
+    'icen:kb-checkpoint-restore': {
+        checkpointId: string;
+        scope: KbCheckpointScope;
+    };
+    'icen:kb-sandbox-message': {
+        channel: 'in' | 'out';
+        payload: KbSandboxMessage;
+    };
+    'icen:kb-chain-step': {
+        index: number;
+        step: KbChainStep;
+    };
+    'icen:kb-acl-grant': {};
+    'icen:kb-acl-remove': {
+        subject: KbAclEntry['subject'];
+    };
+    'icen:kb-acl-inherit': {
+        action: 'break' | 'restore';
+    };
+    'icen:kb-whocan-check': {
+        identity: KbIdentity;
+        decision: KbAclDecision;
+    };
+    'icen:kb-access-request': {
+        request: KbAccessRequest;
+    };
+    'icen:kb-access-decide': {
+        id: string;
+        decision: 'approve' | 'deny';
+        role?: KbRole;
+    };
+    'icen:kb-access-expire': {
+        id: string;
+    };
+    'icen:kb-audit-filter': {
+        channel: KbAuditChannel | 'all';
+    };
+    'icen:kb-audit-export': {
+        channel: KbAuditChannel | 'all';
+    };
+    'icen:kb-hygiene-action': {
+        issue: KbHygieneIssue;
+    };
+    'icen:kb-visibility-identity': {
+        identity: KbIdentity;
+    };
+    'icen:kb-visibility-layer': {
+        layer: 'pre' | 'post' | 'none';
+    };
+    [key: `icen:${string}`]: unknown;
+}
+interface IcenListenOptions {
+    /** 只监听该子树内冒泡上来的事件（组件实例级绑定）。
+     *  广播事件（自 document 派发）不经过元素子树：within 为 Element 时收不到，要收广播请用全局形态 */
+    within?: Element | Document;
+    /** AbortSignal：abort 即解绑（React useEffect 清理 / 批量卸载场景） */
+    signal?: AbortSignal;
+    /** 只触发一次（触发后自动解绑） */
+    once?: boolean;
+}
+/**
+ * 统一绑定器（全库事件一个入口）：
+ *   onIcen('icen:tab-change', (e) => e.detail.index)                       全局
+ *   onIcen('icen:chart-click', '.chart', (e) => …)                          选择器委托
+ *   onIcen('icen:upload', (e) => …, { within: formEl })                     子树限定
+ *   onIcen('icen:ai-done', (e) => …, { signal: ctrl.signal })               广播 + 信号解绑
+ * 返回解绑函数 —— React useEffect / Vue onUnmounted 直接 return。
+ */
+declare function onIcen<K extends keyof IcenEventMap>(type: K, handler: (e: CustomEvent<IcenEventMap[K]>) => void, opts?: IcenListenOptions): () => void;
+declare function onIcen<K extends keyof IcenEventMap>(type: K, selector: string, handler: (e: CustomEvent<IcenEventMap[K]>) => void, opts?: IcenListenOptions): () => void;
+/**
+ * 全库唯一派生口：bubbles + composed + cancelable。返回 false = 被消费方 preventDefault。
+ * 组件作者派发领域事件一律走这里（不要裸写 new CustomEvent）；detail 契约见 IcenEventMap。
+ * 从 document 派发 = 全局广播（传播只经 [document, window]，仅 onIcen 全局形态可收；
+ * within 为 Element 收不到，要收广播请用全局形态）。
+ */
+declare function emitIcen<K extends keyof IcenEventMap>(source: Element | Document, type: K, detail: IcenEventMap[K]): boolean;
+/** 注册/覆盖某手势事件的全站默认行为；传 null 移除（= 禁用该默认）。
+ *  只接受手势层五种事件——领域事件的默认行为归组件交互契约，不会被静默忽略。 */
+declare function setEventPolicy(type: IcenGestureEvent, policy: IcenPolicy | null): void;
+/** 读取某手势事件当前注册的策略（与 setEventPolicy 对称的调试/测试读取器；未注册返回 undefined）。 */
+declare function getEventPolicy(type: IcenGestureEvent): IcenPolicy | undefined;
+/** 清空全部策略（测试/热重载用）。 */
+declare function resetEventPolicies(): void;
+/**
+ * 启动手势层（全局委托一次，幂等；重复调用安全）。
+ * 返回销毁函数：摘除全部 document 级委托并复位幂等标记，销毁后可重新 init。
+ */
+declare function initGestures(): () => void;
+/** 摘除手势层委托（等同 initGestures 返回的销毁函数；未启动时为 no-op）。 */
+declare function destroyGestures(): void;
+
+export { type IcenEventMap, type IcenGestureDetail, type IcenGestureEvent, type IcenListenOptions, type IcenPolicy, destroyGestures, emitIcen, getEventPolicy, initGestures, onIcen, resetEventPolicies, setEventPolicy };