@wordpress/block-editor 12.4.0 → 12.5.0

package/src/components/panel-color-settings/README.md

@@ -0,0 +1,98 @@
+# PanelColorSettings
+
+`PanelColorSettings` is a React component that renders a UI for managing various color settings.
+It is essentially a wrapper around the `PanelColorGradientSettings` component, but specifically disables the gradient features.
+
+## Usage
+
+```jsx
+/**
+ * WordPress dependencies
+ */
+import { PanelColorSettings } from '@wordpress/block-editor';
+import { useState } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+
+// ...
+
+const MyPanelColorSettings = () => {
+	const [ textColor, setTextColor ] = useState( { color: '#000' } );
+	const [ backgroundColor, setBackgroundColor ] = useState( {
+		color: '#fff',
+	} );
+	const [ overlayTextColor, setOverlayTextColor ] = useState( {
+		color: '#000',
+	} );
+	const [ overlayBackgroundColor, setOverlayBackgroundColor ] = useState( {
+		color: '#eee',
+	} );
+
+	return (
+		<PanelColorSettings
+			__experimentalIsRenderedInSidebar
+			title={ __( 'Color' ) }
+			colorSettings={ [
+				{
+					value: textColor.color,
+					onChange: setTextColor,
+					label: __( 'Text' ),
+				},
+				{
+					value: backgroundColor.color,
+					onChange: setBackgroundColor,
+					label: __( 'Background' ),
+				},
+				{
+					value: overlayTextColor.color,
+					onChange: setOverlayTextColor,
+					label: __( 'Submenu & overlay text' ),
+				},
+				{
+					value: overlayBackgroundColor.color,
+					onChange: setOverlayBackgroundColor,
+					label: __( 'Submenu & overlay background' ),
+				},
+			] }
+		/>
+	);
+};
+
+/// ...
+
+<MyPanelColorSettings />;
+```
+
+## Props
+
+The component accepts the following props:
+
+### colorSettings
+
+A user-provided set of color settings.
+
+- Type: `Array`
+- Required: No
+
+Colors settings are provided as an array of objects with the following schema:
+
+| Property | Description                       | Type     |
+| -------- | --------------------------------- | -------- |
+| value    | The current color of the setting  | string   |
+| onChange | Callback on change of the setting | Function |
+| label    | Label of the setting              | string   |
+
+Additionally, the following `PanelColorGradientSettings` props are supported and directly passed down to the underlying `PanelColorGradientSettings` instance:
+
+- `className` - added to the underlying `ToolsPanel` instance.
+- `colors` - array of colors to be used.
+- `gradients` - not recommended to be used since `PanelColorSettings` resets it.
+- `disableCustomColors` - whether addition of custom colors is enabled
+- `disableCustomGradients` - not recommended to be used since `PanelColorSettings` sets it.
+- `children` - displayed below the underlying `PanelColorGradientSettings` instance.
+- `settings` - not recommended to be used, since `PanelColorSettings` builds it from the `colorSettings` prop.
+- `title` - title of the underlying `ToolsPanel`.
+- `showTitle` - whether to show the title of the `ToolsPanel`.
+- `__experimentalIsRenderedInSidebar`
+- `enableAlpha` - whether to enable setting opacity when specifying a color.
+
+Please refer to the `PanelColorGradientSettings` component for more information.

package/src/components/provider/index.js

@@ -28,9 +28,16 @@ export const ExperimentalBlockEditorProvider = withRegistryProvider(
 					...settings,
 					__internalIsInitialized: true,
 				},
-				stripExperimentalSettings
+				{
+					stripExperimentalSettings,
+					reset: true,
+				}
 			);
-		}, [ settings ] );
+		}, [
+			settings,
+			stripExperimentalSettings,
+			__experimentalUpdateSettings,
+		] );
 
 		// Syncs the entity provider with changes in the block-editor store.
 		useBlockSync( props );

package/src/components/provider/test/use-block-sync.js

@@ -48,7 +48,7 @@ describe( 'useBlockSync hook', () => {
 		jest.clearAllMocks();
 	} );
 
