@xmachines/play-xstate 6.0.0 → 7.0.0

package/dist/state-meta.d.ts

@@ -1,18 +1,64 @@
 /**
- * The read of the `meta` of the active states, which BOTH capabilities share.
- *
- * `deriveCurrentRoute` folds this record into a URL, and `deriveCurrentView` folds the
- * same record into a view spec. The two therefore cannot move apart on the selection of
- * the branch, and they cannot move apart on their tolerance of a degenerate snapshot.
- *
- * It lives in its own module, and no longer beside the route derivation, because it
- * belongs to neither capability. `@xmachines/play-xstate/view` imported it from
- * `routing/derive-current-route.ts`, and that module reads `deriveRoute`, which names
- * `@xmachines/play-router`. A view-only application therefore loaded the whole route
- * derivation, and the OPTIONAL peer of the routing reached the runtime graph of the view
- * entry point.
+ * The walk of the active states, which BOTH capabilities share.
+ *
+ * `deriveCurrentRoute` folds the meta record of one active branch into a URL.
+ * `deriveCurrentView` walks the active tree with the same {@link branchOrder}, so a
+ * parallel node tries the region of the URL first for both. The view can still come from
+ * another region, when the region of the URL resolves to no view. For a snapshot without
+ * a machine tree, both read the flat `getMeta()` record.
+ *
+ * It lives in its own module, and not beside the route derivation, because it belongs to
+ * neither capability. `@xmachines/play-xstate/view` reads it, and a view-only application
+ * therefore loads no part of the route derivation.
  */
 import type { AnyMachineSnapshot } from "xstate";
+/** The part of an XState state node that the walks of this module read. */
+export interface BranchNode {
+    id: string;
+    meta?: unknown;
+    states?: Record<string, BranchNode>;
+}
+/**
+ * The keys of the active children of a node, from its part of `snapshot.value`: one key
+ * for a compound node, one for each region of a parallel node, in the order of the
+ * machine, and none for an atomic node.
+ */
+export declare const activeChildKeys: (value: unknown) => string[];
+/** The part of `snapshot.value` that belongs to the active child `key`. */
+export declare const activeChildValue: (value: unknown, key: string) => unknown;
+/**
+ * The keys of the active children of a node, in the order that a branch walk tries
+ * them. For a parallel node, one region comes first:
+ *
+ * 1. the first region whose ACTIVE subtree declares a `meta.route`;
+ * 2. else the first region that declares a route in any of its states. A region that
+ *    owns the routes keeps its place while it sits in a state without a route of its
+ *    own, such as a load;
+ * 3. else the first region.
+ *
+ * The other regions keep the order of the machine.
+ *
+ * A parallel machine often holds its routes in ONE region, and that region need not be
+ * the first one: a menu or a session region can come before it. The route derivation
+ * and the view derivation both follow this order, so the URL comes from the routed
+ * region, and the view without outlets comes from the region of the URL when that region
+ * resolves to a view.
+ */
+export declare const branchOrder: (node: BranchNode, value: unknown) => string[];
+/**
+ * Warns one time for each machine whose state ids break a record that is keyed on them.
+ *
+ * XState does not check that the ids of the states are unique, and a repeated id makes a
+ * `#id` target name two states. play-xstate keys the route, the view and its store on the
+ * id of a state, so a repeated id gives two states one route entry, one store, and one
+ * key. An id that is an array index, such as "42", moves to the front of every record that is
+ * keyed on ids, also the `getMeta()` record of XState, so the route of its state loses its
+ * place in the branch.
+ *
+ * The route derivation and the view derivation call this function. A read helper, such
+ * as {@link firstActiveBranchMeta}, writes no warning.
+ */
+export declare const warnStateIds: (root: BranchNode) => void;
 /**
  * Collects the `meta` object of the active state nodes of a SINGLE branch, from the
  * root to a leaf. The key of each entry is the state id, and the order is the
@@ -28,25 +74,35 @@ import type { AnyMachineSnapshot } from "xstate";
  * the meta keys are those ids, and they carry no information about the ancestry.
  *
  * Therefore this function walks `snapshot.value`, which holds the real hierarchy of
- * the active states by the state key, against the node tree of the machine. It
- * follows the FIRST active child at each level. This gives one deterministic branch,
- * which matches the historical behavior of "the first that it finds" for a parallel
- * machine. It also works with an explicit id, because each node carries its own `id`
- * and its own `meta`.
- *
- * The function returns `null` when the snapshot exposes no machine and no value to
- * walk. This is a defensive measure, because a real XState snapshot always exposes
- * them. The caller then uses `getMeta()`, as before.
+ * the active states by the state key, against the node tree of the machine. At each
+ * level it follows the first key of {@link branchOrder}: for a parallel node, that is
+ * the first region whose active subtree declares a route, else the first region that
+ * declares a route in any state, else the first region. This gives one deterministic
+ * branch. It also works with an explicit id,
+ * because each node carries its own `id` and its own `meta`.
+ *
+ * The function returns `null` when the snapshot exposes no machine tree to walk. This
+ * is a defensive measure, because a real XState snapshot always exposes one. The caller
+ * then reads the flat `getMeta()` record.
  */
 export declare const firstActiveBranchMeta: (snapshot: AnyMachineSnapshot) => Record<string, unknown> | null;
 /**
- * Resolves the meta record that the route derivation and the view derivation fold:
- * the single active branch that {@link firstActiveBranchMeta} walks, which is
- * correct for a parallel machine and for an explicit id, or the flat `getMeta()`
- * record when the snapshot has no machine tree to walk. `deriveCurrentRoute` and
- * `deriveCurrentView` share this function. Therefore the two sides cannot move apart
- * on the selection of the branch, and they cannot move apart on their tolerance of a
- * degenerate snapshot.
+ * Resolves the meta record that the route derivation folds: the single active branch
+ * that {@link firstActiveBranchMeta} walks, which is correct for a parallel machine and
+ * for an explicit id, or the flat `getMeta()` record when the snapshot has no machine
+ * tree to walk.
+ *
+ * The view derivation does not call this function. It walks the tree with
+ * `resolveViewTree`, which shares {@link branchOrder}, so both sides try the routed
+ * region of a parallel node first. They can still select different regions: when the
+ * routed region resolves to no view, the view comes from the next region that resolves
+ * to one, and the route stays in the routed region.
  */
 export declare const activeStateMeta: (snapshot: AnyMachineSnapshot) => Record<string, unknown> | null;
