feat(iOS, Tabs): add bottomAccessory support (#3288)

## Description

Adds support for `botttomAccessory` in Bottom Tabs starting from iOS 26.

## Synchronization with ShadowTree

When bottom accessory transitions between `regular` and `inline`
environments (when tab bar is minimized), we need to update the position
and size of the bottom accessory. Our approach is different for RN <
0.82 and RN >= 0.82.

### Possible approaches

We considered following approaches:
1. asynchronous state updates & events
- this would result in frame changing right after animation start to the
final size
- using `double-rendering` approach (explained further in PR
description) wouldn't really improve the situation
2. (a)synchronous state updates & asynchronous events + DisplayLink
- this allows us to track the native animation of the bottom accessory
and match frame size
- unfortunately, as DisplayLink allows us to read presentation layer
frame, we will always be 1 frame delayed
- with asynchronous updates, this delay increases to multiple frames;
with synchronous updates this would be exactly 1 frame (but this doesn't
mean it looks better!)
3. synchronous state updates & asynchronous events
- synchronous state updates allow us to rely on `CoreAnimations`
framework that animates views natively (details explained further in PR
description)
- unfortunately, this mechanism requires all changes to be performed
synchronously - state update (size change) is handled synchronously
thanks to `immediate` mode for state update introduced in RN 0.82 but
"synchronous" event dispatch in RN 0.82 isn't exactly `synchronous`
(update is performed on next loop beat, this is not enough for CA)
- due to this limitation, any changes in reaction to environment change
are buggy (see `Mounting/unmounting views during transition` section)
4. synchronous state updates & `double-rendering`
- to mitigate problems described above, we render the component twice -
first for `regular` environment, second for `inline` environment
- we change which component is visible on environment change -> we can
do this fully synchronously in native code
  - CA animates this change with cross-fade animation
- this results seems to be a good compromise but requires React state
synchronization between components, e.g. via context

For now, we decided to use:
- Paper: approach 2 (asynchronous)
- Fabric RN < 0.82: approach 2 (asynchronous)
- Fabric RN >= 0.82: approach 4

Those solutions are described in more detail below:

### Legacy architecture & New architecture prior to
`[email protected]`

In versions prior to RN 0.82, we need use `DisplayLink` and presentation
layer frames to get intermediate frames during the transition. This
approach however has a major drawback - we are always at least one frame
behind the current state as we're observing what is currently presented.
When the difference in size/origin between frames is significant, you
can see the content "jumping". In the case of bottom accessory, this is
especially visible when using non-translucent background and
transitioning from `inline` to `regular` environment (pay attention to
the right edge of the accessory).


https://github.com/user-attachments/assets/3931c318-2bb7-4bc2-847f-95168578d7d2

Introduction of synchronous state updates in RN 0.82 (more details
below) does not improve the situation when using this approach as we are
still going to be at least one frame behind the animation.

### `[email protected]` and higher

Thanks to introduction of [synchronous state updates in RN
0.82](facebook/react-native#52604), we can rely
fully on native mechanisms for handling the transition. Bottom accessory
only receives the final frame of the transition and thanks to
synchronous state updates, we can immediately recalculate the layout in
the Shadow Tree and update the Host Tree. This allows Core Animation
framework to make the transition smooth. Details of how we think this
works are available
[here](#3285 (comment)).

Unfortunately, when using `react-native`, the situation is a little bit
more complicated.

#### Text

Text component behaves differently to the native platform. During the
transition, it immediately adapts to the final frame size and then it is
stretched. In bare UIKit app, the text adapt to new frame size at the
end of the transition.

| `react-native` | `UIKit` |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/ea509fee-53bb-4300-a28d-3404525d47dd"
/> | <video
src="https://github.com/user-attachments/assets/17b2d3f8-5f04-406a-828c-504d040ad013"
/> |

This requires more investigation and potentially changes in
`react-native`.

#### Borders

`CoreAnimation` does not support non-uniform borders so `react-native`
handles them in a custom way that does not seem to be compatible with
the transition mechanism.

| non-uniform borders | uniform borders + **CA enabled** |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/e9ce53a9-bb4b-4465-a986-1a1f08791454"
/> | <video
src="https://github.com/user-attachments/assets/bcf029a4-764a-446c-82b6-91bfd42494c6"
/> |

This requires more investigation and potentially changes in
`react-native`.

#### Images

Similar problem (in a way it looks, not the exact mechanism of the bug)
happens when using images e.g. with `width: 100%`.


https://github.com/user-attachments/assets/1aa0b77a-7800-471f-bd38-ac3eed506b87

This requires more investigation and potentially changes in
`react-native`.

#### Mounting/unmounting views during transition

While state updates are performed synchronously, any changes to React
Element Tree in reaction to environment change are handled
asynchronously. We think that this is why the transition handled by
`CoreAnimation` breaks when trying to mount/unmount components on
environment change.


https://github.com/user-attachments/assets/ef0730db-386a-46be-8fcf-e0def3ca4097

Here, we try to remove the note icon. Unfortunately, the rest of the
layout does not adapt. You can also observe the text stretching as
mentioned 2 sections above.

In order to mitigate this issue, we use `double-rendering` approach,
which has been described in `Possible approaches` section.


https://github.com/user-attachments/assets/7d105e62-1f69-4886-845a-464addfa608b

## Changes

- add `BottomTabsAccessory` JS component and use it in `BottomTabs`,
- add `BottomTabsAccessoryComponentView`,
`BottomTabsAccessoryEventEmitter`,
`BottomTabsAccessoryComponentViewManager`,
- add `BottomAccessoryHelper` to handle size and environment changes,
- add `BottomTabsAccessoryShadowStateProxy` to synchronize state between
Host and ShadowTree,
- adapt `BottomTabsHost` to accept 2 types of children (`Screen` and
`Accessory`),
- add test screen.

## Test code and steps to reproduce

Run `Test3288`.

## Checklist

- [x] Included code example that can be used to test this change
- [x] Updated TS types
- [ ] Updated documentation: <!-- For adding new props to native-stack
-->
- [ ]
https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
- [ ]
https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
- [ ]
https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
- [ ]
https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
- [x] Ensured that CI passes

Author: kligarski

apps/src/tests/Test3288.tsx

@@ -0,0 +1,286 @@
+import React, {
+  createContext,
+  Dispatch,
+  SetStateAction,
+  useContext,
+  useState,
+} from 'react';
+
+import ConfigWrapperContext, {
+  type Configuration,
+  DEFAULT_GLOBAL_CONFIGURATION,
+} from '../shared/gamma/containers/bottom-tabs/ConfigWrapperContext';
+import {
+  BottomTabsContainer,
+  type TabConfiguration,
+} from '../shared/gamma/containers/bottom-tabs/BottomTabsContainer';
+import {
+  ColorValue,
+  Pressable,
+  PressableProps,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+} from 'react-native';
+import { SettingsPicker, SettingsSwitch } from '../shared';
+import Colors from '../shared/styling/Colors';
+import PressableWithFeedback from '../shared/PressableWithFeedback';
+import { TabBarMinimizeBehavior } from 'react-native-screens';
+import { BottomTabsAccessoryEnvironment } from 'react-native-screens/components/bottom-tabs/BottomTabsAccessory.types';
+import { NavigationContainer } from '@react-navigation/native';
+
+type BottomAccessoryConfig = {
+  shown: boolean;
+  backgroundColor: ColorValue;
+  shouldAdaptToEnvironment: boolean;
+  tabBarMinimizeBehavior: TabBarMinimizeBehavior;
+};
+
+type BottomAccessoryContextInterface = {
+  config: BottomAccessoryConfig;
+  setConfig: Dispatch<SetStateAction<BottomAccessoryConfig>>;
+};
+
+const DEFAULT_BOTTOM_ACCESSORY_CONFIG: BottomAccessoryConfig = {
+  shown: true,
+  backgroundColor: 'transparent',
+  shouldAdaptToEnvironment: true,
+  tabBarMinimizeBehavior: 'onScrollDown',
+};
+
+const BottomAccessoryContext =
+  createContext<BottomAccessoryContextInterface | null>(null);
+
+const useBottomAccessoryContext = () => {
+  const bottomAccessoryContext = useContext(BottomAccessoryContext);
+
+  if (!bottomAccessoryContext) {
+    throw new Error(
+      'useBottomAccessoryContext has to be used within <BottomAccessoryContext.Provider>',
+    );
+  }
+
+  return bottomAccessoryContext;
+};
+
+function Config() {
+  const { config, setConfig } = useBottomAccessoryContext();
+
+  return (
+    <ScrollView contentContainerStyle={{ padding: 16, gap: 5 }}>
+      <SettingsSwitch
+        label="shown"
+        value={config.shown}
+        onValueChange={value => setConfig({ ...config, shown: value })}
+      />
+      <SettingsPicker<string>
+        label="backgroundColor"
+        value={String(config.backgroundColor)}
+        onValueChange={value =>
+          setConfig({
+            ...config,
+            backgroundColor: value,
+          })
+        }
+        items={['transparent', Colors.NavyLightTransparent, Colors.BlueLight80]}
+      />
+      <SettingsSwitch
+        label="shouldAdaptToEnvironment"
+        value={config.shouldAdaptToEnvironment}
+        onValueChange={value =>
+          setConfig({ ...config, shouldAdaptToEnvironment: value })
+        }
+      />
+      <SettingsPicker<TabBarMinimizeBehavior>
+        label="tabBarMinimizeBehavior"
+        value={config.tabBarMinimizeBehavior}
+        onValueChange={value =>
+          setConfig({
+            ...config,
+            tabBarMinimizeBehavior: value,
+          })
+        }
+        items={['automatic', 'onScrollDown', 'onScrollUp', 'never']}
+      />
+    </ScrollView>
+  );
+}
+
+function TestScreen() {
+  return (
+    <ScrollView
+      contentContainerStyle={{
+        width: '100%',
+        height: 'auto',
+        gap: 15,
+        paddingHorizontal: 30,
+      }}>
+      {[...Array(50).keys()].map(index => (
+        <PressableWithFeedback
+          key={index + 1}
+          onPress={() => console.log(`Pressed #${index + 1}`)}
+          style={{
+            paddingVertical: 10,
+            paddingHorizontal: 20,
+          }}>
+          <Text>Pressable #{index + 1}</Text>
+        </PressableWithFeedback>
+      ))}
+    </ScrollView>
+  );
+}
+
+const TAB_CONFIGS: TabConfiguration[] = [
+  {
+    tabScreenProps: {
+      tabKey: 'Tab1',
+      title: 'Config',
+      icon: {
+        ios: {
+          type: 'sfSymbol',
+          name: 'gear',
+        },
+      },
+    },
+    component: Config,
+  },
+  {
+    tabScreenProps: {
+      tabKey: 'Tab2',
+      title: 'Test',
+      icon: {
+        ios: {
+          type: 'sfSymbol',
+          name: 'rectangle.stack',
+        },
+      },
+    },
+    component: TestScreen,
+  },
+];
+
+function getBottomAccessory(
+  environment: BottomTabsAccessoryEnvironment,
+  config: BottomAccessoryConfig,
+) {
+  const pressableStyle: PressableProps['style'] = ({ pressed }) => ({
+    shadowColor: '#000',
+    shadowOffset: {
+      width: 0.5,
+      height: 0.5,
+    },
+    shadowOpacity: pressed ? 0.9 : 0.0,
+    shadowRadius: 2,
+    transform: pressed ? [{ scale: 1.1 }] : [],
+  });
+  return (
+    <View
+      style={[
+        styles.container,
+        {
+          backgroundColor: config.backgroundColor,
+        },
+      ]}>
+      <View style={styles.left}>
+        <View style={styles.cover} />
+        <View style={styles.data}>
+          <Text style={styles.title} numberOfLines={1}>
+            Never Gonna Give You Up
+          </Text>
+          <Text style={styles.author}>Rick Astley</Text>
+        </View>
+      </View>
+
+      <View style={styles.right}>
+        {(environment === 'regular' || !config.shouldAdaptToEnvironment) && (
+          <Pressable
+            onPress={() => console.log('You know the rules and so do I')}
+            style={pressableStyle}>
+            <Text style={{ fontSize: 28 }}>♫</Text>
+          </Pressable>
+        )}
+
+        <Pressable
+          onPress={() => console.log("We're no strangers to love")}
+          style={pressableStyle}>
+          <Text style={{ fontSize: 30 }}>▶</Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+function Tabs() {
+  const [config, setConfig] = React.useState<Configuration>(
+    DEFAULT_GLOBAL_CONFIGURATION,
+  );
+
+  const { config: bottomAccessoryConfig } = useBottomAccessoryContext();
+
+  return (
+    <ConfigWrapperContext.Provider
+      value={{
+        config,
+        setConfig,
+      }}>
+      <BottomTabsContainer
+        tabConfigs={TAB_CONFIGS}
+        tabBarMinimizeBehavior={bottomAccessoryConfig.tabBarMinimizeBehavior}
+        bottomAccessory={
+          bottomAccessoryConfig.shown
+            ? environment =>
+                getBottomAccessory(environment, bottomAccessoryConfig)
+            : undefined
+        }
+      />
+    </ConfigWrapperContext.Provider>
+  );
+}
+
+function App() {
+  const [bottomAccessoryConfig, setBottomAccessoryConfig] =
+    useState<BottomAccessoryConfig>(DEFAULT_BOTTOM_ACCESSORY_CONFIG);
+
+  return (
+    <NavigationContainer>
+      <BottomAccessoryContext.Provider
+        value={{
+          config: bottomAccessoryConfig,
+          setConfig: setBottomAccessoryConfig,
+        }}>
+        <Tabs />
+      </BottomAccessoryContext.Provider>
+    </NavigationContainer>
+  );
+}
+
+export default App;
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    padding: 5,
+  },
+  left: {
+    flex: 1,
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 10,
+    marginLeft: 10,
+  },
+  cover: { backgroundColor: 'pink', width: 30, height: 30 },
+  data: { flex: 1, paddingRight: 5 },
+  title: { fontWeight: 'bold' },
+  author: { fontSize: 10, color: 'gray' },
+  right: {
+    flex: 0,
+    flexDirection: 'row-reverse',
+    alignItems: 'center',
+    gap: 12,
+    paddingRight: 10,
+  },
+});

apps/src/tests/index.ts

@@ -156,6 +156,7 @@ export { default as Test3248 } from './Test3248';
 export { default as Test3265 } from './Test3265';
 export { default as Test3271 } from './Test3271';
 export { default as Test3282 } from './Test3282';
+export { default as Test3288 } from './Test3288';
 export { default as Test3342 } from './Test3342';
 export { default as Test3346 } from './Test3346';
 export { default as Test3369 } from './Test3369';

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryComponentDescriptor.h

@@ -0,0 +1,34 @@
+#pragma once
+
+#include <react/debug/react_native_assert.h>
+#include <react/renderer/components/rnscreens/Props.h>
+#include <react/renderer/core/ConcreteComponentDescriptor.h>
+#include "RNSBottomTabsAccessoryShadowNode.h"
+
+namespace facebook::react {
+
+class RNSBottomTabsAccessoryComponentDescriptor final
+    : public ConcreteComponentDescriptor<RNSBottomTabsAccessoryShadowNode> {
+ public:
+  using ConcreteComponentDescriptor::ConcreteComponentDescriptor;
+
+  void adopt(ShadowNode &shadowNode) const override {
+    react_native_assert(
+        dynamic_cast<RNSBottomTabsAccessoryShadowNode *>(&shadowNode));
+    auto &bottomTabsAccessoryShadowNode =
+        static_cast<RNSBottomTabsAccessoryShadowNode &>(shadowNode);
+
+    auto state = std::static_pointer_cast<
+        const RNSBottomTabsAccessoryShadowNode::ConcreteState>(
+        shadowNode.getState());
+    auto stateData = state->getData();
+
+    if (stateData.frameSize.width != 0 && stateData.frameSize.height != 0) {
+      bottomTabsAccessoryShadowNode.setSize(stateData.frameSize);
+    }
+
+    ConcreteComponentDescriptor::adopt(shadowNode);
+  }
+};
+
+} // namespace facebook::react

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryShadowNode.cpp

@@ -0,0 +1,14 @@
+#include "RNSBottomTabsAccessoryShadowNode.h"
+
+namespace facebook::react {
+
+extern const char RNSBottomTabsAccessoryComponentName[] =
+    "RNSBottomTabsAccessory";
+
+Point RNSBottomTabsAccessoryShadowNode::getContentOriginOffset(
+    bool /*includeTransform*/) const {
+  auto stateData = getStateData();
+  return stateData.contentOffset;
+}
+
+} // namespace facebook::react

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryShadowNode.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include <jsi/jsi.h>
+#include <react/renderer/components/rnscreens/EventEmitters.h>
+#include <react/renderer/components/rnscreens/Props.h>
+#include <react/renderer/components/view/ConcreteViewShadowNode.h>
+#include "RNSBottomTabsAccessoryState.h"
+
+namespace facebook::react {
+
+JSI_EXPORT extern const char RNSBottomTabsAccessoryComponentName[];
+
+class JSI_EXPORT RNSBottomTabsAccessoryShadowNode final
+    : public ConcreteViewShadowNode<
+          RNSBottomTabsAccessoryComponentName,
+          RNSBottomTabsAccessoryProps,
+          RNSBottomTabsAccessoryEventEmitter,
+          RNSBottomTabsAccessoryState> {
+ public:
+  using ConcreteViewShadowNode::ConcreteViewShadowNode;
+  using StateData = ConcreteViewShadowNode::ConcreteStateData;
+
+  Point getContentOriginOffset(bool includeTransform) const override;
+};
+
+} // namespace facebook::react

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryState.h

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <react/renderer/graphics/Point.h>
+#include <react/renderer/graphics/Size.h>
+
+namespace facebook::react {
+
+class JSI_EXPORT RNSBottomTabsAccessoryState final {
+ public:
+  using Shared = std::shared_ptr<const RNSBottomTabsAccessoryState>;
+
+  RNSBottomTabsAccessoryState() {};
+  RNSBottomTabsAccessoryState(Size frameSize_, Point contentOffset_)
+      : frameSize(frameSize_), contentOffset(contentOffset_) {};
+
+  const Size frameSize{};
+  const Point contentOffset{};
+};
+
+} // namespace facebook::react