@wordpress/components 28.2.0 → 28.3.0

package/src/tabs/tablist.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import * as Ariakit from '@ariakit/react';
 
 /**
@@ -10,8 +9,9 @@ import * as Ariakit from '@ariakit/react';
 import warning from '@wordpress/warning';
 import {
 	forwardRef,
+	useCallback,
 	useEffect,
-	useLayoutEffect,
+	useInsertionEffect,
 	useRef,
 	useState,
 } from '@wordpress/element';
@@ -25,49 +25,111 @@ import { TabListWrapper } from './styles';
 import type { WordPressComponentProps } from '../context';
 import clsx from 'clsx';
 
-function useTrackElementOffset(
-	targetElement?: HTMLElement | null,
-	onUpdate?: () => void
-) {
-	const [ indicatorPosition, setIndicatorPosition ] = useState( {
-		left: 0,
-		top: 0,
-		width: 0,
-		height: 0,
-	} );
+// TODO: move these into a separate utility file, for use in other components
+// such as ToggleGroupControl.
 
-	// TODO: replace with useEventCallback or similar when officially available.
-	const updateCallbackRef = useRef( onUpdate );
-	useLayoutEffect( () => {
-		updateCallbackRef.current = onUpdate;
+/**
+ * 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;
+};
 
-	const observedElementRef = useRef< HTMLElement >();
+/**
+ * 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 ?? undefined;
-
-		function updateIndicator( element: HTMLElement ) {
-			setIndicatorPosition( {
-				// Workaround to prevent unwanted scrollbars, see:
-				// https://github.com/WordPress/gutenberg/pull/61979
-				left: Math.max( element.offsetLeft - 1, 0 ),
-				top: Math.max( element.offsetTop - 1, 0 ),
-				width: parseFloat( getComputedStyle( element ).width ),
-				height: parseFloat( getComputedStyle( element ).height ),
-			} );
-			updateCallbackRef.current?.();
-		}
+		observedElementRef.current = targetElement;
 
 		// Set up a ResizeObserver.
 		if ( ! resizeObserverRef.current ) {
 			resizeObserverRef.current = new ResizeObserver( () => {
 				if ( observedElementRef.current ) {
-					updateIndicator( observedElementRef.current );
+					onResizeEvent( observedElementRef.current );
 				}
 			} );
 		}
@@ -75,7 +137,9 @@ function useTrackElementOffset(
 
 		// Observe new element.
 		if ( targetElement ) {
-			updateIndicator( targetElement );
+			if ( fireOnObserve ) {
+				onResizeEvent( targetElement );
+			}
 			resizeObserver.observe( targetElement );
 		}
 
@@ -85,35 +149,115 @@ function useTrackElementOffset(
 				resizeObserver.unobserve( observedElementRef.current );
 			}
 		};
-	}, [ targetElement ] );
+	}, [ 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 );
-
-	// TODO: replace with useEventCallback or similar when officially available.
-	const updateCallbackRef = useRef( onUpdate );
-	useLayoutEffect( () => {
-		updateCallbackRef.current = onUpdate;
-	} );
-
+	const updateCallbackEvent = useEvent( onUpdate );
 	useEffect( () => {
 		if ( previousValueRef.current !== value ) {
-			updateCallbackRef.current( {
+			updateCallbackEvent( {
 				previousValue: previousValueRef.current,
 			} );
 			previousValueRef.current = value;
 		}
-	}, [ value ] );
+	}, [ updateCallbackEvent, value ] );
 }
 
 export const TabList = forwardRef<
@@ -123,7 +267,7 @@ export const TabList = forwardRef<
 	const context = useTabsContext();
 
 	const selectedId = context?.store.useState( 'selectedId' );
-	const indicatorPosition = useTrackElementOffset(
+	const indicatorPosition = useTrackElementOffsetRect(
 		context?.store.item( selectedId )?.element
 	);
 

package/src/tabs/types.ts

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type * as Ariakit from '@ariakit/react';
 
 export type TabsContextProps =

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

@@ -59,9 +59,11 @@ export const ColorScheme: StoryFn< typeof Theme > = ( {
 } ) => {
 	const { colors } = generateThemeVariables( { accent, background } );
 	const { gray, ...otherColors } = colors;
+	/* eslint-disable @typescript-eslint/no-unused-vars */
 	const contrastIssues = Object.entries(
 		checkContrasts( { accent, background }, colors )
 	).filter( ( [ _, error ] ) => !! error );
