@icen.ai/ui 0.5.0 → 0.8.1

package/dist/behaviors/dropdown.mjs

@@ -1,12 +1,142 @@
+// src/behaviors/popover.ts
+var PANEL_SIZING_ATTRS = {
+  width: "data-panel-width",
+  minWidth: "data-panel-min",
+  maxWidth: "data-panel-max",
+  minHeight: "data-panel-min-height",
+  maxHeight: "data-panel-max-height"
+};
+function readPanelSizing(el) {
+  const out = {};
+  if (!el) return out;
+  for (const key of Object.keys(PANEL_SIZING_ATTRS)) {
+    const raw = el.getAttribute(PANEL_SIZING_ATTRS[key]);
+    if (raw == null) continue;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n > 0) out[key] = n;
+  }
+  return out;
+}
+function applyPanelSizing(panel, sizing) {
+  if (sizing == null) {
+    panel.style.width = "";
+    panel.style.minWidth = "";
+    panel.style.maxWidth = "";
+    panel.style.minHeight = "";
+    panel.style.maxHeight = "";
+    return;
+  }
+  const vw = typeof document === "undefined" ? Number.POSITIVE_INFINITY : document.documentElement.clientWidth;
+  const fitW = (n) => Math.min(n, Math.max(80, vw - 24));
+  if (sizing.width != null) {
+    const w = fitW(sizing.width);
+    panel.style.width = `${w}px`;
+    panel.style.maxWidth = `${w}px`;
+  }
+  if (sizing.minWidth != null) panel.style.minWidth = `${fitW(sizing.minWidth)}px`;
+  if (sizing.maxWidth != null && sizing.width == null) panel.style.maxWidth = `${fitW(sizing.maxWidth)}px`;
+  if (sizing.minHeight != null) panel.style.minHeight = `${sizing.minHeight}px`;
+  if (sizing.maxHeight != null) panel.style.maxHeight = `${sizing.maxHeight}px`;
+}
+var DEFAULT_MIN_WIDTH = 220;
+var DEFAULT_MAX_WIDTH = 420;
+var DEFAULT_MIN_HEIGHT = 120;
+var DEFAULT_MAX_HEIGHT = 420;
+function clamp(value, min, max) {
+  if (max < min) return min;
+  return Math.min(max, Math.max(min, value));
+}
+function chooseSide(preferredSide, availableTop, availableBottom, desiredHeight) {
+  const preferredSpace = preferredSide === "top" ? availableTop : availableBottom;
+  const oppositeSpace = preferredSide === "top" ? availableBottom : availableTop;
+  if (preferredSpace >= desiredHeight) return preferredSide;
+  if (oppositeSpace >= desiredHeight) return preferredSide === "top" ? "bottom" : "top";
+  if (preferredSpace >= oppositeSpace) return preferredSide;
+  return preferredSide === "top" ? "bottom" : "top";
+}
+function horizontalAnchor(anchor, width, align) {
+  if (align === "center") return anchor.left + anchor.width / 2 - width / 2;
+  if (align === "end") return anchor.right - width;
+  return anchor.left;
+}
+function computePopoverLayout(anchor, viewport, opts = {}) {
+  const margin = opts.margin ?? 12;
+  const offset = opts.offset ?? 8;
+  const preferredSide = opts.side ?? "top";
+  const align = opts.align ?? "start";
+  if (preferredSide === "left" || preferredSide === "right") {
+    const availableLeft = Math.max(0, anchor.left - margin - offset);
+    const availableRight = Math.max(0, viewport.width - anchor.right - margin - offset);
+    const side2 = (preferredSide === "left" ? availableLeft : availableRight) >= DEFAULT_MIN_WIDTH ? preferredSide : preferredSide === "left" ? "right" : "left";
+    const minWidth2 = Math.max(1, opts.minWidth ?? DEFAULT_MIN_WIDTH);
+    const maxWidth2 = Math.min(
+      Math.max(opts.maxWidth ?? DEFAULT_MAX_WIDTH, minWidth2),
+      side2 === "left" ? availableLeft : availableRight
+    );
+    const width2 = minWidth2;
+    const left2 = clamp(
+      side2 === "left" ? anchor.left - offset - width2 : anchor.right + offset,
+      margin,
+      viewport.width - margin - width2
+    );
+    const availableHeight2 = Math.max(80, viewport.height - margin * 2);
+    const maxHeight2 = Math.min(opts.maxHeight ?? DEFAULT_MAX_HEIGHT, availableHeight2);
+    const desired = clamp(opts.contentHeightHint ?? Math.min(anchor.height, maxHeight2), 40, maxHeight2);
+    const anchorTop = align === "center" ? anchor.top + anchor.height / 2 - desired / 2 : align === "end" ? anchor.bottom - desired : anchor.top;
+    const top2 = clamp(anchorTop, margin, viewport.height - margin - desired);
+    return { side: side2, left: left2, top: top2, width: width2, maxHeight: maxHeight2 };
+  }
+  const availableWidth = Math.max(80, viewport.width - margin * 2);
+  const requestedMinWidth = Math.max(1, opts.minWidth ?? DEFAULT_MIN_WIDTH);
+  const requestedMaxWidth = Math.max(requestedMinWidth, opts.maxWidth ?? DEFAULT_MAX_WIDTH);
+  const maxWidth = Math.min(requestedMaxWidth, availableWidth);
+  const minWidth = Math.min(requestedMinWidth, maxWidth);
+  const availableTop = Math.max(0, anchor.top - margin - offset);
+  const availableBottom = Math.max(0, viewport.height - anchor.bottom - margin - offset);
+  const availableHeight = Math.max(80, viewport.height - margin * 2);
+  const minHeight = Math.min(Math.max(80, opts.minHeight ?? DEFAULT_MIN_HEIGHT), availableHeight);
+  const requestedMaxHeight = Math.max(minHeight, opts.maxHeight ?? DEFAULT_MAX_HEIGHT);
+  const fallbackHeight = Math.min(260, requestedMaxHeight);
+  const contentHeight = Math.max(opts.contentHeightHint ?? 0, fallbackHeight);
+  const desiredHeight = clamp(contentHeight, minHeight, Math.min(requestedMaxHeight, availableHeight));
+  const side = chooseSide(preferredSide, availableTop, availableBottom, desiredHeight);
+  const sideSpace = side === "top" ? availableTop : availableBottom;
+  const maxHeight = Math.min(
+    requestedMaxHeight,
+    Math.max(80, sideSpace || Math.max(availableTop, availableBottom)),
+    availableHeight
+  );
+  const positionedHeight = clamp(desiredHeight, 40, maxHeight);
+  const width = align === "stretch" ? clamp(anchor.width, minWidth, maxWidth) : maxWidth;
+  const left = clamp(horizontalAnchor(anchor, width, align), margin, viewport.width - margin - width);
+  const desiredTop = side === "top" ? anchor.top - offset - positionedHeight : anchor.bottom + offset;
+  const top = clamp(desiredTop, margin, viewport.height - margin - positionedHeight);
+  return { side, left, top, width, maxHeight };
+}
+
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
+// src/behaviors/context-menu.ts
+function emitMenuSelect(source, item) {
+  emitIcen(item, "icen:menu-select", {
+    source,
+    item,
+    value: item.dataset.value ?? "",
+    /* 优先专用 label 子元素（避开快捷键/图标文本混入），无则退整项文本 */
+    label: (item.querySelector(".menu-item-label, .command-item-label")?.textContent ?? item.textContent ?? "").trim().slice(0, 80)
+  });
+}
+
 // src/behaviors/dropdown.ts
 var VIEWPORT_MARGIN = 12;
 var SIDE_OFFSET = 4;
 var active = null;
 var initialized = false;
