Visualizer: being able to show a title and a description

[mindrones]

It would be nice to have a title to distinguish different machines in various tabs.

It could be jsdoc in a comment like:

/**
 * A longer description that explains the inner workings.
 * It could be multiline.
 * @summary A concise title
 */

that would be rendered as:

<h1>A concise title</h1>
<p>A longer description that explains the inner workings.</p>
<p>It could be multiline.</p>

The title could also be shown in the page <title>.

[a-y-u-s-h]

Or maybe a description key for state nodes could add some visual component containing text about that node, though it's all good even now. ID on root node can act as title for a machine, and I think multiple machine tabs could be added based on ID itself.

JSdoc comments won't work well with all structures (some of us like separating out our states in JSON or YAML).

[davidkpiano]

For now, you can do this:

const machine = createMachine({
  // ...
  meta: {
    description: `# Some test machine` // any markdown
  }
});

And it will display in the inspector.

[Glavin001]

Edit: ❌ Never mind. This changes the state identified as well not only the title. So it beaks transitions 😢 . @davidkpiano any ideas we can show different titles than the state ID?

---

I also wanted to show a more detailed description and also replace the title.

This worked for me:

const fetchMachine = createMachine<Context>({
  // ...
  states: {
    theRawId: {
      key: "The Nice ID", // Override theRawId
      meta: {
        description: "# Description\nAllows screenshots:\n![](https://upload.wikimedia.org/wikipedia/commons/thumb/b/bd/Web_Page.png/800px-Web_Page.png)"
      }
    },
  }
});

[davidkpiano]

The key property will be deprecated as it shouldn't be overridden. I'd recommend using ID instead, and on our end, we should make that custom ID visible in the UI.

[Glavin001]

@davidkpiano : Would this be the applicable repo and line of code? https://github.com/statelyai/xstate-viz/blob/cd7eb85fd38eecfa70f2f9851a403ee0cdca4075/src/StateNodeViz.tsx#L137

If so, I'll create a quick Issue. One of use cases is to get around statelyai/xstate-viz#397 by providing a shorter state name.

Thank you!

*Edit: Created feature request: statelyai/xstate-viz#400

[davidkpiano]

Yes, that's the right area.