@apollo-design/position 0.0.0-stage → 0.1.9

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+> 规范范围：本文件保留实现说明与历史对照证据；上游同构、旧阶段与历史 Gate 要求不再生效。现行规则见 [项目规范](../../AGENTS.md)，公共行为以 Apollo 组件 API 文档与测试契约为准。
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @apollo-design/position
+
+> **层**：L1 ｜ **风险**：high
+>
+> 本文档声明本包的**职责边界**。边界之外的事情不做 —— 如果发现需要做，说明架构需要调整，
+> 应当先修改 `ARCHITECTURE.md` 并记录 ADR。
+
+---
+
+## 职责
+
+浮层定位几何。替代 @rc-component/trigger 与 rc-tooltip 的定位部分。**只做几何与尺寸测量**，触发时机与生命周期在 @apollo-design/overlay。
+
+## 替代的 Ant Design 依赖
+
+- `@rc-component/trigger（定位部分）`
+- `@rc-component/tooltip（定位部分）`
+
+## 公开 API
+
+- placements：12 个方位（topLeft / top / topRight / bottomLeft / ...）
+- 对齐计算：getAlignResult / getAlignOffset / getArrowOffset
+- 边界处理：flip（翻转）/ shift（收缩）/ 滚动容器跟随（含祖先滚动链）
+- 坐标解析：getPopupContainer / getDocument / 可视区与滚动区计算
+- usePosition —— 把上述能力接到响应式目标与浮层元素上
+
+## 明确不做（边界）
+
+- ❌ 不实现触发时机与显隐延迟（那是 @apollo-design/overlay）
+- ❌ 不实现挂载与 z-index（那是 @apollo-design/portal）
+- ❌ 不实现任何视觉样式与 DOM 结构（只输出坐标数字）
+
+## 必须遵守的契约
+
+- ★ 定位结果必须与 antd 像素级一致（这是 AR1，本项目最大风险点）
+- 纯几何部分必须可用无 DOM 的单测验证（坐标进 → 坐标出），只有尺寸测量需要 jsdom
+- 必须支持翻转（flip）与自适应（shift）
+- 箭头位置在 12 个方位下都正确
+
+## 依赖
+
+### 运行时依赖
+
+| `@apollo-design/utils` | `workspace:*` |
+
+### peer 依赖
+
+| `vue` | `catalog:` |
+
+### 构建期 / 测试依赖（devDependencies，**不会**进入用户的依赖树）
+
+（无）
+
+## 依赖约束（ARCHITECTURE.md §3.1）
+
+- **R1 单向**：只能依赖同层或更低层
+- **R2 无环**：不得与其他包循环依赖
+- **R3 地基纯净**（仅 L0）：不得包含任何组件视觉语义
+- **R4 引擎无视觉**（仅 L2）：不得定义颜色/圆角/阴影，不得产出 CSS
+- **R6 显式声明**：跨包导入必须在本文件的 `dependencies` 中声明（`.npmrc` 已设 `hoist=false`）
+- **R7 零 Ant Design 运行时依赖**：发布包的 `dependencies` 不得出现任何 `@ant-design/*`。
+  Ant Design 生态包只允许出现在三处 —— ① 构建期数据源（`registry/tools/gen-*.mjs`）
+  ② 测试 Oracle（`*.oracle.test.ts`）③ `devDependencies`。由 `registry:validate` 的 **E19** 强制。
+
+本包的依赖已通过 `registry/tools/scaffold-packages.mjs` 的分层校验。
+
+## ⚠️ 必须先做 PoC
+
+AR1 —— 必须先做 PoC：topLeft/topRight/center/bottomLeft/bottomRight + 翻转 + 箭头，与 antd 参考截图逐像素比对
+
+在 PoC 通过之前，不得开始依赖本包的组件开发。
+
+## 测试
+
+```bash
+pnpm --filter @apollo-design/position test
+pnpm --filter @apollo-design/position lint
+```
+
+测试要求见 [`TESTING.md`](../../TESTING.md)。
+覆盖率下限为 语句 95% / 分支 90% / 函数 95%（L1 档位，见 `vitest.config.ts` 的 `coverage.thresholds`）。

package/dist/align.mjs

