@endfield-ui/react 0.2.0 → 1.0.0

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

package/src/hooks/useLingering.ts

@@ -0,0 +1,122 @@
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
+import { afterMotion } from "./usePresence";
+
+export type LingeringEntry = {
+  key: string;
+  /** 已经从列表里拿掉了，留着把退场走完 */
+  leaving: boolean;
+};
+
+const same = (a: readonly string[], b: readonly string[]) =>
+  a.length === b.length && a.every((key, index) => key === b[index]);
+
+/**
+ * 新的一份：现在的那几项按现在的顺序，走着的插回它原来挨着的那一项后面。
+ * `keep` 是这一次新走的要不要留。
+ */
+function merge(
+  before: readonly LingeringEntry[],
+  keys: readonly string[],
+  keep: boolean,
+): LingeringEntry[] {
+  const now = new Set(keys);
+  const next: LingeringEntry[] = keys.map((key) => ({ key, leaving: false }));
+  // 顺着旧的那一份走一遍：anchor 是眼下最后一个还在新的一份里的
+  let anchor: string | null = null;
+  for (const entry of before) {
+    if (now.has(entry.key)) {
+      anchor = entry.key;
+      continue;
+    }
+    // 早先就在走的接着走；这一次才走的看 keep
+    if (!entry.leaving && !keep) continue;
+    const at =
+      anchor === null ? -1 : next.findIndex((item) => item.key === anchor);
+    next.splice(at + 1, 0, { key: entry.key, leaving: true });
+    anchor = entry.key;
+  }
+  return next;
+}
+
+/**
+ * 列表里被拿掉的项先留着：`keys` 里少了一项，它不当场消失，而是带着 `leaving`
+ * 留在原来的位置上，等它身上的退场走完才真的拿掉（等法和 `usePresence` 是同一套：
+ * 看元素上正在跑的动效，一个都没有就当场拿掉——测试环境里东西删了就是删了）。
+ *
+ * 用法：`entries` 按顺序渲染成 `ref` 那个容器的直接子元素，走着的那几项带上
+ * `data-leaving`（退场的样式挂在它上面），并且对键盘和读屏隐藏。钩子按这个标记找元素。
+ *
+ * - 这一次变化里同时有加进来的（整批换掉、"只收一个"换了一个）：新走的不留，照旧直接换。
+ * - 走到一半又加回来：它不再是走着的，留在页面上的还是同一个元素。
+ * - `enabled` 为假时不留新走的（项太多的时候）。
+ */
+export function useLingering<T extends Element = HTMLElement>(
+  keys: readonly string[],
+  enabled = true,
+): { ref: RefObject<T | null>; entries: readonly LingeringEntry[] } {
+  const ref = useRef<T>(null);
+  const [state, setState] = useState(() => ({
+    keys,
+    entries: merge([], keys, false),
+  }));
+  let { entries } = state;
+  if (!same(state.keys, keys)) {
+    const known = new Set(state.keys);
+    const grew = keys.some((key) => !known.has(key));
+    entries = merge(state.entries, keys, enabled && !grew);
+    setState({ keys, entries });
+  }
+
+  const drop = useCallback((key: string) => {
+    setState((current) => ({
+      keys: current.keys,
+      entries: current.entries.filter(
+        (entry) => !(entry.leaving && entry.key === key),
+      ),
+    }));
+  }, []);
+
+  // 每一个走着的等一次：它身上的退场走完就拿掉
+  const waits = useRef(new Map<string, () => void>());
+  useLayoutEffect(() => {
+    const pending = waits.current;
+    const leaving = entries
+      .filter((entry) => entry.leaving)
+      .map((entry) => entry.key);
+    // 不再是走着的了（走完了，或者又加回来了）：不等了
+    for (const [key, cancel] of pending) {
+      if (leaving.includes(key)) continue;
+      cancel();
+      pending.delete(key);
+    }
+    if (leaving.length === 0) return;
+    // 走着的那几项在页面上的顺序，就是它们在 entries 里的顺序
+    const nodes = [...(ref.current?.children ?? [])].filter((node) =>
+      node.hasAttribute("data-leaving"),
+    );
+    leaving.forEach((key, index) => {
+      if (pending.has(key)) return;
+      pending.set(
+        key,
+        afterMotion(nodes[index] ?? null, () => drop(key)),
+      );
+    });
+  }, [entries, drop]);
+
+  useEffect(() => {
+    const pending = waits.current;
+    return () => {
+      for (const cancel of pending.values()) cancel();
+      pending.clear();
+    };
+  }, []);
+
+  return { ref, entries };
+}

