react-native-navigation 8.8.5 → 8.8.6-snapshot.2571

package/android/src/main/java/com/reactnativenavigation/viewcontrollers/bottomtabs/BottomTabsController.java

@@ -13,9 +13,11 @@ import android.view.ViewGroup;
 import androidx.annotation.NonNull;
 import androidx.annotation.RestrictTo;
 import androidx.coordinatorlayout.widget.CoordinatorLayout;
-import androidx.core.graphics.Insets;
+import androidx.core.view.ViewCompat;
 import androidx.core.view.WindowInsetsCompat;
 
+import android.util.Log;
+
 import com.aurelhubert.ahbottomnavigation.AHBottomNavigation;
 import com.aurelhubert.ahbottomnavigation.AHBottomNavigationItem;
 import com.reactnativenavigation.options.BottomTabOptions;
@@ -25,6 +27,7 @@ import com.reactnativenavigation.react.CommandListener;
 import com.reactnativenavigation.react.CommandListenerAdapter;
 import com.reactnativenavigation.react.events.EventEmitter;
 import com.reactnativenavigation.utils.ImageLoader;
+import com.reactnativenavigation.utils.SystemUiUtils;
 import com.reactnativenavigation.viewcontrollers.bottomtabs.attacher.BottomTabsAttacher;
 import com.reactnativenavigation.viewcontrollers.child.ChildControllersRegistry;
 import com.reactnativenavigation.viewcontrollers.parent.ParentController;
@@ -34,7 +37,9 @@ import com.reactnativenavigation.viewcontrollers.viewcontroller.ViewController;
 import com.reactnativenavigation.views.bottomtabs.BottomTabs;
 import com.reactnativenavigation.views.bottomtabs.BottomTabsContainer;
 import com.reactnativenavigation.views.bottomtabs.BottomTabsLayout;
+import com.reactnativenavigation.views.bottomtabs.CustomBottomTabItemView;
 
+import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Deque;
 import java.util.LinkedList;
@@ -42,6 +47,8 @@ import java.util.List;
 
 public class BottomTabsController extends ParentController<BottomTabsLayout> implements AHBottomNavigation.OnTabSelectedListener, TabSelector {
 
+    private static final String LOG_TAG = "BottomTabsController";
+
     private BottomTabsContainer bottomTabsContainer;
     private BottomTabs bottomTabs;
     private final Deque<Integer> selectionStack;
@@ -51,6 +58,7 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
     private final BottomTabsAttacher tabsAttacher;
     private final BottomTabsPresenter presenter;
     private final BottomTabPresenter tabPresenter;
+    private boolean useCustomItemViews;
 
     public BottomTabsAnimator getAnimator() {
         return presenter.getAnimator();
@@ -105,13 +113,59 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
         bottomTabs.setOnTabSelectedListener(this);
         root.addBottomTabsContainer(bottomTabsContainer);
 
+        useCustomItemViews = resolveUseCustomItemViews();
+        tabPresenter.setUseCustomItemViews(useCustomItemViews);
+
         bottomTabs.addItems(createTabs());
+
+        if (useCustomItemViews) {
+            attachCustomItemViewsToCells();
+        }
+
         setInitialTab(resolveCurrentOptions);
         tabsAttacher.attach();
 
         return root;
     }
 
+    private boolean resolveUseCustomItemViews() {
+        if (tabs.isEmpty()) return false;
+        int withComponent = 0;
+        for (ViewController<?> tab : tabs) {
+            BottomTabOptions options = tab.resolveCurrentOptions(initialOptions).bottomTabOptions;
+            if (options.component.hasValue()) withComponent++;
+        }
+        if (withComponent == 0) return false;
+        if (withComponent != tabs.size()) {
+            Log.w(LOG_TAG,
+                    "Mixed bottomTab.component usage detected (" + withComponent + " of "
+                            + tabs.size() + " tabs). All tabs must declare a component or none — "
+                            + "falling back to native rendering for all tabs.");
+            return false;
+        }
+        return true;
+    }
+
+    private void attachCustomItemViewsToCells() {
+        List<CustomBottomTabItemView> overlays = new ArrayList<>();
+        int initialIndex = bottomTabs.getCurrentItem();
+        for (int i = 0; i < tabs.size(); i++) {
+            BottomTabOptions options = tabs.get(i).resolveCurrentOptions(initialOptions).bottomTabOptions;
+            String componentId = options.component.componentId.get(tabs.get(i).getId() + "_tab_" + i);
+            String componentName = options.component.name.get();
+            String badge = options.badge.hasValue() ? options.badge.get() : null;
+            CustomBottomTabItemView itemView = new CustomBottomTabItemView(
+                    getActivity(),
+                    componentId,
+                    componentName,
+                    i,
+                    i == initialIndex,
+                    badge);
+            overlays.add(itemView);
+        }
+        bottomTabs.setCustomItemViews(overlays);
+    }
+
     private void setInitialTab(Options resolveCurrentOptions) {
         int initialTabIndex = 0;
         if (resolveCurrentOptions.bottomTabsOptions.currentTabId.hasValue())
@@ -120,6 +174,9 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
             initialTabIndex = resolveCurrentOptions.bottomTabsOptions.currentTabIndex.get();
         }
         bottomTabs.setCurrentItem(initialTabIndex, false);
+        if (useCustomItemViews) {
+            bottomTabs.onCustomItemViewSelectionChanged(initialTabIndex);
+        }
     }
 
     @NonNull
