@multiplatform.one/forms 6.6.0 → 7.0.0

package/src/fields/Stepper/index.tsx

@@ -1,15 +1,17 @@
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
+import { CaretDownIcon, CaretUpIcon, MinusIcon, PlusIcon } from "@phosphor-icons/react";
 import {
   type ComponentProps,
   type MutableRefObject,
+  type ReactNode,
   useCallback,
   useEffect,
   useRef,
   useState,
 } from "react";
-import { ensureFocusVisibleRing } from "@multiplatform.one/theme";
-import { isWeb, useProps } from "tamagui";
+import { isWeb, useProps, View } from "tamagui";
 import { Input as TamaguiInput } from "tamagui";
+import { sizeRecipeForToken } from "@multiplatform.one/theme";
 
 type InputProps = ComponentProps<typeof TamaguiInput>;
 import { Skeleton } from "../../Skeleton";
@@ -23,14 +25,13 @@ import {
 import { useWheelIncrement } from "../../shared/useWheelIncrement";
 import type { FormFieldProps } from "../../fieldLayout";
 import { Input as InputParts } from "../../InputParts";
-import { ControlGroup } from "../../ControlGroup";
-import { Minus, Plus } from "@tamagui/lucide-icons-2";
-import { Button } from "../../Button";
+import { formInputColors } from "../../shared/colorRamps";
 import { t } from "../../shared/t";
 import type { FieldComponentProps, Validator } from "../../types";
 
 const repeatDelay = 400;
 const repeatInterval = 80;
+const LARGE_STEP_FACTOR = 10;
 
 /** CSS timings for discrete value motion (mirrors theme animationConfig). */
 const stepperCssTimings: Record<string, string> = {
@@ -44,6 +45,18 @@ const stepperCssTimings: Record<string, string> = {
   gentle: "ease-in-out 450ms",
 };
 
+const noButtonRing = {
+  outlineWidth: 0,
+  outlineStyle: "none" as const,
+  outlineColor: "transparent",
+};
+
+function preventFocusSteal(e: { preventDefault?: () => void }) {
+  // Spectrum / React Aria: spin buttons are not a tab stop and must not
+  // steal focus from the field. The LC-71 ring stays on Input.Box (+/− inside).
+  e.preventDefault?.();
+}
+
 function useRepeatAction(action: () => void, repeatingRef: MutableRefObject<boolean>) {
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -85,14 +98,14 @@ export type StepperProps<
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > = Omit<
   FormFieldProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
-  // "onChange": FormFieldProps carries the DOM ChangeEventHandler from
-  // YStackProps; this field exposes a canonical value callback instead.
-  "children" | "field" | "onChange"
+  // "onChange"/"value": FormFieldProps carries DOM handlers from YStackProps;
+  // this field exposes a canonical numeric value callback instead.
+  "children" | "field" | "onChange" | "value"
 > &
   Partial<
     Omit<
       FieldComponentProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
-      "children"
+      "children" | "value"
     >
   > & {
     readOnly?: boolean;
@@ -101,18 +114,80 @@ export type StepperProps<
     step?: number;
     precision?: number;
     showButtons?: boolean;
+    /**
+     * Spin-button placement.
+     * `right`/`left` — Spectrum NumberField: stacked carets on that edge.
+     * `both` — Apple quantity stepper: minus | value | plus.
+     */
     buttonPosition?: "left" | "right" | "both";
     allowEmpty?: boolean;
     placeholder?: string;
     inputProps?: Omit<InputProps, "value" | "onChangeText" | "ref">;
     /** Standalone (no form/name) change callback — commits on blur and +/- */
     onChange?: (value: number | null) => void;
+    /** Standalone controlled value. Omit for uncontrolled (`defaultValue`). */
+    value?: number | null;
     /** When true, renders a skeleton placeholder instead of the stepper */
     skeleton?: boolean;
     /** When true, uses compact sizing */
     compact?: boolean;
   };
 
+function StepperSpinButton({
+  kind,
+  disabled,
+  stacked,
+  seam,
+  onPressIn,
+  onPressOut,
+  onActivate,
+  children,
+}: {
+  kind: "increment" | "decrement";
+  disabled: boolean;
+  stacked?: boolean;
+  seam?: "bottom" | "end" | "start";
+  onPressIn: () => void;
+  onPressOut: () => void;
+  onActivate: () => void;
+  children: ReactNode;
+}) {
+  const label = kind === "increment" ? t("Increase") : t("Decrease");
+  return (
+    <InputParts.Button
+      tabIndex={-1}
+      disabled={disabled}
+      aria-disabled={disabled || undefined}
+      aria-label={label}
+      data-stepper-button={kind}
+      cursor={disabled ? "not-allowed" : "pointer"}
+      opacity={disabled ? 0.4 : 1}
+      height={stacked ? "50%" : "100%"}
+      flex={stacked ? 1 : undefined}
+      alignSelf="stretch"
+      borderBottomWidth={seam === "bottom" ? 1 : 0}
+      borderInlineEndWidth={seam === "end" ? 1 : 0}
+      borderInlineStartWidth={seam === "start" ? 1 : 0}
+      borderColor={formInputColors.border.base}
+      focusStyle={noButtonRing}
+      focusVisibleStyle={noButtonRing}
+      hoverStyle={disabled ? { backgroundColor: "transparent" } : undefined}
+      onMouseDown={(e: any) => {
+        preventFocusSteal(e);
+        onActivate();
+      }}
+      onPointerDown={(e: any) => {
+        preventFocusSteal(e);
+        onActivate();
+      }}
+      onPressIn={disabled ? undefined : onPressIn}
+      onPressOut={onPressOut}
+    >
+      {children}
+    </InputParts.Button>
+  );
+}
+
 export function Stepper<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -129,7 +204,8 @@ export function Stepper<
     step = 1,
     precision = 0,
     showButtons = true,
-    buttonPosition = "both",
+    // Spectrum NumberField default: stacked carets on the trailing edge.
+    buttonPosition = "right",
     allowEmpty = false,
     placeholder,
     mode,
@@ -146,27 +222,26 @@ export function Stepper<
     size,
     onBlur,
     onChange,
+    value: valueProp,
     skeleton,
     compact,
     id: idProp,
     ...restProps
   } = useProps(props);
 
-  const { resolvedForm, knobProps, control, id } = useFormField({ form, id: idProp, compact });
+  const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
-  const motionTransition = (knobProps.transition as string | undefined) || "quick";
-  // ControlGroup suppresses the group outline and only tints its border via
-  // async focus-within state, so the ring must live on the input itself
-  // (DG-A11Y-01). Inset (-2) keeps it inside the group chrome.
-  const areaFocusRing = ensureFocusVisibleRing({
-    ...control.focusVisibleKnobProps,
-    outlineOffset: -2,
-  });
+  const motionTransition = knobProps.transition as string | undefined;
+  const controlSize = size || knobProps.sizeToken;
+  // +/- glyphs are control-internal icons: the recipe's icon channel (LC-79).
+  const iconPx = sizeRecipeForToken(String(controlSize)).iconSize;
+  const isControlled = valueProp !== undefined && !name;
 
   // Initialize inputValue from defaultValue for standalone mode
   const [inputValue, setInputValue] = useState<string>(() => {
-    if (defaultValue !== undefined && defaultValue !== null) {
-      return precision > 0 ? (defaultValue as number).toFixed(precision) : String(defaultValue);
+    const initial = isControlled ? valueProp : defaultValue;
+    if (initial !== undefined && initial !== null) {
+      return precision > 0 ? (initial as number).toFixed(precision) : String(initial);
     }
     return "";
   });
@@ -177,14 +252,22 @@ export function Stepper<
   const typingRef = useRef(false);
   const incrementRef = useRef<() => void>(() => {});
   const decrementRef = useRef<() => void>(() => {});
+  const areaRef = useRef<any>(null);
+
+  const focusArea = useCallback(() => {
+    const node = areaRef.current as { focus?: () => void } | null;
+    node?.focus?.();
+  }, []);
 
   const pulseDiscreteStep = useCallback(() => {
     if (repeatingRef.current || typingRef.current) return;
+    // LC-68: no tween when the animation knob resolves to none.
+    if (!motionTransition) return;
     setValueFlash(true);
     // Hold the dipped opacity long enough for the CSS transition to paint
     // intermediates (quick = 100ms).
     setTimeout(() => setValueFlash(false), 90);
-  }, []);
+  }, [motionTransition]);
 
   const repeatIncrement = useRepeatAction(() => incrementRef.current(), repeatingRef);
   const repeatDecrement = useRepeatAction(() => decrementRef.current(), repeatingRef);
@@ -223,32 +306,40 @@ export function Stepper<
     [boundsLo, boundsHi],
   );
 
