@endfield-ui/react 0.3.0 → 1.0.1

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";

package/src/lib/README.md

@@ -7,9 +7,10 @@
 | `cn.ts` | `cn()`：合并类名（`clsx` + `tailwind-merge`）。里面登记了 [theme.css](../styles/theme.css) 的自定义令牌名，否则 `text-micro` 会被当成颜色、与 `text-ink` 互相覆盖 |
 | `focus-ring.ts` | `focusRing`、`focusRingInset`、`focusRingWithin`：全库统一的焦点环类名 |
 | `merge-refs.ts` | `mergeRefs()`：组件自己要用节点、同时还得把它交给使用方时，把几个 ref 合成一个 |
+| `inline-style.ts` | `dropEmptyStyle()`：往元素上临时写过内联样式、又都撤掉之后，把空下来的 `style` 属性拿掉。浏览器是懒着同步这个属性的，直接删会落空、回头又冒出一个空的 |
 | `defined.ts` | `defined()`：去掉值是 `undefined` 的属性。把控件的属性合并到使用方给的元素上（`render`）之前用，免得把那个元素自己写的盖掉 |
 | `decor.ts` | `decor`：装饰层共用的类 |
-| `motion.ts` | `enterFromSide`：浮层面板进场的方向位移——按基元给的 `data-side`，起点往触发元素那一侧偏 `--motion-shift`。见 [动效](../../../../docs/design/foundations/motion.md#方向位移) |
+| `motion.ts` | 几处共用的动效类名。`enterFromSide`：浮层面板进场的方向位移——按基元给的 `data-side`，起点往触发元素那一侧偏 `--motion-shift`；`collapse` / `collapseEnter` / `collapseInner`：按高度收放；`fadeInFast`：小件的淡入；`indicator` / `indicatorBox`：画在容器 `::after` 上的选中指示，位置来自 `useIndicator`；`flipBox` / `flipLeaving`：补位（`useFlip`）的那一排，和里面走的那一项。见 [动效](../../../../docs/design/foundations/motion.md#补的几条约定) |
 | `date.ts` | 日期的纯函数：加减日和月、比较、把两天排成先后、夹到范围内、月历的六行七列。日期一律是 `YYYY-MM-DD` 的字符串，全部按 UTC 算，不碰本地时区。`Calendar`、`DatePicker`、`Schedule` 共用，不对外导出 |
 | `file.ts` | 文件的纯函数：按 `accept` 认类型（扩展名、MIME、`image/*` 通配）、把字节数写成 `1.2 MB`、取扩展名、判断是不是同一个文件。`FileUpload` 用，不对外导出 |
 

package/src/lib/cn.ts

@@ -26,6 +26,7 @@ const twMerge = extendTailwindMerge({
         "indeterminate",
         "bracket-in",
         "shift-in",
+        "wipe-in",
       ],
     },
   },

package/src/lib/inline-style.ts

@@ -0,0 +1,12 @@
+/**
+ * 往元素上临时写过内联样式、又都撤掉之后调：原来没有 `style` 属性的，
+ * 不留一个空的在上面。
+ *
+ * 先问一句"有没有这个属性"不是多余的：浏览器是懒着把内联样式同步成属性的，
+ * 不问就去删，删的那一下落空，回头它又冒出来一个空的 `style=""`。
+ */
+export function dropEmptyStyle(node: HTMLElement) {
+  if (node.style.length === 0 && node.hasAttribute("style")) {
+    node.removeAttribute("style");
+  }
+}

package/src/lib/motion.ts

@@ -13,3 +13,78 @@ export const enterFromSide = [
   "data-starting-style:data-[side=inline-end]:-translate-x-(--motion-shift)",
   "data-starting-style:data-[side=inline-start]:translate-x-(--motion-shift)",
 ].join(" ");
+
+/**
+ * 按高度收放，不量高度：外面这一层是只有一行的网格，行高在 `0fr` 和 `1fr` 之间过渡；
+ * 里面再套一层 `collapseInner`，裁掉还放不下的那一截。表格的明细行、字段下面的错误文字
+ * 都这么收放——内容后来变高了也跟着走。
+ *
+ * 展开 300ms、收起 200ms。收起由 `data-leaving` 触发，配 `usePresence`：收完再卸载。
+ */
+export const collapse = [
+  "grid grid-rows-[1fr]",
+  "transition-[grid-template-rows] duration-(--duration-base) ease-standard",
+  "data-leaving:grid-rows-[0fr] data-leaving:duration-(--duration-fast)",
+].join(" ");
+
+/**
+ * 展开的起点，写在 `@starting-style` 里：元素一挂上就从 0 长出来，展开到一半又收起时
+ * 过渡从半路折回去。只给后来才出现的加（`usePresence` 的 `entered`）——一开始就展开着的，
+ * 不该在载入时播一遍。不支持它的旧浏览器只是没有展开的过程。
+ */
+export const collapseEnter = "starting:grid-rows-[0fr]";
+
+/** 只裁纵向：横向照旧，里面的东西该多宽还是多宽 */
+export const collapseInner = "min-h-0 min-w-0 overflow-y-clip";
+
+/** 小件的淡入，200ms：切过来的页签面板、新加的标签、新选的文件 */
+export const fadeInFast =
+  "animate-fade-in [animation-duration:var(--duration-fast)]";
+
+/**
+ * 选中指示：画在容器的 `::after` 上的一块东西，压在容器的底色之上、各项之下。
+ * 位置和尺寸来自 `useIndicator` 写在容器上的变量；换了一项时滑过去（200ms，
+ * 和各项换字色同一拍），没有当前项时原地淡出。
+ *
+ * 容器上没有 `data-indicator`（量不到）时不画——各项照旧自己画选中态，
+ * 所以给各项的选中底加一个 `in-data-indicator:` 的变体把它让出来。
+ * 这里只管定位和过渡：颜色、圆角由用的地方给，几何用 `indicatorBox` 或者自己写。
+ */
+export const indicator = [
+  "relative isolate",
+  "after:pointer-events-none after:absolute after:top-0 after:left-0 after:-z-1",
+  "after:hidden data-indicator:after:block",
+  "after:opacity-0 data-[indicator=on]:after:opacity-100",
+  "after:transition-[translate,width,height,opacity] after:duration-(--duration-fast) after:ease-standard",
+  // 没有当前项的时候只留淡入淡出：下一次亮起来是原地出现，不是从上一个位置滑来
+  "data-[indicator=off]:after:transition-[opacity]",
+  "data-indicator-instant:after:transition-none",
+].join(" ");
+
+/** 指示盖住当前项的整个盒子：分段选择的墨块、胶囊页签的底 */
+export const indicatorBox = [
+  "after:h-(--indicator-h) after:w-(--indicator-w)",
+  "after:translate-x-(--indicator-x) after:translate-y-(--indicator-y)",
+].join(" ");
+
+/**
+ * 补位（`useFlip`）：一排里有一项走了，其余的从旧位置滑到新位置。
+ *
+ * `flipBox` 给那一排——走的那一项以它为参照钉在原处，并且压在别的项下面。
+ * 少了一行它就矮了：高度由钩子量着收（200ms），这期间还在滑的项不露到它外面去；
+ * 各行靠上排，撑着的那一段空在底下。
+ * `flipLeaving` 给会走的每一项：带上 `data-leaving` 之后脱离排版（位置由钩子给）、
+ * 原地淡出、点不到。
+ *
+ * 过渡由用的地方自己写：各项的 `translate`（滑回原位）、走的那一项的 `opacity`，
+ * 都是 200ms——这几项多半本来就带着换色的过渡，得写进同一份清单里。
+ */
+export const flipBox = [
+  "relative isolate content-start overflow-y-clip",
+  "transition-[min-height] duration-(--duration-fast) ease-standard",
+].join(" ");
+
+export const flipLeaving = [
+  "data-leaving:pointer-events-none data-leaving:absolute data-leaving:-z-1",
+  "data-leaving:opacity-0",
+].join(" ");

package/src/styles/theme.css

@@ -1,9 +1,9 @@
 /*
- * endfield-ui 设计令牌（草案）
+ * endfield-ui 设计令牌
  *
  * 用法：
  *   @import "tailwindcss";
- *   @import "./theme.css";
+ *   @import "@endfield-ui/react/theme.css";
  *
  * 结构：
  *   1. 语义变量      随主题变化；亮色在 :root 与 [data-theme="light"]，
@@ -377,6 +377,7 @@
   --animate-pulse: ef-pulse 2s ease-in-out infinite;
   --animate-bracket-in: ef-bracket-in 200ms ease-out both;
   --animate-shift-in: ef-shift-in 300ms ease-out both;
+  --animate-wipe-in: ef-wipe-in 300ms ease-out both;
 
   /* 三次短促闪烁后点亮（官网实测的关键帧节奏） */
   @keyframes ef-flicker {
@@ -547,6 +548,23 @@
       translate: var(--shift-x, 0) var(--shift-y, 0);
     }
   }
