@xmachines/docs 2.2.0 → 4.0.0

package/api/@xmachines/{play-router → play-url/index}/interfaces/FrameworkParamsSource.md

@@ -1,18 +1,18 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / FrameworkParamsSource
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / FrameworkParamsSource
 
 # Interface: FrameworkParamsSource
 
-Defined in: [framework-params.ts:247](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/framework-params.ts#L247)
+Defined in: [packages/play-url/src/framework-params.ts:212](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L212)
 
 What [resolveFrameworkParams](../functions/resolveFrameworkParams.md) needs from the bridge that calls it.
 
 ## Properties
 
-| Property                                   | Type                              | Description                                                                                                                                                                                                                             | Defined in                                                                                                                            |
-| ------------------------------------------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-basepath"></a> `basePath`  | `string`                          | The resolved prefix of the mount. `""` means that the machine owns the router.                                                                                                                                                          | [framework-params.ts:251](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/framework-params.ts#L251) |
-| <a id="property-pathname"></a> `pathname?` | `string`                          | The machine-side path of the location, with the mount prefix already removed. The field is OPTIONAL, so a caller that was written before it keeps its behaviour: the one branch that reads it falls back without it, exactly as it did. | [framework-params.ts:258](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/framework-params.ts#L258) |
-| <a id="property-pattern"></a> `pattern`    | `string` \| `null` \| `undefined` | The route pattern of the match, from `routeMap.getPathByStateId`.                                                                                                                                                                       | [framework-params.ts:249](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/framework-params.ts#L249) |
+| Property                                   | Type                              | Description                                                                                                                                                                                                                             | Defined in                                                                                                                                               |
+| ------------------------------------------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-basepath"></a> `basePath`  | `string`                          | The resolved prefix of the mount. `""` means that the machine owns the router.                                                                                                                                                          | [packages/play-url/src/framework-params.ts:216](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L216) |
+| <a id="property-pathname"></a> `pathname?` | `string`                          | The machine-side path of the location, with the mount prefix already removed. The field is OPTIONAL, so a caller that was written before it keeps its behaviour: the one branch that reads it falls back without it, exactly as it did. | [packages/play-url/src/framework-params.ts:223](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L223) |
+| <a id="property-pattern"></a> `pattern`    | `string` \| `null` \| `undefined` | The route pattern of the match, from `routeMap.getPathByStateId`.                                                                                                                                                                       | [packages/play-url/src/framework-params.ts:214](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L214) |
 
 ## Methods
 
@@ -22,7 +22,7 @@ What [resolveFrameworkParams](../functions/resolveFrameworkParams.md) needs from
 fallback(): Record<string, string>;
 ```
 
-Defined in: [framework-params.ts:262](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/framework-params.ts#L262)
+Defined in: [packages/play-url/src/framework-params.ts:227](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L227)
 
 The URLPattern extraction of the base class, read lazily.
 
@@ -38,7 +38,7 @@ The URLPattern extraction of the base class, read lazily.
 frameworkParams(): Record<string, string>;
 ```
 
-Defined in: [framework-params.ts:260](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/framework-params.ts#L260)
+Defined in: [packages/play-url/src/framework-params.ts:225](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/framework-params.ts#L225)
 
 The params of the framework router, read lazily and cleaned of empty values.
 

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

@@ -0,0 +1,15 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / GroupPart
+
+# Interface: GroupPart
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:90](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L90)
+
+A `{…}` group, which carries its own parts and its own modifier.
+
+## Properties
+
+| Property                                  | Modifier   | Type                                                       | Defined in                                                                                                                                           |
+| ----------------------------------------- | ---------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-kind"></a> `kind`         | `readonly` | `"group"`                                                  | [packages/play-url/src/pattern-grammar.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L91) |
+| <a id="property-modifier"></a> `modifier` | `readonly` | [`PatternModifier`](../type-aliases/PatternModifier.md)    | [packages/play-url/src/pattern-grammar.ts:93](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L93) |
+| <a id="property-parts"></a> `parts`       | `readonly` | readonly [`PatternPart`](../type-aliases/PatternPart.md)[] | [packages/play-url/src/pattern-grammar.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L92) |

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

@@ -0,0 +1,14 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / LiteralPart
+
+# Interface: LiteralPart
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:57](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L57)
+
+A run of literal characters, with every escape already resolved.
+
+## Properties
+
+| Property                          | Modifier   | Type        | Description                                                     | Defined in                                                                                                                                           |
+| --------------------------------- | ---------- | ----------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-kind"></a> `kind` | `readonly` | `"literal"` | -                                                               | [packages/play-url/src/pattern-grammar.ts:58](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L58) |
+| <a id="property-text"></a> `text` | `readonly` | `string`    | The characters that a path must carry, for example `/settings`. | [packages/play-url/src/pattern-grammar.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L60) |

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

@@ -0,0 +1,21 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / ParamPart
+
+# Interface: ParamPart
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:69](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L69)
+
+A param: `:name`, `(\d+)`, or `*`.
+
+An anonymous param carries no `name`. URLPattern numbers such a group from `0`, and
+this library reports it to no machine — see [ParsedPattern.params](ParsedPattern.md#property-params).
+
+## Properties
+
+| Property                                    | Modifier   | Type                                                    | Description                                                                                                                                                                                                                                                                                                                                                 | Defined in                                                                                                                                           |
+| ------------------------------------------- | ---------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-groupname"></a> `groupName` | `readonly` | `string` \| `null`                                      | The name that URLPattern compiles, with each hyphen rewritten to an underscore, or `null` for an anonymous param. The rewrite happens ONE time, here, and [ParsedPattern.normalized](ParsedPattern.md#property-normalized) carries the same characters. A caller that needs the group name of a param reads this field, and it rewrites nothing of its own. | [packages/play-url/src/pattern-grammar.ts:81](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L81) |
+| <a id="property-kind"></a> `kind`           | `readonly` | `"param"`                                               | -                                                                                                                                                                                                                                                                                                                                                           | [packages/play-url/src/pattern-grammar.ts:70](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L70) |
+| <a id="property-modifier"></a> `modifier`   | `readonly` | [`PatternModifier`](../type-aliases/PatternModifier.md) | -                                                                                                                                                                                                                                                                                                                                                           | [packages/play-url/src/pattern-grammar.ts:86](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L86) |
+| <a id="property-name"></a> `name`           | `readonly` | `string` \| `null`                                      | The declared name, with each hyphen kept, or `null` for an anonymous param.                                                                                                                                                                                                                                                                                 | [packages/play-url/src/pattern-grammar.ts:72](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L72) |
+| <a id="property-prefix"></a> `prefix`       | `readonly` | `string`                                                | The `/` that the param absorbed from the literal before it, or `""`.                                                                                                                                                                                                                                                                                        | [packages/play-url/src/pattern-grammar.ts:85](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L85) |
+| <a id="property-regexp"></a> `regexp`       | `readonly` | `string` \| `null`                                      | The source of the constraint of `:id(\d+)`, or `null` when the param declares none.                                                                                                                                                                                                                                                                         | [packages/play-url/src/pattern-grammar.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L83) |

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

@@ -0,0 +1,23 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / ParsedPattern
+
+# Interface: ParsedPattern
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:115](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L115)
+
+Everything that this library reads from one route pattern.
+
+## Properties
+
+| Property                                            | Modifier   | Type                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Defined in                                                                                                                                             |
+| --------------------------------------------------- | ---------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-bareform"></a> `bareForm`           | `readonly` | `string` \| `null`                                         | The path that the pattern matches when every optional part is absent, or `null` when the pattern holds a part that a path must fill. `/settings/:section?` gives `/settings`, `/a/{b}?/c` gives `/a//c`, and `/profile/:userId` gives `null`.                                                                                                                                                                                                                                           | [packages/play-url/src/pattern-grammar.ts:152](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L152) |
+| <a id="property-declarednames"></a> `declaredNames` | `readonly` | `ReadonlyMap`\<`string`, `string`\>                        | The map from each rewritten group name back to the name that the pattern declares, for example `cat_id` to `cat-id`. The map holds an entry only for a name that the rewrite changed. It is empty for most patterns, and a caller that reads a group name falls back to the name itself.                                                                                                                                                                                                | [packages/play-url/src/pattern-grammar.ts:182](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L182) |
+| <a id="property-indexkey"></a> `indexKey`           | `readonly` | `string`                                                   | The key of the bucket index: the first path segment, or `"*"` when a param can stand in the first segment.                                                                                                                                                                                                                                                                                                                                                                              | [packages/play-url/src/pattern-grammar.ts:169](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L169) |
+| <a id="property-literalpath"></a> `literalPath`     | `readonly` | `string` \| `null`                                         | The ONE path that the pattern matches, with each escape resolved, or `null` when the pattern describes a SET of paths. `/users` gives `/users`, `/tags/c\+\+` gives `/tags/c++`, `/x{y}z` gives `/xyz`, and `/profile/:userId` gives `null`. A bridge writes a real browser URL from this field. The SOURCE of the pattern is no substitute for it: `/tags/c\+\+` carries two backslashes that the address bar must not hold, and a location that carries them matches the route never. | [packages/play-url/src/pattern-grammar.ts:164](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L164) |
+| <a id="property-names"></a> `names`                 | `readonly` | readonly `string`[]                                        | The name of every param of [params](#property-params), in the same order. `resolveFrameworkParams` runs on EVERY navigation and it needs this list each time. The parse holds it, so a navigation allocates none. A caller that hands the array to somebody else copies it: the cache holds this one.                                                                                                                                                                                   | [packages/play-url/src/pattern-grammar.ts:129](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L129) |
+| <a id="property-normalized"></a> `normalized`       | `readonly` | `string`                                                   | The pattern in the form that URLPattern compiles: each param name that holds a hyphen carries an underscore instead.                                                                                                                                                                                                                                                                                                                                                                    | [packages/play-url/src/pattern-grammar.ts:174](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L174) |
+| <a id="property-parameterized"></a> `parameterized` | `readonly` | `boolean`                                                  | True when the pattern needs a URLPattern match, and false when it is a literal path. A malformed pattern reports `true`, so that it reaches the URLPattern constructor and fails there with the error of the API. A parser that called it static would send it to the exact-match map instead, where it matches nothing and reports no fault.                                                                                                                                           | [packages/play-url/src/pattern-grammar.ts:144](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L144) |
+| <a id="property-params"></a> `params`               | `readonly` | readonly [`PatternParam`](PatternParam.md)[]               | The NAMED params, in the order that the pattern declares them.                                                                                                                                                                                                                                                                                                                                                                                                                          | [packages/play-url/src/pattern-grammar.ts:121](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L121) |
+| <a id="property-parts"></a> `parts`                 | `readonly` | readonly [`PatternPart`](../type-aliases/PatternPart.md)[] | The parts, in the order that the pattern declares them.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [packages/play-url/src/pattern-grammar.ts:119](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L119) |
+| <a id="property-requirednames"></a> `requiredNames` | `readonly` | readonly `string`[]                                        | The name of every param that a path must fill, in the order of [params](#property-params). The same rule as [names](#property-names): the parse holds the array, and a navigation reads it.                                                                                                                                                                                                                                                                                             | [packages/play-url/src/pattern-grammar.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L135) |
+| <a id="property-source"></a> `source`               | `readonly` | `string`                                                   | The pattern as the caller wrote it.                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [packages/play-url/src/pattern-grammar.ts:117](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L117) |

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

@@ -0,0 +1,15 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / PatternParam
+
+# Interface: PatternParam
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:99](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L99)
+
+One named param of a pattern, with the question that every caller asks about it.
+
+## Properties
+
+| Property                                    | Modifier   | Type      | Description                                                                                                                                                                                                                                                           | Defined in                                                                                                                                             |
+| ------------------------------------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <a id="property-groupname"></a> `groupName` | `readonly` | `string`  | The name that URLPattern compiles, for example `cat_id`.                                                                                                                                                                                                              | [packages/play-url/src/pattern-grammar.ts:103](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L103) |
+| <a id="property-name"></a> `name`           | `readonly` | `string`  | The name as the pattern declares it, for example `cat-id`.                                                                                                                                                                                                            | [packages/play-url/src/pattern-grammar.ts:101](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L101) |
+| <a id="property-optional"></a> `optional`   | `readonly` | `boolean` | True when a matching path can carry no value for this param. The modifier `?` and the modifier `*` make a param optional, and so does EVERY group above it that carries one of the two. The modifier `+` does not: it repeats a param that one value must still fill. | [packages/play-url/src/pattern-grammar.ts:111](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L111) |

package/api/@xmachines/{play-router → play-url/index}/interfaces/ResolvedBasePath.md

@@ -1,14 +1,14 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / ResolvedBasePath
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / ResolvedBasePath
 
 # Interface: ResolvedBasePath
 
-Defined in: [base-path.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-path.ts#L78)
+Defined in: [packages/play-url/src/base-path.ts:78](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L78)
 
 A base path that is ready for a use in both directions.
 
 ## Properties
 
-| Property                              | Modifier   | Type                           | Description                                                                                                                                                                     | Defined in                                                                                                            |
-| ------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-params"></a> `params` | `readonly` | `Record`\<`string`, `string`\> | The values of each `:param` of the prefix, for the `params` of a `play.route` event. The object is empty for a prefix without a param, and for a pattern that nothing resolved. | [base-path.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-path.ts#L89) |
-| <a id="property-path"></a> `path`     | `readonly` | `string`                       | The normalized prefix: it starts with `/`, it carries no trailing `/`, and it holds no duplicate slash. The empty string means "no prefix".                                     | [base-path.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-path.ts#L83) |
+| Property                              | Modifier   | Type                           | Description                                                                                                                                                                     | Defined in                                                                                                                               |
+| ------------------------------------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="property-params"></a> `params` | `readonly` | `Record`\<`string`, `string`\> | The values of each `:param` of the prefix, for the `params` of a `play.route` event. The object is empty for a prefix without a param, and for a pattern that nothing resolved. | [packages/play-url/src/base-path.ts:89](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L89) |
+| <a id="property-path"></a> `path`     | `readonly` | `string`                       | The normalized prefix: it starts with `/`, it carries no trailing `/`, and it holds no duplicate slash. The empty string means "no prefix".                                     | [packages/play-url/src/base-path.ts:83](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L83) |

package/api/@xmachines/play-url/index/type-aliases/PatternModifier.md

@@ -0,0 +1,11 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / PatternModifier
+
+# Type Alias: PatternModifier
+
+```ts
+type PatternModifier = "" | "?" | "+" | "*";
+```
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:54](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L54)
+
+The modifier of a part. `""` means that the part carries none.

package/api/@xmachines/play-url/index/type-aliases/PatternPart.md

@@ -0,0 +1,9 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / PatternPart
+
+# Type Alias: PatternPart
+
+```ts
+type PatternPart = LiteralPart | ParamPart | GroupPart;
+```
+
+Defined in: [packages/play-url/src/pattern-grammar.ts:96](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/pattern-grammar.ts#L96)

package/api/@xmachines/play-url/index/type-aliases/URLPatternCtor.md

@@ -0,0 +1,22 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / URLPatternCtor
+
+# Type Alias: URLPatternCtor
+
+```ts
+type URLPatternCtor = (init) => URLPatternLike;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:60](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L60)
+
+The constructor type of a URLPatternLike instance.
+
+## Parameters
+
+| Parameter       | Type                        |
+| --------------- | --------------------------- |
+| `init`          | \{ `pathname`: `string`; \} |
+| `init.pathname` | `string`                    |
+
+## Returns
+
+[`URLPatternLike`](URLPatternLike.md)

package/api/@xmachines/play-url/index/type-aliases/URLPatternLike.md

@@ -0,0 +1,68 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / URLPatternLike
+
+# Type Alias: URLPatternLike
+
+```ts
+type URLPatternLike = object;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L52)
+
+The minimal structural type of the part of URLPattern that this package uses.
+
+The type is the published contract of this module, and it names the native API and the
+polyfill both. It also keeps the global declarations of `urlpattern-polyfill` out of
+the emitted `.d.ts` of this package.
+
+## Methods
+
+### exec()
+
+```ts
+exec(input):
+  | {
+  pathname: {
+     groups: Record<string, string | undefined>;
+  };
+}
+  | null;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:53](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L53)
+
+#### Parameters
+
+| Parameter        | Type                        |
+| ---------------- | --------------------------- |
+| `input`          | \{ `pathname`: `string`; \} |
+| `input.pathname` | `string`                    |
+
+#### Returns
+
+\| \{
+`pathname`: \{
+`groups`: `Record`\<`string`, `string` \| `undefined`\>;
+\};
+\}
+\| `null`
+
+---
+
+### test()
+
+```ts
+test(input): boolean;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:56](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L56)
+
+#### Parameters
+
+| Parameter        | Type                        |
+| ---------------- | --------------------------- |
+| `input`          | \{ `pathname`: `string`; \} |
+| `input.pathname` | `string`                    |
+
+#### Returns
+
+`boolean`

package/api/@xmachines/{play-router → play-url/index}/variables/NO_BASE_PATH.md

@@ -1,4 +1,4 @@
-[API](../../../README.md) / [@xmachines/play-router](../README.md) / NO\_BASE\_PATH
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / NO\_BASE\_PATH
 
 # Variable: NO\_BASE\_PATH
 
@@ -6,7 +6,7 @@
 const NO_BASE_PATH: ResolvedBasePath;
 ```
 
-Defined in: [base-path.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.2.0/packages/play-router/src/base-path.ts#L102)
+Defined in: [packages/play-url/src/base-path.ts:102](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/base-path.ts#L102)
 
 The base path of a bridge that has no `basePath` option.
 

package/api/@xmachines/play-url/index/variables/URLPattern.md

@@ -0,0 +1,21 @@
+[API](../../../../README.md) / [@xmachines/play-url](../../README.md) / [index](../README.md) / URLPattern
+
+# Variable: URLPattern
+
+```ts
+const URLPattern: URLPatternCtor;
+```
+
+Defined in: [packages/play-url/src/url-pattern-utils.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v4.0.0/packages/play-url/src/url-pattern-utils.ts#L75)
+
+The URLPattern constructor that this library uses: the native API when the runtime
+carries one, and the polyfill when it does not.
+
+The native API comes first for two reasons. It is faster, because the engine compiles
+the pattern itself. And it is the API that the REST of the page already uses, so a
+pattern that the application builds and a pattern that this library builds behave the
+same way.
+
+The read of `globalThis` happens ONE time, when the module loads. A test that replaces
+`globalThis.URLPattern` afterwards therefore changes nothing here, which is what makes
+the compiled-pattern cache below safe to keep for the life of the process.

package/api/@xmachines/play-view/README.md

@@ -0,0 +1,165 @@
+[API](../../README.md) / @xmachines/play-view
+
+# @xmachines/play-view
+
+The shared view half of every renderer of the XMachines Play Architecture.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Version](https://img.shields.io/badge/version-4.0.0-blue)](https://www.npmjs.com/package/@xmachines/play-view)
+
+## Installation
+
+```bash
+pnpm add @xmachines/play-view
+```
+
+**Peer dependencies.** Install them with the package:
+
+```bash
+pnpm add @xmachines/json-render-core
+```
+
+A renderer of a framework depends on this package already. Install it directly when you write a renderer of your own.
+
+## Overview
+
+A renderer of a framework is two things: the view lifecycle, and the code that binds that lifecycle to the effects of the framework. This package holds the first one. [`@xmachines/play-react`](../play-react/README.md), [`@xmachines/play-vue`](../play-vue/README.md), [`@xmachines/play-solid`](../play-solid/README.md), [`@xmachines/play-svelte`](../play-svelte/README.md) and [`@xmachines/play-dom`](../play-dom/README.md) hold the second one.
+
+It also holds `Viewable` and `PlaySpec`. Every type here names a type of `@xmachines/json-render-core`, and that is the reason they are here and not in [`@xmachines/play-actor`](../play-actor/README.md): an application that routes and renders no view installs this package never, and json-render never.
+
+| Export                                           | Description                                                           |
+| ------------------------------------------------ | --------------------------------------------------------------------- |
+| `Viewable`                                       | The capability of an actor that publishes a `currentView` signal      |
+| `PlaySpec`, `typedSpec`                          | The spec that an actor publishes, and its identity helper             |
+| `BaseActorProviderProps`, `BaseViewContextValue` | The framework-free half of the props and of the context of a provider |
+| `createViewStoreLifecycle`                       | The lifecycle of the state store of one view                          |
+| `createFailureLatch`, `createReportGuard`        | The report of a render failure, one time for each view                |
+| `toAtomState`, `attachRenderErrorHandler`        | The guards that a provider puts around a registry                     |
+| `composePlayState`, `refreshContextSubtree`, …   | The projection of the machine context into the store                  |
+
+## API Summary
+
+### `typedSpec(spec)`
+
+This identity helper gives a view-spec literal the type `PlaySpec` at the definition site. The
+XState `meta` field has the type `Record<string, unknown>`. Therefore this helper is the place
+where the spec shape receives the compile-time check and the IDE autocomplete. The helper has no
+cost at run time.
+
+```ts
+import { typedSpec } from "@xmachines/play-view";
+
+// In an XState machine meta block:
+meta: {
+  view: typedSpec({
+    root: "root",
+    elements: {
+      root: {
+        type: "Dashboard",
+        props: { username: { $state: "/context/username" } },
+        children: [],
+      },
+    },
+  }),
+}
+```
+
+### `PlaySpec`
+
+This type extends the `Spec` type of `@xmachines/json-render-core`. Each derived view receives
+the complete machine context in its state store, under the read-only **`/context` subtree**. A
+spec therefore reads the context through the ordinary `{ $state: "/context/…" }` grammar: in a
+prop, in a `visible` condition, and in `repeat.statePath`.
+
+`/context` is read-only by design. Nothing can write to it. The machine context changes through
+an event only. A `$bindState` write or a `setState` write under `/context` throws an error, and
+the error names the event to send. This is the model: the bindable ephemeral state is at the
+root of the store, from `spec.state`; the domain state is in the machine, and it changes through
+events that are meaningful and easy to inspect.
+
+The path shows the origin of each value. `/context/params/username` comes from the URL.
+`/context/username` belongs to the machine. One value can never hide the other.
+
+The model projects everything, and this has two consequences. The first consequence is
+**exposure**. The complete context is visible to the client in the view store, which includes a
+debug panel, an inspector, and a validator. The context is a client-side value in each case, so
+keep a secret out of it.
+
+The second consequence is **emission granularity**. The emit gate compares the context field by
+field, at the top level only. Therefore an event that changes any field emits the view again
+with the same `viewKey`. A provider refreshes `/context` in the live store, and it does not seed
+the store again. The component does not remount, and the ephemeral view state and the focus
+stay. However, a new emission is still a render pass in the framework layer. Keep
+high-frequency ephemeral data, such as a draft for each keystroke or a timer, in the view store
+(`spec.state` with `$bindState`) or in a child actor. The domain state belongs in the context. A
+keystroke does not.
+
+```ts
+import type { PlaySpec } from "@xmachines/play-view";
+
+const spec: PlaySpec = {
+	root: "root",
+	elements: {
+		root: {
+			type: "Profile",
+			props: { username: { $state: "/context/username" } },
+			children: [],
+		},
+	},
+};
+```
+
+> Historical note: an earlier version had a `contextProps` field. At first the field drove an
+> implicit prop-enrichment pass. That pass merged the allowlisted context fields and the URL
+> params into the props of every element. We removed it, because it put values into components
+> that never asked for them, and it let URL data from the user hide machine-owned state. The
+> field was then a projection filter for a short time. We removed that filter too, because a
+> limit on what a view can read added machinery without a real problem to solve. Always
+> validate the **derived** view (`actor.currentView.get()`), not the raw `meta.view`. The
+> `state` of the derived spec carries the projection, so a tool such as `validateSpec` sees a
+> spec that is consistent with itself.
+
+### `Viewable`
+
+Interface for actors that expose a renderable view signal.
+
+```ts
+import type { Viewable } from "@xmachines/play-view";
+import type { PlaySpec } from "@xmachines/play-view";
+import { Signal } from "@xmachines/play-signals";
+
+// currentView carries PlaySpec | null
+const signal = new Signal.State<PlaySpec | null>(null);
+const viewable: Viewable = { currentView: signal };
+```
+
+### `BaseActorProviderProps<TRegistry>`
+
+The framework-agnostic base props. Every `ActorProvider` implementation shares them: React, Vue, Solid, and Svelte. Each framework renderer package extends this interface.
+
+```ts
+import type { BaseActorProviderProps } from "@xmachines/play-view";
+import type { DefineRegistryResult } from "@xmachines/json-render-react";
+
+interface ActorProviderProps extends BaseActorProviderProps<DefineRegistryResult> {
+	fallback?: React.ReactNode;
+	children: React.ReactNode;
+}
+```
+
+### `BaseViewContextValue<TRegistry>`
+
+The framework-agnostic base of the `ViewContextValue` type in each framework. It holds the `spec`, `handlers`, `registry`, and `store` fields. These fields are identical in React, Vue, Solid, and Svelte.
+
+## Documentation
+
+- [Architecture](../../../contributing/architecture.md)
+- [Play RFC](../../../rfc/play.md)
+
+## License
+
+MIT
+
+## Modules
+
+- [errors](errors/README.md)
+- [index](index/README.md)

package/api/@xmachines/play-view/errors/README.md

@@ -0,0 +1,17 @@
+[API](../../../README.md) / [@xmachines/play-view](../README.md) / errors
+
+# errors
+
+The errors of the view half.
+
+Every error of this workspace extends `PlayError` of `@xmachines/play`, and it carries
+a `scope` and a `code` that stay the same across a patch release and a minor release.
+Match on the `code`, or on the class. Match on the `message` never.
+
+## See
+
+[Architecture](../../../../contributing/architecture.md)
+
+## Classes
+
+- [ReadOnlyContextError](classes/ReadOnlyContextError.md)