Troubleshooting

Expected editor behavior

Pressing return on an empty list item should un-indent it until it is not nested, and then remove it.
Pressing return at the end of a block should create an empty unstyled block.
Atomic blocks (images, embeds, hr) are always preceded and followed by a block (empty if no other block is present). See facebook/draft-js#327.
Blocks starting with "- ", "* ", "1. " are automatically converted to list items.
Pasting content with block nesting above the configured maximum should reduce the depth up to the maximum.

Upgrade considerations

Draft.js

Draft.js is relatively stable but also historically slow to address bugs. Draftail sometimes has to override behavior in a way that may be problematic if the Draft.js API is updated.

When upgrading to a more recent Draft.js version, always review the full CHANGELOG as well as individual changes.

Here are specific parts of the code that should always be reviewed before upgrading, and may need to be updated, or that we may be able to remove:

In Firefox, the dom.event.clipboardevents.enabled setting must be turned on, otherwise the editor will crash on copy-paste. This could be off in Iceweasel. See wagtail/wagtail#4346.

Known issues

Please have a look at Draft.js Known Issues, as well as Draftail’s list of Known issues with Draftail, Draft.js, contenteditable, and other dependencies (springload/draftail#138).