@office-iss/react-native-win32 0.75.2 → 0.76.0-preview.2

package/Libraries/Components/ScrollView/ScrollView.js

@@ -8,6 +8,10 @@
  * @flow strict-local
  */
 
+import type {
+  TScrollViewNativeComponentInstance,
+  TScrollViewNativeImperativeHandle,
+} from '../../../src/private/components/useSyncOnScroll';
 import type {HostComponent} from '../../Renderer/shims/ReactNativeTypes';
 import type {EdgeInsetsProp} from '../../StyleSheet/EdgeInsetsPropType';
 import type {PointProp} from '../../StyleSheet/PointPropType';
@@ -20,9 +24,18 @@ import type {
 } from '../../Types/CoreEventTypes';
 import type {EventSubscription} from '../../vendor/emitter/EventEmitter';
 import type {KeyboardEvent, KeyboardMetrics} from '../Keyboard/Keyboard';
+import typeof View from '../View/View';
 import type {ViewProps} from '../View/ViewPropTypes';
 import type {Props as ScrollViewStickyHeaderProps} from './ScrollViewStickyHeader';
 
+import {
+  HScrollContentViewNativeComponent,
+  HScrollViewNativeComponent,
+} from '../../../src/private/components/HScrollViewNativeComponents';
+import {
+  VScrollContentViewNativeComponent,
+  VScrollViewNativeComponent,
+} from '../../../src/private/components/VScrollViewNativeComponents';
 import AnimatedImplementation from '../../Animated/AnimatedImplementation';
 import FrameRateLogger from '../../Interaction/FrameRateLogger';
 import {findNodeHandle} from '../../ReactNative/RendererProxy';
@@ -36,44 +49,15 @@ import Platform from '../../Utilities/Platform';
 import EventEmitter from '../../vendor/emitter/EventEmitter';
 import Keyboard from '../Keyboard/Keyboard';
 import TextInputState from '../TextInput/TextInputState';
-import View from '../View/View';
-import AndroidHorizontalScrollContentViewNativeComponent from './AndroidHorizontalScrollContentViewNativeComponent';
-import AndroidHorizontalScrollViewNativeComponent from './AndroidHorizontalScrollViewNativeComponent';
 import processDecelerationRate from './processDecelerationRate';
-import ScrollContentViewNativeComponent from './ScrollContentViewNativeComponent';
 import Commands from './ScrollViewCommands';
 import ScrollViewContext, {HORIZONTAL, VERTICAL} from './ScrollViewContext';
-import ScrollViewNativeComponent from './ScrollViewNativeComponent';
 import ScrollViewStickyHeader from './ScrollViewStickyHeader';
 import invariant from 'invariant';
 import memoize from 'memoize-one';
 import nullthrows from 'nullthrows';
 import * as React from 'react';
 
-if (Platform.OS === 'ios') {
-  require('../../Renderer/shims/ReactNative'); // Force side effects to prevent T55744311
-}
-
-const {NativeHorizontalScrollViewTuple, NativeVerticalScrollViewTuple} =
-  Platform.OS === 'android'
-    ? {
-        NativeHorizontalScrollViewTuple: [
-          AndroidHorizontalScrollViewNativeComponent,
-          AndroidHorizontalScrollContentViewNativeComponent,
-        ],
-        NativeVerticalScrollViewTuple: [ScrollViewNativeComponent, View],
-      }
-    : {
-        NativeHorizontalScrollViewTuple: [
-          ScrollViewNativeComponent,
-          ScrollContentViewNativeComponent,
-        ],
-        NativeVerticalScrollViewTuple: [
-          ScrollViewNativeComponent,
-          ScrollContentViewNativeComponent,
-        ],
-      };
-
 /*
  * iOS scroll event timing nuances:
  * ===============================
@@ -167,13 +151,12 @@ export type ScrollViewImperativeMethods = $ReadOnly<{|
 export type DecelerationRateType = 'fast' | 'normal' | number;
 export type ScrollResponderType = ScrollViewImperativeMethods;
 
-type NativeScrollViewInstance = React.ElementRef<HostComponent<mixed>>;
 type PublicScrollViewInstance = $ReadOnly<{|
-  ...$Exact<NativeScrollViewInstance>,
+  ...$Exact<TScrollViewNativeComponentInstance>,
   ...ScrollViewImperativeMethods,
 |}>;
 
-type InnerViewInstance = React.ElementRef<typeof View>;
+type InnerViewInstance = React.ElementRef<View>;
 
 type IOSProps = $ReadOnly<{|
   /**
@@ -660,26 +643,23 @@ export type Props = $ReadOnly<{|
    */
   /* $FlowFixMe[unclear-type] - how to handle generic type without existential
    * operator? */
