@neut/ui 0.0.9 → 0.0.11

package/dist/lib/positioner/create-positioner.d.ts

@@ -0,0 +1,63 @@
+import { Accessor } from 'solid-js';
+import { Middleware, MiddlewareData, Placement, ReferenceElement, Strategy } from './types';
+import { AutoUpdateOptions } from './auto-update';
+type MaybeAccessor<T> = T | Accessor<T>;
+export interface CreatePositionerOptions {
+    /** 期望的初始/首选摆放位置，默认 'bottom' */
+    placement?: MaybeAccessor<Placement>;
+    /** 定位方式：'absolute' 需要 floating 挂在 body 下且无非 static 定位祖先；不确定就用 'fixed' */
+    strategy?: MaybeAccessor<Strategy>;
+    /** middleware 数组，顺序执行，如 [offset(8), flip(), shift({padding: 8})] */
+    middleware?: MaybeAccessor<Middleware[]>;
+    /** 是否在滚动/尺寸变化时自动重新计算，默认 true；也可传细粒度配置 */
+    autoUpdate?: boolean | AutoUpdateOptions;
+}
+export interface Positioner {
+    /** floating 元素相对定位坐标系的 x（细粒度信号，只在数值变化时更新） */
+    x: Accessor<number>;
+    /** floating 元素相对定位坐标系的 y（细粒度信号，只在数值变化时更新） */
+    y: Accessor<number>;
+    /** 经过 middleware（如 flip）调整后的最终 placement */
+    placement: Accessor<Placement>;
+    /** 实际生效的定位策略 */
+    strategy: Accessor<Strategy>;
+    /** 各 middleware 产出的附加数据，例如 arrow 的偏移量 */
+    middlewareData: Accessor<MiddlewareData>;
+    /** 是否已完成至少一次定位计算，可用于首次渲染前隐藏 floating 元素避免闪烁 */
+    isPositioned: Accessor<boolean>;
+    /** 手动触发一次重新计算 */
+    update: () => void;
+    /** 可直接展开到 style 上的便捷样式对象 */
+    floatingStyles: Accessor<{
+        position: Strategy;
+        top: string;
+        left: string;
+        transform: string;
+    }>;
+}
+/**
+ * Solid 的细粒度浮窗定位 primitive。
+ *
+ * 传入 reference / floating 两个元素访问器，返回一组独立的响应式信号
+ * （x、y、placement 等分别更新，不会因为其中一个变化而让另一个也重新渲染），
+ * 上层组件（tooltip / dropdown / popover）只需订阅自己关心的信号。
+ *
+ * @example
+ * ```tsx
+ * const [reference, setReference] = createSignal<HTMLElement>();
+ * const [floating, setFloating] = createSignal<HTMLElement>();
+ * const pos = createPositioner(reference, floating, {
+ *   placement: "bottom-start",
+ *   middleware: [offset(8), flip(), shift({ padding: 8 })],
+ * });
+ *
+ * <button ref={setReference}>trigger</button>
+ * <Show when={open()}>
+ *   <Portal>
+ *     <div ref={setFloating} style={pos.floatingStyles()}>内容</div>
+ *   </Portal>
+ * </Show>
+ * ```
+ */
+export declare function createPositioner(reference: Accessor<ReferenceElement | null | undefined>, floating: Accessor<HTMLElement | null | undefined>, options?: CreatePositionerOptions): Positioner;
+export {};

package/dist/lib/positioner/create-positioner.js

@@ -0,0 +1,51 @@
+import { computePosition as e } from "./core/compute-position.js";
+import { autoUpdate as t } from "./auto-update.js";
+import { createEffect as n, createMemo as r, createSignal as i, onCleanup as a } from "solid-js";
+//#region src/lib/positioner/create-positioner.ts
+function o(e, t) {
+	return e === void 0 ? t : typeof e == "function" ? e() : e;
+}
+function s(s, c, l = {}) {
+	let [u, d] = i(0), [f, p] = i(0), [m, h] = i(o(l.placement, "bottom")), [g, _] = i(o(l.strategy, "absolute")), [v, y] = i({}), [b, x] = i(!1), S = () => {
+		let t = s(), n = c();
+		if (!t || !n) {
+			x(!1);
+			return;
+		}
+		let r = e(t, n, {
+			placement: o(l.placement, "bottom"),
+			strategy: o(l.strategy, "absolute"),
+			middleware: o(l.middleware, [])
+		});
+		d(r.x), p(r.y), h(r.placement), _(r.strategy), y(r.middlewareData), x(!0);
+	};
+	return n(() => {
+		let e = s(), n = c();
+		if (o(l.placement, "bottom"), o(l.strategy, "absolute"), o(l.middleware, []), !e || !n) {
+			x(!1);
+			return;
+		}
+		if (S(), l.autoUpdate !== !1) {
+			let r = t(e, n, S, typeof l.autoUpdate == "object" ? l.autoUpdate : {});
+			a(r);
+		}
+	}), {
+		x: u,
+		y: f,
+		placement: m,
+		strategy: g,
+		middlewareData: v,
+		isPositioned: b,
+		update: S,
+		floatingStyles: r(() => ({
+			position: g(),
+			top: "0px",
+			left: "0px",
+			transform: `translate(${Math.round(u())}px, ${Math.round(f())}px)`
+		}))
+	};
+}
+//#endregion
+export { s as createPositioner };
+
+//# sourceMappingURL=create-positioner.js.map

