[EPIC] WYSIWYG/Rich Text Editor

[nelsonic]

As a person using the dwyl App to capture my thoughts/ideas/tasks/nots
I want to have a rich text editor with (basic) controls for formatting
So that I can visually enhance my items so they are easier/faster to organise and read.

Features / Requirements

Each one of these feature/requirement checkboxes will link to a sub-issue with more detail.
If the feature is already available in our choice of (existing open source) package, then we can simply check it off once the feature is working (and covered by our end-to-end UI tests).

• Basic:
  • ability to apply styles to text:
    • bold
    • italic
    • underline (not standard markdown but we want it for completeness)
    • strikethrough
  • hyperlink existing text
  • pasting/typing a valid link should be automatically hyperlinked (ideally shortened for brevity)
    • links to Youtube/Vimeo should prompt: "embed or just link"?
  • embed an image by pasting a link to the image (display thumbnail inline no resizing yet)
    • Click/tap an image to enlarge/full-screen it
  • Use Keyboard Tab key to indent text.
    • Indenting text should create a "sub-item" where appropriate (acceptance criteria TBD)
  • Bullet points for presentation
  • Numbered (Ordered) lists
  • Checkbox for when an item becomes a task ✅
• Advanced:
  • Markdown support? How popular is this outside of the tech community? I know I would use Markdown if we supported it ... how about you? How important do you feel this is?
  • Emoji support
    • Emoji lookup? (is this available by default on mobile device keyboards?)
  • Mention another person in your team (or contact list) to inform them of or assign a task.
  • Upload images
  • Re-size images in the body of the text

Please add more features/requirements to this list as you think of them. 🙏
This is your product every bit as much as it's mine. Contribute! 🚀

Research

I've done a fair amount of research (8+ hours) into the available options in preparation for opening this issue.

For Web I think we need to use a existing JS package in the short term to ship faster.
As much as I (still) love Elm, there is no "pret-a-porter" editor we can use, and I think it will take us 1-2 months to develop our own. (see more detail below)

During the course of my research I looked at:

• https://github.com/basecamp/trix - used by basecamp. well tested.
• https://github.com/jaredreich/pell - describes itself as "the simplest and smallest WYSIWYG text editor for web, with no dependencies" ... zero dependencies. this really appeals to me!
• https://github.com/yabwe/medium-editor - an open source clone of the medium editor
• https://github.com/neilj/Squire - Squire is an HTML5 rich text editor, which provides powerful cross-browser normalisation in a flexible lightweight package (only 16.5KB of JS after minification and gzip, with no dependencies!) - used in production at ProtonMail, Tutanota, Zoho Mail and Superhuman ... Squire would be my close-second option, but it does not appear to have an efficient way of passing data for collaborative editing (see below)
• many more options: https://awesomeopensource.com/projects/rich-text-editor

Quill.js

My preliminary leaning is towards using Quill.js: https://github.com/quilljs/quill
I don't think Quill is necessarily "better" than any of the others, it just has a "kill feature"!
My reasoning for Quill is actually Delta the underlying format!

Deltas are a simple, yet expressive format that can be used to describe Quill’s contents and changes. The format is a strict subset of JSON, is human readable, and easily parsible by machines. Deltas can describe any Quill document, includes all text and formatting information, without the ambiguity and complexity of HTML.
Don’t be confused by its name Delta—Deltas represents both documents and changes to documents. If you think of Deltas as the instructions from going from one document to another, the way Deltas represent a document is by expressing the instructions starting from an empty document.
Deltas are implemented as a separate standalone library, allowing its use outside of Quill. It is suitable for Operational Transform and can be used in realtime, Google Docs like applications.

zefyr https://github.com/memspace/zefyr uses Delta:

So when we need to build our Cross-platform Native App in Flutter, we already have the format to allow us to efficiently pass minimal data over the wire to collaborate on work as a team. see: dwyl/learn-flutter#50

I like the approach taken by Medium (the blogging/writing) platform they don't show the editor controls at all until you highlight a block of text. At which point they show an ultra-minimalist contextual editor:

We definitely want to take the approach of hiding the interface until the interaction by the "user" invokes it. Having a cluttered interface is the worst!

Elm?

I obviously searched for "elm wysiwyg editor" and "elm rich text editor" both on Google and https://korban.net/elm/catalog (the package search that only includes v0.19 compatible packages) and looked at https://github.com/mweiss/elm-rte ... it hasn't had much traction since the RFP on Elm Discourse (still only 1 contributor last commit 26 Dec 2019), no (real) tests ... the author appears to have shifted focus to: https://github.com/mweiss/elm-rte-toolkit which is still in it's infancy but looks really promising.
See: https://discourse.elm-lang.org/t/a-toolkit-to-create-rich-text-editors-in-elm/5464

If we had unlimited time, we would write our own WYSIWYG editor in Elm for sure!
Having no runtime errors and a compiler to catch any type errors would be awesome!
But we really don't have a lot of time to spend months writing our own editor which will only be useable on the Web and then we would still need to re-write it for Mobile ... We need to Ship!

I don't think we will incur too much technical debt by using an existing JS editor, provided we are laser focussed in our use and it's self contained in the "form" template.

Thoughts?

[nelsonic]

Why Quill: https://quilljs.com/guides/why-quill
API: https://quilljs.com/docs/api/
Building custom modules: https://quilljs.com/guides/building-a-custom-module/

[nelsonic]

Quill Checklist example: https://quilljs.com/standalone/list

Need to understand how it works under the hood. 🔍
This looks like a good place to start: https://github.com/koffeinfrei/quill-task-list (unfinished)