@@ -156,6 +213,7 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
     public void applyChildOptions(Options options, ViewController<?> child) {
         super.applyChildOptions(options, child);
         presenter.applyChildOptions(resolveCurrentOptions(), child);
+        onNavigationBarOptionsChanged(options);
         performOnParentController(parent -> parent.applyChildOptions(
                 this.options.copy()
                         .clearBottomTabsOptions()
@@ -170,6 +228,7 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
         super.mergeChildOptions(options, child);
         presenter.mergeChildOptions(options, child);
         tabPresenter.mergeChildOptions(options, child);
+        onNavigationBarOptionsChanged(options);
         performOnParentController(parent -> parent.mergeChildOptions(options.copy().clearBottomTabsOptions(), child));
     }
 
@@ -291,6 +350,9 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
         ViewController<?> previouslyVisible = getCurrentChild();
         bottomTabs.setCurrentItem(newIndex, false);
         getCurrentChild().onSelected(previouslyVisible);
+        if (useCustomItemViews) {
+            bottomTabs.onCustomItemViewSelectionChanged(newIndex);
+        }
     }
 
     private void saveTabSelection(int newIndex, boolean enableSelectionHistory) {
@@ -316,14 +378,23 @@ public class BottomTabsController extends ParentController<BottomTabsLayout> imp
 
     @Override
     protected WindowInsetsCompat onApplyWindowInsets(View view, WindowInsetsCompat insets) {
-        Insets sysInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars());
-        Insets imeInsets = insets.getInsets(WindowInsetsCompat.Type.ime());
-
-        int bottomInset = (imeInsets.bottom > 0) ? 0 : sysInsets.bottom;
-        view.setPaddingRelative(0, 0, 0, bottomInset);
+        boolean drawBehindNavBar = resolveCurrentOptions().navigationBar.isDrawBehindAndVisible();
+        view.setPaddingRelative(0, 0, 0, SystemUiUtils.getBottomTabsSystemBarPadding(insets, drawBehindNavBar));
         return insets;
     }
 
+    private void onNavigationBarOptionsChanged(Options options) {
+        if (!options.navigationBar.hasAnyValue()) return;
+        refreshNavigationBarInsets();
+    }
+
+    private void refreshNavigationBarInsets() {
+        if (getView() != null) {
+            applyBottomInset();
+            ViewCompat.requestApplyInsets(getView());
+        }
+    }
+
     @RestrictTo(RestrictTo.Scope.TESTS)
     public BottomTabs getBottomTabs() {
         return bottomTabs;

package/android/src/main/java/com/reactnativenavigation/viewcontrollers/bottomtabs/BottomTabsPresenter.kt

@@ -393,6 +393,7 @@ class BottomTabsPresenter(
     private fun syncNavigationBarColor(options: Options, tabsColor: Int) {
         val resolved = options.copy().withDefaultOptions(defaultOptions)
         if (resolved.navigationBar.backgroundColor.hasValue()) return
+        if (resolved.navigationBar.shouldDrawBehind()) return
         val window = (bottomTabsContainer.context as? Activity)?.window ?: return
         SystemUiUtils.setNavigationBarBackgroundColor(window, tabsColor, isColorLight(tabsColor))
     }

package/android/src/main/java/com/reactnativenavigation/viewcontrollers/component/ComponentViewController.java

@@ -173,11 +173,8 @@ public class ComponentViewController extends ChildController<ComponentLayout> {
                 insets.getInsets(WindowInsetsCompat.Type.navigationBars()).top -
                 systemBarsInsets.top;
 
-        int navBarBottom = insets.getInsets(WindowInsetsCompat.Type.navigationBars()).bottom;
-        int imeBottom = insets.getInsets(WindowInsetsCompat.Type.ime()).bottom;
-        int systemWindowInsetBottom = SystemUiUtils.isEdgeToEdgeActive()
-                ? Math.max(imeBottom, navBarBottom)
-                : imeBottom;
+        boolean drawBehindNavBar = resolveCurrentOptions(presenter.defaultOptions).navigationBar.isDrawBehindAndVisible();
+        int systemWindowInsetBottom = SystemUiUtils.getContentBottomSystemBarInset(insets, drawBehindNavBar);
 
         WindowInsetsCompat finalInsets = new WindowInsetsCompat.Builder()
                 .setInsets(WindowInsetsCompat.Type.systemBars() | WindowInsetsCompat.Type.ime(),

package/android/src/main/java/com/reactnativenavigation/viewcontrollers/viewcontroller/Presenter.java

@@ -11,6 +11,8 @@ import android.view.View;
 import android.view.ViewGroup;
 import android.view.ViewGroup.MarginLayoutParams;
 
+import androidx.core.view.ViewCompat;
+
 import com.reactnativenavigation.options.NavigationBarOptions;
 import com.reactnativenavigation.options.Options;
 import com.reactnativenavigation.options.OrientationOptions;
@@ -114,16 +116,16 @@ public class Presenter {
 
     private void applyNavigationBarOptions(NavigationBarOptions options) {
         applyNavigationBarVisibility(options);
-        setNavigationBarBackgroundColor(options);
+        applyNavigationBarBackground(options);
+        refreshNavigationBarInsets();
     }
 
     private void mergeNavigationBarOptions(NavigationBarOptions options) {
-        mergeNavigationBarVisibility(options);
-        setNavigationBarBackgroundColor(options);
-    }
-
-    private void mergeNavigationBarVisibility(NavigationBarOptions options) {
-        if (options.isVisible.hasValue()) applyNavigationBarOptions(options);
+        if (options.isVisible.hasValue()) {
+            applyNavigationBarVisibility(options);
+        }
+        applyNavigationBarBackground(options);
+        refreshNavigationBarInsets();
     }
 
     private void applyNavigationBarVisibility(NavigationBarOptions options) {
@@ -136,20 +138,38 @@ public class Presenter {
         }
     }
 
-    private void setNavigationBarBackgroundColor(NavigationBarOptions navigationBar) {
+    private void applyNavigationBarBackground(NavigationBarOptions navigationBar) {
         if (activity == null) return;
         int defaultColor = SystemUiUtils.getDefaultNavBarColor();
-        if (navigationBar.backgroundColor.canApplyValue()) {
-            int color = navigationBar.backgroundColor.get(defaultColor);
-            SystemUiUtils.setNavigationBarBackgroundColor(activity.getWindow(), color, isColorLight(color));
+        int color;
+        boolean hideOverlay;
+        if (navigationBar.isDrawBehindAndVisible()) {
+            if (navigationBar.backgroundColor.canApplyValue()) {
+                color = navigationBar.backgroundColor.get(defaultColor);
+                hideOverlay = Color.alpha(color) == 0;
+            } else {
+                color = Color.TRANSPARENT;
+                hideOverlay = true;
+            }
         } else {
-            SystemUiUtils.setNavigationBarBackgroundColor(activity.getWindow(), defaultColor, isColorLight(defaultColor));
+            hideOverlay = false;
+            color = navigationBar.backgroundColor.canApplyValue()
+                    ? navigationBar.backgroundColor.get(defaultColor)
+                    : defaultColor;
         }
+        SystemUiUtils.setNavigationBarBackgroundColor(
+                activity.getWindow(), color, isColorLight(color), hideOverlay);
+    }
+
+    private void refreshNavigationBarInsets() {
+        if (activity == null) return;
+        ViewCompat.requestApplyInsets(activity.getWindow().getDecorView());
     }
 
     public void onConfigurationChanged(ViewController controller, Options options) {
         Options withDefault = options.withDefaultOptions(defaultOptions);
-        setNavigationBarBackgroundColor(withDefault.navigationBar);
+        applyNavigationBarBackground(withDefault.navigationBar);
+        refreshNavigationBarInsets();
         StatusBarPresenter.instance.onConfigurationChanged(withDefault.statusBar);
         applyBackgroundColor(controller, withDefault);
     }

package/android/src/main/java/com/reactnativenavigation/views/bottomtabs/BottomTabs.java

@@ -8,6 +8,8 @@ import android.content.Context;
 import android.graphics.Color;
 import android.graphics.drawable.Drawable;
 import android.view.View;
+import android.view.ViewGroup;
+import android.widget.FrameLayout;
 import android.widget.LinearLayout;
 
 import androidx.annotation.IntRange;
@@ -25,6 +27,19 @@ public class BottomTabs extends AHBottomNavigation {
     private boolean itemsCreationEnabled = true;
     private boolean shouldCreateItems = true;
     private List<Runnable> onItemCreationEnabled = new ArrayList<>();
+    private final List<CustomBottomTabItemView> customItemViews = new ArrayList<>();
+    private boolean externalCustomItemViewHost = false;
+
+    /**
+     * When enabled, this view stops re-parenting custom React tab item views
+     * into its native cells on every layout pass — the caller assumes full
+     * ownership of where those item views live in the view tree (used by
+     * the customRow floating-row implementation). Existing behavior is
+     * unchanged when this remains {@code false} (the default).
+     */
+    public void setExternalCustomItemViewHost(boolean enabled) {
+        this.externalCustomItemViewHost = enabled;
+    }
 
     public BottomTabs(Context context) {
         super(context);
@@ -131,6 +146,67 @@ public class BottomTabs extends AHBottomNavigation {
         if (tabsContainer != null) tabsContainer.setLayoutDirection(direction.get());
     }
 
+    /**
+     * Replace the visual content of every tab cell with the provided custom
+     * views. The custom view is attached as a child of the AHBottomNavigation
+     * cell view so taps continue to be handled by the native cell. Pass an
+     * empty list to remove all overlays.
+     */
+    public void setCustomItemViews(List<CustomBottomTabItemView> customViews) {
+        clearCustomItemViews();
+        if (customViews == null || customViews.isEmpty()) return;
+
+        customItemViews.addAll(customViews);
+        attachCustomItemViews();
+    }
+
+    public void onCustomItemViewSelectionChanged(int selectedIndex) {
+        for (int i = 0; i < customItemViews.size(); i++) {
+            customItemViews.get(i).setItemSelected(i == selectedIndex);
+        }
+    }
+
+    public CustomBottomTabItemView getCustomItemView(int index) {
+        if (index < 0 || index >= customItemViews.size()) return null;
+        return customItemViews.get(index);
+    }
+
+    public boolean hasCustomItemViews() {
+        return !customItemViews.isEmpty();
+    }
+
+    private void clearCustomItemViews() {
+        for (CustomBottomTabItemView view : customItemViews) {
+            ViewGroup parent = (ViewGroup) view.getParent();
+            if (parent != null) parent.removeView(view);
+        }
+        customItemViews.clear();
+    }
+
+    private void attachCustomItemViews() {
+        if (externalCustomItemViewHost) return;
+        for (int i = 0; i < customItemViews.size(); i++) {
+            View cell = getViewAtPosition(i);
+            if (!(cell instanceof ViewGroup)) continue;
+            CustomBottomTabItemView itemView = customItemViews.get(i);
+            ViewGroup parent = (ViewGroup) itemView.getParent();
+            if (parent != null && parent != cell) parent.removeView(itemView);
+            if (itemView.getParent() == null) {
+                ((ViewGroup) cell).addView(itemView, new FrameLayout.LayoutParams(
+                        FrameLayout.LayoutParams.MATCH_PARENT,
+                        FrameLayout.LayoutParams.MATCH_PARENT));
+            }
+        }
+    }
+
+    @Override
+    protected void onLayout(boolean changed, int l, int t, int r, int b) {
+        super.onLayout(changed, l, t, r, b);
+        if (changed && !customItemViews.isEmpty()) {
+            attachCustomItemViews();
+        }
+    }
+
     private boolean hasItemsAndIsMeasured(int w, int h, int oldw, int oldh) {
         return w != 0 && h != 0 && (w != oldw || h != oldh) && getItemsCount() > 0;
     }

package/android/src/main/java/com/reactnativenavigation/views/bottomtabs/CustomBottomTabItemView.kt

@@ -0,0 +1,73 @@
+package com.reactnativenavigation.views.bottomtabs
+
+import android.annotation.SuppressLint
+import android.content.Context
+import android.os.Bundle
+import android.view.MotionEvent
+import android.widget.FrameLayout
+import com.reactnativenavigation.react.ReactView
+
+/**
+ * Hosts a [ReactView] that renders a user-supplied React component as a
+ * bottom tab item. The view sits on top of the native AHBottomNavigation tab
+ * cell and forwards touches through to the underlying cell so native
+ * selection, ripple and `selectTabOnPress: false` keep working.
+ *
+ * The hosted component receives the following props at creation:
+ * `componentId`, `tabIndex`, `selected`, `badge`. Selection updates are
+ * pushed via [setSelected]; badge updates via [setBadge].
+ */
+@SuppressLint("ViewConstructor")
+class CustomBottomTabItemView(
+    context: Context,
+    val componentId: String,
+    val componentName: String,
+    val tabIndex: Int,
+    initialSelected: Boolean,
+    initialBadge: String?
+) : FrameLayout(context) {
+
+    val reactView: ReactView = ReactView(context, componentId, componentName)
+    private var isCurrentlySelected: Boolean = initialSelected
+    private var badge: String? = initialBadge
+
+    init {
+        addView(reactView)
+        reactView.isClickable = false
+        reactView.isFocusable = false
+        isClickable = false
+        isFocusable = false
+        pushProps()
+    }
+
+    /**
+     * Touches must always reach the underlying AHBottomNavigation cell so
+     * that native selection, ripple, accessibility focus and
+     * `selectTabOnPress: false` keep working. Returning false here makes
+     * this view completely transparent to touch input and prevents any
+     * `Touchable*` rendered inside the React tree from swallowing taps.
+     */
+    override fun dispatchTouchEvent(ev: MotionEvent?): Boolean = false
+
+    fun setItemSelected(selected: Boolean) {
+        if (this.isCurrentlySelected == selected) return
+        this.isCurrentlySelected = selected
+        pushProps()
+    }
+
+    fun setBadge(badge: String?) {
+        if (this.badge == badge) return
+        this.badge = badge
+        pushProps()
+    }
+
+    private fun pushProps() {
+        val bundle = Bundle().apply {
+            putString("componentId", componentId)
+            putInt("tabIndex", tabIndex)
+            putBoolean("selected", isCurrentlySelected)
+            if (badge != null) putString("badge", badge)
+        }
+        reactView.setProps(bundle)
+    }
+}

package/android/src/test/java/com/reactnativenavigation/presentation/PresenterTest.java

@@ -96,4 +96,18 @@ public class PresenterTest extends BaseTest {
         verify(parentView).setPadding(2,1,4,3);
     }
 
+    @Test
+    public void applyNavigationBarDrawBehind_usesTransparentOverlay() {
+        mockSystemUiUtils(0, 0, (mockedStatic) -> {
+            ViewGroup spy = spy(new FrameLayout(activity));
+            Mockito.when(controller.getView()).thenReturn(spy);
+            Mockito.when(controller.resolveCurrentOptions()).thenReturn(Options.EMPTY);
+            Options options = new Options();
+            options.navigationBar.drawBehind = new Bool(true);
+            uut.applyOptions(controller, options);
+            mockedStatic.verify(() -> SystemUiUtils.setNavigationBarBackgroundColor(
+                    any(), eq(android.graphics.Color.TRANSPARENT), eq(false), eq(true)), times(1));
+        });
+    }
+
 }

package/android/src/test/java/com/reactnativenavigation/utils/SystemUiUtilsTest.kt

@@ -1,16 +1,28 @@
 package com.reactnativenavigation.utils
 
 import android.graphics.Color
+import android.graphics.drawable.ColorDrawable
+import android.view.View
 import android.view.Window
+import android.widget.FrameLayout
+import androidx.appcompat.app.AppCompatActivity
 import com.reactnativenavigation.BaseRobolectricTest
 import com.reactnativenavigation.utils.SystemUiUtils.STATUS_BAR_HEIGHT_TRANSLUCENCY
+import org.assertj.core.api.Java6Assertions.assertThat
+import org.junit.After
 import org.junit.Test
 import org.mockito.Mockito
 import org.mockito.kotlin.verify
+import org.robolectric.Robolectric
 import kotlin.math.ceil
 
 class SystemUiUtilsTest : BaseRobolectricTest() {
 
+    @After
+    fun afterEach() {
+        SystemUiUtils.tearDown()
+    }
+
     @Test
     fun `setStatusBarColor - should change color considering alpha`() {
         val window = Mockito.mock(Window::class.java)
@@ -24,4 +36,55 @@ class SystemUiUtilsTest : BaseRobolectricTest() {
 
         verify(window).statusBarColor = Color.argb(ceil(STATUS_BAR_HEIGHT_TRANSLUCENCY*255).toInt(), 22, 255, 255)
     }
-}
+
+    @Test
+    fun `setupSystemBarBackgrounds - initializes navigation bar background from resolved color`() {
+        val activity = Robolectric.setupActivity(AppCompatActivity::class.java)
+        val contentLayout = FrameLayout(activity)
+        val initialColor = Color.RED
+        SystemUiUtils.setNavigationBarBackgroundColor(activity.window, initialColor, false)
+
+        SystemUiUtils.setupSystemBarBackgrounds(activity, contentLayout)
+
+        assertThat(getBackgroundColor(getNavigationBarBackground(contentLayout))).isEqualTo(initialColor)
+    }
+
+    @Test
+    fun `setNavigationBarBackgroundColor - updates view and window color when edge-to-edge is inactive`() {
+        val activity = Robolectric.setupActivity(AppCompatActivity::class.java)
+        val contentLayout = FrameLayout(activity)
+        @Suppress("DEPRECATION")
+        activity.window.navigationBarColor = Color.BLACK
+        SystemUiUtils.setupSystemBarBackgrounds(activity, contentLayout)
+
+        SystemUiUtils.setNavigationBarBackgroundColor(activity.window, Color.WHITE, true)
+
+        assertThat(getBackgroundColor(getNavigationBarBackground(contentLayout))).isEqualTo(Color.WHITE)
+        assertThat(activity.window.decorView.systemUiVisibility and View.SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR)
+            .isEqualTo(View.SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR)
+    }
+
+    @Test
+    fun `setNavigationBarBackgroundColor - updates view and icon appearance when edge-to-edge is active`() {
+        val activity = Robolectric.setupActivity(AppCompatActivity::class.java)
+        val contentLayout = FrameLayout(activity)
+        val initialColor = Color.RED
+        SystemUiUtils.setNavigationBarBackgroundColor(activity.window, initialColor, false)
+        SystemUiUtils.setupSystemBarBackgrounds(activity, contentLayout)
+        SystemUiUtils.activateEdgeToEdge()
+
+        SystemUiUtils.setNavigationBarBackgroundColor(activity.window, Color.WHITE, true)
+
+        assertThat(getBackgroundColor(getNavigationBarBackground(contentLayout))).isEqualTo(Color.WHITE)
+        assertThat(activity.window.decorView.systemUiVisibility and View.SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR)
+            .isEqualTo(View.SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR)
+    }
+
+    private fun getNavigationBarBackground(contentLayout: FrameLayout): View {
+        return contentLayout.getChildAt(contentLayout.childCount - 1)
+    }
+
+    private fun getBackgroundColor(view: View): Int {
+        return (view.background as ColorDrawable).color
+    }
+}

package/ios/ARCHITECTURE.md

@@ -28,6 +28,11 @@ Base class that user's AppDelegate must extend. Handles React Native and navigat
 - Creates `RCTRootViewFactory` and `ReactHost`
 - Calls `[ReactNativeNavigation bootstrapWithHost:]` to initialize navigation
 - Handles RN version differences (0.77, 0.78, 0.79+) via compile-time macros
+- **Deep linking plumbing**:
+  - Implements `application:openURL:options:` and `application:continueUserActivity:restorationHandler:`; both call `-dispatchDeepLinkURL:`.
+  - `-dispatchDeepLinkURL:` posts `RCTOpenURLNotification` directly if the React runtime is ready, otherwise enqueues the URL.
+  - Observes `RCTContentDidAppearNotification` (the Fabric/bridgeless signal) to flush the queue. This solves the cold-start race where URLs (push notifications, OS link launches) arrive before `RCTLinkingManager` is listening.
+  - Subclasses can call `-dispatchDeepLinkURL:` manually from notification delegates or any other URL source; the queueing behavior is reused automatically.
 
 ### ReactNativeNavigation Bootstrap
 **File**: `ReactNativeNavigation.h/mm`

package/ios/BottomTabPresenter.h

@@ -4,6 +4,13 @@
 
 @property(nonatomic, strong, readonly) RNNTabBarItemCreator *tabCreator;
 
+/**
+ * When YES, tabs whose options declare `bottomTab.component` skip native
+ * icon/text/sfSymbol/role application. The accompanying
+ * `RNNCustomTabBarItemView` is responsible for visual rendering of the tab.
+ */
+@property(nonatomic, assign) BOOL useCustomItemViews;
+
 - (instancetype)initWithDefaultOptions:(RNNNavigationOptions *)defaultOptions
                             tabCreator:(RNNTabBarItemCreator *)tabCreator;
 

package/ios/BottomTabPresenter.mm

@@ -36,10 +36,37 @@
 
 - (void)createTabBarItem:(UIViewController *)child
         bottomTabOptions:(RNNBottomTabOptions *)bottomTabOptions {
+    if (_useCustomItemViews && bottomTabOptions.component.name.hasValue) {
+        UITabBarItem *blankItem = [self createBlankTabBarItem:child
+                                             bottomTabOptions:bottomTabOptions];
+        if (blankItem != child.tabBarItem) {
+            child.tabBarItem = blankItem;
+        }
+        return;
+    }
+
     UITabBarItem *updatedItem = [_tabCreator createTabBarItem:bottomTabOptions mergeItem:child.tabBarItem];
     if (updatedItem != child.tabBarItem) {
         child.tabBarItem = updatedItem;
     }
 }
 
+// Builds a truly blank `UITabBarItem` (nil image, nil title). When custom
+// item views are active, `RNNBottomTabsController` hides the native tab bar
+// visuals and renders the custom row on top. The bar item still needs to
+// exist so that `UITabBarController` reserves the right number of slots and
+// the bottom safe-area inset.
+- (UITabBarItem *)createBlankTabBarItem:(UIViewController *)child
+                       bottomTabOptions:(RNNBottomTabOptions *)bottomTabOptions {
+    UITabBarItem *item = child.tabBarItem ?: [UITabBarItem new];
+    item.image = nil;
+    item.selectedImage = nil;
+    item.title = nil;
+    item.tag = bottomTabOptions.tag;
+    item.accessibilityIdentifier = [bottomTabOptions.testID withDefault:nil];
+    item.accessibilityLabel = [bottomTabOptions.accessibilityLabel withDefault:nil];
+    item.imageInsets = UIEdgeInsetsZero;
+    return item;
+}
+
 @end

package/ios/RNNAppDelegate.h

@@ -56,4 +56,20 @@
 @property(nonatomic) BOOL bridgelessEnabled;
 #endif
 
+/**
+ * Dispatch a deep link URL through React Native's Linking module so JS
+ * subscribers (including RNN's built-in deep linking framework) receive it.
+ *
+ * Safe to call before the JS bridge is ready: URLs that arrive early
+ * (e.g. cold-start notification taps) are queued natively and flushed
+ * automatically once Fabric/React content first appears.
+ *
+ * Custom-scheme and universal-link openings dispatched by the OS are
+ * forwarded through this method automatically; call it manually only
+ * when your app receives a deep link from a source RNN can't intercept
+ * (e.g. a custom `UNUserNotificationCenterDelegate`, a third-party push
+ * SDK callback, etc.).
+ */
+- (void)dispatchDeepLinkURL:(NSURL *)url;
+
 @end