@endfield-ui/react 0.0.0-stage → 0.1.0

package/src/components/back-to-top/BackToTop.tsx

@@ -0,0 +1,124 @@
+import {
+  useCallback,
+  type ComponentProps,
+  type MouseEvent,
+  type RefObject,
+} from "react";
+import {
+  useScrollPosition,
+  type ScrollMetrics,
+} from "../../hooks/useScrollPosition";
+import { ArrowRight } from "../../icons/ArrowRight";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+
+export type BackToTopSize = "sm" | "md";
+
+export type BackToTopProps = Omit<
+  ComponentProps<"button">,
+  "children" | "aria-label"
+> & {
+  /** 默认"回到顶部" */
+  "aria-label"?: string;
+  /** 看哪个滚动容器、回到谁的顶部。不传就是整个页面 */
+  target?: RefObject<HTMLElement | null>;
+  /** 滚过多少像素才出现，默认 400 */
+  threshold?: number;
+  /** 48px（默认）或 40px 见方 */
+  size?: BackToTopSize;
+};
+
+const sizeClass: Record<BackToTopSize, string> = {
+  sm: "size-10 [&_svg]:size-5",
+  md: "size-12 [&_svg]:size-6",
+};
+
+/**
+ * 把焦点交给一个本来不能聚焦的元素：下一次 Tab 从它里面的头上开始。
+ * 它不是控件，所以不画焦点环；焦点一走就把临时加的东西收回来。
+ */
+function handFocusTo(node: HTMLElement) {
+  if (node.hasAttribute("tabindex")) {
+    node.focus({ preventScroll: true });
+    return;
+  }
+  const outline = node.style.outline;
+  node.setAttribute("tabindex", "-1");
+  node.style.outline = "none";
+  node.focus({ preventScroll: true });
+  node.addEventListener(
+    "blur",
+    () => {
+      node.removeAttribute("tabindex");
+      node.style.outline = outline;
+    },
+    { once: true },
+  );
+}
+
+/**
+ * 回到顶部：滚过一段才出现的悬浮钮，点了回到最上面，焦点也跟着回去。
+ * 默认看整个页面、自己 `fixed` 在视口右下角；放进某个滚动容器时传 `target`，
+ * 并用 `className` 把位置改成相对那个容器的。
+ */
+export function BackToTop({
+  "aria-label": ariaLabel = "回到顶部",
+  target,
+  threshold = 400,
+  size = "md",
+  type = "button",
+  className,
+  onClick,
+  ...props
+}: BackToTopProps) {
+  const scrolledFar = useCallback(
+    ({ scrolled }: ScrollMetrics) => scrolled > threshold,
+    [threshold],
+  );
+  const visible = useScrollPosition(target, scrolledFar, false);
+
+  const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
+    onClick?.(event);
+    if (event.defaultPrevented) return;
+
+    const element = target?.current ?? null;
+    // 脚本里显式要的平滑滚动不归 CSS 那条全局规则管，要自己看"减少动态效果"
+    const reduce =
+      typeof window.matchMedia === "function" &&
+      window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    const options: ScrollToOptions = {
+      top: 0,
+      behavior: reduce ? "instant" : "smooth",
+    };
+    if (element) element.scrollTo?.(options);
+    else window.scrollTo(options);
+
+    // 滚到顶之后这个钮会消失：焦点留在它身上就丢了，下一次 Tab 会从页尾开始
+    handFocusTo(element ?? document.body);
+  };
+
+  return (
+    <button
+      {...props}
+      type={type}
+      aria-label={ariaLabel}
+      data-visible={visible ? "" : undefined}
+      data-size={size}
+      onClick={handleClick}
+      className={cn(
+        "fixed right-[calc(1rem+env(safe-area-inset-right))] bottom-[calc(1rem+env(safe-area-inset-bottom))] z-(--z-float)",
+        "inline-flex shrink-0 items-center justify-center shadow-md",
+        // 反转填充：浮在任意内容上，两个主题下都和页面拉得开
+        "bg-surface-inverse text-ink-inverse hover:bg-action hover:text-on-action active:bg-action-pressed active:text-on-action",
+        "transition-[opacity,visibility,background-color,color] duration-(--duration-fast) ease-standard",
+        focusRing,
+        sizeClass[size],
+        // 没出现时 visibility 是 hidden：Tab 到不了，读屏也读不到
+        visible ? "visible opacity-100" : "invisible opacity-0",
+        className,
+      )}
+    >
+      <ArrowRight className="-rotate-90" />
+    </button>
+  );
+}

