Deprecating isPressed in Button component

packages/components/CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Enhancements
 
 -   `SearchControl`: polish metrics for `compact` size variant ([#54663](https://github.com/WordPress/gutenberg/pull/54663)).
+-   `Button`: deprecating `isPressed` prop in favour of `aria-pressed` ([#54740](https://github.com/WordPress/gutenberg/pull/54740)).
 
 ### Bug Fix
 

packages/components/src/button/README.md

@@ -186,6 +186,8 @@ Renders a red text-based button style to indicate destructive behavior.
 
 Renders a pressed button style.
 
+If the native `aria-pressed` attribute is also set, it will take precedence.
+
 -   Required: No
 
 #### `isSmall`: `boolean`

packages/components/src/button/index.tsx

@@ -34,6 +34,7 @@ function useDeprecatedProps( {
 	isSecondary,
 	isTertiary,
 	isLink,
+	isPressed,
 	isSmall,
 	size,
 	variant,
@@ -42,6 +43,11 @@ function useDeprecatedProps( {
 	let computedSize = size;
 	let computedVariant = variant;
 
+	const newProps: { 'aria-pressed'?: boolean } = {
+		// @TODO Mark `isPressed` as deprecated
+		'aria-pressed': isPressed,
+	};
+
 	if ( isSmall ) {
 		computedSize ??= 'small';
 	}
@@ -73,6 +79,7 @@ function useDeprecatedProps( {
 	}
 
 	return {
+		...newProps,
 		...otherProps,
 		size: computedSize,
 		variant: computedVariant,
@@ -85,7 +92,6 @@ export function UnforwardedButton(
 ) {
 	const {
 		__next40pxDefaultSize,
-		isPressed,
 		isBusy,
 		isDestructive,
 		className,
@@ -106,10 +112,16 @@ export function UnforwardedButton(
 		...buttonOrAnchorProps
 	} = useDeprecatedProps( props );
 
-	const { href, target, ...additionalProps } =
-		'href' in buttonOrAnchorProps
-			? buttonOrAnchorProps
-			: { href: undefined, target: undefined, ...buttonOrAnchorProps };
+	const {
+		href,
+		target,
+		'aria-checked': ariaChecked,
+		'aria-pressed': ariaPressed,
+		'aria-selected': ariaSelected,
+		...additionalProps
+	} = 'href' in buttonOrAnchorProps
+		? buttonOrAnchorProps
+		: { href: undefined, target: undefined, ...buttonOrAnchorProps };
 
 	const instanceId = useInstanceId(
 		Button,
@@ -124,14 +136,23 @@ export function UnforwardedButton(
 			// Tooltip should not considered as a child
 			children?.[ 0 ]?.props?.className !== 'components-tooltip' );
 
+	const truthyAriaPressedValues: ( typeof ariaPressed )[] = [
+		true,
+		'true',
+		'mixed',
+	];
+
 	const classes = classnames( 'components-button', className, {
 		'is-next-40px-default-size': __next40pxDefaultSize,
 		'is-secondary': variant === 'secondary',
 		'is-primary': variant === 'primary',
 		'is-small': size === 'small',
 		'is-compact': size === 'compact',
 		'is-tertiary': variant === 'tertiary',
-		'is-pressed': isPressed,
+
+		'is-pressed': truthyAriaPressedValues.includes( ariaPressed ),
+		'is-pressed-mixed': ariaPressed === 'mixed',
+
 		'is-busy': isBusy,
 		'is-link': variant === 'link',
 		'is-destructive': isDestructive,
@@ -146,7 +167,9 @@ export function UnforwardedButton(
 			? {
 					type: 'button',
 					disabled: trulyDisabled,
-					'aria-pressed': isPressed,
+					'aria-checked': ariaChecked,
+					'aria-pressed': ariaPressed,
+					'aria-selected': ariaSelected,
 			  }
 			: {};
 	const anchorProps: ComponentPropsWithoutRef< 'a' > =

packages/components/src/button/stories/index.story.tsx

@@ -26,6 +26,17 @@ const meta: Meta< typeof Button > = {
 	component: Button,
 	argTypes: {
 		// Overrides a limitation of the docgen interpreting our TS types for this as required.
+		'aria-pressed': {
+			control: { type: 'select' },
+			description:
+				'Indicates the current "pressed" state, implying it is a toggle button. Implicitly set by `isPressed`, but takes precedence if both are provided.',
+			options: [ undefined, 'true', 'false', 'mixed' ],
+			table: {
+				type: {
+					summary: 'boolean | "true" | "false" | "mixed"',
+				},
+			},
+		},
 		href: { type: { name: 'string', required: false } },
 		icon: {
 			control: { type: 'select' },

packages/components/src/button/style.scss

@@ -308,7 +308,8 @@
 	}
 
 	// Toggled style.
-	&.is-pressed {
+	&[aria-pressed="true"],
+	&[aria-pressed="mixed"] {
 		color: $components-color-foreground-inverted;
 		background: $components-color-foreground;
 

packages/components/src/button/test/index.tsx

@@ -72,12 +72,6 @@ describe( 'Button', () => {
 			expect( button ).toHaveClass( 'is-link' );
 		} );
 
-		it( 'should render a button element with is-pressed without button class', () => {
-			render( <Button isPressed /> );
-
-			expect( screen.getByRole( 'button' ) ).toHaveClass( 'is-pressed' );
-		} );
-
 		it( 'should render a button element with has-text when children are passed', async () => {
 			const user = userEvent.setup();
 
@@ -347,6 +341,56 @@ describe( 'Button', () => {
 
 			await cleanupTooltip( user );
 		} );
+
+		describe( 'using `aria-pressed` prop', () => {
+			it( 'should render a button element with is-pressed when `true`', () => {
+				render( <Button aria-pressed /> );
+
+				expect( screen.getByRole( 'button' ) ).toHaveClass(
+					'is-pressed'
+				);
+			} );
+
+			it( 'should render a button element with is-pressed when `"true"`', () => {
+				render( <Button aria-pressed="true" /> );
+
+				expect( screen.getByRole( 'button' ) ).toHaveClass(
+					'is-pressed'
+				);
+			} );
+
+			it( 'should render a button element with is-pressed/is-pressed-mixed when `"mixed"`', () => {
+				render( <Button aria-pressed="mixed" /> );
+
+				expect( screen.getByRole( 'button' ) ).toHaveClass(
+					'is-pressed is-pressed-mixed'
+				);
+			} );
+
+			it( 'should render a button element without is-pressed when `undefined`', () => {
+				render( <Button aria-pressed={ undefined } /> );
+
+				expect( screen.getByRole( 'button' ) ).not.toHaveClass(
+					'is-pressed'
+				);
+			} );
+
+			it( 'should render a button element without is-pressed when `false`', () => {
+				render( <Button aria-pressed={ false } /> );
+
+				expect( screen.getByRole( 'button' ) ).not.toHaveClass(
+					'is-pressed'
+				);
+			} );
+
+			it( 'should render a button element without is-pressed when `"false"`', () => {
+				render( <Button aria-pressed="false" /> );
+
+				expect( screen.getByRole( 'button' ) ).not.toHaveClass(
+					'is-pressed'
+				);
+			} );
+		} );
 	} );
 
 	describe( 'with href property', () => {
@@ -434,6 +478,23 @@ describe( 'Button', () => {
 			);
 			expect( screen.getByRole( 'button' ) ).toHaveClass( 'is-compact' );
 		} );
+
+		it( 'should not break when the legacy isPressed prop is passed', () => {
+			render( <Button isPressed /> );
+
+			expect( screen.getByRole( 'button' ) ).toHaveAttribute(
+				'aria-pressed',
+				'true'
+			);
+		} );
+
+		it( 'should prioritize the `aria-pressed` prop over `isPressed`', () => {
+			render( <Button isPressed aria-pressed="mixed" /> );
+			expect( screen.getByRole( 'button' ) ).toHaveAttribute(
+				'aria-pressed',
+				'mixed'
+			);
+		} );
 	} );
 
 	describe( 'static typing', () => {