ToolbarButton: Fix docs for accessibleWhenDisabled (WordPress#63140)

Co-authored-by: mirka <[email protected]> Co-authored-by: DaniGuardiola <[email protected]> Co-authored-by: tyxla <[email protected]>
carstingaxion · Jul 5, 2024 · 88f44fd · 88f44fd
1 parent 885dd36
commit 88f44fd
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 7 deletions.
diff --git a/packages/components/src/toolbar/toolbar-button/index.tsx b/packages/components/src/toolbar/toolbar-button/index.tsx
@@ -16,7 +16,7 @@ import Button from '../../button';
 import ToolbarItem from '../toolbar-item';
 import ToolbarContext from '../toolbar-context';
 import ToolbarButtonContainer from './toolbar-button-container';
-import type { ToolbarButtonDeprecatedProps, ToolbarButtonProps } from './types';
+import type { ToolbarButtonOverriddenProps, ToolbarButtonProps } from './types';
 import type { WordPressComponentProps } from '../../context';
 
 function useDeprecatedProps( {
@@ -32,9 +32,9 @@ function useDeprecatedProps( {
 function UnforwardedToolbarButton(
 	props: Omit<
 		WordPressComponentProps< ToolbarButtonProps, typeof Button, false >,
-		'__experimentalIsFocusable' // ToolbarButton will always be focusable even when disabled.
+		'accessibleWhenDisabled' // By default, ToolbarButton will be focusable when disabled.
 	> &
-		ToolbarButtonDeprecatedProps,
+		ToolbarButtonOverriddenProps,
 	ref: ForwardedRef< any >
 ) {
 	const {

diff --git a/packages/components/src/toolbar/toolbar-button/types.ts b/packages/components/src/toolbar/toolbar-button/types.ts
@@ -37,14 +37,20 @@ export type ToolbarButtonProps = {
 	title?: string;
 };
 
-export type ToolbarButtonDeprecatedProps = {
+export type ToolbarButtonOverriddenProps = {
 	/**
 	 * Whether to keep the button focusable when disabled.
 	 *
-	 * @deprecated ToolbarButton will always be focusable even when disabled.
-	 * @ignore
+	 * In most cases, it is recommended to set this to `true`. Disabling a control without maintaining focusability
+	 * can cause accessibility issues, by hiding their presence from screen reader users,
+	 * or by preventing focus from returning to a trigger element.
+	 *
+	 * Learn more about the [focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols)
+	 * in the WAI-ARIA Authoring Practices Guide.
+	 *
+	 * @default true
 	 */
-	__experimentalIsFocusable?: boolean;
+	accessibleWhenDisabled?: boolean;
 };
 
 export type ToolbarButtonContainerProps = {