@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/fields/OTPInput/index.tsx

@@ -1,11 +1,13 @@
 import type { Validator } from "../../types";
 
 import type { DeepKeys, DeepValue } from "@tanstack/form-core";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { ensureFocusVisibleRing, useResolvedKnobs } from "@multiplatform.one/theme";
 import {
   type ClipboardEvent,
   type ComponentProps,
   Fragment,
+  type KeyboardEvent,
+  memo,
   type RefObject,
   useCallback,
   useEffect,
@@ -23,8 +25,9 @@ import {
   useResolvedValidators,
 } from "../../shared/utils";
 import type { FormFieldProps } from "../../fieldLayout";
-import { Input as InputParts } from "../../InputParts";
+import { FocusContext, Input as InputParts, InputContext } from "../../InputParts";
 import { Skeleton } from "../../Skeleton";
+import { t } from "../../shared/t";
 import type { FieldComponentProps } from "../../types";
 
 export type OTPInputProps<
@@ -35,7 +38,9 @@ export type OTPInputProps<
   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<
@@ -60,25 +65,87 @@ export type OTPInputProps<
     compact?: boolean;
   };
 
+type OTPType = "numeric" | "alphanumeric" | "password";
+
+// Get validation pattern based on type
+const getValidationPattern = (inputType: string) => {
+  switch (inputType) {
+    case "numeric":
+      return /[^0-9]/g;
+    case "alphanumeric":
+      return /[^a-zA-Z0-9]/g;
+    case "password":
+      return /[^a-zA-Z0-9!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]/g;
+    default:
+      return /[^0-9]/g;
+  }
+};
+
+// Get secure text entry based on type
+const getSecureTextEntry = (inputType: string, secure: boolean) => {
+  if (inputType === "password") return true;
+  return secure;
+};
+
+/** Split a value into per-cell digits, dropping characters the type forbids */
+const valueToDigits = (value: string, inputType: string, length: number): string[] =>
+  value
+    .replace(getValidationPattern(inputType), "")
+    .slice(0, length)
+    .split("")
+    .concat(Array(length).fill(""))
+    .slice(0, length);
+
+const navigationKeys = ["Backspace", "ArrowLeft", "ArrowRight", "Home", "End"];
+
+/**
+ * Digit cells own their focus ring (DG-A11Y-01): the ring must be CSS-driven
+ * on the focused input itself — Input.Box's state-driven ring paints on the
+ * wrapper a frame later, which forced-focus a11y probes (interact sweep)
+ * never see. The Box ring is therefore suppressed for OTP cells (see the
+ * no-op FocusContext below) so the cell shows exactly one ring.
+ */
+const suppressBoxFocusRing = { focused: false, setFocused: (_val: boolean) => {} };
+
 interface OTPDigitInputProps {
   value: string;
+  type: OTPType;
   onChange: (value: string) => void;
   onKeyPress: (key: string) => void;
   onFocus: () => void;
   onBlur: () => void;
-  onPaste?: (text: string) => void;
+  onPaste: (text: string) => void;
   autoFocus?: boolean;
   secureTextEntry?: boolean;
   disabled?: boolean;
   readOnly?: boolean;
   required?: boolean;
   hasError?: boolean;
-  inputProps?: ComponentProps<typeof Input>;
-  inputRef?: RefObject<TamaguiElement | null>;
+  digitIndex: number;
+  digitCount: number;
+  fieldId?: string;
+  hasLabel?: boolean;
+  inputProps?: Omit<ComponentProps<typeof Input>, "value" | "onChangeText" | "ref">;
+  /** Stable per-cell element ref (select-on-focus / autoFocus target). */
+  inputRef: RefObject<TamaguiElement | null>;
+  /** Stable ref callback wiring this cell's element into the parent refs. */
+  attachRef: (el: TamaguiElement | null) => void;
 }
 
