@xmachines/docs 2.2.0 → 4.0.0

package/api/@xmachines/play-url/index/README.md

@@ -0,0 +1,65 @@
+[API](../../../README.md) / [@xmachines/play-url](../README.md) / index
+
+# index
+
+@xmachines/play-url - the URL language of the Play Architecture
+
+`URLPattern` is the pattern language of XMachines, and this package reads it in ONE
+place: the parser, the compilation of a pattern against the native API or the polyfill,
+a base path with its `:param` substitution, and the normalization of the params that a
+framework router reports.
+
+It knows nothing of a state machine, of a route tree, or of a router bridge. Those live
+in `@xmachines/play-router`, which reads this package.
+
+The package exists because BOTH directions need the grammar. A URL becomes a state
+through the match of `@xmachines/play-router`, and a state becomes a URL through the
+substitution of the routing capability of `@xmachines/play-xstate`. One parser answers
+both, and neither package depends on the other.
+
+## See
+
+[Routing guide](../../../../guides/routing.md)
+
+## Interfaces
+
+- [BasePathOptions](interfaces/BasePathOptions.md)
+- [FrameworkParamsSource](interfaces/FrameworkParamsSource.md)
+- [GroupPart](interfaces/GroupPart.md)
+- [LiteralPart](interfaces/LiteralPart.md)
+- [ParamPart](interfaces/ParamPart.md)
+- [ParsedPattern](interfaces/ParsedPattern.md)
+- [PatternParam](interfaces/PatternParam.md)
+- [ResolvedBasePath](interfaces/ResolvedBasePath.md)
+
+## Type Aliases
+
+- [PatternModifier](type-aliases/PatternModifier.md)
+- [PatternPart](type-aliases/PatternPart.md)
+- [URLPatternCtor](type-aliases/URLPatternCtor.md)
+- [URLPatternLike](type-aliases/URLPatternLike.md)
+
+## Variables
+
+- [NO\_BASE\_PATH](variables/NO_BASE_PATH.md)
+- [URLPattern](variables/URLPattern.md)
+
+## Functions
+
+- [cleanFrameworkParams](functions/cleanFrameworkParams.md)
+- [getCandidates](functions/getCandidates.md)
+- [getCompiledPattern](functions/getCompiledPattern.md)
+- [getIndexKey](functions/getIndexKey.md)
+- [getNormalizedParamNameMap](functions/getNormalizedParamNameMap.md)
+- [getPatternParamNames](functions/getPatternParamNames.md)
+- [getRequiredPatternParamNames](functions/getRequiredPatternParamNames.md)
+- [holdsUnsubstitutedParam](functions/holdsUnsubstitutedParam.md)
+- [isParameterizedPattern](functions/isParameterizedPattern.md)
+- [joinBasePath](functions/joinBasePath.md)
+- [normalizeBasePath](functions/normalizeBasePath.md)
+- [normalizeParamNames](functions/normalizeParamNames.md)
+- [parsePattern](functions/parsePattern.md)
+- [pickOwnParams](functions/pickOwnParams.md)
+- [resolveBasePath](functions/resolveBasePath.md)
+- [resolveFrameworkParams](functions/resolveFrameworkParams.md)
+- [stripBasePath](functions/stripBasePath.md)

package/api/@xmachines/play-url/index/functions/cleanFrameworkParams.md

