@icen.ai/ui 0.8.0 → 0.9.0

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

package/dist/behaviors/popover.mjs

@@ -1,4 +1,63 @@
 // 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 resolvePanelSizing(el, overrides) {
+  const base = readPanelSizing(el);
+  if (!overrides) return base;
+  for (const key of Object.keys(overrides)) {
+    const v = overrides[key];
+    if (typeof v === "number" && Number.isFinite(v) && v > 0) base[key] = v;
+  }
+  return base;
+}
+function sizingToLayout(sizing, opts) {
+  const out = { ...opts };
+  if (sizing.minWidth != null) out.minWidth = sizing.minWidth;
+  if (sizing.maxWidth != null) out.maxWidth = sizing.maxWidth;
+  if (sizing.width != null) {
+    out.minWidth = sizing.width;
+    out.maxWidth = sizing.width;
+  }
+  if (sizing.maxHeight != null) out.maxHeight = sizing.maxHeight;
+  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;
@@ -23,13 +82,35 @@ function horizontalAnchor(anchor, width, align) {
 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 preferredSide = opts.side ?? "top";
-  const align = opts.align ?? "start";
   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);
@@ -107,7 +188,8 @@ function onKeyDown(e) {
 function openPopover(panel, options) {
   if (typeof document === "undefined") return;
   if (openPanels.has(panel)) closePopover(panel);
-  const { anchor, onClose, ...layoutOpts } = options;
+  const { anchor, onClose, sizing, ...rest } = options;
+  const layoutOpts = sizingToLayout(resolvePanelSizing(panel, sizing), rest);
   const placeholder = document.createComment("popover-anchor");
   panel.parentNode?.insertBefore(placeholder, panel);
   const wasHidden = panel.hidden;
@@ -159,7 +241,11 @@ function closePopover(panel) {
   state.onClose?.();
 }
 export {
+  applyPanelSizing,
   closePopover,
   computePopoverLayout,
-  openPopover
+  openPopover,
+  readPanelSizing,
+  resolvePanelSizing,
+  sizingToLayout
 };

package/dist/behaviors/select.d.mts

@@ -1,4 +1,6 @@
-/** 为 root 下每个 [data-select] 容器初始化（root 自身是 [data-select] 也算）。 */
-declare function initSelect(root?: ParentNode): void;
+/** 为 root 下每个 [data-select] 容器初始化（root 自身是 [data-select] 也算）。
+ *  返回销毁函数：摘除本次初始化容器的全部监听并复位幂等标记（可重新 init）；
+ *  最后一个容器销毁时同时摘除 document 级单例委托。 */
+declare function initSelect(root?: ParentNode): () => void;
 
 export { initSelect };