package/src/components/back-to-top/index.ts

@@ -0,0 +1,5 @@
+export {
+  BackToTop,
+  type BackToTopProps,
+  type BackToTopSize,
+} from "./BackToTop";

package/src/components/badge/Badge.tsx

@@ -0,0 +1,75 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type BadgeProps = Omit<ComponentProps<"span">, "children"> & {
+  /** 数量。显示为橙色数字块 */
+  count?: number;
+  /** 超过后显示为 `max+`，默认 99 */
+  max?: number;
+  /** `count` 为 0 时是否仍然显示，默认不显示 */
+  showZero?: boolean;
+  /** 不带数字的提醒：一个橙色菱形 */
+  dot?: boolean;
+  /** 给读屏的完整说明，如"12 条未读"。提供后角标本身对辅助技术隐藏 */
+  label?: string;
+  /** 被标记的元素。角标压在它的右上角，向外偏移半个自身 */
+  children?: ReactNode;
+};
+
+/** 通知角标：提醒与数量归橙色，不用来表示危险。 */
+export function Badge({
+  count,
+  max = 99,
+  showZero = false,
+  dot = false,
+  label,
+  className,
+  children,
+  ...props
+}: BadgeProps) {
+  let indicator: ReactNode = null;
+  if (dot) {
+    indicator = (
+      <span
+        aria-hidden="true"
+        className="block size-2 rotate-45 bg-notice"
+        data-badge="dot"
+      />
+    );
+  } else if (count !== undefined && (count > 0 || showZero)) {
+    indicator = (
+      <span
+        aria-hidden={label ? "true" : undefined}
+        className="inline-flex h-4.5 min-w-4.5 items-center justify-center bg-notice px-1 font-tech text-xs leading-none font-bold text-neutral-900 tabular-nums"
+        data-badge="count"
+      >
+        {count > max ? `${max}+` : count}
+      </span>
+    );
+  }
+
+  const visible = indicator !== null;
+  const description =
+    visible && label ? <span className="sr-only">{label}</span> : null;
+
+  if (children === undefined) {
+    return (
+      <span {...props} className={cn("inline-flex items-center", className)}>
+        {indicator}
+        {description}
+      </span>
+    );
+  }
+
+  return (
+    <span {...props} className={cn("relative inline-flex", className)}>
+      {children}
+      {visible && (
+        <span className="pointer-events-none absolute top-0 right-0 translate-x-1/2 -translate-y-1/2">
+          {indicator}
+          {description}
+        </span>
+      )}
+    </span>
+  );
+}

package/src/components/badge/index.ts

@@ -0,0 +1 @@
+export { Badge, type BadgeProps } from "./Badge";

package/src/components/bracket-title/BracketTitle.tsx

