From d61f1904b937f8993ed390b6952f0e7d5966debb Mon Sep 17 00:00:00 2001 From: Vrishabhsk Date: Mon, 6 Jan 2025 11:21:49 +0400 Subject: [PATCH] Improve Docs for useNavigationMenu hook --- .../src/navigation/use-navigation-menu.js | 63 ++++++++++++++----- 1 file changed, 48 insertions(+), 15 deletions(-) diff --git a/packages/block-library/src/navigation/use-navigation-menu.js b/packages/block-library/src/navigation/use-navigation-menu.js index 5fd942c485bf84..0acaea589bc47f 100644 --- a/packages/block-library/src/navigation/use-navigation-menu.js +++ b/packages/block-library/src/navigation/use-navigation-menu.js @@ -13,11 +13,38 @@ import { useSelect } from '@wordpress/data'; */ import { PRELOADED_NAVIGATION_MENUS_QUERY } from './constants'; +/** + * Retrieves comprehensive information about a navigation menu and related permissions. + * + * This hook provides a centralized way to access navigation menu data, user permissions, + * and related states. It's particularly useful for components that need to render or + * manage navigation menus in the WordPress block editor or related interfaces. + * + * @param {number|undefined} ref The post ID of the navigation menu. If undefined, some + * return values will be affected (see return object for details). + * + * @return {Object} An object containing navigation menu data and related states: + * - navigationMenu: The navigation menu post object if it exists and is published or draft, null otherwise. + * - isNavigationMenuResolved: Whether the navigation menu data has finished loading. + * - isNavigationMenuMissing: Whether the specified navigation menu doesn't exist or isn't accessible. + * - navigationMenus: An array of all available navigation menu objects. + * - isResolvingNavigationMenus: Whether the list of navigation menus is still loading. + * - hasResolvedNavigationMenus: Whether the list of navigation menus has finished loading. + * - canSwitchNavigationMenu: Whether there are multiple menus available to switch between. + * - canUserCreateNavigationMenus: Whether the current user has permission to create new navigation menus. + * - isResolvingCanUserCreateNavigationMenus: Whether the create permission is still being checked. + * - hasResolvedCanUserCreateNavigationMenus: Whether the create permission check has completed. + * - canUserUpdateNavigationMenu: Whether the user can update the specified menu. Undefined if no ref provided. + * - hasResolvedCanUserUpdateNavigationMenu: Whether the update permission check has completed. Undefined if no ref provided. + * - canUserDeleteNavigationMenu: Whether the user can delete the specified menu. Undefined if no ref provided. + * - hasResolvedCanUserDeleteNavigationMenu: Whether the delete permission check has completed. Undefined if no ref provided. + */ export default function useNavigationMenu( ref ) { + // Retrieve permissions related to CRUD operations for Navigation Menus. const permissions = useResourcePermissions( { kind: 'postType', name: 'wp_navigation', - id: ref, + id: ref, // Necessary to retrieve update and delete permissions. Defaults to true if not provided. } ); const { @@ -32,14 +59,9 @@ export default function useNavigationMenu( ref ) { ); const { - // Can the user create navigation menus? canCreate: canCreateNavigationMenus, - - // Can the user update the specific navigation menu with the given post ID? - canUpdate: canUpdateNavigationMenu, - - // Can the user delete the specific navigation menu with the given post ID? - canDelete: canDeleteNavigationMenu, + canUpdate: canUpdateNavigationMenu, // undefined if ref is missing. + canDelete: canDeleteNavigationMenu, // undefined if ref is missing. isResolving: isResolvingPermissions, hasResolved: hasResolvedPermissions, } = permissions; @@ -80,6 +102,21 @@ export default function useNavigationMenu( ref ) { }; } +/** + * Selects and retrieves information about an existing navigation menu. + * + * This function uses the WordPress data layer to fetch information about a specific + * navigation menu. It handles both published and draft navigation menus, which is + * particularly useful in the context of the block editor where draft posts are valid. + * + * @param {Function} select The `select` function from the WordPress data store. + * @param {number|undefined} ref The ID of the navigation menu to select. + * + * @return {Object} An object containing information about the navigation menu: + * - isNavigationMenuResolved: Whether the data for the navigation menu has finished loading. + * - isNavigationMenuMissing: Whether the requested navigation menu doesn't exist or isn't accessible. + * - navigationMenu: The navigation menu object if it exists and is published or draft, null otherwise. + */ function selectExistingMenu( select, ref ) { if ( ! ref ) { return { @@ -99,10 +136,9 @@ function selectExistingMenu( select, ref ) { args ); - // Only published Navigation posts are considered valid. - // Draft Navigation posts are valid only on the editor, - // requiring a post update to publish to show in frontend. - // To achieve that, index.php must reflect this validation only for published. + // Only published and draft Navigation posts are considered valid. + // Draft Navigation posts are valid only in the editor context, + // requiring a post update to publish to show in the frontend. const isNavigationMenuPublishedOrDraft = editedNavigationMenu.status === 'publish' || editedNavigationMenu.status === 'draft'; @@ -112,9 +148,6 @@ function selectExistingMenu( select, ref ) { isNavigationMenuMissing: hasResolvedNavigationMenu && ( ! navigationMenu || ! isNavigationMenuPublishedOrDraft ), - - // getEditedEntityRecord will return the post regardless of status. - // Therefore if the found post is not published then we should ignore it. navigationMenu: isNavigationMenuPublishedOrDraft ? editedNavigationMenu : null,