@wisdomgarden/torque 0.2.0 → 0.2.2

package/dist/common/is-dev.d.ts

@@ -0,0 +1 @@
+export declare const isDev: () => boolean;

package/dist/common/is-dev.js

@@ -0,0 +1,5 @@
+"use client";
+const e = () => typeof process < "u" && process.env.NODE_ENV !== "production";
+export {
+  e as isDev
+};

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

@@ -12,6 +12,6 @@ export declare function useArrowStyle(withArrow: boolean, arrowData: {
     x?: number;
     y?: number;
 } | undefined, resolvedSide: PopoverSide, arrowSize: number): React.CSSProperties;
-export declare function useTriggerProps(disabled: boolean, trigger: PopoverTrigger, mergedReferenceRef: React.Ref<HTMLElement>, id: string, toggle: () => void, opened: boolean, setOpen: (next: boolean) => void, hoverTimerRef: React.RefObject<number | undefined>, userOnClick?: React.MouseEventHandler<HTMLElement>, userOnKeyDown?: React.KeyboardEventHandler<HTMLElement>): React.HTMLAttributes<HTMLElement> & {
+export declare function useTriggerProps(disabled: boolean, trigger: PopoverTrigger, mergedReferenceRef: React.Ref<HTMLElement>, id: string, toggle: () => void, opened: boolean, setOpen: (next: boolean) => void, scheduleHover: (next: boolean) => void, cancelHoverTimer: () => void, userOnClick?: React.MouseEventHandler<HTMLElement>, userOnKeyDown?: React.KeyboardEventHandler<HTMLElement>): React.HTMLAttributes<HTMLElement> & {
     ref?: React.Ref<HTMLElement>;
 };

package/dist/components/popover/hooks.js

@@ -1,10 +1,10 @@
 "use client";
-import { useEffect as l, useState as m, useRef as b, useCallback as p, useMemo as E } from "react";
-import { registerOpenPopover as y, isTopmostOpenPopover as A } from "./popover-stack.js";
-function L(u, t = !1) {
-  const [n, e] = m(t || u), [r, o] = m(
+import { useEffect as l, useState as b, useRef as p, useCallback as y, useMemo as E } from "react";
+import { registerOpenPopover as A, isTopmostOpenPopover as x } from "./popover-stack.js";
+function k(u, t = !1) {
+  const [n, e] = b(t || u), [r, o] = b(
     u ? "open" : "closing"
-  ), s = b(0);
+  ), s = p(0);
   l(() => (u ? (e(!0), s.current = requestAnimationFrame(() => {
     s.current = requestAnimationFrame(() => {
       o("open");
@@ -12,24 +12,24 @@ function L(u, t = !1) {
   })) : (o("closing"), t && e(!0)), () => {
     s.current && cancelAnimationFrame(s.current);
   }), [t, u]);
-  const i = p(() => {
+  const i = y(() => {
     r === "closing" && !t && e(!1);
   }, [r, t]);
   return { mounted: n, animState: r, handleTransitionEnd: i };
 }
-function P(u, t, n, e, r, o, s, i) {
-  const c = b(null);
+function q(u, t, n, e, r, o, s, i) {
+  const f = p(null);
   l(() => {
-    u === "click" && (t ? c.current = document.activeElement : o().some(
-      (f) => f.contains(document.activeElement)
-    ) && c.current?.focus());
+    u === "click" && (t ? f.current = document.activeElement : o().some(
+      (a) => a.contains(document.activeElement)
+    ) && f.current?.focus());
   }, [t, u, o]), l(() => {
     if (u !== "click" || n !== "open" || !e || i) return;
     if (s?.current) {
       s.current.focus();
       return;
     }
-    (h([r.current])[0] ?? r.current)?.focus();
+    (L([r.current])[0] ?? r.current)?.focus();
   }, [
     n,
     e,
@@ -39,7 +39,7 @@ function P(u, t, n, e, r, o, s, i) {
     i
   ]);
 }
-const x = [
+const h = [
   "a[href]",
   "button:not([disabled])",
   "input:not([disabled])",
@@ -47,27 +47,27 @@ const x = [
   "textarea:not([disabled])",
   '[tabindex]:not([tabindex="-1"])'
 ].join(",");
-function h(u) {
+function L(u) {
   const t = u.flatMap((n) => !n || n.inert || n.getAttribute("aria-hidden") === "true" ? [] : Array.from(
-    n.querySelectorAll(x)
+    n.querySelectorAll(h)
   ));
   return Array.from(new Set(t)).filter(
     (n) => !n.hasAttribute("data-focus-sentinel")
   );
 }
-function C(u, t, n, e, r, o, s) {
+function v(u, t, n, e, r, o, s) {
   l(() => {
     if (t)
-      return y(r, o);
+      return A(r, o);
   }, [o, r, t]), l(() => {
     if (!u || !t) return;
-    const i = (c) => {
-      c.key !== "Escape" || !A(r) || (c.preventDefault(), c.stopImmediatePropagation(), n(), s ? s() : e.current?.focus());
+    const i = (f) => {
+      f.key !== "Escape" || !x(r) || (f.preventDefault(), f.stopImmediatePropagation(), n(), s ? s() : e.current?.focus());
     };
     return document.addEventListener("keydown", i), () => document.removeEventListener("keydown", i);
   }, [u, t, n, e, r, s]);
 }
-function T(u, t, n, e) {
+function B(u, t, n, e) {
   return E(() => {
     if (!u || !t) return {};
     const r = e / 2, o = {
@@ -78,32 +78,31 @@ function T(u, t, n, e) {
     return n === "bottom" ? { ...o, top: -r - 1, left: t.x ?? "", bottom: "" } : n === "top" ? { ...o, bottom: -r - 1, left: t.x ?? "", top: "" } : n === "right" ? { ...o, left: -r - 1, top: t.y ?? "" } : n === "left" ? { ...o, right: -r - 1, top: t.y ?? "" } : o;
   }, [u, t, n, e]);
 }
-function k(u, t, n, e, r, o, s, i, c, f) {
+function F(u, t, n, e, r, o, s, i, f, a, m) {
   return E(() => u ? { ref: n } : t === "none" ? {
     ref: n,
     "aria-expanded": o,
-    onKeyDown: f
+    onKeyDown: m
   } : t === "hover" ? {
     ref: n,
-    onMouseEnter: () => {
-      clearTimeout(i.current), s(!0);
-    },
+    onMouseEnter: () => i(!0),
     onMouseLeave: () => {
-      i.current = window.setTimeout(() => s(!1), 100);
+      o ? i(!1) : f();
     },
-    onFocus: () => s(!0),
-    onBlur: () => {
-      i.current = window.setTimeout(() => s(!1), 100);
+    // 键盘聚焦不走 openDelay：延迟打开对读屏 / 键盘用户只有负作用
+    onFocus: () => {
+      f(), s(!0);
     },
+    onBlur: () => i(!1),
     "aria-describedby": e,
-    onKeyDown: f
+    onKeyDown: m
   } : {
     ref: n,
-    onClick: (a) => {
-      r(), c?.(a);
+    onClick: (c) => {
+      r(), a?.(c);
     },
-    onKeyDown: (a) => {
-      a.key === "Enter" && (a.preventDefault(), r()), f?.(a);
+    onKeyDown: (c) => {
+      c.key === "Enter" && (c.preventDefault(), r()), m?.(c);
     },
     "aria-expanded": o,
     "aria-haspopup": "dialog",
@@ -117,15 +116,16 @@ function k(u, t, n, e, r, o, s, i, c, f) {
     o,
     s,
     i,
-    c,
-    f
+    f,
+    a,
+    m
   ]);
 }
 export {
-  h as getFocusableElements,
-  L as useAnimatedMount,
-  T as useArrowStyle,
-  C as useEscapeClose,
-  P as usePopoverFocus,
-  k as useTriggerProps
+  L as getFocusableElements,
+  k as useAnimatedMount,
+  B as useArrowStyle,
+  v as useEscapeClose,
+  q as usePopoverFocus,
+  F as useTriggerProps
 };

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

@@ -1,6 +1,6 @@
 import { PopoverDropdown } from './popover-dropdown';
 import { PopoverTarget } from './popover-target';
-export declare const Popover: (({ children, position, offset: offsetProp, opened: openedProp, defaultOpened, onOpenChange, disabled, withArrow, arrowSize, trigger, closeOnClickOutside, closeOnEscape, restoreFocus, strategy, initialFocusRef, trapFocus, preventAutoFocus, "aria-labelledby": ariaLabelledby, }: import("./popover.types").PopoverProps) => import("react").JSX.Element) & {
+export declare const Popover: (({ children, position, offset: offsetProp, opened: openedProp, defaultOpened, onOpenChange, disabled, withArrow, arrowSize, trigger, openDelay, closeDelay, closeOnClickOutside, closeOnEscape, restoreFocus, strategy, initialFocusRef, trapFocus, preventAutoFocus, "aria-labelledby": ariaLabelledby, }: import("./popover.types").PopoverProps) => import("react").JSX.Element) & {
     Target: ({ children, ref, onClick, onKeyDown, ...restProps }: import("./popover.types").PopoverTargetProps) => import("react").JSX.Element;
     Dropdown: ({ children, arrowClassName, zIndex, width, maxHeight, matchTargetWidth, radius, withinPortal, keepMounted, ref, ...restProps }: import("./popover.types").PopoverDropdownProps) => import("react").JSX.Element | null;
 };

package/dist/components/popover/popover-dropdown.js

@@ -1,12 +1,12 @@
 "use client";
-import { jsxs as S, jsx as c } from "react/jsx-runtime";
+import { jsxs as E, jsx as c } from "react/jsx-runtime";
 import { getDefaultZIndex as te, Portal as re } from "@mantine/core";
 import { useMergedRef as ne } from "@mantine/hooks";
-import { clsx as I } from "clsx";
+import { clsx as S } from "clsx";
 import { useContext as ie, useRef as ae, useCallback as se } from "react";
-import { useAnimatedMount as de, usePopoverFocus as le, useArrowStyle as ce, getFocusableElements as ue } from "./hooks.js";
-import { PopoverLayerContext as M, usePopoverContext as fe } from "./popover-context.js";
-import T from "./styles/popover.module.css.js";
+import { useAnimatedMount as le, usePopoverFocus as de, useArrowStyle as ce, getFocusableElements as ue } from "./hooks.js";
+import { PopoverLayerContext as I, usePopoverContext as fe } from "./popover-context.js";
+import M from "./styles/popover.module.css.js";
 const Fe = ({
   children: A,
   arrowClassName: C,
@@ -15,56 +15,56 @@ const Fe = ({
   maxHeight: a,
   matchTargetWidth: N = !1,
   radius: z = "sm",
-  withinPortal: L = !0,
-  keepMounted: Z = !1,
-  ref: j,
+  withinPortal: H = !0,
+  keepMounted: L = !1,
+  ref: T,
   ...e
 }) => {
-  const u = ie(M), {
+  const u = ie(I), {
     opened: r,
     trigger: n,
-    strategy: k,
-    x: W,
-    y: $,
+    strategy: Z,
+    x: j,
+    y: k,
     resolvedSide: f,
     middlewareData: s,
-    floatingRef: d,
-    setFloating: H,
+    floatingRef: l,
+    setFloating: W,
     registerNestedFloatingElement: p,
     getFloatingScopeElements: v,
     withArrow: m,
-    arrowSize: O,
+    arrowSize: $,
     arrowRef: P,
-    hoverTimerRef: g,
-    setOpen: V,
-    id: q,
-    initialFocusRef: B,
-    trapFocus: h,
-    preventAutoFocus: G,
-    ariaLabelledby: J
-  } = fe(), { mounted: x, animState: w, handleTransitionEnd: K } = de(
+    scheduleHover: V,
+    cancelHoverTimer: q,
+    id: B,
+    initialFocusRef: G,
+    trapFocus: g,
+    preventAutoFocus: J,
+    ariaLabelledby: K
+  } = fe(), { mounted: h, animState: x, handleTransitionEnd: O } = le(
     r,
-    Z
+    L
   ), y = ae(null), Q = se(
     (o) => {
       y.current?.(), y.current = o ? p(o) : null;
     },
     [p]
   ), U = ne(
-    d,
-    H,
+    l,
+    W,
     Q,
-    j
-  ), l = D ?? (u === null ? te("popover") : u + 1);
-  le(
+    T
+  ), d = D ?? (u === null ? te("popover") : u + 1);
+  de(
     n,
     r,
-    w,
     x,
-    d,
+    h,
+    l,
     v,
-    B,
-    G
+    G,
+    J
   );
   const b = (o) => /* @__PURE__ */ c(
     "span",
@@ -76,7 +76,7 @@ const Fe = ({
       onFocus: () => {
         const i = ue(v());
         if (i.length === 0) {
-          d.current?.focus();
+          l.current?.focus();
           return;
         }
         (o === "start" ? i[i.length - 1] : i[0]).focus();
@@ -86,63 +86,58 @@ const Fe = ({
     m,
     s.arrow,
     f,
-    O
+    $
   ), Y = typeof t == "number" ? `${t}px` : t, _ = t ? Y : void 0, ee = typeof a == "number" ? `${a}px` : a, oe = N ? "var(--t-popover-reference-width)" : _;
-  if (!x) return null;
-  const F = "role" in e ? e.role : n === "click" ? "dialog" : void 0, R = F === "dialog", E = /* @__PURE__ */ S(
+  if (!h) return null;
+  const w = "role" in e ? e.role : n === "click" ? "dialog" : void 0, F = w === "dialog", R = /* @__PURE__ */ E(
     "div",
     {
-      id: q,
-      role: F,
-      "aria-modal": R ? !1 : void 0,
-      "aria-labelledby": R ? J : void 0,
+      id: B,
+      role: w,
+      "aria-modal": F ? !1 : void 0,
+      "aria-labelledby": F ? K : void 0,
       ref: U,
       tabIndex: -1,
-      "data-state": w,
+      "data-state": x,
       "data-radius": z,
       "data-side": f,
       style: {
-        position: k,
-        left: W ?? 0,
-        top: $ ?? 0,
-        zIndex: l,
-        "--t-popover-z": l,
+        position: Z,
+        left: j ?? 0,
+        top: k ?? 0,
+        zIndex: d,
+        "--t-popover-z": d,
         "--t-popover-width": oe,
         "--t-popover-max-height": ee,
         visibility: s.hide?.referenceHidden ? "hidden" : void 0,
         pointerEvents: s.hide?.referenceHidden ? "none" : void 0
       },
-      onTransitionEnd: K,
-      onMouseEnter: n === "hover" ? () => clearTimeout(g.current) : void 0,
-      onMouseLeave: n === "hover" ? () => {
-        g.current = window.setTimeout(
-          () => V(!1),
-          100
-        );
-      } : void 0,
+      onTransitionEnd: O,
+      onMouseEnter: n === "hover" ? () => q() : void 0,
+      onMouseLeave: n === "hover" ? () => V(!1) : void 0,
       ...e,
       "aria-hidden": r ? e["aria-hidden"] : !0,
       inert: r ? e.inert : !0,
-      className: I(T.popover, e.className),
+      className: S(M.popover, e.className),
       children: [
-        /* @__PURE__ */ S(M.Provider, { value: l, children: [
-          h && b("start"),
+        /* @__PURE__ */ E(I.Provider, { value: d, children: [
+          g && b("start"),
           A,
-          h && b("end")
+          g && b("end")
         ] }),
         m && /* @__PURE__ */ c(
           "div",
           {
             ref: P,
             "aria-hidden": "true",
-            className: I(T.arrow, C),
+            className: S(M.arrow, C),
             style: { ...X }
           }
         )
       ]
     }
   );
-  return L ? /* @__PURE__ */ c(re, { children: E }) : E;
+  return H ? /* @__PURE__ */ c(re, { children: R }) : R;
 };
 export {
   Fe as PopoverDropdown

package/dist/components/popover/popover-target.js

@@ -1,39 +1,41 @@
 "use client";
 import { jsx as b } from "react/jsx-runtime";
-import { useMergedRef as v } from "@mantine/hooks";
-import { clsx as T } from "clsx";
+import { useMergedRef as T } from "@mantine/hooks";
+import { clsx as E } from "clsx";
 import r from "react";
-import { useTriggerProps as E } from "./hooks.js";
+import { useTriggerProps as H } from "./hooks.js";
 import { usePopoverContext as N } from "./popover-context.js";
 import P from "./styles/popover.module.css.js";
 const q = ({
   children: e,
   ref: s,
   onClick: m,
-  onKeyDown: f,
+  onKeyDown: i,
   ...o
 }) => {
   const {
-    disabled: i,
-    trigger: n,
-    id: a,
-    toggle: p,
+    disabled: n,
+    trigger: a,
+    id: f,
+    toggle: c,
     opened: l,
-    setOpen: c,
-    hoverTimerRef: g,
-    referenceRef: d,
-    setReference: u
-  } = N(), R = r.isValidElement(e) ? e.props.ref : void 0, x = v(d, u, s, R), t = E(
-    i,
+    setOpen: p,
+    scheduleHover: g,
+    cancelHoverTimer: d,
+    referenceRef: u,
+    setReference: R
+  } = N(), v = r.isValidElement(e) ? e.props.ref : void 0, x = T(u, R, s, v), t = H(
     n,
-    x,
     a,
-    p,
-    l,
+    x,
+    f,
     c,
+    l,
+    p,
     g,
+    d,
     m,
-    f
+    i
   );
   return r.isValidElement(e) ? r.cloneElement(
     e,
@@ -45,7 +47,7 @@ const q = ({
       tabIndex: 0,
       ...t,
       ...o,
-      className: T(P.fallbackTarget, o.className),
+      className: E(P.fallbackTarget, o.className),
       children: e
     }
   );

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

@@ -1,3 +1,3 @@
 import React from 'react';
 import { PopoverProps } from './popover.types';
-export declare const Popover: ({ children, position, offset: offsetProp, opened: openedProp, defaultOpened, onOpenChange, disabled, withArrow, arrowSize, trigger, closeOnClickOutside, closeOnEscape, restoreFocus, strategy, initialFocusRef, trapFocus, preventAutoFocus, "aria-labelledby": ariaLabelledby, }: PopoverProps) => React.JSX.Element;
+export declare const Popover: ({ children, position, offset: offsetProp, opened: openedProp, defaultOpened, onOpenChange, disabled, withArrow, arrowSize, trigger, openDelay, closeDelay, closeOnClickOutside, closeOnEscape, restoreFocus, strategy, initialFocusRef, trapFocus, preventAutoFocus, "aria-labelledby": ariaLabelledby, }: PopoverProps) => React.JSX.Element;

package/dist/components/popover/popover.js

@@ -1,175 +1,201 @@
 "use client";
-import { jsx as ne } from "react/jsx-runtime";
-import { offset as oe, flip as se, size as re, shift as le, limitShift as ce, arrow as ae, hide as ie, useFloating as de, autoUpdate as ue } from "@floating-ui/react-dom";
-import { useDirection as fe, getFloatingPosition as pe } from "@mantine/core";
-import _, { useRef as l, useId as me, useCallback as c, useEffect as ge, useMemo as q } from "react";
-import { useEscapeClose as ve } from "./hooks.js";
-import { PopoverContext as A } from "./popover-context.js";
-const g = 8, ye = ({
-  children: B,
-  position: H = "bottom",
-  offset: y = 8,
-  opened: C,
-  defaultOpened: J = !1,
-  onOpenChange: N,
-  disabled: b = !1,
-  withArrow: r = !1,
-  arrowSize: a = 8,
-  trigger: D = "click",
-  closeOnClickOutside: I = !0,
-  closeOnEscape: K = !0,
-  restoreFocus: Q,
-  strategy: v = "absolute",
-  initialFocusRef: L,
-  trapFocus: M = !1,
-  preventAutoFocus: S = !1,
-  "aria-labelledby": $
+import { jsx as le } from "react/jsx-runtime";
+import { offset as ae, flip as de, size as ue, shift as fe, limitShift as me, arrow as pe, hide as he, useFloating as ve, autoUpdate as ge } from "@floating-ui/react-dom";
+import { useDirection as Ee, getFloatingPosition as we } from "@mantine/core";
+import K, { useRef as c, useId as xe, useCallback as r, useEffect as D, useMemo as Q } from "react";
+import { isDev as Pe } from "../../common/is-dev.js";
+import { useEscapeClose as Re } from "./hooks.js";
+import { PopoverContext as W } from "./popover-context.js";
+const w = 8, Ie = ({
+  children: X,
+  position: Y = "bottom",
+  offset: N = 8,
+  opened: T,
+  defaultOpened: Z = !1,
+  onOpenChange: u,
+  disabled: I = !1,
+  withArrow: l = !1,
+  arrowSize: f = 8,
+  trigger: a = "click",
+  openDelay: L = 0,
+  closeDelay: M = 100,
+  closeOnClickOutside: $ = !0,
+  closeOnEscape: z = !0,
+  restoreFocus: ee,
+  strategy: x = "absolute",
+  initialFocusRef: S,
+  trapFocus: G = !1,
+  preventAutoFocus: H = !1,
+  "aria-labelledby": j
 }) => {
-  const h = _.useContext(A), G = h?.registerNestedFloatingElement, x = h ? h.depth + 1 : 0, E = C !== void 0, [W, X] = _.useState(J), t = E ? C : W, i = l(null), d = l(null), u = l(null), R = l(/* @__PURE__ */ new Set()), T = l(0), F = me(), { dir: Y } = fe(), o = c(
+  const P = K.useContext(W), k = P?.registerNestedFloatingElement, R = P ? P.depth + 1 : 0, d = T !== void 0, [te, ne] = K.useState(Z), o = d ? T : te, m = c(null), p = c(null), h = c(null), y = c(/* @__PURE__ */ new Set()), F = c(void 0), b = xe(), { dir: oe } = Ee(), n = r(
     (e) => {
-      E || X(e), N?.(e);
+      d || ne(e), u?.(e);
     },
-    [E, N]
-  ), P = c(() => o(!1), [o]), j = c(() => o(!t), [t, o]), k = c(
+    [d, u]
+  ), C = r(() => n(!1), [n]), q = r(() => n(!o), [o, n]), s = r(() => {
+    window.clearTimeout(F.current), F.current = void 0;
+  }, []), O = r(
     (e) => {
-      R.current.add(e);
-      const n = G?.(e);
+      s();
+      const t = e ? L : M;
+      if (t <= 0) {
+        n(e);
+        return;
+      }
+      F.current = window.setTimeout(() => n(e), t);
+    },
+    [s, L, M, n]
+  );
+  D(() => s, [s]);
+  const U = c(!1);
+  D(() => {
+    !Pe() || U.current || !d || a === "none" || u || (U.current = !0, console.warn(
+      `[@wisdomgarden/torque] <Popover trigger="${a}"> 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.`
+    ));
+  }, [d, a, u]);
+  const V = r(
+    (e) => {
+      y.current.add(e);
+      const t = k?.(e);
       return () => {
-        R.current.delete(e), n?.();
+        y.current.delete(e), t?.();
       };
     },
-    [G]
-  ), f = c(() => {
-    const e = u.current ? [u.current] : [];
-    return R.current.forEach((n) => {
-      n.isConnected && e.push(n);
+    [k]
+  ), v = r(() => {
+    const e = h.current ? [h.current] : [];
+    return y.current.forEach((t) => {
+      t.isConnected && e.push(t);
     }), Array.from(new Set(e));
   }, []);
-  ge(() => {
-    if (!I || !t) return;
-    const e = (n) => {
-      const m = n.composedPath(), s = d.current;
-      s && m.includes(s) || f().some((te) => m.includes(te)) || P();
+  D(() => {
+    if (!$ || !o) return;
+    const e = (t) => {
+      const E = t.composedPath(), i = p.current;
+      i && E.includes(i) || v().some((ce) => E.includes(ce)) || C();
     };
     return document.addEventListener("mousedown", e, !0), document.addEventListener("touchstart", e, !0), () => {
       document.removeEventListener("mousedown", e, !0), document.removeEventListener("touchstart", e, !0);
     };
-  }, [I, t, P, f]), ve(
-    K,
-    t,
-    P,
-    d,
-    F,
-    x,
-    Q
+  }, [$, o, C, v]), Re(
+    z,
+    o,
+    C,
+    p,
+    b,
+    R,
+    ee
   );
-  const Z = q(
+  const re = Q(
     () => [
-      oe(y + (r ? a / 2 : 0)),
-      se({ padding: g }),
+      ae(N + (l ? f / 2 : 0)),
+      de({ padding: w }),
       // 必须在 shift 之前：否则 availableHeight 是 shift 推动后的位置算出的（≈整屏），高度约束失效
-      re({
-        padding: g,
-        apply({ availableWidth: e, availableHeight: n, rects: m, elements: s }) {
-          s.floating.style.setProperty(
+      ue({
+        padding: w,
+        apply({ availableWidth: e, availableHeight: t, rects: E, elements: i }) {
+          i.floating.style.setProperty(
             "--t-popover-available-width",
             `${Math.max(0, e)}px`
-          ), s.floating.style.setProperty(
+          ), i.floating.style.setProperty(
             "--t-popover-available-height",
-            `${Math.max(0, n)}px`
-          ), s.floating.style.setProperty(
+            `${Math.max(0, t)}px`
+          ), i.floating.style.setProperty(
             "--t-popover-reference-width",
-            `${m.reference.width}px`
+            `${E.reference.width}px`
           );
         }
       }),
-      le({
-        padding: g,
+      fe({
+        padding: w,
         crossAxis: !0,
         mainAxis: !0,
-        limiter: ce()
+        limiter: me()
       }),
-      ...r ? (
+      ...l ? (
         // floating-ui 的 arrow 中间件按设计就是收一个 ref 对象（它在定位阶段自己读
         // .current），不是我们在渲染期读 ref 的值。没有保留该 API 的改写方式。
         // eslint-disable-next-line react-hooks/refs
-        [ae({ element: i, padding: g })]
+        [pe({ element: m, padding: w })]
       ) : [],
-      ie()
+      he()
     ],
-    [y, r, a, i]
+    [N, l, f, m]
   ), {
-    x: w,
-    y: O,
-    refs: p,
-    placement: z,
-    middlewareData: U
-  } = de({
-    open: t,
-    strategy: v,
-    placement: pe(Y, H),
-    middleware: Z,
-    whileElementsMounted: ue
-  }), V = z.split("-")[0], ee = q(
+    x: _,
+    y: A,
+    refs: g,
+    placement: se,
+    middlewareData: B
+  } = ve({
+    open: o,
+    strategy: x,
+    placement: we(oe, Y),
+    middleware: re,
+    whileElementsMounted: ge
+  }), J = se.split("-")[0], ie = Q(
     () => ({
-      opened: t,
-      setOpen: o,
-      toggle: j,
-      trigger: D,
-      disabled: b,
-      id: F,
-      withArrow: r,
-      arrowSize: a,
-      x: w,
-      y: O,
-      strategy: v,
-      resolvedSide: V,
-      middlewareData: U,
-      hoverTimerRef: T,
-      referenceRef: d,
-      floatingRef: u,
-      arrowRef: i,
-      setReference: p.setReference,
-      setFloating: p.setFloating,
-      depth: x,
-      registerNestedFloatingElement: k,
-      getFloatingScopeElements: f,
-      initialFocusRef: L,
-      trapFocus: M,
-      preventAutoFocus: S,
-      ariaLabelledby: $
+      opened: o,
+      setOpen: n,
+      toggle: q,
+      trigger: a,
+      disabled: I,
+      id: b,
+      withArrow: l,
+      arrowSize: f,
+      x: _,
+      y: A,
+      strategy: x,
+      resolvedSide: J,
+      middlewareData: B,
+      scheduleHover: O,
+      cancelHoverTimer: s,
+      referenceRef: p,
+      floatingRef: h,
+      arrowRef: m,
+      setReference: g.setReference,
+      setFloating: g.setFloating,
+      depth: R,
+      registerNestedFloatingElement: V,
+      getFloatingScopeElements: v,
+      initialFocusRef: S,
+      trapFocus: G,
+      preventAutoFocus: H,
+      ariaLabelledby: j
     }),
     [
-      t,
       o,
-      j,
-      D,
-      b,
-      F,
-      r,
+      n,
+      q,
       a,
-      w,
+      I,
+      b,
+      l,
+      f,
+      _,
+      A,
+      x,
+      J,
+      B,
       O,
-      v,
+      s,
+      p,
+      h,
+      m,
+      g.setReference,
+      g.setFloating,
+      R,
       V,
-      U,
-      T,
-      d,
-      u,
-      i,
-      p.setReference,
-      p.setFloating,
-      x,
-      k,
-      f,
-      L,
-      M,
+      v,
       S,
-      $
+      G,
+      H,
+      j
     ]
   );
-  return /* @__PURE__ */ ne(A.Provider, { value: ee, children: B });
+  return /* @__PURE__ */ le(W.Provider, { value: ie, children: X });
 };
 export {
-  ye as Popover
+  Ie 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;
     /**
@@ -55,6 +60,22 @@ export interface PopoverProps {
      * @default 'click'
      */
     trigger?: PopoverTrigger;
+    /**
+     * hover 打开延迟（ms），0 表示立即打开。
+     * 仅 `trigger="hover"` 的鼠标移入生效；键盘聚焦始终立即打开。
+     * @default 0
+     */
+    openDelay?: number;
+    /**
+     * hover 关闭延迟（ms），留出鼠标从触发元素移动到浮层的时间。
+     * 仅 `trigger="hover"` 生效。
+     *
+     * 设为 `0` 即取消这段缓冲：鼠标离开触发元素就同步关闭，够不到浮层，键盘也 Tab 不进去。
+     * 想要「只给看、不给进一步操作」的富文本 tooltip 就该设 `0`，但浮层内容必须纯展示；
+     * 浮层内有可交互内容时不要设 `0`。
+     * @default 100
+     */
+    closeDelay?: number;
     /**
      * 点击外部区域时关闭
      * @default true
@@ -188,7 +209,10 @@ export interface PopoverContextValue {
             escaped?: boolean;
         };
     };
-    hoverTimerRef: React.MutableRefObject<number | undefined>;
+    /** hover 触发的延迟开关调度：同一时刻只保留一个待执行任务，延迟为 0 时同步执行 */
+    scheduleHover: (next: boolean) => void;
+    /** 取消尚未执行的 hover 开关任务 */
+    cancelHoverTimer: () => void;
     referenceRef: React.RefObject<HTMLElement | null>;
     floatingRef: React.RefObject<HTMLDivElement | null>;
     arrowRef: React.RefObject<HTMLDivElement | null>;

package/dist/provider/hooks.js

@@ -1,26 +1,27 @@
 "use client";
 import { useContext as n } from "react";
-import { UiContext as r } from "./ui-context.js";
-const c = () => typeof process < "u" && process.env.NODE_ENV !== "production", t = () => n(r), d = () => t().locale, u = () => {
+import { isDev as r } from "../common/is-dev.js";
+import { UiContext as a } from "./ui-context.js";
+const t = () => n(a), u = () => t().locale, p = () => {
   const { deviceType: e } = t();
   return { deviceType: e };
-}, p = () => {
+}, v = () => {
   const { deviceType: e } = t();
   return {
     isMobile: e === "mobile",
     isTablet: e === "tablet",
     isDesktop: e === "desktop"
   };
-}, o = /* @__PURE__ */ new Set(), v = (e) => {
-  const { linkComponent: s, hasProvider: i } = t();
-  return c() && !i && !o.has(e) && (o.add(e), console.warn(
+}, o = /* @__PURE__ */ new Set(), f = (e) => {
+  const { linkComponent: i, hasProvider: s } = t();
+  return r() && !s && !o.has(e) && (o.add(e), console.warn(
     `[@wisdomgarden/torque] <${e}> rendered outside <UiProvider>, falling back to a plain <a>. On a host with a router this silently turns client-side navigation into a full page load.`
-  )), s;
+  )), i;
 };
 export {
-  p as useCheckDevice,
-  u as useDeviceType,
-  d as useLocale,
+  v as useCheckDevice,
+  p as useDeviceType,
+  u as useLocale,
   t as useUiContext,
-  v as useUiLink
+  f as useUiLink
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wisdomgarden/torque",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Torque Design — Wisdom Garden's base UI component library for React.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",