@wordpress/components 28.3.0 → 28.5.0

package/src/button/style.scss

@@ -1,3 +1,10 @@
+/**
+ * For easier testing of potential regressions, you can use a Button variant matrix
+ * available in a special Storybook instance by running `npm run storybook:e2e:dev`.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/trunk/test/storybook-playwright/README.md
+ */
+
 .components-button {
 	display: inline-flex;
 	text-decoration: none;
@@ -23,16 +30,10 @@
 	}
 
 	&[aria-expanded="true"],
-	&:hover {
+	&:hover:not(:disabled, [aria-disabled="true"]) {
 		color: $components-color-accent;
 	}
 
-	// Unset some hovers, instead of adding :not specificity.
-	&:disabled:hover,
-	&[aria-disabled="true"]:hover {
-		color: initial;
-	}
-
 	// Focus.
 	// See https://github.com/WordPress/gutenberg/issues/13267 for more context on these selectors.
 	&:focus:not(:disabled) {
@@ -80,7 +81,6 @@
 			color: rgba($white, 0.4);
 			background: $components-color-accent;
 			border-color: $components-color-accent;
-			opacity: 1;
 			outline: none;
 
 			&:focus:enabled {
@@ -125,7 +125,6 @@
 			color: $gray-600;
 			background: transparent;
 			transform: none;
-			opacity: 1;
 		}
 	}
 
@@ -199,17 +198,32 @@
 		&:not(.is-primary):not(.is-secondary):not(.is-tertiary):not(.is-link) {
 			color: $alert-red;
 
-			&:hover:not(:disabled) {
+			&:hover:not(:disabled, [aria-disabled="true"]) {
 				color: darken($alert-red, 20%);
 			}
 
-			&:focus:not(:disabled) {
+			&:focus {
 				box-shadow: 0 0 0 var(--wp-admin-border-width-focus) $alert-red;
 			}
 
-			&:active:not(:disabled) {
+			&:active:not(:disabled, [aria-disabled="true"]) {
 				background: $gray-400;
 			}
+
+			&:disabled,
+			&[aria-disabled="true"] {
+				color: $gray-600;
+			}
+		}
+
+		&.is-tertiary {
+			&:hover:not(:disabled, [aria-disabled="true"]) {
+				background: rgba($alert-red, 0.04);
+			}
+
+			&:active:not(:disabled, [aria-disabled="true"]) {
+				background: rgba($alert-red, 0.08);
+			}
 		}
 	}
 
@@ -237,6 +251,11 @@
 		&:focus {
 			border-radius: $radius-block-ui;
 		}
+
+		&:disabled,
+		&[aria-disabled="true"] {
+			color: $gray-600;
+		}
 	}
 
 	&:not(:disabled, [aria-disabled="true"]):active {
@@ -246,7 +265,7 @@
 	&:disabled,
 	&[aria-disabled="true"] {
 		cursor: default;
-		opacity: 0.3;
+		color: $gray-600;
 	}
 
 	&.is-busy,
@@ -259,7 +278,6 @@
 		@media (prefers-reduced-motion: reduce) {
 			animation-duration: 0s;
 		}
-		opacity: 1;
 		background-size: 100px 100%;
 		/* stylelint-disable -- Disable reason: This function call looks nicer when each argument is on its own line. */
 		background-image: linear-gradient(
@@ -325,8 +343,23 @@
 
 	// Toggled style.
 	&.is-pressed {
-		color: $components-color-foreground-inverted;
-		background: $components-color-foreground;
+		&,
+		&:hover {
+			color: $components-color-foreground-inverted;
+			&:not(:disabled, [aria-disabled="true"]) {
+				background: $components-color-foreground;
+			}
+		}
+
+		&:disabled,
+		&[aria-disabled="true"] {
+			color: $gray-600;
+
+			&:not(.is-primary):not(.is-secondary):not(.is-tertiary) {
+				color: $components-color-foreground-inverted;
+				background: $gray-600;
+			}
+		}
 
 		&:focus:not(:disabled) {
 			box-shadow: inset 0 0 0 1px $components-color-background, 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
@@ -334,11 +367,6 @@
 			// Windows High Contrast mode will show this outline, but not the box-shadow.
 			outline: 2px solid transparent;
 		}
-
-		&:hover:not(:disabled) {
-			color: $components-color-foreground-inverted;
-			background: $components-color-foreground;
-		}
 	}
 
 	svg {

package/src/button/test/index.tsx

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
 
 /**
  * WordPress dependencies
@@ -16,6 +15,7 @@ import { plusCircle } from '@wordpress/icons';
 import Button from '..';
 import Tooltip from '../../tooltip';
 import cleanupTooltip from '../../tooltip/test/utils';
+import { press } from '@ariakit/test';
 
 jest.mock( '../../icon', () => () => <div data-testid="test-icon" /> );
 
@@ -73,12 +73,10 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should render a button element with has-text when children are passed', async () => {
-			const user = userEvent.setup();
-
 			render( <Button icon={ plusCircle }>Children</Button> );
 
 			// Move focus to the button
-			await user.tab();
+			await press.Tab();
 
 			expect( screen.getByRole( 'button' ) ).toHaveClass( 'has-text' );
 		} );
@@ -113,8 +111,6 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should render correctly as a tooltip anchor', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<>
 					<Tooltip text="Tooltip text">
@@ -128,7 +124,7 @@ describe( 'Button', () => {
 				name: 'Tooltip anchor',
 			} );
 
-			await user.tab();
+			await press.Tab();
 
 			expect( anchor ).toHaveFocus();
 
@@ -138,7 +134,7 @@ describe( 'Button', () => {
 
 			expect( tooltip ).toBeVisible();
 
-			await user.tab();
+			await press.Tab();
 
 			expect(
 				screen.getByRole( 'button', { name: 'Focus me' } )
@@ -152,8 +148,6 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should render correctly as a tooltip anchor, ignoring its internal tooltip in favour of the external tooltip', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<>
 					<Tooltip text="Tooltip text">
@@ -167,7 +161,7 @@ describe( 'Button', () => {
 				name: 'Button label',
 			} );
 
-			await user.tab();
+			await press.Tab();
 
 			expect( anchor ).toHaveFocus();
 
@@ -184,7 +178,7 @@ describe( 'Button', () => {
 				} )
 			).not.toBeInTheDocument();
 
-			await user.tab();
+			await press.Tab();
 
 			expect(
 				screen.getByRole( 'button', { name: 'Focus me' } )
@@ -198,8 +192,6 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should not trash the rendered HTML elements when toggling between showing and not showing a tooltip', async () => {
-			const user = userEvent.setup();
-
 			const { rerender } = render(
 				<Button label="Button label">Test button</Button>
 			);
@@ -210,7 +202,7 @@ describe( 'Button', () => {
 
 			expect( button ).toBeVisible();
 
-			await user.tab();
+			await press.Tab();
 
 			expect( button ).toHaveFocus();
 
@@ -307,14 +299,12 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should add an aria-label when the label property is used, with Tooltip wrapper', async () => {
-			const user = userEvent.setup();
-
 			render( <Button icon={ plusCircle } label="WordPress" /> );
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
 			// Move focus to the button
-			await user.tab();
+			await press.Tab();
 
 			expect( screen.getByText( 'WordPress' ) ).toBeVisible();
 		} );
@@ -329,7 +319,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',
@@ -338,11 +328,9 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should populate tooltip with label content for buttons without visible labels (no children)', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<Button
-					describedBy="Description text"
+					description="Description text"
 					label="Label"
 					icon={ plusCircle }
 				/>
@@ -351,20 +339,18 @@ describe( 'Button', () => {
 			expect( screen.queryByText( 'Label' ) ).not.toBeInTheDocument();
 
 			// Move focus to the button
-			await user.tab();
+			await press.Tab();
 
 			expect( screen.getByText( 'Label' ) ).toBeVisible();
 
-			await cleanupTooltip( user );
+			await cleanupTooltip();
 		} );
 
 		it( 'should populate tooltip with description content for buttons with visible labels (buttons with children)', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<Button
 					label="Label"
-					describedBy="Description text"
+					description="Description text"
 					icon={ plusCircle }
 					showTooltip
 				>
@@ -378,7 +364,7 @@ describe( 'Button', () => {
 				} )
 			).toBeVisible();
 
-			await user.tab();
+			await press.Tab();
 
 			expect(
 				screen.getByRole( 'tooltip', {
@@ -386,12 +372,10 @@ describe( 'Button', () => {
 				} )
 			).toBeVisible();
 
-			await cleanupTooltip( user );
+			await cleanupTooltip();
 		} );
 
 		it( 'should allow tooltip disable', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<Button
 					icon={ plusCircle }
@@ -407,14 +391,12 @@ describe( 'Button', () => {
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
 			// Move focus to the button
-			await user.tab();
+			await press.Tab();
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 		} );
 
 		it( 'should show the tooltip for empty children', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<Button icon={ plusCircle } label="WordPress" children={ [] } />
 			);
@@ -422,16 +404,14 @@ describe( 'Button', () => {
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
 			// Move focus to the button
-			await user.tab();
+			await press.Tab();
 
 			expect( screen.getByText( 'WordPress' ) ).toBeVisible();
 
-			await cleanupTooltip( user );
+			await cleanupTooltip();
 		} );
 
 		it( 'should not show the tooltip when icon and children defined', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<Button icon={ plusCircle } label="WordPress">
 					Children
@@ -441,14 +421,12 @@ describe( 'Button', () => {
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
 			// Move focus to the button
-			await user.tab();
+			await press.Tab();
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 		} );
 
 		it( 'should force showing the tooltip even if icon and children defined', async () => {
-			const user = userEvent.setup();
-
 			render(
 				<Button icon={ plusCircle } label="WordPress" showTooltip>
 					Children
@@ -458,11 +436,11 @@ describe( 'Button', () => {
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
 			// Move focus to the button
-			await user.tab();
+			await press.Tab();
 
 			expect( screen.getByText( 'WordPress' ) ).toBeVisible();
 
-			await cleanupTooltip( user );
+			await cleanupTooltip();
 		} );
 
 		describe( 'using `aria-pressed` prop', () => {
@@ -542,6 +520,19 @@ describe( 'Button', () => {
 
 			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', () => {
@@ -646,7 +637,7 @@ describe( '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. */ }
+			{ /* @ts-expect-error */ }
 			<Button disabled accessibleWhenDisabled href="foo" />
 		</>;
 	} );

package/src/button/types.ts

@@ -43,9 +43,9 @@ type BaseButtonProps = {
 	 */
 	children?: ReactNode;
 	/**
-	 * An accessible description for the button.
+	 * A visually hidden accessible description for the button.
 	 */
-	describedBy?: string;
+	description?: string;
 	/**
 	 * If provided, renders an Icon component inside the button.
 	 */
@@ -199,6 +199,13 @@ export type DeprecatedButtonProps = {
 	 * @ignore
 	 */
 	isSmall?: boolean;
+	/**
+	 * A visually hidden accessible description for the button.
+	 *
+	 * @deprecated Use the `description` prop instead.
+	 * @ignore
+	 */
+	describedBy?: string;
 };
 
 export type DeprecatedIconButtonProps = {

package/src/card/card/README.md

@@ -106,7 +106,7 @@ const Example = () => (
 
 ### Context
 
-`<Card />`'s sub-components are connected to `<Card />` using [Context](https://reactjs.org/docs/context.html). Certain props like `size` and `isBorderless` are passed through to some of the sub-components.
+`<Card />`'s sub-components are connected to `<Card />` using [Context](https://react.dev/learn/passing-data-deeply-with-context). Certain props like `size` and `isBorderless` are passed through to some of the sub-components.
 
 In the following example, the `<CardBody />` will render with a size of `small`:
 

package/src/card/stories/index.story.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
 /**
  * Internal dependencies
@@ -41,51 +41,52 @@ const meta: Meta< typeof Card > = {
 
 export default meta;
 
-const Template: StoryFn< typeof Card > = ( args ) => <Card { ...args } />;
-
-export const Default = Template.bind( {} );
-Default.args = {
-	children: (
-		<>
-			<CardHeader>
-				<Heading>CardHeader</Heading>
-			</CardHeader>
-			<CardBody>
-				<Text>CardBody</Text>
-			</CardBody>
-			<CardBody>
-				<Text>CardBody (before CardDivider)</Text>
-			</CardBody>
-			<CardDivider />
-			<CardBody>
-				<Text>CardBody (after CardDivider)</Text>
-			</CardBody>
-			<CardMedia>
-				<img
-					alt="Card Media"
-					src="https://images.unsplash.com/photo-1566125882500-87e10f726cdc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1867&q=80"
-				/>
-			</CardMedia>
-			<CardFooter>
-				<Text>CardFooter</Text>
-				<Button variant="secondary">Action Button</Button>
-			</CardFooter>
-		</>
-	),
+export const Default: StoryObj< typeof Card > = {
+	args: {
+		children: (
+			<>
+				<CardHeader>
+					<Heading>CardHeader</Heading>
+				</CardHeader>
+				<CardBody>
+					<Text>CardBody</Text>
+				</CardBody>
+				<CardBody>
+					<Text>CardBody (before CardDivider)</Text>
+				</CardBody>
+				<CardDivider />
+				<CardBody>
+					<Text>CardBody (after CardDivider)</Text>
+				</CardBody>
+				<CardMedia>
+					<img
+						alt="Card Media"
+						src="https://images.unsplash.com/photo-1566125882500-87e10f726cdc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1867&q=80"
+					/>
+				</CardMedia>
+				<CardFooter>
+					<Text>CardFooter</Text>
+					<Button variant="secondary">Action Button</Button>
+				</CardFooter>
+			</>
+		),
+	},
 };
 
 /**
  * `CardMedia` provides a container for full-bleed content within a `Card`,
  * such as images, video, or even just a background color. The corners will be rounded if necessary.
  */
-export const FullBleedContent = Template.bind( {} );
-FullBleedContent.args = {
-	...Default.args,
-	children: (
-		<CardMedia>
-			<div style={ { padding: 16, background: 'beige' } }>
-				Some full bleed content
-			</div>
-		</CardMedia>
-	),
+export const FullBleedContent: StoryObj< typeof Card > = {
+	...Default,
+	args: {
+		...Default.args,
+		children: (
+			<CardMedia>
+				<div style={ { padding: 16, background: 'beige' } }>
+					Some full bleed content
+				</div>
+			</CardMedia>
+		),
+	},
 };

package/src/checkbox-control/README.md

@@ -55,6 +55,7 @@ const MyCheckboxControl = () => {
 	const [ isChecked, setChecked ] = useState( true );
 	return (
 		<CheckboxControl
+			__nextHasNoMarginBottom
 			label="Is author"
 			help="Is the user a author or not?"
 			checked={ isChecked }
@@ -102,6 +103,13 @@ If indeterminate is true the state of the checkbox will be indeterminate.
 
 -   Required: No
 
+#### `__nextHasNoMarginBottom`: `boolean`
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+-   Required: No
+-   Default: `false`
+
 ## Related components
 
 -   To select one option from a set, and you want to show all the available options at once, use the `RadioControl` component.

package/src/checkbox-control/index.tsx

@@ -31,6 +31,7 @@ import type { WordPressComponentProps } from '../context';
  *   const [ isChecked, setChecked ] = useState( true );
  *   return (
  *     <CheckboxControl
+ *       __nextHasNoMarginBottom
  *       label="Is author"
  *       help="Is the user a author or not?"
  *       checked={ isChecked }

package/src/checkbox-control/style.scss

@@ -3,7 +3,7 @@
 	--checkbox-input-size: 24px; // Width & height for small viewports.
 
 	@include break-small() {
-		--checkbox-input-size: 20px;
+		--checkbox-input-size: 16px;
 	}
 
 	--checkbox-input-margin: #{$grid-unit-10};
@@ -12,6 +12,7 @@
 .components-checkbox-control__label {
 	// Ensure label is aligned with checkbox along X axis
 	line-height: var(--checkbox-input-size);
+	cursor: pointer;
 }
 
 .components-checkbox-control__input[type="checkbox"] {
@@ -61,6 +62,7 @@
 	vertical-align: middle;
 	width: var(--checkbox-input-size);
 	aspect-ratio: 1;
+	line-height: 1; // maintains proper height even with WP common.css
 	flex-shrink: 0;
 }
 

package/src/circular-option-picker/test/index.tsx

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import { render, screen } from '@testing-library/react';
-import { press, sleep } from '@ariakit/test';
+import { press } from '@ariakit/test';
 
 /**
  * Internal dependencies
@@ -70,7 +70,6 @@ describe( 'CircularOptionPicker', () => {
 				/>
 			);
 
-			await sleep();
 			await press.Tab();
 			expect( getOption( 'Option One' ) ).toHaveFocus();
 			await press.ArrowRight();
@@ -90,7 +89,6 @@ describe( 'CircularOptionPicker', () => {
 				/>
 			);
 
-			await sleep();
 			await press.Tab();
 			expect( getOption( 'Option One' ) ).toHaveFocus();
 			await press.ArrowRight();
@@ -110,7 +108,6 @@ describe( 'CircularOptionPicker', () => {
 				/>
 			);
 
-			await sleep();
 			await press.Tab();
 			expect( getOption( 'Option One' ) ).toHaveFocus();
 			await press.ArrowRight();