@endfield-ui/react 0.0.0-stage → 0.1.0

package/src/components/dropdown-menu/menu-style.ts

@@ -0,0 +1,47 @@
+import { createContext } from "react";
+import { focusRingInset } from "../../lib/focus-ring";
+
+/*
+ * 下拉菜单与下拉选择共用的面板和选项。
+ * - `plain` 跟随主题的面板，当前项是浅灰底 + 左缘墨色条；
+ * - `strong` 官网语言菜单的样子：固定的深色面板，当前项整行黄底墨字。
+ *   面板自己是一个 `data-theme="dark"` 的局部主题，所以下面的类不用分两套写。
+ */
+export type MenuVariant = "plain" | "strong";
+
+/** 选项要知道自己在哪种面板里，才知道"当前项"怎么画 */
+export const MenuVariantContext = createContext<MenuVariant>("plain");
+
+/** 面板：直角、1px 线、环境阴影；顶部一条半宽的行动色细条，展开时从 0 伸到一半宽 */
+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",
+  "data-ending-style:opacity-0 data-starting-style:opacity-0",
+  "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",
+].join(" ");
+
+/**
+ * 选项：键盘或指针经过时提亮一档；键盘聚焦另有一圈画在里面的焦点环。
+ * 这里不能写 `outline-none`：它把轮廓的线型定成 none，后面的焦点环也跟着画不出来
+ */
+export const menuItem = [
+  "relative flex min-h-9 cursor-default items-center gap-2 px-3 py-1.5 text-sm select-none",
+  "data-disabled:text-ink-disabled",
+  focusRingInset,
+].join(" ");
+
+/** 不是当前项的选项才有悬停底：当前项的底不能被悬停盖掉 */
+export const menuItemHover = "data-highlighted:bg-ink/5";
+
+/** 当前项（下拉选择的已选项、单选菜单项的选中项） */
+export const menuItemCurrent: Record<MenuVariant, string> = {
+  plain:
+    "bg-surface-muted font-medium before:absolute before:inset-y-0 before:left-0 before:w-[3px] before:bg-ink before:content-['']",
+  strong: "bg-action font-medium text-on-action",
+};
+
+export const menuGroupLabel = "px-3 pt-2 pb-1 text-xs text-ink-tertiary";
+
+export const menuSeparator = "my-1 h-px bg-line";

package/src/components/empty-state/EmptyState.tsx

