@wordpress/core-data 7.3.0 → 7.5.0

package/src/hooks/use-entity-block-editor.js

@@ -0,0 +1,148 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useMemo } from '@wordpress/element';
+import { useDispatch, useSelect } from '@wordpress/data';
+import { parse, __unstableSerializeAndClean } from '@wordpress/blocks';
+
+/**
+ * Internal dependencies
+ */
+import { STORE_NAME } from '../name';
+import useEntityId from './use-entity-id';
+import { updateFootnotesFromMeta } from '../footnotes';
+
+const EMPTY_ARRAY = [];
+const parsedBlocksCache = new WeakMap();
+
+/**
+ * Hook that returns block content getters and setters for
+ * the nearest provided entity of the specified type.
+ *
+ * The return value has the shape `[ blocks, onInput, onChange ]`.
+ * `onInput` is for block changes that don't create undo levels
+ * or dirty the post, non-persistent changes, and `onChange` is for
+ * persistent changes. They map directly to the props of a
+ * `BlockEditorProvider` and are intended to be used with it,
+ * or similar components or hooks.
+ *
+ * @param {string} kind         The entity kind.
+ * @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 {[unknown[], Function, Function]} The block array and setters.
+ */
+export default function useEntityBlockEditor( kind, name, { id: _id } = {} ) {
+	const providerId = useEntityId( kind, name );
+	const id = _id ?? providerId;
+	const { getEntityRecord, getEntityRecordEdits } = useSelect( STORE_NAME );
+	const { content, editedBlocks, meta } = useSelect(
+		( select ) => {
+			if ( ! id ) {
+				return {};
+			}
+			const { getEditedEntityRecord } = select( STORE_NAME );
+			const editedRecord = getEditedEntityRecord( kind, name, id );
+			return {
+				editedBlocks: editedRecord.blocks,
+				content: editedRecord.content,
+				meta: editedRecord.meta,
+			};
+		},
+		[ kind, name, id ]
+	);
+	const { __unstableCreateUndoLevel, editEntityRecord } =
+		useDispatch( STORE_NAME );
+
+	const blocks = useMemo( () => {
+		if ( ! id ) {
+			return undefined;
+		}
+
+		if ( editedBlocks ) {
+			return editedBlocks;
+		}
+
+		if ( ! content || typeof content !== 'string' ) {
+			return EMPTY_ARRAY;
+		}
+
+		// If there's an edit, cache the parsed blocks by the edit.
+		// If not, cache by the original enity record.
+		const edits = getEntityRecordEdits( kind, name, id );
+		const isUnedited = ! edits || ! Object.keys( edits ).length;
+		const cackeKey = isUnedited ? getEntityRecord( kind, name, id ) : edits;
+		let _blocks = parsedBlocksCache.get( cackeKey );
+
+		if ( ! _blocks ) {
+			_blocks = parse( content );
+			parsedBlocksCache.set( cackeKey, _blocks );
+		}
+
+		return _blocks;
+	}, [
+		kind,
+		name,
+		id,
+		editedBlocks,
+		content,
+		getEntityRecord,
+		getEntityRecordEdits,
+	] );
+
+	const updateFootnotes = useCallback(
+		( _blocks ) => updateFootnotesFromMeta( _blocks, meta ),
+		[ meta ]
+	);
+
+	const onChange = useCallback(
+		( newBlocks, options ) => {
+			const noChange = blocks === newBlocks;
+			if ( noChange ) {
+				return __unstableCreateUndoLevel( kind, name, id );
+			}
+			const { selection, ...rest } = options;
+
+			// We create a new function here on every persistent edit
+			// to make sure the edit makes the post dirty and creates
+			// a new undo level.
+			const edits = {
+				selection,
+				content: ( { blocks: blocksForSerialization = [] } ) =>
+					__unstableSerializeAndClean( blocksForSerialization ),
+				...updateFootnotes( newBlocks ),
+			};
+
+			editEntityRecord( kind, name, id, edits, {
+				isCached: false,
+				...rest,
+			} );
+		},
+		[
+			kind,
+			name,
+			id,
+			blocks,
+			updateFootnotes,
+			__unstableCreateUndoLevel,
+			editEntityRecord,
+		]
+	);
+
+	const onInput = useCallback(
+		( newBlocks, options ) => {
+			const { selection, ...rest } = options;
+			const footnotesChanges = updateFootnotes( newBlocks );
+			const edits = { selection, ...footnotesChanges };
+
+			editEntityRecord( kind, name, id, edits, {
+				isCached: true,
+				...rest,
+			} );
+		},
+		[ kind, name, id, updateFootnotes, editEntityRecord ]
+	);
+
+	return [ blocks, onInput, onChange ];
+}

