Warn in development when a view reports its safe area 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.

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/__tests__/ViewSafeAreaInsetsWarning-itest.js

@@ -0,0 +1,132 @@
+/**
+ * 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};
+const FRAME = {x: 0, y: 0, width: 390, height: 844};
+
+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,
+    frame: FRAME,
+  });
+}
+
+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/src/private/components/view/warnOnRepeatedSafeAreaInsetsChanges.js

@@ -0,0 +1,78 @@
+/**
+ * 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 type {SafeAreaInsetsChangeEvent} from '../../../../Libraries/Types/CoreEventTypes';
+
+const DISPATCH_WINDOW_MS = 1000;
+const MAX_DISPATCHES_PER_WINDOW = 10;
+
+type DispatchRate = {
+  count: number,
+  windowStart: number,
+  warned: boolean,
+};
+
+const dispatchRates: WeakMap<interface {}, DispatchRate> = new WeakMap();
+
+/**
+ * Wraps an `experimental_onSafeAreaInsetsChange` handler with a development
+ * check for a view that reports insets over and over.
+ *
+ * The system UI does not move many times a second, so a sustained stream of
+ * events means the layout is feeding the insets back into the position of the
+ * observed view: it pads itself by the insets it reports, which moves it, which
+ * changes its insets. Every one of those events renders synchronously, blocking
+ * the UI thread, so the loop is paid for in frames.
+ */
+export default function warnOnRepeatedSafeAreaInsetsChanges(
+  onSafeAreaInsetsChange: (event: SafeAreaInsetsChangeEvent) => unknown,
+): (event: SafeAreaInsetsChangeEvent) => unknown {
+  return event => {
+    // The target identifies the view without keeping it alive; events dispatched
+    // without one are simply not counted.
+    const target = event.target;
+    if (target != null && typeof target === 'object') {
+      warnIfDispatchingTooOften(target);
+    }
+    return onSafeAreaInsetsChange(event);
+  };
+}
+
+function warnIfDispatchingTooOften(target: interface {}): void {
+  const now = performance.now();
+  let dispatchRate: ?DispatchRate = dispatchRates.get(target);
+  if (dispatchRate == null) {
+    const newDispatchRate: DispatchRate = {
+      count: 0,
+      windowStart: now,
+      warned: false,
+    };
+    dispatchRates.set(target, newDispatchRate);
+    dispatchRate = newDispatchRate;
+  }
+  if (dispatchRate.warned) {
+    return;
+  }
+  if (now - dispatchRate.windowStart > DISPATCH_WINDOW_MS) {
+    dispatchRate.windowStart = now;
+    dispatchRate.count = 0;
+  }
+  dispatchRate.count++;
+  if (dispatchRate.count > MAX_DISPATCHES_PER_WINDOW) {
+    dispatchRate.warned = true;
+    console.warn(
+      `\`experimental_onSafeAreaInsetsChange\` fired more than ${MAX_DISPATCHES_PER_WINDOW} ` +
+        `times in ${DISPATCH_WINDOW_MS}ms on a single view. The safe area insets of a view ` +
+        'only change when the system UI moves or the view does, so this is usually a loop: ' +
+        'the view is laid out from the insets it reports, which moves it, which changes its ' +
+        'insets. Each event renders synchronously, so the loop costs frames.',
+    );
+  }
+}

packages/rn-tester/js/examples/SafeAreaInsets/SafeAreaInsetsExample.js

@@ -147,6 +147,71 @@ function FullScreenExample(): React.Node {
   );
 }
 
+function FeedbackLoopModalContent({
+  onClose,
+}: {
+  onClose: () => void,
+}): React.Node {
+  const [insets, , onSafeAreaInsetsChange] = useSafeAreaInsets();
+  const [eventCount, setEventCount] = useState(0);
+  const [looping, setLooping] = useState(false);
+
+  const onLoopingInsetsChange = useCallback(
+    (event: SafeAreaInsetsChangeEvent) => {
+      setEventCount(count => count + 1);
+      onSafeAreaInsetsChange(event);
+    },
+    [onSafeAreaInsetsChange],
+  );
+
+  return (
+    <View style={styles.modal}>
+      {/*
+        The mistake this warns about: the view is *positioned* by the insets it
+        reports, instead of padded by them. Offsetting it moves it out from
+        under the system UI, which zeroes its insets, which moves it back.
+      */}
+      <View
+        experimental_onSafeAreaInsetsChange={
+          looping ? onLoopingInsetsChange : undefined
+        }
+        style={[styles.loopBox, {marginTop: looping ? (insets?.top ?? 0) : 0}]}>
+        <RNTesterText>{`inset events: ${eventCount}`}</RNTesterText>
+      </View>
+      <View style={styles.modalContent}>
+        <RNTesterText>
+          Starting the loop should log a development warning after ten events in
+          a second, once, while the counter keeps climbing.
+        </RNTesterText>
+        {!looping ? (
+          <Button onPress={() => setLooping(true)} title="Start the loop" />
+        ) : null}
+        <Button onPress={onClose} title="Close" />
+      </View>
+    </View>
+  );
+}
+
+function FeedbackLoopExample(): React.Node {
+  const [modalVisible, setModalVisible] = useState(false);
+
+  return (
+    <View>
+      <Modal
+        visible={modalVisible}
+        onRequestClose={() => setModalVisible(false)}
+        animationType="slide"
+        supportedOrientations={['portrait', 'landscape']}>
+        <FeedbackLoopModalContent onClose={() => setModalVisible(false)} />
+      </Modal>
+      <Button
+        onPress={() => setModalVisible(true)}
+        title="Present a view that loops"
+      />
+    </View>
+  );
+}
+
 let benchEventCount = 0;
 
 function BenchRow({
@@ -274,6 +339,11 @@ const styles = StyleSheet.create({
     flexDirection: 'row',
     flexWrap: 'wrap',
   },
+  loopBox: {
+    backgroundColor: '#ffd7d7',
+    paddingVertical: 8,
+    paddingHorizontal: 12,
+  },
   benchScrollContainer: {
     height: 300,
     borderWidth: 1,
@@ -307,6 +377,12 @@ exports.examples = [
       'A full screen view that pads itself by its own safe area insets.',
     render: (): React.Node => <FullScreenExample />,
   },
+  {
+    title: 'A view that reports its insets in a loop',
+    description:
+      'A view positioned by the insets it reports, which moves it out of the system UI and back. Development builds warn once when a view does this.',
+    render: (): React.Node => <FeedbackLoopExample />,
+  },
   {
     title: 'Scroll benchmark',
     description: