react-native-platform-components 1.4.0 → 1.5.0

package/src/TextField.tsx

@@ -8,16 +8,20 @@ import React, {
   useRef,
   useState,
 } from 'react';
-import type { NativeSyntheticEvent, ViewProps } from 'react-native';
+import type { ColorValue, NativeSyntheticEvent, ViewProps } from 'react-native';
 
 import NativeTextField, {
   Commands,
   type TextFieldChangeEvent as NativeChangeEvent,
+  type TextFieldSelectionEvent as NativeSelectionEvent,
   type TextFieldTextEvent as NativeTextEvent,
+  type TextFieldToolbarItem as NativeToolbarItem,
+  type TextFieldToolbarPressEvent as NativeToolbarPressEvent,
 } from './TextFieldNativeComponent';
-import { resolveIcon, type PlatformIcon } from './icons';
+import { NO_ICON, resolveIcon, type PlatformIcon } from './icons';
 import { normalizeLabelStyle, type LabelStyle } from './labelStyle';
 import { focusRegistry } from './focusRegistry';
+import { resolveSubmitBehavior } from './submitBehavior';
 import type { AndroidMaterialMode } from './sharedTypes';
 
 /** Keyboard to show; the React Native `TextInput` values. */
@@ -40,25 +44,82 @@ export type TextFieldKeyboardType =
 export type TextFieldReturnKeyType =
   'default' | 'done' | 'go' | 'next' | 'search' | 'send' | 'none' | 'previous';
 
-/** Autofill hint; a cross-platform subset of the React Native `TextInput` values. */
+/**
+ * Autofill hint: the React Native `TextInput` `autoComplete` values, which
+ * include the HTML autocomplete names. iOS maps them to `textContentType`,
+ * Android to autofill hints. A value one platform has no equivalent for is
+ * ignored there.
+ */
 export type TextFieldAutoComplete =
   | 'off'
   | 'username'
+  | 'username-new'
   | 'password'
+  | 'current-password'
   | 'new-password'
+  | 'password-new'
   | 'one-time-code'
+  | 'sms-otp'
+  | 'email-otp'
+  | '2fa-app-otp'
   | 'email'
   | 'name'
   | 'given-name'
   | 'family-name'
+  | 'additional-name'
+  | 'name-given'
+  | 'name-family'
+  | 'name-middle'
+  | 'name-middle-initial'
+  | 'name-prefix'
+  | 'name-suffix'
+  | 'honorific-prefix'
+  | 'honorific-suffix'
+  | 'nickname'
+  | 'organization'
+  | 'organization-title'
   | 'tel'
+  | 'tel-country-code'
+  | 'tel-national'
+  | 'tel-device'
   | 'street-address'
+  | 'address-line1'
+  | 'address-line2'
+  | 'postal-address'
+  | 'postal-address-country'
+  | 'postal-address-extended'
+  | 'postal-address-extended-postal-code'
+  | 'postal-address-locality'
+  | 'postal-address-region'
+  | 'postal-address-dependent-locality'
+  | 'postal-address-unit'
   | 'postal-code'
   | 'country'
+  | 'birthdate-full'
+  | 'birthdate-day'
+  | 'birthdate-month'
+  | 'birthdate-year'
+  | 'gender'
   | 'cc-number'
   | 'cc-exp'
+  | 'cc-exp-day'
+  | 'cc-exp-month'
+  | 'cc-exp-year'
   | 'cc-csc'
-  | 'url';
+  | 'cc-name'
+  | 'cc-given-name'
+  | 'cc-middle-name'
+  | 'cc-family-name'
+  | 'cc-type'
+  | 'url'
+  | 'flight-number'
+  | 'flight-confirmation-code'
+  | 'gift-card-number'
+  | 'gift-card-pin'
+  | 'loyalty-account-number'
+  | 'promo-code'
+  | 'upi-vpa'
+  | 'wifi-password';
 
 export type TextFieldAutoCapitalize =
   'none' | 'sentences' | 'words' | 'characters';
