@koordinates/xstate-tree 1.0.0-beta.1

package/README.md

@@ -0,0 +1,90 @@
+# xstate-tree
+
+xstate-tree is a React state management framework built using XState. It allows you to create a tree of XState machines and map them to a tree of React views representing them as a UI.
+
+## Overview
+
+Each machine that forms the tree representing your UI has an associated set of selector, action, view functions, and "slots"
+  - Selector functions are provided with the current context of the machine, a function to determine if it can handle a given event and a function to determine if it is in a given state, and expose the returned result to the view.
+  - Action functions are provided with the `send` method bound to the machines interpreter and the result of calling the selector function
+  - Slots are how children of the machine are exposed to the view. They can be either single slot, a single machine, or multi slot for when you have a list of actors. 
+  - View functions are React views provided with the output of the selector and action functions, a function to determine if the machine is in a given state, and the currently active slots
+
+## API
+
+To assist in making xstate-tree easy to use with TypeScript there are "builder" functions for selectors, actions, views and the final XState tree machine itself. These functions primarily exist to type the arguments passed into the selector/action/view functions.
+
+* `buildSelectors`, first argument is the machine we are creating selectors for, second argument is the selector factory which receives the machines context as the first argument. It also memoizes the selector factory for better rendering performance  
+* `buildActions`, first argument is the machine we are creating actions for, the second argument is the result of `buildSelectors` and the third argument is the actions factory which receives an XState `send` function and the result of calling the selectors factory. It also memoizes the selector factory for better rendering performance  
+* `buildView`, first argument is the machine we are creating a view for, second argument is the selector factory, third argument is the actions factory, fourth argument is the array of slots and the fifth argument is the view function itself which gets supplied the selectors, actions, slots and `inState` method as props. It wraps the view in a React.memo  
+* `buildXStateTreeMachine` takes the results of `buildSelectors`, `buildActions`, `buildView` and the list of slots and returns an xstate-tree compatible machine
+
+### Slots
+
+Slots are how invoked/spawned children of the machine are supplied to the Machines view. The child machines get wrapped into a React component responsible for rendering the machine itself. Since the view is provided with these components it is responsible for determining where in the view output they show up. This leaves the view in complete control of where the child views are placed.
+
+Slotted machines are determined based on the id of the invoked/spawned machine. There are two types of slots, single and multi. Single slots are for invoked machines, where there will only be a single machine per slot. Multi slots are for spawned machines where there are multiple children per slot, rendered as a group; think lists. There is a set of helper functions for creating slots which in turn can be used to get the id for the slot.
+
+`singleSlot` accepts the name of the slot (must not end in `s`) as the first argument and returns an object with a method `getId()` that returns the id of the slot.  
+`multiSlot` accepts the name of the slot (must end in `s`) and returns an object with a method `getId(id: string)` that returns the id of the slot
+
+You should always use the `getId` methods when invoking/spawning something into a slot. Each slot the machine has must be represented by a call to `singleSlot` or `multiSlot` and stored into an array of slots. These slots must be passed to the `buildView` and `buildXStateTreeMachine` functions.
+
+### Inter-machine communication
+
+Communicating between multiple independent xstate machines is done via the `broadcast` function.
+Any event broadcast via this function is sent to every machine that has the event in its `nextEvents` array, so it won't get sent to machines that have no handler for the event.
+
+To get access to the type information for these events in a machine listening for it, use the `PickEvent` type to extract the events you are interested in
+
+ie `PickEvent<"FOO" | "BAR">` will return `{type: "FOO" } | { type: "BAR" }` which can be added to your machines event union.
+
+To provide the type information on what events are available you add them to the global XstateTreeEvents interface. This is done using `declare global`
+
+```
+declare global {
+  interface XstateTreeEvents {
+    BASIC: string;
+    WITH_PAYLOAD: { a: "payload" }
+  }
+}
+```
+
+That adds two events to the system, a no payload event (`{ type: "BASIC" }`) and event with payload (`{ type: "WITH_PAYLOAD"; a: "payload" }`). These events will now be visible in the typings for `broadcast` and `PickEvent`. The property name is the `type` of the event and the type of the property is the payload of the event. If the event has no payload, use `string`.
+
+These events can be added anywhere, either next to a component for component specific events or in a module for events that are for multiple machines. One thing that it is important to keep in mind is that these `declare global` declarations must be loaded by the `.d.ts` files when importing the component, otherwise the events will be missing. Which means
+
+1. If they are in their own file, say for a module level declaration, that file will need to be imported somewhere. Somewhere that using a component will trigger the import
+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 `buildXstateTreeMachine`. If they are in the file containing those functions the index.d.ts file will not end up importing them.
+
+
+### Storybook
+
+It's relatively uncomplicated to display xstate-tree views directly in Storybook. Since the views are plain React components
+that accept selectors/actions/slots/inState as props you can just import the view and render it in a Story
+
+There are a few utilities in xstate-tree to make this easier
+
+#### `buildViewProps`
+This is a builder function that accepts a view to provide typings and then an object containing
+actions/selector fields. With the typings it provides these fields are type safe and you can autocomplete them.
+
+It returns the props object and extends it with an `inState` factory function, so you can destructure it for use in Stories. The `inState` function accepts a state string as an argument, and returns a function that returns true if the state supplied matches that. So you can easily render the view in a specific machine state in the Story
+```
+const { actions, selectors, inState } = buildViewProps(view, { actions: {], selectors: {} });
+```
+
+#### `genericSlotsTestingDummy`
+
+This is a simple Proxy object that renders a <div> containing the name of the slot whenever rendering
+a slot is attempted in the view. This will suffice as an argument for the slots prop in most views
+when rendering them in a Story
+
+#### `slotTestingDummyFactory`
+
+This is not relevant if using the render-view-component approach. But useful if you
+are planning on rendering the view using the xstate-tree machine itself, or testing the machine 
+via the view.
+
+It's a simple function that takes a name argument and returns a basic xstate-tree machine that you
+can replace slot services with. It just renders a div containing the name supplied

