@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/nav-menu/NavMenu.tsx

@@ -0,0 +1,288 @@
+import { Dialog as BaseDialog } from "@base-ui/react/dialog";
+import {
+  createContext,
+  useContext,
+  useRef,
+  type ComponentProps,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { ArrowRight } from "../../icons/ArrowRight";
+import { Close } from "../../icons/Close";
+import { cn } from "../../lib/cn";
+import { focusRingInset } from "../../lib/focus-ring";
+import { firstFocusableIn } from "../dialog/initial-focus";
+import { GhostText } from "../ghost-text/GhostText";
+import { IconButton } from "../icon-button/IconButton";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+import { NavActionContext } from "../nav-action/NavAction";
+
+/** 导航项点了之后要把菜单关上 */
+const NavMenuContext = createContext<() => void>(() => {});
+
+export type NavMenuProps = {
+  /** 菜单钮，通常是顶栏最右边的 `<IconButton>`。不传就用 `open` / `onOpenChange` 自己控制 */
+  trigger?: ReactElement<Record<string, unknown>>;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 菜单的名称，读屏打开时读它。没有 `brand` 时也显示在最上面一行 */
+  title: ReactNode;
+  /** 最上面一行左边的标志，通常和顶栏的是同一个 */
+  brand?: ReactNode;
+  /** 导航项下面的一排工具按钮 */
+  tools?: ReactNode;
+  /** 底部通宽的按钮：放一到两个 `NavAction` */
+  footer?: ReactNode;
+  /** 背景底部的一行镂空巨字，纯装饰。写一个短词 */
+  ghost?: string;
+  /** 里面那组栏目的名称 */
+  navLabel?: string;
+  /** 关闭钮的可访问名称 */
+  closeLabel?: string;
+  /** 给整块面板 */
+  className?: string;
+  /** `NavMenuItem` */
+  children: ReactNode;
+};
+
+/**
+ * 全屏菜单：窄屏上顶栏的菜单钮打开的那一整屏栏目。
+ * 打开时焦点移入并被限制在内、背景不可滚动；`Esc` 关闭，焦点回到菜单钮。
+ */
+export function NavMenu({
+  trigger,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  title,
+  brand,
+  tools,
+  footer,
+  ghost,
+  navLabel = "主导航",
+  closeLabel = "关闭菜单",
+  className,
+  children,
+}: NavMenuProps) {
+  const [isOpen, setOpen] = useControllableState({
+    value: open,
+    defaultValue: defaultOpen,
+    onChange: onOpenChange,
+  });
+  const { anchorRef, portalRef } = usePortalScope();
+  const bodyRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <BaseDialog.Root open={isOpen} onOpenChange={(next) => setOpen(next)}>
+      {trigger && <BaseDialog.Trigger ref={anchorRef} render={trigger} />}
+      <BaseDialog.Portal ref={portalRef}>
+        <BaseDialog.Popup
+          // 焦点先落在第一个栏目上，而不是关闭钮
+          initialFocus={firstFocusableIn(bodyRef)}
+          className={cn(
+            "fixed inset-0 z-(--z-overlay) flex flex-col overflow-hidden bg-surface text-ink outline-none",
+            "transition-opacity duration-(--duration-fast) ease-standard",
+            "data-ending-style:opacity-0 data-starting-style:opacity-0",
+            className,
+          )}
+        >
+          {/* 和顶栏等高：关闭钮正好落在菜单钮的位置上 */}
+          <div className="flex h-14 shrink-0 items-center gap-2 border-b border-line bg-surface px-4">
+            <div className="flex min-w-0 flex-1 items-center">
+              {brand}
+              <BaseDialog.Title
+                className={brand ? "sr-only" : "truncate text-base font-medium"}
+              >
+                {title}
+              </BaseDialog.Title>
+            </div>
+            <BaseDialog.Close
+              render={
+                <IconButton aria-label={closeLabel}>
+                  <Close />
+                </IconButton>
+              }
+            />
+          </div>
+
+          <div
+            ref={bodyRef}
+            className="flex min-h-0 flex-1 flex-col overflow-y-auto overscroll-contain"
+          >
+            <NavMenuContext value={() => setOpen(false)}>
+              <nav aria-label={navLabel}>
+                <ul className="flex flex-col gap-1 p-4">{children}</ul>
+              </nav>
+            </NavMenuContext>
+
+            {tools && (
+              <div className="mx-4 flex flex-wrap gap-1 bg-surface-muted p-1">
+                {tools}
+              </div>
+            )}
+
+            {/* 栏目和底部按钮之间的空白。巨字贴着它的下沿，下半截裁掉 */}
+            <div
+              aria-hidden="true"
+              className={cn(
+                "relative flex-1 overflow-hidden",
+                ghost && "min-h-20",
+              )}
+            >
+              {ghost && (
+                <GhostText
+                  variant="outline"
+                  className="absolute bottom-0 left-4 translate-y-1/4"
+                >
+                  {ghost}
+                </GhostText>
+              )}
+            </div>
+
+            {footer && (
+              <div className="flex shrink-0 flex-col gap-2 p-4">
+                <NavActionContext value="block">{footer}</NavActionContext>
+              </div>
+            )}
+          </div>
+        </BaseDialog.Popup>
+      </BaseDialog.Portal>
+    </BaseDialog.Root>
+  );
+}
+
+type ItemOwnProps = {
+  /** 图标，后面跟一条竖向的分隔线 */
+  icon?: ReactNode;
+  /** 当前所在的栏目：整条变信号黄，输出 `aria-current="page"` */
+  current?: boolean;
+  disabled?: boolean;
+  /** 点了之后是否关掉菜单，默认关 */
+  closeOnClick?: boolean;
+  /** 传了就渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  /** 没有 `href` 和 `render` 时渲染成按钮 */
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  children: ReactNode;
+};
+
+export type NavMenuItemProps = ItemOwnProps &
+  Omit<ComponentProps<"li">, keyof ItemOwnProps>;
+
+/** 全屏菜单里的一个栏目。 */
+export function NavMenuItem({
+  icon,
+  current = false,
+  disabled = false,
+  closeOnClick = true,
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  children,
+  ...props
+}: NavMenuItemProps) {
+  const close = useContext(NavMenuContext);
+  const isLink = href !== undefined || render !== undefined;
+
+  const handleClick = (event: MouseEvent<HTMLElement>) => {
+    if (disabled) {
+      event.preventDefault();
+      return;
+    }
+    onClick?.(event);
+    if (closeOnClick) close();
+  };
+
+  const classes = cn(
+    "relative flex h-14 w-full items-center gap-3 px-4 text-left text-base font-medium",
+    "transition-colors duration-(--duration-fast) ease-standard",
+    disabled
+      ? "cursor-not-allowed bg-surface-sunken text-ink-disabled"
+      : current
+        ? [
+            // 黄和旁边的浅灰明度很接近：另加粗体和左缘一条墨色竖条，不只靠颜色
+            "bg-action font-bold text-on-action",
+            "before:absolute before:inset-y-0 before:left-0 before:w-1 before:bg-on-action before:content-['']",
+            // 普通的焦点色在暗色主题下也是黄的，压在黄底上看不见
+            "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-on-action",
+          ]
+        : [
+            "bg-surface-sunken text-ink hover:bg-surface-muted active:bg-line",
+            focusRingInset,
+          ],
+  );
+
+  const mark = disabled
+    ? "text-ink-disabled"
+    : current
+      ? "text-on-action"
+      : "text-ink-secondary";
+
+  const content = (
+    <>
+      {icon && (
+        <>
+          <span
+            aria-hidden="true"
+            className={cn(
+              "flex size-6 shrink-0 items-center justify-center [&_svg]:size-5",
+              mark,
+            )}
+          >
+            {icon}
+          </span>
+          <span
+            aria-hidden="true"
+            className={cn(
+              "h-5 w-px shrink-0",
+              current && !disabled ? "bg-on-action" : "bg-line-strong",
+            )}
+          />
+        </>
+      )}
+      <span className="min-w-0 flex-1 truncate">{children}</span>
+      <ArrowRight size={16} className={cn("shrink-0", mark)} />
+    </>
+  );
+
+  return (
+    <li {...props}>
+      {isLink ? (
+        <LinkElement
+          render={render}
+          // 禁用的链接去掉 href，保留 link 角色，让读屏仍能读出"不可用"
+          href={disabled ? undefined : href}
+          role={disabled ? "link" : undefined}
+          aria-disabled={disabled || undefined}
+          target={target}
+          rel={rel}
+          aria-current={current ? "page" : undefined}
+          onClick={handleClick}
+          className={classes}
+        >
+          {content}
+        </LinkElement>
+      ) : (
+        <button
+          type="button"
+          disabled={disabled}
+          aria-current={current ? "page" : undefined}
+          onClick={handleClick}
+          className={classes}
+        >
+          {content}
+        </button>
+      )}
+    </li>
+  );
+}

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

