Core Data: Add support for entity edits and undo history. (#16867)

* Core Data: Add support for entity edits and undo history.

* Core Data: Update docs.

docs/designers-developers/developers/data/data-core.md

@@ -71,6 +71,22 @@ _Returns_
 
 -   `?Array`: An array of autosaves for the post, or undefined if there is none.
 
+<a name="getCurrentUndoOffset" href="#getCurrentUndoOffset">#</a> **getCurrentUndoOffset**
+
+Returns the current undo offset for the
+entity records edits history. The offset
+represents how many items from the end
+of the history stack we are at. 0 is the
+last edit, -1 is the second last, and so on.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+
+_Returns_
+
+-   `number`: The current undo offset.
+
 <a name="getCurrentUser" href="#getCurrentUser">#</a> **getCurrentUser**
 
 Returns the current user.
@@ -83,6 +99,21 @@ _Returns_
 
 -   `Object`: Current user object.
 
+<a name="getEditedEntityRecord" href="#getEditedEntityRecord">#</a> **getEditedEntityRecord**
+
+Returns the specified entity record, merged with its edits.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordId_ `number`: Record ID.
+
+_Returns_
+
+-   `?Object`: The entity record, merged with its edits.
+
 <a name="getEmbedPreview" href="#getEmbedPreview">#</a> **getEmbedPreview**
 
 Returns the embed preview for the given URL.
@@ -138,6 +169,40 @@ _Returns_
 
 -   `?Object`: Record.
 
+<a name="getEntityRecordEdits" href="#getEntityRecordEdits">#</a> **getEntityRecordEdits**
+
+Returns the specified entity record's edits.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordId_ `number`: Record ID.
+
+_Returns_
+
+-   `?Object`: The entity record's edits.
+
+<a name="getEntityRecordNonTransientEdits" href="#getEntityRecordNonTransientEdits">#</a> **getEntityRecordNonTransientEdits**
+
+Returns the specified entity record's non transient edits.
+
+Transient edits don't create an undo level, and
+are not considered for change detection.
+They are defined in the entity's config.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordId_ `number`: Record ID.
+
+_Returns_
+
+-   `?Object`: The entity record's non transient edits.
+
 <a name="getEntityRecords" href="#getEntityRecords">#</a> **getEntityRecords**
 
 Returns the Entity's records.
@@ -153,6 +218,34 @@ _Returns_
 
 -   `Array`: Records.
 
+<a name="getLastEntitySaveError" href="#getLastEntitySaveError">#</a> **getLastEntitySaveError**
+
+Returns the specified entity record's last save error.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordId_ `number`: Record ID.
+
+_Returns_
+
+-   `?Object`: The entity record's save error.
+
+<a name="getRedoEdit" href="#getRedoEdit">#</a> **getRedoEdit**
+
+Returns the next edit from the current undo offset
+for the entity records edits history, if any.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+
+_Returns_
+
+-   `?Object`: The edit.
+
 <a name="getThemeSupports" href="#getThemeSupports">#</a> **getThemeSupports**
 
 Return theme supports data in the index.
@@ -165,6 +258,19 @@ _Returns_
 
 -   `*`: Index data.
 
+<a name="getUndoEdit" href="#getUndoEdit">#</a> **getUndoEdit**
+
+Returns the previous edit from the current undo offset
+for the entity records edits history, if any.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+
+_Returns_
+
+-   `?Object`: The edit.
+
 <a name="getUserQueryResults" href="#getUserQueryResults">#</a> **getUserQueryResults**
 
 Returns all the users returned by a query ID.
@@ -178,6 +284,22 @@ _Returns_
 
 -   `Array`: Users list.
 
+<a name="hasEditsForEntityRecord" href="#hasEditsForEntityRecord">#</a> **hasEditsForEntityRecord**
+
+Returns true if the specified entity record has edits,
+and false otherwise.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordId_ `number`: Record ID.
+
+_Returns_
+
+-   `boolean`: Whether the entity record has edits or not.
+
 <a name="hasFetchedAutosaves" href="#hasFetchedAutosaves">#</a> **hasFetchedAutosaves**
 
 Returns true if the REST request for autosaves has completed.
@@ -192,6 +314,32 @@ _Returns_
 
 -   `boolean`: True if the REST request was completed. False otherwise.
 
+<a name="hasRedo" href="#hasRedo">#</a> **hasRedo**
+
+Returns true if there is a next edit from the current undo offset
+for the entity records edits history, and false otherwise.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+
+_Returns_
+
+-   `boolean`: Whether there is a next edit or not.
+
+<a name="hasUndo" href="#hasUndo">#</a> **hasUndo**
+
+Returns true if there is a previous edit from the current undo offset
+for the entity records edits history, and false otherwise.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+
+_Returns_
+
+-   `boolean`: Whether there is a previous edit or not.
+
 <a name="hasUploadPermissions" href="#hasUploadPermissions">#</a> **hasUploadPermissions**
 
 > **Deprecated** since 5.0. Callers should use the more generic `canUser()` selector instead of `hasUploadPermissions()`, e.g. `canUser( 'create', 'media' )`.
@@ -242,6 +390,21 @@ _Returns_
 
 -   `boolean`: Whether a request is in progress for an embed preview.
 
+<a name="isSavingEntityRecord" href="#isSavingEntityRecord">#</a> **isSavingEntityRecord**
+
+Returns true if the specified entity record is saving, and false otherwise.
+
+_Parameters_
+
+-   _state_ `Object`: State tree.
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordId_ `number`: Record ID.
+
+_Returns_
+
+-   `?Object`: Whether the entity record is saving or not.
+
 
 <!-- END TOKEN(Autogenerated selectors) -->
 
@@ -261,6 +424,22 @@ _Returns_
 
 -   `Object`: Action object.
 
+<a name="editEntityRecord" href="#editEntityRecord">#</a> **editEntityRecord**
+
+Returns an action object that triggers an
+edit to an entity record.
+
+_Parameters_
+
+-   _kind_ `string`: Kind of the edited entity record.
+-   _name_ `string`: Name of the edited entity record.
+-   _recordId_ `number`: Record ID of the edited entity record.
+-   _edits_ `Object`: The edits.
+
+_Returns_
+
+-   `Object`: Action object.
+
 <a name="receiveAutosaves" href="#receiveAutosaves">#</a> **receiveAutosaves**
 
 Returns an action object used in signalling that the autosaves for a
@@ -368,6 +547,21 @@ _Returns_
 
 -   `Object`: Action object.
 
+<a name="redo" href="#redo">#</a> **redo**
+
+Action triggered to redo the last undoed
+edit to an entity record, if any.
+
+<a name="saveEditedEntityRecord" href="#saveEditedEntityRecord">#</a> **saveEditedEntityRecord**
+
+Action triggered to save an entity record's edits.
+
+_Parameters_
+
+-   _kind_ `string`: Kind of the entity.
+-   _name_ `string`: Name of the entity.
+-   _recordId_ `Object`: ID of the record.
+
 <a name="saveEntityRecord" href="#saveEntityRecord">#</a> **saveEntityRecord**
 
 Action triggered to save an entity record.
@@ -378,8 +572,9 @@ _Parameters_
 -   _name_ `string`: Name of the received entity.
 -   _record_ `Object`: Record to be saved.
 
-_Returns_
+<a name="undo" href="#undo">#</a> **undo**
 
--   `Object`: Updated record.
+Action triggered to undo the last edit to
+an entity record, if any.
 
 <!-- END TOKEN(Autogenerated actions) -->