@wordpress/block-library 11.0.2-next.v.202609171837.0 → 11.2.0

package/src/navigation-link/link-ui/test/get-suggestions-query.jsdom.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { getSuggestionsQuery } from '..';
+
+const PER_PAGE = 20;
+
+const LINK_TYPES = [
+	[ 'page', 'post-type', { type: 'post', subtype: 'page' } ],
+	[ 'post', 'post-type', { type: 'post', subtype: 'post' } ],
+	[ 'category', 'taxonomy', { type: 'term', subtype: 'category' } ],
+	[ 'tag', 'taxonomy', { type: 'term', subtype: 'post_tag' } ],
+	[ 'post_format', 'taxonomy', { type: 'post-format' } ],
+	[ 'event', 'post-type', { type: 'post', subtype: 'event' } ],
+	[ 'genre', 'taxonomy', { type: 'term', subtype: 'genre' } ],
+];
+
+describe( 'getSuggestionsQuery', () => {
+	// A typed search is unscoped: naming no type leaves every endpoint to
+	// answer it, which is what lets a category be found from a page link.
+	it.each( LINK_TYPES )(
+		'searches every entity type from a %s link',
+		( type, kind ) => {
+			const query = getSuggestionsQuery( type, kind );
+
+			expect( query.type ).toBeUndefined();
+			expect( query.subtype ).toBeUndefined();
+		}
+	);
+
+	// Searching everything only helps if the link's own kind leads, so the
+	// block names it rather than narrowing to it.
+	it.each( LINK_TYPES )(
+		'ranks the %s link’s own type above the usual order',
+		( type, kind, expected ) => {
+			expect( getSuggestionsQuery( type, kind ).preferTypes ).toEqual( [
+				expected.subtype ? expected : expected.type,
+			] );
+		}
+	);
+
+	// Before anything is typed there is nothing to rank, so the preview is
+	// narrowed to the link's own type instead.
+	it.each( LINK_TYPES )(
+		'suggests the %s link’s own type before anything is typed',
+		( type, kind, expected ) => {
+			expect(
+				getSuggestionsQuery( type, kind )
+					.initialSuggestionsSearchOptions
+			).toEqual( { ...expected, perPage: PER_PAGE } );
+		}
+	);
+
+	// A custom link points at a URL, and a link just inserted has no type at
+	// all, so neither has a kind of its own to preview. Pages are the most
+	// likely thing to link to.
+	it.each( [
+		[ 'a custom link', 'custom', 'custom' ],
+		[ 'a link with no type', undefined, undefined ],
+	] )(
+		'suggests pages before anything is typed for %s',
+		( _label, type, kind ) => {
+			expect(
+				getSuggestionsQuery( type, kind )
+					.initialSuggestionsSearchOptions
+			).toEqual( { type: 'post', subtype: 'page', perPage: PER_PAGE } );
+		}
+	);
+} );

package/src/navigation-link/shared/controls.jsx

@@ -2,7 +2,7 @@ import {
 	Button,
 	__experimentalToolsPanel as ToolsPanel,
 	__experimentalToolsPanelItem as ToolsPanelItem,
-	CheckboxControl,
+	CheckboxControl as WCCheckboxControl,
 	TextControl,
 	TextareaControl as WCTextareaControl,
 } from '@wordpress/components';