@@ -78,6 +139,77 @@ export type TextFieldChangeEvent = NativeSyntheticEvent<{
   eventCount: number;
 }>;
 
+/** A cursor position or selected range, as UTF-16 offsets into the text. */
+export type TextFieldSelection = { start: number; end: number };
+
+/** Selection events carry the new selection, as on `TextInput`. */
+export type TextFieldSelectionChangeEvent = NativeSyntheticEvent<{
+  selection: TextFieldSelection;
+}>;
+
+/**
+ * What the return key does, as on `TextInput`: `'blurAndSubmit'` calls
+ * `onSubmitEditing` and dismisses the keyboard, `'submit'` calls it and keeps
+ * the keyboard up, `'newline'` inserts a newline (multi-line fields).
+ */
+export type TextFieldSubmitBehavior = 'submit' | 'blurAndSubmit' | 'newline';
+
+/** A system button of the iOS keyboard toolbar (`UIBarButtonItem.SystemItem`). */
+export type TextFieldToolbarSystemItem =
+  | 'done'
+  | 'cancel'
+  | 'save'
+  | 'add'
+  | 'edit'
+  | 'close'
+  | 'search'
+  | 'compose'
+  | 'reply'
+  | 'action'
+  | 'camera'
+  | 'trash'
+  | 'undo'
+  | 'redo';
+
+/**
+ * An item of the iOS keyboard toolbar: a button, or `'flexibleSpace'` to push
+ * the next items to the end.
+ */
+export type TextFieldToolbarItem =
+  | 'flexibleSpace'
+  | {
+      /** Passed to `onItemPress`. */
+      id: string;
+      /** Button title. */
+      title?: string;
+      /** An icon instead of the title: an SF Symbol name or an image. */
+      icon?: PlatformIcon;
+      /** A system button, with its own localized title or symbol. */
+      systemItem?: TextFieldToolbarSystemItem;
+      /** The prominent style: bold, or tinted glass on iOS 26. */
+      prominent?: boolean;
+      /** Screen-reader label; defaults to the title. */
+      accessibilityLabel?: string;
+      /** Test identifier of the button. */
+      testID?: string;
+    };
+
+/** The iOS keyboard toolbar, a `UIToolbar` shown above the keyboard. */
+export interface TextFieldKeyboardToolbar {
+  /**
+   * A Done button at the end of the toolbar that dismisses the keyboard
+   * (`onBlur` is called; `onSubmitEditing` is not). `true` is the system
+   * Done button; a string is a prominent button with that title.
+   */
+  done?: boolean | string;
+  /** Buttons at the start of the toolbar, before Done. */
+  items?: TextFieldToolbarItem[];
+  /** Called with the `id` of a pressed item. */
+  onItemPress?: (id: string) => void;
+  /** Test identifier of the Done button. */
+  doneTestID?: string;
+}
+
 /** Methods available through the `ref`. */
 export interface TextFieldRef {
   /** Focuses the field and shows the keyboard. */
@@ -88,6 +220,11 @@ export interface TextFieldRef {
   clear(): void;
   /** Whether the field currently has focus. */
   isFocused(): boolean;
+  /**
+   * Moves the cursor to `start`, or selects `start`..`end`, in UTF-16
+   * offsets clamped to the text.
+   */
+  setSelection(start: number, end?: number): void;
 }
 
 export interface TextFieldProps extends Omit<
@@ -116,9 +253,33 @@ export interface TextFieldProps extends Omit<
   /** Called when the field loses focus. */
   onBlur?: (event: TextFieldEvent) => void;
 
-  /** Called when the return key is pressed. Single-line fields only. */
+  /**
+   * Called when the return key is pressed, unless it inserts a newline (see
+   * `submitBehavior`).
+   */
   onSubmitEditing?: (event: TextFieldEvent) => void;
 
+  /**
+   * What the return key does. Default: `'blurAndSubmit'` for single-line
+   * fields, `'newline'` for multi-line fields. `'submit'` keeps the keyboard
+   * up, for a chat composer that sends on return.
+   */
+  submitBehavior?: TextFieldSubmitBehavior;
+
+  /**
+   * Called when the cursor moves or the selection changes, with
+   * `nativeEvent.selection` in UTF-16 offsets.
+   */
+  onSelectionChange?: (event: TextFieldSelectionChangeEvent) => void;
+
+  /**
+   * Controlled cursor position or selection, in UTF-16 offsets; `end`
+   * defaults to `start`, a cursor. Like `value`, the field returns to it
+   * when the user moves the cursor, so update it from `onSelectionChange`.
+   * For a one-off move, use the ref's `setSelection` instead.
+   */
+  selection?: { start: number; end?: number };
+
   /**
    * Field label. Android: the Material floating label. iOS: a caption above
    * the field, which takes the tint color while focused.
@@ -153,9 +314,72 @@ export interface TextFieldProps extends Omit<
   /** Called when the trailing icon is pressed. */
   onTrailingIconPress?: () => void;
 
+  /** Test identifier of the leading icon (Android: Material fields only). */
+  leadingIconTestID?: string;
+
+  /** Screen-reader label of the leading icon, which is decorative without one. */
+  leadingIconAccessibilityLabel?: string;
+
+  /** Test identifier of the trailing icon (Android: Material fields only). */
+  trailingIconTestID?: string;
+
+  /** Screen-reader label of the trailing icon. */
+  trailingIconAccessibilityLabel?: string;
+
+  /**
+   * Called when a field with `editable={false}` is pressed, for a field that
+   * opens a menu, a date picker or another screen. The field doesn't focus
+   * or show the keyboard, keeps its enabled look, and is announced as a
+   * button. Ignored while the field is editable.
+   */
+  onPress?: () => void;
+
+  /**
+   * Color of the focused outline (underline for filled fields), the focused
+   * label and the cursor. Default: the tint / Material primary color.
+   */
+  activeColor?: ColorValue;
+
+  /**
+   * Color of the unfocused outline (underline for filled fields). iOS draws
+   * the rounded-rect border itself when this, `activeColor` or
+   * `containerColor` is set.
+   */
+  outlineColor?: ColorValue;
+
+  /** Color of the outline, label and message in the error state. */
+  errorColor?: ColorValue;
+
+  /** Background of the field's box. The host `style.backgroundColor` paints the whole view. */
+  containerColor?: ColorValue;
+
+  /** Color of the typed text. */
+  textColor?: ColorValue;
+
+  /** Color of the placeholder. */
+  placeholderTextColor?: ColorValue;
+
+  /**
+   * Largest scale the field's text may reach with the system text size
+   * (Dynamic Type / font scale), as on React Native `Text`: `2` caps a 17pt
+   * font at 34pt. Unset or `0`: no cap. Applies to the input, label,
+   * placeholder, prefix, suffix and supporting text.
+   */
+  maxFontSizeMultiplier?: number;
+
+  /** Horizontal alignment of the text. Default: the natural (leading) alignment. */
+  textAlign?: 'left' | 'center' | 'right';
+
+  /** Multi-line fields: the height in lines the field starts at. */
+  minLines?: number;
+
+  /** Multi-line fields: the lines the field grows to before it scrolls. */
+  maxLines?: number;
+
   /**
    * When to show a clear button inside the field. Default: `'never'`.
    * Android shows the Material clear icon while the field has text.
+   * Clearing fires `onChange` and `onChangeText('')` on both platforms.
    */
   clearButtonMode?: TextFieldClearButtonMode;
 
@@ -186,7 +410,10 @@ export interface TextFieldProps extends Omit<
   /** Obscures the text, for passwords. */
   secureTextEntry?: boolean;
 
-  /** Multi-line field that grows with its content. Return inserts a newline. */
+  /**
+   * Multi-line field that grows with its content, between `minLines` and
+   * `maxLines`. Return inserts a newline.
+   */
   multiline?: boolean;
 
   /** Whether the text can be edited. Default: `true`. */
@@ -251,6 +478,21 @@ export interface TextFieldProps extends Omit<
 
     /** Width of the leading label column, in points. Default: 100. */
     labelWidth?: number;
+
+    /**
+     * A toolbar above the keyboard (`inputAccessoryView`) with a Done
+     * button and your own buttons. Number and phone pads have no return
+     * key, so this is how they are dismissed.
+     */
+    keyboardToolbar?: TextFieldKeyboardToolbar;
+
+    /**
+     * Requirements for the strong passwords iOS suggests, as a
+     * `UITextInputPasswordRules` descriptor, e.g.
+     * `'minlength: 12; required: lower; required: upper; required: digit;'`.
+     * Use with `autoComplete="new-password"`.
+     */
+    passwordRules?: string;
   };
 
   /**
@@ -265,19 +507,72 @@ export interface TextFieldProps extends Omit<
      */
     material?: AndroidMaterialMode;
 