package/src/hooks/use-entity-id.js

@@ -0,0 +1,21 @@
+/**
+ * WordPress dependencies
+ */
+import { useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { EntityContext } from '../entity-context';
+
+/**
+ * Hook that returns the ID for the nearest
+ * provided entity of the specified type.
+ *
+ * @param {string} kind The entity kind.
+ * @param {string} name The entity name.
+ */
+export default function useEntityId( kind, name ) {
+	const context = useContext( EntityContext );
+	return context?.[ kind ]?.[ name ];
+}

package/src/hooks/use-entity-prop.js

@@ -0,0 +1,60 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
+import { useDispatch, useSelect } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { STORE_NAME } from '../name';
+import useEntityId from './use-entity-id';
+
+/**
+ * Hook that returns the value and a setter for the
+ * specified property of the nearest provided
+ * entity of the specified type.
+ *
+ * @param {string} kind  The entity kind.
+ * @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.
+ *
+ * @return {[*, Function, *]} An array where the first item is the
+ *                            property value, the second is the
+ *                            setter and the third is the full value
+ * 							  object from REST API containing more
+ * 							  information like `raw`, `rendered` and
+ * 							  `protected` props.
+ */
+export default function useEntityProp( kind, name, prop, _id ) {
+	const providerId = useEntityId( kind, name );
+	const id = _id ?? providerId;
+
+	const { value, fullValue } = useSelect(
+		( select ) => {
+			const { getEntityRecord, getEditedEntityRecord } =
+				select( STORE_NAME );
+			const record = getEntityRecord( kind, name, id ); // Trigger resolver.
+			const editedRecord = getEditedEntityRecord( kind, name, id );
+			return record && editedRecord
+				? {
+						value: editedRecord[ prop ],
+						fullValue: record[ prop ],
+				  }
+				: {};
+		},
+		[ kind, name, id, prop ]
+	);
+	const { editEntityRecord } = useDispatch( STORE_NAME );
+	const setValue = useCallback(
+		( newValue ) => {
+			editEntityRecord( kind, name, id, {
+				[ prop ]: newValue,
+			} );
+		},
+		[ editEntityRecord, kind, name, id, prop ]
+	);
+
+	return [ value, setValue, fullValue ];
+}

package/src/hooks/use-entity-records.ts

@@ -4,6 +4,7 @@
 import { addQueryArgs } from '@wordpress/url';
 import deprecated from '@wordpress/deprecated';
 import { useSelect } from '@wordpress/data';
+import { useMemo } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -12,6 +13,7 @@ import useQuerySelect from './use-query-select';
 import { store as coreStore } from '../';
 import type { Options } from './use-entity-record';
 import type { Status } from './constants';
+import { unlock } from '../lock-unlock';
 
 interface EntityRecordsResolution< RecordType > {
 	/** The requested entity record */
@@ -152,3 +154,51 @@ export function __experimentalUseEntityRecords(
 	} );
 	return useEntityRecords( kind, name, queryArgs, options );
 }
