springload / draftail

📝🍸 A configurable rich text editor built with Draft.js

Draftail

📝🍸 A configurable rich text editor built with Draft.js. Check out our demos!

Features

Draftail aims for a mouse-free, keyboard-centric experience. Here are important features worth highlighting:

• Support for keyboard shortcuts. Lots of them!
• Paste from Word. Or any other editor. It just works.
• Autolists – start a line with - , * , 1. to create a list item.
• Shortcuts for heading levels ##, code blocks ```, text formats **, and more.
• Undo / redo – until the end of times.
• Common text types: headings, paragraphs, quotes, lists.
• Common text styles: Bold, italic, and many more.
• API to build custom controls for links, images, and more.
• Compatibility with the draft-js-plugins ecosystem to build more advanced extensions.

This project adheres to Semantic Versioning, and measures performance and code coverage. We also try to follow accessibility best practices (tested with aXe) – please get in touch if you can help us do better in this area.

Documentation

• Getting started
• API reference
• User guide
• Getting started with extensions

Contributing

See anything you like in here? Anything missing? We welcome all support, whether on bug reports, feature requests, code, design, reviews, tests, documentation, and more. Please have a look at our contribution guidelines.

If you just want to set up the project on your own computer, the contribution guidelines also contain all of the setup commands.

Credits

Draftail is made possible by the work of Springload. View the full list of contributors. MIT licensed. The draftail.org documentation and demos are powered by Netlify.

draftail's Issues

Add keyboard shortcuts in `title` attribute of all buttons

Use the following code to display the right shortcut.

const { isOptionKeyCommand, hasCommandModifier } = KeyBindingUtil;
const isOSX = isOptionKeyCommand({ altKey: 'test' }) === 'test';
const COMMAND_MODIFIER_CHAR = isOSX ? '\u2318' : 'Ctrl';

Explore integration with draft-js-plugins

https://www.draft-js-plugins.com/

... so we get plenty of useful, cool features "for free".

Add editor UI with Medium-style controls

That is:

• No toolbar at the top of the editor. Instead,
• Controls on the sides of the editor to add block-level formats and content blocks.
• Inline "hover" toolbar to add inline formats and content entities.

Image/Embed cannot start or end the editor content

inserts / can't remove empty line without deleting it

Undo is unavailable until you click back in the field

Steps to reproduce:

• Select a piece of text
• Click the Bold button
• Press cmd+z to undo. Observe nothing happen.
• Click into the field.
• Press cmd+z again. Observe this actually undo.

Rely on lodash 4 as peerDependency

... so we can start using _.assign, _.omit, _.find, etc.

with babel-plugin-lodash.

Implement custom inline styles

At the moment Draftail does not support defining custom styles. This shouldn't be particularly hard to implement, it just hasn't been necessary for our use case.

See https://draftjs.org/docs/advanced-topics-inline-styles.html when we get to this.

Add undo/redo buttons

