react-native-navigation 8.8.6 → 8.8.7-snapshot.2601

package/src/linking/RouteMatcher.test.ts

@@ -0,0 +1,128 @@
+import { RouteMatcher } from './RouteMatcher';
+import { ScreensConfig } from './types';
+
+describe('RouteMatcher', () => {
+  let uut: RouteMatcher;
+
+  beforeEach(() => {
+    uut = new RouteMatcher();
+  });
+
+  function configure(screens: ScreensConfig) {
+    uut.setRouteTree(uut.buildRouteTree(screens));
+  }
+
+  it('matches a flat route', () => {
+    configure({ Home: 'home' });
+    expect(uut.match('home', 'myapp://home', {})).toEqual({
+      url: 'myapp://home',
+      path: [{ screen: 'Home', params: {} }],
+      queryParams: {},
+    });
+  });
+
+  it('extracts a single path parameter', () => {
+    configure({ Profile: 'user/:id' });
+    expect(uut.match('user/42', 'myapp://user/42', {})).toEqual({
+      url: 'myapp://user/42',
+      path: [{ screen: 'Profile', params: { id: '42' } }],
+      queryParams: {},
+    });
+  });
+
+  it('extracts multiple path parameters', () => {
+    configure({ Post: 'user/:userId/post/:postId' });
+    const result = uut.match('user/5/post/99', 'myapp://user/5/post/99', {});
+    expect(result?.path[0].params).toEqual({ userId: '5', postId: '99' });
+  });
+
+  it('returns null when no route matches', () => {
+    configure({ Home: 'home' });
+    expect(uut.match('unknown', 'myapp://unknown', {})).toBeNull();
+  });
+
+  it('returns null when path is longer than any pattern', () => {
+    configure({ Home: 'home' });
+    expect(uut.match('home/extra', 'myapp://home/extra', {})).toBeNull();
+  });
+
+  it('matches the first registered route on ambiguity', () => {
+    configure({
+      Profile: 'user/:id',
+      User: 'user/:userId',
+    });
+    const result = uut.match('user/42', 'myapp://user/42', {});
+    expect(result?.path[0].screen).toBe('Profile');
+  });
+
+  it('matches a nested route as a chain', () => {
+    configure({
+      Settings: {
+        path: 'settings',
+        screens: { Notifications: 'notifications' },
+      },
+    });
+    expect(uut.match('settings/notifications', 'myapp://settings/notifications', {})).toEqual({
+      url: 'myapp://settings/notifications',
+      path: [
+        { screen: 'Settings', params: {} },
+        { screen: 'Notifications', params: {} },
+      ],
+      queryParams: {},
+    });
+  });
+
+  it('matches a parent-only nested route', () => {
+    configure({
+      Settings: {
+        path: 'settings',
+        screens: { Notifications: 'notifications' },
+      },
+    });
+    expect(uut.match('settings', 'myapp://settings', {})).toEqual({
+      url: 'myapp://settings',
+      path: [{ screen: 'Settings', params: {} }],
+      queryParams: {},
+    });
+  });
+
+  it('supports grouping nodes that consume no segments', () => {
+    configure({
+      Main: {
+        screens: {
+          Feed: 'feed',
+          Search: 'search',
+        },
+      },
+    });
+    const result = uut.match('feed', 'myapp://feed', {});
+    expect(result?.path).toEqual([
+      { screen: 'Main', params: {} },
+      { screen: 'Feed', params: {} },
+    ]);
+  });
+
+  it('passes query params through to the match result', () => {
+    configure({ Home: 'home' });
+    const result = uut.match('home', 'myapp://home?ref=push', { ref: 'push' });
+    expect(result?.queryParams).toEqual({ ref: 'push' });
+  });
+
+  it('returns null when no route tree has been configured', () => {
+    expect(uut.match('home', 'myapp://home', {})).toBeNull();
+  });
+
+  it('matches nested params at multiple levels', () => {
+    configure({
+      Org: {
+        path: 'org/:orgId',
+        screens: { Project: 'project/:projectId' },
+      },
+    });
+    const result = uut.match('org/1/project/2', 'myapp://org/1/project/2', {});
+    expect(result?.path).toEqual([
+      { screen: 'Org', params: { orgId: '1' } },
+      { screen: 'Project', params: { projectId: '2' } },
+    ]);
+  });
+});

package/src/linking/RouteMatcher.ts