package/lib/builders.js

@@ -0,0 +1,62 @@
+import React from "react";
+/**
+ * @public
+ */
+export function buildSelectors(__machine, selectors) {
+    let lastState = undefined;
+    let lastCachedResult = undefined;
+    let lastCtxRef = undefined;
+    return (ctx, canHandleEvent, inState, currentState) => {
+        // Handles caching to ensure stable references to selector results
+        // Only re-run the selector if
+        // * The reference to the context object has changed (the context object should never be mutated)
+        // * The last state we ran the selectors in has changed. This is to ensure `canHandleEvent` and `inState` calls aren't stale
+        if (lastCtxRef === ctx &&
+            lastState === currentState &&
+            lastCachedResult !== undefined) {
+            return lastCachedResult;
+        }
+        else {
+            const result = selectors(ctx, canHandleEvent, inState, currentState);
+            lastCtxRef = ctx;
+            lastCachedResult = result;
+            lastState = currentState;
+            return result;
+        }
+    };
+}
+/**
+ * @public
+ */
+export function buildActions(__machine, __selectors, actions) {
+    let lastSelectorResult = undefined;
+    let lastCachedResult = undefined;
+    let lastSendReference = undefined;
+    return (send, selectors) => {
+        if (lastSelectorResult === selectors &&
+            lastCachedResult !== undefined &&
+            lastSendReference === send) {
+            return lastCachedResult;
+        }
+        lastCachedResult = actions(send, selectors);
+        lastSelectorResult = selectors;
+        lastSendReference = send;
+        return lastCachedResult;
+    };
+}
+/**
+ * @public
+ */
+export function buildView(__machine, __selectors, __actions, __slots, view) {
+    return React.memo(view);
+}
+/**
+ * @public
+ */
+export function buildXStateTreeMachine(machine, meta) {
+    const copiedMeta = { ...meta };
+    copiedMeta.xstateTreeMachine = true;
+    machine.config.meta = { ...machine.config.meta, ...copiedMeta };
+    machine.meta = { ...machine.meta, ...copiedMeta };
+    return machine;
+}