package/dist/lib/positioner/create-positioner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-positioner.js","names":[],"sources":["../../../src/lib/positioner/create-positioner.ts"],"sourcesContent":["import {\n  createEffect,\n  createMemo,\n  createSignal,\n  onCleanup,\n  type Accessor,\n} from \"solid-js\";\nimport type {\n  Middleware,\n  MiddlewareData,\n  Placement,\n  ReferenceElement,\n  Strategy,\n} from \"./types\";\nimport { computePosition } from \"./core/compute-position\";\nimport {\n  autoUpdate as attachAutoUpdate,\n  type AutoUpdateOptions,\n} from \"./auto-update\";\n\ntype MaybeAccessor<T> = T | Accessor<T>;\n\nfunction unwrap<T>(value: MaybeAccessor<T> | undefined, fallback: T): T {\n  if (value === undefined) return fallback;\n  return typeof value === \"function\" ? (value as Accessor<T>)() : value;\n}\n\nexport interface CreatePositionerOptions {\n  /** 期望的初始/首选摆放位置，默认 'bottom' */\n  placement?: MaybeAccessor<Placement>;\n  /** 定位方式：'absolute' 需要 floating 挂在 body 下且无非 static 定位祖先；不确定就用 'fixed' */\n  strategy?: MaybeAccessor<Strategy>;\n  /** middleware 数组，顺序执行，如 [offset(8), flip(), shift({padding: 8})] */\n  middleware?: MaybeAccessor<Middleware[]>;\n  /** 是否在滚动/尺寸变化时自动重新计算，默认 true；也可传细粒度配置 */\n  autoUpdate?: boolean | AutoUpdateOptions;\n}\n\nexport interface Positioner {\n  /** floating 元素相对定位坐标系的 x（细粒度信号，只在数值变化时更新） */\n  x: Accessor<number>;\n  /** floating 元素相对定位坐标系的 y（细粒度信号，只在数值变化时更新） */\n  y: Accessor<number>;\n  /** 经过 middleware（如 flip）调整后的最终 placement */\n  placement: Accessor<Placement>;\n  /** 实际生效的定位策略 */\n  strategy: Accessor<Strategy>;\n  /** 各 middleware 产出的附加数据，例如 arrow 的偏移量 */\n  middlewareData: Accessor<MiddlewareData>;\n  /** 是否已完成至少一次定位计算，可用于首次渲染前隐藏 floating 元素避免闪烁 */\n  isPositioned: Accessor<boolean>;\n  /** 手动触发一次重新计算 */\n  update: () => void;\n  /** 可直接展开到 style 上的便捷样式对象 */\n  floatingStyles: Accessor<{\n    position: Strategy;\n    top: string;\n    left: string;\n    transform: string;\n  }>;\n}\n\n/**\n * Solid 的细粒度浮窗定位 primitive。\n *\n * 传入 reference / floating 两个元素访问器，返回一组独立的响应式信号\n * （x、y、placement 等分别更新，不会因为其中一个变化而让另一个也重新渲染），\n * 上层组件（tooltip / dropdown / popover）只需订阅自己关心的信号。\n *\n * @example\n * ```tsx\n * const [reference, setReference] = createSignal<HTMLElement>();\n * const [floating, setFloating] = createSignal<HTMLElement>();\n * const pos = createPositioner(reference, floating, {\n *   placement: \"bottom-start\",\n *   middleware: [offset(8), flip(), shift({ padding: 8 })],\n * });\n *\n * <button ref={setReference}>trigger</button>\n * <Show when={open()}>\n *   <Portal>\n *     <div ref={setFloating} style={pos.floatingStyles()}>内容</div>\n *   </Portal>\n * </Show>\n * ```\n */\nexport function createPositioner(\n  reference: Accessor<ReferenceElement | null | undefined>,\n  floating: Accessor<HTMLElement | null | undefined>,\n  options: CreatePositionerOptions = {},\n): Positioner {\n  const [x, setX] = createSignal(0);\n  const [y, setY] = createSignal(0);\n  const [placement, setPlacement] = createSignal<Placement>(\n    unwrap(options.placement, \"bottom\"),\n  );\n  const [strategy, setStrategy] = createSignal<Strategy>(\n    unwrap(options.strategy, \"absolute\"),\n  );\n  const [middlewareData, setMiddlewareData] = createSignal<MiddlewareData>({});\n  const [isPositioned, setIsPositioned] = createSignal(false);\n\n  const update = () => {\n    const refEl = reference();\n    const floatEl = floating();\n    if (!refEl || !floatEl) {\n      setIsPositioned(false);\n      return;\n    }\n\n    const result = computePosition(refEl, floatEl, {\n      placement: unwrap(options.placement, \"bottom\"),\n      strategy: unwrap(options.strategy, \"absolute\"),\n      middleware: unwrap(options.middleware, []),\n    });\n\n    // 每个 setter 只有在值真正变化时才会触发下游更新（Solid 信号默认行为），\n    // 这就是“细粒度”的关键：只订阅 x 的节点不会因为 middlewareData 变化而重跑。\n    setX(result.x);\n    setY(result.y);\n    setPlacement(result.placement);\n    setStrategy(result.strategy);\n    setMiddlewareData(result.middlewareData);\n    setIsPositioned(true);\n  };\n\n  createEffect(() => {\n    const refEl = reference();\n    const floatEl = floating();\n    // 主动读取，建立依赖：placement/strategy/middleware 若是响应式访问器，\n    // 变化时也会重新进入这个 effect 并重新计算 + 重新挂 autoUpdate。\n    unwrap(options.placement, \"bottom\");\n    unwrap(options.strategy, \"absolute\");\n    unwrap(options.middleware, []);\n\n    if (!refEl || !floatEl) {\n      setIsPositioned(false);\n      return;\n    }\n\n    update();\n\n    if (options.autoUpdate !== false) {\n      const cleanup = attachAutoUpdate(\n        refEl,\n        floatEl,\n        update,\n        typeof options.autoUpdate === \"object\" ? options.autoUpdate : {},\n      );\n      onCleanup(cleanup);\n    }\n  });\n\n  const floatingStyles = createMemo(() => ({\n    position: strategy(),\n    top: \"0px\",\n    left: \"0px\",\n    // 用 transform 而非 top/left 赋值，避免触发 layout，性能更好\n    transform: `translate(${Math.round(x())}px, ${Math.round(y())}px)`,\n  }));\n\n  return {\n    x,\n    y,\n    placement,\n    strategy,\n    middlewareData,\n    isPositioned,\n    update,\n    floatingStyles,\n  };\n}\n"],"mappings":";;;;AAsBA,SAAS,EAAU,GAAqC,GAAgB;CAEtE,OADI,MAAU,KAAA,IAAkB,IACzB,OAAO,KAAU,aAAc,EAAsB,IAAI;AAClE;AA6DA,SAAgB,EACd,GACA,GACA,IAAmC,CAAC,GACxB;CACZ,IAAM,CAAC,GAAG,KAAQ,EAAa,CAAC,GAC1B,CAAC,GAAG,KAAQ,EAAa,CAAC,GAC1B,CAAC,GAAW,KAAgB,EAChC,EAAO,EAAQ,WAAW,QAAQ,CACpC,GACM,CAAC,GAAU,KAAe,EAC9B,EAAO,EAAQ,UAAU,UAAU,CACrC,GACM,CAAC,GAAgB,KAAqB,EAA6B,CAAC,CAAC,GACrE,CAAC,GAAc,KAAmB,EAAa,EAAK,GAEpD,UAAe;EACnB,IAAM,IAAQ,EAAU,GAClB,IAAU,EAAS;EACzB,IAAI,CAAC,KAAS,CAAC,GAAS;GACtB,EAAgB,EAAK;GACrB;EACF;EAEA,IAAM,IAAS,EAAgB,GAAO,GAAS;GAC7C,WAAW,EAAO,EAAQ,WAAW,QAAQ;GAC7C,UAAU,EAAO,EAAQ,UAAU,UAAU;GAC7C,YAAY,EAAO,EAAQ,YAAY,CAAC,CAAC;EAC3C,CAAC;EASD,AALA,EAAK,EAAO,CAAC,GACb,EAAK,EAAO,CAAC,GACb,EAAa,EAAO,SAAS,GAC7B,EAAY,EAAO,QAAQ,GAC3B,EAAkB,EAAO,cAAc,GACvC,EAAgB,EAAI;CACtB;CAqCA,OAnCA,QAAmB;EACjB,IAAM,IAAQ,EAAU,GAClB,IAAU,EAAS;EAOzB,IAJA,EAAO,EAAQ,WAAW,QAAQ,GAClC,EAAO,EAAQ,UAAU,UAAU,GACnC,EAAO,EAAQ,YAAY,CAAC,CAAC,GAEzB,CAAC,KAAS,CAAC,GAAS;GACtB,EAAgB,EAAK;GACrB;EACF;EAIA,IAFA,EAAO,GAEH,EAAQ,eAAe,IAAO;GAChC,IAAM,IAAU,EACd,GACA,GACA,GACA,OAAO,EAAQ,cAAe,WAAW,EAAQ,aAAa,CAAC,CACjE;GACA,EAAU,CAAO;EACnB;CACF,CAAC,GAUM;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA,gBAhBqB,SAAkB;GACvC,UAAU,EAAS;GACnB,KAAK;GACL,MAAM;GAEN,WAAW,aAAa,KAAK,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC,EAAE;EAChE,EAUE;CACF;AACF"}

package/dist/lib/positioner/index.d.ts

