@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/popover/Popover.tsx

@@ -0,0 +1,97 @@
+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 { popoverDescription, popoverPanel, popoverTitle } from "./panel-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(popoverPanel, className)}>
+            {(title || description) && (
+              <div className="flex flex-col gap-1">
+                {title && (
+                  <BasePopover.Title className={popoverTitle}>
+                    {title}
+                  </BasePopover.Title>
+                )}
+                {description && (
+                  <BasePopover.Description className={popoverDescription}>
+                    {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/popover/panel-style.ts

@@ -0,0 +1,15 @@
+import { menuPanel } from "../dropdown-menu/menu-style";
+
+/**
+ * 气泡卡片与悬浮卡共用的面板：下拉菜单的那一块，只把上下 4px 的内边距换成四周 16px。
+ * 宽度跟着内容走，最宽 320px，也不超过视口里剩下的地方。
+ * 要经过 `cn()`：后面的 `p-4` 要盖掉菜单面板自带的上下内边距
+ */
+export const popoverPanel = [
+  menuPanel,
+  "flex w-max max-w-[min(20rem,var(--available-width))] flex-col gap-3 p-4 text-sm wrap-anywhere",
+];
+
+/** 面板里的标题和它下面的一行说明 */
+export const popoverTitle = "text-base font-bold";
+export const popoverDescription = "text-ink-secondary";

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

package/src/components/radio/Radio.tsx

@@ -0,0 +1,182 @@
+import {
+  createContext,
+  useContext,
+  useId,
+  useMemo,
+  type ChangeEvent,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import {
+  choiceBox,
+  choiceControl,
+  choiceFrame,
+  choiceLabel,
+  choiceMark,
+} from "../checkbox/choice-style";
+import { useFieldContext } from "../field/Field";
+
+type RadioGroupContextValue = {
+  name: string;
+  value: string | undefined;
+  select: (value: string) => void;
+  disabled: boolean;
+  required: boolean;
+  invalid: boolean;
+};
+
+const RadioGroupContext = createContext<RadioGroupContextValue | null>(null);
+
+export type RadioGroupOrientation = "vertical" | "horizontal";
+
+export type RadioGroupProps = Omit<
+  ComponentProps<"div">,
+  "onChange" | "defaultValue"
+> & {
+  /** 受控的当前值 */
+  value?: string;
+  /** 非受控时的初始值 */
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  /** 表单提交用的字段名，缺省自动生成 */
+  name?: string;
+  disabled?: boolean;
+  required?: boolean;
+  /** 竖排（默认）或横排 */
+  orientation?: RadioGroupOrientation;
+};
+
+/**
+ * 单选组。方向键在组内移动并选中，这是原生单选的行为，组件不另外处理。
+ * 标签用 `<Field group label="…">` 包住它，或者自己传 `aria-label`。
+ */
+export function RadioGroup({
+  value,
+  defaultValue,
+  onValueChange,
+  name,
+  disabled: disabledProp,
+  required: requiredProp,
+  orientation = "vertical",
+  className,
+  ...props
+}: RadioGroupProps) {
+  const field = useFieldContext();
+  const autoName = useId();
+  const [current, setCurrent] = useControllableState<string | undefined>({
+    value,
+    defaultValue,
+    onChange: (next) => {
+      if (next !== undefined) onValueChange?.(next);
+    },
+  });
+
+  const disabled = disabledProp ?? field?.disabled ?? false;
+  const required = requiredProp ?? field?.required ?? false;
+  const invalid = field?.invalid ?? false;
+  const groupName = name ?? autoName;
+
+  const context = useMemo<RadioGroupContextValue>(
+    () => ({
+      name: groupName,
+      value: current,
+      select: setCurrent,
+      disabled,
+      required,
+      invalid,
+    }),
+    [groupName, current, setCurrent, disabled, required, invalid],
+  );
+
+  return (
+    <RadioGroupContext value={context}>
+      <div
+        role="radiogroup"
+        // 字段是 <fieldset> 时名称由 <legend> 给；否则指向字段的标签
+        aria-labelledby={field && !field.group ? field.labelId : undefined}
+        aria-describedby={field?.describedBy}
+        aria-invalid={invalid || undefined}
+        aria-required={required || undefined}
+        aria-disabled={disabled || undefined}
+        {...props}
+        data-orientation={orientation}
+        className={cn(
+          "flex",
+          orientation === "vertical" ? "flex-col" : "flex-wrap gap-x-6",
+          className,
+        )}
+      />
+    </RadioGroupContext>
+  );
+}
+
+export type RadioProps = Omit<
+  ComponentProps<"input">,
+  "type" | "size" | "value"
+> & {
+  value: string;
+  /** 右侧的文字标签。不传时必须自己给 `aria-label` */
+  children?: ReactNode;
+};
+
+/**
+ * 单选框，放在 `RadioGroup` 里。`className` 给整行，其余属性与 `ref` 给 `<input>`。
+ * 脱离 `RadioGroup` 时就是一个原生单选，自己管 `name` 与 `checked`。
+ */
+export function Radio({
+  value,
+  disabled,
+  onChange,
+  className,
+  children,
+  ...props
+}: RadioProps) {
+  const group = useContext(RadioGroupContext);
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    onChange?.(event);
+    if (event.target.checked) group?.select(value);
+  };
+
+  const groupProps = group
+    ? {
+        name: group.name,
+        checked: group.value === value,
+        required: group.required,
+        "aria-invalid": group.invalid || undefined,
+      }
+    : {};
+
+  return (
+    <label className={cn(choiceLabel, className)}>
+      <span className={choiceControl}>
+        <span className={choiceFrame}>
+          <input
+            {...props}
+            {...groupProps}
+            type="radio"
+            value={value}
+            disabled={disabled ?? group?.disabled}
+            onChange={handleChange}
+            className={cn(
+              choiceBox,
+              "rounded-full choice-diamond:rounded-none",
+              focusRing,
+            )}
+          />
+          <span
+            aria-hidden="true"
+            className={cn(
+              choiceMark,
+              "size-2 rounded-full bg-accent-ink-inverse peer-checked:opacity-100 peer-disabled:bg-ink-disabled choice-diamond:hidden",
+            )}
+          />
+        </span>
+      </span>
+      {children !== undefined && <span className="min-w-0">{children}</span>}
+    </label>
+  );
+}

package/src/components/radio/index.ts

@@ -0,0 +1,7 @@
+export {
+  Radio,
+  RadioGroup,
+  type RadioGroupOrientation,
+  type RadioGroupProps,
+  type RadioProps,
+} from "./Radio";

package/src/components/rec-indicator/RecIndicator.tsx

@@ -0,0 +1,47 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type RecIndicatorProps = Omit<ComponentProps<"span">, "children"> & {
+  /** 方括号里的字，默认 `REC`；直播、实时数据可以写 `LIVE` */
+  label?: ReactNode;
+  /** 红点硬切明灭，默认开。关掉后红点常亮 */
+  blink?: boolean;
+};
+
+/**
+ * 录制指示：一个红点 + `[ REC ]`。
+ * 只在确有"进行中"的语义时用（正在录制、直播中、实时数据），不要当氛围装饰——
+ * 红色在这套语言里是危险与紧急。
+ */
+export function RecIndicator({
+  label = "REC",
+  blink = true,
+  className,
+  ...props
+}: RecIndicatorProps) {
+  return (
+    <span
+      {...props}
+      className={cn(
+        "inline-flex items-center gap-1 font-tech text-xs leading-none font-medium whitespace-nowrap text-ink uppercase",
+        className,
+      )}
+    >
+      {/* 有意不随主题变：角色色里的"危险"红，作填充用 */}
+      <span
+        aria-hidden="true"
+        className={cn(
+          "mr-0.5 size-2 shrink-0 rounded-full bg-alert",
+          blink && "animate-blink",
+        )}
+      />
+      <span aria-hidden="true" className="text-ink-tertiary">
+        [
+      </span>
+      <span>{label}</span>
+      <span aria-hidden="true" className="text-ink-tertiary">
+        ]
+      </span>
+    </span>
+  );
+}

package/src/components/rec-indicator/index.ts

@@ -0,0 +1 @@
+export { RecIndicator, type RecIndicatorProps } from "./RecIndicator";

package/src/components/registration-strip/RegistrationStrip.tsx

@@ -0,0 +1,51 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+import { decor } from "../../lib/decor";
+
+export type RegistrationStripOrientation = "horizontal" | "vertical";
+
+export type RegistrationStripProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 横条高 3px、每段 64px；竖条是三段 6 × 14px 叠放 */
+  orientation?: RegistrationStripOrientation;
+  /** 横条后面接一段灰线、撑满容器：用作名称下方的分隔线 */
+  rule?: boolean;
+};
+
+// 有意不随主题变：印刷校准用的三原色，只做装饰，不要用在别处
+const segments = ["bg-reg-magenta", "bg-reg-cyan", "bg-reg-yellow"] as const;
+
+/**
+ * 注册色条：品红、青、黄三段的微条，印刷品语气的点缀。
+ * 纯装饰，不承担任何数据或状态含义；一个版块最多一处，离图表远一点。
+ */
+export function RegistrationStrip({
+  orientation = "horizontal",
+  rule = false,
+  className,
+  ...props
+}: RegistrationStripProps) {
+  const vertical = orientation === "vertical";
+
+  return (
+    <div
+      {...props}
+      aria-hidden="true"
+      data-orientation={orientation}
+      className={cn(
+        decor,
+        vertical
+          ? "inline-flex flex-col"
+          : ["flex h-[3px] max-w-full", rule && "w-full"],
+        className,
+      )}
+    >
+      {segments.map((color) => (
+        <span
+          key={color}
+          className={cn(color, vertical ? "h-3.5 w-1.5" : "w-16 min-w-0")}
+        />
+      ))}
+      {rule && !vertical && <span className="min-w-0 flex-1 bg-line" />}
+    </div>
+  );
+}

package/src/components/registration-strip/index.ts

@@ -0,0 +1,5 @@
+export {
+  RegistrationStrip,
+  type RegistrationStripOrientation,
+  type RegistrationStripProps,
+} from "./RegistrationStrip";