@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/item-slot/ItemSlot.tsx

@@ -0,0 +1,284 @@
+import type { ComponentProps, MouseEvent, ReactNode } from "react";
+import { Crosshair } from "../../icons/Crosshair";
+import { Lock } from "../../icons/Lock";
+import { cn } from "../../lib/cn";
+import { decor } from "../../lib/decor";
+import { focusRing } from "../../lib/focus-ring";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+
+export type ItemSlotRarity = 1 | 2 | 3 | 4;
+export type ItemSlotRatio = "1/1" | "4/5";
+
+type OwnProps = {
+  /** 物品名称。格子里只有图标，名称是给读屏的 */
+  name: string;
+  /** 完整的读屏文字。缺省由名称、数量、稀有度与各状态拼出来 */
+  label?: string;
+  /** 右下角的数量 */
+  count?: ReactNode;
+  /** 稀有度 1 – 4：底部一段向上消散的渐变，左缘另有同样个数的小菱形 */
+  rarity?: ItemSlotRarity;
+  /** 宽高比：正方形（默认）或 4:5 */
+  ratio?: ItemSlotRatio;
+  /** 选中：四角出现角括号 */
+  selected?: boolean;
+  /** 锁定：左下角一个锁，卡面不变灰 */
+  locked?: boolean;
+  /** 未获得（图鉴）：内容换成准星占位符 */
+  unowned?: boolean;
+  /** 新获得：左上角的黄签 */
+  isNew?: boolean;
+  /** 黄签上的字，默认 `NEW` */
+  newLabel?: ReactNode;
+  /** 右上角的小圆位：已装备者的头像 */
+  badge?: ReactNode;
+  /** 售罄 / 不可用：整卡压一层遮罩。传文字（"售罄"）会写在遮罩上 */
+  // oxlint-disable-next-line typescript/no-redundant-type-constituents -- ReactNode 本来就含 boolean，写出来是让人一眼看到两种用法
+  unavailable?: boolean | ReactNode;
+  /** 传了就整格渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  /** 传了（且没有 `href` 和 `render`）就整格渲染成按钮 */
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  disabled?: boolean;
+  /** 图标或缩略图 */
+  children?: ReactNode;
+};
+
+export type ItemSlotProps = Omit<ComponentProps<"div">, keyof OwnProps> &
+  OwnProps;
+
+/** 格子里那个可点击的元素带着它：`ItemGrid` 靠它找到能用方向键走到的格子 */
+const slotControl = { "data-slot-control": "" };
+
+const ratioClass: Record<ItemSlotRatio, string> = {
+  "1/1": "aspect-square",
+  "4/5": "aspect-4/5",
+};
+
+// 有意不随主题变：稀有度色阶是固定的角色色，这里只作渐变的填充
+const rarityClass: Record<ItemSlotRarity, string> = {
+  1: "from-rarity-1/55",
+  2: "from-rarity-2/55",
+  3: "from-rarity-3/55",
+  4: "from-rarity-4/55",
+};
+
+/**
+ * 物品格：矩阵里的一个格子——图标、数量、稀有度。
+ * 整格只有一个可点击元素；宽度跟着所在的网格走，格子之间留 6 – 8px。
+ *
+ * `className` 与其余属性给最外层的盒子。角括号画在盒子之外 4px，
+ * 所以网格容器不能贴着格子裁切。一组格子放进 `ItemGrid`，就能用方向键在里面走。
+ */
+export function ItemSlot({
+  name,
+  label,
+  count,
+  rarity,
+  ratio = "1/1",
+  selected = false,
+  locked = false,
+  unowned = false,
+  isNew = false,
+  newLabel = "NEW",
+  badge,
+  unavailable = false,
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  disabled = false,
+  className,
+  children,
+  ...props
+}: ItemSlotProps) {
+  const isLink = href !== undefined || render !== undefined;
+  const isButton = !isLink && onClick !== undefined;
+  const interactive = (isLink || isButton) && !disabled;
+  const hasCount = count !== undefined && count !== null && count !== false;
+  const isUnavailable = unavailable !== false && unavailable !== null;
+  const unavailableText =
+    typeof unavailable === "boolean" ? undefined : unavailable;
+
+  // 图标、数量、角标都是给眼睛看的；读屏拿到的是这一句完整的话
+  const spoken =
+    label ??
+    [
+      name,
+      hasCount && typeof count !== "object" && `数量 ${count}`,
+      rarity && `稀有度 ${rarity}`,
+      isNew && "新获得",
+      unowned && "未获得",
+      locked && "已锁定",
+      isUnavailable &&
+        (typeof unavailableText === "string" ? unavailableText : "不可用"),
+    ]
+      .filter(Boolean)
+      .join("，");
+
+  const faceClass = cn(
+    // 卡面自己裁切：渐变、遮罩、角标都不许越界。焦点环画在它外面，不受影响
+    "absolute inset-0 block overflow-clip border border-line bg-surface-raised text-left text-ink",
+    interactive && [
+      "transition-colors duration-(--duration-fast) ease-standard hover:border-line-strong",
+      focusRing,
+      // 选中时让到角括号之外，两圈不重叠
+      selected && "focus-visible:outline-offset-[6px]",
+    ],
+    disabled && "cursor-not-allowed",
+    // 高对比模式下背景画的角括号不显示，换成一圈系统色的描边
+    selected && "forced-colors:border-2 forced-colors:border-[Highlight]",
+  );
+
+  const face = (
+    <>
+      {rarity && (
+        <span
+          aria-hidden="true"
+          className={cn(
+            decor,
+            "absolute inset-x-0 bottom-0 h-2/5 bg-linear-to-t to-transparent",
+            rarityClass[rarity],
+          )}
+        />
+      )}
+      {rarity === 4 && (
+        // 最高一档在渐变上叠细斜纹，同样向上消散
+        <span
+          aria-hidden="true"
+          className={cn(
+            decor,
+            "hatch hatch-fine absolute inset-x-0 bottom-0 h-2/5 opacity-30 [mask-image:linear-gradient(to_top,black,transparent)]",
+          )}
+        />
+      )}
+
+      <span
+        aria-hidden="true"
+        className="absolute inset-0 flex items-center justify-center p-3"
+      >
+        {unowned ? (
+          <Crosshair className="size-1/2 max-h-8 max-w-8 text-ink-tertiary" />
+        ) : (
+          children
+        )}
+      </span>
+
+      {rarity && (
+        <span
+          aria-hidden="true"
+          className="absolute top-1/2 left-1.5 flex -translate-y-1/2 flex-col gap-1"
+        >
+          {Array.from({ length: rarity }, (_, index) => (
+            <span key={index} className="size-1 rotate-45 bg-ink-secondary" />
+          ))}
+        </span>
+      )}
+
+      {isNew && (
+        <span
+          aria-hidden="true"
+          className="cut-br cut-sm absolute top-0 left-0 flex h-4 items-center bg-action pr-2.5 pl-1 font-tech text-micro font-bold text-on-action uppercase"
+        >
+          {newLabel}
+        </span>
+      )}
+
+      {badge !== undefined && (
+        <span
+          aria-hidden="true"
+          className="absolute top-1 right-1 flex size-5 items-center justify-center overflow-clip rounded-full bg-surface-inverse text-micro font-bold text-ink-inverse"
+        >
+          {badge}
+        </span>
+      )}
+
+      {locked && (
+        <Lock size={14} className="absolute bottom-1 left-1 text-ink" />
+      )}
+
+      {hasCount && (
+        <span
+          aria-hidden="true"
+          className="absolute right-1.5 bottom-1 font-tech text-sm leading-none font-bold tabular-nums"
+        >
+          {count}
+        </span>
+      )}
+
+      {isUnavailable && (
+        <span
+          aria-hidden="true"
+          // 遮罩在两个主题下都是黑的，上面的字固定用白
+          className="absolute inset-0 flex items-center justify-center bg-scrim text-xs font-medium text-neutral-0"
+        >
+          {unavailableText !== undefined && (
+            // 字下面垫一小块近黑，不管底下的图标是什么都读得清
+            <span className="bg-neutral-950/80 px-1.5 py-0.5">
+              {unavailableText}
+            </span>
+          )}
+        </span>
+      )}
+
+      <span className="sr-only">{spoken}</span>
+    </>
+  );
+
+  let node: ReactNode;
+  if (isLink) {
+    node = (
+      <LinkElement
+        render={render}
+        // 禁用的链接去掉 href，保留 link 角色，让读屏仍能读出"不可用"
+        href={disabled ? undefined : href}
+        role={disabled ? "link" : undefined}
+        aria-disabled={disabled || undefined}
+        target={target}
+        rel={rel}
+        aria-current={selected ? "true" : undefined}
+        onClick={disabled ? (event) => event.preventDefault() : onClick}
+        className={faceClass}
+        {...slotControl}
+      >
+        {face}
+      </LinkElement>
+    );
+  } else if (isButton) {
+    node = (
+      <button
+        type="button"
+        disabled={disabled}
+        aria-pressed={selected}
+        onClick={onClick}
+        className={faceClass}
+        {...slotControl}
+      >
+        {face}
+      </button>
+    );
+  } else {
+    node = <div className={faceClass}>{face}</div>;
+  }
+
+  return (
+    <div
+      {...props}
+      data-selected={selected ? "" : undefined}
+      data-rarity={rarity}
+      className={cn(
+        "relative",
+        ratioClass[ratio],
+        selected && "corner-brackets",
+        className,
+      )}
+    >
+      {node}
+    </div>
+  );
+}

