[v5] Routable states

[davidkpiano]

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.

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:

settings: {
  id: 'settings',
  route: {
    guard: ({ context }) => context.role === 'admin'
  }
}

[changeset-bot]

🦋 Changeset detected

Latest commit: 2788fb2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
xstate	Minor
@xstate/react	Major
@xstate/solid	Major
@xstate/svelte	Major
@xstate/vue	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

[christophe-g]

@davidkpiano

I am quite interested in this for binding the route with machine state actors.

Now that emit has landed (thanks!), would it make sense to emit a route event any time a state enters via actor.send({ type: 'xstate.route.anyRouteState')} ?

This would facilitate keeping the route in sync with the active state. Happy to provide more context if needed.

[davidkpiano]

@christophe-g Glad you're interested in it!

Emitting events should be explicit, though, and it may be better to .subscribe(…) to the state changes and map those to URL states.

More context would be appreciated.

[christophe-g]

More context would be appreciated.

@davidkpiano - this is not really more context, but a new lit controller binding xstate actor machine with a router.

• More info: https://github.com/lit-apps/lit-app/tree/dev/packages/xstate-route
• Live example: https://xstate-route.web.app/home/fsm/one

and it may be better to .subscribe(…) to the state changes and map those to URL states.

I took your advice for this controller ...

Any change to have this PR merged ?

[christophe-g]

Dear @davidkpiano - just interested to know if this PR has any chance to be merged, or if there are any blocking issues ?

I have build a lit-controller around this (see above). This PR allows to de-couple business logic (handled by xstate machine), routing / navigation (natively handled by the browser), and views (provided by the router / also bound to state machine), which is great!

[davidkpiano]

Dear @davidkpiano - just interested to know if this PR has any chance to be merged, or if there are any blocking issues ?

I have build a lit-controller around this (see above). This PR allows to de-couple business logic (handled by xstate machine), routing / navigation (natively handled by the browser), and views (provided by the router / also bound to state machine), which is great!

It does have a chance! Going to update it soon.

[christophe-g]

It does have a chance! Going to update it soon.

@davidkpiano - Fantastic, thank you !

[Hebilicious]

For anyone that needs this, I've implemented a verbose workaround:

1. Create a routeTo property in the context for the route
2. Define a guard per routable state that check for routeTo
3. Create a RouteTo event with an array of all routes+ guard

Then you can route to a specific state by assigning routeTo and sending the RouteTo event

Routable state would simplify things massively though.
@davidkpiano Just an idea, but maybe the route should have a way to control where its connected to, something like this :

const todoMachine = createMachine({
  type: 'parallel',
  states: {
    todo: {
      initial: 'new',
      states: {
        new: {},
        editing: {}
      }
    },
    filter: {
      initial: 'all',
      states: {
        all: {
          route: { id: "filterRoute" }
        },
        active: {
          route: { id: "filterRoute" }
        },
        completed: {
          route: [{ id: "filterRoute" }, {id: "helloWorld"}]
        },
        hello: {
          route: { id: "helloWorld" }
        },
        world: {
          route: { id: "helloWorld" }
        }
      }
    }
  }
});

[christophe-g]

Routable state would simplify things massively though

Routable states are a hidden gem of xstate. Using with a lot of joy for instance in relatively complex stepper UI, allowing to bind the view with the state through the route.

[joernroeder]

I'd love to see this as part of xstates core. still plans to merge this in @davidkpiano?

[minhazfm]

This would be a huge help in keeping browser routing in sync with state machines! Thankful for your hard work @davidkpiano! Hope to see this available in V5 soon!

[davidkpiano]

I'd love to see this as part of xstates core. still plans to merge this in @davidkpiano?

Yes, I'd still like to see this merged in soon

[handletastic]

🙏🏼 What faith must I convert to for my plea to realise? 🥺 @davidkpiano