Number Stepper数量选择

"use client"

import * as React from "react"
import { NumberField } from "@base-ui/react/number-field"
import { cva } from "class-variance-authority"
import { Loader2, Minus, Plus } from "lucide-react"

import { cn } from "@/lib/utils"
import { buttonVariants } from "@/components/ui/button"

import type { NumberStepperLabels, NumberStepperProps } from "./types"
import { useNumberStepper } from "./use-number-stepper"

const DEFAULT_LABELS: NumberStepperLabels = {
  decrement: "减少",
  increment: "增加",
  input: "数量",
  pending: "正在保存数量",
  commitError: "保存失败，请重试",
}

const numberStepperControlVariants = cva(
  "flex min-w-0 items-center rounded-md border border-edge bg-muted/60 text-sm transition-colors not-aria-invalid:has-[[data-slot=number-stepper-input]:focus]:border-foreground/25 not-aria-invalid:has-[[data-slot=number-stepper-input]:focus]:bg-background dark:not-aria-invalid:has-[[data-slot=number-stepper-input]:focus]:bg-input/30 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
  {
    variants: {
      size: {
        sm: "h-7 pointer-coarse:h-9",
        default: "h-8 pointer-coarse:h-10",
        lg: "h-9 pointer-coarse:h-11",
      },
    },
    defaultVariants: { size: "default" },
  },
)

