@endfield-ui/react 0.2.0 → 0.3.0

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/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/nav-menu/NavMenu.tsx

@@ -85,6 +85,7 @@ export function NavMenu({
           initialFocus={firstFocusableIn(bodyRef)}
           className={cn(
             "fixed inset-0 z-(--z-overlay) flex flex-col overflow-hidden bg-surface text-ink outline-none",
+            // 整层淡入；里面的栏目另有自己的入场（见 itemEnter）
             "transition-opacity duration-(--duration-fast) ease-standard",
             "data-ending-style:opacity-0 data-starting-style:opacity-0",
             className,
@@ -155,6 +156,17 @@ export function NavMenu({
   );
 }
 
+/*
+ * 栏目入场：逐条从左滑入 8px。第一项等层淡入过半（100ms），之后每项晚 50ms，
+ * 第六项起一起到——从第一项动到最后一项停下 550ms。
+ * 只动 <li> 的位置和透明度：焦点一打开就在第一项上，键盘不用等它
+ */
+const itemEnter = [
+  "animate-shift-in [--shift-x:calc(var(--motion-shift-lg)*-1)]",
+  "[animation-delay:100ms] nth-2:[animation-delay:150ms] nth-3:[animation-delay:200ms]",
+  "nth-4:[animation-delay:250ms] nth-5:[animation-delay:300ms] nth-[n+6]:[animation-delay:350ms]",
+].join(" ");
+
 type ItemOwnProps = {
   /** 图标，后面跟一条竖向的分隔线 */
   icon?: ReactNode;
@@ -188,6 +200,7 @@ export function NavMenuItem({
   rel,
   render,
   onClick,
+  className,
   children,
   ...props
 }: NavMenuItemProps) {
@@ -256,7 +269,7 @@ export function NavMenuItem({
   );
 
   return (
-    <li {...props}>
+    <li {...props} className={cn(itemEnter, className)}>
       {isLink ? (
         <LinkElement
           render={render}

package/src/components/otp-input/OtpInput.tsx

@@ -129,8 +129,11 @@ export function OtpInput({
   const groupLabel = ownLabel ?? fieldContext?.labelId;
 
   const slotClass = cn(
-    "min-w-0 shrink text-center font-tech font-medium tabular-nums text-ink caret-ink",
+    // 字色：空格是透明的，填上（基元给的 data-filled）才有颜色。下面那条颜色的过渡
+    // 本来是给边线的，字色跟着它走——所以填进去的那一位是淡入的。光标另有自己的颜色
+    "min-w-0 shrink text-center font-tech font-medium tabular-nums text-transparent caret-ink",
     "transition-colors duration-(--duration-fast) ease-standard",
+    disabled ? "data-filled:text-ink-disabled" : "data-filled:text-ink",
     focusRing,
     slotSize[size],
     slotFrame[variant],
@@ -139,7 +142,7 @@ export function OtpInput({
         "border-transparent bg-transparent"
       : slotFill[variant],
     disabled
-      ? "cursor-not-allowed border-line text-ink-disabled"
+      ? "cursor-not-allowed border-line"
       : invalid
         ? "border-danger"
         : !readOnly &&

package/src/components/slider/Slider.tsx

@@ -79,10 +79,13 @@ const markLeft = (ratio: number) =>
 
 const thumb = [
   "relative h-5 w-3 bg-surface-inverse shadow-[0_0_0_2px_var(--ef-surface)]",
+  // 按键、外部改值时滑过去。拖动中位置必须贴着指针，所以那时候关掉——
+  // 点轨道也算：基元在按下的那一刻就开始拖了
+  "transition-[inset-inline-start] duration-(--duration-fast) ease-standard data-dragging:transition-none",
   // 触屏的点击区补到 40 × 40px
   "before:absolute before:-inset-x-3.5 before:-inset-y-2.5 before:content-['']",
   // 按住时正中亮一条强调色细线
-  "after:absolute after:inset-y-1 after:left-1/2 after:w-0.5 after:-translate-x-1/2 after:bg-accent-ink-inverse after:opacity-0 after:content-[''] data-dragging:after:opacity-100",
+  "after:absolute after:inset-y-1 after:left-1/2 after:w-0.5 after:-translate-x-1/2 after:bg-accent-ink-inverse after:opacity-0 after:transition-opacity after:duration-(--duration-fast) after:ease-standard after:content-[''] data-dragging:after:opacity-100",
   // 菱形方案：滑块是一个 14px 的菱形，按住时中间亮一个小方块
   "choice-diamond:size-3.5 choice-diamond:rotate-45 choice-diamond:after:inset-1 choice-diamond:after:w-auto choice-diamond:after:translate-x-0",
   "data-disabled:bg-ink-disabled",
@@ -165,7 +168,8 @@ export function Slider(props: SliderProps) {
           )}
         >
           <BaseSlider.Track className="h-1 w-full bg-line">
-            <BaseSlider.Indicator className="bg-ink data-disabled:bg-ink-disabled" />
+            {/* 走过的一段跟着滑块头走：范围滑块两头都会动 */}
+            <BaseSlider.Indicator className="bg-ink transition-[inset-inline-start,width] duration-(--duration-fast) ease-standard data-disabled:bg-ink-disabled data-dragging:transition-none" />
             {(range ? [0, 1] : [0]).map((index) => (
               <BaseSlider.Thumb
                 key={index}

package/src/components/steps/Steps.tsx

@@ -243,6 +243,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 +257,19 @@ 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",
+            "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/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/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/lib/README.md

@@ -9,6 +9,7 @@
 | `merge-refs.ts` | `mergeRefs()`：组件自己要用节点、同时还得把它交给使用方时，把几个 ref 合成一个 |
 | `defined.ts` | `defined()`：去掉值是 `undefined` 的属性。把控件的属性合并到使用方给的元素上（`render`）之前用，免得把那个元素自己写的盖掉 |
 | `decor.ts` | `decor`：装饰层共用的类 |
+| `motion.ts` | `enterFromSide`：浮层面板进场的方向位移——按基元给的 `data-side`，起点往触发元素那一侧偏 `--motion-shift`。见 [动效](../../../../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

@@ -24,6 +24,8 @@ const twMerge = extendTailwindMerge({
         "turn-in",
         "fade-in",
         "indeterminate",
+        "bracket-in",
+        "shift-in",
       ],
     },
   },

package/src/lib/motion.ts

@@ -0,0 +1,15 @@
+/**
+ * 浮层从触发它的那一侧来：进场的起点往触发处偏 `--motion-shift`，走完归位。
+ * 用在基元的浮层面板上——它们带着 `data-side`（面板在触发元素的哪一侧）。
+ *
+ * 位移只写在 `data-starting-style` 上：退场不走位移，只淡出。
+ * 用的地方自己给 `translate` 加过渡。`inline-start` / `inline-end` 按从左往右的排版算。
+ */
+export const enterFromSide = [
+  "data-starting-style:data-[side=bottom]:-translate-y-(--motion-shift)",
+  "data-starting-style:data-[side=top]:translate-y-(--motion-shift)",
+  "data-starting-style:data-[side=right]:-translate-x-(--motion-shift)",
+  "data-starting-style:data-[side=left]:translate-x-(--motion-shift)",
+  "data-starting-style:data-[side=inline-end]:-translate-x-(--motion-shift)",
+  "data-starting-style:data-[side=inline-start]:translate-x-(--motion-shift)",
+].join(" ");

package/src/styles/theme.css

@@ -336,6 +336,13 @@
   --duration-slow: 400ms;
   --duration-slower: 600ms;
 
+  /*
+   * 进场的方向位移：浮层从触发它的那一侧来。只是提示方向，不是滑行。
+   * 大的那一档给大面积的和贴着视口边缘出来的（全屏菜单的栏目、轻提示）
+   */
+  --motion-shift: 4px;
+  --motion-shift-lg: 8px;
+
   /* —— 母题尺寸 —— */
   --cut-sm: 6px;
   --cut-md: 10px;
@@ -368,6 +375,8 @@
   --animate-fade-in: ef-fade-in 300ms ease-out both;
   --animate-indeterminate: ef-indeterminate 1.2s linear infinite alternate;
   --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;
 
   /* 三次短促闪烁后点亮（官网实测的关键帧节奏） */
   @keyframes ef-flicker {
@@ -507,6 +516,37 @@
       opacity: 0.6;
     }
   }
+
+  /*
+   * 角括号落位：八段短线各自从角的顶点伸到满长。写成 after:animate-bracket-in，
+   * 和 corner-brackets 一起用——八层的顺序（横、竖交替）跟着 utilities.css 里那八层背景走。
+   * 只写起点：终点就是括号自己的尺寸。只动背景的尺寸，括号不会比平时多占一点地方
+   */
+  @keyframes ef-bracket-in {
+    from {
+      background-size:
+        0 var(--_w),
+        var(--_w) 0,
+        0 var(--_w),
+        var(--_w) 0,
+        0 var(--_w),
+        var(--_w) 0,
+        0 var(--_w),
+        var(--_w) 0;
+    }
+  }
+
+  /*
+   * 位移入场：从偏着的地方淡入归位。往哪边偏、偏多少由用的地方给
+   * （--shift-x / --shift-y，量用 --motion-shift 那两档），不给就只是淡入。
+   * 只写起点：终点就是元素自己的样子
+   */
+  @keyframes ef-shift-in {
+    from {
+      opacity: 0;
+      translate: var(--shift-x, 0) var(--shift-y, 0);
+    }
+  }
 }
 
 /* ------------------------------------------------------------------ */
@@ -563,6 +603,9 @@
     animation-duration: 0.01ms !important;
     animation-iteration-count: 1 !important;
     transition-duration: 0.01ms !important;
+    /* 延迟也归零：不然错开的入场会变成一项一项蹦出来 */
+    animation-delay: 0s !important;
+    transition-delay: 0s !important;
     scroll-behavior: auto !important;
   }
 }

package/src/styles/utilities.css

@@ -121,7 +121,8 @@
 /* ------------------------------------------------------------------ */
 /* 角括号：四角各一个 L 形短线，用 ::after 的背景画，不占用 outline。    */
 /* 宿主要自己定位（relative 或 absolute）；括号画在宿主之外，            */
-/* 所以宿主和它的裁切祖先之间要留出 --bracket-offset 的空隙             */
+/* 所以宿主和它的裁切祖先之间要留出 --bracket-offset 的空隙。            */
+/* 要它出现时"落位"，再加 after:animate-bracket-in（关键帧在 theme.css）  */
 /* ------------------------------------------------------------------ */
 
 @utility corner-brackets {