@multiplatform.one/forms 6.0.4 → 6.3.0

package/src/fields/Stepper/index.tsx

@@ -1,5 +1,13 @@
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
-import { type ComponentProps, useCallback, useEffect, useRef, useState } from "react";
+import {
+  type ComponentProps,
+  type MutableRefObject,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { ensureFocusVisibleRing } from "@multiplatform.one/theme";
 import { isWeb, useProps } from "tamagui";
 import { Input as TamaguiInput } from "tamagui";
 
@@ -18,12 +26,25 @@ import { Input as InputParts } from "../../InputParts";
 import { ControlGroup } from "../../ControlGroup";
 import { Minus, Plus } from "@tamagui/lucide-icons-2";
 import { Button } from "../../Button";
+import { t } from "../../shared/t";
 import type { FieldComponentProps, Validator } from "../../types";
 
 const repeatDelay = 400;
 const repeatInterval = 80;
 
-function useRepeatAction(action: () => void) {
+/** CSS timings for discrete value motion (mirrors theme animationConfig). */
+const stepperCssTimings: Record<string, string> = {
+  bouncy: "ease-in 200ms",
+  lazy: "ease-in 600ms",
+  slow: "ease-in 500ms",
+  medium: "ease-in-out 250ms",
+  quick: "ease-in 100ms",
+  tooltip: "ease-in 400ms",
+  snappy: "ease-out 80ms",
+  gentle: "ease-in-out 450ms",
+};
+
+function useRepeatAction(action: () => void, repeatingRef: MutableRefObject<boolean>) {
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
   const actionRef = useRef(action);
@@ -38,15 +59,18 @@ function useRepeatAction(action: () => void) {
       clearInterval(intervalRef.current);
       intervalRef.current = null;
     }
-  }, []);
+    repeatingRef.current = false;
+  }, [repeatingRef]);
 
   const start = useCallback(() => {
     stop();
+    // First tap is discrete; interval ticks are continuous scrub (LC-25).
     actionRef.current();
     timerRef.current = setTimeout(() => {
+      repeatingRef.current = true;
       intervalRef.current = setInterval(() => actionRef.current(), repeatInterval);
     }, repeatDelay);
-  }, [stop]);
+  }, [stop, repeatingRef]);
 
   useEffect(() => stop, [stop]);
 
@@ -61,7 +85,9 @@ export type StepperProps<
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > = Omit<
   FormFieldProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
-  "children" | "field"
+  // "onChange": FormFieldProps carries the DOM ChangeEventHandler from
+  // YStackProps; this field exposes a canonical value callback instead.
+  "children" | "field" | "onChange"
 > &
   Partial<
     Omit<
@@ -79,6 +105,8 @@ export type StepperProps<
     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;
     /** When true, renders a skeleton placeholder instead of the stepper */
     skeleton?: boolean;
     /** When true, uses compact sizing */
@@ -117,14 +145,23 @@ export function Stepper<
     required,
     size,
     onBlur,
+    onChange,
     skeleton,
     compact,
     id: idProp,
     ...restProps
   } = useProps(props);
 
-  const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
+  const { resolvedForm, knobProps, control, 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,
+  });
 
   // Initialize inputValue from defaultValue for standalone mode
   const [inputValue, setInputValue] = useState<string>(() => {
@@ -133,10 +170,24 @@ export function Stepper<
     }
     return "";
   });
+  // LC-25: discrete +/- taps tween the value chrome; hold-repeat / typing stay live.
+  // Opacity (not transform) — Tamagui Input owns transform internally on web.
+  const [valueFlash, setValueFlash] = useState(false);
+  const repeatingRef = useRef(false);
+  const typingRef = useRef(false);
   const incrementRef = useRef<() => void>(() => {});
   const decrementRef = useRef<() => void>(() => {});
