react-native-navigation 8.7.5 → 8.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-navigation",
-  "version": "8.7.5",
+  "version": "8.7.6",
   "description": "React Native Navigation - truly native navigation for iOS and Android",
   "license": "MIT",
   "nativePackage": true,
@@ -94,15 +94,16 @@
     "@babel/preset-env": "^7.25.3",
     "@babel/runtime": "^7.25.0",
     "@babel/types": "7.25.0",
+    "@d11/react-native-fast-image": "^8.13.0",
     "@react-native-community/cli": "20.0.0",
     "@react-native-community/cli-platform-android": "20.0.0",
     "@react-native-community/cli-platform-ios": "20.0.0",
     "@react-native-community/datetimepicker": "^8.2.0",
     "@react-native-community/netinfo": "^11.4.1",
-    "@react-native/babel-preset": "0.83.0",
-    "@react-native/eslint-config": "0.83.0",
-    "@react-native/metro-config": "0.83.0",
-    "@react-native/typescript-config": "0.83.0",
+    "@react-native/babel-preset": "0.84.0",
+    "@react-native/eslint-config": "0.84.0",
+    "@react-native/metro-config": "0.84.0",
+    "@react-native/typescript-config": "0.84.0",
     "@testing-library/jest-native": "^5.4.2",
     "@testing-library/react-native": "^13.0.1",
     "@types/hoist-non-react-statics": "^3.3.6",
@@ -130,15 +131,14 @@
     "pixelmatch": "^5.2.1",
     "pngjs": "^6.0.0",
     "prettier": "2.8.8",
-    "react": "19.2.0",
-    "react-native": "0.83.0",
+    "react": "19.2.3",
+    "react-native": "0.84.0",
     "react-native-builder-bob": "^0.40.13",
-    "react-native-fast-image": "^8.6.3",
     "react-native-gesture-handler": "^2.29.1",
-    "react-native-reanimated": "4.1.5",
-    "react-native-worklets": "0.5.0",
+    "react-native-reanimated": "4.2.2",
+    "react-native-worklets": "0.7.4",
     "react-redux": "9.1.2",
-    "react-test-renderer": "19.2.0",
+    "react-test-renderer": "19.2.3",
     "redux": "^5.0.1",
     "remx": "3.x.x",
     "semver": "5.x.x",

package/src/ARCHITECTURE.md

