[v5] Routable states

.changeset/three-sails-rhyme.md

@@ -0,0 +1,38 @@
+---
+'xstate': minor
+---
+
+Added routable states. States with `route: {}` and an explicit `id` can be navigated to from anywhere via a single `{ type: 'xstate.route', to: '#id' }` event.
+
+```ts
+const machine = setup({}).createMachine({
+  id: 'app',
+  initial: 'home',
+  states: {
+    home: { id: 'home', route: {} },
+    dashboard: {
+      initial: 'overview',
+      states: {
+        overview: { id: 'overview', route: {} },
+        settings: { id: 'settings', route: {} }
+      }
+    }
+  }
+});
+
+const actor = createActor(machine).start();
+
+// Route directly to deeply nested state from anywhere
+actor.send({ type: 'xstate.route', to: '#settings' });
+```
+
+Routes support guards for conditional navigation:
+
+```ts
+settings: {
+  id: 'settings',
+  route: {
+    guard: ({ context }) => context.role === 'admin'
+  }
+}
+```

packages/core/src/StateMachine.ts

@@ -9,6 +9,7 @@ import {
 } from './State.ts';
 import { StateNode } from './StateNode.ts';
 import {
+  formatRouteTransitions,
   getAllStateNodes,
   getInitialStateNodes,
   getStateNodeByPath,
@@ -148,6 +149,7 @@ export class StateMachine<
     });
 
     this.root._initialize();
+    formatRouteTransitions(this.root);
 
     this.states = this.root.states; // TODO: remove!
     this.events = this.root.events;

packages/core/src/setup.ts

@@ -25,6 +25,7 @@ import {
   MetaObject,
   NonReducibleUnknown,
   ParameterizedObject,
+  RoutableStateId,
   SetupTypes,
   StateNodeConfig,
   StateSchema,
@@ -251,7 +252,13 @@ type SetupReturn<
     config: TConfig
   ) => StateMachine<
     TContext,
-    TEvent,
+    | TEvent
+    | ([RoutableStateId<TConfig>] extends [never]
+        ? never
+        : {
+            type: 'xstate.route';
+            to: RoutableStateId<TConfig>;
+          }),
     Cast<
       ToChildren<ToProvidedActor<TChildrenMap, TActors>>,
       Record<string, AnyActorRef | undefined>

packages/core/src/stateUtils.ts

@@ -383,6 +383,53 @@ export function formatTransitions<
   return transitions as Map<string, TransitionDefinition<TContext, any>[]>;
 }
 
+/**
+ * Collects route transitions from all descendants with explicit IDs. Called
+ * once on the root node to avoid O(N²) repeated traversals.
+ */
+export function formatRouteTransitions(rootStateNode: AnyStateNode): void {
+  const routeTransitions: AnyTransitionDefinition[] = [];
+  const collectRoutes = (states: Record<string, AnyStateNode>) => {
+    Object.values(states).forEach((sn) => {
+      if (sn.config.route && sn.config.id) {
+        const routeId = sn.config.id;
+        const userGuard = sn.config.route.guard;
+        const routeGuard = (
+          args: { context: any; event: any },
+          params: any
+        ) => {
+          if (args.event.to !== `#${routeId}`) {
+            return false;
+          }
+          if (!userGuard) {
+            return true;
+          }
+          if (typeof userGuard === 'function') {
+            return userGuard(args, params);
+          }
+          return true;
+        };
+        const transition: AnyTransitionConfig = {
+          ...sn.config.route,
+          guard: routeGuard,
+          target: `#${routeId}`
+        };
+
+        routeTransitions.push(
+          formatTransition(rootStateNode, 'xstate.route', transition)
+        );
+      }
+      if (sn.states) {
+        collectRoutes(sn.states);
+      }
+    });
+  };
+  collectRoutes(rootStateNode.states);
+  if (routeTransitions.length > 0) {
+    rootStateNode.transitions.set('xstate.route', routeTransitions);
+  }
+}
+
 export function formatInitialTransition<
   TContext extends MachineContext,
   TEvent extends EventObject

packages/core/src/types.ts

@@ -1038,6 +1038,42 @@ export interface StateNodeConfig<
 
   /** A default target for a history state */
   target?: string | undefined; // `| undefined` makes `HistoryStateNodeConfig` compatible with this interface (it extends it) under `exactOptionalPropertyTypes`
+  route?: RouteTransitionConfig<
+    TContext,
+    TEvent,
+    TEvent,
+    TActor,
+    TAction,
+    TGuard,
+    TDelay,
+    TEmitted
+  >;
+}
+
+export interface RouteTransitionConfig<
+  TContext extends MachineContext,
+  TExpressionEvent extends EventObject,
+  TEvent extends EventObject,
+  TActor extends ProvidedActor,
+  TAction extends ParameterizedObject,
+  TGuard extends ParameterizedObject,
+  TDelay extends string,
+  TEmitted extends EventObject
+> {
+  guard?: Guard<TContext, TExpressionEvent, undefined, TGuard>;
+  actions?: Actions<
+    TContext,
+    TExpressionEvent,
+    TEvent,
+    undefined,
+    TActor,
+    TAction,
+    TGuard,
+    TDelay,
+    TEmitted
+  >;
+  meta?: Record<string, any>;
+  description?: string;
 }
 
 export type AnyStateNodeConfig = StateNodeConfig<
@@ -2499,6 +2535,7 @@ export type ToChildren<TActor extends ProvidedActor> =
 
 export type StateSchema = {
   id?: string;
+  route?: unknown;
   states?: Record<string, StateSchema>;
 
   // Other types
@@ -2542,6 +2579,16 @@ export type StateId<
         }>
       : never);
 
+export type RoutableStateId<TSchema extends StateSchema> =
+  | (TSchema extends { route: any; id: string } ? `#${TSchema['id']}` : never)
+  | (TSchema['states'] extends Record<string, any>
+      ? Values<{
+          [K in keyof TSchema['states'] & string]: RoutableStateId<
+            TSchema['states'][K]
+          >;
+        }>
+      : never);
+
 export interface StateMachineTypes {
   context: MachineContext;
   events: EventObject;