@endfield-ui/react 0.2.0 → 1.0.0

package/src/components/tag-input/TagInput.tsx

@@ -10,14 +10,19 @@ import {
   type KeyboardEvent,
   type MouseEvent,
 } from "react";
+import { useAddedKeys } from "../../hooks/useAddedKeys";
 import { useControllableState } from "../../hooks/useControllableState";
+import { FLIP_LIMIT, useFlip } from "../../hooks/useFlip";
+import { useLingering } from "../../hooks/useLingering";
 import { Close } from "../../icons/Close";
 import { StatusDanger } from "../../icons/StatusDanger";
 import { cn } from "../../lib/cn";
 import { mergeRefs } from "../../lib/merge-refs";
+import { fadeInFast, flipBox, flipLeaving } from "../../lib/motion";
 import { useFieldControl } from "../field/Field";
 import {
   controlBox,
+  controlDisabledText,
   controlElement,
   controlIconSize,
   type ControlSize,
@@ -182,6 +187,15 @@ export function TagInput({
   const [flash, setFlash] = useState<string | null>(null);
   const [message, setMessage] = useState("");
   const full = max !== undefined && tags.length >= max;
+  // 后来加的那几个淡入；一开始就有的是静止的
+  const added = useAddedKeys(tags);
+  // 删掉的那一块先留着把淡出走完，其余的小块和输入框同时补位。
+  // 补位的钩子排在前面：它钉不住的（小块太多、量不到位置）当场藏掉，后面那个就不等了
+  const rowRef = useFlip<HTMLDivElement>();
+  const lingering = useLingering<HTMLDivElement>(
+    tags,
+    tags.length < FLIP_LIMIT,
+  );
 
   useEffect(() => {
     if (flash === null) return;
@@ -367,48 +381,71 @@ export function TagInput({
         className,
       )}
     >
-      <div className="flex min-w-0 flex-1 flex-wrap items-center gap-1 py-1 pl-2">
-        {tags.map((tag, index) => (
-          <span
-            key={tag}
-            data-tag=""
-            data-flash={flash === tag ? "" : undefined}
-            className={cn(
-              valueChip,
-              valueChipSize[size],
-              "transition-colors duration-(--duration-fast) ease-standard",
-              // 重复时闪一下：填充反转。不用黄色——这不是"选中"
-              "data-flash:bg-surface-inverse data-flash:text-ink-inverse",
-              disabled && "text-ink-disabled",
-              !editable && "pr-2",
-            )}
-          >
-            <span className="min-w-0 truncate">{tag}</span>
-            {editable && (
-              <button
-                type="button"
-                // 整个控件只占一个 Tab 停靠点：小块用方向键走
-                tabIndex={-1}
-                aria-label={removeLabel(tag)}
-                onClick={(event) =>
-                  // 键盘触发的（回车、空格）焦点留在小块这一排；鼠标点的回到输入框
-                  remove(
-                    index,
-                    event.detail === 0 && tags.length > 1 ? index : "input",
-                  )
-                }
-                onKeyDown={(event) => handleChipKeyDown(event, index)}
-                className={cn(
-                  valueChipRemove,
-                  "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus",
-                  flash === tag && "text-ink-inverse",
-                )}
-              >
-                <Close size={12} />
-              </button>
-            )}
-          </span>
-        ))}
+      <div
+        ref={mergeRefs(rowRef, lingering.ref)}
+        className={cn(
+          "flex min-w-0 flex-1 flex-wrap items-center gap-1 py-1 pl-2",
+          flipBox,
+        )}
+      >
+        {lingering.entries.map(({ key: tag, leaving }) => {
+          // 正在走的那一块已经不在 tags 里了，下面按位置算的事它都用不上
+          const index = tags.indexOf(tag);
+          return (
+            <span
+              key={tag}
+              // 正在走的不算数：删掉之后焦点落到哪、整排怎么用方向键走，看到的只有还在的
+              data-tag={leaving ? undefined : ""}
+              data-leaving={leaving ? "" : undefined}
+              data-flash={flash === tag && !leaving ? "" : undefined}
+              // 它点不到、Tab 不进去，读屏也读不到：状态在删的那一刻就变了，画面后到
+              inert={leaving}
+              aria-hidden={leaving || undefined}
+              className={cn(
+                valueChip,
+                valueChipSize[size],
+                // 换色、补位时滑回原位、走的时候淡出，都是 200ms
+                "transition-[color,background-color,translate,opacity] duration-(--duration-fast) ease-standard",
+                // 重复时闪一下：填充反转。不用黄色——这不是"选中"
+                "data-flash:bg-surface-inverse data-flash:text-ink-inverse",
+                // 高对比模式下底色被系统换掉，反转闪不出来：闪的时候套一圈系统"选中"色的环，
+                // 画在那一圈线的外面（小块之间有 4px，放得下）
+                "forced-colors:data-flash:outline-2 forced-colors:data-flash:outline-[Highlight]",
+                flipLeaving,
+                added.has(tag) && fadeInFast,
+                // 高对比模式：这是个 <span>，系统不知道它禁用了，字和那一圈线都写明灰字色
+                disabled &&
+                  "text-ink-disabled forced-colors:border-[GrayText] forced-colors:text-[GrayText]",
+                !editable && "pr-2",
+              )}
+            >
+              <span className="min-w-0 truncate">{tag}</span>
+              {editable && (
+                <button
+                  type="button"
+                  // 整个控件只占一个 Tab 停靠点：小块用方向键走
+                  tabIndex={-1}
+                  aria-label={removeLabel(tag)}
+                  onClick={(event) =>
+                    // 键盘触发的（回车、空格）焦点留在小块这一排；鼠标点的回到输入框
+                    remove(
+                      index,
+                      event.detail === 0 && tags.length > 1 ? index : "input",
+                    )
+                  }
+                  onKeyDown={(event) => handleChipKeyDown(event, index)}
+                  className={cn(
+                    valueChipRemove,
+                    "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus",
+                    flash === tag && "text-ink-inverse",
+                  )}
+                >
+                  <Close size={12} />
+                </button>
+              )}
+            </span>
+          );
+        })}
         <input
           {...props}
           ref={mergeRefs(inputRef, ref)}
@@ -446,6 +483,8 @@ export function TagInput({
             controlElement,
             "min-w-12 px-1",
             valueInputHeight[size],
+            // 删了一个小块：和后面的小块一起滑到新位置
+            "transition-[translate] duration-(--duration-fast) ease-standard",
           )}
         />
       </div>
@@ -469,7 +508,7 @@ export function TagInput({
               className={cn(
                 "font-tech text-xs tabular-nums",
                 disabled
-                  ? "text-ink-disabled"
+                  ? controlDisabledText
                   : full
                     ? "text-ink"
                     : "text-ink-secondary",

package/src/components/textarea/Textarea.tsx

@@ -3,6 +3,7 @@ import { cn } from "../../lib/cn";
 import { useFieldControl } from "../field/Field";
 import {
   controlBox,
+  controlDisabledText,
   controlElement,
   type ControlVariant,
 } from "../input/control-box";
@@ -88,7 +89,7 @@ export function Textarea({
           data-count=""
           className={cn(
             "pointer-events-none self-end px-3 pb-1.5 font-tech text-xs tabular-nums",
-            disabled ? "text-ink-disabled" : "text-ink-secondary",
+            disabled ? controlDisabledText : "text-ink-secondary",
           )}
         >
           {maxLength !== undefined ? `${length} / ${maxLength}` : length}

package/src/components/timeline/Timeline.tsx

@@ -25,9 +25,10 @@ export type TimelineItemProps = Omit<ComponentProps<"li">, "title"> & {
 };
 
 const nodeClass: Record<TimelineStatus, string> = {
-  past: "bg-ink",
+  // 高对比模式下底色都被系统换掉，实心的菱形就没了：换成页面的字色
+  past: "bg-ink forced-colors:bg-[CanvasText]",
   // 描一圈最细的线（1px），颜色跟着文字走：亮色下是墨色，暗色下是近白
-  current: "border border-ink bg-action",
+  current: "border border-ink bg-action forced-colors:bg-[Highlight]",
   upcoming: "border-2 border-ink-tertiary",
 };
 
@@ -66,7 +67,7 @@ export function TimelineItem({
           <span className={cn("size-[11px] rotate-45", nodeClass[status])} />
         </span>
         {/* 轴只画在节点之间，不从节点后面穿过，空心菱形才是空的 */}
-        <span className="w-0.5 flex-1 bg-line-strong group-last/item:hidden" />
+        <span className="w-0.5 flex-1 bg-line-strong group-last/item:hidden forced-colors:bg-[CanvasText]" />
       </span>
       <div className="min-w-0 flex-1 pb-6 group-last/item:pb-0">
         {hasDate && (

package/src/components/toast/Toast.tsx

@@ -82,7 +82,15 @@ const toneText: Record<Exclude<ToastTone, "neutral">, string> = {
 
 /*
  * 水平居中 + 跟着手指走的位移（可以往下或往右划走）。
- * 新旧两条在同一个位置交替淡入淡出，所以用绝对定位叠在一起
+ *
+ * 写在 transform 上，不能写在 translate 上：基元在拖动的时候自己往元素上写内联的
+ * transform（从元素现在的 transform 出发，加上指针走过的距离），并把过渡关掉；松手
+ * 之后交还给这里的变量。位置写在别的属性上的话两处会叠加——提示走的是手指的两倍。
+ *
+ * 进场的位移另写在 translate 上（只在起点有）：两个属性各管各的，"滑入"的过渡碰不到
+ * "跟手"的那一份。底部的从下面来；正中的是官网的做法，只有透明度。
+ *
+ * 新旧两条在同一个位置交替，所以用绝对定位叠在一起：旧的原地淡出，新的升上来
  */
 const placementClass: Record<
   ToastPlacement,
@@ -90,11 +98,11 @@ const placementClass: Record<
 > = {
   bottom: {
     viewport: "bottom-6",
-    root: "bottom-0 translate-y-[var(--toast-swipe-movement-y,0px)]",
+    root: "bottom-0 transform-[translate(calc(-50%+var(--toast-swipe-movement-x,0px)),var(--toast-swipe-movement-y,0px))] data-starting-style:translate-y-(--motion-shift-lg)",
   },
   center: {
     viewport: "top-1/2",
-    root: "top-0 translate-y-[calc(-50%+var(--toast-swipe-movement-y,0px))]",
+    root: "top-0 transform-[translate(calc(-50%+var(--toast-swipe-movement-x,0px)),calc(-50%+var(--toast-swipe-movement-y,0px)))]",
   },
 };
 
@@ -169,11 +177,16 @@ function ToastHost({ placement, label, closeLabel, children }: ToastHostProps) {
                 // 黑底白字不随主题变：整条做成暗色的局部主题，图形和焦点环按深色底取值
                 data-theme="dark"
                 className={cn(
-                  "pointer-events-auto absolute left-1/2 w-max max-w-full translate-x-[calc(-50%+var(--toast-swipe-movement-x,0px))]",
+                  "pointer-events-auto absolute left-1/2 w-max max-w-full",
                   // 边线是给暗色页面的：那里黑底和页面几乎一样深，要靠它把提示勾出来。
                   // 亮色页面上它和提示的底几乎同色，看不出来
                   "border border-line bg-black/80 text-base leading-[1.4] text-white",
-                  "transition-opacity duration-(--duration-fast) ease-standard data-ending-style:opacity-0 data-starting-style:opacity-0",
+                  // 三样各走各的：淡入淡出 200ms；进场的位移 300ms；没划够就松手，滑回原位 200ms。
+                  // 拖动中基元把过渡整个关掉，位置贴着手指
+                  "transition-[opacity,translate,transform] duration-[var(--duration-fast),var(--duration-base),var(--duration-fast)] ease-[var(--ease-standard),var(--ease-exit),var(--ease-standard)]",
+                  "data-ending-style:opacity-0 data-starting-style:opacity-0",
+                  // 拖的时候不选中文字：用鼠标拖会把字选上，下一次再拖，浏览器当成"拖这段字"，手势就被取消了
+                  "data-swiping:select-none",
                   // 焦点环画在里面：它是按深色底取的颜色，画到外面会压在亮色的页面上
                   focusRingInset,
                   placementClass[placement].root,

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/components/tooltip/Tooltip.tsx

@@ -11,6 +11,7 @@ import {
 import { createPortal } from "react-dom";
 import { usePortalScope } from "../../hooks/usePortalScope";
 import { cn } from "../../lib/cn";
+import { enterFromSide } from "../../lib/motion";
 
 export type TooltipSide = "top" | "bottom" | "left" | "right";
 export type TooltipAlign = "start" | "center" | "end";
@@ -152,8 +153,11 @@ export function Tooltip({
             className={cn(
               // 透明的边线：高对比模式下背景色被系统覆盖，边线会自己显形
               "relative max-w-64 border border-transparent bg-surface-raised px-2.5 py-1.5 text-sm wrap-anywhere text-ink",
-              "origin-(--transform-origin) transition-opacity duration-(--duration-fast) ease-standard",
+              // 进场从触发元素那一侧挪过来 4px，退场只淡出。小件：进出都是 200ms。
+              // data-instant（键盘聚焦、移到相邻的提示）时基元要它立刻出现，整个不过渡
+              "origin-(--transform-origin) transition-[opacity,translate] duration-(--duration-fast) ease-standard",
               "data-ending-style:opacity-0 data-instant:transition-none data-starting-style:opacity-0",
+              enterFromSide,
               className,
             )}
           >

package/src/components/viewfinder/Viewfinder.tsx

@@ -16,6 +16,12 @@ export type ViewfinderProps = ComponentProps<"div"> & {
   size?: ViewfinderSize;
   /** 正中放一个小准星，标出焦点 */
   crosshair?: boolean;
+  /**
+   * 挂上的时候取景角落位：八段短线各自从角上伸出来，播一次。
+   * 默认不动——取景角平时是静态的装饰。要它晚一点再动（等外面那一层先淡入完），
+   * 在外层设 `--bracket-delay`
+   */
+  animate?: boolean;
   /**
    * 四个角上的读数：坐标、比例、版本、时间码。
    * 必须是真实的数据；没有就不放。
@@ -44,6 +50,7 @@ const readoutPosition: Record<keyof ViewfinderReadouts, string> = {
 export function Viewfinder({
   size = "sm",
   crosshair = false,
+  animate = false,
   readouts,
   className,
   children,
@@ -58,6 +65,8 @@ export function Viewfinder({
           decor,
           "corner-brackets absolute inset-3 [--bracket-color:currentColor] [--bracket-offset:0px] [--bracket-width:1.5px]",
           armClass[size],
+          animate &&
+            "after:animate-bracket-in after:[animation-delay:var(--bracket-delay,0s)]",
         )}
       />
       {crosshair && (

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;
+}