@icen.ai/ui 0.9.0 → 0.10.0

package/dist/behaviors/popover.d.mts

@@ -40,6 +40,12 @@ interface PanelSizing {
     /** 高度上限 */
     maxHeight?: number;
 }
+/** Reveal an item inside one explicit scrollport. Never scrolls document ancestors;
+ * use this instead of scrollIntoView for portalled menus and nested listboxes. */
+declare function revealPopoverItem(item: HTMLElement, scrollport: HTMLElement, opts?: {
+    focus?: boolean;
+    axis?: 'block' | 'inline' | 'both';
+}): void;
 /** 从元素读取 data-panel-* 尺寸属性（非法/缺失字段跳过，不抛异常）。 */
 declare function readPanelSizing(el: Element | null | undefined): PanelSizing;
 /** 合并尺寸：程序面 overrides 优先于属性面（undefined 字段不覆盖）。 */
@@ -52,7 +58,7 @@ declare function sizingToLayout<T extends {
 }>(sizing: PanelSizing, opts: T): T;
 /** 把尺寸契约内联到自建面板（dropdown / context-menu / date-picker 等 fixed 面板）。
  *  传 null 复位全部内联尺寸——单例面板跨实例复用时防「上次的设置串味」。
- *  视口守卫：width / maxWidth 一律夹到 视口宽 − 24px（窄屏上过大的 data-panel-width 不溢出，
+ *  视口守卫：width / maxWidth 一律夹到 视口宽 − 24px（窄屏上过大的 data-icen-panel-width 不溢出，
  *  与 computePopoverLayout 的 availableWidth 同一纪律，不再两套标准）。 */
 declare function applyPanelSizing(panel: HTMLElement, sizing: PanelSizing | null): void;
 interface PopoverLayout {
@@ -68,15 +74,32 @@ interface OpenPopoverOptions extends PopoverLayoutOptions {
     sizing?: PanelSizing;
     /** 关闭（含外点/Esc 触发的关闭）后的回调 */
     onClose?: () => void;
+    /** Optional initial focus inside an interactive panel. */
+    initialFocus?: HTMLElement;
+    /** Restore the anchor only if the panel still owns focus; default true. */
+    restoreFocus?: boolean;
 }
 /** 视口智能布局：返回 {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 为先关后开。 */
+/** Shared ownership for action menus: opening one retires the previous renderer
+ * without stealing focus. The release handle cannot release a newer owner. */
+declare function claimMenuFocus(close: () => void): () => void;
+/** 打开浮层：panel 移入 body 并按 anchor 布局；重复调用同一 panel 为先关后开；
+ *  退场中重开从当前动画位置续接（复用既有门户记录，不重复插占位）。 */
 declare function openPopover(panel: HTMLElement, options: OpenPopoverOptions): void;
-/** 关闭浮层：移除监听并把 panel 还原到打开前的位置与 hidden 状态。 */
-declare function closePopover(panel: HTMLElement): void;
+/** 关闭浮层：视觉先退场（可被打断重开），finalize 再还原门户；焦点与 onClose 立即结算。
+ *  immediate: true 供卸载/销毁路径——跳过退场直接 finalize（拆页时不把面板留在 body）。 */
+declare function closePopover(panel: HTMLElement, opts?: {
+    immediate?: boolean;
+}): void;
+/**
+ * 声明式浮层委托：<button data-icen-popover-target="panelId"> 点击开关 .icen-popover 面板，
+ * 同步触发器 aria-haspopup/aria-expanded/aria-controls；面板内 .icen-popover-close 点击关闭。
+ * 同一 root 重复调用返回同一销毁函数；销毁摘除委托并关闭本作用域打开的浮层。SSR 下返回 no-op。
+ */
+declare function initPopover(root?: ParentNode): () => void;
 
-export { type OpenPopoverOptions, type PanelSizing, type PopoverAlign, type PopoverLayout, type PopoverLayoutOptions, type PopoverRect, type PopoverSide, type PopoverViewport, applyPanelSizing, closePopover, computePopoverLayout, openPopover, readPanelSizing, resolvePanelSizing, sizingToLayout };
+export { type OpenPopoverOptions, type PanelSizing, type PopoverAlign, type PopoverLayout, type PopoverLayoutOptions, type PopoverRect, type PopoverSide, type PopoverViewport, applyPanelSizing, claimMenuFocus, closePopover, computePopoverLayout, initPopover, openPopover, readPanelSizing, resolvePanelSizing, revealPopoverItem, sizingToLayout };

package/dist/behaviors/popover.mjs

@@ -1,10 +1,32 @@
 // src/behaviors/popover.ts
+function revealPopoverItem(item, scrollport, opts = {}) {
+  if (typeof document === "undefined") return;
+  if (opts.focus) item.focus({ preventScroll: true });
+  const rect = item.getBoundingClientRect(), bounds = scrollport.getBoundingClientRect();
+  const style = getComputedStyle(scrollport);
+  const inset = (value, extent) => {
+    const amount = Number.parseFloat(value) || 0;
+    return value.endsWith("%") ? amount * extent / 100 : amount;
+  };
+  if (opts.axis !== "inline") {
+    const top = bounds.top + scrollport.clientTop + inset(style.scrollPaddingTop, scrollport.clientHeight);
+    const bottom = bounds.top + scrollport.clientTop + scrollport.clientHeight - inset(style.scrollPaddingBottom, scrollport.clientHeight);
+    if (rect.top < top) scrollport.scrollTop -= top - rect.top;
+    else if (rect.bottom > bottom) scrollport.scrollTop += rect.bottom - bottom;
+  }
+  if (opts.axis === "inline" || opts.axis === "both") {
+    const left = bounds.left + scrollport.clientLeft + inset(style.scrollPaddingLeft, scrollport.clientWidth);
+    const right = bounds.left + scrollport.clientLeft + scrollport.clientWidth - inset(style.scrollPaddingRight, scrollport.clientWidth);
+    if (rect.left < left) scrollport.scrollLeft -= left - rect.left;
+    else if (rect.right > right) scrollport.scrollLeft += rect.right - right;
+  }
+}
 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"
+  width: "data-icen-panel-width",
+  minWidth: "data-icen-panel-min",
+  maxWidth: "data-icen-panel-max",
+  minHeight: "data-icen-panel-min-height",
+  maxHeight: "data-icen-panel-max-height"
 };
 function readPanelSizing(el) {
   const out = {};
@@ -85,10 +107,10 @@ function computePopoverLayout(anchor, viewport, opts = {}) {
   const preferredSide = opts.side ?? "top";
   const align = opts.align ?? "start";
   if (preferredSide === "left" || preferredSide === "right") {
+    const minWidth2 = Math.max(1, opts.minWidth ?? DEFAULT_MIN_WIDTH);
     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 side2 = (preferredSide === "left" ? availableLeft : availableRight) >= minWidth2 ? preferredSide : preferredSide === "left" ? "right" : "left";
     const maxWidth2 = Math.min(
       Math.max(opts.maxWidth ?? DEFAULT_MAX_WIDTH, minWidth2),
       side2 === "left" ? availableLeft : availableRight
@@ -117,7 +139,7 @@ function computePopoverLayout(anchor, viewport, opts = {}) {
   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 contentHeight = opts.contentHeightHint != null && opts.contentHeightHint > 0 ? opts.contentHeightHint : fallbackHeight;
   const desiredHeight = clamp(contentHeight, minHeight, Math.min(requestedMaxHeight, availableHeight));
   const side = chooseSide(preferredSide, availableTop, availableBottom, desiredHeight);
   const sideSpace = side === "top" ? availableTop : availableBottom;
@@ -134,6 +156,16 @@ function computePopoverLayout(anchor, viewport, opts = {}) {
   return { side, left, top, width, maxHeight };
 }
 var openPanels = /* @__PURE__ */ new Map();
+var closingPanels = /* @__PURE__ */ new Map();
+var EXIT_FALLBACK_MS = 240;
+var menuCloser = null;
+function claimMenuFocus(close) {
+  menuCloser?.();
+  menuCloser = close;
+  return () => {
+    if (menuCloser === close) menuCloser = null;
+  };
+}
 function rectFromElement(el) {
   const r = el.getBoundingClientRect();
   return { left: r.left, top: r.top, right: r.right, bottom: r.bottom, width: r.width, height: r.height };
@@ -151,21 +183,54 @@ function relayout(state) {
     closePopover(state.panel);
     return;
   }
-  const layout = computePopoverLayout(
+  let layout = computePopoverLayout(
     anchor,
     { width: window.innerWidth, height: window.innerHeight },
     state.opts
   );
   const { panel } = state;
+  const scrollPositions = [panel, ...panel.querySelectorAll("*")].filter((node) => node.scrollTop !== 0 || node.scrollLeft !== 0).map((node) => ({ node, top: node.scrollTop, left: node.scrollLeft }));
+  panel.style.width = `${layout.width}px`;
+  if (state.opts.contentHeightHint == null && (layout.side === "top" || layout.side === "bottom")) {
+    panel.style.maxHeight = `${Math.min(state.opts.maxHeight ?? DEFAULT_MAX_HEIGHT, Math.max(80, window.innerHeight - (state.opts.margin ?? 12) * 2))}px`;
+    const measured = panel.offsetHeight;
+    if (measured > 0) layout = computePopoverLayout(anchor, { width: window.innerWidth, height: window.innerHeight }, { ...state.opts, contentHeightHint: measured });
+  }
   panel.style.left = `${layout.left}px`;
-  panel.style.top = `${layout.top}px`;
   panel.style.width = `${layout.width}px`;
   panel.style.maxHeight = `${layout.maxHeight}px`;
-  panel.dataset.side = layout.side;
+  let top = layout.top;
+  const actualHeight = panel.offsetHeight;
+  if (actualHeight > 0 && (layout.side === "top" || layout.side === "bottom")) {
+    const desired = layout.side === "top" ? anchor.top - (state.opts.offset ?? 8) - actualHeight : anchor.bottom + (state.opts.offset ?? 8);
+    const margin = state.opts.margin ?? 12;
+    top = clamp(desired, margin, window.innerHeight - margin - actualHeight);
+  }
+  panel.style.top = `${top}px`;
+  for (const pos of scrollPositions) {
+    pos.node.scrollTop = pos.top;
+    pos.node.scrollLeft = pos.left;
+  }
+  panel.dataset.icenSide = layout.side;
   panel.style.visibility = state.prevVisibility;
 }
-function onWindowChange() {
-  openPanels.forEach(relayout);
+function observeOpenPanel(state) {
+  if (typeof ResizeObserver === "undefined") return;
+  state.resizeObserver = new ResizeObserver(() => {
+    if (state.layoutFrame != null) return;
+    state.layoutFrame = window.requestAnimationFrame(() => {
+      state.layoutFrame = void 0;
+      if (openPanels.get(state.panel) === state) relayout(state);
+    });
+  });
+  state.resizeObserver.observe(state.panel);
+  if (state.anchor instanceof Element) state.resizeObserver.observe(state.anchor);
+}
+function onWindowChange(event) {
+  openPanels.forEach((state) => {
+    if (event?.type === "scroll" && event.target instanceof Node && state.panel.contains(event.target)) return;
+    relayout(state);
+  });
 }
 function onOutsidePointerDown(e) {
   const target = e.target;
@@ -177,18 +242,40 @@ function onOutsidePointerDown(e) {
   });
 }
 function onKeyDown(e) {
-  if (e.key !== "Escape") return;
+  if (e.key !== "Escape" || e.defaultPrevented || e.isComposing || e.keyCode === 229 || menuCloser) return;
   const states = Array.from(openPanels.values());
   const top = states[states.length - 1];
   if (top) {
     e.preventDefault();
+    e.stopPropagation();
     closePopover(top.panel);
   }
 }
 function openPopover(panel, options) {
   if (typeof document === "undefined") return;
+  const pending = closingPanels.get(panel);
+  if (pending) {
+    window.clearTimeout(pending.timer);
+    panel.removeEventListener("transitionend", pending.onEnd);
+    closingPanels.delete(panel);
+    delete panel.dataset.icenState;
+    openPanels.set(panel, pending.state);
+    panel.hidden = false;
+    panel.style.visibility = "hidden";
+    relayout(pending.state);
+    observeOpenPanel(pending.state);
+    if (openPanels.size === 1) {
+      window.addEventListener("resize", onWindowChange);
+      window.addEventListener("scroll", onWindowChange, true);
+      document.addEventListener("pointerdown", onOutsidePointerDown, true);
+      window.addEventListener("keydown", onKeyDown, true);
+    }
+    const ifs = options.initialFocus;
+    if (ifs && panel.contains(ifs)) ifs.focus({ preventScroll: true });
+    return;
+  }
   if (openPanels.has(panel)) closePopover(panel);
-  const { anchor, onClose, sizing, ...rest } = options;
+  const { anchor, onClose, sizing, initialFocus, restoreFocus, ...rest } = options;
   const layoutOpts = sizingToLayout(resolvePanelSizing(panel, sizing), rest);
   const placeholder = document.createComment("popover-anchor");
   panel.parentNode?.insertBefore(placeholder, panel);
@@ -201,25 +288,25 @@ function openPopover(panel, options) {
     onClose,
     placeholder,
     wasHidden,
-    prevVisibility
+    prevVisibility,
+    returnFocus: restoreFocus === false ? null : anchor instanceof HTMLElement ? anchor : document.activeElement instanceof HTMLElement ? document.activeElement : null
   };
   openPanels.set(panel, state);
   document.body.appendChild(panel);
   panel.hidden = false;
   panel.style.visibility = "hidden";
   relayout(state);
+  observeOpenPanel(state);
+  if (initialFocus && panel.contains(initialFocus)) initialFocus.focus({ preventScroll: true });
   if (openPanels.size === 1) {
     window.addEventListener("resize", onWindowChange);
     window.addEventListener("scroll", onWindowChange, true);
     document.addEventListener("pointerdown", onOutsidePointerDown, true);
-    window.addEventListener("keydown", onKeyDown);
+    window.addEventListener("keydown", onKeyDown, true);
   }
 }
-function closePopover(panel) {
-  if (typeof document === "undefined") return;
-  const state = openPanels.get(panel);
-  if (!state) return;
-  openPanels.delete(panel);
+function finalizeClose(panel, state) {
+  delete panel.dataset.icenState;
   panel.style.visibility = state.prevVisibility;
   if (typeof state.wasHidden === "string") panel.setAttribute("hidden", state.wasHidden);
   else panel.hidden = state.wasHidden;
@@ -227,25 +314,139 @@ function closePopover(panel) {
   panel.style.top = "";
   panel.style.width = "";
   panel.style.maxHeight = "";
-  delete panel.dataset.side;
+  delete panel.dataset.icenSide;
   if (state.placeholder.parentNode) {
     state.placeholder.parentNode.insertBefore(panel, state.placeholder);
     state.placeholder.remove();
   }
+}
+function closePopover(panel, opts) {
+  if (typeof document === "undefined") return;
+  const state = openPanels.get(panel);
+  if (!state) return;
+  openPanels.delete(panel);
+  state.resizeObserver?.disconnect();
+  if (state.layoutFrame != null) {
+    window.cancelAnimationFrame(state.layoutFrame);
+    state.layoutFrame = void 0;
+  }
+  const ownsFocus = panel.contains(document.activeElement);
+  if (ownsFocus && state.returnFocus?.isConnected) state.returnFocus.focus({ preventScroll: true });
   if (openPanels.size === 0) {
     window.removeEventListener("resize", onWindowChange);
     window.removeEventListener("scroll", onWindowChange, true);
     document.removeEventListener("pointerdown", onOutsidePointerDown, true);
-    window.removeEventListener("keydown", onKeyDown);
+    window.removeEventListener("keydown", onKeyDown, true);
   }
   state.onClose?.();
+  const calm = opts?.immediate || typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  if (calm || !panel.isConnected) {
+    finalizeClose(panel, state);
+    return;
+  }
+  panel.dataset.icenState = "closing";
+  const finalize = () => {
+    const pending = closingPanels.get(panel);
+    if (!pending || pending.state !== state) return;
+    window.clearTimeout(pending.timer);
+    panel.removeEventListener("transitionend", pending.onEnd);
+    closingPanels.delete(panel);
+    finalizeClose(panel, state);
+  };
+  const onEnd = (event) => {
+    if (event.target === panel && event.propertyName === "opacity") finalize();
+  };
+  panel.addEventListener("transitionend", onEnd);
+  closingPanels.set(panel, {
+    state,
+    timer: window.setTimeout(finalize, EXIT_FALLBACK_MS),
+    onEnd
+  });
+}
+var popoverScopes = /* @__PURE__ */ new WeakMap();
+var popoverDefaults = /* @__PURE__ */ new WeakMap();
+function rememberPopoverDefaults(panel) {
+  let defaults = popoverDefaults.get(panel);
+  if (!defaults) {
+    const side = panel.dataset.icenSide;
+    const align = panel.getAttribute("data-icen-align");
+    defaults = {
+      side: side === "top" || side === "bottom" || side === "left" || side === "right" ? side : void 0,
+      align: align === "start" || align === "center" || align === "end" ? align : void 0
+    };
+    popoverDefaults.set(panel, defaults);
+  }
+  return defaults;
+}
+function initPopover(root) {
+  if (typeof document === "undefined") return () => {
+  };
+  const scope = root ?? document;
+  const existing = popoverScopes.get(scope);
+  if (existing) return existing;
+  const opened = /* @__PURE__ */ new Map();
+  const dismissHandlers = /* @__PURE__ */ new Map();
+  const watchDismiss = (panel) => {
+    if (dismissHandlers.has(panel)) return;
+    const handler = (event) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+      if (target.closest(".icen-popover-close, [data-icen-popover-dismiss]")) closePopover(panel);
+    };
+    panel.addEventListener("click", handler);
+    dismissHandlers.set(panel, handler);
+  };
+  const onClick = (event) => {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    const trigger = target.closest("[data-icen-popover-target]");
+    if (!trigger || !scope.contains(trigger)) return;
+    const id = trigger.getAttribute("data-icen-popover-target") ?? "";
+    const panel = document.getElementById(id);
+    if (!panel || !panel.classList.contains("icen-popover")) return;
+    if (openPanels.has(panel)) {
+      closePopover(panel);
+      return;
+    }
+    const defaults = rememberPopoverDefaults(panel);
+    const sideAttr = trigger.getAttribute("data-icen-side");
+    const alignAttr = trigger.getAttribute("data-icen-align");
+    if (!trigger.hasAttribute("aria-haspopup")) trigger.setAttribute("aria-haspopup", "dialog");
+    trigger.setAttribute("aria-expanded", "true");
+    if (panel.id) trigger.setAttribute("aria-controls", panel.id);
+    opened.set(panel, trigger);
+    watchDismiss(panel);
+    openPopover(panel, {
+      anchor: trigger,
+      side: sideAttr ?? defaults.side ?? "bottom",
+      align: alignAttr ?? defaults.align ?? "start",
+      initialFocus: panel.querySelector("[data-icen-autofocus], [autofocus]") ?? void 0,
+      onClose: () => {
+        opened.delete(panel);
+        trigger.setAttribute("aria-expanded", "false");
+      }
+    });
+  };
+  scope.addEventListener("click", onClick);
+  const dispose = () => {
+    scope.removeEventListener("click", onClick);
+    for (const panel of [...opened.keys()]) closePopover(panel, { immediate: true });
+    for (const [panel, handler] of dismissHandlers) panel.removeEventListener("click", handler);
+    dismissHandlers.clear();
+    popoverScopes.delete(scope);
+  };
+  popoverScopes.set(scope, dispose);
+  return dispose;
 }
 export {
   applyPanelSizing,
+  claimMenuFocus,
   closePopover,
   computePopoverLayout,
+  initPopover,
   openPopover,
   readPanelSizing,
   resolvePanelSizing,
+  revealPopoverItem,
   sizingToLayout
 };

package/dist/behaviors/select.d.mts

@@ -1,6 +1,9 @@
-/** 为 root 下每个 [data-select] 容器初始化（root 自身是 [data-select] 也算）。
+/** 为 root 下每个 [data-icen-select] 容器初始化（root 自身是 [data-icen-select] 也算）。
  *  返回销毁函数：摘除本次初始化容器的全部监听并复位幂等标记（可重新 init）；
  *  最后一个容器销毁时同时摘除 document 级单例委托。 */
 declare function initSelect(root?: ParentNode): () => void;
+/** Resync authored selection classes, labels and form values without emitting a
+ * user-change event. Child/text/native-disabled changes are observed automatically. */
+declare function refreshSelect(root?: ParentNode): void;
 
-export { initSelect };
+export { initSelect, refreshSelect };