@endfield-ui/react 0.0.0-stage → 0.1.0

package/src/components/stepper/Stepper.tsx

@@ -0,0 +1,316 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type ComponentProps,
+  type FocusEvent,
+  type KeyboardEvent,
+  type MouseEvent,
+  type PointerEvent,
+} from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { Minus } from "../../icons/Minus";
+import { Plus } from "../../icons/Plus";
+import { cn } from "../../lib/cn";
+import { focusRingWithin } from "../../lib/focus-ring";
+import { useFieldControl } from "../field/Field";
+
+export type StepperSize = "sm" | "md" | "lg";
+
+export type StepperProps = Omit<
+  ComponentProps<"input">,
+  | "type"
+  | "size"
+  | "value"
+  | "defaultValue"
+  | "onChange"
+  | "min"
+  | "max"
+  | "step"
+> & {
+  /** 受控的当前值 */
+  value?: number;
+  /** 非受控时的初始值，缺省取 `min`，没有 `min` 则为 0 */
+  defaultValue?: number;
+  onValueChange?: (value: number) => void;
+  min?: number;
+  max?: number;
+  /** 每一步的增量，默认 1；可以是小数 */
+  step?: number;
+  /** 32 / 40 / 56px 高 */
+  size?: StepperSize;
+  /** 错误态：数字下方出现一条红线。放在 `Field` 里时跟随它的 `error` */
+  invalid?: boolean;
+  /** 两端按钮的可访问名称 */
+  decrementLabel?: string;
+  incrementLabel?: string;
+};
+
+const boxSize: Record<StepperSize, string> = {
+  sm: "h-8 text-sm",
+  md: "h-10 text-base",
+  lg: "h-14 text-lg",
+};
+
+const buttonSize: Record<StepperSize, string> = {
+  sm: "w-8",
+  md: "w-10",
+  lg: "w-14",
+};
+
+const fieldSize: Record<StepperSize, string> = {
+  sm: "w-12",
+  md: "w-14",
+  lg: "w-20",
+};
+
+const iconSize: Record<StepperSize, number> = { sm: 14, md: 16, lg: 20 };
+
+/** 按住多久开始连续加减，以及之后每一步的间隔 */
+const HOLD_DELAY = 400;
+const HOLD_INTERVAL = 80;
+
+function decimalsOf(value: number) {
+  const text = String(value);
+  const dot = text.indexOf(".");
+  return dot === -1 ? 0 : text.length - dot - 1;
+}
+
+/**
+ * 步进器：`−` 钮 + 数字 + `+` 钮，三段紧贴。数字可以直接输入，
+ * 也可以用 ↑ ↓（一步）、PageUp / PageDown（十步）、Home / End（上下限）。
+ * `className` 给外框，其余属性与 `ref` 给中间的 `<input>`。
+ */
+export function Stepper({
+  value: valueProp,
+  defaultValue,
+  onValueChange,
+  min,
+  max,
+  step = 1,
+  size = "md",
+  invalid: invalidProp,
+  decrementLabel = "减少",
+  incrementLabel = "增加",
+  id: idProp,
+  disabled: disabledProp,
+  required: requiredProp,
+  readOnly = false,
+  "aria-describedby": describedByProp,
+  onKeyDown,
+  onBlur,
+  className,
+  ...props
+}: StepperProps) {
+  const { id, disabled, required, invalid, ...field } = useFieldControl({
+    id: idProp,
+    disabled: disabledProp,
+    required: requiredProp,
+    invalid: invalidProp,
+    "aria-describedby": describedByProp,
+  });
+
+  // 小数步长会带出 0.1 + 0.2 这样的浮点尾数，统一按步长的小数位数取整
+  const precision = Math.max(
+    decimalsOf(step),
+    decimalsOf(min ?? 0),
+    decimalsOf(max ?? 0),
+  );
+  const normalize = (next: number) => {
+    const clamped = Math.min(Math.max(next, min ?? -Infinity), max ?? Infinity);
+    return Number(clamped.toFixed(precision));
+  };
+
+  const [value, setValue] = useControllableState<number>({
+    value: valueProp,
+    defaultValue: defaultValue ?? normalize(0),
+    onChange: onValueChange,
+  });
+
+  // 输入到一半的文字：不为 null 时输入框显示它，失焦或回车时才变成数值
+  const [draft, setDraft] = useState<string | null>(null);
+
+  const atMin = min !== undefined && value <= min;
+  const atMax = max !== undefined && value >= max;
+  const locked = disabled || readOnly;
+
+  /** 加减一段；值真的变了才返回 true，按住连续加减靠它在到头时停表 */
+  const stepBy = (delta: number) => {
+    const typed = draft === null || draft.trim() === "" ? NaN : Number(draft);
+    const base = Number.isFinite(typed) ? typed : value;
+    const next = normalize(base + delta);
+    setDraft(null);
+    if (next === value) return false;
+    setValue(next);
+    return true;
+  };
+
+  const commitDraft = () => {
+    if (draft === null) return;
+    const typed = draft.trim() === "" ? NaN : Number(draft);
+    setDraft(null);
+    // 清空或只敲了一个负号：还原成原来的值
+    if (!Number.isFinite(typed)) return;
+    setValue(normalize(typed));
+  };
+
+  // 定时器里要用到最新的值和回调
+  const stepRef = useRef(stepBy);
+  useEffect(() => {
+    stepRef.current = stepBy;
+  });
+
+  const holdRef = useRef<{ delay?: number; repeat?: number }>({});
+  const release = () => {
+    window.clearTimeout(holdRef.current.delay);
+    window.clearInterval(holdRef.current.repeat);
+    holdRef.current = {};
+  };
+  useEffect(() => release, []);
+
+  const press = (event: PointerEvent<HTMLButtonElement>, delta: number) => {
+    // 只认主键；触屏和笔没有 button 的区分
+    if (event.button > 0) return;
+    release();
+    if (!stepRef.current(delta)) return;
+    holdRef.current.delay = window.setTimeout(() => {
+      holdRef.current.repeat = window.setInterval(() => {
+        if (!stepRef.current(delta)) release();
+      }, HOLD_INTERVAL);
+    }, HOLD_DELAY);
+  };
+
+  // 指针按下时已经走过一步；click 只留给键盘和读屏（它们触发的 click 没有次数）
+  const click = (event: MouseEvent<HTMLButtonElement>, delta: number) => {
+    if (event.detail === 0) stepBy(delta);
+  };
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    const raw = event.target.value;
+    // 只收数字、负号和小数点，其余按键不进输入框
+    if (/^-?\d*\.?\d*$/.test(raw)) setDraft(raw);
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented || locked) return;
+
+    switch (event.key) {
+      case "ArrowUp":
+        stepBy(step);
+        break;
+      case "ArrowDown":
+        stepBy(-step);
+        break;
+      case "PageUp":
+        stepBy(step * 10);
+        break;
+      case "PageDown":
+        stepBy(-step * 10);
+        break;
+      case "Home":
+        if (min === undefined) return;
+        setDraft(null);
+        setValue(min);
+        break;
+      case "End":
+        if (max === undefined) return;
+        setDraft(null);
+        setValue(max);
+        break;
+      case "Enter":
+        // 不拦回车：所在的表单照常提交，只是先把输入到一半的数落定
+        commitDraft();
+        return;
+      default:
+        return;
+    }
+    event.preventDefault();
+  };
+
+  const handleBlur = (event: FocusEvent<HTMLInputElement>) => {
+    onBlur?.(event);
+    commitDraft();
+  };
+
+  const buttonClass = (inactive: boolean) =>
+    cn(
+      "flex shrink-0 items-center justify-center select-none",
+      "transition-colors duration-(--duration-fast) ease-standard",
+      buttonSize[size],
+      inactive
+        ? "cursor-not-allowed bg-disabled text-on-disabled"
+        : "bg-control text-on-control hover:bg-control-hover active:bg-control-pressed",
+    );
+
+  return (
+    <div
+      data-size={size}
+      data-invalid={invalid ? "" : undefined}
+      className={cn(
+        "inline-flex items-stretch",
+        focusRingWithin,
+        boxSize[size],
+        className,
+      )}
+    >
+      <button
+        type="button"
+        // 键盘用户在输入框里按方向键，按钮不占 Tab 顺序
+        tabIndex={-1}
+        aria-label={decrementLabel}
+        disabled={locked || atMin}
+        onPointerDown={(event) => press(event, -step)}
+        onPointerUp={release}
+        onPointerLeave={release}
+        onPointerCancel={release}
+        onClick={(event) => click(event, -step)}
+        className={buttonClass(locked || atMin)}
+      >
+        <Minus size={iconSize[size]} />
+      </button>
+      <input
+        {...props}
+        id={id}
+        type="text"
+        role="spinbutton"
+        inputMode={precision > 0 ? "decimal" : "numeric"}
+        autoComplete="off"
+        value={draft ?? String(value)}
+        disabled={disabled}
+        required={required}
+        readOnly={readOnly}
+        aria-valuenow={value}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-invalid={invalid || undefined}
+        aria-describedby={field["aria-describedby"]}
+        onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        onBlur={handleBlur}
+        className={cn(
+          "min-w-0 flex-1 border-y-2 border-transparent bg-surface-sunken text-center font-tech font-bold tabular-nums outline-none",
+          "disabled:cursor-not-allowed",
+          fieldSize[size],
+          disabled ? "text-ink-disabled" : "text-ink",
+          invalid && !disabled && "border-b-danger",
+        )}
+      />
+      <button
+        type="button"
+        tabIndex={-1}
+        aria-label={incrementLabel}
+        disabled={locked || atMax}
+        onPointerDown={(event) => press(event, step)}
+        onPointerUp={release}
+        onPointerLeave={release}
+        onPointerCancel={release}
+        onClick={(event) => click(event, step)}
+        className={buttonClass(locked || atMax)}
+      >
+        <Plus size={iconSize[size]} />
+      </button>
+    </div>
+  );
+}

