@wordpress/components 28.3.0 → 28.4.0

package/src/tabs/tablist.tsx

@@ -7,14 +7,7 @@ import * as Ariakit from '@ariakit/react';
  * WordPress dependencies
  */
 import warning from '@wordpress/warning';
-import {
-	forwardRef,
-	useCallback,
-	useEffect,
-	useInsertionEffect,
-	useRef,
-	useState,
-} from '@wordpress/element';
+import { forwardRef, useState } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -24,241 +17,8 @@ import { useTabsContext } from './context';
 import { TabListWrapper } from './styles';
 import type { WordPressComponentProps } from '../context';
 import clsx from 'clsx';
-
-// TODO: move these into a separate utility file, for use in other components
-// such as ToggleGroupControl.
-
-/**
- * Any function.
- */
-type AnyFunction = ( ...args: any ) => any;
-
-/**
- * Creates a stable callback function that has access to the latest state and
- * can be used within event handlers and effect callbacks. Throws when used in
- * the render phase.
- *
- * @example
- *
- * ```tsx
- * function Component(props) {
- *   const onClick = useEvent(props.onClick);
- *   React.useEffect(() => {}, [onClick]);
- * }
- * ```
- */
-function useEvent< T extends AnyFunction >( callback?: T ) {
-	const ref = useRef< AnyFunction | undefined >( () => {
-		throw new Error( 'Cannot call an event handler while rendering.' );
-	} );
-	useInsertionEffect( () => {
-		ref.current = callback;
-	} );
-	return useCallback< AnyFunction >(
-		( ...args ) => ref.current?.( ...args ),
-		[]
-	) as T;
-}
-
-/**
- * `useResizeObserver` options.
- */
-type UseResizeObserverOptions = {
-	/**
-	 * Whether to trigger the callback when an element's ResizeObserver is
-	 * first set up.
-	 *
-	 * @default true
-	 */
-	fireOnObserve?: boolean;
-};
-
-/**
- * Fires `onResize` when the target element is resized.
- *
- * **The element must not be stored in a ref**, else it won't be observed
- * or updated. Instead, it should be stored in a React state or equivalent.
- *
- * It sets up a `ResizeObserver` that tracks the element under the hood. The
- * target element can be changed dynamically, and the observer will be
- * updated accordingly.
- *
- * By default, `onResize` is called when the observer is set up, in addition
- * to when the element is resized. This behavior can be disabled with the
- * `fireOnObserve` option.
- *
- * @example
- *
- * ```tsx
- * const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
- *
- * useResizeObserver( targetElement, ( element ) => {
- *   console.log( 'Element resized:', element );
- * } );
- *
- * <div ref={ setTargetElement } />;
- * ```
- */
-function useResizeObserver(
-	/**
-	 * The target element to observe. It can be changed dynamically.
-	 */
-	targetElement: HTMLElement | undefined | null,
-
-	/**
-	 * Callback to fire when the element is resized. It will also be
-	 * called when the observer is set up, unless `fireOnObserve` is
-	 * set to `false`.
-	 */
-	onResize: ( element: HTMLElement ) => void,
-	{ fireOnObserve = true }: UseResizeObserverOptions = {}
-) {
-	const onResizeEvent = useEvent( onResize );
-
-	const observedElementRef = useRef< HTMLElement | null >();
-	const resizeObserverRef = useRef< ResizeObserver >();
-
-	useEffect( () => {
-		if ( targetElement === observedElementRef.current ) {
-			return;
-		}
-
-		observedElementRef.current = targetElement;
-
-		// Set up a ResizeObserver.
-		if ( ! resizeObserverRef.current ) {
-			resizeObserverRef.current = new ResizeObserver( () => {
-				if ( observedElementRef.current ) {
-					onResizeEvent( observedElementRef.current );
-				}
-			} );
-		}
-		const { current: resizeObserver } = resizeObserverRef;
-
-		// Observe new element.
-		if ( targetElement ) {
-			if ( fireOnObserve ) {
-				onResizeEvent( targetElement );
-			}
-			resizeObserver.observe( targetElement );
-		}
-
-		return () => {
-			// Unobserve previous element.
-			if ( observedElementRef.current ) {
-				resizeObserver.unobserve( observedElementRef.current );
-			}
-		};
-	}, [ fireOnObserve, onResizeEvent, targetElement ] );
-}
-
-/**
- * The position and dimensions of an element, relative to its offset parent.
- */
-type ElementOffsetRect = {
-	/**
-	 * The distance from the left edge of the offset parent to the left edge of
-	 * the element.
-	 */
-	left: number;
-	/**
-	 * The distance from the top edge of the offset parent to the top edge of
-	 * the element.
-	 */
-	top: number;
-	/**
-	 * The width of the element.
-	 */
-	width: number;
-	/**
-	 * The height of the element.
-	 */
-	height: number;
-};
-
-/**
- * An `ElementOffsetRect` object with all values set to zero.
- */
-const NULL_ELEMENT_OFFSET_RECT = {
-	left: 0,
-	top: 0,
-	width: 0,
-	height: 0,
-} satisfies ElementOffsetRect;
-
-/**
- * Returns the position and dimensions of an element, relative to its offset
- * parent. This is useful in contexts where `getBoundingClientRect` is not
- * suitable, such as when the element is transformed.
- *
- * **Note:** the `left` and `right` values are adjusted due to a limitation
- * in the way the browser calculates the offset position of the element,
- * which can cause unwanted scrollbars to appear. This adjustment makes the
- * values potentially inaccurate within a range of 1 pixel.
- */
-function getElementOffsetRect( element: HTMLElement ): ElementOffsetRect {
-	return {
-		// The adjustments mentioned in the documentation above are necessary
-		// because `offsetLeft` and `offsetTop` are rounded to the nearest pixel,
-		// which can result in a position mismatch that causes unwanted overflow.
-		// For context, see: https://github.com/WordPress/gutenberg/pull/61979
-		left: Math.max( element.offsetLeft - 1, 0 ),
-		top: Math.max( element.offsetTop - 1, 0 ),
-		// This is a workaround to obtain these values with a sub-pixel precision,
-		// since `offsetWidth` and `offsetHeight` are rounded to the nearest pixel.
-		width: parseFloat( getComputedStyle( element ).width ),
-		height: parseFloat( getComputedStyle( element ).height ),
-	};
-}
-
-/**
- * Tracks the position and dimensions of an element, relative to its offset
- * parent. The element can be changed dynamically.
- */
-function useTrackElementOffsetRect(
-	targetElement: HTMLElement | undefined | null
-) {
-	const [ indicatorPosition, setIndicatorPosition ] =
-		useState< ElementOffsetRect >( NULL_ELEMENT_OFFSET_RECT );
-
-	useResizeObserver( targetElement, ( element ) =>
-		setIndicatorPosition( getElementOffsetRect( element ) )
-	);
-
-	return indicatorPosition;
-}
-
-/**
- * Context object for the `onUpdate` callback of `useOnValueUpdate`.
- */
-type ValueUpdateContext< T > = {
-	previousValue: T;
-};
-
-/**
- * Calls the `onUpdate` callback when the `value` changes.
- */
-function useOnValueUpdate< T >(
-	/**
-	 * The value to watch for changes.
-	 */
-	value: T,
-	/**
-	 * Callback to fire when the value changes.
-	 */
-	onUpdate: ( context: ValueUpdateContext< T > ) => void
-) {
-	const previousValueRef = useRef( value );
-	const updateCallbackEvent = useEvent( onUpdate );
-	useEffect( () => {
-		if ( previousValueRef.current !== value ) {
-			updateCallbackEvent( {
-				previousValue: previousValueRef.current,
-			} );
-			previousValueRef.current = value;
-		}
-	}, [ updateCallbackEvent, value ] );
-}
+import { useTrackElementOffsetRect } from '../utils/element-rect';
+import { useOnValueUpdate } from '../utils/hooks/use-on-value-update';
 
 export const TabList = forwardRef<
 	HTMLDivElement,

