@wordpress/core-data 4.5.0 → 4.8.0

package/src/entities.ts

@@ -13,173 +13,386 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import { addEntities } from './actions';
-import type { Post, Taxonomy, Type, Updatable } from './entity-types';
+import type * as Records from './entity-types';
+import type {
+	EntityType,
+	Context,
+	Post,
+	Taxonomy,
+	Type,
+	Updatable,
+} from './entity-types';
 
 export const DEFAULT_ENTITY_KEY = 'id';
 
 const POST_RAW_ATTRIBUTES = [ 'title', 'excerpt', 'content' ];
 
-export const rootEntitiesConfig = [
+type AttachmentEntity< C extends Context = Context > = EntityType<
 	{
-		label: __( 'Base' ),
-		name: '__unstableBase',
-		kind: 'root',
-		baseURL: '/',
-		baseURLParams: {
-			_fields: [
-				'description',
-				'gmt_offset',
-				'home',
-				'name',
-				'site_icon',
-				'site_icon_url',
-				'site_logo',
-				'timezone_string',
-				'url',
-			].join( ',' ),
-		},
+		name: 'media';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.Attachment< C >,
+	C
+>;
+
+const attachmentConfig: AttachmentEntity[ 'config' ] = {
+	name: 'media',
+	kind: 'root',
+	baseURL: '/wp/v2/media',
+	baseURLParams: { context: 'edit' },
+	plural: 'mediaItems',
+	label: __( 'Media' ),
+	rawAttributes: [ 'caption', 'title', 'description' ],
+};
+
+type SiteEntity< C extends Context = Context > = EntityType<
 	{
-		label: __( 'Site' ),
-		name: 'site',
-		kind: 'root',
-		baseURL: '/wp/v2/settings',
-		getTitle: ( record ) => {
-			return get( record, [ 'title' ], __( 'Site Title' ) );
-		},
+		name: 'site';
+		kind: 'root';
 	},
-	{
-		label: __( 'Post Type' ),
-		name: 'postType',
-		kind: 'root',
-		key: 'slug',
-		baseURL: '/wp/v2/types',
-		baseURLParams: { context: 'edit' },
-		rawAttributes: POST_RAW_ATTRIBUTES,
+	Records.Settings< C >,
+	C
+>;
+
+const siteConfig: SiteEntity[ 'config' ] = {
+	label: __( 'Site' ),
+	name: 'site',
+	kind: 'root',
+	baseURL: '/wp/v2/settings',
+	getTitle: ( record: Records.Settings< 'edit' > ) => {
+		return get( record, [ 'title' ], __( 'Site Title' ) );
 	},
+};
+
+type PostTypeEntity< C extends Context = Context > = EntityType<
 	{
-		name: 'media',
-		kind: 'root',
-		baseURL: '/wp/v2/media',
-		baseURLParams: { context: 'edit' },
-		plural: 'mediaItems',
-		label: __( 'Media' ),
-		rawAttributes: [ 'caption', 'title', 'description' ],
+		name: 'postType';
+		kind: 'root';
+		key: 'slug';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.Type< C >,
+	C
+>;
+
+const postTypeConfig: PostTypeEntity[ 'config' ] = {
+	label: __( 'Post Type' ),
+	name: 'postType',
+	kind: 'root',
+	key: 'slug',
+	baseURL: '/wp/v2/types',
+	baseURLParams: { context: 'edit' },
+};
+
+type TaxonomyEntity< C extends Context = Context > = EntityType<
 	{
-		name: 'taxonomy',
-		kind: 'root',
-		key: 'slug',
-		baseURL: '/wp/v2/taxonomies',
-		baseURLParams: { context: 'edit' },
-		plural: 'taxonomies',
-		label: __( 'Taxonomy' ),
+		name: 'taxonomy';
+		kind: 'root';
+		key: 'slug';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.Taxonomy< C >,
+	C
+>;
+
+const taxonomyConfig: TaxonomyEntity[ 'config' ] = {
+	name: 'taxonomy',
+	kind: 'root',
+	key: 'slug',
+	baseURL: '/wp/v2/taxonomies',
+	baseURLParams: { context: 'edit' },
+	plural: 'taxonomies',
+	label: __( 'Taxonomy' ),
+};
+
+type SidebarEntity< C extends Context = Context > = EntityType<
 	{
-		name: 'sidebar',
-		kind: 'root',
-		baseURL: '/wp/v2/sidebars',
-		baseURLParams: { context: 'edit' },
-		plural: 'sidebars',
-		transientEdits: { blocks: true },
-		label: __( 'Widget areas' ),
+		name: 'sidebar';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.Sidebar< C >,
+	C
+>;
+
+const sidebarConfig: SidebarEntity[ 'config' ] = {
+	name: 'sidebar',
+	kind: 'root',
+	baseURL: '/wp/v2/sidebars',
+	baseURLParams: { context: 'edit' },
+	plural: 'sidebars',
+	transientEdits: { blocks: true },
+	label: __( 'Widget areas' ),
+};
+
+type WidgetEntity< C extends Context = Context > = EntityType<
 	{
-		name: 'widget',
-		kind: 'root',
-		baseURL: '/wp/v2/widgets',
-		baseURLParams: { context: 'edit' },
-		plural: 'widgets',
-		transientEdits: { blocks: true },
-		label: __( 'Widgets' ),
+		name: 'widget';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.Widget< C >,
+	C
+>;
+const widgetConfig: WidgetEntity[ 'config' ] = {
+	name: 'widget',
+	kind: 'root',
+	baseURL: '/wp/v2/widgets',
+	baseURLParams: { context: 'edit' },
+	plural: 'widgets',
+	transientEdits: { blocks: true },
+	label: __( 'Widgets' ),
+};
+
+type WidgetTypeEntity< C extends Context = Context > = EntityType<
 	{
-		name: 'widgetType',
-		kind: 'root',
-		baseURL: '/wp/v2/widget-types',
-		baseURLParams: { context: 'edit' },
-		plural: 'widgetTypes',
-		label: __( 'Widget types' ),
+		name: 'widgetType';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.WidgetType< C >,
+	C
+>;
+const widgetTypeConfig: WidgetTypeEntity[ 'config' ] = {
+	name: 'widgetType',
+	kind: 'root',
+	baseURL: '/wp/v2/widget-types',
+	baseURLParams: { context: 'edit' },
+	plural: 'widgetTypes',
+	label: __( 'Widget types' ),
+};
+
+type UserEntity< C extends Context = Context > = EntityType<
 	{
-		label: __( 'User' ),
-		name: 'user',
-		kind: 'root',
-		baseURL: '/wp/v2/users',
-		baseURLParams: { context: 'edit' },
-		plural: 'users',
-	},
-	{
-		name: 'comment',
-		kind: 'root',
-		baseURL: '/wp/v2/comments',
-		baseURLParams: { context: 'edit' },
-		plural: 'comments',
-		label: __( 'Comment' ),
+		name: 'user';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.User< C >,
+	C
+>;
+const userConfig: UserEntity[ 'config' ] = {
+	label: __( 'User' ),
+	name: 'user',
+	kind: 'root',
+	baseURL: '/wp/v2/users',
+	baseURLParams: { context: 'edit' },
+	plural: 'users',
+};
+
+type CommentEntity< C extends Context = Context > = EntityType<
 	{
-		name: 'menu',
-		kind: 'root',
-		baseURL: '/wp/v2/menus',
-		baseURLParams: { context: 'edit' },
-		plural: 'menus',
-		label: __( 'Menu' ),
+		name: 'comment';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.Comment< C >,
+	C
+>;
+const commentConfig: CommentEntity[ 'config' ] = {
+	name: 'comment',
+	kind: 'root',
+	baseURL: '/wp/v2/comments',
+	baseURLParams: { context: 'edit' },
+	plural: 'comments',
+	label: __( 'Comment' ),
+};
+
+type NavMenuEntity< C extends Context = Context > = EntityType<
 	{
-		name: 'menuItem',
-		kind: 'root',
-		baseURL: '/wp/v2/menu-items',
-		baseURLParams: { context: 'edit' },
-		plural: 'menuItems',
-		label: __( 'Menu Item' ),
-		rawAttributes: [ 'title', 'content' ],
+		name: 'menu';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.NavMenu< C >,
+	C
+>;
+
+const menuConfig: NavMenuEntity[ 'config' ] = {
+	name: 'menu',
+	kind: 'root',
+	baseURL: '/wp/v2/menus',
+	baseURLParams: { context: 'edit' },
+	plural: 'menus',
+	label: __( 'Menu' ),
+};
+
+type NavMenuItemEntity< C extends Context = Context > = EntityType<
 	{
-		name: 'menuLocation',
-		kind: 'root',
-		baseURL: '/wp/v2/menu-locations',
-		baseURLParams: { context: 'edit' },
-		plural: 'menuLocations',
-		label: __( 'Menu Location' ),
-		key: 'name',
+		name: 'menuItem';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.NavMenuItem< C >,
+	C
+>;
+
+const menuItemConfig: NavMenuItemEntity[ 'config' ] = {
+	name: 'menuItem',
+	kind: 'root',
+	baseURL: '/wp/v2/menu-items',
+	baseURLParams: { context: 'edit' },
+	plural: 'menuItems',
+	label: __( 'Menu Item' ),
+	rawAttributes: [ 'title' ],
+};
+
+type MenuLocationEntity< C extends Context = Context > = EntityType<
 	{
-		name: 'navigationArea',
-		kind: 'root',
-		baseURL: '/wp/v2/block-navigation-areas',
-		baseURLParams: { context: 'edit' },
-		plural: 'navigationAreas',
-		label: __( 'Navigation Area' ),
-		key: 'name',
-		getTitle: ( record ) => record?.description,
+		name: 'menuLocation';
+		kind: 'root';
+		key: 'name';
+		baseURLParams: { context: 'edit' };
 	},
+	Records.MenuLocation< C >,
+	C
+>;
+
+const menuLocationConfig: MenuLocationEntity[ 'config' ] = {
+	name: 'menuLocation',
+	kind: 'root',
+	baseURL: '/wp/v2/menu-locations',
+	baseURLParams: { context: 'edit' },
+	plural: 'menuLocations',
+	label: __( 'Menu Location' ),
+	key: 'name',
+};
+
+const globalStyleConfig = {
+	label: __( 'Global Styles' ),
+	name: 'globalStyles',
+	kind: 'root',
+	baseURL: '/wp/v2/global-styles',
+	baseURLParams: { context: 'edit' },
+	plural: 'globalStylesVariations', // Should be different than name.
+	getTitle: ( record ) => record?.title?.rendered || record?.title,
+};
+
+type ThemeEntity< C extends Context = Context > = EntityType<
 	{
-		label: __( 'Global Styles' ),
-		name: 'globalStyles',
-		kind: 'root',
-		baseURL: '/wp/v2/global-styles',
-		baseURLParams: { context: 'edit' },
-		plural: 'globalStylesVariations', // Should be different than name.
-		getTitle: ( record ) => record?.title?.rendered || record?.title,
+		name: 'theme';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
+		key: 'stylesheet';
 	},
+	Records.Theme< C >,
+	C
+>;
+
+const themeConfig: ThemeEntity[ 'config' ] = {
+	label: __( 'Themes' ),
+	name: 'theme',
+	kind: 'root',
+	baseURL: '/wp/v2/themes',
+	baseURLParams: { context: 'edit' },
+	key: 'stylesheet',
+};
+
+type PluginEntity< C extends Context = Context > = EntityType<
 	{
-		label: __( 'Themes' ),
-		name: 'theme',
-		kind: 'root',
-		baseURL: '/wp/v2/themes',
-		baseURLParams: { context: 'edit' },
-		key: 'stylesheet',
+		name: 'plugin';
+		kind: 'root';
+		baseURLParams: { context: 'edit' };
+		key: 'plugin';
 	},
+	Records.Plugin< C >,
+	C
+>;
+const pluginConfig: PluginEntity[ 'config' ] = {
+	label: __( 'Plugins' ),
+	name: 'plugin',
+	kind: 'root',
+	baseURL: '/wp/v2/plugins',
+	baseURLParams: { context: 'edit' },
+	key: 'plugin',
+};
+
+export const rootEntitiesConfig = [
 	{
-		label: __( 'Plugins' ),
-		name: 'plugin',
+		label: __( 'Base' ),
 		kind: 'root',
-		baseURL: '/wp/v2/plugins',
-		baseURLParams: { context: 'edit' },
-		key: 'plugin',
+		name: '__unstableBase',
+		baseURL: '/',
+		baseURLParams: {
+			_fields: [
+				'description',
+				'gmt_offset',
+				'home',
+				'name',
+				'site_icon',
+				'site_icon_url',
+				'site_logo',
+				'timezone_string',
+				'url',
+			].join( ',' ),
+		},
 	},
+	siteConfig,
+	postTypeConfig,
+	attachmentConfig,
+	taxonomyConfig,
+	sidebarConfig,
+	widgetConfig,
+	widgetTypeConfig,
+	userConfig,
+	commentConfig,
+	menuConfig,
+	menuItemConfig,
+	menuLocationConfig,
+	globalStyleConfig,
+	themeConfig,
+	pluginConfig,
 ];
 
+type PostTypeConfig = {
+	kind: 'postType';
+	key: 'id';
+	defaultContext: 'edit';
+};
+
+type PostEntity< C extends Context = Context > = EntityType<
+	PostTypeConfig & { name: 'post' },
+	Records.Post< C >,
+	C
+>;
+type PageEntity< C extends Context > = EntityType<
+	PostTypeConfig & { name: 'page' },
+	Records.Page< C >,
+	C
+>;
+type WpTemplateEntity< C extends Context > = EntityType<
+	PostTypeConfig & { name: 'wp_template' },
+	Records.WpTemplate< C >,
+	C
+>;
+type WpTemplatePartEntity< C extends Context > = EntityType<
+	PostTypeConfig & { name: 'wp_template_part' },
+	Records.WpTemplatePart< C >,
+	C
+>;
+
+export type CoreEntities< C extends Context > =
+	| SiteEntity< C >
+	| PostTypeEntity< C >
+	| AttachmentEntity< C >
+	| TaxonomyEntity< C >
+	| SidebarEntity< C >
+	| WidgetEntity< C >
+	| WidgetTypeEntity< C >
+	| UserEntity< C >
+	| CommentEntity< C >
+	| NavMenuEntity< C >
+	| NavMenuItemEntity< C >
+	| MenuLocationEntity< C >
+	| ThemeEntity< C >
+	| PluginEntity< C >
+	| PostEntity< C >
+	| PageEntity< C >
+	| WpTemplateEntity< C >
+	| WpTemplatePartEntity< C >;
+
 export const additionalEntityConfigLoaders = [
 	{ kind: 'postType', loadEntities: loadPostTypeEntities },
 	{ kind: 'taxonomy', loadEntities: loadTaxonomyEntities },
@@ -302,7 +515,7 @@ export const getMethodName = (
 	const nameSuffix =
 		upperFirst( camelCase( name ) ) + ( usePlural ? 's' : '' );
 	const suffix =
-		usePlural && entityConfig?.plural
+		usePlural && 'plural' in entityConfig && entityConfig?.plural
 			? upperFirst( camelCase( entityConfig.plural ) )
 			: nameSuffix;
 	return `${ prefix }${ kindPrefix }${ suffix }`;

package/src/entity-types/entities.ts

@@ -0,0 +1,127 @@
+/**
+ * Internal dependencies
+ */
+import type { Context } from './helpers';
+import { EntityRecord } from './index';
+
+/**
+ * HTTP Query parameters sent with the API request to fetch the entity records.
+ */
+export type EntityQuery<
+	C extends Context,
+	Fields extends string[] | undefined = undefined
+> = Record< string, any > & {
+	context?: C;
+	/**
+	 * The requested fields. If specified, the REST API will remove from the response
+	 * any fields not on that list.
+	 */
+	_fields?: Fields;
+};
+
+interface Edit {}
+
+/**
+ * Helper type that transforms "raw" entity configuration from entities.ts
+ * into a format that makes searching by root and kind easy and extensible.
+ *
+ * This is the foundation of return type inference in calls such as:
+ * `getEntityRecord( "root", "comment", 15 )`.
+ *
+ * @see EntityRecordOf
+ * @see getEntityRecord
+ */
+export type EntityType<
+	Config extends Pick< EntityConfig< Record, Ctx >, RequiredConfigKeys >,
+	Record extends EntityRecord< Ctx >,
+	Ctx extends Context
+> = {
+	record: Record;
+	config: Omit< EntityConfig< Record, Ctx >, RequiredConfigKeys > & Config;
+	key: Config[ 'key' ] extends string ? Config[ 'key' ] : 'id';
+	defaultContext: Config[ 'baseURLParams' ] extends {
+		context: infer InferredContext;
+	}
+		? InferredContext
+		: 'view';
+};
+
+type RequiredConfigKeys = 'name' | 'kind' | 'key' | 'baseURLParams';
+
+interface EntityConfig< R extends EntityRecord< C >, C extends Context > {
+	/** Path in WP REST API from which to request records of this entity. */
+	baseURL: string;
+
+	/** Arguments to supply by default to API requests for records of this entity. */
+	baseURLParams?: EntityQuery< Context >;
+
+	/**
+	 * Returns the title for a given record of this entity.
+	 *
+	 * Some entities have an associated title, such as the name of a
+	 * particular template part ("full width") or of a menu ("main nav").
+	 */
+	getTitle?: ( record: R ) => string;
+
+	/**
+	 * Indicates an alternate field in record that can be used for identification.
+	 *
+	 * e.g. a post has an id but may also be uniquely identified by its `slug`
+	 */
+	key?: string;
+
+	/**
+	 * Collection in which to classify records of this entity.
+	 *
+	 * 'root' is a special name given to the core entities provided by the editor.
+	 *
+	 * It may be the case that we request an entity record for which we have no
+	 * valid config in memory. In these cases the editor will look for a loader
+	 * function to requests more entity configs from the server for the given
+	 * "kind." This is how WordPress defers loading of template entity configs.
+	 */
+	kind: string;
+
+	/** Translated form of human-recognizable name or reference to records of this entity. */
+	label: string;
+
+	mergedEdits?: {
+		meta?: boolean;
+	};
+
+	/** Name given to records of this entity, e.g. 'media', 'postType', 'widget' */
+	name: string;
+
+	/**
+	 * Manually provided plural form of the entity name.
+	 *
+	 * When not supplied the editor will attempt to auto-generate a plural form.
+	 */
+	plural?: string;
+
+	/**
+	 * Fields in record of this entity which may appear as a compound object with
+	 * a source value (`raw`) as well as a processed value (`rendered`).
+	 *
+	 * e.g. a post's `content` in the edit context contains the raw value stored
+	 *      in the database as well as the rendered version with shortcodes replaced,
+	 *      content texturized, blocks transformed, etc…
+	 */
+	rawAttributes?: ( keyof R )[];
+
+	/**
+	 * Which transient edit operations records of this entity support.
+	 */
+	transientEdits?: {
+		blocks?: boolean;
+		selection?: boolean;
+	};
+
+	// Unstable properties
+
+	/** Returns additional changes before applying edits to a record of this entity. */
+	__unstablePrePersist?: ( record: R, edits: Edit[] ) => Edit[];
+
+	/** Used in `canEdit()` */
+	__unstable_rest_base?: string;
+}

package/src/entity-types/index.ts

@@ -7,7 +7,6 @@ import type { Comment } from './comment';
 import type { MenuLocation } from './menu-location';
 import type { NavMenu } from './nav-menu';
 import type { NavMenuItem } from './nav-menu-item';
-import type { NavigationArea } from './navigation-area';
 import type { Page } from './page';
 import type { Plugin } from './plugin';
 import type { Post } from './post';
@@ -22,6 +21,7 @@ import type { WidgetType } from './widget-type';
 import type { WpTemplate } from './wp-template';
 import type { WpTemplatePart } from './wp-template-part';
 
+export type { EntityType } from './entities';
 export type { BaseEntityRecords } from './base-entity-records';
 
 export type {
@@ -31,7 +31,6 @@ export type {
 	MenuLocation,
 	NavMenu,
 	NavMenuItem,
-	NavigationArea,
 	Page,
 	Plugin,
 	Post,
@@ -54,7 +53,6 @@ export type EntityRecord< C extends Context > =
 	| MenuLocation< C >
 	| NavMenu< C >
 	| NavMenuItem< C >
-	| NavigationArea< C >
 	| Page< C >
 	| Plugin< C >
 	| Post< C >

package/src/hooks/constants.ts

@@ -1,5 +1,4 @@
-/* eslint-disable-next-line no-shadow */
-export enum Status {
+export const enum Status {
 	Idle = 'IDLE',
 	Resolving = 'RESOLVING',
 	Error = 'ERROR',

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export {
+	default as useEntityRecord,
+	__experimentalUseEntityRecord,
+} from './use-entity-record';
+export {
+	default as useEntityRecords,
+	__experimentalUseEntityRecords,
+} from './use-entity-records';