Add an experimental_onSafeAreaInsetsChange view prop

Reports the part of a view that is covered by the system UI, as a view prop:

```jsx
<View
  experimental_onSafeAreaInsetsChange={({nativeEvent: {insets, frame}}) => {
    // insets: {top, right, bottom, left}, frame: {x, y, width, height}
  }}
/>
```

`SafeAreaView` is deprecated in favour of `react-native-safe-area-context`,
but core surfaces like LogBox and the element inspector cannot depend on the
library, so core keeps a private copy of the deprecated component alive. The
smallest primitive that lets both sides go away is native code reporting
inset values to JavaScript — today the library's own `RNCSafeAreaProvider`
component. This adds that primitive, with the payload the library already
uses, so `SafeAreaProvider` can swap its native component for a plain `View`.

Insets are relative to the view: one laid out inside the safe area reports
zeros. That is what makes the prop composable and stops nested providers
from double-padding.

**Cost when unused.** The prop is a `bool` in `BaseViewProps`, like
`onLayout`; native only observes the safe area when it is set. On iOS the
flag is read from the props the view already holds and the last-sent insets
live behind a single pointer ivar that stays nil unless the view observes;
the only unconditional cost is a branch in `layoutSubviews`,
`didMoveToWindow` and `safeAreaInsetsDidChange`.

**Cost when used.** Events fire only when the *insets* change — the frame is
in the payload but not in the trigger — so a view moving inside a scroll
view emits nothing, and 50 observing rows scroll at the same frame times as
zero. An observing view allocates nothing per frame on Android in the steady
state. Benchmarked with the "Scroll benchmark" section of the new RNTester
example.

**Synchronous dispatch.** The event goes out through
`EventEmitter::experimental_flushSync` as a `Discrete` event, so inset-driven
layout is mounted in the frame the insets changed in — first mount included,
and on rotation the padding animates with the transition instead of jumping
after it.

Edge cases covered: view flattening (the prop forms a stacking context so
the host view cannot be optimized away), view recycling on both platforms,
Android views fully clipped by an ancestor, and multi-window iPad.

Author: janicduplessis

packages/react-native/Libraries/Components/View/ViewPropTypes.js

