@koordinates/xstate-tree 3.0.0-beta.1 → 3.0.0

package/README.md

@@ -15,7 +15,7 @@ While xstate-tree manages your application state, it does not have a mechanism f
 
 At Koordinates we use xstate-tree for all new UI development. Our desktop application, built on top of [Kart](https://kartproject.org/) our Geospatial version control system, is built entirely with xstate-tree using GraphQL for global state.
 
-A minimal example of a single machine tree ([CodeSandbox](https://codesandbox.io/s/xstate-tree-b0el6e-forked-4i6txh?file=/src/index.tsx)):
+A minimal example of a single machine tree (See [CodeSandbox](https://codesandbox.io/s/xstate-tree-b0el6e-forked-4i6txh?file=/src/index.tsx) for slightly expanded multi-machine example):
 
 ```tsx
 import React from "react";
@@ -36,6 +36,7 @@ type Events =
 type Context = { incremented: number };
 
 // If this tree had more than a single machine the slots to render child machines into would be defined here
+// see the codesandbox example for an expanded demonstration that uses slots
 const slots = [];
 
 // A standard xstate machine, nothing extra is needed for xstate-tree

package/lib/routing/createRoute/createRoute.js

@@ -66,7 +66,7 @@ export function buildCreateRoute(history, basePath) {
                 }
                 return parentRoutes;
             }
-            return ({ event, matcher, reverser, paramsSchema, querySchema, }) => {
+            return ({ event, matcher, reverser, paramsSchema, querySchema, redirect, }) => {
                 let fullParamsSchema = paramsSchema;
                 let parentRoute = baseRoute;
                 while (fullParamsSchema && parentRoute) {
@@ -82,6 +82,7 @@ export function buildCreateRoute(history, basePath) {
                     paramsSchema,
                     querySchema,
                     parent: baseRoute,
+                    redirect,
                     matcher: matcher,
                     reverser: reverser,
                     // @ts-ignore :cry:
@@ -142,7 +143,7 @@ export function buildCreateRoute(history, basePath) {
                         const parentRoutes = getParentArray();
                         const baseUrl = parentRoutes
                             .map((route) => route.reverser({ params }))
-                            .join("");
+                            .reduce((fullUrl, urlPartial) => joinRoutes(fullUrl, urlPartial), "");
                         return `${joinRoutes(baseUrl, reverser({ params, query }))}`;
                     },
                     // @ts-ignore :cry:

package/lib/routing/handleLocationChange/handleLocationChange.js

@@ -3,7 +3,7 @@ import { matchRoute } from "../matchRoute";
 /**
  * @internal
  */
-export function handleLocationChange(routes, basePath, path, search, setActiveRouteEvents, meta) {
+export function handleLocationChange(routes, basePath, path, search, 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);
@@ -14,9 +14,11 @@ export function handleLocationChange(routes, basePath, path, search, setActiveRo
         };
         // @ts-ignore the event won't match GlobalEvents
         broadcast(fourOhFour);
+        return;
     }
     else if (match.type === "match-error") {
         console.error("Error matching route for", location.pathname);
+        return;
     }
     else {
         const matchedEvent = match.event;
@@ -29,7 +31,7 @@ export function handleLocationChange(routes, basePath, path, search, setActiveRo
             routingEvents.push(route.parent.getEvent({ params, query: {}, meta: { ...(meta !== null && meta !== void 0 ? meta : {}) } }));
             route = route.parent;
         }
-        setActiveRouteEvents([...routingEvents, match.event]);
+        const clonedRoutingEvents = [...routingEvents];
         while (routingEvents.length > 0) {
             const event = routingEvents.pop();
             // copy the originalUrl to all parent events
@@ -39,5 +41,9 @@ export function handleLocationChange(routes, basePath, path, search, setActiveRo
         }
         // @ts-ignore the event won't match GlobalEvents
         broadcast(matchedEvent);
+        return {
+            events: [...clonedRoutingEvents, match.event],
+            matchedRoute: match.route,
+        };
     }
 }

package/lib/xstate-tree.d.ts

@@ -39,6 +39,7 @@ export declare type AnyRoute = {
     querySchema?: Z.ZodObject<any>;
     matcher: (url: string, query: ParsedQuery<string> | undefined) => any;
     reverser: any;
+    redirect?: any;
 };
 
 /**
@@ -105,6 +106,7 @@ export declare function buildCreateRoute(history: XstateTreeHistory, basePath: s
         paramsSchema?: TParamsSchema | undefined;
         querySchema?: TQuerySchema | undefined;
         meta?: TMeta | undefined;
+        redirect?: RouteRedirect<MergeRouteTypes<RouteParams<TBaseRoute>, ResolveZodType<TParamsSchema>>, ResolveZodType<TQuerySchema>, MergeRouteTypes<RouteMeta<TBaseRoute>, TMeta> & SharedMeta> | undefined;
     }) => Route<MergeRouteTypes<RouteParams<TBaseRoute>, ResolveZodType<TParamsSchema>>, ResolveZodType<TQuerySchema>, TEvent, MergeRouteTypes<RouteMeta<TBaseRoute>, TMeta> & SharedMeta>;
     route<TBaseRoute_1 extends AnyRoute>(baseRoute?: TBaseRoute_1 | undefined): <TEvent_1 extends string, TParamsSchema_1 extends Z.ZodObject<any, "strip", Z.ZodTypeAny, {
         [x: string]: any;
@@ -114,11 +116,12 @@ export declare function buildCreateRoute(history: XstateTreeHistory, basePath: s
         [x: string]: any;
     }, {
         [x: string]: any;
-    }> | undefined, TMeta_1 extends Record<string, unknown>>({ event, matcher, reverser, paramsSchema, querySchema, }: {
+    }> | undefined, TMeta_1 extends Record<string, unknown>>({ event, matcher, reverser, paramsSchema, querySchema, redirect, }: {
         event: TEvent_1;
         paramsSchema?: TParamsSchema_1 | undefined;
         querySchema?: TQuerySchema_1 | undefined;
         meta?: TMeta_1 | undefined;
+        redirect?: RouteRedirect<MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1> & SharedMeta> | undefined;
         /**
          * Determines if the route matches the given url and query
          *
@@ -500,6 +503,7 @@ export declare type Route<TParams, TQuery, TEvent, TMeta> = {
     parent?: AnyRoute;
     paramsSchema?: Z.ZodObject<any>;
     querySchema?: Z.ZodObject<any>;
+    redirect?: RouteRedirect<TParams, TQuery, TMeta>;
 };
 
 /**
@@ -545,6 +549,13 @@ export declare type RouteMeta<T> = T extends Route<any, any, any, infer TMeta> ?
  */
 export declare type RouteParams<T> = T extends Route<infer TParams, any, any, any> ? TParams : undefined;
 
+declare type RouteRedirect<TParams, TQuery, TMeta> = (args: MakeEmptyObjectPropertiesOptional<{
+    params: TParams;
+    query: TQuery;
+    meta?: TMeta;
+    abortSignal: AbortSignal;
+}>) => Promise<undefined | RouteArguments<Partial<TParams>, Partial<TQuery>, TMeta>>;
+
 /**
  * @public
  */

package/lib/xstateTree.js

@@ -6,7 +6,7 @@ import { handleLocationChange, RoutingContext, } from "./routing";
 import { useActiveRouteEvents } from "./routing/providers";
 import { useConstant } from "./useConstant";
 import { useService } from "./useService";
-import { isLikelyPageLoad } from "./utils";
+import { assertIsDefined, isLikelyPageLoad } from "./utils";
 export const emitter = new TinyEmitter();
 /**
  * @public
@@ -173,6 +173,7 @@ export function buildRootComponent(machine, routing) {
     }
     const RootComponent = function XstateTreeRootComponent() {
         const [_, __, interpreter] = useMachine(machine, { devTools: true });
+        const [activeRoute, setActiveRoute] = useState(undefined);
         const activeRouteEventsRef = useRef([]);
         const [forceRenderValue, forceRender] = useState(false);
         const setActiveRouteEvents = (events) => {
@@ -187,11 +188,72 @@ export function buildRootComponent(machine, routing) {
                 emitter.off("event", handler);
             };
         }, [interpreter]);
+        useEffect(() => {
+            if (activeRoute === undefined) {
+                return;
+            }
+            const controller = new AbortController();
+            const routes = [activeRoute];
+            let route = activeRoute;
+            while (route.parent) {
+                routes.unshift(route.parent);
+                route = route.parent;
+            }
+            const routeEventPairs = [];
+            const activeRoutesEvent = activeRouteEventsRef.current.find((e) => e.type === activeRoute.event);
+            assertIsDefined(activeRoutesEvent);
+            for (let i = 0; i < routes.length; i++) {
+                const route = routes[i];
+                const routeEvent = activeRouteEventsRef.current[i];
+                routeEventPairs.push([route, routeEvent]);
+            }
+            const routePairsWithRedirects = routeEventPairs.filter(([route]) => {
+                return route.redirect !== undefined;
+            });
+            const redirectPromises = routePairsWithRedirects.map(([route, event]) => {
+                assertIsDefined(route.redirect);
+                return route.redirect({
+                    signal: controller.signal,
+                    query: event.query,
+                    params: event.params,
+                    meta: event.meta,
+                });
+            });
+            void Promise.all(redirectPromises).then((redirects) => {
+                var _a, _b, _c;
+                const didAnyRedirect = redirects.some((x) => x !== undefined);
+                if (!didAnyRedirect || controller.signal.aborted) {
+                    return;
+                }
+                const routeArguments = redirects.reduce((args, redirect) => {
+                    if (redirect) {
+                        args.query = { ...args.query, ...redirect.query };
+                        args.params = { ...args.params, ...redirect.params };
+                        args.meta = { ...args.meta, ...redirect.meta };
+                    }
+                    return args;
+                }, {
+                    // since the redirect results are partials, need to merge them with the original event
+                    // params/query to ensure that all params/query are present
+                    query: { ...((_a = activeRoutesEvent.query) !== null && _a !== void 0 ? _a : {}) },
+                    params: { ...((_b = activeRoutesEvent.params) !== null && _b !== void 0 ? _b : {}) },
+                    meta: { ...((_c = activeRoutesEvent.meta) !== null && _c !== void 0 ? _c : {}) },
+                });
+                activeRoute.navigate(routeArguments);
+            });
+            return () => {
+                controller.abort();
+            };
+        }, [activeRoute]);
         useEffect(() => {
             if (routing) {
                 const { getPathName = () => window.location.pathname, getQueryString = () => window.location.search, } = routing;
                 const queryString = getQueryString();
-                handleLocationChange(routing.routes, routing.basePath, getPathName(), getQueryString(), setActiveRouteEvents, { onloadEvent: isLikelyPageLoad() });
+                const result = handleLocationChange(routing.routes, routing.basePath, getPathName(), getQueryString(), { onloadEvent: isLikelyPageLoad() });
+                if (result) {
+                    setActiveRouteEvents(result.events);
+                    setActiveRoute({ ...result.matchedRoute });
+                }
                 // Hack to ensure the initial location doesn't have undefined state
                 // It's not supposed to, but it does for some reason
                 // And the history library ignores popstate events with undefined state
@@ -202,7 +264,11 @@ export function buildRootComponent(machine, routing) {
             if (routing) {
                 const unsub = routing.history.listen((location) => {
                     var _a;
-                    handleLocationChange(routing.routes, routing.basePath, location.pathname, location.search, setActiveRouteEvents, (_a = location.state) === null || _a === void 0 ? void 0 : _a.meta);
+                    const result = handleLocationChange(routing.routes, routing.basePath, location.pathname, location.search, (_a = location.state) === null || _a === void 0 ? void 0 : _a.meta);
+                    if (result) {
+                        setActiveRouteEvents(result.events);
+                        setActiveRoute({ ...result.matchedRoute });
+                    }
                 });
                 return () => {
                     unsub();

package/package.json

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