simplify examples

Do you want to request a feature or report a bug?

Improvement / debt.

What’s the current behavior?

Right now we have a lot of examples, which is awesome to help people get started and conceptualize what Slate makes possible (a lot). But this is also a drag on maintenance because sometimes the examples are complex, and even written in different styles, which makes deciphering them hard. (Not to mention it makes it harder for newcomers to decipher what they are trying to exemplify.)

What’s the expected behavior?

I’d like to have all examples simplified to be ideally less than 300 LOC or so, and in a single file. (Right now it’s okay to have the default value.json separated out into a separate file, but with #2495 this will be combined into a single file.)

The examples that need simplification are:

• composition
• embeds
• huge-document
• input-tester
• mentions
• plugins
• restore-dom

In some cases this might require actually reducing the functionality of the example to make it simpler to reason about—that’s okay.

For example, the mentions example can be changed to use a window.prompt instead of a complex dropdown. (This is obviously not how someone would implement mentions in their application, but that’s not what the example is for. It is not for copy-pasting into your own codebase as is. It is for showing how the mentions are modeled and managed in Slate.)

---

Secondly, it would be good to break out “tools” from “examples” I think. Currently the composition and input-tester examples aren’t really for end-users. They’re really development tooling that’s helpful when working on Slate. A list of these are:

• composition (move)
• huge-document (move)
• input-tester (move)
• restore-dom (delete)

---

These simplifications will allow us to have a better examples site later, where the source code can live on the page right adjacent to the working example itself. Similar to how react-router has structured their examples. (Getting the complexity and LOC down is critical to making it still understandable in this format.)

[ianstormtaylor]

@thesunny good point, agreed. On desktop I think we can stand to gain a lot though by changing to a sidebar, so we’ll have to have logic to switch for mobile.

[thesunny]

@ianstormtaylor

Is it possible to keep the tools published somewhere at the same time as examples but maybe not as part of the main examples? To me it seems like huge-document and composition would be helpful to have easily accessible to everyone so that people can provide feedback on their platform without having to clone the repo.

For example, some of the composition bugs came in from devices that I don’t own personally. I simply published the examples and gave people the URL.