@wordpress/block-editor 12.4.0 → 12.6.0

package/src/store/actions.js

@@ -1,3 +1,4 @@
+/* eslint no-console: [ 'error', { allow: [ 'error', 'warn' ] } ] */
 /**
  * WordPress dependencies
  */
@@ -27,7 +28,6 @@ import {
 } from '../utils/selection';
 import {
 	__experimentalUpdateSettings,
-	ensureDefaultBlock,
 	privateRemoveBlocks,
 } from './private-actions';
 
@@ -402,7 +402,7 @@ export const replaceBlocks =
 			initialPosition,
 			meta,
 		} );
-		dispatch( ensureDefaultBlock() );
+		dispatch.ensureDefaultBlock();
 	};
 
 /**
@@ -1389,7 +1389,9 @@ export function updateBlockListSettings( clientId, settings ) {
  * @return {Object} Action object
  */
 export function updateSettings( settings ) {
-	return __experimentalUpdateSettings( settings, true );
+	return __experimentalUpdateSettings( settings, {
+		stripExperimentalSettings: true,
+	} );
 }
 
 /**
@@ -1692,3 +1694,193 @@ export function __unstableSetTemporarilyEditingAsBlocks(
 		temporarilyEditingAsBlocks,
 	};
 }
+
+/**
+ * Interface for inserter media requests.
+ *
+ * @typedef {Object} InserterMediaRequest
+ * @property {number} per_page How many items to fetch per page.
+ * @property {string} search   The search term to use for filtering the results.
+ */
+
+/**
+ * Interface for inserter media responses. Any media resource should
+ * map their response to this interface, in order to create the core
+ * WordPress media blocks (image, video, audio).
+ *
+ * @typedef {Object} InserterMediaItem
+ * @property {string}        title        The title of the media item.
+ * @property {string}        url          The source url of the media item.
+ * @property {string}        [previewUrl] The preview source url of the media item to display in the media list.
+ * @property {number}        [id]         The WordPress id of the media item.
+ * @property {number|string} [sourceId]   The id of the media item from external source.
+ * @property {string}        [alt]        The alt text of the media item.
+ * @property {string}        [caption]    The caption of the media item.
+ */
+
+/**
+ * Registers a new inserter media category. Once registered, the media category is
+ * available in the inserter's media tab.
+ *
+ * The following interfaces are used:
+ *
+ * _Type Definition_
+ *
+ * - _InserterMediaRequest_ `Object`: Interface for inserter media requests.
+ *
+ * _Properties_
+ *
+ * - _per_page_ `number`: How many items to fetch per page.
+ * - _search_ `string`: The search term to use for filtering the results.
+ *
+ * _Type Definition_
+ *
+ * - _InserterMediaItem_ `Object`: Interface for inserter media responses. Any media resource should
+ * map their response to this interface, in order to create the core
+ * WordPress media blocks (image, video, audio).
+ *
+ * _Properties_
+ *
+ * - _title_ `string`: The title of the media item.
+ * - _url_ `string: The source url of the media item.
+ * - _previewUrl_ `[string]`: The preview source url of the media item to display in the media list.
+ * - _id_ `[number]`: The WordPress id of the media item.
+ * - _sourceId_ `[number|string]`: The id of the media item from external source.
+ * - _alt_ `[string]`: The alt text of the media item.
+ * - _caption_ `[string]`: The caption of the media item.
+ *
+ * @param    {InserterMediaCategory}                                  category                       The inserter media category to register.
+ *
+ * @example
+ * ```js
+ *
+ * wp.data.dispatch('core/block-editor').registerInserterMediaCategory( {
+ * 	 name: 'openverse',
+ * 	 labels: {
+ * 	 	name: 'Openverse',
+ * 	 	search_items: 'Search Openverse',
+ * 	 },
+ * 	 mediaType: 'image',
+ * 	 async fetch( query = {} ) {
+ * 	 	const defaultArgs = {
+ * 	 		mature: false,
+ * 	 		excluded_source: 'flickr,inaturalist,wikimedia',
+ * 	 		license: 'pdm,cc0',
+ * 	 	};
+ * 	 	const finalQuery = { ...query, ...defaultArgs };
+ * 	 	// Sometimes you might need to map the supported request params according to `InserterMediaRequest`.
+ * 	 	// interface. In this example the `search` query param is named `q`.
+ * 	 	const mapFromInserterMediaRequest = {
+ * 	 		per_page: 'page_size',
+ * 	 		search: 'q',
+ * 	 	};
+ * 	 	const url = new URL( 'https://api.openverse.engineering/v1/images/' );
+ * 	 	Object.entries( finalQuery ).forEach( ( [ key, value ] ) => {
+ * 	 		const queryKey = mapFromInserterMediaRequest[ key ] || key;
+ * 	 		url.searchParams.set( queryKey, value );
+ * 	 	} );
+ * 	 	const response = await window.fetch( url, {
+ * 	 		headers: {
+ * 	 			'User-Agent': 'WordPress/inserter-media-fetch',
+ * 	 		},
+ * 	 	} );
+ * 	 	const jsonResponse = await response.json();
+ * 	 	const results = jsonResponse.results;
+ * 	 	return results.map( ( result ) => ( {
+ * 	 		...result,
+ * 	 		// If your response result includes an `id` prop that you want to access later, it should
+ * 	 		// be mapped to `InserterMediaItem`'s `sourceId` prop. This can be useful if you provide
+ * 	 		// a report URL getter.
+ * 	 		// Additionally you should always clear the `id` value of your response results because
+ * 	 		// it is used to identify WordPress media items.
+ * 	 		sourceId: result.id,
+ * 	 		id: undefined,
+ * 	 		caption: result.caption,
+ * 	 		previewUrl: result.thumbnail,
+ * 	 	} ) );
+ * 	 },
+ * 	 getReportUrl: ( { sourceId } ) =>
+ * 	 	`https://wordpress.org/openverse/image/${ sourceId }/report/`,
+ * 	 isExternalResource: true,
+ * } );
+ * ```
+ *
+ * @typedef {Object} InserterMediaCategory Interface for inserter media category.
+ * @property {string}                                                 name                           The name of the media category, that should be unique among all media categories.
+ * @property {Object}                                                 labels                         Labels for the media category.
+ * @property {string}                                                 labels.name                    General name of the media category. It's used in the inserter media items list.
+ * @property {string}                                                 [labels.search_items='Search'] Label for searching items. Default is ‘Search Posts’ / ‘Search Pages’.
+ * @property {('image'|'audio'|'video')}                              mediaType                      The media type of the media category.
+ * @property {(InserterMediaRequest) => Promise<InserterMediaItem[]>} fetch                          The function to fetch media items for the category.
+ * @property {(InserterMediaItem) => string}                          [getReportUrl]                 If the media category supports reporting media items, this function should return
+ *                                                                                                   the report url for the media item. It accepts the `InserterMediaItem` as an argument.
+ * @property {boolean}                                                [isExternalResource]           If the media category is an external resource, this should be set to true.
+ *                                                                                                   This is used to avoid making a request to the external resource when the user
+ *
+ */
+export const registerInserterMediaCategory =
+	( category ) =>
+	( { select, dispatch } ) => {
+		if ( ! category || typeof category !== 'object' ) {
+			console.error(
+				'Category should be an `InserterMediaCategory` object.'
+			);
+			return;
+		}
+		if ( ! category.name ) {
+			console.error(
+				'Category should have a `name` that should be unique among all media categories.'
+			);
+			return;
+		}
+		if ( ! category.labels?.name ) {
+			console.error( 'Category should have a `labels.name`.' );
+			return;
+		}
+		if ( ! [ 'image', 'audio', 'video' ].includes( category.mediaType ) ) {
+			console.error(
+				'Category should have `mediaType` property that is one of `image|audio|video`.'
+			);
+			return;
+		}
+		if ( ! category.fetch || typeof category.fetch !== 'function' ) {
+			console.error(
+				'Category should have a `fetch` function defined with the following signature `(InserterMediaRequest) => Promise<InserterMediaItem[]>`.'
+			);
+			return;
+		}
+		const { inserterMediaCategories = [] } = select.getSettings();
+		if (
+			inserterMediaCategories.some(
+				( { name } ) => name === category.name
+			)
+		) {
+			console.error(
+				`A category is already registered with the same name: "${ category.name }".`
+			);
+			return;
+		}
+		if (
+			inserterMediaCategories.some(
+				( { labels: { name } } ) => name === category.labels?.name
+			)
+		) {
+			console.error(
+				`A category is already registered with the same labels.name: "${ category.labels.name }".`
+			);
+			return;
+		}
+		// `inserterMediaCategories` is a private block editor setting, which means it cannot
+		// be updated through the public `updateSettings` action. We preserve this setting as
+		// private, so extenders can only add new inserter media categories and don't have any
+		// control over the core media categories.
+		dispatch( {
+			type: 'UPDATE_SETTINGS',
+			settings: {
+				inserterMediaCategories: [
+					...inserterMediaCategories,
+					{ ...category, isExternalResource: true },
+				],
+			},
+		} );
+	};