package/lib/index.js

@@ -0,0 +1,8 @@
+export * from "./builders";
+export * from "./slots";
+export { broadcast, buildRootComponent, onBroadcast } from "./xstateTree";
+export * from "./types";
+export { buildStorybookComponent, buildTestRootComponent, buildViewProps, genericSlotsTestingDummy, slotTestingDummyFactory, } from "./testingUtilities";
+export { Link, buildCreateRoute, matchRoute, } from "./routing";
+export { loggingMetaOptions } from "./useService";
+export { lazy } from "./lazy";

package/lib/lazy.js

@@ -0,0 +1,51 @@
+import { identity } from "lodash";
+import React from "react";
+import { createMachine, } from "xstate";
+import { buildActions, buildSelectors, buildView, buildXStateTreeMachine, } from "./builders";
+import { singleSlot } from "./slots";
+/**
+ * @public
+ * Wraps an xstate-tree returning Promise (generated by `import()` in an xstate-tree machine responsible for
+ * booting up the machine upon resolution
+ *
+ * @param factory - the factory function that returns the promise that resolves to the machine
+ * @param options - configure loading component and context to invoke machine with
+ * @returns an xstate-tree machine that wraps the promise, invoking the resulting machine when it resolves
+ */
+export function lazy(factory, { Loader = () => null, withContext = () => ({}), } = {}) {
+    const loadedMachineSlot = singleSlot("loadedMachine");
+    const slots = [loadedMachineSlot];
+    const machine = createMachine({
+        initial: "loading",
+        states: {
+            loading: {
+                invoke: {
+                    src: () => factory,
+                    onDone: "rendering",
+                },
+            },
+            rendering: {
+                invoke: {
+                    id: loadedMachineSlot.getId(),
+                    src: (_ctx, e) => {
+                        return e.data.withContext({ ...e.data.context, ...withContext() });
+                    },
+                },
+            },
+        },
+    });
+    const selectors = buildSelectors(machine, identity);
+    const actions = buildActions(machine, selectors, identity);
+    const view = buildView(machine, selectors, actions, slots, ({ slots, inState }) => {
+        if (inState("loading")) {
+            return React.createElement(Loader, null);
+        }
+        return React.createElement(slots.loadedMachine, null);
+    });
+    return buildXStateTreeMachine(machine, {
+        actions,
+        selectors,
+        slots,
+        view,
+    });
+}

package/lib/routing/Link.js

@@ -0,0 +1,27 @@
+import React from "react";
+import { useHref } from "./useHref";
+/**
+ * @public
+ * Renders an anchor tag pointing at the provided Route
+ *
+ * The query/params/meta props are conditionally required based on the
+ * route passed as the To parameter
+ */
+export function Link({ to, children, testId, ...rest }) {
+    // @ts-ignore, these fields _might_ exist, so typechecking doesn't believe they exist
+    // and everything that consumes params/query already checks for undefined
+    const { params, query, meta, ...props } = rest;
+    const href = useHref(to, params, query);
+    return (React.createElement("a", { ...props, href: href, "data-testid": testId, onClick: (e) => {
+            if (props.onClick?.(e) === false) {
+                return;
+            }
+            // Holding the Command key on Mac or the Control Key on Windows while clicking the link will open a new tab/window
+            // TODO: add global callback to prevent this
+            if (e.metaKey || e.ctrlKey) {
+                return;
+            }
+            e.preventDefault();
+            to.navigate({ params, query, meta });
+        } }, children));
+}

package/lib/routing/createRoute/createRoute.js