@@ -0,0 +1,11 @@
+export { createPositioner } from './create-positioner';
+export type { CreatePositionerOptions, Positioner } from './create-positioner';
+export { computePosition } from './core/compute-position';
+export { getSide, getAlignment, getOppositePlacement, getOppositeAlignmentPlacement, ALL_PLACEMENTS, } from './core/placement';
+export { autoUpdate } from './auto-update';
+export type { AutoUpdateOptions } from './auto-update';
+export { createVirtualElement } from './virtual-element';
+export type { PointOptions } from './virtual-element';
+export { offset, shift, flip, arrow, size, hide, containingBlockOffset, } from './middleware';
+export type { OffsetOptions, OffsetValue, ShiftOptions, FlipOptions, ArrowOptions, ArrowData, SizeOptions, SizeAvailableSpace, HideOptions, HideData, } from './middleware';
+export type { Placement, Side, Alignment, AlignedPlacement, Strategy, Axis, Coords, Rect, ElementRects, Elements, ReferenceElement, VirtualElement, Middleware, MiddlewareData, MiddlewareState, MiddlewareReturn, ComputePositionConfig, ComputePositionReturn, Boundary, } from './types';

package/dist/lib/positioner/middleware/arrow.d.ts

@@ -0,0 +1,23 @@
+import { Middleware } from '../types';
+import { getSide } from '../core/placement';
+export interface ArrowOptions {
+    /**
+     * 箭头 DOM 元素，或返回该元素的函数（Solid 场景下常传一个访问器）。
+     * 类型是 Element 而不是 HTMLElement，是为了兼容 SVG 场景下用 <svg> 画箭头的写法
+     * （SVGSVGElement 不是 HTMLElement 的子类型）。
+     */
+    element: Element | undefined | (() => Element | undefined);
+    /** 箭头距 floating 边缘的最小间距，默认 4 */
+    padding?: number;
+}
+export interface ArrowData {
+    x?: number;
+    y?: number;
+    /** 箭头应贴靠 floating 的哪一侧（与 floating 的 placement 主边相同） */
+    side: ReturnType<typeof getSide>;
+}
+/**
+ * 计算箭头相对 floating 元素左上角的 x/y 偏移，
+ * 使其始终指向 reference 元素中心，同时不超出 floating 边界。
+ */
+export declare function arrow(options: ArrowOptions): Middleware;

package/dist/lib/positioner/middleware/arrow.js

@@ -0,0 +1,23 @@
+import { getSide as e, isVerticalSide as t } from "../core/placement.js";
+//#region src/lib/positioner/middleware/arrow.ts
+function n(n) {
+	return {
+		name: "arrow",
+		fn(r) {
+			let i = typeof n.element == "function" ? n.element() : n.element, a = e(r.placement);
+			if (!i) return { data: { side: a } };
+			let { rects: o, x: s, y: c } = r, l = n.padding ?? 4, u = t(a), d = i.getBoundingClientRect(), f = d.width || 0, p = d.height || 0, m = r.elements.floating.getBoundingClientRect(), h = u ? m.width : m.height, g = u ? f : p, _ = (u ? o.reference.x + o.reference.width / 2 - s : o.reference.y + o.reference.height / 2 - c) - g / 2, v = l, y = h - g - l;
+			return _ = Math.min(Math.max(_, v), Math.max(v, y)), { data: u ? {
+				x: _,
+				side: a
+			} : {
+				y: _,
+				side: a
+			} };
+		}
+	};
+}
+//#endregion
+export { n as arrow };
+
+//# sourceMappingURL=arrow.js.map

package/dist/lib/positioner/middleware/arrow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrow.js","names":[],"sources":["../../../../src/lib/positioner/middleware/arrow.ts"],"sourcesContent":["import type { Middleware } from \"../types\";\nimport { getSide, isVerticalSide } from \"../core/placement\";\n\nexport interface ArrowOptions {\n  /**\n   * 箭头 DOM 元素，或返回该元素的函数（Solid 场景下常传一个访问器）。\n   * 类型是 Element 而不是 HTMLElement，是为了兼容 SVG 场景下用 <svg> 画箭头的写法\n   * （SVGSVGElement 不是 HTMLElement 的子类型）。\n   */\n  element: Element | undefined | (() => Element | undefined);\n  /** 箭头距 floating 边缘的最小间距，默认 4 */\n  padding?: number;\n}\n\nexport interface ArrowData {\n  x?: number;\n  y?: number;\n  /** 箭头应贴靠 floating 的哪一侧（与 floating 的 placement 主边相同） */\n  side: ReturnType<typeof getSide>;\n}\n\n/**\n * 计算箭头相对 floating 元素左上角的 x/y 偏移，\n * 使其始终指向 reference 元素中心，同时不超出 floating 边界。\n */\nexport function arrow(options: ArrowOptions): Middleware {\n  return {\n    name: \"arrow\",\n    fn(state) {\n      const el =\n        typeof options.element === \"function\"\n          ? options.element()\n          : options.element;\n      const side = getSide(state.placement);\n      if (!el) return { data: { side } };\n\n      const { rects, x, y } = state;\n      const padding = options.padding ?? 4;\n      const vertical = isVerticalSide(side);\n\n      // 用 getBoundingClientRect 而不是 offsetWidth/offsetHeight：后者只有\n      // HTMLElement 才有，SVG 元素（比如 <svg>/<g>）没有这两个属性；\n      // getBoundingClientRect 对所有 Element 都通用，只要箭头本身没有做\n      // CSS transform（本库的 TooltipArrow 就是特意不用 rotate 来避免这个问题）。\n      const arrowRect = el.getBoundingClientRect();\n      const arrowWidth = arrowRect.width || 0;\n      const arrowHeight = arrowRect.height || 0;\n\n      // 关键：floating 的宽高现读现用，不用 state.rects.floating（那是这一轮\n      // computePosition 刚开始时缓存的值）。如果 arrow 前面排了 size 这类会\n      // 通过 apply 回调产生 DOM 副作用（比如响应式地改 max-width）的 middleware，\n      // 而且这次副作用刚好同步生效了，state.rects.floating 就会是“改之前”的\n      // 旧尺寸，用它算出来的箭头位置会带着一个固定的偏移量，跟最终实际渲染的\n      // 盒子宽度对不上。这里现场重新measure，保证永远拿到当下最新的尺寸。\n      const freshFloatingRect = state.elements.floating.getBoundingClientRect();\n      const axisLen = vertical\n        ? freshFloatingRect.width\n        : freshFloatingRect.height;\n      const arrowLen = vertical ? arrowWidth : arrowHeight;\n\n      // reference 中心点相对 floating 左上角的位置\n      const refCenter = vertical\n        ? rects.reference.x + rects.reference.width / 2 - x\n        : rects.reference.y + rects.reference.height / 2 - y;\n\n      let pos = refCenter - arrowLen / 2;\n      const min = padding;\n      const max = axisLen - arrowLen - padding;\n      pos = Math.min(Math.max(pos, min), Math.max(min, max));\n\n      const data: ArrowData = vertical ? { x: pos, side } : { y: pos, side };\n      return { data };\n    },\n  };\n}\n"],"mappings":";;AAyBA,SAAgB,EAAM,GAAmC;CACvD,OAAO;EACL,MAAM;EACN,GAAG,GAAO;GACR,IAAM,IACJ,OAAO,EAAQ,WAAY,aACvB,EAAQ,QAAQ,IAChB,EAAQ,SACR,IAAO,EAAQ,EAAM,SAAS;GACpC,IAAI,CAAC,GAAI,OAAO,EAAE,MAAM,EAAE,QAAK,EAAE;GAEjC,IAAM,EAAE,UAAO,MAAG,SAAM,GAClB,IAAU,EAAQ,WAAW,GAC7B,IAAW,EAAe,CAAI,GAM9B,IAAY,EAAG,sBAAsB,GACrC,IAAa,EAAU,SAAS,GAChC,IAAc,EAAU,UAAU,GAQlC,IAAoB,EAAM,SAAS,SAAS,sBAAsB,GAClE,IAAU,IACZ,EAAkB,QAClB,EAAkB,QAChB,IAAW,IAAW,IAAa,GAOrC,KAJc,IACd,EAAM,UAAU,IAAI,EAAM,UAAU,QAAQ,IAAI,IAChD,EAAM,UAAU,IAAI,EAAM,UAAU,SAAS,IAAI,KAE/B,IAAW,GAC3B,IAAM,GACN,IAAM,IAAU,IAAW;GAIjC,OAHA,IAAM,KAAK,IAAI,KAAK,IAAI,GAAK,CAAG,GAAG,KAAK,IAAI,GAAK,CAAG,CAAC,GAG9C,EAAE,MADe,IAAW;IAAE,GAAG;IAAK;GAAK,IAAI;IAAE,GAAG;IAAK;GAAK,EACvD;EAChB;CACF;AACF"}

