@icen.ai/ui 0.8.0 → 0.8.1

package/dist/behaviors/events.d.mts

@@ -0,0 +1,330 @@
+import { ChartEventDetail } from './charts.js';
+import { AiUsage } from './ai-core.js';
+import { AiDoneEventDetail } from './ai-provider.js';
+import { AiComposerRefSource } from './ai-composer.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;
+    [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 };

package/dist/behaviors/events.mjs

@@ -0,0 +1,208 @@
+// src/behaviors/events.ts
+function onIcen(type, a, b, c) {
+  if (typeof document === "undefined") return () => {
+  };
+  const selector = typeof a === "string" ? a : null;
+  const handler = selector ? b : a;
+  const opts = selector ? c : b;
+  const within = opts?.within ?? document;
+  const once = opts?.once === true;
+  let off = () => {
+  };
+  const fn = (e) => {
+    const broadcast = !(e.target instanceof Element);
+    if (selector) {
+      if (broadcast) return;
+      const detail = e.detail;
+      const src = detail?.source instanceof Element ? detail.source : e.target;
+      if (!(src instanceof Element) || !src.closest(selector)) return;
+    }
+    handler(e);
+    if (once) off();
+  };
+  within.addEventListener(type, fn);
+  off = () => {
+    within.removeEventListener(type, fn);
+    opts?.signal?.removeEventListener("abort", off);
+  };
+  if (opts?.signal) {
+    if (opts.signal.aborted) {
+      off();
+      return () => {
+      };
+    }
+    opts.signal.addEventListener("abort", off, { once: true });
+  }
+  return off;
+}
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+var policies = /* @__PURE__ */ new Map();
+function setEventPolicy(type, policy) {
+  if (policy) policies.set(type, policy);
+  else policies.delete(type);
+}
+function getEventPolicy(type) {
+  return policies.get(type);
+}
+function resetEventPolicies() {
+  policies.clear();
+}
+var LONGPRESS_MS = 520;
+var LONGPRESS_MOVE = 12;
+var CLICK_DELAY = 220;
+var CLICK_DRAG_TOLERANCE = 5;
+function gestureHost(e, name) {
+  const t = e.target;
+  if (!(t instanceof Element)) return null;
+  return t.closest(`[data-gestures~="${name}"]`);
+}
+function pointOf(e) {
+  return e instanceof MouseEvent || typeof PointerEvent !== "undefined" && e instanceof PointerEvent ? { x: e.clientX, y: e.clientY } : { x: 0, y: 0 };
+}
+function emit(host, type, originalEvent, text) {
+  const { x, y } = pointOf(originalEvent);
+  const detail = { source: host, originalEvent, x, y };
+  if (text != null) detail.text = text;
+  const ev = new CustomEvent(type, {
+    detail,
+    bubbles: true,
+    composed: true,
+    cancelable: true
+  });
+  const delivered = host.dispatchEvent(ev);
+  if (delivered) policies.get(type)?.(ev);
+  return ev;
+}
+var gesturesInit = false;
+var gesturesTeardown = null;
+function initGestures() {
+  if (gesturesInit || typeof document === "undefined") return () => {
+  };
+  gesturesInit = true;
+  let clickTimer = null;
+  let pending = null;
+  let downPos = null;
+  let suppressTrailingClick = false;
+  const cancelPendingClick = () => {
+    if (clickTimer) clearTimeout(clickTimer);
+    clickTimer = null;
+    pending = null;
+  };
+  const onDownPos = (e) => {
+    downPos = { x: e.clientX, y: e.clientY };
+    suppressTrailingClick = false;
+  };
+  const isDragRelease = (e) => downPos != null && Math.hypot(e.clientX - downPos.x, e.clientY - downPos.y) > CLICK_DRAG_TOLERANCE;
+  const onClick = (e) => {
+    const host = gestureHost(e, "click");
+    if (!host) return;
+    if (suppressTrailingClick) {
+      suppressTrailingClick = false;
+      return;
+    }
+    if (isDragRelease(e)) return;
+    if (host.matches('[data-gestures~="dblclick"]')) {
+      if (clickTimer) clearTimeout(clickTimer);
+      pending = { host, e };
+      clickTimer = setTimeout(() => {
+        clickTimer = null;
+        const p = pending;
+        pending = null;
+        if (p) emit(p.host, "icen:click", p.e);
+      }, CLICK_DELAY);
+    } else {
+      emit(host, "icen:click", e);
+    }
+  };
+  const onDblClick = (e) => {
+    const host = gestureHost(e, "dblclick");
+    if (!host) return;
+    cancelPendingClick();
+    if (isDragRelease(e)) return;
+    emit(host, "icen:dblclick", e);
+  };
+  const onContextMenu = (e) => {
+    const host = gestureHost(e, "contextmenu");
+    if (!host) return;
+    const hasPolicy = policies.has("icen:contextmenu");
+    const ev = emit(host, "icen:contextmenu", e);
+    if (ev.defaultPrevented || hasPolicy) e.preventDefault();
+  };
+  let lp = null;
+  const clearLp = () => {
+    if (lp) clearTimeout(lp.timer);
+    lp = null;
+  };
+  const onLpDown = (e) => {
+    const host = gestureHost(e, "longpress");
+    if (!host) return;
+    clearLp();
+    lp = {
+      host,
+      e,
+      x: e.clientX,
+      y: e.clientY,
+      timer: setTimeout(() => {
+        const cur = lp;
+        lp = null;
+        if (cur) {
+          suppressTrailingClick = true;
+          emit(cur.host, "icen:longpress", cur.e);
+        }
+      }, LONGPRESS_MS)
+    };
+  };
+  const onLpMove = (e) => {
+    if (!lp) return;
+    if (Math.hypot(e.clientX - lp.x, e.clientY - lp.y) > LONGPRESS_MOVE) clearLp();
+  };
+  const onTextSelect = (e) => {
+    const host = gestureHost(e, "text-select");
+    if (!host) return;
+    const sel = window.getSelection();
+    const text = sel?.toString() ?? "";
+    if (!text.trim() || !sel || !host.contains(sel.anchorNode)) return;
+    emit(host, "icen:text-select", e, text);
+  };
+  document.addEventListener("pointerdown", onDownPos);
+  document.addEventListener("click", onClick);
+  document.addEventListener("dblclick", onDblClick);
+  document.addEventListener("contextmenu", onContextMenu);
+  document.addEventListener("pointerdown", onLpDown);
+  document.addEventListener("pointermove", onLpMove);
+  document.addEventListener("pointerup", clearLp);
+  document.addEventListener("pointercancel", clearLp);
+  document.addEventListener("mouseup", onTextSelect);
+  gesturesTeardown = () => {
+    document.removeEventListener("pointerdown", onDownPos);
+    document.removeEventListener("click", onClick);
+    document.removeEventListener("dblclick", onDblClick);
+    document.removeEventListener("contextmenu", onContextMenu);
+    document.removeEventListener("pointerdown", onLpDown);
+    document.removeEventListener("pointermove", onLpMove);
+    document.removeEventListener("pointerup", clearLp);
+    document.removeEventListener("pointercancel", clearLp);
+    document.removeEventListener("mouseup", onTextSelect);
+    cancelPendingClick();
+    clearLp();
+    gesturesInit = false;
+    gesturesTeardown = null;
+  };
+  return gesturesTeardown;
+}
+function destroyGestures() {
+  gesturesTeardown?.();
+}
+export {
+  destroyGestures,
+  emitIcen,
+  getEventPolicy,
+  initGestures,
+  onIcen,
+  resetEventPolicies,
+  setEventPolicy
+};

