@neut/ui 0.0.8 → 0.0.10

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

@@ -1 +1,34 @@
-export declare const TooltipArrow: () => import("solid-js").JSX.Element;
+export interface TooltipArrowProps {
+    /** 箭头沿 tooltip 边缘方向的长度（像素），默认 8 */
+    width?: number;
+    /** 箭头突出的深度（像素），默认 4 */
+    height?: number;
+    /**
+     * 箭头颜色（Tailwind text-* class，因为 SVG 用 fill="currentColor"）。
+     * 不传的话默认跟 TooltipContent 的默认背景色一致；如果你自定义了
+     * TooltipContent 的背景色，记得这里也传一个匹配的颜色，两者不会自动同步。
+     */
+    class?: string;
+}
+/**
+ * 箭头组件，必须渲染在 <TooltipContent> 内部（依赖它的 context）。
+ * 通过 context 拿到 arrow middleware 算出的偏移量，以及最终生效的 placement，
+ * 从而知道该贴哪条边、三角形尖端朝哪个方向。
+ *
+ * 四个方向用四套独立坐标画三角形，而不是画一个形状再用 CSS rotate 复用——
+ * 这是有意的：arrow middleware 用 el.offsetWidth/offsetHeight 判断"沿边长度"，
+ * 而 CSS transform 不会改变这两个值，如果靠 rotate(90deg) 让同一个 8x4 的形状
+ * "看起来"变成 4x8，offsetWidth/offsetHeight 读到的还是旋转前的 8x4，
+ * 会导致 left/right 方向的偏移计算对不上。直接让未旋转的 SVG 本身尺寸
+ * 就随方向切换（沿边方向用 width，突出方向用 height），从根上避免这个偏差。
+ *
+ * 进出场动画是箭头自己独立播放的一份（data-state + animate-in/out），
+ * 和 TooltipContent 内层元素用的是同一个 animationState 信号驱动，
+ * 保证两者严格同步开始/结束——而不是让箭头被动继承内层元素的动画。
+ * 后者看似更省事，但内层元素的 zoom-in-95 动画会给它加一个非 none 的
+ * transform，CSS 规范规定这会让内层变成子元素新的"包含块"，这和箭头
+ * 故意跳过内层、以外层为基准定位的设计（避免触发滚动条那次的修复）相冲突，
+ * 动画播放期间"父子两层谁负责定位"这个假设会变得不可靠，箭头容易之前观察到
+ * "入场看起来比内容慢一拍"这类问题。独立播放同一份动画彻底避开这个耦合。
+ */
+export declare function TooltipArrow(props: TooltipArrowProps): import("solid-js").JSX.Element;

package/dist/components/tooltip/TooltipArrow/TooltipArrow.js

@@ -1,22 +1,58 @@
 import { clsx as e } from "../../../utils/clsx.js";
-import { useTooltipContext as t } from "../Tooltip/Tooltip.context.js";
-import { useTooltipContentContext as n } from "../TooltipContent/TooltipContent.context.js";
-import { className as r, effect as i, setAttribute as a, setStyleProperty as o, template as s } from "solid-js/web";
+import { useTooltipContentContext as t } from "../TooltipContent/TooltipContent.context.js";
+import { effect as n, setAttribute as r, style as i, template as a, use as o } from "solid-js/web";
 //#region src/components/tooltip/TooltipArrow/TooltipArrow.tsx