-  refreshControl?: ?React.Element<any>,
+  refreshControl?: ?ExactReactElement_DEPRECATED<any>,
   children?: React.Node,
   /**
    * A ref to the inner View element of the ScrollView. This should be used
    * instead of calling `getInnerViewRef`.
    */
-  innerViewRef?: ForwardedRef<InnerViewInstance>,
+  innerViewRef?: React.RefSetter<InnerViewInstance>,
   /**
    * A ref to the Native ScrollView component. This ref can be used to call
    * all of ScrollView's public methods, in addition to native methods like
    * measure, measureLayout, etc.
    */
-  scrollViewRef?: ForwardedRef<PublicScrollViewInstance>,
+  scrollViewRef?: React.RefSetter<PublicScrollViewInstance>,
 |}>;
 
 type State = {|
   layoutHeight: ?number,
-  onScrollEmitter: ?EventEmitter<{
-    scroll: [{x: number, y: number}],
-  }>,
 |};
 
 const IS_ANIMATING_TOUCH_START_THRESHOLD_MS = 16;
@@ -763,9 +743,12 @@ class ScrollView extends React.Component<Props, State> {
   _subscriptionKeyboardDidShow: ?EventSubscription = null;
   _subscriptionKeyboardDidHide: ?EventSubscription = null;
 
+  #onScrollEmitter: ?EventEmitter<{
+    scroll: [{x: number, y: number}],
+  }> = null;
+
   state: State = {
     layoutHeight: null,
-    onScrollEmitter: null,
   };
 
   componentDidMount() {
@@ -835,7 +818,7 @@ class ScrollView extends React.Component<Props, State> {
       this._scrollAnimatedValueAttachment.detach();
     }
 
-    this.state.onScrollEmitter?.removeAllListeners();
+    this.#onScrollEmitter?.removeAllListeners();
   }
 
   /**
@@ -850,7 +833,7 @@ class ScrollView extends React.Component<Props, State> {
   };
 
   getScrollableNode: () => ?number = () => {
-    return findNodeHandle(this._scrollView.nativeInstance);
+    return findNodeHandle(this.getNativeScrollRef());
   };
 
   getInnerViewNode: () => ?number = () => {
@@ -861,8 +844,9 @@ class ScrollView extends React.Component<Props, State> {
     return this._innerView.nativeInstance;
   };
 
-  getNativeScrollRef: () => NativeScrollViewInstance | null = () => {
-    return this._scrollView.nativeInstance;
+  getNativeScrollRef: () => TScrollViewNativeComponentInstance | null = () => {
+    const {nativeInstance} = this._scrollView;
+    return nativeInstance == null ? null : nativeInstance.componentRef.current;
   };
 
   /**
@@ -913,15 +897,11 @@ class ScrollView extends React.Component<Props, State> {
       x = options.x;
       animated = options.animated;
     }
-    if (this._scrollView.nativeInstance == null) {
+    const component = this.getNativeScrollRef();
+    if (component == null) {
       return;
     }
-    Commands.scrollTo(
-      this._scrollView.nativeInstance,
-      x || 0,
-      y || 0,
-      animated !== false,
-    );
+    Commands.scrollTo(component, x || 0, y || 0, animated !== false);
   };
 
   /**
@@ -937,10 +917,11 @@ class ScrollView extends React.Component<Props, State> {
   ) => {
     // Default to true
     const animated = (options && options.animated) !== false;
-    if (this._scrollView.nativeInstance == null) {
+    const component = this.getNativeScrollRef();
+    if (component == null) {
       return;
     }
-    Commands.scrollToEnd(this._scrollView.nativeInstance, animated);
+    Commands.scrollToEnd(component, animated);
   };
 
   /**
@@ -949,48 +930,25 @@ class ScrollView extends React.Component<Props, State> {
    * @platform ios
    */
   flashScrollIndicators: () => void = () => {
-    if (this._scrollView.nativeInstance == null) {
+    const component = this.getNativeScrollRef();
+    if (component == null) {
       return;
     }
-    Commands.flashScrollIndicators(this._scrollView.nativeInstance);
+    Commands.flashScrollIndicators(component);
   };
 
   _subscribeToOnScroll: (
     callback: ({x: number, y: number}) => void,
   ) => EventSubscription = callback => {
-    // An undefined value means the listener has not been added, yet.
-    // A null value means the listener has been removed.
-    let subscription: ?EventSubscription;
-
-    this.setState(
-      ({onScrollEmitter}) => {
-        if (onScrollEmitter) {
-          return null;
-        } else {
-          return {onScrollEmitter: new EventEmitter()};
-        }
-      },
-      () => {
-        // If `subscription` is null, that means it was removed before we got
-        // here so do nothing.
-        if (subscription !== null) {
-          subscription = nullthrows(this.state.onScrollEmitter).addListener(
-            'scroll',
-            callback,
-          );
-        }
-      },
-    );
-
-    return {
-      remove() {
-        // If `subscription` was created before this invocation, remove it.
-        subscription?.remove();
-        // Record this invocation by setting `subscription` to null, in case it
-        // ends up being created after this invocation.
-        subscription = null;
-      },
-    };
+    let onScrollEmitter = this.#onScrollEmitter;
+    if (onScrollEmitter == null) {
+      onScrollEmitter = new EventEmitter();
+      this.#onScrollEmitter = onScrollEmitter;
+      // This is the first subscription, so make sure the native component is
+      // also configured to output synchronous scroll events.
+      this._scrollView.nativeInstance?.unstable_setEnableSyncOnScroll(true);
+    }
+    return onScrollEmitter.addListener('scroll', callback);
   };
 
   /**
@@ -1072,14 +1030,11 @@ class ScrollView extends React.Component<Props, State> {
       );
     }
 
-    if (this._scrollView.nativeInstance == null) {
+    const component = this.getNativeScrollRef();
+    if (component == null) {
       return;
     }
-    Commands.zoomToRect(
-      this._scrollView.nativeInstance,
-      rect,
-      animated !== false,
-    );
+    Commands.zoomToRect(component, rect, animated !== false);
   };
 
   _textInputFocusError() {
@@ -1152,7 +1107,7 @@ class ScrollView extends React.Component<Props, State> {
     ) {
       this._scrollAnimatedValueAttachment =
         AnimatedImplementation.attachNativeEvent(
-          this._scrollView.nativeInstance,
+          this.getNativeScrollRef(),
           'onScroll',
           [{nativeEvent: {contentOffset: {y: this._scrollAnimatedValue}}}],
         );
@@ -1200,7 +1155,7 @@ class ScrollView extends React.Component<Props, State> {
     this._observedScrollSinceBecomingResponder = true;
     this.props.onScroll && this.props.onScroll(e);
 
-    this.state.onScrollEmitter?.emit('scroll', {
+    this.#onScrollEmitter?.emit('scroll', {
       x: e.nativeEvent.contentOffset.x,
       y: e.nativeEvent.contentOffset.y,
     });
@@ -1227,41 +1182,44 @@ class ScrollView extends React.Component<Props, State> {
     );
 
   _scrollView: RefForwarder<
-    NativeScrollViewInstance,
-    PublicScrollViewInstance,
-  > = createRefForwarder(
-    (nativeInstance: NativeScrollViewInstance): PublicScrollViewInstance => {
-      // This is a hack. Ideally we would forwardRef  to the underlying
-      // host component. However, since ScrollView has it's own methods that can be
-      // called as well, if we used the standard forwardRef then these
-      // methods wouldn't be accessible and thus be a breaking change.
-      //
-      // Therefore we edit ref to include ScrollView's public methods so that
-      // they are callable from the ref.
-
-      // $FlowFixMe[prop-missing] - Known issue with appending custom methods.
-      const publicInstance: PublicScrollViewInstance = Object.assign(
-        nativeInstance,
-        {
-          getScrollResponder: this.getScrollResponder,
-          getScrollableNode: this.getScrollableNode,
-          getInnerViewNode: this.getInnerViewNode,
-          getInnerViewRef: this.getInnerViewRef,
-          getNativeScrollRef: this.getNativeScrollRef,
-          scrollTo: this.scrollTo,
-          scrollToEnd: this.scrollToEnd,
-          flashScrollIndicators: this.flashScrollIndicators,
-          scrollResponderZoomTo: this.scrollResponderZoomTo,
-          // TODO: Replace unstable_subscribeToOnScroll once scrollView.addEventListener('scroll', (e: ScrollEvent) => {}, {passive: false});
-          unstable_subscribeToOnScroll: this._subscribeToOnScroll,
-          scrollResponderScrollNativeHandleToKeyboard:
-            this.scrollResponderScrollNativeHandleToKeyboard,
-        },
-      );
+    TScrollViewNativeImperativeHandle,
+    PublicScrollViewInstance | null,
+  > = createRefForwarder(nativeImperativeHandle => {
+    const nativeInstance = nativeImperativeHandle.componentRef.current;
+    if (nativeInstance == null) {
+      return null;
+    }
 
-      return publicInstance;
-    },
-  );
+    // This is a hack. Ideally we would forwardRef  to the underlying
+    // host component. However, since ScrollView has it's own methods that can be
+    // called as well, if we used the standard forwardRef then these
+    // methods wouldn't be accessible and thus be a breaking change.
+    //
+    // Therefore we edit ref to include ScrollView's public methods so that
+    // they are callable from the ref.
+
+    // $FlowFixMe[prop-missing] - Known issue with appending custom methods.
+    const publicInstance: PublicScrollViewInstance = Object.assign(
+      nativeInstance,
+      {
+        getScrollResponder: this.getScrollResponder,
+        getScrollableNode: this.getScrollableNode,
+        getInnerViewNode: this.getInnerViewNode,
+        getInnerViewRef: this.getInnerViewRef,
+        getNativeScrollRef: this.getNativeScrollRef,
+        scrollTo: this.scrollTo,
+        scrollToEnd: this.scrollToEnd,
+        flashScrollIndicators: this.flashScrollIndicators,
+        scrollResponderZoomTo: this.scrollResponderZoomTo,
+        // TODO: Replace unstable_subscribeToOnScroll once scrollView.addEventListener('scroll', (e: ScrollEvent) => {}, {passive: false});
+        unstable_subscribeToOnScroll: this._subscribeToOnScroll,
+        scrollResponderScrollNativeHandleToKeyboard:
+          this.scrollResponderScrollNativeHandleToKeyboard,
+      },
+    );
+
+    return publicInstance;
+  });
 
   /**
    * Warning, this may be called several times for a single keyboard opening.
@@ -1690,14 +1648,19 @@ class ScrollView extends React.Component<Props, State> {
     this.props.onTouchMove && this.props.onTouchMove(e);
   };
 
-  render(): React.Node | React.Element<string> {
-    const [NativeDirectionalScrollView, NativeDirectionalScrollContentView] =
-      this.props.horizontal === true
-        ? NativeHorizontalScrollViewTuple
-        : NativeVerticalScrollViewTuple;
+  render(): React.Node {
+    const horizontal = this.props.horizontal === true;
+
+    const NativeScrollView = horizontal
+      ? HScrollViewNativeComponent
+      : VScrollViewNativeComponent;
+
+    const NativeScrollContentView = horizontal
+      ? HScrollContentViewNativeComponent
+      : VScrollContentViewNativeComponent;
 
     const contentContainerStyle = [
-      this.props.horizontal === true && styles.contentContainerHorizontal,
+      horizontal && styles.contentContainerHorizontal,
       this.props.contentContainerStyle,
     ];
     if (__DEV__ && this.props.style !== undefined) {
@@ -1759,8 +1722,7 @@ class ScrollView extends React.Component<Props, State> {
       });
     }
     children = (
-      <ScrollViewContext.Provider
-        value={this.props.horizontal === true ? HORIZONTAL : VERTICAL}>
+      <ScrollViewContext.Provider value={horizontal ? HORIZONTAL : VERTICAL}>
         {children}
       </ScrollViewContext.Provider>
     );
@@ -1776,7 +1738,7 @@ class ScrollView extends React.Component<Props, State> {
       (Platform.OS === 'android' && this.props.snapToAlignment != null);
 
     const contentContainer = (
-      <NativeDirectionalScrollContentView
+      <NativeScrollContentView
         {...contentSizeChangeProps}
         ref={this._innerView.getForwardingRef(this.props.innerViewRef)}
         style={contentContainerStyle}
@@ -1790,7 +1752,7 @@ class ScrollView extends React.Component<Props, State> {
         collapsable={false}
         collapsableChildren={!preserveChildren}>
         {children}
-      </NativeDirectionalScrollContentView>
+      </NativeScrollContentView>
     );
 
     const alwaysBounceHorizontal =
@@ -1803,10 +1765,7 @@ class ScrollView extends React.Component<Props, State> {
         ? this.props.alwaysBounceVertical
         : !this.props.horizontal;
 
-    const baseStyle =
-      this.props.horizontal === true
-        ? styles.baseHorizontal
-        : styles.baseVertical;
+    const baseStyle = horizontal ? styles.baseHorizontal : styles.baseVertical;
 
     const {experimental_endDraggingSensitivityMultiplier, ...otherProps} =
       this.props;
@@ -1838,7 +1797,6 @@ class ScrollView extends React.Component<Props, State> {
       onScroll: this._handleScroll,
       endDraggingSensitivityMultiplier:
         experimental_endDraggingSensitivityMultiplier,
-      enableSyncOnScroll: this.state.onScrollEmitter ? true : undefined,
       scrollEventThrottle: hasStickyHeaders
         ? 1
         : this.props.scrollEventThrottle,
@@ -1871,18 +1829,18 @@ class ScrollView extends React.Component<Props, State> {
     }
 
     const refreshControl = this.props.refreshControl;
-    const scrollViewRef = this._scrollView.getForwardingRef(
-      this.props.scrollViewRef,
-    );
+    const scrollViewRef: React.RefSetter<TScrollViewNativeImperativeHandle | null> =
+      this._scrollView.getForwardingRef(this.props.scrollViewRef);
 
     if (refreshControl) {
       if (Platform.OS === 'ios') {
         // On iOS the RefreshControl is a child of the ScrollView.
         return (
-          <NativeDirectionalScrollView {...props} ref={scrollViewRef}>
+          // $FlowFixMe[incompatible-type] - Flow only knows element refs.
+          <NativeScrollView {...props} ref={scrollViewRef}>
             {refreshControl}
             {contentContainer}
-          </NativeDirectionalScrollView>
+          </NativeScrollView>
         );
       } else if (Platform.OS === 'android') {
         // On Android wrap the ScrollView with a AndroidSwipeRefreshLayout.
@@ -1896,19 +1854,21 @@ class ScrollView extends React.Component<Props, State> {
         return React.cloneElement(
           refreshControl,
           {style: StyleSheet.compose(baseStyle, outer)},
-          <NativeDirectionalScrollView
+          <NativeScrollView
             {...props}
             style={StyleSheet.compose(baseStyle, inner)}
+            // $FlowFixMe[incompatible-type] - Flow only knows element refs.
             ref={scrollViewRef}>
             {contentContainer}
-          </NativeDirectionalScrollView>,
+          </NativeScrollView>,
         );
       }
     }
     return (
-      <NativeDirectionalScrollView {...props} ref={scrollViewRef}>
+      // $FlowFixMe[incompatible-type] - Flow only knows element refs.
+      <NativeScrollView {...props} ref={scrollViewRef}>
         {contentContainer}
-      </NativeDirectionalScrollView>
+      </NativeScrollView>
     );
   }
 }
@@ -1931,11 +1891,9 @@ const styles = StyleSheet.create({
   },
 });
 
-type ForwardedRef<T> = {current: null | T, ...} | ((null | T) => mixed);
-
 type RefForwarder<TNativeInstance, TPublicInstance> = {
   getForwardingRef: (
-    ?ForwardedRef<TPublicInstance>,
+    ?React.RefSetter<TPublicInstance>,
   ) => (TNativeInstance | null) => void,
   nativeInstance: TNativeInstance | null,
   publicInstance: TPublicInstance | null,
@@ -1973,21 +1931,25 @@ function createRefForwarder<TNativeInstance, TPublicInstance>(
   return state;
 }
 
-/* $FlowFixMe[missing-local-annot] The type annotation(s) required by Flow's
- * LTI update could not be added via codemod */
-function Wrapper(props, ref: (mixed => mixed) | {current: mixed, ...}) {
-  return <ScrollView {...props} scrollViewRef={ref} />;
-}
+// TODO: After upgrading to React 19, remove `forwardRef` from this component.
+// NOTE: This wrapper component is necessary because `ScrollView` is a class
+// component and we need to map `ref` to a differently named prop. This can be
+// removed when `ScrollView` is a functional component.
+const Wrapper = React.forwardRef(function Wrapper(
+  props: Props,
+  ref: ?React.RefSetter<PublicScrollViewInstance>,
+): React.Node {
+  return ref == null ? (
+    <ScrollView {...props} />
+  ) : (
+    <ScrollView {...props} scrollViewRef={ref} />
+  );
+});
 Wrapper.displayName = 'ScrollView';
-// $FlowFixMe[incompatible-call]
-const ForwardedScrollView = React.forwardRef(Wrapper);
-
-// $FlowFixMe[prop-missing] Add static context to ForwardedScrollView
-ForwardedScrollView.Context = ScrollViewContext;
-
-ForwardedScrollView.displayName = 'ScrollView';
+// $FlowExpectedError[prop-missing]
+Wrapper.Context = ScrollViewContext;
 
-module.exports = ((ForwardedScrollView: $FlowFixMe): React.AbstractComponent<
+module.exports = ((Wrapper: $FlowFixMe): React.AbstractComponent<
   React.ElementConfig<typeof ScrollView>,
   PublicScrollViewInstance,
 > &

package/Libraries/Components/ScrollView/ScrollViewNativeComponent.js

@@ -160,6 +160,9 @@ export const __INTERNAL_VIEW_CONFIG: PartialViewConfig =
           snapToInterval: true,
           snapToOffsets: true,
           snapToStart: true,
+          verticalScrollIndicatorInsets: {
+            diff: require('../../Utilities/differ/insetsDiffer'),
+          },
           zoomScale: true,
           ...ConditionallyIgnoredEventHandlers({
             onScrollBeginDrag: true,

package/Libraries/Components/ScrollView/ScrollViewStickyHeader.js

@@ -19,7 +19,7 @@ import * as React from 'react';
 import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
 
 export type Props = $ReadOnly<{
-  children?: React.Element<$FlowFixMe>,
+  children?: ExactReactElement_DEPRECATED<$FlowFixMe>,
   nextHeaderLayoutY: ?number,
   onLayout: (event: LayoutEvent) => void,
   scrollAnimatedValue: Animated.Value,

package/Libraries/Components/StatusBar/StatusBar.js

@@ -272,8 +272,10 @@ class StatusBar extends React.Component<Props> {
   }
 
   /**
-   * Control the visibility of the network activity indicator
+   * DEPRECATED - The status bar network activity indicator is not supported in iOS 13 and later. This will be removed in a future release.
    * @param visible Show the indicator.
+   *
+   * @deprecated
    */
   static setNetworkActivityIndicatorVisible(visible: boolean) {
     if (Platform.OS !== 'ios') {

package/Libraries/Components/TextInput/RCTTextInputViewConfig.js

@@ -85,8 +85,15 @@ const RCTTextInputViewConfig = {
     topContentSizeChange: {
       registrationName: 'onContentSizeChange',
     },
+    topChangeSync: {
+      registrationName: 'onChangeSync',
+    },
+    topKeyPressSync: {
+      registrationName: 'onKeyPressSync',
+    },
   },
   validAttributes: {
+    dynamicTypeRamp: true,
     fontSize: true,
     fontWeight: true,
     fontVariant: true,
@@ -97,6 +104,7 @@ const RCTTextInputViewConfig = {
     textTransform: true,
     textAlign: true,
     fontFamily: true,
+    lineBreakModeIOS: true,
     lineHeight: true,
     isHighlighted: true,
     writingDirection: true,
@@ -150,6 +158,8 @@ const RCTTextInputViewConfig = {
       onSelectionChange: true,
       onContentSizeChange: true,
       onScroll: true,
+      onChangeSync: true,
+      onKeyPressSync: true,
     }),
   },
 };

package/Libraries/Components/TextInput/TextInput.d.ts

@@ -90,6 +90,8 @@ type DataDetectorTypes =
   | 'none'
   | 'all';
 
+export type SubmitBehavior = 'submit' | 'blurAndSubmit' | 'newline';
+
 /**
  * DocumentSelectionState is responsible for maintaining selection information
  * for a document.
@@ -649,11 +651,39 @@ export interface TextInputProps
   autoFocus?: boolean | undefined;
 
   /**
-   * If true, the text field will blur when submitted.
-   * The default value is true.
+   * If `true`, the text field will blur when submitted.
+   * The default value is true for single-line fields and false for
+   * multiline fields. Note that for multiline fields, setting `blurOnSubmit`
+   * to `true` means that pressing return will blur the field and trigger the
+   * `onSubmitEditing` event instead of inserting a newline into the field.
+   *
+   * @deprecated
+   * Note that `submitBehavior` now takes the place of `blurOnSubmit` and will
+   * override any behavior defined by `blurOnSubmit`.
+   * @see submitBehavior
    */
   blurOnSubmit?: boolean | undefined;
 
+  /**
+   * When the return key is pressed,
+   *
+   * For single line inputs:
+   *
+   * - `'newline`' defaults to `'blurAndSubmit'`
+   * - `undefined` defaults to `'blurAndSubmit'`
+   *
+   * For multiline inputs:
+   *
+   * - `'newline'` adds a newline
+   * - `undefined` defaults to `'newline'`
+   *
+   * For both single line and multiline inputs:
+   *
+   * - `'submit'` will only send a submit event and not blur the input
+   * - `'blurAndSubmit`' will both blur the input and send a submit event
+   */
+  submitBehavior?: SubmitBehavior | undefined;
+
   /**
    * If true, caret is hidden. The default value is false.
    */