package/dist/lib/positioner/middleware/containing-block-offset.d.ts

@@ -0,0 +1,27 @@
+import { Middleware } from '../types';
+/**
+ * 修正因祖先元素设置了 transform / filter / perspective / backdrop-filter /
+ * will-change / contain 等 CSS 属性，导致 position:fixed（部分情况下
+ * position:absolute 也一样）的包含块被从“视口”重新定义成该祖先自身，
+ * 从而让按视口坐标算出来的 x/y 出现系统性偏移的问题。
+ *
+ * 典型症状：demo 页面里定位完全正常，放进真实项目（尤其是大量使用
+ * transform 做拖拽/缩放/面板动画的应用，比如设计工具、看板、画布编辑器）
+ * 后，浮层整体固定偏移某个方向，但相对位置关系（比如箭头跟着内容一起偏）
+ * 保持不变——这正是“坐标系被祖先重新定义”而不是“定位算法算错了”的特征。
+ *
+ * 原理：从 floating 元素实际的 DOM 父节点开始向上查找，找到第一个会重新
+ * 定义包含块的祖先，用它的 getBoundingClientRect() 反推出这个“意外包含块”
+ * 相对视口的偏移量，从最终坐标里减掉，抵消这个偏移。
+ *
+ * 局限：只处理纯平移类的偏移（比如 translate、面板展开动画、GPU 加速常见的
+ * translateZ(0)）。如果那个祖先同时还做了 scale/rotate，这里不会做矩阵换算，
+ * 位置依然会有偏差——遇到这种情况，更彻底的办法是让 Portal 挂载点脱离那个
+ * 祖先（比如手动把挂载点换成真正不受影响的 document.body，而不是应用内部
+ * 某个嵌套很深的容器）。
+ *
+ * 建议放在 middleware 数组的最后一位——它修正的是“最终要写进 DOM 的坐标”，
+ * 前面 offset/flip/shift/size/arrow 等都在统一的视口坐标系里计算，不受影响，
+ * 只有真正落地前的这一步需要额外修正。
+ */
+export declare function containingBlockOffset(): Middleware;

package/dist/lib/positioner/middleware/containing-block-offset.js