package/src/components/item-slot/index.ts

@@ -0,0 +1,7 @@
+export { ItemGrid, type ItemGridProps } from "./ItemGrid";
+export {
+  ItemSlot,
+  type ItemSlotProps,
+  type ItemSlotRarity,
+  type ItemSlotRatio,
+} from "./ItemSlot";

package/src/components/kbd/Kbd.tsx

@@ -0,0 +1,33 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+
+export type KbdSize = "sm" | "md";
+
+export type KbdProps = ComponentProps<"kbd"> & {
+  /** 20px 或 24px 高 */
+  size?: KbdSize;
+};
+
+const sizeClass: Record<KbdSize, string> = {
+  sm: "h-5 min-w-5 px-1 text-xs",
+  md: "h-6 min-w-6 px-1.5 text-sm",
+};
+
+/**
+ * 键位提示：一颗小键帽，贴在对应的控件旁。
+ * 只用于真的支持键盘快捷键的地方，触屏界面和普通网页不要伪造键帽。
+ * 组合键分开写：`<Kbd>Ctrl</Kbd> + <Kbd>K</Kbd>`。
+ */
+export function Kbd({ size = "sm", className, ...props }: KbdProps) {
+  return (
+    <kbd
+      {...props}
+      className={cn(
+        // 反转块：亮色下是墨色键帽，暗色下是游戏界面里的白键帽
+        "inline-flex shrink-0 items-center justify-center bg-surface-inverse font-tech leading-none font-medium whitespace-nowrap text-ink-inverse",
+        sizeClass[size],
+        className,
+      )}
+    />
+  );
+}