+
+  /*
+   * 擦入：从左往右露出来。两头都要写——"没有裁切"和 inset() 之间插不了值。
+   * 有东西画到盒子外面一点的（小型面积图的折线有半个线宽在外面），用 --wipe-bleed
+   * 把另外几边往外让，不然走完之后那一圈是被裁掉的
+   */
+  @keyframes ef-wipe-in {
+    from {
+      clip-path: inset(
+        calc(0px - var(--wipe-bleed, 0px)) 100%
+          calc(0px - var(--wipe-bleed, 0px)) calc(0px - var(--wipe-bleed, 0px))
+      );
+    }
+    to {
+      clip-path: inset(calc(0px - var(--wipe-bleed, 0px)));
+    }
+  }
 }
 
 /* ------------------------------------------------------------------ */
@@ -592,6 +610,24 @@
   --color-info: var(--ef-info);
 }
 
+/* ------------------------------------------------------------------ */
+/* 主题切换                                                             */
+/* ------------------------------------------------------------------ */
+
+/*
+ * useTheme 切亮暗时整页交叉淡化一次（浏览器支持视图过渡时）。切的那一下它在 <html> 上标
+ * data-theme-switching，这里把根的那几层换成"颜色、透明度"那一档的时长。
+ * 只在这个标记下生效：使用方自己的视图过渡不受影响。三层要一起给——只改新旧两层的话，
+ * 组那一层还是浏览器默认的 250ms，整个过渡要到那时候才算完。
+ * "减少动态效果"不在这里管：开了的时候 useTheme 根本不走视图过渡
+ */
+:root[data-theme-switching]::view-transition-group(root),
+:root[data-theme-switching]::view-transition-old(root),
+:root[data-theme-switching]::view-transition-new(root) {
+  animation-duration: var(--duration-fast);
+  animation-timing-function: var(--ease-standard);
+}
+
 /* ------------------------------------------------------------------ */
 /* 减少动态效果                                                         */
 /* ------------------------------------------------------------------ */