fix(android): Make overlay container properly pass through touches when interceptTouchOutside is false

[odeyatwi]

Description

Fixes Android overlay touch passthrough when interceptTouchOutside: false by creating a custom OverlayContainer that properly checks child overlays and doesn't consume touch events.

Issue

Closes #4953
Closes #7674

Root Cause

The problem was in Navigator.java where overlaysLayout (a standard CoordinatorLayout) was added on top of all content (z-index 2). Even though OverlayTouchDelegate correctly checked the interceptTouchOutside flag and returned false from onInterceptTouchEvent(), the parent overlaysLayout container was still consuming touch events at the ViewGroup dispatch level before they could fall through to the rootLayout below.

In Android's touch event system, ViewGroups higher in z-order receive touches first, and returning false from onInterceptTouchEvent() only passes touches to children within that ViewGroup, not to views below it in the hierarchy.

Solution

Created OverlayContainer.kt - a custom CoordinatorLayout that:

1. Overrides onInterceptTouchEvent() to iterate through child ComponentLayouts
2. Delegates to each child's onInterceptTouchEvent() which uses OverlayTouchDelegate
3. Returns false when no overlay wants to intercept (respecting interceptTouchOutside: false)
4. Overrides dispatchTouchEvent() to return false for ACTION_DOWN when not intercepting
5. This allows touches to fall through to the rootLayout below in the z-order

Updated Navigator.java to use OverlayContainer instead of standard CoordinatorLayout for overlaysLayout.

Changes

• Added: android/src/main/java/com/reactnativenavigation/views/overlay/OverlayContainer.kt
• Modified: android/src/main/java/com/reactnativenavigation/viewcontrollers/navigator/Navigator.java
• Added: android/src/androidTest/java/com/reactnativenavigation/views/overlay/OverlayContainerTest.kt
• Updated: website/docs/api/options-overlay.mdx

Testing

• Unit tests added (OverlayContainerTest.kt)
• Tests cover single overlay, multiple overlays, and edge cases
• Playground app testing (requires maintainer setup)
• Manual testing on Android devices (requires maintainer)

Platform

• Android (fixed)
• iOS (not affected - already works correctly)

Checklist

• Code follows project style guidelines (Kotlin + Java)
• Added comprehensive unit tests
• Updated documentation
• Commit message follows conventional commits
• Preserves existing behavior when interceptTouchOutside: true
• Uses existing OverlayTouchDelegate logic (no changes to touch detection)

Made with Cursor