WordPress · adamziel · Aug 8, 2022 · Apr 4, 2022 · May 9, 2022 · May 12, 2022
@@ -764,6 +764,57 @@ In the above example, when `PageTitleDisplay` is rendered into an
 application, the page and the resolution details will be retrieved from
 the store state using `getEntityRecord()`, or resolved if missing.
 
+```js
+import { useEntityRecord } from '@wordpress/core-data';
+
+function PageRenameForm( { id } ) {
+	const page = useEntityRecord( 'postType', 'page', id );
+	const [ title, setTitle ] = useState( () => page.record.title.rendered );
 /** 
  * Returns true if, given the currently dispatching action and the previously 
  * dispatched action, the two actions are updating the same block attribute, or 
  * false otherwise. 
  * 
  * @param {Object} action     Currently dispatching action. 
  * @param {Object} lastAction Previously dispatched action. 
  * 
  * @return {boolean} Whether actions are updating the same block attribute. 
  */ 
 export function isUpdatingSameBlockAttribute( action, lastAction ) { 
 	return ( 
 		action.type === 'UPDATE_BLOCK_ATTRIBUTES' && 
 		lastAction !== undefined && 
 		lastAction.type === 'UPDATE_BLOCK_ATTRIBUTES' && 
 		isEqual( action.clientIds, lastAction.clientIds ) && 
 		hasSameKeys( action.attributes, lastAction.attributes ) 
 	); 
 } 
 /** 
  * Higher-order reducer intended to augment the blocks reducer, assigning an 
  * `isPersistentChange` property value corresponding to whether a change in 
  * state can be considered as persistent. All changes are considered persistent 
  * except when updating the same block attribute as in the previous action. 
  * 
  * @param {Function} reducer Original reducer function. 
  * 
  * @return {Function} Enhanced reducer function. 
  */ 
 function withPersistentBlockChange( reducer ) { 
 	let lastAction; 
 	let markNextChangeAsNotPersistent = false; 
 	return ( state, action ) => { 
 		let nextState = reducer( state, action ); 
 		const isExplicitPersistentChange = 
 			action.type === 'MARK_LAST_CHANGE_AS_PERSISTENT' || 
 			markNextChangeAsNotPersistent; 
 		// Defer to previous state value (or default) unless changing or 
 		// explicitly marking as persistent. 
 		if ( state === nextState && ! isExplicitPersistentChange ) { 
 			markNextChangeAsNotPersistent = 
 				action.type === 'MARK_NEXT_CHANGE_AS_NOT_PERSISTENT'; 
 			const nextIsPersistentChange = state?.isPersistentChange ?? true; 
 			if ( state.isPersistentChange === nextIsPersistentChange ) { 
 				return state; 
 			} 
 			return { 
 				...nextState, 
 				isPersistentChange: nextIsPersistentChange, 
 			}; 
 		} 
 		nextState = { 
 			...nextState, 
 			isPersistentChange: isExplicitPersistentChange 
 				? ! markNextChangeAsNotPersistent 
 				: ! isUpdatingSameBlockAttribute( action, lastAction ), 
 		}; 
 		// In comparing against the previous action, consider only those which 
 		// would have qualified as one which would have been ignored or not 
 		// have resulted in a changed state. 
 		lastAction = action; 
 		markNextChangeAsNotPersistent = 
 			action.type === 'MARK_NEXT_CHANGE_AS_NOT_PERSISTENT'; 
 		return nextState; 
 	}; 
 } 
 /** 
  * Returns true if, given the currently dispatching action and the previously 
  * dispatched action, the two actions are updating the same block attribute, or 
  * false otherwise. 
  * 
  * @param {Object} action     Currently dispatching action. 
  * @param {Object} lastAction Previously dispatched action. 
  * 
  * @return {boolean} Whether actions are updating the same block attribute. 
  */ 
 export function isUpdatingSameBlockAttribute( action, lastAction ) { 
 	return ( 
 		action.type === 'UPDATE_BLOCK_ATTRIBUTES' && 
 		lastAction !== undefined && 
 		lastAction.type === 'UPDATE_BLOCK_ATTRIBUTES' && 
 		isEqual( action.clientIds, lastAction.clientIds ) && 
 		hasSameKeys( action.attributes, lastAction.attributes ) 
 	); 
 } 
 /** 
  * Higher-order reducer intended to augment the blocks reducer, assigning an 
  * `isPersistentChange` property value corresponding to whether a change in 
  * state can be considered as persistent. All changes are considered persistent 
  * except when updating the same block attribute as in the previous action. 
  * 
  * @param {Function} reducer Original reducer function. 
  * 
  * @return {Function} Enhanced reducer function. 
  */ 
 function withPersistentBlockChange( reducer ) { 
 	let lastAction; 
 	let markNextChangeAsNotPersistent = false; 
  
 	return ( state, action ) => { 
 		let nextState = reducer( state, action ); 
  
 		const isExplicitPersistentChange = 
 			action.type === 'MARK_LAST_CHANGE_AS_PERSISTENT' || 
 			markNextChangeAsNotPersistent; 
  
 		// Defer to previous state value (or default) unless changing or 
 		// explicitly marking as persistent. 
 		if ( state === nextState && ! isExplicitPersistentChange ) { 
 			markNextChangeAsNotPersistent = 
 				action.type === 'MARK_NEXT_CHANGE_AS_NOT_PERSISTENT'; 
  
 			const nextIsPersistentChange = state?.isPersistentChange ?? true; 
 			if ( state.isPersistentChange === nextIsPersistentChange ) { 
 				return state; 
 			} 
  
 			return { 
 				...nextState, 
 				isPersistentChange: nextIsPersistentChange, 
 			}; 
 		} 
  
 		nextState = { 
 			...nextState, 
 			isPersistentChange: isExplicitPersistentChange 
 				? ! markNextChangeAsNotPersistent 
 				: ! isUpdatingSameBlockAttribute( action, lastAction ), 
 		}; 
  
 		// In comparing against the previous action, consider only those which 
 		// would have qualified as one which would have been ignored or not 
 		// have resulted in a changed state. 
 		lastAction = action; 
 		markNextChangeAsNotPersistent = 
 			action.type === 'MARK_NEXT_CHANGE_AS_NOT_PERSISTENT'; 
  
 		return nextState; 
 	}; 
 } 
+
+	if ( page.isResolving ) {
+		return 'Loading...';
+	}
+
+	async function onRename( event ) {
+		event.preventDefault();
+		page.edit( { title } );
+		try {
+			await page.save( { throwOnError: true } );
+			createSuccessNotice( __( 'Page renamed.' ), {
+				type: 'snackbar',
+			} );
+		} catch ( e ) {
+			const errorMessage =
+				error.message && error.code !== 'unknown_error'
+					? error.message
+					: __( 'An error occurred while renaming the entity.' );
+
+			createErrorNotice( errorMessage, { type: 'snackbar' } );
+		}
+	}
+
+	return (
+		<form onSubmit={ onRename }>
+			<TextControl
+				label={ __( 'Name' ) }
+				value={ title }
+				onChange={ setTitle }
+			/>
+			<Button variant="primary" type="submit">
+				{ __( 'Save' ) }
+			</Button>
+		</form>
+	);
+}
+
+// Rendered in the application:
+// <PageRenameForm id={ 1 } />
+```
+
+In the above example, updating and saving the page title is handled
+via the `edit()` and `save()` mutation helpers provided by
+`useEntityRecord()`;
+
 _Parameters_
 
 -   _kind_ `string`: Kind of the entity, e.g. `root` or a `postType`. See rootEntitiesConfig in ../entities.ts for a list of available kinds.

