Merge branch 'trunk' into 68028/fix-spacing-issue

bin/api-docs/gen-components-docs/markdown/index.mjs

@@ -9,17 +9,14 @@ import json2md from 'json2md';
 import { generateMarkdownPropsJson } from './props.mjs';
 
 /**
- * If the string is contentful, ensure that it ends with a single newline.
- * Otherwise normalize to `undefined`.
+ * Converter for strings that are already formatted as Markdown.
  *
- * @param {string} [str]
+ * @param {string} [input]
+ * @return {string} The trimmed input if it is contentful, otherwise an empty string.
  */
-function normalizeTrailingNewline( str ) {
-	if ( ! str?.trim() ) {
-		return undefined;
-	}
-	return str.replace( /\n*$/, '\n' );
-}
+json2md.converters.md = ( input ) => {
+	return input?.trim() || '';
+};
 
 export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 	const mainDocsJson = [
@@ -28,7 +25,7 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 		{
 			p: `<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-${ typeDocs.displayName.toLowerCase() }--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>`,
 		},
-		normalizeTrailingNewline( typeDocs.description ),
+		{ md: typeDocs.description },
 		...generateMarkdownPropsJson( typeDocs.props ),
 	];
 
@@ -39,7 +36,7 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 					{
 						h3: subcomponentTypeDoc.displayName,
 					},
-					normalizeTrailingNewline( subcomponentTypeDoc.description ),
+					{ md: subcomponentTypeDoc.description },
 					...generateMarkdownPropsJson( subcomponentTypeDoc.props, {
 						headingLevel: 4,
 					} ),
@@ -49,5 +46,5 @@ export function generateMarkdownDocs( { typeDocs, subcomponentTypeDocs } ) {
 
 	return json2md(
 		[ ...mainDocsJson, ...subcomponentDocsJson ].filter( Boolean )
-	);
+	).replace( /\n+$/gm, '\n' ); // clean unnecessary consecutive newlines
 }

bin/api-docs/gen-components-docs/markdown/props.mjs

@@ -33,7 +33,6 @@ export function generateMarkdownPropsJson( props, { headingLevel = 2 } = {} ) {
 
 			return [
 				{ [ `h${ headingLevel + 1 }` ]: `\`${ key }\`` },
-				prop.description,
 				{
 					ul: [
 						`Type: \`${ renderPropType( prop.type ) }\``,
@@ -42,6 +41,7 @@ export function generateMarkdownPropsJson( props, { headingLevel = 2 } = {} ) {
 							`Default: \`${ prop.defaultValue.value }\``,
 					].filter( Boolean ),
 				},
+				{ md: prop.description },
 			];
 		} )
 		.filter( Boolean );

docs/reference-guides/core-blocks.md

@@ -661,7 +661,7 @@ Contains the block elements used to render a post, like the title, date, feature
 -	**Name:** core/post-template
 -	**Category:** theme
 -	**Ancestor:** core/query
--	**Supports:** align (full, wide), color (background, gradients, link, text), interactivity (clientNavigation), layout, spacing (blockGap), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
+-	**Supports:** align (full, wide), color (background, gradients, link, text), interactivity (clientNavigation), layout, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
 
 ## Post Terms
 

packages/block-editor/src/components/block-card/README.md