-    /** Material 3 text field style. Default: `'outlined'`. */
-    variant?: 'outlined' | 'filled';
+    /**
+     * Material 3 text field style. Default: `'outlined'`. `'plain'` has no
+     * box or underline (the label still floats), for a large standalone
+     * input such as an amount; the iOS equivalent is `ios.borderStyle: 'none'`.
+     */
+    variant?: 'outlined' | 'filled' | 'plain';
 
     /** The dense variant, a shorter field. */
     dense?: boolean;
   };
 
-  /** Test identifier */
+  /**
+   * Test identifier. It is set on the inner text input (the `UITextField` /
+   * `UITextView` on iOS, the `EditText` on Android) rather than the host
+   * view, so E2E drivers such as Detox can type into and clear the field.
+   */
   testID?: string;
 }
 
 type NativeTextFieldInstance = React.ComponentRef<typeof NativeTextField>;
 
+const TOOLBAR_ITEM: NativeToolbarItem = {
+  kind: 'button',
+  itemId: '',
+  title: '',
+  systemItem: '',
+  ...NO_ICON,
+  prominent: 'false',
+  accessibilityLabel: '',
+  testID: '',
+};
+
+/** The keyboard toolbar as flat items: yours, then a Done button at the end. */
+function toolbarItems(
+  toolbar: TextFieldKeyboardToolbar | undefined
+): NativeToolbarItem[] {
+  if (toolbar == null) return [];
+  const items = (toolbar.items ?? []).map((item): NativeToolbarItem =>
+    item === 'flexibleSpace'
+      ? { ...TOOLBAR_ITEM, kind: 'flexibleSpace' }
+      : {
+          ...TOOLBAR_ITEM,
+          itemId: item.id,
+          title: item.title ?? '',
+          systemItem: item.systemItem ?? '',
+          ...resolveIcon(item.icon),
+          prominent: item.prominent ? 'true' : 'false',
+          accessibilityLabel: item.accessibilityLabel ?? '',
+          testID: item.testID ?? '',
+        }
+  );
+  if (toolbar.done) {
+    if (items[items.length - 1]?.kind !== 'flexibleSpace') {
+      items.push({ ...TOOLBAR_ITEM, kind: 'flexibleSpace' });
+    }
+    items.push({
+      ...TOOLBAR_ITEM,
+      kind: 'done',
+      title: typeof toolbar.done === 'string' ? toolbar.done : '',
+      prominent: 'true',
+      testID: toolbar.doneTestID ?? '',
+    });
+  }
+  return items;
+}
+
 export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
   function TextFieldComponent(props, ref): React.ReactElement {
     const {
@@ -288,6 +583,9 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
       onFocus,
       onBlur,
       onSubmitEditing,
+      submitBehavior,
+      onSelectionChange,
+      selection,
       label,
       placeholder,
       supportingText,
@@ -297,6 +595,21 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
       leadingIcon,
       trailingIcon,
       onTrailingIconPress,
+      leadingIconTestID,
+      leadingIconAccessibilityLabel,
+      trailingIconTestID,
+      trailingIconAccessibilityLabel,
+      onPress,
+      activeColor,
+      outlineColor,
+      errorColor,
+      containerColor,
+      textColor,
+      placeholderTextColor,
+      maxFontSizeMultiplier,
+      textAlign,
+      minLines,
+      maxLines,
       clearButtonMode,
       passwordToggle,
       showCharacterCount,
@@ -327,9 +640,14 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
     // count JS has seen. Native drops the update when the user has typed
     // since, and the edit that follows brings JS back in line.
     const [mostRecentEventCount, setMostRecentEventCount] = useState(0);
+    const eventCountRef = useRef(0);
     const [lastNativeText, setLastNativeText] = useState<string | undefined>(
       value ?? defaultValue
     );
+    // The selection last reported by native or pushed from here; a
+    // `selection` prop that differs from it is pushed, the same way
+    const [lastNativeSelection, setLastNativeSelection] =
+      useState<TextFieldSelection | null>(null);
 
     // Registered like a TextInput, so Keyboard.dismiss() and the ScrollView
     // keyboard props treat the field as one (see focusRegistry.ts)
@@ -340,14 +658,41 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
       return () => focusRegistry.unregister(node);
     }, []);
 