@@ -0,0 +1,46 @@
+//#region src/lib/positioner/middleware/containing-block-offset.ts
+var e = [
+	"transform",
+	"perspective",
+	"filter",
+	"backdropFilter"
+];
+function t(t) {
+	for (let n of e) {
+		let e = t[n];
+		if (e && e !== "none") return !0;
+	}
+	let n = t.willChange || "";
+	if (/transform|perspective|filter/.test(n)) return !0;
+	let r = t.contain || "";
+	return !!/paint|layout|strict|content/.test(r);
+}
+function n() {
+	return {
+		name: "containingBlockOffset",
+		fn(e) {
+			let n = e.elements.floating.parentElement, r = 0, i = 0, a = null;
+			for (; n && n !== document.documentElement;) {
+				if (t(getComputedStyle(n))) {
+					let e = n.getBoundingClientRect();
+					r = e.x, i = e.y, a = n;
+					break;
+				}
+				n = n.parentElement;
+			}
+			return !a || r === 0 && i === 0 ? { data: { ancestor: null } } : {
+				x: e.x - r,
+				y: e.y - i,
+				data: {
+					ancestor: a,
+					offsetX: r,
+					offsetY: i
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { n as containingBlockOffset };
+
+//# sourceMappingURL=containing-block-offset.js.map

package/dist/lib/positioner/middleware/containing-block-offset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containing-block-offset.js","names":[],"sources":["../../../../src/lib/positioner/middleware/containing-block-offset.ts"],"sourcesContent":["import type { Middleware } from \"../types\";\n\nconst TRANSFORM_STYLE_PROPS = [\n  \"transform\",\n  \"perspective\",\n  \"filter\",\n  \"backdropFilter\",\n] as const;\n\nfunction establishesContainingBlock(style: CSSStyleDeclaration): boolean {\n  for (const prop of TRANSFORM_STYLE_PROPS) {\n    const value = style[prop as keyof CSSStyleDeclaration] as\n      | string\n      | undefined;\n    if (value && value !== \"none\") return true;\n  }\n  const willChange = style.willChange || \"\";\n  if (/transform|perspective|filter/.test(willChange)) return true;\n  const contain = style.contain || \"\";\n  if (/paint|layout|strict|content/.test(contain)) return true;\n  return false;\n}\n\n/**\n * 修正因祖先元素设置了 transform / filter / perspective / backdrop-filter /\n * will-change / contain 等 CSS 属性，导致 position:fixed（部分情况下\n * position:absolute 也一样）的包含块被从“视口”重新定义成该祖先自身，\n * 从而让按视口坐标算出来的 x/y 出现系统性偏移的问题。\n *\n * 典型症状：demo 页面里定位完全正常，放进真实项目（尤其是大量使用\n * transform 做拖拽/缩放/面板动画的应用，比如设计工具、看板、画布编辑器）\n * 后，浮层整体固定偏移某个方向，但相对位置关系（比如箭头跟着内容一起偏）\n * 保持不变——这正是“坐标系被祖先重新定义”而不是“定位算法算错了”的特征。\n *\n * 原理：从 floating 元素实际的 DOM 父节点开始向上查找，找到第一个会重新\n * 定义包含块的祖先，用它的 getBoundingClientRect() 反推出这个“意外包含块”\n * 相对视口的偏移量，从最终坐标里减掉，抵消这个偏移。\n *\n * 局限：只处理纯平移类的偏移（比如 translate、面板展开动画、GPU 加速常见的\n * translateZ(0)）。如果那个祖先同时还做了 scale/rotate，这里不会做矩阵换算，\n * 位置依然会有偏差——遇到这种情况，更彻底的办法是让 Portal 挂载点脱离那个\n * 祖先（比如手动把挂载点换成真正不受影响的 document.body，而不是应用内部\n * 某个嵌套很深的容器）。\n *\n * 建议放在 middleware 数组的最后一位——它修正的是“最终要写进 DOM 的坐标”，\n * 前面 offset/flip/shift/size/arrow 等都在统一的视口坐标系里计算，不受影响，\n * 只有真正落地前的这一步需要额外修正。\n */\nexport function containingBlockOffset(): Middleware {\n  return {\n    name: \"containingBlockOffset\",\n    fn(state) {\n      const floatingEl = state.elements.floating;\n      let node: Element | null = floatingEl.parentElement;\n      let offsetX = 0;\n      let offsetY = 0;\n      let foundAncestor: Element | null = null;\n\n      while (node && node !== document.documentElement) {\n        const style = getComputedStyle(node);\n        if (establishesContainingBlock(style)) {\n          const rect = node.getBoundingClientRect();\n          offsetX = rect.x;\n          offsetY = rect.y;\n          foundAncestor = node;\n          break;\n        }\n        node = node.parentElement;\n      }\n\n      if (!foundAncestor || (offsetX === 0 && offsetY === 0)) {\n        return { data: { ancestor: null } };\n      }\n\n      return {\n        x: state.x - offsetX,\n        y: state.y - offsetY,\n        data: { ancestor: foundAncestor, offsetX, offsetY },\n      };\n    },\n  };\n}\n"],"mappings":";AAEA,IAAM,IAAwB;CAC5B;CACA;CACA;CACA;AACF;AAEA,SAAS,EAA2B,GAAqC;CACvE,KAAK,IAAM,KAAQ,GAAuB;EACxC,IAAM,IAAQ,EAAM;EAGpB,IAAI,KAAS,MAAU,QAAQ,OAAO;CACxC;CACA,IAAM,IAAa,EAAM,cAAc;CACvC,IAAI,+BAA+B,KAAK,CAAU,GAAG,OAAO;CAC5D,IAAM,IAAU,EAAM,WAAW;CAEjC,OADA,EAAI,8BAA8B,KAAK,CAAO;AAEhD;AA2BA,SAAgB,IAAoC;CAClD,OAAO;EACL,MAAM;EACN,GAAG,GAAO;GAER,IAAI,IADe,EAAM,SAAS,SACI,eAClC,IAAU,GACV,IAAU,GACV,IAAgC;GAEpC,OAAO,KAAQ,MAAS,SAAS,kBAAiB;IAEhD,IAAI,EADU,iBAAiB,CACA,CAAK,GAAG;KACrC,IAAM,IAAO,EAAK,sBAAsB;KAGxC,AAFA,IAAU,EAAK,GACf,IAAU,EAAK,GACf,IAAgB;KAChB;IACF;IACA,IAAO,EAAK;GACd;GAMA,OAJI,CAAC,KAAkB,MAAY,KAAK,MAAY,IAC3C,EAAE,MAAM,EAAE,UAAU,KAAK,EAAE,IAG7B;IACL,GAAG,EAAM,IAAI;IACb,GAAG,EAAM,IAAI;IACb,MAAM;KAAE,UAAU;KAAe;KAAS;IAAQ;GACpD;EACF;CACF;AACF"}

package/dist/lib/positioner/middleware/flip.d.ts

@@ -0,0 +1,9 @@
+import { Boundary, Middleware, Placement } from '../types';
+export interface FlipOptions {
+    padding?: number;
+    boundary?: Boundary;
+    /** 翻转候选 placement 列表，按顺序尝试，默认只翻转到正对面 */
+    fallbackPlacements?: Placement[];
+}
+/** 当主轴方向空间不够时，翻转到相对的 placement（如 bottom -> top） */
+export declare function flip(options?: FlipOptions): Middleware;

package/dist/lib/positioner/middleware/flip.js

@@ -0,0 +1,54 @@
+import { getViewportBoundary as e } from "../utils/dom.js";
+import { computeCoordsFromPlacement as t, getOppositePlacement as n, getSide as r } from "../core/placement.js";
+//#region src/lib/positioner/middleware/flip.ts
+function i(e, t, n, r, i) {
+	return {
+		top: i.y - t,
+		left: i.x - e,
+		right: e + n - (i.x + i.width),
+		bottom: t + r - (i.y + i.height)
+	};
+}
+function a(e, t) {
+	switch (e) {
+		case "top": return t.top;
+		case "bottom": return t.bottom;
+		case "left": return t.left;
+		case "right": return t.right;
+	}
+}
+function o(o = {}) {
+	return {
+		name: "flip",
+		fn(s) {
+			let { x: c, y: l, rects: u, placement: d, strategy: f, middlewareData: p, initialPlacement: m } = s;
+			if (p.flip?.flipped) return {};
+			let { padding: h = 0 } = o, g = o.boundary ?? e(f, h), _ = i(c, l, u.floating.width, u.floating.height, g), v = a(r(d), _);
+			if (v <= 0) return {};
+			let y = o.fallbackPlacements ?? [n(m)], b = null;
+			for (let e of y) {
+				if (e === d) continue;
+				let n = t(u, e), o = i(n.x, n.y, u.floating.width, u.floating.height, g), s = a(r(e), o);
+				if (s <= 0) {
+					b = {
+						placement: e,
+						overflow: s
+					};
+					break;
+				}
+				(!b || s < b.overflow) && (b = {
+					placement: e,
+					overflow: s
+				});
+			}
+			return !b || b.overflow >= v ? {} : {
+				reset: { placement: b.placement },
+				data: { flipped: !0 }
+			};
+		}
+	};
+}
+//#endregion
+export { o as flip };
+
+//# sourceMappingURL=flip.js.map

package/dist/lib/positioner/middleware/flip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flip.js","names":[],"sources":["../../../../src/lib/positioner/middleware/flip.ts"],"sourcesContent":["import type { Boundary, Middleware, Placement, Side } from \"../types\";\nimport { getViewportBoundary } from \"../utils/dom\";\nimport {\n  computeCoordsFromPlacement,\n  getOppositePlacement,\n  getSide,\n} from \"../core/placement\";\n\nexport interface FlipOptions {\n  padding?: number;\n  boundary?: Boundary;\n  /** 翻转候选 placement 列表，按顺序尝试，默认只翻转到正对面 */\n  fallbackPlacements?: Placement[];\n}\n\ninterface SideOverflow {\n  top: number;\n  right: number;\n  bottom: number;\n  left: number;\n}\n\nfunction getSideOverflow(\n  x: number,\n  y: number,\n  width: number,\n  height: number,\n  boundary: Boundary,\n): SideOverflow {\n  return {\n    top: boundary.y - y,\n    left: boundary.x - x,\n    right: x + width - (boundary.x + boundary.width),\n    bottom: y + height - (boundary.y + boundary.height),\n  };\n}\n\n/** 取某个 placement 主轴方向对应的溢出量（正数代表溢出了多少像素） */\nfunction getMainAxisOverflow(side: Side, overflow: SideOverflow): number {\n  switch (side) {\n    case \"top\":\n      return overflow.top;\n    case \"bottom\":\n      return overflow.bottom;\n    case \"left\":\n      return overflow.left;\n    case \"right\":\n      return overflow.right;\n  }\n}\n\n/** 当主轴方向空间不够时，翻转到相对的 placement（如 bottom -> top） */\nexport function flip(options: FlipOptions = {}): Middleware {\n  return {\n    name: \"flip\",\n    fn(state) {\n      const {\n        x,\n        y,\n        rects,\n        placement,\n        strategy,\n        middlewareData,\n        initialPlacement,\n      } = state;\n\n      // 已经翻转过一次就不再继续翻，避免来回震荡\n      if (middlewareData.flip?.flipped) return {};\n\n      const { padding = 0 } = options;\n      const boundary =\n        options.boundary ?? getViewportBoundary(strategy, padding);\n\n      const currentOverflow = getSideOverflow(\n        x,\n        y,\n        rects.floating.width,\n        rects.floating.height,\n        boundary,\n      );\n      const currentMainOverflow = getMainAxisOverflow(\n        getSide(placement),\n        currentOverflow,\n      );\n\n      // 当前方向够放，不需要翻\n      if (currentMainOverflow <= 0) return {};\n\n      const candidates = options.fallbackPlacements ?? [\n        getOppositePlacement(initialPlacement),\n      ];\n\n      let best: { placement: Placement; overflow: number } | null = null;\n\n      for (const candidate of candidates) {\n        if (candidate === placement) continue;\n\n        // 关键修复点：真正代入候选 placement 算出它的坐标，再算它自己的真实溢出量，\n        // 而不是用当前（本就溢出的）placement 的 overflow 去做错误的镜像估算。\n        const candidateCoords = computeCoordsFromPlacement(rects, candidate);\n        const candidateOverflow = getSideOverflow(\n          candidateCoords.x,\n          candidateCoords.y,\n          rects.floating.width,\n          rects.floating.height,\n          boundary,\n        );\n        const candidateMainOverflow = getMainAxisOverflow(\n          getSide(candidate),\n          candidateOverflow,\n        );\n\n        if (candidateMainOverflow <= 0) {\n          best = { placement: candidate, overflow: candidateMainOverflow };\n          break; // 找到完全不溢出的候选，直接采用\n        }\n        if (!best || candidateMainOverflow < best.overflow) {\n          best = { placement: candidate, overflow: candidateMainOverflow };\n        }\n      }\n\n      // 没有候选，或翻过去也不比现在好，就不翻\n      if (!best || best.overflow >= currentMainOverflow) return {};\n\n      return {\n        reset: { placement: best.placement },\n        data: { flipped: true },\n      };\n    },\n  };\n}\n"],"mappings":";;;AAsBA,SAAS,EACP,GACA,GACA,GACA,GACA,GACc;CACd,OAAO;EACL,KAAK,EAAS,IAAI;EAClB,MAAM,EAAS,IAAI;EACnB,OAAO,IAAI,KAAS,EAAS,IAAI,EAAS;EAC1C,QAAQ,IAAI,KAAU,EAAS,IAAI,EAAS;CAC9C;AACF;AAGA,SAAS,EAAoB,GAAY,GAAgC;CACvE,QAAQ,GAAR;EACE,KAAK,OACH,OAAO,EAAS;EAClB,KAAK,UACH,OAAO,EAAS;EAClB,KAAK,QACH,OAAO,EAAS;EAClB,KAAK,SACH,OAAO,EAAS;CACpB;AACF;AAGA,SAAgB,EAAK,IAAuB,CAAC,GAAe;CAC1D,OAAO;EACL,MAAM;EACN,GAAG,GAAO;GACR,IAAM,EACJ,MACA,MACA,UACA,cACA,aACA,mBACA,wBACE;GAGJ,IAAI,EAAe,MAAM,SAAS,OAAO,CAAC;GAE1C,IAAM,EAAE,aAAU,MAAM,GAClB,IACJ,EAAQ,YAAY,EAAoB,GAAU,CAAO,GAErD,IAAkB,EACtB,GACA,GACA,EAAM,SAAS,OACf,EAAM,SAAS,QACf,CACF,GACM,IAAsB,EAC1B,EAAQ,CAAS,GACjB,CACF;GAGA,IAAI,KAAuB,GAAG,OAAO,CAAC;GAEtC,IAAM,IAAa,EAAQ,sBAAsB,CAC/C,EAAqB,CAAgB,CACvC,GAEI,IAA0D;GAE9D,KAAK,IAAM,KAAa,GAAY;IAClC,IAAI,MAAc,GAAW;IAI7B,IAAM,IAAkB,EAA2B,GAAO,CAAS,GAC7D,IAAoB,EACxB,EAAgB,GAChB,EAAgB,GAChB,EAAM,SAAS,OACf,EAAM,SAAS,QACf,CACF,GACM,IAAwB,EAC5B,EAAQ,CAAS,GACjB,CACF;IAEA,IAAI,KAAyB,GAAG;KAC9B,IAAO;MAAE,WAAW;MAAW,UAAU;KAAsB;KAC/D;IACF;IACA,CAAI,CAAC,KAAQ,IAAwB,EAAK,cACxC,IAAO;KAAE,WAAW;KAAW,UAAU;IAAsB;GAEnE;GAKA,OAFI,CAAC,KAAQ,EAAK,YAAY,IAA4B,CAAC,IAEpD;IACL,OAAO,EAAE,WAAW,EAAK,UAAU;IACnC,MAAM,EAAE,SAAS,GAAK;GACxB;EACF;CACF;AACF"}

package/dist/lib/positioner/middleware/hide.d.ts

@@ -0,0 +1,22 @@
+import { Boundary, Middleware } from '../types';
+export interface HideOptions {
+    padding?: number;
+    boundary?: Boundary;
+    /**
+     * 'referenceHidden'：reference 元素被自身滚动容器完全裁掉（比如滚出了可滚动的父级）
+     * 'escaped'：floating 元素虽然还在视口内，但已经完全脱离了 reference 所在的边界
+     *（比如 reference 在一个卡片里被横向滚动挡住了一半，虽然 floating 还能摆在视口里，
+     *  但已经不该再显示，否则看起来像是"飘"在别的内容上）
+     * 默认只做 referenceHidden 检测，这是最常见也最需要的场景。
+     */
+    strategy?: "referenceHidden" | "escaped";
+}
+export interface HideData {
+    referenceHidden?: boolean;
+    escaped?: boolean;
+}
+/**
+ * 不改变坐标，只产出"是否应该隐藏浮层"的判断数据，交给上层组件决定要不要渲染。
+ * 用法：在业务组件里读 `middlewareData().hide?.referenceHidden`，为 true 时关闭浮层。
+ */
+export declare function hide(options?: HideOptions): Middleware;

package/dist/lib/positioner/middleware/hide.js

@@ -0,0 +1,19 @@
+import { getRectRelativeTo as e, getViewportBoundary as t } from "../utils/dom.js";
+//#region src/lib/positioner/middleware/hide.ts
+function n(n = {}) {
+	return {
+		name: "hide",
+		fn(r) {
+			let { x: i, y: a, rects: o, strategy: s, elements: c } = r, { padding: l = 0, strategy: u = "referenceHidden" } = n, d = n.boundary ?? t(s, l), f = {};
+			if (u === "referenceHidden") {
+				let t = e(c.reference, s);
+				f.referenceHidden = t.x + t.width <= d.x || t.y + t.height <= d.y || t.x >= d.x + d.width || t.y >= d.y + d.height;
+			}
+			return u === "escaped" && (f.escaped = i + o.floating.width <= d.x || a + o.floating.height <= d.y || i >= d.x + d.width || a >= d.y + d.height), { data: f };
+		}
+	};
+}
+//#endregion
+export { n as hide };
+
+//# sourceMappingURL=hide.js.map

package/dist/lib/positioner/middleware/hide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hide.js","names":[],"sources":["../../../../src/lib/positioner/middleware/hide.ts"],"sourcesContent":["import type { Boundary, Middleware } from \"../types\";\nimport { getViewportBoundary, getRectRelativeTo } from \"../utils/dom\";\n\nexport interface HideOptions {\n  padding?: number;\n  boundary?: Boundary;\n  /**\n   * 'referenceHidden'：reference 元素被自身滚动容器完全裁掉（比如滚出了可滚动的父级）\n   * 'escaped'：floating 元素虽然还在视口内，但已经完全脱离了 reference 所在的边界\n   *（比如 reference 在一个卡片里被横向滚动挡住了一半，虽然 floating 还能摆在视口里，\n   *  但已经不该再显示，否则看起来像是\"飘\"在别的内容上）\n   * 默认只做 referenceHidden 检测，这是最常见也最需要的场景。\n   */\n  strategy?: \"referenceHidden\" | \"escaped\";\n}\n\nexport interface HideData {\n  referenceHidden?: boolean;\n  escaped?: boolean;\n}\n\n/**\n * 不改变坐标，只产出\"是否应该隐藏浮层\"的判断数据，交给上层组件决定要不要渲染。\n * 用法：在业务组件里读 `middlewareData().hide?.referenceHidden`，为 true 时关闭浮层。\n */\nexport function hide(options: HideOptions = {}): Middleware {\n  return {\n    name: \"hide\",\n    fn(state) {\n      const { x, y, rects, strategy: positionStrategy, elements } = state;\n      const { padding = 0, strategy = \"referenceHidden\" } = options;\n      const boundary =\n        options.boundary ?? getViewportBoundary(positionStrategy, padding);\n\n      const data: HideData = {};\n\n      if (strategy === \"referenceHidden\") {\n        const refRect = getRectRelativeTo(elements.reference, positionStrategy);\n        const referenceHidden =\n          refRect.x + refRect.width <= boundary.x ||\n          refRect.y + refRect.height <= boundary.y ||\n          refRect.x >= boundary.x + boundary.width ||\n          refRect.y >= boundary.y + boundary.height;\n        data.referenceHidden = referenceHidden;\n      }\n\n      if (strategy === \"escaped\") {\n        const escaped =\n          x + rects.floating.width <= boundary.x ||\n          y + rects.floating.height <= boundary.y ||\n          x >= boundary.x + boundary.width ||\n          y >= boundary.y + boundary.height;\n        data.escaped = escaped;\n      }\n\n      return { data };\n    },\n  };\n}\n"],"mappings":";;AAyBA,SAAgB,EAAK,IAAuB,CAAC,GAAe;CAC1D,OAAO;EACL,MAAM;EACN,GAAG,GAAO;GACR,IAAM,EAAE,MAAG,MAAG,UAAO,UAAU,GAAkB,gBAAa,GACxD,EAAE,aAAU,GAAG,cAAW,sBAAsB,GAChD,IACJ,EAAQ,YAAY,EAAoB,GAAkB,CAAO,GAE7D,IAAiB,CAAC;GAExB,IAAI,MAAa,mBAAmB;IAClC,IAAM,IAAU,EAAkB,EAAS,WAAW,CAAgB;IAMtE,EAAK,kBAJH,EAAQ,IAAI,EAAQ,SAAS,EAAS,KACtC,EAAQ,IAAI,EAAQ,UAAU,EAAS,KACvC,EAAQ,KAAK,EAAS,IAAI,EAAS,SACnC,EAAQ,KAAK,EAAS,IAAI,EAAS;GAEvC;GAWA,OATI,MAAa,cAMf,EAAK,UAJH,IAAI,EAAM,SAAS,SAAS,EAAS,KACrC,IAAI,EAAM,SAAS,UAAU,EAAS,KACtC,KAAK,EAAS,IAAI,EAAS,SAC3B,KAAK,EAAS,IAAI,EAAS,SAIxB,EAAE,QAAK;EAChB;CACF;AACF"}