@@ -0,0 +1,185 @@
+import { isNil } from "lodash";
+import { match, compile } from "path-to-regexp";
+import { parse, stringify } from "query-string";
+import { joinRoutes } from "../joinRoutes";
+/**
+ * @public
+ */
+export function buildCreateRoute(history, basePath) {
+    function navigate({ history, url, meta, }) {
+        const method = meta?.replace ? history.replace : history.push;
+        method(url, {
+            meta,
+            previousUrl: window.location.pathname,
+        });
+    }
+    return {
+        /**
+         * Creates a dynamic Route using the supplied options
+         *
+         * The return value of dynamicRoute is a function that accepts the routes "dynamic" options
+         * The argument to dynamicRoute itself is the params/query/meta schemas defining the route
+         *
+         * The returned function accepts a singular option object with the following fields
+         *
+         * `event`, the string constant for the routes event
+         * `matches`, a function that is passed a url/query string and determines if the route matches
+         * if the route is matched it returns the extracted params/query objects
+         * `reverse`, a function that is passed params/query objects and turns them into a URL
+         *
+         * The params and query schemas are ZodSchemas, they both need to be an object (ie Z.object())
+         */
+        dynamicRoute: function createDynamicRoute(opts) {
+            return ({ event, matches, reverse, }) => {
+                return {
+                    paramsSchema: opts?.params,
+                    querySchema: opts?.query,
+                    event,
+                    history,
+                    basePath,
+                    parent: undefined,
+                    // @ts-ignore the usual
+                    getEvent({ params, query, meta } = {}) {
+                        return { type: event, params, query, meta };
+                    },
+                    // @ts-ignore not sure how to type this
+                    matches(url, search) {
+                        const query = parse(search);
+                        const match = matches(url, query);
+                        if (match === false) {
+                            return undefined;
+                        }
+                        if (opts?.params && "params" in match) {
+                            opts.params.parse(match.params);
+                        }
+                        if (opts?.query && "query" in match) {
+                            opts.query.parse(match.query);
+                        }
+                        return { type: event, originalUrl: `${url}${search}`, ...match };
+                    },
+                    // @ts-ignore not sure how to type this correctly
+                    // The types from external to this function are correct however
+                    reverse({ params, query } = {}) {
+                        return reverse({ params, query });
+                    },
+                    // @ts-ignore not sure how to type this correctly
+                    // The types from external to this function are correct however
+                    navigate({ params, query, meta } = {}) {
+                        // @ts-ignore same problem
+                        const url = this.reverse({ params, query });
+                        navigate({
+                            url: joinRoutes(this.basePath, url),
+                            meta,
+                            history: this.history,
+                        });
+                    },
+                };
+            };
+        },
+        /**
+         * Creates a static Route using the supplied options
+         *
+         * The return value of staticRoute is a function that accepts the routes options
+         * The only argument to staticRoute itself is an optional parent route
+         *
+         * The returned function accepts 3 arguments
+         *
+         * 1. URL of the route
+         * 2. The event type of the route
+         * 3. The routes options, params schema, query schema and meta type
+         *
+         * The params and query schemas are ZodSchemas, they both need to be an object (ie Z.object())
+         *
+         * When creating a route that has a parent route, the following happens
+         *
+         * 1. The parent routes url is prepended to the routes URL
+         * 2. The parents params schema is merged with the routes schema
+         * 3. The parents meta type is merged with the routes meta type
+         */
+        staticRoute: function createStaticRoute(baseRoute) {
+            return (url, event, opts) => {
+                if (baseRoute && isNil(baseRoute.url)) {
+                    throw new Error("Somehow constructing a route with a base route missing a URL, did you pass a dynamic route?");
+                }
+                const urlWithTrailingSlash = url.endsWith("/") ? url : `${url}/`;
+                const fullUrl = baseRoute
+                    ? joinRoutes(baseRoute.url, urlWithTrailingSlash)
+                    : urlWithTrailingSlash;
+                const matcher = match(fullUrl, {});
+                const reverser = compile(fullUrl);
+                const paramsSchema = baseRoute?.paramsSchema
+                    ? opts?.params
+                        ? baseRoute.paramsSchema.merge(opts.params)
+                        : baseRoute.paramsSchema
+                    : opts?.params
+                        ? opts.params
+                        : undefined;
+                return {
+                    paramsSchema,
+                    querySchema: opts?.query,
+                    event,
+                    history,
+                    basePath,
+                    url: fullUrl,
+                    parent: baseRoute,
+                    // @ts-ignore the usual
+                    getEvent({ params, query, meta } = {}) {
+                        return { type: event, params, query, meta };
+                    },
+                    // @ts-ignore not sure how to type this
+                    matches(url, search) {
+                        const fullUrl = url.endsWith("/") ? url : `${url}/`;
+                        const matches = matcher(fullUrl);
+                        if (matches === false) {
+                            return undefined;
+                        }
+                        const params = matches.params;
+                        if (params && paramsSchema) {
+                            paramsSchema.parse(params);
+                        }
+                        const query = parse(search);
+                        if (opts?.query) {
+                            opts.query.parse(query);
+                        }
+                        return {
+                            type: event,
+                            originalUrl: `${fullUrl}${search}`,
+                            params,
+                            query,
+                        };
+                    },
+                    // @ts-ignore not sure how to type this correctly
+                    // The types from external to this function are correct however
+                    reverse({ params, query } = {}) {
+                        const url = (() => {
+                            if (params) {
+                                // @ts-ignore same problem
+                                return reverser(params);
+                            }
+                            else {
+                                return reverser();
+                            }
+                        })();
+                        if (!isNil(query)) {
+                            return `${url}?${stringify(query)}`;
+                        }
+                        else {
+                            return url;
+                        }
+                    },
+                    // @ts-ignore not sure how to type this correctly
+                    // The types from external to this function are correct however
+                    navigate({ params, query, meta } = {}) {
+                        // @ts-ignore same problem
+                        const url = this.reverse({ params, query });
+                        navigate({
+                            url: joinRoutes(this.basePath, url),
+                            meta,
+                            history: this.history,
+                        });
+                    },
+                };
+            };
+        },
+    };
+}