+    // Text first, then the selection, which may point into the new text
+    const selectionStart = selection?.start;
+    const selectionEnd = selection?.end ?? selectionStart;
     useLayoutEffect(() => {
-      if (typeof value !== 'string' || value === lastNativeText) return;
-      setLastNativeText(value);
       const node = nativeRef.current;
-      if (node != null) {
-        Commands.setText(node, mostRecentEventCount, value);
+      if (typeof value === 'string' && value !== lastNativeText) {
+        setLastNativeText(value);
+        if (node != null) {
+          Commands.setText(node, mostRecentEventCount, value);
+        }
       }
-    }, [value, lastNativeText, mostRecentEventCount]);
+      if (
+        selectionStart != null &&
+        selectionEnd != null &&
+        (lastNativeSelection?.start !== selectionStart ||
+          lastNativeSelection?.end !== selectionEnd)
+      ) {
+        setLastNativeSelection({ start: selectionStart, end: selectionEnd });
+        if (node != null) {
+          Commands.setSelection(
+            node,
+            mostRecentEventCount,
+            selectionStart,
+            selectionEnd
+          );
+        }
+      }
+    }, [
+      value,
+      lastNativeText,
+      mostRecentEventCount,
+      selectionStart,
+      selectionEnd,
+      lastNativeSelection,
+    ]);
 
     useImperativeHandle(
       ref,
@@ -365,6 +710,17 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
           if (node != null) Commands.clear(node);
         },
         isFocused: () => focused.current,