package/dist/lib/positioner/middleware/index.d.ts

@@ -0,0 +1,13 @@
+export { offset } from './offset';
+export type { OffsetOptions, OffsetValue } from './offset';
+export { shift } from './shift';
+export type { ShiftOptions } from './shift';
+export { flip } from './flip';
+export type { FlipOptions } from './flip';
+export { arrow } from './arrow';
+export type { ArrowOptions, ArrowData } from './arrow';
+export { size } from './size';
+export type { SizeOptions, SizeAvailableSpace } from './size';
+export { hide } from './hide';
+export type { HideOptions, HideData } from './hide';
+export { containingBlockOffset } from './containing-block-offset';

package/dist/lib/positioner/middleware/offset.d.ts

@@ -0,0 +1,10 @@
+import { Middleware } from '../types';
+export interface OffsetValue {
+    /** 沿主轴方向的偏移（远离/靠近 reference），默认 0 */
+    mainAxis?: number;
+    /** 沿交叉轴方向的偏移（左右或上下平移），默认 0 */
+    crossAxis?: number;
+}
+export type OffsetOptions = number | OffsetValue;
+/** 让 floating 元素与 reference 保持一定间距，或沿对齐轴做微调 */
+export declare function offset(value?: OffsetOptions): Middleware;

package/dist/lib/positioner/middleware/offset.js

