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}}) => {
    // insets: {top, right, bottom, left}
  }}
/>
```

`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, 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.

Folded in from review: the prop is forwarded through BaseViewManagerDelegate
for components with generated delegates, and the event is exported from the
native view config so it maps to the handler when native view configs are
in use.

Development warning for a view that reports its insets in a loop:

The system UI does not move many times a second, so a sustained stream of
inset events means the layout is feeding the insets back into the position of
the observed view: it is offset by the insets it reports, which moves it out
from under the system UI, which changes its insets. Every one of those events
renders synchronously, so the loop is paid for in frames.

`View` wraps the handler in development builds and warns once per view above
ten events in a second. The check lives in the handler `View` passes down
rather than in either platform's observer, so it covers iOS and Android with
one implementation and surfaces in LogBox with a JavaScript stack.

The production branch is the identity function, so the module stays out of
the bundle, and the native prop is unaffected either way — function props are
normalized to `true` before props are diffed, so wrapping does not produce an
update. Counts are kept per view in a `WeakMap` keyed by the event target, so
views that do not loop are never charged for it.

RNTester grows the mistake it warns about, and a Fantom test with a mocked
clock covers the rate, the once-per-view behaviour, per-view counting, and
that the handler still receives its event.

The payload is the insets alone. A frame is deliberately not included: it
would only be current as of the last inset change, since the trigger is
inset-only, and reporting it needs a coordinate space that differs between
platforms (the enclosing view controller on iOS, the window on Android). A
view that needs its own frame has `onLayout` and `measureInWindow`, which
stay current; the window's frame is in `Dimensions`.

Author: janicduplessis

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

@@ -9,13 +9,23 @@
  */
 
 import type {HostInstance} from '../../../src/private/types/HostInstance';
+import type {SafeAreaInsetsChangeEvent} from '../../Types/CoreEventTypes';
 import type {ViewProps} from './ViewPropTypes';
 
 import TextAncestorContext from '../../Text/TextAncestorContext';
 import ViewNativeComponent from './ViewNativeComponent';
 import * as React from 'react';
 import {use} from 'react';
 