@@ -0,0 +1,39 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / cleanFrameworkParams
+
+# Function: cleanFrameworkParams()
+
+```ts
+function cleanFrameworkParams(params): Record<string, string>;
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:148](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L148)
+
+The params of a framework router, in the shape that [pickOwnParams](pickOwnParams.md) reads.
+
+Every framework reports a param that its own route DECLARES and that the location
+did not fill: Vue Router gives `undefined` or `""`, and SolidJS Router does the
+same. Such an entry is not an answer, and a pick that kept it would send an empty
+value to the actor as though the path carried one. Drop it here instead, one time,
+because the rule belongs to the decision of [resolveFrameworkParams](resolveFrameworkParams.md) and not
+to a bridge: `VueRouterBridge` and `SolidRouterBridge` held one copy each.
+
+A value of an array — the splat of a catch-all route of Vue Router — becomes its
+`String()` form, exactly as a single value does.
+
+The result has a null prototype, for the same reason [pickOwnParams](pickOwnParams.md) gives: a
+plain `{}` accumulator turns `cleaned["__proto__"] = value` into a write of the
+PROTOTYPE setter, which drops a string value in silence. `pickOwnParams` then read
+`Object.hasOwn(params, "__proto__")` as `false`, called the pick incomplete, and fell
+back to the URLPattern extraction, for a route the framework had answered already.
+
+## Parameters
+
+| Parameter | Type                            | Description                             |
+| --------- | ------------------------------- | --------------------------------------- |
+| `params`  | `Record`\<`string`, `unknown`\> | The raw params of the framework router. |
+
+## Returns
+
+`Record`\<`string`, `string`\>
+
+The params with no absent value, each one a string.

package/api/@xmachines/play-url/index/functions/getCandidates.md

@@ -0,0 +1,29 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getCandidates
+
+# Function: getCandidates()
+
+```ts
+function getCandidates<T>(patternBuckets, indexKey): T[];
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:242](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L242)
+
+Joins the bucket of the named segment and the wildcard bucket of one index key.
+The order of the insertion stays, through the `order` field.
+
+## Type Parameters
+
+| Type Parameter         |
+| ---------------------- |
+| `T` _extends_ `object` |
+
+## Parameters
+
+| Parameter        | Type                     | Description                                              |
+| ---------------- | ------------------------ | -------------------------------------------------------- |
+| `patternBuckets` | `Map`\<`string`, `T`[]\> | The map from a bucket key to its ordered pattern entries |
+| `indexKey`       | `string`                 | The key of the first segment, from `getIndexKey`         |
+
+## Returns
+
+`T`[]

package/api/@xmachines/play-url/index/functions/getCompiledPattern.md

@@ -0,0 +1,31 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getCompiledPattern
+
+# Function: getCompiledPattern()
+
+```ts
+function getCompiledPattern(pattern): URLPatternLike;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L216)
+
+Compiles a route pattern into a `URLPattern`, and it uses the cache of the module level
+again.
+
+[normalizeParamNames](normalizeParamNames.md) normalizes the pattern before the compilation. A param name
+with a hyphen (`:cat-id`) therefore becomes a valid URLPattern identifier (`:cat_id`).
+A caller that reads the values of the groups must map each normalized name back with
+[getNormalizedParamNameMap](getNormalizedParamNameMap.md).
+
+## Parameters
+
+| Parameter | Type     | Description                                                     |
+| --------- | -------- | --------------------------------------------------------------- |
+| `pattern` | `string` | The string of the route pattern, for example `/profile/:userId` |
+
+## Returns
+
+[`URLPatternLike`](../type-aliases/URLPatternLike.md)
+
+## Throws
+
+When URLPattern cannot compile the pattern.

package/api/@xmachines/play-url/index/functions/getIndexKey.md

@@ -0,0 +1,30 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getIndexKey
+
+# Function: getIndexKey()
+
+```ts
+function getIndexKey(path): string;
+```
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:199](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L199)
+
+Computes the key of the bucket index of a concrete PATH.
+
+The key is the first path segment, for example `"settings"` of `"/settings/billing"`.
+The root path `"/"` gives the key `"/"`, and a path whose first segment is EMPTY —
+`"//docs"` — gives the key `""`. The two are different keys, so a pattern that matches
+both asks [ParsedPattern.indexKey](../interfaces/ParsedPattern.md#property-indexkey) for the wildcard key instead.
+
+[ParsedPattern.indexKey](../interfaces/ParsedPattern.md#property-indexkey) computes the key of a PATTERN, and it calls this
+function for every pattern whose first segment is a literal. One function therefore
+answers both sides, and a pattern in the wrong bucket cannot happen.
+
+## Parameters
+
+| Parameter | Type     | Description               |
+| --------- | -------- | ------------------------- |
+| `path`    | `string` | The string of a URL path. |
+
+## Returns
+
+`string`

package/api/@xmachines/play-url/index/functions/getNormalizedParamNameMap.md

@@ -0,0 +1,32 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getNormalizedParamNameMap
+
+# Function: getNormalizedParamNameMap()
+
+```ts
+function getNormalizedParamNameMap(path): ReadonlyMap<string, string>;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:154](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L154)
+
+Builds the map from each normalized URLPattern group name back to the original param
+name, which holds a hyphen, of a route pattern.
+
+The map holds only the params that [normalizeParamNames](normalizeParamNames.md) rewrote. A param with a
+valid identifier keeps its own name, and it needs no entry.
+
+## Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+## Returns
+
+`ReadonlyMap`\<`string`, `string`\>
+
+## Example
+
+```ts
+getNormalizedParamNameMap("/docs/:cat-id/:plain");
+// → Map { "cat_id" → "cat-id" }
+```

