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 { useState } from '@wordpress/data';
+import { useDispatch } from '@wordpress/data';
+import { __ } from '@wordpress/i18n';
+import { TextControl } from '@wordpress/components';
+import { store as noticeStore } from '@wordpress/notices';
+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; 
 	}; 
 } 
+	const { createSuccessNotice, createErrorNotice } =
+		useDispatch( noticeStore );
+
+	if ( page.isResolving ) {
+		return 'Loading...';
+	}
+
+	async function onRename( event ) {
+		event.preventDefault();
+		page.edit( { title } );
+		try {
+			await page.save();
+			createSuccessNotice( __( 'Page renamed.' ), {
+				type: 'snackbar',
+			} );
+		} catch ( error ) {
+			createErrorNotice( error.message, { type: 'snackbar' } );
+		}
+	}
+
+	return (
+		<form onSubmit={ onRename }>
+			<TextControl
+				label={ __( 'Name' ) }
+				value={ title }
+				onChange={ setTitle }
+			/>
+			<button 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 local (in-browser) 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 local 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 { useState } from '@wordpress/data';
+ * import { useDispatch } from '@wordpress/data';
+ * import { __ } from '@wordpress/i18n';
+ * import { TextControl } from '@wordpress/components';
+ * import { store as noticeStore } from '@wordpress/notices';
+ * import { useEntityRecord } from '@wordpress/core-data';
+ *
+ * function PageRenameForm( { id } ) {
+ * 	const page = useEntityRecord( 'postType', 'page', id );
+ * 	const [ title, setTitle ] = useState( () => page.record.title.rendered );
+ * 	const { createSuccessNotice, createErrorNotice } =
+ * 		useDispatch( noticeStore );
+ *
+ * 	if ( page.isResolving ) {
+ * 		return 'Loading...';
+ * 	}
+ *
+ * 	async function onRename( event ) {
+ * 		event.preventDefault();
+ * 		page.edit( { title } );
+ * 		try {
+ * 			await page.save();
+ * 			createSuccessNotice( __( 'Page renamed.' ), {
+ * 				type: 'snackbar',
+ * 			} );
+ * 		} catch ( error ) {
+ * 			createErrorNotice( error.message, { type: 'snackbar' } );
+ * 		}
+ * 	}
+ *
+ * 	return (
+ * 		<form onSubmit={ onRename }>
+ * 			<TextControl
+ * 				label={ __( 'Name' ) }
+ * 				value={ title }
+ * 				onChange={ setTitle }
+ * 			/>
+ * 			<button 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,31 @@ 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, {
+					throwOnError: true,
+					...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 +179,10 @@ export default function useEntityRecord< RecordType >(
 
 	return {
 		record,
-		...rest,
+		editedRecord,
+		hasEdits,
+		...querySelectRest,
+		...mutations,
 	};
 }