[v5] Routable states

[davidkpiano]

This PR enables developers to mark states as "routes" by providing a route config, which is just a normal transition config without the target:

const todoMachine = createMachine({
  type: 'parallel',
  states: {
    todo: {
      initial: 'new',
      states: {
        new: {},
        editing: {}
      }
    },
    filter: {
      initial: 'all',
      states: {
        all: {
          route: {}
        },
        active: {
          route: {}
        },
        completed: {
          route: {}
        }
      }
    }
  }
});

const todoActor = createActor(todoMachine).start();

todoActor.send({ type: 'xstate.route.filter.active' });
// => transitions directly to { todo: 'new', filter: 'active' }

The motivation for this is that there are many use-cases for wanting to transition directly to a state, such as in modeling page routes or steps in a multi-step form. Previously, you needed to manually hard-code transitions for these, which resulted in an unnatural and verbose state machine definition.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1a4b773

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a 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 !

[handletastic]

What's the current state? 👍🏼 Would love to see this ! 🚀

[christophe-g]

I see that this PR was marked as ready for review, but this might have gone unnoticed ; )

Just adding a comment here to try revive this powerful feature - and thanks anyway for this great piece of code !

[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