@endfield-ui/react 0.3.0 → 1.0.1

package/src/components/toc/Toc.tsx

@@ -13,13 +13,16 @@ import {
   type ReactNode,
   type RefObject,
 } from "react";
+import { useIndicator } from "../../hooks/useIndicator";
 import {
   useScrollPosition,
   type ScrollMetrics,
 } from "../../hooks/useScrollPosition";
 import { cn } from "../../lib/cn";
 import { focusRingInset } from "../../lib/focus-ring";
+import { dropEmptyStyle } from "../../lib/inline-style";
 import { mergeRefs } from "../../lib/merge-refs";
+import { indicator } from "../../lib/motion";
 import { LinkElement, type LinkRender } from "../link-element/LinkElement";
 
 export type TocLevel = 1 | 2 | 3;
@@ -51,11 +54,50 @@ export type TocProps = TocOwnProps &
 /** 点了一项之后，多久没有滚动事件算这一次滚动停下了 */
 const SETTLE_MS = 150;
 
+/**
+ * 让接下来的这一次滚动是平滑的：给这几个滚动容器写上内联的 `scroll-behavior`，
+ * 滚动停下（`SETTLE_MS` 里没有再滚）就还原成原来的内联值。返回的函数提前还原。
+ *
+ * 滚动本身不归它管——跳过去的仍然是浏览器（锚点跳转）。
+ */
+function smoothOnce(scrollers: readonly HTMLElement[]) {
+  const before = scrollers.map((scroller) =>
+    scroller.style.getPropertyValue("scroll-behavior"),
+  );
+  for (const scroller of scrollers) {
+    scroller.style.setProperty("scroll-behavior", "smooth");
+  }
+
+  // 页面的滚动事件发在 window 上，容器的发在它自己身上
+  const sources = scrollers.map((scroller) =>
+    scroller === document.documentElement ? window : scroller,
+  );
+  let timer: ReturnType<typeof setTimeout>;
+  const restore = () => {
+    clearTimeout(timer);
+    for (const source of sources) source.removeEventListener("scroll", wait);
+    scrollers.forEach((scroller, index) => {
+      scroller.style.setProperty("scroll-behavior", before[index]!);
+      dropEmptyStyle(scroller);
+    });
+  };
+  function wait() {
+    clearTimeout(timer);
+    timer = setTimeout(restore, SETTLE_MS);
+  }
+  for (const source of sources) {
+    source.addEventListener("scroll", wait, { passive: true });
+  }
+  wait();
+  return restore;
+}
+
 /**
  * 页内目录：这一页有哪几节、现在看到了哪一节。里面放 `TocItem`。
  *
- * 位置由使用方给，通常是 `className="sticky top-6"`。点一项就是点一个锚点链接：
- * 滚不滚、平不平滑是浏览器和页面 CSS 的事，它不接管滚动。
+ * 位置由使用方给，通常是 `className="sticky top-6"`。点一项仍然是点一个锚点链接——
+ * 地址、后退、`scroll-mt` 都是浏览器原生的那一套；它只让这一次跳转滚得平滑
+ * （系统开了"减少动态效果"时照旧直接跳）。
  */
 export function Toc({
   title,
@@ -69,6 +111,8 @@ export function Toc({
   ...props
 }: TocProps) {
   const navRef = useRef<HTMLElement>(null);
+  // 当前项的粗条画在列表上：换一项时是同一段沿引线滑过去
+  const listRef = useIndicator<HTMLUListElement>("[aria-current]");
   const titleId = useId();
   // 目录的项数变了（内容是后来才到的）要重新算一次，不等下一次滚动
   const count = Children.count(children);
@@ -133,6 +177,32 @@ export function Toc({
 
   const active = pinned ?? spied;
 
+  // 点了一项之后的那一次跳转滚得平滑。这是脚本里要的平滑滚动，"减少动态效果"得自己看
+  const restoreScroll = useRef<(() => void) | null>(null);
+  useEffect(() => () => restoreScroll.current?.(), []);
+  const pick = useCallback(
+    (section: string) => {
+      setPinned(section);
+      restoreScroll.current?.();
+      restoreScroll.current = null;
+      if (!document.getElementById(section)) return;
+      if (
+        typeof window.matchMedia === "function" &&
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches
+      ) {
+        return;
+      }
+      // 小节在容器里时，页面也可能跟着滚（把它带到眼前）：两处一起
+      const container = target?.current;
+      restoreScroll.current = smoothOnce(
+        container
+          ? [container, document.documentElement]
+          : [document.documentElement],
+      );
+    },
+    [target],
+  );
+
   const report = useRef(onActiveChange);
   report.current = onActiveChange;
   const reported = useRef<string | null>(null);
@@ -158,7 +228,7 @@ export function Toc({
     }
   }, [active]);
 
-  const context = useMemo(() => ({ active, pick: setPinned }), [active]);
+  const context = useMemo(() => ({ active, pick }), [active, pick]);
   const hasTitle = title !== undefined && title !== null && title !== false;
 
   return (
@@ -179,8 +249,19 @@ export function Toc({
           {title}
         </p>
       )}
-      {/* 引线：从头贯到尾的一条细线，当前项那一段由那一项自己换成粗条 */}
-      <ul className="relative before:absolute before:inset-y-0 before:left-0 before:w-px before:bg-line before:content-['']">
+      {/* 引线：从头贯到尾的一条细线；当前项那一段是压在它上面的粗条 */}
+      <ul
+        ref={listRef}
+        className={cn(
+          // 和粗条同一层：它在前、粗条在后，粗条压着它；两样都在各项之下
+          "before:absolute before:inset-y-0 before:left-0 before:-z-1 before:w-px before:bg-line before:content-['']",
+          indicator,
+          // 3px 宽，比当前项上下各短 4px；长度跟着那一项的高度走
+          "after:top-1 after:h-[calc(var(--indicator-h)-0.5rem)] after:w-[3px] after:translate-y-(--indicator-y) after:bg-ink",
+          // 高对比模式下底色被系统换掉，粗条就没了：改用系统的"选中"色
+          "forced-colors:after:bg-[Highlight]",
+        )}
+      >
         <TocContext value={context}>{children}</TocContext>
       </ul>
     </nav>
@@ -251,8 +332,9 @@ export function TocItem({
           focusRingInset,
           levelPadding[level],
           current
-            ? // 不加粗：加粗会让折行变掉，整列目录跟着跳。靠的是引线上的这一段粗条
-              "text-ink before:absolute before:inset-y-1 before:left-0 before:w-[3px] before:bg-ink before:content-['']"
+            ? // 不加粗：加粗会让折行变掉，整列目录跟着跳。靠的是引线上的这一段粗条——
+              // 列表量到了位置就由列表上滑动的那一段来画，这里的让出来
+              "text-ink before:absolute before:inset-y-1 before:left-0 before:w-[3px] before:bg-ink before:content-[''] in-data-indicator:before:hidden forced-colors:before:bg-[Highlight]"
             : "text-ink-secondary hover:text-ink",
         )}
       >

package/src/components/toolbar/Toolbar.tsx

@@ -48,6 +48,18 @@ const barVariant: Record<ToolbarVariant, string> = {
   outline: "border border-line-strong bg-surface p-px",
 };
 
+/*
+ * 高对比模式下凹陷的底被系统换成页面色，带子就没了：补一圈线。里面没按下的钮平时就是透明的，
+ * 靠带子围着，所以补的是带子，不是每个钮。线画在内边距里，不占地方；描边的那种本来就有线，
+ * 只把颜色写明。整条禁用时是灰字色
+ */
+const barForced: Record<ToolbarVariant, string> = {
+  sunken:
+    "forced-colors:outline forced-colors:-outline-offset-1 forced-colors:outline-[ButtonText] forced-colors:data-disabled:outline-[GrayText]",
+  outline:
+    "forced-colors:border-[ButtonText] forced-colors:data-disabled:border-[GrayText]",
+};
+
 /**
  * 工具栏：一排作用于同一个对象的小工具，收在一条带子里。整条只占一个 Tab 停靠点，
  * 方向键在各项之间走。里面放 `ToolbarButton`、`ToolbarToggle`、`ToolbarToggleGroup`、
@@ -98,6 +110,7 @@ export function Toolbar({
           // 放不下就换行，不出横向滚动条
           orientation === "vertical" ? "flex-col" : "flex-wrap items-center",
           barVariant[variant],
+          barForced[variant],
           className,
         )}
       />
@@ -135,6 +148,13 @@ const itemBase = [
   "data-popup-open:bg-surface-inverse data-popup-open:text-ink-inverse",
   "data-disabled:cursor-not-allowed data-disabled:bg-transparent data-disabled:text-ink-disabled",
   "data-disabled:data-pressed:bg-disabled data-disabled:data-pressed:text-on-disabled",
+  // 高对比模式下底色都被系统换掉，按下的和没按的就成了一个样子：按下的改用系统的"选中"色（禁用的是灰字色）。
+  // 这一个的颜色不让系统再改（不然它会在字后面垫一块页面色），焦点环跟着写明
+  "forced-colors:data-pressed:forced-color-adjust-none forced-colors:data-pressed:outline-[Highlight]",
+  "forced-colors:data-pressed:bg-[Highlight] forced-colors:data-pressed:text-[HighlightText]",
+  "forced-colors:data-disabled:data-pressed:bg-[GrayText] forced-colors:data-disabled:data-pressed:text-[Canvas]",
+  // 禁用的钮还走得到，所以不是真的 disabled：系统不会替它把字换灰，自己写明
+  "forced-colors:data-disabled:text-[GrayText]",
   // 焦点环压在旁边的钮上面
   "focus-visible:z-1",
   focusRing,
@@ -146,6 +166,8 @@ const itemIcon = [
   "group-data-pressed/item:text-accent-ink-inverse",
   "group-data-popup-open/item:text-accent-ink-inverse",
   "group-data-disabled/item:group-data-pressed/item:text-on-disabled",
+  "forced-colors:group-data-pressed/item:text-[HighlightText]",
+  "forced-colors:group-data-disabled/item:group-data-pressed/item:text-[Canvas]",
 ].join(" ");
 
 function useItemClass(iconOnly: boolean, className: string | undefined) {
@@ -380,6 +402,8 @@ export function ToolbarSeparator({
       {...props}
       className={cn(
         "shrink-0 self-center bg-line-strong",
+        // 高对比模式下这条线是底色画的，会不见：用控件的字色；所在的那一条（或那一组）禁用时跟着灰
+        "forced-colors:bg-[ButtonText] forced-colors:in-data-disabled:bg-[GrayText]",
         "data-[orientation=vertical]:mx-1 data-[orientation=vertical]:h-4 data-[orientation=vertical]:w-px",
         "data-[orientation=horizontal]:my-1 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-4",
         className,

package/src/hooks/README.md

@@ -4,11 +4,17 @@
 
 | hook | 作用 |
 | --- | --- |
-| `useTheme` | 读写 `<html data-theme>`；支持 `light` / `dark` / `system`，选择记在 `localStorage` |
+| `useTheme` | 读写 `<html data-theme>`；支持 `light` / `dark` / `system`，选择记在 `localStorage`。亮暗变了的时候放在视图过渡里换，整页交叉淡化一次（200ms，时长在 [theme.css](../styles/theme.css) 的 `data-theme-switching` 下）；浏览器不支持、系统开了"减少动态效果"时直接切 |
 | `useControllableState` | 受控 / 非受控状态合并；值没变时不触发 `onChange` |
 | `useInView` | 元素第一次进入视口后返回 `true`，之后不再变回去——入场动画只播一次 |
+| `useReducedMotion` | 系统开了"减少动态效果"时返回 `true`，设置变了跟着变。只给脚本驱动的动效用（滚动数字）：CSS 的动画和过渡不用它 |
+| `usePresence` | 退场后再卸载：`open` 变成假之后元素先留着，等它身上正在跑的过渡和动画走完才卸载；没有动效可等就当场卸载。另外告诉你这个元素是不是"后来才出现的"——一开始就在的不播进场。加载页的滑出在用。不对外导出 |
+| `useAddedKeys` | 一串 key 里哪几个是后来加进来的：一开始就在的不算，删了又加回来的算。"新项淡入"只给这几个加入场的类（标签输入、文件上传）。不对外导出 |
+| `useIndicator` | 选中指示的位置：量出容器里当前项相对容器的位置和尺寸，写成容器上的 CSS 变量，并标上有没有当前项（`data-indicator`）。换了一项才滑；第一次到位、同一项挪了地方或变了大小都直接到；量不到就不标，各项照旧自己画选中态。给分段选择、页内目录、胶囊页签的滑动用。不对外导出 |
+| `useLingering` | 列表里被拿掉的项先留着：给它现在的那几个 key，返回"现在的 + 正在走的"（走的带 `leaving`，排在原来的位置上），等走的那一项身上的动效走完才拿掉——等法和 `usePresence` 是同一个（`afterMotion`），没有动效可等就当场拿掉。同时有加进来的不留。给标签输入、文件上传的列表用。不对外导出 |
+| `useFlip` | 补位：一排里有一项走了（带着 `data-leaving`），其余的直接子元素从旧位置滑到新位置——每次渲染后记位置，少了一项的那一次把挪了地方的先用 `translate` 摆回旧位置、再撤掉，滑回来靠 CSS 的过渡。走的那一项被钉在原处；容器因此变矮了，高度也量着收过去。只有少了一项才补位；超过 50 项、量不到就不做。给标签输入用。不对外导出 |
 | `useOverflowing` | 容器里的内容是不是比容器宽、比容器高。给"只有真的能滚动时才是一个能聚焦的区域"用（表格、排期）。不对外导出 |
 | `useScrollPosition` | 盯着一个滚动容器（不传就是整个页面），由滚动位置算出一个值：滚动、窗口尺寸变了、内容晚到都会重新算，值没变不重新渲染。滚动提示和回到顶部共用。不对外导出 |
 | `usePortalScope` | 浮层挂到 `<body>` 下之后拿不到局部容器上的 `data-theme` / `data-choice`：返回 `anchorRef`（给触发元素）和 `portalRef`（给浮层的容器），容器挂载时把最近的开关抄过去。`invertTheme` 抄相反的主题（文字提示）。最近的是反转块（`data-theme="inverse"`）时，抄的是它实际算出来的亮或暗 |
 
-还没有 `useReducedMotion`：目前的动效都是 CSS 动画与过渡，由 [theme.css](../styles/theme.css) 末尾的全局规则统一降级。等出现用 JS 驱动的动效时再加。
+动效几乎都是 CSS 的动画与过渡，由 [theme.css](../styles/theme.css) 末尾的全局规则统一降级，不用在组件里判断。那条规则管不到脚本：一帧一帧自己算的动效（现在只有滚动数字）要用 `useReducedMotion` 自己看；脚本里要的平滑滚动、视图过渡（页内目录、回到顶部、`useTheme`）也是各自当场看一眼系统的设置。

package/src/hooks/index.ts

@@ -1,4 +1,5 @@
 export { useControllableState } from "./useControllableState";
 export { useInView } from "./useInView";
+export { useReducedMotion } from "./useReducedMotion";
 export { useTheme, type Theme, type ThemePreference } from "./useTheme";
 export { usePortalScope } from "./usePortalScope";

package/src/hooks/useAddedKeys.ts

@@ -0,0 +1,26 @@
+import { useState } from "react";
+
+const NONE: ReadonlySet<string> = new Set();
+
+const same = (a: readonly string[], b: readonly string[]) =>
+  a.length === b.length && a.every((key, index) => key === b[index]);
+
+/**
+ * 一串 key 里哪几个是后来加进来的。一开始就在的不算；删掉之后又加回来的算。
+ *
+ * 给"新项淡入"用：入场的类只加在这几个上。一开始就有的不该在载入时播一遍，
+ * 已经在的也不会因为别的项变了而重播——它一直带着那个类，动画只在挂上时播一次。
+ */
+export function useAddedKeys(keys: readonly string[]): ReadonlySet<string> {
+  const [state, setState] = useState({ keys, added: NONE });
+  if (!same(state.keys, keys)) {
+    const before = new Set(state.keys);
+    setState({
+      keys,
+      added: new Set(
+        keys.filter((key) => !before.has(key) || state.added.has(key)),
+      ),
+    });
+  }
+  return state.added;
+}

package/src/hooks/useFlip.ts

@@ -0,0 +1,211 @@
+import { useEffect, useLayoutEffect, useRef, type RefObject } from "react";
+import { dropEmptyStyle } from "../lib/inline-style";
+import { afterMotion } from "./usePresence";
+
+/** 一排里超过这么多项就不补位：一项一项量、一项一项起过渡，多了不划算，也看不清谁去了哪 */
+export const FLIP_LIMIT = 50;
+
+/** 一项在容器里的排版位置：相对容器的内边距盒，不算它身上挂着的位移 */
+type Place = { left: number; top: number; width: number; height: number };
+
+/** 一个容器记着的事 */
+type Memory = {
+  /** 上一次量的时候各项在哪 */
+  seen: Map<Element, Place>;
+  /** 上一次量的时候容器多高 */
+  height: number;
+  /** 钉过的（或者钉不住藏起来的）那几项 */
+  pinned: WeakSet<Element>;
+  /** 容器的高度正在收：取消"收完把写上去的撤掉"的那一次等待 */
+  settle: (() => void) | null;
+};
+
+const px = (value: number) => `${Math.round(value * 100) / 100}px`;
+
+/** 这个元素眼下挂着的位移：补位滑到一半时不是 0 */
+function flight(node: Element): [number, number] {
+  const value = getComputedStyle(node).translate;
+  if (!value || value === "none") return [0, 0];
+  const [x = 0, y = 0] = value
+    .split(" ")
+    .map((part) => Number.parseFloat(part) || 0);
+  return [x, y];
+}
+
+/** 把写上去的内联样式撤干净：原来没有 style 属性的，不留一个空的在上面 */
+function unset(node: HTMLElement, names: readonly string[]) {
+  for (const name of names) node.style.removeProperty(name);
+  dropEmptyStyle(node);
+}
+
+const PIN = ["left", "top", "width", "height"] as const;
+/** 往走的那一项上写过的全部：钉它的那四样，钉不住时的藏 */
+const HELD = [...PIN, "display"] as const;
+
+/**
+ * 量一遍、记下来。这一次有一项刚走，就补位：走的钉在原处，
+ * 其余挪了地方的先摆回旧位置（不过渡），再撤掉——撤的那一下滑回原位；
+ * 容器因此变矮了的话，高度也从原来的收到新的。
+ */
+function arrange(node: HTMLElement, memory: Memory) {
+  const { seen, pinned } = memory;
+  const items = [...node.children] as HTMLElement[];
+  const leaving = (item: Element) => item.hasAttribute("data-leaving");
+  // 走到一半又回来了的（删了马上又加回来）：往它上面写过的撤掉
+  for (const item of items) {
+    if (leaving(item) || !pinned.has(item)) continue;
+    pinned.delete(item);
+    unset(item, HELD);
+  }
+
+  const box = node.getBoundingClientRect();
+  // 量不到（服务端渲染、还没排版、藏着）或者项太多：不做，旧的位置也不留。
+  // 刚走的那一项这时候钉不住——它已经脱离排版，没有位置会跑到这一排的头上去，不留在画面上
+  if (
+    box.width === 0 ||
+    box.height === 0 ||
+    items.filter((item) => !leaving(item)).length > FLIP_LIMIT
+  ) {
+    seen.clear();
+    memory.height = 0;
+    for (const item of items) {
+      if (!leaving(item) || pinned.has(item)) continue;
+      pinned.add(item);
+      item.style.setProperty("display", "none");
+    }
+    return;
+  }
+  // 祖先带缩放时，量到的矩形是放大过的：折回排版的尺寸
+  const laid = Number.parseFloat(getComputedStyle(node).width);
+  const scale = laid > 0 ? box.width / laid : 1;
+
+  // 先全部量完再动手写：一边量一边写，每一项都要重排一遍
+  const gone: [HTMLElement, Place | undefined][] = [];
+  const moved: [HTMLElement, number, number][] = [];
+  const next: [Element, Place][] = [];
+  for (const item of items) {
+    const before = seen.get(item);
+    if (leaving(item)) {
+      if (!pinned.has(item)) gone.push([item, before]);
+      continue;
+    }
+    const rect = item.getBoundingClientRect();
+    const [x, y] = flight(item);
+    const place = {
+      left:
+        (rect.left - box.left) / scale - node.clientLeft + node.scrollLeft - x,
+      top: (rect.top - box.top) / scale - node.clientTop + node.scrollTop - y,
+      width: rect.width / scale,
+      height: rect.height / scale,
+    };
+    next.push([item, place]);
+    if (!before) continue;
+    // 眼前的位置（旧的排版位置，加上还没走完的位移）离新的排版位置有多远
+    const dx = before.left + x - place.left;
+    const dy = before.top + y - place.top;
+    if (Math.abs(dx) >= 0.5 || Math.abs(dy) >= 0.5) moved.push([item, dx, dy]);
+  }
+  seen.clear();
+  for (const [item, place] of next) seen.set(item, place);
+
+  // 容器眼前有多高。高度正收到一半时，量到的就是收到一半的那个数
+  const tall = box.height / scale;
+  const shrinking = memory.settle !== null;
+  const from = shrinking ? tall : memory.height;
+  if (!shrinking) memory.height = tall;
+
+  // 只在有一项刚走的那一次补位。加了一项、容器宽了、字体到了，别的项都是直接到位的
+  if (gone.length === 0) return;
+
+  for (const [item, place] of gone) {
+    pinned.add(item);
+    if (place) {
+      PIN.forEach((name) => item.style.setProperty(name, px(place[name])));
+    } else {
+      // 没记过它的位置（刚加进来就走了）：钉不住，不留在画面上
+      item.style.setProperty("display", "none");
+    }
+  }
+
+  // 少了一行，容器就矮了：高度也跟着收，不然它当场缩上去，还在滑的那几项会露在外面，
+  // 后面的内容也跟着跳一下。量着收——先撑在眼前的高度上，再放到新的高度
+  memory.settle?.();
+  memory.settle = null;
+  node.style.setProperty("transition", "none");
+  node.style.removeProperty("min-height");
+  const to = node.getBoundingClientRect().height / scale;
+  memory.height = to;
+  const shrink = from - to >= 0.5;
+  if (shrink) node.style.setProperty("min-height", px(from));
+
+  for (const [item, dx, dy] of moved) {
+    item.style.setProperty("transition", "none");
+    item.style.setProperty("translate", `${px(dx)} ${px(dy)}`);
+  }
+  // 让"还在旧位置上"这一下落定，再撤掉：撤的那一下由各项自己的过渡滑回原位
+  node.getBoundingClientRect();
+  for (const [item] of moved) unset(item, ["transition", "translate"]);
+  node.style.removeProperty("transition");
+  if (shrink) {
+    node.style.setProperty("min-height", px(to));
+    // 收完就把写上去的撤掉：留着的话，下一次内容少了它不会跟着矮
+    memory.settle = afterMotion(node, () => {
+      memory.settle = null;
+      unset(node, ["min-height"]);
+    });
+  } else {
+    dropEmptyStyle(node);
+  }
+}
+
+/**
+ * 补位：容器里有一项走了，其余的直接子元素从旧位置滑到新位置，不是瞬移过去。
+ * 返回的 `ref` 给容器。
+ *
+ * - 走的那一项要带 `data-leaving`、并且脱离排版（`lib/motion.ts` 的 `flipLeaving`）：
+ *   钩子把它钉在原来的位置上，它在那里把退场走完；容器要是定位的参照（`flipBox`）。
+ * - 其余各项要给 `translate` 加上过渡：钩子只负责把它们摆回旧位置再放手，
+ *   滑回来靠的是 CSS——所以系统开了"减少动态效果"时是直接到位的。
+ * - 容器因此变矮了（少了一行），它的高度也从原来的收到新的（量着收，过渡同样在
+ *   `flipBox` 里）；收完撤掉，不留在容器上。
+ * - 各项只动 `translate`。正滑到一半又少一项，从眼前的位置接着走。
+ * - 只有"少了一项"才补位；加一项、容器尺寸变了，各项直接到位。
+ * - 超过 `FLIP_LIMIT` 项、量不到位置时不做：走的那一项也不留，照旧直接消失。
+ */
+export function useFlip<
+  T extends HTMLElement = HTMLElement,
+>(): RefObject<T | null> {
+  const ref = useRef<T>(null);
+  const memory = useRef<Memory>({
+    seen: new Map(),
+    height: 0,
+    pinned: new WeakSet(),
+    settle: null,
+  });
+
+  // 每次渲染后量一遍：哪一次渲染会少一项事先不知道，旧位置得一直是新的
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (node) arrange(node, memory.current);
+  });
+
+  // 容器的尺寸变了（窗口窄了、换行变了）没有渲染：重记一遍位置。
+  // 这时候没有刚走的项，所以不会补位
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (!node || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => arrange(node, memory.current));
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    const held = memory.current;
+    return () => {
+      held.settle?.();
+      held.settle = null;
+    };
+  }, []);
+
+  return ref;
+}

package/src/hooks/useIndicator.ts

@@ -0,0 +1,135 @@
+import { useLayoutEffect, useRef, type RefObject } from "react";
+
+const VARS = [
+  "--indicator-x",
+  "--indicator-y",
+  "--indicator-w",
+  "--indicator-h",
+] as const;
+
+function clear(node: HTMLElement) {
+  if (node.dataset.indicator === undefined) return;
+  delete node.dataset.indicator;
+  for (const name of VARS) node.style.removeProperty(name);
+}
+
+/** 量一次、写一次。`last` 记着上一次指的是哪一项：换了才滑 */
+function place(
+  node: HTMLElement,
+  selector: string,
+  last: { current: Element | null },
+) {
+  const box = node.getBoundingClientRect();
+  // 量不到（还没排版，或者藏着）：什么都不标，各项照旧自己画
+  if (box.width === 0 || box.height === 0) {
+    clear(node);
+    last.current = null;
+    return;
+  }
+
+  const item = node.querySelector(selector);
+  const rect = item?.getBoundingClientRect();
+  if (!item || !rect || rect.width === 0 || rect.height === 0) {
+    // 一项都没有：指示留在原地淡出
+    node.dataset.indicator = "off";
+    last.current = null;
+    return;
+  }
+
+  // 祖先带缩放时矩形是缩放之后的，变量要的是缩放之前的
+  const laid = Number.parseFloat(getComputedStyle(node).width);
+  const scale = laid > 0 ? box.width / laid : 1;
+  const values = [
+    (rect.left - box.left) / scale - node.clientLeft + node.scrollLeft,
+    (rect.top - box.top) / scale - node.clientTop + node.scrollTop,
+    rect.width / scale,
+    rect.height / scale,
+  ].map((value) => `${Math.round(value * 100) / 100}px`);
+
+  const slide =
+    node.dataset.indicator === "on" &&
+    last.current !== null &&
+    last.current !== item;
+  last.current = item;
+
+  if (
+    VARS.some((name, at) => node.style.getPropertyValue(name) !== values[at])
+  ) {
+    // 第一次到位、从没有到有、同一项挪了地方或变了大小：直接到，不过渡
+    if (!slide) node.dataset.indicatorInstant = "";
+    VARS.forEach((name, at) => node.style.setProperty(name, values[at]!));
+    if (!slide) {
+      // 先让这一步落定再撤标记：不然浏览器看到的仍然是"变了"，照样过渡
+      node.getBoundingClientRect();
+      delete node.dataset.indicatorInstant;
+    }
+  }
+  node.dataset.indicator = "on";
+}
+
+/**
+ * 选中指示的位置：量出容器里"当前项"相对容器的位置和尺寸，写成容器上的 CSS 变量
+ * （`--indicator-x` / `-y` / `-w` / `-h`），并在容器上标 `data-indicator`——`on` 是有当前项，
+ * `off` 是没有。指示本身由用的地方画在容器的 `::after` 上（`lib/motion.ts` 的 `indicator`），
+ * 换了一项时由 CSS 的过渡滑过去。
+ *
+ * 只有"换了一项"才滑；第一次到位、同一项挪了地方或变了大小（容器宽了、字体到了、
+ * 前面多了一项）都直接到位。量不到（服务端、还没排版、藏着）时什么都不标，
+ * 各项照旧自己画选中态——不会有哪一帧没有选中态。
+ *
+ * `current` 是当前项在容器里的选择器；传 `null` 是不用。
+ */
+export function useIndicator<T extends HTMLElement = HTMLElement>(
+  current: string | null,
+): RefObject<T | null> {
+  const ref = useRef<T>(null);
+  const last = useRef<Element | null>(null);
+  const observer = useRef<ResizeObserver | null>(null);
+  const watched = useRef<Element[]>([]);
+
+  // 每次渲染后量一次：选中的换了、项多了少了，都落在这里
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (!node) return;
+    if (current === null) {
+      clear(node);
+      last.current = null;
+      return;
+    }
+    place(node, current, last);
+
+    // 盯着的是容器和它的每一个直接子元素：哪一个变了大小，当前项都可能跟着挪
+    const watching = observer.current;
+    if (!watching) return;
+    const next = [node, ...node.children];
+    const before = watched.current;
+    if (
+      next.length === before.length &&
+      next.every((element, at) => element === before[at])
+    ) {
+      return;
+    }
+    watching.disconnect();
+    for (const element of next) watching.observe(element);
+    watched.current = next;
+  });
+
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (!node || current === null || typeof ResizeObserver === "undefined") {
+      return;
+    }
+    const watching = new ResizeObserver(() => place(node, current, last));
+    const targets = [node, ...node.children];
+    for (const element of targets) watching.observe(element);
+    observer.current = watching;
+    watched.current = targets;
+    return () => {
+      watching.disconnect();
+      observer.current = null;
+      watched.current = [];
+    };
+  }, [current]);
+
+  return ref;
+}