package/src/hooks/usePresence.ts

@@ -0,0 +1,100 @@
+import { useLayoutEffect, useRef, useState, type RefObject } from "react";
+
+type Options<T extends Element> = {
+  /**
+   * 开始退场、还没去看有没有动效在跑之前调。退场的起点要用脚本摆的在这里摆
+   * （提示条量自己的高度）。返回的函数在退场被打断（中途又打开）时把摆上去的撤掉
+   */
+  onLeave?: (node: T) => void | (() => void);
+  /** 退完、已经卸载之后 */
+  onExited?: () => void;
+};
+
+export type Presence<T extends Element> = {
+  /** 给会动的那个元素：退场时等的是它身上的过渡和动画 */
+  ref: RefObject<T | null>;
+  /** 该不该渲染 */
+  mounted: boolean;
+  /** 正在退场：`open` 已经是假的了，元素还留着 */
+  leaving: boolean;
+  /** 是后来才出现的。一开始就在的是 `false`——进场的起点只给后来出现的 */
+  entered: boolean;
+};
+
+/** 循环的动画（加载指示那一类）等不到头，不等 */
+function ends(animation: Animation) {
+  return animation.effect?.getComputedTiming().iterations !== Infinity;
+}
+
+/**
+ * 等这个元素上**正在跑的**、有尽头的过渡和动画走完，再调 `done`；一个都没有
+ * （没有写退场的样式、测试环境里没有动效）就当场调。返回的函数取消这一次等待。
+ */
+export function afterMotion(
+  node: Element | null,
+  done: () => void,
+): () => void {
+  let live = true;
+  const finish = () => {
+    if (live) done();
+  };
+  // 读这一下，浏览器会先把这次的样式变化算完：刚起的过渡已经在里面了。
+  // `finished` 要现在就拿住——过渡被取消之后再去拿，拿到的是一个永远不落定的新承诺
+  const running =
+    typeof node?.getAnimations === "function"
+      ? node.getAnimations().filter(ends)
+      : [];
+  if (running.length === 0) finish();
+  else {
+    void Promise.allSettled(
+      running.map((animation) => animation.finished),
+    ).then(finish);
+  }
+  return () => {
+    live = false;
+  };
+}
+
+/**
+ * 退场后再卸载：`open` 变成假之后元素先留着，等它身上的动效走完才卸载。
+ *
+ * 等的是这个元素上**正在跑的**过渡和动画，不另抄一份时长；一个都没有
+ * （没有写退场的样式、测试环境里没有动效）就当场卸载。退场途中又打开：不卸载，
+ * 过渡自己折回去。
+ */
+export function usePresence<T extends Element = HTMLElement>(
+  open: boolean,
+  { onLeave, onExited }: Options<T> = {},
+): Presence<T> {
+  const ref = useRef<T>(null);
+  const [mounted, setMounted] = useState(open);
+  const [entered, setEntered] = useState(false);
+  // 打开：立刻挂上
+  if (open && !mounted) {
+    setMounted(true);
+    setEntered(true);
+  }
+  const leaving = !open && mounted;
+
+  const handlers = useRef({ onLeave, onExited });
+  useLayoutEffect(() => {
+    handlers.current = { onLeave, onExited };
+  });
+
+  useLayoutEffect(() => {
+    if (!leaving) return;
+    const node = ref.current;
+    const undo = node ? handlers.current.onLeave?.(node) : undefined;
+    const cancel = afterMotion(node, () => {
+      setMounted(false);
+      handlers.current.onExited?.();
+    });
+
+    return () => {
+      cancel();
+      undo?.();
+    };
+  }, [leaving]);
+
+  return { ref, mounted, leaving, entered };
+}

package/src/hooks/useReducedMotion.ts

@@ -0,0 +1,26 @@
+import { useSyncExternalStore } from "react";
+
+const QUERY = "(prefers-reduced-motion: reduce)";
+
+function subscribe(notify: () => void) {
+  if (typeof window.matchMedia !== "function") return () => {};
+  const media = window.matchMedia(QUERY);
+  media.addEventListener("change", notify);
+  return () => media.removeEventListener("change", notify);
+}
+
+function read() {
+  return (
+    typeof window.matchMedia === "function" && window.matchMedia(QUERY).matches
+  );
+}
+
+/**
+ * 系统开了"减少动态效果"时返回 true，设置变了会跟着变。
+ *
+ * CSS 的动画和过渡不用它：`theme.css` 末尾的全局规则已经统一降级了。
+ * 只有脚本驱动的动效（一帧一帧自己算的）才要看它——那条规则管不到脚本。
+ */
+export function useReducedMotion(): boolean {
+  return useSyncExternalStore(subscribe, read, () => false);
+}

