@wordpress/block-editor 7.0.1 → 8.0.0

package/src/components/inspector-controls/fill.js

@@ -0,0 +1,53 @@
+/**
+ * External dependencies
+ */
+import { isEmpty } from 'lodash';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	__experimentalStyleProvider as StyleProvider,
+	__experimentalToolsPanelContext as ToolsPanelContext,
+} from '@wordpress/components';
+import warning from '@wordpress/warning';
+
+/**
+ * Internal dependencies
+ */
+import useDisplayBlockControls from '../use-display-block-controls';
+import groups from './groups';
+
+export default function InspectorControlsFill( {
+	__experimentalGroup: group = 'default',
+	children,
+} ) {
+	const isDisplayed = useDisplayBlockControls();
+	const Fill = groups[ group ]?.Fill;
+	if ( ! Fill ) {
+		warning( `Unknown InspectorControl group "${ group }" provided.` );
+		return null;
+	}
+	if ( ! isDisplayed ) {
+		return null;
+	}
+
+	return (
+		<StyleProvider document={ document }>
+			<Fill>
+				{ ( fillProps ) => {
+					// Children passed to InspectorControlsFill will not have
+					// access to any React Context whose Provider is part of
+					// the InspectorControlsSlot tree. So we re-create the
+					// Provider in this subtree.
+					const value = ! isEmpty( fillProps ) ? fillProps : null;
+					return (
+						<ToolsPanelContext.Provider value={ value }>
+							{ children }
+						</ToolsPanelContext.Provider>
+					);
+				} }
+			</Fill>
+		</StyleProvider>
+	);
+}

package/src/components/inspector-controls/{index.native.js → fill.native.js}

@@ -7,18 +7,27 @@ import { View } from 'react-native';
  * WordPress dependencies
  */
 import { Children } from '@wordpress/element';
-import { createSlotFill, BottomSheetConsumer } from '@wordpress/components';
+import { BottomSheetConsumer } from '@wordpress/components';
+import warning from '@wordpress/warning';
 
 /**
  * Internal dependencies
  */
+import groups from './groups';
 import { useBlockEditContext } from '../block-edit/context';
 import { BlockSettingsButton } from '../block-settings';
 
-const { Fill, Slot } = createSlotFill( 'InspectorControls' );
-
-const FillWithSettingsButton = ( { children, ...props } ) => {
+export default function InspectorControlsFill( {
+	children,
+	__experimentalGroup: group = 'default',
+	...props
+} ) {
 	const { isSelected } = useBlockEditContext();
+	const Fill = groups[ group ]?.Fill;
+	if ( ! Fill ) {
+		warning( `Unknown InspectorControl group "${ group }" provided.` );
+		return null;
+	}
 	if ( ! isSelected ) {
 		return null;
 	}
@@ -35,13 +44,4 @@ const FillWithSettingsButton = ( { children, ...props } ) => {
 			{ Children.count( children ) > 0 && <BlockSettingsButton /> }
 		</>
 	);
-};
-
-const InspectorControls = FillWithSettingsButton;
-
-InspectorControls.Slot = Slot;
-
-/**
- * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md
- */
-export default InspectorControls;
+}

package/src/components/inspector-controls/groups.js

@@ -0,0 +1,22 @@
+/**
+ * WordPress dependencies
+ */
+import { createSlotFill } from '@wordpress/components';
+
+const InspectorControlsDefault = createSlotFill( 'InspectorControls' );
+const InspectorControlsAdvanced = createSlotFill( 'InspectorAdvancedControls' );
+const InspectorControlsDimensions = createSlotFill(
+	'InspectorControlsDimensions'
+);
+const InspectorControlsTypography = createSlotFill(
+	'InspectorControlsTypography'
+);
+
+const groups = {
+	default: InspectorControlsDefault,
+	advanced: InspectorControlsAdvanced,
+	dimensions: InspectorControlsDimensions,
+	typography: InspectorControlsTypography,
+};
+
+export default groups;

package/src/components/inspector-controls/index.js

