@koordinates/xstate-tree 5.1.0-next.9 → 5.2.0

package/README.md

@@ -20,10 +20,9 @@ A minimal example of a single machine tree:
 ```tsx
 import React from "react";
 import { createRoot } from "react-dom/client";
-import { createMachine } from "xstate";
-import { assign } from "@xstate/immer";
+import { setup, assign, assertEvent } from "xstate";
 import {
-  createXStateTreeMachine
+  createXStateTreeMachine,
   buildRootComponent
 } from "@koordinates/xstate-tree";
 
@@ -32,40 +31,37 @@ type Events =
   | { type: "INCREMENT"; amount: number };
 type Context = { incremented: number };
 
-// A standard xstate machine, nothing extra is needed for xstate-tree
-const machine = createMachine<Context, Events>(
-  {
-    id: "root",
-    initial: "inactive",
-    context: {
-      incremented: 0
-    },
-    states: {
-      inactive: {
-        on: {
-          SWITCH_CLICKED: "active"
-        }
-      },
-      active: {
-        on: {
-          SWITCH_CLICKED: "inactive",
-          INCREMENT: { actions: "increment" }
-        }
+// A standard xstate v5 machine, nothing extra is needed for xstate-tree
+const machine = setup({
+  types: { context: {} as Context, events: {} as Events },
+  actions: {
+    increment: assign({
+      incremented: ({ context, event }) => {
+        assertEvent(event, "INCREMENT");
+        return context.incremented + event.amount;
       }
-    }
+    })
+  }
+}).createMachine({
+  id: "root",
+  initial: "inactive",
+  context: {
+    incremented: 0
   },
-  {
-    actions: {
-      increment: assign((context, event) => {
-        if (event.type !== "INCREMENT") {
-          return;
-        }
-        
-        context.incremented += event.amount;
-      })
+  states: {
+    inactive: {
+      on: {
+        SWITCH_CLICKED: "active"
+      }
+    },
+    active: {
+      on: {
+        SWITCH_CLICKED: "inactive",
+        INCREMENT: { actions: "increment" }
+      }
     }
   }
-);
+});
 
 const RootMachine = createXStateTreeMachine(machine, {
   // Selectors to transform the machines state into a representation useful for the view
@@ -95,10 +91,10 @@ const RootMachine = createXStateTreeMachine(machine, {
   // 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
   slots: [],
-  // A view to bring it all together
-  // the return value is a plain React view that can be rendered anywhere by passing in the needed props
+  // A React component view to bring it all together
+  // the return value is a plain React component that can be rendered anywhere by passing in the needed props
   // the view has no knowledge of the machine it's bound to
-  view({ actions, selectors }) {
+  View({ actions, selectors }) {
     return (
       <div>
         <button onClick={() => actions.switch()}>
@@ -118,6 +114,7 @@ const RootMachine = createXStateTreeMachine(machine, {
 });
 
 // Build the React host for the tree
+// You can pass input to the machine via the input prop
 const XstateTreeRoot = buildRootComponent(RootMachine);
 
 // Rendering it with React
@@ -133,7 +130,7 @@ Each machine that forms the tree representing your UI has an associated set of s
   - 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 for a single actor, 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, and the currently active slots
+  - View functions are React components provided with the output of the selector and action functions, and the currently active slots
 
 ## API
 
@@ -142,7 +139,7 @@ To assist in making xstate-tree easy to use with TypeScript there is the `create
 `createXStateTreeMachine` accepts the xstate machine as the first argument and takes an options argument with the following fields, it is important the fields are defined in this order or TypeScript will infer the wrong types:
 * `selectors`, receives an object with `ctx`, `inState`, `canHandleEvent`, and `meta` fields. `ctx` is the machines current context, `inState` is the xstate `state.matches` function to allow determining if the machine is in a given state, and `canHandleEvent` accepts an event object and returns whether the machine will do anything in response to that event in it's current state. `meta` is the xstate `state.meta` object with all the per state meta flattened into an object 
 * `actions`,  receives an object with `send` and `selectors` fields. `send` is the xstate `send` function bound to the machine, and `selectors` is the result of calling the selector function 