@@ -23,6 +23,7 @@ import type {
   LayoutRectangle,
   MouseEvent,
   PointerEvent,
+  SafeAreaInsetsChangeEvent,
 } from '../../Types/CoreEventTypes';
 import type {
   AccessibilityActionEvent,
@@ -63,6 +64,32 @@ type DirectEventProps = Readonly<{
    */
   onLayout?: ?(event: LayoutChangeEvent) => unknown,
 
+  /**
+   * Invoked when the part of this view that is covered by the system UI
+   * (status bar, navigation bar, home indicator, display cutouts, ...)
+   * changes, with:
+   *
+   * `{nativeEvent: {insets: {top, right, bottom, left}, frame: {x, y, width, height}}}`
+   *
+   * `insets` are relative to this view: an inset is only non-zero for the part
+   * of the view that actually overlaps the system UI. `frame` is the position
+   * of the view at the time of the event, relative to its enclosing view
+   * controller on iOS and to the window on Android; it does not trigger the
+   * event on its own, so it can be stale while the view moves without its
+   * insets changing.
+   *
+   * The event is dispatched synchronously, so the rendering it schedules is
+   * applied in the same frame the insets changed in.
+   *
+   * Setting this prop makes the view observe safe area changes; views without
+   * it are unaffected.
+   *
+   * @experimental
+   */
+  experimental_onSafeAreaInsetsChange?: ?(
+    event: SafeAreaInsetsChangeEvent,
+  ) => unknown,
+
   /**
    * When `accessible` is `true`, the system will invoke this function when the
    * user performs the magic tap gesture.

packages/react-native/Libraries/Components/View/__tests__/ViewSafeAreaInsets-itest.js

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import '@react-native/fantom/src/setUpDefaultReactNativeEnvironment';
+
+import type {HostInstance} from 'react-native/src/private/types/HostInstance';
+
+import * as Fantom from '@react-native/fantom';
+import * as React from 'react';
+import {createRef} from 'react';
+import {View} from 'react-native';
+
+const INSETS = {top: 44, right: 0, bottom: 34, left: 0};
+const FRAME = {x: 0, y: 0, width: 390, height: 844};
+
+describe('experimental_onSafeAreaInsetsChange', () => {
+  it('delivers the insets and the frame of the view', () => {
+    const root = Fantom.createRoot();
+    const nodeRef = createRef<HostInstance>();
+    const onSafeAreaInsetsChange = jest.fn();
+
+    Fantom.runTask(() => {
+      root.render(
+        <View
+          collapsable={false}
+          ref={nodeRef}
+          experimental_onSafeAreaInsetsChange={event => {
+            onSafeAreaInsetsChange(event.nativeEvent);
+          }}
+        />,
+      );
+    });
+
+    Fantom.dispatchNativeEvent(nodeRef, 'safeAreaInsetsChange', {
+      insets: INSETS,
+      frame: FRAME,
+    });
+
+    expect(onSafeAreaInsetsChange).toHaveBeenCalledTimes(1);
+    const [event] = onSafeAreaInsetsChange.mock.lastCall;
+    expect(event.insets).toEqual(INSETS);
+    expect(event.frame).toEqual(FRAME);
+  });
+
+  it('is not delivered to views that did not opt in', () => {
+    const root = Fantom.createRoot();
+    const nodeRef = createRef<HostInstance>();
+
+    Fantom.runTask(() => {
+      root.render(<View collapsable={false} ref={nodeRef} />);
+    });
+
+    // The prop is what makes the view observe the safe area, so a view without
+    // it is never the target of the event.
+    expect(
+      root
+        .getRenderedOutput({props: ['experimental_onSafeAreaInsetsChange']})
+        .toJSX(),
+    ).toEqual(<rn-view />);
+  });
+
+  it('prevents the view from being flattened', () => {
+    const root = Fantom.createRoot();
+
+    Fantom.runTask(() => {
+      root.render(
+        // A layout-only view would ordinarily be flattened away; observing the
+        // safe area requires a host view to observe with.
+        <View experimental_onSafeAreaInsetsChange={() => {}}>
+          <View collapsable={false} />
+        </View>,
+      );
+    });
+
+    expect(
+      root
+        .getRenderedOutput({props: ['experimental_onSafeAreaInsetsChange']})
+        .toJSX(),
+    ).toEqual(
+      <rn-view experimental_onSafeAreaInsetsChange="true">
+        <rn-view />
+      </rn-view>,
+    );
+  });
+
+  it('is reflected in the props of the view when set', () => {
+    const root = Fantom.createRoot();
+
+    Fantom.runTask(() => {
+      root.render(
+        <View
+          collapsable={false}
+          experimental_onSafeAreaInsetsChange={() => {}}
+        />,
+      );
+    });
+
+    expect(
+      root
+        .getRenderedOutput({props: ['experimental_onSafeAreaInsetsChange']})
+        .toJSX(),
+    ).toEqual(<rn-view experimental_onSafeAreaInsetsChange="true" />);
+  });
+});

packages/react-native/Libraries/NativeComponent/BaseViewConfig.android.js

@@ -204,6 +204,9 @@ const directEventTypes = {
   topLayout: {
     registrationName: 'onLayout',
   },
+  topSafeAreaInsetsChange: {
+    registrationName: 'experimental_onSafeAreaInsetsChange',
+  },
 };
 
 const validAttributesForNonEventProps = {
@@ -405,6 +408,7 @@ const validAttributesForNonEventProps = {
 // Props for bubbling and direct events
 const validAttributesForEventProps = {
   onLayout: true,
+  experimental_onSafeAreaInsetsChange: true,
 
   // PanResponder handlers
   onMoveShouldSetResponder: true,

packages/react-native/Libraries/NativeComponent/BaseViewConfig.ios.js

@@ -179,6 +179,9 @@ const directEventTypes = {
   topLayout: {
     registrationName: 'onLayout',
   },
+  topSafeAreaInsetsChange: {
+    registrationName: 'experimental_onSafeAreaInsetsChange',
+  },
   onGestureHandlerEvent: DynamicallyInjectedByGestureHandler({
     registrationName: 'onGestureHandlerEvent',
   }),
@@ -380,6 +383,7 @@ const validAttributesForNonEventProps = {
 // Props for bubbling and direct events
 const validAttributesForEventProps = ConditionallyIgnoredEventHandlers({
   onLayout: true,
+  experimental_onSafeAreaInsetsChange: true,
   onMagicTap: true,
 
   // Accessibility

packages/react-native/Libraries/Types/CoreEventTypes.js

@@ -76,6 +76,29 @@ export type LayoutChangeEvent = NativeSyntheticEvent<
   }>,
 >;
 
+export type SafeAreaInsets = Readonly<{
+  top: number,
+  right: number,
+  bottom: number,
+  left: number,
+}>;
+
+export type SafeAreaInsetsChangeEvent = NativeSyntheticEvent<
+  Readonly<{
+    /**
+     * The part of the view that is covered by the system UI, in the view's own
+     * coordinate space.
+     */
+    insets: SafeAreaInsets,
+    /**
+     * The frame of the view at the time of the event. Relative to the
+     * enclosing view controller on iOS and to the window on Android; only
+     * updated when the insets change.
+     */
+    frame: LayoutRectangle,
+  }>,
+>;
+
 /**
  * @deprecated Use `TextLayoutEvent` instead.
  */

packages/react-native/React/Fabric/Mounting/ComponentViews/View/RCTViewComponentView.mm

@@ -25,6 +25,7 @@
 #import <React/RCTLocalizedString.h>
 #import <React/RCTLog.h>
 #import <React/RCTRadialGradient.h>
+#import <React/RCTUtils.h>
 #import <react/featureflags/ReactNativeFeatureFlags.h>
 #import <react/renderer/components/view/ViewComponentDescriptor.h>
 #import <react/renderer/components/view/ViewEventEmitter.h>
@@ -122,6 +123,11 @@ @implementation RCTViewComponentView {
   NSMutableSet<NSString *> *_accessibilityOrderNativeIDs;
   RCTSwiftUIContainerViewWrapper *_swiftUIWrapper;
   BOOL _focusable;
+  // The insets sent with the last `onSafeAreaInsetsChange` event, or nil if
+  // none was sent yet. A pointer because almost no view observes the safe
+  // area: the views that do pay for a small box, every other view only for
+  // the pointer.
+  NSValue *_lastSentSafeAreaInsets;
 }
 
 #ifdef RCT_DYNAMIC_FRAMEWORKS
@@ -438,6 +444,15 @@ - (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &
         -newViewProps.hitSlop.right};
   }
 