@@ -0,0 +1,301 @@
+# JavaScript/TypeScript Architecture
+
+The JavaScript layer provides the public API and orchestrates communication between React components and native navigation implementations.
+
+## Entry Point
+
+`index.ts` exports the `Navigation` singleton (a `NavigationDelegate` instance) along with re-exports from `Modal`, `EventsRegistry`, `Constants`, and all interfaces. Applications use `Navigation.*` for commands and `Navigation.events().*` for event subscriptions.
+
+## Module Structure
+
+```
+src/
+├── index.ts                 # Main entry point, exports Navigation singleton
+├── Navigation.ts            # NavigationRoot - core orchestrator
+├── NavigationDelegate.ts    # Public API facade
+├── adapters/                # Native bridge layer
+├── commands/                # Command processing
+├── components/              # React component management
+├── events/                  # Event system
+├── interfaces/              # TypeScript type definitions
+└── processors/              # Extensibility hooks
+```
+
+## Core Classes
+
+### NavigationDelegate (Public API)
+**File**: `NavigationDelegate.ts`
+
+Facade providing the public `Navigation` API. All methods proxy to `NavigationRoot`.
+
+```typescript
+// Usage
+import { Navigation } from 'react-native-navigation';
+Navigation.setRoot({ root: { stack: { children: [...] } } });
+```
+
+### NavigationRoot (Core Orchestrator)
+**File**: `Navigation.ts`
+
+Coordinates all subsystems. Constructed with dependencies:
+- `NativeCommandsSender` - sends commands to native
+- `NativeEventsReceiver` - receives events from native
+- `AppRegistryService` - manages React Native component registry
+
+Initializes and coordinates:
+- `Store` - component instance & props storage
+- `ComponentRegistry` - component registration
+- `LayoutTreeParser` - converts layouts to internal nodes
+- `LayoutTreeCrawler` - processes layout trees
+- `Commands` - command execution
+- `EventsRegistry` - event subscriptions
+- `OptionsProcessor` - option processing
+- `LayoutProcessor` - layout transformations
+
+## Adapters Layer
+
+Bridge between JavaScript and native/React Native APIs.
+
+| Adapter | Purpose |
+|---------|---------|
+| `NativeCommandsSender` | Wraps TurboModule for command dispatch |
+| `NativeEventsReceiver` | Wraps NativeEventEmitter for events |
+| `NativeRNNTurboModule` | TurboModule spec interface |
+| `NativeRNNTurboEventEmitter` | TurboModule event emitter spec |
+| `UniqueIdProvider` | Generates unique component/command IDs |
+| `ColorService` | Converts colors to native format |
+| `AssetResolver` | Resolves require() image assets (class: AssetService) |
+| `AppRegistryService` | Registers components with React Native |
+| `Constants` | Platform dimension constants |
+| `TouchablePreview` | 3D Touch / Haptic preview handling |
+
+## Commands Layer
+
+### Commands Class
+**File**: `commands/Commands.ts`
+
+Central command dispatcher. Each navigation command:
+1. Validates input
+2. Processes layout through pipeline
+3. Sends to native via adapter
+4. Returns promise with result
+
+### Processing Pipeline
+
+The pipeline executes in this exact order:
+
+```
+Input Layout (from API)
+       ↓
+1. OptionsCrawler.crawl()         # Extract static options from component classes
+       ↓
+2. LayoutProcessor.process()      # Apply registered layout processors
+       ↓
+3. LayoutTreeParser.parse()       # Convert to internal LayoutNode tree
+       ↓
+4. LayoutTreeCrawler.crawl()      # Process options, save props to Store
+       ↓
+5. OptionsProcessor (during crawl) # Resolve colors, assets, custom processors
+       ↓
+6. NativeCommandsSender           # Send to native module
+```
+
+### LayoutNode (Internal Tree)
+```typescript
+interface LayoutNode {
+  id: string;           // Unique identifier
+  type: LayoutType;     // Component|Stack|BottomTabs|etc
+  data: {
+    name?: string;      // Component name
+    options?: any;      // Processed options
+    passProps?: any;    // Component props (cleared before native)
+  };
+  children: LayoutNode[];
+}
+```
+
+### LayoutType Enum
+```typescript
+enum LayoutType {
+  Component = 'Component',
+  Stack = 'Stack',
+  BottomTabs = 'BottomTabs',
+  SideMenuRoot = 'SideMenuRoot',
+  SideMenuCenter = 'SideMenuCenter',
+  SideMenuLeft = 'SideMenuLeft',
+  SideMenuRight = 'SideMenuRight',
+  TopTabs = 'TopTabs',
+  ExternalComponent = 'ExternalComponent',
+  SplitView = 'SplitView',
+}
+```
+
+## Components Layer
+
+### ComponentRegistry
+**File**: `components/ComponentRegistry.ts`
+
+Manages React component registration and wrapping.
+
+```typescript
+Navigation.registerComponent('ScreenName', () => MyComponent);
+```
+
+### ComponentWrapper
+**File**: `components/ComponentWrapper.tsx`
+
+Higher-order component that:
+- Wraps original component with lifecycle management
+- Stores instance in `Store` for event dispatch
+- Injects `componentId` and `componentName` props
+
+### Store
+**File**: `components/Store.ts`
+
+Centralized storage for:
+- `componentsByName` - registered component providers
+- `componentsInstancesById` - mounted component instances
+- `propsById` - static props by component ID
+- `pendingPropsById` - props awaiting component mount
+- `wrappedComponents` - cached wrapped components
+- `lazyRegistratorFn` - function for lazy component registration
+
+## Events Layer
+
+### EventsRegistry
+**File**: `events/EventsRegistry.ts`
+
+Public API for event subscriptions:
+
+```typescript
+Navigation.events().registerComponentDidAppearListener(({ componentId }) => {});
+Navigation.events().registerCommandCompletedListener(({ commandId }) => {});
+```
+
+### ComponentEventsObserver
+**File**: `events/ComponentEventsObserver.ts`
+
+Dispatches events to component instance methods:
+- `componentWillAppear()`
+- `componentDidAppear()`
+- `componentDidDisappear()`
+- `navigationButtonPressed()`
+- `screenPopped()`
+
+### CommandsObserver
+**File**: `events/CommandsObserver.ts`
+
+Notifies listeners of command lifecycle (start, complete).
+
+## Events (Native → JS)
+
+| Event | Description |
+|-------|-------------|
+| `RNN.AppLaunched` | App initialization complete |
+| `RNN.ComponentWillAppear` | Component about to appear |
+| `RNN.ComponentDidAppear` | Component now visible |
+| `RNN.ComponentDidDisappear` | Component hidden |
+| `RNN.NavigationButtonPressed` | TopBar button tapped |
+| `RNN.BottomTabPressed` | Tab pressed (even if selected) |
+| `RNN.BottomTabSelected` | Tab selection changed |
+| `RNN.BottomTabLongPressed` | Tab long-pressed |
+| `RNN.ModalDismissed` | Modal was dismissed |
+| `RNN.ModalAttemptedToDismiss` | Swipe-to-dismiss attempted |
+| `RNN.ScreenPopped` | Screen removed from stack |
+| `RNN.SearchBarUpdated` | Search text changed |
+| `RNN.SearchBarCancelPressed` | Search cancelled |
+| `RNN.PreviewCompleted` | 3D Touch preview completed |
+| `RNN.CommandCompleted` | Navigation command finished |
+
+## Processors Layer
+
+### OptionProcessorsStore
+**File**: `processors/OptionProcessorsStore.ts`
+
+Registers custom option processors:
+
+```typescript
+Navigation.addOptionProcessor('topBar.title.text', (value, commandName) => {
+  return value.toUpperCase(); // Transform all titles
+});
+```
+
+### LayoutProcessorsStore
+**File**: `processors/LayoutProcessorsStore.ts`
+
+Registers layout transformers:
+
+```typescript
+Navigation.addLayoutProcessor((layout, commandName) => {
+  // Add default options to all components
+  return layout;
+});
+```
+
+## Interfaces
+
+### Layout Types
+**File**: `interfaces/Layout.ts`
+
+```typescript
+interface LayoutRoot {
+  root: Layout;
+  modals?: any[];
+  overlays?: any[];
+}
+
+type Layout = {
+  component?: LayoutComponent;
+  stack?: LayoutStack;
+  bottomTabs?: LayoutBottomTabs;
+  sideMenu?: LayoutSideMenu;
+  splitView?: LayoutSplitView;
+  topTabs?: LayoutTopTabs;
+  externalComponent?: ExternalComponent;
+}
+```
+
+### Options Interface
+**File**: `interfaces/Options.ts` (comprehensive)
+
+Contains all configuration options for:
+- Status bar, navigation bars
+- Top bar (buttons, title, search)
+- Bottom tabs
+- Side menus
+- Modals, overlays
+- Animations
+- Layout parameters
+
+### NavigationComponent
+**File**: `interfaces/NavigationComponent.ts`
+
+Base class for navigation-aware components:
+
+```typescript
+class MyScreen extends NavigationComponent<Props> {
+  static options: Options = { ... };
+
+  componentDidAppear(event) { }
+  navigationButtonPressed(event) { }
+}
+```
+
+## Dependencies
+
+**Production**:
+- `lodash` - utility functions
+- `hoist-non-react-statics` - HOC support
+- `react-lifecycles-compat` - lifecycle polyfill
+- `tslib` - TypeScript helpers
+
+**Peer**:
+- `react`, `react-native` (required)
+- `remx` (optional state management)
+
+## Build Output
+
+Uses `react-native-builder-bob`:
+- **Source**: `src/`
+- **Output**: `lib/`
+- **Targets**: ESM modules + TypeScript declarations

package/src/interfaces/Options.ts

@@ -457,7 +457,37 @@ export interface OptionsTopBarScrollEdgeAppearanceBackground {
   translucent?: boolean;
 }
 
+export interface OptionsTopBarScrollEdgeAppearanceTitle {
+  /**
+   * Font size
+   */
+  fontSize?: number;
+  /**
+   * Text color
+   */
+  color?: Color;
+  /**
+   * Set the font family for the title
+   */
+  fontFamily?: FontFamily;
+  /**
+   * Set the font style for the title
+   */
+  fontStyle?: FontStyle;
+  /**
+   * Specifies font weight. The values 'normal' and 'bold' are supported
+   * for most fonts. Not all fonts have a variant for each of the numeric
+   * values, in that case the closest one is chosen.
+   */
+  fontWeight?: FontWeight;
+}
+
 export interface OptionsTopBarScrollEdgeAppearance {
+  /**
+   * Title configuration applied when the scroll view reaches the edge
+   * ### (iOS specific)
+   */
+  title?: OptionsTopBarScrollEdgeAppearanceTitle;
   background?: OptionsTopBarScrollEdgeAppearanceBackground;
   active: boolean;
   /**