Commit 77c1dd6e2d9 for woocommerce

commit 77c1dd6e2d9b32965865cd4a913bc6bea820d0ad
Author: Justin P <228780+layoutd@users.noreply.github.com>
Date:   Thu Oct 22 10:29:35 2026 +0200

    Clarify how getNewPath uses its path argument (#69989)

    * Clarify that getNewPath uses the path argument as-is

    * Add changelog entry for navigation path docs

    * Fix navigation README lint issues and stale signatures, clarify navigateTo url doc

    * Shorten changelog comment for navigation path docs

    * Type the onQueryChange query parameter as an object in its JSDoc

diff --git a/packages/js/navigation/README.md b/packages/js/navigation/README.md
index f77456cc164..3a81517c43d 100644
--- a/packages/js/navigation/README.md
+++ b/packages/js/navigation/README.md
@@ -28,123 +28,138 @@ render() {
 }
 ```

-### getPath() ⇒ <code>String</code>
+### getPath() ⇒ `String`
+
 Get the current path from history.

-**Returns**: <code>String</code> - Current path.
+**Returns**: `String` - Current path.
+
+### getTimeRelatedQuery(query) ⇒ `Object`

-### getTimeRelatedQuery(query) ⇒ <code>Object</code>
 Gets time related parameters from a query.

-**Returns**: <code>Object</code> - Object containing the time related queries.
+**Returns**: `Object` - Object containing the time related queries.

 | Param | Type | Description |
 | --- | --- | --- |
-| query | <code>Object</code> | Query containing the parameters. |
+| query | `Object` | Query containing the parameters. |
+
+### getIdsFromQuery(queryString) ⇒ `Array`

-### getIdsFromQuery(queryString) ⇒ <code>Array</code>
 Get an array of IDs from a comma-separated query parameter.

-**Returns**: <code>Array</code> - List of IDs converted to an array of unique integers.
+**Returns**: `Array` - List of IDs converted to an array of unique integers.

 | Param | Type | Description |
 | --- | --- | --- |
-| queryString | <code>string</code> | string value extracted from URL. |
+| queryString | `string` | string value extracted from URL. |
+
+### getNewPath(query, path, currentQuery, page) ⇒ `String`

-### getNewPath(query, path, currentQuery) ⇒ <code>String</code>
 Return a URL with set query parameters.

-**Returns**: <code>String</code> - Updated URL merging query params into existing params.
+**Returns**: `String` - Updated URL merging query params into existing params.

 | Param | Type | Description |
 | --- | --- | --- |
-| query | <code>Object</code> | object of params to be updated. |
-| path | <code>String</code> | Relative path (defaults to current path). |
-| currentQuery | <code>Object</code> | object of current query params (defaults to current querystring). |
+| query | `Object` | object of params to be updated. |
+| path | `String` | Admin page path, e.g. `/analytics/orders` (defaults to the current path). Used as-is for the `path` query arg; `./` and `../` segments are not resolved against the current path. |
+| currentQuery | `Object` | object of current query params (defaults to current querystring). |
+| page | `String` | Page key (defaults to "wc-admin"). |
+
+### getQuery() ⇒ `Object`

-### getQuery() ⇒ <code>Object</code>
 Get the current query string, parsed into an object, from history.

-**Returns**: <code>Object</code> - Current query object, defaults to empty object.
+**Returns**: `Object` - Current query object, defaults to empty object.
+
+### onQueryChange(param, path, query) ⇒ `function`

-### onQueryChange(param, path, query) ⇒ <code>function</code>
 This function returns an event handler for the given `param`

-**Returns**: <code>function</code> - A callback which will update `param` to the passed value when called.
+**Returns**: `function` - A callback which will update `param` to the passed value when called.

 | Param | Type | Description |
 | --- | --- | --- |
-| param | <code>string</code> | The parameter in the querystring which should be updated (ex `page`, `per_page`) |
-| path | <code>string</code> | Relative path (defaults to current path). |
-| query | <code>string</code> | object of current query params (defaults to current querystring). |
+| param | `string` | The parameter in the querystring which should be updated (ex `page`, `per_page`) |
+| path | `string` | Admin page path, e.g. `/analytics/orders` (defaults to the current path). Used as-is for the `path` query arg; `./` and `../` segments are not resolved against the current path. |
+| query | `Object` | object of current query params (defaults to current querystring). |
+
+### updateQueryString(query, path, currentQuery, page)

-### updateQueryString(query, path, currentQuery)
 Updates the query parameters of the current page.

 | Param | Type | Description |
 | --- | --- | --- |
-| query | <code>Object</code> | object of params to be updated. |
-| path | <code>String</code> | Relative path (defaults to current path). |
-| currentQuery | <code>Object</code> | object of current query params (defaults to current querystring). |
+| query | `Object` | object of params to be updated. |
+| path | `String` | Admin page path, e.g. `/analytics/orders` (defaults to the current path). Used as-is for the `path` query arg; `./` and `../` segments are not resolved against the current path. |
+| currentQuery | `Object` | object of current query params (defaults to current querystring). |
+| page | `String` | Page key (defaults to "wc-admin"). |
+
+### flattenFilters(filters) ⇒ `Array`

-### flattenFilters(filters) ⇒ <code>Array</code>
 Collapse an array of filter values with subFilters into a 1-dimensional array.

-**Returns**: <code>Array</code> - Flattened array of all filters.
+**Returns**: `Array` - Flattened array of all filters.

 | Param | Type | Description |
 | --- | --- | --- |
-| filters | <code>Array</code> | Set of filters with possible subfilters. |
+| filters | `Array` | Set of filters with possible subfilters. |
+
+### getActiveFiltersFromQuery(query, config) ⇒ `Array.<activeFilters>`

-### getActiveFiltersFromQuery(query, config) ⇒ <code>Array.&lt;activeFilters&gt;</code>
 Given a query object, return an array of activeFilters, if any.

-**Returns**: <code>Array.&lt;activeFilters&gt;</code> - - array of activeFilters
+**Returns**: `Array.<activeFilters>` - - array of activeFilters

 | Param | Type | Description |
 | --- | --- | --- |
-| query | <code>object</code> | query object |
-| config | <code>object</code> | config object |
+| query | `object` | query object |
+| config | `object` | config object |
+
+### getDefaultOptionValue(config, options) ⇒ `string` \| `undefined`

-### getDefaultOptionValue(config, options) ⇒ <code>string</code> \| <code>undefined</code>
-Get the default option's value from the configuration object for a given filter. The first option is used as default if no <code>defaultOption</code> is provided.
+Get the default option's value from the configuration object for a given filter. The first option is used as default if no `defaultOption` is provided.

-**Returns**: <code>string</code> \| <code>undefined</code> - - the value of the default option.
+**Returns**: `string` \| `undefined` - - the value of the default option.

 | Param | Type | Description |
 | --- | --- | --- |
-| config | <code>object</code> | a filter config object. |
-| options | <code>array</code> | select options. |
+| config | `object` | a filter config object. |
+| options | `array` | select options. |
+
+### getQueryFromActiveFilters(activeFilters, query, config) ⇒ `object`

-### getQueryFromActiveFilters(activeFilters, query, config) ⇒ <code>object</code>
 Given activeFilters, create a new query object to update the url. Use previousFilters to
 Remove unused params.

-**Returns**: <code>object</code> - - query object representing the new parameters
+**Returns**: `object` - - query object representing the new parameters

 | Param | Type | Description |
 | --- | --- | --- |
-| activeFilters | <code>Array.&lt;activeFilters&gt;</code> | activeFilters shown in the UI |
-| query | <code>object</code> | the current url query object |
-| config | <code>object</code> | config object |
+| activeFilters | `Array.<activeFilters>` | activeFilters shown in the UI |
+| query | `object` | the current url query object |
+| config | `object` | config object |
+
+### getUrlKey(key, rule) ⇒ `string`

-### getUrlKey(key, rule) ⇒ <code>string</code>
 Get the url query key from the filter key and rule.

-**Returns**: <code>string</code> - - url query key.
+**Returns**: `string` - - url query key.

 | Param | Type | Description |
 | --- | --- | --- |
-| key | <code>string</code> | filter key. |
-| rule | <code>string</code> | filter rule. |
+| key | `string` | filter key. |
+| rule | `string` | filter rule. |
+
+### activeFilter : `Object`

-### activeFilter : <code>Object</code>
 Describe activeFilter object.

-**Properties**
+#### Properties

 | Name | Type | Description |
 | --- | --- | --- |
-| key | <code>string</code> | filter key. |
-| [rule] | <code>string</code> | a modifying rule for a filter, eg 'includes' or 'is_not'. |
-| value | <code>string</code> | filter value(s). |
+| key | `string` | filter key. |
+| [rule] | `string` | a modifying rule for a filter, eg 'includes' or 'is_not'. |
+| value | `string` | filter value(s). |
diff --git a/packages/js/navigation/changelog/fix-get-new-path-path-docs b/packages/js/navigation/changelog/fix-get-new-path-path-docs
new file mode 100644
index 00000000000..a67317472a7
--- /dev/null
+++ b/packages/js/navigation/changelog/fix-get-new-path-path-docs
@@ -0,0 +1,4 @@
+Significance: patch
+Type: dev
+Comment: Clarify the navigation `path` argument docs and fix README markdown lint issues; docs only.
+
diff --git a/packages/js/navigation/src/index.js b/packages/js/navigation/src/index.js
index 9074c4def0c..3506b8c0632 100644
--- a/packages/js/navigation/src/index.js
+++ b/packages/js/navigation/src/index.js
@@ -103,7 +103,7 @@ export function getSetOfIdsFromQuery( queryString = '' ) {
  * Updates the query parameters of the current page.
  *
  * @param {Object} query        object of params to be updated.
- * @param {string} path         Relative path (defaults to current path).
+ * @param {string} path         Admin page path, e.g. `/analytics/orders` (defaults to the current path). Used as-is for the `path` query arg; `./` and `../` segments are not resolved against the current path.
  * @param {Object} currentQuery object of current query params (defaults to current querystring).
  * @param {string} page         Page key (defaults to "wc-admin")
  */
@@ -235,8 +235,8 @@ export const useQuery = () => {
  * This function returns an event handler for the given `param`
  *
  * @param {string} param The parameter in the querystring which should be updated (ex `page`, `per_page`)
- * @param {string} path  Relative path (defaults to current path).
- * @param {string} query object of current query params (defaults to current querystring).
+ * @param {string} path  Admin page path, e.g. `/analytics/orders` (defaults to the current path). Used as-is for the `path` query arg; `./` and `../` segments are not resolved against the current path.
+ * @param {Object} query object of current query params (defaults to current querystring).
  * @return {Function} A callback which will update `param` to the passed value when called.
  */
 export function onQueryChange( param, path = getPath(), query = getQuery() ) {
@@ -276,7 +276,7 @@ export const isWCAdmin = ( url = window.location.href ) => {
  * or the router as appropriate.
  *
  * @param {Object} args     - All arguments.
- * @param {string} args.url - Relative path or absolute url to navigate to
+ * @param {string} args.url - Admin page path (written as-is into the `path` query arg, like getNewPath), an admin-relative URL such as `admin.php?page=wc-settings`, or an absolute URL.
  */
 export const navigateTo = ( { url } ) => {
 	const parsedUrl = parseAdminUrl( url );
diff --git a/packages/js/navigation/src/url.js b/packages/js/navigation/src/url.js
index be8d37fb040..a25d90872fc 100644
--- a/packages/js/navigation/src/url.js
+++ b/packages/js/navigation/src/url.js
@@ -34,7 +34,7 @@ export function getQuery() {
  * Return a URL with set query parameters.
  *
  * @param {Object} query        object of params to be updated.
- * @param {string} path         Relative path (defaults to current path).
+ * @param {string} path         Admin page path, e.g. `/analytics/orders` (defaults to the current path). Used as-is for the `path` query arg; `./` and `../` segments are not resolved against the current path.
  * @param {Object} currentQuery object of current query params (defaults to current querystring).
  * @param {string} page         Page key (defaults to "wc-admin")
  * @return {string}  Updated URL merging query params into existing params.