@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/texture/Texture.tsx

@@ -0,0 +1,45 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+import { decor } from "../../lib/decor";
+
+export type TextureVariant = "dots" | "grid" | "contour";
+
+export type TextureProps = Omit<ComponentProps<"div">, "children"> & {
+  /**
+   * - `dots` 点阵，印刷网点：弹窗、卡片、面板的底，默认；
+   * - `grid` 工程网格，图纸与坐标：图解、工作台的背景；
+   * - `contour` 等高线，测绘与地形：偏在一角，被容器的边缘截断。
+   */
+  variant?: TextureVariant;
+};
+
+const variantClass: Record<TextureVariant, string> = {
+  dots: "dot-grid",
+  grid: "blueprint-grid",
+  contour: "contour",
+};
+
+/**
+ * 铺在内容之下的一层底纹，纯装饰。默认铺满最近的定位祖先：
+ * 父容器要自己写 `relative`，需要裁切时再加 `overflow-clip`。
+ * 一个视口选一种；文字下面垫一层实色，别让底纹穿过正文。
+ */
+export function Texture({
+  variant = "dots",
+  className,
+  ...props
+}: TextureProps) {
+  return (
+    <div
+      {...props}
+      aria-hidden="true"
+      data-variant={variant}
+      className={cn(
+        decor,
+        "absolute inset-0",
+        variantClass[variant],
+        className,
+      )}
+    />
+  );
+}

package/src/components/texture/index.ts

@@ -0,0 +1 @@
+export { Texture, type TextureProps, type TextureVariant } from "./Texture";

package/src/components/tick-ring/TickRing.tsx

@@ -0,0 +1,77 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { decor } from "../../lib/decor";
+
+export type TickRingProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 直径：数字是像素，也可以传 `"100%"` 这类长度（高度跟着宽度走）。默认 240 */
+  size?: number | string;
+  /** 外圈刻度的根数，默认 40 */
+  ticks?: number;
+  /** 整体缓慢匀速旋转（60 秒一圈） */
+  spin?: boolean;
+  /** 被圆环围住的主体，居中 */
+  children?: ReactNode;
+};
+
+/**
+ * 刻度圆环：细内环 + 一圈刻度 + 两段不对称的粗弧，围住一个主体（模型、头像、地图焦点）。
+ * 纯装饰，只用在展示性的画面上。颜色继承文字：浅色底上是墨与灰，
+ * 压在深色画面上时给它加 `data-theme="dark"`。
+ *
+ * 它不承载数据；表示进度用 `ProgressRing`。
+ */
+export function TickRing({
+  size = 240,
+  ticks = 40,
+  spin = false,
+  className,
+  style,
+  children,
+  ...props
+}: TickRingProps) {
+  const count = Math.max(1, Math.round(ticks));
+
+  return (
+    <div
+      {...props}
+      className={cn(
+        "relative inline-grid aspect-square shrink-0 place-items-center text-ink",
+        className,
+      )}
+      style={{ width: size, ...style }}
+    >
+      <svg
+        aria-hidden="true"
+        focusable="false"
+        viewBox="0 0 240 240"
+        fill="none"
+        stroke="currentColor"
+        className={cn(
+          decor,
+          "absolute inset-0 size-full",
+          spin && "animate-spin-slow",
+        )}
+      >
+        <circle cx="120" cy="120" r="96" strokeOpacity={0.35} />
+        {/* pathLength 把周长归一化成"每根刻度 10 个单位"：短线 1.5、间隔 8.5 */}
+        <circle
+          data-ticks={count}
+          cx="120"
+          cy="120"
+          r="114"
+          strokeOpacity={0.5}
+          strokeWidth={8}
+          pathLength={count * 10}
+          strokeDasharray="1.5 8.5"
+        />
+        {/* 两段弧一长一短、不对称摆放：等长对称的两段会被看成加载指示 */}
+        <path
+          d="M120 6A114 114 0 0 1 218.7 63M81 227.1A114 114 0 0 1 25.5 183.7"
+          strokeOpacity={0.55}
+          strokeWidth={5}
+        />
+      </svg>
+      {children !== undefined && <div className="relative">{children}</div>}
+    </div>
+  );
+}

