[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[bot]]

⚠️ No Changeset found

Latest commit: ca809782feb908308300ac7e17ceb67ece902359

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[bot]]

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.

[ghost]

👇 Click on the image for a new way to code review

Legend

[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 ! 🚀