-* `view`, is a React component that receives `actions`, `selectors`, and `slots` as props. `actions` and `selectors` being the result of the action/selector functions and `slots` being an object with keys as the slot names and the values the slots React component 
+* `View`, is a React component (note the capital V) that receives `actions`, `selectors`, and `slots` as props. `actions` and `selectors` being the result of the action/selector functions and `slots` being an object with keys as the slot names and the values the slots React component 
 
 Full API docs coming soon, see [#20](https://github.com/koordinates/xstate-tree/issues/20)
 
@@ -189,11 +186,11 @@ These events can be added anywhere, either next to a component for component spe
 
 #### `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
+This utility accepts a React component and wraps it with an xstate-tree machine so you can easily invoke arbitrary React components in your xstate machines. This utility also accepts Root components returned from `buildRootComponent`.
 
-```
+```tsx
 function MyView() {
-  return <div>My View</div>;
+  return <div>{"My View"}</div>;
 }
 
 const MyViewMachine = viewToMachine(MyView);
@@ -203,9 +200,9 @@ const MyViewMachine = viewToMachine(MyView);
 
 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
+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. The utility now supports routes with dots in their event names (e.g., "user.profile.view").
 
-```
+```tsx
 const routeA = createRoute.simpleRoute()({
   url: "/a",
   event: "GO_TO_A",
@@ -227,25 +224,97 @@ There are some exported type helpers for use with xstate-tree
 
 * `SelectorsFrom<TMachine>`: Takes a machine and returns the type of the selectors object
 * `ActionsFrom<TMachine>`: Takes a machine and returns the type of the actions object
+* `AnyXstateTreeMachine`: Type for any xstate-tree machine, useful for function parameters
+
+
+### New Features in v5
+
+#### `buildRootComponent` Input Support
+
+You can now pass input to your root machine when using `buildRootComponent`. The function signature has changed to accept a single object parameter:
+
+```tsx
+// Without routing
+const XstateTreeRoot = buildRootComponent(RootMachine);
+
+// With routing
+const XstateTreeRoot = buildRootComponent({
+  machine: RootMachine,
+  routing: {
+    routes,
+    history,
+    basePath: "/"
+  }
+});
+
+// Pass input to the machine
+ReactRoot.render(<XstateTreeRoot input={{ initialData: data }} />);
+```
+
+#### `useOnRoute` Hook
 
+A new hook for executing side effects when specific routes are active. Unlike `useIsRouteActive`, this hook tells you when you're on the exact route (not just part of the active route chain):
+
+```tsx
+import { useOnRoute } from "@koordinates/xstate-tree";
+
+function MyComponent() {
+  useOnRoute(myRoute, ({ params, query }) => {
+    // Execute side effects when myRoute is the active end route
+    console.log("Route is active with params:", params);
+  });
+}
+```
+
+#### Children Support for Root Components
+
+Root components and slots now support passing children, allowing you to wrap your application with providers:
+
+```tsx
+<XstateTreeRoot>
+  <GlobalProvider>
+    {/* Your app renders here */}
+  </GlobalProvider>
+</XstateTreeRoot>
+```
+
+#### Improved `lazy` Loading
+
+The `lazy` utility now supports passing input to the lazily loaded machine:
+
+```tsx
+const LazyMachine = lazy(() => import("./MyMachine"), {
+  Loader: () => <div>Loading...</div>,
+  input: { initialData: "data" }
+});
+```
+
+#### Testing Improvements
+
+- `TestRoutingContext` now supports nesting routing roots for better testing scenarios
+- Removed deprecated testing utilities: `buildTestRootComponent`, `buildViewProps`, `slotTestingDummyFactory`
+
+#### Logging Improvements
+
+- Internal XState events are now filtered from logs for cleaner output
+- `_subscription` property is stripped from logged data
+- Route objects are no longer logged after matching to reduce console noise
+- `loggingMetaOptions` export available for configuring logging behavior
+
+### Breaking Changes from v4
+
+- **Removed v1 style builders**: `buildView`, `buildSelectors`, `buildActions` have been removed. Use `createXStateTreeMachine` instead.
+- **Child actor behavior**: Children in final states are no longer automatically removed from views. You must manually call `stopChild` to remove them.
+- **Testing utilities removed**: `buildTestRootComponent`, `buildViewProps`, and `slotTestingDummyFactory` have been removed.
 
 ### [Storybook](https://storybook.js.org)
 
-It is relatively simple 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
+It is relatively simple to display xstate-tree views directly in Storybook. Since the views are plain React components that accept selectors/actions/slots 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
+There is a utility in xstate-tree to make this easier:
 
 #### `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

@@ -31,9 +31,19 @@ function createXStateTreeMachine(machine, options) {
         View: options.View,
         slots: (options.slots ?? []),
     };
-    return machineWithMeta;
+    return fixProvideLosingXstateTreeMeta(machineWithMeta);
 }
 exports.createXStateTreeMachine = createXStateTreeMachine;
+function fixProvideLosingXstateTreeMeta(machine) {
+    const originalProvide = machine.provide.bind(machine);
+    machine.provide = (impl) => {
+        const result = originalProvide(impl);
+        result._xstateTree = machine._xstateTree;
+        fixProvideLosingXstateTreeMeta(result);
+        return result;
+    };
+    return machine;
+}
 /**
  * @public
  *
@@ -64,11 +74,19 @@ exports.viewToMachine = viewToMachine;
  * @returns an xstate-tree machine that will render the right machines based on the routing events
  */
 function buildRoutingMachine(_routes, mappings) {
+    /**
+     * States in xstate can't contain dots, since the states are named after the routing events
+     * if the routing event contains a dot that will make a state with a dot in it
+     * this function sanitizes the event name to remove dots and is used for the state names and targets
+     */
+    function sanitizeEventName(event) {
+        return event.replace(/\.([a-zA-Z])/g, (_, letter) => letter.toUpperCase());
+    }
     const contentSlot = (0, slots_1.singleSlot)("Content");
     const mappingsToStates = Object.entries(mappings).reduce((acc, [event, _machine]) => {
         return {
             ...acc,
-            [event]: {
+            [sanitizeEventName(event)]: {
                 invoke: {
                     src: event,
                     id: contentSlot.getId(),
@@ -79,7 +97,7 @@ function buildRoutingMachine(_routes, mappings) {
     const mappingsToEvents = Object.keys(mappings).reduce((acc, event) => ({
         ...acc,
         [event]: {
-            target: `.${event}`,
+            target: `.${sanitizeEventName(event)}`,
         },
     }), {});
     const machine = (0, xstate_1.setup)({

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.genericSlotsTestingDummy = 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.genericSlotsTestingDummy = exports.onBroadcast = exports.buildRootComponent = exports.broadcast = void 0;
 __exportStar(require("./builders"), exports);
 __exportStar(require("./slots"), exports);
 var xstateTree_1 = require("./xstateTree");
@@ -32,6 +32,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:
@@ -132,6 +133,16 @@ function buildCreateRoute(history, basePath) {
                         if (querySchema) {
                             querySchema.parse(matches.query);
                         }
+                        // Check canMatch predicate if provided
+                        if (canMatch) {
+                            const canMatchResult = canMatch({
+                                params: fullParams,
+                                query: matches.query ?? {},
+                            });
+                            if (!canMatchResult) {
+                                return false;
+                            }
+                        }
                         return {
                             originalUrl: `${fullUrl}${search}`,
                             type: event,

package/lib/routing/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useActiveRouteEvents = 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,8 +15,11 @@ 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; } });
 Object.defineProperty(exports, "useInRoutingContext", { enumerable: true, get: function () { return providers_1.useInRoutingContext; } });
+Object.defineProperty(exports, "useInTestRoutingContext", { enumerable: true, get: function () { return providers_1.useInTestRoutingContext; } });
 Object.defineProperty(exports, "useActiveRouteEvents", { enumerable: true, get: function () { return providers_1.useActiveRouteEvents; } });

package/lib/routing/providers.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TestRoutingContext = exports.useActiveRouteEvents = exports.useInRoutingContext = exports.RoutingContext = void 0;
+exports.TestRoutingContext = exports.useActiveRouteEvents = exports.useInTestRoutingContext = exports.useInRoutingContext = exports.RoutingContext = void 0;
 const react_1 = __importDefault(require("react"));
 const react_2 = require("react");
 exports.RoutingContext = (0, react_2.createContext)(undefined);
@@ -22,6 +22,14 @@ function useInRoutingContext() {
     return context !== undefined;
 }
 exports.useInRoutingContext = useInRoutingContext;
+/**
+ * @private
+ */
+function useInTestRoutingContext() {
+    const context = (0, react_2.useContext)(exports.RoutingContext);
+    return context?.isTestRoutingContext ?? false;
+}
+exports.useInTestRoutingContext = useInTestRoutingContext;
 /**
  * @public
  *
@@ -46,6 +54,9 @@ exports.useActiveRouteEvents = useActiveRouteEvents;
  * @param activeRouteEvents - The active route events to use in the context
  */
 function TestRoutingContext({ activeRouteEvents, children, }) {
-    return (react_1.default.createElement(exports.RoutingContext.Provider, { value: { activeRouteEvents: { current: activeRouteEvents } } }, children));
+    return (react_1.default.createElement(exports.RoutingContext.Provider, { value: {
+            activeRouteEvents: { current: activeRouteEvents },
+            isTestRoutingContext: true,
+        } }, children));
 }
 exports.TestRoutingContext = TestRoutingContext;

package/lib/routing/useOnRoute.js

@@ -0,0 +1,23 @@
+"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) => activeRouteEvent.type === route.event &&
+        activeRouteEvent.meta?.indexEvent === true);
+}
+exports.useOnRoute = useOnRoute;

package/lib/utils.js

@@ -121,9 +121,12 @@ function mergeMeta(meta) {
     }, {});
 }
 exports.mergeMeta = mergeMeta;
-function getCircularReplacer() {
+function getCircularReplacer(stripKeys) {
     const seen = new WeakSet();
     return (key, value) => {
+        if (stripKeys.includes(key)) {
+            return;
+        }
         if (typeof value === "object" && value !== null) {
             if (seen.has(value)) {
                 // Circular reference found, discard key
@@ -135,7 +138,7 @@ function getCircularReplacer() {
         return value;
     };
 }
-function toJSON(value) {
-    return JSON.parse(JSON.stringify(value, getCircularReplacer()));
+function toJSON(value, stripKeys = []) {
+    return JSON.parse(JSON.stringify(value, getCircularReplacer(stripKeys)));
 }
 exports.toJSON = toJSON;

package/lib/xstate-tree.d.ts

@@ -45,12 +45,13 @@ export declare type AnyRoute = {
     matcher: (url: string, query: ParsedQuery<string> | undefined) => any;
     reverser: any;
     redirect?: any;
+    canMatch?: any;
 };
 
 /**
  * @public
  */
-export declare type AnyXstateTreeMachine = XstateTreeMachine<AnyStateMachine>;
+export declare type AnyXstateTreeMachine = XstateTreeMachine<AnyStateMachine, any, any, any[]>;
 
 /**
  * @public
@@ -91,6 +92,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;
@@ -100,7 +102,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;
@@ -122,6 +124,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>;
 };
 
@@ -136,7 +139,9 @@ export declare function buildCreateRoute(history: () => XstateTreeHistory, baseP
 export declare function buildRootComponent<TMachine extends AnyXstateTreeMachine>(options: {
     machine: TMachine;
 } & MarkOptionalLikePropertiesOptional<RootOptions<InputFrom<TMachine>>>): {
-    (): JSX.Element;
+    ({ children, }: {
+        children?: React_2.ReactNode;
+    }): JSX.Element;
     rootMachine: TMachine;
 };
 
@@ -329,7 +334,7 @@ declare type OmitOptional<T> = {
  */
 export declare function onBroadcast(handler: (event: GlobalEvents) => void): () => void;
 
-declare type Options<TStateMachine extends AnyStateMachine> = {
+declare type Options<TStateMachine extends AnyXstateTreeMachine> = {
     /**
      * Displayed while the promise is resolving, defaults to returning null
      */
@@ -370,6 +375,14 @@ export declare type Query<T> = T extends {
     query: infer TQuery;
 } ? TQuery : undefined;
 
+/**
+ * Repairs the return type of the `provide` function on XstateTreeMachines to correctly return
+ * an XstateTreeMachine type instead of an xstate StateMachine
+ */
+declare type RepairProvideReturnType<T extends AnyStateMachine, TSelectorsOutput, TActionsOutput, TSlots extends readonly Slot[]> = {
+    [K in keyof T]: K extends "provide" ? (...args: Parameters<T[K]>) => XstateTreeMachine<T, TSelectorsOutput, TActionsOutput, TSlots> : T[K];
+};
+
 declare type ResolveZodType<T extends Z.ZodType<any> | undefined> = undefined extends T ? undefined : Z.TypeOf<Exclude<T, undefined>>;
 
 declare type Return<TRoutes extends Route<any, any, any, any>[]> = {
@@ -464,6 +477,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>;
 };
 
 /**
@@ -661,6 +680,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.
@@ -691,6 +722,7 @@ export declare type View<TActionsOutput, TSelectorsOutput, TSlots extends readon
     slots: Record<GetSlotNames<TSlots>, React_2.ComponentType>;
     actions: TActionsOutput;
     selectors: TSelectorsOutput;
+    children?: React_2.ReactNode;
 }>;
 
 /**
@@ -701,7 +733,7 @@ export declare type View<TActionsOutput, TSelectorsOutput, TSlots extends readon
  * @param view - the React view you want to invoke in an xstate machine
  * @returns The view wrapped into an xstate-tree machine, ready to be invoked by other xstate machines or used with `buildRootComponent`
  */
-export declare function viewToMachine(view: () => JSX.Element): AnyXstateTreeMachine;
+export declare function viewToMachine(view: (args?: any) => JSX.Element | null): AnyXstateTreeMachine;
 
 declare type WithParentPath<TCurrent extends string, TParentPath extends string> = `${TParentPath extends "" ? "" : `${TParentPath}.`}${TCurrent}`;
 
@@ -716,7 +748,7 @@ export declare type XstateTreeHistory<T = unknown> = History_2<{
 /**
  * @public
  */
-export declare type XstateTreeMachine<TMachine extends AnyStateMachine, TSelectorsOutput = ContextFrom<TMachine>, TActionsOutput = Record<never, string>, TSlots extends readonly Slot[] = Slot[]> = TMachine & XstateTreeMachineInjection<TMachine, TSelectorsOutput, TActionsOutput, TSlots>;
+export declare type XstateTreeMachine<TMachine extends AnyStateMachine, TSelectorsOutput = ContextFrom<TMachine>, TActionsOutput = Record<never, string>, TSlots extends readonly Slot[] = Slot[]> = RepairProvideReturnType<TMachine, TSelectorsOutput, TActionsOutput, TSlots> & XstateTreeMachineInjection<TMachine, TSelectorsOutput, TActionsOutput, TSlots>;
 
 /**
  * @internal

package/lib/xstateTree.js

@@ -32,7 +32,6 @@ const fast_memoize_1 = __importDefault(require("fast-memoize"));
 const react_2 = __importStar(require("react"));
 const tiny_emitter_1 = require("tiny-emitter");
 const routing_1 = require("./routing");
-const providers_1 = require("./routing/providers");
 const useConstant_1 = require("./useConstant");
 const useService_1 = require("./useService");
 const utils_1 = require("./utils");
@@ -69,8 +68,8 @@ interpreter) {
     return interpreter.sessionId;
 }
 const getViewForInterpreter = (0, fast_memoize_1.default)((interpreter) => {
-    return react_2.default.memo(function InterpreterView() {
-        const activeRouteEvents = (0, providers_1.useActiveRouteEvents)();
+    return react_2.default.memo(function InterpreterView({ children, }) {
+        const activeRouteEvents = (0, routing_1.useActiveRouteEvents)();
         (0, react_2.useEffect)(() => {
             if (activeRouteEvents) {
                 activeRouteEvents.forEach((event) => {
@@ -80,7 +79,7 @@ const getViewForInterpreter = (0, fast_memoize_1.default)((interpreter) => {
                 });
             }
         }, []);
-        return react_2.default.createElement(XstateTreeView, { actor: interpreter });
+        return react_2.default.createElement(XstateTreeView, { actor: interpreter }, children);
     });
 }, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -105,7 +104,7 @@ function useSlots(interpreter, slots) {
         return slots.reduce((views, slot) => {
             return {
                 ...views,
-                [slot]: () => {
+                [slot]: (({ children: reactChildren }) => {
                     // eslint-disable-next-line react-hooks/rules-of-hooks
                     const [__, children] = (0, useService_1.useService)(interpreter);
                     if (slot.toString().endsWith("Multi")) {
@@ -116,26 +115,25 @@ function useSlots(interpreter, slots) {
                         const interpreterForSlot = children[`${slot.toLowerCase()}-slot`];
                         if (interpreterForSlot) {
                             const View = getViewForInterpreter(interpreterForSlot);
-                            return react_2.default.createElement(View, null);
+                            return react_2.default.createElement(View, null, reactChildren);
                         }
                         else {
                             // Waiting for the interpreter for this slot to be invoked
                             return null;
                         }
                     }
-                },
+                }),
             };
         }, {});
     });
 }
 function XstateTreeMultiSlotView({ childInterpreters, }) {
-    console.log("XstateTreeMultiSlotView", childInterpreters);
     return (react_2.default.createElement(react_2.default.Fragment, null, childInterpreters.map((i) => (react_2.default.createElement(XstateTreeView, { key: i.id, actor: i })))));
 }
 /**
  * @internal
  */
-function XstateTreeView({ actor }) {
+function XstateTreeView({ actor, children }) {
     const [current] = (0, useService_1.useService)(actor);
     const currentRef = (0, react_2.useRef)(current);
     currentRef.current = current;
@@ -175,7 +173,7 @@ function XstateTreeView({ actor }) {
         inState: inState,
         meta: (0, utils_1.mergeMeta)(current.getMeta()),
     });
-    return (react_2.default.createElement(View, { selectors: selectorsRef.current, actions: actions, slots: slots }));
+    return (react_2.default.createElement(View, { selectors: selectorsRef.current, actions: actions, slots: slots }, children));
 }
 exports.XstateTreeView = XstateTreeView;
 /**
@@ -211,7 +209,7 @@ function buildRootComponent(options) {
     if (!machine._xstateTree.View) {
         throw new Error("Root machine has no associated view");
     }
-    const RootComponent = function XstateTreeRootComponent() {
+    const RootComponent = function XstateTreeRootComponent({ children, }) {
         const lastSnapshotsRef = (0, react_2.useRef)({});
         const [_, __, interpreter] = (0, react_1.useActor)(machine, {
             input,
@@ -221,15 +219,20 @@ function buildRootComponent(options) {
                         console.log(`[xstate-tree] actor spawned: ${event.actorRef.id}`);
                         break;
                     case "@xstate.event":
+                        // Ignore internal events
+                        if (event.event.type.includes("xstate.")) {
+                            return;
+                        }
                         console.log(`[xstate-tree] event: ${event.sourceRef ? event.sourceRef.id : "UNKNOWN"} -> ${event.event.type} -> ${event.actorRef.id}`, event.event);
                         break;
                     case "@xstate.snapshot":
                         const lastSnapshot = lastSnapshotsRef.current[event.actorRef.sessionId];
+                        const strippedKeys = ["_subscription"];
                         if (!lastSnapshot) {
-                            console.log(`[xstate-tree] initial snapshot: ${event.actorRef.id}`, (0, utils_1.toJSON)(event.snapshot));
+                            console.log(`[xstate-tree] initial snapshot: ${event.actorRef.id}`, (0, utils_1.toJSON)(event.snapshot, strippedKeys));
                         }
                         else {
-                            console.log(`[xstate-tree] snapshot: ${event.actorRef.id} transitioning to`, (0, utils_1.toJSON)(event.snapshot), "from", (0, utils_1.toJSON)(lastSnapshot));
+                            console.log(`[xstate-tree] snapshot: ${event.actorRef.id} transitioning to`, (0, utils_1.toJSON)(event.snapshot, strippedKeys), "from", (0, utils_1.toJSON)(lastSnapshot, strippedKeys));
                         }
                         lastSnapshotsRef.current[event.actorRef.sessionId] = event.snapshot;
                         break;
@@ -243,7 +246,10 @@ function buildRootComponent(options) {
             activeRouteEventsRef.current = events;
         };
         const insideRoutingContext = (0, routing_1.useInRoutingContext)();
-        if (insideRoutingContext && typeof routing !== "undefined") {
+        const inTestRoutingContext = (0, routing_1.useInTestRoutingContext)();
+        if (!inTestRoutingContext &&
+            insideRoutingContext &&
+            typeof routing !== "undefined") {
             const m = "Routing root rendered inside routing context, this implies a bug";
             if (process.env.NODE_ENV !== "production") {
                 throw new Error(m);
@@ -363,10 +369,10 @@ function buildRootComponent(options) {
         }, [activeRoute]);
         if (routingProviderValue) {
             return (react_2.default.createElement(routing_1.RoutingContext.Provider, { value: routingProviderValue },
-                react_2.default.createElement(XstateTreeView, { actor: interpreter })));
+                react_2.default.createElement(XstateTreeView, { actor: interpreter }, children)));
         }
         else {
-            return react_2.default.createElement(XstateTreeView, { actor: interpreter });
+            return react_2.default.createElement(XstateTreeView, { actor: interpreter }, children);
         }
     };
     RootComponent.rootMachine = machine;

package/package.json

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