+	/* eslint-enable @typescript-eslint/no-unused-vars */
 
 	const Chip = ( { color, name }: { color: string; name: string } ) => (
 		<HStack justify="flex-start">

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

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import type { ForwardedRef } from 'react';
-// eslint-disable-next-line no-restricted-imports
 import * as Ariakit from '@ariakit/react';
 
 /**

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

@@ -2,14 +2,12 @@
  * External dependencies
  */
 import type { ForwardedRef } from 'react';
-// eslint-disable-next-line no-restricted-imports
 import { LayoutGroup } from 'framer-motion';
 
 /**
  * WordPress dependencies
  */
 import { useInstanceId } from '@wordpress/compose';
-import { __ } from '@wordpress/i18n';
 import { useMemo } from '@wordpress/element';
 
 /**

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

@@ -2,9 +2,7 @@
  * External dependencies
  */
 import type { ForwardedRef } from 'react';
-// eslint-disable-next-line no-restricted-imports
 import * as Ariakit from '@ariakit/react';
-// eslint-disable-next-line no-restricted-imports
 import { motion } from 'framer-motion';
 
 /**

package/src/toolbar/toolbar/README.md

@@ -74,6 +74,15 @@ Leave undefined for the default style. Or `'unstyled'` which removes the border
 -   Required: No
 -   Default: `undefined`
 
+#### `orientation`: `'horizontal' | 'vertical'`
+
+Specifies the toolbar's orientation.
+
+Leave undefined or 'horizontal' for horizontal orientation keyboard interactions, choose 'vertical' for the alternative.
+
+-   Required: No
+-   Default: `horizontal`
+
 ## Related components
 
 -   Toolbar may contain [ToolbarGroup](/packages/components/src/toolbar-group/README.md), [ToolbarButton](/packages/components/src/toolbar-button/README.md) and [ToolbarItem](/packages/components/src/toolbar-Item/README.md) as children.

package/src/toolbar/toolbar/style.scss

@@ -20,6 +20,13 @@
 
 .components-accessible-toolbar,
 .components-toolbar {
+
+	&[aria-orientation="vertical"] {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+	}
+
 	.components-button {
 		position: relative;
 		height: $block-toolbar-height;

package/src/toolbar/toolbar/toolbar-container.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import * as Ariakit from '@ariakit/react';
 import type { ForwardedRef } from 'react';
 

package/src/toolbar/toolbar/types.ts

@@ -22,4 +22,10 @@ export type ToolbarProps = {
 	 * @default undefined
 	 */
 	variant?: 'unstyled' | undefined;
+	/**
+	 * Orientation of the toolbar keyboard interactions.
+	 *
+	 * @default 'horizontal'
+	 */
+	orientation?: 'horizontal' | 'vertical';
 };

package/src/toolbar/toolbar-button/index.tsx

@@ -16,22 +16,36 @@ import Button from '../../button';
 import ToolbarItem from '../toolbar-item';
 import ToolbarContext from '../toolbar-context';
 import ToolbarButtonContainer from './toolbar-button-container';
-import type { ToolbarButtonProps } from './types';
+import type { ToolbarButtonOverriddenProps, ToolbarButtonProps } from './types';
 import type { WordPressComponentProps } from '../../context';
 