@@ -214,7 +214,7 @@ export function Controls( {
 						}
 						isShownByDefault
 					>
-						<CheckboxControl
+						<WCCheckboxControl
 							label={ __( 'Open in new tab' ) }
 							checked={ opensInNewTab }
 							onChange={ ( value ) =>

package/src/navigation-link/shared/index.js

@@ -19,3 +19,7 @@ export { useEnableLinkStatusValidation } from './use-enable-link-status-validati
 export { useIsDraggingWithin } from './use-is-dragging-within';
 export { selectLabelText } from './select-label-text';
 export { useLinkPreview } from './use-link-preview';
+export {
+	isBlockSuggestion,
+	useBlockSuggestions,
+} from './use-block-suggestions';

package/src/navigation-link/shared/test/use-block-suggestions.jsdom.test.js

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest';
+import { BlockIcon } from '@wordpress/block-editor';
+import {
+	addBlockSuggestions,
+	BLOCK_SUGGESTION_TYPE,
+	isBlockSuggestion,
+} from '../use-block-suggestions';
+
+const homeLink = {
+	id: 'core/home-link',
+	name: 'core/home-link',
+	title: 'Home Link',
+	icon: { src: 'home' },
+};
+const pageList = {
+	id: 'core/page-list',
+	name: 'core/page-list',
+	title: 'Page List',
+	icon: { src: 'list' },
+	keywords: [ 'menu', 'navigation' ],
+};
+const pageLinkVariation = {
+	id: 'core/navigation-link/page',
+	name: 'core/navigation-link',
+	title: 'Page Link',
+	icon: { src: 'page' },
+};
+const homePage = {
+	id: 1,
+	title: 'Home Office',
+	type: 'page',
+	kind: 'post-type',
+	url: '/home-office',
+};
+const menuPage = {
+	id: 2,
+	title: 'Menu',
+	type: 'page',
+	kind: 'post-type',
+	url: '/menu',
+};
+
+describe( 'addBlockSuggestions', () => {
+	it( 'describes a block as a suggestion that is not a link', () => {
+		const [ suggestion ] = addBlockSuggestions( [], [ homeLink ], 'Home' );
+
+		expect( suggestion ).toEqual( {
+			id: 'core/home-link',
+			blockItemId: 'core/home-link',
+			type: BLOCK_SUGGESTION_TYPE,
+			title: 'Home Link',
+			icon: expect.anything(),
+			typeLabel: 'Block',
+		} );
+	} );
+
+	// LinkControl renders an icon it is given as is, so the block's icon
+	// object is turned into an element here, where blocks are known about.
+	it( 'renders the block icon the way the inserter does', () => {
+		const [ suggestion ] = addBlockSuggestions( [], [ homeLink ], 'Home' );
+
+		expect( suggestion.icon.type ).toBe( BlockIcon );
+		expect( suggestion.icon.props.icon ).toBe( homeLink.icon );
+	} );
+
+	it( 'puts a block whose title starts with the search before the links', () => {
+		const suggestions = addBlockSuggestions(
+			[ homePage ],
+			[ homeLink ],
+			'home'
+		);
+
+		expect( suggestions.map( ( { title } ) => title ) ).toEqual( [
+			'Home Link',
+			'Home Office',
+		] );
+	} );
+
+	it( 'puts a block that matches any other way after the links', () => {
+		// Page List matches "menu" by keyword, not by title.
+		const suggestions = addBlockSuggestions(
+			[ menuPage ],
+			[ pageList ],
+			'menu'
+		);
+
+		expect( suggestions.map( ( { title } ) => title ) ).toEqual( [
+			'Menu',
+			'Page List',
+		] );
+	} );
+
+	it( 'leaves out the link variations, which the links already cover', () => {
+		const suggestions = addBlockSuggestions(
+			[],
+			[ pageLinkVariation ],
+			'page'
+		);
+
+		expect( suggestions ).toEqual( [] );
+	} );
+
+	it( 'leaves out blocks that cannot be inserted', () => {
+		const suggestions = addBlockSuggestions(
+			[],
+			[ { ...homeLink, isDisabled: true } ],
+			'home'
+		);
+
+		expect( suggestions ).toEqual( [] );
+	} );
+
+	it( 'adds every block that matches', () => {
+		const items = Array.from( { length: 5 }, ( _, index ) => ( {
+			id: `test/home-${ index }`,
+			name: `test/home-${ index }`,
+			title: `Home ${ index }`,
+		} ) );
+
+		expect( addBlockSuggestions( [], items, 'home' ) ).toHaveLength( 5 );
+	} );
+
+	it( 'returns the links unchanged when no block matches', () => {
+		const suggestions = [ homePage ];
+
+		expect(
+			addBlockSuggestions( suggestions, [ homeLink ], 'office' )
+		).toBe( suggestions );
+	} );
+
+	it( 'returns the links unchanged when nothing is searched', () => {
+		const suggestions = [ homePage ];
+
+		expect( addBlockSuggestions( suggestions, [ homeLink ], '' ) ).toBe(
+			suggestions
+		);
+	} );
+
+	// A site can register a post type called "block", whose results arrive
+	// with that type, so a block is recognized by something only it carries.
+	it( 'tells a block apart from a post of a type called "block"', () => {
+		const [ blockSuggestion ] = addBlockSuggestions(
+			[],
+			[ homeLink ],
+			'Home'
+		);
+		const postOfTypeBlock = {
+			id: 12,
+			title: 'Home',
+			type: 'block',
+			kind: 'post-type',
+			url: '/block/home',
+		};
+
+		expect( isBlockSuggestion( blockSuggestion ) ).toBe( true );
+		expect( isBlockSuggestion( postOfTypeBlock ) ).toBe( false );
+	} );
+} );

package/src/navigation-link/shared/test/use-entity-binding.jsdom.test.js

@@ -326,10 +326,6 @@ describe( 'useEntityBinding', () => {
 		} );
 
 		it( 'handles invalid kind gracefully in createBinding', () => {
-			const consoleSpy = vi
-				.spyOn( console, 'warn' )
-				.mockImplementation( () => {} );
-
 			const attributes = {
 				metadata: {},
 				id: null,
@@ -347,15 +343,13 @@ describe( 'useEntityBinding', () => {
 				result.current.createBinding();
 			} );
 
-			expect( consoleSpy ).toHaveBeenCalledWith(
+			expect( console ).toHaveWarnedWith(
 				'Failed to create entity binding:',
 				expect.stringContaining( 'Invalid kind "invalid-kind"' )
 			);
 
 			// Should not call updateBlockBindings when validation fails
 			expect( mockUpdateBlockBindings ).not.toHaveBeenCalled();
-
-			consoleSpy.mockRestore();
 		} );
 	} );
 } );