-function clamp(value, min, max) {
-  if (max < min) return min;
-  return Math.min(max, Math.max(min, value));
-}
 function menuItems(panel) {
   return Array.from(panel.querySelectorAll(".menu-item:not(.is-disabled):not(:disabled)"));
 }
@@ -19,21 +149,14 @@ function place() {
   if (!active) return;
   const { trigger, panel } = active;
   const rect = trigger.getBoundingClientRect();
-  const vw = window.innerWidth;
-  const vh = window.innerHeight;
-  const pw = panel.offsetWidth;
-  const ph = panel.offsetHeight;
-  const left = clamp(rect.left, VIEWPORT_MARGIN, vw - VIEWPORT_MARGIN - pw);
-  let top = rect.bottom + SIDE_OFFSET;
-  let side = "bottom";
-  if (top + ph > vh - VIEWPORT_MARGIN && rect.top - SIDE_OFFSET - ph >= VIEWPORT_MARGIN) {
-    top = rect.top - SIDE_OFFSET - ph;
-    side = "top";
-  }
-  top = clamp(top, VIEWPORT_MARGIN, vh - VIEWPORT_MARGIN - ph);
-  panel.style.left = `${left}px`;
-  panel.style.top = `${top}px`;
-  panel.dataset.side = side;
+  const layout = computePopoverLayout(
+    rect,
+    { width: window.innerWidth, height: window.innerHeight },
+    { side: "bottom", offset: SIDE_OFFSET, margin: VIEWPORT_MARGIN }
+  );
+  panel.style.left = `${layout.left}px`;
+  panel.style.top = `${layout.top}px`;
+  panel.dataset.side = layout.side;
 }
 function openDropdown(trigger, highlightFirst = false) {
   closeDropdown();
@@ -44,6 +167,7 @@ function openDropdown(trigger, highlightFirst = false) {
   panel.className = "menu";
   panel.setAttribute("role", "menu");
   panel.style.visibility = "hidden";
+  applyPanelSizing(panel, readPanelSizing(root));
   while (template.firstChild) panel.appendChild(template.firstChild);
   panel.querySelectorAll(".menu-item").forEach((el) => el.setAttribute("role", "menuitem"));
   document.body.appendChild(panel);
@@ -75,7 +199,10 @@ function onOutsidePointerDown(e) {
   if (active.panel.contains(target) || active.trigger.contains(target)) return;
   closeDropdown();
 }
-function onScroll() {
+function onScroll(e) {
+  if (!active) return;
+  const target = e.target;
+  if (target instanceof Node && active.panel.contains(target)) return;
   closeDropdown();
 }
 function onKeyDown(e) {
@@ -97,21 +224,28 @@ function onKeyDown(e) {
   if (e.key === "Enter" && active.highlight >= 0) {
     e.preventDefault();
     const item = items[active.highlight];
+    emitMenuSelect(active.panel, item);
     closeDropdown(true);
     item.click();
   }
 }
-function initDropdown(root = document) {
-  if (typeof document === "undefined") return;
-  root.querySelectorAll("[data-dropdown-trigger]").forEach((el) => el.setAttribute("aria-expanded", "false"));
-  if (initialized) return;
+function initDropdown(root) {
+  if (typeof document === "undefined") return () => {
+  };
+  const scope = root ?? document;
+  scope.querySelectorAll("[data-dropdown-trigger]").forEach((el) => el.setAttribute("aria-expanded", "false"));
+  if (initialized) return () => {
+  };
   initialized = true;
-  document.addEventListener("click", (e) => {
+  const onClick = (e) => {
     const target = e.target instanceof Element ? e.target : null;
     if (!target) return;
     if (active && target.closest(".menu-item") && active.panel.contains(target)) {
       const item = target.closest(".menu-item");
       if (item) {
+        if (!item.matches(".is-disabled") && !item.matches(":disabled")) {
+          emitMenuSelect(active.panel, item);
+        }
         closeDropdown();
         return;
       }
@@ -120,8 +254,9 @@ function initDropdown(root = document) {
     if (!trigger) return;
     if (active && active.trigger === trigger) closeDropdown();
     else openDropdown(trigger);
-  });
-  document.addEventListener("keydown", (e) => {
+  };
+  document.addEventListener("click", onClick);
+  const onKeyDown2 = (e) => {
     if (e.key !== "ArrowDown") return;
     if (active) return;
     const target = e.target instanceof Element ? e.target : null;
@@ -129,7 +264,15 @@ function initDropdown(root = document) {
     if (!trigger) return;
     e.preventDefault();
     openDropdown(trigger, true);
-  });
+  };
+  document.addEventListener("keydown", onKeyDown2);
+  const destroy = () => {
+    document.removeEventListener("click", onClick);
+    document.removeEventListener("keydown", onKeyDown2);
+    closeDropdown();
+    initialized = false;
+  };
+  return destroy;
 }
 export {
   initDropdown

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 };