@@ -0,0 +1,79 @@
+import type { ComponentProps, ElementType, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type EmptyStateProps = Omit<ComponentProps<"div">, "title"> & {
+  /** 一句话说明现状："暂无记录" */
+  title: ReactNode;
+  /** 一句话说明原因或下一步 */
+  description?: ReactNode;
+  /** 可选的一个行动，通常是一个 `control` 按钮 */
+  action?: ReactNode;
+  /** 图形。默认是取景角 + 准星；传 `null` 去掉 */
+  icon?: ReactNode;
+  /** 虚线描边，默认有 */
+  bordered?: boolean;
+  /** 标题层级，默认 3（`<h3>`） */
+  level?: 2 | 3 | 4 | 5 | 6;
+};
+
+/** 取景角 + 准星：游戏内图鉴用它表示"未获得"，空状态沿用这个符号 */
+function Viewfinder() {
+  return (
+    <svg
+      width={56}
+      height={56}
+      viewBox="0 0 48 48"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={1.5}
+      strokeLinecap="butt"
+      strokeLinejoin="miter"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <path d="M4 14V4h10M34 4h10v10M44 34v10H34M14 44H4V34" />
+      <path d="M24 18v12M18 24h12" />
+    </svg>
+  );
+}
+
+/** 没有内容时的占位。说清楚为什么为空、接下来能做什么；不要用大幅插画填满。 */
+export function EmptyState({
+  title,
+  description,
+  action,
+  icon,
+  bordered = true,
+  level = 3,
+  className,
+  children,
+  ...props
+}: EmptyStateProps) {
+  const Heading: ElementType = `h${level}`;
+  const graphic = icon === undefined ? <Viewfinder /> : icon;
+
+  return (
+    <div
+      {...props}
+      className={cn(
+        "flex flex-col items-center px-6 py-10 text-center text-ink",
+        bordered && "border border-dashed border-line-strong",
+        className,
+      )}
+    >
+      {graphic !== null && (
+        <div aria-hidden="true" className="mb-4 text-ink-tertiary">
+          {graphic}
+        </div>
+      )}
+      <Heading className="text-base font-medium">{title}</Heading>
+      {description && (
+        <p className="mt-1 max-w-[40ch] text-sm text-ink-secondary">
+          {description}
+        </p>
+      )}
+      {children}
+      {action && <div className="mt-5">{action}</div>}
+    </div>
+  );
+}

package/src/components/empty-state/index.ts

@@ -0,0 +1 @@
+export { EmptyState, type EmptyStateProps } from "./EmptyState";

package/src/components/field/Field.tsx

@@ -0,0 +1,203 @@
+import {
+  createContext,
+  useContext,
+  useId,
+  useMemo,
+  type HTMLAttributes,
+  type ReactNode,
+} from "react";
+import { StatusDanger } from "../../icons/StatusDanger";
+import { cn } from "../../lib/cn";
+
+type FieldContextValue = {
+  /** 单个控件的 id；`group` 字段里有多个控件，不提供 */
+  controlId: string | undefined;
+  labelId: string;
+  describedBy: string | undefined;
+  invalid: boolean;
+  disabled: boolean;
+  required: boolean;
+  group: boolean;
+};
+
+const FieldContext = createContext<FieldContextValue | null>(null);
+
+/** 给成组的控件（单选组）读取所在字段的状态。不在 `Field` 里时返回 `null`。 */
+export function useFieldContext(): FieldContextValue | null {
+  return useContext(FieldContext);
+}
+
+type ControlProps = {
+  id?: string;
+  disabled?: boolean;
+  required?: boolean;
+  /** 错误态。不传时跟随所在的 `Field` */
+  invalid?: boolean;
+  "aria-describedby"?: string;
+};
+
+/**
+ * 把所在 `Field` 的 id、说明文字、错误态、禁用、必填并进控件自己的属性。
+ * 控件上显式传的值优先。自定义控件用它接入 `Field`。
+ */
+export function useFieldControl({
+  id,
+  disabled,
+  required,
+  invalid,
+  "aria-describedby": describedBy,
+}: ControlProps) {
+  const field = useContext(FieldContext);
+  const mergedDescribedBy =
+    [describedBy, field?.describedBy].filter(Boolean).join(" ") || undefined;
+
+  return {
+    id: id ?? field?.controlId,
+    disabled: disabled ?? field?.disabled ?? false,
+    required: required ?? field?.required ?? false,
+    invalid: invalid ?? field?.invalid ?? false,
+    "aria-describedby": mergedDescribedBy,
+  };
+}
+
+export type FieldProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+  /** 标签，在控件上方。不要用占位文字代替它 */
+  label: ReactNode;
+  /** 帮助文字，在控件下方 */
+  help?: ReactNode;
+  /** 错误说明：写"哪里不对、怎么改"。有值即为错误态 */
+  error?: ReactNode;
+  /** 必填：标签后加一个小菱形，并交给里面的控件 */
+  required?: boolean;
+  /** 禁用：标签变浅，并交给里面的控件 */
+  disabled?: boolean;
+  /**
+   * 里面是一组控件（几个复选、一个单选组）而不是单个输入框时打开：
+   * 渲染成 `<fieldset>` + `<legend>`。
+   */
+  group?: boolean;
+  /** 单个控件的 id，缺省自动生成 */
+  controlId?: string;
+  children: ReactNode;
+};
+
+/** 表单字段：标签在上、控件在下，下面是帮助与错误文字，三者自动关联。 */
+export function Field({
+  label,
+  help,
+  error,
+  required = false,
+  disabled = false,
+  group = false,
+  controlId,
+  className,
+  children,
+  ...props
+}: FieldProps) {
+  const baseId = useId();
+  const id = controlId ?? `${baseId}-control`;
+  const labelId = `${baseId}-label`;
+  const helpId = `${baseId}-help`;
+  const errorId = `${baseId}-error`;
+
+  const hasError = error !== undefined && error !== null && error !== false;
+  const hasHelp = help !== undefined && help !== null && help !== false;
+  const describedBy =
+    [hasError && errorId, hasHelp && helpId].filter(Boolean).join(" ") ||
+    undefined;
+
+  const context = useMemo<FieldContextValue>(
+    () => ({
+      controlId: group ? undefined : id,
+      labelId,
+      describedBy,
+      invalid: hasError,
+      disabled,
+      required,
+      group,
+    }),
+    [group, id, labelId, describedBy, hasError, disabled, required],
+  );
+
+  const labelClass = cn(
+    "block text-sm font-medium",
+    disabled ? "text-ink-disabled" : "text-ink",
+  );
+
+  const labelContent = (
+    <>
+      {label}
+      {required && (
+        // 行动色在亮色表面上看不见，必填记号用强调色的文字档
+        <span
+          aria-hidden="true"
+          data-required=""
+          className={cn(
+            "ml-1.5 inline-block size-1.5 rotate-45 align-middle",
+            disabled ? "bg-ink-disabled" : "bg-accent-ink",
+          )}
+        />
+      )}
+    </>
+  );
+
+  const messages = (
+    <>
+      {hasError && (
+        <p
+          id={errorId}
+          className="mt-1.5 flex items-start gap-1.5 text-sm text-danger"
+        >
+          <StatusDanger size={16} className="mt-0.5 shrink-0" />
+          <span className="min-w-0 wrap-anywhere">{error}</span>
+        </p>
+      )}
+      {hasHelp && (
+        <p
+          id={helpId}
+          className={cn(
+            "mt-1.5 text-sm",
+            disabled ? "text-ink-disabled" : "text-ink-secondary",
+          )}
+        >
+          {help}
+        </p>
+      )}
+    </>
+  );
+
+  if (group) {
+    return (
+      <fieldset
+        {...props}
+        disabled={disabled}
+        aria-describedby={describedBy}
+        data-invalid={hasError ? "" : undefined}
+        className={cn("min-w-0", className)}
+      >
+        <legend id={labelId} className={cn(labelClass, "mb-1.5")}>
+          {labelContent}
+        </legend>
+        {/* 组里的控件默认竖排；要横排就自己包一层，作为这里唯一的子元素 */}
+        <div className="flex flex-col items-start">
+          <FieldContext value={context}>{children}</FieldContext>
+        </div>
+        {messages}
+      </fieldset>
+    );
+  }
+
+  return (
+    <div
+      {...props}
+      data-invalid={hasError ? "" : undefined}
+      className={cn("min-w-0", className)}
+    >
+      <label id={labelId} htmlFor={id} className={cn(labelClass, "mb-1.5")}>
+        {labelContent}
+      </label>
+      <FieldContext value={context}>{children}</FieldContext>
+      {messages}
+    </div>
+  );
+}