[nelsonic]

Checklist on localhost:

[nelsonic]

Sadly, the Delta does not have the "checked" attribute applied to the done item ...
we may need to take a look at this: https://github.com/koffeinfrei/quill-task-list/pull/1/files

[nelsonic]

The first Advanced feature listed above is Markdown support.
Out of the box Quill does not support Markdown.
I looked at https://github.com/patleeman/quill-markdown-shortcuts
but at the time of writing, the demo https://patleeman.github.io/quill-markdown-shortcuts fails:

While searching for "Quill Markdown support" I came across this post
"Why We Moved From Quill to Slate":
https://medium.com/the-lead/why-we-moved-from-quill-to-slate-94f42aa54fec

The Why? https://github.com/ianstormtaylor/slate#why
and Principals https://github.com/ianstormtaylor/slate#principles
of Slate all make sense to me. First-class Plugins especially.

But then when we look at the Slate examples they are all React:

• https://github.com/ianstormtaylor/slate/blob/master/site/examples/plaintext.js
• https://github.com/ianstormtaylor/slate/blob/master/site/examples/richtext.js

Obviously this is because Fb has succeeded in pushing React to most devs despite its objective inferiority from a technical and UX perspective.

Slate looks promising, but it's still very much "beta". 💭

[nelsonic]

I didn't "give up" on Quill before I made a decent attempt to implement/understand it:

I still think we can use Quill and especially the Delta OT format.
But we need to figure out how we can use and extend it for our needs.

[kepta]

I wanted to surface https://github.com/bangle-io/bangle.dev, a library which I have been working on recently. It supports majority of your requirements and is built on top of Prosemirror which makes it very easy to extend. And ya it support OT collaboration.

[nelsonic]

@kepta apologies for not responding at the time. 🤦
I saw the notification, gave it a 👍 "reaction"
and then it got lost in the ether.
Been reading through your docs/code. Superb work. 😍
Though given the number of ⭐ on your various projects,
you don't need me to tell you. 😜 plenty of validation. 🎉

[nelsonic]

For ultra-basic wysiwyg this could be an <option>:
https://tailwindcomponents.com/component/wysiwyg

https://tailwindcomponents.com/component/wysiwyg/landing

[nelsonic]

Used my alone-time on the train 🚂 today to sketch the "Enhance" Menu for the App (AKA WYSIWYG Editor):
https://www.figma.com/file/WrpkKGJNYZbeCzMRDVtvQLbC/dwyl-app?type=design&node-id=1554-4180&mode=design

Feedback is very much encouraged/welcome. 💬 🙏

[iteles]

I feel very much like the Actions items you have here are the really important ones that should be built out and tested first.

tl;dr

Tooltips

Yes! Do these 'play' once, on initial load?
Nothing to add here except at a later date if needed, we can also add a 'replay initial walkthrough' button in the Settings/Account menus.

Basic Enhancement

It's kind of fascinating because I think it speaks to the different use cases for this app.
My personal main usage is to capture very quick thought ideas and tasks which do not require much text formatting, but I know your main usage would differ to mine @nelsonic, which is why building this thing requires a lot of design thought!

Of these, the only one I would see as 'important' for my use case(s) is the hyperlink functionality as I have noted/requested in dwyl/mvp#141
I would argue however, that the first iteration of this functionality should be automatic rather than explicit - Any URL (denoted by beginning with http://) should automatically hyperlink. This is a case of enhancing the experience and speeding things up for people.

Should there be a user feedback request to then make this explicit or actually allow hyperlinking of words as you would need when writing a document/full note/blog post/draft of an email/whatever long form text, then we build that out.

Actions

This is where the magic happens!

Picture addition, time estimates, deadlines and tasks are all great, though obviously the task item will need more definition to build out the functionality (does this turn the whole item into a task? Does it create subtasks? How does this appear on the list interface? Definitely all topics for a different - and existing - issue).

However, the actual interface here feels too small - I can't quite picture people with big thumbs actually hitting the icon they truly want.
Easily solved in the first instance by increasing height of the icons and giving them some left and right margin.

I would also consider having them in a separate menu/area altogether to the 'basic enhancement' features and differentiating them with some styling, but this isn't relevant if we start building these actions out first as opposed to the basic enhancement features. I can take a stab at this if I get some help from you @nelsonic in prioritising tasks.

When each of these has a linked issue, I can also comment on the functionality (like I would like to be able to take a picture from directly inside the app as a post-MVP feature for example).

[nelsonic]

@iteles all good insights/questions as always. ❤️

The goal of building our App in an API-driven way means that this layout/flow is just one interpretation of what we can do to help people interact with their data. Having all of the functionality via the API means anyone can build the interface they want to interact with their data. If someone wants to use the Terminal to capture items and start|stop their timers, they can! If they want to use Siri or XYZ Assistant, they can.

I've studied interface design enough to know that the flow I'm proposing will work well.
There are no "I'm stuck" moments, just a systematic contextual product tour via Tool Tips. By having a settings.json that keeps track of where the person is on their journey we know if they have seen the "intro" to the Actions Menu or not. If they are totally new to the App, then we will guide them through in a systematic way.
If at any point they want to reply the Tool Tips they can simply select "Feature Tour" from the Main Menu:
https://www.figma.com/file/WrpkKGJNYZbeCzMRDVtvQLbC/dwyl-app?type=design&node-id=1516-4909&mode=design
But as noted in: https://news.ycombinator.com/item?id=36846520 ( dwyl/flutter-date-time-tutorial#1 (comment) ) we want our interface to be immediately intuitive.

Please feel free to open issues for the specific features you would like to see. 🙏