Fix the NPM package!

[Sheldonfrith]

I originally left an issue on the 'kingly' repo, as I was unaware of this repo.

Now that I look at the code in this repo it appears that the package on NPM is not up to date with this repo (it is missing many files that are in this repo).

[Sheldonfrith]

Looks like it might be an issue with the package.json, as the only files NPM is downloading on my end are the ones specified in the 'files' field of package.json ... not sure why this is, I don't see a .npmignore anywhere... but I don't know much about NPM.

[Sheldonfrith]

Well it looks like I got it working, but I had to manually add the files missing from the package.

[brucou]

@Sheldonfrith the grammar file is indeed missing from the package.json file. Will issue a new version today.

[brucou]

@Sheldonfrith I released a new version. This should remove some verbose logs, update kingly to its latest version and add the appropriate files in the package.json. I'll look into the issue with yed2kingly not in the path tonight.

[brucou]

@Sheldonfrith version 0.7.0 should also allow the CLI to be called directly from the shell without prefixing with node. I updated the documentation. You need to install globally the package so the script is put in the global path. Let me know if there is any pending issues. You can then use yed2kingly filename or the shorthand y2k filename.

Also there is the slim package which does something similar to yed2kingly. It takes a yed file and compiles it to zero-dependency vanilla-js (count 1K-2K post compilation depending on your machine size). That can be useful for production builds. I also updated that package that suffered from the same issues. Hopefully it works also fine now.

[Sheldonfrith]

@brucou Works like a charm now, thanks!

[brucou]

@Sheldonfrith excellent!!!!

Just getting started with Kingly, if it does what I think it does its awesome and will surely become very popular!

Let me know later on if the package does what you thought :-) any feedback is welcome!

[Sheldonfrith]

Well, I don't think its exactly what I thought it was. It's not that there's anything wrong with the library that I can see, its just I'm trying to accomplish something very specific, and maybe what I'm trying to do is just a bad paradigm (I'm fairly new to software dev).

I'm trying to figure out an architecture that will allow me to completely separate UI logic from UI rendering/View layer in a way which allows very rapid changes to the entire UI design, without requiring any changes to the UI logic code, and I'd like all the UI logic hopefully to be encapsulated by a single statecharts-style state machine. Sorry for the imprecise language, I don't have a computer science degree, so I'm probably not using the right terms for things.

I've spent the past few weeks trying to figure out how to do this with XState, but constantly running into roadblocks. I initially thought that Kingly WAS the architecture I was looking for, but after I've now read through most of the docs it seems to provide similar functionality to XState just in a different way (maybe better, but its too early for me to tell). The primary thing that I'm looking for that Kingly doesn't provide (which is also missing from XState) is some sort of intuitive linking between the 'state' and the 'view' while maintaining complete independence and truly allowing the 'state' to be easily plugged in to any front end framework (yes I know I'm contradicting myself). HOWEVER reading through the Kingly docs, and seeing how you do things has given me a better understanding of statecharts in general and might have given me the breakthrough I've been looking for, as I've just come up with an architecture/design that I think will accomplish what I want, without major drawbacks. I'm probably reinventing the wheel here, as it seems everything has been done before a million times in the coding world, but the architecture I've come up with allows any aspect of the UI design to be changed without requiring any changes to the state-machine layer, as long as the UI design changes, obviously, don't require a change in the BEHAVIOR of the app, and I know you might say Kingly and XState already do that, but not how I'm envisioning it (hopefully once I've written the code I will be able to explain it better, or at least show it). However I may still use Kingly for the state-machine part of the architecture partly because I like its simplicity and also because I really like the yed2kingly and the ability to compose the basic structure of the code graphically.

[brucou]

Thank you for sharing your objectives. You are right that I will tell you that Kingly does allow to write UIs and separate logic from UI (visual) design :-)