package/src/navigation-link/shared/test/use-link-preview.jsdom.test.js

@@ -208,7 +208,7 @@ describe( 'computeBadges', () => {
 
 			expect( badges ).toContainEqual( {
 				label: 'External link',
-				intent: 'default',
+				intent: 'none',
 			} );
 		} );
 
@@ -221,7 +221,7 @@ describe( 'computeBadges', () => {
 
 			expect( badges ).toContainEqual( {
 				label: 'Page',
-				intent: 'default',
+				intent: 'none',
 			} );
 		} );
 
@@ -233,7 +233,7 @@ describe( 'computeBadges', () => {
 
 			expect( badges ).toContainEqual( {
 				label: 'Internal link',
-				intent: 'default',
+				intent: 'none',
 			} );
 		} );
 
@@ -245,7 +245,7 @@ describe( 'computeBadges', () => {
 
 			expect( badges ).toContainEqual( {
 				label: 'Homepage',
-				intent: 'default',
+				intent: 'none',
 			} );
 		} );
 
@@ -262,7 +262,7 @@ describe( 'computeBadges', () => {
 			} );
 			expect( badges ).toContainEqual( {
 				label: 'Homepage',
-				intent: 'default',
+				intent: 'none',
 			} );
 		} );
 
@@ -276,7 +276,7 @@ describe( 'computeBadges', () => {
 				} );
 				expect( badges ).not.toContainEqual( {
 					label: 'Homepage',
-					intent: 'default',
+					intent: 'none',
 				} );
 			}
 		);
@@ -293,7 +293,7 @@ describe( 'computeBadges', () => {
 				} );
 				expect( badges ).toContainEqual( {
 					label: 'Homepage',
-					intent: 'default',
+					intent: 'none',
 				} );
 			}
 		);
@@ -306,7 +306,7 @@ describe( 'computeBadges', () => {
 
 			expect( badges ).toContainEqual( {
 				label: 'Page',
-				intent: 'default',
+				intent: 'none',
 			} );
 		} );
 	} );
@@ -319,7 +319,7 @@ describe( 'computeBadges', () => {
 
 			expect( badges ).toContainEqual( {
 				label: 'No link selected',
-				intent: 'error',
+				intent: 'high',
 			} );
 		} );
 
@@ -333,7 +333,7 @@ describe( 'computeBadges', () => {
 
 			expect( badges ).toContainEqual( {
 				label: 'Missing page',
-				intent: 'error',
+				intent: 'high',
 			} );
 		} );
 
@@ -346,7 +346,7 @@ describe( 'computeBadges', () => {
 
 			expect( badges ).toContainEqual( {
 				label: 'Published',
-				intent: 'success',
+				intent: 'stable',
 			} );
 		} );
 
@@ -359,7 +359,7 @@ describe( 'computeBadges', () => {
 
 			expect( badges ).toContainEqual( {
 				label: 'Draft',
-				intent: 'warning',
+				intent: 'low',
 			} );
 		} );
 	} );
