Revisions: add new selectors to fetch entity revisions

docs/reference-guides/data/data-core.md

@@ -420,6 +420,39 @@ _Returns_
 
 -   A value whose reference will change only when an edit occurs.
 
+### getRevision
+
+Returns a single, specific revision of a parent entity.
+
+_Parameters_
+
+-   _state_ `State`: State tree
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordKey_ `EntityRecordKey`: The key of the entity record whose revisions you want to fetch.
+-   _revisionKey_ `EntityRecordKey`: The revision's key.
+-   _query_ `GetRecordsHttpQuery`: Optional query. If requesting specific fields, fields must always include the ID. For valid query parameters see revisions schema in [the REST API Handbook](https://developer.wordpress.org/rest-api/reference/). Then see the arguments available "Retrieve a [entity kind]".
+
+_Returns_
+
+-   `RevisionRecord | Record< PropertyKey, never > | undefined`: Record.
+
+### getRevisions
+
+Returns an entity's revisions.
+
+_Parameters_
+
+-   _state_ `State`: State tree
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordKey_ `EntityRecordKey`: The key of the entity record whose revisions you want to fetch.
+-   _query_ `GetRecordsHttpQuery`: Optional query. If requesting specific fields, fields must always include the ID. For valid query parameters see revisions schema in [the REST API Handbook](https://developer.wordpress.org/rest-api/reference/). Then see the arguments available "Retrieve a [Entity kind]".
+
+_Returns_
+
+-   `RevisionRecord[] | null`: Record.
+
 ### getThemeSupports
 
 Return theme supports data in the index.
@@ -704,6 +737,24 @@ _Returns_
 
 -   `Object`: Action object.
 
+### receiveRevisions
+
+Returns an action object used in signalling that revisions have been received.
+
+_Parameters_
+
+-   _kind_ `string`: Kind of the received entity record revisions.
+-   _name_ `string`: Name of the received entity record revisions.
+-   _recordKey_ `number|string`: The key of the entity record whose revisions you want to fetch.
+-   _records_ `Array|Object`: Revisions received.
+-   _query_ `?Object`: Query Object.
+-   _invalidateCache_ `?boolean`: Should invalidate query caches.
+-   _meta_ `?Object`: Meta information about pagination.
+
+_Returns_
+
+-   `Object`: Action object.
+
 ### receiveThemeSupports
 
 > **Deprecated** since WP 5.9, this is not useful anymore, use the selector direclty.

packages/core-data/CHANGELOG.md

@@ -9,6 +9,7 @@
 ## Enhancements
 
 -   Add `getEntityRecordsTotalItems` and `getEntityRecordsTotalPages` selectors. [#55164](https://github.com/WordPress/gutenberg/pull/55164).
+-   Revisions: add new selectors, `getRevisions` and `getRevision`, to fetch entity revisions. [#54046](https://github.com/WordPress/gutenberg/pull/54046).
 
 ## 6.20.0 (2023-10-05)
 

packages/core-data/README.md

@@ -123,7 +123,7 @@ The package provides general methods to interact with the entities (`getEntityRe
 
 ```js
 // Get the record collection for the user entity.
-wp.data.select( 'core' ).getEntityRecords( 'root' 'user' );
+wp.data.select( 'core' ).getEntityRecords( 'root', 'user' );
 
 // Get a single record for the user entity.
 wp.data.select( 'core' ).getEntityRecord( 'root', 'user', recordId );
@@ -138,7 +138,7 @@ In addition to the general utilities (`getEntityRecords`, `getEntityRecord`, etc
 
 ```js
 // Collection
-wp.data.select( 'core' ).getEntityRecords( 'root' 'user' );
+wp.data.select( 'core' ).getEntityRecords( 'root', 'user' );
 wp.data.select( 'core' ).getUsers();
 
 // Single record
@@ -248,6 +248,24 @@ _Returns_
 
 -   `Object`: Action object.
 
+### receiveRevisions
+
+Returns an action object used in signalling that revisions have been received.
+
+_Parameters_
+
+-   _kind_ `string`: Kind of the received entity record revisions.
+-   _name_ `string`: Name of the received entity record revisions.
+-   _recordKey_ `number|string`: The key of the entity record whose revisions you want to fetch.
+-   _records_ `Array|Object`: Revisions received.
+-   _query_ `?Object`: Query Object.
+-   _invalidateCache_ `?boolean`: Should invalidate query caches.
+-   _meta_ `?Object`: Meta information about pagination.
+
+_Returns_
+
+-   `Object`: Action object.
+
 ### receiveThemeSupports
 
 > **Deprecated** since WP 5.9, this is not useful anymore, use the selector direclty.
@@ -727,6 +745,39 @@ _Returns_
 
 -   A value whose reference will change only when an edit occurs.
 
+### getRevision
+
+Returns a single, specific revision of a parent entity.
+
+_Parameters_
+
+-   _state_ `State`: State tree
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordKey_ `EntityRecordKey`: The key of the entity record whose revisions you want to fetch.
+-   _revisionKey_ `EntityRecordKey`: The revision's key.
+-   _query_ `GetRecordsHttpQuery`: Optional query. If requesting specific fields, fields must always include the ID. For valid query parameters see revisions schema in [the REST API Handbook](https://developer.wordpress.org/rest-api/reference/). Then see the arguments available "Retrieve a [entity kind]".
+
+_Returns_
+
+-   `RevisionRecord | Record< PropertyKey, never > | undefined`: Record.
+
+### getRevisions
+
+Returns an entity's revisions.
+
+_Parameters_
+
+-   _state_ `State`: State tree
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _recordKey_ `EntityRecordKey`: The key of the entity record whose revisions you want to fetch.
+-   _query_ `GetRecordsHttpQuery`: Optional query. If requesting specific fields, fields must always include the ID. For valid query parameters see revisions schema in [the REST API Handbook](https://developer.wordpress.org/rest-api/reference/). Then see the arguments available "Retrieve a [Entity kind]".
+
+_Returns_
+
+-   `RevisionRecord[] | null`: Record.
+
 ### getThemeSupports
 
 Return theme supports data in the index.

packages/core-data/src/actions.js

@@ -924,3 +924,36 @@ export function receiveDefaultTemplateId( query, templateId ) {
 		templateId,
 	};
 }
+
+/**
+ * Returns an action object used in signalling that revisions have been received.
+ *
+ * @param {string}        kind            Kind of the received entity record revisions.
+ * @param {string}        name            Name of the received entity record revisions.
+ * @param {number|string} recordKey       The key of the entity record whose revisions you want to fetch.
+ * @param {Array|Object}  records         Revisions received.
+ * @param {?Object}       query           Query Object.
+ * @param {?boolean}      invalidateCache Should invalidate query caches.
+ * @param {?Object}       meta            Meta information about pagination.
+ * @return {Object} Action object.
+ */
+export function receiveRevisions(
+	kind,
+	name,
+	recordKey,
+	records,
+	query,
+	invalidateCache = false,
+	meta
+) {
+	return {
+		type: 'RECEIVE_ITEM_REVISIONS',
+		items: Array.isArray( records ) ? records : [ records ],
+		recordKey,
+		meta,
+		query,
+		kind,
+		name,
+		invalidateCache,
+	};
+}

packages/core-data/src/entities.js

@@ -19,6 +19,10 @@ export const DEFAULT_ENTITY_KEY = 'id';
 
 const POST_RAW_ATTRIBUTES = [ 'title', 'excerpt', 'content' ];
 
+// A hardcoded list of post types that support revisions.
+// @TODO: Ideally this should be fetched from the  `/types` REST API's view context.
+const POST_TYPES_WITH_REVISIONS_SUPPORT = [ 'post', 'page' ];
+
 export const rootEntitiesConfig = [
 	{
 		label: __( 'Base' ),
@@ -207,6 +211,12 @@ export const rootEntitiesConfig = [
 		baseURLParams: { context: 'edit' },
 		plural: 'globalStylesVariations', // Should be different than name.
 		getTitle: ( record ) => record?.title?.rendered || record?.title,
+		getRevisionsUrl: ( parentId ) =>
+			`/wp/v2/global-styles/${ parentId }/revisions`,
+		supports: {
+			revisions: true,
+		},
+		supportsPagination: true,
 	},
 	{
 		label: __( 'Themes' ),
@@ -295,6 +305,11 @@ async function loadPostTypeEntities() {
 				selection: true,
 			},
 			mergedEdits: { meta: true },
+			supports: {
+				revisions: POST_TYPES_WITH_REVISIONS_SUPPORT.includes(
+					postType?.slug
+				),
+			},
 			rawAttributes: POST_RAW_ATTRIBUTES,
 			getTitle: ( record ) =>
 				record?.title?.rendered ||
@@ -328,6 +343,12 @@ async function loadPostTypeEntities() {
 			syncObjectType: 'postType/' + postType.name,
 			getSyncObjectId: ( id ) => id,
 			supportsPagination: true,
+			getRevisionsUrl: ( parentId, revisionId ) =>
+				`/${ namespace }/${
+					postType.rest_base
+				}/${ parentId }/revisions${
+					revisionId ? '/' + revisionId : ''
+				}`,
 		};
 	} );
 }

packages/core-data/src/entity-types/global-styles-revision.ts

@@ -0,0 +1,47 @@
+/**
+ * Internal dependencies
+ */
+import type { Context, ContextualField, OmitNevers } from './helpers';
+
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
+		export interface GlobalStylesRevision< C extends Context > {
+			/**
+			 * The ID for the author of the global styles revision.
+			 */
+			author: number;
+			/**
+			 * The date the post global styles revision published, in the site's timezone.
+			 */
+			date: string | null;
+			/**
+			 * The date the global styles revision was published, as GMT.
+			 */
+			date_gmt: ContextualField< string | null, 'view' | 'edit', C >;
+			/**
+			 * Unique identifier for the revision.
+			 */
+			id: number;
+			/**
+			 * The date the global styles revision was last modified, in the site's timezone.
+			 */
+			modified: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * The date the global styles revision was last modified, as GMT.
+			 */
+			modified_gmt: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * Identifier for the parent of the revision.
+			 */
+			parent: number;
+			styles: Record< string, Object >;
+			settings: Record< string, Object >;
+		}
+	}
+}
+
+export type GlobalStylesRevision< C extends Context = 'view' > = OmitNevers<
+	_BaseEntityRecords.GlobalStylesRevision< C >
+>;

packages/core-data/src/entity-types/index.ts

@@ -4,12 +4,14 @@
 import type { Context, Updatable } from './helpers';
 import type { Attachment } from './attachment';
 import type { Comment } from './comment';
+import type { GlobalStylesRevision } from './global-styles-revision';
 import type { MenuLocation } from './menu-location';
 import type { NavMenu } from './nav-menu';
 import type { NavMenuItem } from './nav-menu-item';
 import type { Page } from './page';
 import type { Plugin } from './plugin';
 import type { Post } from './post';
+import type { PostRevision } from './post-revision';
 import type { Settings } from './settings';
 import type { Sidebar } from './sidebar';
 import type { Taxonomy } from './taxonomy';
@@ -27,12 +29,14 @@ export type {
 	Attachment,
 	Comment,
 	Context,
+	GlobalStylesRevision,
 	MenuLocation,
 	NavMenu,
 	NavMenuItem,
 	Page,
 	Plugin,
 	Post,
+	PostRevision,
 	Settings,
 	Sidebar,
 	Taxonomy,
@@ -82,12 +86,14 @@ export interface PerPackageEntityRecords< C extends Context > {
 	core:
 		| Attachment< C >
 		| Comment< C >
+		| GlobalStylesRevision< C >
 		| MenuLocation< C >
 		| NavMenu< C >
 		| NavMenuItem< C >
 		| Page< C >
 		| Plugin< C >
 		| Post< C >
+		| PostRevision< C >
 		| Settings< C >
 		| Sidebar< C >
 		| Taxonomy< C >