Make accessible toolbar stable and deprecate old usage

docs/manifest.json

@@ -1199,6 +1199,18 @@
 		"markdown_source": "../packages/components/src/toolbar-button/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "ToolbarGroup",
+		"slug": "toolbar-group",
+		"markdown_source": "../packages/components/src/toolbar-group/README.md",
+		"parent": "components"
+	},
+	{
+		"title": "ToolbarItem",
+		"slug": "toolbar-item",
+		"markdown_source": "../packages/components/src/toolbar-item/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "Toolbar",
 		"slug": "toolbar",

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

@@ -7,10 +7,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import {
-	ToolbarGroup,
-	__experimentalToolbarItem as ToolbarItem,
-} from '@wordpress/components';
+import { ToolbarGroup, ToolbarItem } from '@wordpress/components';
 import { getBlockType } from '@wordpress/blocks';
 import { Component } from '@wordpress/element';
 import { withSelect } from '@wordpress/data';

packages/block-editor/src/components/block-settings-menu/index.js

@@ -1,10 +1,7 @@
 /**
  * WordPress dependencies
  */
-import {
-	ToolbarGroup,
-	__experimentalToolbarItem as ToolbarItem,
-} from '@wordpress/components';
+import { ToolbarGroup, ToolbarItem } from '@wordpress/components';
 
 /**
  * Internal dependencies

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

@@ -11,7 +11,7 @@ import {
 	DropdownMenu,
 	ToolbarButton,
 	ToolbarGroup,
-	__experimentalToolbarItem as ToolbarItem,
+	ToolbarItem,
 	MenuGroup,
 	Popover,
 } from '@wordpress/components';

packages/block-editor/src/components/navigable-toolbar/index.js

@@ -9,6 +9,7 @@ import {
 	useEffect,
 	useCallback,
 } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 import { focus } from '@wordpress/dom';
 import { useShortcut } from '@wordpress/keyboard-shortcuts';
 
@@ -23,7 +24,7 @@ function useUpdateLayoutEffect( effect, deps ) {
 }
 
 function hasOnlyToolbarItem( elements ) {
-	const dataProp = 'experimentalToolbarItem';
+	const dataProp = 'toolbarItem';
 	return ! elements.some( ( element ) => ! ( dataProp in element.dataset ) );
 }
 
@@ -59,7 +60,15 @@ function useIsAccessibleToolbar( ref ) {
 
 	const determineIsAccessibleToolbar = useCallback( () => {
 		const tabbables = focus.tabbable.find( ref.current );
-		setIsAccessibleToolbar( hasOnlyToolbarItem( tabbables ) );
+		const onlyToolbarItem = hasOnlyToolbarItem( tabbables );
+		if ( ! onlyToolbarItem ) {
+			deprecated( 'Using custom components as toolbar controls', {
+				alternative: 'ToolbarItem or ToolbarButton components',
+				link:
+					'https://developer.wordpress.org/block-editor/components/toolbar-button/',
+			} );
+		}
+		setIsAccessibleToolbar( onlyToolbarItem );
 	}, [] );
 
 	useLayoutEffect( determineIsAccessibleToolbar, [] );
@@ -106,7 +115,7 @@ function NavigableToolbar( { children, focusOnMount, ...props } ) {
 	if ( isAccessibleToolbar ) {
 		return (
 			<Toolbar
-				__experimentalAccessibilityLabel={ props[ 'aria-label' ] }
+				label={ props[ 'aria-label' ] }
 				ref={ wrapper }
 				{ ...props }
 			>

packages/block-editor/src/components/rich-text/format-toolbar/index.js

@@ -10,7 +10,7 @@ import { orderBy } from 'lodash';
 
 import { __ } from '@wordpress/i18n';
 import {
-	__experimentalToolbarItem as ToolbarItem,
+	ToolbarItem,
 	ToolbarGroup,
 	DropdownMenu,
 	Slot,

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

@@ -7,7 +7,7 @@ import { debounce } from 'lodash';
  * WordPress dependencies
  */
 import { BlockControls } from '@wordpress/block-editor';
-import { Toolbar } from '@wordpress/components';
+import { ToolbarGroup } from '@wordpress/components';
 import { Component } from '@wordpress/element';
 import { __, _x } from '@wordpress/i18n';
 import { BACKSPACE, DELETE, F10, isKeyboardEvent } from '@wordpress/keycodes';
@@ -248,9 +248,9 @@ export default class ClassicEdit extends Component {
 		return (
 			<>
 				<BlockControls>
-					<Toolbar>
+					<ToolbarGroup>
 						<ConvertToBlocksButton clientId={ clientId } />
-					</Toolbar>
+					</ToolbarGroup>
 				</BlockControls>
 				<div
 					key="toolbar"

packages/block-library/src/heading/heading-level-dropdown.js

@@ -69,9 +69,7 @@ export default function HeadingLevelDropdown( { selectedLevel, onChange } ) {
 			renderContent={ () => (
 				<Toolbar
 					className="block-library-heading-level-toolbar"
-					__experimentalAccessibilityLabel={ __(
-						'Change heading level'
-					) }
+					label={ __( 'Change heading level' ) }
 				>
 					<ToolbarGroup
 						isCollapsed={ false }

packages/block-library/src/image/image-editor.js

@@ -20,7 +20,7 @@ import {
 import {
 	ToolbarGroup,
 	ToolbarButton,
-	__experimentalToolbarItem as ToolbarItem,
+	ToolbarItem,
 	Spinner,
 	RangeControl,
 	DropdownMenu,

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

@@ -25,7 +25,7 @@ import {
 	TextControl,
 	ToggleControl,
 	ToolbarGroup,
-	__experimentalToolbarItem as ToolbarItem,
+	ToolbarItem,
 } from '@wordpress/components';
 import {
 	alignLeft,

packages/components/src/index.js

@@ -99,7 +99,7 @@ export { default as Toolbar } from './toolbar';
 export { default as ToolbarButton } from './toolbar-button';
 export { default as __experimentalToolbarContext } from './toolbar-context';
 export { default as ToolbarGroup } from './toolbar-group';
-export { default as __experimentalToolbarItem } from './toolbar-item';
+export { default as ToolbarItem } from './toolbar-item';
 export { default as Tooltip } from './tooltip';
 export {
 	default as __experimentalTreeGrid,

packages/components/src/index.native.js

@@ -18,7 +18,7 @@ export { default as Toolbar } from './toolbar';
 export { default as ToolbarButton } from './toolbar-button';
 export { default as __experimentalToolbarContext } from './toolbar-context';
 export { default as ToolbarGroup } from './toolbar-group';
-export { default as __experimentalToolbarItem } from './toolbar-item';
+export { default as ToolbarItem } from './toolbar-item';
 export { default as Icon } from './icon';
 export { default as IconButton } from './button/deprecated';
 export { default as Spinner } from './spinner';

packages/components/src/toolbar-button/README.md

@@ -1,19 +1,52 @@
 # ToolbarButton
 
-A ToolbarButton can be used to add actions to your block control, usually inside a ToolbarGroup. It has similar features to the [Button](/packages/components/src/button/README.md) component. Using `ToolbarButton` will ensure the correct styling for a button in a toolbar, and also that keyboard interactions in a toolbar are consistent with the [WAI ARIA toolbar pattern](https://www.w3.org/TR/wai-aria-practices/#toolbar).
+ToolbarButton can be used to add actions to a toolbar, usually inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md).
+
+It has similar features to the [Button](/packages/components/src/button/README.md) component. Using `ToolbarButton` will ensure the correct styling for a button in a toolbar, and also that keyboard interactions in a toolbar are consistent with the [WAI-ARIA toolbar pattern](https://www.w3.org/TR/wai-aria-practices/#toolbar).
 
 ## Usage
 
+To create general interfaces, you'll want to render ToolbarButton in a [Toolbar](/packages/components/src/toolbar/README.md) component.
+
 ```jsx
-import { ToolbarButton } from "@wordpress/components";
-import { edit } from "@wordpress/icons";
-
-const MyToolbarButton = () => (
-    <MyToolbarButton
-        title="Edit"
-        icon={ edit }
-        onClick={ onEdit } />
-);
+import { Toolbar, ToolbarButton } from '@wordpress/components';
+import { edit } from '@wordpress/icons';
+
+function MyToolbar() {
+	return (
+		<Toolbar label="Options">
+			<ToolbarButton
+				icon={ edit }
+				label="Edit"
+				onClick={ () => alert( 'Editing' ) }
+			/>
+		</Toolbar>
+	);
+}
+```
+
+### Inside BlockControls
+
+If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md) instead. Optinally wrapping it with [ToolbarGroup](/packages/components/src/toolbar-group/README.md).
+
+```jsx
+import { BlockControls } from '@wordpress/block-editor';
+import { ToolbarGroup, ToolbarButton } from '@wordpress/components';
+import { edit } from '@wordpress/icons';
+
+function Edit() {
+	return (
+		<BlockControls>
+			<ToolbarGroup>
+				<ToolbarButton
+					icon={ edit }
+					label="Edit"
+					onClick={ () => alert( 'Editing' ) }
+				/>
+			</ToolbarGroup>
+		</BlockControls>
+	);
+}
 ```
 
 ## Props

packages/components/src/toolbar-button/index.js

@@ -30,8 +30,6 @@ function ToolbarButton(
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	if ( ! accessibleToolbarState ) {
-		// This should be deprecated when <Toolbar __experimentalAccessibilityLabel="label">
-		// becomes stable.
 		return (
 			<ToolbarButtonContainer className={ containerClassName }>
 				<Button
@@ -52,7 +50,7 @@ function ToolbarButton(
 					) }
 					isPressed={ isActive }
 					disabled={ isDisabled }
-					data-experimental-toolbar-item
+					data-toolbar-item
 					{ ...extraProps }
 					{ ...props }
 				>

packages/components/src/toolbar-button/stories/index.js

@@ -16,7 +16,7 @@ export const _default = () => {
 	const icon = text( 'Icon', 'wordpress' );
 
 	return (
-		<Toolbar __experimentalAccessibilityLabel="Example Toolbar">
+		<Toolbar label="Example Toolbar">
 			<ToolbarButton icon={ icon } label={ label } />
 		</Toolbar>
 	);

packages/components/src/toolbar-group/README.md

@@ -0,0 +1,33 @@
+# ToolbarGroup
+
+A ToolbarGroup can be used to create subgroups of controls inside a [Toolbar](/packages/components/src/toolbar/README.md).
+
+## Usage
+
+```jsx
+import { Toolbar, ToolbarGroup, ToolbarButton } from '@wordpress/components';
+import { paragraph, formatBold, formatItalic, link } from '@wordpress/icons';
+
+function MyToolbar() {
+	return (
+		<Toolbar label="Options">
+			<ToolbarGroup>
+				<ToolbarButton icon={ paragraph } label="Paragraph" />
+			</ToolbarGroup>
+			<ToolbarGroup>
+				<ToolbarButton icon={ formatBold } label="Bold" />
+				<ToolbarButton icon={ formatItalic } label="Italic" />
+				<ToolbarButton icon={ link } label="Link" />
+			</ToolbarGroup>
+		</Toolbar>
+	);
+}
+```
+
+### Props
+
+ToolbarGroup will pass all HTML props to the underlying element.
+
+## Related components
+
+* ToolbarGroup may contain [ToolbarButton](/packages/components/src/toolbar-button/README.md) and [ToolbarItem](/packages/components/src/toolbar-Item/README.md) as children.

packages/components/src/toolbar-group/index.js

@@ -56,7 +56,7 @@ function ToolbarGroup( {
 	...props
 } ) {
 	// It'll contain state if `ToolbarGroup` is being used within
-	// `<Toolbar accessibilityLabel="label" />`
+	// `<Toolbar label="label" />`
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	if ( ( ! controls || ! controls.length ) && ! children ) {

packages/components/src/toolbar-group/toolbar-group-collapsed.js

@@ -12,15 +12,15 @@ import ToolbarItem from '../toolbar-item';
 
 function ToolbarGroupCollapsed( { controls = [], ...props } ) {
 	// It'll contain state if `ToolbarGroup` is being used within
-	// `<Toolbar __experimentalAccessibilityLabel="label" />`
+	// `<Toolbar label="label" />`
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	const renderDropdownMenu = ( toggleProps ) => (
 		<DropdownMenu
 			controls={ controls }
 			toggleProps={ {
 				...toggleProps,
-				'data-experimental-toolbar-item': true,
+				'data-toolbar-item': true,
 			} }
 			{ ...props }
 		/>

packages/components/src/toolbar-item/README.md

@@ -0,0 +1,73 @@
+# ToolbarItem
+
+A ToolbarItem is a generic headless component that can be used to make any custom component a [Toolbar](/packages/components/src/toolbar/README.md) item. It should be inside a [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md) when used to create general interfaces. If you're using it to add controls to your custom block, you should consider using [BlockControls](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md).
+
+## Usage
+
+### `as` prop
+
+You can use the `as` prop with a custom component or any HTML element.
+
+```jsx
+import { Toolbar, ToolbarItem, Button } from '@wordpress/components';
+
+function MyToolbar() {
+	return (
+		<Toolbar label="Options">
+			<ToolbarItem as={ Button }>I am a toolbar button</ToolbarItem>
+			<ToolbarItem as="button">I am another toolbar button</ToolbarItem>
+		</Toolbar>
+	);
+}
+```
+
+### render prop
+
+You can pass children as function to get the ToolbarItem props and pass them to another component.
+
+```jsx
+import { Toolbar, ToolbarItem, DropdownMenu } from '@wordpress/components';
+import { table } from '@wordpress/icons';
+
+function MyToolbar() {
+	return (
+		<Toolbar label="Options">
+			<ToolbarItem>
+				{ ( toolbarItemHTMLProps ) => (
+					<DropdownMenu
+						icon={ table }
+						toggleProps={ toolbarItemHTMLProps }
+						label={ 'Edit table' }
+						controls={ [] }
+					/>
+				) }
+			</ToolbarItem>
+		</Toolbar>
+	);
+}
+```
+
+### Inside BlockControls
+
+If you're working on a custom block and you want to add controls to the block toolbar, you should use [BlockControls](/docs/designers-developers/developers/tutorials/block-tutorial/block-controls-toolbar-and-sidebar.md) instead. Optinally wrapping it with [ToolbarGroup](/packages/components/src/toolbar-group/README.md).
+
+```jsx
+import { BlockControls } from '@wordpress/block-editor';
+import { Toolbar, ToolbarGroup, ToolbarItem, Button } from '@wordpress/components';
+import { edit } from '@wordpress/icons';
+
+function Edit() {
+	return (
+		<BlockControls>
+			<ToolbarGroup>
+				<ToolbarItem as={ Button }>I am a toolbar button</ToolbarItem>
+			</ToolbarGroup>
+		</BlockControls>
+	);
+}
+```
+
+## Related components
+
+* ToolbarItem should be used inside [Toolbar](/packages/components/src/toolbar/README.md) or [ToolbarGroup](/packages/components/src/toolbar-group/README.md).
+* If you want a simple toolbar button, consider using [ToolbarButton](/packages/components/src/toolbar-button/README.md) instead.