As an optional extra control, using EditorState.undo / EditorState.redo (see https://github.com/draft-js-plugins/draft-js-plugins/tree/master/draft-js-undo-plugin).

We may want to refactor how custom controls are defined first, so we don't always add options on top of options and clutter the editor API / config.

UI audit

Below is a list of improvements that could be made to improve usability:

Small improvements:

• Add placeholder "Type to get started" / "Start writing" (people have trouble knowing where to type).
• [ ] Make text input area look more like a text area. #96
• Sticky editor controls
• [ ] naming of labels (non-dev people don't know what H3, BR etc mean.) #80
• [ ] Bigger editor controls and more descriptive icons. #80

Bigger improvements:

• [ ] Show hidden characters (more like indesign) so you can see if you have extra p tags etc #95
• [ ] More obvious grouping controls into "things of can do to one word" vs "things you can do to a block of words" See #80.
• [ ] Image / embed treatment – See #92, #93.
• [ ] Add undo / redo – See #79.
• [ ] Add word/character count and reading time – See #94.
• [ ] Refresh editor design See #64.

Add example content with all of the following

• Several different list types ie.
  • bulleted,
  • numbered,
  • action,
• Need to be able to include document links
  • that will have pdf icon
  • and probably file size (auto generated).
• May need location link that could have a location pin icon (needs to be inline with paragraph text most likely).
• All the generic text elements like
  • headings,
  • paragraphs,
  • bold,
  • italics,
  • links.
• Terms and conditions type thing…dunno if that means a muted text choice AND a small text option. or just a custom paragraph type for terms which would have both those styles attached.
• Hr element probably needed all the time.

Test coverage reports & PR integration

With Coveralls https://coveralls.io/github/springload/draftail/ & https://github.com/nickmerwin/node-coveralls

Selection range disappear upon using inline styles

The selection disappear but is still functional when using inline style buttons.

Others buttons might be affected as well but it's hard to tell since clicking on them jumps to the top of the page (see #2 and #3).

Add to awesome-draft-js

Once the demo/documentation is in good enough shape.

https://github.com/nikgraf/awesome-draft-js

Pressing shift + tab on nested list items does not always produce the same result

Initially observed to be specific to:

• ordered-list-item
• empty
• shift + tab

If the block has text it works. Pressing return instead of shift + tab works.

Automated cross-browser tests

With SauceLabs or Browserstack.

At least screenshots of multiple text editors with various features enabled.

An empty editor state should serialize to null, not an empty object

Currently, when serializing an empty editor state, it will return an empty object, which is basically an invalid content state. Therefore, the editor should return null which clearly state the lack of content.

Note: Corresponding changes will need to happen in springload/draftjs_exporter and springload/wagtaildraftail.

HR elements are buggy

Caret position when deleting them is a bit strange

Document editor API in README and demo

• Available props and their impact
• Options shape
• Other API
• As good as http://megadraft.io/#/?_k=dw4baj
• As good as http://bitwiser.in/medium-draft/
• Also document migration recommendations
• Use https://github.com/SamyPesse/draft-js-prism

Make user guide / usage video

... to showcase capabilities and highlight shortcuts / methodology.

imageFormats should be defined within the WAGTAIL_IMAGE entity

Currently, an imageFormats option is required, regardless of an image entity being defined in the mediaControls (e.g. {'entity': 'WAGTAIL_IMAGE', 'label': 'Image', 'icon': 'image'}).

Since those are configuration for a specific entity, that should be passed along to that entity.

Automated integration tests

With browser automation. Simulate inserting text & verifying the output JSON.

Make most setup options optional

• With good defaults. Use lodash's related helper functions.
• Also make name and value optional.

Feedback on editor UX

The UI and UX of the editor (see demo) as they stand are directly from initial prototypes, which could be refined a bit now that the editor's feature set is better understood. There will be ongoing work on the editor, so the point for now is to make it "good enough" that we don't feel bad about other people to start using it.

Here is a list of specific things to review:

• Embed block behaviour (see below)
• Image block behaviour (see below)
• Undo/redo buttons – or the lack thereof. The default editor in Wagtail has them. Are they worth adding, or should we expect people to know the keyboard shortcuts?

Embed block behaviour

... or the lack thereof – how the block for embeds has two open/closed states even though there is nothing to act upon in the "open" state. We also do not have a way to edit an existing embed at the moment – instead, the user has to remove it, then add a new one. Would that be worth adding? How?

Image block behaviour

This is displayed within the editor's UI. There are two states as with the embed block. I'm not sure whether having explicit "Save" and "Cancel" actions in here is good – it dilutes the overall understanding of whether the editor's content is saved or not:

• Within Wagtail, nothing is actually saved until you hit "Save draft" at the bottom of the page
• Outside of Wagtail, there would either be a save mechanism for the whole content as well, or everything would be auto-saved on every change.

Edit: reading time? https://github.com/michael-lynch/reading-time

Test editor performance

Let's aim for 10 editors running with decent perf.

Make CSS available as part of package

... so basic editor & Draft.js styles are contained within it.

CSS stacking context can get complicated

At the moment, here are the layers we have in the editor, from "bottom" to top:

• Editor content, where you type.
• Tooltips
• Disabled editor overlay
• Active block (auto-closes tooltips)
• Toolbar (sticky)
• Dialogs that are opened from any of those.

This is starting to be a lot of stacking. To make matters even more complex,

• Other third-party modals should be able to appear above all of those.
• Should people want to use the editor inside of a modal, this should be supported too.

@samanthaksanders @laurarbunea do you have insights on how to keep this manageable? Just in terms of CSS, this is what I've done so far:

// All the z-index values are defined at the top as increments of one over the previous.
$editor-z-index: 1;
$tooltip-z-index: $editor-z-index + 1;
$overlay-z-index: $tooltip-z-index + 1;
$activeblock-z-index: $overlay-z-index + 1;
$toolbar-z-index: $activeblock-z-index + 1;

// [...]
// Those variables are referenced in the code where z-index is set.

Generally I have trouble with z-index, and how to manage sizes of this stack. Tips welcome!

Use onMousedown on toolbar buttons instead of onClick

To preserve focus within the editor UI when toggling blocks / styles.

Improve appearance of controls in the toolbar, with grouping

This is a subset of #75, with the goal of reaching feature parity with the current Wagtail editor.

Here is what we want:

Tasks:

• Button styles
• Button grouping / segmented buttons
• More obvious grouping controls into "things of can do to one word" vs "things you can do to a block of words"
• Bigger editor controls and more descriptive icons.
• Naming of labels (non-dev people don't know what H3, BR etc mean.)

The button grouping is harder to solve than it might look – this target screenshot is what the most common editor will look like, but people may also have way less (or way more) of a given type of control, and we still need to ensure the toolbar looks good no matter how much screen real estate is available.

What is the purpose of media/dialog controls?

Media and Dialog controls comes from 2 different sets in the options but their implementations are identical. What is the difference then?

Provide default behavior for entity strategy

See also springload/wagtaildraftail#6. This is the behavior of all strategies I've used so far (check entity type only, not text patterns).

Some boilerplate:

const getEntityStrategy = (entityType) => {
    return (contentBlock, callback) => {
        contentBlock.findEntityRanges((character) => {
            const entityKey = character.getEntity();
            return (
                entityKey !== null &&
                Entity.get(entityKey).getType() === entityType
            );
        }, callback);
    };
};

Shortcuts allow formatting now allowed in INLINE_STYLES

Given an editor field initialised with no inline styles, they won't be available as buttons but will still work as shortcuts.

Fix code block rendering (double wrap)

See facebookarchive/draft-js#406.

To be customised in the block render map – probably code wrapped in pre.

Add "linkify" feature

There are two scenarios here.

Pasting a URL on selected text adds a link to the given URL on the selected text

Wordpress / Dropbox Paper do this and it feels very pleasant to use. See https://github.com/ianstormtaylor/slate-paste-linkify/blob/master/lib/index.js

1. Highlight some text
2. Paste a URL
3. Auto-links it

Pasting / typing a URL in text converts it into a link

This is the usual "linkify". Lots of editors do this.

Good copy/pasting support

Expected behavior

• Flattens lists that are too nested.
• Strip all blocks which aren't allowed in the current field – One needs to be careful when removing default blocks from the block map, and/or aliasing elements. If an element is missing, the editor will crash.
• IMAGE entities are created, but come with an unstyled block instead of atomic. This should be normalised.
• There is no built-in way to configure whether IMAGE and LINK are available in the first place. They should be removed if necessary (both from the block, and the entity map).
• There is no way to customise which styles are available. Styles should be removed if necessary.

Unexpected behavior

• Drops the style of the first block in the clipboard
• Concatenates multiple paragraphs into one block (whitespace is missing)
• Drops whitespace in front of text node right after inline entity
• [ ] Be smart about pasting of uppercase text? IS SHOUTING ALLOWED? WHAT IF YOU COPY/PASTE AN H2?

Example big content to copy paste:

• http://kiwibank.co.nz/personal-banking/investments/term-deposits/

• http://kiwibank.co.nz/personal-banking/investments/notice-saver/

• http://kiwibank.co.nz/personal-banking/kiwisaver/what-is-kiwisaver/

• https://www.kiwibank.co.nz/about-us/legal-docs/#kiwibanks-quarterly-disclosure-statements-and-the-annual-reports-of-kiwibank-and-its-related-entities - The content inside an accordion block will be a rich text area so need to be able to probably build this content in a rich text field…i.e.. heading, doc link, heading, doc link, terms and conditions etc.

• https://www.kiwibank.co.nz/personal-banking/credit-cards/low-interest-cards/low-rate-mastercard/ - this page has an example of the inline rates that get loaded from the current api

• https://www.kiwibank.co.nz/about-us/security/common-banking-frauds-and-scams/card-fraud/

• https://www.kiwibank.co.nz/personal-banking/home-loans/getting-a-home-loan/first-home-buyers/should-you-buy/ - ignore custom things like the grid with two columns of text. look at the big blocks of text that will most likely be able to be build with one rich text area :)

• https://www.kiwibank.co.nz/personal-banking/home-loans/getting-a-home-loan/first-home-buyers/finding-a-house/

• The first home buyers guide inside the getting a home loan section has some pages that have a lot of content if you need to copy paste big blocks for testing.

• Try copy/pasting from Word.

• Try copy/pasting from Pages.

Editor styling

Hi Thibaud,

We are trialling Draftrail on a client website and there are a few styling issues in the admin section (when creating the content).

• Links are not getting styled (they look exactly the same as the paragraph copy) - error in the JS may be causing this.
• Heading styles could be bold to make the content more 'scanable'
• T&Cs are not styled in the editor (look exactly the same as the paragraph copy)

Chat to me if you need anything else :)

Only render the toolbar when editor is focused

Do not hardcode HR button

Ideally, this would be up to the user to include HR or not (like block types and inline styles). Currently it's hardcoded.

Open-source Wagtail integration for the editor

... based on wagtaildemo.

Add more Markdown-style shortcuts to format content

I love draftail's markdown-style shortcut for starting lists with " - ". Would it be possible to do something similar for code formatting, i.e. start a new block with "```" or inline with "`"?

Change API of decorators to be compatible with latest Draft.js version

Decorators need to access contentState so they can query entities from it, instead of the Entity global.

Editor links should open the tooltip when clicking their icon

Document what ES6 polyfill is necessary

... and make sure the Draftail examples and our projects are using them.

See https://facebook.github.io/draft-js/docs/advanced-topics-issues-and-pitfalls.html#polyfills

Cancel event default on all buttons

So there are no buttons taking you back to the top of the page.

React component tests

• With Enzyme
• Using snapshot testing
• Get to 100% test coverage

Extract serialisation API

... so serialisation method is implementation-specific rather than built-in.

• Demonstrate multiple scenarios via examples

Browser support definition

Rename entity config attributes

• component should be decorator (it's the component for the decorator)
• control should be source (control is way too vague, source is vague too but still more descriptive)

Provide "paste as plain text" or "clear formatting" features

This is a fairly common feature of text editors, and also fairly easy to implement with Draft.js

Define and document styling/theming primitives for the editor

It is important to allow this editor to be themed, with ability to override the styles but also configure the UI in JS as required. This will support work like springload/wagtaildraftail#43.

Cannot remove link

Clicking on a link and then Remove has no effect.

Uncaught TypeError: Cannot read property 'getSelectionEntity' of undefined

at Object.getSelectedEntitySelection (http://localhost:8111/static/js/wagtailadmin.js:51528:35) at DraftailEditor.onRemoveEntity (http://localhost:8111/static/js/wagtailadmin.js:28267:62) at Object.ReactErrorUtils.invokeGuardedCallback (http://localhost:8111/static/js/wagtailadmin.js:6349:17) at executeDispatch (http://localhost:8111/static/js/wagtailadmin.js:6134:22) at Object.executeDispatchesInOrder (http://localhost:8111/static/js/wagtailadmin.js:6157:6) at executeDispatchesAndRelease (http://localhost:8111/static/js/wagtailadmin.js:5581:23) at executeDispatchesAndReleaseTopLevel (http://localhost:8111/static/js/wagtailadmin.js:5592:11) at Array.forEach (native) at forEachAccumulated (http://localhost:8111/static/js/wagtailadmin.js:6448:10) at Object.processEventQueue (http://localhost:8111/static/js/wagtailadmin.js:5768:8)