Working with SlateJS: Dos and Donts

[mkoskim]

MaweJS Editor component uses SlateJS as its low level editing component. There are many, many things that can go wrong or are at least misleading. I try to share my experiences working with SlateJS here.

SlateJS repository: https://github.com/ianstormtaylor/slate

SlateJS itself uses browser's (Chrome on ElectronJS) own internal editor, meant to edit contenteditable=true content. SlateJS's ReactEditor renders the Slate buffer as React elements.

Note: SlateJS is not necessarily used as the low-level editing component to eternity. Several AAA editors like Microsoft Visual Code (ElectronJS application) and Googledocs (web application) have their own editor implementation. It is just a big effort to start building such a component, and thus it will not happen in near future. Compared to its competitors, SlateJS performs very well: either it has the necessary features needed for MaweJS, or the component itself is built on SlateJS.

SlateJS is still mainly meant for editors like the one here in GitHub - to write comments and such, not entire stories.

[mkoskim]

The first thing to understand is how you render SlateJS elements. MaweJS's element rendering is here:

https://github.com/mkoskim/mawejs/blob/master/src/gui/editor/slateEditor.js#L79

Do not forget to render children! Whatever you do, always remember to render attributes and children. In that particular render function, I use ellips to grab children to rest, so that I can use bit shorter format. Instead of this:

<h5 {...attributes}>{children}</h5>

I can use this:

<h5 {...attributes} {...props}/>

Voids: Now, SlateJS has also so called void blocks. Void blocks are something that are rendered "outside" of SlateJS, and in most examples, they are images. It is very, very tempting idea to e.g. add the editor void-type title element, which will the get the content from body.head.

It is possible, at least in this case. There are few caveats when making voids:

1. You still need to have children with the void element. Don't forget to render them.
2. Voids with contenteditable=false can break the cursor movement. If the selection gets stuck to certain type of void element, instead of having a cursor, the page now acts like a regular HTML page: pressing up and down move the window, not the cursor.

Voids are very tempting way to implement something "out-of-SlateJS" to an editor, but there are lots of issues, if you want the void block editable by user (like title element) and retain the cursor and cursor movement.

[mkoskim]

It is not that simple making a void.

One of my folding implementations had something like: when the folded attribute of heading element is true, my isVoid reports true. Did this change the block a void element? No. SlateJS had already rendered children inside the block, and reporting it to void crashed the editor.

To make a void, you need to insert a void element to a buffer, not just "mark" something for this rendering round as a void.

So, my next attempt was very brute force: I selected the content of the scene, stored the content in an element, and replaced the entire content with void element.

It worked basically fine, except that when doing the opposite (void element was replaced with saved node tree) the normalize() function crashed.

The normalize() mechanism in SlateJS does not currently assume, that in one operation there will be huge blocks inserted in the buffer. It has internal limitation for the normalization rounds.

So, lesson 2: Don't play too smart. Try to keep automated buffer modifications small.