-	it( 'resets the block-editor blocks when the controll value changes', async () => {
+	it( 'resets the block-editor blocks when the controlled value changes', async () => {
 		const fakeBlocks = [];
 		const resetBlocks = jest.spyOn( blockEditorActions, 'resetBlocks' );
 		const replaceInnerBlocks = jest.spyOn(
@@ -58,7 +58,7 @@ describe( 'useBlockSync hook', () => {
 		const onChange = jest.fn();
 		const onInput = jest.fn();
 
-		const { rerender } = render(
+		const { rerender, unmount } = render(
 			<TestWrapper
 				value={ fakeBlocks }
 				onChange={ onChange }
@@ -88,9 +88,16 @@ describe( 'useBlockSync hook', () => {
 		expect( onInput ).not.toHaveBeenCalled();
 		expect( replaceInnerBlocks ).not.toHaveBeenCalled();
 		expect( resetBlocks ).toHaveBeenCalledWith( testBlocks );
+
+		unmount();
+
+		expect( onChange ).not.toHaveBeenCalled();
+		expect( onInput ).not.toHaveBeenCalled();
+		expect( replaceInnerBlocks ).not.toHaveBeenCalled();
+		expect( resetBlocks ).toHaveBeenCalledWith( [] );
 	} );
 
-	it( 'replaces the inner blocks of a block when the control value changes if a clientId is passed', async () => {
+	it( 'replaces the inner blocks of a block when the controlled value changes if a clientId is passed', async () => {
 		const fakeBlocks = [];
 		const replaceInnerBlocks = jest.spyOn(
 			blockEditorActions,
@@ -100,7 +107,7 @@ describe( 'useBlockSync hook', () => {
 		const onChange = jest.fn();
 		const onInput = jest.fn();
 
-		const { rerender } = render(
+		const { rerender, unmount } = render(
 			<TestWrapper
 				clientId="test"
 				value={ fakeBlocks }
@@ -138,8 +145,16 @@ describe( 'useBlockSync hook', () => {
 		expect( onChange ).not.toHaveBeenCalled();
 		expect( onInput ).not.toHaveBeenCalled();
 		expect( resetBlocks ).not.toHaveBeenCalled();
-		// We can't check the args because the blocks are cloned.
-		expect( replaceInnerBlocks ).toHaveBeenCalled();
+		expect( replaceInnerBlocks ).toHaveBeenCalledWith( 'test', [
+			expect.objectContaining( { name: 'test/test-block' } ),
+		] );
+
+		unmount();
+
+		expect( onChange ).not.toHaveBeenCalled();
+		expect( onInput ).not.toHaveBeenCalled();
+		expect( resetBlocks ).not.toHaveBeenCalled();
+		expect( replaceInnerBlocks ).toHaveBeenCalledWith( 'test', [] );
 	} );
 
 	it( 'does not add the controlled blocks to the block-editor store if the store already contains them', async () => {

package/src/components/provider/use-block-sync.js

@@ -134,6 +134,19 @@ export default function useBlockSync( {
 		}
 	};
 
+	// Clean up the changes made by setControlledBlocks() when the component
+	// containing useBlockSync() unmounts.
+	const unsetControlledBlocks = () => {
+		__unstableMarkNextChangeAsNotPersistent();
+		if ( clientId ) {
+			setHasControlledInnerBlocks( clientId, false );
+			__unstableMarkNextChangeAsNotPersistent();
+			replaceInnerBlocks( clientId, [] );
+		} else {
+			resetBlocks( [] );
+		}
+	};
+
 	// Add a subscription to the block-editor registry to detect when changes
 	// have been made. This lets us inform the data source of changes. This
 	// is an effect so that the subscriber can run synchronously without
@@ -287,4 +300,10 @@ export default function useBlockSync( {
 			unsubscribe();
 		};
 	}, [ registry, clientId ] );
+
+	useEffect( () => {
+		return () => {
+			unsetControlledBlocks();
+		};
+	}, [] );
 }

package/src/components/recursion-provider/README.md

@@ -0,0 +1,101 @@
+# RecursionProvider
+
+According to Gutenberg's block rendering architecture, any block type capable of recursion should be responsible for handling its own infinite loops. 
+
+To help with detecting infinite loops on the client, the `RecursionProvider` component and the `useHasRecursion()` hook are used to identify if a block has already been rendered. 
+
+## Usage
+
+```jsx
+/**
+ * WordPress dependencies
+ */
+import {
+	__experimentalRecursionProvider as RecursionProvider,
+	__experimentalUseHasRecursion as useHasRecursion,
+	useBlockProps,
+	Warning,
+} from '@wordpress/block-editor';
+import { __ } from '@wordpress/i18n';
+
+export default function MyRecursiveBlockEdit( { attributes: { ref } } ) {
+	const hasAlreadyRendered = useHasRecursion( ref );
+	const blockProps = useBlockProps( {
+		className: 'my-block__custom-class',
+	} );
+
+	if ( hasAlreadyRendered ) {
+		return (
+			<div { ...blockProps }>
+				<Warning>
+					{ __( 'Block cannot be rendered inside itself.' ) }
+				</Warning>
+			</div>
+		);
+	}
+
+	return (
+		<RecursionProvider uniqueId={ ref }>
+			Block editing code here....
+		</RecursionProvider>
+	);
+}
+
+/// ...
+
+<MyRecursiveBlockEdit />;
+```
+
+## Props
+
+The component accepts the following props:
+
+### uniqueId
+
+Any value that acts as a unique identifier for a block instance.
+
+- Type: `any`
+- Required: Yes
+
+### children
+
+Components to be rendered as content.
+
+- Type: `Element`
+- Required: Yes.
+
+### blockName
+
+Optional block name.
+
+- Type: `String`
+- Required: No
+- Default: ''
+
+# `useHasRecursion()`
+
+Used in conjunction with `RecursionProvider`, this hook is used to identify if a block has already been rendered.
+
+## Usage
+
+For example usage, refer to the example above.
+
+## Props
+
+The component accepts the following props:
+
+### uniqueId
+
+Any value that acts as a unique identifier for a block instance.
+
+- Type: `any`
+- Required: Yes
+
+### blockName
+
+Optional block name.
+
+- Type: `String`
+- Required: No
+- Default: ''
+

package/src/components/resolution-tool/index.js

@@ -0,0 +1,56 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	SelectControl,
+	__experimentalToolsPanelItem as ToolsPanelItem,
+} from '@wordpress/components';
+import { __, _x } from '@wordpress/i18n';
+
+const DEFAULT_SIZE_OPTIONS = [
+	{
+		label: _x( 'Thumbnail', 'Image size option for resolution control' ),
+		value: 'thumbnail',
+	},
+	{
+		label: _x( 'Medium', 'Image size option for resolution control' ),
+		value: 'medium',
+	},
+	{
+		label: _x( 'Large', 'Image size option for resolution control' ),
+		value: 'large',
+	},
+	{
+		label: _x( 'Full Size', 'Image size option for resolution control' ),
+		value: 'full',
+	},
+];
+
+export default function ResolutionTool( {
+	panelId,
+	value,
+	onChange,
+	options = DEFAULT_SIZE_OPTIONS,
+	defaultValue = DEFAULT_SIZE_OPTIONS[ 0 ].value,
+	isShownByDefault = true,
+} ) {
+	const displayValue = value ?? defaultValue;
+	return (
+		<ToolsPanelItem
+			hasValue={ () => displayValue !== defaultValue }
+			label={ __( 'Resolution' ) }
+			onDeselect={ () => onChange( defaultValue ) }
+			isShownByDefault={ isShownByDefault }
+			panelId={ panelId }
+		>
+			<SelectControl
+				label={ __( 'Resolution' ) }
+				value={ displayValue }
+				options={ options }
+				onChange={ onChange }
+				help={ __( 'Select the size of the source image.' ) }
+				size={ '__unstable-large' }
+			/>
+		</ToolsPanelItem>
+	);
+}

package/src/components/resolution-tool/stories/index.js

@@ -0,0 +1,48 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import {
+	Panel,
+	__experimentalToolsPanel as ToolsPanel,
+} from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import ResolutionTool from '..';
+
+export default {
+	title: 'BlockEditor (Private APIs)/ResolutionControl',
+	component: ResolutionTool,
+	argTypes: {
+		panelId: { control: { type: null } },
+		onChange: { action: 'changed' },
+	},
+};
+
+export const Default = ( { panelId, onChange: onChangeProp, ...props } ) => {
+	const [ resolution, setResolution ] = useState( undefined );
+	const resetAll = () => {
+		setResolution( undefined );
+		onChangeProp( undefined );
+	};
+	return (
+		<Panel>
+			<ToolsPanel panelId={ panelId } resetAll={ resetAll }>
+				<ResolutionTool
+					panelId={ panelId }
+					onChange={ ( newValue ) => {
+						setResolution( newValue );
+						onChangeProp( newValue );
+					} }
+					value={ resolution }
+					{ ...props }
+				/>
+			</ToolsPanel>
+		</Panel>
+	);
+};
+Default.args = {
+	panelId: 'panel-id',
+};

package/src/components/url-input/index.js

@@ -434,6 +434,7 @@ class URLInput extends Component {
 			placeholder = __( 'Paste URL or type to search' ),
 			__experimentalRenderControl: renderControl,
 			value = '',
+			hideLabelFromVision = false,
 		} = this.props;
 
 		const {
@@ -452,6 +453,7 @@ class URLInput extends Component {
 			className: classnames( 'block-editor-url-input', className, {
 				'is-full-width': isFullWidth,
 			} ),
+			hideLabelFromVision,
 		};
 
 		const inputProps = {

package/src/components/writing-flow/use-tab-nav.js

@@ -11,6 +11,7 @@ import { useRef } from '@wordpress/element';
  * Internal dependencies
  */
 import { store as blockEditorStore } from '../../store';
+import { isInSameBlock, isInsideRootBlock } from '../../utils/dom';
 
 export default function useTabNav() {
 	const container = useRef();
@@ -116,41 +117,20 @@ export default function useTabNav() {
 				return;
 			}
 
+			const nextTabbable = focus.tabbable[ direction ]( event.target );
+
 			// We want to constrain the tabbing to the block and its child blocks.
 			// If the preceding form element is within a different block,
 			// such as two sibling image blocks in the placeholder state,
 			// we want shift + tab from the first form element to move to the image
 			// block toolbar and not the previous image block's form element.
-			// TODO: Should this become a utility function?
-			/**
-			 * Determine whether an element is part of or is the selected block.
-			 *
-			 * @param {Object} selectedBlockElement
-			 * @param {Object} element
-			 * @return {boolean} Whether the element is part of or is the selected block.
-			 */
-			const isElementPartOfSelectedBlock = (
-				selectedBlockElement,
-				element
-			) => {
-				// Check if the element is or is within the selected block by finding the
-				// closest element with a data-block attribute and seeing if
-				// it matches our current selected block ID
-				const elementBlockId = element
-					.closest( '[data-block]' )
-					?.getAttribute( 'data-block' );
-				const isElementSameBlock =
-					elementBlockId === getSelectedBlockClientId();
-
-				// Check if the element is a child of the selected block. This could be a
-				// child block in a group or column block, etc.
-				const isElementChildOfBlock =
-					selectedBlockElement.contains( element );
-
-				return isElementSameBlock || isElementChildOfBlock;
-			};
+			const currentBlock = event.target.closest( '[data-block]' );
+			const isElementPartOfSelectedBlock =
+				currentBlock &&
+				nextTabbable &&
+				( isInSameBlock( currentBlock, nextTabbable ) ||
+					isInsideRootBlock( currentBlock, nextTabbable ) );
 
-			const nextTabbable = focus.tabbable[ direction ]( event.target );
 			// Allow tabbing from the block wrapper to a form element,
 			// and between form elements rendered in a block and its child blocks,
 			// such as inside a placeholder. Form elements are generally
@@ -159,10 +139,7 @@ export default function useTabNav() {
 			// future they can be rendered in an iframe or shadow DOM.
 			if (
 				isFormElement( nextTabbable ) &&
-				isElementPartOfSelectedBlock(
-					event.target.closest( '[data-block]' ),
-					nextTabbable
-				)
+				isElementPartOfSelectedBlock
 			) {
 				return;
 			}

package/src/components/writing-mode-control/index.js

@@ -0,0 +1,68 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { BaseControl, Button } from '@wordpress/components';
+import { __, isRTL } from '@wordpress/i18n';
+import { textHorizontal, textVertical } from '@wordpress/icons';
+
+const WRITING_MODES = [
+	{
+		name: __( 'Horizontal' ),
+		value: 'horizontal-tb',
+		icon: textHorizontal,
+	},
+	{
+		name: __( 'Vertical' ),
+		value: isRTL() ? 'vertical-lr' : 'vertical-rl',
+		icon: textVertical,
+	},
+];
+
+/**
+ * Control to facilitate writing mode selections.
+ *
+ * @param {Object}   props           Component props.
+ * @param {string}   props.className Class name to add to the control.
+ * @param {string}   props.value     Currently selected writing mode.
+ * @param {Function} props.onChange  Handles change in the writing mode selection.
+ *
+ * @return {WPElement} Writing Mode control.
+ */
+export default function WritingModeControl( { className, value, onChange } ) {
+	return (
+		<fieldset
+			className={ classnames(
+				'block-editor-writing-mode-control',
+				className
+			) }
+		>
+			<BaseControl.VisualLabel as="legend">
+				{ __( 'Orientation' ) }
+			</BaseControl.VisualLabel>
+			<div className="block-editor-writing-mode-control__buttons">
+				{ WRITING_MODES.map( ( writingMode ) => {
+					return (
+						<Button
+							key={ writingMode.value }
+							icon={ writingMode.icon }
+							label={ writingMode.name }
+							isPressed={ writingMode.value === value }
+							onClick={ () => {
+								onChange(
+									writingMode.value === value
+										? undefined
+										: writingMode.value
+								);
+							} }
+						/>
+					);
+				} ) }
+			</div>
+		</fieldset>
+	);
+}

package/src/components/writing-mode-control/style.scss

@@ -0,0 +1,18 @@
+.block-editor-writing-mode-control {
+	border: 0;
+	margin: 0;
+	padding: 0;
+
+	.block-editor-writing-mode-control__buttons {
+		// 4px of padding makes the row 40px high, same as an input.
+		padding: $grid-unit-05 0;
+		display: flex;
+	}
+
+	.components-button.has-icon {
+		height: $grid-unit-40;
+		margin-right: $grid-unit-05;
+		min-width: $grid-unit-40;
+		padding: 0;
+	}
+}

package/src/hooks/behaviors.js

@@ -7,6 +7,7 @@ import { __ } from '@wordpress/i18n';
 import { hasBlockSupport } from '@wordpress/blocks';
 import { createHigherOrderComponent } from '@wordpress/compose';
 import { useSelect } from '@wordpress/data';
+import { useMemo } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -65,35 +66,40 @@ function BehaviorsControl( {
 		...behaviorsOptions,
 	];
 
+	const { behaviors, behaviorsValue } = useMemo( () => {
+		const mergedBehaviors = {
+			...themeBehaviors,
+			...( blockBehaviors || {} ),
+		};
+
+		let value = '';
+		if ( blockBehaviors === undefined ) {
+			value = 'default';
+		}
+		if ( blockBehaviors?.lightbox.enabled ) {
+			value = 'lightbox';
+		}
+		return {
+			behaviors: mergedBehaviors,
+			behaviorsValue: value,
+		};
+	}, [ blockBehaviors, themeBehaviors ] );
 	// If every behavior is disabled, do not show the behaviors inspector control.
 	if ( behaviorsOptions.length === 0 ) {
 		return null;
 	}
-	// Block behaviors take precedence over theme behaviors.
-	const behaviors = { ...themeBehaviors, ...( blockBehaviors || {} ) };
 
 	const helpText = disabled
 		? __( 'The lightbox behavior is disabled for linked images.' )
 		: '';
 
-	const value = () => {
-		if ( blockBehaviors === undefined ) {
-			return 'default';
-		}
-		if ( behaviors?.lightbox.enabled ) {
-			return 'lightbox';
-		}
-		return '';
-	};
-
 	return (
 		<InspectorControls group="advanced">
-			{ /* This div is needed to prevent a margin bottom between the dropdown and the button. */ }
 			<div>
 				<SelectControl
 					label={ __( 'Behaviors' ) }
 					// At the moment we are only supporting one behavior (Lightbox)
-					value={ value() }
+					value={ behaviorsValue }
 					options={ options }
 					onChange={ onChangeBehavior }
 					hideCancelButton={ true }
@@ -101,7 +107,7 @@ function BehaviorsControl( {
 					size="__unstable-large"
 					disabled={ disabled }
 				/>
-				{ behaviors?.lightbox.enabled && (
+				{ behaviorsValue === 'lightbox' && (
 					<SelectControl
 						label={ __( 'Animation' ) }
 						// At the moment we are only supporting one behavior (Lightbox)
@@ -115,7 +121,10 @@ function BehaviorsControl( {
 								value: 'zoom',
 								label: __( 'Zoom' ),
 							},
-							{ value: 'fade', label: 'Fade' },
+							{
+								value: 'fade',
+								label: __( 'Fade' ),
+							},
 						] }
 						onChange={ onChangeAnimation }
 						hideCancelButton={ false }