The primary thing that I'm looking for that Kingly doesn't provide (which is also missing from XState) is some sort of intuitive linking between the 'state' and the 'view' while maintaining complete independence and truly allowing the 'state' to be easily plugged in to any front end framework (yes I know I'm contradicting myself).

The linking between state (of the application) and view that you are mentioning are props. If you have a visual design for which you are able to elicit a fixed number of parameters from which you can implement that design, then those parameters are your props, and one concern of the Kingly machine will be to compute those props from the state of the machine.

For instance, in the chess game (in the simplest iteration of the game --- no undo etc.), we only need to know if a particular piece on the board if selected, what piece that is if any, and the position of the board to draw. Cf. https://brucou.github.io/documentation/v1/tutorials/chess-game.html#Specifications. This is encoded in the documentation with props position and squareStyles, which are those used by the chosen React UI component. So now that I think about it, it does appear coupled to the UI component, in the sense that if you change the component to, say, use a Vue chess component with different props, then you have to change the implementation. Well yes, and no, I'll explain.

• position and squareStyles have all the information I need to visualize my UI. If my design does not change at all, I can just compute the Vue props from those two, without changing the machine. For instance, this https://github.com/vitogit/vue-chessboard#usage component uses fen as prop, where fen is a string that encodes the content of the board (for instance 5rr1/3nqpk1/p3p2p/Pp1pP1pP/2pP1PN1/2P1Q3/2P3P1/R4RK1 b - f3 0 28). To use the Vue component without modifying previous code, I can add, in the render command handler, a function that computes fen from position. The change happens in the render command handler, not in the machine (the behavior specifications have not changed!!). So you did have to change something, but it was in code that was anyways bound to change (you changed the design! so you have to change the render command handler)
• Note that complete independence between view and application state is not possible because precisely, your view depends on the application state, and it is that dependency that you are enforcing in your code. Two independent things do not affect each other and you do not want that. You want changes in the application state to be reflected in the UI. In Kingly that dependency between view and application is represented by the computation of props by the machine, and the render command handler.
• What ARE independent are the behavior of the application and the visual design. That is, your chess game does not change rules if you change the board visual appearance. Because Kingly completely separate behavior or application logic from rendering, you don't have to change the machine specifications if your behavior did not change. That means you don;t have to test the behavior again if you already did!

yes I know I'm contradicting myself

Yes and no. This happens all the time in spoken speech. The words we use are not precise enough to avoid contradictions. We often get out of contradicitons by describing reality better with our words. Here, I would say the view should be separated into, say, the HTML, and the computation that produces the HTML. The application can be separated in event handling, behavior computation and command handling (that is the Kingly architecture). You want to link user events to application commands, that is the machine. You want to link the render command to HTML: that's the view computation implemented in the render command handler. That view computation is a pure function, so there is no view state, only view parameters (props).

With all that said, whether you end up using Kingly or not, I am interested to see what you came up with. Thanks for the feeback on Kingly, it is very useful to me. If you have any suggestions, also feel free to share them.

[Sheldonfrith]

Thanks for the reply. Unfortunately I'm working two jobs right now so I'm not able put much time into this problem, but I'm figuring out what I can during my breaks. I've refined my ideas more today, and it actually looks like there are only going to be minor architectural differences from what you described, the differences are primarily oriented around making the designer's job easier (I'm terrible at design so Im always architecting with the assumption of working with a designer). Right now, although I can't actually play around with it yet, I'm envisioning maybe a CLI that takes the UI statemachine and gets all possible configurations of the machine (minus the extended state/context obviously) and provides a simple interface to map view/rendering functions with each of the possible states. I can provide this list of states to the designer and (as long as they are well named) the designer can easily design what the view should look like for every possible scenario (in practice the machine states might for example map to a function that composes React components and provides their props from the state machine). I think this is very similar to what Kingly does with the machine outputting commands which provide the props for the view. Hopefully I can find time to try to implement a simple example soon. But my lunch break is over now...

[brucou]

Sure, whenever the time is best for you. Sleeping and resting properly is also important. Our brain can only process so much in a day. From what you say, I think that we are of a similar mind. My design skills are probably even below yours, and that was a motivation for Kingly's architecture. Separation of concerns here was partly motivated by separation of skills.

One comment though. There are different levels and skills of designers. If you have somebody purely doing the HTML (and not even so, some can just give you screens in the form of graphic files, but that is rare), then you will indeed have to be more explicit about the miscellaneous state of the applicatoin which impact the visual design. So in the chess game, that would be to tell the designer that you want a chess board with no pieces selected, and then one chess board with exactly one piece selected. These are the two screens that you will find in the docs. In the chess game with the chronometer, you would have to tell the designer to also provide a screen with the clock steady, and another one with the clock blinking (corresponding to a game that is paused). So if you deal with these designers, you may not need to give them a list of the states of the machine --- that is an implementation detail. You need to give them specification details (the application should make it visible to the user when the game is paused, etc.) and let them do their thing. Then you can turn all these specification details into props and states and so on.

Alright, letting you work, no stress and no rush. I have to work too in fact.