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

package/src/Navigation.ts

@@ -28,6 +28,8 @@ import { LayoutProcessorsStore } from './processors/LayoutProcessorsStore';
 import { CommandName } from './interfaces/CommandName';
 import { OptionsCrawler } from './commands/OptionsCrawler';
 import { OptionsProcessor as OptionProcessor } from './interfaces/Processors';
+import { LinkingHandler } from './linking/LinkingHandler';
+import { LinkingConfig } from './linking/types';
 
 export class NavigationRoot {
   public readonly TouchablePreview = TouchablePreview;
@@ -45,6 +47,7 @@ export class NavigationRoot {
   private readonly componentEventsObserver: ComponentEventsObserver;
   private readonly componentWrapper: ComponentWrapper;
   private readonly optionsCrawler: OptionsCrawler;
+  private readonly linkingHandler: LinkingHandler;
 
   constructor(
     private readonly nativeCommandsSender: NativeCommandsSender,
@@ -96,6 +99,7 @@ export class NavigationRoot {
       this.commandsObserver,
       this.componentEventsObserver
     );
+    this.linkingHandler = new LinkingHandler((layout) => this.commands.showModal(layout));
 
     this.componentEventsObserver.registerOnceForAllComponentEvents();
   }
@@ -168,7 +172,9 @@ export class NavigationRoot {
    * Reset the app to a new layout
    */
   public setRoot(layout: LayoutRoot): Promise<string> {
-    return this.commands.setRoot(layout);
+    const result = this.commands.setRoot(layout);
+    result.then(() => this.linkingHandler.setRootReady()).catch(() => {});
+    return result;
   }
 
   /**
@@ -280,6 +286,35 @@ export class NavigationRoot {
     return this.commands.getLaunchArgs();
   }
 
+  /**
+   * Configure deep link handling. Maps URL prefixes and path patterns to
+   * RNN components. By default each matched link is presented as a modal
+   * (wrapped in a stack so a topBar close button can be configured); supply
+   * `getModal` to customize the modal layout or `onLink` to bypass the
+   * default behavior entirely.
+   */
+  public setLinking(config: LinkingConfig): void {
+    this.linkingHandler.configure(config);
+  }
+
+  /**
+   * Manually run a URL through the deep link pipeline as if it had been
+   * delivered by the OS. Useful for URLs received from push notifications
+   * or other non-`Linking` sources.
+   */
+  public handleDeepLink(url: string): void {
+    this.linkingHandler.handleURL(url);
+  }
+
+  /**
+   * Signal that the app is ready to process deep links (e.g. after the
+   * user has authenticated). When set to `true`, any links that were
+   * queued while not ready are replayed in order.
+   */
+  public setLinkingReady(ready: boolean): void {
+    this.linkingHandler.setLinkingReady(ready);
+  }
+
   /**
    * Obtain the events registry instance
    */

package/src/NavigationDelegate.ts

@@ -10,6 +10,7 @@ import { NavigationRoot } from './Navigation';
 import { NativeCommandsSender } from './adapters/NativeCommandsSender';
 import { NativeEventsReceiver } from './adapters/NativeEventsReceiver';
 import { AppRegistryService } from './adapters/AppRegistryService';
+import { LinkingConfig } from './linking/types';
 
 export class NavigationDelegate {
   private concreteNavigation: NavigationRoot;
@@ -204,6 +205,27 @@ export class NavigationDelegate {
     return this.concreteNavigation.getLaunchArgs();
   }
 
+  /**
+   * Configure deep link handling.
+   */
+  public setLinking(config: LinkingConfig): void {
+    this.concreteNavigation.setLinking(config);
+  }
+
+  /**
+   * Manually feed a URL into the deep link pipeline.
+   */
+  public handleDeepLink(url: string): void {
+    this.concreteNavigation.handleDeepLink(url);
+  }
+
+  /**
+   * Signal readiness to process deep links. Flushes any queued links.
+   */
+  public setLinkingReady(ready: boolean): void {
+    this.concreteNavigation.setLinkingReady(ready);
+  }
+
   /**
    * Obtain the events registry instance
    */

package/src/adapters/AndroidCustomRowForwarder.ts

@@ -0,0 +1,83 @@
+import { NativeModules, Platform } from 'react-native';
+
+import { Options } from '../interfaces/Options';
+
+/**
+ * Walks a Layout / Options tree looking for `bottomTabs.customRow`
+ * configuration and forwards it to the Android-only native module
+ * `RNNBottomTabsCustomRowModule`.
+ *
+ * On iOS this is a no-op — the existing native options parser already picks
+ * up `bottomTabs.customRow` and applies it to the iOS custom row.
+ *
+ * The original layout/options object is *never* modified — both pipelines
+ * (iOS native parser, Android native parser which currently ignores the
+ * field) keep seeing the same data.
+ */
+export class AndroidCustomRowForwarder {
+  forwardFromLayout(layout: any) {
+    if (!this.shouldForward()) return;
+    const config = this.findCustomRowInLayout(layout);
+    if (config) this.send(config);
+  }
+
+  forwardFromLayouts(layouts: any[]) {
+    if (!this.shouldForward()) return;
+    for (const layout of layouts) {
+      const config = this.findCustomRowInLayout(layout);
+      if (config) {
+        this.send(config);
+        return;
+      }
+    }
+  }
+
+  forwardFromOptions(options: Options | undefined) {
+    if (!this.shouldForward() || !options) return;
+    const config = this.extractFromOptions(options);
+    if (config) this.send(config);
+  }
+
+  private shouldForward(): boolean {
+    return Platform.OS === 'android';
+  }
+
+  private findCustomRowInLayout(layout: any): object | null {
+    if (!layout || typeof layout !== 'object') return null;
+    // Walk both the raw layout shape (`layout.options`) and the
+    // post-`layoutTreeParser.parse` shape (`layout.data.options`).
+    const direct =
+      this.extractFromOptions(layout.options) ??
+      this.extractFromOptions(layout.data?.options);
+    if (direct) return direct;
+    const children = layout.children;
+    if (Array.isArray(children)) {
+      for (const child of children) {
+        const found = this.findCustomRowInLayout(child);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  private extractFromOptions(options: Options | undefined): object | null {
+    if (!options || typeof options !== 'object') return null;
+    const bottomTabs: any = (options as any).bottomTabs;
+    if (!bottomTabs || typeof bottomTabs !== 'object') return null;
+    const customRow = bottomTabs.customRow;
+    if (!customRow || typeof customRow !== 'object') return null;
+    return customRow;
+  }
+
+  private send(config: object): void {
+    const nativeModule = (NativeModules as any).RNNBottomTabsCustomRowModule;
+    if (!nativeModule || typeof nativeModule.configure !== 'function') {
+      return;
+    }
+    try {
+      nativeModule.configure(config);
+    } catch {
+      // Native module not ready yet; attacher will pick up config on next rescan.
+    }
+  }
+}

package/src/commands/Commands.ts

@@ -13,8 +13,11 @@ import { Store } from '../components/Store';
 import { LayoutProcessor } from '../processors/LayoutProcessor';
 import { CommandName } from '../interfaces/CommandName';
 import { OptionsCrawler } from './OptionsCrawler';
+import { AndroidCustomRowForwarder } from '../adapters/AndroidCustomRowForwarder';
 
 export class Commands {
+  private readonly androidCustomRowForwarder = new AndroidCustomRowForwarder();
+
   constructor(
     private readonly store: Store,
     private readonly nativeCommandsSender: NativeCommandsSender,
@@ -59,6 +62,8 @@ export class Commands {
       this.layoutTreeCrawler.crawl(overlayLayout, CommandName.SetRoot);
     });
 
+    this.androidCustomRowForwarder.forwardFromLayouts([root, ...modals, ...overlays]);
+
     const result = this.nativeCommandsSender.setRoot(commandId, { root, modals, overlays });
     return result;
   }
@@ -67,6 +72,8 @@ export class Commands {
     const input = cloneDeep(options);
     this.optionsProcessor.processDefaultOptions(input, CommandName.SetDefaultOptions);
 
+    this.androidCustomRowForwarder.forwardFromOptions(input);
+
     this.nativeCommandsSender.setDefaultOptions(input);
     this.commandsObserver.notify(CommandName.SetDefaultOptions, { options });
   }
@@ -82,6 +89,8 @@ export class Commands {
         `Navigation.mergeOptions was invoked on component with id: ${componentId} before it is mounted, this can cause UI issues and should be avoided.\n Use static options instead.`
       );
 
+    this.androidCustomRowForwarder.forwardFromOptions(input);
+
     this.nativeCommandsSender.mergeOptions(componentId, input);
     this.commandsObserver.notify(CommandName.MergeOptions, { componentId, options });
   }
@@ -101,6 +110,8 @@ export class Commands {
     this.commandsObserver.notify(CommandName.ShowModal, { commandId, layout: layoutNode });
     this.layoutTreeCrawler.crawl(layoutNode, CommandName.ShowModal);
 
+    this.androidCustomRowForwarder.forwardFromLayout(layoutNode);
+
     const result = this.nativeCommandsSender.showModal(commandId, layoutNode);
     return result;
   }
@@ -135,6 +146,8 @@ export class Commands {
     this.commandsObserver.notify(CommandName.Push, { commandId, componentId, layout });
     this.layoutTreeCrawler.crawl(layout, CommandName.Push);
 
+    this.androidCustomRowForwarder.forwardFromLayout(layout);
+
     const result = this.nativeCommandsSender.push(commandId, componentId, layout);
     return result;
   }
@@ -181,6 +194,8 @@ export class Commands {
       this.layoutTreeCrawler.crawl(layoutNode, CommandName.SetStackRoot);
     });
 
+    this.androidCustomRowForwarder.forwardFromLayouts(input);
+
     const result = this.nativeCommandsSender.setStackRoot(commandId, componentId, input);
     return result;
   }

package/src/index.ts

@@ -16,3 +16,4 @@ export * from './interfaces/NavigationFunctionComponent';
 export * from './interfaces/CommandName';
 export * from './interfaces/Processors';
 export * from './interfaces/ProcessorSubscription';
+export * from './linking/types';

package/src/interfaces/Options.ts

@@ -999,6 +999,54 @@ export interface OptionsBottomTabs {
    * Control the shadow of the Bottom tabs bar
    */
   shadow?: ShadowOptions;
+  /**
+   * Visual options for the floating row that hosts custom React-component
+   * bottom tab cells. Only takes effect when every `bottomTab.component`
+   * is set on that `bottomTabs` layout.
+   *
+   * Same JS shape on iOS and Android. iOS applies options via the native
+   * parser; Android receives them through `RNNBottomTabsCustomRowModule`.
+   */
+  customRow?: BottomTabsCustomRowOptions;
+}
+
+export interface BottomTabsCustomRowOptions {
+  /**
+   * Content height of the row in points (iOS) / dp (Android). Excludes
+   * safe-area inset. Total row height = `height` + safe bottom + `bottomMargin`.
+   *
+   * Default: native tab content height; on iOS 26+ an extra 18pt when omitted.
+   */
+  height?: number;
+  /**
+   * Solid background color for the row. When set, overrides
+   * `backgroundEffect`.
+   */
+  backgroundColor?: Color;
+  /**
+   * Visual effect for the row background.
+   * - `glass`: iOS 26+ `UIGlassEffect`.
+   * - `blur`: `UIBlurEffect` with `systemChromeMaterial`.
+   * - `none`: fully transparent.
+   *
+   * Default: `glass` on iOS 26+, `blur` on older versions.
+   */
+  backgroundEffect?: 'glass' | 'blur' | 'none';
+  /**
+   * Corner radius applied to the row's background.
+   * Default: 28 on iOS 26+, 0 below.
+   */
+  cornerRadius?: number;
+  /**
+   * Horizontal inset from the screen edges.
+   * Default: 16 on iOS 26+, 0 below.
+   */
+  horizontalMargin?: number;
+  /**
+   * Distance between the row's bottom edge and the safe-area bottom.
+   * Default: 0.
+   */
+  bottomMargin?: number;
 }
 
 export interface ShadowOptions {
@@ -1035,6 +1083,45 @@ export type ImageResource = ImageSourcePropType | string | ImageSystemSource;
 export interface OptionsBottomTab {
   dotIndicator?: DotIndicatorOptions;
 
+  /**
+   * Render a React component as the tab item content (icon + text area).
+   *
+   * When set, the native icon, text and font props (`text`, `icon`,
+   * `selectedIcon`, `sfSymbol`, `sfSelectedSymbol`, `iconColor`,
+   * `selectedIconColor`, `iconWidth`, `iconHeight`, `iconInsets`,
+   * `fontFamily`, `fontWeight`, `fontSize`, `selectedFontSize`,
+   * `textColor`, `selectedTextColor`) are ignored for that tab.
+   *
+   * For the custom rendering to take effect every tab in the
+   * `bottomTabs` layout must declare a `component`. If only some
+   * tabs declare one a warning is logged and native rendering is
+   * used for all tabs.
+   *
+   * The component receives the following initial props and
+   * subsequent prop updates:
+   * - `componentId`: stable id for this tab item instance
+   * - `tabIndex`: position of the tab (0-based)
+   * - `selected`: whether this tab is currently selected
+   * - `badge`: current badge text (mirrors `bottomTab.badge`)
+   *
+   * Native still owns selection, hide/show, drawBehind, animations
+   * and the dot indicator. To switch tabs from inside the component
+   * use `Navigation.mergeOptions(parentId, { bottomTabs: { currentTabIndex } })`.
+   */
+  component?: {
+    /**
+     * The registered name of the component (passed to
+     * `Navigation.registerComponent`).
+     */
+    name: string;
+    /**
+     * Props passed once when the component is created. Updates from
+     * native (`selected`, `badge`) are delivered as separate prop
+     * updates.
+     */
+    passProps?: object;
+  };
+
   /**
    * Set the text to display below the icon
    */
@@ -1574,6 +1661,11 @@ export interface AnimationOptions {
 export interface NavigationBarOptions {
   backgroundColor?: Color;
   visible?: boolean;
+  /**
+   * Draw screen content behind the system navigation bar while keeping it visible.
+   * On Android 15+ edge-to-edge, use with `backgroundColor: 'transparent'`.
+   */
+  drawBehind?: boolean;
 }
 
 /**

package/src/linking/DeferredLinkQueue.test.ts

@@ -0,0 +1,60 @@
+import { DeferredLinkQueue } from './DeferredLinkQueue';
+
+describe('DeferredLinkQueue', () => {
+  let uut: DeferredLinkQueue;
+  let flushed: string[];
+
+  beforeEach(() => {
+    uut = new DeferredLinkQueue();
+    flushed = [];
+    uut.setFlushCallback((url) => flushed.push(url));
+  });
+
+  it('starts not ready', () => {
+    expect(uut.isReady()).toBe(false);
+  });
+
+  it('enqueues URLs while not ready', () => {
+    uut.enqueue('myapp://a');
+    uut.enqueue('myapp://b');
+    expect(uut.pending()).toEqual(['myapp://a', 'myapp://b']);
+    expect(flushed).toEqual([]);
+  });
+
+  it('flushes queued URLs in order when becoming ready', () => {
+    uut.enqueue('myapp://a');
+    uut.enqueue('myapp://b');
+    uut.setReady(true);
+    expect(flushed).toEqual(['myapp://a', 'myapp://b']);
+    expect(uut.pending()).toEqual([]);
+  });
+
+  it('does not re-flush when already ready', () => {
+    uut.setReady(true);
+    uut.enqueue('myapp://a');
+    uut.setReady(true);
+    expect(flushed).toEqual([]);
+    expect(uut.pending()).toEqual(['myapp://a']);
+  });
+
+  it('flushes again after toggling not-ready → ready', () => {
+    uut.setReady(true);
+    uut.setReady(false);
+    uut.enqueue('myapp://x');
+    uut.setReady(true);
+    expect(flushed).toEqual(['myapp://x']);
+  });
+
+  it('clear() drops pending URLs', () => {
+    uut.enqueue('myapp://a');
+    uut.clear();
+    uut.setReady(true);
+    expect(flushed).toEqual([]);
+  });
+
+  it('flush() is a no-op when no callback is registered', () => {
+    const fresh = new DeferredLinkQueue();
+    fresh.enqueue('myapp://a');
+    expect(() => fresh.flush()).not.toThrow();
+  });
+});

package/src/linking/DeferredLinkQueue.ts

@@ -0,0 +1,55 @@
+/**
+ * Holds URLs while the linking pipeline is not ready and replays them in
+ * order once it becomes ready.
+ *
+ * Readiness is set by the owning `LinkingHandler` and reflects the combined
+ * state of:
+ *   - whether the first `setRoot` has resolved (so a modal can be presented),
+ *   - whether the user-supplied `isReady` predicate (if any) returns `true`.
+ */
+export class DeferredLinkQueue {
+  private queue: string[] = [];
+  private ready = false;
+  private flushCallback: ((url: string) => void) | null = null;
+
+  public setFlushCallback(callback: (url: string) => void): void {
+    this.flushCallback = callback;
+  }
+
+  public setReady(ready: boolean): void {
+    const becameReady = !this.ready && ready;
+    this.ready = ready;
+    if (becameReady) {
+      this.flush();
+    }
+  }
+
+  public isReady(): boolean {
+    return this.ready;
+  }
+
+  /**
+   * Enqueue a URL for later processing. Should only be called when the
+   * queue is not ready; the handler decides when to enqueue vs process.
+   */
+  public enqueue(url: string): void {
+    this.queue.push(url);
+  }
+
+  public flush(): void {
+    if (!this.flushCallback) return;
+    const pending = [...this.queue];
+    this.queue = [];
+    for (const url of pending) {
+      this.flushCallback(url);
+    }
+  }
+
+  public clear(): void {
+    this.queue = [];
+  }
+
+  public pending(): string[] {
+    return [...this.queue];
+  }
+}