-function OTPDigitInput({
+/**
+ * One digit cell.
+ *
+ * MEMOIZED with per-cell-stable props on purpose (iOS-sweep fix): every
+ * focus/blur/auto-advance flips OTP-root state (focusedIndex/digits), and on
+ * iOS Fabric a re-render that touches the focused RN TextInput resigns the
+ * first responder — the keyboard closed the instant a digit took focus, so
+ * cells could never be typed into. With React.memo + stable handlers, root
+ * re-renders skip the untouched cells entirely and focus survives; only the
+ * cell whose `value` changed re-renders.
+ */
+const OTPDigitInput = memo(function OTPDigitInput({
   value,
+  type,
   onChange,
   onKeyPress,
   onFocus,
@@ -90,20 +157,32 @@ function OTPDigitInput({
   readOnly,
   required,
   hasError,
+  digitIndex,
+  digitCount,
+  fieldId,
+  hasLabel,
   inputProps,
-  inputRef: externalRef,
+  inputRef,
+  attachRef,
 }: OTPDigitInputProps) {
-  const internalRef = useRef<TamaguiElement | null>(null);
-  const inputRef = externalRef || internalRef;
   const didFinishSSR = useDidFinishSSR();
-  const { knobProps } = useResolvedKnobs();
-  const cellSize = knobProps.sizeToken;
+  const { knobProps, control } = useResolvedKnobs();
+  // Honor the size the field was given (InputParts root receives
+  // `fieldProps.size || knobProps.sizeToken`): table cells pass a compact
+  // token, and default-size 44pt digit squares overflow the ~$8-wide cell.
+  const { size: contextSize } = InputContext.useStyledContext();
+  const cellSize = contextSize ?? knobProps.sizeToken;
+  // Inset (-2) so the ring stays inside the cell and adjacent cells don't clip it.
+  const cellFocusRing = ensureFocusVisibleRing({
+    ...control.focusVisibleKnobProps,
+    outlineOffset: -2,
+  });
 
   useEffect(() => {
     if (autoFocus && didFinishSSR && inputRef.current) {
       (inputRef.current as HTMLElement).focus();
     }
-  }, [autoFocus, didFinishSSR]);
+  }, [autoFocus, didFinishSSR, inputRef]);
 
   const cellRadius = getOTPCellRadius(knobProps.borderRadius.borderRadius);
 
@@ -111,64 +190,233 @@ function OTPDigitInput({
     <InputParts.Box
       width={cellSize}
       height={cellSize}
+      // Inside table cells Input.Box goes chromeless with `flex={1}` —
+      // flex-basis 0 beats `width` in Yoga and every digit collapses to 0pt
+      // (the row shrinks to just its gaps). Digit cells are fixed squares, so
+      // pin them inflexible; outside cells this is the default anyway.
+      flexGrow={0}
+      flexShrink={0}
+      flexBasis="auto"
       borderRadius={cellRadius}
-      tabIndex={-1}
-      onFocus={() => {
-        onFocus();
-        if (isWeb && inputRef.current) {
-          requestAnimationFrame(() => {
-            (inputRef.current as unknown as HTMLInputElement)?.select();
-          });
-        }
-      }}
-      onBlur={onBlur}
+      // LC-40: forward `disabled` so each cell renders the washed chrome.
+      disabled={disabled}
+      // Web only: keep the Box out of the tab order. The focus handlers live
+      // on the Area itself (native RN Views neither focus nor bubble focus).
+      {...(isWeb ? { tabIndex: -1 } : {})}
     >
-      <InputParts.Area
-        ref={inputRef}
-        value={value}
-        keyboardType="number-pad"
-        textContentType="oneTimeCode"
-        autoComplete="one-time-code"
-        secureTextEntry={secureTextEntry}
-        textAlign="center"
-        padding={0}
-        disabled={disabled}
-        readOnly={!!readOnly}
-        aria-required={required || undefined}
-        aria-invalid={hasError || undefined}
-        aria-readonly={readOnly || undefined}
-        onChangeText={(text) => {
-          const filtered = text.replace(/[^0-9]/g, "");
-          if (!filtered) return;
-          const newChar =
-            filtered.length > 1 && value
-              ? (filtered.replace(value, "") || filtered)[0]
-              : filtered[0];
-          onChange(newChar);
-        }}
-        onKeyPress={(e) => {
-          const event = e.nativeEvent;
-          onKeyPress(event.key);
-        }}
-        {...(isWeb
-          ? {
-              onPaste: (e: ClipboardEvent<HTMLInputElement>) => {
-                e.preventDefault();
-                const pastedData = e.clipboardData?.getData("text") || "";
-                if (onPaste && pastedData) {
-                  onPaste(pastedData);
-                }
-              },
+      <FocusContext.Provider {...suppressBoxFocusRing}>
+        <InputParts.Area
+          ref={attachRef}
+          value={value}
+          focusStyle={cellFocusRing}
+          focusVisibleStyle={cellFocusRing}
+          keyboardType="number-pad"
+          textContentType="oneTimeCode"
+          autoComplete="one-time-code"
+          secureTextEntry={secureTextEntry}
+          textAlign="center"
+          padding={0}
+          disabled={disabled}
+          readOnly={!!readOnly}
+          id={digitIndex === 0 ? fieldId : undefined}
+          aria-label={
+            hasLabel
+              ? `Digit ${digitIndex + 1} of ${digitCount}`
+              : `One-time code digit ${digitIndex + 1} of ${digitCount}`
+          }
+          aria-required={required || undefined}
+          aria-invalid={hasError || undefined}
+          aria-readonly={readOnly || undefined}
+          onFocus={() => {
+            onFocus();
+            if (isWeb && inputRef.current) {
+              requestAnimationFrame(() => {
+                (inputRef.current as unknown as HTMLInputElement)?.select();
+              });
             }
-          : {})}
-        {...(inputProps as Record<string, unknown>)}
-      />
+          }}
+          onBlur={onBlur}
+          onChangeText={(text) => {
+            const pattern = getValidationPattern(type);
+            const filtered = text.replace(pattern, "");
+            if (!filtered) return;
+            const newChar =
+              filtered.length > 1 && value
+                ? (filtered.replace(value, "") || filtered)[0]
+                : filtered[0];
+            onChange(newChar);
+          }}
+          onKeyPress={
+            isWeb
+              ? undefined
+              : (e) => {
+                  const event = e.nativeEvent;
+                  onKeyPress(event.key);
+                }
+          }
+          {...(isWeb
+            ? {
+                // react-native-web never fires onKeyPress reliably, so drive
+                // navigation/deletion from the DOM keydown event instead
+                onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => {
+                  if (navigationKeys.includes(e.key)) {
+                    e.preventDefault();
+                    onKeyPress(e.key);
+                  }
+                },
+                onPaste: (e: ClipboardEvent<HTMLInputElement>) => {
+                  e.preventDefault();
+                  const pastedData = e.clipboardData?.getData("text") || "";
+                  if (pastedData) {
+                    onPaste(pastedData);
+                  }
+                },
+              }
+            : {})}
+          {...(inputProps as Record<string, unknown>)}
+        />
+      </FocusContext.Provider>
     </InputParts.Box>
   );
+});
+
+// ---------------------------------------------------------------------------
+// OTPCellsRow — the digit row shared by the standalone and form branches
+// ---------------------------------------------------------------------------
+
+/** Stable per-cell handler bundle (see OTPDigitInput memo note). */
+interface StableCell {
+  onChange: (value: string) => void;
+  onKeyPress: (key: string) => void;
+  onPaste: (text: string) => void;
+  onFocus: () => void;
+  onBlur: () => void;
+  inputRef: RefObject<TamaguiElement | null>;
+  attachRef: (el: TamaguiElement | null) => void;
 }
 
-// Inner component that handles field state
-type OTPType = "numeric" | "alphanumeric" | "password";
+interface OTPCellsRowProps {
+  digits: string[];
+  length: number;
+  type: OTPType;
+  secureTextEntry: boolean;
+  autoFocus: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  hasError: boolean;
+  fieldId?: string;
+  hasLabel: boolean;
+  separator?: string;
+  clearable: boolean;
+  inputProps?: Omit<ComponentProps<typeof Input>, "value" | "onChangeText" | "ref">;
+  inputRefs: RefObject<Array<HTMLElement | null>>;
+  onDigitChange: (index: number, value: string) => void;
+  onKeyPress: (index: number, key: string) => void;
+  onPaste: (text: string) => void;
+  onFocusIndex: (index: number) => void;
+  onClear: () => void;
+}
+
+function OTPCellsRow({
+  digits,
+  length,
+  type,
+  secureTextEntry,
+  autoFocus,
+  disabled,
+  readOnly,
+  required,
+  hasError,
+  fieldId,
+  hasLabel,
+  separator,
+  clearable,
+  inputProps,
+  inputRefs,
+  onDigitChange,
+  onKeyPress,
+  onPaste,
+  onFocusIndex,
+  onClear,
+}: OTPCellsRowProps) {
+  const { knobProps } = useResolvedKnobs();
+
+  // Handlers route through a `latest` ref so the per-cell callbacks handed to
+  // the memoized cells never change identity (identity churn re-renders the
+  // focused cell, and on iOS Fabric that resigns the first responder).
+  const latest = useRef({ onDigitChange, onKeyPress, onPaste, onFocusIndex });
+  latest.current = { onDigitChange, onKeyPress, onPaste, onFocusIndex };
+
+  const cellsRef = useRef<Map<number, StableCell>>(new Map());
+  const cellAt = (index: number): StableCell => {
+    let cell = cellsRef.current.get(index);
+    if (!cell) {
+      const inputRef: RefObject<TamaguiElement | null> = { current: null };
+      cell = {
+        onChange: (value) => latest.current.onDigitChange(index, value),
+        onKeyPress: (key) => latest.current.onKeyPress(index, key),
+        onPaste: (text) => latest.current.onPaste(text),
+        onFocus: () => latest.current.onFocusIndex(index),
+        onBlur: () => latest.current.onFocusIndex(-1),
+        inputRef,
+        attachRef: (el) => {
+          inputRef.current = el;
+          inputRefs.current[index] = el as HTMLElement | null;
+        },
+      };
+      cellsRef.current.set(index, cell);
+    }
+    return cell;
+  };
+
+  return (
+    <XStack gap={knobProps.gap.gap} alignItems="center">
+      {Array.from({ length }, (_, index) => {
+        const cell = cellAt(index);
+        return (
+          <Fragment key={`digit-${index}`}>
+            <OTPDigitInput
+              value={digits[index]}
+              type={type}
+              onChange={cell.onChange}
+              onKeyPress={cell.onKeyPress}
+              onPaste={cell.onPaste}
+              onFocus={cell.onFocus}
+              onBlur={cell.onBlur}
+              autoFocus={autoFocus && index === 0}
+              secureTextEntry={getSecureTextEntry(type, secureTextEntry)}
+              disabled={disabled}
+              readOnly={readOnly}
+              required={required}
+              hasError={hasError}
+              digitIndex={index}
+              digitCount={length}
+              fieldId={fieldId}
+              hasLabel={hasLabel}
+              inputProps={inputProps}
+              inputRef={cell.inputRef}
+              attachRef={cell.attachRef}
+            />
+            {separator && index < length - 1 && <Text>{separator}</Text>}
+          </Fragment>
+        );
+      })}
+      {clearable && !readOnly && (
+        <Button
+          circular
+          onPress={onClear}
+          disabled={disabled}
+          marginInlineStart="$2"
+          aria-label={t("Clear")}
+          tabIndex={-1}
+        >
+          ×
+        </Button>
+      )}
+    </XStack>
+  );
+}
 
 /** Minimal field interface for OTPFieldRenderer */
 interface OTPFieldApi {
@@ -189,10 +437,7 @@ interface OTPFieldRendererProps {
   handleDigitChange: (index: number, value: string) => void;
   handleKeyPress: (index: number, key: string) => void;
   handlePaste: (text: string) => void;
-  focusedIndex: number;
   setFocusedIndex: (index: number) => void;
-  getSecureTextEntry: (type: OTPType, secureTextEntry: boolean) => boolean;
-  getValidationPattern: (type: OTPType) => RegExp;
   autoFocus: boolean;
   type: OTPType;
   secureTextEntry: boolean;
@@ -220,10 +465,7 @@ function OTPFieldRenderer({
   handleDigitChange,
   handleKeyPress,
   handlePaste,
-  focusedIndex: _focusedIndex,
   setFocusedIndex,
-  getSecureTextEntry,
-  getValidationPattern,
   autoFocus,
   type,
   secureTextEntry,
@@ -249,33 +491,28 @@ function OTPFieldRenderer({
     const fieldValue = field.state.value as string;
     if (fieldValue && fieldValue !== lastFieldValueRef.current) {
       lastFieldValueRef.current = fieldValue;
-      const fieldDigits = fieldValue
-        .slice(0, length)
-        .split("")
-        .concat(Array(length).fill(""))
-        .slice(0, length);
-      setDigits(fieldDigits);
+      setDigits(valueToDigits(fieldValue, type, length));
     }
-  }, [field.state.value, length, setDigits]);
-
-  // Update field value when digits change
+  }, [field.state.value, type, length, setDigits]);
+
+  // Update field value when digits change. Callbacks live in refs so a new
+  // onChange/onComplete identity alone cannot re-emit and loop parents.
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
   useEffect(() => {
     const code = digits.join("");
-    if (code !== lastFieldValueRef.current) {
-      lastFieldValueRef.current = code;
-      fieldHandleChangeRef.current(code);
-    }
-
-    // Only call callbacks if not disabled
-    if (!disabled) {
-      if (onChange) {
-        onChange(code);
-      }
-      if (code.length === length && onComplete) {
-        onComplete(code);
-      }
+    if (code === lastFieldValueRef.current) return;
+    lastFieldValueRef.current = code;
+    fieldHandleChangeRef.current(code);
+
+    if (disabled) return;
+    onChangeRef.current?.(code);
+    if (code.length === length) {
+      onCompleteRef.current?.(code);
     }
-  }, [digits, length, disabled, onChange, onComplete]);
+  }, [digits, length, disabled]);
 
   const error = field.state.meta.errors.length
     ? String(field.state.meta.errors[0])
@@ -300,64 +537,33 @@ function OTPFieldRenderer({
       size={fieldProps.size}
       knobProps={knobProps as any}
       onBlur={fieldBlurHandler}
+      // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+      // the sibling label/helper readable) — it needs the disabled state.
+      disabled={disabled}
     >
       <InputParts size={fieldProps.size || knobProps.sizeToken}>
-        <XStack gap={knobProps.gap.gap} alignItems="center">
-          {Array.from({ length }, (_, index) => {
-            const inputRef = {
-              current: null,
-            } as RefObject<TamaguiElement | null>;
-            return (
-              <Fragment key={`digit-${index}`}>
-                <OTPDigitInput
-                  value={digits[index]}
-                  onChange={(value) => handleDigitChange(index, value)}
-                  onKeyPress={(key) => handleKeyPress(index, key)}
-                  onPaste={handlePaste}
-                  onFocus={() => setFocusedIndex(index)}
-                  onBlur={() => setFocusedIndex(-1)}
-                  autoFocus={autoFocus && index === 0}
-                  secureTextEntry={getSecureTextEntry(type, secureTextEntry)}
-                  disabled={disabled}
-                  readOnly={readOnly}
-                  required={fieldProps.required}
-                  hasError={!!error}
-                  inputRef={inputRef}
-                  inputProps={{
-                    ...inputProps,
-                    ref: (el: TamaguiElement | null) => {
-                      inputRefs.current[index] = el as HTMLElement | null;
-                      inputRef.current = el;
-                    },
-                    onChangeText: (text: string) => {
-                      const pattern = getValidationPattern(type);
-                      const filtered = text.replace(pattern, "");
-                      if (!filtered) return;
-                      const newChar =
-                        filtered.length > 1 && digits[index]
-                          ? (filtered.replace(digits[index], "") || filtered)[0]
-                          : filtered[0];
-                      handleDigitChange(index, newChar);
-                    },
-                  }}
-                />
-                {separator && index < length - 1 && <Text>{separator}</Text>}
-              </Fragment>
-            );
-          })}
-          {clearable && !readOnly && (
-            <Button
-              circular
-              onPress={handleClear}
-              disabled={disabled}
-              marginLeft="$2"
-              aria-label="Clear"
-              tabIndex={-1}
-            >
-              ×
-            </Button>
-          )}
-        </XStack>
+        <OTPCellsRow
+          digits={digits}
+          length={length}
+          type={type}
+          secureTextEntry={secureTextEntry}
+          autoFocus={autoFocus}
+          disabled={disabled}
+          readOnly={readOnly}
+          required={fieldProps.required}
+          hasError={!!error}
+          fieldId={id}
+          hasLabel={Boolean(fieldProps.label)}
+          separator={separator}
+          clearable={clearable}
+          inputProps={inputProps}
+          inputRefs={inputRefs}
+          onDigitChange={handleDigitChange}
+          onKeyPress={handleKeyPress}
+          onPaste={handlePaste}
+          onFocusIndex={setFocusedIndex}
+          onClear={handleClear}
+        />
       </InputParts>
     </FieldLayout>
   );
@@ -405,26 +611,39 @@ export function OTPInput<
 
   const [digits, setDigits] = useState<string[]>(() => {
     if (value) {
-      return value.slice(0, length).split("").concat(Array(length).fill("")).slice(0, length);
+      return valueToDigits(value, type, length);
     }
     return Array(length).fill("");
   });
-  const [focusedIndex, setFocusedIndex] = useState<number>(autoFocus ? 0 : -1);
+  // Render-synced mirror so the stable handlers below can read the current
+  // digits without depending on the state (identity churn re-renders the
+  // memoized cells — see OTPDigitInput).
+  const digitsRef = useRef(digits);
+  digitsRef.current = digits;
+  // Tracked for parity with the previous implementation (focus state is not
+  // used for styling — the focused cell paints its own CSS/native ring).
+  const [, setFocusedIndex] = useState<number>(autoFocus ? 0 : -1);
   const inputRefs = useRef<Array<HTMLElement | null>>([]);
 
+  // Last code emitted to standalone onChange/onComplete. Prevents re-emitting
+  // the same code (SB-T2-10 idle loop when WiredTable rebuilt onChange each render).
+  const lastEmittedCodeRef = useRef<string | null>(null);
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+
   // Update digits when value prop changes (standalone mode)
   useEffect(() => {
-    if (value !== undefined) {
-      const newDigits = value
-        .slice(0, length)
-        .split("")
-        .concat(Array(length).fill(""))
-        .slice(0, length);
-      setDigits(newDigits);
-    }
-  }, [value, length]);
-
-  // Update form value when digits change (only in standalone mode)
+    if (value === undefined) return;
+    const next = valueToDigits(value, type, length);
+    setDigits((prev) => (prev.join("") === next.join("") ? prev : next));
+    // Keep emit guard aligned with the controlled value so remounts/syncs
+    // don't immediately bounce the same code back to the parent.
+    lastEmittedCodeRef.current = typeof value === "string" ? value : next.join("");
+  }, [value, type, length]);
+
+  // Emit standalone callbacks only when the joined code actually changes.
   useEffect(() => {
     // Skip if using form integration - callbacks are handled in OTPFieldRenderer
     if (resolvedForm && name) {
@@ -432,46 +651,51 @@ export function OTPInput<
     }
 
     const code = digits.join("");
+    if (code === lastEmittedCodeRef.current) return;
+    lastEmittedCodeRef.current = code;
 
-    // Call onChange callback
-    if (onChange && !disabled) {
-      onChange(code);
+    if (disabled) return;
+    onChangeRef.current?.(code);
+    if (code.length === length) {
+      onCompleteRef.current?.(code);
     }
+  }, [digits, length, resolvedForm, name, disabled]);
 
-    // Call onComplete when code is complete
-    if (code.length === length && onComplete && !disabled) {
-      onComplete(code);
-    }
-  }, [digits, length, resolvedForm, name, onChange, onComplete, disabled]);
-
+  // Stable handlers (functional updates; identities never change) so the
+  // memoized digit cells skip re-renders — see the OTPDigitInput memo note.
   const handleDigitChange = useCallback(
-    (index: number, value: string) => {
-      const newDigits = [...digits];
-      newDigits[index] = value;
-      setDigits(newDigits);
+    (index: number, digitValue: string) => {
+      setDigits((prev) => {
+        const next = [...prev];
+        next[index] = digitValue;
+        return next;
+      });
 
       // Auto-advance to next input
-      if (value && index < length - 1) {
+      if (digitValue && index < length - 1) {
         setFocusedIndex(index + 1);
         inputRefs.current[index + 1]?.focus();
       }
     },
-    [digits, length],
+    [length],
   );
 
   const handleKeyPress = useCallback(
     (index: number, key: string) => {
       if (key === "Backspace") {
-        if (!digits[index] && index > 0) {
+        const wasEmpty = !digitsRef.current[index];
+        setDigits((prev) => {
+          const next = [...prev];
+          if (!prev[index] && index > 0) {
+            next[index - 1] = "";
+          } else {
+            next[index] = "";
+          }
+          return next;
+        });
+        if (wasEmpty && index > 0) {
           setFocusedIndex(index - 1);
           inputRefs.current[index - 1]?.focus();
-          const newDigits = [...digits];
-          newDigits[index - 1] = "";
-          setDigits(newDigits);
-        } else {
-          const newDigits = [...digits];
-          newDigits[index] = "";
-          setDigits(newDigits);
         }
       } else if (key === "ArrowLeft" && index > 0) {
         setFocusedIndex(index - 1);
@@ -479,44 +703,33 @@ export function OTPInput<
       } else if (key === "ArrowRight" && index < length - 1) {
         setFocusedIndex(index + 1);
         inputRefs.current[index + 1]?.focus();
+      } else if (key === "Home" && index > 0) {
+        setFocusedIndex(0);
+        inputRefs.current[0]?.focus();
+      } else if (key === "End" && index < length - 1) {
+        setFocusedIndex(length - 1);
+        inputRefs.current[length - 1]?.focus();
       }
     },
-    [digits, length],
+    [length],
   );
 
   const handlePaste = useCallback(
     (pastedText: string) => {
-      const digitsOnly = pastedText.replace(/[^0-9]/g, "");
-      if (digitsOnly.length >= length) {
-        const newDigits = digitsOnly.slice(0, length).split("");
-        setDigits(newDigits);
-        setFocusedIndex(length - 1);
-        inputRefs.current[length - 1]?.focus();
-      }
+      const pastedChars = pastedText
+        .replace(getValidationPattern(type), "")
+        .slice(0, length)
+        .split("");
+      if (!pastedChars.length) return;
+      const newDigits = pastedChars.concat(Array(length).fill("")).slice(0, length);
+      setDigits(newDigits);
+      const focusIndex = Math.min(pastedChars.length, length - 1);
+      setFocusedIndex(focusIndex);
+      inputRefs.current[focusIndex]?.focus();
     },
-    [length],
+    [length, type],
   );
 
-  // Get validation pattern based on type
-  const getValidationPattern = (inputType: string) => {
-    switch (inputType) {
-      case "numeric":
-        return /[^0-9]/g;
-      case "alphanumeric":
-        return /[^a-zA-Z0-9]/g;
-      case "password":
-        return /[^a-zA-Z0-9!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]/g;
-      default:
-        return /[^0-9]/g;
-    }
-  };
-
-  // Get secure text entry based on type
-  const getSecureTextEntry = (inputType: string, secure: boolean) => {
-    if (inputType === "password") return true;
-    return secure;
-  };
-
   const handleClearStandalone = () => {
     setDigits(Array(length).fill(""));
     if (inputRefs.current[0]) {
@@ -526,16 +739,22 @@ export function OTPInput<
 
   // Render skeleton placeholder (after all hooks)
   if (skeleton) {
+    // Mirror LC-20 SKELETON-MIRRORS-ANATOMY: cells shrink-wrap the row, so the
+    // label MUST be a deterministic px width — never % inside this auto-width
+    // stack. Cell size + radius match live OTPDigitInput (getOTPCellRadius).
+    const cellSize = fieldProps.size || knobProps.sizeToken;
+    const cellRadius = getOTPCellRadius(knobProps.borderRadius.borderRadius);
     return (
-      <InputParts size={fieldProps.size || knobProps.sizeToken}>
-        {fieldProps.label && <Skeleton variant="text" width="30%" height={14} />}
+      <InputParts size={cellSize}>
+        {fieldProps.label && <Skeleton variant="text" width={96} height={14} />}
         <XStack gap={knobProps.gap.gap} alignItems="center">
           {Array.from({ length }, (_, i) => (
             <Skeleton
               key={i}
               variant="rounded"
-              width={knobProps.sizeToken}
-              height={knobProps.sizeToken}
+              width={cellSize}
+              height={cellSize}
+              borderRadius={cellRadius}
             />
           ))}
         </XStack>
@@ -555,64 +774,32 @@ export function OTPInput<
         size={fieldProps.size}
         knobProps={knobProps as any}
         onBlur={fieldProps.onBlur}
+        // LC-40: see form branch — FieldLayout carries dimWhole.
+        disabled={disabled}
       >
         <InputParts size={fieldProps.size || knobProps.sizeToken}>
-          <XStack gap={knobProps.gap.gap} alignItems="center">
-            {Array.from({ length }, (_, index) => {
-              const inputRef = {
-                current: null,
-              } as RefObject<TamaguiElement | null>;
-              return (
-                <Fragment key={`digit-${index}`}>
-                  <OTPDigitInput
-                    value={digits[index]}
-                    onChange={(value) => handleDigitChange(index, value)}
-                    onKeyPress={(key) => handleKeyPress(index, key)}
-                    onPaste={handlePaste}
-                    onFocus={() => setFocusedIndex(index)}
-                    onBlur={() => setFocusedIndex(-1)}
-                    autoFocus={autoFocus && index === 0}
-                    secureTextEntry={getSecureTextEntry(type, secureTextEntry)}
-                    disabled={disabled}
-                    readOnly={readOnly}
-                    required={fieldProps.required}
-                    hasError={!!fieldProps.error}
-                    inputRef={inputRef}
-                    inputProps={{
-                      ...inputProps,
-                      ref: (el: TamaguiElement | null) => {
-                        inputRefs.current[index] = el as HTMLElement | null;
-                        inputRef.current = el;
-                      },
-                      onChangeText: (text: string) => {
-                        const pattern = getValidationPattern(type);
-                        const filtered = text.replace(pattern, "");
-                        if (!filtered) return;
-                        const newChar =
-                          filtered.length > 1 && digits[index]
-                            ? (filtered.replace(digits[index], "") || filtered)[0]
-                            : filtered[0];
-                        handleDigitChange(index, newChar);
-                      },
-                    }}
-                  />
-                  {separator && index < length - 1 && <Text>{separator}</Text>}
-                </Fragment>
-              );
-            })}
-            {clearable && !readOnly && (
-              <Button
-                circular
-                onPress={handleClearStandalone}
-                disabled={disabled}
-                marginLeft="$2"
-                aria-label="Clear"
-                tabIndex={-1}
-              >
-                ×
-              </Button>
-            )}
-          </XStack>
+          <OTPCellsRow
+            digits={digits}
+            length={length}
+            type={type}
+            secureTextEntry={secureTextEntry}
+            autoFocus={autoFocus}
+            disabled={disabled}
+            readOnly={readOnly}
+            required={fieldProps.required}
+            hasError={!!fieldProps.error}
+            fieldId={id}
+            hasLabel={Boolean(fieldProps.label)}
+            separator={separator}
+            clearable={clearable}
+            inputProps={inputProps}
+            inputRefs={inputRefs}
+            onDigitChange={handleDigitChange}
+            onKeyPress={handleKeyPress}
+            onPaste={handlePaste}
+            onFocusIndex={setFocusedIndex}
+            onClear={handleClearStandalone}
+          />
         </InputParts>
       </FieldLayout>
     );
@@ -637,10 +824,7 @@ export function OTPInput<
           handleDigitChange={handleDigitChange}
           handleKeyPress={handleKeyPress}
           handlePaste={handlePaste}
-          focusedIndex={focusedIndex}
           setFocusedIndex={setFocusedIndex}
-          getSecureTextEntry={getSecureTextEntry}
-          getValidationPattern={getValidationPattern}
           autoFocus={autoFocus}
           type={type}
           secureTextEntry={secureTextEntry}