package/api/@xmachines/play-url/index/functions/getPatternParamNames.md

@@ -0,0 +1,29 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getPatternParamNames
+
+# Function: getPatternParamNames()
+
+```ts
+function getPatternParamNames(pattern): string[];
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:26](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L26)
+
+Reads the names of every `:param` of a route pattern of the route map.
+
+The names come from the parse of `pattern-grammar.ts`, which reads the WHOLE grammar:
+a `{…}` group and a `(\d+)` constraint both hide a name from an expression that looks
+for `:name` alone. An ANONYMOUS param — `*` and a bare `(\d+)` — carries no name, and
+the list therefore holds none.
+
+## Parameters
+
+| Parameter | Type     | Description                                      |
+| --------- | -------- | ------------------------------------------------ |
+| `pattern` | `string` | A route pattern, for example `/profile/:userId`. |
+
+## Returns
+
+`string`[]
+
+The names, in the order that the pattern declares them. A fresh array, because
+`parsePattern` caches the parse that it reads.

package/api/@xmachines/play-url/index/functions/getRequiredPatternParamNames.md

@@ -0,0 +1,39 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / getRequiredPatternParamNames
+
+# Function: getRequiredPatternParamNames()
+
+```ts
+function getRequiredPatternParamNames(pattern): string[];
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L52)
+
+The names of every param the pattern REQUIRES, so an optional one is left out.
+
+A param is optional when its own modifier is `?` or `*`, and when EVERY group above it
+carries one of the two. `?` alone was the test before, and it read `/files/:path*` and
+`/books{/:id}?` as required patterns: a path that fills neither then counted as a gap,
+the pick was discarded, and a correct parse from Vue Router or SolidJS Router went with
+it. That is the same class of defect as the all-optional bug of !133, for the modifiers
+that the fix did not cover.
+
+An optional segment that did not match has no value, and a framework reports none. That
+is a complete answer and not a partial one, so a MIXED pattern such as
+`/profile/:userId/:tab?` keeps the parse of the framework when only `:tab` is absent.
+
+A pattern whose params are ALL optional reports nothing at all, which reads the same as
+"the framework matched another route", so [pickOwnParams](pickOwnParams.md) falls back for it.
+[resolveFrameworkParams](resolveFrameworkParams.md) settles that case from the PATH instead.
+
+## Parameters
+
+| Parameter | Type     | Description                                            |
+| --------- | -------- | ------------------------------------------------------ |
+| `pattern` | `string` | A route pattern, for example `/profile/:userId/:tab?`. |
+
+## Returns
+
+`string`[]
+
+The required names, in the order that the pattern declares them. A fresh
+array, because `parsePattern` caches the parse that it reads.

package/api/@xmachines/play-url/index/functions/holdsUnsubstitutedParam.md