+  // `onSafeAreaInsetsChange`. Scheduled whenever the prop is set, not only on
+  // its transitions: recycled views keep their last props, so `oldViewProps`
+  // of a freshly reused view is not a reliable baseline.
+  if (newViewProps.onSafeAreaInsetsChange) {
+    [self setNeedsLayout];
+  } else if (oldViewProps.onSafeAreaInsetsChange) {
+    _lastSentSafeAreaInsets = nil;
+  }
+
   // `overflow`
   if (oldViewProps.getClipsContentToBounds() != newViewProps.getClipsContentToBounds()) {
     self.currentContainerView.clipsToBounds = newViewProps.getClipsContentToBounds();
@@ -720,6 +735,105 @@ - (void)updateLayoutMetrics:(const LayoutMetrics &)layoutMetrics
   }
 }
 
+#pragma mark - Safe area insets
+
+// The view controller the view is hosted in, which is the coordinate space
+// `frame` is reported in. Modals and other view controllers are positioned
+// independently of the window, so the window is not a usable reference.
+static UIViewController *RCTParentViewControllerOfView(UIView *view)
+{
+  UIResponder *responder = view.nextResponder;
+  while (responder != nil) {
+    if ([responder isKindOfClass:[UIViewController class]]) {
+      return (UIViewController *)responder;
+    }
+    responder = responder.nextResponder;
+  }
+  return nil;
+}
+
+static BOOL RCTEdgeInsetsEqualWithThreshold(UIEdgeInsets lhs, UIEdgeInsets rhs, CGFloat threshold)
+{
+  return ABS(lhs.left - rhs.left) <= threshold && ABS(lhs.top - rhs.top) <= threshold &&
+      ABS(lhs.right - rhs.right) <= threshold && ABS(lhs.bottom - rhs.bottom) <= threshold;
+}
+
+// The event is only ever emitted from `layoutSubviews`; everything that might
+// have changed the insets merely marks the view as needing layout. This defers
+// the emit out of arbitrary call contexts — in particular out of
+// `updateProps`, which runs inside the mounting transaction where
+// synchronously re-entering React is not safe — while keeping it in the same
+// frame: the layout pass runs before the frame is displayed.
+- (void)_safeAreaInsetsMayHaveChanged
+{
+  if (!_eventEmitter) {
+    return;
+  }
+
+  // The view has not been mounted or laid out yet, so the insets we would
+  // compute are not the ones the view ends up with.
+  if (self.window == nil || CGSizeEqualToSize(self.bounds.size, CGSizeZero)) {
+    return;
+  }
+
+  // Only a change of the insets triggers an event. The frame is part of the
+  // payload but not of the trigger: a view that moves without its overlap with
+  // the system UI changing stays silent, which is what makes observing views
+  // safe to place inside scroll views.
+  UIEdgeInsets insets = self.safeAreaInsets;
+  if (_lastSentSafeAreaInsets != nil &&
+      RCTEdgeInsetsEqualWithThreshold(insets, _lastSentSafeAreaInsets.UIEdgeInsetsValue, 1.0 / RCTScreenScale())) {
+    return;
+  }
+
+  UIView *referenceView = RCTParentViewControllerOfView(self).view ?: self.window;
+  CGRect frame = [self convertRect:self.bounds toView:referenceView];
+
+  _lastSentSafeAreaInsets = [NSValue valueWithUIEdgeInsets:insets];
+
+  static_cast<const ViewEventEmitter &>(*_eventEmitter)
+      .onSafeAreaInsetsChange(
+          EdgeInsets{
+              .left = (Float)insets.left,
+              .top = (Float)insets.top,
+              .right = (Float)insets.right,
+              .bottom = (Float)insets.bottom},
+          RCTRectFromCGRect(frame));
+}
+
+// The prop is checked here rather than inside the helper so that views which
+// do not use it only pay for a branch on a prop they already have in hand.
+- (BOOL)_observesSafeAreaInsets
+{
+  return static_cast<const ViewProps &>(*_props).onSafeAreaInsetsChange;
+}
+
+- (void)safeAreaInsetsDidChange
+{
+  [super safeAreaInsetsDidChange];
+  if ([self _observesSafeAreaInsets]) {
+    [self setNeedsLayout];
+  }
+}
+
+- (void)didMoveToWindow
+{
+  [super didMoveToWindow];
+  if ([self _observesSafeAreaInsets]) {
+    [self setNeedsLayout];
+  }
+}
+
+- (void)layoutSubviews
+{
+  [super layoutSubviews];
+  // Both the insets and the frame depend on where the view sits in the window,
+  // so moving or resizing it changes them without UIKit notifying us.
+  if ([self _observesSafeAreaInsets]) {
+    [self _safeAreaInsetsMayHaveChanged];
+  }
+}
+
 - (BOOL)isJSResponder
 {
   return _isJSResponder;
@@ -775,6 +889,7 @@ - (void)prepareForRecycle
   _filterLayer = nil;
   [self clearExistingBackgroundImageLayers];
 
+  _lastSentSafeAreaInsets = nil;
   _propKeysManagedByAnimated_DO_NOT_USE_THIS_IS_BROKEN = nil;
   _eventEmitter.reset();
   _isJSResponder = NO;

packages/react-native/ReactAndroid/api/ReactAndroid.api

@@ -3264,6 +3264,7 @@ public abstract class com/facebook/react/uimanager/BaseViewManager : com/faceboo
 	public fun setMoveShouldSetResponder (Landroid/view/View;Z)V
 	public fun setMoveShouldSetResponderCapture (Landroid/view/View;Z)V
 	public fun setNativeId (Landroid/view/View;Ljava/lang/String;)V
+	public fun setOnSafeAreaInsetsChange (Landroid/view/View;Z)V
 	public fun setOpacity (Landroid/view/View;F)V
 	public fun setOutlineColor (Landroid/view/View;Ljava/lang/Integer;)V
 	public fun setOutlineOffset (Landroid/view/View;F)V
@@ -4604,6 +4605,7 @@ public final class com/facebook/react/uimanager/ViewProps {
 	public static final field NONE Ljava/lang/String;
 	public static final field NUMBER_OF_LINES Ljava/lang/String;
 	public static final field ON Ljava/lang/String;
+	public static final field ON_SAFE_AREA_INSETS_CHANGE Ljava/lang/String;
 	public static final field OPACITY Ljava/lang/String;
 	public static final field OUTLINE_COLOR Ljava/lang/String;
 	public static final field OUTLINE_OFFSET Ljava/lang/String;