package/src/components/kbd/index.ts

@@ -0,0 +1 @@
+export { Kbd, type KbdProps, type KbdSize } from "./Kbd";

package/src/components/link-element/LinkElement.tsx

@@ -0,0 +1,25 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { ComponentProps, ReactElement } from "react";
+import { defined } from "../../lib/defined";
+
+/** 用来代替 `<a>` 的元素，通常是路由库的链接组件：`<Link to="/archive" />` */
+export type LinkRender = ReactElement<Record<string, unknown>>;
+
+export type LinkElementProps = ComponentProps<"a"> & {
+  render?: LinkRender;
+};
+
+/**
+ * 各控件"链接形态"里的那个 `<a>`。不对外导出。
+ *
+ * 传了 `render` 就把控件算好的类名、状态属性和事件合并到那个元素上，
+ * 由它来渲染：类名拼在一起，事件两边都触发，其余属性以那个元素自己写的为准。
+ */
+export function LinkElement({ render, ref, ...props }: LinkElementProps) {
+  return useRender({
+    render,
+    ref,
+    props: render ? defined(props) : props,
+    defaultTagName: "a",
+  });
+}

package/src/components/list/List.tsx

@@ -0,0 +1,229 @@
+import {
+  createContext,
+  useContext,
+  type ComponentProps,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn";
+import { focusRingInset } from "../../lib/focus-ring";
+import { GhostText } from "../ghost-text/GhostText";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+import { bandCanvas, bandGap, bandRow } from "./band-style";
+
+export type ListVariant = "plain" | "band";
+
+export type ListProps = ComponentProps<"ul"> & {
+  /**
+   * - `plain` 行间一条 1px 的线，默认；
+   * - `band` 浅色画布上一条条固定深色的行，行间留缝；选中行整行反转成白底墨字。
+   */
+  variant?: ListVariant;
+};
+
+const ListVariantContext = createContext<ListVariant>("plain");
+
+/** 列表行的容器，外圈不描边。里面只放 `ListRow`。 */
+export function List({ variant = "plain", className, ...props }: ListProps) {
+  return (
+    <ListVariantContext value={variant}>
+      <ul
+        {...props}
+        data-variant={variant}
+        className={cn(
+          "text-ink",
+          variant === "band"
+            ? ["flex flex-col", bandCanvas, bandGap]
+            : "divide-y divide-line",
+          className,
+        )}
+      />
+    </ListVariantContext>
+  );
+}
+
+export type ListRowSize = "sm" | "md";
+
+export type ListRowProps = Omit<ComponentProps<"li">, "onClick"> & {
+  /** 行首：图标、日期块、缩略图 */
+  start?: ReactNode;
+  /** 行尾：数值或状态，右对齐、等宽 */
+  end?: ReactNode;
+  /** 标题下的一行次要说明 */
+  description?: ReactNode;
+  /** 选中：浅灰底 + 左缘黄条 + 标题加粗；在 `band` 列表里是整行反转成白底墨字 */
+  selected?: boolean;
+  /** 已完成：整行降一档对比，行尾数值前多一个低对比的描边词，读屏多读一句"已完成" */
+  completed?: boolean;
+  /** 完成态的描边词，默认 `DONE`。纯装饰；传 `null` 去掉 */
+  completedWord?: ReactNode;
+  /** 40px 或 48px 行高 */
+  size?: ListRowSize;
+  /** 传了就整行渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  /** 传了（且没有 `href` 和 `render`）就整行渲染成按钮 */
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  disabled?: boolean;
+};
+
+const sizeClass: Record<ListRowSize, string> = {
+  sm: "min-h-10 py-2",
+  md: "min-h-12 py-2.5",
+};
+
+/* 描边词不能比一行文字高，否则会把行撑开 */
+const completedWordSize: Record<ListRowSize, string> = {
+  sm: "text-lg",
+  md: "text-xl",
+};
+
+/**
+ * 一行一个条目。整行可点时只有一个可点击元素，不要在里面再嵌按钮。
+ * 左缘的黄条只表示"选中"，不要拿它表示类目。
+ */
+export function ListRow({
+  start,
+  end,
+  description,
+  selected,
+  completed = false,
+  completedWord = "DONE",
+  size = "md",
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  disabled = false,
+  className,
+  children,
+  ...props
+}: ListRowProps) {
+  const band = useContext(ListVariantContext) === "band";
+  const isLink = href !== undefined || render !== undefined;
+  const isButton = !isLink && onClick !== undefined;
+  const interactive = (isLink || isButton) && !disabled;
+
+  const rowClass = cn(
+    "relative flex w-full items-center gap-3 px-4 text-left",
+    sizeClass[size],
+    // 完成：降低对比但保持可读
+    completed && "text-ink-secondary",
+    // 行带：选中靠整行换主题来表达（见下面的 data-theme），这里只管底和边线
+    band && bandRow,
+    selected &&
+      !band &&
+      "bg-surface-muted before:absolute before:inset-y-0 before:left-0 before:w-1 before:bg-action before:content-['']",
+    interactive && [
+      "transition-colors duration-(--duration-fast) ease-standard",
+      !selected &&
+        (band
+          ? // 行带的底是实色，悬停换成提亮一档的实色；半透明的底会把画布透出来
+            "hover:bg-surface-raised active:bg-surface-muted"
+          : "hover:bg-ink/5 active:bg-ink/10"),
+      focusRingInset,
+    ],
+    disabled && "cursor-not-allowed text-ink-disabled",
+  );
+
+  const content = (
+    <>
+      {start && <span className="flex shrink-0 items-center">{start}</span>}
+      <span className="min-w-0 flex-1">
+        <span className={cn("block truncate", selected && "font-bold")}>
+          {children}
+          {completed && <span className="sr-only">（已完成）</span>}
+        </span>
+        {description && (
+          <span
+            className={cn(
+              "block truncate text-xs",
+              disabled ? "text-ink-disabled" : "text-ink-secondary",
+            )}
+          >
+            {description}
+          </span>
+        )}
+      </span>
+      {completed && completedWord !== null && (
+        // 排在标题和行尾数值之间，不压在任何文字上；行很窄时让给标题
+        <GhostText
+          variant="outline"
+          className={cn(
+            "hidden shrink-0 leading-none @sm:block",
+            completedWordSize[size],
+          )}
+        >
+          {completedWord}
+        </GhostText>
+      )}
+      {end && (
+        <span
+          className={cn(
+            "flex shrink-0 items-center font-tech text-sm tabular-nums",
+            disabled
+              ? "text-ink-disabled"
+              : selected
+                ? "text-ink"
+                : "text-ink-secondary",
+          )}
+        >
+          {end}
+        </span>
+      )}
+    </>
+  );
+
+  let row: ReactNode;
+  if (isLink) {
+    row = (
+      <LinkElement
+        render={render}
+        // 禁用的链接去掉 href，保留 link 角色，让读屏仍能读出"不可用"
+        href={disabled ? undefined : href}
+        role={disabled ? "link" : undefined}
+        aria-disabled={disabled || undefined}
+        target={target}
+        rel={rel}
+        aria-current={selected ? "true" : undefined}
+        onClick={disabled ? (event) => event.preventDefault() : onClick}
+        className={rowClass}
+      >
+        {content}
+      </LinkElement>
+    );
+  } else if (isButton) {
+    row = (
+      <button
+        type="button"
+        disabled={disabled}
+        // 只有声明了 selected 的行才是"可切换"的
+        aria-pressed={selected}
+        onClick={onClick}
+        className={rowClass}
+      >
+        {content}
+      </button>
+    );
+  } else {
+    row = <div className={rowClass}>{content}</div>;
+  }
+
+  return (
+    <li
+      // 行带是一块固定的深色，选中的那一行反过来是固定的浅色：
+      // 整行换主题，里面的次要文字、焦点环跟着取值
+      data-theme={band ? (selected ? "light" : "dark") : undefined}
+      {...props}
+      data-selected={selected ? "" : undefined}
+      data-completed={completed ? "" : undefined}
+      className={cn("@container", className)}
+    >
+      {row}
+    </li>
+  );
+}

package/src/components/list/band-style.ts

@@ -0,0 +1,18 @@
+/*
+ * 行带：浅色画布上一条条固定深色的行。列表的 `band` 变体和数据行带共用。
+ *
+ * 行带自己是一个局部暗色主题——用 `bandRow` 的元素（或它的祖先）上要写
+ * `data-theme="dark"`，行里的次要文字、焦点环才会按深色底取值。
+ */
+
+/** 画布：凹陷底，四周留 12px */
+export const bandCanvas = "bg-surface-sunken p-3";
+
+/** 行与行之间的缝 */
+export const bandGap = "gap-1.5";
+
+/**
+ * 一条行带。带一圈 1px 的线：亮色页面上看不出来；
+ * 暗色页面上画布是纯黑、行带是 #141414，靠它分开。
+ */
+export const bandRow = "border border-line bg-surface text-ink";

package/src/components/list/index.ts

@@ -0,0 +1,8 @@
+export {
+  List,
+  ListRow,
+  type ListProps,
+  type ListRowProps,
+  type ListRowSize,
+  type ListVariant,
+} from "./List";