@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/page-header/PageHeader.tsx

@@ -0,0 +1,182 @@
+import type { ComponentProps, MouseEvent, ReactNode } from "react";
+import { ArrowLeft } from "../../icons/ArrowLeft";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+
+export type PageHeaderProps = Omit<ComponentProps<"header">, "title"> & {
+  /** 页面的标题 */
+  title: ReactNode;
+  /** 标题的层级，默认 1（`<h1>`）。页头用在抽屉、分栏里时改小 */
+  level?: 1 | 2 | 3;
+  /** 标题上面的微文字行，如 `// ARCHIVE　共 128 条` */
+  meta?: ReactNode;
+  /** 标题下面的一段说明 */
+  description?: ReactNode;
+  /** 最上面的层级路径：放一个 `Breadcrumb` */
+  breadcrumb?: ReactNode;
+  /** 标题左边的返回：放一个 `PageHeaderBack` */
+  back?: ReactNode;
+  /** 右边的行动区：几个按钮。放不下时折到标题下面 */
+  actions?: ReactNode;
+  /** 底下加一条分隔线 */
+  divider?: boolean;
+  /**
+   * 吸在滚动容器的顶上，带实底和底下那条线。
+   * 上面还有吸顶的顶栏时用 `className` 改 `top`
+   */
+  sticky?: boolean;
+  /** 标题下面的一行：页签、几个统计块 */
+  children?: ReactNode;
+};
+
+/**
+ * 页头：这是哪一页、怎么回去、在这一页能做什么。一页一个。
+ * 按自身的宽度响应：行动区放不下时折到标题下面。
+ */
+export function PageHeader({
+  title,
+  level = 1,
+  meta,
+  description,
+  breadcrumb,
+  back,
+  actions,
+  divider = false,
+  sticky = false,
+  className,
+  children,
+  ...props
+}: PageHeaderProps) {
+  const Heading = `h${level}` as const;
+
+  return (
+    <header
+      {...props}
+      data-sticky={sticky ? "" : undefined}
+      className={cn(
+        "@container flex flex-col gap-4 text-ink",
+        divider && !sticky && "border-b border-line pb-6",
+        sticky &&
+          "sticky top-0 z-(--z-float) border-b border-line bg-surface py-4",
+        className,
+      )}
+    >
+      {breadcrumb}
+      <div className="flex flex-col gap-1">
+        {meta && <p className="font-tech text-xs text-ink-secondary">{meta}</p>}
+        <div className="flex flex-wrap items-start justify-between gap-x-6 gap-y-4">
+          {/* 标题这一组至少留 16rem：行动区挤不进来就整块折下去，而不是把标题挤成一个字一行 */}
+          <div className="flex min-w-0 flex-1 basis-64 items-start gap-4">
+            {/*
+             * 标题的一行是 40px 高（宽了是 48px）。返回和行动区各放在同样高的一格里居中，
+             * 所以它们对的是标题的第一行——标题折成几行、下面有没有说明都一样
+             */}
+            {back && (
+              <div className="flex h-10 shrink-0 items-center @md:h-12">
+                {back}
+              </div>
+            )}
+            <div className="flex min-w-0 flex-col gap-1">
+              <Heading className="min-w-0 text-2xl leading-10 font-bold wrap-anywhere @md:text-3xl @md:leading-12">
+                {title}
+              </Heading>
+              {description && (
+                <p className="max-w-prose text-sm text-ink-secondary">
+                  {description}
+                </p>
+              )}
+            </div>
+          </div>
+          {actions && (
+            <div
+              data-actions=""
+              className="flex min-h-10 flex-wrap items-center gap-2 @md:min-h-12"
+            >
+              {actions}
+            </div>
+          )}
+        </div>
+      </div>
+      {children}
+    </header>
+  );
+}
+
+type BackOwnProps = {
+  /** 默认"返回"。建议写成"返回某某" */
+  "aria-label"?: string;
+  /** 传了就渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  disabled?: boolean;
+};
+
+export type PageHeaderBackProps = BackOwnProps &
+  Omit<ComponentProps<"button">, keyof BackOwnProps | "type" | "children">;
+
+/**
+ * 页头里的返回：40px 的深灰斜纹方块加一个左箭头，`back` 按钮收成的图标形态。
+ * 放进 `PageHeader` 的 `back`。
+ */
+export function PageHeaderBack({
+  "aria-label": label = "返回",
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  disabled = false,
+  className,
+  ...props
+}: PageHeaderBackProps) {
+  const classes = cn(
+    "relative inline-flex size-10 shrink-0 items-center justify-center",
+    "transition-colors duration-(--duration-fast) ease-standard",
+    focusRing,
+    disabled
+      ? "cursor-not-allowed bg-disabled text-on-disabled"
+      : // 有意不随主题翻转：和 back 按钮是同一块深灰
+        "hatch hatch-mid bg-control text-white shadow-xs hover:bg-neutral-600 active:bg-control-pressed",
+    className,
+  );
+  const icon = <ArrowLeft size={20} />;
+
+  if (href !== undefined || render !== undefined) {
+    return (
+      <LinkElement
+        render={render}
+        // 禁用的链接去掉 href，保留 link 角色，让读屏仍能读出"不可用"
+        href={disabled ? undefined : href}
+        role={disabled ? "link" : undefined}
+        aria-disabled={disabled || undefined}
+        aria-label={label}
+        target={target}
+        rel={rel}
+        onClick={disabled ? (event) => event.preventDefault() : onClick}
+        data-page-header-back=""
+        className={classes}
+      >
+        {icon}
+      </LinkElement>
+    );
+  }
+
+  return (
+    <button
+      {...props}
+      type="button"
+      aria-label={label}
+      disabled={disabled}
+      onClick={onClick}
+      data-page-header-back=""
+      className={classes}
+    >
+      {icon}
+    </button>
+  );
+}

package/src/components/page-header/index.ts

@@ -0,0 +1,6 @@
+export {
+  PageHeader,
+  PageHeaderBack,
+  type PageHeaderBackProps,
+  type PageHeaderProps,
+} from "./PageHeader";

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";

package/src/components/panel/Panel.tsx

@@ -0,0 +1,114 @@
+import type { ComponentProps, ElementType, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type PanelProps = ComponentProps<"div"> & {
+  /** 1px 描边，默认有。关掉后只靠底色差分层 */
+  bordered?: boolean;
+};
+
+/** 围住一组信息的容器：直角、底色只比页面差一档、没有阴影。不要面板套面板。 */
+export function Panel({ bordered = true, className, ...props }: PanelProps) {
+  return (
+    <div
+      {...props}
+      className={cn(
+        "bg-surface-raised text-ink",
+        bordered && "border border-line",
+        className,
+      )}
+    />
+  );
+}
+
+export type PanelHeaderVariant = "band" | "line";
+
+export type PanelHeaderProps = Omit<ComponentProps<"div">, "title"> & {
+  /**
+   * - `band` 反转的横带 + 左端短竖条，默认。它是一个 `data-theme="inverse"` 的
+   *   局部主题：里面的按钮、标签、焦点环都按这条带子的底色取值；
+   * - `line` 只有一条细线和小标题，更轻。同一个界面选一种。
+   */
+  variant?: PanelHeaderVariant;
+  /** 标题右侧的计数或一个小操作 */
+  extra?: ReactNode;
+  /** 标题层级，默认 3（`<h3>`） */
+  level?: 2 | 3 | 4 | 5 | 6;
+};
+
+export function PanelHeader({
+  variant = "band",
+  extra,
+  level = 3,
+  className,
+  children,
+  ...props
+}: PanelHeaderProps) {
+  const Heading: ElementType = `h${level}`;
+
+  return (
+    <div
+      // 标题带和页面相反：整条换成反转主题，下面照常用 surface / ink
+      data-theme={variant === "band" ? "inverse" : undefined}
+      {...props}
+      className={cn(
+        "relative flex items-center justify-between gap-3 px-4 text-sm font-medium text-ink",
+        variant === "band"
+          ? "min-h-8 bg-surface"
+          : "min-h-10 border-b border-line",
+        className,
+      )}
+    >
+      {variant === "band" && (
+        // 亮色页面上是黄条压墨底，暗色页面上是深黄条压近白底
+        <span
+          aria-hidden="true"
+          className="absolute top-1/2 left-0 h-4 w-1 -translate-y-1/2 bg-accent-ink"
+        />
+      )}
+      <Heading className="min-w-0 truncate">{children}</Heading>
+      {extra && <div className="flex shrink-0 items-center gap-2">{extra}</div>}
+    </div>
+  );
+}
+
+export type PanelBodyProps = ComponentProps<"div">;
+
+export function PanelBody({ className, ...props }: PanelBodyProps) {
+  return <div {...props} className={cn("p-4", className)} />;
+}
+
+export type PanelRowsProps = ComponentProps<"dl">;
+
+/** 属性行的容器。里面只放 `PanelRow`。 */
+export function PanelRows({ className, ...props }: PanelRowsProps) {
+  return <dl {...props} className={cn("px-4", className)} />;
+}
+
+export type PanelRowProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 属性名，左对齐 */
+  label: ReactNode;
+  /** 属性值，右对齐、等宽、加粗 */
+  children: ReactNode;
+};
+
+export function PanelRow({
+  label,
+  children,
+  className,
+  ...props
+}: PanelRowProps) {
+  return (
+    <div
+      {...props}
+      className={cn(
+        "flex items-baseline justify-between gap-4 border-b border-line py-2.5 last:border-b-0",
+        className,
+      )}
+    >
+      <dt className="text-sm text-ink-secondary">{label}</dt>
+      <dd className="text-right font-tech text-sm font-bold text-ink tabular-nums">
+        {children}
+      </dd>
+    </div>
+  );
+}

package/src/components/panel/index.ts

@@ -0,0 +1,13 @@
+export {
+  Panel,
+  PanelBody,
+  PanelHeader,
+  PanelRow,
+  PanelRows,
+  type PanelBodyProps,
+  type PanelHeaderProps,
+  type PanelHeaderVariant,
+  type PanelProps,
+  type PanelRowProps,
+  type PanelRowsProps,
+} from "./Panel";

package/src/components/play-button/PlayButton.tsx

@@ -0,0 +1,92 @@
+import type { ComponentProps } from "react";
+import { TriangleRight } from "../../icons/TriangleRight";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+
+export type PlayMarkSize = "sm" | "md" | "lg";
+
+/* 24 / 32 / 40px，三角占一半 */
+const boxSize: Record<PlayMarkSize, string> = {
+  sm: "size-6 [&_svg]:size-3",
+  md: "size-8 [&_svg]:size-4",
+  lg: "size-10 [&_svg]:size-5",
+};
+
+/*
+ * 黄色小方块 + 墨色三角。有意不随主题变：它压在图上。
+ * 黄色压在浅色的图上边界不清楚，认它靠的是里面的三角。
+ */
+const markBase =
+  "inline-flex shrink-0 items-center justify-center rounded-xs bg-action text-on-action";
+
+export type PlayMarkProps = Omit<ComponentProps<"span">, "children"> & {
+  size?: PlayMarkSize;
+};
+
+/**
+ * 播放记号：只是一个记号，不能点，对读屏隐藏。
+ * 整张卡已经是一个链接时用它（媒体卡的 `video`）；要它自己能点用 `PlayButton`。
+ */
+export function PlayMark({ size = "md", className, ...props }: PlayMarkProps) {
+  return (
+    <span
+      aria-hidden="true"
+      {...props}
+      data-size={size}
+      className={cn(markBase, boxSize[size], className)}
+    >
+      <TriangleRight />
+    </span>
+  );
+}
+
+export type PlayButtonProps = Omit<
+  ComponentProps<"button">,
+  "children" | "aria-label"
+> & {
+  /** 默认"播放"。一页有好几个时写明播的是什么 */
+  "aria-label"?: string;
+  size?: PlayMarkSize;
+};
+
+/** 播放钮：和播放记号同一个画法的按钮，给"点了就在原地播放"的封面用。 */
+export function PlayButton({
+  "aria-label": ariaLabel = "播放",
+  size = "md",
+  type = "button",
+  disabled = false,
+  className,
+  ...props
+}: PlayButtonProps) {
+  return (
+    <button
+      {...props}
+      type={type}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      data-size={size}
+      className={cn(
+        "group relative",
+        markBase,
+        boxSize[size],
+        "transition-colors duration-(--duration-fast) ease-standard",
+        focusRing,
+        // 24px 小于触屏的最小点击区，用伪元素向外补到 40px
+        size === "sm" && "after:absolute after:-inset-2 after:content-['']",
+        disabled
+          ? "cursor-not-allowed bg-disabled text-on-disabled"
+          : "active:bg-action-pressed",
+        className,
+      )}
+    >
+      {/* 悬停：记号让一步，和按钮的竖条变箭头是同一种做法 */}
+      <TriangleRight
+        className={cn(
+          "transition-[translate] duration-(--duration-base) ease-standard",
+          !disabled &&
+            "group-hover:translate-x-0.5 group-active:translate-x-0.5",
+        )}
+      />
+    </button>
+  );
+}

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

@@ -0,0 +1,7 @@
+export {
+  PlayButton,
+  PlayMark,
+  type PlayButtonProps,
+  type PlayMarkProps,
+  type PlayMarkSize,
+} from "./PlayButton";