package/lib/routing/createRoute/index.js

@@ -0,0 +1 @@
+export { buildCreateRoute, } from "./createRoute";

package/lib/routing/handleLocationChange/handleLocationChange.js

@@ -0,0 +1,47 @@
+import { broadcast } from "../../xstateTree";
+import { matchRoute } from "../matchRoute";
+/**
+ * @internal
+ */
+export function handleLocationChange(routes, basePath, path, search, setActiveRouteEvents, meta) {
+    console.debug("[xstate-tree] Matching routes", basePath, path, search, meta);
+    const match = matchRoute(routes, basePath, path, search);
+    console.debug("[xstate-tree] Match result", match);
+    if (match.type === "no-matches") {
+        const fourOhFour = {
+            type: "ROUTING_404",
+            url: path,
+        };
+        // @ts-ignore the event won't match GlobalEvents
+        broadcast(fourOhFour);
+    }
+    else if (match.type === "match-error") {
+        console.error("Error matching route for", location.pathname);
+    }
+    else {
+        const matchedEvent = match.event;
+        matchedEvent.meta = { ...(meta ?? {}) };
+        matchedEvent.meta.indexEvent = true;
+        const { params } = match.event;
+        const routingEvents = [];
+        let route = match.route;
+        while (route.parent) {
+            routingEvents.push(route.parent.getEvent({ params, query: {}, meta: { ...(meta ?? {}) } }));
+            route = route.parent;
+        }
+        setActiveRouteEvents([...routingEvents, match.event]);
+        // Bumps the processing for the state machines to the next event tick
+        // and out of the popstate handler
+        setTimeout(() => {
+            while (routingEvents.length > 0) {
+                const event = routingEvents.pop();
+                // copy the originalUrl to all parent events
+                event.originalUrl = match.event.originalUrl;
+                // @ts-ignore the event won't match GlobalEvents
+                broadcast(event);
+            }
+            // @ts-ignore the event won't match GlobalEvents
+            broadcast(matchedEvent);
+        }, 0);
+    }
+}

package/lib/routing/handleLocationChange/index.js