@@ -0,0 +1,36 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / holdsUnsubstitutedParam
+
+# Function: holdsUnsubstitutedParam()
+
+```ts
+function holdsUnsubstitutedParam(pathname): boolean;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:120](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L120)
+
+Tells you if a CONCRETE path still carries a param that nothing substituted.
+
+This is a different question from [isParameterizedPattern](isParameterizedPattern.md), and it needs a
+different test. `RouterBridgeBase.resolveNavigationPath` asks it about a value that the
+ACTOR reports, which is a real path built from real param values — and a real path
+carries a character of the pattern grammar whenever a param value does. `/search/a+b`,
+`/tags/c++`, `/docs/rfc(2119)` and `/i18n/{en}` are all ordinary locations, and the
+grammar reads a modifier, a constraint and a group in them. A bridge that judged them
+by the grammar refused to navigate, and it said nothing.
+
+The test is therefore narrow on purpose: `:` and `*` are the two characters that mark a
+param a substitution did not fill, and a path that holds one of them can reach the URL
+bar never. A param VALUE that holds one of them is refused too, which is the price, and
+it is the price this library paid before the grammar existed.
+
+## Parameters
+
+| Parameter  | Type     | Description                                                          |
+| ---------- | -------- | -------------------------------------------------------------------- |
+| `pathname` | `string` | The PATHNAME half of an actor route, with the query already removed. |
+
+## Returns
+
+`boolean`
+
+`true` when the path cannot go to the URL bar as it stands

package/api/@xmachines/play-url/index/functions/isParameterizedPattern.md

@@ -0,0 +1,36 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / isParameterizedPattern
+
+# Function: isParameterizedPattern()
+
+```ts
+function isParameterizedPattern(pattern): boolean;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:97](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L97)
+
+Tells you if a route path needs a URLPattern match, and is not a concrete URL.
+
+A pattern holds a param — `:name`, `(\d+)` or `*` — or a `{…}` group, or an escape.
+Each of them needs a match, and each of them carries no concrete value, so the code
+can push such a path to a browser URL never.
+
+This function is THE single source of truth of the question "is this path a pattern?".
+`RouteMap` uses it for its decision between the static map and the index of the pattern
+buckets, and `extractRouteParams` uses it to answer `{}` for a literal path. A CONCRETE
+path asks [holdsUnsubstitutedParam](holdsUnsubstitutedParam.md) instead, and never this function.
+
+The answer comes from the parse, and not from a search for a `:` or a `*`. That search
+called `/a{/b}?/c` a static path, and `RouteMap` then put it in the exact-match map,
+where the path `/a/c` reached it never.
+
+## Parameters
+
+| Parameter | Type     | Description                                                                                 |
+| --------- | -------- | ------------------------------------------------------------------------------------------- |
+| `pattern` | `string` | The string of a URL path or of a route pattern, for example `/profile/:userId` or `/docs/*` |
+
+## Returns
+
+`boolean`
+
+`true` when the path needs a URLPattern match

package/api/@xmachines/{play-router → play-url/index}/functions/joinBasePath.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / joinBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / joinBasePath
 
 # Function: joinBasePath()
 
@@ -6,7 +6,7 @@
 function joinBasePath(basePath, path): string;
 ```
 
-Defined in: [base-path.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-path.ts#L302)
+Defined in: [packages/play-url/src/base-path.ts:302](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L302)
 
 Adds the base path to an outbound path of the machine.
 

package/api/@xmachines/{play-router → play-url/index}/functions/normalizeBasePath.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / normalizeBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / normalizeBasePath
 
 # Function: normalizeBasePath()
 
@@ -6,7 +6,7 @@
 function normalizeBasePath(basePath?): string;
 ```
 
