@wordpress/components 28.2.0 → 28.4.0

package/build-types/v-stack/hook.d.ts

@@ -1,5 +1,3 @@
-/// <reference types="react" />
-/// <reference types="react" />
 /**
  * Internal dependencies
  */
@@ -21,27 +19,27 @@ export declare function useVStack(props: WordPressComponentProps<VStackProps, 'd
     tabIndex?: number | undefined;
     "aria-activedescendant"?: string | undefined;
     "aria-atomic"?: (boolean | "false" | "true") | undefined;
-    "aria-autocomplete"?: "both" | "none" | "inline" | "list" | undefined;
+    "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined;
     "aria-braillelabel"?: string | undefined;
     "aria-brailleroledescription"?: string | undefined;
     "aria-busy"?: (boolean | "false" | "true") | undefined;
-    "aria-checked"?: boolean | "mixed" | "false" | "true" | undefined;
+    "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined;
     "aria-colcount"?: number | undefined;
     "aria-colindex"?: number | undefined;
     "aria-colindextext"?: string | undefined;
     "aria-colspan"?: number | undefined;
     "aria-controls"?: string | undefined;
-    "aria-current"?: boolean | "page" | "false" | "true" | "time" | "step" | "location" | "date" | undefined;
+    "aria-current"?: boolean | "false" | "true" | "page" | "step" | "location" | "date" | "time" | undefined;
     "aria-describedby"?: string | undefined;
     "aria-description"?: string | undefined;
     "aria-details"?: string | undefined;
     "aria-disabled"?: (boolean | "false" | "true") | undefined;
-    "aria-dropeffect"?: "none" | "copy" | "move" | "link" | "execute" | "popup" | undefined;
+    "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined;
     "aria-errormessage"?: string | undefined;
     "aria-expanded"?: (boolean | "false" | "true") | undefined;
     "aria-flowto"?: string | undefined;
     "aria-grabbed"?: (boolean | "false" | "true") | undefined;
-    "aria-haspopup"?: boolean | "listbox" | "grid" | "menu" | "false" | "true" | "dialog" | "tree" | undefined;
+    "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined;
     "aria-hidden"?: (boolean | "false" | "true") | undefined;
     "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined;
     "aria-keyshortcuts"?: string | undefined;
@@ -56,9 +54,9 @@ export declare function useVStack(props: WordPressComponentProps<VStackProps, 'd
     "aria-owns"?: string | undefined;
     "aria-placeholder"?: string | undefined;
     "aria-posinset"?: number | undefined;
-    "aria-pressed"?: boolean | "mixed" | "false" | "true" | undefined;
+    "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined;
     "aria-readonly"?: (boolean | "false" | "true") | undefined;
-    "aria-relevant"?: "all" | "text" | "additions" | "additions removals" | "additions text" | "removals" | "removals additions" | "removals text" | "text additions" | "text removals" | undefined;
+    "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined;
     "aria-required"?: (boolean | "false" | "true") | undefined;
     "aria-roledescription"?: string | undefined;
     "aria-rowcount"?: number | undefined;
@@ -242,7 +240,7 @@ export declare function useVStack(props: WordPressComponentProps<VStackProps, 'd
     suppressContentEditableWarning?: boolean | undefined;
     accessKey?: string | undefined;
     autoFocus?: boolean | undefined;
-    contentEditable?: "inherit" | (boolean | "false" | "true") | "plaintext-only" | undefined;
+    contentEditable?: (boolean | "false" | "true") | "inherit" | "plaintext-only" | undefined;
     contextMenu?: string | undefined;
     dir?: string | undefined;
     draggable?: (boolean | "false" | "true") | undefined;
@@ -270,7 +268,7 @@ export declare function useVStack(props: WordPressComponentProps<VStackProps, 'd
     results?: number | undefined;
     security?: string | undefined;
     unselectable?: "on" | "off" | undefined;
-    inputMode?: "none" | "text" | "numeric" | "search" | "tel" | "url" | "email" | "decimal" | undefined;
+    inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
     is?: string | undefined;
     as?: keyof JSX.IntrinsicElements | undefined;
 };

package/build-types/v-stack/hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/v-stack/hook.ts"],"names":[],"mappings":";;AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,wBAAgB,SAAS,CACxB,KAAK,EAAE,uBAAuB,CAAE,WAAW,EAAE,KAAK,CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBpD"}
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/v-stack/hook.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,wBAAgB,SAAS,CACxB,KAAK,EAAE,uBAAuB,CAAE,WAAW,EAAE,KAAK,CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBpD"}

package/build-types/v-stack/stories/index.story.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="react" />
 /**
  * External dependencies
  */
@@ -7,8 +6,8 @@ import { VStack } from '..';
 declare const meta: Meta<typeof VStack>;
 export default meta;
 export declare const Default: import("@storybook/types").AnnotatedStoryFn<import("@storybook/react").ReactRenderer, Omit<import("../../h-stack/types").Props, "spacing" | "alignment"> & {
-    alignment?: (string & {}) | "-moz-initial" | "inherit" | "initial" | "revert" | "revert-layer" | "unset" | "stretch" | "center" | "end" | "flex-end" | "flex-start" | "start" | "baseline" | "normal" | "self-end" | "self-start" | "left" | "right" | "bottom" | "top" | "edge" | "bottomLeft" | "bottomRight" | "topLeft" | "topRight" | undefined;
-    spacing?: import("csstype").Property.Width<string | number> | undefined;
+    alignment?: import("../../h-stack/types").HStackAlignment | import("react").CSSProperties["alignItems"];
+    spacing?: import("react").CSSProperties["width"];
 } & import("react").RefAttributes<any> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "wrap" | "expanded" | "justify" | "direction" | "spacing" | "children" | "as" | "alignment" | keyof import("react").RefAttributes<any> | "isReversed"> & {
     as?: keyof JSX.IntrinsicElements | undefined;
 }>;

package/build-types/v-stack/stories/index.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/v-stack/stories/index.story.tsx"],"names":[],"mappings":";AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,kBAAkB,CAAC;AAMtD,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAgB5B,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,MAAM,CAkB9B,CAAC;AACF,eAAe,IAAI,CAAC;AAiBpB,eAAO,MAAM,OAAO;;;;;EAAsB,CAAC"}
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/v-stack/stories/index.story.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,kBAAkB,CAAC;AAMtD,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAgB5B,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,MAAM,CAkB9B,CAAC;AACF,eAAe,IAAI,CAAC;AAiBpB,eAAO,MAAM,OAAO;;;;;EAAsB,CAAC"}

package/build-types/view/component.d.ts

@@ -1,5 +1,3 @@
-/// <reference types="react" />
-/// <reference types="react" />
 /**
  * `View` is a core component that renders everything in the library.
  * It is the principle component in the entire library.

package/build-types/view/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/view/component.tsx"],"names":[],"mappings":";;AAwBA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAEd,CAAC;AAEJ,eAAe,IAAI,CAAC"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/view/component.tsx"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAEd,CAAC;AAEJ,eAAe,IAAI,CAAC"}

package/build-types/visually-hidden/component.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="react" />
 import type { VisuallyHiddenProps } from './types';
 /**
  * `VisuallyHidden` is a component used to render text intended to be visually

package/build-types/visually-hidden/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/component.tsx"],"names":[],"mappings":";AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAmBnD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,gHAG1B,CAAC;AAEF,eAAe,cAAc,CAAC"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/component.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAmBnD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,gHAG1B,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/build-types/z-stack/component.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="react" />
 import type { ZStackProps } from './types';
 /**
  * `ZStack` allows you to stack things along the Z-axis.

package/build-types/z-stack/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/z-stack/component.tsx"],"names":[],"mappings":";AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAkD3C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,wGAAgD,CAAC;AAEpE,eAAe,MAAM,CAAC"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/z-stack/component.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAkD3C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,wGAAgD,CAAC;AAEpE,eAAe,MAAM,CAAC"}

package/build-types/z-stack/styles.d.ts

@@ -1,14 +1,13 @@
-/// <reference types="react" />
 export declare const ZStackChildView: import("@emotion/styled").StyledComponent<{
-    theme?: import("@emotion/react").Theme | undefined;
-    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
 } & {
     offsetAmount: number;
     zIndex: number;
 }, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const ZStackView: import("@emotion/styled").StyledComponent<{
-    theme?: import("@emotion/react").Theme | undefined;
-    as?: import("react").ElementType<any, keyof import("react").JSX.IntrinsicElements> | undefined;
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
 } & {
     isLayered: boolean;
 }, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/build-types/z-stack/styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../src/z-stack/styles.ts"],"names":[],"mappings":";AAMA,eAAO,MAAM,eAAe;;;;kBACb,MAAM;YACZ,MAAM;yGAUd,CAAC;AAEF,eAAO,MAAM,UAAU;;;;eACX,OAAO;yGAgBlB,CAAC"}
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../src/z-stack/styles.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,eAAe;;SAqBF,MACrB,WAAW;;kBArBD,MAAM;YACZ,MAAM;yGAUd,CAAC;AAEF,eAAO,MAAM,UAAU;;eAQlB,WAAW;;eAPJ,OAAO;yGAgBlB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "28.2.0",
+	"version": "28.4.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -43,29 +43,28 @@
 		"@types/gradient-parser": "0.1.3",
 		"@types/highlight-words-core": "1.2.1",
 		"@use-gesture/react": "^10.3.1",
-		"@wordpress/a11y": "^4.2.0",
-		"@wordpress/compose": "^7.2.0",
-		"@wordpress/date": "^5.2.0",
-		"@wordpress/deprecated": "^4.2.0",
-		"@wordpress/dom": "^4.2.0",
-		"@wordpress/element": "^6.2.0",
-		"@wordpress/escape-html": "^3.2.0",
-		"@wordpress/hooks": "^4.2.0",
-		"@wordpress/html-entities": "^4.2.0",
-		"@wordpress/i18n": "^5.2.0",
-		"@wordpress/icons": "^10.2.0",
-		"@wordpress/is-shallow-equal": "^5.2.0",
-		"@wordpress/keycodes": "^4.2.0",
-		"@wordpress/primitives": "^4.2.0",
-		"@wordpress/private-apis": "^1.2.0",
-		"@wordpress/rich-text": "^7.2.0",
-		"@wordpress/warning": "^3.2.0",
+		"@wordpress/a11y": "^4.4.0",
+		"@wordpress/compose": "^7.4.0",
+		"@wordpress/date": "^5.4.0",
+		"@wordpress/deprecated": "^4.4.0",
+		"@wordpress/dom": "^4.4.0",
+		"@wordpress/element": "^6.4.0",
+		"@wordpress/escape-html": "^3.4.0",
+		"@wordpress/hooks": "^4.4.0",
+		"@wordpress/html-entities": "^4.4.0",
+		"@wordpress/i18n": "^5.4.0",
+		"@wordpress/icons": "^10.4.0",
+		"@wordpress/is-shallow-equal": "^5.4.0",
+		"@wordpress/keycodes": "^4.4.0",
+		"@wordpress/primitives": "^4.4.0",
+		"@wordpress/private-apis": "^1.4.0",
+		"@wordpress/rich-text": "^7.4.0",
+		"@wordpress/warning": "^3.4.0",
 		"change-case": "^4.1.2",
 		"clsx": "^2.1.1",
 		"colord": "^2.7.0",
 		"date-fns": "^3.6.0",
 		"deepmerge": "^4.3.0",
-		"downshift": "^6.0.15",
 		"fast-deep-equal": "^3.1.3",
 		"framer-motion": "^11.1.9",
 		"gradient-parser": "^0.1.5",
@@ -86,5 +85,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "aa5b14bb5bdbb8d8a02914e154c3bc1c2f18ace6"
+	"gitHead": "363edb39b8dda8727f652e42cbb8497732693ed2"
 }

package/src/animation/index.tsx

@@ -6,7 +6,6 @@
  * @see https://www.framer.com/docs/animation/
  */
 
-// eslint-disable-next-line no-restricted-imports
 export {
 	motion as __unstableMotion,
 	AnimatePresence as __unstableAnimatePresence,

package/src/autocomplete/README.md

@@ -8,7 +8,7 @@ The following props are used to control the behavior of the component.
 
 ### record
 
-The rich text value object the autocomleter is being applied to.
+The rich text value object the autocompleter is being applied to.
 
 -   Required: Yes
 -   Type: `RichTextValue`
@@ -50,7 +50,7 @@ A function that returns nodes to be rendered within the Autocomplete.
 
 ### isSelected
 
-Whether or not the Autocomplte componenet is selected, and if its `Popover` should be displayed.
+Whether or not the Autocomplete component is selected, and if its `Popover` should be displayed.
 
 - Required: Yes
 - Type: `Boolean`

package/src/autocomplete/autocompleter-ui.tsx

@@ -58,6 +58,7 @@ function ListBox( {
 					id={ `components-autocomplete-item-${ instanceId }-${ option.key }` }
 					role="option"
 					aria-selected={ index === selectedIndex }
+					accessibleWhenDisabled
 					disabled={ option.isDisabled }
 					className={ clsx(
 						'components-autocomplete__result',

package/src/autocomplete/index.tsx

@@ -13,7 +13,6 @@ import {
 	useRef,
 	useMemo,
 } from '@wordpress/element';
-import { __, _n } from '@wordpress/i18n';
 import { useInstanceId, useMergeRefs, useRefEffect } from '@wordpress/compose';
 import {
 	create,

package/src/autocomplete/types.ts

@@ -200,9 +200,8 @@ export type AutocompleteProps = UseAutocompleteProps & {
 		props: Omit< ReturnType< typeof useAutocomplete >, 'popover' >
 	) => React.ReactNode;
 	/**
-	 * Whether or not the Autocomplte componenet is selected, and if its
-	 * `Popover`
-	 * should be displayed.
+	 * Whether or not the Autocomplete component is selected, and if its
+	 * `Popover` should be displayed.
 	 */
 	isSelected: boolean;
 };

package/src/base-control/README.md

@@ -53,7 +53,7 @@ If true, the label will only be visible to screen readers.
 
 ### help
 
-Additional description for the control. The element containing the description will be programmatically associated to the BaseControl by the means of an `aria-describedby` attribute.
+Additional description for the control. Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an `aria-describedby` attribute.
 
 -   Type: `ReactNode`
 -   Required: No

package/src/base-control/index.tsx

@@ -2,6 +2,12 @@
  * External dependencies
  */
 import clsx from 'clsx';
+import type { ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -116,14 +122,16 @@ const UnconnectedBaseControl = (
  * 	</BaseControl>
  * );
  */
-export const VisualLabel = ( {
-	className,
-	children,
-	...props
-}: WordPressComponentProps< BaseControlVisualLabelProps, 'span' > ) => {
+const UnforwardedVisualLabel = (
+	props: WordPressComponentProps< BaseControlVisualLabelProps, 'span' >,
+	ref: ForwardedRef< any >
+) => {
+	const { className, children, ...restProps } = props;
+
 	return (
 		<StyledVisualLabel
-			{ ...props }
+			ref={ ref }
+			{ ...restProps }
 			className={ clsx( 'components-base-control__label', className ) }
 		>
 			{ children }
@@ -131,6 +139,8 @@ export const VisualLabel = ( {
 	);
 };
 
+export const VisualLabel = forwardRef( UnforwardedVisualLabel );
+
 export const BaseControl = Object.assign(
 	contextConnectWithoutRef( UnconnectedBaseControl, 'BaseControl' ),
 	{ VisualLabel }

package/src/base-control/stories/index.story.tsx

@@ -55,7 +55,6 @@ WithHelpText.args = {
  * otherwise use if the `label` prop was passed.
  */
 export const WithVisualLabel: StoryFn< typeof BaseControl > = ( props ) => {
-	// @ts-expect-error - Unclear how to fix, see also https://github.com/WordPress/gutenberg/pull/39468#discussion_r827150516
 	BaseControl.VisualLabel.displayName = 'BaseControl.VisualLabel';
 
 	return (

package/src/base-control/types.ts

@@ -21,7 +21,7 @@ export type BaseControlProps = {
 	/**
 	 * Additional description for the control.
 	 *
-	 * The element containing the description will be programmatically associated to the BaseControl by the means of an `aria-describedby` attribute.
+	 * Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an `aria-describedby` attribute.
 	 */
 	help?: ReactNode;
 	/**

package/src/border-box-control/border-box-control-visualizer/component.tsx

@@ -1,8 +1,3 @@
-/**
- * WordPress dependencies
- */
-import { __ } from '@wordpress/i18n';
-
 /**
  * Internal dependencies
  */

package/src/button/README.md

@@ -115,6 +115,17 @@ The presence of a `href` prop determines whether an `anchor` element is rendered
 
 Props not included in this set will be applied to the `a` or `button` element.
 
+#### `accessibleWhenDisabled`: `boolean`
+
+Whether to keep the button focusable when disabled.
+
+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.
+
+-   Required: No
+-   Default: `false`
+
 #### `children`: `ReactNode`
 
 The button's children.
@@ -127,7 +138,7 @@ An optional additional class name to apply to the rendered button.
 
 -   Required: No
 
-#### `describedBy`: `string`
+#### `description`: `string`
 
 An accessible description for the button.
 
@@ -137,6 +148,8 @@ An accessible description for the button.
 
 Whether the button is disabled. If `true`, this will force a `button` element to be rendered, even when an `href` is given.
 
+In most cases, it is recommended to also set the `accessibleWhenDisabled` prop to `true`.
+
 -   Required: No
 
 #### `href`: `string`

package/src/button/index.tsx

@@ -29,6 +29,7 @@ import { positionToPlacement } from '../popover/utils';
 const disabledEventsOnDisabledButton = [ 'onMouseDown', 'onClick' ] as const;
 
 function useDeprecatedProps( {
+	__experimentalIsFocusable,
 	isDefault,
 	isPrimary,
 	isSecondary,
@@ -38,14 +39,17 @@ function useDeprecatedProps( {
 	isSmall,
 	size,
 	variant,
+	describedBy,
 	...otherProps
 }: ButtonProps & DeprecatedButtonProps ): ButtonProps {
 	let computedSize = size;
 	let computedVariant = variant;
 
-	const newProps: { 'aria-pressed'?: boolean } = {
+	const newProps = {
+		accessibleWhenDisabled: __experimentalIsFocusable,
 		// @todo Mark `isPressed` as deprecated
 		'aria-pressed': isPressed,
+		description: describedBy,
 	};
 
 	if ( isSmall ) {
@@ -91,6 +95,7 @@ export function UnforwardedButton(
 ) {
 	const {
 		__next40pxDefaultSize,
+		accessibleWhenDisabled,
 		isBusy,
 		isDestructive,
 		className,
@@ -106,8 +111,7 @@ export function UnforwardedButton(
 		size = 'default',
 		text,
 		variant,
-		__experimentalIsFocusable: isFocusable,
-		describedBy,
+		description,
 		...buttonOrAnchorProps
 	} = useDeprecatedProps( props );
 
@@ -159,8 +163,8 @@ export function UnforwardedButton(
 		'has-icon': !! icon,
 	} );
 
-	const trulyDisabled = disabled && ! isFocusable;
-	const Tag = href !== undefined && ! trulyDisabled ? 'a' : 'button';
+	const trulyDisabled = disabled && ! accessibleWhenDisabled;
+	const Tag = href !== undefined && ! disabled ? 'a' : 'button';
 	const buttonProps: ComponentPropsWithoutRef< 'button' > =
 		Tag === 'button'
 			? {
@@ -177,7 +181,7 @@ export function UnforwardedButton(
 	const disableEventProps: {
 		[ key: string ]: ( event: MouseEvent ) => void;
 	} = {};
-	if ( disabled && isFocusable ) {
+	if ( disabled && accessibleWhenDisabled ) {
 		// In this case, the button will be disabled, but still focusable and
 		// perceivable by screen reader users.
 		buttonProps[ 'aria-disabled' ] = true;
@@ -206,7 +210,7 @@ export function UnforwardedButton(
 				// The tooltip is not explicitly disabled.
 				false !== showTooltip ) );
 
-	const descriptionId = describedBy ? instanceId : undefined;
+	const descriptionId = description ? instanceId : undefined;
 
 	const describedById =
 		additionalProps[ 'aria-describedby' ] || descriptionId;
@@ -260,8 +264,8 @@ export function UnforwardedButton(
 		? {
 				text:
 					( children as string | ReactElement[] )?.length &&
-					describedBy
-						? describedBy
+					description
+						? description
 						: label,
 				shortcut,
 				placement:
@@ -274,9 +278,9 @@ export function UnforwardedButton(
 	return (
 		<>
 			<Tooltip { ...tooltipProps }>{ element }</Tooltip>
-			{ describedBy && (
+			{ description && (
 				<VisuallyHidden>
-					<span id={ descriptionId }>{ describedBy }</span>
+					<span id={ descriptionId }>{ description }</span>
 				</VisuallyHidden>
 			) }
 		</>

package/src/button/stories/e2e/index.story.tsx

@@ -39,12 +39,13 @@ export const VariantStates: StoryFn< typeof Button > = (
 					key={ variant ?? 'undefined' }
 				>
 					<Button { ...props } variant={ variant } />
+					{ /* eslint-disable-next-line no-restricted-syntax */ }
 					<Button { ...props } variant={ variant } disabled />
 					<Button
 						{ ...props }
 						variant={ variant }
 						disabled
-						__experimentalIsFocusable
+						accessibleWhenDisabled
 					/>
 					<Button { ...props } variant={ variant } isBusy />
 					<Button { ...props } variant={ variant } isDestructive />

package/src/button/test/index.tsx

@@ -235,13 +235,14 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should add a disabled prop to the button', () => {
+			// eslint-disable-next-line no-restricted-syntax
 			render( <Button disabled /> );
 
 			expect( screen.getByRole( 'button' ) ).toBeDisabled();
 		} );
 
 		it( 'should add only aria-disabled attribute when disabled and isFocusable are true', () => {
-			render( <Button disabled __experimentalIsFocusable /> );
+			render( <Button disabled accessibleWhenDisabled /> );
 			const button = screen.getByRole( 'button' );
 
 			expect( button ).toBeEnabled();
@@ -328,7 +329,7 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should support adding aria-describedby text', () => {
-			render( <Button describedBy="Description text" /> );
+			render( <Button description="Description text" /> );
 			expect(
 				screen.getByRole( 'button', {
 					description: 'Description text',
@@ -341,7 +342,7 @@ describe( 'Button', () => {
 
 			render(
 				<Button
-					describedBy="Description text"
+					description="Description text"
 					label="Label"
 					icon={ plusCircle }
 				/>
@@ -363,7 +364,7 @@ describe( 'Button', () => {
 			render(
 				<Button
 					label="Label"
-					describedBy="Description text"
+					description="Description text"
 					icon={ plusCircle }
 					showTooltip
 				>
@@ -536,10 +537,24 @@ describe( 'Button', () => {
 
 		it( 'should become a button again when disabled is supplied', () => {
 			// @ts-expect-error - a button should not have `href`
+			// eslint-disable-next-line no-restricted-syntax
 			render( <Button href="https://wordpress.org/" disabled /> );
 
 			expect( screen.getByRole( 'button' ) ).toBeVisible();
 		} );
+
+		it( 'should become a button again when disabled is supplied, even with `accessibleWhenDisabled`', () => {
+			render(
+				<Button
+					// @ts-expect-error - a button should not have `href`
+					// eslint-disable-next-line no-restricted-syntax
+					href="https://wordpress.org/"
+					disabled
+					accessibleWhenDisabled
+				/>
+			);
+			expect( screen.getByRole( 'button' ) ).toBeVisible();
+		} );
 	} );
 
 	describe( 'ref forwarding', () => {
@@ -617,6 +632,15 @@ describe( 'Button', () => {
 				'mixed'
 			);
 		} );
+
+		it( 'should not break when the legacy __experimentalIsFocusable prop is passed', () => {
+			// eslint-disable-next-line no-restricted-syntax
+			render( <Button disabled __experimentalIsFocusable /> );
+			const button = screen.getByRole( 'button' );
+
+			expect( button ).toBeEnabled();
+			expect( button ).toHaveAttribute( 'aria-disabled' );
+		} );
 	} );
 
 	describe( 'static typing', () => {
@@ -624,15 +648,19 @@ describe( 'Button', () => {
 			<Button href="foo" />
 			{ /* @ts-expect-error - `target` requires `href` */ }
 			<Button target="foo" />
+
+			{ /* eslint-disable no-restricted-syntax */ }
 			{ /* @ts-expect-error - `disabled` is only for buttons */ }
 			<Button href="foo" disabled />
+			{ /* eslint-enable no-restricted-syntax */ }
+
 			<Button href="foo" type="image/png" />
 			{ /* @ts-expect-error - if button, type must be submit/reset/button */ }
 			<Button type="image/png" />
 			{ /* @ts-expect-error */ }
 			<Button type="invalidtype" />
-			{ /* @ts-expect-error - although the runtime behavior will allow this to be an anchor, this is probably a mistake. */ }
-			<Button disabled __experimentalIsFocusable href="foo" />
+			{ /* @ts-expect-error */ }
+			<Button disabled accessibleWhenDisabled href="foo" />
 		</>;
 	} );
 } );