@@ -375,12 +375,12 @@ it( 'should show "Internal link" badge for hash links even when type is present'
 	// Should prioritize hash link detection over type
 	expect( badges ).toContainEqual( {
 		label: 'Internal link',
-		intent: 'default',
+		intent: 'none',
 	} );
 	// Should NOT show Page badge
 	expect( badges ).not.toContainEqual( {
 		label: 'Page',
-		intent: 'default',
+		intent: 'none',
 	} );
 } );
 
@@ -394,12 +394,12 @@ it( 'should show "Homepage" badge for root path even when type is present', () =
 	// Should prioritize homepage detection over type
 	expect( badges ).toContainEqual( {
 		label: 'Homepage',
-		intent: 'default',
+		intent: 'none',
 	} );
 	// Should NOT show Page badge
 	expect( badges ).not.toContainEqual( {
 		label: 'Page',
-		intent: 'default',
+		intent: 'none',
 	} );
 } );
 
@@ -420,12 +420,12 @@ test.each( [
 		// Should prioritize external link detection over type
 		expect( badges ).toContainEqual( {
 			label: 'External link',
-			intent: 'default',
+			intent: 'none',
 		} );
 		// Should NOT show Page badge
 		expect( badges ).not.toContainEqual( {
 			label: 'Page',
-			intent: 'default',
+			intent: 'none',
 		} );
 	}
 );
@@ -440,12 +440,12 @@ it( 'should show "Page" badge for internal custom links', () => {
 	// Should show Page badge for internal custom links
 	expect( badges ).toContainEqual( {
 		label: 'Page',
-		intent: 'default',
+		intent: 'none',
 	} );
 	// Should NOT show Custom badge
 	expect( badges ).not.toContainEqual( {
 		label: 'Custom',
-		intent: 'default',
+		intent: 'none',
 	} );
 } );
 
@@ -644,7 +644,7 @@ describe( 'useLinkPreview', () => {
 
 			expect( result.current.badges ).toContainEqual( {
 				label: 'No link selected',
-				intent: 'error',
+				intent: 'high',
 			} );
 		} );
 
@@ -676,7 +676,7 @@ describe( 'useLinkPreview', () => {
 
 			expect( result.current.badges ).toContainEqual( {
 				label: 'Missing page',
-				intent: 'error',
+				intent: 'high',
 			} );
 		} );
 

package/src/navigation-link/shared/use-block-suggestions.js