package/src/hooks/useTheme.ts

@@ -7,11 +7,14 @@ type Snapshot = { theme: ThemePreference; resolvedTheme: Theme };
 
 const STORAGE_KEY = "ef-theme";
 const DARK_QUERY = "(prefers-color-scheme: dark)";
+const REDUCE_QUERY = "(prefers-reduced-motion: reduce)";
 
 const serverSnapshot: Snapshot = { theme: "light", resolvedTheme: "light" };
 const listeners = new Set<() => void>();
 let snapshot: Snapshot | null = null;
 let stopWatchingSystem: (() => void) | null = null;
+/** 正在走的那一次切换（视图过渡）：它走完才撤掉 <html> 上的标记 */
+let switching: unknown = null;
 
 function isPreference(value: unknown): value is ThemePreference {
   return value === "light" || value === "dark" || value === "system";
@@ -42,10 +45,45 @@ function getSnapshot(): Snapshot {
   return snapshot;
 }
 
+/**
+ * 换主题。亮暗真的变了、浏览器有视图过渡、系统没开"减少动态效果"时，放在视图过渡里换：
+ * 整页交叉淡化一次，而不是带换色过渡的慢慢过去、别的硬切，参差不齐。否则当场换。
+ *
+ * 走视图过渡的时候是晚一帧才换的——浏览器要先把旧的样子拍下来。
+ * 期间 <html> 上标着 data-theme-switching：淡化的时长挂在它下面（theme.css），
+ * 使用方自己的视图过渡不受影响。局部主题那几块新旧一个样，看不出变化。
+ */
 function commit(theme: ThemePreference) {
-  snapshot = { theme, resolvedTheme: resolve(theme) };
-  document.documentElement.dataset.theme = snapshot.resolvedTheme;
-  for (const listener of listeners) listener();
+  const next: Snapshot = { theme, resolvedTheme: resolve(theme) };
+  const element = document.documentElement;
+  const apply = () => {
+    snapshot = next;
+    element.dataset.theme = next.resolvedTheme;
+    for (const listener of listeners) listener();
+  };
+
+  if (
+    element.dataset.theme === next.resolvedTheme ||
+    typeof document.startViewTransition !== "function" ||
+    // 全局的降级规则管不到视图过渡的那几层：这里自己看
+    window.matchMedia?.(REDUCE_QUERY).matches
+  ) {
+    apply();
+    return;
+  }
+
+  element.dataset.themeSwitching = "";
+  const transition = document.startViewTransition(apply);
+  switching = transition;
+  const done = () => {
+    // 被下一次切换打断了的：标记留给后来的那一次撤
+    if (switching !== transition) return;
+    switching = null;
+    delete element.dataset.themeSwitching;
+  };
+  transition.finished.then(done, done);
+  // 被打断时这个承诺是被拒绝的：不算错
+  transition.ready.catch(() => {});
 }
 
 function subscribe(listener: () => void) {
@@ -83,7 +121,8 @@ function setTheme(theme: ThemePreference) {
  *
  * - `theme`：用户的选择，可以是 `"system"`；
  * - `resolvedTheme`：实际生效的 `"light"` 或 `"dark"`；
- * - `setTheme`：切换并记到 `localStorage`。
+ * - `setTheme`：切换并记到 `localStorage`。亮暗变了的时候整页交叉淡化一次
+ *   （浏览器支持视图过渡、系统没开"减少动态效果"时；否则直接切）。
  */
 export function useTheme(): Snapshot & {
   setTheme: (theme: ThemePreference) => void;
@@ -94,6 +133,7 @@ export function useTheme(): Snapshot & {
     () => serverSnapshot,
   );
 
+  // 挂上的时候把记着的主题同步到 <html>：这不是切换，直接写，不淡
   useEffect(() => {
     document.documentElement.dataset.theme = resolvedTheme;
   }, [resolvedTheme]);

package/src/index.ts

@@ -51,6 +51,7 @@ export * from "./components/progress";
 export * from "./components/radio";
 export * from "./components/rec-indicator";
 export * from "./components/registration-strip";
+export * from "./components/rolling-number";
 export * from "./components/schedule";
 export * from "./components/scroll-area";
 export * from "./components/scroll-hint";