@wordpress/components 39.0.0 → 40.1.0

package/src/textarea-control/stories/migration-guide.mdx

@@ -0,0 +1,79 @@
+import { Markdown, Meta } from '@storybook/addon-docs/blocks';
+import * as TextareaControlStories from './index.story';
+
+<Meta of={ TextareaControlStories } name="Migration Guide" />
+
+# TextareaControl migration guide
+
+Migrate from [`TextareaControl`](?path=/docs/components-textareacontrol--docs) in `@wordpress/components` to [`TextareaControl`](?path=/docs/design-system-components-form-textareacontrol--docs) in `@wordpress/ui`.
+
+## Basic migration
+
+Update the import and swap the callback prop:
+
+```jsx
+// Before
+import { TextareaControl } from '@wordpress/components';
+
+<TextareaControl
+	label="Description"
+	value={ value }
+	onChange={ setValue }
+	help="Enter a short description."
+/>;
+
+// After
+import { TextareaControl } from '@wordpress/ui';
+
+<TextareaControl
+	label="Description"
+	value={ value }
+	onValueChange={ setValue }
+	description="Enter a short description."
+/>;
+```
+
+## Prop mapping
+
+<Markdown>{ `
+| \`@wordpress/components\` | \`@wordpress/ui\` | Notes |
+| --- | --- | --- |
+| \`onChange\` | \`onValueChange\` | Receives the next string value on every change. |
+| \`help\` | \`description\` | Use plain text only. |
+| \`help\` with links or other markup | \`details\` | Use when the help text needs semantic content. |
+| \`hideLabelFromVision\` | \`hideLabelFromVision\` | Same behavior. |
+| \`rows\` | \`rows\` | Same default (\`4\`). |
+` }</Markdown>
+
+## Labels
+
+`TextareaControl` requires a `label` prop with a plain `string` value. The legacy component treats `label` as optional.
+
+When the visible label text already exists elsewhere, pass a descriptive string and hide it visually:
+
+```jsx
+<TextareaControl
+	label="Notes"
+	hideLabelFromVision
+	value={ value }
+	onValueChange={ setValue }
+/>;
+```
+
+When the label is not a plain string, or you need a custom layout, compose the [`Textarea`](?path=/docs/design-system-components-form-primitives-textarea--docs) and [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) primitives instead of `TextareaControl`:
+
+```jsx
+import { Field, Textarea } from '@wordpress/ui';
+
+<Field.Root>
+	<Field.Label>
+		Custom <strong>label</strong> content
+	</Field.Label>
+	<Textarea
+		value={ value }
+		onValueChange={ setValue }
+	/>
+</Field.Root>
+```
+
+See the [`Field` stories](?path=/docs/design-system-components-form-primitives-field--docs) for other association patterns, such as external labels with `aria-labelledby`.

package/src/textarea-control/style.module.scss

@@ -0,0 +1,61 @@
+@use "@wordpress/base-styles/mixins" as *;
+@use "../utils/theme-variables" as *;
+
+.textarea {
+	width: 100%;
+	display: block;
+	background: $components-color-background;
+	color: $components-color-foreground;
+	/* stylelint-disable-next-line logical-css/require-logical-keywords -- Preserve Emotion `resize: vertical`; `block` is not equivalent in vertical writing modes. */
+	resize: vertical;
+
+	@include input-control;
+
+	// Vertical padding is to match the standard 40px control height when rows=1,
+	// in conjunction with the 20px line-height.
+	// "Standard" metrics are 10px 12px, but subtracts 1px each to account for the border width.
+	line-height: 20px;
+	padding: 9px 11px;
+
+	// Matching the 20px line-height + the 9px top and bottom padding.
+	min-height: 38px;
+
+	&:disabled {
+		border-color: var(--wpds-color-stroke-interactive-neutral-disabled);
+		color: var(--wpds-color-foreground-interactive-neutral-disabled);
+		// Core's `form.css` sets its own background on disabled textareas.
+		background: $components-color-background;
+	}
+
+	// Use opacity to work in various editor styles.
+	// Keep the legacy vendor placeholders from the Emotion styles for parity
+	&::-webkit-input-placeholder {
+		color: $components-color-dark-gray-placeholder;
+	}
+
+	&::-moz-placeholder {
+		color: $components-color-dark-gray-placeholder;
+	}
+
+	&:-ms-input-placeholder {
+		color: $components-color-dark-gray-placeholder;
+	}
+
+	:global(.is-dark-theme) & {
+		&::-webkit-input-placeholder {
+			color: $components-color-light-gray-placeholder;
+		}
+
+		&::-moz-placeholder {
+			color: $components-color-light-gray-placeholder;
+		}
+
+		&:-ms-input-placeholder {
+			color: $components-color-light-gray-placeholder;
+		}
+	}
+
+	&:disabled::placeholder {
+		color: var(--wpds-color-foreground-interactive-neutral-disabled);
+	}
+}

