search

dwyl / app

Clear your mind. Organise your life. Ignore distractions. Focus on what matters.
http://dwyl.github.io/app/
147 stars 22 forks source link

[EPIC] WYSIWYG/Rich Text Editor #275

Open nelsonic opened 4 years ago

nelsonic commented 4 years ago

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).

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:

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: image 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: https://github.com/dwyl/learn-flutter/issues/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:

image

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 commented 4 years ago

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 commented 4 years ago

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

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 commented 4 years ago

Checklist on localhost:

quill-checklist
nelsonic commented 4 years ago

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 commented 4 years ago

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:

quill-markdown-shortcuts-fail

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:

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 commented 4 years ago

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

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 commented 3 years ago

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 commented 2 years ago

@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 commented 1 year ago

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

image

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

nelsonic commented 1 year ago

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

image image image image

Feedback is very much encouraged/welcome. 💬 🙏

iteles commented 1 year ago

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 https://github.com/dwyl/mvp/issues/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 commented 1 year ago

@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 ( https://github.com/dwyl/flutter-date-time-tutorial/issues/1#issuecomment-1650027373 ) we want our interface to be immediately intuitive.

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