@@ -0,0 +1,126 @@
+import {
+  ScreensConfig,
+  ScreenConfig,
+  RouteNode,
+  RouteMatch,
+  RouteMatchSegment,
+} from './types';
+
+/**
+ * Compiles a `screens` config into a tree of `RouteNode`s and resolves
+ * parsed paths to a matched `RouteMatch`.
+ *
+ * Matching is depth-first, in insertion order. The first node whose pattern
+ * (and nested children) consume the entire path wins.
+ */
+export class RouteMatcher {
+  private routeTree: RouteNode[] | null = null;
+
+  public buildRouteTree(screens: ScreensConfig): RouteNode[] {
+    const nodes: RouteNode[] = [];
+    for (const [screenName, config] of Object.entries(screens)) {
+      nodes.push(this.buildNode(screenName, config));
+    }
+    return nodes;
+  }
+
+  public setRouteTree(tree: RouteNode[]): void {
+    this.routeTree = tree;
+  }
+
+  /**
+   * Match a parsed path (e.g. `"user/42"`) against the configured tree.
+   * Returns the matched chain or `null` when no route matches.
+   */
+  public match(
+    path: string,
+    url: string,
+    queryParams: Record<string, string>
+  ): RouteMatch | null {
+    if (!this.routeTree) return null;
+
+    const pathSegments = path.split('/').filter((s) => s.length > 0);
+    const result = this.matchRecursive(pathSegments, 0, this.routeTree);
+    if (!result) return null;
+
+    return { url, path: result, queryParams };
+  }
+
+  private buildNode(screenName: string, config: ScreenConfig): RouteNode {
+    if (typeof config === 'string') {
+      return {
+        screen: screenName,
+        pattern: config,
+        segments: this.splitPattern(config),
+        children: [],
+      };
+    }
+
+    const children = config.screens ? this.buildRouteTree(config.screens) : [];
+    return {
+      screen: screenName,
+      pattern: config.path ?? null,
+      segments: config.path ? this.splitPattern(config.path) : [],
+      children,
+    };
+  }
+
+  private splitPattern(pattern: string): string[] {
+    return pattern.split('/').filter((s) => s.length > 0);
+  }
+
+  private matchRecursive(
+    pathSegments: string[],
+    offset: number,
+    nodes: RouteNode[]
+  ): RouteMatchSegment[] | null {
+    for (const node of nodes) {
+      const result = this.tryMatchNode(pathSegments, offset, node);
+      if (result) return result;
+    }
+    return null;
+  }
+
+  private tryMatchNode(
+    pathSegments: string[],
+    offset: number,
+    node: RouteNode
+  ): RouteMatchSegment[] | null {
+    if (node.pattern === null && node.segments.length === 0) {
+      if (node.children.length === 0) return null;
+      const childMatch = this.matchRecursive(pathSegments, offset, node.children);
+      if (!childMatch) return null;
+      return [{ screen: node.screen, params: {} }, ...childMatch];
+    }
+
+    const patternSegments = node.segments;
+    if (offset + patternSegments.length > pathSegments.length) {
+      return null;
+    }
+
+    const params: Record<string, string> = {};
+    for (let i = 0; i < patternSegments.length; i++) {
+      const pattern = patternSegments[i];
+      const actual = pathSegments[offset + i];
+      if (pattern.startsWith(':')) {
+        params[pattern.slice(1)] = actual;
+      } else if (pattern !== actual) {
+        return null;
+      }
+    }
+
+    const newOffset = offset + patternSegments.length;
+    const segment: RouteMatchSegment = { screen: node.screen, params };
+
+    if (newOffset === pathSegments.length) {
+      return [segment];
+    }
+
+    if (node.children.length > 0) {
+      const childMatch = this.matchRecursive(pathSegments, newOffset, node.children);
+      if (childMatch) return [segment, ...childMatch];
+    }
+
+    return null;
+  }
+}

package/src/linking/URLParser.test.ts