+/**
+ * The flat `getMeta()` record of a snapshot, or `null` when the snapshot gives none. The
+ * keys of the ancestors come first. Both derivations read it for a snapshot that exposes
+ * no machine tree, so they read it through this one function.
+ */
+export declare const flatStateMeta: (snapshot: AnyMachineSnapshot) => Record<string, unknown> | null;
 //# sourceMappingURL=state-meta.d.ts.map

package/dist/state-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-meta.d.ts","sourceRoot":"","sources":["../src/state-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,qBAAqB,GACjC,UAAU,kBAAkB,KAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAqC5B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,kBAAkB,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAMxF,CAAC"}
+{"version":3,"file":"state-meta.d.ts","sourceRoot":"","sources":["../src/state-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,MAAM,EAKhD,CAAC;AAER,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,EAAE,KAAK,MAAM,KAAG,OAGlD,CAAC;AA8Bd;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,UAAU,EAAE,OAAO,OAAO,KAAG,MAAM,EAgBpE,CAAC;AAaF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,UAAU,KAAG,IA2B/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,qBAAqB,GACjC,UAAU,kBAAkB,KAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAgC5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,kBAAkB,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAGxF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,kBAAkB,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAItF,CAAC"}

package/dist/state-meta.js

@@ -1,77 +1,175 @@
+//#region packages/play-xstate/src/state-meta.ts
 /**
- * Collects the `meta` object of the active state nodes of a SINGLE branch, from the
- * root to a leaf. The key of each entry is the state id, and the order is the
- * ancestors first. {@link deriveRoute} folds this shape.
- *
- * `snapshot.getMeta()` returns a FLAT record of the meta object of every active
- * state. For a machine that is not parallel, that record is one chain of ancestors
- * already. For a PARALLEL machine, it mixes the entries of every active region. A
- * blind fold therefore joins a relative route of one region to an absolute route of
- * a sibling region, and the URL belongs to the tree of neither region. The flat
- * record also cannot go back into a hierarchy: when a state declares an explicit
- * `id`, for example a child with `id: "dashboard-overview"` under `id: "dashboard"`,
- * the meta keys are those ids, and they carry no information about the ancestry.
- *
- * Therefore this function walks `snapshot.value`, which holds the real hierarchy of
- * the active states by the state key, against the node tree of the machine. It
- * follows the FIRST active child at each level. This gives one deterministic branch,
- * which matches the historical behavior of "the first that it finds" for a parallel
- * machine. It also works with an explicit id, because each node carries its own `id`
- * and its own `meta`.
- *
- * The function returns `null` when the snapshot exposes no machine and no value to
- * walk. This is a defensive measure, because a real XState snapshot always exposes
- * them. The caller then uses `getMeta()`, as before.
- */
-export const firstActiveBranchMeta = (snapshot) => {
-    const root = snapshot.machine?.root;
-    if (!root)
-        return null;
-    const ordered = {};
-    let node = root;
-    let value = snapshot.value;
-    while (node) {
-        if (node.meta && typeof node.meta === "object") {
-            ordered[node.id] = node.meta; // nosemgrep: gitlab.eslint.detect-object-injection
-        }
-        // Find the key of the active child at this level. A string value is the name of an
-        // atomic active leaf. An object value is a compound node, with one key, or a
-        // parallel node, with many keys: take the first key, for one deterministic
-        // branch.
-        let key;
-        if (typeof value === "string") {
-            key = value;
-        }
-        else if (value && typeof value === "object") {
-            key = Object.keys(value)[0];
-        }
-        if (key === undefined)
-            break;
-        const child = node.states?.[key]; // nosemgrep: gitlab.eslint.detect-object-injection
-        if (!child)
-            break;
-        value =
-            typeof value === "object" && value !== null
-                ? value[key] // nosemgrep: gitlab.eslint.detect-object-injection
-                : {};
-        node = child;
-    }
-    return ordered;
+* The keys of the active children of a node, from its part of `snapshot.value`: one key
+* for a compound node, one for each region of a parallel node, in the order of the
+* machine, and none for an atomic node.
+*/
+var activeChildKeys = (value) => typeof value === "string" ? [value] : value !== null && typeof value === "object" ? Object.keys(value) : [];
+/** The part of `snapshot.value` that belongs to the active child `key`. */
+var activeChildValue = (value, key) => value !== null && typeof value === "object" ? value[key] : void 0;
+var declaresRoute = (node) => node.meta !== null && typeof node.meta === "object" && node.meta.route !== void 0;
+/** `true` when a state of the active subtree of `node` declares a `meta.route`. */
+var routeBelow = (node, value) => {
+	if (declaresRoute(node)) return true;
+	for (const key of activeChildKeys(value)) {
+		const child = node.states?.[key];
+		if (child && routeBelow(child, activeChildValue(value, key))) return true;
+	}
+	return false;
+};
+var routesByNode = /* @__PURE__ */ new WeakMap();
+var holdsRoutes = (node) => {
+	let holds = routesByNode.get(node);
+	if (holds === void 0) {
+		holds = declaresRoute(node) || Object.values(node.states ?? {}).some(holdsRoutes);
+		routesByNode.set(node, holds);
+	}
+	return holds;
+};
+/**
+* The keys of the active children of a node, in the order that a branch walk tries
+* them. For a parallel node, one region comes first:
+*
+* 1. the first region whose ACTIVE subtree declares a `meta.route`;
+* 2. else the first region that declares a route in any of its states. A region that
+*    owns the routes keeps its place while it sits in a state without a route of its
+*    own, such as a load;
+* 3. else the first region.
+*
+* The other regions keep the order of the machine.
+*
+* A parallel machine often holds its routes in ONE region, and that region need not be
+* the first one: a menu or a session region can come before it. The route derivation
+* and the view derivation both follow this order, so the URL comes from the routed
+* region, and the view without outlets comes from the region of the URL when that region
+* resolves to a view.
+*/
+var branchOrder = (node, value) => {
+	const keys = activeChildKeys(value);
+	if (keys.length < 2) return keys;
+	const childOf = (key) => node.states?.[key];
+	const routed = keys.find((key) => {
+		const child = childOf(key);
+		return child !== void 0 && routeBelow(child, activeChildValue(value, key));
+	}) ?? keys.find((key) => {
+		const child = childOf(key);
+		return child !== void 0 && holdsRoutes(child);
+	});
+	return routed === void 0 || routed === keys[0] ? keys : [routed, ...keys.filter((key) => key !== routed)];
+};
+var checkedMachines = /* @__PURE__ */ new WeakSet();
+/**
+* An id that JavaScript reads as an array index: a whole number from 0 to 2^32 - 2, with
+* no leading zero. An object lists such a key before every other key.
+*/
+var isIndexLike = (id) => /^(0|[1-9]\d*)$/.test(id) && Number(id) < 2 ** 32 - 1;
+/** The ids in quotes, separated by commas, for a warning. */
+var quoted = (ids) => [...ids].map((id) => `"${id}"`).join(", ");
+/**
+* Warns one time for each machine whose state ids break a record that is keyed on them.
+*
+* XState does not check that the ids of the states are unique, and a repeated id makes a
+* `#id` target name two states. play-xstate keys the route, the view and its store on the
+* id of a state, so a repeated id gives two states one route entry, one store, and one
+* key. An id that is an array index, such as "42", moves to the front of every record that is
+* keyed on ids, also the `getMeta()` record of XState, so the route of its state loses its
+* place in the branch.
+*
+* The route derivation and the view derivation call this function. A read helper, such
+* as {@link firstActiveBranchMeta}, writes no warning.
+*/
+var warnStateIds = (root) => {
+	if (checkedMachines.has(root)) return;
+	checkedMachines.add(root);
+	const seen = /* @__PURE__ */ new Set();
+	const repeated = /* @__PURE__ */ new Set();
+	const indexLike = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (seen.has(node.id)) repeated.add(node.id);
+		seen.add(node.id);
+		if (isIndexLike(node.id)) indexLike.add(node.id);
+		for (const child of Object.values(node.states ?? {})) visit(child);
+	};
+	visit(root);
+	const faults = [...repeated.size > 0 ? [`it gives two or more states the same id (${quoted(repeated)})`] : [], ...indexLike.size > 0 ? [`it gives a state an id that is an array index (${quoted(indexLike)})`] : []];
+	if (faults.length === 0) return;
+	console.warn(`[play-xstate] The state ids of the machine "${root.id}" break a rule: ${faults.join("; ")}. play-xstate keys the route, the view and its store on the id of a state. Give each state its own id, and do not use an array index as an id.`);
+};
+/**
+* Collects the `meta` object of the active state nodes of a SINGLE branch, from the
+* root to a leaf. The key of each entry is the state id, and the order is the
+* ancestors first. {@link deriveRoute} folds this shape.
+*
+* `snapshot.getMeta()` returns a FLAT record of the meta object of every active
+* state. For a machine that is not parallel, that record is one chain of ancestors
+* already. For a PARALLEL machine, it mixes the entries of every active region. A
+* blind fold therefore joins a relative route of one region to an absolute route of
+* a sibling region, and the URL belongs to the tree of neither region. The flat
+* record also cannot go back into a hierarchy: when a state declares an explicit
+* `id`, for example a child with `id: "dashboard-overview"` under `id: "dashboard"`,
+* the meta keys are those ids, and they carry no information about the ancestry.
+*
+* Therefore this function walks `snapshot.value`, which holds the real hierarchy of
+* the active states by the state key, against the node tree of the machine. At each
+* level it follows the first key of {@link branchOrder}: for a parallel node, that is
+* the first region whose active subtree declares a route, else the first region that
+* declares a route in any state, else the first region. This gives one deterministic
+* branch. It also works with an explicit id,
+* because each node carries its own `id` and its own `meta`.
+*
+* The function returns `null` when the snapshot exposes no machine tree to walk. This
+* is a defensive measure, because a real XState snapshot always exposes one. The caller
+* then reads the flat `getMeta()` record.
+*/
+var firstActiveBranchMeta = (snapshot) => {
+	const root = snapshot.machine?.root;
+	if (!root) return null;
+	const ordered = {};
+	let node = root;
+	let value = snapshot.value;
+	while (node) {
+		if (node.meta && typeof node.meta === "object") Object.defineProperty(ordered, node.id, {
+			value: node.meta,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+		const key = branchOrder(node, value)[0];
+		if (key === void 0) break;
+		const child = node.states?.[key];
+		if (!child) break;
+		value = activeChildValue(value, key);
+		node = child;
+	}
+	return ordered;
+};
+/**
+* Resolves the meta record that the route derivation folds: the single active branch
+* that {@link firstActiveBranchMeta} walks, which is correct for a parallel machine and
+* for an explicit id, or the flat `getMeta()` record when the snapshot has no machine
+* tree to walk.
+*
+* The view derivation does not call this function. It walks the tree with
+* `resolveViewTree`, which shares {@link branchOrder}, so both sides try the routed
+* region of a parallel node first. They can still select different regions: when the
+* routed region resolves to no view, the view comes from the next region that resolves
+* to one, and the route stays in the routed region.
+*/
+var activeStateMeta = (snapshot) => {
+	if (!snapshot) return null;
+	return firstActiveBranchMeta(snapshot) ?? flatStateMeta(snapshot);
 };
 /**
- * Resolves the meta record that the route derivation and the view derivation fold:
- * the single active branch that {@link firstActiveBranchMeta} walks, which is
- * correct for a parallel machine and for an explicit id, or the flat `getMeta()`
- * record when the snapshot has no machine tree to walk. `deriveCurrentRoute` and
- * `deriveCurrentView` share this function. Therefore the two sides cannot move apart
- * on the selection of the branch, and they cannot move apart on their tolerance of a
- * degenerate snapshot.
- */
-export const activeStateMeta = (snapshot) => {
-    if (!snapshot || typeof snapshot.getMeta !== "function") {
-        return null;
-    }
-    const meta = firstActiveBranchMeta(snapshot) ?? snapshot.getMeta();
-    return meta && typeof meta === "object" ? meta : null;
+* The flat `getMeta()` record of a snapshot, or `null` when the snapshot gives none. The
+* keys of the ancestors come first. Both derivations read it for a snapshot that exposes
+* no machine tree, so they read it through this one function.
+*/
+var flatStateMeta = (snapshot) => {
+	if (!snapshot || typeof snapshot.getMeta !== "function") return null;
+	const meta = snapshot.getMeta();
+	return meta && typeof meta === "object" ? meta : null;
 };
+//#endregion
+export { activeChildKeys, activeChildValue, activeStateMeta, branchOrder, firstActiveBranchMeta, flatStateMeta, warnStateIds };
+
 //# sourceMappingURL=state-meta.js.map

package/dist/state-meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-meta.js","sourceRoot":"","sources":["../src/state-meta.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACpC,QAA4B,EACK,EAAE;IACnC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,IAEnB,CAAC;IACb,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,IAAI,IAAI,GAA4B,IAAI,CAAC;IACzC,IAAI,KAAK,GAAY,QAAQ,CAAC,KAAK,CAAC;IAEpC,OAAO,IAAI,EAAE,CAAC;QACb,IAAI,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAChD,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,mDAAmD;QAClF,CAAC;QAED,mFAAmF;QACnF,6EAA6E;QAC7E,2EAA2E;QAC3E,UAAU;QACV,IAAI,GAAuB,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/B,GAAG,GAAG,KAAK,CAAC;QACb,CAAC;aAAM,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/C,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;QACD,IAAI,GAAG,KAAK,SAAS;YAAE,MAAM;QAE7B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,CAA4B,CAAC,CAAC,mDAAmD;QAChH,IAAI,CAAC,KAAK;YAAE,MAAM;QAClB,KAAK;YACJ,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAC1C,CAAC,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,mDAAmD;gBAC7F,CAAC,CAAC,EAAE,CAAC;QACP,IAAI,GAAG,KAAK,CAAC;IACd,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,QAA4B,EAAkC,EAAE;IAC/F,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC;IACb,CAAC;IACD,MAAM,IAAI,GAAG,qBAAqB,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;IACnE,OAAO,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAgC,CAAC,CAAC,CAAC,IAAI,CAAC;AACpF,CAAC,CAAC"}
+{"version":3,"file":"state-meta.js","names":[],"sources":["../src/state-meta.ts"],"sourcesContent":["/**\n * The walk of the active states, which BOTH capabilities share.\n *\n * `deriveCurrentRoute` folds the meta record of one active branch into a URL.\n * `deriveCurrentView` walks the active tree with the same {@link branchOrder}, so a\n * parallel node tries the region of the URL first for both. The view can still come from\n * another region, when the region of the URL resolves to no view. For a snapshot without\n * a machine tree, both read the flat `getMeta()` record.\n *\n * It lives in its own module, and not beside the route derivation, because it belongs to\n * neither capability. `@xmachines/play-xstate/view` reads it, and a view-only application\n * therefore loads no part of the route derivation.\n */\nimport type { AnyMachineSnapshot } from \"xstate\";\n\n/** The part of an XState state node that the walks of this module read. */\nexport interface BranchNode {\n\tid: string;\n\tmeta?: unknown;\n\tstates?: Record<string, BranchNode>;\n}\n\n/**\n * The keys of the active children of a node, from its part of `snapshot.value`: one key\n * for a compound node, one for each region of a parallel node, in the order of the\n * machine, and none for an atomic node.\n */\nexport const activeChildKeys = (value: unknown): string[] =>\n\ttypeof value === \"string\"\n\t\t? [value]\n\t\t: value !== null && typeof value === \"object\"\n\t\t\t? Object.keys(value)\n\t\t\t: [];\n\n/** The part of `snapshot.value` that belongs to the active child `key`. */\nexport const activeChildValue = (value: unknown, key: string): unknown =>\n\tvalue !== null && typeof value === \"object\"\n\t\t? (value as Record<string, unknown>)[key] // nosemgrep: gitlab.eslint.detect-object-injection\n\t\t: undefined;\n\nconst declaresRoute = (node: BranchNode): boolean =>\n\tnode.meta !== null &&\n\ttypeof node.meta === \"object\" &&\n\t(node.meta as { route?: unknown }).route !== undefined;\n\n/** `true` when a state of the active subtree of `node` declares a `meta.route`. */\nconst routeBelow = (node: BranchNode, value: unknown): boolean => {\n\tif (declaresRoute(node)) return true;\n\tfor (const key of activeChildKeys(value)) {\n\t\tconst child = node.states?.[key]; // nosemgrep: gitlab.eslint.detect-object-injection\n\t\tif (child && routeBelow(child, activeChildValue(value, key))) return true;\n\t}\n\treturn false;\n};\n\n// Whether a state node or one of its descendants declares a `meta.route`, for each\n// node. The state nodes of a machine are static, so one answer holds for its life.\nconst routesByNode = new WeakMap<BranchNode, boolean>();\n\nconst holdsRoutes = (node: BranchNode): boolean => {\n\tlet holds = routesByNode.get(node);\n\tif (holds === undefined) {\n\t\tholds = declaresRoute(node) || Object.values(node.states ?? {}).some(holdsRoutes);\n\t\troutesByNode.set(node, holds);\n\t}\n\treturn holds;\n};\n\n/**\n * The keys of the active children of a node, in the order that a branch walk tries\n * them. For a parallel node, one region comes first:\n *\n * 1. the first region whose ACTIVE subtree declares a `meta.route`;\n * 2. else the first region that declares a route in any of its states. A region that\n *    owns the routes keeps its place while it sits in a state without a route of its\n *    own, such as a load;\n * 3. else the first region.\n *\n * The other regions keep the order of the machine.\n *\n * A parallel machine often holds its routes in ONE region, and that region need not be\n * the first one: a menu or a session region can come before it. The route derivation\n * and the view derivation both follow this order, so the URL comes from the routed\n * region, and the view without outlets comes from the region of the URL when that region\n * resolves to a view.\n */\nexport const branchOrder = (node: BranchNode, value: unknown): string[] => {\n\tconst keys = activeChildKeys(value);\n\tif (keys.length < 2) return keys;\n\tconst childOf = (key: string): BranchNode | undefined => node.states?.[key]; // nosemgrep: gitlab.eslint.detect-object-injection\n\tconst routed =\n\t\tkeys.find((key) => {\n\t\t\tconst child = childOf(key);\n\t\t\treturn child !== undefined && routeBelow(child, activeChildValue(value, key));\n\t\t}) ??\n\t\tkeys.find((key) => {\n\t\t\tconst child = childOf(key);\n\t\t\treturn child !== undefined && holdsRoutes(child);\n\t\t});\n\treturn routed === undefined || routed === keys[0]\n\t\t? keys\n\t\t: [routed, ...keys.filter((key) => key !== routed)];\n};\n\nconst checkedMachines = new WeakSet<BranchNode>();\n\n/**\n * An id that JavaScript reads as an array index: a whole number from 0 to 2^32 - 2, with\n * no leading zero. An object lists such a key before every other key.\n */\nconst isIndexLike = (id: string): boolean => /^(0|[1-9]\\d*)$/.test(id) && Number(id) < 2 ** 32 - 1;\n\n/** The ids in quotes, separated by commas, for a warning. */\nconst quoted = (ids: Set<string>): string => [...ids].map((id) => `\"${id}\"`).join(\", \");\n\n/**\n * Warns one time for each machine whose state ids break a record that is keyed on them.\n *\n * XState does not check that the ids of the states are unique, and a repeated id makes a\n * `#id` target name two states. play-xstate keys the route, the view and its store on the\n * id of a state, so a repeated id gives two states one route entry, one store, and one\n * key. An id that is an array index, such as \"42\", moves to the front of every record that is\n * keyed on ids, also the `getMeta()` record of XState, so the route of its state loses its\n * place in the branch.\n *\n * The route derivation and the view derivation call this function. A read helper, such\n * as {@link firstActiveBranchMeta}, writes no warning.\n */\nexport const warnStateIds = (root: BranchNode): void => {\n\tif (checkedMachines.has(root)) return;\n\tcheckedMachines.add(root);\n\tconst seen = new Set<string>();\n\tconst repeated = new Set<string>();\n\tconst indexLike = new Set<string>();\n\tconst visit = (node: BranchNode): void => {\n\t\tif (seen.has(node.id)) repeated.add(node.id);\n\t\tseen.add(node.id);\n\t\tif (isIndexLike(node.id)) indexLike.add(node.id);\n\t\tfor (const child of Object.values(node.states ?? {})) visit(child);\n\t};\n\tvisit(root);\n\tconst faults = [\n\t\t...(repeated.size > 0\n\t\t\t? [`it gives two or more states the same id (${quoted(repeated)})`]\n\t\t\t: []),\n\t\t...(indexLike.size > 0\n\t\t\t? [`it gives a state an id that is an array index (${quoted(indexLike)})`]\n\t\t\t: []),\n\t];\n\tif (faults.length === 0) return;\n\tconsole.warn(\n\t\t`[play-xstate] The state ids of the machine \"${root.id}\" break a rule: ` +\n\t\t\t`${faults.join(\"; \")}. play-xstate keys the route, the view and its store on the id ` +\n\t\t\t\"of a state. Give each state its own id, and do not use an array index as an id.\",\n\t);\n};\n\n/**\n * Collects the `meta` object of the active state nodes of a SINGLE branch, from the\n * root to a leaf. The key of each entry is the state id, and the order is the\n * ancestors first. {@link deriveRoute} folds this shape.\n *\n * `snapshot.getMeta()` returns a FLAT record of the meta object of every active\n * state. For a machine that is not parallel, that record is one chain of ancestors\n * already. For a PARALLEL machine, it mixes the entries of every active region. A\n * blind fold therefore joins a relative route of one region to an absolute route of\n * a sibling region, and the URL belongs to the tree of neither region. The flat\n * record also cannot go back into a hierarchy: when a state declares an explicit\n * `id`, for example a child with `id: \"dashboard-overview\"` under `id: \"dashboard\"`,\n * the meta keys are those ids, and they carry no information about the ancestry.\n *\n * Therefore this function walks `snapshot.value`, which holds the real hierarchy of\n * the active states by the state key, against the node tree of the machine. At each\n * level it follows the first key of {@link branchOrder}: for a parallel node, that is\n * the first region whose active subtree declares a route, else the first region that\n * declares a route in any state, else the first region. This gives one deterministic\n * branch. It also works with an explicit id,\n * because each node carries its own `id` and its own `meta`.\n *\n * The function returns `null` when the snapshot exposes no machine tree to walk. This\n * is a defensive measure, because a real XState snapshot always exposes one. The caller\n * then reads the flat `getMeta()` record.\n */\nexport const firstActiveBranchMeta = (\n\tsnapshot: AnyMachineSnapshot,\n): Record<string, unknown> | null => {\n\tconst root = snapshot.machine?.root as BranchNode | undefined;\n\tif (!root) return null;\n\n\tconst ordered: Record<string, unknown> = {};\n\tlet node: BranchNode | undefined = root;\n\tlet value: unknown = snapshot.value;\n\n\twhile (node) {\n\t\tif (node.meta && typeof node.meta === \"object\") {\n\t\t\t// A definition, and not an assignment: an id \"__proto__\" would set the prototype\n\t\t\t// of the record, and the entry would leave Object.entries.\n\t\t\tObject.defineProperty(ordered, node.id, {\n\t\t\t\tvalue: node.meta,\n\t\t\t\tenumerable: true,\n\t\t\t\twritable: true,\n\t\t\t\tconfigurable: true,\n\t\t\t});\n\t\t}\n\n\t\t// The key of the active child at this level: the name of an atomic active leaf, the\n\t\t// one key of a compound node, or the routed region of a parallel node.\n\t\tconst key: string | undefined = branchOrder(node, value)[0];\n\t\tif (key === undefined) break;\n\n\t\tconst child: BranchNode | undefined = node.states?.[key]; // nosemgrep: gitlab.eslint.detect-object-injection\n\t\tif (!child) break;\n\t\tvalue = activeChildValue(value, key);\n\t\tnode = child;\n\t}\n\n\treturn ordered;\n};\n\n/**\n * Resolves the meta record that the route derivation folds: the single active branch\n * that {@link firstActiveBranchMeta} walks, which is correct for a parallel machine and\n * for an explicit id, or the flat `getMeta()` record when the snapshot has no machine\n * tree to walk.\n *\n * The view derivation does not call this function. It walks the tree with\n * `resolveViewTree`, which shares {@link branchOrder}, so both sides try the routed\n * region of a parallel node first. They can still select different regions: when the\n * routed region resolves to no view, the view comes from the next region that resolves\n * to one, and the route stays in the routed region.\n */\nexport const activeStateMeta = (snapshot: AnyMachineSnapshot): Record<string, unknown> | null => {\n\tif (!snapshot) return null;\n\treturn firstActiveBranchMeta(snapshot) ?? flatStateMeta(snapshot);\n};\n\n/**\n * The flat `getMeta()` record of a snapshot, or `null` when the snapshot gives none. The\n * keys of the ancestors come first. Both derivations read it for a snapshot that exposes\n * no machine tree, so they read it through this one function.\n */\nexport const flatStateMeta = (snapshot: AnyMachineSnapshot): Record<string, unknown> | null => {\n\tif (!snapshot || typeof snapshot.getMeta !== \"function\") return null;\n\tconst meta: unknown = snapshot.getMeta();\n\treturn meta && typeof meta === \"object\" ? (meta as Record<string, unknown>) : null;\n};\n"],"mappings":"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"}

package/dist/view/derive-current-view.d.ts

@@ -2,9 +2,10 @@
  * The view derivation — the meta.view half of the player pipeline.
  *
  * This file is beside src/routing/, so that player-actor.ts holds the actor
- * itself only: the atoms, the hooks, and the lifecycle. The walk over the active
- * branch is shared with the route derivation. Therefore the view of a parallel
- * machine always belongs to the region of its URL.
+ * itself only: the atoms, the hooks, and the lifecycle. The walk shares
+ * `branchOrder` with the route derivation, so a parallel node tries the region of its
+ * URL first. When that region resolves to no view, the view comes from the next region
+ * that resolves to one.
  */
 import type { AnyMachineSnapshot } from "xstate";
 import { type PlaySpec } from "@xmachines/play-view";
@@ -37,13 +38,20 @@ import { type PlaySpec } from "@xmachines/play-view";
  *
  * ### The viewKey
  *
- * The derived spec carries a `viewKey` field. Its value is the key of the meta
- * record, which is the id of the state node, of the entry that this derivation
- * selected. A provider uses it as the key of its store lifecycle: a new key seeds
- * the store again, and the same key refreshes `/context` in place. The value comes
- * from the selected entry, and not from "the id of the active state", because for a
- * parallel machine the branch of the walk and the flat `getMeta()` fallback can
- * select a view of a different region than the leaf of the branch.
+ * The derived spec carries a `viewKey` field. Its value is the id of the state node
+ * whose view the walk selected: the outermost state that composes with `outlets`, or
+ * the state of the deepest view. A provider uses it as the key of its store lifecycle:
+ * a new key seeds the store again, and the same key refreshes `/context` in place. The
+ * value comes from the selected view, and not from "the id of the active state",
+ * because for a parallel machine the walk can select a view of a different region than
+ * the leaf of the routed branch.
+ *
+ * ### One rule
+ *
+ * One walk of the active state tree derives every view, and a machine with no
+ * `outlets` is its simple case: the deepest view wins. Declare `outlets` on a state to
+ * show its view beside the views of its children. A snapshot that exposes no machine
+ * tree falls back to its flat `getMeta()` record, as the route derivation does.
  *
  * @param snapshot - The current snapshot of the XState machine.
  * @returns The derived `PlaySpec`, or `null` when the current state has no view metadata.

package/dist/view/derive-current-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-current-view.d.ts","sourceRoot":"","sources":["../../src/view/derive-current-view.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAiC,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAyEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,kBAAkB,KAAG,QAAQ,GAAG,IA4C3E,CAAC"}
+{"version":3,"file":"derive-current-view.d.ts","sourceRoot":"","sources":["../../src/view/derive-current-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAKN,KAAK,QAAQ,EAIb,MAAM,sBAAsB,CAAC;AAqO9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,kBAAkB,KAAG,QAAQ,GAAG,IAmC3E,CAAC"}