-  // Increment value
-  const increment = useCallback(() => {
-    const currentValue = parseValue(inputValue) || 0;
-    const newValue = clampValue(currentValue + step);
-    if (newValue !== null) {
-      pulseDiscreteStep();
-      setInputValue(formatValue(newValue));
-      // Standalone path has no field sync effect — push immediately.
-      if (!name) onChange?.(newValue);
-    }
-  }, [inputValue, parseValue, clampValue, step, formatValue, name, onChange, pulseDiscreteStep]);
-
-  // Decrement value
-  const decrement = useCallback(() => {
-    const currentValue = parseValue(inputValue) || 0;
-    const newValue = clampValue(currentValue - step);
-    if (newValue !== null) {
-      pulseDiscreteStep();
-      setInputValue(formatValue(newValue));
-      if (!name) onChange?.(newValue);
-    }
-  }, [inputValue, parseValue, clampValue, step, formatValue, name, onChange, pulseDiscreteStep]);
+  const commitNumber = useCallback(
+    (next: number | null, pulse = false) => {
+      const clamped = clampValue(next);
+      const formatted = formatValue(clamped);
+      if (formatted === inputValue) return;
+      if (pulse) pulseDiscreteStep();
+      setInputValue(formatted);
+      if (!name) onChange?.(clamped);
+    },
+    [clampValue, formatValue, inputValue, name, onChange, pulseDiscreteStep],
+  );
+
+  const applyDelta = useCallback(
+    (delta: number) => {
+      if (disabled || readOnly) return;
+      const current = parseValue(inputValue);
+      const from = current ?? 0;
+      commitNumber(from + delta, true);
+    },
+    [disabled, readOnly, parseValue, inputValue, commitNumber],
+  );
+
+  const increment = useCallback(() => applyDelta(step), [applyDelta, step]);
+  const decrement = useCallback(() => applyDelta(-step), [applyDelta, step]);
 
   incrementRef.current = increment;
   decrementRef.current = decrement;
 
