@endfield-ui/react 0.0.0-stage → 0.1.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/pagination/Pagination.tsx

@@ -0,0 +1,181 @@
+import {
+  useState,
+  type ChangeEvent,
+  type ComponentProps,
+  type KeyboardEvent,
+} from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { ChevronLeft } from "../../icons/ChevronLeft";
+import { ChevronRight } from "../../icons/ChevronRight";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import { IconButton, type IconButtonSize } from "../icon-button/IconButton";
+
+export type PaginationSize = "md" | "lg";
+
+export type PaginationProps = Omit<
+  ComponentProps<"nav">,
+  "children" | "onChange"
+> & {
+  /** 受控的当前页，从 1 起 */
+  page?: number;
+  /** 非受控时的初始页，默认 1 */
+  defaultPage?: number;
+  onPageChange?: (page: number) => void;
+  /** 总页数 */
+  pageCount: number;
+  /** 页码处换成输入框：输入页码后回车或失焦跳页，Esc 还原 */
+  jump?: boolean;
+  /** 条高 48 或 56px */
+  size?: PaginationSize;
+  prevLabel?: string;
+  nextLabel?: string;
+  /** 跳页输入框的可访问名称 */
+  jumpLabel?: string;
+  /** 读屏听到的当前位置，默认"第 1 页，共 12 页" */
+  pageLabel?: (page: number, pageCount: number) => string;
+};
+
+const barSize: Record<PaginationSize, string> = {
+  md: "h-12",
+  lg: "h-14",
+};
+
+/* 方钮比条高小 8px */
+const buttonSize: Record<PaginationSize, IconButtonSize> = {
+  md: "md",
+  lg: "lg",
+};
+
+const defaultPageLabel = (page: number, pageCount: number) =>
+  `第 ${page} 页，共 ${pageCount} 页`;
+
+/**
+ * 分页条：浅灰斜纹条，两端是方钮，中间是 `01 / 12`。
+ * 不列一长串数字按钮；要跳页就打开 `jump`，在页码处直接输入。
+ */
+export function Pagination({
+  page,
+  defaultPage = 1,
+  onPageChange,
+  pageCount,
+  jump = false,
+  size = "md",
+  prevLabel = "上一页",
+  nextLabel = "下一页",
+  jumpLabel = "跳到第几页",
+  pageLabel = defaultPageLabel,
+  className,
+  ...props
+}: PaginationProps) {
+  const total = Math.max(1, Math.floor(pageCount));
+  const clamp = (next: number) => Math.min(Math.max(next, 1), total);
+
+  const [inner, setPage] = useControllableState({
+    value: page,
+    defaultValue: defaultPage,
+    onChange: onPageChange,
+  });
+  const current = clamp(inner);
+
+  // 输入到一半的页码：不为 null 时输入框显示它
+  const [draft, setDraft] = useState<string | null>(null);
+
+  // 至少两位，补零；总页数上百时跟着加宽
+  const digits = Math.max(2, String(total).length);
+  const pad = (value: number) => String(value).padStart(digits, "0");
+
+  const go = (next: number) => setPage(clamp(next));
+
+  const commitDraft = () => {
+    if (draft === null) return;
+    const typed = Number.parseInt(draft, 10);
+    setDraft(null);
+    if (Number.isFinite(typed)) go(typed);
+  };
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    setDraft(event.target.value.replace(/\D/g, "").slice(0, digits + 1));
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === "Enter") {
+      event.preventDefault();
+      commitDraft();
+    } else if (event.key === "Escape") {
+      setDraft(null);
+    }
+  };
+
+  const squareClass = "bg-surface-raised shadow-sm";
+
+  return (
+    <nav
+      aria-label="分页"
+      {...props}
+      data-size={size}
+      className={cn(
+        "@container hatch flex items-center justify-between gap-2 bg-surface-muted px-1 text-ink",
+        barSize[size],
+        className,
+      )}
+    >
+      <IconButton
+        variant="accent"
+        size={buttonSize[size]}
+        aria-label={prevLabel}
+        disabled={current <= 1}
+        onClick={() => go(current - 1)}
+        className={squareClass}
+      >
+        <ChevronLeft />
+      </IconButton>
+
+      {/* 很窄的容器里页码小一档，三位数的页码才放得下 */}
+      <div className="flex min-w-0 items-center gap-2 font-display text-base leading-none whitespace-nowrap tabular-nums @2xs:text-lg">
+        {/* 看得见的 01 / 12 对读屏隐藏，换成一句完整的话，翻页时播报 */}
+        <span className="sr-only" aria-live="polite">
+          {pageLabel(current, total)}
+        </span>
+        {jump ? (
+          <input
+            type="text"
+            inputMode="numeric"
+            autoComplete="off"
+            aria-label={jumpLabel}
+            value={draft ?? pad(current)}
+            onChange={handleChange}
+            onKeyDown={handleKeyDown}
+            onBlur={commitDraft}
+            onFocus={(event) => event.target.select()}
+            style={{ width: `calc(${digits}ch + 0.75rem)` }}
+            className={cn(
+              "h-8 border-b-2 border-line-strong bg-surface-raised text-center font-bold text-ink",
+              "transition-colors duration-(--duration-fast) ease-standard",
+              "hover:not-focus:border-ink-secondary focus:border-ink",
+              focusRing,
+            )}
+          />
+        ) : (
+          <span aria-hidden="true" className="font-bold">
+            {pad(current)}
+          </span>
+        )}
+        <span aria-hidden="true" className="font-medium text-ink-secondary">
+          {`/ ${pad(total)}`}
+        </span>
+      </div>
+
+      <IconButton
+        variant="accent"
+        size={buttonSize[size]}
+        aria-label={nextLabel}
+        disabled={current >= total}
+        onClick={() => go(current + 1)}
+        className={squareClass}
+      >
+        <ChevronRight />
+      </IconButton>
+    </nav>
+  );
+}

package/src/components/pagination/index.ts

@@ -0,0 +1,5 @@
+export {
+  Pagination,
+  type PaginationProps,
+  type PaginationSize,
+} from "./Pagination";