Improve Link Control accessibility

packages/block-editor/src/components/link-control/index.js

@@ -6,16 +6,23 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { Button, Spinner, Notice, TextControl } from '@wordpress/components';
-import { __ } from '@wordpress/i18n';
+import {
+	Button,
+	Spinner,
+	Notice,
+	TextControl,
+	VisuallyHidden,
+} from '@wordpress/components';
+import { __, sprintf } from '@wordpress/i18n';
 import { useRef, useState, useEffect } from '@wordpress/element';
 import { focus } from '@wordpress/dom';
 import { ENTER } from '@wordpress/keycodes';
 import { isShallowEqualObjects } from '@wordpress/is-shallow-equal';
 import { useSelect, useDispatch } from '@wordpress/data';
 import { store as preferencesStore } from '@wordpress/preferences';
 import { keyboardReturn } from '@wordpress/icons';
-
+import { useInstanceId } from '@wordpress/compose';
+import { speak } from '@wordpress/a11y';
 /**
  * Internal dependencies
  */
@@ -201,11 +208,24 @@ function LinkControl( {
 	const { createPage, isCreatingPage, errorMessage } =
 		useCreatePage( createSuggestion );
 
+	function setEditingMode( nextEditingMode ) {
+		setIsEditingLink( nextEditingMode );
+
+		speak(
+			nextEditingMode
+				? __( 'Entering link edit mode' )
+				: __( 'Leaving link edit mode' ),
+			'assertive'
+		);
+	}
+
 	useEffect( () => {
 		if ( forceIsEditingLink === undefined ) {
 			return;
 		}
 
+		// Do not announcement automatic mode state change
+		// via speak().
 		setIsEditingLink( forceIsEditingLink );
 	}, [ forceIsEditingLink ] );
 
@@ -243,7 +263,7 @@ function LinkControl( {
 			wrapperNode.current.ownerDocument.activeElement
 		);
 
-		setIsEditingLink( false );
+		setEditingMode( false );
 	};
 
 	const handleSelectSuggestion = ( updatedValue ) => {
@@ -335,23 +355,54 @@ function LinkControl( {
 	const showTextControl = hasLinkValue && hasTextControl;
 
 	const isEditing = ( isEditingLink || ! value ) && ! isCreatingPage;
+	const isCreating = isEditingLink && ! value && ! isCreatingPage;
 	const isDisabled = ! valueHasChanges || currentInputIsEmpty;
 	const showSettings = !! settings?.length && isEditingLink && hasLinkValue;
 
+	const dialogTitleId = useInstanceId(
+		LinkControl,
+		`block-editor-link-control___title`
+	);
+	const dialogDescritionId = useInstanceId(
+		LinkControl,
+		`block-editor-link-control___description`
+	);
+
+	const isPreviewing = value && ! isEditingLink && ! isCreatingPage;
 	return (
 		<div
 			tabIndex={ -1 }
 			ref={ wrapperNode }
 			className="block-editor-link-control"
+			aria-labelledby={ dialogTitleId }
+			aria-describedby={ dialogDescritionId }
 		>
 			{ isCreatingPage && (
 				<div className="block-editor-link-control__loading">
-					<Spinner /> { __( 'Creating' ) }…
+					<Spinner />
+					{ __( 'Creating' ) }…
 				</div>
 			) }
 
 			{ isEditing && (
 				<>
+					<VisuallyHidden>
+						<h2 id={ dialogTitleId }>
+							{ sprintf(
+								// translators: %s: action name for the link mode (edit or create).
+								__( '%s Link' ),
+								isCreating ? __( 'Create' ) : __( 'Edit' )
+							) }
+						</h2>
+
+						<p id={ dialogDescritionId }>
+							{ sprintf(
+								// translators: %s: action name for the link action (edit or create).
+								__( '%s the link' ),
+								isCreating ? __( 'Creating' ) : __( 'Editing' )
+							) }
+						</p>
+					</VisuallyHidden>
 					<div
 						className={ classnames( {
 							'block-editor-link-control__search-input-wrapper': true,
@@ -411,75 +462,86 @@ function LinkControl( {
 							{ errorMessage }
 						</Notice>
 					) }
-				</>
-			) }
 
-			{ value && ! isEditingLink && ! isCreatingPage && (
-				<LinkPreview
-					key={ value?.url } // force remount when URL changes to avoid race conditions for rich previews
-					value={ value }
-					onEditClick={ () => setIsEditingLink( true ) }
-					hasRichPreviews={ hasRichPreviews }
-					hasUnlinkControl={ shownUnlinkControl }
-					additionalControls={ () => {
-						// Expose the "Opens in new tab" settings in the preview
-						// as it is the most common setting to change.
-						if (
-							settings?.find(
-								( setting ) => setting.id === 'opensInNewTab'
-							)
-						) {
-							return (
-								<LinkSettings
-									value={ internalControlValue }
-									settings={ settings?.filter(
-										( { id } ) => id === 'opensInNewTab'
-									) }
-									onChange={ onChange }
-								/>
-							);
-						}
-					} }
-					onRemove={ () => {
-						onRemove();
-						setIsEditingLink( true );
-					} }
-				/>
-			) }
+					{ showSettings && (
+						<div className="block-editor-link-control__tools">
+							{ ! currentInputIsEmpty && (
+								<LinkControlSettingsDrawer
+									settingsOpen={ isSettingsOpen }
+									setSettingsOpen={
+										setSettingsOpenWithPreference
+									}
+								>
+									<LinkSettings
+										value={ internalControlValue }
+										settings={ settings }
+										onChange={ createSetInternalSettingValueHandler(
+											settingsKeys
+										) }
+									/>
+								</LinkControlSettingsDrawer>
+							) }
+						</div>
+					) }
 
-			{ showSettings && (
-				<div className="block-editor-link-control__tools">
-					{ ! currentInputIsEmpty && (
-						<LinkControlSettingsDrawer
-							settingsOpen={ isSettingsOpen }
-							setSettingsOpen={ setSettingsOpenWithPreference }
-						>
-							<LinkSettings
-								value={ internalControlValue }
-								settings={ settings }
-								onChange={ createSetInternalSettingValueHandler(
-									settingsKeys
-								) }
-							/>
-						</LinkControlSettingsDrawer>
+					{ showActions && (
+						<div className="block-editor-link-control__search-actions">
+							<Button
+								variant="primary"
+								onClick={ isDisabled ? noop : handleSubmit }
+								className="block-editor-link-control__search-submit"
+								aria-disabled={ isDisabled }
+							>
+								{ __( 'Save' ) }
+							</Button>
+							<Button variant="tertiary" onClick={ handleCancel }>
+								{ __( 'Cancel' ) }
+							</Button>
+						</div>
 					) }
-				</div>
+				</>
 			) }
 
-			{ showActions && (
-				<div className="block-editor-link-control__search-actions">
-					<Button
-						variant="primary"
-						onClick={ isDisabled ? noop : handleSubmit }
-						className="block-editor-link-control__search-submit"
-						aria-disabled={ isDisabled }
-					>
-						{ __( 'Save' ) }
-					</Button>
-					<Button variant="tertiary" onClick={ handleCancel }>
-						{ __( 'Cancel' ) }
-					</Button>
-				</div>
+			{ isPreviewing && (
+				<>
+					<VisuallyHidden>
+						<h2 id={ dialogTitleId }>{ __( 'Preview Link' ) }</h2>
+						<p id={ dialogDescritionId }>
+							{ __( 'Previewing the currently selected link.' ) }
+						</p>
+					</VisuallyHidden>
+					<LinkPreview
+						key={ value?.url } // force remount when URL changes to avoid race conditions for rich previews
+						value={ value }
+						onEditClick={ () => setEditingMode( true ) }
+						hasRichPreviews={ hasRichPreviews }
+						hasUnlinkControl={ shownUnlinkControl }
+						additionalControls={ () => {
+							// Expose the "Opens in new tab" settings in the preview
+							// as it is the most common setting to change.
+							if (
+								settings?.find(
+									( setting ) =>
+										setting.id === 'opensInNewTab'
+								)
+							) {
+								return (
+									<LinkSettings
+										value={ internalControlValue }
+										settings={ settings?.filter(
+											( { id } ) => id === 'opensInNewTab'
+										) }
+										onChange={ onChange }
+									/>
+								);
+							}
+						} }
+						onRemove={ () => {
+							onRemove();
+							setEditingMode( true );
+						} }
+					/>
+				</>
 			) }
 
 			{ renderControlBottom && renderControlBottom() }

packages/block-editor/src/components/link-control/link-preview.js

@@ -10,6 +10,7 @@ import { __ } from '@wordpress/i18n';
 import {
 	Button,
 	ExternalLink,
+	VisuallyHidden,
 	__experimentalText as Text,
 } from '@wordpress/components';
 import { filterURLForDisplay, safeDecodeURI } from '@wordpress/url';
@@ -20,7 +21,6 @@ import { __unstableStripHTML as stripHTML } from '@wordpress/dom';
  * Internal dependencies
  */
 import { ViewerSlot } from './viewer-slot';
-
 import useRichUrlData from './use-rich-url-data';
 
 export default function LinkPreview( {
@@ -84,28 +84,43 @@ export default function LinkPreview( {
 					>
 						{ icon }
 					</span>
-					<span className="block-editor-link-control__search-item-details">
+					<dl className="block-editor-link-control__search-item-details">
 						{ ! isEmptyURL ? (
 							<>
-								<ExternalLink
-									className="block-editor-link-control__search-item-title"
-									href={ value.url }
-								>
-									{ displayTitle }
-								</ExternalLink>
+								<VisuallyHidden>
+									<dt>Link title</dt>
+								</VisuallyHidden>
+								<dd>
+									<ExternalLink
+										className="block-editor-link-control__search-item-title"
+										href={ value.url }
+									>
+										{ displayTitle }
+									</ExternalLink>
+								</dd>
 
 								{ value?.url && displayTitle !== displayURL && (
-									<span className="block-editor-link-control__search-item-info">
-										{ displayURL }
-									</span>
+									<>
+										<VisuallyHidden>
+											<dt>Link URL</dt>
+										</VisuallyHidden>
+										<dd className="block-editor-link-control__search-item-info">
+											{ displayURL }
+										</dd>
+									</>
 								) }
 							</>
 						) : (
-							<span className="block-editor-link-control__search-item-error-notice">
-								{ __( 'Link is empty' ) }
-							</span>
+							<>
+								<VisuallyHidden>
+									<dt>Link value</dt>
+								</VisuallyHidden>
+								<dd className="block-editor-link-control__search-item-error-notice">
+									{ __( 'Link is empty' ) }
+								</dd>
+							</>
 						) }
-					</span>
+					</dl>
 				</span>
 
 				<Button

packages/block-editor/src/components/link-control/style.scss

@@ -412,6 +412,16 @@ $preview-image-height: 140px;
 	padding-right: $grid-unit-20;
 }
 
+.block-editor-link-control__search-item-details {
+	margin-block-start: 0;
+	margin-block-end: 0;
+
+	dd {
+		margin-inline-start: 0;
+		margin-block-end: 0;
+	}
+}
+
 .block-editor-link-control__setting {
 	margin-bottom: 0;
 	flex: 1;

packages/block-library/src/navigation-link/link-ui.js

@@ -4,6 +4,7 @@
 import { __unstableStripHTML as stripHTML } from '@wordpress/dom';
 import { Popover, Button } from '@wordpress/components';
 import { __, sprintf } from '@wordpress/i18n';
+import { speak } from '@wordpress/a11y';
 import {
 	__experimentalLinkControl as LinkControl,
 	BlockIcon,
@@ -139,6 +140,14 @@ export function LinkUI( props ) {
 			status: 'draft',
 		} );
 
+		speak(
+			sprintf(
+				/* translators: %s: title of the page that has been created. */
+				__( 'Draft Page "%s" created.' ),
+				pageTitle
+			)
+		);
+
 		return {
 			id: page.id,
 			type: postType,
@@ -180,6 +189,7 @@ export function LinkUI( props ) {
 
 	return (
 		<Popover
+			role="dialog"
 			placement="bottom"
 			onClose={ props.onClose }
 			anchor={ props.anchor }