# iOS Native Architecture

The iOS implementation provides native navigation using UIKit view controllers, coordinated through a bridge module that receives commands from JavaScript.

## App Integration

### RNNAppDelegate
**Files**: `RNNAppDelegate.h/mm`

Base class that user's AppDelegate must extend. Handles React Native and navigation initialization:

```objc
// AppDelegate.h - User extends RNNAppDelegate
#import "RNNAppDelegate.h"
@interface AppDelegate : RNNAppDelegate
@end

// AppDelegate.m - User implements sourceURLForBridge
@implementation AppDelegate
- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge {
  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
}
@end
```

**What RNNAppDelegate does:**
- Sets up React Native feature flags (Fabric, TurboModules, Bridgeless)
- Creates `RCTRootViewFactory` and `ReactHost`
- Calls `[ReactNativeNavigation bootstrapWithHost:]` to initialize navigation
- Handles RN version differences (0.77, 0.78, 0.79+) via compile-time macros

### ReactNativeNavigation Bootstrap
**File**: `ReactNativeNavigation.h/mm`

Public API for native initialization:

```objc
// New architecture (0.77+)
[ReactNativeNavigation bootstrapWithHost:reactHost];

// Legacy bridge
[ReactNativeNavigation bootstrapWithBridge:bridge];

// Register native screens
[ReactNativeNavigation registerExternalComponent:@"NativeScreen"
                                        callback:^(NSDictionary *props, RCTBridge *bridge) {
    return [[MyNativeVC alloc] init];
}];
```

### Autolink Script (`npx rnn-link`)

The `autolink/postlink/postLinkIOS.js` script automates setup:

| Linker | What it does |
|--------|--------------|
| `AppDelegateLinker` | Changes AppDelegate to extend `RNNAppDelegate`, imports ReactNativeNavigation, removes RCTRootView setup |
| `PodfileLinker` | Adds required pods configuration |
| `PlistLinker` | Updates Info.plist if needed |

**AppDelegateLinker transformations:**
- Swift: `class AppDelegate: RCTAppDelegate` → `class AppDelegate: RNNAppDelegate`
- Obj-C header: `@interface AppDelegate : RCTAppDelegate` → `@interface AppDelegate : RNNAppDelegate`
- Imports `<ReactNativeNavigation/ReactNativeNavigation.h>`
- Removes manual RCTRootView/window setup (navigation manages the window)

## Directory Structure

```
ios/
├── RNNBridgeModule.h/mm         # Bridge entry point (legacy architecture)
├── RNNBridgeManager.h/mm        # Bridge initialization
├── RNNCommandsHandler.h/mm      # Command dispatcher
├── RNNEventEmitter.h/mm         # Event emission to JS
├── RNNLayoutManager.h/mm        # View controller tracking
├── RNNLayoutNode.h/mm           # Layout tree parsing
├── RNNNavigationOptions.h/mm    # Options model
├── RNNComponentViewController.h/mm  # React component screen
├── RNNStackController.h/mm      # Stack navigation
├── RNNBottomTabsController.h/mm # Tab navigation
├── RNNSideMenuViewController.h/mm   # Side menu
├── RNNTopTabsViewController.h/mm    # Top tabs
├── RNNSplitViewController.h/mm  # Split view (iPad)
├── RNNModalManager.h/mm         # Modal presentation
├── RNNOverlayManager.h/mm       # Overlay management
├── TurboModules/                # New architecture entry points
│   ├── RNNTurboModule.h/mm      # TurboModule spec implementation
│   ├── RNNTurboManager.h/mm     # Manager for host, window, external components
│   ├── RNNTurboCommandsHandler.h/mm  # TurboModule command routing
│   └── RNNTurboEventEmitter.h/mm     # Event emission for new arch
├── Utils/                       # Utility classes
├── RNNSideMenu/                 # MMDrawerController integration
└── ReactNativeNavigation.xcodeproj/
```

## Bridge Architecture

The library supports both the legacy bridge and new TurboModule architecture:
- **Legacy (Bridge)**: `RNNBridgeModule` receives commands via `RCT_EXPORT_METHOD`
- **New Architecture**: `RNNTurboModule` (in `TurboModules/`) receives commands directly