-Defined in: [base-path.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-path.ts#L130)
+Defined in: [packages/play-url/src/base-path.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L130)
 
 Normalizes a base path, and it substitutes no `:param` segment of that path.
 

package/api/@xmachines/play-url/index/functions/normalizeParamNames.md

@@ -0,0 +1,36 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / normalizeParamNames
+
+# Function: normalizeParamNames()
+
+```ts
+function normalizeParamNames(path): string;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:139](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L139)
+
+Normalizes a route path, so that each of its parameter names is a valid URLPattern
+identifier.
+
+URLPattern requires a valid JS identifier as a parameter name, and such an identifier
+holds no hyphen. Therefore the function replaces a name with a hyphen, for example
+`:cat-id`, with the equivalent name with an underscore (`:cat_id`), for the compilation
+step of URLPattern. A caller that needs the values of the captured groups, and not a
+test of the match alone, must map each normalized group name back to the original param
+name with [getNormalizedParamNameMap](getNormalizedParamNameMap.md).
+
+## Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `path`    | `string` |
+
+## Returns
+
+`string`
+
+## Example
+
+```ts
+normalizeParamNames("/docs/:cat-id/:page-num?");
+// → "/docs/:cat_id/:page_num?"
+```

package/api/@xmachines/play-url/index/functions/parsePattern.md

@@ -0,0 +1,27 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / parsePattern
+
+# Function: parsePattern()
+
+```ts
+function parsePattern(pattern): ParsedPattern;
+```
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:262](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L262)
+
+Reads a route pattern, one time for each distinct pattern.
+
+The parser reports a fault never. A pattern that it cannot read reports
+`parameterized: true` and `bareForm: null`, which sends it to the URLPattern
+constructor and keeps every derived answer on the safe side.
+
+## Parameters
+
+| Parameter | Type     | Description                                        |
+| --------- | -------- | -------------------------------------------------- |
+| `pattern` | `string` | The route pattern, for example `/profile/:userId`. |
+
+## Returns
+
+[`ParsedPattern`](../interfaces/ParsedPattern.md)
+
+The parse. The caller treats it as read-only: the cache holds this object.

package/api/@xmachines/{play-router → play-url/index}/functions/pickOwnParams.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / pickOwnParams
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / pickOwnParams
 
 # Function: pickOwnParams()
 
@@ -6,7 +6,7 @@
 function pickOwnParams(params, names, requiredNames?): Record<string, string> | null;
 ```
 
-Defined in: [framework-params.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/framework-params.ts#L117)
+Defined in: [packages/play-url/src/framework-params.ts:84](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L84)
 
 Keeps the entries of `params` whose name the pattern of the machine declares, and
 only when the result covers EVERY name of that pattern.
@@ -31,8 +31,8 @@ which settles the question without the framework and without URLPattern.
 | Parameter       | Type                           | Default value | Description                                                                                                                                                                                                                                                                    |
 | --------------- | ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `params`        | `Record`\<`string`, `string`\> | `undefined`   | The params of the framework router. [cleanFrameworkParams](cleanFrameworkParams.md) removes each empty value already, and one that reaches here anyway counts as absent: an empty value says that the segment did not match, and never that the path carries the empty string. |
-| `names`         | `string`[]                     | `undefined`   | The names that the pattern of the machine declares.                                                                                                                                                                                                                            |
-| `requiredNames` | `string`[]                     | `names`       | The names the pattern REQUIRES. The default treats every name as required, so a two-argument call keeps the strict test.                                                                                                                                                       |
+| `names`         | readonly `string`[]            | `undefined`   | The names that the pattern of the machine declares.                                                                                                                                                                                                                            |
+| `requiredNames` | readonly `string`[]            | `names`       | The names the pattern REQUIRES. The default treats every name as required, so a two-argument call keeps the strict test.                                                                                                                                                       |
 
 ## Returns
 

package/api/@xmachines/{play-router → play-url/index}/functions/resolveBasePath.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / resolveBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / resolveBasePath
 
 # Function: resolveBasePath()
 
@@ -6,7 +6,7 @@
 function resolveBasePath(basePath?, params?): ResolvedBasePath;
 ```
 
-Defined in: [base-path.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-path.ts#L180)
+Defined in: [packages/play-url/src/base-path.ts:180](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L180)
 
 Resolves a base path and its params to the concrete prefix that a browser URL
 carries.

package/api/@xmachines/play-url/index/functions/resolveFrameworkParams.md

@@ -0,0 +1,49 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / resolveFrameworkParams
+
+# Function: resolveFrameworkParams()
+
+```ts
+function resolveFrameworkParams(__namedParameters): Record<string, string>;
+```
+
+Defined in: [packages/play-url/src/framework-params.ts:261](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L261)
+
+Decides which params describe the route of the machine.
+
+The four branches, in the order that they apply:
+
+- **The pattern declares no name** — a static path, a bare `*` wildcard, or an
+  unknown stateId. The answer is `{}`. The params of the framework must NOT travel
+  here: under a catch-all they hold the splat of the host, and that value would reach
+  the actor as a param of the machine. A bare `*` names nothing that a machine can
+  read, and URLPattern numbers its group `0`.
+- **The bridge sits under a mount** — the framework matched a route of the HOST by
+  construction, because the machine owns the suffix of the path only. Its params
+  therefore describe this pattern never, whatever they are named, and a name that
+  happens to collide carries the value of the host. Read the params of the machine
+  from its own pattern instead.
+- **The framework covers every REQUIRED name** — it matched the machine route. Keep
+  its parse, together with its decoding. An optional `:name?` that the framework
+  reports not is covered too: a segment that did not match has no value. A gap in a
+  required name falls back, because keeping it would drop a name the route declares.
+- **The path IS the bare form of the pattern** — every optional part is absent, so `{}`
+  is the complete answer. The branch reads the path and trusts the framework with
+  nothing, which is what makes it safe under a catch-all of the host, and it calls
+  URLPattern for a location that needs none.
+
+What these branches decide is whether a NAVIGATION compiles and runs a URLPattern
+again. The API itself is always present: `url-pattern-utils.ts` imports the polyfill as
+an ordinary dependency, and no code path asks whether the runtime carries the native
+one.
+
+## Parameters
+
+| Parameter           | Type                                                              |
+| ------------------- | ----------------------------------------------------------------- |
+| `__namedParameters` | [`FrameworkParamsSource`](../interfaces/FrameworkParamsSource.md) |
+
+## Returns
+
+`Record`\<`string`, `string`\>
+
+The path parameters of the machine route, or `{}`.

package/api/@xmachines/{play-router → play-url/index}/functions/stripBasePath.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / stripBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / stripBasePath
 
 # Function: stripBasePath()
 
@@ -6,7 +6,7 @@
 function stripBasePath(pathname, basePath): string | null;
 ```
 
-Defined in: [base-path.ts:276](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-path.ts#L276)
+Defined in: [packages/play-url/src/base-path.ts:276](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L276)
 
 Removes the base path from an inbound location of the router.
 

package/api/@xmachines/play-url/index/interfaces/BasePathOptions.md

@@ -0,0 +1,28 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / BasePathOptions
+
+# Interface: BasePathOptions
+
+Defined in: [packages/play-url/src/base-path.ts:44](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L44)
+
+The base-path options that every router bridge, `connectRouter` function, and
+`PlayRouterProvider` component accepts.
+
+## Example
+
+```typescript
+// A host that mounts a machine under a route it resolved in a loader
+connectRouter({
+	actor,
+	router,
+	routeMap,
+	basePath: "/:machineId/play",
+	basePathParams: { machineId },
+});
+```
+
+## Properties
+
+| Property                                               | Modifier   | Type                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Defined in                                                                                                                               |
+| ------------------------------------------------------ | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-basepath"></a> `basePath?`             | `readonly` | `string`                                   | The URL prefix that the routes of the machine hang off, for example `"/admin"` or `"/:machineId/play"`. A `:param` segment is a declarative convenience, so that a host keeps ONE string that mirrors its own route config. Every `:param` must have a value in [BasePathOptions.basePathParams](#property-basepathparams), because the bridge writes a real URL. An optional segment (`:param?`) and a wildcard (`*`) are therefore refused: neither of them resolves to one concrete prefix. An absent value, `""`, and `"/"` all mean "no prefix", which is the behaviour of every release before this option existed.                                                 | [packages/play-url/src/base-path.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L58) |
+| <a id="property-basepathparams"></a> `basePathParams?` | `readonly` | `Record`\<`string`, `string` \| `number`\> | The values of the `:param` segments of [BasePathOptions.basePath](#property-basepath). These values belong to the HOST, which wrote the prefix and resolved them, so they travel in NO `play.route` event: the machine is authoritative over its own params, and `event.params` holds what the pattern of the machine declares, and nothing else. A param of the host that shares a name with one of the machine can therefore shadow it never. A host reads them back from `bridge.basePathParams`, where they cannot go stale. A machine that needs the identity of its host takes it through the `input` of the actor, where that identity decides WHICH machine runs. | [packages/play-url/src/base-path.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L72) |