@koordinates/xstate-tree 5.1.0-next.1 → 5.1.0-next.11

package/README.md

@@ -185,6 +185,42 @@ These events can be added anywhere, either next to a component for component spe
 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 `createXStateTreeMachine`. If they are in the file containing those functions the index.d.ts file will not end up importing them.
 
 
+### Utilities
+
+#### `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
+
+```
+function MyView() {
+  return <div>My View</div>;
+}
+
+const MyViewMachine = viewToMachine(MyView);
+```
+
+#### `buildRoutingMachine`
+
+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
+
+```
+const routeA = createRoute.simpleRoute()({
+  url: "/a",
+  event: "GO_TO_A",
+});
+const routeB = createRoute.simpleRoute()({
+  url: "/b",
+  event: "GO_TO_B",
+});
+
+const RoutingMachine = buildRoutingMachine([routeA, routeB], {
+  GO_TO_A: MachineA,
+  GO_TO_B: MachineB,
+});
+```
+
 ### Type helpers
 
 There are some exported type helpers for use with xstate-tree

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
  *

package/lib/routing/handleLocationChange/handleLocationChange.js

@@ -9,7 +9,6 @@ const matchRoute_1 = require("../matchRoute");
 function handleLocationChange(routes, basePath, path, search, meta) {
     console.debug("[xstate-tree] Matching routes", basePath, path, search, meta);
     const match = (0, matchRoute_1.matchRoute)(routes, basePath, path, search);
-    console.debug("[xstate-tree] Match result", match);
     if (match.type === "no-matches") {
         const fourOhFour = {
             type: "ROUTING_404",
@@ -20,10 +19,11 @@ function handleLocationChange(routes, basePath, path, search, meta) {
         return;
     }
     else if (match.type === "match-error") {
-        console.error("Error matching route for", location.pathname);
+        console.error("Error matching route for", location.pathname, match.error);
         return;
     }
     else {
+        console.log("[xstate-tree] matched route", match.event);
         const matchedEvent = match.event;
         matchedEvent.meta = { ...(meta ?? {}) };
         matchedEvent.meta.indexEvent = true;

package/lib/routing/matchRoute/matchRoute.js

@@ -32,7 +32,7 @@ function matchRoute(routes, basePath, path, search) {
         return { type: "no-matches" };
     }
     else if (matchingRoute instanceof Error) {
-        return { type: "match-error" };
+        return { type: "match-error", error: matchingRoute };
     }
     return { type: "matched", route: matchingRoute, event: event };
 }

package/lib/utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toJSON = exports.mergeMeta = exports.isNil = exports.isEqual = exports.difference = exports.isLikelyPageLoad = exports.assert = exports.assertIsDefined = exports.delay = void 0;
+exports.toJSON = exports.mergeMeta = exports.isNil = exports.isEqual = exports.difference = exports.assert = exports.assertIsDefined = exports.delay = void 0;
 function delay(ms = 0) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -26,15 +26,6 @@ function assert(value, msg) {
     }
 }
 exports.assert = assert;
-function isLikelyPageLoad() {
-    // without performance API, we can't tell if this is a page load
-    if (typeof performance === "undefined") {
-        return false;
-    }
-    // if it's been < 5 seconds since the page was loaded, it's probably a page load
-    return performance.now() < 5000;
-}
-exports.isLikelyPageLoad = isLikelyPageLoad;
 function difference(a, b) {
     const result = {};
     for (const key in b) {

package/lib/xstate-tree.d.ts

@@ -50,7 +50,7 @@ export declare type AnyRoute = {
 /**
  * @public
  */
-export declare type AnyXstateTreeMachine = XstateTreeMachine<AnyStateMachine>;
+export declare type AnyXstateTreeMachine = XstateTreeMachine<AnyStateMachine, any, any, any[]>;
 
 /**
  * @public
@@ -133,15 +133,11 @@ export declare function buildCreateRoute(history: () => XstateTreeHistory, baseP
  * @param machine - The root machine of the tree
  * @param routing - The routing configuration for the tree
  */
-export declare function buildRootComponent(machine: AnyXstateTreeMachine, routing?: {
-    routes: AnyRoute[];
-    history: XstateTreeHistory<any>;
-    basePath: string;
-    getPathName?: () => string;
-    getQueryString?: () => string;
-}): {
+export declare function buildRootComponent<TMachine extends AnyXstateTreeMachine>(options: {
+    machine: TMachine;
+} & MarkOptionalLikePropertiesOptional<RootOptions<InputFrom<TMachine>>>): {
     (): JSX.Element;
-    rootMachine: AnyXstateTreeMachine;
+    rootMachine: TMachine;
 };
 
 /**
@@ -177,7 +173,7 @@ export declare type CanHandleEvent<TMachine extends AnyStateMachine> = (e: Event
  * @param machine - The xstate machine to create the xstate-tree machine from
  * @param options - the xstate-tree options
  */
-export declare function createXStateTreeMachine<TMachine extends AnyStateMachine, TSelectorsOutput = ContextFrom<TMachine>, TActionsOutput = Record<never, string>, TSlots extends readonly Slot[] = []>(machine: TMachine, options: V2BuilderMeta<TMachine, TSelectorsOutput, TActionsOutput, TSlots>): XstateTreeMachine<TMachine>;
+export declare function createXStateTreeMachine<TMachine extends AnyStateMachine, TSelectorsOutput = ContextFrom<TMachine>, TActionsOutput = Record<never, string>, TSlots extends readonly Slot[] = []>(machine: TMachine, options: V2BuilderMeta<TMachine, TSelectorsOutput, TActionsOutput, TSlots>): XstateTreeMachine<TMachine, TSelectorsOutput, TActionsOutput, TSlots>;
 
 declare type EmptyKeys<T> = keyof {
     [K in keyof T as IsEmptyObject<T[K], true> extends true ? K : never]: T[K];
@@ -217,6 +213,8 @@ declare type IsEmptyObject<Obj, ExcludeOptional extends boolean = false> = undef
 never
 ] ? true : false;
 
+declare type IsUnknown<T> = unknown extends T ? true : false;
+
 /**
  * @public
  *
@@ -278,7 +276,10 @@ export declare function loggingMetaOptions<TEvents extends EventObject, TContext
     };
 };
 
-declare type MakeEmptyObjectPropertiesOptional<T> = Omit<T, EmptyKeys<T>> & Partial<Pick<T, EmptyKeys<T>>>;
+/**
+ * Marks any required property that can accept undefined as optional
+ */
+declare type MarkOptionalLikePropertiesOptional<T> = Omit<T, EmptyKeys<T>> & Partial<Pick<T, EmptyKeys<T>>>;
 
 /**
  * @internal
@@ -328,7 +329,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
      */
@@ -369,6 +370,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>[]> = {
@@ -379,6 +388,18 @@ declare type Return<TRoutes extends Route<any, any, any, any>[]> = {
     type: "no-matches";
 } | {
     type: "match-error";
+    error: unknown;
+};
+
+declare type RootOptions<TInput> = {
+    routing: {
+        routes: AnyRoute[];
+        history: XstateTreeHistory<any>;
+        basePath: string;
+        getPathName?: () => string;
+        getQueryString?: () => string;
+    } | undefined;
+    input: IsUnknown<TInput> extends true ? undefined : TInput;
 };
 
 /**
@@ -456,7 +477,7 @@ export declare type Route<TParams, TQuery, TEvent, TMeta> = {
 /**
  * @public
  */
-export declare type RouteArgumentFunctions<TReturn, TParams, TQuery, TMeta, TArgs = RouteArguments<TParams, TQuery, TMeta>> = IsEmptyObject<TArgs> extends true ? () => TReturn : keyof TArgs extends "meta" ? (args?: TArgs) => TReturn : EmptyRouteArguments<TParams, TQuery> extends true ? (args?: Partial<TArgs>) => TReturn : (args: MakeEmptyObjectPropertiesOptional<TArgs>) => TReturn;
+export declare type RouteArgumentFunctions<TReturn, TParams, TQuery, TMeta, TArgs = RouteArguments<TParams, TQuery, TMeta>> = IsEmptyObject<TArgs> extends true ? () => TReturn : keyof TArgs extends "meta" ? (args?: TArgs) => TReturn : EmptyRouteArguments<TParams, TQuery> extends true ? (args?: Partial<TArgs>) => TReturn : (args: MarkOptionalLikePropertiesOptional<TArgs>) => TReturn;
 
 /**
  * @public
@@ -496,7 +517,14 @@ 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<{
+/**
+ * @public
+ *
+ * Extract query type from route
+ */
+export declare type RouteQuery<T> = T extends Route<any, infer TQuery, any, any> ? TQuery : undefined;
+
+declare type RouteRedirect<TParams, TQuery, TMeta> = (args: MarkOptionalLikePropertiesOptional<{
     params: TParams;
     query: TQuery;
     meta?: TMeta;
@@ -696,13 +724,13 @@ export declare type XstateTreeHistory<T = unknown> = History_2<{
 /**
  * @public
  */
-export declare type XstateTreeMachine<TMachine extends AnyStateMachine> = TMachine & XstateTreeMachineInjection<TMachine>;
+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
  */
-export declare type XstateTreeMachineInjection<TMachine extends AnyStateMachine> = {
-    _xstateTree: XstateTreeMachineStateSchemaV2<TMachine>;
+export declare type XstateTreeMachineInjection<TMachine extends AnyStateMachine, TSelectorsOutput = ContextFrom<TMachine>, TActionsOutput = Record<never, string>, TSlots extends readonly Slot[] = Slot[]> = {
+    _xstateTree: XstateTreeMachineStateSchemaV2<TMachine, TSelectorsOutput, TActionsOutput, TSlots>;
 };
 
 /**

package/lib/xstateTree.js

@@ -203,7 +203,8 @@ exports.recursivelySend = recursivelySend;
  * @param machine - The root machine of the tree
  * @param routing - The routing configuration for the tree
  */
-function buildRootComponent(machine, routing) {
+function buildRootComponent(options) {
+    const { input, machine, routing } = options;
     if (!machine._xstateTree) {
         throw new Error("Root machine is not an xstate-tree machine, missing metadata");
     }
@@ -213,6 +214,7 @@ function buildRootComponent(machine, routing) {
     const RootComponent = function XstateTreeRootComponent() {
         const lastSnapshotsRef = (0, react_2.useRef)({});
         const [_, __, interpreter] = (0, react_1.useActor)(machine, {
+            input,
             inspect(event) {
                 switch (event.type) {
                     case "@xstate.actor":
@@ -318,7 +320,7 @@ function buildRootComponent(machine, routing) {
                 const { getPathName = () => routing.history.location.pathname, getQueryString = () => routing.history.location.search, } = routing;
                 const initialMeta = {
                     ...(routing.history.location.state?.meta ?? {}),
-                    onloadEvent: (0, utils_1.isLikelyPageLoad)(),
+                    onloadEvent: true,
                 };
                 const queryString = getQueryString();
                 const result = (0, routing_1.handleLocationChange)(routing.routes, routing.basePath, getPathName(), getQueryString(), initialMeta);

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.1",
+  "version": "5.1.0-next.11",
   "license": "MIT",
   "description": "Build UIs with Actors using xstate and React",
   "keywords": [