@@ -0,0 +1,187 @@
+import { getIntersectionArea } from './area.mjs';
+import { getNumberOffset } from './offset.mjs';
+import { splitPoints, getAlignPoint, flatPoint, reversePoint } from './point.mjs';
+
+function supportAdjust(value) {
+  if (typeof value === "boolean") return value;
+  return value !== void 0 && value >= 0;
+}
+function topLeft(rect) {
+  return getAlignPoint(rect, ["t", "l"]);
+}
+function bottomRight(rect) {
+  return getAlignPoint(rect, ["b", "r"]);
+}
+function alignPopup(ctx, align, flip = {}) {
+  const { target, popup } = ctx;
+  const scaleX = ctx.scaleX ?? 1;
+  const scaleY = ctx.scaleY ?? 1;
+  const overflow = align.overflow ?? {};
+  const [targetOffsetX, targetOffsetY] = getNumberOffset(target, align.targetOffset);
+  const targetRect = {
+    x: target.x - targetOffsetX,
+    y: target.y - targetOffsetY,
+    width: target.width,
+    height: target.height
+  };
+  let [popupOffsetX, popupOffsetY] = getNumberOffset(popup, align.offset);
+  const htmlRegion = align.htmlRegion ?? "visible";
+  const isVisibleFirst = htmlRegion === "visibleFirst";
+  const compareArea = htmlRegion === "visible" ? ctx.visible : ctx.scroll;
+  const adjustArea = htmlRegion === "scroll" ? ctx.scroll : ctx.visible;
+  const recommendArea = ctx.visible;
+  const [popupPoint, targetPoint] = align.points ?? [];
+  const targetPoints = splitPoints(targetPoint ?? "");
+  const popupPoints = splitPoints(popupPoint ?? "");
+  const targetAlignPoint = getAlignPoint(targetRect, targetPoints);
+  const popupAlignPoint = getAlignPoint(popup, popupPoints);
+  let nextPoints = [popupPoints, targetPoints];
+  let nextOffsetX = targetAlignPoint.x - popupAlignPoint.x + popupOffsetX;
+  let nextOffsetY = targetAlignPoint.y - popupAlignPoint.y + popupOffsetY;
+  const originIntersectionArea = getIntersectionArea(popup, nextOffsetX, nextOffsetY, compareArea);
+  const originRecommendArea = getIntersectionArea(popup, nextOffsetX, nextOffsetY, recommendArea);
+  const nextFlip = { ...flip };
+  const targetTL = topLeft(targetRect);
+  const targetBR = bottomRight(targetRect);
+  const popupTL = topLeft(popup);
+  const popupBR = bottomRight(popup);
+  let nextPopupY = popup.y + nextOffsetY;
+  let nextPopupBottom = nextPopupY + popup.height;
+  let nextPopupX = popup.x + nextOffsetX;
+  let nextPopupRight = nextPopupX + popup.width;
+  const tryFlip = (axis, trigger, memoryKey, compute, apply, negateOffset) => {
+    if (!trigger) return;
+    const candidate = compute();
+    const newArea = axis === 0 ? getIntersectionArea(popup, nextOffsetX, candidate, compareArea) : getIntersectionArea(popup, candidate, nextOffsetY, compareArea);
+    const newRecommend = axis === 0 ? getIntersectionArea(popup, nextOffsetX, candidate, recommendArea) : getIntersectionArea(popup, candidate, nextOffsetY, recommendArea);
+    const accepted = newArea > originIntersectionArea || newArea === originIntersectionArea && (!isVisibleFirst || newRecommend >= originRecommendArea);
+    nextFlip[memoryKey] = accepted;
+    if (!accepted) return;
+    apply(candidate);
+    negateOffset();
+    nextPoints = [reversePoint(nextPoints[0], axis), reversePoint(nextPoints[1], axis)];
+  };
+  const needAdjustY = supportAdjust(overflow.adjustY);
+  const sameTB = popupPoints[0] === targetPoints[0];
+  tryFlip(
+    0,
+    needAdjustY && popupPoints[0] === "t" && (nextPopupBottom > adjustArea.bottom || !!flip.bt),
+    "bt",
+    () => sameTB ? nextOffsetY - (popup.height - targetRect.height) : targetTL.y - popupBR.y - popupOffsetY,
+    (v) => {
+      nextOffsetY = v;
+    },
+    () => {
+      popupOffsetY = -popupOffsetY;
+    }
+  );
+  tryFlip(
+    0,
+    needAdjustY && popupPoints[0] === "b" && (nextPopupY < adjustArea.top || !!flip.tb),
+    "tb",
+    () => sameTB ? nextOffsetY + (popup.height - targetRect.height) : targetBR.y - popupTL.y - popupOffsetY,
+    (v) => {
+      nextOffsetY = v;
+    },
+    () => {
+      popupOffsetY = -popupOffsetY;
+    }
+  );
+  const needAdjustX = supportAdjust(overflow.adjustX);
+  const sameLR = popupPoints[1] === targetPoints[1];
+  tryFlip(
+    1,
+    needAdjustX && popupPoints[1] === "l" && (nextPopupRight > adjustArea.right || !!flip.rl),
+    "rl",
+    () => sameLR ? nextOffsetX - (popup.width - targetRect.width) : targetTL.x - popupBR.x - popupOffsetX,
+    (v) => {
+      nextOffsetX = v;
+    },
+    () => {
+      popupOffsetX = -popupOffsetX;
+    }
+  );
+  tryFlip(
+    1,
+    needAdjustX && popupPoints[1] === "r" && (nextPopupX < adjustArea.left || !!flip.lr),
+    "lr",
+    () => sameLR ? nextOffsetX + (popup.width - targetRect.width) : targetBR.x - popupTL.x - popupOffsetX,
+    (v) => {
+      nextOffsetX = v;
+    },
+    () => {
+      popupOffsetX = -popupOffsetX;
+    }
+  );
+  nextPopupY = popup.y + nextOffsetY;
+  nextPopupBottom = nextPopupY + popup.height;
+  nextPopupX = popup.x + nextOffsetX;
+  nextPopupRight = nextPopupX + popup.width;
+  const numShiftX = overflow.shiftX === true ? 0 : overflow.shiftX;
+  if (typeof numShiftX === "number") {
+    if (nextPopupX < recommendArea.left) {
+      nextOffsetX -= nextPopupX - recommendArea.left - popupOffsetX;
+      if (targetRect.x + targetRect.width < recommendArea.left + numShiftX) {
+        nextOffsetX += targetRect.x - recommendArea.left + targetRect.width - numShiftX;
+      }
+    }
+    if (nextPopupRight > recommendArea.right) {
+      nextOffsetX -= nextPopupRight - recommendArea.right - popupOffsetX;
+      if (targetRect.x > recommendArea.right - numShiftX) {
+        nextOffsetX += targetRect.x - recommendArea.right + numShiftX;
+      }
+    }
+  }
+  const numShiftY = overflow.shiftY === true ? 0 : overflow.shiftY;
+  if (typeof numShiftY === "number") {
+    if (nextPopupY < recommendArea.top) {
+      nextOffsetY -= nextPopupY - recommendArea.top - popupOffsetY;
+      if (targetRect.y + targetRect.height < recommendArea.top + numShiftY) {
+        nextOffsetY += targetRect.y - recommendArea.top + targetRect.height - numShiftY;
+      }
+    }
+    if (nextPopupBottom > recommendArea.bottom) {
+      nextOffsetY -= nextPopupBottom - recommendArea.bottom - popupOffsetY;
+      if (targetRect.y > recommendArea.bottom - numShiftY) {
+        nextOffsetY += targetRect.y - recommendArea.bottom + numShiftY;
+      }
+    }
+  }
+  const popupLeft = popup.x + nextOffsetX;
+  const popupRight = popupLeft + popup.width;
+  const popupTop = popup.y + nextOffsetY;
+  const popupBottom = popupTop + popup.height;
+  const targetLeft = targetRect.x;
+  const targetRight = targetLeft + targetRect.width;
+  const targetTop = targetRect.y;
+  const targetBottom = targetTop + targetRect.height;
+  const xCenter = (Math.max(popupLeft, targetLeft) + Math.min(popupRight, targetRight)) / 2;
+  const yCenter = (Math.max(popupTop, targetTop) + Math.min(popupBottom, targetBottom)) / 2;
+  const nextArrowX = xCenter - popupLeft;
+  const nextArrowY = yCenter - popupTop;
+  let finalOffsetX = nextOffsetX;
+  let finalOffsetY = nextOffsetY;
+  if (scaleX === 1) finalOffsetX = Math.floor(finalOffsetX);
+  if (scaleY === 1) finalOffsetY = Math.floor(finalOffsetY);
+  return {
+    offsetX: finalOffsetX / scaleX,
+    offsetY: finalOffsetY / scaleY,
+    arrowX: nextArrowX / scaleX,
+    arrowY: nextArrowY / scaleY,
+    points: [flatPoint(nextPoints[0]), flatPoint(nextPoints[1])],
+    flip: nextFlip,
+    overflow
+  };
+}
+function toAlignResult(outcome) {
+  return {
+    offsetX: outcome.offsetX,
+    offsetY: outcome.offsetY,
+    arrowX: outcome.arrowX,
+    arrowY: outcome.arrowY,
+    points: outcome.points,
+    flip: outcome.flip
+  };
+}
+
+export { alignPopup, toAlignResult };

package/dist/area.mjs

@@ -0,0 +1,29 @@
+function getIntersectionArea(rect, offsetX, offsetY, area) {
+  const left = rect.x + offsetX;
+  const top = rect.y + offsetY;
+  const right = left + rect.width;
+  const bottom = top + rect.height;
+  const width = Math.min(right, area.right) - Math.max(left, area.left);
+  const height = Math.min(bottom, area.bottom) - Math.max(top, area.top);
+  return Math.max(0, width) * Math.max(0, height);
+}
+function clipArea(initArea, clips) {
+  const visibleArea = { ...initArea };
+  for (const clip of clips) {
+    visibleArea.left = Math.max(visibleArea.left, clip.left);
+    visibleArea.top = Math.max(visibleArea.top, clip.top);
+    visibleArea.right = Math.min(visibleArea.right, clip.right);
+    visibleArea.bottom = Math.min(visibleArea.bottom, clip.bottom);
+  }
+  return visibleArea;
+}
+function rectToArea(rect) {
+  return {
+    left: rect.x,
+    top: rect.y,
+    right: rect.x + rect.width,
+    bottom: rect.y + rect.height
+  };
+}
+
+export { clipArea, getIntersectionArea, rectToArea };