@multiplatform.one/forms 6.0.0

package/src/fields/OTPInput/index.tsx

@@ -0,0 +1,662 @@
+import type { Validator } from "../../types";
+
+import type { DeepKeys, DeepValue } from "@tanstack/form-core";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  type ClipboardEvent,
+  type ComponentProps,
+  Fragment,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { useProps, type TamaguiElement } from "tamagui";
+import { Input, Text, XStack, isWeb, useDidFinishSSR } from "tamagui";
+import { Button } from "../../Button";
+import { Field, FieldLayout } from "../../fieldLayout";
+import {
+  getOTPCellRadius,
+  mergeFieldHandler,
+  useFormField,
+  useResolvedValidators,
+} from "../../shared/utils";
+import type { FormFieldProps } from "../../fieldLayout";
+import { Input as InputParts } from "../../InputParts";
+import { Skeleton } from "../../Skeleton";
+import type { FieldComponentProps } from "../../types";
+
+export type OTPInputProps<
+  TParentData extends Record<string, unknown> = Record<string, unknown>,
+  TName extends DeepKeys<TParentData> = DeepKeys<TParentData>,
+  TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined,
+  TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> = Omit<
+  FormFieldProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
+  "children" | "field"
+> &
+  Partial<
+    Omit<
+      FieldComponentProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
+      "children"
+    >
+  > & {
+    readOnly?: boolean;
+    length?: number;
+    secureTextEntry?: boolean;
+    autoFocus?: boolean;
+    onComplete?: (code: string) => void;
+    onChange?: (value: string) => void;
+    value?: string;
+    type?: "numeric" | "alphanumeric" | "password";
+    clearable?: boolean;
+    separator?: string;
+    inputProps?: Omit<ComponentProps<typeof Input>, "value" | "onChangeText" | "ref">;
+    /** When true, renders a skeleton placeholder instead of the OTP input */
+    skeleton?: boolean;
+    /** When true, uses compact sizing */
+    compact?: boolean;
+  };
+
+interface OTPDigitInputProps {
+  value: string;
+  onChange: (value: string) => void;
+  onKeyPress: (key: string) => void;
+  onFocus: () => void;
+  onBlur: () => 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>;
+}
+
+function OTPDigitInput({
+  value,
+  onChange,
+  onKeyPress,
+  onFocus,
+  onBlur,
+  onPaste,
+  autoFocus,
+  secureTextEntry,
+  disabled,
+  readOnly,
+  required,
+  hasError,
+  inputProps,
+  inputRef: externalRef,
+}: OTPDigitInputProps) {
+  const internalRef = useRef<TamaguiElement | null>(null);
+  const inputRef = externalRef || internalRef;
+  const didFinishSSR = useDidFinishSSR();
+  const { knobProps } = useResolvedKnobs();
+  const cellSize = knobProps.sizeToken;
+
+  useEffect(() => {
+    if (autoFocus && didFinishSSR && inputRef.current) {
+      (inputRef.current as HTMLElement).focus();
+    }
+  }, [autoFocus, didFinishSSR]);
+
+  const cellRadius = getOTPCellRadius(knobProps.borderRadius.borderRadius);
+
+  return (
+    <InputParts.Box
+      width={cellSize}
+      height={cellSize}
+      borderRadius={cellRadius}
+      tabIndex={-1}
+      onFocus={() => {
+        onFocus();
+        if (isWeb && inputRef.current) {
+          requestAnimationFrame(() => {
+            (inputRef.current as unknown as HTMLInputElement)?.select();
+          });
+        }
+      }}
+      onBlur={onBlur}
+    >
+      <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);
+                }
+              },
+            }
+          : {})}
+        {...(inputProps as Record<string, unknown>)}
+      />
+    </InputParts.Box>
+  );
+}
+
+// Inner component that handles field state
+type OTPType = "numeric" | "alphanumeric" | "password";
+
+/** Minimal field interface for OTPFieldRenderer */
+interface OTPFieldApi {
+  state: {
+    value: string;
+    meta: { errors: readonly (string | undefined)[] };
+  };
+  handleChange: (value: string) => void;
+  handleBlur: () => void;
+}
+
+/** Props for OTPFieldRenderer inner component */
+interface OTPFieldRendererProps {
+  field: OTPFieldApi;
+  digits: string[];
+  setDigits: (digits: string[]) => void;
+  length: number;
+  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;
+  disabled?: boolean;
+  readOnly?: boolean;
+  clearable: boolean;
+  separator?: string;
+  inputProps?: Omit<ComponentProps<typeof Input>, "value" | "onChangeText" | "ref">;
+  fieldProps: Omit<
+    FormFieldProps<Record<string, unknown>, string, unknown, unknown, unknown>,
+    "children" | "field"
+  >;
+  inputRefs: RefObject<Array<HTMLElement | null>>;
+  onComplete?: (code: string) => void;
+  onChange?: (value: string) => void;
+  fieldBlurHandler: (...args: any[]) => void;
+  id?: string;
+}
+
+function OTPFieldRenderer({
+  field,
+  digits,
+  setDigits,
+  length,
+  handleDigitChange,
+  handleKeyPress,
+  handlePaste,
+  focusedIndex: _focusedIndex,
+  setFocusedIndex,
+  getSecureTextEntry,
+  getValidationPattern,
+  autoFocus,
+  type,
+  secureTextEntry,
+  disabled,
+  readOnly,
+  clearable,
+  separator,
+  inputProps,
+  fieldProps,
+  inputRefs,
+  onComplete,
+  onChange,
+  fieldBlurHandler,
+  id,
+}: OTPFieldRendererProps) {
+  const lastFieldValueRef = useRef<string | null>(null);
+  const fieldHandleChangeRef = useRef(field.handleChange);
+  fieldHandleChangeRef.current = field.handleChange;
+  const { knobProps } = useResolvedKnobs();
+
+  // Sync digits with field value
+  useEffect(() => {
+    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);
+    }
+  }, [field.state.value, length, setDigits]);
+
+  // Update field value when digits change
+  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);
+      }
+    }
+  }, [digits, length, disabled, onChange, onComplete]);
+
+  const error = field.state.meta.errors.length
+    ? String(field.state.meta.errors[0])
+    : fieldProps.error;
+
+  const handleClear = () => {
+    setDigits(Array(length).fill(""));
+    field.handleChange("");
+    if (inputRefs.current[0]) {
+      inputRefs.current[0].focus();
+    }
+  };
+
+  return (
+    <FieldLayout
+      id={id}
+      label={fieldProps.label}
+      labelProps={fieldProps.labelProps}
+      error={error}
+      helperText={fieldProps.helperText}
+      required={fieldProps.required}
+      size={fieldProps.size}
+      knobProps={knobProps as any}
+      onBlur={fieldBlurHandler}
+    >
+      <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>
+      </InputParts>
+    </FieldLayout>
+  );
+}
+
+export function OTPInput<
+  TParentData extends Record<string, unknown> = Record<string, unknown>,
+  TName extends DeepKeys<TParentData> = DeepKeys<TParentData>,
+  TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined,
+  TFormValidator extends Validator<TParentData, unknown> | undefined = undefined,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+>(props: OTPInputProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) {
+  const {
+    defaultValue,
+    form,
+    inputProps,
+    length = 6,
+    secureTextEntry = false,
+    autoFocus = false,
+    onComplete,
+    onChange,
+    value,
+    type = "numeric",
+    clearable = false,
+    separator,
+    mode,
+    name,
+    preserveValue,
+    validators,
+    disabled,
+    readOnly,
+    skeleton,
+    compact,
+    id: idProp,
+    ...fieldProps
+  } = useProps(props);
+
+  const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
+  const resolvedValidators = useResolvedValidators(
+    fieldProps.required,
+    validators,
+    fieldProps.label,
+    name,
+  );
+
+  const [digits, setDigits] = useState<string[]>(() => {
+    if (value) {
+      return value.slice(0, length).split("").concat(Array(length).fill("")).slice(0, length);
+    }
+    return Array(length).fill("");
+  });
+  const [focusedIndex, setFocusedIndex] = useState<number>(autoFocus ? 0 : -1);
+  const inputRefs = useRef<Array<HTMLElement | null>>([]);
+
+  // 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)
+  useEffect(() => {
+    // Skip if using form integration - callbacks are handled in OTPFieldRenderer
+    if (resolvedForm && name) {
+      return;
+    }
+
+    const code = digits.join("");
+
+    // Call onChange callback
+    if (onChange && !disabled) {
+      onChange(code);
+    }
+
+    // Call onComplete when code is complete
+    if (code.length === length && onComplete && !disabled) {
+      onComplete(code);
+    }
+  }, [digits, length, resolvedForm, name, onChange, onComplete, disabled]);
+
+  const handleDigitChange = useCallback(
+    (index: number, value: string) => {
+      const newDigits = [...digits];
+      newDigits[index] = value;
+      setDigits(newDigits);
+
+      // Auto-advance to next input
+      if (value && index < length - 1) {
+        setFocusedIndex(index + 1);
+        inputRefs.current[index + 1]?.focus();
+      }
+    },
+    [digits, length],
+  );
+
+  const handleKeyPress = useCallback(
+    (index: number, key: string) => {
+      if (key === "Backspace") {
+        if (!digits[index] && 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);
+        inputRefs.current[index - 1]?.focus();
+      } else if (key === "ArrowRight" && index < length - 1) {
+        setFocusedIndex(index + 1);
+        inputRefs.current[index + 1]?.focus();
+      }
+    },
+    [digits, 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();
+      }
+    },
+    [length],
+  );
+
+  // 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]) {
+      inputRefs.current[0].focus();
+    }
+  };
+
+  // Render skeleton placeholder (after all hooks)
+  if (skeleton) {
+    return (
+      <InputParts size={fieldProps.size || knobProps.sizeToken}>
+        {fieldProps.label && <Skeleton variant="text" width="30%" height={14} />}
+        <XStack gap={knobProps.gap.gap} alignItems="center">
+          {Array.from({ length }, (_, i) => (
+            <Skeleton
+              key={i}
+              variant="rounded"
+              width={knobProps.sizeToken}
+              height={knobProps.sizeToken}
+            />
+          ))}
+        </XStack>
+      </InputParts>
+    );
+  }
+
+  if (!resolvedForm || !name) {
+    return (
+      <FieldLayout
+        id={id}
+        label={fieldProps.label}
+        labelProps={fieldProps.labelProps}
+        error={fieldProps.error}
+        helperText={fieldProps.helperText}
+        required={fieldProps.required}
+        size={fieldProps.size}
+        knobProps={knobProps as any}
+        onBlur={fieldProps.onBlur}
+      >
+        <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>
+        </InputParts>
+      </FieldLayout>
+    );
+  }
+
+  // Works with TanStack Form context
+  return (
+    <Field
+      defaultValue={defaultValue}
+      form={resolvedForm}
+      mode={mode}
+      name={name}
+      preserveValue={preserveValue}
+      validators={resolvedValidators}
+    >
+      {(field) => (
+        <OTPFieldRenderer
+          field={field as unknown as OTPFieldApi}
+          digits={digits}
+          setDigits={setDigits}
+          length={length}
+          handleDigitChange={handleDigitChange}
+          handleKeyPress={handleKeyPress}
+          handlePaste={handlePaste}
+          focusedIndex={focusedIndex}
+          setFocusedIndex={setFocusedIndex}
+          getSecureTextEntry={getSecureTextEntry}
+          getValidationPattern={getValidationPattern}
+          autoFocus={autoFocus}
+          type={type}
+          secureTextEntry={secureTextEntry}
+          disabled={disabled}
+          readOnly={readOnly}
+          clearable={clearable}
+          separator={separator}
+          inputProps={inputProps}
+          fieldProps={fieldProps}
+          inputRefs={inputRefs}
+          onComplete={onComplete}
+          onChange={onChange}
+          fieldBlurHandler={mergeFieldHandler(field, "handleBlur", fieldProps.onBlur)}
+          id={id}
+        />
+      )}
+    </Field>
+  );
+}