@koordinates/xstate-tree 5.2.3 → 5.4.0

package/lib/routing/useIsRouteActive.js

@@ -2,22 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useIsRouteActive = void 0;
 const providers_1 = require("./providers");
-/**
- * @public
- * Accepts Routes and returns true if any route is currently active. False if not.
- *
- * If used outside of a RoutingContext, an error will be thrown.
- * @param routes - the routes to check
- * @returns true if any route is active, false if not
- * @throws if used outside of an xstate-tree root
- */
-function useIsRouteActive(...routes) {
+function useIsRouteActive(...args) {
     const activeRouteEvents = (0, providers_1.useActiveRouteEvents)();
     if (!activeRouteEvents) {
         throw new Error("useIsRouteActive must be used within a RoutingContext. Are you using it outside of an xstate-tree Root?");
     }
+    let routes;
+    let predicate;
+    if (args.length === 2 &&
+        Array.isArray(args[0]) &&
+        typeof args[1] === "function") {
+        routes = args[0];
+        predicate = args[1];
+    }
+    else {
+        routes = args;
+    }
     return activeRouteEvents.some((activeRouteEvent) => {
-        return routes.some((route) => activeRouteEvent.type === route.event);
+        const matches = routes.some((route) => activeRouteEvent.type === route.event);
+        if (!matches)
+            return false;
+        return predicate ? predicate(activeRouteEvent) : true;
     });
 }
 exports.useIsRouteActive = useIsRouteActive;

package/lib/xstate-tree.d.ts

@@ -218,6 +218,13 @@ declare type IsEmptyObject<Obj, ExcludeOptional extends boolean = false> = undef
 never
 ] ? true : false;
 
+/**
+ * @public
+ * Predicate invoked with the matching active route event to decide whether the
+ * route should be considered active.
+ */
+declare type IsRouteActivePredicate<TRoutes extends AnyRoute[]> = (event: RoutingEvent<TRoutes[number]>) => boolean;
+
 declare type IsUnknown<T> = unknown extends T ? true : false;
 
 /**
@@ -403,6 +410,7 @@ declare type RootOptions<TInput> = {
         basePath: string;
         getPathName?: () => string;
         getQueryString?: () => string;
+        shouldBlockActiveRouteUpdate?: (event: RoutingEvent<any>) => boolean;
     } | undefined;
     input: IsUnknown<TInput> extends true ? undefined : TInput;
 };
@@ -680,6 +688,20 @@ export declare function useActiveRouteEvents(): {
  */
 export declare function useIsRouteActive(...routes: AnyRoute[]): boolean;
 
+/**
+ * @public
+ * Accepts an array of Routes and a predicate. Returns true if any of the
+ * routes is currently active AND the predicate returns true when called with
+ * the matching active route event.
+ *
+ * If used outside of a RoutingContext, an error will be thrown.
+ * @param routes - the routes to check
+ * @param predicate - called with the matching active route event; return true to treat the route as active
+ * @returns true if any route is active and the predicate returns true, false otherwise
+ * @throws if used outside of an xstate-tree root
+ */
+export declare function useIsRouteActive<TRoutes extends AnyRoute[]>(routes: [...TRoutes], predicate: IsRouteActivePredicate<TRoutes>): boolean;
+
 /**
  * @public
  * Accepts a single Route and returns true if the route is currently active and marked as an index route.

package/lib/xstateTree.js

@@ -331,8 +331,12 @@ function buildRootComponent(options) {
                 const queryString = getQueryString();
                 const result = (0, routing_1.handleLocationChange)(routing.routes, routing.basePath, getPathName(), getQueryString(), initialMeta);
                 if (result) {
-                    setActiveRouteEvents(result.events);
-                    setActiveRoute({ ...result.matchedRoute });
+                    const matchedEvent = result.events[result.events.length - 1];
+                    const block = routing.shouldBlockActiveRouteUpdate?.(matchedEvent) === true;
+                    if (!block) {
+                        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
@@ -347,8 +351,12 @@ function buildRootComponent(options) {
                 const unsub = routing.history.listen((location) => {
                     const result = (0, routing_1.handleLocationChange)(routing.routes, routing.basePath, location.pathname, location.search, location.state?.meta);
                     if (result) {
-                        setActiveRouteEvents(result.events);
-                        setActiveRoute({ ...result.matchedRoute });
+                        const matchedEvent = result.events[result.events.length - 1];
+                        const block = routing.shouldBlockActiveRouteUpdate?.(matchedEvent) === true;
+                        if (!block) {
+                            setActiveRouteEvents(result.events);
+                            setActiveRoute({ ...result.matchedRoute });
+                        }
                     }
                 });
                 return () => {

package/package.json

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