@@ -0,0 +1,40 @@
+import type { ComponentProps, ElementType, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type BracketTitleProps = Omit<ComponentProps<"h3">, "children"> & {
+  /** 标题层级，默认 3（`<h3>`） */
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** 名称 */
+  children: ReactNode;
+};
+
+const bracket = "font-medium text-ink-tertiary";
+
+/**
+ * 方括号标题 `[ 名称 ]`：人物、地点、物品的名称——"一个被归档的条目"。
+ * 普通的分节标题用 `SectionTitle`。字号用 `className` 改，默认是名称用的 `text-4xl`。
+ */
+export function BracketTitle({
+  level = 3,
+  className,
+  children,
+  ...props
+}: BracketTitleProps) {
+  const Heading: ElementType = `h${level}`;
+
+  return (
+    // 括号和名称排在同一行内而不是弹性盒里：名称换行时，右括号跟在最后一个字后面
+    <Heading
+      {...props}
+      className={cn("text-4xl font-bold wrap-anywhere text-ink", className)}
+    >
+      <span aria-hidden="true" className={cn(bracket, "mr-[0.4em]")}>
+        [
+      </span>
+      {children}
+      <span aria-hidden="true" className={cn(bracket, "ml-[0.4em]")}>
+        ]
+      </span>
+    </Heading>
+  );
+}

package/src/components/bracket-title/index.ts

@@ -0,0 +1 @@
+export { BracketTitle, type BracketTitleProps } from "./BracketTitle";

package/src/components/breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,161 @@
+import {
+  Children,
+  useEffect,
+  useRef,
+  useState,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+
+export type BreadcrumbProps = ComponentProps<"nav"> & {
+  /**
+   * 最多显示几项。超出时保留首项和靠后的几项，中间折叠成 `…`，点击展开。
+   * 不传则全部显示。
+   */
+  maxItems?: number;
+  /** 折叠按钮的可访问名称 */
+  expandLabel?: string;
+};
+
+function Separator() {
+  return (
+    <span
+      aria-hidden="true"
+      className="text-ink-tertiary [li:first-child>&]:hidden"
+    >
+      /
+    </span>
+  );
+}
+
+/** 层级路径：`// 档案 / 干员 / 详情`。双斜杠起头，单斜杠分隔。 */
+export function Breadcrumb({
+  maxItems,
+  expandLabel = "显示完整路径",
+  "aria-label": ariaLabel = "面包屑",
+  className,
+  children,
+  ...props
+}: BreadcrumbProps) {
+  const [expanded, setExpanded] = useState(false);
+  const listRef = useRef<HTMLOListElement>(null);
+  const justExpanded = useRef(false);
+
+  const items = Children.toArray(children);
+  const collapsed =
+    maxItems !== undefined &&
+    maxItems >= 2 &&
+    items.length > maxItems &&
+    !expanded;
+
+  // 展开后折叠按钮消失，把焦点交给第一个刚露出来的链接，键盘用户不会掉回页面开头
+  useEffect(() => {
+    if (!justExpanded.current) return;
+    justExpanded.current = false;
+    listRef.current
+      ?.querySelector<HTMLElement>("li:nth-child(2) a, li:nth-child(2) button")
+      ?.focus();
+  }, [expanded]);
+
+  let visible: ReactNode[] = items;
+  if (collapsed) {
+    visible = [
+      items[0],
+      <li key="ellipsis" className="flex items-center gap-2">
+        <Separator />
+        <button
+          type="button"
+          aria-label={expandLabel}
+          aria-expanded={false}
+          onClick={() => {
+            justExpanded.current = true;
+            setExpanded(true);
+          }}
+          className={cn(
+            "px-1 text-ink-secondary hover:text-ink",
+            "transition-colors duration-(--duration-fast) ease-standard",
+            focusRing,
+          )}
+        >
+          …
+        </button>
+      </li>,
+      ...items.slice(items.length - (maxItems - 1)),
+    ];
+  }
+
+  return (
+    <nav
+      {...props}
+      aria-label={ariaLabel}
+      className={cn("flex items-baseline gap-2 text-sm", className)}
+    >
+      <span aria-hidden="true" className="shrink-0 text-ink-tertiary">
+        {"//"}
+      </span>
+      <ol
+        ref={listRef}
+        className="flex min-w-0 flex-wrap items-baseline gap-x-2 gap-y-1"
+      >
+        {visible}
+      </ol>
+    </nav>
+  );
+}
+
+export type BreadcrumbItemProps = Omit<ComponentProps<"li">, "children"> & {
+  /** 传了就渲染成链接 */
+  href?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  /** 当前页：加粗、不可点击，输出 `aria-current="page"`。给最后一项 */
+  current?: boolean;
+  children: ReactNode;
+};
+
+export function BreadcrumbItem({
+  href,
+  render,
+  current = false,
+  className,
+  children,
+  ...props
+}: BreadcrumbItemProps) {
+  let content: ReactNode;
+  if (current) {
+    content = (
+      <span aria-current="page" className="font-bold text-ink">
+        {children}
+      </span>
+    );
+  } else if (href !== undefined || render !== undefined) {
+    content = (
+      <LinkElement
+        render={render}
+        href={href}
+        className={cn(
+          "text-ink-secondary underline-offset-4 hover:text-ink hover:underline",
+          "transition-colors duration-(--duration-fast) ease-standard",
+          focusRing,
+        )}
+      >
+        {children}
+      </LinkElement>
+    );
+  } else {
+    content = <span className="text-ink-secondary">{children}</span>;
+  }
+
+  return (
+    <li
+      {...props}
+      className={cn("flex min-w-0 items-baseline gap-2", className)}
+    >
+      <Separator />
+      {content}
+    </li>
+  );
+}

package/src/components/breadcrumb/index.ts

@@ -0,0 +1,6 @@
+export {
+  Breadcrumb,
+  BreadcrumbItem,
+  type BreadcrumbItemProps,
+  type BreadcrumbProps,
+} from "./Breadcrumb";