@icen.ai/ui 0.8.0 → 0.8.1

package/dist/behaviors/modal.mjs

@@ -1,5 +1,53 @@
+// 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`;
+}
+
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
 // src/behaviors/modal.ts
-var FOCUSABLE = 'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+var 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';
 var openId = null;
 var restoreFocusTo = null;
 var prevBodyOverflow = "";
@@ -11,7 +59,7 @@ function findBackdrop(id) {
 function portal(backdrop) {
   if (backdrop.parentElement !== document.body) document.body.appendChild(backdrop);
 }
-function openModal(id) {
+function openModal(id, opts) {
   if (typeof document === "undefined") return;
   if (openId === id) return;
   if (openId) closeModal(openId);
@@ -22,6 +70,7 @@ function openModal(id) {
   }
   const panel = backdrop.querySelector(".modal");
   if (!panel) return;
+  applyPanelSizing(panel, readPanelSizing(backdrop));
   portal(backdrop);
   restoreFocusTo = document.activeElement instanceof HTMLElement ? document.activeElement : null;
   openId = id;
@@ -34,14 +83,14 @@ function openModal(id) {
   if (!panel.hasAttribute("aria-labelledby")) {
     const title = panel.querySelector(".modal-title");
     if (title) {
-      if (!title.id) title.id = `modal-title-${CSS.escape(id)}`;
+      if (!title.id) title.id = `modal-title-${id.replace(/[^\w-]/g, "-")}`;
       panel.setAttribute("aria-labelledby", title.id);
     }
   }
   if (!panel.hasAttribute("aria-describedby")) {
     const desc = panel.querySelector(".modal-description");
     if (desc) {
-      if (!desc.id) desc.id = `modal-desc-${CSS.escape(id)}`;
+      if (!desc.id) desc.id = `modal-desc-${id.replace(/[^\w-]/g, "-")}`;
       panel.setAttribute("aria-describedby", desc.id);
     }
   }
@@ -76,8 +125,14 @@ function openModal(id) {
     }
   };
   window.addEventListener("keydown", keyHandler);
-  const focusable = panel.querySelector(FOCUSABLE);
-  (focusable ?? panel).focus();
+  if (opts?.initialFocus === "none") {
+  } else if (opts?.initialFocus instanceof HTMLElement) {
+    opts.initialFocus.focus();
+  } else {
+    const focusable = panel.querySelector(FOCUSABLE);
+    (focusable ?? panel).focus();
+  }
+  emitIcen(document, "icen:modal-open", { id });
 }
 function closeModal(id) {
   if (typeof document === "undefined") return;
@@ -92,14 +147,17 @@ function closeModal(id) {
   document.body.style.overflow = prevBodyOverflow;
   if (restoreFocusTo && restoreFocusTo.isConnected) restoreFocusTo.focus();
   restoreFocusTo = null;
+  emitIcen(document, "icen:modal-close", { id });
 }
 function initModal(root) {
-  if (typeof document === "undefined") return;
+  if (typeof document === "undefined") return () => {
+  };
   const scope = root ?? document;
   scope.querySelectorAll("[data-modal-open]").forEach((el) => el.setAttribute("aria-haspopup", "dialog"));
-  if (initialized) return;
+  if (initialized) return () => {
+  };
   initialized = true;
-  document.addEventListener("click", (e) => {
+  const onClick = (e) => {
     const target = e.target instanceof Element ? e.target : null;
     if (!target) return;
     const opener = target.closest("[data-modal-open]");
@@ -117,9 +175,17 @@ function initModal(root) {
     if (target instanceof HTMLElement && target.classList.contains("modal-backdrop") && target.dataset.modal && target.dataset.closeOnOverlay !== "false") {
       closeModal(target.dataset.modal);
     }
-  });
+  };
+  document.addEventListener("click", onClick);
+  const destroy = () => {
+    document.removeEventListener("click", onClick);
+    if (openId) closeModal(openId);
+    initialized = false;
+  };
+  return destroy;
 }
 export {
+  FOCUSABLE,
   closeModal,
   initModal,
   openModal

package/dist/behaviors/nav.d.mts

@@ -1,6 +1,6 @@
 /**
  * 为 root 下每个 .nav[data-scroll-reactive] 初始化（root 自身匹配也算）。
- * 返回销毁函数：移除本次初始化挂上的全部 window scroll/resize 监听。
+ * 返回销毁函数：移除本次初始化挂上的全部 window scroll/resize 与 nav click 监听。
  */
 declare function initNav(root?: ParentNode): () => void;
 

package/dist/behaviors/nav.mjs

@@ -1,8 +1,19 @@
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
 // src/behaviors/nav.ts
 function prefersReducedMotion() {
   if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
   return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
+var NAV_ITEM_SELECTOR = ".nav-btn, .nav-link";
+function isNavItemDisabled(item) {
+  return item.classList.contains("is-disabled") || item.getAttribute("aria-disabled") === "true" || item instanceof HTMLButtonElement && item.disabled;
+}
 function setup(nav) {
   const el = nav;
   if (el.__icenNavInit) return void 0;
@@ -36,17 +47,32 @@ function setup(nav) {
     ticking = true;
     window.requestAnimationFrame(apply);
   };
-  const onResize = () => {
-    if (ticking) return;
-    ticking = true;
-    window.requestAnimationFrame(apply);
-  };
   window.addEventListener("scroll", onScroll, { passive: true });
-  window.addEventListener("resize", onResize, { passive: true });
+  window.addEventListener("resize", onScroll, { passive: true });
   apply();
+  const onSelect = (ev) => {
+    const target = ev.target;
+    if (!(target instanceof Element)) return;
+    const item = target.closest(NAV_ITEM_SELECTOR);
+    if (!item || item.closest(".nav") !== nav) return;
+    if (isNavItemDisabled(item)) return;
+    const items = Array.from(nav.querySelectorAll(NAV_ITEM_SELECTOR));
+    const index = items.indexOf(item);
+    if (index === -1) return;
+    items.forEach((it) => {
+      if (it === item) return;
+      it.classList.remove("is-active");
+      if (it.getAttribute("aria-current") === "page") it.removeAttribute("aria-current");
+    });
+    item.classList.add("is-active");
+    item.setAttribute("aria-current", "page");
+    emitIcen(item, "icen:nav-select", { item, index });
+  };
+  nav.addEventListener("click", onSelect);
   return () => {
     window.removeEventListener("scroll", onScroll);
-    window.removeEventListener("resize", onResize);
+    window.removeEventListener("resize", onScroll);
+    nav.removeEventListener("click", onSelect);
     el.__icenNavInit = false;
   };
 }

package/dist/behaviors/notification.d.mts

@@ -70,7 +70,10 @@ interface NotificationHandle {
     id: string;
     /** 当前 DOM 元素（可能已脱离 DOM） */
     el: HTMLElement;
-    /** 关闭本条 */
+    /**
+     * 关闭本条。设计边界：dismiss 不可拦截（无 before-close 钩子，onClose 只能事后观察）；
+     * 持久化走 localStorage 是当前设计边界（无网络/多端同步，配额或隐私模式受限时静默放弃）。
+     */
     dismiss(): void;
     /** 部分更新（title / description / progress / unread / actions / tag 等） */
     update(patch: NotificationUpdatePatch): void;
@@ -99,6 +102,10 @@ interface NotificationUpdatePatch {
     link?: string;
     linkLabel?: string;
 }
+/**
+ * 通知的内部记录形态，同时是 get(id) / getAll() 的公开返回类型
+ * （导出以便消费方对返回值做类型注解）。
+ */
 interface NotificationRecord {
     id: string;
     title: string;
@@ -129,6 +136,10 @@ interface NotifyFn {
     info(title: string, opts?: NotificationOptions): NotificationHandle | null;
     progress(title: string, opts?: NotificationOptions): NotificationHandle | null;
     confirm(title: string, opts?: NotificationConfirmOptions): Promise<boolean>;
+    /**
+     * 关闭单条（id 缺省 = 全部）。设计边界：dismiss 不可拦截、持久化走 localStorage
+     * 是当前设计边界（详见 NotificationHandle.dismiss）。
+     */
     dismiss(id?: string): void;
     clear(): void;
     markRead(id?: string): void;
@@ -166,7 +177,12 @@ interface NotificationPushInput {
  */
 declare function createNotificationCenter(parent?: ParentNode, opts?: NotificationConfig): NotificationCenterHandle;
 declare const notify: NotifyFn;
-/** 委托初始化：建立默认容器 + 恢复持久化通知。幂等。 */
-declare function initNotification(): void;
+/**
+ * 委托初始化：建立默认容器 + 恢复持久化通知。幂等。
+ * 返回销毁函数：移除本次恢复的持久化通知（连同 DOM 与 store 记录），默认容器已空时
+ * 一并回收，并复位幂等标记（可重新 init）。注意：销毁只回收 init 恢复的内容；
+ * notify() 逐条创建的通知不在回收范围（由宿主自行 dismiss），destroy 后 push 仍可用。
+ */
+declare function initNotification(): () => void;
 
-export { type NotificationAction, type NotificationCenterHandle, type NotificationConfig, type NotificationConfirmOptions, type NotificationHandle, type NotificationKind, type NotificationOptions, type NotificationPushInput, type NotificationUpdatePatch, createNotificationCenter, initNotification, notify };
+export { type NotificationAction, type NotificationCenterHandle, type NotificationConfig, type NotificationConfirmOptions, type NotificationHandle, type NotificationKind, type NotificationOptions, type NotificationPushInput, type NotificationRecord, type NotificationUpdatePatch, createNotificationCenter, initNotification, notify };

package/dist/behaviors/notification.mjs

@@ -240,7 +240,7 @@ function buildDescription(text) {
   el.textContent = text;
   return el;
 }
-function buildActions(record, getHandle) {
+function buildActions(record) {
   const actions = record.opts.actions?.length ? record.opts.actions : record.opts.actionLabel ? [{ label: record.opts.actionLabel, onClick: record.opts.onAction }] : null;
   if (!actions || actions.length === 0) return null;
   const wrap = document.createElement("div");
@@ -254,13 +254,11 @@ function buildActions(record, getHandle) {
     btn.textContent = a.label;
     btn.addEventListener("click", (ev) => {
       ev.stopPropagation();
-      const h = getHandle();
       if (a.onClick) {
         const ret = a.onClick();
         if (ret === false) return;
       }
       if (!a.keepOpen) dismissRecord(record.id);
-      else void h;
     });
     wrap.appendChild(btn);
   }
@@ -379,7 +377,7 @@ function renderNotification(record, container, getHandle) {
   content.className = "notification-content";
   content.appendChild(buildTitle(record.title));
   if (record.opts.description) content.appendChild(buildDescription(record.opts.description));
-  const actions = buildActions(record, getHandle);
+  const actions = buildActions(record);
   if (actions) content.appendChild(actions);
   const link = buildLink(record);
   if (link) content.appendChild(link);
@@ -415,6 +413,7 @@ function pushToContainer(container, el, priority) {
     container.appendChild(el);
   }
 }
+var LEAVE_FALLBACK_MS = 360;
 function removeOne(el, onClose) {
   if (el.classList.contains("is-leaving")) return;
   el.classList.add("is-leaving");
@@ -426,23 +425,23 @@ function removeOne(el, onClose) {
     onClose?.();
   };
   el.addEventListener("transitionend", finish, { once: true });
-  window.setTimeout(finish, 360);
+  window.setTimeout(finish, LEAVE_FALLBACK_MS);
 }
-function trimStack(container) {
+function trimStack(container, maxStack, remove) {
   for (; ; ) {
     const items = Array.from(container.querySelectorAll(":scope > .notification"));
-    if (items.length <= cfg.maxStack) return;
+    if (items.length <= maxStack) return;
     const target = items.find((it) => !it.classList.contains("is-priority")) ?? items[0];
     if (!target) return;
     const rec = target.id ? store.get(target.id) : void 0;
     if (rec?.timer) window.clearTimeout(rec.timer);
     if (target.classList.contains("is-leaving")) {
       target.remove();
-      if (target.id) store.delete(target.id);
+      if (target.id) remove(target.id);
       continue;
     }
     removeOne(target);
-    if (target.id) store.delete(target.id);
+    if (target.id) remove(target.id);
     return;
   }
 }
@@ -516,38 +515,49 @@ function makeHandle(record) {
   };
   return handle;
 }
-function showRecord(title, kind, opts) {
-  if (!isBrowser()) return null;
-  const container = ensureContainer();
+function pushRecord(title, kind, opts, container, maxStack, cfgRef, ownerStore) {
   const id = opts.id ?? genId();
-  if (store.has(id)) dismissRecord(id);
   const duration = opts.duration ?? 0;
   const record = {
     id,
     title,
     kind,
-    opts: { unread: opts.unread ?? false, ...opts, id },
+    // 默认值放展开前会被显式传入的 { unread: undefined } 覆盖回 undefined，故先展开再兜底
+    opts: { ...opts, unread: opts.unread ?? false, id },
     el: null,
     createdAt: Date.now(),
     duration,
     remaining: duration,
     paused: false,
     timer: 0,
-    startedAt: 0
+    startedAt: 0,
+    cfgRef,
+    ownerStore
   };
   const handle = makeHandle(record);
   const el = renderNotification(record, container, () => handle);
   record.el = el;
   handle.el = el;
   pushToContainer(container, el, record.opts.priority ?? "normal");
+  ownerStore?.set(id, record);
   store.set(id, record);
   attachTimer(record, handle);
-  trimStack(container);
+  trimStack(container, maxStack, (removedId) => {
+    ownerStore?.delete(removedId);
+    store.delete(removedId);
+  });
   persistSave();
-  playSound(record.cfgRef?.sound ?? cfg.sound);
+  playSound(cfgRef?.sound ?? cfg.sound);
   opts.onShow?.(handle);
   return handle;
 }
+function showRecord(title, kind, opts) {
+  if (!isBrowser()) return null;
+  const container = ensureContainer();
+  const id = opts.id ?? genId();
+  if (store.has(id)) dismissRecord(id);
+  return pushRecord(title, kind, opts, container, cfg.maxStack);
+}
 function dismissRecord(id) {
   const record = store.get(id);
   if (!record) {
@@ -696,6 +706,7 @@ function createNotificationCenter(parent, opts = {}) {
       getAll: () => [],
       config() {
       },
+      // SSR 桩：非真实元素，destroy 前不得触碰 el（本分支内其余方法均为 no-op）
       el: {}
     };
   }
@@ -726,60 +737,15 @@ function createNotificationCenter(parent, opts = {}) {
   }
   function push(input) {
     if (destroyed) return null;
-    const kind = input.kind ?? "info";
-    const opts2 = input.options ?? {};
-    const id = opts2.id ?? genId();
-    const duration = opts2.duration ?? 0;
-    const record = {
-      id,
-      title: input.title,
-      kind,
-      opts: { unread: opts2.unread ?? false, ...opts2, id },
-      el: null,
-      createdAt: Date.now(),
-      duration,
-      remaining: duration,
-      paused: false,
-      timer: 0,
-      startedAt: 0,
-      cfgRef: local,
-      ownerStore: localStore
-    };
-    const handle = makeHandle(record);
-    const el = renderNotification(record, container, () => handle);
-    record.el = el;
-    handle.el = el;
-    pushToContainer(container, el, record.opts.priority ?? "normal");
-    localStore.set(id, record);
-    store.set(id, record);
-    attachTimer(record, handle);
-    for (; ; ) {
-      const items = Array.from(container.querySelectorAll(":scope > .notification"));
-      if (items.length <= local.maxStack) break;
-      const target = items.find((it) => !it.classList.contains("is-priority")) ?? items[0];
-      if (!target) break;
-      const tid = target.id;
-      const rec = tid ? localStore.get(tid) : void 0;
-      if (rec?.timer) window.clearTimeout(rec.timer);
-      if (target.classList.contains("is-leaving")) {
-        target.remove();
-        if (tid) {
-          localStore.delete(tid);
-          store.delete(tid);
-        }
-        continue;
-      }
-      removeOne(target);
-      if (tid) {
-        localStore.delete(tid);
-        store.delete(tid);
-      }
-      break;
-    }
-    persistSave();
-    playSound(local.sound);
-    opts2.onShow?.(handle);
-    return handle;
+    return pushRecord(
+      input.title,
+      input.kind ?? "info",
+      input.options ?? {},
+      container,
+      local.maxStack,
+      local,
+      localStore
+    );
   }
   function dismiss(id) {
     if (id) {
@@ -889,17 +855,31 @@ var notify = Object.assign(
   }
 );
 function initNotification() {
-  if (!isBrowser()) return;
-  if (globalInit.done) return;
+  if (!isBrowser()) return () => {
+  };
+  if (globalInit.done) return () => {
+  };
   globalInit.done = true;
   const container = ensureContainer();
   const key = persistKeyFor(cfg.persist);
+  const restored = [];
   if (key) {
     knownPersistKeys.add(key);
     for (const r of restorePersisted(container, key)) {
       store.set(r.id, r);
+      restored.push(r);
     }
   }
+  return () => {
+    for (const r of restored) {
+      if (r.timer) window.clearTimeout(r.timer);
+      store.delete(r.id);
+      r.el?.remove();
+    }
+    restored.length = 0;
+    if (container.childElementCount === 0) container.remove();
+    globalInit.done = false;
+  };
 }
 export {
   createNotificationCenter,

package/dist/behaviors/popover.d.mts

@@ -1,3 +1,4 @@
+/** 布局锚矩形（视口坐标，宽高齐全，元素锚或手工锚共用此形状）。 */
 interface PopoverRect {
     left: number;
     top: number;
@@ -6,11 +7,14 @@ interface PopoverRect {
     width: number;
     height: number;
 }
+/** 视口尺寸（可用空间计算的基准）。 */
 interface PopoverViewport {
     width: number;
     height: number;
 }
-type PopoverSide = 'top' | 'bottom';
+/** 浮层相对锚的展开侧。 */
+type PopoverSide = 'top' | 'bottom' | 'left' | 'right';
+/** 浮层与锚的对齐方式（stretch = 纵向侧时随锚宽拉伸）。 */
 type PopoverAlign = 'start' | 'center' | 'end' | 'stretch';
 interface PopoverLayoutOptions {
     side?: PopoverSide;
@@ -24,6 +28,33 @@ interface PopoverLayoutOptions {
     /** 内容预期高度：避免用被裁剪的实测高度参与选侧 */
     contentHeightHint?: number;
 }
+interface PanelSizing {
+    /** 固定宽（最高优先，跳过 min/max 夹取） */
+    width?: number;
+    /** 最小宽（默认 = 锚点/trigger 宽或组件 CSS 默认） */
+    minWidth?: number;
+    /** 最大宽 */
+    maxWidth?: number;
+    /** 最小高（与 PopoverLayoutOptions.minHeight 对齐） */
+    minHeight?: number;
+    /** 高度上限 */
+    maxHeight?: number;
+}
+/** 从元素读取 data-panel-* 尺寸属性（非法/缺失字段跳过，不抛异常）。 */
+declare function readPanelSizing(el: Element | null | undefined): PanelSizing;
+/** 合并尺寸：程序面 overrides 优先于属性面（undefined 字段不覆盖）。 */
+declare function resolvePanelSizing(el: Element | null | undefined, overrides?: PanelSizing | null): PanelSizing;
+/** 把 PanelSizing 折算进布局 opts：固定宽 → min=max；否则 min/max 夹取；maxHeight 透传。 */
+declare function sizingToLayout<T extends {
+    minWidth?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+}>(sizing: PanelSizing, opts: T): T;
+/** 把尺寸契约内联到自建面板（dropdown / context-menu / date-picker 等 fixed 面板）。
+ *  传 null 复位全部内联尺寸——单例面板跨实例复用时防「上次的设置串味」。
+ *  视口守卫：width / maxWidth 一律夹到 视口宽 − 24px（窄屏上过大的 data-panel-width 不溢出，
+ *  与 computePopoverLayout 的 availableWidth 同一纪律，不再两套标准）。 */
+declare function applyPanelSizing(panel: HTMLElement, sizing: PanelSizing | null): void;
 interface PopoverLayout {
     side: PopoverSide;
     left: number;
@@ -33,14 +64,19 @@ interface PopoverLayout {
 }
 interface OpenPopoverOptions extends PopoverLayoutOptions {
     anchor: Element | PopoverRect;
+    /** 统一面板尺寸契约（优先于面板元素的 data-panel-* 与上方直接尺寸字段） */
+    sizing?: PanelSizing;
     /** 关闭（含外点/Esc 触发的关闭）后的回调 */
     onClose?: () => void;
 }
-/** 视口智能布局：返回 {side, left, top, width, maxHeight}。 */
+/** 视口智能布局：返回 {side, left, top, width, maxHeight}。
+ *  纵向侧（top/bottom）：选侧按上下空间，宽按 min/max 夹取，高按内容预期。
+ *  横向侧（left/right）：锚点左右翻转，宽取 min（无内容测量，横向侧取下限），
+ *  高占满可用空间，纵向按 align（start/center/end；stretch 视作 start）贴锚。 */
 declare function computePopoverLayout(anchor: PopoverRect, viewport: PopoverViewport, opts?: PopoverLayoutOptions): PopoverLayout;
 /** 打开浮层：panel 移入 body 并按 anchor 布局；重复调用同一 panel 为先关后开。 */
 declare function openPopover(panel: HTMLElement, options: OpenPopoverOptions): void;
 /** 关闭浮层：移除监听并把 panel 还原到打开前的位置与 hidden 状态。 */
 declare function closePopover(panel: HTMLElement): void;
 
-export { type OpenPopoverOptions, type PopoverAlign, type PopoverLayout, type PopoverLayoutOptions, type PopoverRect, type PopoverSide, type PopoverViewport, closePopover, computePopoverLayout, openPopover };
+export { type OpenPopoverOptions, type PanelSizing, type PopoverAlign, type PopoverLayout, type PopoverLayoutOptions, type PopoverRect, type PopoverSide, type PopoverViewport, applyPanelSizing, closePopover, computePopoverLayout, openPopover, readPanelSizing, resolvePanelSizing, sizingToLayout };