@endfield-ui/react 0.1.0 → 0.3.0

package/src/components/carousel/Carousel.tsx

@@ -2,10 +2,7 @@ import {
   Children,
   createContext,
   isValidElement,
-  useCallback,
   useContext,
-  useEffect,
-  useRef,
   type ComponentProps,
   type KeyboardEvent,
   type ReactNode,
@@ -17,6 +14,7 @@ import { cn } from "../../lib/cn";
 import { focusRing } from "../../lib/focus-ring";
 import { DashIndicator } from "../dash-indicator/DashIndicator";
 import { IconButton } from "../icon-button/IconButton";
+import { useSnapTrack } from "./snap-track";
 
 export type CarouselRatio = "16/9" | "4/3" | "1/1" | "3/4" | "21/9";
 
@@ -58,9 +56,6 @@ export type CarouselProps = Omit<
 
 type SlideLike = { title?: ReactNode; description?: ReactNode };
 
-/** 滚动停下之后多久算"停稳了"。没有 scrollend 事件的浏览器靠它 */
-const SETTLE_MS = 120;
-
 /**
  * 媒体轮播：一次看一张的大幅媒体，前后翻。不自动播放。
  * 轨道是原生的横向滚动加滚动吸附，触屏滑动是浏览器自带的。
@@ -91,11 +86,12 @@ export function Carousel({
     onChange: onIndexChange,
   });
   const index = Math.min(Math.max(rawIndex, 0), last);
-  const trackRef = useRef<HTMLDivElement>(null);
-  const settleTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
-  // 给不跟着渲染重建的回调（尺寸变化）读最新的下标
-  const indexRef = useRef(index);
-  indexRef.current = index;
+  // 下标和滚动位置互相跟的那一段，和图片查看共用
+  const { trackRef, onScroll } = useSnapTrack({
+    index,
+    count,
+    onSettle: setIndex,
+  });
 
   const go = (next: number) => {
     if (count === 0) return;
@@ -114,42 +110,6 @@ export function Carousel({
     }
   };
 
-  // 下标变了：滚过去。已经在那儿（用户自己滑过去的）就不动
-  useEffect(() => {
-    const track = trackRef.current;
-    if (!track || track.clientWidth === 0) return;
-    if (Math.round(track.scrollLeft / track.clientWidth) === index) return;
-    track.scrollTo?.({ left: index * track.clientWidth, behavior: "smooth" });
-  }, [index]);
-
-  // 宽度变了：轨道的滚动位置是像素，会错开，重新对到当前这一张（不要动画）
-  useEffect(() => {
-    const track = trackRef.current;
-    if (!track || typeof ResizeObserver === "undefined") return;
-    const observer = new ResizeObserver(() => {
-      track.scrollTo?.({
-        left: indexRef.current * track.clientWidth,
-        behavior: "instant",
-      });
-    });
-    observer.observe(track);
-    return () => observer.disconnect();
-  }, []);
-
-  useEffect(() => () => clearTimeout(settleTimer.current), []);
-
-  // 用户自己滑：等滚动停稳，由停下的位置定下标。滚动途中不改——
-  // 翻页钮触发的滚动会路过中间那几张
-  const onScroll = useCallback(() => {
-    clearTimeout(settleTimer.current);
-    settleTimer.current = setTimeout(() => {
-      const track = trackRef.current;
-      if (!track || track.clientWidth === 0) return;
-      const stopped = Math.round(track.scrollLeft / track.clientWidth);
-      setIndex(Math.min(Math.max(stopped, 0), last));
-    }, SETTLE_MS);
-  }, [setIndex, last]);
-
   const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {
     const next = {
       ArrowLeft: index - 1,

package/src/components/carousel/snap-track.ts

@@ -0,0 +1,74 @@
+import { useCallback, useEffect, useRef } from "react";
+
+/** 滚动停下之后多久算"停稳了"。没有 scrollend 事件的浏览器靠它 */
+const SETTLE_MS = 120;
+
+type SnapTrackOptions = {
+  /** 现在是第几张，从 0 起 */
+  index: number;
+  /** 一共几张 */
+  count: number;
+  /** 用户自己滑、停稳在了第几张 */
+  onSettle: (index: number) => void;
+};
+
+/**
+ * 一条横向滚动加滚动吸附的轨道，每一张和轨道一样宽。下标和滚动位置互相跟：
+ * 下标变了轨道滚过去；用户自己滑的时候反过来，等滚动停稳，由停下的位置定下标。
+ * 手势、惯性都是浏览器的。媒体轮播和图片查看共用，不对外导出。
+ *
+ * 把 `trackRef` 和 `onScroll` 交给那个滚动容器。
+ */
+export function useSnapTrack({ index, count, onSettle }: SnapTrackOptions) {
+  const trackRef = useRef<HTMLDivElement>(null);
+  const settleTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const last = Math.max(0, count - 1);
+  // 给不跟着渲染重建的回调（尺寸变化）读最新的下标
+  const indexRef = useRef(index);
+  indexRef.current = index;
+  const placed = useRef(false);
+
+  // 下标变了：滚过去。已经在那儿（用户自己滑过去的）就不动。
+  // 刚挂上的那一次直接到位：从第一张一路滑到第三张不是谁想看的
+  useEffect(() => {
+    const first = !placed.current;
+    placed.current = true;
+    const track = trackRef.current;
+    if (!track || track.clientWidth === 0) return;
+    if (Math.round(track.scrollLeft / track.clientWidth) === index) return;
+    track.scrollTo?.({
+      left: index * track.clientWidth,
+      behavior: first ? "instant" : "smooth",
+    });
+  }, [index]);
+
+  // 宽度变了：轨道的滚动位置是像素，会错开，重新对到当前这一张（不要动画）
+  useEffect(() => {
+    const track = trackRef.current;
+    if (!track || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      track.scrollTo?.({
+        left: indexRef.current * track.clientWidth,
+        behavior: "instant",
+      });
+    });
+    observer.observe(track);
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => () => clearTimeout(settleTimer.current), []);
+
+  // 用户自己滑：等滚动停稳，由停下的位置定下标。滚动途中不改——
+  // 翻页钮触发的滚动会路过中间那几张
+  const onScroll = useCallback(() => {
+    clearTimeout(settleTimer.current);
+    settleTimer.current = setTimeout(() => {
+      const track = trackRef.current;
+      if (!track || track.clientWidth === 0) return;
+      const stopped = Math.round(track.scrollLeft / track.clientWidth);
+      onSettle(Math.min(Math.max(stopped, 0), last));
+    }, SETTLE_MS);
+  }, [onSettle, last]);
+
+  return { trackRef, onScroll };
+}

package/src/components/checkbox/choice-style.ts

@@ -25,6 +25,9 @@ export const choiceBox =
 export const choiceFrame =
   "relative inline-flex size-5 items-center justify-center";
 
-/** 压在方格 / 圆正中的记号，默认透明，由 peer 的状态点亮 */
+/**
+ * 压在方格 / 圆正中的记号，默认透明，由 peer 的状态点亮。
+ * 淡入淡出，和方格换底色的那一下同时走——底色有过渡而记号硬切，看起来是两件事
+ */
 export const choiceMark =
-  "pointer-events-none absolute inset-0 m-auto text-accent-ink-inverse opacity-0 peer-disabled:text-ink-disabled";
+  "pointer-events-none absolute inset-0 m-auto text-accent-ink-inverse opacity-0 transition-opacity duration-(--duration-fast) ease-standard peer-disabled:text-ink-disabled";

package/src/components/corner-brackets/CornerBrackets.tsx

@@ -20,6 +20,7 @@ const sizeClass: Record<CornerBracketsSize, string> = {
  * 用于矩阵里的单选（物品格、名册卡、图鉴）；列表行用左缘色条，页签用底色，都不用它。
  *
  * 括号画在盒子之外 4px：它所在的容器不能贴着盒子裁切。
+ * 出现时八段短线从角的顶点伸到满长（200ms），消失是直接消失。
  * 括号只是给眼睛看的，选中态另外要有 `aria-selected` / `aria-pressed`。
  */
 export function CornerBrackets({
@@ -34,7 +35,7 @@ export function CornerBrackets({
       data-visible={visible ? "" : undefined}
       className={cn(
         "relative",
-        visible && "corner-brackets",
+        visible && "corner-brackets after:animate-bracket-in",
         sizeClass[size],
         className,
       )}

package/src/components/dialog/Dialog.tsx

@@ -116,8 +116,10 @@ export function Dialog({
             className={cn(
               overlaySurface,
               "relative flex max-h-full min-h-0 w-full flex-col",
-              "transition-[scale,opacity] duration-(--duration-base) ease-exit",
-              "data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+              // 进场：淡入（200ms），同时从下面升上来 8px（300ms）。退场只淡出——位移只写在起点上。
+              // 不放大：这套语言里没有东西是"变大着出来"的
+              "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:translate-y-(--motion-shift-lg) data-starting-style:opacity-0",
               sizeClass[size],
               className,
             )}

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

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

@@ -348,7 +348,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",
             )}
           />
         )}

package/src/components/hover-card/HoverCard.tsx

@@ -0,0 +1,101 @@
+import { PreviewCard as BasePreviewCard } from "@base-ui/react/preview-card";
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { cn } from "../../lib/cn";
+import {
+  popoverDescription,
+  popoverPanel,
+  popoverTitle,
+} from "../popover/panel-style";
+
+export type HoverCardSide = "top" | "bottom" | "left" | "right";
+export type HoverCardAlign = "start" | "center" | "end";
+
+export type HoverCardProps = Omit<
+  ComponentProps<"div">,
+  "title" | "children" | "className" | "style"
+> & {
+  /** 触发元素：一个链接（`<a>`、带 `href` 的按钮、路由库的链接组件） */
+  trigger: ReactElement<Record<string, unknown>>;
+  /** 卡片里的标题 */
+  title?: ReactNode;
+  /** 标题下的一行说明 */
+  description?: ReactNode;
+  /** 卡片出现在链接的哪一侧，放不下时自动翻到对面。默认 `bottom` */
+  side?: HoverCardSide;
+  /** 和链接的哪一边对齐。默认 `start` */
+  align?: HoverCardAlign;
+  /** 指针停住多久后出现，毫秒，默认 600。键盘聚焦时同样要等 */
+  delay?: number;
+  /** 指针离开多久后消失，毫秒，默认 300：够把指针移进卡片里 */
+  closeDelay?: number;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 给卡片 */
+  className?: string;
+  children?: ReactNode;
+};
+
+/**
+ * 悬浮卡：指针停在一个链接上时，在旁边预览它的去处。面板和气泡卡片是同一块。
+ *
+ * 触屏上不出现，读屏也不会读到它：里面只放"点进去也看得到"的内容，
+ * 不放只有这里才有的信息和操作。要操作的用 `Popover`，一句说明用 `Tooltip`。
+ */
+export function HoverCard({
+  trigger,
+  title,
+  description,
+  side = "bottom",
+  align = "start",
+  delay = 600,
+  closeDelay = 300,
+  open,
+  defaultOpen,
+  onOpenChange,
+  className,
+  children,
+  ...props
+}: HoverCardProps) {
+  const { anchorRef, portalRef } = usePortalScope();
+
+  return (
+    <BasePreviewCard.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange && ((next) => onOpenChange(next))}
+    >
+      <BasePreviewCard.Trigger
+        ref={anchorRef}
+        render={trigger}
+        delay={delay}
+        closeDelay={closeDelay}
+      />
+      <BasePreviewCard.Portal ref={portalRef}>
+        <BasePreviewCard.Positioner
+          side={side}
+          align={align}
+          sideOffset={4}
+          className="z-(--z-overlay) outline-none"
+        >
+          <BasePreviewCard.Popup
+            {...props}
+            data-hover-card=""
+            className={cn(popoverPanel, className)}
+          >
+            {(title || description) && (
+              <div className="flex flex-col gap-1">
+                {title && <p className={popoverTitle}>{title}</p>}
+                {description && (
+                  <p className={popoverDescription}>{description}</p>
+                )}
+              </div>
+            )}
+            {children}
+          </BasePreviewCard.Popup>
+        </BasePreviewCard.Positioner>
+      </BasePreviewCard.Portal>
+    </BasePreviewCard.Root>
+  );
+}

package/src/components/hover-card/index.ts

@@ -0,0 +1,6 @@
+export {
+  HoverCard,
+  type HoverCardAlign,
+  type HoverCardProps,
+  type HoverCardSide,
+} from "./HoverCard";