@@ -1,27 +1,25 @@
-/**
- * WordPress dependencies
- */
-import {
-	__experimentalStyleProvider as StyleProvider,
-	createSlotFill,
-} from '@wordpress/components';
-
 /**
  * Internal dependencies
  */
-import useDisplayBlockControls from '../use-display-block-controls';
+import InspectorControlsFill from './fill';
+import InspectorControlsSlot from './slot';
 
-const { Fill, Slot } = createSlotFill( 'InspectorControls' );
+const InspectorControls = InspectorControlsFill;
 
-function InspectorControls( { children } ) {
-	return useDisplayBlockControls() ? (
-		<StyleProvider document={ document }>
-			<Fill>{ children }</Fill>
-		</StyleProvider>
-	) : null;
-}
+InspectorControls.Slot = InspectorControlsSlot;
 
-InspectorControls.Slot = Slot;
+// This is just here for backward compatibility.
+export const InspectorAdvancedControls = ( props ) => {
+	return (
+		<InspectorControlsFill { ...props } __experimentalGroup="advanced" />
+	);
+};
+InspectorAdvancedControls.Slot = ( props ) => {
+	return (
+		<InspectorControlsSlot { ...props } __experimentalGroup="advanced" />
+	);
+};
+InspectorAdvancedControls.slotName = 'InspectorAdvancedControls';
 
 /**
  * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md

package/src/components/inspector-controls/slot.js

@@ -0,0 +1,45 @@
+/**
+ * WordPress dependencies
+ */
+import { __experimentalUseSlot as useSlot } from '@wordpress/components';
+import warning from '@wordpress/warning';
+
+/**
+ * Internal dependencies
+ */
+import BlockSupportToolsPanel from './block-support-tools-panel';
+import BlockSupportSlotContainer from './block-support-slot-container';
+import groups from './groups';
+
+export default function InspectorControlsSlot( {
+	__experimentalGroup: group = 'default',
+	bubblesVirtually = true,
+	label,
+	...props
+} ) {
+	const Slot = groups[ group ]?.Slot;
+	const slot = useSlot( Slot?.__unstableName );
+	if ( ! Slot || ! slot ) {
+		warning( `Unknown InspectorControl group "${ group }" provided.` );
+		return null;
+	}
+
+	const hasFills = Boolean( slot.fills && slot.fills.length );
+	if ( ! hasFills ) {
+		return null;
+	}
+
+	if ( label ) {
+		return (
+			<BlockSupportToolsPanel group={ group } label={ label }>
+				<BlockSupportSlotContainer
+					{ ...props }
+					bubblesVirtually={ bubblesVirtually }
+					Slot={ Slot }
+				/>
+			</BlockSupportToolsPanel>
+		);
+	}
+
+	return <Slot { ...props } bubblesVirtually={ bubblesVirtually } />;
+}

package/src/components/inspector-controls/slot.native.js

@@ -0,0 +1,22 @@
+/**
+ * WordPress dependencies
+ */
+import warning from '@wordpress/warning';
+
+/**
+ * Internal dependencies
+ */
+import groups from './groups';
+
+export default function InspectorControlsSlot( {
+	__experimentalGroup: group = 'default',
+	...props
+} ) {
+	const Slot = groups[ group ]?.Slot;
+	if ( ! Slot ) {
+		warning( `Unknown InspectorControl group "${ group }" provided.` );
+		return null;
+	}
+
+	return <Slot { ...props } />;
+}

package/src/components/letter-spacing-control/index.js

@@ -15,12 +15,18 @@ import useSetting from '../../components/use-setting';
 /**
  * Control for letter-spacing.
  *
- * @param {Object}   props          Component props.
- * @param {string}   props.value    Currently selected letter-spacing.
- * @param {Function} props.onChange Handles change in letter-spacing selection.
- * @return {WPElement}                      Letter-spacing control.
+ * @param {Object}   props                      Component props.
+ * @param {string}   props.value                Currently selected letter-spacing.
+ * @param {Function} props.onChange             Handles change in letter-spacing selection.
+ * @param {boolean}  props.__unstableInputWidth Input width to pass through to inner UnitControl.
+ *
+ * @return {WPElement}                          Letter-spacing control.
  */