package/src/components/stepper/index.ts

@@ -0,0 +1 @@
+export { Stepper, type StepperProps, type StepperSize } from "./Stepper";

package/src/components/steps/Steps.tsx

@@ -0,0 +1,302 @@
+import {
+  Children,
+  createContext,
+  useContext,
+  type ComponentProps,
+  type MouseEventHandler,
+  type ReactNode,
+} from "react";
+import { Check } from "../../icons/Check";
+import { StatusDanger } from "../../icons/StatusDanger";
+import { cn } from "../../lib/cn";
+import { focusRingWithin } from "../../lib/focus-ring";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+
+export type StepsOrientation = "horizontal" | "vertical";
+export type StepsSize = "sm" | "md";
+export type StepStatus = "done" | "current" | "upcoming";
+
+/** 读屏听到的状态。未到的步骤不另说 */
+export type StepStatusLabels = {
+  done: string;
+  current: string;
+  invalid: string;
+};
+
+const defaultLabels: StepStatusLabels = {
+  done: "已完成",
+  current: "当前步骤",
+  invalid: "有误",
+};
+
+type StepContextValue = {
+  index: number;
+  status: StepStatus;
+  orientation: StepsOrientation;
+  size: StepsSize;
+  labels: StepStatusLabels;
+};
+
+const StepContext = createContext<StepContextValue | null>(null);
+
+export type StepsProps = Omit<ComponentProps<"ol">, "aria-label"> & {
+  /** 这是哪件事的步骤，比如"建站流程" */
+  "aria-label": string;
+  /** 走到了第几步，从 0 起。等于步数时全部是已完成 */
+  current: number;
+  /**
+   * - `horizontal` 横排，默认。所在的容器窄于 28rem 时自动改成竖排；
+   * - `vertical` 一直竖排。
+   */
+  orientation?: StepsOrientation;
+  size?: StepsSize;
+  /** 换掉读屏听到的那几句状态 */
+  statusLabels?: Partial<StepStatusLabels>;
+  /** 直接放 `Step` */
+  children: ReactNode;
+};
+
+/*
+ * 竖排是底子，横排是在容器够宽（@md，28rem）时盖上去的一层：
+ * 这样横排在窄容器里自己就退回竖排，不用另写一遍。
+ */
+const listLayout: Record<StepsOrientation, string> = {
+  vertical: "flex-col",
+  horizontal: "flex-col @md:flex-row",
+};
+
+const itemLayout: Record<StepsOrientation, string> = {
+  vertical: "gap-3",
+  horizontal: "gap-3 @md:flex-1 @md:flex-col @md:gap-2",
+};
+
+const railLayout: Record<StepsOrientation, string> = {
+  vertical: "flex-col",
+  horizontal: "flex-col @md:flex-row",
+};
+
+/* 线和节点之间留 8px，不从节点后面穿过 */
+const lineLayout: Record<StepsOrientation, string> = {
+  vertical: "my-2 min-h-4 w-0.5",
+  horizontal:
+    "my-2 min-h-4 w-0.5 @md:mx-2 @md:my-0 @md:h-0.5 @md:min-h-0 @md:w-auto",
+};
+
+const bodyLayout: Record<StepsOrientation, string> = {
+  vertical: "pb-4 group-last/step:pb-0",
+  horizontal: "pb-4 group-last/step:pb-0 @md:pr-4 @md:pb-0",
+};
+
+/**
+ * 步骤条：一件事分几步做，一共几步、走到了哪一步。里面只放 `Step`。
+ * 每一步的状态由 `current` 和它的位置算出来。
+ *
+ * `className` 给最外面的那层（它是量宽度的容器），其余属性给里面的 `<ol>`。
+ */
+export function Steps({
+  current,
+  orientation = "horizontal",
+  size = "md",
+  statusLabels,
+  className,
+  children,
+  ...props
+}: StepsProps) {
+  const labels = { ...defaultLabels, ...statusLabels };
+  const steps = Children.toArray(children);
+
+  return (
+    <div
+      data-orientation={orientation}
+      data-size={size}
+      className={cn("@container w-full text-ink", className)}
+    >
+      <ol {...props} className={cn("flex", listLayout[orientation])}>
+        {steps.map((step, index) => (
+          <StepContext
+            // 步骤是按位置认的：序号、状态都从位置来
+            key={index}
+            value={{
+              index,
+              status:
+                index < current
+                  ? "done"
+                  : index === current
+                    ? "current"
+                    : "upcoming",
+              orientation,
+              size,
+              labels,
+            }}
+          >
+            {step}
+          </StepContext>
+        ))}
+      </ol>
+    </div>
+  );
+}
+
+type StepOwnProps = {
+  title: ReactNode;
+  /** 标题下的说明 */
+  description?: ReactNode;
+  /** 这一步有东西没填对：节点换成警示图标，读屏多听到一句"有误" */
+  invalid?: boolean;
+  /** 传了就可以点（回到做过的步骤）：标题是链接，点击范围铺满这一步 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替标题里的 `<a>`（路由库的链接组件） */
+  render?: LinkRender;
+  /** 不是链接、但要能点时用它：标题是按钮 */
+  onClick?: MouseEventHandler<HTMLElement>;
+};
+
+export type StepProps = StepOwnProps &
+  Omit<ComponentProps<"li">, keyof StepOwnProps | "children">;
+
+const nodeSize: Record<StepsSize, string> = {
+  sm: "size-5 text-micro [&_svg]:size-3",
+  md: "size-6 text-xs [&_svg]:size-3.5",
+};
+
+const nodeClass: Record<StepStatus, string> = {
+  // 墨底黄勾：和选中的复选框是同一个逻辑
+  done: "bg-surface-inverse text-accent-ink-inverse",
+  // 描一圈最细的线：黄色对白底立不住。颜色跟着文字走，暗色下是近白
+  current: "border border-ink bg-action font-bold text-on-action",
+  upcoming: "border border-line-strong text-ink-secondary",
+};
+
+const titleSize: Record<StepsSize, string> = {
+  sm: "text-xs",
+  md: "text-sm",
+};
+
+const titleClass: Record<StepStatus, string> = {
+  done: "font-medium text-ink",
+  current: "font-bold text-ink",
+  upcoming: "font-medium text-ink-secondary",
+};
+
+export function Step({
+  title,
+  description,
+  invalid = false,
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  className,
+  ...props
+}: StepProps) {
+  const context = useContext(StepContext);
+  if (!context) {
+    throw new Error("<Step> 必须放在 <Steps> 里");
+  }
+  const { index, status, orientation, size, labels } = context;
+  const isLink = href !== undefined || render !== undefined;
+  const interactive = isLink || onClick !== undefined;
+
+  // 读屏听到的状态：节点和线都是画给眼睛看的
+  const spoken = [
+    status === "done"
+      ? labels.done
+      : status === "current"
+        ? labels.current
+        : "",
+    invalid ? labels.invalid : "",
+  ]
+    .filter(Boolean)
+    .join("，");
+
+  // 焦点环画在整一步上；点击范围用伪元素铺满这一步
+  const hit =
+    "text-left outline-none after:absolute after:inset-0 after:content-[''] hover:underline hover:underline-offset-4";
+
+  const heading = (
+    <>
+      {spoken !== "" && <span className="sr-only">{`${spoken}：`}</span>}
+      {title}
+    </>
+  );
+
+  return (
+    <li
+      {...props}
+      data-status={status}
+      data-invalid={invalid ? "" : undefined}
+      aria-current={status === "current" ? "step" : undefined}
+      className={cn(
+        "group/step relative flex min-w-0",
+        itemLayout[orientation],
+        interactive && focusRingWithin,
+        className,
+      )}
+    >
+      <span
+        aria-hidden="true"
+        className={cn("flex shrink-0 items-center", railLayout[orientation])}
+      >
+        <span
+          className={cn(
+            "flex shrink-0 items-center justify-center font-tech leading-none tabular-nums",
+            nodeSize[size],
+            invalid ? "border border-danger text-danger" : nodeClass[status],
+          )}
+        >
+          {invalid ? (
+            <StatusDanger />
+          ) : status === "done" ? (
+            <Check />
+          ) : (
+            String(index + 1).padStart(2, "0")
+          )}
+        </span>
+        {/* 这一步走完了，通向下一步的线才是实的 */}
+        <span
+          className={cn(
+            "flex-1 group-last/step:hidden",
+            lineLayout[orientation],
+            status === "done" ? "bg-ink" : "bg-line-strong",
+          )}
+        />
+      </span>
+      <div className={cn("min-w-0 flex-1", bodyLayout[orientation])}>
+        <div
+          className={cn(
+            "wrap-anywhere",
+            titleSize[size],
+            titleClass[status],
+            // 竖排时标题的第一行对齐节点的中线
+            size === "md" ? "leading-6" : "leading-5",
+          )}
+        >
+          {isLink ? (
+            <LinkElement
+              render={render}
+              href={href}
+              target={target}
+              rel={rel}
+              onClick={onClick}
+              className={hit}
+            >
+              {heading}
+            </LinkElement>
+          ) : onClick ? (
+            <button type="button" onClick={onClick} className={hit}>
+              {heading}
+            </button>
+          ) : (
+            heading
+          )}
+        </div>
+        {description !== undefined && (
+          <div className="mt-0.5 text-xs text-ink-secondary">{description}</div>
+        )}
+      </div>
+    </li>
+  );
+}

package/src/components/steps/index.ts

@@ -0,0 +1,10 @@
+export {
+  Step,
+  Steps,
+  type StepProps,
+  type StepStatus,
+  type StepStatusLabels,
+  type StepsOrientation,
+  type StepsProps,
+  type StepsSize,
+} from "./Steps";