Both entry points delegate to `RNNCommandsHandler` for command execution.

```
┌────────────────────────────────────────────────────────────┐
│                 JavaScript (TurboModule)                   │
└─────────────────────────┬──────────────────────────────────┘
                          │
┌─────────────────────────▼──────────────────────────────────┐
│  RNNBridgeModule (bridge) / RNNTurboModule (new arch)      │
│  - setRoot, push, pop, showModal, dismissModal, etc.       │
└─────────────────────────┬──────────────────────────────────┘
                          │
┌─────────────────────────▼──────────────────────────────────┐
│  RNNCommandsHandler                                         │
│  - Validates commands, manages layout lifecycle            │
│  - Coordinates with managers                               │
└──────┬──────────────┬──────────────┬──────────────┬────────┘
       │              │              │              │
┌──────▼─────┐ ┌──────▼─────┐ ┌──────▼─────┐ ┌─────▼──────┐
│RNNLayout   │ │RNNModal    │ │RNNOverlay  │ │RNNViewController│
│Manager     │ │Manager     │ │Manager     │ │Factory     │
└────────────┘ └────────────┘ └────────────┘ └────────────┘
```

## View Controller Hierarchy

All navigation view controllers conform to `RNNLayoutProtocol`:

```
UIViewController
├── RNNComponentViewController    # React component screen
├── RNNExternalViewController     # Native screen wrapper
└── RNNSplashScreenViewController # Launch screen

UINavigationController
└── RNNStackController           # Stack navigation

UITabBarController
└── RNNBottomTabsController      # Bottom tabs

UIViewController (custom)
├── RNNTopTabsViewController     # Horizontal top tabs
└── RNNSideMenuChildViewController  # Drawer child

MMDrawerController
└── RNNSideMenuViewController    # Side menu/drawer

UISplitViewController
└── RNNSplitViewController       # Master-detail (iPad)
```

## Core Classes

### RNNBridgeModule
Entry point for JavaScript commands (legacy architecture). Exports methods via `RCT_EXPORT_METHOD`:

```objc
RCT_EXPORT_METHOD(setRoot:(NSString*)commandId layout:(NSDictionary*)layout
                  resolver:(RCTPromiseResolveBlock)resolve
                  rejecter:(RCTPromiseRejectBlock)reject);
```

`RNNBridgeModule` returns the main queue as its `methodQueue`; `RNNTurboModule` uses `RCTExecuteOnMainQueue` for each command to ensure UI operations run on the main thread.

### RNNBridgeManager
Initializes bridge infrastructure:
- Creates RNNLayoutManager, RNNModalManager, RNNOverlayManager
- Creates RNNViewControllerFactory, RNNCommandsHandler
- Provides extra modules to React bridge
- Handles JavaScript reload events

### RNNCommandsHandler
Central command dispatcher implementing all navigation operations:
- `setRoot:` - Replace root view controller
- `push:componentId:layout:` - Push to stack
- `pop:componentId:` - Pop from stack
- `showModal:` - Present modal
- `dismissModal:` - Dismiss modal
- `showOverlay:` - Show overlay window
- `dismissOverlay:` - Hide overlay

### RNNLayoutManager
Tracks active view controllers:
- `addPendingViewController:` - Register during creation
- `removePendingViewController:` - Cleanup after presentation
- `findComponentForId:` - Lookup by componentId

### RNNLayoutNode
Parses JSON layout from JavaScript:
- Determines type via predicates: `isComponent`, `isStack`, `isTabs`, etc.
- Holds `type`, `nodeId`, `data` (options), `children`

### RNNViewControllerFactory
Creates view controllers from RNNLayoutNode:
- `createStack:` → RNNStackController
- `createBottomTabs:` → RNNBottomTabsController
- `createComponent:` → RNNComponentViewController
- `createSideMenu:` → RNNSideMenuViewController

## RNNLayoutProtocol

Protocol all navigation controllers implement:

```objc
@protocol RNNLayoutProtocol
- (instancetype)initWithLayoutInfo:(RNNLayoutInfo*)layoutInfo
                           creator:(id<RNNComponentViewCreator>)creator
                           options:(RNNNavigationOptions*)options
                    defaultOptions:(RNNNavigationOptions*)defaultOptions
                         presenter:(RNNBasePresenter*)presenter
                      eventEmitter:(RNNEventEmitter*)eventEmitter
              childViewControllers:(NSArray*)childViewControllers;

- (void)render;
- (UIViewController*)getCurrentChild;
- (void)mergeOptions:(RNNNavigationOptions*)options;
- (RNNNavigationOptions*)resolveOptions;
- (void)setDefaultOptions:(RNNNavigationOptions*)defaultOptions;
- (void)onChildWillAppear;
- (void)readyForPresentation;
- (CGFloat)getTopBarHeight;
- (CGFloat)getBottomTabsHeight;
@end
```

Additional methods provided via `UIViewController+LayoutProtocol` category:
- `destroy`, `topMostViewController`, `stack`
- `componentWillAppear`, `componentDidAppear`, `componentDidDisappear`
- `screenPopped`, `prepareForTransition`
- `resolveOptionsWithDefault`, `mergeChildOptions:child:`

## Presenter Pattern

Each view controller type has a corresponding presenter that applies options:

| Controller | Presenter |
|------------|-----------|
| RNNComponentViewController | RNNComponentPresenter |
| RNNStackController | RNNStackPresenter + TopBarPresenter |
| RNNBottomTabsController | RNNBottomTabsPresenter + BottomTabPresenter |
| RNNSideMenuViewController | RNNSideMenuPresenter |
| RNNSplitViewController | RNNSplitViewControllerPresenter |

### RNNBasePresenter
Base class with lifecycle methods:
- `applyOptionsOnInit:` - Initial setup
- `applyOptions:` - Apply current options
- `mergeOptions:resolvedOptions:` - Runtime updates
- `componentWillAppear`, `componentDidAppear`, `componentDidDisappear`

## React View Integration

### RNNReactView
Wraps RCTRootView (legacy) or RCTSurfaceHostingView (new architecture):
- Implements `RNNComponentProtocol`
- Manages `componentId`, `componentType`, `moduleName`
- Lifecycle: `componentWillAppear`, `componentDidAppear`, `componentDidDisappear`

### RNNReactRootViewCreator
Creates RNNReactView instances:
- Supports component types: Component, TopBarTitle, TopBarButton, TopBarBackground
- Handles size flexibility for flexible layouts

### RNNReactComponentRegistry
Caches created React component instances:
- `createComponentIfNotExists:parentComponentId:componentType:reactViewReadyBlock:`
- `removeComponent:`, `clearComponentsForParentId:`

## Options System

### RNNNavigationOptions
Master options object containing all configuration:

```objc
@interface RNNNavigationOptions : RNNOptions
@property RNNTopBarOptions* topBar;
@property RNNBottomTabsOptions* bottomTabs;
@property RNNBottomTabOptions* bottomTab;
@property RNNTopTabsOptions* topTabs;
@property RNNSideMenuOptions* sideMenu;
@property RNNOverlayOptions* overlay;
@property RNNAnimationsOptions* animations;
@property RNNStatusBarOptions* statusBar;
@property RNNLayoutOptions* layout;
@property RNNModalOptions* modal;
@property RNNPreviewOptions* preview;
@property RNNSplitViewOptions* splitView;
@end
```

### Options Resolution
Options merge in hierarchy:
1. Component's own options
2. Parent controller options (loop through chain)
3. Default options (from `setDefaultOptions`)

## Event Emission

### RNNEventEmitter
Sends events to JavaScript via RCTEventEmitter:

| Event | Method |
|-------|--------|
| Component lifecycle | `sendComponentWillAppear:`, `sendComponentDidAppear:`, `sendComponentDidDisappear:` |
| Button press | `sendOnNavigationButtonPressed:buttonId:` |
| Command completion | `sendOnNavigationCommandCompletion:commandId:` |
| Tab events | `sendBottomTabSelected:unselected:`, `sendBottomTabLongPressed:`, `sendBottomTabPressed:` |
| Modal events | `sendModalsDismissedEvent:numberOfModalsDismissed:`, `sendModalAttemptedToDismissEvent:` |
| Screen events | `sendScreenPoppedEvent:` |
| Search | `sendOnSearchBarUpdated:text:isFocused:`, `sendOnSearchBarCancelPressed:` |
| Preview | `sendOnPreviewCompleted:previewComponentId:` |