@@ -50,7 +50,11 @@ describe( 'useEntityRecord', () => {
 		);
 
 		expect( data ).toEqual( {
-			records: undefined,
+			edit: expect.any( Function ),
+			editedRecord: {},
+			hasEdits: false,
+			record: undefined,
+			save: expect.any( Function ),
 			hasResolved: false,
 			isResolving: false,
 			status: 'IDLE',
@@ -66,7 +70,11 @@ describe( 'useEntityRecord', () => {
 		} );
 
 		expect( data ).toEqual( {
+			edit: expect.any( Function ),
+			editedRecord: {},
+			hasEdits: false,
 			record: { hello: 'world', id: 1 },
+			save: expect.any( Function ),
 			hasResolved: true,
 			isResolving: false,
 			status: 'SUCCESS',

@@ -1,7 +1,9 @@
 /**
  * WordPress dependencies
  */
+import { useDispatch, useSelect } from '@wordpress/data';
 import deprecated from '@wordpress/deprecated';
+import { useMemo } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -14,11 +16,25 @@ export interface EntityRecordResolution< RecordType > {
 	/** The requested entity record */
 	record: RecordType | null;
 
+	/** The edited entity record */
+	editedRecord: Partial< RecordType >;
+
+	/** Apply edits to the edited entity record */
+	edit: ( diff: Partial< RecordType > ) => void;
+
+	/** Persist the edits to the server */
+	save: () => Promise< void >;
+
 	/**
 	 * Is the record still being resolved?
 	 */
 	isResolving: boolean;
 
+	/**
+	 * Does the record have any edits?
+	 */
+	hasEdits: boolean;
+
 	/**
 	 * Is the record resolved by now?
 	 */
@@ -66,6 +82,58 @@ export interface Options {
  * application, the page and the resolution details will be retrieved from
  * the store state using `getEntityRecord()`, or resolved if missing.
  *
+ * @example
+ * ```js
+ * import { useEntityRecord } from '@wordpress/core-data';
+ *
+ * function PageRenameForm( { id } ) {
+ *   const page = useEntityRecord( 'postType', 'page', id );
+ *   const [ title, setTitle ] = useState( () => page.record.title.rendered );
+ *
+ *   if ( page.isResolving ) {
+ *     return 'Loading...';
+ *   }
+ *
+ *   async function onRename( event ) {
+ *       event.preventDefault();
+ *       page.edit({ title });
+ *       try {
+ *           await page.save({ throwOnError: true })
+ *           createSuccessNotice( __( 'Page renamed.' ), {
+ *               type: 'snackbar',
+ *           } );
+ *       } catch(e) {
+ *            const errorMessage =
+ *                error.message && error.code !== 'unknown_error'
+ *                    ? error.message
+ *                    : __( 'An error occurred while renaming the entity.' );
+ *
+ *            createErrorNotice( errorMessage, { type: 'snackbar' } );
+ *       }
+ *   }
+ *
+ *   return (
+ *       <form onSubmit={ onRename }>
+ *           <TextControl
+ *               label={ __( 'Name' ) }
+ *               value={ title }
+ *               onChange={ setTitle }
+ *           />
+ *           <Button variant="primary" type="submit">
+ *               { __( 'Save' ) }
+ *           </Button>
+ *       </form>
+ *   );
+ * }
+ *
+ * // Rendered in the application:
+ * // <PageRenameForm id={ 1 } />
+ * ```
+ *
+ * In the above example, updating and saving the page title is handled
+ * via the `edit()` and `save()` mutation helpers provided by
+ * `useEntityRecord()`;
+ *
  * @return Entity record data.
  * @template RecordType
  */
@@ -75,7 +143,28 @@ export default function useEntityRecord< RecordType >(
 	recordId: string | number,
 	options: Options = { enabled: true }
 ): EntityRecordResolution< RecordType > {
-	const { data: record, ...rest } = useQuerySelect(
+	const { editEntityRecord, saveEditedEntityRecord } =
+		useDispatch( coreStore );
+
+	const mutations = useMemo(
+		() => ( {
+			edit: ( record ) =>
+				editEntityRecord( kind, name, recordId, record ),
+			save: ( saveOptions: any ) =>
+				saveEditedEntityRecord( kind, name, recordId, saveOptions ),
+		} ),
+		[ recordId ]
+	);
+
+	const { editedRecord, hasEdits } = useSelect(
+		( select ) => ( {
+			editedRecord: select( coreStore ).getEditedEntityRecord(),
+			hasEdits: select( coreStore ).hasEditsForEntityRecord(),
+		} ),
+		[ kind, name, recordId ]
+	);
+
+	const { data: record, ...querySelectRest } = useQuerySelect(
 		( query ) => {
 			if ( ! options.enabled ) {
 				return null;
@@ -87,7 +176,10 @@ export default function useEntityRecord< RecordType >(
 
 	return {
 		record,
-		...rest,
+		editedRecord,
+		hasEdits,
+		...querySelectRest,
+		...mutations,
 	};
 }