+  useEffect(() => {
+    if (!isControlled || typingRef.current) return;
+    const formatted = formatValue(valueProp ?? null);
+    setInputValue((prev) => (prev === formatted ? prev : formatted));
+  }, [isControlled, valueProp, formatValue]);
+
   const { wheelProps } = useWheelIncrement({
     onIncrement: increment,
     onDecrement: decrement,
@@ -256,6 +347,46 @@ export function Stepper<
     readOnly,
   });
 
+  const handleStepperKeyDown = useCallback(
+    (event: any) => {
+      if (disabled || readOnly) return;
+      const unit = event.shiftKey ? step * LARGE_STEP_FACTOR : step;
+      switch (event.key) {
+        case "ArrowUp":
+          event.preventDefault();
+          applyDelta(unit);
+          break;
+        case "ArrowDown":
+          event.preventDefault();
+          applyDelta(-unit);
+          break;
+        case "PageUp":
+          event.preventDefault();
+          applyDelta(step * LARGE_STEP_FACTOR);
+          break;
+        case "PageDown":
+          event.preventDefault();
+          applyDelta(-step * LARGE_STEP_FACTOR);
+          break;
+        case "Home":
+          if (boundsLo !== undefined) {
+            event.preventDefault();
+            commitNumber(boundsLo, true);
+          }
+          break;
+        case "End":
+          if (boundsHi !== undefined) {
+            event.preventDefault();
+            commitNumber(boundsHi, true);
+          }
+          break;
+        default:
+          break;
+      }
+    },
+    [disabled, readOnly, step, applyDelta, boundsLo, boundsHi, commitNumber],
+  );
+
   // Handle input change
   const handleInputChange = useCallback(
     (text: string) => {
@@ -288,104 +419,163 @@ export function Stepper<
     const atMin = currentValue !== null && boundsLo !== undefined && currentValue <= boundsLo;
     const atMax = currentValue !== null && boundsHi !== undefined && currentValue >= boundsHi;
     const live = repeatingRef.current || typingRef.current;
-    const timing = stepperCssTimings[motionTransition] ?? stepperCssTimings.quick;
+    const timing = motionTransition
+      ? (stepperCssTimings[motionTransition] ?? stepperCssTimings.quick)
+      : undefined;
     // Prefer explicit CSS opacity transition — Tamagui `transition` on Input can
     // compile to `all` and fight focus rings; scoped opacity is enough for LC-25.
-    const valueMotionStyle = !live
-      ? {
-          transition: isWeb ? `opacity ${timing}` : undefined,
-          opacity: valueFlash ? 0.45 : 1,
-        }
-      : { opacity: 1 };
-    const controlGroup = (
-      <ControlGroup>
-        {showButtons && !readOnly && (buttonPosition === "left" || buttonPosition === "both") && (
-          <Button
-            size={knobProps.sizeToken}
-            disabled={disabled || atMin}
-            tabIndex={-1}
-            aria-label={t("Decrease")}
-            onPressIn={repeatDecrement.onPressIn}
-            onPressOut={repeatDecrement.onPressOut}
-            icon={Minus}
-          />
+    const valueMotionStyle =
+      !live && timing
+        ? {
+            transition: isWeb ? `opacity ${timing}` : undefined,
+            opacity: valueFlash ? 0.45 : 1,
+          }
+        : { opacity: 1 };
+
+    const stacked = buttonPosition === "left" || buttonPosition === "right";
+    const showSpin = showButtons && !readOnly;
+    const decDisabled = !!(disabled || atMin);
+    const incDisabled = !!(disabled || atMax);
+
+    const decrementButton = (
+      <StepperSpinButton
+        kind="decrement"
+        disabled={decDisabled}
+        stacked={stacked}
+        seam={buttonPosition === "both" ? "end" : undefined}
+        onPressIn={repeatDecrement.onPressIn}
+        onPressOut={repeatDecrement.onPressOut}
+        onActivate={focusArea}
+      >
+        {stacked ? (
+          <CaretDownIcon size={iconPx} weight="bold" aria-hidden />
+        ) : (
+          <MinusIcon size={iconPx} weight="bold" aria-hidden />
+        )}
+      </StepperSpinButton>
+    );
+    const incrementButton = (
+      <StepperSpinButton
+        kind="increment"
+        disabled={incDisabled}
+        stacked={stacked}
+        seam={stacked ? "bottom" : buttonPosition === "both" ? "start" : undefined}
+        onPressIn={repeatIncrement.onPressIn}
+        onPressOut={repeatIncrement.onPressOut}
+        onActivate={focusArea}
+      >
+        {stacked ? (
+          <CaretUpIcon size={iconPx} weight="bold" aria-hidden />
+        ) : (
+          <PlusIcon size={iconPx} weight="bold" aria-hidden />
         )}
+      </StepperSpinButton>
+    );
 
-        <InputParts.Area
-          id={id}
-          value={inputValue}
-          placeholder={placeholder}
-          keyboardType="numeric"
-          disabled={disabled}
-          readOnly={!!readOnly}
-          aria-labelledby={label ? `${id}-label` : undefined}
-          aria-label={label ? undefined : t("Number")}
-          aria-required={required || undefined}
-          aria-invalid={hasError || undefined}
-          aria-readonly={readOnly || undefined}
-          data-stepper-value
-          data-stepper-live={live ? "true" : undefined}
-          data-stepper-flash={valueFlash ? "true" : undefined}
-          onChangeText={readOnly ? undefined : handleInputChange}
-          textAlign="center"
-          focusStyle={areaFocusRing}
-          focusVisibleStyle={areaFocusRing}
-          opacity={valueMotionStyle.opacity}
-          // LC-25 native value tween intentionally disabled: Tamagui's RN
-          // animation driver crashes Hermes ("Cannot add new property
-          // '_tracking'") when animating a text input. Web keeps the CSS tween.
-          {...(inputProps as any)}
-          {...(isWeb
-            ? {
-                style: {
-                  ...(inputProps as any)?.style,
-                  transition: valueMotionStyle.transition,
-                  opacity: valueMotionStyle.opacity,
-                },
-              }
-            : undefined)}
-          {...(onBlurHandler
-            ? {
-                onBlur: () => {
-                  typingRef.current = false;
-                  onBlurHandler();
-                },
-              }
-            : {
-                onBlur: () => {
-                  typingRef.current = false;
-                },
-              })}
-          {...(onFocusHandler ? { onFocus: onFocusHandler } : undefined)}
-        />
+    const spinColumn = (edge: "start" | "end") => (
+      <View
+        flexDirection="column"
+        alignSelf="stretch"
+        flexShrink={0}
+        width={controlSize}
+        borderInlineStartWidth={edge === "end" ? 1 : 0}
+        borderInlineEndWidth={edge === "start" ? 1 : 0}
+        borderColor={formInputColors.border.base}
+      >
+        {incrementButton}
+        {decrementButton}
+      </View>
+    );
 
-        {showButtons && !readOnly && (buttonPosition === "right" || buttonPosition === "both") && (
-          <Button
-            size={knobProps.sizeToken}
-            disabled={disabled || atMax}
-            tabIndex={-1}
-            aria-label={t("Increase")}
-            onPressIn={repeatIncrement.onPressIn}
-            onPressOut={repeatIncrement.onPressOut}
-            icon={Plus}
-          />
-        )}
-      </ControlGroup>
+    const area = (
+      <InputParts.Area
+        ref={areaRef}
+        id={id}
+        value={inputValue}
+        placeholder={placeholder}
+        keyboardType={precision > 0 ? "decimal-pad" : "numeric"}
+        inputMode={precision > 0 ? "decimal" : "numeric"}
+        autoComplete="off"
+        disabled={disabled}
+        readOnly={!!readOnly}
+        role="spinbutton"
+        aria-valuenow={currentValue ?? undefined}
+        aria-valuemin={boundsLo}
+        aria-valuemax={boundsHi}
+        // Labelled: the sibling Label wires `aria-labelledby` onto this id
+        // itself — naming it here too doubles the spoken name.
+        aria-label={label ? undefined : t("Number")}
+        aria-required={required || undefined}
+        aria-invalid={hasError || undefined}
+        aria-readonly={readOnly || undefined}
+        data-stepper-value
+        data-stepper-live={live ? "true" : undefined}
+        data-stepper-flash={valueFlash ? "true" : undefined}
+        onChangeText={readOnly ? undefined : handleInputChange}
+        textAlign="center"
+        opacity={valueMotionStyle.opacity}
+        // LC-25 native value tween intentionally disabled: Tamagui's RN
+        // animation driver crashes Hermes ("Cannot add new property
+        // '_tracking'") when animating a text input. Web keeps the CSS tween.
+        {...(inputProps as any)}
+        {...(isWeb
+          ? {
+              style: {
+                ...(inputProps as any)?.style,
+                transition: valueMotionStyle.transition,
+                opacity: valueMotionStyle.opacity,
+              },
+            }
+          : undefined)}
+        onKeyDown={(event: any) => {
+          (inputProps as any)?.onKeyDown?.(event);
+          if (event.defaultPrevented) return;
+          handleStepperKeyDown(event);
+        }}
+        {...(onBlurHandler
+          ? {
+              onBlur: () => {
+                typingRef.current = false;
+                onBlurHandler();
+              },
+            }
+          : {
+              onBlur: () => {
+                typingRef.current = false;
+              },
+            })}
+        {...(onFocusHandler ? { onFocus: onFocusHandler } : undefined)}
+      />
+    );
+
+    // LC-71: ring rides Input.Box so +/− sit inside the perceived boundary.
+    const box = (
+      <InputParts.Box size={controlSize} disabled={disabled} data-stepper="true">
+        {showSpin && buttonPosition === "both" ? decrementButton : null}
+        {showSpin && buttonPosition === "left" ? spinColumn("start") : null}
+        {area}
+        {showSpin && buttonPosition === "right" ? spinColumn("end") : null}
+        {showSpin && buttonPosition === "both" ? incrementButton : null}
+      </InputParts.Box>
     );
 
     // Wrap with wheel handler on web
     if (isWeb && !disabled && !readOnly) {
-      return <div {...wheelProps}>{controlGroup}</div>;
+      return (
+        <div {...wheelProps} style={{ minWidth: 0, width: "100%" }}>
+          {box}
+        </div>
+      );
     }
-    return controlGroup;
+    return box;
   };
 
   // Render skeleton placeholder
   if (skeleton) {
     return (
-      <InputParts size={size || knobProps.sizeToken}>
-        {label && <Skeleton variant="text" width="30%" height={14} />}
-        <Skeleton variant="rounded" width="100%" height={knobProps.sizeToken} />
+      <InputParts size={controlSize}>
+        {label && <Skeleton variant="text" width="30%" />}
+        <Skeleton variant="rounded" width="100%" height={controlSize} />
       </InputParts>
     );
   }
@@ -411,7 +601,7 @@ export function Stepper<
         // the sibling label/helper readable) — it needs the disabled state.
         disabled={disabled}
       >
-        <InputParts size={size || knobProps.sizeToken}>
+        <InputParts size={controlSize}>
           {renderNumberRow(commitStandalone, undefined, !!errorProp)}
         </InputParts>
       </FieldLayout>
@@ -450,6 +640,7 @@ export function Stepper<
           parseValue={parseValue}
           clampValue={clampValue}
           knobProps={knobProps}
+          controlSize={controlSize}
           renderNumberRow={renderNumberRow}
         />
       )}
@@ -467,6 +658,7 @@ function StepperFieldRenderer<TData>({
   parseValue,
   clampValue,
   knobProps,
+  controlSize,
   renderNumberRow,
 }: any) {
   const isFieldUpdateRef = useRef(false);
@@ -513,7 +705,7 @@ function StepperFieldRenderer<TData>({
       // LC-40: see standalone branch — FieldLayout carries dimWhole.
       disabled={fieldProps.disabled}
     >
-      <InputParts size={fieldProps.size || knobProps.sizeToken}>
+      <InputParts size={fieldProps.size || controlSize || knobProps.sizeToken}>
         {renderNumberRow(
           undefined,
           () => field.handleChange(parseValue(inputValue) as TData),