### RNNBridgeEventEmitter
Concrete implementation that sends `onAppLaunched` on initialization.

## Modal & Overlay Management

### RNNModalManager
- Tracks presented modals array
- Supports custom transition animations via ScreenAnimationController
- Handles presentationController delegate for adaptive presentation

### RNNOverlayManager
- Manages UIWindow instances for overlays
- Each overlay gets its own RNNOverlayWindow
- Maintains previous window reference for restoration
- Controls window level and accessibility

## Animation System

### ScreenAnimationController
Implements `UIViewControllerAnimatedTransitioning`:
- Custom push/pop/modal transitions
- Content transitions (RNNEnterExitAnimation)
- Element transitions (ElementTransitionOptions)
- Shared element transitions (SharedElementTransitionOptions)

### Element Animators
- `ElementAnimator` - Individual element animations
- `SharedElementAnimator` - Cross-screen shared elements
- Transition types: Alpha, Scale, Translation, Frame, Bounds, Color, CornerRadius

### RNNSetRootAnimator
Animates window root replacement using CABasicAnimation.

## Navigation Types

### Stack Navigation (RNNStackController)
- Subclass of UINavigationController
- Push/pop with custom animations
- Back button customization
- Uses StackControllerDelegate for bar delegate handling

```objc
// Extension methods
@interface UINavigationController (RNNCommands)
- (void)push:(UIViewController*)vc onTop:(UIViewController*)onTopVC
     animated:(BOOL)animated completion:(void(^)(void))completion rejection:(RCTPromiseRejectBlock)rejection;
- (void)popAnimated:(BOOL)animated completion:(void(^)(NSString*))completion rejection:(RCTPromiseRejectBlock)rejection;
@end
```

### Bottom Tabs (RNNBottomTabsController)
- Subclass of UITabBarController
- Tab attachment modes: Together, OnSwitchToTab, AfterInitialTab
- Long-press gesture support
- Badge and dot indicator support

### Side Menu (RNNSideMenuViewController)
- Uses MMDrawerController (third-party)
- Center, left, right child containers
- Configurable open modes and widths

### Top Tabs (RNNTopTabsViewController)
- Custom horizontal tab implementation
- Not based on UITabBarController
- Manual content switching

### Split View (RNNSplitViewController)
- UISplitViewController subclass
- Master-detail for iPad

## External Components

### RNNExternalComponentStore
Registry for native (non-React) view controllers.

### RNNExternalViewController
Wraps native UIViewController for integration:

```objc
[ReactNativeNavigation registerExternalComponent:@"NativeScreen"
                                       callback:^(NSDictionary *props, RCTBridge *bridge) {
    return [[MyNativeViewController alloc] init];
}];
```

## Key Files Reference

| File | Purpose |
|------|---------|
| `RNNBridgeModule.h/mm` | Bridge entry point (legacy) |
| `TurboModules/RNNTurboModule.mm` | TurboModule entry point (new arch) |
| `TurboModules/RNNTurboCommandsHandler.mm` | TurboModule command routing |
| `RNNCommandsHandler.h/mm` | Command execution |
| `RNNLayoutManager.h/mm` | Controller tracking |
| `RNNViewControllerFactory.h/mm` | Controller creation |
| `RNNComponentViewController.h/mm` | React screen |
| `RNNStackController.h/mm` | Stack navigation |
| `RNNBottomTabsController.h/mm` | Tab navigation |
| `RNNNavigationOptions.h/mm` | Options model |
| `RNNBasePresenter.h/mm` | Presenter base |
| `TopBarPresenter.h/mm` | Top bar styling |
| `RNNReactView.h/mm` | React view wrapper |
| `ScreenAnimationController.h/mm` | Custom transitions |
