ContentState.createEntity Documentation Error

[hnordt]

Hello.

In ContentState.createEntity docs we have:

It says "Returns new ContentState record updated to include the newly created DraftEntity record in it's EntityMap.".

Now in ContentState.createEntity source code, we have:

  createEntity(
    type: DraftEntityType,
    mutability: DraftEntityMutability,
    data?: Object,
  ): ContentState {
    // TODO: update this when we fully remove DraftEntity
    DraftEntity.__create(
      type,
      mutability,
      data,
    );
    return this;
  }

Either the docs needs to be fixed or ContentState.createEntity should apply the created entity (atm it's just creating).

Actually ContentState.createEntity behavior is a bit strange, e.g.:

      const contentState = editorState.getCurrentContent();
      const selectionState = editorState.getSelection();
      const contentStateWithEntity = contentState.createEntity(
        "LINK",
        "MUTABLE",
        { url }
      );
      const entityKey = contentStateWithEntity.getLastCreatedEntityKey();
      const contentStateWithLink = Modifier.applyEntity(
        // contentState doesn't has the created entity, but still applied the created
        // entity successfully
        // I think it happens because the entity is owned by the editorState currently
        // Reading the docs, I expected that only contentStateWithEntity
        // would be able to apply the created entity
        contentState,
        selectionState,
        entityKey
      );
      const editorStateWithLink = EditorState.push(
        editorState,
        contentStateWithLink,
        "apply-entity"
      );

[mmmoussa]

An instance of ContentState can contain an entity in its entity map without the entity being applied to any text. When using a new entity you have to create it and then apply it. The docs are describing this correctly. ContentState.createEntity should not apply the created entity.

With regard to your example about the strange behaviour, the reason you can use contentState is because your comment that it doesn't have the created entity is incorrect. contentState.createEntity returns the same instance of the ContentState, which means that both contentState and contentStateWithEntity are the same.

[hnordt]

@mmmoussa thank you, I understand now. The source of my misunderstanding was the "Returns new ContentState" part. I fixed it: #1150

Btw, as ContentState.createEntity creates a new entity inside the current instance and returns it, it looks a bit like a mutable operation, no?

      const contentState = editorState.getCurrentContent();
      // As Draft.js uses an immutable model, I expect that only contentStateWithEntity
      // contains the newly created entity
      const contentStateWithEntity = contentState.createEntity(
        "LINK",
        "MUTABLE",
        { url }
      );

The docs provide this example, it looks a bit explicit that only the second variable constant contains the new entity.