How to adapt to a javasript framework?

[j2l]

Hello, Your approach from diagram to code is fantastic! I'm discovering state machines but know yED. Thank you! What would be need to generate enhanced javascript code like react, vue, svelte? (the later is very close to javascript) Adapt by hand yedEdgeLabelGrammar.ne and js? Something else? Thank you!

[brucou]

Bonjour Philippe,

yEd is about the best diagramming tools out there for modeling, and I tried many. I am glad you like it.

What do you want to achieve? You want to:

• change the edge label grammar; or
• change the generated output?

If you want to keep the same edge label grammar, then you don't need to change the yedEdgeLabelGrammar.ne. That grammar is pretty simple and is as follows:

MAIN -> OneTransitionLabel                             {% d => d[0] %}
| MultipleTransitionLabel                              {% d => d[0] %}
MultipleTransitionLabel -> ("|" OneTransitionLabel):+  {% d => d[0].map(x => x[1]) %}
OneTransitionLabel ->
  EventClause "[" GuardClause "]" _ "/" ActionsClause  {% d => ({event: d[0], guard: d[2], actions: d[6]}) %}
| EventClause "[" GuardClause "]" _                    {% d => ({event: d[0], guard: d[2], actions: []}) %}
| EventClause "/" ActionsClause                        {% d => ({event: d[0], guard: [], actions: d[2]}) %}
| EventClause                                          {% d => ({event: d[0], guard: [], actions: []}) %}
| "[" GuardClause "]" _ "/" ActionsClause              {% d => ({event: "", guard: d[1], actions: d[5]}) %}
| "/" ActionsClause                                    {% d => ({event: "", guard: [], actions: d[1]}) %}
| "[" GuardClause "]"                                  {% d => ({event: "", guard: d[1], actions: []}) %}

EventClause -> [^\/\[\]\|,]:+                           {% d => d[0].join('') %}
GuardClause -> Guard ("," Guard):*                     {% d =>  [d[0]].concat(d[1].map(dd => dd[1]))  %}
Guard -> [^\[\],]:*                                     {% d => (d[0] || []).join('') %}
ActionsClause -> Action ("," Action):*                 {% d =>  [d[0]].concat(d[1].map(dd => dd[1]))  %}
Action        -> [^\/\|\[\]\(\),]:* ActionsComments:*  {% d => (d[0] || []).join('') %}
ActionsComments -> "(" __ ")" _
StringLiteral -> [\w]:+
  _ -> [\s]:*
  __ -> [^()]:*

This file contains both a description of the label grammar with an eBNF-like syntax and instructions to convert a parse tree into an abstract syntax tree (the %d =>...). You can play with it in the Nearley playground. Simply copy paste that grammar into the playground. Type some edge label on the input field in the right, and you will see the results of the parsing. .ne denotes a Nearly extension. Nearley is the parser I use here. It is not the fastest parser but it is the most user-friendly (playground, ambiguity tolerance, etc.). The .ne file is compiled to a .js file that does the actual parsing. So Nearley is in fact a parser generator. It takes a language description file (.ne) and generates a parser (.js) with a CLI (cf. Nearley documentation).

If you want to change the output, then you need to modify index.js. Namely you probably should write new code starting there. You should be able to use what is before: the parsing logic, the file reading and writing, and the data transformations. What you will have to change is the compiledContents.

I hope that helps.

Tell me more about you want to do. If I understand your use case, I am happy to support you into generating your Svelte code. And also, you can speak French if that's better for you :-)

[j2l]

Bonjour ! Are you also French? I don't mind continuing writing in English to help others (use case through SEO) for the moment. I might switch to French if it goes deep though.

Thank you very much for all this information. OK, let's go ideal: I'd like to design in yED, and push a big red button (or a command line like slim or yed2kingly) to:

