react-native-navigation 8.8.6 → 8.8.7

package/src/linking/LinkingHandler.test.ts

@@ -0,0 +1,332 @@
+import { LinkingHandler, LinkingAPI } from './LinkingHandler';
+import { LinkingConfig, RouteMatch } from './types';
+import { Layout } from '../interfaces/Layout';
+
+describe('LinkingHandler', () => {
+  let uut: LinkingHandler;
+  let mockShowModal: jest.Mock<Promise<string>, [Layout]>;
+  let mockLinking: jest.Mocked<LinkingAPI>;
+  let urlListener: ((event: { url: string }) => void) | null;
+
+  const baseConfig: LinkingConfig = {
+    prefixes: ['myapp://', 'https://myapp.com'],
+    config: {
+      screens: {
+        Home: 'home',
+        Profile: 'user/:id',
+        Settings: {
+          path: 'settings',
+          screens: { Notifications: 'notifications' },
+        },
+      },
+    },
+  };
+
+  beforeEach(() => {
+    mockShowModal = jest.fn().mockResolvedValue('modalId');
+    urlListener = null;
+    mockLinking = {
+      addEventListener: jest.fn((_type, handler) => {
+        urlListener = handler;
+        return { remove: jest.fn() };
+      }),
+      getInitialURL: jest.fn().mockResolvedValue(null),
+    } as unknown as jest.Mocked<LinkingAPI>;
+    uut = new LinkingHandler(mockShowModal, mockLinking);
+  });
+
+  afterEach(() => {
+    uut.teardown();
+  });
+
+  describe('resolve', () => {
+    beforeEach(() => uut.configure(baseConfig));
+
+    it('resolves a simple URL to a route match', () => {
+      expect(uut.resolve('myapp://home')).toEqual({
+        url: 'myapp://home',
+        path: [{ screen: 'Home', params: {} }],
+        queryParams: {},
+      });
+    });
+
+    it('resolves a URL with path params', () => {
+      expect(uut.resolve('myapp://user/42')).toEqual({
+        url: 'myapp://user/42',
+        path: [{ screen: 'Profile', params: { id: '42' } }],
+        queryParams: {},
+      });
+    });
+
+    it('resolves a nested route as a chain', () => {
+      const match = uut.resolve('myapp://settings/notifications');
+      expect(match?.path).toEqual([
+        { screen: 'Settings', params: {} },
+        { screen: 'Notifications', params: {} },
+      ]);
+    });
+
+    it('returns null when the prefix does not match', () => {
+      expect(uut.resolve('other://home')).toBeNull();
+    });
+
+    it('returns null when no route matches', () => {
+      expect(uut.resolve('myapp://unknown')).toBeNull();
+    });
+
+    it('returns null before configure() is called', () => {
+      const fresh = new LinkingHandler(mockShowModal, mockLinking);
+      expect(fresh.resolve('myapp://home')).toBeNull();
+    });
+  });
+
+  describe('default modal presentation', () => {
+    it('defers links until rootReady is signalled, then auto-flushes', () => {
+      uut.configure(baseConfig);
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).not.toHaveBeenCalled();
+      uut.setRootReady();
+      expect(mockShowModal).toHaveBeenCalledTimes(1);
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [{ component: { name: 'Home', passProps: {} } }],
+        },
+      });
+    });
+
+    it('processes links immediately once rootReady', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42');
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [{ component: { name: 'Profile', passProps: { id: '42' } } }],
+        },
+      });
+    });
+
+    it('builds a push chain inside the modal stack for nested matches', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.handleURL('myapp://settings/notifications');
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [
+            { component: { name: 'Settings', passProps: {} } },
+            { component: { name: 'Notifications', passProps: {} } },
+          ],
+        },
+      });
+    });
+
+    it('merges query params into passProps', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42?source=push');
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [
+            {
+              component: {
+                name: 'Profile',
+                passProps: { id: '42', source: 'push' },
+              },
+            },
+          ],
+        },
+      });
+    });
+
+    it('filters React-reserved query params from passProps', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42?ref=push&key=abc&utm=foo');
+      expect(mockShowModal).toHaveBeenCalledWith({
+        stack: {
+          children: [
+            {
+              component: {
+                name: 'Profile',
+                passProps: { id: '42', utm: 'foo' },
+              },
+            },
+          ],
+        },
+      });
+    });
+  });
+
+  describe('getModal override', () => {
+    it('uses the supplied builder instead of the default', () => {
+      const customLayout: Layout = {
+        component: { name: 'Custom' },
+      };
+      const getModal = jest.fn().mockReturnValue(customLayout);
+      uut.configure({ ...baseConfig, getModal });
+      uut.setRootReady();
+      uut.handleURL('myapp://home');
+      expect(getModal).toHaveBeenCalledTimes(1);
+      const passedMatch = getModal.mock.calls[0][0];
+      expect(passedMatch.path).toEqual([{ screen: 'Home', params: {} }]);
+      expect(mockShowModal).toHaveBeenCalledWith(customLayout);
+    });
+
+    it('skips presentation when getModal returns undefined', () => {
+      const getModal = jest.fn().mockReturnValue(undefined);
+      uut.configure({ ...baseConfig, getModal });
+      uut.setRootReady();
+      uut.handleURL('myapp://home');
+      expect(getModal).toHaveBeenCalled();
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onLink override', () => {
+    it('calls onLink and bypasses showModal entirely', () => {
+      const onLink = jest.fn();
+      uut.configure({ ...baseConfig, onLink });
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42');
+      expect(onLink).toHaveBeenCalledTimes(1);
+      const passedMatch = onLink.mock.calls[0][0];
+      expect(passedMatch.path).toEqual([{ screen: 'Profile', params: { id: '42' } }]);
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+
+    it('takes precedence over getModal', () => {
+      const onLink = jest.fn();
+      const getModal = jest.fn();
+      uut.configure({ ...baseConfig, onLink, getModal });
+      uut.setRootReady();
+      uut.handleURL('myapp://home');
+      expect(onLink).toHaveBeenCalled();
+      expect(getModal).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('fallback', () => {
+    it('is called when no prefix matches', () => {
+      const fallback = jest.fn();
+      uut.configure({ ...baseConfig, fallback });
+      uut.setRootReady();
+      uut.handleURL('other://home');
+      expect(fallback).toHaveBeenCalledWith('other://home');
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+
+    it('is called when no route matches', () => {
+      const fallback = jest.fn();
+      uut.configure({ ...baseConfig, fallback });
+      uut.setRootReady();
+      uut.handleURL('myapp://unknown');
+      expect(fallback).toHaveBeenCalledWith('myapp://unknown');
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+
+    it('is silent when not supplied', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      expect(() => uut.handleURL('myapp://unknown')).not.toThrow();
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('isReady predicate', () => {
+    it('queues links while isReady returns false', () => {
+      let ready = false;
+      uut.configure({ ...baseConfig, isReady: () => ready });
+      uut.setRootReady();
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).not.toHaveBeenCalled();
+      ready = true;
+      uut.setLinkingReady(true);
+      expect(mockShowModal).toHaveBeenCalledTimes(1);
+    });
+
+    it('setLinkingReady(true) overrides a false isReady', () => {
+      uut.configure({ ...baseConfig, isReady: () => false });
+      uut.setRootReady();
+      uut.setLinkingReady(true);
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).toHaveBeenCalled();
+    });
+
+    it('setLinkingReady(false) blocks even when isReady is absent', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      uut.setLinkingReady(false);
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Linking subscription', () => {
+    it('dispatches URL events through the pipeline', () => {
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      urlListener?.({ url: 'myapp://home' });
+      expect(mockShowModal).toHaveBeenCalled();
+    });
+
+    it('reads the initial URL on configure', async () => {
+      mockLinking.getInitialURL.mockResolvedValueOnce('myapp://home');
+      uut.configure(baseConfig);
+      uut.setRootReady();
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(mockShowModal).toHaveBeenCalled();
+    });
+
+    it('removes the listener on teardown', () => {
+      const remove = jest.fn();
+      (mockLinking.addEventListener as jest.Mock).mockReturnValueOnce({ remove });
+      uut.configure(baseConfig);
+      uut.teardown();
+      expect(remove).toHaveBeenCalled();
+    });
+
+    it('reconfiguring tears down the previous subscription', () => {
+      const remove = jest.fn();
+      (mockLinking.addEventListener as jest.Mock).mockReturnValueOnce({ remove });
+      uut.configure(baseConfig);
+      uut.configure(baseConfig);
+      expect(remove).toHaveBeenCalled();
+    });
+  });
+
+  describe('setRootReady', () => {
+    it('is idempotent', () => {
+      uut.configure(baseConfig);
+      uut.handleURL('myapp://home');
+      uut.setRootReady();
+      uut.setRootReady();
+      expect(mockShowModal).toHaveBeenCalledTimes(1);
+    });
+
+    it('persists across reconfigure', () => {
+      uut.setRootReady();
+      uut.configure(baseConfig);
+      uut.handleURL('myapp://home');
+      expect(mockShowModal).toHaveBeenCalled();
+    });
+  });
+
+  describe('match payload', () => {
+    it('passes the full match object to onLink', () => {
+      let captured: RouteMatch | null = null;
+      uut.configure({
+        ...baseConfig,
+        onLink: (match) => {
+          captured = match;
+        },
+      });
+      uut.setRootReady();
+      uut.handleURL('myapp://user/42?source=push');
+      expect(captured).toEqual({
+        url: 'myapp://user/42?source=push',
+        path: [{ screen: 'Profile', params: { id: '42' } }],
+        queryParams: { source: 'push' },
+      });
+    });
+  });
+});

package/src/linking/LinkingHandler.ts

@@ -0,0 +1,169 @@
+import { Linking } from 'react-native';
+import { Layout } from '../interfaces/Layout';
+import { URLParser } from './URLParser';
+import { RouteMatcher } from './RouteMatcher';
+import { DeferredLinkQueue } from './DeferredLinkQueue';
+import { ModalLayoutBuilder } from './ModalLayoutBuilder';
+import { LinkingConfig, RouteMatch } from './types';
+
+/** A function that shows a layout as a modal. Mirrors `Commands.showModal`. */
+export type ShowModal = (layout: Layout) => Promise<string>;
+
+/**
+ * Minimal abstraction over React Native's `Linking` module so the handler
+ * can be tested without touching native bindings.
+ */
+export interface LinkingAPI {
+  addEventListener(
+    type: 'url',
+    handler: (event: { url: string }) => void
+  ): { remove: () => void };
+  getInitialURL(): Promise<string | null>;
+}
+
+/**
+ * Orchestrates deep linking:
+ *
+ *   1. Subscribes to URL events from `Linking` and the initial URL.
+ *   2. Parses + matches each URL against the configured `screens` tree.
+ *   3. Defers processing until both:
+ *        - the first `setRoot` has resolved (so a modal can be presented), and
+ *        - the user-supplied `isReady` predicate (if any) returns `true`.
+ *   4. Resolves matches in this order:
+ *        - `onLink(match)` if provided (full escape hatch), else
+ *        - `getModal(match)` if provided, else
+ *        - the default `ModalLayoutBuilder` output.
+ *      Result is presented via `showModal`.
+ *   5. Calls `fallback(url)` when a URL has no matching prefix or route.
+ */
+export class LinkingHandler {
+  private readonly urlParser: URLParser;
+  private readonly routeMatcher: RouteMatcher;
+  private readonly deferredQueue: DeferredLinkQueue;
+  private readonly modalLayoutBuilder: ModalLayoutBuilder;
+  private readonly showModal: ShowModal;
+  private readonly linkingAPI: LinkingAPI;
+
+  private config: LinkingConfig | null = null;
+  private linkingSubscription: { remove: () => void } | null = null;
+  private rootReady = false;
+  private userReadyOverride: boolean | null = null;
+
+  constructor(showModal: ShowModal, linkingAPI?: LinkingAPI) {
+    this.urlParser = new URLParser();
+    this.routeMatcher = new RouteMatcher();
+    this.deferredQueue = new DeferredLinkQueue();
+    this.modalLayoutBuilder = new ModalLayoutBuilder();
+    this.showModal = showModal;
+    this.linkingAPI = linkingAPI || (Linking as unknown as LinkingAPI);
+    this.deferredQueue.setFlushCallback((url) => this.processURL(url));
+  }
+
+  public configure(config: LinkingConfig): void {
+    this.teardown();
+    this.config = config;
+
+    const tree = this.routeMatcher.buildRouteTree(config.config.screens);
+    this.routeMatcher.setRouteTree(tree);
+
+    this.refreshReady();
+    this.subscribe();
+  }
+
+  /**
+   * Manually feed a URL into the pipeline as if it came from the OS.
+   * Useful for URLs received from push notifications or other sources.
+   */
+  public handleURL(url: string): void {
+    if (!this.config) return;
+    if (!this.isReady()) {
+      this.deferredQueue.enqueue(url);
+      return;
+    }
+    this.processURL(url);
+  }
+
+  /**
+   * Called by `NavigationRoot` after the first `setRoot` resolves. Subsequent
+   * calls are no-ops.
+   */
+  public setRootReady(): void {
+    if (this.rootReady) return;
+    this.rootReady = true;
+    this.refreshReady();
+  }
+
+  /**
+   * Public toggle for the app-supplied readiness gate. Overrides the
+   * `config.isReady` predicate from the moment it's first called.
+   */
+  public setLinkingReady(ready: boolean): void {
+    this.userReadyOverride = ready;
+    this.refreshReady();
+  }
+
+  /**
+   * Resolve a URL to a `RouteMatch` without side effects. Returns `null`
+   * when the URL doesn't match any configured prefix or route.
+   */
+  public resolve(url: string): RouteMatch | null {
+    if (!this.config) return null;
+    const parsed = this.urlParser.parse(url, this.config.prefixes);
+    if (!parsed) return null;
+    return this.routeMatcher.match(parsed.path, url, parsed.queryParams);
+  }
+
+  public teardown(): void {
+    if (this.linkingSubscription) {
+      this.linkingSubscription.remove();
+      this.linkingSubscription = null;
+    }
+    this.deferredQueue.clear();
+    this.config = null;
+    this.userReadyOverride = null;
+  }
+
+  private subscribe(): void {
+    this.linkingSubscription = this.linkingAPI.addEventListener('url', (event) => {
+      this.handleURL(event.url);
+    });
+
+    this.linkingAPI.getInitialURL().then((url) => {
+      if (url) this.handleURL(url);
+    });
+  }
+
+  private processURL(url: string): void {
+    if (!this.config) return;
+
+    const match = this.resolve(url);
+    if (!match) {
+      this.config.fallback?.(url);
+      return;
+    }
+
+    if (this.config.onLink) {
+      this.config.onLink(match);
+      return;
+    }
+
+    const layout = this.config.getModal
+      ? this.config.getModal(match)
+      : this.modalLayoutBuilder.build(match);
+
+    if (layout) {
+      this.showModal(layout);
+    }
+  }
+
+  private isReady(): boolean {
+    if (!this.rootReady) return false;
+    if (this.userReadyOverride !== null) return this.userReadyOverride;
+    if (this.config?.isReady) return this.config.isReady();
+    return true;
+  }
+
+  private refreshReady(): void {
+    this.deferredQueue.setReady(this.isReady());
+  }
+}

package/src/linking/ModalLayoutBuilder.test.ts

@@ -0,0 +1,105 @@
+import { ModalLayoutBuilder } from './ModalLayoutBuilder';
+
+describe('ModalLayoutBuilder', () => {
+  let uut: ModalLayoutBuilder;
+
+  beforeEach(() => {
+    uut = new ModalLayoutBuilder();
+  });
+
+  it('wraps a single-segment match in a stack', () => {
+    const layout = uut.build({
+      url: 'myapp://home',
+      path: [{ screen: 'Home', params: {} }],
+      queryParams: {},
+    });
+    expect(layout).toEqual({
+      stack: {
+        children: [
+          {
+            component: { name: 'Home', passProps: {} },
+          },
+        ],
+      },
+    });
+  });
+
+  it('builds a push chain for multi-segment matches', () => {
+    const layout = uut.build({
+      url: 'myapp://settings/notifications',
+      path: [
+        { screen: 'Settings', params: {} },
+        { screen: 'Notifications', params: {} },
+      ],
+      queryParams: {},
+    });
+    expect(layout.stack?.children).toEqual([
+      { component: { name: 'Settings', passProps: {} } },
+      { component: { name: 'Notifications', passProps: {} } },
+    ]);
+  });
+
+  it('passes path params as passProps', () => {
+    const layout = uut.build({
+      url: 'myapp://user/42',
+      path: [{ screen: 'Profile', params: { id: '42' } }],
+      queryParams: {},
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({ id: '42' });
+  });
+
+  it('merges query params into every segment, with path params taking precedence', () => {
+    const layout = uut.build({
+      url: 'myapp://user/42?id=99&source=push',
+      path: [{ screen: 'Profile', params: { id: '42' } }],
+      queryParams: { id: '99', source: 'push' },
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({
+      id: '42',
+      source: 'push',
+    });
+  });
+
+  it('applies query params to every segment of a nested match', () => {
+    const layout = uut.build({
+      url: 'myapp://settings/notifications?source=push',
+      path: [
+        { screen: 'Settings', params: {} },
+        { screen: 'Notifications', params: {} },
+      ],
+      queryParams: { source: 'push' },
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({ source: 'push' });
+    expect(layout.stack?.children?.[1].component?.passProps).toEqual({ source: 'push' });
+  });
+
+  it('filters the React-reserved "ref" query param from passProps', () => {
+    const layout = uut.build({
+      url: 'myapp://user/42?ref=notification&utm=push',
+      path: [{ screen: 'Profile', params: { id: '42' } }],
+      queryParams: { ref: 'notification', utm: 'push' },
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({
+      id: '42',
+      utm: 'push',
+    });
+  });
+
+  it('filters the React-reserved "key" query param from passProps', () => {
+    const layout = uut.build({
+      url: 'myapp://home?key=abc',
+      path: [{ screen: 'Home', params: {} }],
+      queryParams: { key: 'abc' },
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({});
+  });
+
+  it('filters reserved keys when they appear as path params too', () => {
+    const layout = uut.build({
+      url: 'myapp://r/abc',
+      path: [{ screen: 'Home', params: { ref: 'abc' } }],
+      queryParams: {},
+    });
+    expect(layout.stack?.children?.[0].component?.passProps).toEqual({});
+  });
+});

package/src/linking/ModalLayoutBuilder.ts

@@ -0,0 +1,60 @@
+import { Layout } from '../interfaces/Layout';
+import { RouteMatch, RouteMatchSegment } from './types';
+
+/**
+ * Props that React treats specially and must never be forwarded as
+ * regular component props. If a URL contains query parameters or path
+ * parameters using these names, they are dropped from `passProps`
+ * (with a dev-mode warning) to avoid crashing the screen.
+ */
+const RESERVED_PROP_NAMES = new Set(['ref', 'key']);
+
+/**
+ * Builds the default modal layout for a matched deep link.
+ *
+ * Behavior:
+ *   - Wraps the matched chain in a `stack`. Even a single-component match
+ *     gets wrapped so the screen has a topBar where the user can mount a
+ *     close button via `topBar.leftButtons`.
+ *   - Each segment becomes a `component` child of the stack, in match order.
+ *     The first segment is the root of the stack; subsequent segments are
+ *     pushed on top.
+ *   - Path params for each segment are merged with query params and passed
+ *     as `passProps` to that segment's component. Path params win on key
+ *     collision. React-reserved keys (`ref`, `key`) are filtered out.
+ */
+export class ModalLayoutBuilder {
+  public build(match: RouteMatch): Layout {
+    return {
+      stack: {
+        children: match.path.map((segment) => ({
+          component: {
+            name: segment.screen,
+            passProps: this.mergeProps(segment, match.queryParams),
+          },
+        })),
+      },
+    };
+  }
+
+  private mergeProps(
+    segment: RouteMatchSegment,
+    queryParams: Record<string, string>
+  ): Record<string, string> {
+    const merged: Record<string, string> = { ...queryParams, ...segment.params };
+    const safe: Record<string, string> = {};
+    for (const key of Object.keys(merged)) {
+      if (RESERVED_PROP_NAMES.has(key)) {
+        if (__DEV__) {
+          console.warn(
+            `[RNN linking] Dropping reserved prop "${key}" from passProps for screen "${segment.screen}". ` +
+              `Rename the URL parameter to avoid conflicting with React-reserved names.`
+          );
+        }
+        continue;
+      }
+      safe[key] = merged[key];
+    }
+    return safe;
+  }
+}