/** 带边界、长按步进和异步回滚的方条数量选择。 */
function NumberStepper({
  value: valueProp,
  defaultValue = null,
  onValueChange,
  onValueCommit,
  onCommitError,
  min = 0,
  max,
  step = 1,
  smallStep = step === "any" ? 1 : step,
  largeStep = step === "any" ? 10 : step * 10,
  allowWheelScrub = false,
  locale = "zh-CN",
  label,
  size = "default",
  disabled = false,
  readOnly = false,
  error,
  labels: labelsProp,
  className,
  id: idProp,
  "aria-label": ariaLabel,
  "aria-labelledby": labelledBy,
  "aria-invalid": ariaInvalid,
  "aria-describedby": describedBy,
  ...props
}: NumberStepperProps) {
  const labels = { ...DEFAULT_LABELS, ...labelsProp }
  const autoId = React.useId()
  const id = idProp ?? autoId
  const inputRef = React.useRef<HTMLInputElement>(null)
  // 最近一次是按哪个键改的数：保存时让那个按钮转圈，数字照常显示，用户看得到自己改成了几
  // 点加减按钮时 Base UI 会把焦点移到中间的输入框；指针带来的焦点隐藏光标，按任意键后恢复。
  const [pointerFocus, setPointerFocus] = React.useState(false)
  const [lastAction, setLastAction] = React.useState<"decrement" | "increment">(
    "increment",
  )
  const { value, pending, commitError, change, commit, reset } =
    useNumberStepper({
      value: valueProp,
      defaultValue,
      onValueChange,
      onValueCommit,
      onCommitError,
    })
  const resetRef = React.useRef(reset)
  React.useEffect(() => {
    resetRef.current = reset
  })
  React.useEffect(() => {
    const form = inputRef.current?.form
    if (!form || valueProp !== undefined) return
    let timer: ReturnType<typeof setTimeout> | undefined
    const onReset = (event: Event) => {
      timer = setTimeout(() => {
        if (!event.defaultPrevented) {
          // 先结束手动编辑，让 NumberField 恢复文本同步；reset 会取消这次失焦提交。
          inputRef.current?.blur()
          resetRef.current()
        }
      })
    }
    form.addEventListener("reset", onReset)
    return () => {
      clearTimeout(timer)
      form.removeEventListener("reset", onReset)
    }
  }, [valueProp, props.form])

  const message =
    error ||
    (commitError?.cause instanceof Error
      ? commitError.cause.message || labels.commitError
      : commitError
        ? labels.commitError
        : null)
  const invalid =
    Boolean(message) ||
    (ariaInvalid !== undefined &&
      ariaInvalid !== false &&
      ariaInvalid !== "false")
  const errorId = `${id}-error`
  const description =
    [describedBy, message ? errorId : undefined].filter(Boolean).join(" ") ||
    undefined
  const buttonSize =
    size === "sm" ? "icon-sm" : size === "lg" ? "icon-lg" : "icon"
  const buttonClass = buttonVariants({
    variant: "ghost",
    size: buttonSize,
    // 按下时只缩小图标给一点触感，按钮底色和尺寸不动；减少动态效果时不缩。
    // 按钮留在方条边框里面、撑满框内高度：不用负边距伸到边线上，否则按下时的底色和下沉会盖住边框（出错时的红边尤其明显）
    className:
      "h-full touch-manipulation self-stretch focus-visible:ring-inset [&_svg]:transition-transform [&_svg]:duration-100 [&_svg]:ease-out active:[&_svg]:scale-[0.8] motion-reduce:[&_svg]:transition-none motion-reduce:active:[&_svg]:scale-100 rounded-none border-0 border-edge text-muted-foreground transition-colors active:not-aria-[haspopup]:translate-y-0 aria-disabled:pointer-events-none aria-disabled:opacity-40 disabled:opacity-40",
  })

  function handleCommit(next: number | null) {
    if (disabled || readOnly || pending) return
    // NumberField 只在步进时 snap，直接输入失焦时在这里按 min 对齐。
    const snapped =
      next === null || step === "any" || step <= 0
        ? next
        : Number((min + Math.round((next - min) / step) * step).toPrecision(15))
    commit(
      snapped === null
        ? null
        : Math.min(max ?? Infinity, Math.max(min, snapped)),
    )
  }

  return (
    <NumberField.Root
      {...props}
      id={id}
      data-slot="number-stepper"
      data-size={size}
      data-invalid={invalid ? "" : undefined}
      data-disabled={disabled ? "" : undefined}
      data-readonly={readOnly || pending ? "" : undefined}
      aria-busy={pending || undefined}
      className={cn(
        "inline-flex max-w-full flex-col gap-1.5 align-middle",
        label && "w-full",
        className,
      )}
      value={value}
      min={min}
      max={max}
      step={step}
      smallStep={smallStep}
      largeStep={largeStep}
      snapOnStep
      locale={locale}
      allowWheelScrub={allowWheelScrub}
      disabled={disabled}
      readOnly={readOnly || pending}
      onValueChange={change}
      onValueCommitted={handleCommit}
    >
      <NumberField.Group
        data-slot="number-stepper-control"
        data-pointer-focus={pointerFocus ? "" : undefined}
        aria-invalid={invalid || undefined}
        onPointerDown={(event) => {
          if ((event.target as Element).closest("button")) setPointerFocus(true)
        }}
        // 用捕获阶段：方向键会被 Base UI 在输入框上处理掉，冒泡阶段收不到
        onKeyDownCapture={() => setPointerFocus(false)}
        onBlur={(event) => {
          if (!event.currentTarget.contains(event.relatedTarget))
            setPointerFocus(false)
        }}
        className={cn(
          numberStepperControlVariants({ size }),
          disabled && "cursor-not-allowed opacity-50",
        )}
      >
        {label && (
          <label
            data-slot="number-stepper-label"
            htmlFor={id}
            className="mr-auto min-w-0 truncate px-3 text-muted-foreground"
          >
            {label}
          </label>
        )}
        <NumberField.Decrement
          data-slot="number-stepper-decrement"
          onPointerDown={() => setLastAction("decrement")}
          aria-label={labels.decrement}
          disabled={pending || readOnly || (value !== null && value <= min)}
          className={cn(
            buttonClass,
            "border-r border-edge first:rounded-l-[calc(var(--radius-md)-1px)]",
          )}
        >
          {pending && lastAction === "decrement" ? (
            <Loader2
              data-slot="number-stepper-spinner"
              aria-hidden="true"
              className="motion-safe:animate-spin"
            />
          ) : (
            <Minus aria-hidden="true" />
          )}
        </NumberField.Decrement>
        <div className="relative min-w-0">
          <NumberField.Input
            ref={inputRef}
            data-slot="number-stepper-input"
            role="spinbutton"
            aria-roledescription={undefined}
            aria-valuemin={min}
            aria-valuemax={max}
            aria-valuenow={value ?? undefined}
            aria-label={ariaLabel ?? (label ? undefined : labels.input)}
            aria-labelledby={labelledBy}
            aria-invalid={invalid || undefined}
            aria-describedby={description}
            inputMode="numeric"
            form={props.form}
            className={cn(
              "field-sizing-content min-h-0 max-w-24 min-w-10 bg-transparent px-2 text-center text-sm font-medium tabular-nums outline-none in-data-pointer-focus:caret-transparent pointer-coarse:text-base",
              pending && "text-muted-foreground",
            )}
            onKeyDown={(event) => {
              if (["ArrowDown", "PageDown", "Home"].includes(event.key))
                setLastAction("decrement")
              else if (["ArrowUp", "PageUp", "End"].includes(event.key))
                setLastAction("increment")
              if (
                event.key === "Enter" &&
                !event.nativeEvent.isComposing &&
                !disabled &&
                !readOnly &&
                !pending
              ) {
                event.preventDefault()
                event.currentTarget.blur()
              }
            }}
          />
        </div>
        <NumberField.Increment
          data-slot="number-stepper-increment"
          onPointerDown={() => setLastAction("increment")}
          aria-label={labels.increment}
          disabled={
            pending ||
            readOnly ||
            (value !== null && max !== undefined && value >= max)
          }
          className={cn(
            buttonClass,
            "rounded-r-[calc(var(--radius-md)-1px)] border-l border-edge",
          )}
        >
          {pending && lastAction === "increment" ? (
            <Loader2
              data-slot="number-stepper-spinner"
              aria-hidden="true"
              className="motion-safe:animate-spin"
            />
          ) : (
            <Plus aria-hidden="true" />
          )}
        </NumberField.Increment>
      </NumberField.Group>
      {message && (
        <p
          id={errorId}
          data-slot="number-stepper-error"
          role="alert"
          className="text-xs text-destructive"
        >
          {message}
        </p>
      )}
      <span role="status" className="sr-only">
        {pending ? labels.pending : ""}
      </span>
    </NumberField.Root>
  )
}