package/src/components/tick-ring/index.ts

@@ -0,0 +1 @@
+export { TickRing, type TickRingProps } from "./TickRing";

package/src/components/timeline/Timeline.tsx

@@ -0,0 +1,84 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type TimelineProps = ComponentProps<"ol">;
+
+/** 竖向时间线的容器，里面只放 `TimelineItem`，按时间顺序排。 */
+export function Timeline({ className, ...props }: TimelineProps) {
+  return <ol {...props} className={cn("text-ink", className)} />;
+}
+
+export type TimelineStatus = "past" | "current" | "upcoming";
+
+export type TimelineItemProps = Omit<ComponentProps<"li">, "title"> & {
+  /**
+   * - `past` 已过：实心菱形，默认；
+   * - `current` 当前：黄色菱形，标题加粗；
+   * - `upcoming` 未到：空心菱形，文字降为次级色。
+   */
+  status?: TimelineStatus;
+  /** 节点旁的日期或时间，等宽小字 */
+  date?: ReactNode;
+  title: ReactNode;
+  /** 标题下的说明 */
+  children?: ReactNode;
+};
+
+const nodeClass: Record<TimelineStatus, string> = {
+  past: "bg-ink",
+  // 描一圈最细的线（1px），颜色跟着文字走：亮色下是墨色，暗色下是近白
+  current: "border border-ink bg-action",
+  upcoming: "border-2 border-ink-tertiary",
+};
+
+const titleClass: Record<TimelineStatus, string> = {
+  past: "text-ink",
+  current: "font-bold text-ink",
+  upcoming: "text-ink-secondary",
+};
+
+export function TimelineItem({
+  status = "past",
+  date,
+  title,
+  className,
+  children,
+  ...props
+}: TimelineItemProps) {
+  const hasDate = date !== undefined && date !== null && date !== false;
+
+  return (
+    <li
+      {...props}
+      data-status={status}
+      aria-current={status === "current" ? "step" : undefined}
+      className={cn("group/item flex gap-3", className)}
+    >
+      {/* 字号跟第一行文字走，节点才能对齐它 */}
+      <span
+        aria-hidden="true"
+        className={cn(
+          "flex shrink-0 flex-col items-center",
+          hasDate ? "text-xs" : "text-base",
+        )}
+      >
+        <span className="flex h-[1lh] min-h-4 w-4 items-center justify-center">
+          <span className={cn("size-[11px] rotate-45", nodeClass[status])} />
+        </span>
+        {/* 轴只画在节点之间，不从节点后面穿过，空心菱形才是空的 */}
+        <span className="w-0.5 flex-1 bg-line-strong group-last/item:hidden" />
+      </span>
+      <div className="min-w-0 flex-1 pb-6 group-last/item:pb-0">
+        {hasDate && (
+          <div className="font-tech text-xs text-ink-secondary tabular-nums">
+            {date}
+          </div>
+        )}
+        <div className={cn("wrap-anywhere", titleClass[status])}>{title}</div>
+        {children !== undefined && (
+          <div className="mt-1 text-sm text-ink-secondary">{children}</div>
+        )}
+      </div>
+    </li>
+  );
+}

package/src/components/timeline/index.ts

@@ -0,0 +1,7 @@
+export {
+  Timeline,
+  TimelineItem,
+  type TimelineItemProps,
+  type TimelineProps,
+  type TimelineStatus,
+} from "./Timeline";

package/src/components/toast/Toast.tsx

