Add description property to state and transition

[davidkpiano]

This PR adds description as a top-level property for state nodes and transitions:

const machine = createMachine({
  // ...
  states: {
    active: {
      // ...
      description: 'The task is in progress',
      on: {
        DEACTIVATE: {
          // ...
          description: 'Deactivates the task'
        }
      }
    }
  }
});

[changeset-bot]

⚠️ No Changeset found

Latest commit: 622565f

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

[mattpocock]

Is this an alternative to meta.description?. I like it.

[davidkpiano]

Is this an alternative to meta.description?. I like it.

You got it! I feel that description merits its own property, especially as we're making statecharts-as-documentation first-class citizens.

[mattpocock]

Agree! I will add this to the parser.

[Andarist]

What the meta property is supposed to hold now? Is it just a bag of whatever one wants to put on a state/transition (basically Record<string, any>)? What has prompted moving this from the meta to the "core"?

[mattpocock]

@Andarist Having autocomplete on description should be nice! And having it as a key on the event should also be handy

[Andarist]

We probably should mention here that "rendering in Markdown" applies to the XState visual tooling. It would also be nice to specify what flavor of Markdown this is interpreted as (I assume that it's GFM but could be Commonmark or something else)

[davidkpiano]

I removed the markdown part. Will specify in documentation for tooling, not here

[davidkpiano]

What the meta property is supposed to hold now? Is it just a bag of whatever one wants to put on a state/transition (basically Record<string, any>)? What has prompted moving this from the meta to the "core"?

Devs use meta for many different things, some of which may even conflict with description etc. We ultimately don't want to mix things that XState will natively support in tooling (like description) with "free-form" meta objects.

Motivation is also here: #2672 (comment)

[Andarist]

This probably deserves a small changeset - other than that: LGTM