-  const repeatIncrement = useRepeatAction(() => incrementRef.current());
-  const repeatDecrement = useRepeatAction(() => decrementRef.current());
+
+  const pulseDiscreteStep = useCallback(() => {
+    if (repeatingRef.current || typingRef.current) return;
+    setValueFlash(true);
+    // Hold the dipped opacity long enough for the CSS transition to paint
+    // intermediates (quick = 100ms).
+    setTimeout(() => setValueFlash(false), 90);
+  }, []);
+
+  const repeatIncrement = useRepeatAction(() => incrementRef.current(), repeatingRef);
+  const repeatDecrement = useRepeatAction(() => decrementRef.current(), repeatingRef);
 
   // Format number to string with precision
   const formatValue = useCallback(
@@ -157,15 +208,19 @@ export function Stepper<
     [allowEmpty],
   );
 
+  // Normalize bounds so reversed min/max still clamp into the real range
+  const boundsLo = min !== undefined && max !== undefined ? Math.min(min, max) : min;
+  const boundsHi = min !== undefined && max !== undefined ? Math.max(min, max) : max;
+
   // Clamp value within min/max bounds
   const clampValue = useCallback(
     (value: number | null): number | null => {
       if (value === null) return null;
-      if (min !== undefined && value < min) return min;
-      if (max !== undefined && value > max) return max;
+      if (boundsLo !== undefined && value < boundsLo) return boundsLo;
+      if (boundsHi !== undefined && value > boundsHi) return boundsHi;
       return value;
     },
-    [min, max],
+    [boundsLo, boundsHi],
   );
 
   // Increment value
@@ -173,18 +228,23 @@ export function Stepper<
     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]);
+  }, [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]);
+  }, [inputValue, parseValue, clampValue, step, formatValue, name, onChange, pulseDiscreteStep]);
 
   incrementRef.current = increment;
   decrementRef.current = decrement;
@@ -199,6 +259,7 @@ export function Stepper<
   // Handle input change
   const handleInputChange = useCallback(
     (text: string) => {
+      typingRef.current = true;
       // Allow empty string
       if (text === "" && allowEmpty) {
         setInputValue("");
@@ -223,14 +284,27 @@ export function Stepper<
     onFocusHandler?: () => void,
     hasError?: boolean,
   ) => {
+    const currentValue = parseValue(inputValue);
+    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;
+    // 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}
+            disabled={disabled || atMin}
             tabIndex={-1}
-            aria-label="Decrease"
+            aria-label={t("Decrease")}
             onPressIn={repeatDecrement.onPressIn}
             onPressOut={repeatDecrement.onPressOut}
             icon={Minus}
@@ -238,27 +312,59 @@ export function Stepper<
         )}
 
         <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"
-          {...(onBlurHandler ? { onBlur: onBlurHandler } : undefined)}
-          {...(onFocusHandler ? { onFocus: onFocusHandler } : undefined)}
+          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)}
         />
 
         {showButtons && !readOnly && (buttonPosition === "right" || buttonPosition === "both") && (
           <Button
             size={knobProps.sizeToken}
-            disabled={disabled}
+            disabled={disabled || atMax}
             tabIndex={-1}
-            aria-label="Increase"
+            aria-label={t("Increase")}
             onPressIn={repeatIncrement.onPressIn}
             onPressOut={repeatIncrement.onPressOut}
             icon={Plus}
@@ -285,6 +391,11 @@ export function Stepper<
   }
 
   if (!resolvedForm || !name) {
+    const commitStandalone = () => {
+      const clamped = clampValue(parseValue(inputValue));
+      setInputValue(formatValue(clamped));
+      onChange?.(clamped);
+    };
     return (
       <FieldLayout
         id={id}
@@ -296,9 +407,12 @@ export function Stepper<
         size={size}
         knobProps={knobProps}
         onBlur={onBlur}
+        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+        // the sibling label/helper readable) — it needs the disabled state.
+        disabled={disabled}
       >
         <InputParts size={size || knobProps.sizeToken}>
-          {renderNumberRow(undefined, undefined, !!errorProp)}
+          {renderNumberRow(commitStandalone, undefined, !!errorProp)}
         </InputParts>
       </FieldLayout>
     );
@@ -325,6 +439,7 @@ export function Stepper<
             required,
             size,
             readOnly,
+            disabled,
             onBlur,
             ...restProps,
           }}
