@koordinates/xstate-tree 4.4.0-beta.1 → 4.5.0

package/README.md

@@ -185,6 +185,42 @@ These events can be added anywhere, either next to a component for component spe
 2. If they are tied to a component they need to be in the index.ts file that imports the view/selectors/actions etc and calls `createXStateTreeMachine`. If they are in the file containing those functions the index.d.ts file will not end up importing them.
 
 
+### Utilities
+
+#### `viewToMachine`
+
+This utility accepts a React view that does not take any props and wraps it with an xstate-tree machine so you can easily invoke arbitrary React views in your xstate machines
+
+```
+function MyView() {
+  return <div>My View</div>;
+}
+
+const MyViewMachine = viewToMachine(MyView);
+```
+
+#### `buildRoutingMachine`
+
+This utility aims to reduce boilerplate by generating a common type of state machine, a routing machine. This is a machine that solely consists of routing events that transition to states that invoke xstate-tree machines.
+
+The first argument is the array of routes you wish to handle, and the second is an object mapping from those event types to the xstate-tree machine that will be invoked for that routing event
+
+```
+const routeA = createRoute.simpleRoute()({
+  url: "/a",
+  event: "GO_TO_A",
+});
+const routeB = createRoute.simpleRoute()({
+  url: "/b",
+  event: "GO_TO_B",
+});
+
+const RoutingMachine = buildRoutingMachine([routeA, routeB], {
+  GO_TO_A: MachineA,
+  GO_TO_B: MachineB,
+});
+```
+
 ### Type helpers
 
 There are some exported type helpers for use with xstate-tree

package/lib/builders.js

@@ -3,9 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.viewToMachine = exports.createXStateTreeMachine = exports.buildXStateTreeMachine = exports.buildView = exports.buildActions = exports.buildSelectors = void 0;
+exports.buildRoutingMachine = exports.viewToMachine = exports.createXStateTreeMachine = exports.buildXStateTreeMachine = exports.buildView = exports.buildActions = exports.buildSelectors = void 0;
 const react_1 = __importDefault(require("react"));
 const xstate_1 = require("xstate");
+const slots_1 = require("./slots");
 /**
  * @public
  *
@@ -158,8 +159,62 @@ exports.createXStateTreeMachine = createXStateTreeMachine;
  * @returns The view wrapped into an xstate-tree machine, ready to be invoked by other xstate machines or used with `buildRootComponent`
  */
 function viewToMachine(view) {
-    return createXStateTreeMachine((0, xstate_1.createMachine)({ initial: "idle", states: { idle: {} } }), {
+    return createXStateTreeMachine((0, xstate_1.createMachine)({
+        initial: "idle",
+        states: { idle: {} },
+    }), {
         View: view,
     });
 }
 exports.viewToMachine = viewToMachine;
+/**
+ * @public
+ *
+ * Utility to aid in reducing boilerplate of mapping route events to xstate-tree machines
+ *
+ * Takes a list of routes and a mapping of route events to xstate-tree machines and returns an xstate-tree machine
+ * that renders the machines based on the routing events
+ *
+ * @param _routes - the array of routes you wish to map to machines
+ * @param mappings - an object mapping the route events to the machine to invoke
+ * @returns an xstate-tree machine that will render the right machines based on the routing events
+ */
+function buildRoutingMachine(_routes, mappings) {
+    const contentSlot = (0, slots_1.singleSlot)("Content");
+    const mappingsToStates = Object.entries(mappings).reduce((acc, [event, _machine]) => {
+        return {
+            ...acc,
+            [event]: {
+                invoke: {
+                    src: (_ctx, e) => {
+                        return mappings[e.type];
+                    },
+                    id: contentSlot.getId(),
+                },
+            },
+        };
+    }, {});
+    const mappingsToEvents = Object.keys(mappings).reduce((acc, event) => ({
+        ...acc,
+        [event]: {
+            target: `.${event}`,
+        },
+    }), {});
+    const machine = (0, xstate_1.createMachine)({
+        on: {
+            ...mappingsToEvents,
+        },
+        initial: "idle",
+        states: {
+            idle: {},
+            ...mappingsToStates,
+        },
+    });
+    return createXStateTreeMachine(machine, {
+        slots: [contentSlot],
+        View: ({ slots }) => {
+            return react_1.default.createElement(slots.Content, null);
+        },
+    });
+}
+exports.buildRoutingMachine = buildRoutingMachine;

package/lib/xstate-tree.d.ts

@@ -182,6 +182,20 @@ export declare function buildRootComponent(machine: AnyXstateTreeMachine, routin
     rootMachine: AnyXstateTreeMachine;
 };
 
+/**
+ * @public
+ *
+ * Utility to aid in reducing boilerplate of mapping route events to xstate-tree machines
+ *
+ * Takes a list of routes and a mapping of route events to xstate-tree machines and returns an xstate-tree machine
+ * that renders the machines based on the routing events
+ *
+ * @param _routes - the array of routes you wish to map to machines
+ * @param mappings - an object mapping the route events to the machine to invoke
+ * @returns an xstate-tree machine that will render the right machines based on the routing events
+ */
+export declare function buildRoutingMachine<TRoutes extends AnyRoute[]>(_routes: TRoutes, mappings: Record<TRoutes[number]["event"], AnyXstateTreeMachine>): AnyXstateTreeMachine;
+
 /**
  * @public
  *

package/package.json

@@ -2,7 +2,7 @@
   "name": "@koordinates/xstate-tree",
   "main": "lib/index.js",
   "types": "lib/xstate-tree.d.ts",
-  "version": "4.4.0-beta.1",
+  "version": "4.5.0",
   "license": "MIT",
   "description": "Build UIs with Actors using xstate and React",
   "keywords": [