@icen.ai/ui 0.8.0 → 0.8.1

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

package/dist/behaviors/select.mjs

@@ -1,4 +1,31 @@
 // 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;
+}
 var DEFAULT_MIN_WIDTH = 220;
 var DEFAULT_MAX_WIDTH = 420;
 var DEFAULT_MIN_HEIGHT = 120;
@@ -23,13 +50,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);
@@ -53,6 +102,13 @@ function computePopoverLayout(anchor, viewport, opts = {}) {
   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/select.ts
 var openSelect = null;
 var globalBound = false;
@@ -98,18 +154,33 @@ function unbindOpenListeners() {
 }
 function setup(container) {
   const el = container;
-  if (el.__icenSelectInit) return;
-  el.__icenSelectInit = true;
+  if (el.__icenSelectInit) return () => {
+  };
+  const ac = new AbortController();
+  const on = (t, ev, fn) => {
+    const listener = (evt) => fn(evt);
+    t.addEventListener(ev, listener, { signal: ac.signal });
+  };
   const triggerEl = container.querySelector(".select-trigger");
   const panelEl = container.querySelector(".select-panel");
   const valueEl = container.querySelector(".select-value");
   const hiddenInput = container.querySelector("input[data-select-value]");
-  if (!triggerEl || !panelEl) return;
+  if (!triggerEl || !panelEl) return () => {
+  };
+  el.__icenSelectInit = true;
   const trigger = triggerEl;
   const panel = panelEl;
   const isMultiple = container.hasAttribute("data-select-multiple");
   const isSearchable = container.hasAttribute("data-select-search");
   const maxSelect = Number(container.getAttribute("data-select-max")) || 0;
+  const panelSizing = resolvePanelSizing(container);
+  function resolvedPanelWidth(triggerWidth) {
+    let w = triggerWidth;
+    if (panelSizing.minWidth != null) w = Math.max(w, panelSizing.minWidth);
+    if (panelSizing.maxWidth != null) w = Math.min(w, panelSizing.maxWidth);
+    if (panelSizing.width != null) w = panelSizing.width;
+    return w;
+  }
   const placeholder = container.getAttribute("data-select-placeholder") ?? (valueEl?.classList.contains("is-empty") ? valueEl?.textContent ?? "" : "");
   if (isMultiple) panel.setAttribute("data-select-multiple", "");
   let searchInput = null;
@@ -177,8 +248,8 @@ function setup(container) {
     setFocus(firstEnabled());
   }
   if (searchInput) {
-    searchInput.addEventListener("input", () => filterOptions(searchInput.value));
-    searchInput.addEventListener("keydown", (ev) => {
+    on(searchInput, "input", () => filterOptions(searchInput.value));
+    on(searchInput, "keydown", (ev) => {
       if (ev.key === "Escape") {
         ev.stopPropagation();
         searchInput.value = "";
@@ -189,6 +260,7 @@ function setup(container) {
   }
   function positionPanel() {
     const rect = trigger.getBoundingClientRect();
+    const panelWidth = resolvedPanelWidth(rect.width);
     const layout = computePopoverLayout(
       rect,
       { width: window.innerWidth, height: window.innerHeight },
@@ -196,9 +268,9 @@ function setup(container) {
         side: "bottom",
         align: "stretch",
         offset: PANEL_OFFSET,
-        minWidth: rect.width,
-        maxWidth: rect.width,
-        maxHeight: PANEL_MAX_HEIGHT
+        minWidth: panelWidth,
+        maxWidth: panelWidth,
+        maxHeight: panelSizing.maxHeight ?? PANEL_MAX_HEIGHT
       }
     );
     panel.style.left = `${layout.left + window.scrollX}px`;
@@ -242,19 +314,59 @@ function setup(container) {
   function updateMultiTrigger() {
     if (!valueEl) return;
     const selected = allOptions().filter((o) => o.classList.contains("is-selected"));
+    let chipsEl = trigger.querySelector(".select-chips");
     if (selected.length === 0) {
       valueEl.textContent = placeholder;
       valueEl.classList.add("is-empty");
+      valueEl.hidden = false;
+      if (chipsEl) chipsEl.hidden = true;
       container.removeAttribute("data-value");
     } else {
       valueEl.classList.remove("is-empty");
-      const maxLabel = Number(container.getAttribute("data-select-max-label")) || 2;
-      if (selected.length <= maxLabel) {
-        valueEl.textContent = selected.map((o) => o.textContent ?? "").join("\u3001");
-      } else {
-        valueEl.textContent = `\u5DF2\u9009 ${selected.length} \u9879`;
+      valueEl.hidden = true;
+      if (!chipsEl) {
+        chipsEl = document.createElement("span");
+        chipsEl.className = "select-chips";
+        valueEl.insertAdjacentElement("afterend", chipsEl);
+      }
+      chipsEl.hidden = false;
+      chipsEl.textContent = "";
+      const maxLabel = Number(container.getAttribute("data-select-max-label")) || 3;
+      const shown = selected.slice(0, maxLabel);
+      const rest = selected.length - shown.length;
+      for (const o of shown) {
+        const label = o.textContent ?? "";
+        const chip = document.createElement("span");
+        chip.className = "select-chip";
+        const lb = document.createElement("span");
+        lb.textContent = label;
+        chip.appendChild(lb);
+        const x = document.createElement("span");
+        x.className = "select-chip-x";
+        x.setAttribute("role", "button");
+        x.setAttribute("tabindex", "-1");
+        x.setAttribute("aria-label", `\u79FB\u9664 ${label}`);
+        x.textContent = "\xD7";
+        on(x, "pointerdown", (ev) => ev.stopPropagation());
+        on(x, "click", (ev) => {
+          ev.stopPropagation();
+          ev.preventDefault();
+          o.classList.remove("is-selected");
+          updateMultiTrigger();
+          syncHiddenInput();
+        });
+        chip.appendChild(x);
+        chipsEl.appendChild(chip);
       }
+      if (rest > 0) {
+        const more = document.createElement("span");
+        more.className = "select-chip select-chip--more";
+        more.textContent = `+${rest}`;
+        chipsEl.appendChild(more);
+      }
+      container.setAttribute("data-value", getSelectedValues().join(","));
     }
+    if (clearBtn) clearBtn.hidden = selected.length === 0;
     if (maxSelect > 0) {
       const atMax = selected.length >= maxSelect;
       allOptions().forEach((o) => {
@@ -265,8 +377,10 @@ function setup(container) {
     }
   }
   function syncHiddenInput() {
-    if (!hiddenInput) return;
     const values = getSelectedValues();
+    const label = allOptions().filter((o) => o.classList.contains("is-selected")).map((o) => (o.textContent ?? "").trim()).join(", ");
+    emitIcen(container, "icen:select-change", { value: values[0] ?? "", values, label });
+    if (!hiddenInput) return;
     hiddenInput.value = isMultiple ? values.join(",") : values[0] ?? "";
     hiddenInput.dispatchEvent(new Event("change", { bubbles: true }));
   }
@@ -297,16 +411,16 @@ function setup(container) {
   }
   const clearBtn = container.querySelector(".select-clear");
   if (clearBtn && isMultiple) {
-    clearBtn.addEventListener("click", (ev) => {
+    on(clearBtn, "click", (ev) => {
       ev.stopPropagation();
       allOptions().forEach((o) => o.classList.remove("is-selected"));
       updateMultiTrigger();
       syncHiddenInput();
     });
-    clearBtn.addEventListener("pointerdown", (ev) => ev.stopPropagation());
+    on(clearBtn, "pointerdown", (ev) => ev.stopPropagation());
   }
-  trigger.addEventListener("click", () => isOpen() ? closePanel() : openPanel());
-  trigger.addEventListener("keydown", (ev) => {
+  on(trigger, "click", () => isOpen() ? closePanel() : openPanel());
+  on(trigger, "keydown", (ev) => {
     if (!isOpen()) {
       if (ev.key === "ArrowDown" || ev.key === "ArrowUp" || ev.key === "Enter" || ev.key === " ") {
         ev.preventDefault();
@@ -336,13 +450,13 @@ function setup(container) {
         break;
     }
   });
-  panel.addEventListener("click", (ev) => {
+  on(panel, "click", (ev) => {
     const t = ev.target;
     if (!(t instanceof Element)) return;
     const opt = t.closest(".select-option");
     if (opt instanceof HTMLButtonElement && panel.contains(opt)) choose(opt);
   });
-  panel.addEventListener("mouseover", (ev) => {
+  on(panel, "mouseover", (ev) => {
     const t = ev.target;
     if (!(t instanceof Element)) return;
     const opt = t.closest(".select-option");
@@ -351,15 +465,38 @@ function setup(container) {
     if (idx >= 0 && !opt.classList.contains("is-disabled")) setFocus(idx);
   });
   if (isMultiple) updateMultiTrigger();
+  return () => {
+    if (openSelect?.panel === panel) closePanel();
+    ac.abort();
+    el.__icenSelectInit = false;
+  };
 }
+var activeSetups = /* @__PURE__ */ new Set();
 function initSelect(root) {
-  if (typeof document === "undefined") return;
+  if (typeof document === "undefined") return () => {
+  };
   const scope = root ?? document;
   bindGlobalListeners();
   const containers = [];
   if (scope instanceof Element && scope.matches("[data-select]")) containers.push(scope);
   containers.push(...Array.from(scope.querySelectorAll("[data-select]")));
-  for (const c of containers) setup(c);
+  const disposers = [];
+  for (const c of containers) {
+    const dispose = setup(c);
+    activeSetups.add(dispose);
+    disposers.push(dispose);
+  }
+  return () => {
+    for (const d of disposers) {
+      d();
+      activeSetups.delete(d);
+    }
+    if (activeSetups.size === 0 && globalBound) {
+      document.removeEventListener("pointerdown", onGlobalPointerDown);
+      document.removeEventListener("keydown", onGlobalKeyDown);
+      globalBound = false;
+    }
+  };
 }
 export {
   initSelect

package/dist/behaviors/sidebar.d.mts

@@ -1,4 +1,7 @@
-/** 为 root 下每个 .sidebar 初始化（root 自身是 .sidebar 也算）。 */
-declare function initSidebar(root?: ParentNode): void;
+/**
+ * 为 root 下每个 .sidebar 初始化（root 自身是 .sidebar 也算）。
+ * 返回销毁函数：移除本次挂上的容器监听并复位幂等标记（销毁后可重新 init）。SSR 下返回 no-op。
+ */
+declare function initSidebar(root?: ParentNode): () => void;
 
 export { initSidebar };

package/dist/behaviors/sidebar.mjs

@@ -1,7 +1,14 @@
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
 // src/behaviors/sidebar.ts
 function setup(sidebar) {
   const el = sidebar;
-  if (el.__icenSidebarInit) return;
+  if (el.__icenSidebarInit) return void 0;
   el.__icenSidebarInit = true;
   sidebar.querySelectorAll(".sidebar-group-title").forEach((title) => {
     const group = title.closest(".sidebar-group");
@@ -11,9 +18,21 @@ function setup(sidebar) {
       title.setAttribute("aria-controls", panel.id);
     }
   });
-  el.addEventListener("click", (ev) => {
+  sidebar.querySelectorAll("[data-sidebar-collapse]").forEach((btn) => {
+    if (!btn.hasAttribute("aria-expanded")) {
+      btn.setAttribute("aria-expanded", String(!sidebar.classList.contains("sidebar--collapsed")));
+    }
+  });
+  const onClick = (ev) => {
     const target = ev.target;
     if (!(target instanceof Element)) return;
+    const collapseBtn = target.closest("[data-sidebar-collapse]");
+    if (collapseBtn && collapseBtn.closest(".sidebar") === el) {
+      const collapsed = el.classList.toggle("sidebar--collapsed");
+      collapseBtn.setAttribute("aria-expanded", String(!collapsed));
+      emitIcen(el, "icen:sidebar-collapse", { collapsed });
+      return;
+    }
     const title = target.closest(".sidebar-group-title");
     if (!(title instanceof HTMLElement)) return;
     if (title.closest(".sidebar") !== el) return;
@@ -21,19 +40,30 @@ function setup(sidebar) {
     if (!group) return;
     const open = group.classList.toggle("is-open");
     title.setAttribute("aria-expanded", String(open));
-    sidebar.dispatchEvent(new CustomEvent("icen:sidebar-toggle", {
-      bubbles: true,
-      detail: { group, open }
-    }));
-  });
+    emitIcen(sidebar, "icen:sidebar-toggle", { group, open });
+  };
+  el.addEventListener("click", onClick);
+  return () => {
+    el.removeEventListener("click", onClick);
+    el.__icenSidebarInit = false;
+  };
 }
 function initSidebar(root) {
-  if (typeof document === "undefined") return;
-  const scope = root ?? document;
-  const sidebars = [];
-  if (scope instanceof Element && scope.matches(".sidebar")) sidebars.push(scope);
-  sidebars.push(...Array.from(scope.querySelectorAll(".sidebar")));
-  for (const s of sidebars) setup(s);
+  const cleanups = [];
+  if (typeof document !== "undefined") {
+    const scope = root ?? document;
+    const sidebars = [];
+    if (scope instanceof Element && scope.matches(".sidebar")) sidebars.push(scope);
+    sidebars.push(...Array.from(scope.querySelectorAll(".sidebar")));
+    for (const s of sidebars) {
+      const cleanup = setup(s);
+      if (cleanup) cleanups.push(cleanup);
+    }
+  }
+  return () => {
+    for (const fn of cleanups) fn();
+    cleanups.length = 0;
+  };
 }
 export {
   initSidebar

package/dist/behaviors/slider.d.mts

@@ -1,4 +1,7 @@
-/** 为 root 下每个 .slider 容器初始化（root 自身是 .slider 也算）。 */
-declare function initSlider(root?: ParentNode): void;
+/**
+ * 为 root 下每个 .slider 容器初始化（root 自身是 .slider 也算）。
+ * 返回销毁函数：移除本次挂上的全部监听并复位幂等标记（销毁后可重新 init）。SSR 下返回 no-op。
+ */
+declare function initSlider(root?: ParentNode): () => void;
 
 export { initSlider };

package/dist/behaviors/slider.mjs

@@ -1,4 +1,15 @@
+// src/behaviors/events.ts
+function emitIcen(source, type, detail) {
+  return source.dispatchEvent(
+    new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true })
+  );
+}
+
 // src/behaviors/slider.ts
+function bind(target, type, fn, bag) {
+  target.addEventListener(type, fn);
+  bag.push(() => target.removeEventListener(type, fn));
+}
 function pct(input) {
   const min = Number(input.min || "0");
   const max = Number(input.max || "100");
@@ -6,7 +17,7 @@ function pct(input) {
   if (range <= 0) return 0;
   return (Number(input.value) - min) / range * 100;
 }
-function setupSingle(slider, native) {
+function setupSingle(slider, native, bag) {
   const fill = slider.querySelector(".slider-fill");
   const thumb = slider.querySelector(".slider-thumb");
   const sync = () => {
@@ -14,22 +25,16 @@ function setupSingle(slider, native) {
     if (fill) fill.style.width = `${p}%`;
     if (thumb) thumb.style.left = `calc(${p}% - 8px)`;
   };
-  native.addEventListener("input", () => {
+  bind(native, "input", () => {
     sync();
-    slider.dispatchEvent(new CustomEvent("icen:slider-input", {
-      bubbles: true,
-      detail: { value: Number(native.value) }
-    }));
-  });
-  native.addEventListener("change", () => {
-    slider.dispatchEvent(new CustomEvent("icen:slider-change", {
-      bubbles: true,
-      detail: { value: Number(native.value) }
-    }));
-  });
+    emitIcen(slider, "icen:slider-input", { value: Number(native.value) });
+  }, bag);
+  bind(native, "change", () => {
+    emitIcen(slider, "icen:slider-change", { value: Number(native.value) });
+  }, bag);
   sync();
 }
-function setupDual(slider, natives) {
+function setupDual(slider, natives, bag) {
   const lo = natives.find((n) => n.getAttribute("data-thumb") === "lo") ?? natives[0];
   const hi = natives.find((n) => n.getAttribute("data-thumb") === "hi") ?? natives[1];
   if (!lo || !hi || lo === hi) return;
@@ -59,46 +64,52 @@ function setupDual(slider, natives) {
     lo.style.clipPath = `inset(0 ${100 - pLo}% 0 0)`;
     hi.style.clipPath = `inset(0 0 0 ${pHi}%)`;
   };
-  lo.addEventListener("input", () => {
+  bind(lo, "input", () => {
     sync(lo);
-    slider.dispatchEvent(new CustomEvent("icen:slider-input", {
-      bubbles: true,
-      detail: { lo: Number(lo.value), hi: Number(hi.value) }
-    }));
-  });
-  hi.addEventListener("input", () => {
+    emitIcen(slider, "icen:slider-input", { lo: Number(lo.value), hi: Number(hi.value) });
+  }, bag);
+  bind(hi, "input", () => {
     sync(hi);
-    slider.dispatchEvent(new CustomEvent("icen:slider-input", {
-      bubbles: true,
-      detail: { lo: Number(lo.value), hi: Number(hi.value) }
-    }));
-  });
+    emitIcen(slider, "icen:slider-input", { lo: Number(lo.value), hi: Number(hi.value) });
+  }, bag);
   const onChange = () => {
-    slider.dispatchEvent(new CustomEvent("icen:slider-change", {
-      bubbles: true,
-      detail: { lo: Number(lo.value), hi: Number(hi.value) }
-    }));
+    emitIcen(slider, "icen:slider-change", { lo: Number(lo.value), hi: Number(hi.value) });
   };
-  lo.addEventListener("change", onChange);
-  hi.addEventListener("change", onChange);
+  bind(lo, "change", onChange, bag);
+  bind(hi, "change", onChange, bag);
   sync(null);
 }
 function setup(slider) {
   const el = slider;
-  if (el.__icenSliderInit) return;
-  el.__icenSliderInit = true;
+  if (el.__icenSliderInit) return void 0;
   const natives = Array.from(slider.querySelectorAll(".slider-native"));
-  if (natives.length === 0) return;
-  if (slider.classList.contains("slider--dual")) setupDual(slider, natives);
-  else setupSingle(slider, natives[0]);
+  if (natives.length === 0) return void 0;
+  el.__icenSliderInit = true;
+  const bag = [];
+  if (slider.classList.contains("slider--dual")) setupDual(slider, natives, bag);
+  else setupSingle(slider, natives[0], bag);
+  return () => {
+    for (const off of bag) off();
+    bag.length = 0;
+    el.__icenSliderInit = false;
+  };
 }
 function initSlider(root) {
-  if (typeof document === "undefined") return;
-  const scope = root ?? document;
-  const containers = [];
-  if (scope instanceof Element && scope.matches(".slider")) containers.push(scope);
-  containers.push(...Array.from(scope.querySelectorAll(".slider")));
-  for (const c of containers) setup(c);
+  const cleanups = [];
+  if (typeof document !== "undefined") {
+    const scope = root ?? document;
+    const containers = [];
+    if (scope instanceof Element && scope.matches(".slider")) containers.push(scope);
+    containers.push(...Array.from(scope.querySelectorAll(".slider")));
+    for (const c of containers) {
+      const cleanup = setup(c);
+      if (cleanup) cleanups.push(cleanup);
+    }
+  }
+  return () => {
+    for (const fn of cleanups) fn();
+    cleanups.length = 0;
+  };
 }
 export {
   initSlider