Fix/screen reader text (#20607)

* First stab at using VisuallyHidden component

* Completely replace screen-reader-text with <VisuallyHidden />

* Consistency changes with as="" property

* Remove extra space

* Formatting

* Formatting

* Restore .screen-reader-text CSS class in PHP files

* Use as="" instead of extra div

* Formatting change

* Use as="" instead of wrapping elements with screen-reader-text class

* Remove responsive-block-control/style.css from this PR

* Ensure <RichText tagName="figcaption" is always a direct descendant of <figure>

* Use label props when substituting for label with props

* Formatting

* Pass className to both VisuallyHidden and RichText

* Restore screen-reader-text in AdminNotices test

* Restore original formatting in admin-notices/test/index.js

packages/block-editor/src/components/block-navigation/list.js

@@ -7,7 +7,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { Button } from '@wordpress/components';
+import { Button, VisuallyHidden } from '@wordpress/components';
 import {
 	__experimentalGetBlockLabel as getBlockLabel,
 	getBlockType,
@@ -58,9 +58,9 @@ export default function BlockNavigationList( {
 								<BlockIcon icon={ blockType.icon } showColors />
 								{ getBlockLabel( blockType, block.attributes ) }
 								{ isSelected && (
-									<span className="screen-reader-text">
+									<VisuallyHidden as="span">
 										{ __( '(selected block)' ) }
-									</span>
+									</VisuallyHidden>
 								) }
 							</Button>
 						</div>

packages/block-editor/src/components/button-block-appender/index.js

@@ -6,7 +6,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { Button, Tooltip } from '@wordpress/components';
+import { Button, Tooltip, VisuallyHidden } from '@wordpress/components';
 import { _x, sprintf } from '@wordpress/i18n';
 import { Icon, plus } from '@wordpress/icons';
 
@@ -62,9 +62,7 @@ function ButtonBlockAppender( {
 							disabled={ disabled }
 							label={ label }
 						>
-							<span className="screen-reader-text">
-								{ label }
-							</span>
+							<VisuallyHidden as="span">{ label }</VisuallyHidden>
 							<Icon icon={ plus } />
 						</Button>
 					</Tooltip>

packages/block-editor/src/components/inserter/menu.js

@@ -20,7 +20,11 @@ import scrollIntoView from 'dom-scroll-into-view';
 import { speak } from '@wordpress/a11y';
 import { __, _n, _x, sprintf } from '@wordpress/i18n';
 import { Component, createRef } from '@wordpress/element';
-import { PanelBody, withSpokenMessages } from '@wordpress/components';
+import {
+	PanelBody,
+	withSpokenMessages,
+	VisuallyHidden,
+} from '@wordpress/components';
 import {
 	isReusableBlock,
 	createBlock,
@@ -316,12 +320,12 @@ export class InserterMenu extends Component {
 				onKeyDown={ this.onKeyDown }
 			>
 				<div className="block-editor-inserter__main-area">
-					<label
+					<VisuallyHidden
+						as="label"
 						htmlFor={ `block-editor-inserter__search-${ instanceId }` }
-						className="screen-reader-text"
 					>
 						{ __( 'Search for a block' ) }
-					</label>
+					</VisuallyHidden>
 					<input
 						id={ `block-editor-inserter__search-${ instanceId }` }
 						type="search"

packages/block-editor/src/components/link-control/settings-drawer.js

@@ -7,7 +7,7 @@ import { noop } from 'lodash';
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
-import { ToggleControl } from '@wordpress/components';
+import { ToggleControl, VisuallyHidden } from '@wordpress/components';
 
 const defaultSettings = [
 	{
@@ -44,9 +44,9 @@ const LinkControlSettingsDrawer = ( {
 
 	return (
 		<fieldset className="block-editor-link-control__settings">
-			<legend className="screen-reader-text">
+			<VisuallyHidden as="legend">
 				{ __( 'Currently selected link settings' ) }
-			</legend>
+			</VisuallyHidden>
 			{ theSettings }
 		</fieldset>
 	);

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

@@ -1,3 +1,3 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`Basic rendering should render 1`] = `"<div tabindex=\\"-1\\" class=\\"block-editor-link-control\\"><form><div class=\\"block-editor-link-control__search-input-wrapper\\"><div class=\\"components-base-control block-editor-url-input block-editor-link-control__search-input\\"><div class=\\"components-base-control__field\\"><input class=\\"block-editor-url-input__input\\" type=\\"text\\" aria-label=\\"URL\\" required=\\"\\" placeholder=\\"Search or type url\\" role=\\"combobox\\" aria-expanded=\\"false\\" aria-autocomplete=\\"list\\" aria-owns=\\"block-editor-url-input-suggestions-0\\" value=\\"\\"></div></div><div class=\\"block-editor-link-control__search-actions\\"><button type=\\"submit\\" class=\\"components-button block-editor-link-control__search-submit has-icon\\" aria-label=\\"Submit\\"><svg width=\\"24\\" height=\\"24\\" xmlns=\\"http://www.w3.org/2000/svg\\" viewBox=\\"-2 -2 24 24\\" role=\\"img\\" aria-hidden=\\"true\\" focusable=\\"false\\"><path d=\\"M16 4h2v9H7v3l-5-4 5-4v3h9V4z\\"></path></svg></button></div></div></form><fieldset class=\\"block-editor-link-control__settings\\"><legend class=\\"screen-reader-text\\">Currently selected link settings</legend><div class=\\"components-base-control components-toggle-control block-editor-link-control__setting\\"><div class=\\"components-base-control__field\\"><span class=\\"components-form-toggle\\"><input class=\\"components-form-toggle__input\\" id=\\"inspector-toggle-control-0\\" type=\\"checkbox\\"><span class=\\"components-form-toggle__track\\"></span><span class=\\"components-form-toggle__thumb\\"></span><svg width=\\"6\\" height=\\"6\\" aria-hidden=\\"true\\" role=\\"img\\" focusable=\\"false\\" xmlns=\\"http://www.w3.org/2000/svg\\" viewBox=\\"0 0 6 6\\" class=\\"components-form-toggle__off\\"><path d=\\"M3 1.5c.8 0 1.5.7 1.5 1.5S3.8 4.5 3 4.5 1.5 3.8 1.5 3 2.2 1.5 3 1.5M3 0C1.3 0 0 1.3 0 3s1.3 3 3 3 3-1.3 3-3-1.3-3-3-3z\\"></path></svg></span><label for=\\"inspector-toggle-control-0\\" class=\\"components-toggle-control__label\\">Open in new tab</label></div></div></fieldset></div>"`;
+exports[`Basic rendering should render 1`] = `"<div tabindex=\\"-1\\" class=\\"block-editor-link-control\\"><form><div class=\\"block-editor-link-control__search-input-wrapper\\"><div class=\\"components-base-control block-editor-url-input block-editor-link-control__search-input\\"><div class=\\"components-base-control__field\\"><input class=\\"block-editor-url-input__input\\" type=\\"text\\" aria-label=\\"URL\\" required=\\"\\" placeholder=\\"Search or type url\\" role=\\"combobox\\" aria-expanded=\\"false\\" aria-autocomplete=\\"list\\" aria-owns=\\"block-editor-url-input-suggestions-0\\" value=\\"\\"></div></div><div class=\\"block-editor-link-control__search-actions\\"><button type=\\"submit\\" class=\\"components-button block-editor-link-control__search-submit has-icon\\" aria-label=\\"Submit\\"><svg width=\\"24\\" height=\\"24\\" xmlns=\\"http://www.w3.org/2000/svg\\" viewBox=\\"-2 -2 24 24\\" role=\\"img\\" aria-hidden=\\"true\\" focusable=\\"false\\"><path d=\\"M16 4h2v9H7v3l-5-4 5-4v3h9V4z\\"></path></svg></button></div></div></form><fieldset class=\\"block-editor-link-control__settings\\"><legend class=\\"components-visually-hidden\\">Currently selected link settings</legend><div class=\\"components-base-control components-toggle-control block-editor-link-control__setting\\"><div class=\\"components-base-control__field\\"><span class=\\"components-form-toggle\\"><input class=\\"components-form-toggle__input\\" id=\\"inspector-toggle-control-0\\" type=\\"checkbox\\"><span class=\\"components-form-toggle__track\\"></span><span class=\\"components-form-toggle__thumb\\"></span><svg width=\\"6\\" height=\\"6\\" aria-hidden=\\"true\\" role=\\"img\\" focusable=\\"false\\" xmlns=\\"http://www.w3.org/2000/svg\\" viewBox=\\"0 0 6 6\\" class=\\"components-form-toggle__off\\"><path d=\\"M3 1.5c.8 0 1.5.7 1.5 1.5S3.8 4.5 3 4.5 1.5 3.8 1.5 3 2.2 1.5 3 1.5M3 0C1.3 0 0 1.3 0 3s1.3 3 3 3 3-1.3 3-3-1.3-3-3-3z\\"></path></svg></span><label for=\\"inspector-toggle-control-0\\" class=\\"components-toggle-control__label\\">Open in new tab</label></div></div></fieldset></div>"`;

packages/block-editor/src/components/responsive-block-control/label.js

@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import { useInstanceId } from '@wordpress/compose';
+import { VisuallyHidden } from '@wordpress/components';
 import { _x, sprintf } from '@wordpress/i18n';
 import { Fragment } from '@wordpress/element';
 
@@ -26,12 +27,9 @@ export default function ResponsiveBlockControlLabel( {
 			<span aria-describedby={ `rbc-desc-${ instanceId }` }>
 				{ viewport.label }
 			</span>
-			<span
-				className="screen-reader-text"
-				id={ `rbc-desc-${ instanceId }` }
-			>
+			<VisuallyHidden as="span" id={ `rbc-desc-${ instanceId }` }>
 				{ accessibleLabel }
-			</span>
+			</VisuallyHidden>
 		</Fragment>
 	);
 }

packages/block-editor/src/components/responsive-block-control/test/__snapshots__/index.js.snap

@@ -1,3 +1,3 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`Basic rendering should render with required props 1`] = `"<fieldset class=\\"block-editor-responsive-block-control\\"><legend class=\\"block-editor-responsive-block-control__title\\">Padding</legend><div class=\\"block-editor-responsive-block-control__inner\\"><div class=\\"components-base-control components-toggle-control block-editor-responsive-block-control__toggle\\"><div class=\\"components-base-control__field\\"><span class=\\"components-form-toggle is-checked\\"><input class=\\"components-form-toggle__input\\" id=\\"inspector-toggle-control-0\\" type=\\"checkbox\\" aria-describedby=\\"inspector-toggle-control-0__help\\" checked=\\"\\"><span class=\\"components-form-toggle__track\\"></span><span class=\\"components-form-toggle__thumb\\"></span><svg width=\\"2\\" height=\\"6\\" xmlns=\\"http://www.w3.org/2000/svg\\" viewBox=\\"0 0 2 6\\" class=\\"components-form-toggle__on\\" role=\\"img\\" aria-hidden=\\"true\\" focusable=\\"false\\"><path d=\\"M0 0h2v6H0z\\"></path></svg></span><label for=\\"inspector-toggle-control-0\\" class=\\"components-toggle-control__label\\">Use the same padding on all screensizes.</label></div><p id=\\"inspector-toggle-control-0__help\\" class=\\"components-base-control__help\\">Toggle between using the same value for all screen sizes or using a unique value per screen size.</p></div><div class=\\"block-editor-responsive-block-control__group\\"><div class=\\"components-base-control\\"><div class=\\"components-base-control__field\\"><label class=\\"components-base-control__label\\" for=\\"inspector-select-control-0\\"><span aria-describedby=\\"rbc-desc-0\\">All</span><span class=\\"screen-reader-text\\" id=\\"rbc-desc-0\\">Controls the padding property for All viewports.</span></label><select id=\\"inspector-select-control-0\\" class=\\"components-select-control__input\\"><option value=\\"\\">Please select</option><option value=\\"small\\">Small</option><option value=\\"medium\\">Medium</option><option value=\\"large\\">Large</option></select></div></div><p id=\\"all\\">All is used here for testing purposes to ensure we have access to details about the device.</p></div></div></fieldset>"`;
+exports[`Basic rendering should render with required props 1`] = `"<fieldset class=\\"block-editor-responsive-block-control\\"><legend class=\\"block-editor-responsive-block-control__title\\">Padding</legend><div class=\\"block-editor-responsive-block-control__inner\\"><div class=\\"components-base-control components-toggle-control block-editor-responsive-block-control__toggle\\"><div class=\\"components-base-control__field\\"><span class=\\"components-form-toggle is-checked\\"><input class=\\"components-form-toggle__input\\" id=\\"inspector-toggle-control-0\\" type=\\"checkbox\\" aria-describedby=\\"inspector-toggle-control-0__help\\" checked=\\"\\"><span class=\\"components-form-toggle__track\\"></span><span class=\\"components-form-toggle__thumb\\"></span><svg width=\\"2\\" height=\\"6\\" xmlns=\\"http://www.w3.org/2000/svg\\" viewBox=\\"0 0 2 6\\" class=\\"components-form-toggle__on\\" role=\\"img\\" aria-hidden=\\"true\\" focusable=\\"false\\"><path d=\\"M0 0h2v6H0z\\"></path></svg></span><label for=\\"inspector-toggle-control-0\\" class=\\"components-toggle-control__label\\">Use the same padding on all screensizes.</label></div><p id=\\"inspector-toggle-control-0__help\\" class=\\"components-base-control__help\\">Toggle between using the same value for all screen sizes or using a unique value per screen size.</p></div><div class=\\"block-editor-responsive-block-control__group\\"><div class=\\"components-base-control\\"><div class=\\"components-base-control__field\\"><label class=\\"components-base-control__label\\" for=\\"inspector-select-control-0\\"><span aria-describedby=\\"rbc-desc-0\\">All</span><span class=\\"components-visually-hidden\\" id=\\"rbc-desc-0\\">Controls the padding property for All viewports.</span></label><select id=\\"inspector-select-control-0\\" class=\\"components-select-control__input\\"><option value=\\"\\">Please select</option><option value=\\"small\\">Small</option><option value=\\"medium\\">Medium</option><option value=\\"large\\">Large</option></select></div></div><p id=\\"all\\">All is used here for testing purposes to ensure we have access to details about the device.</p></div></div></fieldset>"`;

packages/block-library/src/categories/edit.js

@@ -11,6 +11,7 @@ import {
 	Placeholder,
 	Spinner,
 	ToggleControl,
+	VisuallyHidden,
 } from '@wordpress/components';
 import { compose, withInstanceId } from '@wordpress/compose';
 import { withSelect } from '@wordpress/data';
@@ -136,9 +137,9 @@ class CategoriesEdit extends Component {
 		const selectId = `blocks-category-select-${ instanceId }`;
 		return (
 			<>
-				<label htmlFor={ selectId } className="screen-reader-text">
+				<VisuallyHidden as="label" htmlFor={ selectId }>
 					{ __( 'Categories' ) }
-				</label>
+				</VisuallyHidden>
 				<select
 					id={ selectId }
 					className="wp-block-categories__dropdown"

packages/block-library/src/gallery/gallery.js

@@ -7,6 +7,7 @@ import classnames from 'classnames';
  * WordPress dependencies
  */
 import { RichText } from '@wordpress/block-editor';
+import { VisuallyHidden } from '@wordpress/components';
 import { __, sprintf } from '@wordpress/i18n';
 
 /**
@@ -40,10 +41,6 @@ export const Gallery = ( props ) => {
 		images,
 	} = attributes;
 
-	const captionClassNames = classnames( 'blocks-gallery-caption', {
-		'screen-reader-text': ! isSelected && RichText.isEmpty( caption ),
-	} );
-
 	return (
 		<figure
 			className={ classnames( className, {
@@ -91,9 +88,10 @@ export const Gallery = ( props ) => {
 				} ) }
 			</ul>
 			{ mediaPlaceholder }
-			<RichText
+			<RichTextVisibilityHelper
+				isHidden={ ! isSelected && RichText.isEmpty( caption ) }
 				tagName="figcaption"
-				className={ captionClassNames }
+				className="blocks-gallery-caption"
 				placeholder={ __( 'Write gallery caption…' ) }
 				value={ caption }
 				unstableOnFocus={ onFocusGalleryCaption }
@@ -104,4 +102,12 @@ export const Gallery = ( props ) => {
 	);
 };
 
+function RichTextVisibilityHelper( { isHidden, ...richTextProps } ) {
+	return isHidden ? (
+		<VisuallyHidden as={ RichText } { ...richTextProps } />
+	) : (
+		<RichText { ...richTextProps } />
+	);
+}
+
 export default Gallery;

packages/components/src/button/style.scss

@@ -256,7 +256,7 @@
 
 	// Fixes a Safari+VoiceOver bug, where the screen reader text is announced not respecting the source order.
 	// See https://core.trac.wordpress.org/ticket/42006 and https://github.com/h5bp/html5-boilerplate/issues/1985
-	.screen-reader-text {
+	.components-visually-hidden {
 		height: auto;
 	}
 }

packages/components/src/custom-gradient-picker/control-points.js

@@ -16,6 +16,7 @@ import { useInstanceId } from '@wordpress/compose';
 import Button from '../button';
 import ColorPicker from '../color-picker';
 import Dropdown from '../dropdown';
+import VisuallyHidden from '../visually-hidden';
 import {
 	getGradientWithColorAtIndexChanged,
 	getGradientWithControlPointRemoved,
@@ -116,11 +117,11 @@ function ControlPointButton( {
 				} }
 				{ ...additionalProps }
 			/>
-			<div className="screen-reader-text" id={ descriptionId }>
+			<VisuallyHidden id={ descriptionId }>
 				{ __(
 					'Use your left or right arrow keys or drag and drop with the mouse to change the gradient position. Press the button to change the color or remove the control point.'
 				) }
-			</div>
+			</VisuallyHidden>
 		</ControlPointKeyboardMove>
 	);
 }

packages/components/src/custom-select-control/index.js

@@ -11,7 +11,7 @@ import { Icon, check, chevronDown } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
-import { Button } from '../';
+import { Button, VisuallyHidden } from '../';
 
 const itemToString = ( item ) => item && item.name;
 // This is needed so that in Windows, where
@@ -98,19 +98,20 @@ export default function CustomSelectControl( {
 				className
 			) }
 		>
-			{ /* eslint-disable-next-line jsx-a11y/label-has-associated-control, jsx-a11y/label-has-for */ }
-			<label
-				{ ...getLabelProps( {
-					className: classnames(
-						'components-custom-select-control__label',
-						{
-							'screen-reader-text': hideLabelFromVision,
-						}
-					),
-				} ) }
-			>
-				{ label }
-			</label>
+			{ hideLabelFromVision ? (
+				<VisuallyHidden as="label" { ...getLabelProps() }>
+					{ label }
+				</VisuallyHidden>
+			) : (
+				/* eslint-disable-next-line jsx-a11y/label-has-associated-control, jsx-a11y/label-has-for */
+				<label
+					{ ...getLabelProps( {
+						className: 'components-custom-select-control__label',
+					} ) }
+				>
+					{ label }
+				</label>
+			) }
 			<Button
 				{ ...getToggleButtonProps( {
 					// This is needed because some speech recognition software don't support `aria-labelledby`.

packages/components/src/font-size-picker/index.js

@@ -12,6 +12,7 @@ import { textColor } from '@wordpress/icons';
 import Button from '../button';
 import RangeControl from '../range-control';
 import CustomSelectControl from '../custom-select-control';
+import VisuallyHidden from '../visually-hidden';
 
 const DEFAULT_FONT_SIZE = 'default';
 const CUSTOM_FONT_SIZE = 'custom';
@@ -99,9 +100,7 @@ export default function FontSizePicker( {
 	const fontSizePickerNumberId = `components-font-size-picker__number#${ instanceId }`;
 	return (
 		<fieldset className="components-font-size-picker">
-			<legend className="screen-reader-text">
-				{ __( 'Font size' ) }
-			</legend>
+			<VisuallyHidden as="legend">{ __( 'Font size' ) }</VisuallyHidden>
 			<div className="components-font-size-picker__controls">
 				{ fontSizes.length > 0 && (
 					<CustomSelectControl

packages/editor/src/components/post-preview-button/index.js

@@ -8,7 +8,7 @@ import classnames from 'classnames';
  * WordPress dependencies
  */
 import { Component, createRef, renderToString } from '@wordpress/element';
-import { Button, Path, SVG } from '@wordpress/components';
+import { Button, Path, SVG, VisuallyHidden } from '@wordpress/components';
 import { __, _x } from '@wordpress/i18n';
 import { withSelect, withDispatch } from '@wordpress/data';
 import { ifCondition, compose } from '@wordpress/compose';
@@ -207,10 +207,10 @@ export class PostPreviewButton extends Component {
 				{ this.props.textContent
 					? this.props.textContent
 					: _x( 'Preview', 'imperative verb' ) }
-				<span className="screen-reader-text">
+				<VisuallyHidden as="span">
 					{ /* translators: accessibility text */
 					__( '(opens in a new tab)' ) }
-				</span>
+				</VisuallyHidden>
 			</Button>
 		);
 	}

packages/editor/src/components/post-preview-button/test/__snapshots__/index.js.snap

@@ -10,11 +10,11 @@ exports[`PostPreviewButton render() should render currentPostLink otherwise 1`]
   target="wp-preview-1"
 >
   Preview
-  <span
-    className="screen-reader-text"
+  <VisuallyHidden
+    as="span"
   >
     (opens in a new tab)
-  </span>
+  </VisuallyHidden>
 </ForwardRef(Button)>
 `;
 
@@ -28,10 +28,10 @@ exports[`PostPreviewButton render() should render previewLink if provided 1`] =
   target="wp-preview-1"
 >
   Preview
-  <span
-    className="screen-reader-text"
+  <VisuallyHidden
+    as="span"
   >
     (opens in a new tab)
-  </span>
+  </VisuallyHidden>
 </ForwardRef(Button)>
 `;

packages/editor/src/components/post-text-editor/index.js

@@ -11,6 +11,7 @@ import { Component } from '@wordpress/element';
 import { parse } from '@wordpress/blocks';
 import { withSelect, withDispatch } from '@wordpress/data';
 import { withInstanceId, compose } from '@wordpress/compose';
+import { VisuallyHidden } from '@wordpress/components';
 
 export class PostTextEditor extends Component {
 	constructor() {
@@ -67,12 +68,12 @@ export class PostTextEditor extends Component {
 		const { instanceId } = this.props;
 		return (
 			<>
-				<label
+				<VisuallyHidden
+					as="label"
 					htmlFor={ `post-content-${ instanceId }` }
-					className="screen-reader-text"
 				>
 					{ __( 'Type text or HTML' ) }
-				</label>
+				</VisuallyHidden>
 				<Textarea
 					autoComplete="off"
 					dir="auto"