+// Only development builds check for a view reporting its insets in a loop; the
+// production branch keeps the handler as it is, and the module out of the bundle.
+const warnOnRepeatedSafeAreaInsetsChanges: (
+  onSafeAreaInsetsChange: (event: SafeAreaInsetsChangeEvent) => unknown,
+) => (event: SafeAreaInsetsChangeEvent) => unknown = __DEV__
+  ? require('../../../src/private/components/view/warnOnRepeatedSafeAreaInsetsChanges')
+      .default
+  : onSafeAreaInsetsChange => onSafeAreaInsetsChange;
+
 export type ViewInstance = HostInstance;
 
 /**
@@ -115,6 +125,18 @@ component View(ref?: React.RefSetter<ViewInstance>, ...props: ViewProps) {
     };
   }
 
+  if (__DEV__) {
+    // Views are the only place the prop is used in practice, so the check for a
+    // view reporting its insets in a loop lives here rather than on every host
+    // component that inherits the prop.
+    const onSafeAreaInsetsChange =
+      resolvedProps.experimental_onSafeAreaInsetsChange;
+    if (onSafeAreaInsetsChange != null) {
+      resolvedProps.experimental_onSafeAreaInsetsChange =
+        warnOnRepeatedSafeAreaInsetsChanges(onSafeAreaInsetsChange);
+    }
+  }
+
   const actualView =
     ref == null ? (
       <ViewNativeComponent {...resolvedProps} />

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,108 @@
+/**
+ * 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};
+
+describe('experimental_onSafeAreaInsetsChange', () => {
+  it('delivers the insets 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,
+    });
+
+    expect(onSafeAreaInsetsChange).toHaveBeenCalledTimes(1);
+    const [event] = onSafeAreaInsetsChange.mock.lastCall;
+    expect(event.insets).toEqual(INSETS);
+  });
+
+  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/Components/View/__tests__/ViewSafeAreaInsetsWarning-itest.js

@@ -0,0 +1,130 @@
+/**
+ * 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 {HighResTimeStampMock} from '@react-native/fantom/src/HighResTimeStampMock';
+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};
+
+function renderObservingView(): {current: HostInstance | null} {
+  const nodeRef = createRef<HostInstance>();
+  const root = Fantom.createRoot();
+  Fantom.runTask(() => {
+    root.render(
+      <View ref={nodeRef} experimental_onSafeAreaInsetsChange={() => {}} />,
+    );
+  });
+  return nodeRef;
+}
+
+function dispatchInsetsChange(nodeRef: {current: HostInstance | null}) {
+  Fantom.dispatchNativeEvent(nodeRef, 'safeAreaInsetsChange', {
+    insets: INSETS,
+  });
+}
+
+describe('experimental_onSafeAreaInsetsChange warning', () => {
+  const originalConsoleWarn = console.warn;
+  let mockConsoleWarn: JestMockFn<ReadonlyArray<unknown>, void>;
+  let mockClock: ?HighResTimeStampMock;
+
+  beforeEach(() => {
+    mockConsoleWarn = jest.fn();
+    // $FlowFixMe[cannot-write]
+    console.warn = mockConsoleWarn;
+    mockClock = Fantom.installHighResTimeStampMock();
+  });
+
+  afterEach(() => {
+    // $FlowFixMe[cannot-write]
+    console.warn = originalConsoleWarn;
+    mockClock?.uninstall();
+    mockClock = null;
+  });
+
+  it('stays silent while the insets change at a plausible rate', () => {
+    const nodeRef = renderObservingView();
+
+    // A rotation, a keyboard, a split view: a handful of changes, spread out.
+    for (let i = 0; i < 20; i++) {
+      dispatchInsetsChange(nodeRef);
+      mockClock?.advanceTimeBy(200);
+    }
+
+    expect(mockConsoleWarn).not.toHaveBeenCalled();
+  });
+
+  it('warns once when a single view loops within the window', () => {
+    const nodeRef = renderObservingView();
+
+    for (let i = 0; i < 11; i++) {
+      dispatchInsetsChange(nodeRef);
+      mockClock?.advanceTimeBy(16);
+    }
+
+    expect(mockConsoleWarn).toHaveBeenCalledTimes(1);
+    expect(mockConsoleWarn.mock.lastCall[0]).toContain(
+      '`experimental_onSafeAreaInsetsChange` fired more than 10 times in 1000ms',
+    );
+
+    // The loop keeps running; the warning does not.
+    for (let i = 0; i < 50; i++) {
+      dispatchInsetsChange(nodeRef);
+      mockClock?.advanceTimeBy(16);
+    }
+
+    expect(mockConsoleWarn).toHaveBeenCalledTimes(1);
+  });
+
+  it('counts each view separately', () => {
+    const nodeRefA = renderObservingView();
+    const nodeRefB = renderObservingView();
+
+    for (let i = 0; i < 10; i++) {
+      dispatchInsetsChange(nodeRefA);
+      dispatchInsetsChange(nodeRefB);
+      mockClock?.advanceTimeBy(16);
+    }
+
+    expect(mockConsoleWarn).not.toHaveBeenCalled();
+
+    dispatchInsetsChange(nodeRefA);
+
+    expect(mockConsoleWarn).toHaveBeenCalledTimes(1);
+  });
+
+  it('still delivers the event to the handler', () => {
+    const nodeRef = createRef<HostInstance>();
+    const onSafeAreaInsetsChange = jest.fn();
+    const root = Fantom.createRoot();
+    Fantom.runTask(() => {
+      root.render(
+        <View
+          ref={nodeRef}
+          experimental_onSafeAreaInsetsChange={event => {
+            onSafeAreaInsetsChange(event.nativeEvent);
+          }}
+        />,
+      );
+    });
+
+    dispatchInsetsChange(nodeRef);
+
+    expect(onSafeAreaInsetsChange).toHaveBeenCalledTimes(1);
+    expect(onSafeAreaInsetsChange.mock.lastCall[0].insets).toEqual(INSETS);
+  });
+});

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,23 @@ 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,
+  }>,
+>;
+
 /**
  * @deprecated Use `TextLayoutEvent` instead.
  */