@endfield-ui/react 0.2.0 → 1.0.0

package/src/components/dropdown-menu/MenuCheck.tsx

@@ -28,10 +28,12 @@ export function MenuCheck({ checked, disabled = false }: MenuCheckProps) {
             ? [
                 "border-ink-disabled bg-surface-sunken text-ink-disabled",
                 // 菱形方案里"已选"只靠实心表达，禁用了也要保持实心
-                checked && "choice-diamond:bg-ink-disabled",
+                checked &&
+                  "choice-diamond:bg-ink-disabled forced-colors:choice-diamond:bg-[GrayText]",
               ]
             : checked
-              ? "border-surface-inverse bg-surface-inverse text-accent-ink-inverse"
+              ? // 高对比模式下反转块没了：和复选框一样改用系统的"选中"色
+                "border-surface-inverse bg-surface-inverse text-accent-ink-inverse forced-colors:border-[Highlight] forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]"
               : "border-line-strong bg-surface-sunken",
         )}
       >

package/src/components/dropdown-menu/menu-style.ts

@@ -1,5 +1,6 @@
 import { createContext } from "react";
 import { focusRingInset } from "../../lib/focus-ring";
+import { enterFromSide } from "../../lib/motion";
 
 /*
  * 下拉菜单与下拉选择共用的面板和选项。
@@ -12,11 +13,17 @@ export type MenuVariant = "plain" | "strong";
 /** 选项要知道自己在哪种面板里，才知道"当前项"怎么画 */
 export const MenuVariantContext = createContext<MenuVariant>("plain");
 