+function useDeprecatedProps( {
+	isDisabled,
+	...otherProps
+}: React.ComponentProps< typeof ToolbarButton > ) {
+	return {
+		disabled: isDisabled,
+		...otherProps,
+	};
+}
+
 function UnforwardedToolbarButton(
-	{
+	props: Omit<
+		WordPressComponentProps< ToolbarButtonProps, typeof Button, false >,
+		'accessibleWhenDisabled' // By default, ToolbarButton will be focusable when disabled.
+	> &
+		ToolbarButtonOverriddenProps,
+	ref: ForwardedRef< any >
+) {
+	const {
 		children,
 		className,
 		containerClassName,
 		extraProps,
 		isActive,
-		isDisabled,
 		title,
-		...props
-	}: WordPressComponentProps< ToolbarButtonProps, typeof Button, false >,
-	ref: ForwardedRef< any >
-) {
+		...restProps
+	} = useDeprecatedProps( props );
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	if ( ! accessibleToolbarState ) {
@@ -39,10 +53,10 @@ function UnforwardedToolbarButton(
 			<ToolbarButtonContainer className={ containerClassName }>
 				<Button
 					ref={ ref }
-					icon={ props.icon }
+					icon={ restProps.icon }
 					label={ title }
-					shortcut={ props.shortcut }
-					data-subscript={ props.subscript }
+					shortcut={ restProps.shortcut }
+					data-subscript={ restProps.subscript }
 					onClick={ (
 						event: ReactMouseEvent<
 							HTMLButtonElement & HTMLAnchorElement,
@@ -50,9 +64,9 @@ function UnforwardedToolbarButton(
 						>
 					) => {
 						event.stopPropagation();
-						// TODO: Possible bug; maybe use onClick instead of props.onClick.
-						if ( props.onClick ) {
-							props.onClick( event );
+						// TODO: Possible bug; maybe use onClick instead of restProps.onClick.
+						if ( restProps.onClick ) {
+							restProps.onClick( event );
 						}
 					} }
 					className={ clsx(
@@ -60,10 +74,10 @@ function UnforwardedToolbarButton(
 						className
 					) }
 					isPressed={ isActive }
-					disabled={ isDisabled }
+					accessibleWhenDisabled
 					data-toolbar-item
 					{ ...extraProps }
-					{ ...props }
+					{ ...restProps }
 				>
 					{ children }
 				</Button>
@@ -78,14 +92,13 @@ function UnforwardedToolbarButton(
 		<ToolbarItem
 			className={ clsx( 'components-toolbar-button', className ) }
 			{ ...extraProps }
-			{ ...props }
+			{ ...restProps }
 			ref={ ref }
 		>
 			{ ( toolbarItemProps ) => (
 				<Button
 					label={ title }
 					isPressed={ isActive }
-					disabled={ isDisabled }
 					{ ...toolbarItemProps }
 				>
 					{ children }

package/src/toolbar/toolbar-button/types.ts

@@ -22,6 +22,9 @@ export type ToolbarButtonProps = {
 	isActive?: boolean;
 	/**
 	 * Indicates if the button is disabled.
+	 *
+	 * @deprecated Use `disabled` instead.
+	 * @ignore
 	 */
 	isDisabled?: boolean;
 	/**
@@ -34,6 +37,22 @@ export type ToolbarButtonProps = {
 	title?: string;
 };
 
+export type ToolbarButtonOverriddenProps = {
+	/**
+	 * 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.
+	 *
+	 * @default true
+	 */
+	accessibleWhenDisabled?: boolean;
+};
+
 export type ToolbarButtonContainerProps = {
 	/**
 	 * Children to be rendered inside the button container.

package/src/toolbar/toolbar-context/index.ts

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type * as Ariakit from '@ariakit/react';
 
 /**

package/src/toolbar/toolbar-item/index.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import * as Ariakit from '@ariakit/react';
 import type { ForwardedRef } from 'react';
 
@@ -50,6 +49,7 @@ function ToolbarItem(
 
 	return (
 		<Ariakit.ToolbarItem
+			accessibleWhenDisabled
 			{ ...allProps }
 			store={ accessibleToolbarStore }
 			render={ render }

package/src/tooltip/index.tsx

@@ -1,8 +1,8 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import * as Ariakit from '@ariakit/react';
+import clsx from 'clsx';
 
 /**
  * WordPress dependencies
@@ -45,6 +45,7 @@ function UnforwardedTooltip(
 ) {
 	const {
 		children,
+		className,
 		delay = TOOLTIP_DELAY,
 		hideOnClick = true,
 		placement,
@@ -113,7 +114,7 @@ function UnforwardedTooltip(
 			{ isOnlyChild && ( text || shortcut ) && (
 				<Ariakit.Tooltip
 					{ ...restProps }
-					className="components-tooltip"
+					className={ clsx( 'components-tooltip', className ) }
 					unmountOnHide
 					gutter={ 4 }
 					id={ describedById }

package/src/tooltip/test/index.tsx

@@ -105,6 +105,24 @@ describe( 'Tooltip', () => {
 				screen.getByRole( 'button', { name: 'Anchor' } )
 			).not.toHaveAttribute( 'data-foo' );
 		} );
+
+		it( 'should add default and custom class names to the tooltip', async () => {
+			render( <Tooltip { ...props } className="foo" /> );
+
+			// Hover over the anchor, tooltip should show
+			await hover(
+				screen.getByRole( 'button', { name: 'Tooltip anchor' } )
+			);
+
+			// Check default and custom classnames
+			await waitFor( () =>
+				expect(
+					screen.getByRole( 'tooltip', {
+						name: 'tooltip text',
+					} )
+				).toHaveClass( 'components-tooltip', 'foo' )
+			);
+		} );
 	} );
 
 	describe( 'keyboard focus', () => {

package/src/tooltip/types.ts

@@ -16,6 +16,10 @@ export type TooltipProps = {
 	 * **Note**: Accepts only one child element.
 	 */
 	children: React.ReactElement;
+	/**
+	 * Custom class name for the tooltip.
+	 */
+	className?: string;
 	/**
 	 * Option to hide the tooltip when the anchor is clicked.
 	 *

package/src/unit-control/index.tsx

@@ -167,11 +167,12 @@ function UnforwardedUnitControl(
 	if ( ! disableUnits && isUnitSelectTabbable && units.length ) {
 		handleOnKeyDown = ( event: KeyboardEvent< HTMLInputElement > ) => {
 			props.onKeyDown?.( event );
-			// Unless the meta key was pressed (to avoid interfering with
-			// shortcuts, e.g. pastes), moves focus to the unit select if a key
+			// Unless the meta or ctrl key was pressed (to avoid interfering with
+			// shortcuts, e.g. pastes), move focus to the unit select if a key
 			// matches the first character of a unit.
 			if (
 				! event.metaKey &&
+				! event.ctrlKey &&
 				reFirstCharacterOfUnits.test( event.key )
 			) {
 				refInputSuffix.current?.focus();