react-native-navigation 8.7.4 → 8.7.5-snapshot.2299

package/android/ARCHITECTURE.md

@@ -0,0 +1,458 @@
+# Android Native Architecture
+
+The Android implementation provides native navigation using Views and ViewGroups (not Fragments), coordinated through a TurboModule that receives commands from JavaScript.
+
+## App Integration
+
+### NavigationApplication
+**File**: `NavigationApplication.java`
+
+Abstract Application class that user's MainApplication must extend:
+
+```kotlin
+// MainApplication.kt - User extends NavigationApplication
+class MainApplication : NavigationApplication() {
+    override val reactNativeHost: ReactNativeHost
+        get() = NavigationReactNativeHost(this) // Must use NavigationReactNativeHost
+}
+```
+
+**What NavigationApplication does:**
+- Initializes SoLoader
+- Provides `ReactGateway` singleton for React lifecycle
+- Offers `registerExternalComponent()` for native screens
+
+### NavigationActivity
+**File**: `NavigationActivity.java`
+
+Base Activity that user's MainActivity must extend:
+
+```kotlin
+// MainActivity.kt - User extends NavigationActivity
+class MainActivity : NavigationActivity() {
+    // No getMainComponentName() needed - navigation handles root
+}
+```
+
+**What NavigationActivity does:**
+- Creates `Navigator` with root, modal, and overlay layouts
+- Manages back press via `OnBackPressedCallback`
+- Coordinates React lifecycle with activity lifecycle
+
+### NavigationReactNativeHost
+**File**: `react/NavigationReactNativeHost.kt`
+
+Custom ReactNativeHost that integrates with navigation:
+- Used instead of `DefaultReactNativeHost`
+- Provides proper module registration for navigation
+
+### Autolink Script (`npx rnn-link`)
+
+The `autolink/postlink/postLinkAndroid.js` script automates setup:
+
+| Linker | What it does |
+|--------|--------------|
+| `ApplicationLinker` | Changes MainApplication to extend `NavigationApplication`, uses `NavigationReactNativeHost`, removes SoLoader.init() |
+| `ActivityLinker` | Changes MainActivity to extend `NavigationActivity`, removes `getMainComponentName()` |
+| `GradleLinker` | Updates build.gradle if needed |
+
+**ApplicationLinker transformations:**
+- `class MainApplication : Application(), ReactApplication` → `class MainApplication : NavigationApplication()`
+- `DefaultReactNativeHost(this)` → `NavigationReactNativeHost(this)`
+- Removes `SoLoader.init()` (NavigationApplication handles it)
+- Removes new architecture entry point load block
+
+**ActivityLinker transformations:**
+- `class MainActivity : ReactActivity()` → `class MainActivity : NavigationActivity()`
+- Removes `getMainComponentName()` override
+- Removes `createReactActivityDelegate()` override
+
+## Directory Structure
+
+```
+android/src/main/java/com/reactnativenavigation/
+├── NavigationActivity.java       # Main Activity entry point
+├── NavigationApplication.java    # Application class
+├── NavigationPackage.kt          # React package registration
+├── react/                        # React bridge layer
+│   ├── NavigationTurboModule.kt  # TurboModule implementation
+│   ├── ReactGateway.java         # React lifecycle management
+│   └── events/
+│       └── EventEmitter.java     # Event emission to JS
+├── options/                      # Options parsing and factories
+│   ├── LayoutFactory.java        # Creates ViewControllers from layout nodes
+│   └── Options.java              # Options model
+├── viewcontrollers/              # ViewController hierarchy
+│   ├── ViewController.java       # Base class
+│   ├── ChildController.java      # With presenter support
+│   ├── ParentController.java     # Container controllers
+│   ├── stack/                    # Stack navigation
+│   ├── bottomtabs/               # Bottom tabs
+│   ├── toptabs/                  # Top tabs (lowercase)
+│   ├── sidemenu/                 # Side menu/drawer
+│   ├── modal/                    # Modal management
+│   └── externalcomponent/        # Native component support
+├── views/                        # UI View implementations
+├── utils/                        # Utilities
+└── hierarchy/                    # Root layout management
+```
+
+## Bridge Architecture
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                 JavaScript (TurboModule)                   │
+└─────────────────────────┬──────────────────────────────────┘
+                          │
+┌─────────────────────────▼──────────────────────────────────┐
+│  NavigationTurboModule.kt                                   │
+│  - setRoot, push, pop, showModal, dismissModal, etc.       │
+└─────────────────────────┬──────────────────────────────────┘
+                          │
+┌─────────────────────────▼──────────────────────────────────┐
+│  Navigator (Root ViewController)                           │
+│  - Manages root, modals, overlays                          │
+│  - Coordinates LayoutFactory                               │
+└──────┬──────────────┬──────────────┬──────────────┬────────┘
+       │              │              │              │
+┌──────▼─────┐ ┌──────▼─────┐ ┌──────▼─────┐ ┌─────▼──────┐
+│ModalStack  │ │OverlayMgr  │ │LayoutFactory│ │EventEmitter│
+└────────────┘ └────────────┘ └────────────┘ └────────────┘
+```
+
+## Entry Points
+
+### NavigationApplication
+Abstract Application class that apps extend:
+- Manages `ReactGateway` singleton
+- Initializes SoLoader
+- Provides `registerExternalComponent()` for native screens
+
+### NavigationActivity
+Main Activity containing all navigation:
+- Creates `Navigator` with three CoordinatorLayouts:
+  - `rootLayout` - Main navigation content
+  - `modalsLayout` - Modal stack
+  - `overlaysLayout` - Overlays (highest z-order)
+- Handles back press via `OnBackPressedCallback`
+- Coordinates activity lifecycle with React
+
+### NavigationTurboModule
+TurboModule implementation (Kotlin, ~300 lines):
+
+```kotlin
+@ReactMethod
+fun setRoot(commandId: String, layout: ReadableMap, promise: Promise)
+
+@ReactMethod
+fun push(commandId: String, componentId: String, layout: ReadableMap, promise: Promise)
+
+@ReactMethod
+fun showModal(commandId: String, layout: ReadableMap, promise: Promise)
+```
+
+All commands execute on UI thread via `UiThread.post()`.
+
+## ViewController Hierarchy
+
+**Note**: Android implementation does NOT use Fragments - it's purely View-based.
+
+```
+ViewController (abstract)
+│   - Base for all navigation controllers
+│   - Manages view creation and lifecycle
+│   - Handles options and back press
+│
+├── ChildController
+│   │   - Adds Presenter support
+│   │
+│   ├── ComponentViewController
+│   │       - Renders React components via ReactView
+│   │
+│   └── ExternalComponentViewController
+│           - Wraps native Android views
+│
+└── ParentController (extends ChildController)
+        - Container for child controllers
+        │
+        ├── StackController
+        │       - Push/pop navigation
+        │       - Uses IdStack<ViewController>
+        │
+        ├── BottomTabsController
+        │       - UITabBarController equivalent
+        │       - Uses AHBottomNavigation
+        │
+        ├── TopTabsController
+        │       - Horizontal ViewPager tabs
+        │
+        ├── SideMenuController
+        │       - DrawerLayout-based drawer
+        │
+        └── Navigator
+                - Root controller
+                - Manages modals and overlays
+```
+
+## Core Classes
+
+### ViewController (Base)
+**File**: `viewcontrollers/viewcontroller/ViewController.java` (~500 lines)
+
+Abstract base for all navigation controllers:
+
+```java
+public abstract class ViewController<T extends ViewGroup> {
+    protected abstract T createView();  // Subclasses create views
+
+    public void onViewWillAppear() { }
+    public void onViewDidAppear() { }
+    public void onViewDisappear() { }
+
+    public void mergeOptions(Options options) { }
+    public void applyOptions(Options options) { }
+    public boolean handleBack(CommandListener listener) { }
+    public void destroy() { }
+}
+```
+
+### Navigator (Root)
+**File**: `viewcontrollers/navigator/Navigator.java`
+
+Root ViewController managing:
+- Root content hierarchy
+- Modal stack (`ModalStack`)
+- Overlay manager (`OverlayManager`)
+- Component lookup by ID
+
+### LayoutFactory
+**File**: `options/LayoutFactory.java`
+
+Factory creating ViewControllers from LayoutNode. Owned by `NavigationTurboModule` and used to build the view controller hierarchy when commands are received from JavaScript.
+
+```java
+public ViewController create(LayoutNode node) {
+    switch (node.type) {
+        case Component: return createComponent(node);
+        case Stack: return createStack(node);
+        case BottomTabs: return createBottomTabs(node);
+        case SideMenuRoot: return createSideMenuRoot(node);
+        case SideMenuCenter: return createSideMenuContent(node);
+        case SideMenuLeft: return createSideMenuLeft(node);
+        case SideMenuRight: return createSideMenuRight(node);
+        case TopTabs: return createTopTabs(node);
+        // Note: SplitView is iOS-only, not implemented on Android
+    }
+}
+```
+
+## Navigation Types
+
+### Stack Navigation (StackController)
+**Files**: `viewcontrollers/stack/`
+
+- View: `StackLayout` (CoordinatorLayout with TopBar)
+- Internal stack: `IdStack<ViewController<?>>`
+- Components: `TopBarController`, `StackAnimator`, `StackPresenter`, `FabPresenter`
+
+Operations:
+- `push(viewController, listener)`
+- `pop(options, listener)`
+- `popTo(target, options, listener)`
+- `popToRoot(options, listener)`
+- `setRoot(children, listener)`
+
+### Bottom Tabs (BottomTabsController)
+**Files**: `viewcontrollers/bottomtabs/`
+
+- View: `BottomTabsLayout` (CoordinatorLayout with BottomTabs)
+- Uses `AHBottomNavigation` library
+- Components: `BottomTabsPresenter`, `BottomTabPresenter`, `BottomTabsAnimator`
+
+Attachment Modes:
+- `TogetherAttacher` - Load all tabs immediately
+- `OnSwitchToTabAttacher` - Lazy load on selection
+- `AfterInitialTabAttacher` - Load initial + others in background
+
+### Side Menu (SideMenuController)
+**Files**: `viewcontrollers/sidemenu/`
+
+- View: `SideMenuRoot` (DrawerLayout-based)
+- Children: Center, Left, Right controllers
+- `SideMenuPresenter` for styling
+
+### Top Tabs (TopTabsController)
+**Files**: `viewcontrollers/toptabs/`
+
+- View: `TopTabsViewPager` (ViewPager-based)
+- `TopTabsLayoutCreator` for view creation
+
+### Modals (ModalStack)
+**Files**: `viewcontrollers/modal/`
+
+Not a ViewController - manages modal presentation:
+- `ModalPresenter` - Show/dismiss with animations
+- `ModalAnimator` (Kotlin) - Animation handling
+- Stack of modals with lifecycle management
+
+### Overlays (OverlayManager)
+**File**: `viewcontrollers/overlay/OverlayManager.kt`
+
+Registry of active overlays:
+- Show/dismiss by component ID
+- Configuration change handling
+- Host pause/resume lifecycle
+
+## React Component Rendering
+
+### ComponentViewController
+Manages React component lifecycle:
+- Creates `ComponentLayout` view
+- Initializes `ReactView` with ReactSurface
+- Emits lifecycle events to JS
+- Handles scroll events and status bar
+
+### ReactView
+**File**: `react/ReactView.java`
+
+Extends FrameLayout, wraps `ReactSurface`:
+- `start()` - Attach surface to React instance
+- `destroy()` - Clean up React surface
+- `sendComponentWillStart()` - Emit event to JS
+- `isReady()` - Check surface attachment
+
+## Event Emission
+
+### EventEmitter
+**File**: `react/events/EventEmitter.java`
+
+Events sent to JavaScript:
+
+| Event | Description |
+|-------|-------------|
+| `RNN.AppLaunched` | App initialization complete |
+| `RNN.ComponentDidAppear` | Component visible |
+| `RNN.ComponentWillAppear` | About to become visible |
+| `RNN.ComponentDidDisappear` | Component hidden |
+| `RNN.NavigationButtonPressed` | TopBar button tapped |
+| `RNN.BottomTabSelected` | Tab selection changed |
+| `RNN.BottomTabPressed` | Tab pressed (even if selected) |
+| `RNN.ModalDismissed` | Modal was dismissed |
+| `RNN.ScreenPopped` | Screen removed from stack |
+| `RNN.CommandCompleted` | Navigation command finished |
+
+## Options System
+
+### Options Class
+**File**: `options/Options.java`
+
+```java
+public class Options {
+    public TopBarOptions topBar;
+    public TopTabsOptions topTabs;
+    public BottomTabsOptions bottomTabsOptions;
+    public BottomTabOptions bottomTabOptions;
+    public OverlayOptions overlayOptions;
+    public FabOptions fabOptions;
+    public AnimationsOptions animations;
+    public SideMenuRootOptions sideMenuRootOptions;
+    public ModalOptions modal;
+    public StatusBarOptions statusBar;
+    public NavigationBarOptions navigationBar;
+    public LayoutOptions layout;
+    public HardwareBackButtonOptions hardwareBack;
+}
+```
+
+### Options Flow
+1. **Parse**: JSON from JS → Options object via JSONParser
+2. **Merge**: Default → Screen → Component options
+3. **Apply**: Presenter applies to views
+
+## Presenter Pattern
+
+Each ViewController has a Presenter:
+
+| ViewController | Presenter |
+|---------------|-----------|
+| StackController | StackPresenter |
+| BottomTabsController | BottomTabsPresenter + BottomTabPresenter |
+| ComponentViewController | ComponentPresenter |
+| SideMenuController | SideMenuPresenter |
+| Navigator | RootPresenter |
+
+### Presenter Base
+**File**: `viewcontrollers/viewcontroller/Presenter.java`
+
+Handles:
+- Orientation changes
+- Status bar styling
+- Navigation bar styling
+- Layout parameters
+
+## Animation System
+
+### Animators (Kotlin)
+- `StackAnimator.kt` - Push, pop, setRoot animations
+- `ModalAnimator.kt` - Modal show/dismiss
+- `BottomTabsAnimator.kt` - Tab transitions
+- `TopBarAppearanceAnimator.kt` - Top bar changes
+
+### Element Transitions
+Via `TransitionAnimatorCreator.kt`:
+- Position, scale, rotation animations
+- Color transitions
+- Corner radius animations
+- Shared element support
+
+## Activity Lifecycle
+
+```java
+onCreate()      // Create Navigator, initialize React
+onPostCreate()  // Set content layout
+onResume()      // React host resume, event emitter setup
+onPause()       // React host pause
+onDestroy()     // Clean up Navigator
+onConfigurationChanged()  // Handle orientation, locale
+onNewIntent()   // Process deep links
+onActivityResult()  // Handle permissions
+```
+
+## ViewController Lifecycle
+
+```
+View creation
+    ↓
+onViewWillAppear()   // Register with registry
+    ↓
+onViewDidAppear()    // Emit event to JS
+    ↓
+[visible]
+    ↓
+onViewWillDisappear()
+    ↓
+onViewDisappear()    // Unregister from registry
+    ↓
+destroy()            // Complete cleanup
+```
+
+## Key Files Reference
+
+All paths relative to `android/src/main/java/com/reactnativenavigation/`:
+
+| File | Path | Purpose |
+|------|------|---------|
+| NavigationActivity.java | `.` | Main Activity |
+| NavigationApplication.java | `.` | Application class |
+| NavigationTurboModule.kt | `react/` | JS bridge |
+| Navigator.java | `viewcontrollers/navigator/` | Root controller |
+| ViewController.java | `viewcontrollers/viewcontroller/` | Base class |
+| StackController.java | `viewcontrollers/stack/` | Stack navigation |
+| BottomTabsController.java | `viewcontrollers/bottomtabs/` | Tab navigation |
+| LayoutFactory.java | `options/` | Controller factory |
+| Options.java | `options/` | Options model |
+| Presenter.java | `viewcontrollers/viewcontroller/` | Base presenter |
+| EventEmitter.java | `react/events/` | JS events |
+| ReactView.java | `react/` | React component wrapper |
+| StackAnimator.kt | `viewcontrollers/stack/` | Stack animations |
+| ModalStack.java | `viewcontrollers/modal/` | Modal management |

package/android/src/main/java/com/reactnativenavigation/views/stack/topbar/titlebar/IconBackgroundDrawable.kt

@@ -8,12 +8,12 @@ import com.reactnativenavigation.options.params.DensityPixel
 
 
 class IconBackgroundDrawable(
-        private val wrapped: Drawable,
-        private val cornerRadius: DensityPixel,
-        private val backgroundWidth: Int,
-        private val backgroundHeight: Int,
-        private val iconColor: Int?,
-        val backgroundColor: Int?
+    private val wrapped: Drawable,
+    private val cornerRadius: DensityPixel,
+    private val backgroundWidth: Int,
+    private val backgroundHeight: Int,
+    private val iconColor: Int?,
+    val backgroundColor: Int?
 ) : Drawable() {
     private val path: Path = Path()
     private val bitmapPaint = Paint().apply {
@@ -56,28 +56,31 @@ class IconBackgroundDrawable(
         canvas.drawBitmap(wrapped.toBitmap(), null, bitmapRect, bitmapPaint)
     }
 
+    override fun getIntrinsicWidth(): Int = backgroundWidth
+    override fun getIntrinsicHeight(): Int = backgroundHeight
+
     override fun setBounds(l: Int, t: Int, r: Int, b: Int) {
-        updatePath(RectF(l.toFloat(), t.toFloat(), backgroundWidth.toFloat(), backgroundHeight.toFloat()))
-        super.setBounds(l, t, backgroundWidth, backgroundHeight)
+        updatePath(RectF(0f, 0f, backgroundWidth.toFloat(), backgroundHeight.toFloat()))
+        super.setBounds(l, t, l + backgroundWidth, t + backgroundHeight)
     }
 
     override fun setBounds(r: Rect) {
-        r.right = backgroundWidth
-        r.bottom = backgroundHeight
-        updatePath(RectF(r))
+        r.right = r.left + backgroundWidth
+        r.bottom = r.top + backgroundHeight
+        updatePath(RectF(0f, 0f, backgroundWidth.toFloat(), backgroundHeight.toFloat()))
         super.setBounds(r)
     }
 
     override fun onBoundsChange(bounds: Rect) {
         if (bounds != null) {
             backgroundRect = Rect((bounds.width() - backgroundWidth) / 2,
-                    (bounds.height() - backgroundHeight) / 2,
-                    bounds.width() - (bounds.width() - backgroundWidth) / 2,
-                    bounds.height() - (bounds.height() - backgroundHeight) / 2)
+                (bounds.height() - backgroundHeight) / 2,
+                bounds.width() - (bounds.width() - backgroundWidth) / 2,
+                bounds.height() - (bounds.height() - backgroundHeight) / 2)
             bitmapRect = Rect((bounds.width() - bitmapWidth) / 2,
-                    (bounds.height() - bitmapHeight) / 2,
-                    bounds.width() - (bounds.width() - bitmapWidth) / 2,
-                    bounds.height() - (bounds.height() - bitmapHeight) / 2)
+                (bounds.height() - bitmapHeight) / 2,
+                bounds.width() - (bounds.width() - bitmapWidth) / 2,
+                bounds.height() - (bounds.height() - bitmapHeight) / 2)
         }
         super.onBoundsChange(bounds)
     }