@icen.ai/ui 0.5.0 → 0.8.1

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.d.mts

@@ -0,0 +1,4 @@
+/** 为 root 下所有输入类结构初始化（root 自身匹配也算）。幂等。 */
+declare function initInput(root?: ParentNode): void;
+
+export { initInput };

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");
@@ -53,6 +61,8 @@ function setupAutosize(ta) {
   resizeTextarea(ta);
 }
 function setupCounter(field) {
+  const el = field;
+  if (el.__icenCounterInit) return;
   const maxAttr = field.getAttribute("maxlength");
   const dataCount = field.getAttribute("data-count");
   if (!maxAttr && dataCount === null) return;
@@ -72,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}`;
@@ -82,14 +94,19 @@ function setupCounter(field) {
       else if (ratio >= 0.8) counterEl.classList.add("is-warn");
     }
   }
+  ;
   field.addEventListener("input", () => {
-    if (!isComposing) update();
+    if (!isComposing()) update();
   });
   update();
 }
 function setupMask(field) {
+  const el = field;
+  if (el.__icenMaskInit) return;
   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) {
@@ -131,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;
@@ -159,14 +176,10 @@ 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);
-    const nextSlotIdx = maskChars.findIndex((ch, i) => {
-      if (!isInputSlot(ch)) return false;
-      return i >= field.value.length || !isInputSlot(maskChars[Math.min(field.value.length, maskChars.length - 1)]);
-    });
     const nextSlot = maskChars.find((ch, i) => {
       const filledSlots = maskChars.slice(0, i).filter(isInputSlot).length;
       return isInputSlot(ch) && filledSlots >= currentRaw.length;
@@ -178,6 +191,9 @@ function setupMask(field) {
 }
 function setupTrim(field) {
   if (!field.hasAttribute("data-trim")) return;
+  const el = field;
+  if (el.__icenTrimInit) return;
+  el.__icenTrimInit = true;
   field.addEventListener("blur", () => {
     const trimmed = field.value.trim();
     if (trimmed !== field.value) {
@@ -190,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);
@@ -200,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);
@@ -234,16 +251,19 @@ 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.classList.add("is-complete");
+      emitIcen(group, "icen:otp-complete", { code });
       group.dispatchEvent(new CustomEvent("otp:complete", { detail: { code }, bubbles: true }));
     }
   };
   cells.forEach((cell) => cell.addEventListener("input", fireComplete));
 }
-function initInput(root = document) {
+function initInput(root) {
   if (typeof document === "undefined") return;
+  const scope = root ?? document;
   const wraps = [];
-  if (root instanceof Element && root.matches(".input-wrap")) wraps.push(root);
-  wraps.push(...Array.from(root.querySelectorAll(".input-wrap")));
+  if (scope instanceof Element && scope.matches(".input-wrap")) wraps.push(scope);
+  wraps.push(...Array.from(scope.querySelectorAll(".input-wrap")));
   for (const w of wraps) {
     const el = w;
     if (el.__icenInputInit) continue;
@@ -252,37 +272,37 @@ function initInput(root = document) {
     setupPasswordToggle(w);
   }
   const textareas = [];
-  if (root instanceof HTMLTextAreaElement && root.matches("[data-autosize]")) textareas.push(root);
-  textareas.push(...Array.from(root.querySelectorAll("textarea[data-autosize]")));
+  if (scope instanceof HTMLTextAreaElement && scope.matches("[data-autosize]")) textareas.push(scope);
+  textareas.push(...Array.from(scope.querySelectorAll("textarea[data-autosize]")));
   for (const ta of textareas) setupAutosize(ta);
   const countedFields = [];
-  if (root instanceof Element) {
-    const fields = Array.from(root.querySelectorAll(
+  if (scope instanceof Element) {
+    const fields = Array.from(scope.querySelectorAll(
       "input[maxlength], input[data-count], textarea[maxlength], textarea[data-count]"
     ));
     countedFields.push(...fields);
-    if (root instanceof HTMLInputElement || root instanceof HTMLTextAreaElement) {
-      if (root.hasAttribute("maxlength") || root.hasAttribute("data-count")) countedFields.push(root);
+    if (scope instanceof HTMLInputElement || scope instanceof HTMLTextAreaElement) {
+      if (scope.hasAttribute("maxlength") || scope.hasAttribute("data-count")) countedFields.push(scope);
     }
   }
   for (const f of countedFields) setupCounter(f);
   const maskedInputs = [];
-  if (root instanceof Element) {
-    maskedInputs.push(...Array.from(root.querySelectorAll("input[data-mask]")));
-    if (root instanceof HTMLInputElement && root.hasAttribute("data-mask")) maskedInputs.push(root);
+  if (scope instanceof Element) {
+    maskedInputs.push(...Array.from(scope.querySelectorAll("input[data-mask]")));
+    if (scope instanceof HTMLInputElement && scope.hasAttribute("data-mask")) maskedInputs.push(scope);
   }
   for (const inp of maskedInputs) setupMask(inp);
   const trimFields = [];
-  if (root instanceof Element) {
-    trimFields.push(...Array.from(root.querySelectorAll("[data-trim]")));
-    if ((root instanceof HTMLInputElement || root instanceof HTMLTextAreaElement) && root.hasAttribute("data-trim")) {
-      trimFields.push(root);
+  if (scope instanceof Element) {
+    trimFields.push(...Array.from(scope.querySelectorAll("[data-trim]")));
+    if ((scope instanceof HTMLInputElement || scope instanceof HTMLTextAreaElement) && scope.hasAttribute("data-trim")) {
+      trimFields.push(scope);
     }
   }
   for (const f of trimFields) setupTrim(f);
   const otps = [];
-  if (root instanceof Element && root.matches(".otp")) otps.push(root);
-  otps.push(...Array.from(root.querySelectorAll(".otp")));
+  if (scope instanceof Element && scope.matches(".otp")) otps.push(scope);
+  otps.push(...Array.from(scope.querySelectorAll(".otp")));
   for (const g of otps) setupOtp(g);
 }
 export {

package/dist/behaviors/modal.d.mts

@@ -0,0 +1,30 @@
+/** 焦点陷阱的可聚焦元素选择器（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;
+
+export { FOCUSABLE, type ModalOpenOptions, closeModal, initModal, openModal };

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,14 +59,18 @@ 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);
   const backdrop = findBackdrop(id);
-  if (!backdrop) return;
+  if (!backdrop) {
+    console.warn(`[@icen.ai/ui] modal: \u672A\u627E\u5230 data-modal="${id}" \u7684 .modal-backdrop\uFF0C\u5DF2\u8DF3\u8FC7\u6253\u5F00`);
+    return;
+  }
   const panel = backdrop.querySelector(".modal");
   if (!panel) return;
+  applyPanelSizing(panel, readPanelSizing(backdrop));
   portal(backdrop);
   restoreFocusTo = document.activeElement instanceof HTMLElement ? document.activeElement : null;
   openId = id;
@@ -31,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);
     }
   }
@@ -52,7 +104,9 @@ function openModal(id) {
       return;
     }
     if (e.key !== "Tab") return;
-    const els = panel.querySelectorAll(FOCUSABLE);
+    const els = Array.from(panel.querySelectorAll(FOCUSABLE)).filter(
+      (el) => !el.hidden && el.offsetParent !== null
+    );
     if (els.length === 0) {
       e.preventDefault();
       panel.focus();
@@ -71,14 +125,19 @@ 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;
   const backdrop = findBackdrop(id);
-  if (!backdrop) return;
-  backdrop.hidden = true;
+  if (backdrop) backdrop.hidden = true;
   if (openId !== id) return;
   openId = null;
   if (keyHandler) {
@@ -88,13 +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 = document) {
-  if (typeof document === "undefined") return;
-  root.querySelectorAll("[data-modal-open]").forEach((el) => el.setAttribute("aria-haspopup", "dialog"));
-  if (initialized) return;
+function initModal(root) {
+  if (typeof document === "undefined") return () => {
+  };
+  const scope = root ?? document;
+  scope.querySelectorAll("[data-modal-open]").forEach((el) => el.setAttribute("aria-haspopup", "dialog"));
+  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]");
@@ -112,9 +175,17 @@ function initModal(root = document) {
     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

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