@@ -0,0 +1,192 @@
+import { __, sprintf } from '@wordpress/i18n';
+import { speak } from '@wordpress/a11y';
+import { createElement, useCallback } from '@wordpress/element';
+import { useDispatch, useSelect } from '@wordpress/data';
+import {
+	createBlock,
+	createBlocksFromInnerBlocksTemplate,
+} from '@wordpress/blocks';
+import {
+	BlockIcon,
+	store as blockEditorStore,
+	privateApis as blockEditorPrivateApis,
+} from '@wordpress/block-editor';
+import { unlock } from '../../lock-unlock';
+
+const { searchItems, normalizeString } = unlock( blockEditorPrivateApis );
+
+/**
+ * The `type` of a suggestion that inserts a block rather than setting a link.
+ */
+export const BLOCK_SUGGESTION_TYPE = 'block';
+
+/**
+ * Whether a suggestion inserts a block rather than setting a link.
+ *
+ * The `type` alone is not enough: a site can register a post type called
+ * "block", whose results arrive with that type. Only a block suggestion
+ * carries the inserter item it was made from.
+ *
+ * @param {Object} suggestion A link suggestion.
+ * @return {boolean} Whether it is a block suggestion.
+ */
+export function isBlockSuggestion( suggestion ) {
+	return (
+		suggestion?.type === BLOCK_SUGGESTION_TYPE &&
+		typeof suggestion.blockItemId === 'string'
+	);
+}
+
+/**
+ * The link variations are left out: searching already finds the pages, posts
+ * and terms they would link to.
+ */
+const EXCLUDED_BLOCK_NAMES = [ 'core/navigation-link' ];
+
+// Match on what a block is called, not on its description or category, which
+// would list blocks for words that only happen to describe them.
+const SEARCH_FIELDS = [
+	{ get: ( item ) => item.title },
+	{ get: ( item ) => item.keywords },
+];
+
+/**
+ * Adds the blocks that match a search to the link suggestions.
+ *
+ * A block whose title starts with the search is what was asked for by name,
+ * so it goes before the links. Any other matching block goes after them.
+ *
+ * @param {Array}  suggestions Link suggestions.
+ * @param {Array}  blockItems  Inserter items the Navigation allows.
+ * @param {string} searchTerm  What the user typed.
+ * @return {Array} The suggestions, with any matching blocks added.
+ */
+export function addBlockSuggestions( suggestions, blockItems, searchTerm ) {
+	if ( ! searchTerm?.trim() ) {
+		return suggestions;
+	}
+
+	const matches = searchItems( blockItems, searchTerm, {
+		fields: SEARCH_FIELDS,
+		filter: ( item ) =>
+			! item.isDisabled && ! EXCLUDED_BLOCK_NAMES.includes( item.name ),
+	} );
+
+	if ( ! matches.length ) {
+		return suggestions;
+	}
+
+	const search = normalizeString( searchTerm.trim() );
+	const before = [];
+	const after = [];
+
+	for ( const item of matches ) {
+		const suggestion = {
+			id: item.id,
+			blockItemId: item.id,
+			type: BLOCK_SUGGESTION_TYPE,
+			title: item.title,
+			icon: createElement( BlockIcon, { icon: item.icon } ),
+			typeLabel: __( 'Block' ),
+		};
+
+		if ( normalizeString( item.title ).startsWith( search ) ) {
+			before.push( suggestion );
+		} else {
+			after.push( suggestion );
+		}
+	}
+
+	return [ ...before, ...suggestions, ...after ];
+}
+
+/**
+ * Lists the blocks a Navigation allows in a link's search results, and
+ * inserts the one that is chosen.
+ *
+ * The allowed blocks are read when a search runs, not subscribed to, so an
+ * open link UI does no work as the editor changes.
+ *
+ * @param {Object}    options               Hook options.
+ * @param {string}    options.clientId      Client ID of the link or submenu.
+ * @param {boolean}   options.isEnabled     Whether to list blocks at all.
+ * @param {Function=} options.onBlockInsert Called with the inserted block by a
+ *                                          caller that tracks the new link,
+ *                                          such as the list view.
+ * @param {Function=} options.onClose       Closes the link UI.
+ * @return {{ transformSuggestions: Function|undefined, insertBlockFromSuggestion: Function }}
+ * The `transformSuggestions` to give LinkControl, and the handler for a chosen
+ * block suggestion.
+ */
+export function useBlockSuggestions( {
+	clientId,
+	isEnabled,
+	onBlockInsert,
+	onClose,
+} ) {
+	const {
+		getBlockIndex,
+		getBlockOrder,
+		getBlockRootClientId,
+		getInserterItems,
+	} = useSelect( blockEditorStore );
+	const { insertBlock, replaceBlock } = useDispatch( blockEditorStore );
+
+	const transformSuggestions = useCallback(
+		( suggestions, { isInitialSuggestions, searchTerm } ) =>
+			isInitialSuggestions
+				? suggestions
+				: addBlockSuggestions(
+						suggestions,
+						getInserterItems( getBlockRootClientId( clientId ) ),
+						searchTerm
+					),
+		[ clientId, getBlockRootClientId, getInserterItems ]
+	);
+
+	const insertBlockFromSuggestion = ( itemId ) => {
+		const rootClientId = getBlockRootClientId( clientId );
+		const item = getInserterItems( rootClientId ).find(
+			( { id } ) => id === itemId
+		);
+
+		if ( ! item ) {
+			return;
+		}
+
+		const block = createBlock(
+			item.name,
+			item.initialAttributes,
+			createBlocksFromInnerBlocksTemplate( item.innerBlocks )
+		);
+		const index = getBlockIndex( clientId );
+
+		if ( onBlockInsert ) {
+			// A caller that tracks the new link, such as the list view, removes
+			// it itself once told about the block, as with the "Add block" pane.
+			insertBlock( block, index, rootClientId, false );
+			onBlockInsert( block );
+		} else if ( getBlockOrder( clientId ).length ) {
+			// A submenu keeps its items, so the block goes before it, where the
+			// "Add block" pane puts it.
+			insertBlock( block, index, rootClientId );
+			onClose?.();
+		} else {
+			// An empty link is replaced by the block.
+			replaceBlock( clientId, block );
+		}
+
+		speak(
+			sprintf(
+				/* translators: %s: The title of the block that was added. */
+				__( '%s block added.' ),
+				item.title
+			)
+		);
+	};
+
+	return {
+		transformSuggestions: isEnabled ? transformSuggestions : undefined,
+		insertBlockFromSuggestion,
+	};
+}