@@ -0,0 +1,105 @@
+import { URLParser } from './URLParser';
+
+describe('URLParser', () => {
+  let uut: URLParser;
+
+  beforeEach(() => {
+    uut = new URLParser();
+  });
+
+  describe('stripPrefix', () => {
+    it('returns the remainder after the matching prefix', () => {
+      expect(uut.stripPrefix('myapp://home', ['myapp://'])).toBe('home');
+    });
+
+    it('returns null when no prefix matches', () => {
+      expect(uut.stripPrefix('other://home', ['myapp://'])).toBeNull();
+    });
+
+    it('chooses the longest matching prefix', () => {
+      const result = uut.stripPrefix('https://myapp.com/v2/home', [
+        'https://myapp.com',
+        'https://myapp.com/v2',
+      ]);
+      expect(result).toBe('/home');
+    });
+  });
+
+  describe('parse', () => {
+    const prefixes = ['myapp://', 'https://myapp.com'];
+
+    it('returns null when no prefix matches', () => {
+      expect(uut.parse('other://home', prefixes)).toBeNull();
+    });
+
+    it('parses a simple path', () => {
+      expect(uut.parse('myapp://home', prefixes)).toEqual({
+        path: 'home',
+        queryParams: {},
+      });
+    });
+
+    it('trims leading and trailing slashes', () => {
+      expect(uut.parse('myapp:///home/', prefixes)).toEqual({
+        path: 'home',
+        queryParams: {},
+      });
+    });
+
+    it('parses query parameters', () => {
+      expect(uut.parse('myapp://search?q=hello&page=2', prefixes)).toEqual({
+        path: 'search',
+        queryParams: { q: 'hello', page: '2' },
+      });
+    });
+
+    it('decodes URL-encoded path segments', () => {
+      expect(uut.parse('myapp://hello%20world', prefixes)).toEqual({
+        path: 'hello world',
+        queryParams: {},
+      });
+    });
+
+    it('decodes URL-encoded query parameter keys and values', () => {
+      expect(uut.parse('myapp://search?q=hello%20world&a%20b=c', prefixes)).toEqual({
+        path: 'search',
+        queryParams: { q: 'hello world', 'a b': 'c' },
+      });
+    });
+
+    it('strips fragments before parsing the query', () => {
+      expect(uut.parse('myapp://home?x=1#section', prefixes)).toEqual({
+        path: 'home',
+        queryParams: { x: '1' },
+      });
+    });
+
+    it('strips fragments when there is no query string', () => {
+      expect(uut.parse('myapp://home#section', prefixes)).toEqual({
+        path: 'home',
+        queryParams: {},
+      });
+    });
+
+    it('treats query keys without values as empty strings', () => {
+      expect(uut.parse('myapp://home?flag', prefixes)).toEqual({
+        path: 'home',
+        queryParams: { flag: '' },
+      });
+    });
+
+    it('handles malformed encoding without throwing', () => {
+      expect(uut.parse('myapp://%E0%A4%A', prefixes)).toEqual({
+        path: '%E0%A4%A',
+        queryParams: {},
+      });
+    });
+
+    it('keeps "=" inside values intact', () => {
+      expect(uut.parse('myapp://search?token=a=b=c', prefixes)).toEqual({
+        path: 'search',
+        queryParams: { token: 'a=b=c' },
+      });
+    });
+  });
+});

package/src/linking/URLParser.ts

@@ -0,0 +1,62 @@
+import { ParsedURL } from './types';
+
+/**
+ * Parses a URL string against a list of configured prefixes.
+ *
+ * Responsibilities:
+ *   - Strip the longest matching prefix (or report no match).
+ *   - Drop any `#fragment` portion.
+ *   - Decode each path segment so literal patterns compare against decoded
+ *     text (e.g. `hello%20world` matches a `hello world` pattern segment).
+ *   - Parse the query string into a plain key/value map.
+ */
+export class URLParser {
+  public stripPrefix(url: string, prefixes: string[]): string | null {
+    const sorted = [...prefixes].sort((a, b) => b.length - a.length);
+    for (const prefix of sorted) {
+      if (url.startsWith(prefix)) {
+        return url.slice(prefix.length);
+      }
+    }
+    return null;
+  }
+
+  public parse(url: string, prefixes: string[]): ParsedURL | null {
+    const stripped = this.stripPrefix(url, prefixes);
+    if (stripped === null) {
+      return null;
+    }
+
+    const withoutFragment = stripped.split('#', 1)[0];
+    const [pathPart, queryPart] = withoutFragment.split('?', 2);
+
+    const path = pathPart
+      .split('/')
+      .filter((s) => s.length > 0)
+      .map((segment) => safeDecode(segment))
+      .join('/');
+
+    const queryParams: Record<string, string> = {};
+    if (queryPart) {
+      for (const pair of queryPart.split('&')) {
+        if (!pair) continue;
+        const eqIndex = pair.indexOf('=');
+        const rawKey = eqIndex === -1 ? pair : pair.slice(0, eqIndex);
+        const rawValue = eqIndex === -1 ? '' : pair.slice(eqIndex + 1);
+        const key = safeDecode(rawKey);
+        if (!key) continue;
+        queryParams[key] = safeDecode(rawValue);
+      }
+    }
+
+    return { path, queryParams };
+  }
+}
+
+function safeDecode(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}