@@ -0,0 +1,21 @@
+import { getSide as e, isVerticalSide as t } from "../core/placement.js";
+//#region src/lib/positioner/middleware/offset.ts
+function n(n = 0) {
+	return {
+		name: "offset",
+		fn(r) {
+			let { x: i, y: a, placement: o } = r, s = e(o), c = t(s), l = typeof n == "number" ? n : n.mainAxis ?? 0, u = typeof n == "number" ? 0 : n.crossAxis ?? 0, d = l * (s === "bottom" || s === "right" ? 1 : -1);
+			return c ? {
+				x: i + u,
+				y: a + d
+			} : {
+				x: i + d,
+				y: a + u
+			};
+		}
+	};
+}
+//#endregion
+export { n as offset };
+
+//# sourceMappingURL=offset.js.map

package/dist/lib/positioner/middleware/offset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offset.js","names":[],"sources":["../../../../src/lib/positioner/middleware/offset.ts"],"sourcesContent":["import type { Middleware } from \"../types\";\nimport { getSide, isVerticalSide } from \"../core/placement\";\n\nexport interface OffsetValue {\n  /** 沿主轴方向的偏移（远离/靠近 reference），默认 0 */\n  mainAxis?: number;\n  /** 沿交叉轴方向的偏移（左右或上下平移），默认 0 */\n  crossAxis?: number;\n}\n\nexport type OffsetOptions = number | OffsetValue;\n\n/** 让 floating 元素与 reference 保持一定间距，或沿对齐轴做微调 */\nexport function offset(value: OffsetOptions = 0): Middleware {\n  return {\n    name: \"offset\",\n    fn(state) {\n      const { x, y, placement } = state;\n      const side = getSide(placement);\n      const vertical = isVerticalSide(side);\n\n      const mainAxis =\n        typeof value === \"number\" ? value : (value.mainAxis ?? 0);\n      const crossAxis = typeof value === \"number\" ? 0 : (value.crossAxis ?? 0);\n\n      // top/left 是\"负方向\"，bottom/right 是\"正方向\"\n      const mainSign = side === \"bottom\" || side === \"right\" ? 1 : -1;\n\n      const diffMain = mainAxis * mainSign;\n\n      return vertical\n        ? { x: x + crossAxis, y: y + diffMain }\n        : { x: x + diffMain, y: y + crossAxis };\n    },\n  };\n}\n"],"mappings":";;AAaA,SAAgB,EAAO,IAAuB,GAAe;CAC3D,OAAO;EACL,MAAM;EACN,GAAG,GAAO;GACR,IAAM,EAAE,MAAG,MAAG,iBAAc,GACtB,IAAO,EAAQ,CAAS,GACxB,IAAW,EAAe,CAAI,GAE9B,IACJ,OAAO,KAAU,WAAW,IAAS,EAAM,YAAY,GACnD,IAAY,OAAO,KAAU,WAAW,IAAK,EAAM,aAAa,GAKhE,IAAW,KAFA,MAAS,YAAY,MAAS,UAAU,IAAI;GAI7D,OAAO,IACH;IAAE,GAAG,IAAI;IAAW,GAAG,IAAI;GAAS,IACpC;IAAE,GAAG,IAAI;IAAU,GAAG,IAAI;GAAU;EAC1C;CACF;AACF"}

package/dist/lib/positioner/middleware/shift.d.ts

@@ -0,0 +1,13 @@
+import { Boundary, Middleware } from '../types';
+export interface ShiftOptions {
+    /** 距边界的最小间距，默认 0 */
+    padding?: number;
+    /** 自定义边界矩形，默认使用视口 */
+    boundary?: Boundary;
+    /** 是否限制主轴方向（如 top/bottom placement 的 y 方向），默认 true */
+    mainAxis?: boolean;
+    /** 是否限制交叉轴方向（如 top/bottom placement 的 x 方向），默认 true */
+    crossAxis?: boolean;
+}
+/** 平移 floating 元素，使其尽量停留在边界（默认视口）内，不做 placement 翻转 */
+export declare function shift(options?: ShiftOptions): Middleware;