package/src/tip/style.scss

@@ -7,7 +7,7 @@
 
 	svg {
 		align-self: center;
-		fill: $alert-yellow;
+		color: $alert-yellow;
 		flex-shrink: 0;
 		margin-right: $grid-unit-20;
 	}

package/src/toggle-control/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,6 +1,9 @@
+import { describe, expect, it, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import ToggleControl from '..';
 
+globalThis.wpVitest.mockMatchMedia();
+
 describe( 'ToggleControl', () => {
 	it( 'should label the toggle', () => {
 		render( <ToggleControl label="My toggle" onChange={ () => {} } /> );
@@ -11,7 +14,7 @@ describe( 'ToggleControl', () => {
 	} );
 
 	it( 'triggers change callback with boolean', () => {
-		const onChange = jest.fn();
+		const onChange = vi.fn();
 
 		render( <ToggleControl label="My toggle" onChange={ onChange } /> );
 

package/src/toggle-group-control/context.ts

@@ -1,11 +1,20 @@
 import { createContext, useContext } from '@wordpress/element';
 import type { ToggleGroupControlContextProps } from './types';
 
-const ToggleGroupControlContext = createContext(
-	{} as ToggleGroupControlContextProps
-);
+const ToggleGroupControlContext = createContext<
+	ToggleGroupControlContextProps | undefined
+>( undefined );
 ToggleGroupControlContext.displayName = 'ToggleGroupControlContext';
 
-export const useToggleGroupControlContext = () =>
-	useContext( ToggleGroupControlContext );
+export const useToggleGroupControlContext = (
+	componentName = 'ToggleGroupControlOptionBase'
+) => {
+	const context = useContext( ToggleGroupControlContext );
+	if ( ! context ) {
+		throw new Error(
+			`${ componentName } can only be rendered inside ToggleGroupControl.`
+		);
+	}
+	return context;
+};
 export default ToggleGroupControlContext;

package/src/toggle-group-control/stories/index.story.tsx

@@ -39,8 +39,9 @@ const Template: StoryFn< typeof ToggleGroupControl > = ( {
 	onChange,
 	...props
 } ) => {
-	const [ value, setValue ] =
-		useState< ToggleGroupControlProps[ 'value' ] >();
+	const [ value, setValue ] = useState< ToggleGroupControlProps[ 'value' ] >(
+		props.value
+	);
 
 	return (
 		<ToggleGroupControl
@@ -135,3 +136,15 @@ Deselectable.args = {
 	...WithIcons.args,
 	isDeselectable: true,
 };
+
+/**
+ * When the `disabled` prop is true, the control is unselectable.
+ */
+export const Disabled: StoryFn< typeof ToggleGroupControl > = Template.bind(
+	{}
+);
+Disabled.args = {
+	...Default.args,
+	disabled: true,
+	value: 'left',
+};

package/src/toggle-group-control/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,3 +1,4 @@
+import { describe, expect, it, test, vi } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import { press, click, hover, sleep } from '@ariakit/test';
 import { useState } from '@wordpress/element';
@@ -12,12 +13,22 @@ import { TOOLTIP_DELAY } from '../../tooltip';
 import type { ToggleGroupControlProps } from '../types';
 import controlStyles from '../toggle-group-control/style.module.scss';
 import optionStyles from '../toggle-group-control-option-base/style.module.scss';
+globalThis.wpVitest.mockResizeObserver();
 
 const hoverOutside = async () => {
 	await hover( document.body );
 	await hover( document.body, { clientX: 10, clientY: 10 } );
 };
 
+const expectGroupChromeDisabled = ( group: HTMLElement ) => {
+	expect( group ).toBeVisible();
+	expect( group ).toHaveAttribute( 'aria-disabled', 'true' );
+	// `toBeEnabled()` treats aria-disabled as disabled, so it cannot
+	// catch an HTML `disabled` leak onto this div.
+	// eslint-disable-next-line jest-dom/prefer-enabled-disabled
+	expect( group ).not.toHaveAttribute( 'disabled' );
+};
+
 const getGeneratedEmotionClassNames = ( element: HTMLElement ) =>
 	Array.from( element.classList ).filter( ( className ) =>
 		/^(css|emotion)-/.test( className )
@@ -90,6 +101,32 @@ const optionsWithDisabledOption = (
 	</>
 );
 
+describe( 'required context', () => {
+	it( 'throws when ToggleGroupControlOption is outside ToggleGroupControl', () => {
+		expect( () =>
+			render( <ToggleGroupControlOption value="value" label="Label" /> )
+		).toThrow(
+			'ToggleGroupControlOption can only be rendered inside ToggleGroupControl.'
+		);
+		expect( console ).toHaveErrored();
+	} );
+
+	it( 'throws when ToggleGroupControlOptionIcon is outside ToggleGroupControl', () => {
+		expect( () =>
+			render(
+				<ToggleGroupControlOptionIcon
+					value="value"
+					label="Label"
+					icon={ formatUppercase }
+				/>
+			)
+		).toThrow(
+			'ToggleGroupControlOptionIcon can only be rendered inside ToggleGroupControl.'
+		);
+		expect( console ).toHaveErrored();
+	} );
+} );
+
 describe.each( [
 	[ 'uncontrolled', ToggleGroupControl ],
 	[ 'controlled', ControlledToggleGroupControl ],
@@ -98,17 +135,27 @@ describe.each( [
 
 	describe( 'should render correctly', () => {
 		it( 'with text options', () => {
-			const { container } = render(
+			render(
 				<Component label="Test Toggle Group Control">
 					{ options }
 				</Component>
 			);
 
-			expect( container ).toMatchSnapshot();
+			expect(
+				screen.getByRole( 'radiogroup', {
+					name: 'Test Toggle Group Control',
+				} )
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'radio', { name: 'R' } )
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'radio', { name: 'J' } )
+			).toBeInTheDocument();
 		} );
 
 		it( 'with icons', () => {
-			const { container } = render(
+			render(
 				<Component value="uppercase" label="Test Toggle Group Control">
 					<ToggleGroupControlOptionIcon
 						value="uppercase"
@@ -123,7 +170,12 @@ describe.each( [
 				</Component>
 			);
 
-			expect( container ).toMatchSnapshot();
+			expect(
+				screen.getByRole( 'radio', { name: 'Uppercase' } )
+			).toBeChecked();
+			expect(
+				screen.getByRole( 'radio', { name: 'Lowercase' } )
+			).not.toBeChecked();
 		} );
 	} );
 	it( 'should render with the correct option initially selected when `value` is defined', () => {
@@ -143,7 +195,7 @@ describe.each( [
 		expect( screen.getByRole( 'radio', { name: 'J' } ) ).not.toBeChecked();
 	} );
 	it( 'should call onChange with proper value', async () => {
-		const mockOnChange = jest.fn();
+		const mockOnChange = vi.fn();
 
 		render(
 			<Component
@@ -402,7 +454,7 @@ describe.each( [
 	describe( 'isDeselectable', () => {
 		describe( 'isDeselectable = false', () => {
 			it( 'should not be deselectable', async () => {
-				const mockOnChange = jest.fn();
+				const mockOnChange = vi.fn();
 
 				render(
 					<Component
@@ -453,7 +505,7 @@ describe.each( [
 			} );
 
 			it( 'should ignore disabled radio options', async () => {
-				const mockOnChange = jest.fn();
+				const mockOnChange = vi.fn();
 
 				render(
 					<Component
@@ -501,7 +553,7 @@ describe.each( [
 
 		describe( 'isDeselectable = true', () => {
 			it( 'should be deselectable', async () => {
-				const mockOnChange = jest.fn();
+				const mockOnChange = vi.fn();
 
 				render(
 					<Component
@@ -567,7 +619,7 @@ describe.each( [
 			} );
 
 			it( 'should ignore disabled options', async () => {
-				const mockOnChange = jest.fn();
+				const mockOnChange = vi.fn();
 
 				render(
 					<Component
@@ -626,6 +678,228 @@ describe.each( [
 			} );
 		} );
 	} );
+
+	describe( 'disabled', () => {
+		it( 'should not select another option when the control is disabled', async () => {
+			const mockOnChange = vi.fn();
+
+			render(
+				<Component
+					value="rigas"
+					label="Test"
+					disabled
+					onChange={ mockOnChange }
+				>
+					{ options }
+				</Component>
+			);
+
+			expectGroupChromeDisabled(
+				screen.getByRole( 'radiogroup', { name: 'Test' } )
+			);
+
+			expect( screen.getByRole( 'radio', { name: 'R' } ) ).toBeChecked();
+
+			await click( screen.getByRole( 'radio', { name: 'J' } ) );
+
+			expect( screen.getByRole( 'radio', { name: 'R' } ) ).toBeChecked();
+			expect(
+				screen.getByRole( 'radio', { name: 'J' } )
+			).not.toBeChecked();
+			expect( mockOnChange ).not.toHaveBeenCalled();
+
+			await press.ArrowRight();
+			expect( mockOnChange ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should skip the disabled control when tabbing', async () => {
+			render(
+				<>
+					<button>Before ToggleGroupControl</button>
+					<Component value="rigas" label="Test" disabled>
+						{ options }
+					</Component>
+					<button>After ToggleGroupControl</button>
+				</>
+			);
+
+			await press.Tab();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Before ToggleGroupControl',
+				} )
+			).toHaveFocus();
+
+			await press.Tab();
+
+			const expectedFocusTarget =
+				mode === 'uncontrolled'
+					? screen.getByRole( 'button', {
+							name: 'After ToggleGroupControl',
+					  } )
+					: screen.getByRole( 'button', { name: 'Reset' } );
+
+			expect( expectedFocusTarget ).toHaveFocus();
+		} );
+
+		it( 'should keep the selected option when the control is disabled', () => {
+			render(
+				<Component value="jack" label="Test" disabled>
+					{ options }
+				</Component>
+			);
+
+			expect( screen.getByRole( 'radio', { name: 'J' } ) ).toBeChecked();
+			expect(
+				screen.getByRole( 'radio', { name: 'R' } )
+			).not.toBeChecked();
+		} );
+
+		it( 'should not call onChange when a disabled control is clicked', async () => {
+			const mockOnChange = vi.fn();
+
+			render(
+				<Component
+					value="rigas"
+					label="Test"
+					disabled
+					onChange={ mockOnChange }
+				>
+					{ options }
+				</Component>
+			);
+
+			await click( screen.getByRole( 'radio', { name: 'J' } ) );
+			await click( screen.getByRole( 'radio', { name: 'R' } ) );
+
+			expect( mockOnChange ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should disable every option when the control is disabled, including options without their own disabled prop', () => {
+			render(
+				<Component value="pizza" label="Test" disabled>
+					{ optionsWithDisabledOption }
+				</Component>
+			);
+
+			expectGroupChromeDisabled(
+				screen.getByRole( 'radiogroup', { name: 'Test' } )
+			);
+
+			expect(
+				screen.getByRole( 'radio', { name: 'Pizza' } )
+			).toBeDisabled();
+			expect(
+				screen.getByRole( 'radio', { name: 'Rice' } )
+			).toBeDisabled();
+			expect(
+				screen.getByRole( 'radio', { name: 'Pasta' } )
+			).toBeDisabled();
+		} );
+
+		it( 'should not deselect the pressed option when the control is disabled', async () => {
+			const mockOnChange = vi.fn();
+
+			render(
+				<Component
+					value="rigas"
+					label="Test"
+					onChange={ mockOnChange }
+					isDeselectable
+					disabled
+				>
+					{ options }
+				</Component>
+			);
+
+			expectGroupChromeDisabled(
+				screen.getByRole( 'group', { name: 'Test' } )
+			);
+
+			const pressed = screen.getByRole( 'button', {
+				name: 'R',
+				pressed: true,
+			} );
+			expect( pressed ).toBeVisible();
+			expect( pressed ).toBeDisabled();
+
+			await click( pressed );
+
+			expect(
+				screen.getByRole( 'button', {
+					name: 'R',
+					pressed: true,
+				} )
+			).toBeVisible();
+			expect( mockOnChange ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should skip a deselectable disabled control when tabbing', async () => {
+			render(
+				<>
+					<button>Before ToggleGroupControl</button>
+					<Component
+						isDeselectable
+						value="rigas"
+						label="Test"
+						disabled
+					>
+						{ options }
+					</Component>
+					<button>After ToggleGroupControl</button>
+				</>
+			);
+
+			await press.Tab();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Before ToggleGroupControl',
+				} )
+			).toHaveFocus();
+
+			await press.Tab();
+
+			const expectedFocusTarget =
+				mode === 'uncontrolled'
+					? screen.getByRole( 'button', {
+							name: 'After ToggleGroupControl',
+					  } )
+					: screen.getByRole( 'button', { name: 'Reset' } );
+
+			expect( expectedFocusTarget ).toHaveFocus();
+		} );
+
+		it( 'should not call onChange when a deselectable disabled control is clicked', async () => {
+			const mockOnChange = vi.fn();
+
+			render(
+				<Component
+					value="rigas"
+					label="Test"
+					onChange={ mockOnChange }
+					isDeselectable
+					disabled
+				>
+					{ options }
+				</Component>
+			);
+
+			await click(
+				screen.getByRole( 'button', {
+					name: 'R',
+					pressed: true,
+				} )
+			);
+			await click(
+				screen.getByRole( 'button', {
+					name: 'J',
+					pressed: false,
+				} )
+			);
+
+			expect( mockOnChange ).not.toHaveBeenCalled();
+		} );
+	} );
 } );
 
 test( 'should render block styles without Emotion-generated classes', () => {

package/src/toggle-group-control/toggle-group-control/README.md

@@ -18,11 +18,7 @@ import {
 
 function Example() {
 	return (
-		<ToggleGroupControl
-			label="my label"
-			value="vertical"
-			isBlock
-		>
+		<ToggleGroupControl label="my label" value="vertical" isBlock>
 			<ToggleGroupControlOption value="horizontal" label="Horizontal" />
 			<ToggleGroupControlOption value="vertical" label="Vertical" />
 		</ToggleGroupControl>
@@ -84,3 +80,10 @@ Callback when a segment is selected.
 The value of the `ToggleGroupControl`.
 
 -   Required: No
+
+### `disabled`: `boolean`
+
+If true, every option is unselectable. The selected value is left as-is.
+
+-   Required: No
+-   Default: `false`

package/src/toggle-group-control/toggle-group-control/as-button-group.tsx

@@ -19,6 +19,7 @@ function UnforwardedToggleGroupControlAsButtonGroup(
 		value: valueProp,
 		id: idProp,
 		setSelectedElement,
+		disabled,
 		...otherProps
 	}: WordPressComponentProps<
 		ToggleGroupControlMainControlProps,
@@ -56,6 +57,7 @@ function UnforwardedToggleGroupControlAsButtonGroup(
 			isBlock: ! isAdaptiveWidth,
 			isDeselectable: true,
 			setSelectedElement,
+			disabled: Boolean( disabled ),
 		} ),
 		[
 			baseId,
@@ -63,6 +65,7 @@ function UnforwardedToggleGroupControlAsButtonGroup(
 			setSelectedValue,
 			isAdaptiveWidth,
 			setSelectedElement,
+			disabled,
 		]
 	);
 
@@ -74,6 +77,7 @@ function UnforwardedToggleGroupControlAsButtonGroup(
 				ref={ forwardedRef }
 				role="group"
 				id={ baseId }
+				aria-disabled={ disabled || undefined }
 			>
 				{ children }
 			</View>

package/src/toggle-group-control/toggle-group-control/as-radio-group.tsx

@@ -21,6 +21,7 @@ function UnforwardedToggleGroupControlAsRadioGroup(
 		value: valueProp,
 		id: idProp,
 		setSelectedElement,
+		disabled,
 		...otherProps
 	}: WordPressComponentProps<
 		ToggleGroupControlMainControlProps,
@@ -78,6 +79,7 @@ function UnforwardedToggleGroupControlAsRadioGroup(
 			// @ts-expect-error - This is wrong and we should fix it.
 			setValue,
 			setSelectedElement,
+			disabled: Boolean( disabled ),
 		} ),
 		[
 			baseId,
@@ -86,6 +88,7 @@ function UnforwardedToggleGroupControlAsRadioGroup(
 			selectedValue,
 			setSelectedElement,
 			setValue,
+			disabled,
 		]
 	);
 
@@ -98,6 +101,7 @@ function UnforwardedToggleGroupControlAsRadioGroup(
 				{ ...otherProps }
 				id={ baseId }
 				ref={ forwardedRef }
+				disabled={ disabled || undefined }
 			>
 				{ children }
 			</Ariakit.RadioGroup>

package/src/toggle-group-control/toggle-group-control/component.tsx

@@ -25,6 +25,7 @@ function UnconnectedToggleGroupControl(
 		isAdaptiveWidth = false,
 		isBlock = false,
 		isDeselectable = false,
+		disabled = false,
 		id,
 		label,
 		hideLabelFromVision = false,
@@ -83,6 +84,7 @@ function UnconnectedToggleGroupControl(
 				onChange={ onChange }
 				ref={ refs }
 				value={ value }
+				disabled={ disabled }
 			>
 				{ children }
 			</MainControl>