package/dist/behaviors/input.mjs

@@ -1,12 +1,20 @@
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
 // src/behaviors/input.ts
-var isComposing = false;
-if (typeof document !== "undefined") {
-  document.addEventListener("compositionstart", () => {
-    isComposing = true;
+function trackComposing(target) {
+  let composing = false;
+  target.addEventListener("compositionstart", () => {
+    composing = true;
   });
-  document.addEventListener("compositionend", () => {
-    isComposing = false;
+  target.addEventListener("compositionend", () => {
+    composing = false;
   });
+  return () => composing;
 }
 function setupClear(wrap) {
   const btn = wrap.querySelector(".input-clear");
@@ -58,7 +66,6 @@ function setupCounter(field) {
   const maxAttr = field.getAttribute("maxlength");
   const dataCount = field.getAttribute("data-count");
   if (!maxAttr && dataCount === null) return;
-  el.__icenCounterInit = true;
   const max = maxAttr ? Number(maxAttr) : 0;
   let counter = null;
   const wrap = field.closest(".input-wrap, .textarea-wrap");
@@ -75,6 +82,8 @@ function setupCounter(field) {
   }
   const counterEl = counter;
   if (!counterEl) return;
+  el.__icenCounterInit = true;
+  const isComposing = trackComposing(field);
   function update() {
     const len = field.value.length;
     counterEl.textContent = max > 0 ? `${len} / ${max}` : `${len}`;
@@ -85,8 +94,9 @@ function setupCounter(field) {
       else if (ratio >= 0.8) counterEl.classList.add("is-warn");
     }
   }
+  ;
   field.addEventListener("input", () => {
-    if (!isComposing) update();
+    if (!isComposing()) update();
   });
   update();
 }
@@ -96,6 +106,7 @@ function setupMask(field) {
   const mask = field.getAttribute("data-mask");
   if (!mask) return;
   el.__icenMaskInit = true;
+  const isComposing = trackComposing(field);
   const maskChars = [];
   for (const ch of mask) maskChars.push(ch);
   function isInputSlot(ch) {
@@ -137,7 +148,7 @@ function setupMask(field) {
   field.value = lastFormatted;
   field.setAttribute("data-raw-value", extractRaw(lastFormatted));
   field.addEventListener("input", () => {
-    if (isComposing) return;
+    if (isComposing()) return;
     const cursorPos = field.selectionStart ?? 0;
     const oldRaw = extractRaw(lastFormatted);
     const newFull = field.value;
@@ -165,7 +176,7 @@ function setupMask(field) {
     field.setSelectionRange(targetCursor, targetCursor);
   });
   field.addEventListener("keydown", (ev) => {
-    if (isComposing) return;
+    if (isComposing()) return;
     if (ev.ctrlKey || ev.metaKey || ev.altKey) return;
     if (["Backspace", "Delete", "Tab", "Escape", "ArrowLeft", "ArrowRight", "Home", "End", "Enter"].includes(ev.key)) return;
     const currentRaw = extractRaw(field.value);
@@ -195,6 +206,7 @@ function setupOtp(group) {
   const el = group;
   if (el.__icenInputInit) return;
   el.__icenInputInit = true;
+  const isComposing = trackComposing(group);
   const cells = Array.from(group.querySelectorAll(".otp-cell"));
   const syncFilled = (cell) => {
     cell.classList.toggle("is-filled", cell.value.length > 0);
@@ -205,7 +217,7 @@ function setupOtp(group) {
     }
     syncFilled(cell);
     cell.addEventListener("input", () => {
-      if (isComposing) return;
+      if (isComposing()) return;
       const ch = cell.value.slice(-1);
       cell.value = ch;
       syncFilled(cell);
@@ -239,7 +251,8 @@ function setupOtp(group) {
   const fireComplete = () => {
     const code = cells.map((c) => c.value).join("");
     if (code.length === cells.length && cells.every((c) => c.value.length > 0)) {
-      group.dispatchEvent(new CustomEvent("icen:otp-complete", { detail: { code }, bubbles: true }));
+      group.classList.add("is-complete");
+      emitIcen(group, "icen:otp-complete", { code });
       group.dispatchEvent(new CustomEvent("otp:complete", { detail: { code }, bubbles: true }));
     }
   };

package/dist/behaviors/modal.d.mts

@@ -1,11 +1,30 @@
-/** 打开指定 id 的 modal；已有其他 modal 打开时先关闭它。 */
-declare function openModal(id: string): void;
-/** 关闭指定 id 的 modal（backdrop 已被外部移除时也照常复位状态/监听/滚动锁）。 */
+/** 焦点陷阱的可聚焦元素选择器（modal / command-palette 焦点陷阱全库共用）。 */
+declare const FOCUSABLE = "button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"]), [contenteditable]:not([contenteditable=\"false\"]), audio, video, details>summary";
+/** openModal 可选项。 */
+interface ModalOpenOptions {
+    /**
+     * 初始焦点：缺省 = 聚焦面板内第一个可聚焦元素（无则面板自身）；
+     * 传 HTMLElement = 聚焦该元素；'none' = 不动焦点（调用方自管，焦点陷阱仍生效）。
+     */
+    initialFocus?: HTMLElement | 'none';
+}
+/**
+ * 打开指定 id 的 modal；已有其他 modal 打开时先关闭它。
+ * 打开成功后从 document 派发 icen:modal-open { id }（广播）。
+ */
+declare function openModal(id: string, opts?: ModalOpenOptions): void;
+/**
+ * 关闭指定 id 的 modal（backdrop 已被外部移除时也照常复位状态/监听/滚动锁）。
+ * 关闭已打开的 modal 后从 document 派发 icen:modal-close { id }（广播）；
+ * 关闭未被接管打开的 modal（幂等空操作路径）不派发。
+ */
 declare function closeModal(id: string): void;
 /**
  * 绑定触发器/关闭钮/backdrop 点击（document 级事件委托，重复调用安全）。
  * root 用于扫描 [data-modal-open] 补 aria-haspopup=dialog。
+ * 返回销毁函数：摘除 document 委托并复位幂等标记（销毁后可重新 init）；
+ * 销毁时若有 modal 开着会顺带关闭（复位滚动锁/监听/焦点）。SSR 下返回 no-op。
  */
-declare function initModal(root?: ParentNode): void;
+declare function initModal(root?: ParentNode): () => void;
 
-export { closeModal, initModal, openModal };
+export { FOCUSABLE, type ModalOpenOptions, closeModal, initModal, openModal };