@@ -0,0 +1,257 @@
+import { Toast as BaseToast } from "@base-ui/react/toast";
+import {
+  createContext,
+  isValidElement,
+  useContext,
+  useMemo,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+import { Close } from "../../icons/Close";
+import type { IconProps } from "../../icons/createIcon";
+import { StatusDanger } from "../../icons/StatusDanger";
+import { StatusInfo } from "../../icons/StatusInfo";
+import { StatusSuccess } from "../../icons/StatusSuccess";
+import { StatusWarning } from "../../icons/StatusWarning";
+import { cn } from "../../lib/cn";
+import { focusRing, focusRingInset } from "../../lib/focus-ring";
+
+export type ToastTone = "neutral" | "info" | "success" | "warning" | "danger";
+export type ToastPlacement = "bottom" | "center";
+
+export type ToastAction = {
+  label: ReactNode;
+  /** 点了之后这条提示随即关掉 */
+  onClick: () => void;
+};
+
+export type ToastOptions = {
+  /** 一句话 */
+  message: ReactNode;
+  /** 文字前的小图形，区分成功与失败。底色不变。默认 `neutral`：没有图形 */
+  tone?: ToastTone;
+  /** 一个操作，比如"撤销"。带操作的提示多停一会儿，并出现关闭图标 */
+  action?: ToastAction;
+  /** 停留多久，毫秒。`0` 是一直留着，直到被关掉或被下一条替换 */
+  duration?: number;
+};
+
+export type ToastApi = {
+  /** 弹出一条，返回它的 id。上一条还在的话会被它替换 */
+  (input: ReactNode | ToastOptions): string;
+  /** 关掉指定的一条；不传 id 就关掉当前这条 */
+  dismiss: (id?: string) => void;
+};
+
+type ToastData = {
+  tone: ToastTone;
+  dismissible: boolean;
+};
+
+/* 带操作的提示默认停留的时间：要留出读完再去点的工夫 */
+const ACTION_DURATION = 8000;
+
+const ToastContext = createContext<ToastApi | null>(null);
+
+/** 弹出轻提示。要在 `ToastProvider` 里面用。 */
+export function useToast(): ToastApi {
+  const toast = useContext(ToastContext);
+  if (!toast) {
+    throw new Error("useToast 要在 <ToastProvider> 里面用");
+  }
+  return toast;
+}
+
+/* 和提示条一样，四种色调用四种不同外形的图标 */
+const toneIcon: Record<
+  Exclude<ToastTone, "neutral">,
+  ComponentType<IconProps>
+> = {
+  info: StatusInfo,
+  success: StatusSuccess,
+  warning: StatusWarning,
+  danger: StatusDanger,
+};
+
+const toneText: Record<Exclude<ToastTone, "neutral">, string> = {
+  info: "text-info",
+  success: "text-success",
+  warning: "text-warning",
+  danger: "text-danger",
+};
+
+/*
+ * 水平居中 + 跟着手指走的位移（可以往下或往右划走）。
+ * 新旧两条在同一个位置交替淡入淡出，所以用绝对定位叠在一起
+ */
+const placementClass: Record<
+  ToastPlacement,
+  { viewport: string; root: string }
+> = {
+  bottom: {
+    viewport: "bottom-6",
+    root: "bottom-0 translate-y-[var(--toast-swipe-movement-y,0px)]",
+  },
+  center: {
+    viewport: "top-1/2",
+    root: "top-0 translate-y-[calc(-50%+var(--toast-swipe-movement-y,0px))]",
+  },
+};
+
+function isOptions(input: ReactNode | ToastOptions): input is ToastOptions {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    !isValidElement(input) &&
+    "message" in input
+  );
+}
+
+let counter = 0;
+
+type ToastHostProps = {
+  placement: ToastPlacement;
+  label: string;
+  closeLabel: string;
+  children: ReactNode;
+};
+
+function ToastHost({ placement, label, closeLabel, children }: ToastHostProps) {
+  const { toasts, add, close } = BaseToast.useToastManager<ToastData>();
+
+  const api = useMemo<ToastApi>(() => {
+    const show = (input: ReactNode | ToastOptions) => {
+      const options = isOptions(input) ? input : { message: input };
+      const { message, tone = "neutral", action, duration } = options;
+      const id = `ef-toast-${++counter}`;
+
+      // 同时只显示一条：新的替换旧的
+      close();
+      return add({
+        id,
+        title: message,
+        type: tone,
+        // 警告与失败要打断读屏当前在读的内容，其余的排队
+        priority: tone === "danger" || tone === "warning" ? "high" : "low",
+        timeout: duration ?? (action ? ACTION_DURATION : undefined),
+        actionProps: action && {
+          children: action.label,
+          onClick: () => {
+            action.onClick();
+            close(id);
+          },
+        },
+        data: { tone, dismissible: action !== undefined || duration === 0 },
+      });
+    };
+    show.dismiss = (id?: string) => close(id);
+    return show;
+  }, [add, close]);
+
+  return (
+    <ToastContext value={api}>
+      {children}
+      <BaseToast.Portal>
+        <BaseToast.Viewport
+          aria-label={label}
+          className={cn(
+            "pointer-events-none fixed inset-x-4 z-(--z-toast) h-0",
+            placementClass[placement].viewport,
+          )}
+        >
+          {toasts.map((toast) => {
+            const tone = toast.data?.tone ?? "neutral";
+            const Icon = tone === "neutral" ? null : toneIcon[tone];
+            return (
+              <BaseToast.Root
+                key={toast.id}
+                toast={toast}
+                // 黑底白字不随主题变：整条做成暗色的局部主题，图形和焦点环按深色底取值
+                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))]",
+                  // 边线是给暗色页面的：那里黑底和页面几乎一样深，要靠它把提示勾出来。
+                  // 亮色页面上它和提示的底几乎同色，看不出来
+                  "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",
+                  // 焦点环画在里面：它是按深色底取的颜色，画到外面会压在亮色的页面上
+                  focusRingInset,
+                  placementClass[placement].root,
+                )}
+              >
+                <BaseToast.Content
+                  className={cn(
+                    "flex items-center gap-3 py-2.5 pl-5",
+                    toast.data?.dismissible ? "pr-2" : "pr-5",
+                  )}
+                >
+                  {Icon && tone !== "neutral" && (
+                    <Icon
+                      size={16}
+                      className={cn("shrink-0", toneText[tone])}
+                    />
+                  )}
+                  <BaseToast.Title
+                    render={<p />}
+                    className="min-w-0 wrap-anywhere"
+                  />
+                  {toast.actionProps && (
+                    <BaseToast.Action
+                      className={cn(
+                        "shrink-0 border-b border-current text-sm font-medium text-accent-ink active:opacity-80",
+                        focusRing,
+                      )}
+                    />
+                  )}
+                  {toast.data?.dismissible && (
+                    <BaseToast.Close
+                      aria-label={closeLabel}
+                      className={cn(
+                        "inline-flex size-8 shrink-0 items-center justify-center text-ink-secondary hover:text-ink",
+                        focusRing,
+                      )}
+                    >
+                      <Close size={16} />
+                    </BaseToast.Close>
+                  )}
+                </BaseToast.Content>
+              </BaseToast.Root>
+            );
+          })}
+        </BaseToast.Viewport>
+      </BaseToast.Portal>
+    </ToastContext>
+  );
+}
+
+export type ToastProviderProps = {
+  /** 出现在哪：视口底部居中（默认），或者视口正中（官网的做法） */
+  placement?: ToastPlacement;
+  /** 默认停留多久，毫秒。规范是 2 – 4 秒 */
+  duration?: number;
+  /** 提示区域的可访问名称（按 `F6` 可以把焦点移进来） */
+  label?: string;
+  /** 关闭图标的可访问名称 */
+  closeLabel?: string;
+  children: ReactNode;
+};
+
+/**
+ * 轻提示的容器，包在应用的最外层。里面的任何地方用 `useToast()` 弹出。
+ * 重要的、需要用户处理的信息不要用轻提示，用提示条或弹窗。
+ */
+export function ToastProvider({
+  placement = "bottom",
+  duration = 3000,
+  label = "通知",
+  closeLabel = "关闭",
+  children,
+}: ToastProviderProps) {
+  return (
+    <BaseToast.Provider timeout={duration} limit={1}>
+      <ToastHost placement={placement} label={label} closeLabel={closeLabel}>
+        {children}
+      </ToastHost>
+    </BaseToast.Provider>
+  );
+}

package/src/components/toast/index.ts

@@ -0,0 +1,10 @@
+export {
+  ToastProvider,
+  useToast,
+  type ToastAction,
+  type ToastApi,
+  type ToastOptions,
+  type ToastPlacement,
+  type ToastProviderProps,
+  type ToastTone,
+} from "./Toast";