Draft.js API improvements in 0.10.0 and 0.11.0

[flarnie]

What: The API for managing entities will be moved from the global Entity module into contentState, with a deprecation warning in v0.10.0 and a full breaking change in v0.11.0.

Why:

• currently changing or adding entities won't trigger a re-render. This is a big pain!
• the use of a non-Immutable storage for entities doesn't fit well with the rest of the Draft architecture
• moves Entity storage out of global module; this just makes more sense as an API, rather than having it globally available.
  Other maintainers - feel free to add detail and say this more eloquently.

Will 0.10.0 include breaking changes?
Nope! When you update to v0.10.0, you should start seeing warnings in the console when the old Entity module API is used. The new API, using contentState will be supported, and you can migrate to the new API incrementally.

We will put out documentation about how to update all use cases when releasing 0.10.0.

Once you are fully migrated to the new API, you can update to 0.11.0, which will include the fully breaking change and will also include the benefits of the new API.

What's taking so long???

• Since we are improving the API in a breaking way, we are doing extra testing and preparing documentation to make the 0.10.0 and 0.11.0 releases run smoothly.
• We are a tiny team with other projects, and so thanks for everyone's patience! We are actively working on catching up, and there are discussions ongoing for how to improve the state of this project. See Draft.js Roadmap Update #835.

[flarnie]

Just an update - we released 0.10.0, including the deprecation of DraftEntity and the new API for managing DraftEntity records.

Next steps:

• Publish v0.11.0@next for beta testing
• Publish any intermediate bug fixes at v0.10.1
• Internal testing of v0.11.0 on Facebook's wide range of use cases
• Release v0.11.0 and continue doing regular releases in the future

[tobiasandersen]

Awesome! Great job @flarnie 🥇

[sdtsui]

Nice! Looking forward to seeing the changes. 🎉

[asprouse]

@flarnie Any update on publishing 0.11@next? 0.10's pseudo-immutable behavior is causing bugs/confusion (#1047)

[SmilinBrian]

It is unclear to me how import from any source other than "raw" ContentState or plain-vanilla HTML is best accomplished once Entities cannot be created without a ContentState instance.

That is, our use case involves storing Editor results in HTML after editing with Entities which correspond to various XHTML tags within the stored data. We are using HubSpot/draft-convert, which offers nice "hooks" to analyze the HTML/DOM as it is being parsed, and we create Entities for various parts of the document at parsing time. Like the built-in convertFromHTML() importer the end result is ContentBlocks and an EntityMap, and the next step is ContentState.createFromBlockArray(contentBlocks, entityMap).

If Entities cannot be created without a ContentState instance, is the suggested import process now to create an empty ContentState, then add Blocks and Entities to it as they are parsed?

Or asked a different way: Is there any non-deprecated Entity creation support planned for import methods other than the built-in ones?

As implied in HubSpot/draft-convert#38, our usage of draft-convert already generates "DraftEntity.create will be deprecated soon!" warnings in 0.10, and it sounds like it will stop working in 0.11.

[deep-c]

Awesome work! When is a release of v0.11.0 likely :) ?

[fraziermork]

If I go back to a previous state via undo, will the entities also fall back to the state they were in at that point?

[benbriggs]

Since the convertFromHTML in draft-convert was originally based on Draft's built-in one, my strategy to solve the issue there should be usable within the built-in module as well. Similar to what was suggested above I create an empty ContentState at the beginning and pass down functions to generate/manipulate entities while parsing nodes. See HubSpot/draft-convert#82

Edit: After looking at the alpha branch it looks like this use has already been solved by returning entity map along with the array of content blocks

[MadebyAe]

About breaking changes

@flarnie First of all thanks for drive Draft JS! — I have a question related to the migrating 0.9x to 0.10.x seems editState has a kind of mutation onChange I can see the previous editState also change.

Happy to look into this.

[flarnie]

Hi @MadebyAe - I think I would need more details to understand your question and why this is a problem. Could you open an issue and describe how you've run into this bug?

[BrodaNoel]

Why breaking change on 0.11.x, instead of 1.x.x?

[mrkev]

I'll be giving this a shot now since @flarnie has since left the project. Evidently, this wont ship on v0.11.0, since that's already shipped with both APIs.

The old API will be removed on version v0.12.0.

@BrodaNoel pre version 1, minor versions can be breaking too.

[mrkev]

Closing in favour of #2650, since the DraftEntity API will be changed in v0.12.0 instead. Any follow-ups should be brought up there.