-export default function LetterSpacingControl( { value, onChange } ) {
+export default function LetterSpacingControl( {
+	value,
+	onChange,
+	__unstableInputWidth = '60px',
+} ) {
 	const units = useCustomUnits( {
 		availableUnits: useSetting( 'spacing.units' ) || [ 'px', 'em', 'rem' ],
 		defaultValues: { px: '2', em: '.2', rem: '.2' },
@@ -29,7 +35,7 @@ export default function LetterSpacingControl( { value, onChange } ) {
 		<UnitControl
 			label={ __( 'Letter-spacing' ) }
 			value={ value }
-			__unstableInputWidth="60px"
+			__unstableInputWidth={ __unstableInputWidth }
 			units={ units }
 			onChange={ onChange }
 		/>

package/src/components/line-height-control/index.native.js

@@ -0,0 +1,25 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { UnitControl } from '@wordpress/components';
+/**
+ * Internal dependencies
+ */
+import { BASE_DEFAULT_VALUE, STEP, isLineHeightDefined } from './utils';
+
+export default function LineHeightControl( { value: lineHeight, onChange } ) {
+	const isDefined = isLineHeightDefined( lineHeight );
+	const value = isDefined ? lineHeight : BASE_DEFAULT_VALUE;
+	return (
+		<UnitControl
+			label={ __( 'Line Height' ) }
+			min={ 0 }
+			max={ 5 }
+			step={ STEP }
+			value={ value }
+			onChange={ onChange }
+			units={ false }
+		/>
+	);
+}

package/src/components/link-control/README.md

@@ -2,17 +2,7 @@
 
 Renders a link control. A link control is a controlled input which maintains a value associated with a link (HTML anchor element) and relevant settings for how that link is expected to behave.
 
-It is designed to provide a standardized UI for the creation of a link throughout the Editor.
-
-## History
-
-Much of the context for this component can be found in [the original Issue](https://github.com/WordPress/gutenberg/issues/17557).
-
-Previously iterations of a hyperlink UI existed within the Gutenberg interface but these tended to be highly tailored to their individual use cases and were not standardized, each having their own implementation.
-
-These older UIs tended to make use of two existing components: `URLInput` and `URLPopover`. When a requirement was raised to implement a new UI for hyperlink creation, an assessment of these existing components was undertaken and it was determined that they were too opinionated as to be easily refactored to accommodate the new use cases required by the new UI. Attempting to do so would also have meant unavoidable breaking changes to the interface of `URLInput` which would have (most probably) caused breaking changes to ripple across not only the Core codebase, but also that of 3rd party Plugins.
-
-As a result, it was agreed that a new component `LinkControl` would be created to realise the new hyperlink creation interface. This new UI would begin life as an experimental component which would consume `URLInput` internally. The API of `URLInput` would be enhanced as required with "experimental" features to facilitate the implementation of the new UI.
+It is designed to provide a standardized UI for the creation of a link throughout the Editor, see History section at bottom for further background.
 
 ## Relationship to `<URLInput>`
 
@@ -29,7 +19,7 @@ The distinction between the two components is perhaps best summarized by the fol
 
 When creating links the `LinkControl` component will handle two kinds of input from users:
 
-1. Entity searches - the user may input free-text based search queries for entities retrieved from remote data sources (in the context of WordPress these are `Pages`). For example, a user might search for a `Page` they have just created by name (eg: About) and the UI will return a matching result if found.
+1. Entity searches - the user may input free-text based search queries for entities retrieved from remote data sources (in the context of WordPress these are post-type entities). For example, a user might search for a `Page` they have just created by name (eg: About) and the UI will return a matching result if found.
 2. Direct entry - the user may also enter any arbitrary URL-like text. This includes full URLs (https://), URL fragements (eg: `#myinternallink`), `tel` protocol links (eg: `tel: 0800 1234`) and `mailto` protocol links (eg: `mailto: hello@wordpress.org`).
 
 In addition, `<LinkControl>` also allows for on the fly creation of links based on the **current content of the `<input>` element**. When enabled, a default "Create new" search suggestion is appended to all non-URL-like search results.
@@ -38,7 +28,9 @@ When this suggestion is selected it will call the `createSuggestion` prop afford
 
 ### Data sources
 
-By default `LinkControl` utilizes the `__experimentalFetchLinkSuggestions` API from `core/block-editor` in order to retrieve search suggestions for matching `Page` post-type entities.
+By default `LinkControl` utilizes the `__experimentalFetchLinkSuggestions` API from `core/block-editor` in order to retrieve search suggestions for matching post-type entities.
+
+By default this provides no functionality and so you must implement and provide this in your own Editor instance ([example](https://github.com/WordPress/gutenberg/blob/65c752816f46a9334b84f4801d80dea00ed76fba/packages/editor/src/components/provider/use-block-editor-settings.js#L114-L115)).
 
 ## Props
 
@@ -63,7 +55,7 @@ The resulting default properties of `value` include:
 -   Required: No
 -   Default:
 
-```
+```js
 [
 	{
 		id: 'opensInNewTab',
@@ -74,6 +66,14 @@ The resulting default properties of `value` include:
 
 An array of settings objects associated with a link (for example: a setting to determine whether or not the link opens in a new tab). Each object will be used to render a `ToggleControl` for that setting.
 
+To disable settings, pass in an empty array. for example:
+
+```jsx
+<LinkControl
+	settings={ [] }
+/>
+```
+
 ### onChange
 
 -   Type: `Function`
@@ -105,6 +105,22 @@ Whether to present suggestions when typing the URL.
 
 Whether to present initial suggestions immediately.
 
+### suggestionsQuery
+
+-   Type: `Object`
+-   Required: No
+
+Controls the query parameters used to search for suggestions. For example, to limit a query to just `Page` types use:
+
+```jsx
+<LinkControl
+	suggestionQuery={ {
+		type: 'post',
+		subtype: 'page',
+	} }
+/>
+```
+
 ### forceIsEditingLink
 
 -   Type: `boolean`
@@ -176,6 +192,13 @@ A `suggestion` should have the following shape:
 	)}
 />
 ```
+### renderControlBottom 
+
+-   Type: `Function`
+-   Required: No
+-   Default: null
+
+A render prop that can be used to pass optional controls to be rendered at the bottom of the component.
 
 # LinkControlSearchInput
 
@@ -527,3 +550,13 @@ If true, type of the suggestion is rendered (e.g. post, tag)
 The suggestion to render.
 
 See the [createSuggestion](#createSuggestion) section of this file to learn more about suggestions.
+
+## History
+
+Much of the context for this component can be found in [the original Issue](https://github.com/WordPress/gutenberg/issues/17557).
+
+Previously iterations of a hyperlink UI existed within the Gutenberg interface but these tended to be highly tailored to their individual use cases and were not standardized, each having their own implementation.
+
+These older UIs tended to make use of two existing components: `URLInput` and `URLPopover`. When a requirement was raised to implement a new UI for hyperlink creation, an assessment of these existing components was undertaken and it was determined that they were too opinionated as to be easily refactored to accommodate the new use cases required by the new UI. Attempting to do so would also have meant unavoidable breaking changes to the interface of `URLInput` which would have (most probably) caused breaking changes to ripple across not only the Core codebase, but also that of 3rd party Plugins.
+
+As a result, it was agreed that a new component `LinkControl` would be created to realise the new hyperlink creation interface. This new UI would begin life as an experimental component which would consume `URLInput` internally. The API of `URLInput` would be enhanced as required with "experimental" features to facilitate the implementation of the new UI.

package/src/components/link-control/index.js

@@ -2,11 +2,12 @@
  * External dependencies
  */
 import { noop } from 'lodash';
+import classnames from 'classnames';
 
 /**
  * WordPress dependencies
  */
-import { Button, Spinner, Notice } from '@wordpress/components';
+import { Button, Spinner, Notice, TextControl } from '@wordpress/components';
 import { keyboardReturn } from '@wordpress/icons';
 import { __ } from '@wordpress/i18n';
 import { useRef, useState, useEffect } from '@wordpress/element';
@@ -93,6 +94,7 @@ import { DEFAULT_LINK_SETTINGS } from './constants';
  * @property {Object=}                    suggestionsQuery           Query parameters to pass along to wp.blockEditor.__experimentalFetchLinkSuggestions.
  * @property {boolean=}                   noURLSuggestion            Whether to add a fallback suggestion which treats the search query as a URL.
  * @property {string|Function|undefined}  createSuggestionButtonText The text to use in the button that calls createSuggestion.
+ * @property {Function}                   renderControlBottom        Optional controls to be rendered at the bottom of the component.
  */
 
 /**
@@ -119,6 +121,8 @@ function LinkControl( {
 	noURLSuggestion = false,
 	createSuggestionButtonText,
 	hasRichPreviews = false,
+	hasTextControl = false,
+	renderControlBottom = null,
 } ) {
 	if ( withCreateSuggestion === undefined && createSuggestion ) {
 		withCreateSuggestion = true;
@@ -126,8 +130,13 @@ function LinkControl( {
 
 	const isMounting = useRef( true );
 	const wrapperNode = useRef();
+	const textInputRef = useRef();
+
 	const [ internalInputValue, setInternalInputValue ] = useState(
-		( value && value.url ) || ''
+		value?.url || ''
+	);
+	const [ internalTextValue, setInternalTextValue ] = useState(
+		value?.title || ''
 	);
 	const currentInputValue = propInputValue || internalInputValue;
 	const [ isEditingLink, setIsEditingLink ] = useState(
@@ -137,6 +146,8 @@ function LinkControl( {
 	);
 	const isEndingEditWithFocus = useRef( false );
 
+	const currentInputIsEmpty = ! currentInputValue?.trim()?.length;
+
 	useEffect( () => {
 		if (
 			forceIsEditingLink !== undefined &&
@@ -147,22 +158,53 @@ function LinkControl( {
 	}, [ forceIsEditingLink ] );
 
 	useEffect( () => {
+		// We don't auto focus into the Link UI on mount
+		// because otherwise using the keyboard to select text
+		// *within* the link format is not possible.
 		if ( isMounting.current ) {
 			isMounting.current = false;
 			return;
 		}
+		// Unless we are mounting, we always want to focus either:
+		// - the URL input
+		// - the first focusable element in the Link UI.
+		// But in editing mode if there is a text input present then
+		// the URL input is at index 1. If not then it is at index 0.
+		const whichFocusTargetIndex = textInputRef?.current ? 1 : 0;
 
-		// When switching between editable and non editable LinkControl
-		// move focus to the first element to avoid focus loss.
+		// Scenario - when:
+		// - switching between editable and non editable LinkControl
+		// - clicking on a link
+		// ...then move focus to the *first* element to avoid focus loss
+		// and to ensure focus is *within* the Link UI.
 		const nextFocusTarget =
-			focus.focusable.find( wrapperNode.current )[ 0 ] ||
-			wrapperNode.current;
+			focus.focusable.find( wrapperNode.current )[
+				whichFocusTargetIndex
+			] || wrapperNode.current;
 
 		nextFocusTarget.focus();
 
 		isEndingEditWithFocus.current = false;
 	}, [ isEditingLink ] );
 
+	useEffect( () => {
+		/**
+		 * If the value's `text` property changes then sync this
+		 * back up with state.
+		 */
+		if ( value?.title && value.title !== internalTextValue ) {
+			setInternalTextValue( value.title );
+		}
+
+		/**
+		 * Update the state value internalInputValue if the url value changes
+		 * for example when clicking on another anchor
+		 */
+		if ( value?.url ) {
+			setInternalInputValue( value.url );
+		}
+	}, [ value ] );
+
 	/**
 	 * Cancels editing state and marks that focus may need to be restored after
 	 * the next render, if focus was within the wrapper when editing finished.
@@ -180,22 +222,47 @@ function LinkControl( {
 	);
 
 	const handleSelectSuggestion = ( updatedValue ) => {
-		onChange( updatedValue );
+		onChange( {
+			...updatedValue,
+			title: internalTextValue || updatedValue?.title,
+		} );
 		stopEditing();
 	};
 
-	const handleSubmitButton = () => {
-		if ( currentInputValue !== value?.url ) {
-			onChange( { url: currentInputValue } );
+	const handleSubmit = () => {
+		if (
+			currentInputValue !== value?.url ||
+			internalTextValue !== value?.title
+		) {
+			onChange( {
+				url: currentInputValue,
+				title: internalTextValue,
+			} );
 		}
 		stopEditing();
 	};
 
+	const handleSubmitWithEnter = ( event ) => {
+		const { keyCode } = event;
+		if (
+			keyCode === ENTER &&
+			! currentInputIsEmpty // disallow submitting empty values.
+		) {
+			event.preventDefault();
+			handleSubmit();
+		}
+	};
+
 	const shownUnlinkControl =
 		onRemove && value && ! isEditingLink && ! isCreatingPage;
 
 	const showSettingsDrawer = !! settings?.length;
 
+	// Only show text control once a URL value has been committed
+	// and it isn't just empty whitespace.
+	// See https://github.com/WordPress/gutenberg/pull/33849/#issuecomment-932194927.
+	const showTextControl = value?.url?.trim()?.length > 0 && hasTextControl;
+
 	return (
 		<div
 			tabIndex={ -1 }
@@ -210,10 +277,26 @@ function LinkControl( {
 
 			{ ( isEditingLink || ! value ) && ! isCreatingPage && (
 				<>
-					<div className="block-editor-link-control__search-input-wrapper">
+					<div
+						className={ classnames( {
+							'block-editor-link-control__search-input-wrapper': true,
+							'has-text-control': showTextControl,
+						} ) }
+					>
+						{ showTextControl && (
+							<TextControl
+								ref={ textInputRef }
+								className="block-editor-link-control__field block-editor-link-control__text-content"
+								label="Text"
+								value={ internalTextValue }
+								onChange={ setInternalTextValue }
+								onKeyDown={ handleSubmitWithEnter }
+							/>
+						) }
+
 						<LinkControlSearchInput
 							currentLink={ value }
-							className="block-editor-link-control__search-input"
+							className="block-editor-link-control__field block-editor-link-control__search-input"
 							placeholder={ searchInputPlaceholder }
 							value={ currentInputValue }
 							withCreateSuggestion={ withCreateSuggestion }
@@ -228,20 +311,15 @@ function LinkControl( {
 							createSuggestionButtonText={
 								createSuggestionButtonText
 							}
+							useLabel={ showTextControl }
 						>
 							<div className="block-editor-link-control__search-actions">
 								<Button
-									onClick={ () => handleSubmitButton() }
-									onKeyDown={ ( event ) => {
-										const { keyCode } = event;
-										if ( keyCode === ENTER ) {
-											event.preventDefault();
-											handleSubmitButton();
-										}
-									} }
+									onClick={ handleSubmit }
 									label={ __( 'Submit' ) }
 									icon={ keyboardReturn }
 									className="block-editor-link-control__search-submit"
+									disabled={ currentInputIsEmpty } // disallow submitting empty values.
 								/>
 							</div>
 						</LinkControlSearchInput>
@@ -264,28 +342,21 @@ function LinkControl( {
 					value={ value }
 					onEditClick={ () => setIsEditingLink( true ) }
 					hasRichPreviews={ hasRichPreviews }
+					hasUnlinkControl={ shownUnlinkControl }
+					onRemove={ onRemove }
 				/>
 			) }
 
-			{ ( showSettingsDrawer || shownUnlinkControl ) && (
+			{ showSettingsDrawer && (
 				<div className="block-editor-link-control__tools">
 					<LinkControlSettingsDrawer
 						value={ value }
 						settings={ settings }
 						onChange={ onChange }
 					/>
-					{ shownUnlinkControl && (
-						<Button
-							className="block-editor-link-control__unlink"
-							isDestructive
-							variant="link"
-							onClick={ onRemove }
-						>
-							{ __( 'Unlink' ) }
-						</Button>
-					) }
 				</div>
 			) }
+			{ renderControlBottom && renderControlBottom() }
 		</div>
 	);
 }