@@ -21,6 +21,7 @@ const MyBlockCard = () => (
 		icon={ paragraph }
 		title="Paragraph"
 		description="Start with the basic building block of all narrative."
+		name="Custom Block"
 	/>
 );
 ```
@@ -45,6 +46,12 @@ The title of the block.
 
 The description of the block.
 
+#### name
+
+-   **Type:** `String`
+
+The custom name of the block.
+
 ## Related components
 
 Block Editor components are components that can be used to compose the UI of your block editor. Thus, they can only be used under a [`BlockEditorProvider`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/provider/README.md) in the components tree.

packages/block-editor/src/components/block-card/index.js

@@ -6,26 +6,55 @@ import clsx from 'clsx';
 /**
  * WordPress dependencies
  */
-import deprecated from '@wordpress/deprecated';
 import {
 	Button,
 	__experimentalText as Text,
 	__experimentalVStack as VStack,
 	privateApis as componentsPrivateApis,
 } from '@wordpress/components';
-import { chevronLeft, chevronRight } from '@wordpress/icons';
+import { useDispatch, useSelect } from '@wordpress/data';
+import deprecated from '@wordpress/deprecated';
 import { __, isRTL } from '@wordpress/i18n';
-import { useSelect, useDispatch } from '@wordpress/data';
+import { chevronLeft, chevronRight } from '@wordpress/icons';
 
 /**
  * Internal dependencies
  */
-import BlockIcon from '../block-icon';
-import { store as blockEditorStore } from '../../store';
 import { unlock } from '../../lock-unlock';
+import { store as blockEditorStore } from '../../store';
+import BlockIcon from '../block-icon';
 
 const { Badge } = unlock( componentsPrivateApis );
 
+/**
+ * A card component that displays block information including title, icon, and description.
+ * Can be used to show block metadata and navigation controls for parent blocks.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-card/README.md
+ *
+ * @example
+ * ```jsx
+ * function Example() {
+ *   return (
+ *     <BlockCard
+ *       title="My Block"
+ *       icon="smiley"
+ *       description="A simple block example"
+ *       name="Custom Block"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param {Object}        props             Component props.
+ * @param {string}        props.title       The title of the block.
+ * @param {string|Object} props.icon        The icon of the block. This can be any of [WordPress' Dashicons](https://developer.wordpress.org/resource/dashicons/), or a custom `svg` element.
+ * @param {string}        props.description The description of the block.
+ * @param {Object}        [props.blockType] Deprecated: Object containing block type data.
+ * @param {string}        [props.className] Additional classes to apply to the card.
+ * @param {string}        [props.name]      Custom block name to display before the title.
+ * @return {Element}                        Block card component.
+ */
 function BlockCard( { title, icon, description, blockType, className, name } ) {
 	if ( blockType ) {
 		deprecated( '`blockType` property in `BlockCard component`', {

packages/block-editor/src/components/keyboard-shortcuts/index.js

@@ -29,8 +29,8 @@ function KeyboardShortcutsRegister() {
 			category: 'block',
 			description: __( 'Remove the selected block(s).' ),
 			keyCombination: {
-				modifier: 'access',
-				character: 'z',
+				modifier: 'shift',
+				character: 'backspace',
 			},
 		} );
 

packages/block-editor/src/components/media-replace-flow/index.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import clsx from 'clsx';
-
 /**
  * WordPress dependencies
  */
@@ -61,10 +56,7 @@ const MediaReplaceFlow = ( {
 	popoverProps,
 	renderToggle,
 } ) => {
-	const mediaUpload = useSelect( ( select ) => {
-		return select( blockEditorStore ).getSettings().mediaUpload;
-	}, [] );
-	const canUpload = !! mediaUpload;
+	const { getSettings } = useSelect( blockEditorStore );
 	const errorNoticeID = `block-editor/media-replace-flow/error-notice/${ ++uniqueId }`;
 
 	const onUploadError = ( message ) => {
@@ -106,7 +98,7 @@ const MediaReplaceFlow = ( {
 			return onSelect( files );
 		}
 		onFilesUpload( files );
-		mediaUpload( {
+		getSettings().mediaUpload( {
 			allowedTypes,
 			filesList: files,
 			onFileChange: ( [ media ] ) => {
@@ -228,15 +220,7 @@ const MediaReplaceFlow = ( {
 					</NavigableMenu>
 					{ onSelectURL && (
 						// eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
-						<form
-							className={ clsx(
-								'block-editor-media-flow__url-input',
-								{
-									'has-siblings':
-										canUpload || onToggleFeaturedImage,
-								}
-							) }
-						>
+						<form className="block-editor-media-flow__url-input">
 							<span className="block-editor-media-replace-flow__image-url-label">
 								{ __( 'Current media URL:' ) }
 							</span>

packages/block-editor/src/components/media-replace-flow/style.scss

@@ -9,17 +9,17 @@
 	margin-left: 4px;
 }
 
+.block-editor-media-replace-flow__media-upload-menu:not(:empty) + .block-editor-media-flow__url-input {
+	border-top: $border-width solid $gray-900;
+	margin-top: $grid-unit-10;
+	padding-bottom: $grid-unit-10;
+}
+
 .block-editor-media-flow__url-input {
 	margin-right: -$grid-unit-10;
 	margin-left: -$grid-unit-10;
 	padding: $grid-unit-20;
 
-	&.has-siblings {
-		border-top: $border-width solid $gray-900;
-		margin-top: $grid-unit-10;
-		padding-bottom: $grid-unit-10;
-	}
-
 	.block-editor-media-replace-flow__image-url-label {
 		display: block;
 		top: $grid-unit-20;

packages/block-editor/src/components/resolution-tool/index.js

@@ -33,6 +33,7 @@ export default function ResolutionTool( {
 	options = DEFAULT_SIZE_OPTIONS,
 	defaultValue = DEFAULT_SIZE_OPTIONS[ 0 ].value,
 	isShownByDefault = true,
+	resetAllFilter,
 } ) {
 	const displayValue = value ?? defaultValue;
 	return (
@@ -42,6 +43,7 @@ export default function ResolutionTool( {
 			onDeselect={ () => onChange( defaultValue ) }
 			isShownByDefault={ isShownByDefault }
 			panelId={ panelId }
+			resetAllFilter={ resetAllFilter }
 		>
 			<SelectControl
 				__nextHasNoMarginBottom

packages/block-editor/src/components/resolution-tool/stories/index.story.js

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { useState } from '@wordpress/element';
+import { useReducer } from '@wordpress/element';
 import {
 	Panel,
 	__experimentalToolsPanel as ToolsPanel,
@@ -21,28 +21,55 @@ export default {
 	},
 };
 
-export const Default = ( { panelId, onChange: onChangeProp, ...props } ) => {
-	const [ resolution, setResolution ] = useState( undefined );
-	const resetAll = () => {
-		setResolution( undefined );
+export const Default = ( {
+	label,
+	panelId,
+	onChange: onChangeProp,
+	...props
+} ) => {
+	const [ attributes, setAttributes ] = useReducer(
+		( prevState, nextState ) => ( { ...prevState, ...nextState } ),
+		{}
+	);
+	const { resolution } = attributes;
+	const resetAll = ( resetFilters = [] ) => {
+		let newAttributes = {};
+
+		resetFilters.forEach( ( resetFilter ) => {
+			newAttributes = {
+				...newAttributes,
+				...resetFilter( newAttributes ),
+			};
+		} );
+
+		setAttributes( newAttributes );
 		onChangeProp( undefined );
 	};
 	return (
 		<Panel>
-			<ToolsPanel panelId={ panelId } resetAll={ resetAll }>
+			<ToolsPanel
+				label={ label }
+				panelId={ panelId }
+				resetAll={ resetAll }
+			>
 				<ResolutionTool
 					panelId={ panelId }
 					onChange={ ( newValue ) => {
-						setResolution( newValue );
+						setAttributes( { resolution: newValue } );
 						onChangeProp( newValue );
 					} }
 					value={ resolution }
+					resetAllFilter={ () => ( {
+						resolution: undefined,
+					} ) }
 					{ ...props }
 				/>
 			</ToolsPanel>
 		</Panel>
 	);
 };
 Default.args = {
+	label: 'Settings',
+	defaultValue: 'full',
 	panelId: 'panel-id',
 };

packages/block-editor/src/components/rich-text/event-listeners/delete.js

@@ -6,7 +6,7 @@ import { isCollapsed, isEmpty } from '@wordpress/rich-text';
 
 export default ( props ) => ( element ) => {
 	function onKeyDown( event ) {
-		const { keyCode } = event;
+		const { keyCode, shiftKey } = event;
 
 		if ( event.defaultPrevented ) {
 			return;
@@ -30,6 +30,11 @@ export default ( props ) => ( element ) => {
 				return;
 			}
 
+			// Exclude shift+backspace as they are shortcuts for deleting blocks.
+			if ( shiftKey ) {
+				return;
+			}
+
 			if ( onMerge ) {
 				onMerge( ! isReverse );
 			}

packages/block-editor/src/components/text-alignment-control/README.md

@@ -0,0 +1,49 @@
+# TextAlignmentControl
+
+The `TextAlignmentControl` component is responsible for rendering a control element that allows users to select and apply text alignment options to blocks or elements in the Gutenberg editor. It provides an intuitive interface for aligning text with options such as `left`, `center` and `right`.
+
+## Usage
+
+Renders the Text Alignment Component with `left`, `center` and `right` alignment options.
+
+```jsx
+import { TextAlignmentControl } from '@wordpress/block-editor';
+
+const MyTextAlignmentControlComponent = () => (
+	<TextAlignmentControl
+		value={ textAlign }
+		onChange={ ( value ) => {
+			setAttributes( { textAlign: value } );
+		} }
+	/>
+);
+```
+
+## Props
+
+### `value`
+
+-   **Type:** `String`
+-   **Default:** `undefined`
+-   **Options:** `left`, `center`, `right`, `justify`
+
+The current value of the text alignment setting. You may only choose from the `Options` listed above.
+
+### `onChange`
+
+-   **Type:** `Function`
+
+A callback function invoked when the text alignment value is changed via an interaction with any of the options. The function is called with the new alignment value (`left`, `center`, `right`) as the only argument.
+
+### `className`
+
+-   **Type:** `String`
+
+Class name to add to the control for custom styling.
+
+### `options`
+
+-   **Type:** `Array`
+-   **Default:** [`left`, `center`, `right`]
+
+An array that determines which alignment options will be available in the control. You can pass an array of alignment values to customize the options.