@@ -0,0 +1,6 @@
+export {
+  NavMenu,
+  NavMenuItem,
+  type NavMenuItemProps,
+  type NavMenuProps,
+} from "./NavMenu";

package/src/components/navigator/Navigator.tsx

@@ -0,0 +1,136 @@
+import type { ComponentProps, ReactNode } from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { ChevronLeft } from "../../icons/ChevronLeft";
+import { ChevronRight } from "../../icons/ChevronRight";
+import { cn } from "../../lib/cn";
+import { IconButton, type IconButtonSize } from "../icon-button/IconButton";
+
+export type NavigatorSize = "sm" | "md";
+
+export type NavigatorProps = Omit<
+  ComponentProps<"div">,
+  "children" | "onChange"
+> & {
+  /** 各条目的名称，按顺序 */
+  items: ReactNode[];
+  /** 受控的当前条目，从 0 起 */
+  index?: number;
+  /** 非受控时的初始条目，默认 0 */
+  defaultIndex?: number;
+  onIndexChange?: (index: number) => void;
+  /** 首尾相接：到最后一项再往后回到第一项。默认到头时按钮禁用 */
+  loop?: boolean;
+  /** 40 或 56px 高 */
+  size?: NavigatorSize;
+  prevLabel?: string;
+  nextLabel?: string;
+  /** 读屏听到的当前位置，默认"第 1 项，共 4 项" */
+  positionLabel?: (position: number, count: number) => string;
+};
+
+const boxSize: Record<NavigatorSize, string> = {
+  sm: "h-10 gap-1 p-1 text-sm",
+  md: "h-14 gap-2 p-2 text-base",
+};
+
+const buttonSize: Record<NavigatorSize, IconButtonSize> = {
+  sm: "sm",
+  md: "md",
+};
+
+const defaultPositionLabel = (position: number, count: number) =>
+  `第 ${position} 项，共 ${count} 项`;
+
+/**
+ * 胶囊导航器：在少量条目间前后切换，并显示当前条目的名称。
+ * 用 `aria-label` 说明翻的是什么（"勘探区"）。
+ */
+export function Navigator({
+  items,
+  index,
+  defaultIndex = 0,
+  onIndexChange,
+  loop = false,
+  size = "md",
+  prevLabel = "上一项",
+  nextLabel = "下一项",
+  positionLabel = defaultPositionLabel,
+  className,
+  ...props
+}: NavigatorProps) {
+  const count = items.length;
+  const [inner, setIndex] = useControllableState({
+    value: index,
+    defaultValue: defaultIndex,
+    onChange: onIndexChange,
+  });
+  const current = Math.min(Math.max(inner, 0), Math.max(count - 1, 0));
+
+  const go = (next: number) => {
+    if (count === 0) return;
+    setIndex(
+      loop ? (next + count) % count : Math.min(Math.max(next, 0), count - 1),
+    );
+  };
+
+  const single = count <= 1;
+
+  return (
+    <div
+      role="group"
+      {...props}
+      data-size={size}
+      className={cn(
+        "inline-flex max-w-full items-center rounded-full bg-surface-muted text-ink",
+        boxSize[size],
+        className,
+      )}
+    >
+      <IconButton
+        variant="floating"
+        size={buttonSize[size]}
+        aria-label={prevLabel}
+        disabled={single || (!loop && current === 0)}
+        onClick={() => go(current - 1)}
+      >
+        <ChevronLeft />
+      </IconButton>
+
+      <div
+        aria-live="polite"
+        aria-atomic="true"
+        className="flex min-w-0 flex-1 items-baseline justify-center gap-2 px-2"
+      >
+        <span className="shrink-0 font-tech text-xs font-bold text-accent-ink tabular-nums">
+          <span aria-hidden="true">{`${count === 0 ? 0 : current + 1}/${count}`}</span>
+          <span className="sr-only">{positionLabel(current + 1, count)}</span>
+        </span>
+        {/* 所有名称叠在同一格里，按最宽的定宽：翻动时两端的按钮不跑位 */}
+        <span className="grid min-w-0">
+          {items.map((item, position) => (
+            <span
+              key={position}
+              data-current={position === current ? "" : undefined}
+              className={cn(
+                "col-start-1 row-start-1 truncate text-center",
+                position !== current && "invisible",
+              )}
+            >
+              {item}
+            </span>
+          ))}
+        </span>
+      </div>
+
+      <IconButton
+        variant="floating"
+        size={buttonSize[size]}
+        aria-label={nextLabel}
+        disabled={single || (!loop && current === count - 1)}
+        onClick={() => go(current + 1)}
+      >
+        <ChevronRight />
+      </IconButton>
+    </div>
+  );
+}

