@wordpress/block-editor 12.4.0 → 12.5.0

package/src/hooks/supports.js

@@ -30,11 +30,17 @@ const TEXT_COLUMNS_SUPPORT_KEY = 'typography.textColumns';
  * decorations e.g. settings found in `block.json`.
  */
 const TEXT_DECORATION_SUPPORT_KEY = 'typography.__experimentalTextDecoration';
+/**
+ * Key within block settings' supports array indicating support for writing mode
+ * e.g. settings found in `block.json`.
+ */
+const WRITING_MODE_SUPPORT_KEY = 'typography.__experimentalWritingMode';
 /**
  * Key within block settings' supports array indicating support for text
  * transforms e.g. settings found in `block.json`.
  */
 const TEXT_TRANSFORM_SUPPORT_KEY = 'typography.__experimentalTextTransform';
+
 /**
  * Key within block settings' supports array indicating support for letter-spacing
  * e.g. settings found in `block.json`.
@@ -50,6 +56,7 @@ const TYPOGRAPHY_SUPPORT_KEYS = [
 	TEXT_COLUMNS_SUPPORT_KEY,
 	TEXT_DECORATION_SUPPORT_KEY,
 	TEXT_TRANSFORM_SUPPORT_KEY,
+	WRITING_MODE_SUPPORT_KEY,
 	LETTER_SPACING_SUPPORT_KEY,
 ];
 const SPACING_SUPPORT_KEY = 'spacing';

package/src/hooks/typography.js

@@ -30,6 +30,7 @@ const TEXT_DECORATION_SUPPORT_KEY = 'typography.__experimentalTextDecoration';
 const TEXT_COLUMNS_SUPPORT_KEY = 'typography.textColumns';
 const FONT_STYLE_SUPPORT_KEY = 'typography.__experimentalFontStyle';
 const FONT_WEIGHT_SUPPORT_KEY = 'typography.__experimentalFontWeight';
+const WRITING_MODE_SUPPORT_KEY = 'typography.__experimentalWritingMode';
 export const TYPOGRAPHY_SUPPORT_KEY = 'typography';
 export const TYPOGRAPHY_SUPPORT_KEYS = [
 	LINE_HEIGHT_SUPPORT_KEY,
@@ -39,6 +40,7 @@ export const TYPOGRAPHY_SUPPORT_KEYS = [
 	FONT_FAMILY_SUPPORT_KEY,
 	TEXT_COLUMNS_SUPPORT_KEY,
 	TEXT_DECORATION_SUPPORT_KEY,
+	WRITING_MODE_SUPPORT_KEY,
 	TEXT_TRANSFORM_SUPPORT_KEY,
 	LETTER_SPACING_SUPPORT_KEY,
 ];

package/src/hooks/utils.js

@@ -136,6 +136,7 @@ export function useBlockSettings( name, parentLayout ) {
 	const lineHeight = useSetting( 'typography.lineHeight' );
 	const textColumns = useSetting( 'typography.textColumns' );
 	const textDecoration = useSetting( 'typography.textDecoration' );
+	const writingMode = useSetting( 'typography.writingMode' );
 	const textTransform = useSetting( 'typography.textTransform' );
 	const letterSpacing = useSetting( 'typography.letterSpacing' );
 	const padding = useSetting( 'spacing.padding' );
@@ -211,6 +212,7 @@ export function useBlockSettings( name, parentLayout ) {
 				textDecoration,
 				textTransform,
 				letterSpacing,
+				writingMode,
 			},
 			spacing: {
 				spacingSizes: {
@@ -244,6 +246,7 @@ export function useBlockSettings( name, parentLayout ) {
 		textDecoration,
 		textTransform,
 		letterSpacing,
+		writingMode,
 		padding,
 		margin,
 		blockGap,

package/src/private-apis.js

@@ -5,6 +5,7 @@ import * as globalStyles from './components/global-styles';
 import { ExperimentalBlockEditorProvider } from './components/provider';
 import { lock } from './lock-unlock';
 import { getRichTextValues } from './components/rich-text/content';
+import { kebabCase } from './utils/object';
 import ResizableBoxPopover from './components/resizable-box-popover';
 import { ComposedPrivateInserter as PrivateInserter } from './components/inserter';
 import { PrivateListView } from './components/list-view';
@@ -16,6 +17,8 @@ import BlockQuickNavigation from './components/block-quick-navigation';
 import { LayoutStyle } from './components/block-list/layout';
 import { BlockRemovalWarningModal } from './components/block-removal-warning-modal';
 import { useLayoutClasses, useLayoutStyles } from './hooks';
+import DimensionsTool from './components/dimensions-tool';
+import ResolutionTool from './components/resolution-tool';
 
 /**
  * Private @wordpress/block-editor APIs.
@@ -25,6 +28,7 @@ lock( privateApis, {
 	...globalStyles,
 	ExperimentalBlockEditorProvider,
 	getRichTextValues,
+	kebabCase,
 	PrivateInserter,
 	PrivateListView,
 	ResizableBoxPopover,
@@ -37,4 +41,6 @@ lock( privateApis, {
 	BlockRemovalWarningModal,
 	useLayoutClasses,
 	useLayoutStyles,
+	DimensionsTool,
+	ResolutionTool,
 } );

package/src/private-apis.native.js

@@ -3,6 +3,7 @@
  */
 import * as globalStyles from './components/global-styles';
 import { ExperimentalBlockEditorProvider } from './components/provider';
+import { kebabCase } from './utils/object';
 import { lock } from './lock-unlock';
 
 /**
@@ -11,5 +12,6 @@ import { lock } from './lock-unlock';
 export const privateApis = {};
 lock( privateApis, {
 	...globalStyles,
+	kebabCase,
 	ExperimentalBlockEditorProvider,
 } );

package/src/store/actions.js

@@ -1,3 +1,4 @@
+/* eslint no-console: [ 'error', { allow: [ 'error', 'warn' ] } ] */
 /**
  * WordPress dependencies
  */
@@ -1389,7 +1390,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 +1695,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

@@ -205,6 +205,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,
@@ -1924,7 +1938,7 @@ const combinedReducers = combineReducers( {
 	blockVisibility,
 	blockEditingModes,
 	removalPromptData,
-	isRemovalPromptSupported,
+	blockRemovalRules,
 } );
 
 function withAutomaticChangeReset( reducer ) {