+        setSelection: (start: number, end?: number) => {
+          const node = nativeRef.current;
+          if (node != null) {
+            Commands.setSelection(
+              node,
+              eventCountRef.current,
+              start,
+              end ?? start
+            );
+          }
+        },
       }),
       []
     );
@@ -372,6 +728,7 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
     const handleChange = useCallback(
       (event: NativeSyntheticEvent<NativeChangeEvent>) => {
         const { text, eventCount } = event.nativeEvent;
+        eventCountRef.current = eventCount;
         setMostRecentEventCount(eventCount);
         setLastNativeText(text);
         onChange?.(event);
@@ -405,10 +762,37 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
       [onSubmitEditing]
     );
 
+    const handleSelectionChange = useCallback(
+      (event: NativeSyntheticEvent<NativeSelectionEvent>) => {
+        const { start, end } = event.nativeEvent;
+        setLastNativeSelection({ start, end });
+        onSelectionChange?.({
+          ...event,
+          nativeEvent: { selection: { start, end } },
+        });
+      },
+      [onSelectionChange]
+    );
+
+    const onToolbarItemPress = ios?.keyboardToolbar?.onItemPress;
+    const handleToolbarPress = useCallback(
+      (event: NativeSyntheticEvent<NativeToolbarPressEvent>) => {
+        onToolbarItemPress?.(event.nativeEvent.itemId);
+      },
+      [onToolbarItemPress]
+    );
+
     const handleTrailingIconPress = useCallback(() => {
       onTrailingIconPress?.();
     }, [onTrailingIconPress]);
 
+    const handlePress = useCallback(() => {
+      onPress?.();
+    }, [onPress]);
+
+    // A read-only field with onPress acts as a button
+    const pressable = editable === false && onPress != null;
+
     const nativeLeadingIcon = useMemo(
       () => resolveIcon(leadingIcon),
       [leadingIcon]
@@ -433,10 +817,16 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
         borderStyle: ios?.borderStyle ?? '',
         labelPlacement: ios?.labelPlacement ?? '',
         labelWidth: ios?.labelWidth ?? 0,
+        passwordRules: ios?.passwordRules ?? '',
       }),
       [ios]
     );
 
