@wordpress/core-data 4.2.1 → 4.3.0

package/src/entities.js

@@ -18,12 +18,25 @@ export const DEFAULT_ENTITY_KEY = 'id';
 
 const POST_RAW_ATTRIBUTES = [ 'title', 'excerpt', 'content' ];
 
-export const defaultEntities = [
+export const rootEntitiesConfig = [
 	{
 		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( ',' ),
+		},
 	},
 	{
 		label: __( 'Site' ),
@@ -50,6 +63,7 @@ export const defaultEntities = [
 		baseURLParams: { context: 'edit' },
 		plural: 'mediaItems',
 		label: __( 'Media' ),
+		rawAttributes: [ 'caption', 'title', 'description' ],
 	},
 	{
 		name: 'taxonomy',
@@ -164,9 +178,9 @@ export const defaultEntities = [
 	},
 ];
 
-export const kinds = [
-	{ name: 'postType', loadEntities: loadPostTypeEntities },
-	{ name: 'taxonomy', loadEntities: loadTaxonomyEntities },
+export const additionalEntityConfigLoaders = [
+	{ kind: 'postType', loadEntities: loadPostTypeEntities },
+	{ kind: 'taxonomy', loadEntities: loadTaxonomyEntities },
 ];
 
 /**
@@ -257,6 +271,15 @@ async function loadTaxonomyEntities() {
 /**
  * Returns the entity's getter method name given its kind and name.
  *
+ * @example
+ * ```js
+ * const nameSingular = getMethodName( 'root', 'theme', 'get' );
+ * // nameSingular is getRootTheme
+ *
+ * const namePlural = getMethodName( 'root', 'theme', 'set' );
+ * // namePlural is setRootThemes
+ * ```
+ *
  * @param {string}  kind      Entity kind.
  * @param {string}  name      Entity name.
  * @param {string}  prefix    Function prefix.
@@ -270,13 +293,13 @@ export const getMethodName = (
 	prefix = 'get',
 	usePlural = false
 ) => {
-	const entity = find( defaultEntities, { kind, name } );
+	const entityConfig = find( rootEntitiesConfig, { kind, name } );
 	const kindPrefix = kind === 'root' ? '' : upperFirst( camelCase( kind ) );
 	const nameSuffix =
 		upperFirst( camelCase( name ) ) + ( usePlural ? 's' : '' );
 	const suffix =
-		usePlural && entity.plural
-			? upperFirst( camelCase( entity.plural ) )
+		usePlural && entityConfig?.plural
+			? upperFirst( camelCase( entityConfig.plural ) )
 			: nameSuffix;
 	return `${ prefix }${ kindPrefix }${ suffix }`;
 };
@@ -286,21 +309,24 @@ export const getMethodName = (
  *
  * @param {string} kind Kind
  *
- * @return {Array} Entities
+ * @return {(thunkArgs: object) => Promise<Array>} Entities
  */
-export const getKindEntities = ( kind ) => async ( { select, dispatch } ) => {
-	let entities = select.getEntitiesByKind( kind );
-	if ( entities && entities.length !== 0 ) {
-		return entities;
+export const getOrLoadEntitiesConfig = ( kind ) => async ( {
+	select,
+	dispatch,
+} ) => {
+	let configs = select.getEntitiesConfig( kind );
+	if ( configs && configs.length !== 0 ) {
+		return configs;
 	}
 
-	const kindConfig = find( kinds, { name: kind } );
-	if ( ! kindConfig ) {
+	const loader = find( additionalEntityConfigLoaders, { kind } );
+	if ( ! loader ) {
 		return [];
 	}
 
-	entities = await kindConfig.loadEntities();
-	dispatch( addEntities( entities ) );
+	configs = await loader.loadEntities();
+	dispatch( addEntities( configs ) );
 
-	return entities;
+	return configs;
 };

package/src/entity-provider.js

@@ -15,53 +15,59 @@ import { parse, __unstableSerializeAndClean } from '@wordpress/blocks';
  */
 import { STORE_NAME } from './name';
 
+/** @typedef {import('@wordpress/blocks').WPBlock} WPBlock */
+
 const EMPTY_ARRAY = [];
 
 /**
  * Internal dependencies
  */
-import { defaultEntities, kinds } from './entities';
+import { rootEntitiesConfig, additionalEntityConfigLoaders } from './entities';
 
-const entities = {
-	...defaultEntities.reduce( ( acc, entity ) => {
-		if ( ! acc[ entity.kind ] ) {
-			acc[ entity.kind ] = {};
+const entityContexts = {
+	...rootEntitiesConfig.reduce( ( acc, loader ) => {
+		if ( ! acc[ loader.kind ] ) {
+			acc[ loader.kind ] = {};
 		}
-		acc[ entity.kind ][ entity.name ] = { context: createContext() };
+		acc[ loader.kind ][ loader.name ] = {
+			context: createContext( undefined ),
+		};
 		return acc;
 	}, {} ),
-	...kinds.reduce( ( acc, kind ) => {
-		acc[ kind.name ] = {};
+	...additionalEntityConfigLoaders.reduce( ( acc, loader ) => {
+		acc[ loader.kind ] = {};
 		return acc;
 	}, {} ),
 };
-const getEntity = ( kind, type ) => {
-	if ( ! entities[ kind ] ) {
+const getEntityContext = ( kind, name ) => {
+	if ( ! entityContexts[ kind ] ) {
 		throw new Error( `Missing entity config for kind: ${ kind }.` );
 	}
 
-	if ( ! entities[ kind ][ type ] ) {
-		entities[ kind ][ type ] = { context: createContext() };
+	if ( ! entityContexts[ kind ][ name ] ) {
+		entityContexts[ kind ][ name ] = {
+			context: createContext( undefined ),
+		};
 	}
 
-	return entities[ kind ][ type ];
+	return entityContexts[ kind ][ name ].context;
 };
 
 /**
  * Context provider component for providing
- * an entity for a specific entity type.
+ * an entity for a specific entity.
  *
  * @param {Object} props          The component's props.
  * @param {string} props.kind     The entity kind.
- * @param {string} props.type     The entity type.
+ * @param {string} props.type     The entity name.
  * @param {number} props.id       The entity ID.
  * @param {*}      props.children The children to wrap.
  *
  * @return {Object} The provided children, wrapped with
  *                   the entity's context provider.
  */
-export default function EntityProvider( { kind, type, id, children } ) {
-	const Provider = getEntity( kind, type ).context.Provider;
+export default function EntityProvider( { kind, type: name, id, children } ) {
+	const Provider = getEntityContext( kind, name ).Provider;
 	return <Provider value={ id }>{ children }</Provider>;
 }
 
@@ -70,10 +76,10 @@ export default function EntityProvider( { kind, type, id, children } ) {
  * provided entity of the specified type.
  *
  * @param {string} kind The entity kind.
- * @param {string} type The entity type.
+ * @param {string} name The entity name.
  */
-export function useEntityId( kind, type ) {
-	return useContext( getEntity( kind, type ).context );
+export function useEntityId( kind, name ) {
+	return useContext( getEntityContext( kind, name ) );
 }
 
 /**
@@ -82,7 +88,7 @@ export function useEntityId( kind, type ) {
  * entity of the specified type.
  *
  * @param {string} kind  The entity kind.
- * @param {string} type  The entity type.
+ * @param {string} name  The entity name.
  * @param {string} prop  The property name.
  * @param {string} [_id] An entity ID to use instead of the context-provided one.
  *
@@ -93,8 +99,8 @@ export function useEntityId( kind, type ) {
  * 							  information like `raw`, `rendered` and
  * 							  `protected` props.
  */
-export function useEntityProp( kind, type, prop, _id ) {
-	const providerId = useEntityId( kind, type );
+export function useEntityProp( kind, name, prop, _id ) {
+	const providerId = useEntityId( kind, name );
 	const id = _id ?? providerId;
 
 	const { value, fullValue } = useSelect(
@@ -102,25 +108,25 @@ export function useEntityProp( kind, type, prop, _id ) {
 			const { getEntityRecord, getEditedEntityRecord } = select(
 				STORE_NAME
 			);
-			const entity = getEntityRecord( kind, type, id ); // Trigger resolver.
-			const editedEntity = getEditedEntityRecord( kind, type, id );
-			return entity && editedEntity
+			const record = getEntityRecord( kind, name, id ); // Trigger resolver.
+			const editedRecord = getEditedEntityRecord( kind, name, id );
+			return record && editedRecord
 				? {
-						value: editedEntity[ prop ],
-						fullValue: entity[ prop ],
+						value: editedRecord[ prop ],
+						fullValue: record[ prop ],
 				  }
 				: {};
 		},
-		[ kind, type, id, prop ]
+		[ kind, name, id, prop ]
 	);
 	const { editEntityRecord } = useDispatch( STORE_NAME );
 	const setValue = useCallback(
 		( newValue ) => {
-			editEntityRecord( kind, type, id, {
+			editEntityRecord( kind, name, id, {
 				[ prop ]: newValue,
 			} );
 		},
-		[ kind, type, id, prop ]
+		[ kind, name, id, prop ]
 	);
 
 	return [ value, setValue, fullValue ];
@@ -138,25 +144,25 @@ export function useEntityProp( kind, type, prop, _id ) {
  * or similar components or hooks.
  *
  * @param {string} kind         The entity kind.
- * @param {string} type         The entity type.
+ * @param {string} name         The entity name.
  * @param {Object} options
  * @param {string} [options.id] An entity ID to use instead of the context-provided one.
  *
  * @return {[WPBlock[], Function, Function]} The block array and setters.
  */
-export function useEntityBlockEditor( kind, type, { id: _id } = {} ) {
-	const providerId = useEntityId( kind, type );
+export function useEntityBlockEditor( kind, name, { id: _id } = {} ) {
+	const providerId = useEntityId( kind, name );
 	const id = _id ?? providerId;
 	const { content, blocks } = useSelect(
 		( select ) => {
 			const { getEditedEntityRecord } = select( STORE_NAME );
-			const editedEntity = getEditedEntityRecord( kind, type, id );
+			const editedRecord = getEditedEntityRecord( kind, name, id );
 			return {
-				blocks: editedEntity.blocks,
-				content: editedEntity.content,
+				blocks: editedRecord.blocks,
+				content: editedRecord.content,
 			};
 		},
-		[ kind, type, id ]
+		[ kind, name, id ]
 	);
 	const { __unstableCreateUndoLevel, editEntityRecord } = useDispatch(
 		STORE_NAME
@@ -170,7 +176,7 @@ export function useEntityBlockEditor( kind, type, { id: _id } = {} ) {
 			const parsedContent = parse( content );
 			editEntityRecord(
 				kind,
-				type,
+				name,
 				id,
 				{
 					blocks: parsedContent,
@@ -187,7 +193,7 @@ export function useEntityBlockEditor( kind, type, { id: _id } = {} ) {
 
 			const noChange = blocks === edits.blocks;
 			if ( noChange ) {
-				return __unstableCreateUndoLevel( kind, type, id );
+				return __unstableCreateUndoLevel( kind, name, id );
 			}
 
 			// We create a new function here on every persistent edit
@@ -196,18 +202,18 @@ export function useEntityBlockEditor( kind, type, { id: _id } = {} ) {
 			edits.content = ( { blocks: blocksForSerialization = [] } ) =>
 				__unstableSerializeAndClean( blocksForSerialization );
 
-			editEntityRecord( kind, type, id, edits );
+			editEntityRecord( kind, name, id, edits );
 		},
-		[ kind, type, id, blocks ]
+		[ kind, name, id, blocks ]
 	);
 
 	const onInput = useCallback(
 		( newBlocks, options ) => {
 			const { selection } = options;
 			const edits = { blocks: newBlocks, selection };
-			editEntityRecord( kind, type, id, edits );
+			editEntityRecord( kind, name, id, edits );
 		},
-		[ kind, type, id ]
+		[ kind, name, id ]
 	);
 
 	return [ blocks ?? EMPTY_ARRAY, onInput, onChange ];

package/src/entity-types/attachment.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import {
+import type {
 	Context,
 	ContextualField,
 	MediaType,
@@ -12,10 +12,10 @@ import {
 	PingStatus,
 } from './helpers';
 
-import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
 
-declare module './base-entity-types' {
-	export namespace BaseEntityTypes {
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
 		export interface Attachment< C extends Context > {
 			/**
 			 * The date the post was published, in the site's timezone.
@@ -142,5 +142,5 @@ declare module './base-entity-types' {
 }
 
 export type Attachment< C extends Context > = OmitNevers<
-	_BaseEntityTypes.Attachment< C >
+	_BaseEntityRecords.Attachment< C >
 >;

package/src/entity-types/{base-entity-types.ts → base-entity-records.ts}

@@ -1,10 +1,10 @@
 /**
- * This module exists solely to make the BaseEntityTypes namespace extensible
+ * This module exists solely to make the BaseEntityRecords namespace extensible
  * with declaration merging:
  *
  * ```ts
- * declare module './base-entity-types' {
- *     export namespace BaseEntityTypes {
+ * declare module './base-entity-records' {
+ *     export namespace BaseEntityRecords {
  * 		     export interface Comment< C extends Context > {
  * 		         id: number;
  * 		         // ...
@@ -19,7 +19,7 @@
  * ```ts
  * import type { Context } from '@wordpress/core-data';
  * declare module '@wordpress/core-data' {
- *     export namespace BaseEntityTypes {
+ *     export namespace BaseEntityRecords {
  *         export interface Comment< C extends Context > {
  *             numberOfViews: number;
  *         }
@@ -33,4 +33,4 @@
  * // c.id is still present
  * ```
  */
-export namespace BaseEntityTypes {}
+export namespace BaseEntityRecords {}

package/src/entity-types/comment.ts

@@ -1,19 +1,19 @@
 /**
  * Internal dependencies
  */
-import {
+import type {
 	AvatarUrls,
 	Context,
 	ContextualField,
 	OmitNevers,
 	RenderedText,
 } from './helpers';
-import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
 
 export type CommentStatus = 'hold' | 'approve' | 'spam' | 'trash' | '1' | '0';
 
-declare module './base-entity-types' {
-	export namespace BaseEntityTypes {
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
 		export interface Comment< C extends Context > {
 			/**
 			 * Unique identifier for the comment.
@@ -92,5 +92,5 @@ declare module './base-entity-types' {
 }
 
 export type Comment< C extends Context > = OmitNevers<
-	_BaseEntityTypes.Comment< C >
+	_BaseEntityRecords.Comment< C >
 >;

package/src/entity-types/helpers.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import { EntityRecord } from './index';
+import type { EntityRecord } from './index';
 
 export interface AvatarUrls {
 	/**

package/src/entity-types/index.ts

@@ -1,6 +1,7 @@
 /**
  * Internal dependencies
  */
+import type { Context, Updatable } from './helpers';
 import type { Attachment } from './attachment';
 import type { Comment } from './comment';
 import type { MenuLocation } from './menu-location';
@@ -20,15 +21,13 @@ import type { Widget } from './widget';
 import type { WidgetType } from './widget-type';
 import type { WpTemplate } from './wp-template';
 import type { WpTemplatePart } from './wp-template-part';
-import type { Context, Updatable } from './helpers';
 
-export type { BaseEntityTypes } from './base-entity-types';
+export type { BaseEntityRecords } from './base-entity-records';
 
 export type {
-	Context,
-	Updatable,
 	Attachment,
 	Comment,
+	Context,
 	MenuLocation,
 	NavMenu,
 	NavMenuItem,
@@ -40,6 +39,7 @@ export type {
 	Sidebar,
 	Taxonomy,
 	Theme,
+	Updatable,
 	User,
 	Type,
 	Widget,

package/src/entity-types/menu-location.ts

@@ -1,12 +1,12 @@
 /**
  * Internal dependencies
  */
-import { Context, OmitNevers } from './helpers';
+import type { Context, OmitNevers } from './helpers';
 
-import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
 
-declare module './base-entity-types' {
-	export namespace BaseEntityTypes {
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
 		export interface MenuLocation< C extends Context > {
 			/**
 			 * The name of the menu location.
@@ -25,5 +25,5 @@ declare module './base-entity-types' {
 }
 
 export type MenuLocation< C extends Context > = OmitNevers<
-	_BaseEntityTypes.MenuLocation< C >
+	_BaseEntityRecords.MenuLocation< C >
 >;

package/src/entity-types/nav-menu-item.ts

@@ -1,9 +1,14 @@
 /**
  * Internal dependencies
  */
-import { RenderedText, Context, ContextualField, OmitNevers } from './helpers';
+import type {
+	RenderedText,
+	Context,
+	ContextualField,
+	OmitNevers,
+} from './helpers';
 
-import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
 
 export type NavMenuItemType =
 	| 'taxonomy'
@@ -18,8 +23,8 @@ export type NavMenuItemStatus =
 	| 'private';
 export type Target = '_blank' | '';
 
-declare module './base-entity-types' {
-	export namespace BaseEntityTypes {
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
 		export interface NavMenuItem< C extends Context > {
 			/**
 			 * The title for the object.
@@ -102,5 +107,5 @@ declare module './base-entity-types' {
 }
 
 export type NavMenuItem< C extends Context > = OmitNevers<
-	_BaseEntityTypes.NavMenuItem< C >
+	_BaseEntityRecords.NavMenuItem< C >
 >;

package/src/entity-types/nav-menu.ts

@@ -1,12 +1,12 @@
 /**
  * Internal dependencies
  */
-import { Context, ContextualField, OmitNevers } from './helpers';
+import type { Context, ContextualField, OmitNevers } from './helpers';
 
-import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
 
-declare module './base-entity-types' {
-	export namespace BaseEntityTypes {
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
 		export interface NavMenu< C extends Context > {
 			/**
 			 * Unique identifier for the term.
@@ -49,5 +49,5 @@ declare module './base-entity-types' {
 }
 
 export type NavMenu< C extends Context > = OmitNevers<
-	_BaseEntityTypes.NavMenu< C >
+	_BaseEntityRecords.NavMenu< C >
 >;

package/src/entity-types/navigation-area.ts

@@ -1,12 +1,12 @@
 /**
  * Internal dependencies
  */
-import { Context, OmitNevers } from './helpers';
+import type { Context, OmitNevers } from './helpers';
 
-import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
 
-declare module './base-entity-types' {
-	export namespace BaseEntityTypes {
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
 		export interface NavigationArea< C extends Context > {
 			/**
 			 * The name of the navigation area.
@@ -25,5 +25,5 @@ declare module './base-entity-types' {
 }
 
 export type NavigationArea< C extends Context > = OmitNevers<
-	_BaseEntityTypes.NavigationArea< C >
+	_BaseEntityRecords.NavigationArea< C >
 >;

package/src/entity-types/page.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import {
+import type {
 	CommentingStatus,
 	Context,
 	ContextualField,
@@ -11,10 +11,10 @@ import {
 	OmitNevers,
 } from './helpers';
 
-import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
 
-declare module './base-entity-types' {
-	export namespace BaseEntityTypes {
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
 		export interface Page< C extends Context > {
 			/**
 			 * The date the post was published, in the site's timezone.
@@ -140,5 +140,5 @@ declare module './base-entity-types' {
 }
 
 export type Page< C extends Context > = OmitNevers<
-	_BaseEntityTypes.Page< C >
+	_BaseEntityRecords.Page< C >
 >;

package/src/entity-types/plugin.ts

@@ -1,12 +1,17 @@
 /**
  * Internal dependencies
  */
-import { Context, ContextualField, RenderedText, OmitNevers } from './helpers';
+import type {
+	Context,
+	ContextualField,
+	RenderedText,
+	OmitNevers,
+} from './helpers';
 
-import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
 
-declare module './base-entity-types' {
-	export namespace BaseEntityTypes {
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
 		export interface Plugin< C extends Context > {
 			/**
 			 * The plugin file.
@@ -70,5 +75,5 @@ declare module './base-entity-types' {
 
 export type PluginStatus = 'active' | 'inactive';
 export type Plugin< C extends Context > = OmitNevers<
-	_BaseEntityTypes.Plugin< C >
+	_BaseEntityRecords.Plugin< C >
 >;

package/src/entity-types/post.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import {
+import type {
 	CommentingStatus,
 	Context,
 	ContextualField,
@@ -12,10 +12,10 @@ import {
 	OmitNevers,
 } from './helpers';
 
-import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
 
-declare module './base-entity-types' {
-	export namespace BaseEntityTypes {
+declare module './base-entity-records' {
+	export namespace BaseEntityRecords {
 		export interface Post< C extends Context > {
 			/**
 			 * The date the post was published, in the site's timezone.
@@ -149,5 +149,5 @@ declare module './base-entity-types' {
 }
 
 export type Post< C extends Context > = OmitNevers<
-	_BaseEntityTypes.Post< C >
+	_BaseEntityRecords.Post< C >
 >;