+
+export function useEntityRecordsWithPermissions< RecordType >(
+	kind: string,
+	name: string,
+	queryArgs: Record< string, unknown > = {},
+	options: Options = { enabled: true }
+): EntityRecordsResolution< RecordType > {
+	const entityConfig = useSelect(
+		( select ) => select( coreStore ).getEntityConfig( kind, name ),
+		[ kind, name ]
+	);
+	const { records: data, ...ret } = useEntityRecords(
+		kind,
+		name,
+		queryArgs,
+		options
+	);
+	const ids = useMemo(
+		() =>
+			data?.map(
+				// @ts-ignore
+				( record: RecordType ) => record[ entityConfig?.key ?? 'id' ]
+			) ?? [],
+		[ data, entityConfig?.key ]
+	);
+
+	const permissions = useSelect(
+		( select ) => {
+			const { getEntityRecordsPermissions } = unlock(
+				select( coreStore )
+			);
+			return getEntityRecordsPermissions( kind, name, ids );
+		},
+		[ ids, kind, name ]
+	);
+
+	const dataWithPermissions = useMemo(
+		() =>
+			data?.map( ( record, index ) => ( {
+				// @ts-ignore
+				...record,
+				permissions: permissions[ index ],
+			} ) ) ?? [],
+		[ data, permissions ]
+	);
+
+	return { records: dataWithPermissions, ...ret };
+}

package/src/hooks/use-resource-permissions.ts

@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import deprecated from '@wordpress/deprecated';
+import warning from '@wordpress/warning';
 
 /**
  * Internal dependencies
@@ -41,20 +42,34 @@ type ResourcePermissionsResolution< IdType > = [
 		( IdType extends void ? SpecificResourcePermissionsResolution : {} ),
 ];
 
+type EntityResource = { kind: string; name: string; id?: string | number };
+
+function useResourcePermissions< IdType = void >(
+	resource: string,
+	id?: IdType
+): ResourcePermissionsResolution< IdType >;
+
+function useResourcePermissions< IdType = void >(
+	resource: EntityResource,
+	id?: never
+): ResourcePermissionsResolution< IdType >;
+
 /**
  * Resolves resource permissions.
  *
  * @since 6.1.0 Introduced in WordPress core.
  *
- * @param    resource The resource in question, e.g. media.
- * @param    id       ID of a specific resource entry, if needed, e.g. 10.
+ * @param    resource Entity resource to check. Accepts entity object `{ kind: 'root', name: 'media', id: 1 }`
+ *                    or REST base as a string - `media`.
+ * @param    id       Optional ID of the resource to check, e.g. 10. Note: This argument is discouraged
+ *                    when using an entity object as a resource to check permissions and will be ignored.
  *
  * @example
  * ```js
  * import { useResourcePermissions } from '@wordpress/core-data';
  *
  * function PagesList() {
- *   const { canCreate, isResolving } = useResourcePermissions( 'pages' );
+ *   const { canCreate, isResolving } = useResourcePermissions( { kind: 'postType', name: 'page' } );
  *
  *   if ( isResolving ) {
  *     return 'Loading ...';
@@ -82,7 +97,7 @@ type ResourcePermissionsResolution< IdType > = [
  *     canUpdate,
  *     canDelete,
  *     isResolving
- *   } = useResourcePermissions( 'pages', pageId );
+ *   } = useResourcePermissions( { kind: 'postType', name: 'page', id: pageId } );
  *
  *   if ( isResolving ) {
  *     return 'Loading ...';
@@ -109,15 +124,35 @@ type ResourcePermissionsResolution< IdType > = [
  * @return Entity records data.
  * @template IdType
  */