• get .js or some .svelte file(s) ready to finalize (see a XState svelte tutorial to get why I switch to state machines : https://css-tricks.com/coordinating-svelte-animations-with-xstate/)
• get a test folder populated with all tests ready against this generated code :smile:

XState tried various javascript platforms (https://xstate.js.org/docs/recipes/svelte.html) and a particular svelte demo is pretty self explanatory about the diagram+code: https://github.com/kyrianda/svelte-xstate-inspect-plantuml/ But it totally lacks the awesomeness of designing in a robust (and so great at automatic layouts) diagramming solution like yED.

BTW, did you know you can start building yED diagrams from a table? https://yed.yworks.com/support/manual/import_excel.html This helps drafting big diagrams and avoid labeling mistakes for connections.

[brucou]

I do understand the French language :-) But yes English may be better. So:

• generate some Svelte file should not be difficult as long as you know with Svelte code you want to output. That said that may not even be necessary. Kingly really produces a simple JavaScript function so you can reuse that anywhere. You may have a Svelte component (say that accepts as parameter a Kingly machine imported from the yED compiled file. That is how I integrated Kingly with React. API here. You really just have to write the same component but with Svelte instead of React. You should be able to keep the same API (you can ignore the preprocessor in the beginning, that's for complex cases). I can help you with that if you want to.
• about tests, I am currently working on that. I already have automatic test generation working, and it is working fine, but the API is not as friendly as I would like. The thing about tests is that if it is not simple, people won't write them. So I still haven't published it. But more on that when I get there. Could easily take three months though... In any case, you can't have (interesting) tests automatically generated for you if you do not write a generator on every transition. Hard to explain here, but suffice to say that you will need more than yED to do that.

Otherwise:

• yes I know you can use a table as an input for yED. yED has been there for 20 years and there are a lot of features like that that are available. That said, the table format may not be the most practical for simple purposes. I do agree that for large graphs there may be some value in connection with Excel macros to check the graph against some rules.
• will have a closer look at the Svelte animations article though I don't really follow XState. I am happy that it is spreading the good word about state machines, but it very much looks like an usine a gaz. State machines really are a simple construct.
• The codesandbox link from your article is not working anymore (or maybe that's my machine, I have some very restricted environment there for security reasons): https://codesandbox.io/embed/before-mgsif?fontsize=14&theme=dark. I see it is about an autocomplete widget. I have an example like that here on the documentation site. That's the machine:

The great with state machines is that you don't really have to look at the code anymore. And if you keep it simple like Kingly tries to do, there is not much to learn and visualize. Anyways, I may try to turn the react-state-driven component into a svelte-state-driven component if you are interested to test it for your use case.

[brucou]

@j2l I just realized I already did a Svelte integration: https://github.com/brucou/svelte-machine-component :-)

Just that I did not document it. It is 60 lines of code, so not too hard to understand, but I should write a proper documentation for it. I may take advantage from your interest to refresh the implementation and document it. I don't really remember what I did there, that was two years ago and apparently I never used it - it is just so simple with Svelte to directly used the machine in a component that making a wrapper does not have so many advantages.

[j2l]

Hihi, I also forget what I did a few years ago. Thank you! I'll take time to study this. Rapidly, it seems complicated, maybe because of svelte back.

[brucou]

Yeah it took me a while to get into it. This uses Svelte slot props which is a bit of a convoluted feature in any template language (e.g., same applies to Vue or Angular). So basically it goes like this:

• API: <Machine commandHandlers initEvent fsm let:dispatch={dispatch}/>
• fsm: the machine created by Kingly's createStateMachine factory. That factory can be imported from the JavaScript compiled from yEd. Sth like import {createStateMachine} from yourYedCompiledFileHere.js.`
• commandHandlers: a POJO that maps every one of its properties to a command handler that, well, handle the matching command. For instance {FETCH_THIS: function fetch (dispatch, params) {fetch that thing; return something}}
• initEvent: the initial event to send to the machine. It is optional but generally you want to do that to get something to display the when the component mounts.

How does this work?

• the let:dispatch let you bind a dispatch variable that can be used inside of the <Machine /> component. E.g:

  <Machine commandHandlers=... initEvent=... fsm=... let:dispatch={dispatch}>
  <button on:click="{e => dispatch(SOME_EVENT, some params computed from e, }" .../>
  </Machine>

• At mount: displays the component slot (here <button/>)
• When user clicks: dispatch the SOME_EVENT event to the machine. The machine computes some commands. Those commands are matched to the corresponding command handler. The matching command handler is executed with the following parameters: commandHandler (dispatch, some params computed from e). Because the command handler is passed the dispatcher, it can also send events to the machine. For instance when the FETCH_THIS requests fails or succeeds, the command handler can send FETCHED_OK or FAILED_FETCH events to the machine.

If you have a concrete example to use this with, I can guide you through how to do it. Just let me know. But again, I think that inlining works best, and that's probably why I did not publish this component in the end.

[j2l]

Hello! OK, I'm back to svelte and fsm. I hope you had time to finalize tests :smile:

As I wanted a real-life example to run svelte from, I started with the password fsm.

I successfully generated the password-meter.graphml.js password-meter.graphml.fsm.js.zip

I tried to add the js file from the doc (https://codesandbox.io/s/mqx96pm64j?from-embed=&file=/src/index.js) and the basic html (div app) and import it as svelte component import KinglyPassword from "./kinglyPassword.svelte";

I adapted the INIT_SCREEN:

  const INIT_SCREEN = `
    <section>
      <label for="password">Enter password</label>
      <input
        type="password"
        name="password"
        id="password"
        onkeyup="${inputEventHandler}"
      />

      <meter max="4" id="password-strength-meter"></meter>
      <p id="password-strength-text"></p>
      <button onclick="${buttonEventHandler}">Submit</button>
    </section>
  `;

But it never shows up (maybe because svelte needs @html?) I have no error in the console though, just the Kingly messages.

Maybe using the JS example is not the best way to make it work?

Si I tried another way I understand that, in App.svelte, I'll need:

import { NO_OUTPUT } from "kingly";
  import emitonoff from "emitonoff";
  import {
    events,
    states,
    getKinglyTransitions,
    createStateMachineFromGraph,
  } from "../password-meter.graphml.fsm.js";
  let commandHandlers, effectHandlers;
  let initEvent = {};
  let fsm = createStateMachineFromGraph(events, states, getKinglyTransitions);

But then, I don't know what to add to reach something like: <Machine commandHandlers=... initEvent=... fsm=... let:dispatch={dispatch}></Machine>

[brucou]

Great to hear that you are back to Svelte and fsm :-) I will add a Svelte example for the password meter (hopefully tonight) to the documentation. We can then take it from there and address any questions you may have. What do you think?

[j2l]

Yes, if you could use the graph js file I attached, it's perfect!

[brucou]

@j2l I made a copy paste of the Vue implementation of the password meter, and converted it to Svelte. Quick and dirty but there it is: https://codesandbox.io/s/inspiring-wright-tdrxk?file=/App.svelte

Will have a look at your password-meter.graphml...js file tomorrow. But generally speaking, and reviewing our exchange from the beginning, I was telling you that abstracting the fsm into a component resulted in somewhat convoluted code with Svelte and that directly using the code was not a bad option. Cf. code comments, I will abstract a bit more the code tomorrow.

Going to bed!

[j2l]

This is great! Thank you! Can't wait for a yed to svelte FSM to happen.

[brucou]

Here is the version with the event handler logic abstracted: https://codesandbox.io/s/fast-breeze-9736z?file=/App.svelte.

As you can see the abstraction is a 3-liner. That is very much how I would use Kingly fsm with Svelte. Abstracting with a <Machine> component, while seemingly attractive, is not the best option in my opinion with Svelte.

• create a dispatcher from the machine and command handlers
• dispatch all user events to the machine with the dispatcher
• the dispatcher will execute the command as instructed by the command handlers
• that's it! there is nothing more to it.

I realize that I still haven't looked at your file :-) Will do tomorrow. But you see that once you have your machine exported (that's fsm.js), it does not matter how you created that machine (with createStateMachineFromGraph, or from the slim compiler, or directly written by you).

More tomorrow

[brucou]

Well I did it now https://codesandbox.io/s/billowing-currying-0jlkr?file=/fsm.js

Gotchas:

• the event names (in properties.js must match the ones you used in the yed file)
• you can create the fsm quicker with createStateMachineFromGraph. Cf. fsm.js
• the name of events you used in yed are exported so you can have them to reuse them Cf. fsm.js. That's how I was able to put back in properties.js the right values for the events.
• so are the states, but those you are never going to need it in normal circumstances so you can safely ignore it. That was more for debugging purposes.

[j2l]

Wow! Trop bien !

Thank you soooo much for delivering so fast and perfectly. I really appreciate you took the challenge. I'll study this ASAP. Closing.

Excellente journée à toi !!!

[brucou]

Merci, si tu as d'autres questions, tu me dis. Je vais ptet actualiser la docs et rajouter Svelte quand meme.

[j2l]

Ca marche, merci encore.