From ef67a090ec5f9804c3db4bf61240d6b56d078d00 Mon Sep 17 00:00:00 2001
From: Nadeem Iqbal <mr_nadeem_iqbal@yahoo.com>
Date: Sun, 17 May 2026 18:25:41 +0500
Subject: [PATCH 1/2] [go_router] docs: Document regex constraints on path
 parameters

GoRoute.path supports constraining a path parameter to a regular expression
via the :name(regex) syntax (parsed in path_utils.dart by _parameterRegExp
and patternToRegExp), but the feature was undocumented; users found it only
by trawling issues such as flutter/flutter#143070 and flutter/flutter#107240.

Add a paragraph to GoRoute.path's dartdoc describing the supported syntax,
explaining the matching semantics (segments that fail the pattern fall
through), and noting the constraint that the regex must not introduce its
own capturing groups.

Fixes flutter/flutter#177766.
---
 packages/go_router/lib/src/route.dart | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/packages/go_router/lib/src/route.dart b/packages/go_router/lib/src/route.dart
index cf1a7e240827..40dfaae63001 100644
--- a/packages/go_router/lib/src/route.dart
+++ b/packages/go_router/lib/src/route.dart
@@ -361,6 +361,15 @@ class GoRoute extends RouteBase {
   /// `/family/456` and etc. The parameter values are stored in [GoRouterState]
   /// that are passed into [pageBuilder] and [builder].
   ///
+  /// A path parameter may optionally be constrained to a regular expression
+  /// by appending the expression in parentheses after the parameter name:
+  /// `:paramName(regex)`. The parameter only matches if the corresponding path
+  /// segment also matches the regular expression — segments that fail the
+  /// pattern fall through to other route candidates. For example,
+  /// `/users/:id(\d+)` matches `/users/42` but not `/users/alice`. The
+  /// expression must not introduce its own capturing groups; everything
+  /// between the parentheses is interpreted as a Dart [RegExp] body.
+  ///
   /// The query parameter are also capture during the route parsing and stored
   /// in [GoRouterState].
   ///

From 822e01f9365be12a5b6f7a0f40f85a1e2bdd808d Mon Sep 17 00:00:00 2001
From: Nadeem Iqbal <mr_nadeem_iqbal@yahoo.com>
Date: Sun, 17 May 2026 22:52:26 +0500
Subject: [PATCH 2/2] [go_router] docs: Use "nested parentheses" wording in
 regex path param doc

Address review feedback (#11722): the parser disallows un-escaped nested
parentheses (per `_parameterRegExp`'s `[^\\()]` class) and additionally
escapes `:`, `=`, and `!`, which also prevents non-capturing groups and
lookarounds. Saying the expression "must not contain nested parentheses"
captures the actual constraint more accurately than "must not introduce
its own capturing groups".
---
 packages/go_router/lib/src/route.dart | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/go_router/lib/src/route.dart b/packages/go_router/lib/src/route.dart
index 40dfaae63001..b68f1cd64fa4 100644
--- a/packages/go_router/lib/src/route.dart
+++ b/packages/go_router/lib/src/route.dart
@@ -367,8 +367,8 @@ class GoRoute extends RouteBase {
   /// segment also matches the regular expression — segments that fail the
   /// pattern fall through to other route candidates. For example,
   /// `/users/:id(\d+)` matches `/users/42` but not `/users/alice`. The
-  /// expression must not introduce its own capturing groups; everything
-  /// between the parentheses is interpreted as a Dart [RegExp] body.
+  /// expression must not contain nested parentheses; everything between the
+  /// outer parentheses is interpreted as a Dart [RegExp] body.
   ///
   /// The query parameter are also capture during the route parsing and stored
   /// in [GoRouterState].