-/** 面板：直角、1px 线、环境阴影；顶部一条半宽的行动色细条，展开时从 0 伸到一半宽 */
+/**
+ * 面板：直角、1px 线、环境阴影；顶部一条半宽的行动色细条，展开时从 0 伸到一半宽。
+ *
+ * 进场：淡入（200ms），同时从触发处那一侧挪过来 4px（300ms，和细条同一拍）。
+ * 退场只淡出——位移只写在起点上。两个时长、两条缓动按属性一一对应
+ */
 export const menuPanel = [
   "relative min-w-40 border border-line bg-surface-raised py-1 text-ink shadow-sm outline-none",
-  "origin-(--transform-origin) transition-opacity duration-(--duration-fast) ease-standard",
+  "origin-(--transform-origin) transition-[opacity,translate] duration-[var(--duration-fast),var(--duration-base)] ease-[var(--ease-standard),var(--ease-exit)]",
   "data-ending-style:opacity-0 data-starting-style:opacity-0",
+  enterFromSide,
   "before:pointer-events-none before:absolute before:-top-px before:-left-px before:h-[3px] before:w-1/2 before:origin-left before:bg-action before:content-['']",
   "before:transition-transform before:duration-(--duration-base) before:ease-exit data-starting-style:before:scale-x-0",
   "forced-colors:before:hidden",
@@ -35,11 +42,21 @@ export const menuItem = [
 /** 不是当前项的选项才有悬停底：当前项的底不能被悬停盖掉 */
 export const menuItemHover = "data-highlighted:bg-ink/5";
 
-/** 当前项（下拉选择的已选项、单选菜单项的选中项） */
+/**
+ * 当前项（下拉选择的已选项、单选菜单项的选中项）。
+ *
+ * `strong` 的当前项是一整行黄底，而面板是深色的局部主题，焦点色也是黄的：
+ * 画在里面的焦点环换成压得住黄底的颜色，并且再往里收 2px——那个颜色是墨色，
+ * 贴着边的话和深色的面板分不开，看上去只是黄底小了一圈。
+ *
+ * 高对比模式下底色都被系统换掉：两种面板的当前项都是左缘一条系统"选中"色的竖条
+ * （`strong` 平时没有这一条，只在这时候画）
+ */
 export const menuItemCurrent: Record<MenuVariant, string> = {
   plain:
-    "bg-surface-muted font-medium before:absolute before:inset-y-0 before:left-0 before:w-[3px] before:bg-ink before:content-['']",
-  strong: "bg-action font-medium text-on-action",
+    "bg-surface-muted font-medium before:absolute before:inset-y-0 before:left-0 before:w-[3px] before:bg-ink before:content-[''] forced-colors:before:bg-[Highlight]",
+  strong:
+    "bg-action font-medium text-on-action focus-visible:-outline-offset-4 focus-visible:outline-on-action forced-colors:before:absolute forced-colors:before:inset-y-0 forced-colors:before:left-0 forced-colors:before:w-[3px] forced-colors:before:bg-[Highlight] forced-colors:before:content-['']",
 };
 
 export const menuGroupLabel = "px-3 pt-2 pb-1 text-xs text-ink-tertiary";

package/src/components/empty-state/EmptyState.tsx

@@ -14,6 +14,8 @@ export type EmptyStateProps = Omit<ComponentProps<"div">, "title"> & {
   bordered?: boolean;
   /** 标题层级，默认 3（`<h3>`） */
   level?: 2 | 3 | 4 | 5 | 6;
+  /** 挂上时淡入一次，不"啪"地一下出现。默认开启 */
+  animate?: boolean;
 };
 
 /** 取景角 + 准星：游戏内图鉴用它表示"未获得"，空状态沿用这个符号 */
@@ -45,6 +47,7 @@ export function EmptyState({
   icon,
   bordered = true,
   level = 3,
+  animate = true,
   className,
   children,
   ...props
@@ -58,6 +61,8 @@ export function EmptyState({
       className={cn(
         "flex flex-col items-center px-6 py-10 text-center text-ink",
         bordered && "border border-dashed border-line-strong",
+        // 入场只是淡入，不加位移；挂上就播，不等进视口——它要管的就是挂上的那一刻
+        animate && "animate-fade-in",
         className,
       )}
     >

package/src/components/field/Field.tsx

@@ -3,11 +3,14 @@ import {
   useContext,
   useId,
   useMemo,
+  useState,
   type HTMLAttributes,
   type ReactNode,
 } from "react";
+import { usePresence } from "../../hooks/usePresence";
 import { StatusDanger } from "../../icons/StatusDanger";
 import { cn } from "../../lib/cn";
+import { collapse, collapseEnter, collapseInner } from "../../lib/motion";
 
 type FieldContextValue = {
   /** 单个控件的 id；`group` 字段里有多个控件，不提供 */
@@ -106,6 +109,16 @@ export function Field({
     [hasError && errorId, hasHelp && helpId].filter(Boolean).join(" ") ||
     undefined;
 
+  // 错误说明撤掉之后先收起、再卸载。收的时候 `error` 已经空了，画的是最后那一句
+  const {
+    ref: errorRef,
+    mounted: errorMounted,
+    leaving: errorLeaving,
+    entered: errorEntered,
+  } = usePresence<HTMLDivElement>(hasError);
+  const [lastError, setLastError] = useState(error);
+  if (hasError && !Object.is(lastError, error)) setLastError(error);
+
   const context = useMemo<FieldContextValue>(
     () => ({
       controlId: group ? undefined : id,
@@ -143,14 +156,33 @@ export function Field({
 
   const messages = (
     <>
-      {hasError && (
-        <p
-          id={errorId}
-          className="mt-1.5 flex items-start gap-1.5 text-sm text-danger"
+      {errorMounted && (
+        // 出现时按高度把下面的内容顶开并淡入，撤掉时反过来：下面的不会被"啪"地顶一下
+        <div
+          ref={errorRef}
+          data-leaving={errorLeaving ? "" : undefined}
+          // 正在收起的是已经撤掉的那一句，不再读给读屏
+          aria-hidden={errorLeaving || undefined}
+          className={cn(
+            collapse,
+            // 小件：高度和淡入淡出都是 200ms
+            "transition-[grid-template-rows,opacity] duration-(--duration-fast) data-leaving:opacity-0",
+            errorEntered && [collapseEnter, "starting:opacity-0"],
+          )}
         >
-          <StatusDanger size={16} className="mt-0.5 shrink-0" />
-          <span className="min-w-0 wrap-anywhere">{error}</span>
-        </p>
+          <div className={collapseInner}>
+            {/* 和控件之间的 6px 写成内边距，跟着一起收 */}
+            <p
+              id={errorId}
+              className="flex items-start gap-1.5 pt-1.5 text-sm text-danger"
+            >
+              <StatusDanger size={16} className="mt-0.5 shrink-0" />
+              <span className="min-w-0 wrap-anywhere">
+                {hasError ? error : lastError}
+              </span>
+            </p>
+          </div>
+        </div>
       )}
       {hasHelp && (
         <p

package/src/components/file-upload/FileUpload.tsx

@@ -7,7 +7,9 @@ import {
   type ReactNode,
   type Ref,
 } from "react";
+import { useAddedKeys } from "../../hooks/useAddedKeys";
 import { useControllableState } from "../../hooks/useControllableState";
+import { useLingering } from "../../hooks/useLingering";
 import { StatusDanger } from "../../icons/StatusDanger";
 import { Upload } from "../../icons/Upload";
 import { cn } from "../../lib/cn";
@@ -15,6 +17,7 @@ import { decor } from "../../lib/decor";
 import { formatFileSize, matchesAccept, sameFile } from "../../lib/file";
 import { focusRingWithin } from "../../lib/focus-ring";
 import { mergeRefs } from "../../lib/merge-refs";
+import { collapse, fadeInFast } from "../../lib/motion";
 import { useFieldControl } from "../field/Field";
 import { FileItem } from "./FileItem";
 
@@ -104,6 +107,10 @@ const zoneSize: Record<FileUploadSize, string> = {
   md: "gap-3 px-4 py-4",
 };
 
+/** 列表里认一个文件靠的那串字 */
+const fileKey = (file: File) =>
+  `${file.name}-${file.size}-${file.lastModified}`;
+
 /** 拖进来的东西里的文件；文件夹不收 */
 function droppedFiles(transfer: DataTransfer): File[] {
   const items = [...(transfer.items ?? [])];
@@ -115,6 +122,46 @@ function droppedFiles(transfer: DataTransfer): File[] {
   });
 }
 
+/**
+ * 列表里的一行。淡入、收起都写在这一层：里面那一行可能是使用方自己画的（renderFile）。
+ * 移除的那一行先留着——高度收到 0 并淡出，连它占的 4px 行距一起收，收完才卸载；
+ * 下面的行和控件后面的内容是被带着上来的。
+ */
+function FileRow({
+  leaving,
+  entering,
+  children,
+}: {
+  leaving: boolean;
+  entering: boolean;
+  children: ReactNode;
+}) {
+  // 走的时候外面不再给内容了（那个文件在使用方那边可能已经清掉）：画的是最后一次的
+  const [last, setLast] = useState(children);
+  if (!leaving && last !== children) setLast(children);
+
+  return (
+    <li
+      data-leaving={leaving ? "" : undefined}
+      // 正在收起的：点不到、Tab 不进去，读屏也读不到
+      inert={leaving}
+      aria-hidden={leaving || undefined}
+      className={cn(
+        collapse,
+        // 小件：高度、行距、淡出都是 200ms
+        "transition-[grid-template-rows,margin,opacity] duration-(--duration-fast)",
+        "data-leaving:-mb-1 data-leaving:opacity-0",
+        entering && fadeInFast,
+      )}
+    >
+      {/* 只在收的时候裁：平时里面的焦点环要画得出去 */}
+      <div className="min-h-0 min-w-0 in-data-leaving:overflow-y-clip">
+        {leaving ? last : children}
+      </div>
+    </li>
+  );
+}
+
 /**
  * 文件上传：选文件，或者把文件拖进来。它只管"选"和"列"——发请求、算进度是使用方的事。
  *
@@ -164,6 +211,11 @@ export function FileUpload({
     defaultValue: defaultValue ?? [],
     onChange: onValueChange,
   });
+  const keys = files.map(fileKey);
+  // 后来加进来的那几行淡入；一开始就有的是静止的
+  const added = useAddedKeys(keys);
+  // 移除的那一行先留着收起来，收完才从页面里拿掉
+  const lingering = useLingering<HTMLUListElement>(keys);
   const [rejections, setRejections] = useState<FileRejection[]>([]);
   const [dragging, setDragging] = useState(false);
   // dragenter / dragleave 在每个子元素上都会来一次：数着，归零才算真的离开
@@ -190,8 +242,10 @@ export function FileUpload({
     if (index === null) return;
     pendingFocus.current = null;
     const buttons =
-      listRef.current?.querySelectorAll<HTMLElement>("[data-file-remove]") ??
-      [];
+      // 正在收起的那一行不算
+      listRef.current?.querySelectorAll<HTMLElement>(
+        "li:not([data-leaving]) [data-file-remove]",
+      ) ?? [];
     const target = buttons[Math.min(index, buttons.length - 1)];
     if (target) target.focus();
     else inputRef.current?.focus();
@@ -348,7 +402,7 @@ export function FileUpload({
             data-brackets=""
             className={cn(
               decor,
-              "corner-brackets absolute inset-1.5 [--bracket-offset:0px]",
+              "corner-brackets absolute inset-1.5 [--bracket-offset:0px] after:animate-bracket-in",
             )}
           />
         )}
@@ -391,28 +445,33 @@ export function FileUpload({
         )}
       </div>
 
-      {files.length > 0 && (
+      {lingering.entries.length > 0 && (
         <ul
-          ref={listRef}
+          ref={mergeRefs(listRef, lingering.ref)}
           aria-label={labels.list}
-          className="flex flex-col gap-1"
+          // 最后一行也在收了：列表和上面之间那 8px 跟着收，卸载的那一刻后面的内容不跳
+          data-emptying={files.length === 0 ? "" : undefined}
+          className="flex flex-col gap-1 transition-[margin] duration-(--duration-fast) ease-standard data-emptying:-mt-2"
         >
-          {files.map((file, index) => {
+          {lingering.entries.map(({ key, leaving }) => {
+            const index = keys.indexOf(key);
+            const file = files[index];
             const actions = { remove: () => remove(index), index };
             return (
-              <li key={`${file.name}-${file.size}-${file.lastModified}`}>
-                {renderFile ? (
-                  renderFile(file, actions)
-                ) : (
-                  <FileItem
-                    name={file.name}
-                    size={file.size}
-                    disabled={disabled}
-                    removeLabel={removeLabel(file.name)}
-                    onRemove={actions.remove}
-                  />
-                )}
-              </li>
+              <FileRow key={key} leaving={leaving} entering={added.has(key)}>
+                {file !== undefined &&
+                  (renderFile ? (
+                    renderFile(file, actions)
+                  ) : (
+                    <FileItem
+                      name={file.name}
+                      size={file.size}
+                      disabled={disabled}
+                      removeLabel={removeLabel(file.name)}
+                      onRemove={actions.remove}
+                    />
+                  ))}
+              </FileRow>
             );
           })}
         </ul>

package/src/components/icon-button/IconButton.tsx

@@ -21,8 +21,9 @@ export type IconButtonProps = Omit<ComponentProps<"button">, "aria-label"> & {
 };
 
 const sizeClass: Record<IconButtonSize, string> = {
-  // 32px 小于触屏的最小点击区，用伪元素向外补到 40px
-  sm: "size-8 after:absolute after:-inset-1 after:content-[''] [&_svg]:size-4",
+  // 32px 小于触屏的最小点击区，用伪元素向外补到 40px。
+  // 高对比模式下多了一圈 1px 的线，伪元素是从线的里沿起算的，多补 1px 才还是 40px
+  sm: "size-8 after:absolute after:-inset-1 after:content-[''] forced-colors:after:-inset-[5px] [&_svg]:size-4",
   md: "size-10 [&_svg]:size-5",
   lg: "size-12 [&_svg]:size-6",
 };
@@ -50,6 +51,17 @@ const pressedClass: Record<IconButtonVariant, string> = {
   inverse: "bg-surface-inverse text-accent-ink-inverse",
 };
 
+/*
+ * 高对比模式下底色都被系统换掉：没激活的只剩一个图标，看不出是按钮；激活的和没激活的也成了
+ * 一个样子。所以都补一圈线（圆的那种是圆圈）——没激活的是按钮的字色，禁用的是灰字色，
+ * 激活的整块改用系统的"选中"色。线三种状态都有，换状态时图标不会挪
+ */
+const outlineForced = "forced-colors:border";
+const enabledForced = "forced-colors:border-[ButtonText]";
+const pressedForced =
+  "forced-colors:border-[Highlight] forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]";
+const disabledForced = "forced-colors:border-[GrayText]";
+
 const disabledClass: Record<IconButtonVariant, string> = {
   plain: "cursor-not-allowed bg-surface-sunken text-ink-disabled",
   floating:
@@ -81,11 +93,12 @@ export function IconButton({
         "transition-colors duration-(--duration-fast) ease-standard",
         focusRing,
         sizeClass[size],
+        outlineForced,
         disabled
-          ? disabledClass[variant]
+          ? [disabledClass[variant], disabledForced]
           : pressed
-            ? pressedClass[variant]
-            : enabledClass[variant],
+            ? [pressedClass[variant], pressedForced]
+            : [enabledClass[variant], enabledForced],
         className,
       )}
     >

package/src/components/image-viewer/ImageViewer.tsx

@@ -5,6 +5,7 @@ import {
   isValidElement,
   useContext,
   useRef,
+  useState,
   type ComponentProps,
   type KeyboardEvent,
   type ReactElement,
@@ -279,7 +280,12 @@ function Stage({
         </BaseDialog.Close>
       </div>
 
-      <Viewfinder size="md" className="min-h-0 flex-1">
+      {/* 取景角等整层淡入完了再落位：一起动的话被淡入盖住，看不见 */}
+      <Viewfinder
+        size="md"
+        animate
+        className="min-h-0 flex-1 [--bracket-delay:var(--duration-fast)]"
+      >
         <div
           ref={trackRef}
           data-image-viewer-track=""
@@ -287,27 +293,15 @@ function Stage({
           className="absolute inset-0 flex snap-x snap-mandatory overflow-x-auto overscroll-x-contain [scrollbar-width:none]"
         >
           {items.map((item, position) => (
-            <div
+            <Slide
               key={position}
-              role="group"
-              aria-roledescription="幻灯片"
-              aria-label={`第 ${position + 1} 张，共 ${count} 张`}
-              // 不在眼前的：Tab 走不进去，读屏也读不到
-              inert={position !== index}
-              data-current={position === index ? "" : undefined}
-              // 点图以外的空处就是关
-              onClick={(event) => {
-                if (event.target === event.currentTarget) onClose();
-              }}
-              className={cn(
-                "flex size-full shrink-0 snap-start items-center justify-center p-6 sm:p-10",
-                // 图按原比例整张放进去：不裁切，也不放大过它自己的尺寸
-                "*:max-h-full *:max-w-full [&>img]:object-contain [&>video]:object-contain",
-              )}
+              label={`第 ${position + 1} 张，共 ${count} 张`}
+              current={position === index}
+              onClose={onClose}
             >
               {/* 只渲染当前这张和左右各一张：二十张图不会一打开就全去取 */}
               {Math.abs(position - index) <= 1 ? item.props.children : null}
-            </div>
+            </Slide>
           ))}
         </div>
       </Viewfinder>
@@ -360,6 +354,52 @@ function Stage({
   );
 }
 
+type SlideProps = {
+  label: string;
+  current: boolean;
+  onClose: () => void;
+  children: ReactNode;
+};
+
+/**
+ * 轨道上的一张。图是使用方给的元素，这里不碰它，只在外面听它的 `load`：
+ * 还没取到的图是透明的，取到了淡入——不是"啪"地一下出现。
+ * 只管直接放进来的 `<img>`；视频、别的内容不等，和原来一样直接在
+ */
+function Slide({ label, current, onClose, children }: SlideProps) {
+  // 取到过一次就算数：翻远了再翻回来，图是现成的，不用再藏一次
+  const [loaded, setLoaded] = useState(false);
+  const settle = () => setLoaded(true);
+
+  return (
+    <div
+      role="group"
+      aria-roledescription="幻灯片"
+      aria-label={label}
+      // 不在眼前的：Tab 走不进去，读屏也读不到
+      inert={!current}
+      data-current={current ? "" : undefined}
+      data-loaded={loaded ? "" : undefined}
+      // load 和 error 不冒泡，但捕获阶段从外往里走，在这一层听得到。
+      // 取不到的图也要露出来：使用方写的替代文字在那里
+      onLoadCapture={settle}
+      onErrorCapture={settle}
+      // 点图以外的空处就是关
+      onClick={(event) => {
+        if (event.target === event.currentTarget) onClose();
+      }}
+      className={cn(
+        "flex size-full shrink-0 snap-start items-center justify-center p-6 sm:p-10",
+        // 图按原比例整张放进去：不裁切，也不放大过它自己的尺寸
+        "*:max-h-full *:max-w-full [&>img]:object-contain [&>video]:object-contain",
+        "[&>img]:transition-opacity [&>img]:duration-(--duration-fast) [&>img]:ease-standard not-data-loaded:[&>img]:opacity-0",
+      )}
+    >
+      {children}
+    </div>
+  );
+}
+
 export type ImageViewerItemProps = Omit<
   ComponentProps<"li">,
   "title" | "aria-label"

package/src/components/input/control-box.ts

@@ -41,6 +41,12 @@ const fill: Record<ControlVariant, string> = {
   outline: "bg-surface",
 };
 
+/**
+ * 只读时留着占位的那条透明边线，高对比模式下写成页面色：系统会把透明的边线也换成字色
+ * 显出来，而底色本来就都没了——只读的就和能填的一个样。输入框和验证码输入共用
+ */
+export const readOnlyFrame = "forced-colors:border-[Canvas]";
+
 export function controlBox({
   variant = "sunken",
   invalid,
@@ -56,6 +62,8 @@ export function controlBox({
       ? // 只读：没有边线、底变透明。边线留透明的，尺寸不跳
         "border-transparent bg-transparent"
       : fill[variant],
+    // 只在透明的那条线真的作数时：禁用、错误各有自己的边线颜色，排在后面盖掉它
+    readOnly && !disabled && !invalid && readOnlyFrame,
     disabled
       ? "cursor-not-allowed border-line text-ink-disabled"
       : invalid
@@ -66,6 +74,19 @@ export function controlBox({
   );
 }
 
-/** 框里真正的 `<input>` / `<textarea>`：没有自己的底和边，焦点环画在外框上 */
+/**
+ * 框里真正的 `<input>` / `<textarea>`：没有自己的底和边，焦点环画在外框上。
+ *
+ * 高对比模式下禁用的字色要自己写明：平时的 `ink-disabled` 写在外框上，系统换掉之后
+ * 只有它自己认得的禁用控件才是灰字色——`<textarea>`、写了 `type` 的 `<input>` 认得，
+ * 没写 `type` 的 `<input>`（输入框、组合框都是）不认，字和没禁用的一个颜色
+ */
 export const controlElement =
-  "min-w-0 flex-1 bg-transparent outline-none placeholder:text-ink-tertiary disabled:cursor-not-allowed disabled:placeholder:text-ink-disabled";
+  "min-w-0 flex-1 bg-transparent outline-none placeholder:text-ink-tertiary disabled:cursor-not-allowed disabled:placeholder:text-ink-disabled forced-colors:disabled:text-[GrayText]";
+
+/**
+ * 框里跟着禁用变浅、但自己不是控件的字（计数）：`ink-disabled` 写在 `<span>` 上，
+ * 高对比模式下系统当普通字换掉，写明灰字色
+ */
+export const controlDisabledText =
+  "text-ink-disabled forced-colors:text-[GrayText]";

package/src/components/input/value-chip.ts

@@ -12,12 +12,13 @@ export const valueChipSize: Record<ControlSize, string> = {
   lg: "h-8 text-base",
 };
 
+// 高对比模式下底色被系统换掉，小块就成了一串连着的字：补一圈线，一块还是一块
 export const valueChip =
-  "flex max-w-full min-w-0 cursor-default items-center bg-surface-muted pl-2 text-ink";
+  "flex max-w-full min-w-0 cursor-default items-center bg-surface-muted pl-2 text-ink forced-colors:border forced-colors:border-[ButtonText]";
 
 /** 小块右端的删除叉：一个和小块等高的方钮 */
 export const valueChipRemove =
-  "flex aspect-square h-full shrink-0 items-center justify-center text-ink-secondary hover:bg-line hover:text-ink";
+  "flex aspect-square h-full shrink-0 items-center justify-center text-ink-secondary hover:bg-line hover:text-ink forced-colors:in-data-disabled:text-[GrayText]";
 
 /** 和小块排在一起的那个输入框：和小块一样高，这一行才不会比小块高出一截 */
 export const valueInputHeight: Record<ControlSize, string> = {

package/src/components/item-slot/ItemSlot.tsx

@@ -274,7 +274,8 @@ export function ItemSlot({
       className={cn(
         "relative",
         ratioClass[ratio],
-        selected && "corner-brackets",
+        // 选中的那一刻括号从角上伸出来；取消时直接消失
+        selected && "corner-brackets after:animate-bracket-in",
         className,
       )}
     >

package/src/components/loader/Loader.tsx

@@ -1,13 +1,12 @@
 import {
   useEffect,
-  useRef,
-  useState,
   type ComponentProps,
   type KeyboardEvent,
   type ReactNode,
-  type TransitionEvent,
 } from "react";
+import { usePresence } from "../../hooks/usePresence";
 import { cn } from "../../lib/cn";
+import { mergeRefs } from "../../lib/merge-refs";
 
 export type LoaderProps = Omit<ComponentProps<"div">, "children"> & {
   /** 真实进度，0 – 100。不知道就不传：显示不确定进度，不显示数字 */
@@ -24,9 +23,6 @@ export type LoaderProps = Omit<ComponentProps<"div">, "children"> & {
   onExited?: () => void;
 };
 
-/** 滑出的时长，与 `--duration-slower` 一致；过渡事件没来时靠它兜底 */
-const EXIT_MS = 600;
-
 /**
  * 加载页：近黑底、大号等宽百分比、一行标语、黄色进度条。只用于整页的首次加载。
  * 不伪造进度；内容就绪后立刻把 `open` 置为 `false`，不要为了播完动画而等待。
@@ -39,32 +35,15 @@ export function Loader({
   label = "加载中",
   onExited,
   onKeyDown,
-  onTransitionEnd,
   className,
+  ref,
   ...props
 }: LoaderProps) {
-  const rootRef = useRef<HTMLDivElement>(null);
-  const [mounted, setMounted] = useState(open);
-  // 重新打开：立刻挂回来
-  if (open && !mounted) setMounted(true);
-
-  const onExitedRef = useRef(onExited);
-  useEffect(() => {
-    onExitedRef.current = onExited;
+  // 退出：滑出的过渡走完后卸载；重新打开立刻挂回来
+  const { ref: rootRef, mounted } = usePresence<HTMLDivElement>(open, {
+    onExited,
   });
 
-  const leaving = !open && mounted;
-
-  // 退出：滑出的过渡结束后卸载。没有过渡的环境里事件不会来，由定时器兜底
-  useEffect(() => {
-    if (!leaving) return;
-    const timer = window.setTimeout(() => {
-      setMounted(false);
-      onExitedRef.current?.();
-    }, EXIT_MS + 100);
-    return () => window.clearTimeout(timer);
-  }, [leaving]);
-
   // 整页模式：加载期间锁住页面滚动，把焦点收进来；开始退出时就放开
   useEffect(() => {
     if (!fullscreen || !open) return;
@@ -79,18 +58,10 @@ export function Loader({
         previousFocus.focus({ preventScroll: true });
       }
     };
-  }, [fullscreen, open]);
+  }, [fullscreen, open, rootRef]);
 
   if (!mounted) return null;
 
-  const handleTransitionEnd = (event: TransitionEvent<HTMLDivElement>) => {
-    onTransitionEnd?.(event);
-    if (leaving && event.target === event.currentTarget) {
-      setMounted(false);
-      onExitedRef.current?.();
-    }
-  };
-
   const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
     onKeyDown?.(event);
     // 整页加载时焦点留在加载页上，不让 Tab 走到被盖住的内容里
@@ -102,12 +73,11 @@ export function Loader({
 
   return (
     <div
-      ref={rootRef}
       tabIndex={-1}
       {...props}
+      ref={mergeRefs(rootRef, ref)}
       data-state={open ? "open" : "closing"}
       onKeyDown={handleKeyDown}
-      onTransitionEnd={handleTransitionEnd}
       className={cn(
         // 有意不随主题变：加载页是固定的近黑底
         "@container flex flex-col justify-end bg-neutral-950 text-neutral-0 outline-none",
@@ -137,13 +107,14 @@ export function Loader({
           aria-valuemin={0}
           aria-valuemax={100}
           aria-valuenow={indeterminate ? undefined : current}
-          className="relative h-1.5 overflow-hidden rounded-sm bg-neutral-800"
+          // 高对比模式下底色都被系统换掉：轨道剩一圈线，填充用系统的"选中"色（同 Progress）
+          className="relative h-1.5 overflow-hidden rounded-sm bg-neutral-800 forced-colors:outline forced-colors:-outline-offset-1 forced-colors:outline-[CanvasText]"
         >
           {indeterminate ? (
-            <span className="absolute inset-y-0 left-0 w-2/5 animate-indeterminate bg-action motion-reduce:translate-x-3/4" />
+            <span className="absolute inset-y-0 left-0 w-2/5 animate-indeterminate bg-action motion-reduce:translate-x-3/4 forced-colors:bg-[Highlight]" />
           ) : (
             <span
-              className="absolute inset-0 origin-left bg-action transition-transform duration-(--duration-base) ease-standard"
+              className="absolute inset-0 origin-left bg-action transition-transform duration-(--duration-base) ease-standard forced-colors:bg-[Highlight]"
               style={{ transform: `scaleX(${current / 100})` }}
             />
           )}