@koordinates/xstate-tree 4.6.7 → 4.8.0

package/lib/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.lazy = exports.loggingMetaOptions = exports.TestRoutingContext = exports.useActiveRouteEvents = exports.useRouteArgsIfActive = exports.useIsRouteActive = exports.matchRoute = exports.buildCreateRoute = exports.Link = exports.slotTestingDummyFactory = exports.genericSlotsTestingDummy = exports.buildViewProps = exports.buildTestRootComponent = exports.onBroadcast = exports.buildRootComponent = exports.broadcast = void 0;
+exports.lazy = exports.loggingMetaOptions = exports.useOnRoute = exports.TestRoutingContext = exports.useActiveRouteEvents = exports.useRouteArgsIfActive = exports.useIsRouteActive = exports.matchRoute = exports.buildCreateRoute = exports.Link = exports.slotTestingDummyFactory = exports.genericSlotsTestingDummy = exports.buildViewProps = exports.buildTestRootComponent = exports.onBroadcast = exports.buildRootComponent = exports.broadcast = void 0;
 __exportStar(require("./builders"), exports);
 __exportStar(require("./slots"), exports);
 var xstateTree_1 = require("./xstateTree");
@@ -35,6 +35,7 @@ Object.defineProperty(exports, "useIsRouteActive", { enumerable: true, get: func
 Object.defineProperty(exports, "useRouteArgsIfActive", { enumerable: true, get: function () { return routing_1.useRouteArgsIfActive; } });
 Object.defineProperty(exports, "useActiveRouteEvents", { enumerable: true, get: function () { return routing_1.useActiveRouteEvents; } });
 Object.defineProperty(exports, "TestRoutingContext", { enumerable: true, get: function () { return routing_1.TestRoutingContext; } });
+Object.defineProperty(exports, "useOnRoute", { enumerable: true, get: function () { return routing_1.useOnRoute; } });
 var useService_1 = require("./useService");
 Object.defineProperty(exports, "loggingMetaOptions", { enumerable: true, get: function () { return useService_1.loggingMetaOptions; } });
 var lazy_1 = require("./lazy");

package/lib/routing/createRoute/createRoute.js

@@ -69,7 +69,7 @@ function buildCreateRoute(history, basePath) {
                 }
                 return parentRoutes;
             }
-            return ({ event, matcher, reverser, paramsSchema, querySchema, redirect, preload, }) => {
+            return ({ event, matcher, reverser, paramsSchema, querySchema, redirect, preload, canMatch, }) => {
                 let fullParamsSchema = paramsSchema;
                 let parentRoute = baseRoute;
                 while (fullParamsSchema && parentRoute) {
@@ -86,6 +86,7 @@ function buildCreateRoute(history, basePath) {
                     querySchema,
                     parent: baseRoute,
                     redirect,
+                    canMatch,
                     matcher: matcher,
                     reverser: reverser,
                     // @ts-ignore :cry:
@@ -95,7 +96,7 @@ function buildCreateRoute(history, basePath) {
                     },
                     // @ts-ignore :cry:
                     matches(suppliedUrl, search) {
-                        var _a, _b, _c;
+                        var _a, _b, _c, _d;
                         const fullUrl = suppliedUrl.endsWith("/")
                             ? suppliedUrl
                             : suppliedUrl + "/";
@@ -133,11 +134,21 @@ function buildCreateRoute(history, basePath) {
                         if (querySchema) {
                             querySchema.parse(matches.query);
                         }
+                        // Check canMatch predicate if provided
+                        if (canMatch) {
+                            const canMatchResult = canMatch({
+                                params: fullParams,
+                                query: (_c = matches.query) !== null && _c !== void 0 ? _c : {},
+                            });
+                            if (!canMatchResult) {
+                                return false;
+                            }
+                        }
                         return {
                             originalUrl: `${fullUrl}${search}`,
                             type: event,
                             params: fullParams,
-                            query: (_c = matches.query) !== null && _c !== void 0 ? _c : {},
+                            query: (_d = matches.query) !== null && _d !== void 0 ? _d : {},
                         };
                     },
                     // @ts-ignore :cry:

package/lib/routing/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useActiveRouteEvents = exports.useInTestRoutingContext = exports.useInRoutingContext = exports.TestRoutingContext = exports.RoutingContext = exports.useRouteArgsIfActive = exports.useIsRouteActive = exports.handleLocationChange = exports.matchRoute = exports.Link = exports.joinRoutes = exports.buildCreateRoute = void 0;
+exports.useActiveRouteEvents = exports.useInTestRoutingContext = exports.useInRoutingContext = exports.TestRoutingContext = exports.RoutingContext = exports.useOnRoute = exports.useRouteArgsIfActive = exports.useIsRouteActive = exports.handleLocationChange = exports.matchRoute = exports.Link = exports.joinRoutes = exports.buildCreateRoute = void 0;
 var createRoute_1 = require("./createRoute");
 Object.defineProperty(exports, "buildCreateRoute", { enumerable: true, get: function () { return createRoute_1.buildCreateRoute; } });
 var joinRoutes_1 = require("./joinRoutes");
@@ -15,6 +15,8 @@ var useIsRouteActive_1 = require("./useIsRouteActive");
 Object.defineProperty(exports, "useIsRouteActive", { enumerable: true, get: function () { return useIsRouteActive_1.useIsRouteActive; } });
 var useRouteArgsIfActive_1 = require("./useRouteArgsIfActive");
 Object.defineProperty(exports, "useRouteArgsIfActive", { enumerable: true, get: function () { return useRouteArgsIfActive_1.useRouteArgsIfActive; } });
+var useOnRoute_1 = require("./useOnRoute");
+Object.defineProperty(exports, "useOnRoute", { enumerable: true, get: function () { return useOnRoute_1.useOnRoute; } });
 var providers_1 = require("./providers");
 Object.defineProperty(exports, "RoutingContext", { enumerable: true, get: function () { return providers_1.RoutingContext; } });
 Object.defineProperty(exports, "TestRoutingContext", { enumerable: true, get: function () { return providers_1.TestRoutingContext; } });

package/lib/routing/useOnRoute.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useOnRoute = void 0;
+const providers_1 = require("./providers");
+/**
+ * @public
+ * Accepts a single Route and returns true if the route is currently active and marked as an index route.
+ * False if not.
+ *
+ * If used outside of a RoutingContext, an error will be thrown.
+ * @param route - the route to check
+ * @returns true if the route is active and an index route, false if not
+ * @throws if used outside of an xstate-tree root
+ */
+function useOnRoute(route) {
+    const activeRouteEvents = (0, providers_1.useActiveRouteEvents)();
+    if (!activeRouteEvents) {
+        throw new Error("useOnRoute must be used within a RoutingContext. Are you using it outside of an xstate-tree Root?");
+    }
+    return activeRouteEvents.some((activeRouteEvent) => {
+        var _a;
+        return activeRouteEvent.type === route.event &&
+            ((_a = activeRouteEvent.meta) === null || _a === void 0 ? void 0 : _a.indexEvent) === true;
+    });
+}
+exports.useOnRoute = useOnRoute;

package/lib/xstate-tree.d.ts

@@ -60,6 +60,7 @@ export declare type AnyRoute = {
     matcher: (url: string, query: ParsedQuery<string> | undefined) => any;
     reverser: any;
     redirect?: any;
+    canMatch?: any;
 };
 
 /**
@@ -129,6 +130,7 @@ export declare function buildCreateRoute(history: () => XstateTreeHistory, baseP
         meta?: TMeta | undefined;
         redirect?: RouteRedirect<MergeRouteTypes<RouteParams<TBaseRoute>, ResolveZodType<TParamsSchema>>, ResolveZodType<TQuerySchema>, MergeRouteTypes<RouteMeta<TBaseRoute>, TMeta> & SharedMeta> | undefined;
         preload?: RouteArgumentFunctions<void, MergeRouteTypes<RouteParams<TBaseRoute>, ResolveZodType<TParamsSchema>>, ResolveZodType<TQuerySchema>, MergeRouteTypes<RouteMeta<TBaseRoute>, TMeta>, RouteArguments<MergeRouteTypes<RouteParams<TBaseRoute>, ResolveZodType<TParamsSchema>>, ResolveZodType<TQuerySchema>, MergeRouteTypes<RouteMeta<TBaseRoute>, TMeta>>> | undefined;
+        canMatch?: RouteArgumentFunctions<boolean, MergeRouteTypes<RouteParams<TBaseRoute>, ResolveZodType<TParamsSchema>>, ResolveZodType<TQuerySchema>, MergeRouteTypes<RouteMeta<TBaseRoute>, TMeta> & SharedMeta, RouteArguments<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;
@@ -138,7 +140,7 @@ export declare function buildCreateRoute(history: () => XstateTreeHistory, baseP
         [x: string]: any;
     }, {
         [x: string]: any;
-    }> | undefined, TMeta_1 extends Record<string, unknown>>({ event, matcher, reverser, paramsSchema, querySchema, redirect, preload, }: {
+    }> | undefined, TMeta_1 extends Record<string, unknown>>({ event, matcher, reverser, paramsSchema, querySchema, redirect, preload, canMatch, }: {
         event: TEvent_1;
         paramsSchema?: TParamsSchema_1 | undefined;
         querySchema?: TQuerySchema_1 | undefined;
@@ -160,6 +162,7 @@ export declare function buildCreateRoute(history: () => XstateTreeHistory, baseP
          */
         reverser: RouteArgumentFunctions<string, MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1>, RouteArguments<MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1>>>;
         preload?: RouteArgumentFunctions<void, MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1>, RouteArguments<MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1>>> | undefined;
+        canMatch?: RouteArgumentFunctions<boolean, MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1> & SharedMeta, RouteArguments<MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1> & SharedMeta>> | undefined;
     }) => Route<MergeRouteTypes<RouteParams<TBaseRoute_1>, ResolveZodType<TParamsSchema_1>>, ResolveZodType<TQuerySchema_1>, TEvent_1, MergeRouteTypes<RouteMeta<TBaseRoute_1>, TMeta_1> & SharedMeta>;
 };
 
@@ -591,6 +594,12 @@ export declare type Route<TParams, TQuery, TEvent, TMeta> = {
     paramsSchema?: Z.ZodObject<any>;
     querySchema?: Z.ZodObject<any>;
     redirect?: RouteRedirect<TParams, TQuery, TMeta>;
+    /**
+     * Optional predicate to control whether this route can be matched.
+     * Called after URL matching but before the route is considered matched.
+     * Useful for access control or conditional routing.
+     */
+    canMatch?: RouteArgumentFunctions<boolean, TParams, TQuery, TMeta>;
 };
 
 /**
@@ -809,6 +818,18 @@ export declare function useActiveRouteEvents(): {
  */
 export declare function useIsRouteActive(...routes: AnyRoute[]): boolean;
 
+/**
+ * @public
+ * Accepts a single Route and returns true if the route is currently active and marked as an index route.
+ * False if not.
+ *
+ * If used outside of a RoutingContext, an error will be thrown.
+ * @param route - the route to check
+ * @returns true if the route is active and an index route, false if not
+ * @throws if used outside of an xstate-tree root
+ */
+export declare function useOnRoute(route: AnyRoute): boolean;
+
 /**
  * @public
  * Returns the arguments for the given route if the route is active.

package/package.json

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