package/src/store/defaults.js

@@ -18,6 +18,7 @@ export const PREFERENCES_DEFAULTS = {
  * @property {number}        maxWidth                               Max width to constraint resizing
  * @property {boolean|Array} allowedBlockTypes                      Allowed block types
  * @property {boolean}       hasFixedToolbar                        Whether or not the editor toolbar is fixed
+ * @property {boolean}       distractionFree                        Whether or not the editor UI is distraction free
  * @property {boolean}       focusMode                              Whether the focus mode is enabled or not
  * @property {Array}         styles                                 Editor Styles
  * @property {boolean}       keepCaretInsideBlock                   Whether caret should move between blocks in edit mode

package/src/store/index.js

@@ -43,3 +43,13 @@ const registeredStore = registerStore( STORE_NAME, {
 } );
 unlock( registeredStore ).registerPrivateActions( privateActions );
 unlock( registeredStore ).registerPrivateSelectors( privateSelectors );
+
+// TODO: Remove once we switch to the `register` function (see above).
+//
+// Until then, private functions also need to be attached to the original
+// `store` descriptor in order to avoid unit tests failing, which could happen
+// when tests create new registries in which they register stores.
+//
+// @see https://github.com/WordPress/gutenberg/pull/51145#discussion_r1239999590
+unlock( store ).registerPrivateActions( privateActions );
+unlock( store ).registerPrivateSelectors( privateSelectors );

package/src/store/private-actions.js

@@ -3,11 +3,6 @@
  */
 import { Platform } from '@wordpress/element';
 
-/**
- * Internal dependencies
- */
-import { blockTypePromptMessages } from '../components/block-removal-warning-modal';
-
 const castArray = ( maybeArray ) =>
 	Array.isArray( maybeArray ) ? maybeArray : [ maybeArray ];
 
@@ -28,13 +23,15 @@ const privateSettings = [
  * Action that updates the block editor settings and
  * conditionally preserves the experimental ones.
  *
- * @param {Object}  settings                  Updated settings
- * @param {boolean} stripExperimentalSettings Whether to strip experimental settings.
+ * @param {Object}  settings                          Updated settings
+ * @param {Object}  options                           Options object.
+ * @param {boolean} options.stripExperimentalSettings Whether to strip experimental settings.
+ * @param {boolean} options.reset                     Whether to reset the settings.
  * @return {Object} Action object
  */
 export function __experimentalUpdateSettings(
 	settings,
-	stripExperimentalSettings = false
+	{ stripExperimentalSettings = false, reset = false } = {}
 ) {
 	let cleanSettings = settings;
 	// There are no plugins in the mobile apps, so there is no
@@ -50,6 +47,7 @@ export function __experimentalUpdateSettings(
 	return {
 		type: 'UPDATE_SETTINGS',
 		settings: cleanSettings,
+		reset,
 	};
 }
 
@@ -155,35 +153,22 @@ export const privateRemoveBlocks =
 		// confirmation that they intended to remove such block(s). However,
 		// the editor instance is responsible for presenting those confirmation
 		// prompts to the user. Any instance opting into removal prompts must
-		// register using `toggleRemovalPromptSupport()`.
+		// register using `setBlockRemovalRules()`.
 		//
 		// @see https://github.com/WordPress/gutenberg/pull/51145
-		if (
-			! forceRemove &&
-			// FIXME: Without this existence check, the unit tests for
-			// `__experimentalDeleteReusableBlock` in
-			// `packages/reusable-blocks/src/store/test/actions.js` fail due to
-			// the fact that the `registry` object passed to the thunk actions
-			// doesn't include this private action. This needs to be
-			// investigated to understand whether it's a real smell or if it's
-			// because not all store code has been updated to accommodate
-			// private selectors.
-			select.isRemovalPromptSupported &&
-			select.isRemovalPromptSupported()
-		) {
+		const rules = ! forceRemove && select.getBlockRemovalRules();
+		if ( rules ) {
 			const blockNamesForPrompt = new Set();
 
 			// Given a list of client IDs of blocks that the user intended to
 			// remove, perform a tree search (BFS) to find all block names
 			// corresponding to "important" blocks, i.e. blocks that require a
 			// removal prompt.
-			//
-			// @see blockTypePromptMessages
 			const queue = [ ...clientIds ];
 			while ( queue.length ) {
 				const clientId = queue.shift();
 				const blockName = select.getBlockName( clientId );
-				if ( blockTypePromptMessages[ blockName ] ) {
+				if ( rules[ blockName ] ) {
 					blockNamesForPrompt.add( blockName );
 				}
 				const innerBlocks = select.getBlockOrder( clientId );
@@ -194,7 +179,7 @@ export const privateRemoveBlocks =
 			// skip any other steps (thus postponing actual removal).
 			if ( blockNamesForPrompt.size ) {
 				dispatch(
-					displayRemovalPrompt(
+					displayBlockRemovalPrompt(
 						clientIds,
 						selectPrevious,
 						Array.from( blockNamesForPrompt )
@@ -246,7 +231,7 @@ export const ensureDefaultBlock =
  * Returns an action object used in signalling that a block removal prompt must
  * be displayed.
  *
- * Contrast with `toggleRemovalPromptSupport`.
+ * Contrast with `setBlockRemovalRules`.
  *
  * @param {string|string[]} clientIds           Client IDs of blocks to remove.
  * @param {boolean}         selectPrevious      True if the previous block
@@ -254,16 +239,19 @@ export const ensureDefaultBlock =
  *                                              (if no previous block exists)
  *                                              should be selected
  *                                              when a block is removed.
- * @param {string[]}        blockNamesForPrompt Names of blocks requiring user
+ * @param {string[]}        blockNamesForPrompt Names of the blocks that
+ *                                              triggered the need for
+ *                                              confirmation before removal.
+ *
  * @return {Object} Action object.
  */
-export function displayRemovalPrompt(
+function displayBlockRemovalPrompt(
 	clientIds,
 	selectPrevious,
 	blockNamesForPrompt
 ) {
 	return {
-		type: 'DISPLAY_REMOVAL_PROMPT',
+		type: 'DISPLAY_BLOCK_REMOVAL_PROMPT',
 		clientIds,
 		selectPrevious,
 		blockNamesForPrompt,
@@ -277,24 +265,36 @@ export function displayRemovalPrompt(
  *
  * @return {Object} Action object.
  */
-export function clearRemovalPrompt() {
+export function clearBlockRemovalPrompt() {
 	return {
-		type: 'CLEAR_REMOVAL_PROMPT',
+		type: 'CLEAR_BLOCK_REMOVAL_PROMPT',
 	};
 }
 
 /**
- * Returns an action object used in signalling that a removal prompt display
- * mechanism is available or unavailable in the current editor.
+ * Returns an action object used to set up any rules that a block editor may
+ * provide in order to prevent a user from accidentally removing certain
+ * blocks. These rules are then used to display a confirmation prompt to the
+ * user. For instance, in the Site Editor, the Query Loop block is important
+ * enough to warrant such confirmation.
+ *
+ * IMPORTANT: Registering rules implicitly signals to the `privateRemoveBlocks`
+ * action that the editor will be responsible for displaying block removal
+ * prompts and confirming deletions. This action is meant to be used by
+ * component `BlockRemovalWarningModal` only.
+ *
+ * The data is a record whose keys are block types (e.g. 'core/query') and
+ * whose values are the explanation to be shown to users (e.g. 'Query Loop
+ * displays a list of posts or pages.').
  *
- * Contrast with `displayRemovalPrompt`.
+ * Contrast with `displayBlockRemovalPrompt`.
  *
- * @param {boolean} status Whether a prompt display mechanism exists.
+ * @param {Record<string,string>|false} rules Block removal rules.
  * @return {Object} Action object.
  */
-export function toggleRemovalPromptSupport( status = true ) {
+export function setBlockRemovalRules( rules = false ) {
 	return {
-		type: 'TOGGLE_REMOVAL_PROMPT_SUPPORT',
-		status,
+		type: 'SET_BLOCK_REMOVAL_RULES',
+		rules,
 	};
 }

package/src/store/private-selectors.js

@@ -136,21 +136,18 @@ export const isBlockSubtreeDisabled = createSelector(
  *
  * @return {Object[]} Tree of block objects with only clientID and innerBlocks set.
  */
-export const getListViewClientIdsTree = createSelector(
+export const getEnabledClientIdsTree = createSelector(
 	( state, rootClientId = '' ) => {
 		return getBlockOrder( state, rootClientId ).flatMap( ( clientId ) => {
 			if ( getBlockEditingMode( state, clientId ) !== 'disabled' ) {
 				return [
 					{
 						clientId,
-						innerBlocks: getListViewClientIdsTree(
-							state,
-							clientId
-						),
+						innerBlocks: getEnabledClientIdsTree( state, clientId ),
 					},
 				];
 			}
-			return getListViewClientIdsTree( state, clientId );
+			return getEnabledClientIdsTree( state, clientId );
 		} );
 	},
 	( state ) => [
@@ -205,6 +202,6 @@ export function getRemovalPromptData( state ) {
  *
  * @return {boolean} Whether removal prompt exists.
  */
-export function isRemovalPromptSupported( state ) {
-	return state.isRemovalPromptSupported;
+export function getBlockRemovalRules( state ) {
+	return state.blockRemovalRules;
 }

package/src/store/reducer.js

@@ -1480,14 +1480,14 @@ export function isSelectionEnabled( state = true, action ) {
  */
 function removalPromptData( state = false, action ) {
 	switch ( action.type ) {
-		case 'DISPLAY_REMOVAL_PROMPT':
+		case 'DISPLAY_BLOCK_REMOVAL_PROMPT':
 			const { clientIds, selectPrevious, blockNamesForPrompt } = action;
 			return {
 				clientIds,
 				selectPrevious,
 				blockNamesForPrompt,
 			};
-		case 'CLEAR_REMOVAL_PROMPT':
+		case 'CLEAR_BLOCK_REMOVAL_PROMPT':
 			return false;
 	}
 
@@ -1495,17 +1495,25 @@ function removalPromptData( state = false, action ) {
 }
 
 /**
- * Reducer prompt availability state.
+ * Reducer returning any rules that a block editor may provide in order to
+ * prevent a user from accidentally removing certain blocks. These rules are
+ * then used to display a confirmation prompt to the user. For instance, in the
+ * Site Editor, the Query Loop block is important enough to warrant such
+ * confirmation.
+ *
+ * The data is a record whose keys are block types (e.g. 'core/query') and
+ * whose values are the explanation to be shown to users (e.g. 'Query Loop
+ * displays a list of posts or pages.').
  *
  * @param {boolean} state  Current state.
  * @param {Object}  action Dispatched action.
  *
- * @return {boolean} Updated state.
+ * @return {Record<string,string>} Updated state.
  */
-function isRemovalPromptSupported( state = false, action ) {
+function blockRemovalRules( state = false, action ) {
 	switch ( action.type ) {
-		case 'TOGGLE_REMOVAL_PROMPT_SUPPORT':
-			return action.status;
+		case 'SET_BLOCK_REMOVAL_RULES':
+			return action.rules;
 	}
 
 	return state;
@@ -1623,6 +1631,12 @@ export function template( state = { isValid: true }, action ) {
 export function settings( state = SETTINGS_DEFAULTS, action ) {
 	switch ( action.type ) {
 		case 'UPDATE_SETTINGS':
+			if ( action.reset ) {
+				return {
+					...SETTINGS_DEFAULTS,
+					...action.settings,
+				};
+			}
 			return {
 				...state,
 				...action.settings,
@@ -1841,7 +1855,6 @@ export function lastBlockInserted( state = {}, action ) {
 	switch ( action.type ) {
 		case 'INSERT_BLOCKS':
 		case 'REPLACE_BLOCKS':
-		case 'REPLACE_INNER_BLOCKS':
 			if ( ! action.blocks.length ) {
 				return state;
 			}
@@ -1924,7 +1937,7 @@ const combinedReducers = combineReducers( {
 	blockVisibility,
 	blockEditingModes,
 	removalPromptData,
-	isRemovalPromptSupported,
+	blockRemovalRules,
 } );
 
 function withAutomaticChangeReset( reducer ) {