@endfield-ui/react 0.0.0-stage → 0.1.0

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

package/src/components/popover/Popover.tsx

@@ -0,0 +1,105 @@
+import { Popover as BasePopover } from "@base-ui/react/popover";
+import type { ComponentProps, ReactElement, ReactNode } from "react";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { cn } from "../../lib/cn";
+import { menuPanel } from "../dropdown-menu/menu-style";
+
+export type PopoverSide = "top" | "bottom" | "left" | "right";
+export type PopoverAlign = "start" | "center" | "end";
+
+export type PopoverProps = Omit<
+  ComponentProps<"div">,
+  "title" | "children" | "className" | "style"
+> & {
+  /** 触发按钮 */
+  trigger: ReactElement<Record<string, unknown>>;
+  /** 标题。有它时它就是面板的可访问名称；没有时自己传 `aria-label` */
+  title?: ReactNode;
+  /** 标题下的一行说明，会关联给读屏 */
+  description?: ReactNode;
+  /** 面板出现在触发按钮的哪一侧，放不下时自动翻到对面。默认 `bottom` */
+  side?: PopoverSide;
+  /** 和触发按钮的哪一边对齐。默认 `start` */
+  align?: PopoverAlign;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 给面板 */
+  className?: string;
+  children?: ReactNode;
+};
+
+/**
+ * 气泡卡片：点击触发、里面可以操作的一小块面板。不是模态——页面其余部分照常可用，
+ * 点别处、按 `Esc`、焦点移出去都会关。只是一句说明用 `Tooltip`，
+ * 必须做完才能继续的用 `Dialog`。
+ */
+export function Popover({
+  trigger,
+  title,
+  description,
+  side = "bottom",
+  align = "start",
+  open,
+  defaultOpen,
+  onOpenChange,
+  className,
+  children,
+  ...props
+}: PopoverProps) {
+  const { anchorRef, portalRef } = usePortalScope();
+
+  return (
+    <BasePopover.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange && ((next) => onOpenChange(next))}
+    >
+      <BasePopover.Trigger ref={anchorRef} render={trigger} />
+      <BasePopover.Portal ref={portalRef}>
+        <BasePopover.Positioner
+          side={side}
+          align={align}
+          sideOffset={4}
+          className="z-(--z-overlay) outline-none"
+        >
+          <BasePopover.Popup
+            {...props}
+            className={cn(
+              menuPanel,
+              // 面板和下拉菜单是同一份画法，只把上下 4px 的内边距换成四周 16px
+              "flex w-max max-w-[min(20rem,var(--available-width))] flex-col gap-3 p-4 text-sm wrap-anywhere",
+              className,
+            )}
+          >
+            {(title || description) && (
+              <div className="flex flex-col gap-1">
+                {title && (
+                  <BasePopover.Title className="text-base font-bold">
+                    {title}
+                  </BasePopover.Title>
+                )}
+                {description && (
+                  <BasePopover.Description className="text-ink-secondary">
+                    {description}
+                  </BasePopover.Description>
+                )}
+              </div>
+            )}
+            {children}
+          </BasePopover.Popup>
+        </BasePopover.Positioner>
+      </BasePopover.Portal>
+    </BasePopover.Root>
+  );
+}
+
+export type PopoverCloseProps = {
+  /** 点了就关掉面板的按钮，比如"完成" */
+  children: ReactElement<Record<string, unknown>>;
+};
+
+/** 包住面板里"点了就关"的按钮。 */
+export function PopoverClose({ children }: PopoverCloseProps) {
+  return <BasePopover.Close render={children} />;
+}

package/src/components/popover/index.ts

@@ -0,0 +1,8 @@
+export {
+  Popover,
+  PopoverClose,
+  type PopoverAlign,
+  type PopoverCloseProps,
+  type PopoverProps,
+  type PopoverSide,
+} from "./Popover";

package/src/components/progress/Progress.tsx