package/src/components/field/index.ts

@@ -0,0 +1,6 @@
+export {
+  Field,
+  useFieldContext,
+  useFieldControl,
+  type FieldProps,
+} from "./Field";

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

@@ -0,0 +1,201 @@
+import type { ComponentProps, ReactNode } from "react";
+import { Close } from "../../icons/Close";
+import { StatusDanger } from "../../icons/StatusDanger";
+import { StatusSuccess } from "../../icons/StatusSuccess";
+import { cn } from "../../lib/cn";
+import { fileExtension, formatFileSize } from "../../lib/file";
+import { focusRing, focusRingInset } from "../../lib/focus-ring";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+import { Progress } from "../progress/Progress";
+import { Tag } from "../tag/Tag";
+
+export type FileItemStatus = "uploading" | "done" | "error";
+
+type OwnProps = {
+  /** 文件名。前面的扩展名标签是从它里面取的 */
+  name: string;
+  /** 大小，字节 */
+  size?: number;
+  /**
+   * 传到哪一步了，由使用方给：
+   * - 不传：只是列出来；
+   * - `uploading` 行底一条进度条，大小的位置换成百分比；
+   * - `done` 多一个成功图标；
+   * - `error` 文件名下面一行错误说明。
+   */
+  status?: FileItemStatus;
+  /** `uploading` 时的进度，0 – 100。不传就是不确定进度 */
+  progress?: number;
+  /** `error` 时的说明：写"怎么了、怎么办" */
+  error?: ReactNode;
+  /** 传了右端就有移除钮 */
+  onRemove?: () => void;
+  /** 传了、且是 `error` 时，多一个"重试" */
+  onRetry?: () => void;
+  /** 移除钮的可访问名称，默认"移除某某" */
+  removeLabel?: string;
+  /** "重试"两个字 */
+  retryLabel?: ReactNode;
+  /** `done` 时读屏多听到的一句，默认"已上传" */
+  doneLabel?: string;
+  /** 进度条的可访问名称，默认"某某的上传进度" */
+  progressLabel?: string;
+  /** 传了文件名就是链接：已有的附件可以点开 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  disabled?: boolean;
+};
+
+export type FileItemProps = OwnProps &
+  Omit<ComponentProps<"div">, keyof OwnProps | "children">;
+
+/**
+ * 一个文件一行：扩展名、文件名、大小、状态、移除钮。
+ * `FileUpload` 里每个文件默认渲染一行；也可以单独拿去列"已有的附件"。
+ */
+export function FileItem({
+  name,
+  size,
+  status,
+  progress,
+  error,
+  onRemove,
+  onRetry,
+  removeLabel = `移除${name}`,
+  retryLabel = "重试",
+  doneLabel = "已上传",
+  progressLabel = `${name}的上传进度`,
+  href,
+  target,
+  rel,
+  render,
+  disabled = false,
+  className,
+  ...props
+}: FileItemProps) {
+  const uploading = status === "uploading";
+  const failed = status === "error";
+  const isLink = href !== undefined || render !== undefined;
+
+  let meta: string | null = null;
+  if (uploading && progress !== undefined) {
+    meta = `${Math.round(Math.min(Math.max(progress, 0), 100))}%`;
+  } else if (!uploading && size !== undefined) {
+    meta = formatFileSize(size);
+  }
+
+  return (
+    <div
+      {...props}
+      data-status={status}
+      className={cn(
+        "relative flex min-h-10 items-center gap-3 bg-surface-muted pl-2 text-sm",
+        disabled ? "text-ink-disabled" : "text-ink",
+        !onRemove && "pr-3",
+        className,
+      )}
+    >
+      <Tag
+        // 禁用的那一行，扩展名也跟着降下去
+        variant={disabled ? "muted" : "inverse"}
+        size="sm"
+        aria-hidden="true"
+        data-extension=""
+        className={cn(
+          "min-w-10 justify-center font-tech font-bold",
+          disabled && "text-ink-disabled",
+        )}
+      >
+        {fileExtension(name) || "FILE"}
+      </Tag>
+
+      <span className="flex min-w-0 flex-1 flex-col py-1.5">
+        {isLink ? (
+          <LinkElement
+            render={render}
+            href={href}
+            target={target}
+            rel={rel}
+            title={name}
+            className={cn("truncate underline underline-offset-4", focusRing)}
+          >
+            {name}
+          </LinkElement>
+        ) : (
+          <span title={name} className="truncate">
+            {name}
+          </span>
+        )}
+        {failed && error && (
+          <span className="flex items-start gap-1 text-xs text-danger">
+            <StatusDanger size={12} className="mt-0.5 shrink-0" />
+            <span className="min-w-0 wrap-anywhere">{error}</span>
+          </span>
+        )}
+      </span>
+
+      {meta !== null && (
+        <span
+          data-meta=""
+          className={cn(
+            "shrink-0 font-tech text-xs tabular-nums",
+            disabled ? "text-ink-disabled" : "text-ink-secondary",
+          )}
+        >
+          {meta}
+        </span>
+      )}
+      {status === "done" && (
+        <>
+          <StatusSuccess size={16} className="shrink-0 text-success" />
+          <span className="sr-only">{doneLabel}</span>
+        </>
+      )}
+      {failed && onRetry && (
+        <button
+          type="button"
+          disabled={disabled}
+          onClick={onRetry}
+          className={cn(
+            "shrink-0 font-medium underline underline-offset-4",
+            focusRing,
+          )}
+        >
+          {retryLabel}
+        </button>
+      )}
+      {onRemove && (
+        <button
+          type="button"
+          data-file-remove=""
+          aria-label={removeLabel}
+          disabled={disabled}
+          onClick={onRemove}
+          className={cn(
+            "flex size-8 shrink-0 items-center justify-center self-center",
+            "transition-colors duration-(--duration-fast) ease-standard",
+            disabled
+              ? "cursor-not-allowed text-ink-disabled"
+              : "text-ink-secondary hover:bg-line hover:text-ink",
+            // 这一行和上下两行只隔 4px，环画在里面
+            focusRingInset,
+          )}
+        >
+          <Close size={14} />
+        </button>
+      )}
+
+      {uploading && (
+        <Progress
+          size="sm"
+          value={progress}
+          aria-label={progressLabel}
+          className="absolute inset-x-0 bottom-0"
+        />
+      )}
+    </div>
+  );
+}