+    const nativeToolbarItems = useMemo(
+      () => toolbarItems(ios?.keyboardToolbar),
+      [ios?.keyboardToolbar]
+    );
+
     const nativeAndroid = useMemo(
       () => ({
         material: android?.material ?? 'm3',
@@ -469,6 +859,8 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
         autoCorrect={autoCorrect === false ? 'disabled' : 'enabled'}
         secureTextEntry={secureTextEntry ? 'secure' : 'plain'}
         lines={multiline ? 'multiline' : 'single'}
+        submitBehavior={resolveSubmitBehavior(submitBehavior, multiline)}
+        keyboardToolbarItems={nativeToolbarItems}
         interactivity={editable === false ? 'disabled' : 'enabled'}
         autoFocus={autoFocus ? 'focus' : 'none'}
         selectTextOnFocus={selectTextOnFocus ? 'select' : 'keep'}
@@ -476,15 +868,37 @@ export const TextField = forwardRef<TextFieldRef, TextFieldProps>(
         keyboardAppearance={keyboardAppearance ?? 'default'}
         textStyle={nativeTextStyle}
         spokenLabel={accessibilityLabel ?? ''}
+        leadingIconTestID={leadingIconTestID ?? ''}
+        leadingIconSpokenLabel={leadingIconAccessibilityLabel ?? ''}
+        trailingIconTestID={trailingIconTestID ?? ''}
+        trailingIconSpokenLabel={trailingIconAccessibilityLabel ?? ''}
+        activeColor={activeColor}
+        outlineColor={outlineColor}
+        errorColor={errorColor}
+        containerColor={containerColor}
+        textColor={textColor}
+        placeholderTextColor={placeholderTextColor}
+        maxFontSizeMultiplier={maxFontSizeMultiplier ?? 0}
+        textAlign={textAlign ?? ''}
+        minLines={minLines ?? 0}
+        maxLines={maxLines ?? 0}
+        pressMode={pressable ? 'button' : 'none'}
         ios={nativeIOS}
         android={nativeAndroid}
         onFieldChange={handleChange}
         onFieldFocus={handleFocus}
         onFieldBlur={handleBlur}
         onFieldSubmit={onSubmitEditing ? handleSubmit : undefined}
+        onFieldSelectionChange={
+          onSelectionChange || selection ? handleSelectionChange : undefined
+        }
+        onKeyboardToolbarPress={
+          onToolbarItemPress ? handleToolbarPress : undefined
+        }
         onTrailingIconPress={
           onTrailingIconPress ? handleTrailingIconPress : undefined
         }
+        onFieldPress={pressable ? handlePress : undefined}
         {...viewProps}
       />
     );