@icen.ai/ui 0.5.0 → 0.8.1

package/dist/behaviors/datatable.mjs

@@ -1,10 +1,151 @@
+// 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 applyPanelSizing(panel2, sizing) {
+  if (sizing == null) {
+    panel2.style.width = "";
+    panel2.style.minWidth = "";
+    panel2.style.maxWidth = "";
+    panel2.style.minHeight = "";
+    panel2.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);
+    panel2.style.width = `${w}px`;
+    panel2.style.maxWidth = `${w}px`;
+  }
+  if (sizing.minWidth != null) panel2.style.minWidth = `${fitW(sizing.minWidth)}px`;
+  if (sizing.maxWidth != null && sizing.width == null) panel2.style.maxWidth = `${fitW(sizing.maxWidth)}px`;
+  if (sizing.minHeight != null) panel2.style.minHeight = `${sizing.minHeight}px`;
+  if (sizing.maxHeight != null) panel2.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
 var FLIP_MARGIN = 10;
 var CLAMP_MARGIN = 8;
+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)
+  });
+}
 var panel = null;
 var focusableItems = [];
 var focusedIndex = -1;
-function buildItem(item) {
+function buildItem(item, menuPanel) {
   if ("type" in item && item.type === "separator") {
     const sep = document.createElement("div");
     sep.className = "menu-separator";
@@ -54,19 +195,21 @@ function buildItem(item) {
     btn.appendChild(shortcut);
   }
   btn.addEventListener("click", () => {
+    emitMenuSelect(menuPanel, btn);
     entry.onClick?.();
-    closeMenu();
+    closeContextMenu();
   });
   return btn;
 }
-function openContextMenu(x, y, items) {
+function openContextMenu(x, y, items, opts) {
   if (typeof document === "undefined") return;
-  closeMenu();
+  closeContextMenu();
   panel = document.createElement("div");
   panel.className = "menu menu--context";
   panel.setAttribute("role", "menu");
   panel.style.visibility = "hidden";
-  for (const item of items) panel.appendChild(buildItem(item));
+  applyPanelSizing(panel, opts?.sizing ?? {});
+  for (const item of items) panel.appendChild(buildItem(item, panel));
   document.body.appendChild(panel);
   const rect = panel.getBoundingClientRect();
   const vw = window.innerWidth;
@@ -77,6 +220,7 @@ function openContextMenu(x, y, items) {
   if (y + rect.height > vh - FLIP_MARGIN) ny = y - rect.height;
   if (nx < CLAMP_MARGIN) nx = CLAMP_MARGIN;
   if (ny < CLAMP_MARGIN) ny = CLAMP_MARGIN;
+  panel.dataset.side = ny < y ? "top" : "bottom";
   panel.style.left = `${nx}px`;
   panel.style.top = `${ny}px`;
   panel.style.visibility = "";
@@ -87,18 +231,18 @@ function openContextMenu(x, y, items) {
     setFocused(0);
   });
   document.addEventListener("pointerdown", onOutsidePointerDown, true);
-  document.addEventListener("scroll", onCloseSignal, true);
+  document.addEventListener("scroll", onScrollSignal, true);
   window.addEventListener("resize", onCloseSignal);
   window.addEventListener("keydown", onKeyDown);
 }
-function closeMenu() {
+function closeContextMenu() {
   if (!panel) return;
   panel.remove();
   panel = null;
   focusableItems = [];
   focusedIndex = -1;
   document.removeEventListener("pointerdown", onOutsidePointerDown, true);
-  document.removeEventListener("scroll", onCloseSignal, true);
+  document.removeEventListener("scroll", onScrollSignal, true);
   window.removeEventListener("resize", onCloseSignal);
   window.removeEventListener("keydown", onKeyDown);
 }
@@ -110,16 +254,20 @@ function setFocused(next) {
 function onOutsidePointerDown(e) {
   if (!panel) return;
   const target = e.target;
-  if (!(target instanceof Node) || !panel.contains(target)) closeMenu();
+  if (!(target instanceof Node) || !panel.contains(target)) closeContextMenu();
+}
+function onScrollSignal(e) {
+  if (panel && e.target instanceof Node && panel.contains(e.target)) return;
+  closeContextMenu();
 }
 function onCloseSignal() {
-  closeMenu();
+  closeContextMenu();
 }
 function onKeyDown(e) {
   if (!panel) return;
   if (e.key === "Escape") {
     e.preventDefault();
-    closeMenu();
+    closeContextMenu();
     return;
   }
   if (focusableItems.length === 0) return;
@@ -175,7 +323,9 @@ function noopHandle() {
     getData: () => [],
     exportCSV: noop,
     showColumn: noop,
-    hideColumn: noop
+    hideColumn: noop,
+    setPage: noop,
+    setPageSize: noop
   };
 }
 function createTable(el, opts) {
@@ -223,7 +373,7 @@ function createTable(el, opts) {
     if (search) {
       const q = search.toLowerCase();
       rows = rows.filter(
-        (row) => cols().some((c) => String(row[c.key] ?? "").toLowerCase().includes(q))
+        (row) => opts.searchFn ? opts.searchFn(search, row) : cols().some((c) => String(row[c.key] ?? "").toLowerCase().includes(q))
       );
     }
     if (filters.size > 0) {
@@ -364,6 +514,20 @@ function createTable(el, opts) {
     return input;
   }
   let openPanel = null;
+  function positionDropdownPanel(panel2, btn) {
+    panel2.hidden = false;
+    const sizing = resolvePanelSizing(el);
+    applyPanelSizing(panel2, sizing);
+    const rect = btn.getBoundingClientRect();
+    const pr = panel2.getBoundingClientRect();
+    const layout = computePopoverLayout(
+      { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom, width: rect.width, height: rect.height },
+      { width: window.innerWidth, height: window.innerHeight },
+      { side: "bottom", align: "end", offset: 4, margin: 8, minWidth: Math.max(pr.width, 180), maxWidth: Math.max(pr.width, 180), contentHeightHint: pr.height, maxHeight: sizing.maxHeight }
+    );
+    panel2.style.left = `${layout.left}px`;
+    panel2.style.top = `${layout.top}px`;
+  }
   function onPanelScroll(ev) {
     if (openPanel && ev.target instanceof Node && openPanel.el.contains(ev.target)) return;
     closeFilterPanel();
@@ -381,15 +545,7 @@ function createTable(el, opts) {
     document.body.appendChild(panel2);
     openPanel = { key: col.key, el: panel2 };
     btn.classList.add("is-open");
-    const rect = btn.getBoundingClientRect();
-    const pr = panel2.getBoundingClientRect();
-    let x = rect.right - pr.width;
-    let y = rect.bottom + 4;
-    if (x < 8) x = 8;
-    if (y + pr.height > window.innerHeight - 8) y = rect.top - pr.height - 4;
-    panel2.style.left = `${x}px`;
-    panel2.style.top = `${y}px`;
-    panel2.hidden = false;
+    positionDropdownPanel(panel2, btn);
     window.addEventListener("scroll", onPanelScroll, true);
     window.addEventListener("resize", onPanelScroll);
   }
@@ -410,7 +566,7 @@ function createTable(el, opts) {
         else allKeys.forEach((k) => selected.delete(k));
         emitSelection();
         renderBody();
-        renderHead();
+        syncHeadState();
       });
       cell.appendChild(box);
       headRow.appendChild(cell);
@@ -447,6 +603,7 @@ function createTable(el, opts) {
           } else if (sortDir === "asc") sortDir = "desc";
           else sortKey = null;
           invalidate();
+          if (sortKey) emitIcen(root, "icen:table-sort-change", { key: sortKey, dir: sortDir });
           opts.onSortChange?.(sortKey, sortDir);
           renderAll();
         };
@@ -466,6 +623,7 @@ function createTable(el, opts) {
         const btn = document.createElement("button");
         btn.type = "button";
         btn.className = "dt-filter-btn";
+        btn.dataset.colKey = col.key;
         if (hasFilter) btn.classList.add("is-active");
         btn.setAttribute("aria-label", `\u7B5B\u9009\u300C${col.title}\u300D`);
         btn.appendChild(svgIcon(ICON_FUNNEL, 12));
@@ -491,6 +649,33 @@ function createTable(el, opts) {
       headRow.appendChild(cell);
     }
   }
+  function syncHeadState() {
+    const headBox = headRow.querySelector(".dt-cell--check .dt-check");
+    if (headBox) {
+      const allKeys = pipeline().map((r) => keyOfRow(r));
+      const selCount = allKeys.filter((k) => selected.has(k)).length;
+      headBox.checked = selCount > 0 && selCount === allKeys.length;
+      headBox.indeterminate = selCount > 0 && selCount < allKeys.length;
+    }
+    headRow.querySelectorAll(".dt-filter-btn").forEach((b) => {
+      const key = b.dataset.colKey;
+      if (key) b.classList.toggle("is-active", filters.has(key));
+    });
+  }
+  function renderHeadKeepPanel() {
+    const keep = openPanel;
+    renderHead();
+    if (!keep) return;
+    openPanel = keep;
+    document.body.appendChild(keep.el);
+    window.addEventListener("scroll", onPanelScroll, true);
+    window.addEventListener("resize", onPanelScroll);
+    if (keep.key !== "__cols") {
+      headRow.querySelectorAll(".dt-filter-btn").forEach((b) => {
+        if (b.dataset.colKey === keep.key) b.classList.add("is-open");
+      });
+    }
+  }
   function attachResize(handle, col) {
     handle.addEventListener("pointerdown", (ev) => {
       ev.preventDefault();
@@ -508,12 +693,17 @@ function createTable(el, opts) {
         });
       };
       const onUp = (e) => {
-        handle.releasePointerCapture(e.pointerId);
+        try {
+          handle.releasePointerCapture(e.pointerId);
+        } catch {
+        }
         handle.removeEventListener("pointermove", onMove);
         handle.removeEventListener("pointerup", onUp);
+        handle.removeEventListener("pointercancel", onUp);
       };
       handle.addEventListener("pointermove", onMove);
       handle.addEventListener("pointerup", onUp);
+      handle.addEventListener("pointercancel", onUp);
     });
   }
   function openColumnPanel(btn) {
@@ -532,8 +722,10 @@ function createTable(el, opts) {
       box.addEventListener("change", () => {
         if (box.checked) colHidden.delete(col.key);
         else colHidden.set(col.key, true);
+        emitIcen(root, "icen:table-columns-change", { hidden: Array.from(colHidden.keys()) });
         invalidate();
-        renderAll();
+        renderBody();
+        renderHeadKeepPanel();
       });
       const text = document.createElement("span");
       text.textContent = col.title;
@@ -543,20 +735,13 @@ function createTable(el, opts) {
     panel2.appendChild(list);
     document.body.appendChild(panel2);
     openPanel = { key: "__cols", el: panel2 };
-    const rect = btn.getBoundingClientRect();
-    const pr = panel2.getBoundingClientRect();
-    let x = rect.right - pr.width;
-    let y = rect.bottom + 4;
-    if (x < 8) x = 8;
-    if (y + pr.height > window.innerHeight - 8) y = rect.top - pr.height - 4;
-    panel2.style.left = `${x}px`;
-    panel2.style.top = `${y}px`;
-    panel2.hidden = false;
+    positionDropdownPanel(panel2, btn);
     window.addEventListener("scroll", onPanelScroll, true);
     window.addEventListener("resize", onPanelScroll);
   }
   function exportCSV(filename) {
     const rows = pipeline();
+    emitIcen(root, "icen:table-export", { count: rows.length });
     const visible = cols();
     const header = visible.map((c) => csvEscape(c.title)).join(",");
     const lines = rows.map(
@@ -569,7 +754,7 @@ function createTable(el, opts) {
     a.href = url;
     a.download = filename ?? "export.csv";
     a.click();
-    URL.revokeObjectURL(url);
+    window.setTimeout(() => URL.revokeObjectURL(url), 1e3);
   }
   function csvEscape(s) {
     if (/[",\r\n]/.test(s)) return `"${s.replace(/"/g, '""')}"`;
@@ -593,9 +778,11 @@ function createTable(el, opts) {
         else cur.delete(v);
         if (cur.size === values.length) filters.delete(col.key);
         else filters.set(col.key, cur);
+        emitIcen(root, "icen:table-filter-change", { key: col.key, values: Array.from(filters.get(col.key) ?? []) });
         invalidate();
         page = 1;
-        renderAll();
+        renderBody();
+        syncHeadState();
       });
       const text = document.createElement("span");
       text.textContent = v === "" ? "\uFF08\u7A7A\uFF09" : v;
@@ -612,14 +799,17 @@ function createTable(el, opts) {
       filters.delete(col.key);
       invalidate();
       page = 1;
-      closeFilterPanel();
-      renderAll();
+      list.querySelectorAll(".dt-check").forEach((b) => {
+        b.checked = true;
+      });
+      renderBody();
+      syncHeadState();
     });
     footRow.appendChild(reset);
     panel2.append(list, footRow);
     return panel2;
   }
-  function makeRow(row, rowIndex, key) {
+  function makeRow(row, rowIndex, key, offsets) {
     const tr = document.createElement("div");
     tr.className = "dt-row";
     tr.setAttribute("role", "row");
@@ -633,17 +823,19 @@ function createTable(el, opts) {
     if (selectable) {
       const cell = document.createElement("div");
       cell.className = "dt-cell dt-cell--check";
-      if (frozenOffsets().size > 0 && selectable) {
+      if (offsets.size > 0) {
         cell.classList.add("dt-cell--frozen");
         cell.style.left = "0px";
       }
       const box = makeCheck(selected.has(key), "\u9009\u62E9\u8BE5\u884C");
+      let shiftClicked = false;
       box.addEventListener("click", (ev) => {
-        box._shift = ev.shiftKey;
+        shiftClicked = ev.shiftKey;
         ev.stopPropagation();
       });
       box.addEventListener("change", () => {
-        const shift = box._shift === true;
+        const shift = shiftClicked;
+        shiftClicked = false;
         if (shift && lastClickedIndex >= 0 && lastClickedIndex !== rowIndex) {
           const rows = pipeline();
           const [lo, hi] = lastClickedIndex < rowIndex ? [lastClickedIndex, rowIndex] : [rowIndex, lastClickedIndex];
@@ -661,8 +853,8 @@ function createTable(el, opts) {
         }
         lastClickedIndex = rowIndex;
         emitSelection();
-        renderHead();
-        renderFoot(pipeline().length);
+        syncHeadState();
+        renderFoot(opts.remote ? opts.totalCount ?? data.length : pipeline().length);
       });
       cell.appendChild(box);
       tr.appendChild(cell);
@@ -680,12 +872,12 @@ function createTable(el, opts) {
         ev.stopPropagation();
         if (expanded.has(key)) expanded.delete(key);
         else expanded.add(key);
+        emitIcen(root, "icen:table-row-toggle", { row, index: rowIndex, expanded: expanded.has(key) });
         renderBody();
       });
       cell.appendChild(btn);
       tr.appendChild(cell);
     }
-    const offsets = frozenOffsets();
     for (const col of cols()) {
       const cell = document.createElement("div");
       cell.className = "dt-cell";
@@ -702,11 +894,16 @@ function createTable(el, opts) {
       tr.classList.add("is-clickable");
       tr.addEventListener("click", () => opts.onRowClick(row));
     }
+    tr.addEventListener("click", () => {
+      emitIcen(root, "icen:table-row-click", { row, index: rowIndex });
+    });
     if (opts.contextMenu) {
       tr.addEventListener("contextmenu", (ev) => {
         ev.preventDefault();
         ev.stopPropagation();
-        openContextMenu(ev.clientX, ev.clientY, opts.contextMenu(row));
+        openContextMenu(ev.clientX, ev.clientY, opts.contextMenu(row), {
+          sizing: readPanelSizing(el)
+        });
       });
     }
     return tr;
@@ -721,7 +918,7 @@ function createTable(el, opts) {
   }
   function visibleRange(total) {
     if (!virtual) {
-      if (opts.pagination === false) return [0, total];
+      if (opts.remote || opts.pagination === false) return [0, total];
       const start2 = (page - 1) * pageSize;
       return [start2, Math.min(total, start2 + pageSize)];
     }
@@ -733,7 +930,7 @@ function createTable(el, opts) {
   }
   function renderBody() {
     const rows = pipeline();
-    const total = rows.length;
+    const total = opts.remote ? opts.totalCount ?? data.length : rows.length;
     const keepTop = virtual ? scroll.scrollTop : 0;
     body.textContent = "";
     if (opts.loading) {
@@ -760,6 +957,7 @@ function createTable(el, opts) {
     }
     const [start, end] = visibleRange(total);
     const frag = document.createDocumentFragment();
+    const offsets = frozenOffsets();
     if (virtual && start > 0) {
       const top = document.createElement("div");
       top.style.height = `${start * rowH}px`;
@@ -768,7 +966,7 @@ function createTable(el, opts) {
     for (let i = start; i < end; i++) {
       const row = rows[i];
       const key = keyOfRow(row);
-      frag.appendChild(makeRow(row, i, key));
+      frag.appendChild(makeRow(row, i, key, offsets));
       if (expandable && expanded.has(key)) frag.appendChild(makeExpandRow(row));
     }
     if (virtual && end < total) {
@@ -797,7 +995,8 @@ function createTable(el, opts) {
       clear.addEventListener("click", () => {
         selected.clear();
         emitSelection();
-        renderAll();
+        renderBody();
+        syncHeadState();
       });
       sel.appendChild(clear);
       foot.appendChild(sel);
@@ -820,6 +1019,10 @@ function createTable(el, opts) {
     sizeSel.addEventListener("change", () => {
       pageSize = Number(sizeSel.value);
       page = 1;
+      emitIcen(root, "icen:table-page-size-change", { pageSize });
+      emitIcen(root, "icen:table-page-change", { page, pageSize });
+      opts.onPageSizeChange?.(pageSize);
+      opts.onPageChange?.(page, pageSize);
       renderAll();
     });
     pager.appendChild(sizeSel);
@@ -833,6 +1036,8 @@ function createTable(el, opts) {
       if (opts2.aria) b.setAttribute("aria-label", opts2.aria);
       b.addEventListener("click", () => {
         page = target;
+        emitIcen(root, "icen:table-page-change", { page, pageSize });
+        opts.onPageChange?.(page, pageSize);
         renderAll();
       });
       return b;
@@ -861,6 +1066,7 @@ function createTable(el, opts) {
     window.clearTimeout(searchTimer);
     searchTimer = window.setTimeout(() => {
       search = searchInput?.value.trim() ?? "";
+      emitIcen(root, "icen:table-search-change", { query: search });
       invalidate();
       page = 1;
       renderAll();
@@ -884,9 +1090,9 @@ function createTable(el, opts) {
   }
   document.addEventListener("keydown", onDocKeydown);
   function emitSelection() {
-    if (!opts.onSelectionChange) return;
     const rows = data.filter((r) => selected.has(keyOfRow(r)));
-    opts.onSelectionChange(rows);
+    emitIcen(root, "icen:table-selection-change", { selected: rows });
+    opts.onSelectionChange?.(rows);
   }
   function renderAll() {
     if (destroyed) return;
@@ -895,7 +1101,26 @@ function createTable(el, opts) {
   }
   rekey();
   renderAll();
+  function setPage(n) {
+    if (!Number.isFinite(n) || n < 1) return;
+    page = Math.round(n);
+    emitIcen(root, "icen:table-page-change", { page, pageSize });
+    opts.onPageChange?.(page, pageSize);
+    renderAll();
+  }
+  function setPageSize(n) {
+    if (!Number.isFinite(n) || n <= 0) return;
+    pageSize = Math.round(n);
+    page = 1;
+    emitIcen(root, "icen:table-page-size-change", { pageSize });
+    emitIcen(root, "icen:table-page-change", { page, pageSize });
+    opts.onPageSizeChange?.(pageSize);
+    opts.onPageChange?.(page, pageSize);
+    renderAll();
+  }
   return {
+    setPage,
+    setPageSize,
     setData(next) {
       data = next;
       rekey();
@@ -938,7 +1163,8 @@ function createTable(el, opts) {
     exportCSV,
     showColumn(key) {
       colHidden.delete(key);
-      opts.columns.find((c) => c.key === key).hidden = false;
+      const col = opts.columns.find((c) => c.key === key);
+      if (col) col.hidden = false;
       invalidate();
       renderAll();
     },

package/dist/behaviors/date-picker.d.mts

@@ -0,0 +1,4 @@
+/** 返回销毁函数：摘除本次初始化容器的全部监听并复位幂等标记（可重新 init）。 */
+declare function initDatePicker(root?: ParentNode): () => void;
+
+export { initDatePicker };