@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/loader/Loader.tsx

@@ -0,0 +1,154 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  type ComponentProps,
+  type KeyboardEvent,
+  type ReactNode,
+  type TransitionEvent,
+} from "react";
+import { cn } from "../../lib/cn";
+
+export type LoaderProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 真实进度，0 – 100。不知道就不传：显示不确定进度，不显示数字 */
+  value?: number;
+  /** 进度下方的一行标语 */
+  tagline?: ReactNode;
+  /** 置为 `false` 时遮罩向上滑出，结束后卸载。默认 `true` */
+  open?: boolean;
+  /** 铺满视口并锁住页面（默认）；关掉则铺满所在的定位容器 */
+  fullscreen?: boolean;
+  /** 进度条的可访问名称 */
+  label?: string;
+  /** 滑出结束、已经卸载之后触发 */
+  onExited?: () => void;
+};
+
+/** 滑出的时长，与 `--duration-slower` 一致；过渡事件没来时靠它兜底 */
+const EXIT_MS = 600;
+
+/**
+ * 加载页：近黑底、大号等宽百分比、一行标语、黄色进度条。只用于整页的首次加载。
+ * 不伪造进度；内容就绪后立刻把 `open` 置为 `false`，不要为了播完动画而等待。
+ */
+export function Loader({
+  value,
+  tagline,
+  open = true,
+  fullscreen = true,
+  label = "加载中",
+  onExited,
+  onKeyDown,
+  onTransitionEnd,
+  className,
+  ...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 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;
+    const page = document.documentElement;
+    const previousOverflow = page.style.overflow;
+    const previousFocus = document.activeElement;
+    page.style.overflow = "hidden";
+    rootRef.current?.focus({ preventScroll: true });
+    return () => {
+      page.style.overflow = previousOverflow;
+      if (previousFocus instanceof HTMLElement && previousFocus.isConnected) {
+        previousFocus.focus({ preventScroll: true });
+      }
+    };
+  }, [fullscreen, open]);
+
+  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 走到被盖住的内容里
+    if (fullscreen && open && event.key === "Tab") event.preventDefault();
+  };
+
+  const indeterminate = value === undefined;
+  const current = indeterminate ? 0 : Math.min(Math.max(value, 0), 100);
+
+  return (
+    <div
+      ref={rootRef}
+      tabIndex={-1}
+      {...props}
+      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",
+        fullscreen ? "fixed inset-0 z-(--z-loader)" : "absolute inset-0",
+        "transition-[translate] duration-(--duration-slower) ease-emphasis",
+        open ? "translate-y-0" : "pointer-events-none -translate-y-full",
+        className,
+      )}
+    >
+      <div className="flex flex-col gap-4 p-6 @md:p-10">
+        {!indeterminate && (
+          // 数字与 % 两种字号；确切的值由下面的进度条交给读屏
+          <p
+            aria-hidden="true"
+            className="font-tech leading-none font-medium tabular-nums"
+          >
+            <span className="text-4xl @md:text-5xl">{Math.round(current)}</span>
+            <span className="text-2xl font-normal @md:text-4xl">%</span>
+          </p>
+        )}
+        {tagline !== undefined && (
+          <p className="text-base @md:text-xl">{tagline}</p>
+        )}
+        <div
+          role="progressbar"
+          aria-label={label}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={indeterminate ? undefined : current}
+          className="relative h-1.5 overflow-hidden rounded-sm bg-neutral-800"
+        >
+          {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-0 origin-left bg-action transition-transform duration-(--duration-base) ease-standard"
+              style={{ transform: `scaleX(${current / 100})` }}
+            />
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/loader/index.ts

@@ -0,0 +1 @@
+export { Loader, type LoaderProps } from "./Loader";

package/src/components/marquee/Marquee.tsx

@@ -0,0 +1,96 @@
+import { useEffect, useRef, useState, type ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+
+export type MarqueeProps = ComponentProps<"div"> & {
+  /** 走完一程的秒数，默认 20。内容越长给得越大 */
+  duration?: number;
+  /** 首尾两份内容之间的间隔，任意 CSS 长度，默认 `2rem` */
+  gap?: string;
+  /** 鼠标悬停或焦点落到里面时暂停，默认开 */
+  pauseOnHover?: boolean;
+  /** 由使用方控制的暂停 */
+  paused?: boolean;
+  /** 只在内容放不下时才动；放得下就是一行普通的文字 */
+  overflowOnly?: boolean;
+};
+
+/**
+ * 跑马灯：内容复制一份首尾相接，匀速走到一半后停顿一下再循环。
+ * 用在巨字和过长的单行文字上；系统开启"减少动态效果"时静止在起点。
+ * 纯装饰的巨字给它加 `aria-hidden`。
+ */
+export function Marquee({
+  duration = 20,
+  gap = "2rem",
+  pauseOnHover = true,
+  paused = false,
+  overflowOnly = false,
+  className,
+  children,
+  ...props
+}: MarqueeProps) {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const copyRef = useRef<HTMLDivElement>(null);
+  // 量出来之前先当它放得下：先静止、再动起来，比先动一下再停住自然
+  const [fits, setFits] = useState(true);
+
+  useEffect(() => {
+    const root = rootRef.current;
+    const copy = copyRef.current;
+    if (!overflowOnly || !root || !copy) return;
+
+    const measure = () => {
+      setFits(copy.getBoundingClientRect().width <= root.clientWidth);
+    };
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(root);
+    observer.observe(copy);
+    return () => observer.disconnect();
+  }, [overflowOnly]);
+
+  const moving = !(overflowOnly && fits);
+  // 间隔用外边距：它不算进一份内容自己的宽度，量"放不放得下"时不用再扣掉
+  const copyStyle = moving ? { marginRight: gap } : undefined;
+
+  return (
+    <div
+      ref={rootRef}
+      {...props}
+      data-moving={moving ? "" : undefined}
+      className={cn("group/marquee flex overflow-hidden", className)}
+    >
+      <div
+        className={cn(
+          "flex w-max shrink-0",
+          moving && "animate-marquee motion-reduce:animate-none",
+          moving &&
+            pauseOnHover &&
+            "group-hover/marquee:[animation-play-state:paused] group-focus-within/marquee:[animation-play-state:paused]",
+          paused && "[animation-play-state:paused]",
+        )}
+        style={moving ? { animationDuration: `${duration}s` } : undefined}
+      >
+        <div
+          ref={copyRef}
+          className="flex shrink-0 items-center"
+          style={copyStyle}
+        >
+          {children}
+        </div>
+        {moving && (
+          // 副本只为首尾相接：对读屏隐藏、不可聚焦，减少动态效果时不显示
+          <div
+            aria-hidden="true"
+            inert
+            className="flex shrink-0 items-center motion-reduce:hidden"
+            style={copyStyle}
+          >
+            {children}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/marquee/index.ts

@@ -0,0 +1 @@
+export { Marquee, type MarqueeProps } from "./Marquee";

package/src/components/media-card/MediaCard.tsx

@@ -0,0 +1,139 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { focusRingWithin } from "../../lib/focus-ring";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+import { PlayMark } from "../play-button/PlayButton";
+
+export type MediaCardRatio = "16/9" | "4/3" | "1/1" | "3/4";
+
+export type MediaCardProps = Omit<ComponentProps<"article">, "title"> & {
+  /** 图片、视频封面或任意占位图形，铺满媒体区 */
+  media: ReactNode;
+  /** 媒体区的宽高比 */
+  ratio?: MediaCardRatio;
+  title: ReactNode;
+  /** 微标行里的类目，组件在前面加 `//` */
+  category?: ReactNode;
+  /** 微标行里的日期 */
+  date?: ReactNode;
+  /** 类型标签（如 `PV`），放在图片下方的微标行里，不叠在图上 */
+  tag?: ReactNode;
+  /** 这张卡是一段影像：媒体区左下角多一个播放记号。记号不能点，整卡仍然只有一个链接 */
+  video?: boolean;
+  /** `video` 时加在标题前、读屏才听得到的那个词，默认"视频" */
+  videoLabel?: string;
+  /** 传了就整卡可点：标题是链接，点击范围铺满整张卡 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替标题里的 `<a>`（路由库的链接组件）。传了整卡同样可点 */
+  render?: LinkRender;
+  /** 标题的层级，默认 `h3` */
+  level?: 2 | 3 | 4 | 5 | 6;
+};
+
+const ratioClass: Record<MediaCardRatio, string> = {
+  "16/9": "aspect-video",
+  "4/3": "aspect-4/3",
+  "1/1": "aspect-square",
+  "3/4": "aspect-3/4",
+};
+
+/**
+ * 媒体卡：图片 + 微标行 + 标题。标题和标签都在图片之外。
+ * 整卡只有一个可点击元素，不要在里面再放按钮或链接。
+ */
+export function MediaCard({
+  media,
+  ratio = "16/9",
+  title,
+  category,
+  date,
+  tag,
+  video = false,
+  videoLabel = "视频",
+  href,
+  target,
+  rel,
+  render,
+  level = 3,
+  className,
+  ...props
+}: MediaCardProps) {
+  const Heading = `h${level}` as const;
+  const isLink = href !== undefined || render !== undefined;
+  const hasCategory = category !== undefined && category !== null;
+  const hasDate = date !== undefined && date !== null;
+  const hasMeta = hasCategory || hasDate;
+  // 播放记号是画给眼睛看的；读屏在标题前听到同一件事
+  const heading = video ? (
+    <>
+      <span className="sr-only">{`${videoLabel}：`}</span>
+      {title}
+    </>
+  ) : (
+    title
+  );
+
+  return (
+    <article
+      {...props}
+      className={cn(
+        "group/card relative flex min-w-0 flex-col text-ink",
+        isLink && focusRingWithin,
+        className,
+      )}
+    >
+      <div
+        className={cn(
+          "relative overflow-clip rounded-md bg-surface-muted",
+          "[&>img]:size-full [&>img]:object-cover [&>svg]:size-full [&>video]:size-full [&>video]:object-cover",
+          ratioClass[ratio],
+        )}
+      >
+        {media}
+        {video && (
+          // 内缩 8px：不贴着圆角，也不挡底边那条悬停线
+          <PlayMark className="pointer-events-none absolute bottom-2 left-2" />
+        )}
+        {isLink && (
+          // 悬停：一条底边强调线从左充出。不放大、不上浮
+          <span
+            aria-hidden="true"
+            className="pointer-events-none absolute inset-x-0 bottom-0 h-1 origin-left scale-x-0 bg-action transition-transform duration-(--duration-base) ease-standard group-hover/card:scale-x-100 group-has-focus-visible/card:scale-x-100"
+          />
+        )}
+      </div>
+      {(tag !== undefined || hasMeta) && (
+        // 行高按类型标签的高度留足：一排卡片里有的带标签、有的不带，标题仍然对齐
+        <p className="mt-3 flex min-h-5 flex-wrap items-center gap-x-2 gap-y-1 text-xs text-ink-secondary">
+          {tag}
+          {hasMeta && (
+            <span className="font-tech">
+              <span aria-hidden="true">{"// "}</span>
+              {category}
+              {hasCategory && hasDate && "　"}
+              {date}
+            </span>
+          )}
+        </p>
+      )}
+      <Heading className="mt-1.5 text-base font-medium wrap-anywhere">
+        {isLink ? (
+          <LinkElement
+            render={render}
+            href={href}
+            target={target}
+            rel={rel}
+            // 焦点环画在整张卡上；点击范围用伪元素铺满整张卡
+            className="outline-none after:absolute after:inset-0 after:content-['']"
+          >
+            {heading}
+          </LinkElement>
+        ) : (
+          heading
+        )}
+      </Heading>
+    </article>
+  );
+}

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

@@ -0,0 +1,5 @@
+export {
+  MediaCard,
+  type MediaCardProps,
+  type MediaCardRatio,
+} from "./MediaCard";

package/src/components/nav-action/NavAction.tsx

@@ -0,0 +1,142 @@
+import {
+  createContext,
+  useContext,
+  type ComponentProps,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { TriangleRight } from "../../icons/TriangleRight";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+
+export type NavActionLayout = "inline" | "block" | "stacked";
+
+/** 侧轨和全屏菜单用它告诉里面的主行动块该怎么摆。不对外导出 */
+export const NavActionContext = createContext<NavActionLayout | null>(null);
+
+type OwnProps = {
+  /** 换掉默认的实心三角 */
+  icon?: ReactNode;
+  /**
+   * 摆法。放在侧轨、全屏菜单里时由它们决定，一般不用传：
+   * - `inline` 40px 高的横块，顶栏里；
+   * - `block` 48px 高的通宽横条，展开的侧轨和全屏菜单的底部；
+   * - `stacked` 48px 宽、至少 96px 高的竖块，文字竖排，收起的侧轨里。
+   */
+  layout?: NavActionLayout;
+  /** 传了就渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  disabled?: boolean;
+  children: ReactNode;
+};
+
+export type NavActionProps = OwnProps &
+  Omit<ComponentProps<"button">, keyof OwnProps | "type">;
+
+const layoutClass: Record<NavActionLayout, string> = {
+  inline: "inline-flex h-10 items-center gap-2.5 px-4 text-sm",
+  block: "flex h-12 w-full items-center gap-3 px-4 text-base",
+  // 竖排的文字长了就往下长：96px 是最小高度
+  stacked:
+    "flex min-h-24 w-12 flex-col items-center justify-center gap-2 py-3 text-sm",
+};
+
+/**
+ * 主行动块：整个产品最主要的那一个去处（"前往控制台"）。
+ * 反转的一整块，悬停时变成信号黄。侧轨、顶栏、全屏菜单的底部放的都是它；
+ * 一个界面里只放一个。
+ */
+export function NavAction({
+  icon,
+  layout: layoutProp,
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  disabled = false,
+  className,
+  children,
+  ...props
+}: NavActionProps) {
+  const inherited = useContext(NavActionContext);
+  const layout = layoutProp ?? inherited ?? "inline";
+  const stacked = layout === "stacked";
+
+  const classes = cn(
+    "shrink-0 font-medium whitespace-nowrap select-none",
+    "transition-colors duration-(--duration-fast) ease-standard",
+    focusRing,
+    layoutClass[layout],
+    disabled
+      ? "cursor-not-allowed bg-disabled text-on-disabled"
+      : "bg-surface-inverse text-ink-inverse hover:bg-action hover:text-on-action active:bg-action-pressed active:text-on-action",
+    className,
+  );
+
+  const content = (
+    <>
+      <span
+        aria-hidden="true"
+        className="flex shrink-0 items-center justify-center [&_svg]:size-3"
+      >
+        {icon ?? <TriangleRight />}
+      </span>
+      {/* 图标与文字之间一条半透明的细线，跟着字色走 */}
+      <span
+        aria-hidden="true"
+        className={cn(
+          "shrink-0 bg-current opacity-30",
+          stacked ? "h-px w-4" : "h-4 w-px",
+        )}
+      />
+      <span
+        className={cn(
+          stacked
+            ? "tracking-label [writing-mode:vertical-rl]"
+            : "min-w-0 truncate",
+        )}
+      >
+        {children}
+      </span>
+    </>
+  );
+
+  if (href !== undefined || render !== undefined) {
+    return (
+      <LinkElement
+        render={render}
+        // 禁用的链接去掉 href，保留 link 角色，让读屏仍能读出"不可用"
+        href={disabled ? undefined : href}
+        role={disabled ? "link" : undefined}
+        aria-disabled={disabled || undefined}
+        target={target}
+        rel={rel}
+        onClick={disabled ? (event) => event.preventDefault() : onClick}
+        data-layout={layout}
+        className={classes}
+      >
+        {content}
+      </LinkElement>
+    );
+  }
+
+  return (
+    <button
+      {...props}
+      type="button"
+      disabled={disabled}
+      onClick={onClick}
+      data-layout={layout}
+      className={classes}
+    >
+      {content}
+    </button>
+  );
+}

package/src/components/nav-action/index.ts

@@ -0,0 +1,5 @@
+export {
+  NavAction,
+  type NavActionLayout,
+  type NavActionProps,
+} from "./NavAction";