@wisdomgarden/torque 0.2.1 → 0.2.3

package/dist/components/popover/popover.js

@@ -1,194 +1,185 @@
 "use client";
-import { jsx as ie } from "react/jsx-runtime";
-import { offset as le, flip as ae, size as de, shift as ue, limitShift as fe, arrow as me, hide as pe, useFloating as ge, autoUpdate as ve } from "@floating-ui/react-dom";
-import { useDirection as he, getFloatingPosition as Ee } from "@mantine/core";
-import B, { useRef as l, useId as xe, useCallback as r, useEffect as J, useMemo as K } from "react";
-import { useEscapeClose as Re } from "./hooks.js";
-import { PopoverContext as Q } from "./popover-context.js";
-const v = 8, Te = ({
-  children: W,
-  position: X = "bottom",
-  offset: C = 8,
-  opened: N,
-  defaultOpened: Y = !1,
-  onOpenChange: T,
-  disabled: b = !1,
+import { jsx as re } from "react/jsx-runtime";
+import { offset as se, flip as ie, size as le, shift as ae, limitShift as ce, arrow as de, hide as ue, useFloating as fe, autoUpdate as pe } from "@floating-ui/react-dom";
+import { useDirection as me, getFloatingPosition as ge } from "@mantine/core";
+import J, { useRef as r, useId as he, useCallback as s, useEffect as K, useMemo as L } from "react";
+import { isDev as ve } from "../../common/is-dev.js";
+import { PopoverContext as O } from "./popover-context.js";
+const g = 8, be = ({
+  children: Q,
+  position: W = "bottom",
+  offset: P = 8,
+  opened: w,
+  defaultOpened: X = !1,
+  onOpenChange: d,
+  disabled: y = !1,
   withArrow: i = !1,
-  arrowSize: a = 8,
-  trigger: I = "click",
-  openDelay: L = 0,
-  closeDelay: M = 100,
-  closeOnClickOutside: S = !0,
-  closeOnEscape: Z = !0,
-  restoreFocus: z,
+  arrowSize: u = 8,
+  trigger: l = "click",
+  openDelay: F = 0,
+  closeDelay: E = 100,
+  closeOnClickOutside: b = !0,
+  closeOnEscape: C = !0,
+  restoreFocus: D,
   strategy: h = "absolute",
-  initialFocusRef: $,
-  trapFocus: D = !1,
-  preventAutoFocus: G = !1,
-  "aria-labelledby": H
+  initialFocusRef: N,
+  trapFocus: T = !1,
+  preventAutoFocus: I = !1,
+  "aria-labelledby": M
 }) => {
-  const E = B.useContext(Q), j = E?.registerNestedFloatingElement, x = E ? E.depth + 1 : 0, R = N !== void 0, [ee, te] = B.useState(Y), o = R ? N : ee, d = l(null), u = l(null), f = l(null), F = l(/* @__PURE__ */ new Set()), P = l(void 0), y = xe(), { dir: ne } = he(), n = r(
+  const $ = J.useContext(O)?.registerNestedFloatingElement, a = w !== void 0, [Y, Z] = J.useState(X), c = a ? w : Y, f = r(null), S = r(null), p = r(null), v = r(/* @__PURE__ */ new Set()), x = r(void 0), G = he(), { dir: z } = me(), n = s(
     (e) => {
-      R || te(e), T?.(e);
+      a || Z(e), d?.(e);
     },
-    [R, T]
-  ), w = r(() => n(!1), [n]), k = r(() => n(!o), [o, n]), s = r(() => {
-    window.clearTimeout(P.current), P.current = void 0;
-  }, []), O = r(
+    [a, d]
+  ), H = s(() => n(!c), [c, n]), o = s(() => {
+    window.clearTimeout(x.current), x.current = void 0;
+  }, []), j = s(
     (e) => {
-      s();
-      const t = e ? L : M;
+      o();
+      const t = e ? F : E;
       if (t <= 0) {
         n(e);
         return;
       }
-      P.current = window.setTimeout(() => n(e), t);
+      x.current = window.setTimeout(() => n(e), t);
     },
-    [s, L, M, n]
+    [o, F, E, n]
   );
-  J(() => s, [s]);
-  const U = r(
+  K(() => o, [o]);
+  const k = r(!1);
+  K(() => {
+    !ve() || k.current || !a || l === "none" || d || (k.current = !0, console.warn(
+      `[@wisdomgarden/torque] <Popover trigger="${l}"> is controlled through \`opened\` but got no \`onOpenChange\`, so every built-in trigger resolves to a no-op — including the \`openDelay\` / \`closeDelay\` timers, which still run and then have nowhere to report. Pass \`onOpenChange\`, or use trigger="none" if the host owns the open state.`
+    ));
+  }, [a, l, d]);
+  const q = s(
     (e) => {
-      F.current.add(e);
-      const t = j?.(e);
+      v.current.add(e);
+      const t = $?.(e);
       return () => {
-        F.current.delete(e), t?.();
+        v.current.delete(e), t?.();
       };
     },
-    [j]
-  ), m = r(() => {
-    const e = f.current ? [f.current] : [];
-    return F.current.forEach((t) => {
+    [$]
+  ), U = s(() => {
+    const e = p.current ? [p.current] : [];
+    return v.current.forEach((t) => {
       t.isConnected && e.push(t);
     }), Array.from(new Set(e));
-  }, []);
-  J(() => {
-    if (!S || !o) return;
-    const e = (t) => {
-      const g = t.composedPath(), c = u.current;
-      c && g.includes(c) || m().some((ce) => g.includes(ce)) || w();
-    };
-    return document.addEventListener("mousedown", e, !0), document.addEventListener("touchstart", e, !0), () => {
-      document.removeEventListener("mousedown", e, !0), document.removeEventListener("touchstart", e, !0);
-    };
-  }, [S, o, w, m]), Re(
-    Z,
-    o,
-    w,
-    u,
-    y,
-    x,
-    z
-  );
-  const oe = K(
+  }, []), ee = L(
     () => [
-      le(C + (i ? a / 2 : 0)),
-      ae({ padding: v }),
+      se(P + (i ? u / 2 : 0)),
+      ie({ padding: g }),
       // 必须在 shift 之前：否则 availableHeight 是 shift 推动后的位置算出的（≈整屏），高度约束失效
-      de({
-        padding: v,
-        apply({ availableWidth: e, availableHeight: t, rects: g, elements: c }) {
-          c.floating.style.setProperty(
+      le({
+        padding: g,
+        apply({ availableWidth: e, availableHeight: t, rects: oe, elements: R }) {
+          R.floating.style.setProperty(
             "--t-popover-available-width",
             `${Math.max(0, e)}px`
-          ), c.floating.style.setProperty(
+          ), R.floating.style.setProperty(
             "--t-popover-available-height",
             `${Math.max(0, t)}px`
-          ), c.floating.style.setProperty(
+          ), R.floating.style.setProperty(
             "--t-popover-reference-width",
-            `${g.reference.width}px`
+            `${oe.reference.width}px`
           );
         }
       }),
-      ue({
-        padding: v,
+      ae({
+        padding: g,
         crossAxis: !0,
         mainAxis: !0,
-        limiter: fe()
+        limiter: ce()
       }),
       ...i ? (
         // floating-ui 的 arrow 中间件按设计就是收一个 ref 对象（它在定位阶段自己读
         // .current），不是我们在渲染期读 ref 的值。没有保留该 API 的改写方式。
         // eslint-disable-next-line react-hooks/refs
-        [me({ element: d, padding: v })]
+        [de({ element: f, padding: g })]
       ) : [],
-      pe()
+      ue()
     ],
-    [C, i, a, d]
+    [P, i, u, f]
   ), {
     x: V,
     y: _,
-    refs: p,
-    placement: re,
-    middlewareData: q
-  } = ge({
-    open: o,
+    refs: m,
+    placement: te,
+    middlewareData: A
+  } = fe({
+    open: c,
     strategy: h,
-    placement: Ee(ne, X),
-    middleware: oe,
-    whileElementsMounted: ve
-  }), A = re.split("-")[0], se = K(
+    placement: ge(z, W),
+    middleware: ee,
+    whileElementsMounted: pe
+  }), B = te.split("-")[0], ne = L(
     () => ({
-      opened: o,
+      opened: c,
       setOpen: n,
-      toggle: k,
-      trigger: I,
-      disabled: b,
-      id: y,
+      toggle: H,
+      trigger: l,
+      disabled: y,
+      id: G,
       withArrow: i,
-      arrowSize: a,
+      arrowSize: u,
       x: V,
       y: _,
       strategy: h,
-      resolvedSide: A,
-      middlewareData: q,
-      scheduleHover: O,
-      cancelHoverTimer: s,
-      referenceRef: u,
-      floatingRef: f,
-      arrowRef: d,
-      setReference: p.setReference,
-      setFloating: p.setFloating,
-      depth: x,
-      registerNestedFloatingElement: U,
-      getFloatingScopeElements: m,
-      initialFocusRef: $,
-      trapFocus: D,
-      preventAutoFocus: G,
-      ariaLabelledby: H
+      resolvedSide: B,
+      middlewareData: A,
+      scheduleHover: j,
+      cancelHoverTimer: o,
+      referenceRef: S,
+      floatingRef: p,
+      arrowRef: f,
+      setReference: m.setReference,
+      setFloating: m.setFloating,
+      registerNestedFloatingElement: q,
+      getFloatingScopeElements: U,
+      initialFocusRef: N,
+      trapFocus: T,
+      preventAutoFocus: I,
+      ariaLabelledby: M,
+      restoreFocus: D,
+      closeOnEscape: C,
+      closeOnClickOutside: b
     }),
     [
-      o,
+      c,
       n,
-      k,
-      I,
-      b,
+      H,
+      l,
       y,
+      G,
       i,
-      a,
+      u,
       V,
       _,
       h,
+      B,
       A,
-      q,
-      O,
-      s,
-      u,
+      j,
+      o,
+      S,
+      p,
       f,
-      d,
-      p.setReference,
-      p.setFloating,
-      x,
+      m.setReference,
+      m.setFloating,
+      q,
       U,
-      m,
-      $,
+      N,
+      T,
+      I,
+      M,
       D,
-      G,
-      H
+      C,
+      b
     ]
   );
-  return /* @__PURE__ */ ie(Q.Provider, { value: se, children: W });
+  return /* @__PURE__ */ re(O.Provider, { value: ne, children: Q });
 };
 export {
-  Te as Popover
+  be as Popover
 };

package/dist/components/popover/popover.types.d.ts

@@ -22,7 +22,11 @@ export interface PopoverProps {
      */
     offset?: number;
     /**
-     * 受控模式：是否展开
+     * 受控模式：是否展开。
+     *
+     * 受控之后内部不再持有开关状态，所有内部触发都只转发给 `onOpenChange`，
+     * 所以除 `trigger="none"` 外**必须同时提供 `onOpenChange`** ——
+     * 漏传会让 click / hover 以及 `openDelay` / `closeDelay` 全部静默失效。
      */
     opened?: boolean;
     /**
@@ -31,7 +35,8 @@ export interface PopoverProps {
      */
     defaultOpened?: boolean;
     /**
-     * 展开状态变更回调
+     * 展开状态变更回调。受控与非受控都会调用；受控下它是内部触发唯一的出口，
+     * 必须无条件回写，业务上的启用与否交给 `disabled`。
      */
     onOpenChange?: (opened: boolean) => void;
     /**
@@ -64,6 +69,10 @@ export interface PopoverProps {
     /**
      * hover 关闭延迟（ms），留出鼠标从触发元素移动到浮层的时间。
      * 仅 `trigger="hover"` 生效。
+     *
+     * 设为 `0` 即取消这段缓冲：鼠标离开触发元素就同步关闭，够不到浮层，键盘也 Tab 不进去。
+     * 想要「只给看、不给进一步操作」的富文本 tooltip 就该设 `0`，但浮层内容必须纯展示；
+     * 浮层内有可交互内容时不要设 `0`。
      * @default 100
      */
     closeDelay?: number;
@@ -209,11 +218,9 @@ export interface PopoverContextValue {
     arrowRef: React.RefObject<HTMLDivElement | null>;
     setReference: (node: HTMLElement | null) => void;
     setFloating: (node: HTMLDivElement | null) => void;
-    /** 当前 Popover 的逻辑嵌套深度，用于浮层层级和 Escape 栈排序 */
-    depth: number;
     /** 将后代 Portal 浮层登记到当前 Popover 的交互与焦点范围中 */
     registerNestedFloatingElement: (element: HTMLElement) => () => void;
-    /** 返回当前浮层及所有已登记后代浮层，用于外部点击与焦点判断 */
+    /** 返回当前浮层及所有已登记后代浮层，用于焦点范围判断 */
     getFloatingScopeElements: () => HTMLElement[];
     /** 外部传入的初始焦点目标；`usePopoverFocus` 有值时优先聚焦该元素 */
     initialFocusRef?: React.RefObject<HTMLElement | null>;
@@ -223,4 +230,10 @@ export interface PopoverContextValue {
     preventAutoFocus: boolean;
     /** dialog 的 `aria-labelledby` id；由 `PopoverDropdown` 写到 role="dialog" 元素上 */
     ariaLabelledby?: string;
+    /** Escape 关闭后恢复焦点的方法；未传时聚焦 Target */
+    restoreFocus?: () => void;
+    /** 交给层级模块：本层为栈顶时 Escape 是否关闭 */
+    closeOnEscape: boolean;
+    /** 交给层级模块：点在外面时是否关闭 */
+    closeOnClickOutside: boolean;
 }

package/dist/components/tooltip/index.d.ts

@@ -27,6 +27,14 @@ export type TooltipProps = React.HTMLAttributes<HTMLDivElement> & WrapperDisplay
     readonly strategy?: FloatingStrategy;
     /** 是否禁用 Tooltip 的显示 */
     readonly disabled?: boolean;
+    /**
+     * 鼠标移入浮层时是否保持显示，默认 `true`。
+     *
+     * - `true`：浮层可 hover，用户能选中并复制其中的文字，适合 info 等解释说明场景；
+     * - `false`：浮层不响应鼠标（`pointer-events: none`），鼠标移向浮层即消失，
+     *   适合列表选择等仅需查看完整文本、无复制需求的场景。
+     */
+    readonly interactive?: boolean;
     /** 触发 Tooltip 的目标元素 */
     readonly children: React.ReactNode;
     /** Tooltip 内显示的提示内容 */
@@ -41,7 +49,7 @@ export type TooltipProps = React.HTMLAttributes<HTMLDivElement> & WrapperDisplay
     readonly truncateMaxLines?: number;
     /** 透传给浮层根节点的 ref */
     readonly ref?: React.Ref<HTMLDivElement>;
-    /** 浮层的 z-index 层级，默认 300 */
+    /** 浮层的 z-index 层级。不传时由层级模块按打开顺序计算（普通层从 200 起） */
     readonly zIndex?: number;
 };
 /**
@@ -50,5 +58,5 @@ export type TooltipProps = React.HTMLAttributes<HTMLDivElement> & WrapperDisplay
  * 基于 `@floating-ui/react-dom` 封装的工具提示组件，支持智能定位、自动翻转、箭头指示，
  * 以及独有的「仅文本截断时才显示 (showOnlyWhenTruncated)」功能。
  */
-export declare const Tooltip: ({ position, strategy, arrowProps, offset: offsetProp, label, children, disabled, showOnlyWhenTruncated, truncateMaxWidth, truncateMaxLines, ref: externalRef, inline, block, zIndex, ...others }: TooltipProps) => import("react").JSX.Element;
+export declare const Tooltip: ({ position, strategy, arrowProps, offset: offsetProp, label, children, disabled, interactive, showOnlyWhenTruncated, truncateMaxWidth, truncateMaxLines, ref: externalRef, inline, block, zIndex: zIndexProp, ...others }: TooltipProps) => import("react").JSX.Element;
 export type * from './types';

package/dist/components/tooltip/index.js

@@ -1,150 +1,158 @@
 "use client";
-import { jsxs as b, Fragment as oe, jsx as m } from "react/jsx-runtime";
-import { offset as ne, flip as se, shift as ie, arrow as ae, hide as le, useFloating as ce, autoUpdate as de } from "@floating-ui/react-dom";
-import { useDirection as ue, getFloatingPosition as fe, Portal as me, Transition as pe } from "@mantine/core";
-import { useMergedRef as H } from "@mantine/hooks";
-import { useRef as i, useState as ge, isValidElement as we, useMemo as p, useCallback as r } from "react";
-import { FloatingArrow as ve } from "./floating-arrow.js";
-import h from "./styles.module.css.js";
-import { useMergedEvents as Te } from "./use-merged-events.js";
-import { useTooltipTrigger as Ee } from "./use-tooltip-trigger.js";
-import { getTruncationTarget as Re, isTruncated as Fe } from "./utils.js";
-const g = 8, Le = ({
-  position: D = "top",
-  strategy: N = "absolute",
-  arrowProps: P,
-  offset: w = 5,
-  label: y,
+import { jsxs as H, Fragment as ie, jsx as g } from "react/jsx-runtime";
+import { offset as ae, flip as le, shift as ce, arrow as de, hide as fe, useFloating as me, autoUpdate as ue } from "@floating-ui/react-dom";
+import { useDirection as pe, getFloatingPosition as ge, Transition as we } from "@mantine/core";
+import { useMergedRef as I } from "@mantine/hooks";
+import { useRef as i, useState as Te, isValidElement as ve, useMemo as w, useCallback as r } from "react";
+import { Portal as xe } from "../_inner/portal/portal.js";
+import { useOverlayLayer as Ee } from "../overlay-layer/use-overlay-layer.js";
+import { FloatingArrow as Re } from "./floating-arrow.js";
+import L from "./styles.module.css.js";
+import { useMergedEvents as Fe } from "./use-merged-events.js";
+import { useTooltipTrigger as Me } from "./use-tooltip-trigger.js";
+import { getTruncationTarget as ye, isTruncated as he } from "./utils.js";
+const T = 8, Be = ({
+  position: b = "top",
+  strategy: z = "absolute",
+  arrowProps: D,
+  offset: v = 5,
+  label: N,
   children: a,
-  disabled: A,
-  showOnlyWhenTruncated: l = !1,
-  truncateMaxWidth: L,
-  truncateMaxLines: k = 1,
-  ref: I,
-  inline: c,
-  block: v = !0,
-  zIndex: S = 300,
+  disabled: x,
+  interactive: l = !0,
+  showOnlyWhenTruncated: c = !1,
+  truncateMaxWidth: P,
+  truncateMaxLines: A = 1,
+  ref: k,
+  inline: d,
+  block: E = !0,
+  zIndex: S,
   ...j
 }) => {
-  const T = i(null), d = i(null), E = i(null), [R, o] = ge(!1), z = we(a), B = p(
-    () => c !== void 0 ? !c : v ?? !0,
-    [v, c]
+  const R = i(null), f = i(null), F = i(null), [m, o] = Te(!1), B = ve(a), C = w(
+    () => d !== void 0 ? !d : E ?? !0,
+    [E, d]
   ), {
-    size: C = 6,
-    offset: G = 5,
-    radius: V = 0
-  } = P ?? {}, { dir: F } = ue(), U = p(() => [
-    ne(w),
-    se({ padding: g }),
-    ie({ padding: g }),
+    size: G = 6,
+    offset: V = 5,
+    radius: O = 0
+  } = D ?? {}, { dir: M } = pe(), U = w(() => [
+    ae(v),
+    le({ padding: T }),
+    ce({ padding: T }),
     // 同 popover.tsx：floating-ui 的 arrow 中间件收的就是 ref 对象本身。
     // eslint-disable-next-line react-hooks/refs
-    ae({ element: E, padding: g }),
-    le()
-  ], [w]), {
+    de({ element: F, padding: T }),
+    fe()
+  ], [v]), {
     x: X,
     y: Y,
-    refs: M,
+    refs: y,
     floatingStyles: _,
     placement: q,
     middlewareData: { arrow: { x: J, y: K } = {} },
-    middlewareData: x
-  } = ce({
-    open: R,
-    strategy: N,
-    placement: fe(F, D),
+    middlewareData: h
+  } = me({
+    open: m,
+    strategy: z,
+    placement: ge(M, b),
     middleware: U,
-    whileElementsMounted: de
-  }), O = H(
-    T,
-    I,
-    M.setFloating
+    whileElementsMounted: ue
+  }), { zIndex: Q, ref: Z } = Ee({
+    opened: !x && m,
+    zIndex: S,
+    name: "tooltip"
+  }), $ = I(
+    R,
+    k,
+    y.setFloating,
+    Z
   ), t = i(0), n = r(() => {
     t.current && (clearTimeout(t.current), t.current = 0);
-  }, []), Q = H(d, M.setReference), s = r(() => {
-    if (n(), l) {
-      const e = Re(d.current);
-      if (!Fe(e)) return;
+  }, []), W = I(f, y.setReference), s = r(() => {
+    if (n(), c) {
+      const e = ye(f.current);
+      if (!he(e)) return;
     }
     o(!0);
-  }, [n, l]), u = r((e) => {
-    const f = e.relatedTarget instanceof Node ? e.relatedTarget : null;
-    f && (d.current?.contains(f) || T.current?.contains(f)) || (t.current = window.setTimeout(() => {
+  }, [n, c]), u = r((e) => {
+    const p = e.relatedTarget instanceof Node ? e.relatedTarget : null;
+    p && (f.current?.contains(p) || R.current?.contains(p)) || (t.current = window.setTimeout(() => {
       o(!1);
     }, 100));
-  }, []), Z = r(() => {
+  }, []), ee = r(() => {
     t.current = window.setTimeout(() => {
       o(!1);
     }, 100);
-  }, []), $ = r(() => {
+  }, []), te = r(() => {
     n(), o(!1);
-  }, [n]), W = Te({
-    userProps: z ? a.props : {},
+  }, [n]), re = Fe({
+    userProps: B ? a.props : {},
     internalProps: {
       onMouseEnter: s,
       onMouseLeave: u,
       onFocus: s,
-      onBlur: Z,
-      onClick: $
+      onBlur: ee,
+      onClick: te
     }
-  }), ee = p(
-    () => ({
+  }), oe = w(
+    () => l ? {
       onMouseEnter: s,
       onMouseLeave: u
-    }),
-    [s, u]
-  ), { trigger: te, id: re } = Ee({
+    } : {},
+    [l, s, u]
+  ), { trigger: ne, id: se } = Me({
     children: a,
-    showOnlyWhenTruncated: l,
-    truncateMaxWidth: L,
-    truncateMaxLines: k,
-    isBlock: B,
-    mergedReferenceRef: Q,
-    mergedEvents: W
+    showOnlyWhenTruncated: c,
+    truncateMaxWidth: P,
+    truncateMaxLines: A,
+    isBlock: C,
+    mergedReferenceRef: W,
+    mergedEvents: re
   });
-  return /* @__PURE__ */ b(oe, { children: [
-    /* @__PURE__ */ m(me, { children: /* @__PURE__ */ m(pe, { mounted: !A && R, children: (e) => /* @__PURE__ */ b(
+  return /* @__PURE__ */ H(ie, { children: [
+    /* @__PURE__ */ g(xe, { children: /* @__PURE__ */ g(we, { mounted: !x && m, children: (e) => /* @__PURE__ */ H(
       "div",
       {
-        id: re,
+        id: se,
         tabIndex: -1,
         role: "tooltip",
-        ref: O,
-        className: h.wgTooltip,
+        ref: $,
+        className: L.wgTooltip,
         ...j,
         style: {
           left: X,
           top: Y,
           ...e,
           ..._,
-          zIndex: S,
-          visibility: x.hide?.referenceHidden ? "hidden" : void 0,
-          pointerEvents: x.hide?.referenceHidden ? "none" : void 0
+          zIndex: Q,
+          visibility: h.hide?.referenceHidden ? "hidden" : void 0,
+          pointerEvents: !l || h.hide?.referenceHidden ? "none" : void 0
         },
-        ...ee,
+        ...oe,
         children: [
-          y,
-          /* @__PURE__ */ m(
-            ve,
+          N,
+          /* @__PURE__ */ g(
+            Re,
             {
               "aria-hidden": "true",
-              ref: E,
-              className: h.wgTooltipArrow,
+              ref: F,
+              className: L.wgTooltipArrow,
               arrowX: J,
               arrowY: K,
-              arrowSize: C,
-              arrowOffset: G,
-              arrowRadius: V,
-              dir: F,
+              arrowSize: G,
+              arrowOffset: V,
+              arrowRadius: O,
+              dir: M,
               placement: q
             }
           )
         ]
       }
     ) }) }),
-    te
+    ne
   ] });
 };
 export {
-  Le as Tooltip
+  Be as Tooltip
 };