package/src/textarea-control/README.md

@@ -79,6 +79,7 @@ const MyTextareaControl = () => {
 
 	return (
 		<TextareaControl
+		  __nextHasNoMarginBottom
 			label="Text"
 			help="Enter some text"
 			value={ text }
@@ -131,6 +132,13 @@ The current value of the textarea.
 
 -   Required: Yes
 
+#### `__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
 
 -   For a field where users only enter one line of text, use the `TextControl` component.

package/src/textarea-control/index.tsx

@@ -69,6 +69,7 @@ function UnforwardedTextareaControl(
  *
  *   return (
  *     <TextareaControl
+ *       __nextHasNoMarginBottom
  *       label="Text"
  *       help="Enter some text"
  *       value={ text }

package/src/toggle-control/index.tsx

@@ -3,6 +3,7 @@
  */
 import type { ChangeEvent, ForwardedRef } from 'react';
 import { css } from '@emotion/react';
+import clsx from 'clsx';
 
 /**
  * WordPress dependencies
@@ -87,11 +88,17 @@ export function ToggleControl(
 	return (
 		<BaseControl
 			id={ id }
-			help={ helpLabel }
+			help={
+				helpLabel && (
+					<span className="components-toggle-control__help">
+						{ helpLabel }
+					</span>
+				)
+			}
 			className={ classes }
 			__nextHasNoMarginBottom
 		>
-			<HStack justify="flex-start" spacing={ 3 }>
+			<HStack justify="flex-start" spacing={ 2 }>
 				<FormToggle
 					id={ id }
 					checked={ checked }
@@ -103,7 +110,9 @@ export function ToggleControl(
 				<FlexBlock
 					as="label"
 					htmlFor={ id }
-					className="components-toggle-control__label"
+					className={ clsx( 'components-toggle-control__label', {
+						'is-disabled': disabled,
+					} ) }
 				>
 					{ label }
 				</FlexBlock>

package/src/toggle-control/style.scss

@@ -0,0 +1,11 @@
+.components-toggle-control__label {
+	line-height: $toggle-height;
+
+	&:not(.is-disabled) {
+		cursor: pointer;
+	}
+}
+
+.components-toggle-control__help {
+	margin-left: $toggle-width + $grid-unit-10;
+}

package/src/toggle-group-control/test/__snapshots__/index.tsx.snap

@@ -132,6 +132,11 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
   border: 0;
 }
 
+.emotion-12[disabled] {
+  opacity: 0.4;
+  cursor: default;
+}
+
 .emotion-12:active {
   background: #fff;
 }
@@ -213,6 +218,11 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
   border: 0;
 }
 
+.emotion-18[disabled] {
+  opacity: 0.4;
+  cursor: default;
+}
+
 .emotion-18:active {
   background: #fff;
 }
@@ -238,7 +248,7 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
         class="components-toggle-group-control emotion-8 emotion-9"
         data-wp-c16t="true"
         data-wp-component="ToggleGroupControl"
-        id="toggle-group-control-as-radio-group-10"
+        id="toggle-group-control-as-radio-group-11"
         role="radiogroup"
       >
         <div
@@ -252,7 +262,7 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
             data-value="uppercase"
             data-wp-c16t="true"
             data-wp-component="ToggleGroupControlOptionBase"
-            id="toggle-group-control-as-radio-group-10-24"
+            id="toggle-group-control-as-radio-group-11-30"
             role="radio"
             type="button"
             value="uppercase"
@@ -291,7 +301,7 @@ exports[`ToggleGroupControl controlled should render correctly with icons 1`] =
             data-value="lowercase"
             data-wp-c16t="true"
             data-wp-component="ToggleGroupControlOptionBase"
-            id="toggle-group-control-as-radio-group-10-25"
+            id="toggle-group-control-as-radio-group-11-31"
             role="radio"
             type="button"
             value="lowercase"
@@ -452,6 +462,11 @@ exports[`ToggleGroupControl controlled should render correctly with text options
   border: 0;
 }
 
+.emotion-12[disabled] {
+  opacity: 0.4;
+  cursor: default;
+}
+
 .emotion-12:active {
   background: #fff;
 }
@@ -486,7 +501,7 @@ exports[`ToggleGroupControl controlled should render correctly with text options
         class="components-toggle-group-control emotion-8 emotion-9"
         data-wp-c16t="true"
         data-wp-component="ToggleGroupControl"
-        id="toggle-group-control-as-radio-group-9"
+        id="toggle-group-control-as-radio-group-10"
         role="radiogroup"
       >
         <div
@@ -499,7 +514,7 @@ exports[`ToggleGroupControl controlled should render correctly with text options
             data-value="rigas"
             data-wp-c16t="true"
             data-wp-component="ToggleGroupControlOptionBase"
-            id="toggle-group-control-as-radio-group-9-22"
+            id="toggle-group-control-as-radio-group-10-28"
             role="radio"
             type="button"
             value="rigas"
@@ -521,7 +536,7 @@ exports[`ToggleGroupControl controlled should render correctly with text options
             data-value="jack"
             data-wp-c16t="true"
             data-wp-component="ToggleGroupControlOptionBase"
-            id="toggle-group-control-as-radio-group-9-23"
+            id="toggle-group-control-as-radio-group-10-29"
             role="radio"
             type="button"
             value="jack"
@@ -677,6 +692,11 @@ exports[`ToggleGroupControl uncontrolled should render correctly with icons 1`]
   border: 0;
 }
 
+.emotion-12[disabled] {
+  opacity: 0.4;
+  cursor: default;
+}
+
 .emotion-12:active {
   background: #fff;
 }
@@ -758,6 +778,11 @@ exports[`ToggleGroupControl uncontrolled should render correctly with icons 1`]
   border: 0;
 }
 
+.emotion-18[disabled] {
+  opacity: 0.4;
+  cursor: default;
+}
+
 .emotion-18:active {
   background: #fff;
 }
@@ -991,6 +1016,11 @@ exports[`ToggleGroupControl uncontrolled should render correctly with text optio
   border: 0;
 }
 
+.emotion-12[disabled] {
+  opacity: 0.4;
+  cursor: default;
+}
+
 .emotion-12:active {
   background: #fff;
 }

package/src/toggle-group-control/test/index.tsx

@@ -80,6 +80,13 @@ const optionsWithTooltip = (
 		/>
 	</>
 );
+const optionsWithDisabledOption = (
+	<>
+		<ToggleGroupControlOption value="pizza" label="Pizza" />
+		<ToggleGroupControlOption value="rice" label="Rice" disabled />
+		<ToggleGroupControlOption value="pasta" label="Pasta" />
+	</>
+);
 
 describe.each( [
 	[ 'uncontrolled', ToggleGroupControl ],
@@ -351,6 +358,53 @@ describe.each( [
 
 				expect( expectedFocusTarget ).toHaveFocus();
 			} );
+
+			it( 'should ignore disabled radio options', async () => {
+				const mockOnChange = jest.fn();
+
+				render(
+					<Component
+						value="pizza"
+						onChange={ mockOnChange }
+						label="Test Toggle Group Control"
+					>
+						{ optionsWithDisabledOption }
+					</Component>
+				);
+
+				await sleep();
+				await press.Tab();
+
+				expect(
+					screen.getByRole( 'radio', { name: 'Pizza' } )
+				).toBeChecked();
+				expect(
+					screen.getByRole( 'radio', { name: 'Rice' } )
+				).toBeDisabled();
+
+				// Arrow navigation skips the disabled option
+				await press.ArrowRight();
+				expect(
+					screen.getByRole( 'radio', { name: 'Pasta' } )
+				).toBeChecked();
+				expect( mockOnChange ).toHaveBeenCalledTimes( 1 );
+				expect( mockOnChange ).toHaveBeenLastCalledWith( 'pasta' );
+
+				// Arrow navigation skips the disabled option
+				await press.ArrowLeft();
+				expect(
+					screen.getByRole( 'radio', { name: 'Pizza' } )
+				).toBeChecked();
+				expect( mockOnChange ).toHaveBeenCalledTimes( 2 );
+				expect( mockOnChange ).toHaveBeenLastCalledWith( 'pizza' );
+
+				// Clicks don't cause the option to be selected
+				await click( screen.getByRole( 'radio', { name: 'Rice' } ) );
+				expect(
+					screen.getByRole( 'radio', { name: 'Pizza' } )
+				).toBeChecked();
+				expect( mockOnChange ).toHaveBeenCalledTimes( 2 );
+			} );
 		} );
 
 		describe( 'isDeselectable = true', () => {
@@ -421,6 +475,66 @@ describe.each( [
 					} )
 				).toHaveFocus();
 			} );
+
+			it( 'should ignore disabled options', async () => {
+				const mockOnChange = jest.fn();
+
+				render(
+					<Component
+						value="pizza"
+						isDeselectable
+						onChange={ mockOnChange }
+						label="Test Toggle Group Control"
+					>
+						{ optionsWithDisabledOption }
+					</Component>
+				);
+
+				await sleep();
+				await press.Tab();
+
+				expect(
+					screen.getByRole( 'button', {
+						name: 'Pizza',
+						pressed: true,
+					} )
+				).toBeVisible();
+				expect(
+					screen.getByRole( 'button', {
+						name: 'Rice',
+						pressed: false,
+					} )
+				).toBeDisabled();
+
+				// Tab key navigation skips the disabled option
+				await press.Tab();
+				await press.Space();
+				expect(
+					screen.getByRole( 'button', {
+						name: 'Pasta',
+						pressed: true,
+					} )
+				).toHaveFocus();
+				expect( mockOnChange ).toHaveBeenCalledTimes( 1 );
+				expect( mockOnChange ).toHaveBeenLastCalledWith( 'pasta' );
+
+				// Tab key navigation skips the disabled option
+				await press.ShiftTab();
+				expect(
+					screen.getByRole( 'button', {
+						name: 'Pizza',
+						pressed: false,
+					} )
+				).toHaveFocus();
+
+				// Clicks don't cause the option to be selected.
+				await click(
+					screen.getByRole( 'button', {
+						name: 'Rice',
+					} )
+				);
+				expect( mockOnChange ).toHaveBeenCalledTimes( 1 );
+			} );
 		} );
 	} );
 } );

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

@@ -52,7 +52,9 @@ function ToggleGroupControlOptionBase(
 			false
 		>,
 		// the element's id is generated internally
-		'id'
+		| 'id'
+		// due to how the component works, only the `disabled` prop should be used
+		| 'aria-disabled'
 	>,
 	forwardedRef: ForwardedRef< any >
 ) {
@@ -82,6 +84,7 @@ function ToggleGroupControlOptionBase(
 		children,
 		showTooltip = false,
 		onFocus: onFocusProp,
+		disabled,
 		...otherButtonProps
 	} = buttonProps;
 
@@ -130,6 +133,7 @@ function ToggleGroupControlOptionBase(
 				{ isDeselectable ? (
 					<button
 						{ ...commonProps }
+						disabled={ disabled }
 						onFocus={ onFocusProp }
 						aria-pressed={ isPressed }
 						type="button"
@@ -139,6 +143,7 @@ function ToggleGroupControlOptionBase(
 					</button>
 				) : (
 					<Ariakit.Radio
+						disabled={ disabled }
 						render={
 							<button
 								type="button"

package/src/toggle-group-control/toggle-group-control-option-base/styles.ts

@@ -64,6 +64,11 @@ export const buttonView = ( {
 		border: 0;
 	}
 
+	&[disabled] {
+		opacity: 0.4;
+		cursor: default;
+	}
+
 	&:active {
 		background: ${ CONFIG.toggleGroupControlBackgroundColor };
 	}

package/src/tools-panel/tools-panel-header/component.tsx

@@ -200,7 +200,7 @@ const ToolsPanelHeader = (
 					menuProps={ { className: dropdownMenuClassName } }
 					toggleProps={ {
 						size: 'small',
-						describedBy: dropdownMenuDescriptionText,
+						description: dropdownMenuDescriptionText,
 					} }
 				>
 					{ () => (

package/src/tree-select/README.md

@@ -15,6 +15,7 @@ const MyTreeSelect = () => {
 
 	return (
 		<TreeSelect
+		  __nextHasNoMarginBottom
 			label="Parent page"
 			noOptionLabel="No parent page"
 			onChange={ ( newPage ) => setPage( newPage ) }
@@ -89,3 +90,11 @@ An array containing the tree objects with the possible nodes the user can select
 
 -   Type: `Object[]`
 -   Required: No
+
+#### __nextHasNoMarginBottom
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`

package/src/tree-select/index.tsx

@@ -37,6 +37,7 @@ function getSelectOptions(
  *
  * 	return (
  * 		<TreeSelect
+ *      __nextHasNoMarginBottom
  * 			label="Parent page"
  * 			noOptionLabel="No parent page"
  * 			onChange={ ( newPage ) => setPage( newPage ) }