package/src/components/navigator/index.ts

@@ -0,0 +1,5 @@
+export {
+  Navigator,
+  type NavigatorProps,
+  type NavigatorSize,
+} from "./Navigator";

package/src/components/otp-input/OtpInput.tsx

@@ -0,0 +1,211 @@
+import { OTPField as BaseOtpField } from "@base-ui/react/otp-field";
+import { Fragment, useId, type ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import { useFieldContext, useFieldControl } from "../field/Field";
+import type { ControlSize, ControlVariant } from "../input/control-box";
+
+export type OtpInputType = "numeric" | "alphanumeric";
+export type OtpInputSize = ControlSize;
+export type OtpInputVariant = ControlVariant;
+
+export type OtpInputProps = Omit<
+  ComponentProps<"div">,
+  "onChange" | "defaultValue" | "children"
+> & {
+  /** 一共几位，默认 6 */
+  length?: number;
+  /** 拼起来的那一串 */
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  /** 每一位都填上了。粘贴一整串也算 */
+  onComplete?: (value: string) => void;
+  /** 收哪些字符：`numeric` 只收数字，默认；`alphanumeric` 收字母和数字 */
+  type?: OtpInputType;
+  /** 字母统一成大写：值也是大写，不只是看起来 */
+  uppercase?: boolean;
+  /** 把填进去的字遮成圆点 */
+  mask?: boolean;
+  /** 每几格之间加一道短横，如 6 位的码写 `3` 分成两组。只是画的 */
+  groupSize?: number;
+  /** 32 / 40 / 56px 见方 */
+  size?: OtpInputSize;
+  /** 同输入框：`sunken` 凹陷的底 + 底边线，默认；`outline` 四边描边 */
+  variant?: OtpInputVariant;
+  /** 错误态：每一格的边线变红。放在 `Field` 里时跟随它的 `error` */
+  invalid?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  /** 传了就有一个隐藏字段随表单提交，值是拼起来的那一串 */
+  name?: string;
+  form?: string;
+  /** 填满就提交所在的表单 */
+  autoSubmit?: boolean;
+  /** 挂载后焦点落在第一格 */
+  autoFocus?: boolean;
+  /** 第二格起每一格的可访问名称，默认"第 2 位，共 6 位"。第一格的名称是字段的标签 */
+  slotLabel?: (position: number, length: number) => string;
+};
+
+/* 格子见方；容器窄了宽度可以让，高度不变 */
+const slotSize: Record<ControlSize, string> = {
+  sm: "h-8 w-8 text-base",
+  md: "h-10 w-10 text-lg",
+  lg: "h-14 w-14 text-2xl",
+};
+
+const slotFrame: Record<ControlVariant, string> = {
+  sunken: "border-b-2",
+  outline: "border",
+};
+
+const slotFill: Record<ControlVariant, string> = {
+  sunken: "bg-surface-sunken",
+  outline: "bg-surface",
+};
+
+const gapClass: Record<ControlSize, string> = {
+  sm: "gap-1.5",
+  md: "gap-2",
+  lg: "gap-2",
+};
+
+const defaultSlotLabel = (position: number, length: number) =>
+  `第 ${position} 位，共 ${length} 位`;
+
+const toUpperCase = (value: string) => value.toUpperCase();
+
+/**
+ * 验证码输入：一格一位的短码。每一格是一个真的输入框——打一位跳一格，
+ * 粘贴一整串会分到各格，整组在 Tab 顺序里只停一次。
+ *
+ * 每个都要有标签：放进 `Field`，或者自己传 `aria-label`。
+ * `className` 与 `ref` 给外面那一排。
+ */
+export function OtpInput({
+  length = 6,
+  value,
+  defaultValue,
+  onValueChange,
+  onComplete,
+  type = "numeric",
+  uppercase = false,
+  mask = false,
+  groupSize,
+  size = "md",
+  variant = "sunken",
+  invalid: invalidProp,
+  id: idProp,
+  disabled: disabledProp,
+  required: requiredProp,
+  readOnly = false,
+  name,
+  form,
+  autoSubmit = false,
+  autoFocus = false,
+  slotLabel = defaultSlotLabel,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": describedByProp,
+  className,
+  ...props
+}: OtpInputProps) {
+  const fieldContext = useFieldContext();
+  const { id, disabled, required, invalid, ...field } = useFieldControl({
+    id: idProp,
+    disabled: disabledProp,
+    required: requiredProp,
+    invalid: invalidProp,
+    "aria-describedby": describedByProp,
+  });
+  const describedBy = field["aria-describedby"];
+
+  // 基元不认第一格上的 aria-label（它要一个真的标签）：自己传名称时，
+  // 把它写成一段隐藏的文字，让第一格和整组都指过去
+  const labelId = useId();
+  const ownLabel = ariaLabelledBy ?? (ariaLabel ? labelId : undefined);
+  const groupLabel = ownLabel ?? fieldContext?.labelId;
+
+  const slotClass = cn(
+    "min-w-0 shrink text-center font-tech font-medium tabular-nums text-ink caret-ink",
+    "transition-colors duration-(--duration-fast) ease-standard",
+    focusRing,
+    slotSize[size],
+    slotFrame[variant],
+    readOnly
+      ? // 只读：没有边线、底变透明。边线留透明的，尺寸不跳
+        "border-transparent bg-transparent"
+      : slotFill[variant],
+    disabled
+      ? "cursor-not-allowed border-line text-ink-disabled"
+      : invalid
+        ? "border-danger"
+        : !readOnly &&
+          // 悬停只在没聚焦时生效：聚焦中的格子不会因为鼠标经过而变浅
+          "border-line-strong hover:not-focus:border-ink-secondary focus:border-ink",
+  );
+
+  const group = groupSize !== undefined && groupSize > 0 ? groupSize : 0;
+
+  return (
+    <BaseOtpField.Root
+      {...props}
+      id={id}
+      length={length}
+      value={value}
+      defaultValue={defaultValue}
+      onValueChange={onValueChange && ((next) => onValueChange(next))}
+      onValueComplete={onComplete && ((next) => onComplete(next))}
+      validationType={type}
+      normalizeValue={uppercase ? toUpperCase : undefined}
+      mask={mask}
+      disabled={disabled}
+      readOnly={readOnly}
+      required={required}
+      name={name}
+      form={form}
+      autoSubmit={autoSubmit}
+      aria-labelledby={groupLabel}
+      aria-describedby={describedBy}
+      data-size={size}
+      data-variant={variant}
+      data-invalid={invalid ? "" : undefined}
+      className={cn(
+        // 不许比容器宽：放在"靠左对齐"的弹性容器里时它是按内容定宽的，
+        // 没有这一条格子就不会收窄，而是整排伸出去
+        "flex max-w-full min-w-0 items-center",
+        gapClass[size],
+        className,
+      )}
+    >
+      {ariaLabel && !ariaLabelledBy && (
+        <span id={labelId} hidden>
+          {ariaLabel}
+        </span>
+      )}
+      {Array.from({ length }, (_, index) => (
+        <Fragment key={index}>
+          {group > 0 && index > 0 && index % group === 0 && (
+            <span
+              aria-hidden="true"
+              data-separator=""
+              className="h-0.5 w-2 shrink-0 bg-line-strong"
+            />
+          )}
+          <BaseOtpField.Input
+            // 第一格的名称是字段的标签（或者上面那段隐藏的文字），说明文字也挂在它上面
+            {...(index === 0
+              ? { "aria-labelledby": ownLabel, "aria-describedby": describedBy }
+              : { "aria-label": slotLabel(index + 1, length) })}
+            aria-invalid={invalid || undefined}
+            autoFocus={autoFocus && index === 0}
+            autoCapitalize={uppercase ? "characters" : "none"}
+            className={slotClass}
+          />
+        </Fragment>
+      ))}
+    </BaseOtpField.Root>
+  );
+}

package/src/components/otp-input/index.ts

@@ -0,0 +1,7 @@
+export {
+  OtpInput,
+  type OtpInputProps,
+  type OtpInputSize,
+  type OtpInputType,
+  type OtpInputVariant,
+} from "./OtpInput";