Zag JS Visualizer

plan.md

Plan for the Zag JS v1 Visualizer

1. StateNode Structure

   • initial: Points to the initial child StateNode
   • transitions: Includes eventType, cond | condition | guard, actions, and a short description
   • id, key: Identifiers for the node string
   • states: An array of children StateNode[]
   • order: A numeric indicator (e.g. 1, 2, 3), likely matching the definition order
   • description: A brief explanation of the node’s role optional string
   • definition: References to invoke, entry, and exit actions Record<'name' | 'id', string>
   • tags: State tags string[]
   • parent: StateNode
   • type: Either atomic or compound (only the root node is compound in Zag) => The machine is a node (root node)

2. Building the Tree

   • Create a root StateNode and attach each state as a child (states array).
   • Since Zag doesn’t use nested states, this is just one level below root.
   • Traverse all nodes to set their parent and assign an order if needed.

3. Creating a Directed Graph

   • Once the Root node and its children are established, construct a directed graph from them.
   • Each StateNode becomes a node, and each transition becomes a directed edge.

4. Simulation

   • The plan is to run the machine, send events, and check which StateNode is active and what the context is.
   • Guards (cond) can be asked dynamically, context can change, and transitions determine the new active state.

5. Visualization

   • We use elkjs for graph
   • Support panning, autolayout

6. Data

   • We wanna be able to parse machine code. i.e. evaluating machine schema in isolated browser environment. This result can then be interpreted by useMachine
   • https://github.com/maple3142/wasm-jseval

Notes

• Sending events to child machines in Zag => Set, Send, Register, Use
• Visualizer only expects a machine, so parsing happens outside
• Getting intial state from running machine. service.state.initial

Miscellanous - (Possible Future)

• Embeds
• Syncing with a visual component

Resolve

• Getting next events of active state