Merge pull request Expensify#88589 from software-mansion-labs/collectioneur/dynamic-routes-optional-path-parameters

Author: mjasikowski

contributingGuides/NAVIGATION.md

@@ -750,11 +750,49 @@ KEYBOARD_SHORTCUTS: {
 > and makes it harder to reason about which screens can trigger a given flow.
 > When in doubt, prefer an explicit list.
 
-### Current limitations (work in progress)
+### Optional path parameters
 
-- **Optional path parameters:** Suffixes must not include optional path params (e.g. `a/:reportID?`). Required path parameters (e.g. `flag/:reportActionID`) and query parameters are supported - see [Dynamic routes with query parameters](#dynamic-routes-with-query-parameters).
+Dynamic route suffixes may declare optional path parameters by appending `?` to the parameter name.
+An optional parameter can be present or absent in the URL; when absent, the corresponding key is
+omitted from the navigation state's `params` (it is **not** set to `undefined`).
 
-If you try to use dynamic routes with optional path parameters now, you will either fail to navigate to the page at all or end up on a non-existent page, and the navigation will be broken.
+Optionals can appear anywhere in the suffix:
+
+- **Trailing optional:** `member-details/:accountID?` matches both `member-details` and `member-details/123`.
+- **Middle optional:** `wrap/:p?/end` matches both `wrap/end` and `wrap/x/end`.
+- **Multiple optionals:** `a/:p1?/b/:p2?` matches `a/b`, `a/x/b`, `a/b/y`, and `a/x/b/y`.
+
+#### Configuration example
+
+```ts
+DYNAMIC_ROUTES: {
+    MEMBER_DETAILS: {
+        path: 'member-details/:accountID?',
+        entryScreens: [SCREENS.WORKSPACE.MEMBERS],
+        getRoute: (accountID?: string) => (accountID ? `member-details/${accountID}` : 'member-details'),
+    },
+},
+```
+
+#### Precedence rules
+
+When several registered suffixes could match the same URL, the matcher uses a deterministic
+three-phase order. Each phase exhausts all sub-suffix lengths (longest to shortest) before the
+next phase begins:
+
+1. **Static beats everything.** All sub-suffix lengths are checked for an exact static match
+   first. A short static match (e.g. single-segment `country`) always beats a longer parametric
+   match (e.g. `:reportID/country`).
+2. **Strict parametric beats optional parametric.** After statics, all sub-suffix lengths are
+   checked for strict parametric patterns (no optional params, e.g. `flag/:reportID/:reportActionID`).
+   Only after those are exhausted does the matcher try optional parametric patterns
+   (e.g. `page/:id?`).
+3. **Longest match wins within each phase.** Within a single phase the algorithm iterates from
+   the longest candidate to the shortest, so a 3-segment match beats a 2-segment one when both
+   are registered.
+4. **Among patterns of the same kind: first registered wins.** If multiple patterns of the same
+   type (strict or optional) could match the same candidate, the one declared first in
+   `DYNAMIC_ROUTES` wins.
 
 ### Multi-segment dynamic routes
 

src/hooks/useDynamicBackPath.ts

@@ -1,17 +1,20 @@
+import findMatchingDynamicSuffix from '@libs/Navigation/helpers/dynamicRoutesUtils/findMatchingDynamicSuffix';
 import getPathWithoutDynamicSuffix from '@libs/Navigation/helpers/dynamicRoutesUtils/getPathWithoutDynamicSuffix';
-import matchPathPattern from '@libs/Navigation/helpers/dynamicRoutesUtils/matchPathPattern';
-import splitPathAndQuery from '@libs/Navigation/helpers/dynamicRoutesUtils/splitPathAndQuery';
 import getPathFromState from '@libs/Navigation/helpers/getPathFromState';
 import type {State} from '@libs/Navigation/types';
 import type {DynamicRouteSuffix, Route} from '@src/ROUTES';
 import ROUTES from '@src/ROUTES';
 import useRootNavigationState from './useRootNavigationState';
 
 /**
- * Returns the back path for a dynamic route by removing the dynamic suffix from the current URL.
- * Supports both static suffixes (exact string match) and parametric suffixes (pattern matching).
- * Only removes the suffix if it's the last segment(s) of the path.
- * @param dynamicRouteSuffix - The dynamic route suffix to remove from the current URL.
+ * Removes the given dynamic suffix from the end of the current URL to produce a "back" path.
+ *
+ * Supported suffix types: static (`/edit`), parametric (`/:reportID`),
+ * and parametric with optional params (`/:reportID/:reportActionID?`).
+ *
+ * If the suffix doesn't match the tail of the current path, returns the path as-is.
+ *
+ * @param dynamicRouteSuffix - The dynamic route pattern to remove from the current URL.
  * @returns The back path for the dynamic route.
  */
 function useDynamicBackPath(dynamicRouteSuffix: DynamicRouteSuffix): Route {
@@ -27,34 +30,12 @@ function useDynamicBackPath(dynamicRouteSuffix: DynamicRouteSuffix): Route {
         return ROUTES.HOME;
     }
 
-    // Remove leading slashes for consistent processing
-    const pathWithoutLeadingSlash = path.replace(/^\/+/, '');
-    const [normalizedPath] = splitPathAndQuery(pathWithoutLeadingSlash);
-
-    if (!normalizedPath) {
-        return pathWithoutLeadingSlash as Route;
-    }
-
-    // Fast path: exact string match (static suffixes)
-    if (normalizedPath.endsWith(`/${dynamicRouteSuffix}`)) {
-        return getPathWithoutDynamicSuffix(pathWithoutLeadingSlash, dynamicRouteSuffix);
-    }
-
-    // Parametric path: take the last N segments and try pattern matching
-    const patternSegmentCount = dynamicRouteSuffix.split('/').filter(Boolean).length;
-    const pathSegments = normalizedPath.split('/').filter(Boolean);
-
-    if (patternSegmentCount > 0 && patternSegmentCount <= pathSegments.length) {
-        const tailSegments = pathSegments.slice(-patternSegmentCount);
-        const tailCandidate = tailSegments.join('/');
-        const match = matchPathPattern(tailCandidate, dynamicRouteSuffix);
-
-        if (match) {
-            return getPathWithoutDynamicSuffix(pathWithoutLeadingSlash, tailCandidate, dynamicRouteSuffix);
-        }
+    const pathWithoutLeadingSlash = path.replaceAll(/^\/+/g, '');
+    const match = findMatchingDynamicSuffix(pathWithoutLeadingSlash);
+    if (match && match.pattern === dynamicRouteSuffix) {
+        return getPathWithoutDynamicSuffix(pathWithoutLeadingSlash, match.actualSuffix, match.pattern);
     }
 
-    // No match found - the suffix is not at the end of the current path.
     return pathWithoutLeadingSlash as Route;
 }
 

src/libs/Navigation/helpers/dynamicRoutesUtils/compileDynamicRoutePattern.ts

@@ -0,0 +1,96 @@
+import StringUtils from '@libs/StringUtils';
+import {DYNAMIC_ROUTES} from '@src/ROUTES';
+
+/**
+ * Compiles a dynamic-route suffix pattern (e.g. `flag/:reportID/:reportActionID?`) into a regex.
+ * Used to detect and strip dynamic suffixes from URL paths.
+ */
+
+type CompiledPattern = {
+    /** Original pattern string, e.g. `'a/:p?/b'`. */
+    pattern: string;
+
+    /** Compiled regex. */
+    regex: RegExp;
+
+    /** Names of all `:param` and `:param?` placeholders in declaration order. */
+    paramNames: string[];
+
+    /** Minimum number of URL segments that can satisfy this pattern (all optionals absent). */
+    minSegments: number;
+
+    /** Maximum number of URL segments that can satisfy this pattern (all optionals present). */
+    maxSegments: number;
+};
+
+function compileDynamicRoutePattern(pattern: string): CompiledPattern {
+    if (!pattern) {
+        throw new Error(`[compileDynamicRoutePattern] Pattern must be a non-empty string, got "${pattern}"`);
+    }
+
+    const segments = pattern.split('/');
+
+    // Reject patterns with empty segments (e.g. 'a//b'), but allow a trailing slash.
+    if (segments.some((s, i) => s === '' && i !== segments.length - 1)) {
+        throw new Error(`[compileDynamicRoutePattern] Pattern "${pattern}" contains an empty segment`);
+    }
+
+    const paramNames: string[] = [];
+    const seenParamNames = new Set<string>();
+    let minSegments = 0;
+    let maxSegments = 0;
+    let regexBody = '';
+
+    for (const segment of segments) {
+        if (segment === '') {
+            continue;
+        }
+
+        if (segment.startsWith(':')) {
+            const optional = segment.endsWith('?');
+            const name = optional ? segment.slice(1, -1) : segment.slice(1);
+
+            if (!name || name.includes(':')) {
+                throw new Error(`[compileDynamicRoutePattern] Pattern "${pattern}" contains a malformed param "${segment}"`);
+            }
+            if (seenParamNames.has(name)) {
+                throw new Error(`[compileDynamicRoutePattern] Pattern "${pattern}" declares duplicate param "${name}"`);
+            }
+            seenParamNames.add(name);
+            paramNames.push(name);
+
+            if (optional) {
+                regexBody += `(?:(?<${name}>[^/]+)\\/)?`;
+                maxSegments += 1;
+            } else {
+                regexBody += `(?<${name}>[^/]+)\\/`;
+                minSegments += 1;
+                maxSegments += 1;
+            }
+        } else {
+            regexBody += `${StringUtils.escapeRegExp(segment)}\\/`;
+            minSegments += 1;
+            maxSegments += 1;
+        }
+    }
+
+    if (paramNames.length === 0 && minSegments === 0) {
+        throw new Error(`[compileDynamicRoutePattern] Pattern "${pattern}" has no segments`);
+    }
+
+    const regex = new RegExp(`^${regexBody}$`);
+    return {pattern, regex, paramNames, minSegments, maxSegments};
+}
+
+type CompiledEntry = {key: string; compiled: CompiledPattern};
+
+const compiledParametricDynamicRoutes: CompiledEntry[] = Object.entries(DYNAMIC_ROUTES)
+    .filter(([, entry]) => entry.path.includes(':'))
+    .map(([key, entry]) => ({key, compiled: compileDynamicRoutePattern(entry.path)}));
+
+const compiledStrictParametricDynamicRoutes = compiledParametricDynamicRoutes.filter(({compiled}) => compiled.minSegments === compiled.maxSegments);
+const compiledOptionalParametricDynamicRoutes = compiledParametricDynamicRoutes.filter(({compiled}) => compiled.minSegments < compiled.maxSegments);
+
+export default compileDynamicRoutePattern;
+export {compiledStrictParametricDynamicRoutes, compiledOptionalParametricDynamicRoutes};
+export type {CompiledEntry};

src/libs/Navigation/helpers/dynamicRoutesUtils/findMatchingDynamicSuffix.ts

@@ -1,5 +1,6 @@
-import {dynamicRoutePaths, parametricEntriesBySegmentCount} from './isDynamicRouteSuffix';
-import matchPathPattern from './matchPathPattern';
+import type {CompiledEntry} from './compileDynamicRoutePattern';
+import {compiledOptionalParametricDynamicRoutes, compiledStrictParametricDynamicRoutes} from './compileDynamicRoutePattern';
+import {dynamicRoutePaths} from './isDynamicRouteSuffix';
 import splitPathAndQuery from './splitPathAndQuery';
 
 type DynamicSuffixMatch = {
@@ -11,11 +12,53 @@ type DynamicSuffixMatch = {
     pathParams: Record<string, string>;
 };
 
+/**
+ * Tries to match a candidate suffix against a list of compiled parametric patterns.
+ * Returns the first match with extracted path params, or undefined.
+ *
+ * @private - Internal helper. Do not export or use outside this file.
+ */
+function tryMatchParametric(candidate: string, candidateSegmentCount: number, patterns: CompiledEntry[]): DynamicSuffixMatch | undefined {
+    const normalized = candidate.endsWith('/') ? candidate : `${candidate}/`;
+
+    for (const {compiled} of patterns) {
+        if (candidateSegmentCount < compiled.minSegments || candidateSegmentCount > compiled.maxSegments) {
+            continue;
+        }
+        const match = compiled.regex.exec(normalized);
+        if (!match) {
+            continue;
+        }
+        const pathParams: Record<string, string> = {};
+        for (const name of compiled.paramNames) {
+            const value = match.groups?.[name];
+            if (value === undefined) {
+                continue;
+            }
+            try {
+                pathParams[name] = decodeURIComponent(value);
+            } catch {
+                pathParams[name] = value;
+            }
+        }
+        return {pattern: compiled.pattern, actualSuffix: candidate, pathParams};
+    }
+
+    return undefined;
+}
+
 /**
  * Finds a registered dynamic route suffix that matches the end of the given path.
- * Iterates path sub-suffixes from longest to shortest and checks each against
- * registered dynamic paths. Supports both exact static matches and parametric
- * pattern matches (e.g. 'flag/:reportID/:reportActionID').
+ *
+ * Uses three-phase matching with decreasing specificity. Each phase iterates
+ * all sub-suffixes from longest to shortest before the next phase begins:
+ *   1. Static matches (`dynamicRoutePaths` Set lookup).
+ *   2. Strict parametric patterns (no optional params).
+ *   3. Optional parametric patterns (has at least one `:param?`).
+ *
+ * This guarantees that any static match, even a short one, always beats
+ * a parametric match, and any strict-parametric match always beats an
+ * optional-parametric match.
  *
  * @param path - The path to find the matching dynamic suffix for
  * @returns The matching dynamic suffix, or undefined if no matching suffix is found
@@ -28,26 +71,27 @@ function findMatchingDynamicSuffix(path = ''): DynamicSuffixMatch | undefined {
 
     const segments = normalizedPath.split('/').filter(Boolean);
 
-    // Iterate from the full path (longest candidate) down to single-segment suffixes.
-    // This guarantees the longest matching suffix is returned first.
+    // Phase 1: Static matches (longest to shortest)
     for (let i = 0; i < segments.length; i++) {
         const candidate = segments.slice(i).join('/');
-
-        // Static match (e.g. 'country', 'verify-account')
         if (dynamicRoutePaths.has(candidate)) {
             return {pattern: candidate, actualSuffix: candidate, pathParams: {}};
         }
+    }
+
+    // Phase 2: Strict parametric patterns - no optional params (longest to shortest)
+    for (let i = 0; i < segments.length; i++) {
+        const result = tryMatchParametric(segments.slice(i).join('/'), segments.length - i, compiledStrictParametricDynamicRoutes);
+        if (result) {
+            return result;
+        }
+    }
 
-        // Parametric pattern match - only check patterns with the same segment count.
-        const candidateSegmentCount = segments.length - i;
-        const matchingEntries = parametricEntriesBySegmentCount.get(candidateSegmentCount);
-        if (matchingEntries) {
-            for (const entry of matchingEntries) {
-                const match = matchPathPattern(candidate, entry.path);
-                if (match) {
-                    return {pattern: entry.path, actualSuffix: candidate, pathParams: match.params};
-                }
-            }
+    // Phase 3: Optional parametric patterns - has at least one :param? (longest to shortest)
+    for (let i = 0; i < segments.length; i++) {
+        const result = tryMatchParametric(segments.slice(i).join('/'), segments.length - i, compiledOptionalParametricDynamicRoutes);
+        if (result) {
+            return result;
         }
     }
 

src/libs/Navigation/helpers/dynamicRoutesUtils/getStateForDynamicRoute.ts

@@ -67,10 +67,14 @@ function getStateForDynamicRoute(path: string, dynamicRouteName: keyof typeof DY
     const buildNestedState = (routes: string[], currentIndex: number): RouteNode => {
         const currentRoute = routes.at(currentIndex);
 
-        // If this is the last route, create leaf node with path and merged params
+        // If this is the last route, create leaf node with path and merged params.
+        // Filter out undefined values so absent optional path params don't surface as
+        // explicit `{key: undefined}` entries in the navigation state.
         if (currentIndex === routes.length - 1) {
-            const mergedParams = parentRouteParams || params ? {...(parentRouteParams ?? {}), ...(params ?? {})} : undefined;
-            const paramsSpread = mergedParams ? {params: mergedParams} : {};
+            const mergedParams = {...(parentRouteParams ?? {}), ...(params ?? {})};
+            const cleanedParams = Object.fromEntries(Object.entries(mergedParams).filter(([, v]) => v !== undefined));
+            const paramsSpread = cleanedParams && Object.keys(cleanedParams).length > 0 ? {params: cleanedParams} : {};
+
             return {
                 name: currentRoute ?? '',
                 path,