@endfield-ui/react 0.0.0-stage → 0.1.0

package/src/components/hazard-stripe/HazardStripe.tsx

@@ -0,0 +1,35 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+import { decor } from "../../lib/decor";
+
+export type HazardStripeSize = "sm" | "md";
+
+export type HazardStripeProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 条高 6px 或 12px */
+  size?: HazardStripeSize;
+};
+
+const sizeClass: Record<HazardStripeSize, string> = {
+  sm: "h-1.5",
+  md: "h-3",
+};
+
+/**
+ * 警示条纹：黄黑相间的窄条，和红色一样带"危险 / 施工"的含义。
+ * 放在删除确认、不可逆操作这类区域的边缘；一个视口最多一处，普通内容不要用。
+ * 它只是装饰：危险的含义必须另外用文字写出来。
+ */
+export function HazardStripe({
+  size = "md",
+  className,
+  ...props
+}: HazardStripeProps) {
+  return (
+    <div
+      {...props}
+      aria-hidden="true"
+      // 有意不随主题变：警示条纹在哪种底色上都是黄黑两色
+      className={cn(decor, "hazard w-full", sizeClass[size], className)}
+    />
+  );
+}

package/src/components/hazard-stripe/index.ts

@@ -0,0 +1,5 @@
+export {
+  HazardStripe,
+  type HazardStripeProps,
+  type HazardStripeSize,
+} from "./HazardStripe";

package/src/components/icon-button/IconButton.tsx

@@ -0,0 +1,95 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+
+export type IconButtonVariant = "plain" | "floating" | "accent" | "inverse";
+export type IconButtonSize = "sm" | "md" | "lg";
+
+export type IconButtonProps = Omit<ComponentProps<"button">, "aria-label"> & {
+  /** 纯图标控件必须有可访问名称 */
+  "aria-label": string;
+  /**
+   * - `plain` 方形浅灰底，工具栏与顶栏，默认；
+   * - `floating` 圆形白底 + 环境阴影，翻页与浮在图像上的操作；
+   * - `accent` 方形，悬停或激活时变信号黄；
+   * - `inverse` 方形，悬停或激活时变墨底；它打开的菜单、展开条开着的时候也是。
+   */
+  variant?: IconButtonVariant;
+  size?: IconButtonSize;
+  /** 开关类按钮的激活状态，同时输出 `aria-pressed` */
+  pressed?: boolean;
+};
+
+const sizeClass: Record<IconButtonSize, string> = {
+  // 32px 小于触屏的最小点击区，用伪元素向外补到 40px
+  sm: "size-8 after:absolute after:-inset-1 after:content-[''] [&_svg]:size-4",
+  md: "size-10 [&_svg]:size-5",
+  lg: "size-12 [&_svg]:size-6",
+};
+
+const restClass =
+  "bg-surface-sunken text-ink-secondary hover:bg-surface-muted hover:text-ink active:bg-line";
+
+const enabledClass: Record<IconButtonVariant, string> = {
+  plain: restClass,
+  // 有意不随主题翻转：它要压在图像和深色版块上
+  floating:
+    "rounded-full bg-neutral-50 text-neutral-900 shadow-sm hover:bg-neutral-200 active:bg-neutral-300",
+  accent:
+    "bg-surface-sunken text-ink-secondary hover:bg-action hover:text-on-action active:bg-action-pressed",
+  inverse:
+    // data-popup-open 是浮层基元写在触发元素上的：它打开的东西还开着
+    "bg-surface-sunken text-ink-secondary hover:bg-surface-inverse hover:text-accent-ink-inverse active:bg-surface-inverse data-popup-open:bg-surface-inverse data-popup-open:text-accent-ink-inverse",
+};
+
+const pressedClass: Record<IconButtonVariant, string> = {
+  plain: "bg-surface-muted text-ink active:bg-line",
+  floating:
+    "rounded-full bg-neutral-200 text-neutral-900 shadow-sm active:bg-neutral-300",
+  accent: "bg-action text-on-action active:bg-action-pressed",
+  inverse: "bg-surface-inverse text-accent-ink-inverse",
+};
+
+const disabledClass: Record<IconButtonVariant, string> = {
+  plain: "cursor-not-allowed bg-surface-sunken text-ink-disabled",
+  floating:
+    "cursor-not-allowed rounded-full bg-neutral-50 text-neutral-400 shadow-sm",
+  accent: "cursor-not-allowed bg-surface-sunken text-ink-disabled",
+  inverse: "cursor-not-allowed bg-surface-sunken text-ink-disabled",
+};
+
+export function IconButton({
+  variant = "plain",
+  size = "md",
+  pressed,
+  disabled = false,
+  type = "button",
+  className,
+  children,
+  ...props
+}: IconButtonProps) {
+  return (
+    <button
+      {...props}
+      type={type}
+      disabled={disabled}
+      aria-pressed={pressed}
+      data-variant={variant}
+      data-size={size}
+      className={cn(
+        "relative inline-flex shrink-0 items-center justify-center",
+        "transition-colors duration-(--duration-fast) ease-standard",
+        focusRing,
+        sizeClass[size],
+        disabled
+          ? disabledClass[variant]
+          : pressed
+            ? pressedClass[variant]
+            : enabledClass[variant],
+        className,
+      )}
+    >
+      {children}
+    </button>
+  );
+}