@@ -0,0 +1 @@
+export { handleLocationChange, } from "./handleLocationChange";

package/lib/routing/index.js

@@ -0,0 +1,6 @@
+export { buildCreateRoute, } from "./createRoute";
+export { joinRoutes } from "./joinRoutes";
+export { Link } from "./Link";
+export { matchRoute } from "./matchRoute";
+export { handleLocationChange, } from "./handleLocationChange";
+export { RoutingContext } from "./providers";

package/lib/routing/joinRoutes.js

@@ -0,0 +1,5 @@
+export function joinRoutes(base, route) {
+    const realBase = base.endsWith("/") ? base.slice(0, -1) : base;
+    const realRoute = route.startsWith("/") ? route : `/${route}`;
+    return realBase + realRoute;
+}

package/lib/routing/matchRoute/index.js

@@ -0,0 +1 @@
+export { matchRoute } from "./matchRoute";

package/lib/routing/matchRoute/matchRoute.js

@@ -0,0 +1,35 @@
+/**
+ * @public
+ */
+export function matchRoute(routes, basePath, path, search) {
+    const realBase = basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+    const realPath = (() => {
+        if (path.startsWith(realBase) && realBase.length > 0) {
+            return path.substring(realBase.length);
+        }
+        return path;
+    })();
+    const [matchingRoute, event] = routes
+        .map((route) => {
+        try {
+            const match = route.matches(realPath, search);
+            if (match) {
+                return [route, match];
+            }
+        }
+        catch (e) {
+            if (e instanceof Error) {
+                return [e, undefined];
+            }
+        }
+        return [undefined, undefined];
+    })
+        .find(([match]) => Boolean(match)) ?? [undefined, undefined];
+    if (matchingRoute === undefined) {
+        return { type: "no-matches" };
+    }
+    else if (matchingRoute instanceof Error) {
+        return { type: "match-error" };
+    }
+    return { type: "matched", route: matchingRoute, event: event };
+}

package/lib/routing/providers.js

@@ -0,0 +1,18 @@
+import { createContext, useContext } from "react";
+export const RoutingContext = createContext(undefined);
+function useRoutingContext() {
+    const context = useContext(RoutingContext);
+    if (context === undefined) {
+        throw new Error("useRoutingContext must be used within a RoutingContext provider");
+    }
+    return context;
+}
+export function useActiveRouteEvents() {
+    try {
+        const context = useRoutingContext();
+        return context.activeRouteEvents;
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/routing/routingEvent.js

@@ -0,0 +1 @@
+export {};

package/lib/routing/useHref.js

@@ -0,0 +1,14 @@
+import { joinRoutes } from "./joinRoutes";
+/**
+ * Returns a string created by joining the base path and routes URL
+ */
+export function useHref(to, params, query) {
+    try {
+        const routePath = to.reverse({ params, query });
+        return joinRoutes(to.basePath, routePath);
+    }
+    catch (e) {
+        console.error(e);
+    }
+    return "";
+}

package/lib/setupScript.js

@@ -0,0 +1 @@
+import "@testing-library/jest-dom/extend-expect";

package/lib/slots/index.js

@@ -0,0 +1 @@
+export * from "./slots";

package/lib/slots/slots.js

@@ -0,0 +1,25 @@
+var SlotType;
+(function (SlotType) {
+    SlotType[SlotType["SingleSlot"] = 0] = "SingleSlot";
+    SlotType[SlotType["MultiSlot"] = 1] = "MultiSlot";
+})(SlotType || (SlotType = {}));
+/**
+ * @public
+ */
+export function singleSlot(name) {
+    return {
+        type: SlotType.SingleSlot,
+        name,
+        getId: () => `${name.toLowerCase()}-slot`,
+    };
+}
+/**
+ * @public
+ */
+export function multiSlot(name) {
+    return {
+        type: SlotType.MultiSlot,
+        name,
+        getId: (id) => `${id}-${name.toLowerCase()}-slots`,
+    };
+}