-var c = /* @__PURE__ */ s("<div>"), l = () => {
-	let { triggerRef: s } = t(), { side: l, align: u } = n(), d = () => s?.offsetWidth ?? 0;
+var s = /*#__PURE__*/ a("<svg aria-hidden=true><polygon fill=currentColor>");
+function c(a) {
+	let c = t("TooltipArrow"), l = () => a.width ?? 8, u = () => a.height ?? 4, d = () => c.placement().split("-")[0], f = () => d() === "top" || d() === "bottom", p = () => c.middlewareData().arrow, m = () => {
+		let e = l(), t = u();
+		switch (d()) {
+			case "top": return `0,0 ${e},0 ${e / 2},${t}`;
+			case "bottom": return `0,${t} ${e},${t} ${e / 2},0`;
+			case "left": return `0,0 0,${e} ${t},${e / 2}`;
+			default: return `${t},0 ${t},${e} 0,${e / 2}`;
+		}
+	}, h = () => {
+		let e = u(), t = f() ? p()?.x ?? 0 : p()?.y ?? 0;
+		switch (d()) {
+			case "top": return {
+				bottom: `-${e}px`,
+				left: `${t}px`
+			};
+			case "bottom": return {
+				top: `-${e}px`,
+				left: `${t}px`
+			};
+			case "left": return {
+				right: `-${e}px`,
+				top: `${t}px`
+			};
+			default: return {
+				left: `-${e}px`,
+				top: `${t}px`
+			};
+		}
+	};
 	return (() => {
-		var t = c();
-		return a(t, "data-side", l), a(t, "data-align", u), i((n) => {
-			var i = e("absolute size-2.5 z-50 translate-y-[calc(-50%-2px)] rotate-45 rounded-xs bg-neutral-950 dark:bg-neutral-50 fill-neutral-950 dark:fill-neutral-50", "data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2", "data-[side=left]:top-1/2! data-[side=left]:right-[-0.175rem] data-[side=left]:-translate-y-1/2", "data-[side=right]:top-1/2! data-[side=right]:left-[-0.175rem] data-[side=right]:-translate-y-1/2", "data-[side=top]:-bottom-2.5 data-[side=top]:data-[align=center]:left-1/2 data-[side=top]:data-[align=center]:-translate-x-1/2 data-[side=top]:data-[align=start]:left-(--arrow-offset) data-[side=top]:data-[align=start]:-translate-x-1/2 data-[side=top]:data-[align=end]:right-(--arrow-offset) data-[side=top]:data-[align=end]:translate-x-1/2", "data-[side=bottom]:top-1 data-[side=bottom]:data-[align=center]:left-1/2 data-[side=bottom]:data-[align=center]:-translate-x-1/2 data-[side=bottom]:data-[align=start]:left-(--arrow-offset) data-[side=bottom]:data-[align=start]:-translate-x-1/2 data-[side=bottom]:data-[align=end]:right-(--arrow-offset) data-[side=bottom]:data-[align=end]:translate-x-1/2"), a = `${d() / 2}px`;
-			return i !== n.e && r(t, n.e = i), a !== n.t && o(t, "--arrow-offset", n.t = a), n;
+		var t = s(), d = t.firstChild, p = c.setArrowElement;
+		return typeof p == "function" ? o(p, t) : c.setArrowElement = t, n((n) => {
+			var o = f() ? l() : u(), s = f() ? u() : l(), p = f() ? `0 0 ${l()} ${u()}` : `0 0 ${u()} ${l()}`, g = c.animationState(), _ = {
+				position: "absolute",
+				...h()
+			}, v = e("data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95", "text-foreground", a.class), y = m();
+			return o !== n.e && r(t, "width", n.e = o), s !== n.t && r(t, "height", n.t = s), p !== n.a && r(t, "viewBox", n.a = p), g !== n.o && r(t, "data-state", n.o = g), n.i = i(t, _, n.i), v !== n.n && r(t, "class", n.n = v), y !== n.s && r(d, "points", n.s = y), n;
 		}, {
 			e: void 0,
-			t: void 0
+			t: void 0,
+			a: void 0,
+			o: void 0,
+			i: void 0,
+			n: void 0,
+			s: void 0
 		}), t;
 	})();
-};
+}
 //#endregion
-export { l as TooltipArrow };
+export { c as TooltipArrow };
 
 //# sourceMappingURL=TooltipArrow.js.map

package/dist/components/tooltip/TooltipArrow/TooltipArrow.js.map

@@ -1 +1 @@
-{"version":3,"file":"TooltipArrow.js","names":["clsx","useTooltipContentContext","useTooltipContext","TooltipArrow","triggerRef","side","align","triggerWidth","offsetWidth","_el$","_tmpl$","_$setAttribute","_$effect","_p$","_v$","_v$2","e","_$className","t","_$setStyleProperty","undefined"],"sources":["../../../../src/components/tooltip/TooltipArrow/TooltipArrow.tsx"],"sourcesContent":["import { clsx } from \"~/utils\";\nimport { useTooltipContentContext } from \"../TooltipContent/TooltipContent.context\";\nimport { useTooltipContext } from \"../Tooltip/Tooltip.context\";\n\nexport const TooltipArrow = () => {\n  const { triggerRef } = useTooltipContext();\n  const { side, align } = useTooltipContentContext();\n\n  const triggerWidth = () => triggerRef?.offsetWidth ?? 0;\n\n  return (\n    <div\n      // ref={setup}\n      data-side={side}\n      data-align={align}\n      class={clsx(\n        \"absolute size-2.5 z-50 translate-y-[calc(-50%-2px)] rotate-45 rounded-xs bg-neutral-950 dark:bg-neutral-50 fill-neutral-950 dark:fill-neutral-50\",\n        \"data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2\",\n        \"data-[side=left]:top-1/2! data-[side=left]:right-[-0.175rem] data-[side=left]:-translate-y-1/2\",\n        \"data-[side=right]:top-1/2! data-[side=right]:left-[-0.175rem] data-[side=right]:-translate-y-1/2\",\n        \"data-[side=top]:-bottom-2.5 data-[side=top]:data-[align=center]:left-1/2 data-[side=top]:data-[align=center]:-translate-x-1/2 data-[side=top]:data-[align=start]:left-(--arrow-offset) data-[side=top]:data-[align=start]:-translate-x-1/2 data-[side=top]:data-[align=end]:right-(--arrow-offset) data-[side=top]:data-[align=end]:translate-x-1/2\",\n        \"data-[side=bottom]:top-1 data-[side=bottom]:data-[align=center]:left-1/2 data-[side=bottom]:data-[align=center]:-translate-x-1/2 data-[side=bottom]:data-[align=start]:left-(--arrow-offset) data-[side=bottom]:data-[align=start]:-translate-x-1/2 data-[side=bottom]:data-[align=end]:right-(--arrow-offset) data-[side=bottom]:data-[align=end]:translate-x-1/2\",\n      )}\n      style={{\n        \"--arrow-offset\": `${triggerWidth() / 2}px`,\n      }}\n    />\n  );\n};\n"],"mappings":";;;;;oCAIaG,UAAqB;CAChC,IAAM,EAAEC,kBAAeF,GAAmB,EACpC,EAAEG,SAAMC,aAAUL,GAA0B,EAE5CM,UAAqBH,GAAYI,eAAe;AAEtD,eAAA;EAAA,IAAAC,IAAAC,GAAA;AAciD,SAdjDC,EAAAF,GAAA,aAGeJ,EAAI,EAAAM,EAAAF,GAAA,cACHH,EAAK,EAAAM,GAAAC,MAAA;GAAA,IAAAC,IACVd,EACL,oJACA,wNACA,kGACA,oGACA,uVACA,qWACD,EAAAe,IAEmB,GAAGR,GAAc,GAAG,EAAC;AAAI,UAAAO,MAAAD,EAAAG,KAAAC,EAAAR,GAAAI,EAAAG,IAAAF,EAAA,EAAAC,MAAAF,EAAAK,KAAAC,EAAAV,GAAA,kBAAAI,EAAAK,IAAAH,EAAA,EAAAF;KAAA;GAAAG,GAAAI,KAAAA;GAAAF,GAAAE,KAAAA;GAAA,CAAA,EAAAX;KAAA"}
+{"version":3,"file":"TooltipArrow.js","names":["clsx","useTooltipContentContext","TooltipArrowProps","width","height","class","TooltipArrow","props","ctx","alongLen","protrusion","side","placement","split","isVertical","arrowData","middlewareData","arrow","x","y","points","a","p","positionStyle","crossOffset","bottom","left","top","right","_el$","_tmpl$","_el$2","firstChild","_ref$","setArrowElement","_$use","_$effect","_p$","_v$","_v$2","_v$3","_v$4","animationState","_v$5","position","_v$6","_v$7","e","_$setAttribute","t","o","i","_$style","n","s","undefined"],"sources":["../../../../src/components/tooltip/TooltipArrow/TooltipArrow.tsx"],"sourcesContent":["import { clsx } from \"~/utils\";\nimport { useTooltipContentContext } from \"../TooltipContent/TooltipContent.context\";\n\nexport interface TooltipArrowProps {\n  /** 箭头沿 tooltip 边缘方向的长度（像素），默认 8 */\n  width?: number;\n  /** 箭头突出的深度（像素），默认 4 */\n  height?: number;\n  /**\n   * 箭头颜色（Tailwind text-* class，因为 SVG 用 fill=\"currentColor\"）。\n   * 不传的话默认跟 TooltipContent 的默认背景色一致；如果你自定义了\n   * TooltipContent 的背景色，记得这里也传一个匹配的颜色，两者不会自动同步。\n   */\n  class?: string;\n}\n\n/**\n * 箭头组件，必须渲染在 <TooltipContent> 内部（依赖它的 context）。\n * 通过 context 拿到 arrow middleware 算出的偏移量，以及最终生效的 placement，\n * 从而知道该贴哪条边、三角形尖端朝哪个方向。\n *\n * 四个方向用四套独立坐标画三角形，而不是画一个形状再用 CSS rotate 复用——\n * 这是有意的：arrow middleware 用 el.offsetWidth/offsetHeight 判断\"沿边长度\"，\n * 而 CSS transform 不会改变这两个值，如果靠 rotate(90deg) 让同一个 8x4 的形状\n * \"看起来\"变成 4x8，offsetWidth/offsetHeight 读到的还是旋转前的 8x4，\n * 会导致 left/right 方向的偏移计算对不上。直接让未旋转的 SVG 本身尺寸\n * 就随方向切换（沿边方向用 width，突出方向用 height），从根上避免这个偏差。\n *\n * 进出场动画是箭头自己独立播放的一份（data-state + animate-in/out），\n * 和 TooltipContent 内层元素用的是同一个 animationState 信号驱动，\n * 保证两者严格同步开始/结束——而不是让箭头被动继承内层元素的动画。\n * 后者看似更省事，但内层元素的 zoom-in-95 动画会给它加一个非 none 的\n * transform，CSS 规范规定这会让内层变成子元素新的\"包含块\"，这和箭头\n * 故意跳过内层、以外层为基准定位的设计（避免触发滚动条那次的修复）相冲突，\n * 动画播放期间\"父子两层谁负责定位\"这个假设会变得不可靠，箭头容易之前观察到\n * \"入场看起来比内容慢一拍\"这类问题。独立播放同一份动画彻底避开这个耦合。\n */\nexport function TooltipArrow(props: TooltipArrowProps) {\n  const ctx = useTooltipContentContext(\"TooltipArrow\");\n\n  const alongLen = () => props.width ?? 8;\n  const protrusion = () => props.height ?? 4;\n\n  const side = () =>\n    ctx.placement().split(\"-\")[0] as \"top\" | \"bottom\" | \"left\" | \"right\";\n  const isVertical = () => side() === \"top\" || side() === \"bottom\";\n\n  const arrowData = () =>\n    ctx.middlewareData().arrow as { x?: number; y?: number } | undefined;\n\n  const points = () => {\n    const a = alongLen();\n    const p = protrusion();\n    switch (side()) {\n      case \"top\":\n        return `0,0 ${a},0 ${a / 2},${p}`; // 尖端朝下，指向下方的 trigger\n      case \"bottom\":\n        return `0,${p} ${a},${p} ${a / 2},0`; // 尖端朝上\n      case \"left\":\n        return `0,0 0,${a} ${p},${a / 2}`; // 尖端朝右\n      default:\n        return `${p},0 ${p},${a} 0,${a / 2}`; // 尖端朝左\n    }\n  };\n\n  const positionStyle = () => {\n    const p = protrusion();\n    const crossOffset = isVertical()\n      ? (arrowData()?.x ?? 0)\n      : (arrowData()?.y ?? 0);\n    switch (side()) {\n      case \"top\":\n        return { bottom: `-${p}px`, left: `${crossOffset}px` };\n      case \"bottom\":\n        return { top: `-${p}px`, left: `${crossOffset}px` };\n      case \"left\":\n        return { right: `-${p}px`, top: `${crossOffset}px` };\n      default:\n        return { left: `-${p}px`, top: `${crossOffset}px` };\n    }\n  };\n\n  return (\n    <svg\n      ref={ctx.setArrowElement}\n      width={isVertical() ? alongLen() : protrusion()}\n      height={isVertical() ? protrusion() : alongLen()}\n      viewBox={\n        isVertical()\n          ? `0 0 ${alongLen()} ${protrusion()}`\n          : `0 0 ${protrusion()} ${alongLen()}`\n      }\n      data-state={ctx.animationState()}\n      style={{ position: \"absolute\", ...positionStyle() }}\n      class={clsx(\n        \"data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95\",\n        \"text-foreground\",\n        props.class,\n      )}\n      aria-hidden=\"true\"\n    >\n      <polygon points={points()} fill=\"currentColor\" />\n    </svg>\n  );\n}\n"],"mappings":"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"}

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

@@ -1 +1,2 @@
 export { TooltipArrow } from './TooltipArrow';
+export type { TooltipArrowProps } from './TooltipArrow';

package/dist/components/tooltip/TooltipContent/TooltipContent.context.d.ts

@@ -1,7 +1,21 @@
-interface TooltipContentContextValue {
-    side: "top" | "bottom" | "left" | "right";
-    align: "start" | "center" | "end";
+import { Accessor } from 'solid-js';
+import { MiddlewareData, Placement } from '../../../lib';
+export interface TooltipContentContextValue {
+    /** createPositioner 产出的 middlewareData，TooltipArrow 从里面取 arrow 中间件算好的偏移量 */
+    middlewareData: Accessor<MiddlewareData>;
+    /** 经过 flip 调整后的最终 placement，决定箭头贴哪条边、朝哪个方向 */
+    placement: Accessor<Placement>;
+    /** TooltipArrow 挂载时用来把自己的 DOM 节点注册给 arrow middleware（Element 而不是 HTMLElement，兼容 SVG 箭头） */
+    setArrowElement: (el: Element) => void;
+    /**
+     * 驱动进出场动画的状态，和 TooltipContent 内层元素的 data-state 用的是
+     * 同一个信号——TooltipArrow 应该用它独立播放自己的一份动画，而不是依赖
+     * "作为内层元素的子节点、被动继承内层的 transform/opacity 动画"这种隐式
+     * 机制（内层的 zoom-in-95 动画会给它加一个非 none 的 transform，CSS 规范
+     * 规定这会让内层变成子元素新的"包含块"，和箭头故意跳过内层、以外层为
+     * 基准的设计相冲突，动画播放期间会让"父子两层谁负责什么"变得不可靠）。
+     */
+    animationState: Accessor<"open" | "closed">;
 }
 export declare const TooltipContentContext: import('solid-js').Context<TooltipContentContextValue | undefined>;
-export declare function useTooltipContentContext(): TooltipContentContextValue;
-export {};
+export declare function useTooltipContentContext(component: string): TooltipContentContextValue;

package/dist/components/tooltip/TooltipContent/TooltipContent.context.js

@@ -1,10 +1,10 @@
 import { createContext as e, useContext as t } from "solid-js";
 //#region src/components/tooltip/TooltipContent/TooltipContent.context.ts
 var n = e();
-function r() {
-	let e = t(n);
-	if (!e) throw Error("useTooltipContentContext must be used within TooltipContent");
-	return e;
+function r(e) {
+	let r = t(n);
+	if (!r) throw Error(`<${e}> 必须渲染在 <TooltipContent> 内部`);
+	return r;
 }
 //#endregion
 export { n as TooltipContentContext, r as useTooltipContentContext };

package/dist/components/tooltip/TooltipContent/TooltipContent.context.js.map

@@ -1 +1 @@
-{"version":3,"file":"TooltipContent.context.js","names":[],"sources":["../../../../src/components/tooltip/TooltipContent/TooltipContent.context.ts"],"sourcesContent":["import { createContext, useContext } from \"solid-js\";\n\ninterface TooltipContentContextValue {\n  side: \"top\" | \"bottom\" | \"left\" | \"right\";\n  align: \"start\" | \"center\" | \"end\";\n}\n\nexport const TooltipContentContext =\n  createContext<TooltipContentContextValue>();\n\nexport function useTooltipContentContext() {\n  const ctx = useContext(TooltipContentContext);\n  if (!ctx)\n    throw new Error(\n      \"useTooltipContentContext must be used within TooltipContent\",\n    );\n  return ctx;\n}\n"],"mappings":";;AAOA,IAAa,IACX,GAA2C;AAE7C,SAAgB,IAA2B;CACzC,IAAM,IAAM,EAAW,EAAsB;AAC7C,KAAI,CAAC,EACH,OAAU,MACR,8DACD;AACH,QAAO"}
+{"version":3,"file":"TooltipContent.context.js","names":[],"sources":["../../../../src/components/tooltip/TooltipContent/TooltipContent.context.ts"],"sourcesContent":["import { createContext, useContext, type Accessor } from \"solid-js\";\nimport type { MiddlewareData, Placement } from \"~/lib\";\n\nexport interface TooltipContentContextValue {\n  /** createPositioner 产出的 middlewareData，TooltipArrow 从里面取 arrow 中间件算好的偏移量 */\n  middlewareData: Accessor<MiddlewareData>;\n  /** 经过 flip 调整后的最终 placement，决定箭头贴哪条边、朝哪个方向 */\n  placement: Accessor<Placement>;\n  /** TooltipArrow 挂载时用来把自己的 DOM 节点注册给 arrow middleware（Element 而不是 HTMLElement，兼容 SVG 箭头） */\n  setArrowElement: (el: Element) => void;\n  /**\n   * 驱动进出场动画的状态，和 TooltipContent 内层元素的 data-state 用的是\n   * 同一个信号——TooltipArrow 应该用它独立播放自己的一份动画，而不是依赖\n   * \"作为内层元素的子节点、被动继承内层的 transform/opacity 动画\"这种隐式\n   * 机制（内层的 zoom-in-95 动画会给它加一个非 none 的 transform，CSS 规范\n   * 规定这会让内层变成子元素新的\"包含块\"，和箭头故意跳过内层、以外层为\n   * 基准的设计相冲突，动画播放期间会让\"父子两层谁负责什么\"变得不可靠）。\n   */\n  animationState: Accessor<\"open\" | \"closed\">;\n}\n\nexport const TooltipContentContext =\n  createContext<TooltipContentContextValue>();\n\nexport function useTooltipContentContext(\n  component: string,\n): TooltipContentContextValue {\n  const ctx = useContext(TooltipContentContext);\n  if (!ctx) {\n    throw new Error(`<${component}> 必须渲染在 <TooltipContent> 内部`);\n  }\n  return ctx;\n}\n"],"mappings":";;AAqBA,IAAa,IACX,EAA0C;AAE5C,SAAgB,EACd,GAC4B;CAC5B,IAAM,IAAM,EAAW,CAAqB;CAC5C,IAAI,CAAC,GACH,MAAU,MAAM,IAAI,EAAU,4BAA4B;CAE5D,OAAO;AACT"}

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

@@ -1,2 +1,11 @@
 import { TooltipContentProps } from './TooltipContent.types';
-export declare const TooltipContent: (props: TooltipContentProps) => import("solid-js").JSX.Element;
+/**
+ * Tooltip 的浮层内容。挂 Portal 到 body，用 position:fixed 定位。
+ *
+ * 内容本身默认是可以 hover 的（不是 pointer-events:none）：鼠标移进 content
+ * 会取消待执行的关闭计时器（ctx.keepOpen），移出才真正走 closeDelay 关闭——
+ * 这样用户可以把鼠标从 trigger 移动到 tooltip 上选中里面的文字，不会因为
+ * "离开 trigger 就关闭" 而选不到。如果你的 tooltip 内容很简单、不需要这个特性，
+ * 可以自己在外面包一层设置 pointer-events: none。
+ */
+export declare function TooltipContent(props: TooltipContentProps): import("solid-js").JSX.Element;

package/dist/components/tooltip/TooltipContent/TooltipContent.js

@@ -1,76 +1,90 @@
-import { clsx as e } from "../../../utils/clsx.js";
-import { useTooltipContext as t } from "../Tooltip/Tooltip.context.js";
-import { TooltipContentContext as n } from "./TooltipContent.context.js";
+import { getAlignment as e, getSide as t } from "../../../lib/positioner/core/placement.js";
+import { getTransformOrigin as n } from "./TooltipContent.utils.js";
 import { useTooltipContent as r } from "./useTooltipContent.js";
-import { Portal as i, createComponent as a, insert as o, mergeProps as s, spread as c, template as l, use as u } from "solid-js/web";
-import { Show as d, createMemo as f, createSignal as p, mergeProps as m, splitProps as h } from "solid-js";
+import { TooltipContentContext as i } from "./TooltipContent.context.js";
+import { Portal as a, createComponent as o, effect as s, insert as c, mergeProps as l, setAttribute as u, spread as d, style as f, template as p, use as m } from "solid-js/web";
+import { Show as h, onCleanup as g, splitProps as _ } from "solid-js";
 //#region src/components/tooltip/TooltipContent/TooltipContent.tsx
-var g = /* @__PURE__ */ l("<div data-slot=tooltip-content role=tooltip>"), _ = (l) => {
-	let _ = t(), [v, y] = h(m({
-		side: "top",
-		align: "center",
-		alignOffset: 0,
-		sideOffset: 4
-	}, l), [
+var v = /*#__PURE__*/ p("<div style=z-index:1000><div><div role=tooltip>");
+function y(...e) {
+	return e.filter(Boolean).join(" ");
+}
+function b(p) {
+	let { ctx: b, pos: x, mounted: S, animationState: C, setArrowElement: w, setContentElement: T, slideStyle: E } = r(() => p), [D, O] = _(p, [
 		"side",
 		"align",
-		"alignOffset",
 		"sideOffset",
+		"alignOffset",
+		"collisionPadding",
 		"class",
-		"classList",
+		"style",
 		"children"
-	]), [b, x] = p(), { shouldRender: S, position: C } = r(b, () => v), w = f(() => _.open());
-	return a(d, {
+	]);
+	return o(h, {
 		get when() {
 			return S();
 		},
 		get children() {
-			return a(i, { get children() {
-				var t = g();
-				return u(x, t), c(t, s({
-					get "data-open"() {
-						return w() || void 0;
+			return o(a, { get children() {
+				var r = v(), a = r.firstChild, p = a.firstChild;
+				return m((e) => {
+					b.setFloating(e), g(() => b.setFloating(void 0));
+				}, r), m(T, p), d(p, l({
+					get id() {
+						return b.contentId;
 					},
-					get "data-closed"() {
-						return !w() || void 0;
-					},
-					get "data-align"() {
-						return C.align;
+					get "data-state"() {
+						return C();
 					},
 					get "data-side"() {
-						return C.side;
+						return t(x.placement());
 					},
-					get id() {
-						return _.contentId;
+					get "data-align"() {
+						return e(x.placement()) ?? "center";
 					},
-					get class() {
-						return e("fixed z-50 pointer-events-none inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-md bg-neutral-950 dark:bg-neutral-50 px-3 py-1.5 text-xs text-white dark:text-neutral-950 has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", v.class);
+					get onMouseEnter() {
+						return b.keepOpen;
+					},
+					get onMouseLeave() {
+						return b.requestClose;
 					},
 					get style() {
 						return {
-							top: `${C.top}px`,
-							left: `${C.left}px`,
-							visibility: C.top === 0 ? "hidden" : "visible"
+							"transform-origin": n(x.placement()),
+							...typeof D.style == "object" ? D.style : void 0
 						};
+					},
+					get class() {
+						return y("max-w-xs rounded-md px-3 py-1.5 text-xs leading-relaxed shadow-md", "data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95", "data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95", "data-[side=top]:slide-in-from-bottom-2", "data-[side=bottom]:slide-in-from-top-2", "data-[side=left]:slide-in-from-right-2", "data-[side=right]:slide-in-from-left-2", "bg-foreground text-background", D.class);
 					}
-				}, y), !1, !0), o(t, a(n.Provider, {
-					value: {
-						get side() {
-							return C.side;
-						},
-						get align() {
-							return C.align;
-						}
+				}, O), !1, !0), c(p, o(i.Provider, {
+					get value() {
+						return {
+							middlewareData: x.middlewareData,
+							placement: x.placement,
+							setArrowElement: w,
+							animationState: C
+						};
 					},
 					get children() {
-						return v.children;
+						return D.children;
 					}
-				})), t;
+				})), s((e) => {
+					var t = x.placement(), n = {
+						...x.floatingStyles(),
+						opacity: +!!x.isPositioned()
+					}, i = E();
+					return t !== e.e && u(r, "data-placement", e.e = t), e.t = f(r, n, e.t), e.a = f(a, i, e.a), e;
+				}, {
+					e: void 0,
+					t: void 0,
+					a: void 0
+				}), r;
 			} });
 		}
 	});
-};
+}
 //#endregion
-export { _ as TooltipContent };
+export { b as TooltipContent };
 
 //# sourceMappingURL=TooltipContent.js.map

package/dist/components/tooltip/TooltipContent/TooltipContent.js.map

@@ -1 +1 @@
-{"version":3,"file":"TooltipContent.js","names":["createMemo","createSignal","mergeProps","Show","splitProps","useTooltipContext","Portal","TooltipContentProps","clsx","TooltipContentContext","useTooltipContent","TooltipContent","props","ctx","merged","side","align","alignOffset","sideOffset","const","local","others","ref","setRef","HTMLDivElement","shouldRender","position","isOpen","open","_$createComponent","when","children","_el$","_tmpl$","_$use","_$spread","_$mergeProps","data-open","undefined","data-closed","data-align","data-side","id","contentId","class","style","top","left","visibility","_$insert","Provider","value"],"sources":["../../../../src/components/tooltip/TooltipContent/TooltipContent.tsx"],"sourcesContent":["import {\n  createMemo,\n  createSignal,\n  mergeProps,\n  Show,\n  splitProps,\n} from \"solid-js\";\nimport { useTooltipContext } from \"../Tooltip/Tooltip.context\";\nimport { Portal } from \"solid-js/web\";\nimport type { TooltipContentProps } from \"./TooltipContent.types\";\nimport { clsx } from \"~/utils\";\nimport { TooltipContentContext } from \"./TooltipContent.context\";\nimport { useTooltipContent } from \"./useTooltipContent\";\n\nexport const TooltipContent = (props: TooltipContentProps) => {\n  const ctx = useTooltipContext();\n\n  const merged = mergeProps(\n    { side: \"top\", align: \"center\", alignOffset: 0, sideOffset: 4 } as const,\n    props,\n  );\n  const [local, others] = splitProps(merged, [\n    \"side\",\n    \"align\",\n    \"alignOffset\",\n    \"sideOffset\",\n    \"class\",\n    \"classList\",\n    \"children\",\n  ]);\n\n  const [ref, setRef] = createSignal<HTMLDivElement>();\n\n  const { shouldRender, position } = useTooltipContent(ref, () => local);\n\n  const isOpen = createMemo(() => ctx.open());\n\n  return (\n    <Show when={shouldRender()}>\n      <Portal>\n        <div\n          ref={setRef}\n          data-slot=\"tooltip-content\"\n          data-open={isOpen() || undefined}\n          data-closed={!isOpen() || undefined}\n          data-align={position.align}\n          data-side={position.side}\n          id={ctx.contentId}\n          role=\"tooltip\"\n          class={clsx(\n            \"fixed z-50 pointer-events-none inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-md bg-neutral-950 dark:bg-neutral-50 px-3 py-1.5 text-xs text-white dark:text-neutral-950 has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95\",\n            local.class,\n          )}\n          style={{\n            top: `${position.top}px`,\n            left: `${position.left}px`,\n            visibility: position.top === 0 ? \"hidden\" : \"visible\",\n          }}\n          {...others}\n        >\n          <TooltipContentContext.Provider\n            value={{\n              get side() {\n                return position.side;\n              },\n              get align() {\n                return position.align;\n              },\n            }}\n          >\n            {local.children}\n          </TooltipContentContext.Provider>\n        </div>\n      </Portal>\n    </Show>\n  );\n};\n"],"mappings":";;;;;;;2EAcaW,KAAkBC,MAA+B;CAC5D,IAAMC,IAAMR,GAAmB,EAMzB,CAACe,GAAOC,KAAUjB,EAJTF,EACb;EAAEa,MAAM;EAAOC,OAAO;EAAUC,aAAa;EAAGC,YAAY;EAAG,EAC/DN,EACD,EAC0C;EACzC;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CAAC,EAEI,CAACU,GAAKC,KAAUtB,GAA8B,EAE9C,EAAEwB,iBAAcC,gBAAahB,EAAkBY,SAAWF,EAAM,EAEhEO,IAAS3B,QAAiBa,EAAIe,MAAM,CAAC;AAE3C,QAAAC,EACG1B,GAAI;EAAA,IAAC2B,OAAI;AAAA,UAAEL,GAAc;;EAAA,IAAAM,WAAA;AAAA,UAAAF,EACvBvB,GAAM,EAAA,IAAAyB,WAAA;IAAA,IAAAC,IAAAC,GAAA;AA+Bc,WA/BdC,EAEEX,GAAMS,EAAA,EAAAG,EAAAH,GAAAI,EAAA;KAAA,IAAA,cAAA;AAAA,aAEAT,GAAQ,IAAIW,KAAAA;;KAAS,IAAA,gBAAA;AAAA,aACnB,CAACX,GAAQ,IAAIW,KAAAA;;KAAS,IAAA,eAAA;AAAA,aACvBZ,EAASV;;KAAK,IAAA,cAAA;AAAA,aACfU,EAASX;;KAAI,IACxB2B,KAAE;AAAA,aAAE7B,EAAI8B;;KAAS,IAAA,QAAA;AAAA,aAEVnC,EACL,k0BACAY,EAAMwB,MACP;;KAAA,IACDC,QAAK;AAAA,aAAE;OACLC,KAAK,GAAGpB,EAASoB,IAAG;OACpBC,MAAM,GAAGrB,EAASqB,KAAI;OACtBC,YAAYtB,EAASoB,QAAQ,IAAI,WAAW;OAC7C;;KAAA,EACGzB,EAAM,EAAA,IAAA,GAAA,EAAA4B,EAAAjB,GAAAH,EAETpB,EAAsByC,UAAQ;KAC7BC,OAAO;MACL,IAAIpC,OAAO;AACT,cAAOW,EAASX;;MAElB,IAAIC,QAAQ;AACV,cAAOU,EAASV;;MAEnB;KAAA,IAAAe,WAAA;AAAA,aAEAX,EAAMW;;KAAQ,CAAA,CAAA,EAAAC;MAAA,CAAA;;EAAA,CAAA"}
+{"version":3,"file":"TooltipContent.js","names":["Show","onCleanup","splitProps","Portal","useTooltipContent","TooltipContentContext","getTransformOrigin","getSide","getAlignment","TooltipContentProps","cn","classes","Array","filter","Boolean","join","TooltipContent","props","ctx","pos","mounted","animationState","setArrowElement","setContentElement","slideStyle","local","rest","_$createComponent","when","children","_el$","_tmpl$","_el$2","firstChild","_el$3","_$use","el","setFloating","undefined","_$spread","_$mergeProps","id","contentId","data-state","data-side","placement","data-align","onMouseEnter","keepOpen","onMouseLeave","requestClose","style","class","_$insert","Provider","value","middlewareData","_$effect","_p$","_v$","_v$2","floatingStyles","opacity","isPositioned","_v$3","e","_$setAttribute","t","_$style","a"],"sources":["../../../../src/components/tooltip/TooltipContent/TooltipContent.tsx"],"sourcesContent":["import { Show, onCleanup, splitProps } from \"solid-js\";\nimport { Portal } from \"solid-js/web\";\nimport { useTooltipContent } from \"./useTooltipContent\";\nimport { TooltipContentContext } from \"./TooltipContent.context\";\nimport { getTransformOrigin } from \"./TooltipContent.utils\";\nimport { getSide, getAlignment } from \"~/lib\";\nimport type { TooltipContentProps } from \"./TooltipContent.types\";\n\nfunction cn(...classes: Array<string | false | undefined | null>): string {\n  return classes.filter(Boolean).join(\" \");\n}\n\n/**\n * Tooltip 的浮层内容。挂 Portal 到 body，用 position:fixed 定位。\n *\n * 内容本身默认是可以 hover 的（不是 pointer-events:none）：鼠标移进 content\n * 会取消待执行的关闭计时器（ctx.keepOpen），移出才真正走 closeDelay 关闭——\n * 这样用户可以把鼠标从 trigger 移动到 tooltip 上选中里面的文字，不会因为\n * \"离开 trigger 就关闭\" 而选不到。如果你的 tooltip 内容很简单、不需要这个特性，\n * 可以自己在外面包一层设置 pointer-events: none。\n */\nexport function TooltipContent(props: TooltipContentProps) {\n  const {\n    ctx,\n    pos,\n    mounted,\n    animationState,\n    setArrowElement,\n    setContentElement,\n    slideStyle,\n  } = useTooltipContent(() => props);\n\n  // 只摘出内部要单独处理的几个字段，剩下的（style、data-*、onXxx 等任意原生\n  // prop）原样透传给内层元素——和 TooltipTrigger 是同一套约定。\n  const [local, rest] = splitProps(props, [\n    \"side\",\n    \"align\",\n    \"sideOffset\",\n    \"alignOffset\",\n    \"collisionPadding\",\n    \"class\",\n    \"style\",\n    \"children\",\n  ]);\n\n  return (\n    <Show when={mounted()}>\n      <Portal>\n        {/*\n          外层：只负责定位（position:fixed 来自 floatingStyles），不设 overflow，\n          也不参与任何动画——它的 transform 已经被占用来做定位（translate(x,y)），\n          如果别的动画也要控制 transform 会互相冲突，所以动画都放在下面两层。\n        */}\n        <div\n          ref={(el) => {\n            ctx.setFloating(el);\n            // Solid 的 ref 回调只在元素创建时触发一次，元素被移除时不会自动\n            // 再调用一次传 undefined（这是 React 的约定，不是 Solid 的）。\n            // 不手动清空的话，ctx.floating() 会一直指向一个已经从 DOM 里\n            // 摘除的\"僵尸节点\"，直到下次重新打开——期间如果被别处读取\n            // （比如 TooltipGroup 抢占时读取矩形），getBoundingClientRect()\n            // 对一个 detached 元素规范规定就是返回全 0 的矩形，会造成\n            // \"滑动效果从左上角(0,0)滑入\"这种明显错误的观感。\n            onCleanup(() => ctx.setFloating(undefined));\n          }}\n          data-placement={pos.placement()}\n          style={{\n            ...pos.floatingStyles(),\n            \"z-index\": 1000,\n            opacity: pos.isPositioned() ? 1 : 0,\n          }}\n        >\n          {/*\n            滑动层：命中 <TooltipGroup> 抢占时，用来把整个 tooltip（内容+箭头）\n            从旧 tooltip 的位置平移过来（FLIP 技术，细节见 useTooltipContent 里\n            的 slideOffset 计算）。平时 slideStyle() 是空对象，这一层形同不存在。\n\n            这一层必须夹在\"定位层\"和\"样式/动画层\"之间、而不是随便找个地方加：\n            它自己也会用到 transform（滑动过程中），如果和定位层共用一个元素会\n            跟 translate(x,y) 冲突（原因同上）；但它又不能在样式层（overflow:auto\n            那层）的下面/内部，因为箭头的 position:absolute 是故意跳过样式层、\n            以\"最近的已定位祖先\"为基准的（这是修复箭头戳出来触发滚动条那次的\n            设计），如果滑动层的 transform 出现在样式层内部，箭头的定位基准就会\n            变成滑动层而不是外层——效果上依然正确（滑动层的盒子和外层几乎重合），\n            但为了让\"定位基准\"这件事始终清晰、不产生\"技术上是谁、视觉上又是谁\"\n            的心智负担，把滑动层放在外层和样式层之间、维持这条链路的清晰顺序。\n          */}\n          <div style={slideStyle()}>\n            {/*\n              内层：真正的视觉样式 + 进出场动画。\n              data-state 跟着 animationState 走（不是 isVisible/mounted）：\n              - isVisible 变 false 的瞬间，animationState 立刻跟着变 closed，\n                触发退场动画的 class；\n              - isVisible 变 true 时，animationState 会晚一帧才变 open，\n                留出时间让箭头（TooltipArrow）完成挂载、注册给 arrow middleware、\n                算出正确的位置偏移（细节见 useTooltipContent 里的注释）；\n              - mounted 会比 animationState 变 closed 更晚才变 false（见下面的\n                Presence 逻辑），留出时间让退场动画播完。\n\n              data-[state=open]/data-[state=closed] 这套 class 依赖 tailwindcss-animate\n              插件提供的 animate-in/animate-out/fade-in-0/zoom-in-95 等工具类——\n              如果你的项目还没装，`npm install tailwindcss-animate` 并在 tailwind\n              config 里加上这个 plugin 即可；不想装的话，把这几个 data-[state=...]\n              class 换成你自己写的 @keyframes + 对应 class 也一样能工作，\n              Presence 逻辑（mounted 延迟卸载）不依赖具体用了哪套动画实现。\n\n              箭头（TooltipArrow）不依赖\"作为这个元素的子节点、被动继承这里的\n              transform/opacity 动画\"这种隐式机制——它自己也从 context 里读到\n              同一个 animationState，独立播放一份自己的入场/退场动画，两者由\n              同一个信号同步触发。\n\n              data-side/data-align 是从最终生效的 placement 拆出来的，驱动上面\n              这几条方向感知的 slide-in class，也顺带给 transform-origin 提供了\n              依据——缩放动画的锚点会落在\"贴近 trigger 的那条边\"上（细节见\n              TooltipContent.utils.ts 里的 getTransformOrigin），而不是默认的\n              几何中心，这样整个入场效果才会像是\"从 trigger 那里长出来\"，\n              贴近 shadcn 的实际观感。\n\n              特意没有 overflow:auto / max-height，tooltip 不支持内容超长时滚动——\n              宽度上限靠下面静态的 max-w-xs class 兜底，让文字自然换行；高度完全\n              不做限制。这不只是为了贴近 shadcn/Radix 的行为（它们的 tooltip 也不\n              允许滚动），还避免了一个真实踩过的坑：overflow:auto 配合这里的\n              zoom-in-95 动画（会给这个元素加一个非 none 的 transform，CSS 规范\n              规定这会让它变成子元素新的包含块）曾经导致箭头戳出边缘的那部分被\n              误判成\"可滚动溢出\"，表现为打开瞬间闪一下滚动条、箭头跟着被遮住，\n              动画播完滚动条消失、箭头才重新出现。去掉滚动能力后这个耦合从根上\n              就不存在了。\n            */}\n            <div\n              ref={setContentElement}\n              id={ctx.contentId}\n              role=\"tooltip\"\n              data-state={animationState()}\n              data-side={getSide(pos.placement())}\n              data-align={getAlignment(pos.placement()) ?? \"center\"}\n              onMouseEnter={ctx.keepOpen}\n              onMouseLeave={ctx.requestClose}\n              style={{\n                \"transform-origin\": getTransformOrigin(pos.placement()),\n                ...(typeof local.style === \"object\" ? local.style : undefined),\n              }}\n              class={cn(\n                \"max-w-xs rounded-md px-3 py-1.5 text-xs leading-relaxed shadow-md\",\n                \"data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95\",\n                \"data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95\",\n                // 方向感知的滑入：不只是原地淡入缩放，还从\"贴近 trigger 的反方向\"\n                // 轻微位移过来——比如 placement 是 top（content 在 trigger 上方），\n                // 就从下方 8px（slide-in-from-bottom-2）滑上来，视觉上更像是从\n                // trigger 那里\"冒出来\"，而不是凭空原地出现。只在打开时生效，\n                // 贴近 shadcn 的实际行为（它们的退场动画没有对应的滑出位移）。\n                \"data-[side=top]:slide-in-from-bottom-2\",\n                \"data-[side=bottom]:slide-in-from-top-2\",\n                \"data-[side=left]:slide-in-from-right-2\",\n                \"data-[side=right]:slide-in-from-left-2\",\n                \"bg-foreground text-background\",\n                local.class,\n              )}\n              {...rest}\n            >\n              <TooltipContentContext.Provider\n                value={{\n                  middlewareData: pos.middlewareData,\n                  placement: pos.placement,\n                  setArrowElement,\n                  animationState,\n                }}\n              >\n                {local.children}\n              </TooltipContentContext.Provider>\n            </div>\n          </div>\n        </div>\n      </Portal>\n    </Show>\n  );\n}\n"],"mappings":";;;;;;;;AAQA,SAASU,EAAG,GAAGC,GAA2D;CACxE,OAAOA,EAAQE,OAAOC,OAAO,CAAC,CAACC,KAAK,GAAG;AACzC;AAWA,SAAgBC,EAAeC,GAA4B;CACzD,IAAM,EACJC,QACAC,QACAC,YACAC,mBACAC,oBACAC,sBACAC,kBACEpB,QAAwBa,CAAK,GAI3B,CAACQ,GAAOC,KAAQxB,EAAWe,GAAO;EACtC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CAAU,CACX;CAED,OAAAU,EACG3B,GAAI;EAAA,IAAC4B,OAAI;GAAA,OAAER,EAAQ;EAAC;EAAA,IAAAS,WAAA;GAAA,OAAAF,EAClBxB,GAAM,EAAA,IAAA0B,WAAA;IAAA,IAAAC,IAAAC,EAAA,GAAAC,IAAAF,EAAAG,YAAAC,IAAAF,EAAAC;IAwCqB,OAxCrBE,GAOGC,MAAO;KASXnC,AARAiB,EAAImB,YAAYD,CAAE,GAQlBnC,QAAgBiB,EAAImB,YAAYC,KAAAA,CAAS,CAAC;IAC5C,GAACR,CAAA,GAAAK,EAiEQZ,GAAiBW,CAAA,GAAAK,EAAAL,GAAAM,EAAA;KAAA,IACtBC,KAAE;MAAA,OAAEvB,EAAIwB;KAAS;KAAA,IAAA,eAAA;MAAA,OAELrB,EAAe;KAAC;KAAA,IAAA,cAAA;MAAA,OACjBd,EAAQY,EAAI0B,UAAU,CAAC;KAAC;KAAA,IAAA,eAAA;MAAA,OACvBrC,EAAaW,EAAI0B,UAAU,CAAC,KAAK;KAAQ;KAAA,IACrDE,eAAY;MAAA,OAAE7B,EAAI8B;KAAQ;KAAA,IAC1BC,eAAY;MAAA,OAAE/B,EAAIgC;KAAY;KAAA,IAC9BC,QAAK;MAAA,OAAE;OACL,oBAAoB7C,EAAmBa,EAAI0B,UAAU,CAAC;OACtD,GAAI,OAAOpB,EAAM0B,SAAU,WAAW1B,EAAM0B,QAAQb,KAAAA;MACtD;KAAC;KAAA,IAAA,QAAA;MAAA,OACM5B,EACL,qEACA,yFACA,kGAMA,0CACA,0CACA,0CACA,0CACA,iCACAe,EAAM2B,KACR;KAAC;IAAA,GACG1B,CAAI,GAAA,IAAA,EAAA,GAAA2B,EAAAnB,GAAAP,EAEPtB,EAAsBiD,UAAQ;KAAA,IAC7BC,QAAK;MAAA,OAAE;OACLC,gBAAgBrC,EAAIqC;OACpBX,WAAW1B,EAAI0B;OACfvB;OACAD;MACF;KAAC;KAAA,IAAAQ,WAAA;MAAA,OAEAJ,EAAMI;KAAQ;IAAA,CAAA,CAAA,GAAA4B,GAAAC,MAAA;KAAA,IAAAC,IAtGLxC,EAAI0B,UAAU,GAACe,IACxB;MACL,GAAGzC,EAAI0C,eAAe;MAEtBC,SAAS3C,KAAI4C,aAAa;KAC5B,GAACC,IAiBWxC,EAAW;KAAC,OAAAmC,MAAAD,EAAAO,KAAAC,EAAApC,GAAA,kBAAA4B,EAAAO,IAAAN,CAAA,GAAAD,EAAAS,IAAAC,EAAAtC,GAAA8B,GAAAF,EAAAS,CAAA,GAAAT,EAAAW,IAAAD,EAAApC,GAAAgC,GAAAN,EAAAW,CAAA,GAAAX;IAAA,GAAA;KAAAO,GAAA3B,KAAAA;KAAA6B,GAAA7B,KAAAA;KAAA+B,GAAA/B,KAAAA;IAAA,CAAA,GAAAR;GAAA,EAAA,CAAA;EAAA;CAAA,CAAA;AAwFlC"}

package/dist/components/tooltip/TooltipContent/TooltipContent.types.d.ts

@@ -1,9 +1,19 @@
+import { Alignment, Side } from '../../../lib';
 import { BaseProps, PolymorphicProps } from '../../../types';
 interface BaseTooltipContentProps extends BaseProps {
-    side?: "top" | "bottom" | "left" | "right";
-    align?: "start" | "center" | "end";
-    alignOffset?: number;
+    /** 贴 trigger 的哪一侧，默认 'top' */
+    side?: Side;
+    /** 沿边对齐方式，默认 'center'（不偏移，居中对齐） */
+    align?: Alignment | "center";
+    /** 沿主轴（side 指向的方向）与 trigger 之间的间距（像素），默认 8 */
     sideOffset?: number;
+    /**
+     * 沿交叉轴（对齐方向）的偏移（像素），默认 0——align 是 'start'/'end' 时
+     * 微调对齐位置用。底层直接对应 offset middleware 的 crossAxis。
+     */
+    alignOffset?: number;
+    /** 距视口边缘的最小间距（像素），用于 flip/shift 的边界检测，默认 8 */
+    collisionPadding?: number;
 }
 export type TooltipContentProps = PolymorphicProps<"div", BaseTooltipContentProps, false>;
 export {};

package/dist/components/tooltip/TooltipContent/TooltipContent.utils.d.ts

@@ -1,6 +1,57 @@
-export declare function computePosition(trigger: HTMLElement, content: HTMLElement, side: "top" | "bottom" | "left" | "right", align: "start" | "center" | "end", alignOffset: number, sideOffset: number): {
-    top: number;
-    left: number;
-    side: "left" | "right" | "bottom" | "top";
-    align: "center" | "start" | "end";
-};
+import { Middleware, Placement, Side, Alignment } from '../../../lib';
+/**
+ * 把 shadcn/Radix 风格的 side + align 拆分参数，转换成核心库统一用的
+ * `Placement` 字符串（比如 side='top' + align='start' → 'top-start'）。
+ * align 是 'center'（默认对齐、不偏移）时不带后缀，直接是 side 本身。
+ */
+export declare function toPlacement(side: Side, align: Alignment | "center"): Placement;
+/**
+ * 根据最终生效的 placement，算出缩放动画应该以哪个点为锚点（CSS transform-origin）。
+ * 锚点应该落在"贴近 trigger 的那条边"上——比如 placement 是 'top'（content 在
+ * trigger 上方），锚点就该是 content 自己的底边，缩放动画看起来才会像是
+ * "从 trigger 那里长出来"，而不是原地放大缩小（默认的 transform-origin 是
+ * 几何中心 50% 50%，视觉上和"从哪个方向冒出来"没有任何关联）。
+ * 交叉轴（对齐方向）同理：align 是 start 就贴左/上边，end 就贴右/下边。
+ */
+export declare function getTransformOrigin(placement: Placement): string;
+export interface BuildTooltipMiddlewareOptions {
+    sideOffset: number;
+    /** 沿交叉轴（对齐方向）的偏移，对应 offset middleware 的 crossAxis */
+    alignOffset: number;
+    collisionPadding: number;
+    arrowElement: () => Element | undefined;
+}
+/**
+ * Tooltip 定位管线的固定配方：
+ *
+ * 1. offset      — 沿主轴保持 sideOffset 间距，沿交叉轴偏移 alignOffset
+ * 2. flip        — 主轴方向放不下就翻到对面（比如上方没空间就翻到下方）
+ * 3. shift       — 翻转后仍溢出，就在不换边的前提下贴边平移
+ * 4. arrow       — 算出箭头相对 content 的偏移，让它始终指向 trigger 中心
+ * 5. hide        — trigger 被自己的滚动容器完全裁掉时标记隐藏
+ * 6. containingBlockOffset — 修正祖先元素 transform 等属性导致的 position:fixed
+ *    包含块偏移（demo 里通常不出现，放进有大量 transform 的真实项目后才会暴露，
+ *    详见该 middleware 自身的注释）。放在最后一位，因为它修正的是"最终要写进
+ *    DOM 的坐标"，前面几步都在统一的视口坐标系里计算，不受这个偏移影响。
+ *
+ * 特意没有用 size 中间件去动态限制 max-height、允许内容超长时滚动——
+ * tooltip 不应该出现滚动条（这不是本库的一般性限制，是 tooltip 这个组件
+ * 类型本身该有的样子，shadcn/Radix 的 Tooltip 也是这么做的）。宽度上限
+ * 靠 TooltipContent.tsx 里静态的 `max-w-xs` class 兜底，让文字自然换行；
+ * 高度完全不做限制，交给内容自身的实际高度决定。
+ *
+ * 这个决定还有一个技术上的原因：早先的实现里试过用 size 中间件动态算
+ * max-height 配合 overflow:auto 实现"超长内容可滚动"，结果发现内层元素
+ * 一旦同时具备 overflow:auto 和入场动画（zoom-in-95 会给它加一个 transform），
+ * 动画播放期间 transform 会让这个元素变成箭头新的包含块（CSS 规范：非 none
+ * 的 transform 会创建包含块），箭头戳出内层边缘的那部分又会被算进内层的
+ * 可滚动溢出区域——于是出现了"打开瞬间闪一下滚动条，箭头跟着被遮住，
+ * 动画播完滚动条消失、箭头才重新出现"这种诡异现象。去掉滚动能力后，
+ * 这个耦合从根上就不存在了。
+ *
+ * 顺序不能随便换：arrow 必须在 shift/flip 之后（要用最终坐标才能算对偏移），
+ * containingBlockOffset 必须在所有其他 middleware 之后。
+ *
+ * 单独抽成函数是为了让 useTooltipContent 保持简洁，也方便针对这套管线单独测试。
+ */
+export declare function createTooltipMiddleware(options: BuildTooltipMiddlewareOptions): Middleware[];

package/dist/components/tooltip/TooltipContent/TooltipContent.utils.js

@@ -1,64 +1,40 @@
+import { getAlignment as e, getSide as t } from "../../../lib/positioner/core/placement.js";
+import { offset as n } from "../../../lib/positioner/middleware/offset.js";
+import { shift as r } from "../../../lib/positioner/middleware/shift.js";
+import { flip as i } from "../../../lib/positioner/middleware/flip.js";
+import { arrow as a } from "../../../lib/positioner/middleware/arrow.js";
+import { hide as o } from "../../../lib/positioner/middleware/hide.js";
+import { containingBlockOffset as s } from "../../../lib/positioner/middleware/containing-block-offset.js";
 //#region src/components/tooltip/TooltipContent/TooltipContent.utils.ts
-function e(e, t, n, r, i, a) {
-	let o = e.getBoundingClientRect(), s = t.offsetWidth, c = t.offsetHeight, l = window.innerWidth, u = window.innerHeight, d = 0, f = 0, p = n, m = r;
-	switch (n) {
-		case "top":
-			o.top < c + a && o.bottom + a + c <= u && (p = "bottom");
-			break;
-		case "bottom":
-			o.bottom + a + c > u && o.top - a - c >= 0 && (p = "top");
-			break;
-		case "left":
-			o.left < s + a && o.right + a + s <= l && (p = "right");
-			break;
-		case "right":
-			o.right + a + s > l && o.left - a - s >= 0 && (p = "left");
-			break;
-	}
-	switch (p) {
-		case "top":
-			d = o.top - c - a;
-			break;
-		case "bottom":
-			d = o.bottom + a;
-			break;
-		case "left":
-			f = o.left - s - a;
-			break;
-		case "right":
-			f = o.right + a;
-			break;
-	}
-	if (p === "top" || p === "bottom") switch (r) {
-		case "start":
-			f = o.left + i;
-			break;
-		case "center":
-			f = o.left + o.width / 2 - s / 2 + i;
-			break;
-		case "end":
-			f = o.right - s - i;
-			break;
-	}
-	else switch (r) {
-		case "start":
-			d = o.top + i;
-			break;
-		case "center":
-			d = o.top + o.height / 2 - c / 2 + i;
-			break;
-		case "end":
-			d = o.bottom - c - i;
-			break;
+function c(e, t) {
+	return t === "center" ? e : `${e}-${t}`;
+}
+function l(n) {
+	let r = t(n), i = e(n), a = i === "start" ? "0%" : i === "end" ? "100%" : "50%";
+	switch (r) {
+		case "top": return `${a} 100%`;
+		case "bottom": return `${a} 0%`;
+		case "left": return `100% ${a}`;
+		case "right": return `0% ${a}`;
 	}
-	return p === "top" || p === "bottom" ? f < 4 ? (f = 4, m = "start") : f + s > l - 4 && (f = l - s - 4, m = "end") : d < 4 ? (d = 4, m = "start") : d + c > u - 4 && (d = u - c - 4, m = "end"), {
-		top: d,
-		left: f,
-		side: p,
-		align: m
-	};
+}
+function u(e) {
+	return [
+		n({
+			mainAxis: e.sideOffset,
+			crossAxis: e.alignOffset
+		}),
+		i(),
+		r({ padding: e.collisionPadding }),
+		a({
+			element: e.arrowElement,
+			padding: 6
+		}),
+		o(),
+		s()
+	];
 }
 //#endregion
-export { e as computePosition };
+export { u as createTooltipMiddleware, l as getTransformOrigin, c as toPlacement };
 
 //# sourceMappingURL=TooltipContent.utils.js.map