package/dist/lib/positioner/middleware/shift.js

@@ -0,0 +1,30 @@
+import { getViewportBoundary as e } from "../utils/dom.js";
+//#region src/lib/positioner/middleware/shift.ts
+function t(t = {}) {
+	return {
+		name: "shift",
+		fn(n) {
+			let { x: r, y: i, rects: a, strategy: o } = n, { padding: s = 0, mainAxis: c = !0, crossAxis: l = !0 } = t, u = t.boundary ?? e(o, s), d = r, f = i;
+			if (l) {
+				let e = u.x, t = u.x + u.width - a.floating.width;
+				d = Math.min(Math.max(r, e), Math.max(e, t));
+			}
+			if (c) {
+				let e = u.y, t = u.y + u.height - a.floating.height;
+				f = Math.min(Math.max(i, e), Math.max(e, t));
+			}
+			return {
+				x: d,
+				y: f,
+				data: {
+					x: d - r,
+					y: f - i
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { t as shift };
+
+//# sourceMappingURL=shift.js.map

package/dist/lib/positioner/middleware/shift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shift.js","names":[],"sources":["../../../../src/lib/positioner/middleware/shift.ts"],"sourcesContent":["import type { Boundary, Middleware } from \"../types\";\nimport { getViewportBoundary } from \"../utils/dom\";\n\nexport interface ShiftOptions {\n  /** 距边界的最小间距，默认 0 */\n  padding?: number;\n  /** 自定义边界矩形，默认使用视口 */\n  boundary?: Boundary;\n  /** 是否限制主轴方向（如 top/bottom placement 的 y 方向），默认 true */\n  mainAxis?: boolean;\n  /** 是否限制交叉轴方向（如 top/bottom placement 的 x 方向），默认 true */\n  crossAxis?: boolean;\n}\n\n/** 平移 floating 元素，使其尽量停留在边界（默认视口）内，不做 placement 翻转 */\nexport function shift(options: ShiftOptions = {}): Middleware {\n  return {\n    name: \"shift\",\n    fn(state) {\n      const { x, y, rects, strategy } = state;\n      const { padding = 0, mainAxis = true, crossAxis = true } = options;\n      const boundary =\n        options.boundary ?? getViewportBoundary(strategy, padding);\n\n      let nextX = x;\n      let nextY = y;\n\n      if (crossAxis) {\n        const minX = boundary.x;\n        const maxX = boundary.x + boundary.width - rects.floating.width;\n        nextX = Math.min(Math.max(x, minX), Math.max(minX, maxX));\n      }\n\n      if (mainAxis) {\n        const minY = boundary.y;\n        const maxY = boundary.y + boundary.height - rects.floating.height;\n        nextY = Math.min(Math.max(y, minY), Math.max(minY, maxY));\n      }\n\n      return {\n        x: nextX,\n        y: nextY,\n        data: { x: nextX - x, y: nextY - y },\n      };\n    },\n  };\n}\n"],"mappings":";;AAeA,SAAgB,EAAM,IAAwB,CAAC,GAAe;CAC5D,OAAO;EACL,MAAM;EACN,GAAG,GAAO;GACR,IAAM,EAAE,MAAG,MAAG,UAAO,gBAAa,GAC5B,EAAE,aAAU,GAAG,cAAW,IAAM,eAAY,OAAS,GACrD,IACJ,EAAQ,YAAY,EAAoB,GAAU,CAAO,GAEvD,IAAQ,GACR,IAAQ;GAEZ,IAAI,GAAW;IACb,IAAM,IAAO,EAAS,GAChB,IAAO,EAAS,IAAI,EAAS,QAAQ,EAAM,SAAS;IAC1D,IAAQ,KAAK,IAAI,KAAK,IAAI,GAAG,CAAI,GAAG,KAAK,IAAI,GAAM,CAAI,CAAC;GAC1D;GAEA,IAAI,GAAU;IACZ,IAAM,IAAO,EAAS,GAChB,IAAO,EAAS,IAAI,EAAS,SAAS,EAAM,SAAS;IAC3D,IAAQ,KAAK,IAAI,KAAK,IAAI,GAAG,CAAI,GAAG,KAAK,IAAI,GAAM,CAAI,CAAC;GAC1D;GAEA,OAAO;IACL,GAAG;IACH,GAAG;IACH,MAAM;KAAE,GAAG,IAAQ;KAAG,GAAG,IAAQ;IAAE;GACrC;EACF;CACF;AACF"}

package/dist/lib/positioner/middleware/size.d.ts

@@ -0,0 +1,13 @@
+import { Boundary, Middleware, MiddlewareState } from '../types';
+export interface SizeAvailableSpace {
+    availableWidth: number;
+    availableHeight: number;
+}
+export interface SizeOptions {
+    padding?: number;
+    boundary?: Boundary;
+    /** 拿到可用空间后自行处理，比如设置 floating 的 maxHeight */
+    apply?: (space: SizeAvailableSpace, state: MiddlewareState) => void;
+}
+/** 计算 floating 在当前边界内的可用宽高，交给 apply 回调去应用（如设置 max-height 实现滚动） */
+export declare function size(options?: SizeOptions): Middleware;

package/dist/lib/positioner/types.d.ts

@@ -0,0 +1,74 @@
+export type Side = "top" | "right" | "bottom" | "left";
+export type Alignment = "start" | "end";
+export type AlignedPlacement = `${Side}-${Alignment}`;
+export type Placement = Side | AlignedPlacement;
+export type Strategy = "absolute" | "fixed";
+export type Axis = "x" | "y";
+export interface Coords {
+    x: number;
+    y: number;
+}
+export interface Rect extends Coords {
+    width: number;
+    height: number;
+}
+export interface ElementRects {
+    reference: Rect;
+    floating: Rect;
+}
+export interface Elements {
+    reference: ReferenceElement;
+    floating: HTMLElement;
+}
+/**
+ * 虚拟参照元素：用于锚定到一个不存在真实 DOM 节点的位置，
+ * 最典型的场景就是右键菜单——锚点是鼠标点击的那个像素坐标，不是某个元素。
+ * 只要实现 getBoundingClientRect() 就能像真实 HTMLElement 一样参与定位计算。
+ */
+export interface VirtualElement {
+    getBoundingClientRect(): Rect;
+    /**
+     * 可选：关联一个真实 DOM 节点，autoUpdate 会用它去查找可滚动祖先容器
+     * （虚拟元素本身没有父节点链，无法直接判断哪些祖先滚动会影响这个点的位置）。
+     */
+    contextElement?: Element;
+}
+export type ReferenceElement = Element | VirtualElement;
+export interface MiddlewareData {
+    [key: string]: any;
+}
+/** 传给每个 middleware 的当前计算状态 */
+export interface MiddlewareState extends Coords {
+    initialPlacement: Placement;
+    placement: Placement;
+    strategy: Strategy;
+    rects: ElementRects;
+    elements: Elements;
+    middlewareData: MiddlewareData;
+}
+export interface MiddlewareReturn extends Partial<Coords> {
+    data?: any;
+    /**
+     * 若返回该字段，表示需要用新的 placement 重新计算一轮，
+     * 主循环会用新 placement 重跑一次（用于 flip 等场景）。
+     */
+    reset?: boolean | {
+        placement?: Placement;
+    };
+}
+export interface Middleware {
+    name: string;
+    fn(state: MiddlewareState): MiddlewareReturn;
+}
+export interface ComputePositionConfig {
+    placement?: Placement;
+    strategy?: Strategy;
+    middleware?: Middleware[];
+}
+export interface ComputePositionReturn extends Coords {
+    placement: Placement;
+    strategy: Strategy;
+    middlewareData: MiddlewareData;
+}
+export interface Boundary extends Rect {
+}