package/src/components/icon-button/index.ts

@@ -0,0 +1,6 @@
+export {
+  IconButton,
+  type IconButtonProps,
+  type IconButtonSize,
+  type IconButtonVariant,
+} from "./IconButton";

package/src/components/input/Input.tsx

@@ -0,0 +1,109 @@
+import type { ComponentProps, ReactNode } from "react";
+import { StatusDanger } from "../../icons/StatusDanger";
+import { cn } from "../../lib/cn";
+import { useFieldControl } from "../field/Field";
+import {
+  controlBox,
+  controlElement,
+  controlIconSize,
+  controlSize,
+  type ControlSize,
+  type ControlVariant,
+} from "./control-box";
+
+export type InputSize = ControlSize;
+export type InputVariant = ControlVariant;
+
+export type InputProps = Omit<ComponentProps<"input">, "size"> & {
+  /**
+   * - `sunken` 凹陷的底 + 一条底边线，默认；
+   * - `outline` 四边描边，放在凹陷底色的区域（工具条、筛选栏）里时用。
+   */
+  variant?: InputVariant;
+  /** 32 / 40 / 56px 高 */
+  size?: InputSize;
+  /** 框内左端：图标 */
+  start?: ReactNode;
+  /** 框内右端：单位、清除按钮 */
+  end?: ReactNode;
+  /** 错误态：底边线变红，右侧出现菱形图标。放在 `Field` 里时跟随它的 `error` */
+  invalid?: boolean;
+};
+
+/**
+ * 单行输入框。`className` 给外框，其余属性与 `ref` 给里面的 `<input>`。
+ * 每个输入框都要有标签：放进 `Field`，或者自己传 `aria-label`。
+ */
+export function Input({
+  variant = "sunken",
+  size = "md",
+  start,
+  end,
+  invalid: invalidProp,
+  id: idProp,
+  disabled: disabledProp,
+  required: requiredProp,
+  readOnly = false,
+  "aria-describedby": describedByProp,
+  className,
+  ...props
+}: InputProps) {
+  const { id, disabled, required, invalid, ...field } = useFieldControl({
+    id: idProp,
+    disabled: disabledProp,
+    required: requiredProp,
+    invalid: invalidProp,
+    "aria-describedby": describedByProp,
+  });
+
+  return (
+    <div
+      data-variant={variant}
+      data-size={size}
+      data-invalid={invalid ? "" : undefined}
+      className={cn(
+        controlBox({ variant, invalid, disabled, readOnly }),
+        "items-center",
+        controlSize[size],
+        className,
+      )}
+    >
+      {start && (
+        <span className="flex shrink-0 items-center pl-3 text-ink-secondary">
+          {start}
+        </span>
+      )}
+      <input
+        {...props}
+        id={id}
+        disabled={disabled}
+        required={required}
+        readOnly={readOnly}
+        aria-invalid={invalid || undefined}
+        aria-describedby={field["aria-describedby"]}
+        className={cn(
+          controlElement,
+          "h-full",
+          start ? "pl-2" : "pl-3",
+          end || invalid ? "pr-2" : "pr-3",
+        )}
+      />
+      {invalid && (
+        <StatusDanger
+          size={controlIconSize[size]}
+          className={cn("shrink-0 text-danger", !end && "mr-3")}
+        />
+      )}
+      {end && (
+        <span
+          className={cn(
+            "flex shrink-0 items-center pr-3 text-sm text-ink-secondary",
+            invalid && "pl-2",
+          )}
+        >
+          {end}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/components/input/control-box.ts

@@ -0,0 +1,71 @@
+import { cn } from "../../lib/cn";
+import { focusRingWithin } from "../../lib/focus-ring";
+
+/*
+ * 输入框与多行文本共用的外框，直角，两种画法：
+ * - `sunken` 凹陷的底 + 一条 2px 的底边线，默认；
+ * - `outline` 四边 1px 的描边 + 页面底色，放在凹陷底色的区域里时用。
+ * 状态都靠边线的颜色变化：默认灰 → 悬停深一档 → 聚焦墨 → 错误红。
+ */
+
+export type ControlVariant = "sunken" | "outline";
+export type ControlSize = "sm" | "md" | "lg";
+
+/** 32 / 40 / 56px 高，字号跟随通用的三档。输入框和下拉选择的触发器共用 */
+export const controlSize: Record<ControlSize, string> = {
+  sm: "h-8 text-sm",
+  md: "h-10 text-base",
+  lg: "h-14 text-lg",
+};
+
+export const controlIconSize: Record<ControlSize, number> = {
+  sm: 14,
+  md: 16,
+  lg: 20,
+};
+
+type BoxState = {
+  variant?: ControlVariant;
+  invalid: boolean;
+  disabled: boolean;
+  readOnly: boolean;
+};
+
+const frame: Record<ControlVariant, string> = {
+  sunken: "border-b-2",
+  outline: "border",
+};
+
+const fill: Record<ControlVariant, string> = {
+  sunken: "bg-surface-sunken",
+  outline: "bg-surface",
+};
+
+export function controlBox({
+  variant = "sunken",
+  invalid,
+  disabled,
+  readOnly,
+}: BoxState) {
+  return cn(
+    "flex w-full min-w-0 text-ink",
+    frame[variant],
+    "transition-colors duration-(--duration-fast) ease-standard",
+    focusRingWithin,
+    readOnly
+      ? // 只读：没有边线、底变透明。边线留透明的，尺寸不跳
+        "border-transparent bg-transparent"
+      : fill[variant],
+    disabled
+      ? "cursor-not-allowed border-line text-ink-disabled"
+      : invalid
+        ? "border-danger"
+        : !readOnly &&
+          // 悬停只在没聚焦时生效：生成的 CSS 里 hover 排在 focus-within 之后，会盖掉聚焦的墨色
+          "border-line-strong hover:not-focus-within:border-ink-secondary focus-within:border-ink",
+  );
+}
+
+/** 框里真正的 `<input>` / `<textarea>`：没有自己的底和边，焦点环画在外框上 */
+export const controlElement =
+  "min-w-0 flex-1 bg-transparent outline-none placeholder:text-ink-tertiary disabled:cursor-not-allowed disabled:placeholder:text-ink-disabled";

package/src/components/input/index.ts

@@ -0,0 +1,6 @@
+export {
+  Input,
+  type InputProps,
+  type InputSize,
+  type InputVariant,
+} from "./Input";

package/src/components/input/value-chip.ts

@@ -0,0 +1,34 @@
+import type { ControlSize } from "./control-box";
+
+/*
+ * 已经定下来的值在框里排成的小块：组合框的多选、标签输入共用。
+ * 直角——它是值，不是会自己变的状态。右端一个删除叉。
+ */
+
+/** 小块高 20 / 24 / 32px，跟着外框的三档 */
+export const valueChipSize: Record<ControlSize, string> = {
+  sm: "h-5 text-xs",
+  md: "h-6 text-sm",
+  lg: "h-8 text-base",
+};
+
+export const valueChip =
+  "flex max-w-full min-w-0 cursor-default items-center bg-surface-muted pl-2 text-ink";
+
+/** 小块右端的删除叉：一个和小块等高的方钮 */
+export const valueChipRemove =
+  "flex aspect-square h-full shrink-0 items-center justify-center text-ink-secondary hover:bg-line hover:text-ink";
+
+/** 和小块排在一起的那个输入框：和小块一样高，这一行才不会比小块高出一截 */
+export const valueInputHeight: Record<ControlSize, string> = {
+  sm: "h-5",
+  md: "h-6",
+  lg: "h-8",
+};
+
+/** 多选时外框只定最小高度：小块多了会换行、外框跟着长高 */
+export const multiValueBox: Record<ControlSize, string> = {
+  sm: "min-h-8 text-sm",
+  md: "min-h-10 text-base",
+  lg: "min-h-14 text-lg",
+};

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

@@ -0,0 +1,207 @@
+import {
+  useEffect,
+  useRef,
+  type ComponentProps,
+  type FocusEvent,
+  type KeyboardEvent,
+} from "react";
+import { cn } from "../../lib/cn";
+import { mergeRefs } from "../../lib/merge-refs";
+
+export type ItemGridProps = ComponentProps<"div">;
+
+type SlotPosition = { top: number; left: number };
+
+const CONTROL = "[data-slot-control]";
+/** 禁用的按钮本来就聚焦不了；禁用的链接只是标了 `aria-disabled` */
+const ENABLED = `${CONTROL}:not(:disabled):not([aria-disabled="true"])`;
+const SELECTED = '[aria-pressed="true"], [aria-current]';
+
+const KEYS = new Set([
+  "ArrowLeft",
+  "ArrowRight",
+  "ArrowUp",
+  "ArrowDown",
+  "Home",
+  "End",
+]);
+
+/** 同一行的格子顶边应该一样高，留 2px 给小数像素 */
+const ROW_TOLERANCE = 2;
+
+/**
+ * 按下一个键之后该到哪一格。`positions` 是各格子的位置（文档顺序），返回目标的下标；
+ * 不该动的时候（已经在边上、不认识的键）返回 `current`。
+ *
+ * - `←` `→` 在同一行里移动，到头不折行；
+ * - `↑` `↓` 到上下一行里水平位置最近的那一格；
+ * - `Home` / `End` 到行首行尾，带 `ctrl` 是第一格和最后一格。
+ */
+export function nextSlotIndex(
+  positions: readonly SlotPosition[],
+  current: number,
+  key: string,
+  ctrl = false,
+): number {
+  const here = positions[current];
+  if (!here) return current;
+
+  // 按顶边把格子分成行；行内按左边排，左边一样时按文档顺序
+  const order = positions
+    .map((_, index) => index)
+    .sort(
+      (a, b) =>
+        positions[a]!.top - positions[b]!.top ||
+        positions[a]!.left - positions[b]!.left ||
+        a - b,
+    );
+  const rows: number[][] = [];
+  for (const index of order) {
+    const row = rows.at(-1);
+    if (
+      row &&
+      positions[index]!.top - positions[row[0]!]!.top <= ROW_TOLERANCE
+    ) {
+      row.push(index);
+    } else {
+      rows.push([index]);
+    }
+  }
+  for (const row of rows) {
+    row.sort((a, b) => positions[a]!.left - positions[b]!.left || a - b);
+  }
+
+  const rowIndex = rows.findIndex((row) => row.includes(current));
+  const row = rows[rowIndex]!;
+  const column = row.indexOf(current);
+
+  const nearestIn = (target: number[] | undefined) => {
+    if (!target) return current;
+    let best = target[0]!;
+    for (const index of target) {
+      if (
+        Math.abs(positions[index]!.left - here.left) <
+        Math.abs(positions[best]!.left - here.left)
+      ) {
+        best = index;
+      }
+    }
+    return best;
+  };
+
+  switch (key) {
+    case "ArrowRight":
+      return row[column + 1] ?? current;
+    case "ArrowLeft":
+      return row[column - 1] ?? current;
+    case "ArrowDown":
+      return nearestIn(rows[rowIndex + 1]);
+    case "ArrowUp":
+      return nearestIn(rows[rowIndex - 1]);
+    case "Home":
+      return ctrl ? rows[0]![0]! : row[0]!;
+    case "End":
+      return ctrl ? rows.at(-1)!.at(-1)! : row.at(-1)!;
+    default:
+      return current;
+  }
+}
+
+/**
+ * 物品格的矩阵：一组 `ItemSlot` 排成自动填充的网格，整个矩阵只占一个 Tab 停靠点，
+ * 进去之后用方向键在格子之间走。给它一个 `aria-label`，说明这是哪一组物品。
+ *
+ * 默认每格最小 72px、间距 8px，四周留 4px 给选中格的角括号；用 `className` 改。
+ */
+export function ItemGrid({
+  className,
+  onKeyDown,
+  onFocus,
+  ref: forwardedRef,
+  ...props
+}: ItemGridProps) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  // 漫游 tabindex：只有一格能被 Tab 停到。优先是上次聚焦的那一格，其次是选中的，再其次是第一格。
+  // 直接写在 DOM 上——格子自己不管 tabindex，React 不会把它改回去
+  useEffect(() => {
+    const grid = ref.current;
+    if (!grid) return;
+
+    const sync = () => {
+      const enabled = [...grid.querySelectorAll<HTMLElement>(ENABLED)];
+      const stop =
+        enabled.find((control) => control === document.activeElement) ??
+        enabled.find((control) => control.getAttribute("tabindex") === "0") ??
+        enabled.find((control) => control.matches(SELECTED)) ??
+        enabled[0];
+      for (const control of grid.querySelectorAll<HTMLElement>(CONTROL)) {
+        const next = control === stop ? "0" : "-1";
+        if (control.getAttribute("tabindex") !== next) {
+          control.setAttribute("tabindex", next);
+        }
+      }
+    };
+
+    sync();
+    // 格子增减、禁用状态变化之后重新定一次；只盯这些，自己改 tabindex 不会再触发
+    const observer = new MutationObserver(sync);
+    observer.observe(grid, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["disabled", "aria-disabled"],
+    });
+    return () => observer.disconnect();
+  }, []);
+
+  const handleFocus = (event: FocusEvent<HTMLDivElement>) => {
+    onFocus?.(event);
+    const target = event.target as HTMLElement;
+    if (!target.matches(CONTROL)) return;
+    // 焦点到了哪一格（方向键走过去的，或者点的），停靠点就跟到哪一格
+    for (const control of event.currentTarget.querySelectorAll(CONTROL)) {
+      control.setAttribute("tabindex", control === target ? "0" : "-1");
+    }
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented || !KEYS.has(event.key)) return;
+    if (event.altKey || event.metaKey || event.shiftKey) return;
+    const ctrl = event.ctrlKey;
+    // Ctrl 只和 Home / End 配
+    if (ctrl && event.key !== "Home" && event.key !== "End") return;
+
+    const controls = [
+      ...event.currentTarget.querySelectorAll<HTMLElement>(ENABLED),
+    ];
+    const current = controls.indexOf(document.activeElement as HTMLElement);
+    if (current === -1) return;
+
+    // 网格是自动填充的，一行几格随宽度变：按格子此刻的实际位置算
+    const positions = controls.map((control) => {
+      const rect = control.getBoundingClientRect();
+      return { top: rect.top, left: rect.left };
+    });
+    const next = nextSlotIndex(positions, current, event.key, ctrl);
+
+    // 走到边上不动的时候也拦下来，免得页面跟着滚
+    event.preventDefault();
+    if (next !== current) controls[next]!.focus();
+  };
+
+  return (
+    <div
+      role="group"
+      {...props}
+      ref={mergeRefs(ref, forwardedRef)}
+      onFocus={handleFocus}
+      onKeyDown={handleKeyDown}
+      className={cn(
+        "grid grid-cols-[repeat(auto-fill,minmax(4.5rem,1fr))] gap-2 p-1",
+        className,
+      )}
+    />
+  );
+}