@endfield-ui/react 0.2.0 → 1.0.0

package/src/components/sparkline/Sparkline.tsx

@@ -1,5 +1,7 @@
 import type { ComponentProps } from "react";
+import { useInView } from "../../hooks/useInView";
 import { cn } from "../../lib/cn";
+import { mergeRefs } from "../../lib/merge-refs";
 
 export type SparklineVariant = "area" | "line";
 export type SparklineTone = "info" | "danger" | "accent" | "neutral";
@@ -22,6 +24,8 @@ export type SparklineProps = Omit<ComponentProps<"svg">, "children"> & {
   max?: number;
   /** 传了它就是一张有名称的图；不传是纯装饰，对读屏隐藏 */
   label?: string;
+  /** 进入视口时从左画出一次。默认开启 */
+  animate?: boolean;
 };
 
 /* 画在一个 100 × 100 的格子里，再由 SVG 拉伸到实际的盒子 */
@@ -58,7 +62,13 @@ export function sparklinePath(
   return { line, area: `${line}L${SIZE} ${SIZE}L0 ${SIZE}Z` };
 }
 
-/* data 与 alert 是不随主题变的角色色：白底和深色行带上都认得出 */
+/*
+ * data 与 alert 是不随主题变的角色色：白底和深色行带上都认得出。
+ * 高对比模式：SVG 上写的颜色系统不换，压在使用者自己定的页面色上可能看不清——
+ * 四种色调都换成页面的字色（色调说的事本来就要靠旁边的数字）
+ */
+const areaForced = "forced-colors:fill-[CanvasText]";
+const lineForced = "forced-colors:stroke-[CanvasText]";
 const areaClass: Record<SparklineTone, string> = {
   info: "fill-data/75",
   danger: "fill-alert/75",
@@ -84,10 +94,16 @@ export function Sparkline({
   min,
   max,
   label,
+  animate = true,
   className,
+  ref,
   ...props
 }: SparklineProps) {
   const path = sparklinePath(data, { min, max });
+  const [inViewRef, inView] = useInView<SVGSVGElement>({ disabled: !animate });
+  // 入场：整张图从左擦出来，面积和折线是同一个写法。一屏里的几张各看各的视口，同时到的一起画
+  const pending = animate && !inView;
+  const playing = animate && inView;
 
   return (
     <svg
@@ -100,12 +116,20 @@ export function Sparkline({
       data-variant={variant}
       data-tone={tone}
       {...props}
-      // 折线贴着上下边缘时，线宽的一半会落在盒子外面
-      className={cn("block h-8 w-full overflow-visible", className)}
+      ref={mergeRefs(inViewRef, ref)}
+      className={cn(
+        // 折线贴着上下边缘时，线宽的一半会落在盒子外面
+        "block h-8 w-full overflow-visible",
+        pending && "[clip-path:inset(0_100%_0_0)]",
+        // 擦的时候把盒子外面那一圈也留出来（线宽的一半，尖角还要多一点）
+        playing &&
+          "animate-wipe-in [animation-duration:var(--duration-slower)] [--wipe-bleed:4px]",
+        className,
+      )}
     >
       {path &&
         (variant === "area" ? (
-          <path d={path.area} className={areaClass[tone]} />
+          <path d={path.area} className={cn(areaClass[tone], areaForced)} />
         ) : (
           <path
             d={path.line}
@@ -114,7 +138,7 @@ export function Sparkline({
             strokeLinejoin="miter"
             // 图被横向拉伸了，线宽不跟着变
             vectorEffect="non-scaling-stroke"
-            className={lineClass[tone]}
+            className={cn(lineClass[tone], lineForced)}
           />
         ))}
     </svg>

package/src/components/spinner/Spinner.tsx

@@ -19,8 +19,12 @@ const sizeClass: Record<SpinnerSize, string> = {
 };
 
 // 系统开启"减少动态效果"时停成一个 45° 的菱形，和列表里的菱形记号是同一个样子
-const square =
-  "animate-spin bg-current motion-reduce:rotate-45 motion-reduce:animate-none";
+const square = [
+  "animate-spin bg-current motion-reduce:rotate-45 motion-reduce:animate-none",
+  // 高对比模式下底色被系统换成页面色，方块就没了：换成页面的字色。
+  // 写的是系统色，不是 currentColor——使用方用 className 给它另上了颜色时，这里照样看得见
+  "forced-colors:bg-[CanvasText]",
+].join(" ");
 
 /**
  * 行内加载指示：一个匀速旋转的小方块，颜色继承文字。

package/src/components/stepper/Stepper.tsx

@@ -238,6 +238,8 @@ export function Stepper({
     cn(
       "flex shrink-0 items-center justify-center select-none",
       "transition-colors duration-(--duration-fast) ease-standard",
+      // 高对比模式下底色都被系统换掉，加减钮只剩一个记号：补一圈线，和中间那一格连成三格
+      "forced-colors:border forced-colors:border-[ButtonText] forced-colors:disabled:border-[GrayText]",
       buttonSize[size],
       inactive
         ? "cursor-not-allowed bg-disabled text-on-disabled"
@@ -292,6 +294,8 @@ export function Stepper({
         className={cn(
           "min-w-0 flex-1 border-y-2 border-transparent bg-surface-sunken text-center font-tech font-bold tabular-nums outline-none",
           "disabled:cursor-not-allowed",
+          // 高对比模式：上下各一条 1px 的线，和两端按钮的那一圈连成三格
+          "forced-colors:border-y forced-colors:border-[ButtonText] forced-colors:disabled:border-[GrayText]",
           fieldSize[size],
           disabled ? "text-ink-disabled" : "text-ink",
           invalid && !disabled && "border-b-danger",

package/src/components/steps/Steps.tsx

@@ -75,11 +75,16 @@ const railLayout: Record<StepsOrientation, string> = {
   horizontal: "flex-col @md:flex-row",
 };
 
-/* 线和节点之间留 8px，不从节点后面穿过 */
+/*
+ * 线和节点之间留 8px，不从节点后面穿过。
+ * 高对比模式下线是底色画的，整条都会不见：没到的收成一条 1px 的细线，画成线自己的一条边
+ * （竖排在右、横排在下）；走过的那一段照旧充进来，填上剩下的 1px，还是 2px。
+ * 走没走过是粗对细，不靠两种系统色分
+ */
 const lineLayout: Record<StepsOrientation, string> = {
-  vertical: "my-2 min-h-4 w-0.5",
+  vertical: "my-2 min-h-4 w-0.5 forced-colors:border-r",
   horizontal:
-    "my-2 min-h-4 w-0.5 @md:mx-2 @md:my-0 @md:h-0.5 @md:min-h-0 @md:w-auto",
+    "my-2 min-h-4 w-0.5 @md:mx-2 @md:my-0 @md:h-0.5 @md:min-h-0 @md:w-auto forced-colors:@max-md:border-r forced-colors:@md:border-b",
 };
 
 const bodyLayout: Record<StepsOrientation, string> = {
@@ -161,11 +166,17 @@ const nodeSize: Record<StepsSize, string> = {
   md: "size-6 text-xs [&_svg]:size-3.5",
 };
 
+/*
+ * 高对比模式下底色都被系统换掉：已完成的只剩一个勾浮着，当前的和未到的都成了空心框、
+ * 只差序号的粗细。三种状态还是三种形状——页面字色的实心块、系统"选中"色的实心块、空心框
+ */
 const nodeClass: Record<StepStatus, string> = {
   // 墨底黄勾：和选中的复选框是同一个逻辑
-  done: "bg-surface-inverse text-accent-ink-inverse",
-  // 描一圈最细的线：黄色对白底立不住。颜色跟着文字走，暗色下是近白
-  current: "border border-ink bg-action font-bold text-on-action",
+  done: "bg-surface-inverse text-accent-ink-inverse forced-colors:bg-[CanvasText] forced-colors:text-[Canvas]",
+  // 描一圈最细的线：黄色对白底立不住。颜色跟着文字走，暗色下是近白。
+  // 序号是字，压在"选中"色上要关掉系统的接管（不然字后面会垫一块页面色），边线跟着自己写
+  current:
+    "border border-ink bg-action font-bold text-on-action forced-colors:forced-color-adjust-none forced-colors:border-[Highlight] forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]",
   upcoming: "border border-line-strong text-ink-secondary",
 };
 
@@ -243,6 +254,8 @@ export function Step({
         <span
           className={cn(
             "flex shrink-0 items-center justify-center font-tech leading-none tabular-nums",
+            // 未到 → 当前 → 已完成，换色不硬切
+            "transition-colors duration-(--duration-fast) ease-standard",
             nodeSize[size],
             invalid ? "border border-danger text-danger" : nodeClass[status],
           )}
@@ -255,12 +268,20 @@ export function Step({
             String(index + 1).padStart(2, "0")
           )}
         </span>
-        {/* 这一步走完了，通向下一步的线才是实的 */}
+        {/*
+          这一步走完了，通向下一步的线才是实的。线自己一直是"没到"的颜色，
+          墨色画在 ::before 上，走完时从起点一端充到头，往回走时收回去。
+          从左上角两个方向一起放大，所以横排、竖排、容器变窄自动改竖排用的是同一组类。
+          墨色那一层比线多出去 16px、由线自己裁掉：这样粗的那个方向一开始就是满的
+          （不多出去的话，线是一边变长一边从 0 变粗的，半路上看着比别的线细）
+        */}
         <span
           className={cn(
-            "flex-1 group-last/step:hidden",
+            "relative flex-1 overflow-clip bg-line-strong group-last/step:hidden",
+            "forced-colors:border-[CanvasText] forced-colors:before:bg-[CanvasText]",
+            "before:absolute before:top-0 before:-right-4 before:-bottom-4 before:left-0 before:origin-top-left before:bg-ink before:transition-[scale] before:duration-(--duration-base) before:ease-exit before:content-['']",
             lineLayout[orientation],
-            status === "done" ? "bg-ink" : "bg-line-strong",
+            status === "done" ? "before:scale-100" : "before:scale-0",
           )}
         />
       </span>

package/src/components/switch/Switch.tsx

@@ -22,6 +22,15 @@ const trackTransition =
   "transition-colors duration-(--duration-fast) ease-standard";
 const dualLabel =
   "pointer-events-none relative min-w-9 px-3 text-center transition-colors duration-(--duration-fast) ease-standard peer-disabled:text-ink-disabled";
+/*
+ * 高对比模式：旋钮是系统的"选中"色（禁用时是灰字色），压在它上面的那个值用配它的字色，
+ * 轨道上的另一个值用页面的字色。关的时候旋钮在"关"的值下面，开了换到"开"的值下面。
+ * 两个值的颜色都写明了，不让系统再改——不然它会在字后面垫一块页面色，把旋钮盖掉
+ */
+const dualOffForced =
+  "forced-colors:forced-color-adjust-none forced-colors:text-[HighlightText] forced-colors:peer-checked:text-[CanvasText] forced-colors:peer-disabled:text-[Canvas] forced-colors:peer-checked:peer-disabled:text-[GrayText]";
+const dualOnForced =
+  "forced-colors:forced-color-adjust-none forced-colors:text-[CanvasText] forced-colors:peer-checked:text-[HighlightText] forced-colors:peer-disabled:text-[GrayText] forced-colors:peer-checked:peer-disabled:text-[Canvas]";
 
 /**
  * 开关：胶囊轨道 + 圆形旋钮，立即生效的设置用它（需要"保存"才生效的用复选框）。
@@ -58,6 +67,8 @@ export function Switch({
         className={cn(
           // 两个值都是有效值，轨道不随开关变色：反转块的 80%，压在图像上时略微透出底下
           "peer absolute inset-0 size-full appearance-none rounded-full bg-surface-inverse/80 group-hover:bg-surface-inverse disabled:cursor-not-allowed disabled:bg-surface-muted",
+          // 高对比模式下底色都被系统换掉：轨道剩一圈边线，旋钮（下面那一块）用系统的"选中"色
+          "forced-colors:border forced-colors:border-[ButtonText] forced-colors:disabled:border-[GrayText]",
           trackTransition,
           focusRing,
         )}
@@ -68,20 +79,29 @@ export function Switch({
           "pointer-events-none absolute inset-y-1 left-1 w-[calc(50%-0.25rem)] rounded-full bg-surface-muted",
           "transition-[translate] duration-(--duration-fast) ease-standard",
           "peer-checked:translate-x-full peer-disabled:bg-surface-raised",
+          "forced-colors:bg-[Highlight] forced-colors:peer-disabled:bg-[GrayText]",
         )}
       />
       {/* 旋钮上的值用墨色，轨道上的另一个值降到 70% */}
       <span
         aria-hidden="true"
         data-value="off"
-        className={cn(dualLabel, "text-ink peer-checked:text-ink-inverse/70")}
+        className={cn(
+          dualLabel,
+          "text-ink peer-checked:text-ink-inverse/70",
+          dualOffForced,
+        )}
       >
         {offLabel}
       </span>
       <span
         aria-hidden="true"
         data-value="on"
-        className={cn(dualLabel, "text-ink-inverse/70 peer-checked:text-ink")}
+        className={cn(
+          dualLabel,
+          "text-ink-inverse/70 peer-checked:text-ink",
+          dualOnForced,
+        )}
       >
         {onLabel}
       </span>
@@ -96,6 +116,9 @@ export function Switch({
         className={cn(
           // 开：反转块作轨道。颜色只点在旋钮上，不是整条黄色轨道
           "peer h-7 w-13 appearance-none rounded-full bg-line-strong group-hover:bg-ink-tertiary checked:bg-surface-inverse disabled:cursor-not-allowed disabled:bg-surface-muted",
+          // 高对比模式下底色都被系统换掉，整个开关就没了：关是一圈边线，开是系统"选中"色的实心轨道
+          "forced-colors:border-2 forced-colors:border-[ButtonText] forced-colors:checked:border-[Highlight] forced-colors:checked:bg-[Highlight]",
+          "forced-colors:disabled:border-[GrayText] forced-colors:checked:disabled:bg-[GrayText]",
           trackTransition,
           focusRing,
         )}
@@ -106,6 +129,7 @@ export function Switch({
           "pointer-events-none absolute top-1 left-1 size-5 rounded-full bg-surface-raised",
           "transition-[translate,background-color] duration-(--duration-fast) ease-standard",
           "peer-checked:translate-x-6 peer-checked:bg-accent-ink-inverse peer-disabled:bg-ink-disabled",
+          "forced-colors:bg-[ButtonText] forced-colors:peer-checked:bg-[HighlightText] forced-colors:peer-disabled:bg-[GrayText] forced-colors:peer-checked:peer-disabled:bg-[Canvas]",
         )}
       />
     </span>

package/src/components/table/Table.tsx

@@ -16,10 +16,12 @@ import {
 } from "react";
 import { useControllableState } from "../../hooks/useControllableState";
 import { useOverflowing } from "../../hooks/useOverflowing";
+import { usePresence, type Presence } from "../../hooks/usePresence";
 import { TriangleRight } from "../../icons/TriangleRight";
 import { cn } from "../../lib/cn";
 import { focusRing, focusRingInset } from "../../lib/focus-ring";
 import { mergeRefs } from "../../lib/merge-refs";
+import { collapse, collapseEnter, collapseInner } from "../../lib/motion";
 
 export type TableHeaderVariant = "band" | "muted";
 export type TableSize = "sm" | "md";
@@ -173,10 +175,11 @@ export type TableBodyProps = ComponentProps<"tbody">;
 
 /*
  * 每隔五行加重一条线。只数主行：展开的明细也是一个 <tr>，不能让它把数数错。
- * 第五行自己展开着的时候，它的下边线没有了，加重的那条画在它的明细下面
+ * 第五行后面跟着明细的时候（展开着，或者正在收起），它的下边线没有了，
+ * 加重的那条画在它的明细下面
  */
 const ruledLines = [
-  "[&>tr:nth-child(5n_of_:not([data-detail])):not([data-expanded])>*]:border-line-strong",
+  "[&>tr:nth-child(5n_of_:not([data-detail])):not(:has(+tr[data-detail]))>*]:border-line-strong",
   "[&>tr:nth-child(5n_of_:not([data-detail]))+tr[data-detail]>*]:border-line-strong",
 ].join(" ");
 
@@ -241,6 +244,8 @@ export function TableRow({
   const expandable =
     detail !== undefined && detail !== null && detail !== false;
   const open = expandable && expanded;
+  // 收起：明细先按高度收回去，收完再卸载
+  const detailPresence = usePresence<HTMLDivElement>(open);
 
   const context = useMemo(
     () =>
@@ -269,18 +274,19 @@ export function TableRow({
         className={cn(
           "group/row transition-colors duration-(--duration-fast) ease-standard",
           selected ? rowSelected : rowIdle,
-          // 展开着：它和下面的明细是一块，中间不画线
-          "[&[data-expanded]>*]:border-b-transparent",
+          // 后面跟着明细（展开着，或者正在收起）：它们是一块，中间不画线
+          "[&:has(+tr[data-detail])>*]:border-b-transparent",
           className,
         )}
       >
         <RowContext value={context}>{children}</RowContext>
       </tr>
-      {open && (
+      {detailPresence.mounted && (
         <DetailRow
           id={detailId}
           rowRef={rowRef}
           estimate={countCells(children)}
+          presence={detailPresence}
         >
           {detail}
         </DetailRow>
@@ -303,11 +309,13 @@ function DetailRow({
   id,
   rowRef,
   estimate,
+  presence,
   children,
 }: {
   id: string;
   rowRef: RefObject<HTMLTableRowElement | null>;
   estimate: number;
+  presence: Presence<HTMLDivElement>;
   children: ReactNode;
 }) {
   const [measured, setMeasured] = useState<number | null>(null);
@@ -323,14 +331,30 @@ function DetailRow({
   });
 
   return (
-    <tr id={id} data-detail="">
+    // 正在收起的明细点不到、Tab 不进去
+    <tr id={id} data-detail="" inert={presence.leaving}>
       <td
         colSpan={measured ?? estimate}
         className="border-b border-line bg-surface-sunken p-0 [tr:last-child>&]:border-b-0"
       >
-        {/* 表格横向滚动时明细不跟着滚走：钉在容器的左缘，宽度是容器看得见的那一段 */}
-        <div className="sticky left-0 w-[var(--table-viewport,100%)] px-4 py-3 text-sm whitespace-normal">
-          {children}
+        {/*
+         * 表格横向滚动时明细不跟着滚走：钉在容器的左缘，宽度是容器看得见的那一段。
+         * 收放也在这一层上——表格行的高度过渡不了，过渡的是单元格里的它
+         */}
+        <div
+          ref={presence.ref}
+          data-leaving={presence.leaving ? "" : undefined}
+          className={cn(
+            "sticky left-0 w-[var(--table-viewport,100%)]",
+            collapse,
+            presence.entered && collapseEnter,
+          )}
+        >
+          <div className={collapseInner}>
+            <div className="px-4 py-3 text-sm whitespace-normal">
+              {children}
+            </div>
+          </div>
         </div>
       </td>
     </tr>

package/src/components/tabs/Tabs.tsx

@@ -3,14 +3,18 @@ import {
   useContext,
   useId,
   useMemo,
+  useState,
   type ComponentProps,
   type KeyboardEvent,
   type MouseEvent,
 } from "react";
 import { useControllableState } from "../../hooks/useControllableState";
+import { useIndicator } from "../../hooks/useIndicator";
 import { TriangleRight } from "../../icons/TriangleRight";
 import { cn } from "../../lib/cn";
 import { focusRing, focusRingInset } from "../../lib/focus-ring";
+import { mergeRefs } from "../../lib/merge-refs";
+import { fadeInFast, indicator, indicatorBox } from "../../lib/motion";
 import { capsuleBase, capsuleSize, capsuleState } from "../chip/capsule-style";
 
 export type TabsVariant = "block" | "capsule" | "wedge";
@@ -22,6 +26,8 @@ type TabsContextValue = {
   baseId: string;
   variant: TabsVariant;
   size: TabsSize;
+  /** 切换过没有：一开始选中的那一块面板是静止的，切过来的才淡入 */
+  switched: boolean;
 };
 
 const TabsContext = createContext<TabsContextValue | null>(null);
@@ -71,9 +77,13 @@ export function Tabs({
     onChange: onValueChange,
   });
 
+  const [initial] = useState(current);
+  const [switched, setSwitched] = useState(false);
+  if (!switched && current !== initial) setSwitched(true);
+
   const context = useMemo(
-    () => ({ value: current, select, baseId, variant, size }),
-    [current, select, baseId, variant, size],
+    () => ({ value: current, select, baseId, variant, size, switched }),
+    [current, select, baseId, variant, size, switched],
   );
 
   return (
@@ -85,8 +95,12 @@ export function Tabs({
 
 export type TabListProps = ComponentProps<"div">;
 
-export function TabList({ className, onKeyDown, ...props }: TabListProps) {
+export function TabList({ className, onKeyDown, ref, ...props }: TabListProps) {
   const { variant } = useTabsContext("TabList");
+  // 胶囊：选中的底画在这一栏上，换一个时是同一块滑过去。另外两种的"让位"是实测的，不动
+  const listRef = useIndicator<HTMLDivElement>(
+    variant === "capsule" ? '[role="tab"][aria-selected="true"]' : null,
+  );
 
   // 漫游 tabindex：方向键在页签之间移动焦点并直接切换
   const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
@@ -128,13 +142,24 @@ export function TabList({ className, onKeyDown, ...props }: TabListProps) {
   return (
     <div
       {...props}
+      ref={mergeRefs(listRef, ref)}
       role="tablist"
       aria-orientation="horizontal"
       onKeyDown={handleKeyDown}
       className={cn(
         // 页签很多时横向滚动，不换行
         "flex overflow-x-auto [scrollbar-width:thin]",
-        variant === "capsule" && "gap-2 p-1",
+        variant === "capsule" && [
+          "gap-2 p-1",
+          // 胶囊各有各的宽：底滑过去的时候宽度跟着变。它在滚动的内容里，跟着内容走
+          indicator,
+          indicatorBox,
+          // 墨底提到各个胶囊的轮廓线之上：滑过去的时候是一块干净的实心胶囊，
+          // 不被相邻胶囊的轮廓切开。胶囊里的字另提一层，留在它上面
+          "after:z-0 after:rounded-full after:bg-surface-inverse",
+          // 高对比模式下底色被系统换掉，这一块成了盖住选中胶囊轮廓的一片页面色：改用系统的"选中"色
+          "forced-colors:after:bg-[Highlight]",
+        ],
         // 楔形坐在一条墨线上：亮色页面上黄色对白底的明度差很小，靠这条线托住
         variant === "wedge" && "border-b-2 border-ink",
         className,
@@ -205,14 +230,21 @@ export function Tab({
           focusRing,
           capsuleSize[size],
           selected
-            ? capsuleState.selected
+            ? // 这一栏量到了位置，底就由栏上滑动的那一块来画
+              [
+                capsuleState.selected,
+                "in-data-indicator:bg-transparent forced-colors:in-data-indicator:bg-transparent",
+              ]
             : disabled
               ? capsuleState.disabled
               : capsuleState.rest,
           className,
         )}
       >
-        {children}
+        {/* 字在滑动的墨底之上；间距跟按钮自己的走，里面照旧是一行居中的弹性排布 */}
+        <span className="relative z-1 inline-flex items-center gap-[inherit]">
+          {children}
+        </span>
       </button>
     );
   }
@@ -229,7 +261,13 @@ export function Tab({
           focusRingInset,
           wedgeSize[size],
           selected
-            ? "text-on-action before:bg-action"
+            ? // 焦点环画在里面、压在黄楔上：普通的焦点色在暗色主题下也是黄的，看不见，
+              // 换成压得住黄底的颜色。再往里收 2px：这个颜色贴着边的话，在暗色页面上
+              // 和页面分不开，看上去只是黄楔小了一圈。
+              // 高对比模式下黄底被系统换掉：楔形改用系统的"选中"色，字用配它的字色；
+              // 这一个的颜色不让系统再改，不然它会在字后面垫一块页面色。
+              // 画在里面的焦点环也用那个字色，再往里收 2px：贴着边的话它和页面一个颜色
+              "text-on-action before:bg-action focus-visible:-outline-offset-4 focus-visible:outline-on-action forced-colors:forced-color-adjust-none forced-colors:text-[HighlightText] forced-colors:before:bg-[Highlight] forced-colors:focus-visible:-outline-offset-4 forced-colors:focus-visible:outline-[HighlightText]"
             : disabled
               ? "cursor-not-allowed text-ink-disabled"
               : "text-ink hover:before:bg-ink/5",
@@ -287,7 +325,10 @@ export type TabPanelProps = ComponentProps<"div"> & {
   value: string;
 };
 
-/** 未选中的面板保留一个隐藏的空容器，让页签的 `aria-controls` 始终有所指。 */
+/**
+ * 未选中的面板保留一个隐藏的空容器，让页签的 `aria-controls` 始终有所指。
+ * 切过来的面板淡入；一开始就选中的那一块不动。
+ */
 export function TabPanel({
   value,
   className,
@@ -305,7 +346,12 @@ export function TabPanel({
       aria-labelledby={toId(context.baseId, "tab", value)}
       hidden={!selected}
       tabIndex={0}
-      className={cn(focusRing, className)}
+      className={cn(
+        focusRing,
+        // 只淡入、不位移：页签本身已经有"让位"的动作
+        selected && context.switched && fadeInFast,
+        className,
+      )}
     >
       {selected ? children : null}
     </div>