@@ -0,0 +1,133 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type ProgressSize = "sm" | "md";
+
+export type ProgressProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 当前值。不传就是"不确定进度"：一段色块在轨道上往返 */
+  value?: number;
+  /** 最大值，默认 100；分段进度下默认等于段数 */
+  max?: number;
+  /** 步骤数明确时把轨道切成等长的小段，`value` 是已完成的段数 */
+  segments?: number;
+  /** 4px 细条或 8px 标准条 */
+  size?: ProgressSize;
+  /** 在右侧显示数值：百分比，分段时是 `3 / 6` */
+  showValue?: boolean;
+  /** 自定义数值的写法 */
+  formatValue?: (value: number, max: number) => ReactNode;
+  /** 入场时从左侧充填一次 */
+  animate?: boolean;
+};
+
+const trackSize: Record<ProgressSize, string> = {
+  sm: "h-1",
+  md: "h-2",
+};
+
+/*
+ * 填充是纯色，不描边：亮色界面上一圈墨色的框显得重。
+ * 亮色下它对浅灰轨道只有 1.3:1，确切数值靠 showValue 或旁边的文字给出。
+ */
+const fillClass = "bg-action";
+
+/**
+ * 进度：灰轨 + 黄填充。表示"完成了多少"；表示"数量有多少"用图表，那是蓝色的事。
+ *
+ * `className` 给外层，其余属性（`aria-label` 等）给带 `role="progressbar"` 的轨道。
+ */
+export function Progress({
+  value,
+  max,
+  segments,
+  size = "md",
+  showValue = false,
+  formatValue,
+  animate = false,
+  className,
+  style,
+  ...props
+}: ProgressProps) {
+  const segmented = segments !== undefined && segments > 0;
+  const total = max ?? (segmented ? segments : 100);
+  const indeterminate = value === undefined;
+  const current = indeterminate ? 0 : Math.min(Math.max(value, 0), total);
+  const ratio = total > 0 ? current / total : 0;
+
+  let bar: ReactNode;
+  if (segmented) {
+    const done = Math.round(ratio * segments);
+    bar = (
+      <span className="flex h-full gap-1">
+        {Array.from({ length: segments }, (_, index) => (
+          <span
+            key={index}
+            data-done={index < done ? "" : undefined}
+            className={cn("flex-1", index < done ? fillClass : "bg-line")}
+          />
+        ))}
+      </span>
+    );
+  } else if (indeterminate) {
+    bar = (
+      <span
+        className={cn(
+          "absolute inset-y-0 left-0 w-2/5 animate-indeterminate",
+          // 减少动态效果时停在正中，不会被看成"进度 40%"
+          "motion-reduce:translate-x-3/4",
+          fillClass,
+        )}
+      />
+    );
+  } else if (ratio > 0) {
+    bar = (
+      <span
+        className={cn(
+          "absolute inset-y-0 left-0 transition-[width] duration-(--duration-base) ease-standard",
+          animate && "origin-left animate-fill",
+          fillClass,
+        )}
+        style={{ width: `${ratio * 100}%` }}
+      />
+    );
+  }
+
+  let text: ReactNode = null;
+  if (showValue && !indeterminate) {
+    if (formatValue) text = formatValue(current, total);
+    else if (segmented) text = `${current} / ${total}`;
+    else text = `${Math.round(ratio * 100)}%`;
+  }
+
+  return (
+    <div
+      className={cn("flex items-center gap-3 text-ink", className)}
+      style={style}
+      data-size={size}
+    >
+      <div
+        role="progressbar"
+        aria-valuemin={0}
+        aria-valuemax={total}
+        aria-valuenow={indeterminate ? undefined : current}
+        aria-valuetext={
+          segmented && !indeterminate ? `${current} / ${total}` : undefined
+        }
+        {...props}
+        className={cn(
+          "relative min-w-0 flex-1",
+          trackSize[size],
+          !segmented && "bg-line",
+        )}
+      >
+        {bar}
+      </div>
+      {text !== null && (
+        // 留出"100%"的宽度：几条并排时数值位数不同，轨道也能对齐
+        <span className="min-w-[4ch] shrink-0 text-right font-tech text-sm leading-none font-bold tabular-nums">
+          {text}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/components/progress/ProgressRing.tsx

@@ -0,0 +1,123 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type ProgressRingProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 当前值。不传就是"不确定进度"：一段弧匀速旋转 */
+  value?: number;
+  /** 最大值，默认 100 */
+  max?: number;
+  /** 直径，像素，默认 48 */
+  size?: number;
+  /** 线宽，像素，缺省取直径的 9% */
+  thickness?: number;
+  /** 在中心显示百分比的数值，不带 `%` */
+  showValue?: boolean;
+  /** 中心的内容：图标或头像。传了就不显示数值 */
+  children?: ReactNode;
+};
+
+/**
+ * 进度环：细圆环轨道 + 从 12 点方向顺时针的黄弧。用在紧凑的位置，或者围住一个头像、图标。
+ * 取色与 `Progress` 相同；需要名称时传 `aria-label`。
+ */
+export function ProgressRing({
+  value,
+  max = 100,
+  size = 48,
+  thickness,
+  showValue = false,
+  className,
+  style,
+  children,
+  ...props
+}: ProgressRingProps) {
+  const stroke = thickness ?? Math.max(2, Math.round(size * 0.09));
+  const radius = (size - stroke) / 2;
+  const circumference = 2 * Math.PI * radius;
+
+  const indeterminate = value === undefined;
+  const current = indeterminate ? 0 : Math.min(Math.max(value, 0), max);
+  const ratio = max > 0 ? current / max : 0;
+
+  const circle = {
+    cx: size / 2,
+    cy: size / 2,
+    r: radius,
+    fill: "none",
+    strokeWidth: stroke,
+  };
+
+  let arc: ReactNode = null;
+  if (indeterminate) {
+    arc = (
+      <>
+        <circle
+          {...circle}
+          className="origin-center animate-spin stroke-action motion-reduce:hidden"
+          strokeDasharray={`${circumference / 4} ${circumference}`}
+        />
+        {/* 减少动态效果时换成一圈虚线：静止的一段弧会被看成"进度 25%" */}
+        <circle
+          {...circle}
+          className="hidden stroke-action motion-reduce:block"
+          strokeDasharray={`${stroke} ${stroke * 2}`}
+        />
+      </>
+    );
+  } else if (ratio > 0) {
+    arc = (
+      <circle
+        {...circle}
+        className="stroke-action transition-[stroke-dashoffset] duration-(--duration-base) ease-standard"
+        strokeDasharray={circumference}
+        strokeDashoffset={circumference * (1 - ratio)}
+      />
+    );
+  }
+
+  let center: ReactNode = null;
+  if (children !== undefined) {
+    center = (
+      <span className="relative flex items-center justify-center">
+        {children}
+      </span>
+    );
+  } else if (showValue && !indeterminate) {
+    center = (
+      <span
+        className="relative font-tech leading-none font-bold tabular-nums"
+        style={{ fontSize: Math.round(size * 0.3) }}
+      >
+        {Math.round(ratio * 100)}
+      </span>
+    );
+  }
+
+  return (
+    <div
+      role="progressbar"
+      aria-valuemin={0}
+      aria-valuemax={max}
+      aria-valuenow={indeterminate ? undefined : current}
+      {...props}
+      className={cn(
+        "relative inline-flex shrink-0 items-center justify-center text-ink",
+        className,
+      )}
+      style={{ width: size, height: size, ...style }}
+    >
+      {/* 整张图逆时针转 90°，弧的起点就落在 12 点方向 */}
+      <svg
+        width={size}
+        height={size}
+        viewBox={`0 0 ${size} ${size}`}
+        aria-hidden="true"
+        className="absolute inset-0 -rotate-90"
+      >
+        <circle {...circle} className="stroke-line" />
+        {arc}
+      </svg>
+      {center}
+    </div>
+  );
+}

package/src/components/progress/index.ts

@@ -0,0 +1,2 @@
+export { Progress, type ProgressProps, type ProgressSize } from "./Progress";
+export { ProgressRing, type ProgressRingProps } from "./ProgressRing";