-export default function useResourcePermissions< IdType = void >(
-	resource: string,
+function useResourcePermissions< IdType = void >(
+	resource: string | EntityResource,
 	id?: IdType
 ): ResourcePermissionsResolution< IdType > {
+	// Serialize `resource` to a string that can be safely used as a React dep.
+	// We can't just pass `resource` as one of the deps, because if it is passed
+	// as an object literal, then it will be a different object on each call even
+	// if the values remain the same.
+	const isEntity = typeof resource === 'object';
+	const resourceAsString = isEntity ? JSON.stringify( resource ) : resource;
+
+	if ( isEntity && typeof id !== 'undefined' ) {
+		warning(
+			`When 'resource' is an entity object, passing 'id' as a separate argument isn't supported.`
+		);
+	}
+
 	return useQuerySelect(
 		( resolve ) => {
+			const hasId = isEntity ? !! resource.id : !! id;
 			const { canUser } = resolve( coreStore );
-			const create = canUser( 'create', resource );
-			if ( ! id ) {
+			const create = canUser(
+				'create',
+				isEntity
+					? { kind: resource.kind, name: resource.name }
+					: resource
+			);
+
+			if ( ! hasId ) {
 				const read = canUser( 'read', resource );
 
 				const isResolving = create.isResolving || read.isResolving;
@@ -168,10 +203,12 @@ export default function useResourcePermissions< IdType = void >(
 				canDelete: hasResolved && _delete.data,
 			};
 		},
-		[ resource, id ]
+		[ resourceAsString, id ]
 	);
 }
 
+export default useResourcePermissions;
+
 export function __experimentalUseResourcePermissions(
 	resource: string,
 	id?: unknown

package/src/index.js

@@ -18,7 +18,7 @@ import {
 	getMethodName,
 } from './entities';
 import { STORE_NAME } from './name';
-import { unlock } from './private-apis';
+import { unlock } from './lock-unlock';
 
 // The entity selectors/resolvers and actions are shortcuts to their generic equivalents
 // (getEntityRecord, getEntityRecords, updateEntityRecord, updateEntityRecords)
@@ -86,3 +86,4 @@ export * from './entity-provider';
 export * from './entity-types';
 export * from './fetch';
 export * from './hooks';
+export * from './private-apis';

package/src/lock-unlock.js

@@ -0,0 +1,10 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.',
+		'@wordpress/core-data'
+	);

package/src/private-apis.js

@@ -1,10 +1,10 @@
 /**
- * WordPress dependencies
+ * Internal dependencies
  */
-import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+import { useEntityRecordsWithPermissions } from './hooks/use-entity-records';
+import { lock } from './lock-unlock';
 
-export const { lock, unlock } =
-	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
-		'I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.',
-		'@wordpress/core-data'
-	);
+export const privateApis = {};
+lock( privateApis, {
+	useEntityRecordsWithPermissions,
+} );

package/src/private-selectors.ts

@@ -50,3 +50,46 @@ export const getBlockPatternsForPostType = createRegistrySelector(
 			() => [ select( STORE_NAME ).getBlockPatterns() ]
 		)
 );
+
+/**
+ * Returns the entity records permissions for the given entity record ids.
+ */
+export const getEntityRecordsPermissions = createRegistrySelector( ( select ) =>
+	createSelector(
+		( state: State, kind: string, name: string, ids: string[] ) => {
+			const normalizedIds = Array.isArray( ids ) ? ids : [ ids ];
+			return normalizedIds.map( ( id ) => ( {
+				delete: select( STORE_NAME ).canUser( 'delete', {
+					kind,
+					name,
+					id,
+				} ),
+				update: select( STORE_NAME ).canUser( 'update', {
+					kind,
+					name,
+					id,
+				} ),
+			} ) );
+		},
+		( state ) => [ state.userPermissions ]
+	)
+);
+
+/**
+ * Returns the entity record permissions for the given entity record id.
+ *
+ * @param state Data state.
+ * @param kind  Entity kind.
+ * @param name  Entity name.
+ * @param id    Entity record id.
+ *
+ * @return The entity record permissions.
+ */
+export function getEntityRecordPermissions(
+	state: State,
+	kind: string,
+	name: string,
+	id: string
+) {
+	return getEntityRecordsPermissions( state, kind, name, id )[ 0 ];
+}