export { NumberStepper, numberStepperControlVariants }
export type {
  NumberStepperLabels,
  NumberStepperProps,
  NumberStepperSize,
} from "./types"

import type * as React from "react"
import type { NumberField } from "@base-ui/react/number-field"

type NumberStepperSize = "sm" | "default" | "lg"

type NumberStepperLabels = {
  decrement: string
  increment: string
  input: string
  pending: string
  commitError: string
}

type NumberStepperProps = Omit<
  NumberField.Root.Props,
  | "value"
  | "defaultValue"
  | "onValueChange"
  | "onValueCommitted"
  | "children"
  | "className"
  | "render"
  | "allowOutOfRange"
  | "snapOnStep"
> & {
  /** 最小数量。
   * @default 0
   */
  min?: number
  /** 最大数量；达到后加号不可用。 */
  max?: number
  /** 步长；失焦按 min 为基准对齐，any 关闭对齐。
   * @default 1
   */
  step?: number | "any"
  /** 聚焦且指针悬停时，是否允许滚轮修改数值。
   * @default false
   */
  allowWheelScrub?: boolean
  /** 受控数值；null 表示未填写。 */
  value?: number | null
  /** 非受控初始值。
   * @default null
   */
  defaultValue?: number | null
  /** 数值改变时调用；提交失败回滚时也调用。 */
  onValueChange?: (value: number | null) => void
  /** 一次操作结束、停手 400ms 后提交；Promise 期间锁定控件，失败回滚。 */
  onValueCommit?: (value: number | null) => void | Promise<void>
  /** 提交失败时接收原始错误；Error.message 同时显示在条下。 */
  onCommitError?: (error: unknown) => void
  /** 条内左侧标签；不传时控件随内容收窄。 */
  label?: React.ReactNode
  /** 高度 28 / 32 / 36px；触屏 36 / 40 / 44px。
   * @default "default"
   */
  size?: NumberStepperSize
  /** 外部校验提示，优先于提交错误。 */
  error?: React.ReactNode
  /** 覆盖按钮名称、无标签输入名称和提交提示。 */
  labels?: Partial<NumberStepperLabels>
  /** 根元素样式。 */
  className?: string
}

export type { NumberStepperLabels, NumberStepperProps, NumberStepperSize }

"use client"

import * as React from "react"

import type { NumberStepperProps } from "./types"

/** 合并一次操作中的快速变更；回滚基准是这批操作开始前的值。 */
function useNumberStepper({
  value: valueProp,
  defaultValue = null,
  onValueChange,
  onValueCommit,
  onCommitError,
}: NumberStepperProps) {
  const [internalValue, setInternalValue] = React.useState(defaultValue)
  const value = valueProp === undefined ? internalValue : valueProp
  const [pending, setPending] = React.useState(false)
  const [commitError, setCommitError] = React.useState<{
    cause: unknown
  } | null>(null)
  const current = React.useRef(value)
  const batch = React.useRef<{ before: number | null } | null>(null)
  const timer = React.useRef<ReturnType<typeof setTimeout> | undefined>(
    undefined,
  )
  const generation = React.useRef(0)
  const busy = React.useRef(false)

  React.useEffect(() => {
    // 外部替换值时，旧请求的结果不能覆盖新值。
    if (current.current !== value) {
      clearTimeout(timer.current)
      generation.current += 1
      batch.current = null
      busy.current = false
      setPending(false)
    }
    current.current = value
  }, [value])

  React.useEffect(() => {
    return () => {
      clearTimeout(timer.current)
      generation.current += 1
    }
  }, [])

  function update(next: number | null) {
    current.current = next
    setInternalValue(next)
    onValueChange?.(next)
  }

  function change(next: number | null) {
    if (busy.current) return
    clearTimeout(timer.current)
    if (next === current.current) return
    batch.current ??= { before: current.current }
    setCommitError(null)
    update(next)
  }

  function commit(next: number | null) {
    if (busy.current) return
    clearTimeout(timer.current)
    change(next)
    const transaction = batch.current
    if (!transaction) return
    if (transaction.before === next) {
      batch.current = null
      return
    }
    timer.current = setTimeout(async () => {
      batch.current = null
      const request = ++generation.current
      const fail = (error: unknown) => {
        if (request !== generation.current) return
        update(transaction.before)
        setCommitError({ cause: error })
        onCommitError?.(error)
      }
      try {
        const result = onValueCommit?.(next)
        if (result && typeof result.then === "function") {
          busy.current = true
          setPending(true)
          await result
        }
      } catch (error) {
        fail(error)
      } finally {
        if (request === generation.current) {
          busy.current = false
          setPending(false)
        }
      }
    }, 400)
  }

  function reset() {
    clearTimeout(timer.current)
    generation.current += 1
    batch.current = null
    busy.current = false
    setPending(false)
    setCommitError(null)
    update(defaultValue)
  }

  return { value, pending, commitError, change, commit, reset }
}

export { useNumberStepper }