Stabilize the useResourcePermissions hook (#43268)

Originally introduced in Pull Request #38785

packages/block-library/src/navigation-link/edit.js

@@ -44,7 +44,7 @@ import { placeCaretAtHorizontalEdge } from '@wordpress/dom';
 import { link as linkIcon, addSubmenu } from '@wordpress/icons';
 import {
 	store as coreStore,
-	__experimentalUseResourcePermissions as useResourcePermissions,
+	useResourcePermissions,
 } from '@wordpress/core-data';
 import { decodeEntities } from '@wordpress/html-entities';
 

packages/block-library/src/navigation-submenu/edit.js

@@ -40,7 +40,7 @@ import {
 import { placeCaretAtHorizontalEdge } from '@wordpress/dom';
 import { link as linkIcon, removeSubmenu } from '@wordpress/icons';
 import {
-	__experimentalUseResourcePermissions as useResourcePermissions,
+	useResourcePermissions,
 	store as coreStore,
 } from '@wordpress/core-data';
 import { speak } from '@wordpress/a11y';

packages/block-library/src/navigation/use-navigation-menu.js

@@ -3,7 +3,7 @@
  */
 import {
 	store as coreStore,
-	__experimentalUseResourcePermissions as useResourcePermissions,
+	useResourcePermissions,
 } from '@wordpress/core-data';
 import { useSelect } from '@wordpress/data';
 

packages/core-data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### New Features
+
+-   Stabilized the `useResourcePermissions` hook ([#43268](https://github.com/WordPress/gutenberg/pull/43268))
+
 ## 4.13.0 (2022-08-10)
 
 ## 4.12.0 (2022-07-27)

packages/core-data/README.md

@@ -875,6 +875,72 @@ _Returns_
 
 -   `EntityRecordsResolution< RecordType >`: Entity records data.
 
+### useResourcePermissions
+
+Resolves resource permissions.
+
+_Usage_
+
+```js
+import { useResourcePermissions } from '@wordpress/core-data';
+
+function PagesList() {
+	const { canCreate, isResolving } = useResourcePermissions( 'pages' );
+
+	if ( isResolving ) {
+		return 'Loading ...';
+	}
+
+	return (
+		<div>
+			{ canCreate ? <button>+ Create a new page</button> : false }
+			// ...
+		</div>
+	);
+}
+
+// Rendered in the application:
+// <PagesList />
+```
+
+```js
+import { useResourcePermissions } from '@wordpress/core-data';
+
+function Page( { pageId } ) {
+	const { canCreate, canUpdate, canDelete, isResolving } =
+		useResourcePermissions( 'pages', pageId );
+
+	if ( isResolving ) {
+		return 'Loading ...';
+	}
+
+	return (
+		<div>
+			{ canCreate ? <button>+ Create a new page</button> : false }
+			{ canUpdate ? <button>Edit page</button> : false }
+			{ canDelete ? <button>Delete page</button> : false }
+			// ...
+		</div>
+	);
+}
+
+// Rendered in the application:
+// <Page pageId={ 15 } />
+```
+
+In the above example, when `PagesList` is rendered into an
+application, the appropriate permissions and the resolution details will be retrieved from
+the store state using `canUser()`, or resolved if missing.
+
+_Parameters_
+
+-   _resource_ `string`: The resource in question, e.g. media.
+-   _id_ `IdType`: ID of a specific resource entry, if needed, e.g. 10.
+
+_Returns_
+
+-   `ResourcePermissionsResolution< IdType >`: Entity records data.
+
 <!-- END TOKEN(Autogenerated hooks|src/hooks/index.ts) -->
 
 ## Contributing to this package

packages/core-data/src/hooks/index.ts

@@ -6,3 +6,7 @@ export {
 	default as useEntityRecords,
 	__experimentalUseEntityRecords,
 } from './use-entity-records';
+export {
+	default as useResourcePermissions,
+	__experimentalUseResourcePermissions,
+} from './use-resource-permissions';

packages/core-data/src/hooks/use-resource-permissions.ts

@@ -1,3 +1,8 @@
+/**
+ * WordPress dependencies
+ */
+import deprecated from '@wordpress/deprecated';
+
 /**
  * Internal dependencies
  */
@@ -65,14 +70,44 @@ type ResourcePermissionsResolution< IdType > = [
  * // <PagesList />
  * ```
  *
+ * @example
+ * ```js
+ * import { useResourcePermissions } from '@wordpress/core-data';
+ *
+ * function Page({ pageId }) {
+ *   const {
+ *     canCreate,
+ *     canUpdate,
+ *     canDelete,
+ *     isResolving
+ *   } = useResourcePermissions( 'pages', pageId );
+ *
+ *   if ( isResolving ) {
+ *     return 'Loading ...';
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       {canCreate ? (<button>+ Create a new page</button>) : false}
+ *       {canUpdate ? (<button>Edit page</button>) : false}
+ *       {canDelete ? (<button>Delete page</button>) : false}
+ *       // ...
+ *     </div>
+ *   );
+ * }
+ *
+ * // Rendered in the application:
+ * // <Page pageId={ 15 } />
+ * ```
+ *
  * In the above example, when `PagesList` is rendered into an
  * application, the appropriate permissions and the resolution details will be retrieved from
  * the store state using `canUser()`, or resolved if missing.
  *
  * @return Entity records data.
  * @template IdType
  */
-export default function __experimentalUseResourcePermissions< IdType = void >(
+export default function useResourcePermissions< IdType = void >(
 	resource: string,
 	id?: IdType
 ): ResourcePermissionsResolution< IdType > {
@@ -114,3 +149,14 @@ export default function __experimentalUseResourcePermissions< IdType = void >(
 		[ resource, id ]
 	);
 }
+
+export function __experimentalUseResourcePermissions(
+	resource: string,
+	id?: IdType
+) {
+	deprecated( `wp.data.__experimentalUseResourcePermissions`, {
+		alternative: 'wp.data.useResourcePermissions',
+		since: '6.1',
+	} );
+	return useResourcePermissions( resource, id );
+}

packages/core-data/src/index.js

@@ -68,9 +68,6 @@ export const store = createReduxStore( STORE_NAME, storeConfig() );
 register( store );
 
 export { default as EntityProvider } from './entity-provider';
-export { default as useEntityRecord } from './hooks/use-entity-record';
-export { default as useEntityRecords } from './hooks/use-entity-records';
-export { default as __experimentalUseResourcePermissions } from './hooks/use-resource-permissions';
 export * from './entity-provider';
 export * from './entity-types';
 export * from './fetch';

packages/edit-widgets/src/components/widget-areas-block-editor-provider/index.js

@@ -7,7 +7,7 @@ import { useDispatch, useSelect } from '@wordpress/data';
 import {
 	useEntityBlockEditor,
 	store as coreStore,
-	__experimentalUseResourcePermissions as useResourcePermissions,
+	useResourcePermissions,
 } from '@wordpress/core-data';
 import { useMemo } from '@wordpress/element';
 import {