@@ -395,6 +510,8 @@ function StepperFieldRenderer<TData>({
       size={fieldProps.size}
       knobProps={knobProps}
       onBlur={mergeFieldHandler(field, "handleBlur", fieldProps.onBlur)}
+      // LC-40: see standalone branch — FieldLayout carries dimWhole.
+      disabled={fieldProps.disabled}
     >
       <InputParts size={fieldProps.size || knobProps.sizeToken}>
         {renderNumberRow(

package/src/fields/Switch/Switch.spec.tsx

@@ -53,6 +53,164 @@ describe("Switch", () => {
       if (switchElement) fireEvent.click(switchElement);
       expect(onCheckedChange).toHaveBeenCalledWith(false);
     });
+
+    it("fires canonical onChange and the deprecated onCheckedChange alias once each", async () => {
+      const onChange = vi.fn();
+      const onCheckedChange = vi.fn();
+      const result = renderWithProviders(
+        <Switch
+          name="switch"
+          defaultValue={false}
+          onChange={onChange}
+          onCheckedChange={onCheckedChange}
+        />,
+      );
+      const switchElement = result.getSwitch();
+      await act(async () => {
+        if (switchElement) fireEvent.click(switchElement);
+      });
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(true);
+      expect(onCheckedChange).toHaveBeenCalledTimes(1);
+      expect(onCheckedChange).toHaveBeenCalledWith(true);
+    });
+
+    it("should toggle on via press+drag across the track", async () => {
+      const onCheckedChange = vi.fn();
+      const result = renderWithProviders(
+        <Switch name="switch" defaultValue={false} onCheckedChange={onCheckedChange} />,
+      );
+      const switchElement = result.getSwitch();
+      expect(switchElement).toBeTruthy();
+      if (!switchElement) return;
+
+      await act(async () => {
+        fireEvent.pointerDown(switchElement, { clientX: 0, pointerId: 1, button: 0 });
+      });
+      await act(async () => {
+        fireEvent(
+          document,
+          new PointerEvent("pointermove", { clientX: 48, pointerId: 1, bubbles: true }),
+        );
+      });
+      await act(async () => {
+        fireEvent(
+          document,
+          new PointerEvent("pointerup", { clientX: 48, pointerId: 1, bubbles: true }),
+        );
+      });
+
+      expect(onCheckedChange).toHaveBeenCalledWith(true);
+      expect(switchElement.getAttribute("aria-checked")).toBe("true");
+    });
+
+    it("should toggle off via press+drag across the track", async () => {
+      const onCheckedChange = vi.fn();
+      const result = renderWithProviders(
+        <Switch name="switch" defaultValue={true} onCheckedChange={onCheckedChange} />,
+      );
+      const switchElement = result.getSwitch();
+      expect(switchElement).toBeTruthy();
+      if (!switchElement) return;
+
+      await act(async () => {
+        fireEvent.pointerDown(switchElement, { clientX: 48, pointerId: 1, button: 0 });
+      });
+      await act(async () => {
+        fireEvent(
+          document,
+          new PointerEvent("pointermove", { clientX: 0, pointerId: 1, bubbles: true }),
+        );
+      });
+      await act(async () => {
+        fireEvent(
+          document,
+          new PointerEvent("pointerup", { clientX: 0, pointerId: 1, bubbles: true }),
+        );
+      });
+
+      expect(onCheckedChange).toHaveBeenCalledWith(false);
+      expect(switchElement.getAttribute("aria-checked")).toBe("false");
+    });
+
+    it("does not enter drag mode below the drag-intent threshold (mid-flight retargets must not teleport)", async () => {
+      const onCheckedChange = vi.fn();
+      const result = renderWithProviders(
+        <Switch name="switch" defaultValue={false} onCheckedChange={onCheckedChange} />,
+      );
+      const switchElement = result.getSwitch();
+      expect(switchElement).toBeTruthy();
+      if (!switchElement) return;
+      const thumb = switchElement.querySelector(".is_SwitchThumb") as HTMLElement;
+      expect(thumb).toBeTruthy();
+
+      await act(async () => {
+        fireEvent.pointerDown(switchElement, { clientX: 0, pointerId: 1, button: 0 });
+      });
+      await act(async () => {
+        // 5px < SWITCH_DRAG_INTENT_PX (10): must NOT engage dragX — engaging
+        // it snaps the thumb + disables its transition, teleporting any
+        // in-flight toggle animation (interruptibility, spec Axiom 4).
+        fireEvent(
+          document,
+          new PointerEvent("pointermove", { clientX: 5, pointerId: 1, bubbles: true }),
+        );
+      });
+      // Thumb stays at its resting position — not tracking the sub-intent pointer.
+      expect(thumb.style.transform || "").not.toContain("5px");
+
+      await act(async () => {
+        fireEvent(
+          document,
+          new PointerEvent("pointerup", { clientX: 5, pointerId: 1, bubbles: true }),
+        );
+      });
+      // Sub-intent gesture is a click: the follow-up click toggle still fires.
+      await act(async () => {
+        fireEvent.click(switchElement);
+      });
+      expect(onCheckedChange).toHaveBeenCalledWith(true);
+    });
+
+    it("should not toggle when a drag snaps back below the midpoint", async () => {
+      const onCheckedChange = vi.fn();
+      const result = renderWithProviders(
+        <Switch name="switch" defaultValue={false} onCheckedChange={onCheckedChange} />,
+      );
+      const switchElement = result.getSwitch();
+      expect(switchElement).toBeTruthy();
+      if (!switchElement) return;
+
+      await act(async () => {
+        fireEvent.pointerDown(switchElement, { clientX: 0, pointerId: 1, button: 0 });
+      });
+      await act(async () => {
+        // Past drag-intent (10px) but still below the snap midpoint.
+        fireEvent(
+          document,
+          new PointerEvent("pointermove", { clientX: 12, pointerId: 1, bubbles: true }),
+        );
+      });
+      await act(async () => {
+        fireEvent(
+          document,
+          new PointerEvent("pointerup", { clientX: 12, pointerId: 1, bubbles: true }),
+        );
+      });
+      // Same-gesture press that follows a drag must not flip the value.
+      await act(async () => {
+        fireEvent.click(switchElement);
+      });
+
+      expect(onCheckedChange).not.toHaveBeenCalled();
+      expect(switchElement.getAttribute("aria-checked")).toBe("false");
+
+      // A later click (new gesture) still toggles.
+      await act(async () => {
+        fireEvent.click(switchElement);
+      });
+      expect(onCheckedChange).toHaveBeenCalledWith(true);
+    });
   });
 
   describe("with form context", () => {

package/src/fields/Switch/Switch.stories.tsx

@@ -125,6 +125,9 @@ export const Interactive: Story = {
       const [checked, setChecked] = useState(false);
       return (
         <YStack gap="$4" maxWidth={400}>
+          <Paragraph size="$2" color="$placeholderColor">
+            Click to toggle, or press and drag the thumb on/off.
+          </Paragraph>
           <Switch
             label="Enable notifications"
             checked={checked}
@@ -186,3 +189,8 @@ export const Comparison: StoryObj = {
     return <ComparisonExample />;
   },
 };
+
+/** Loading placeholder — the skeleton mirrors track + label anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  args: { label: "Enable notifications", skeleton: true },
+};