package/src/linking/types.ts

@@ -0,0 +1,115 @@
+import { Layout } from '../interfaces/Layout';
+
+/**
+ * A single matched segment of a deep link route.
+ */
+export interface RouteMatchSegment {
+  /** Name of the registered RNN component this segment maps to. */
+  screen: string;
+  /** Path parameters extracted from this segment's pattern (e.g. `:id`). */
+  params: Record<string, string>;
+}
+
+/**
+ * Result of matching a URL against the configured `screens` tree.
+ */
+export interface RouteMatch {
+  /** Original URL that was matched. */
+  url: string;
+  /**
+   * Ordered chain of matched screens, from outermost to innermost.
+   * For a nested route like `settings/notifications`, this contains
+   * `[{ screen: 'Settings' }, { screen: 'Notifications' }]`.
+   */
+  path: RouteMatchSegment[];
+  /** Query string parameters from the URL. */
+  queryParams: Record<string, string>;
+}
+
+/**
+ * Internal representation of a parsed URL after prefix stripping.
+ */
+export interface ParsedURL {
+  /** Decoded path with leading/trailing slashes removed. */
+  path: string;
+  /** Query string parameters. */
+  queryParams: Record<string, string>;
+}
+
+/**
+ * Internal compiled representation of a single screen entry in the route tree.
+ */
+export interface RouteNode {
+  /** Screen name (the key from `screens`). */
+  screen: string;
+  /** Path pattern as written by the user, or `null` for grouping nodes. */
+  pattern: string | null;
+  /** Pattern split into segments, ready for matching. */
+  segments: string[];
+  /** Nested children. */
+  children: RouteNode[];
+}
+
+/**
+ * Per-screen configuration. Either a path pattern string, or an object with
+ * an optional path and nested screens.
+ *
+ * Examples:
+ *   `'home'`                                   - leaf route
+ *   `'user/:id'`                               - leaf with path parameter
+ *   `{ path: 'settings', screens: {...} }`     - nested route
+ *   `{ screens: {...} }`                       - grouping node (no path)
+ */
+export type ScreenConfig =
+  | string
+  | {
+      path?: string;
+      screens?: ScreensConfig;
+    };
+
+export interface ScreensConfig {
+  [screenName: string]: ScreenConfig;
+}
+
+/**
+ * Configuration passed to `Navigation.setLinking`.
+ *
+ * When a deep link is received, RNN parses it, matches it against the
+ * `screens` tree, and by default presents the matched chain as a modal
+ * (wrapped in a stack so a topBar is available for a close button).
+ *
+ * To customize the modal layout, provide `getModal`. To bypass the modal
+ * behavior entirely (e.g. push onto an existing stack), provide `onLink`.
+ */
+export interface LinkingConfig {
+  /** URL prefixes your app handles (custom schemes and universal-link hosts). */
+  prefixes: string[];
+  /** Screen-to-path mapping. */
+  config: {
+    screens: ScreensConfig;
+  };
+  /**
+   * Customize the modal layout for a matched route. Return `undefined` to
+   * skip presenting a modal for this match (useful for conditional skipping).
+   * When omitted, the default builder wraps the matched chain in a stack.
+   */
+  getModal?: (match: RouteMatch) => Layout | undefined;
+  /**
+   * Full escape hatch. When provided, RNN does not present a modal; the
+   * handler is responsible for executing whatever navigation commands it
+   * wants (push, setRoot, dismissAllModals + showModal, etc.).
+   * When set, `getModal` is ignored.
+   */
+  onLink?: (match: RouteMatch) => void;
+  /**
+   * Called when a received URL does not match any configured route or has
+   * no matching prefix. Useful for logging or routing to a "not found" flow.
+   */
+  fallback?: (url: string) => void;
+  /**
+   * Predicate evaluated before each link is processed. When it returns
+   * `false`, the link is queued and replayed once `setLinkingReady(true)`
+   * is called. Use this to defer links until e.g. authentication completes.
+   */
+  isReady?: () => boolean;
+}