@wordpress/components 25.6.1 → 25.8.0

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

@@ -7,10 +7,10 @@ import styled from '@emotion/styled';
 /**
  * Internal dependencies
  */
-import { CONFIG, COLORS, reduceMotion } from '../../utils';
+import { CONFIG, COLORS } from '../../utils';
 import type { ToggleGroupControlProps } from '../types';
 
-export const ToggleGroupControl = ( {
+export const toggleGroupControl = ( {
 	isBlock,
 	isDeselectable,
 	size,
@@ -24,8 +24,6 @@ export const ToggleGroupControl = ( {
 	min-width: 0;
 	padding: 2px;
 	position: relative;
-	transition: transform ${ CONFIG.transitionDurationFastest } linear;
-	${ reduceMotion( 'transition' ) }
 
 	${ toggleGroupControlSize( size ) }
 	${ ! isDeselectable && enclosingBorders( isBlock ) }
@@ -72,21 +70,6 @@ export const block = css`
 	width: 100%;
 `;
 
-export const BackdropView = styled.div`
-	background: ${ COLORS.gray[ 900 ] };
-	border-radius: ${ CONFIG.controlBorderRadius };
-	left: 0;
-	position: absolute;
-	top: 2px;
-	bottom: 2px;
-	transition: transform ${ CONFIG.transitionDurationFast } ease;
-	${ reduceMotion( 'transition' ) }
-	z-index: 1;
-	// Windows High Contrast mode will show this outline, but not the box-shadow.
-	outline: 2px solid transparent;
-	outline-offset: -3px;
-`;
-
 export const VisualLabelWrapper = styled.div`
 	// Makes the inline label be the correct height, equivalent to setting line-height: 0
 	display: flex;

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

@@ -0,0 +1,50 @@
+/**
+ * WordPress dependencies
+ */
+import { usePrevious } from '@wordpress/compose';
+import { useEffect, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { ToggleGroupControlProps } from '../types';
+
+type ValueProp = ToggleGroupControlProps[ 'value' ];
+
+/**
+ * Used to determine, via an internal heuristics, whether an `undefined` value
+ * received for the `value` prop should be interpreted as the component being
+ * used in uncontrolled mode, or as an "empty" value for controlled mode.
+ *
+ * @param valueProp The received `value`
+ */
+export function useComputeControlledOrUncontrolledValue(
+	valueProp: ValueProp
+): { value: ValueProp; defaultValue: ValueProp } {
+	const hasEverBeenUsedInControlledMode = useRef( false );
+	const previousValueProp = usePrevious( valueProp );
+
+	useEffect( () => {
+		if ( ! hasEverBeenUsedInControlledMode.current ) {
+			// Assume the component is being used in controlled mode if:
+			// - the `value` prop is not `undefined`
+			// - the `value` prop was not previously `undefined` and was given a new value
+			hasEverBeenUsedInControlledMode.current =
+				valueProp !== undefined &&
+				previousValueProp !== undefined &&
+				valueProp !== previousValueProp;
+		}
+	}, [ valueProp, previousValueProp ] );
+
+	let value, defaultValue;
+
+	if ( hasEverBeenUsedInControlledMode.current ) {
+		// When in controlled mode, use `''` instead of `undefined`
+		value = valueProp ?? '';
+	} else {
+		// When in uncontrolled mode, the `value` should be intended as the initial value
+		defaultValue = valueProp;
+	}
+
+	return { value, defaultValue };
+}

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

@@ -3,12 +3,15 @@
  */
 import type { ForwardedRef } from 'react';
 // eslint-disable-next-line no-restricted-imports
-import { Radio } from 'reakit';
+import { Radio } from '@ariakit/react/radio';
+// eslint-disable-next-line no-restricted-imports
+import { motion, useReducedMotion } from 'framer-motion';
 
 /**
  * WordPress dependencies
  */
 import { useInstanceId } from '@wordpress/compose';
+import { useMemo } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -26,10 +29,16 @@ import Tooltip from '../../tooltip';
 
 const { ButtonContentView, LabelView } = styles;
 
+const REDUCED_MOTION_TRANSITION_CONFIG = {
+	duration: 0,
+};
+
+const LAYOUT_ID = 'toggle-group-backdrop-shared-layout-id';
+
 const WithToolTip = ( { showTooltip, text, children }: WithToolTipProps ) => {
 	if ( showTooltip && text ) {
 		return (
-			<Tooltip text={ text } position="top center">
+			<Tooltip text={ text } placement="top">
 				{ children }
 			</Tooltip>
 		);
@@ -38,56 +47,78 @@ const WithToolTip = ( { showTooltip, text, children }: WithToolTipProps ) => {
 };
 
 function ToggleGroupControlOptionBase(
-	props: WordPressComponentProps<
-		ToggleGroupControlOptionBaseProps,
-		'button',
-		false
+	props: Omit<
+		WordPressComponentProps<
+			ToggleGroupControlOptionBaseProps,
+			'button',
+			false
+		>,
+		// the element's id is generated internally
+		'id'
 	>,
 	forwardedRef: ForwardedRef< any >
 ) {
+	const shouldReduceMotion = useReducedMotion();
 	const toggleGroupControlContext = useToggleGroupControlContext();
+
 	const id = useInstanceId(
 		ToggleGroupControlOptionBase,
 		toggleGroupControlContext.baseId || 'toggle-group-control-option-base'
-	) as string;
+	);
+
 	const buttonProps = useContextSystem(
 		{ ...props, id },
 		'ToggleGroupControlOptionBase'
 	);
+
 	const {
 		isBlock = false,
 		isDeselectable = false,
 		size = 'default',
-		...otherContextProps /* context props for Ariakit Radio */
 	} = toggleGroupControlContext;
+
 	const {
 		className,
 		isIcon = false,
 		value,
 		children,
 		showTooltip = false,
+		onFocus: onFocusProp,
 		...otherButtonProps
 	} = buttonProps;
 
-	const isPressed = otherContextProps.state === value;
+	const isPressed = toggleGroupControlContext.value === value;
 	const cx = useCx();
-	const labelViewClasses = cx( isBlock && styles.labelBlock );
-	const classes = cx(
-		styles.buttonView( { isDeselectable, isIcon, isPressed, size } ),
-		className
+	const labelViewClasses = useMemo(
+		() => cx( isBlock && styles.labelBlock ),
+		[ cx, isBlock ]
 	);
+	const itemClasses = useMemo(
+		() =>
+			cx(
+				styles.buttonView( {
+					isDeselectable,
+					isIcon,
+					isPressed,
+					size,
+				} ),
+				className
+			),
+		[ cx, isDeselectable, isIcon, isPressed, size, className ]
+	);
+	const backdropClasses = useMemo( () => cx( styles.backdropView ), [ cx ] );
 
 	const buttonOnClick = () => {
 		if ( isDeselectable && isPressed ) {
-			otherContextProps.setState( undefined );
+			toggleGroupControlContext.setValue( undefined );
 		} else {
-			otherContextProps.setState( value );
+			toggleGroupControlContext.setValue( value );
 		}
 	};
 
 	const commonProps = {
 		...otherButtonProps,
-		className: classes,
+		className: itemClasses,
 		'data-value': value,
 		ref: forwardedRef,
 	};
@@ -101,6 +132,7 @@ function ToggleGroupControlOptionBase(
 				{ isDeselectable ? (
 					<button
 						{ ...commonProps }
+						onFocus={ onFocusProp }
 						aria-pressed={ isPressed }
 						type="button"
 						onClick={ buttonOnClick }
@@ -109,17 +141,35 @@ function ToggleGroupControlOptionBase(
 					</button>
 				) : (
 					<Radio
-						{ ...commonProps }
-						{
-							...otherContextProps /* these are only for Ariakit Radio */
+						render={
+							<button
+								{ ...commonProps }
+								onFocus={ ( event ) => {
+									onFocusProp?.( event );
+									if ( event.defaultPrevented ) return;
+									toggleGroupControlContext.setValue( value );
+								} }
+							/>
 						}
-						as="button"
 						value={ value }
 					>
 						<ButtonContentView>{ children }</ButtonContentView>
 					</Radio>
 				) }
 			</WithToolTip>
+			{ /* Animated backdrop using framer motion's shared layout animation */ }
+			{ isPressed ? (
+				<motion.div
+					className={ backdropClasses }
+					transition={
+						shouldReduceMotion
+							? REDUCED_MOTION_TRANSITION_CONFIG
+							: undefined
+					}
+					role="presentation"
+					layoutId={ LAYOUT_ID }
+				/>
+			) : null }
 		</LabelView>
 	);
 }

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

@@ -50,8 +50,10 @@ export const buttonView = ( {
 	padding: 0 12px;
 	position: relative;
 	text-align: center;
-	transition: background ${ CONFIG.transitionDurationFast } linear,
-		color ${ CONFIG.transitionDurationFast } linear, font-weight 60ms linear;
+	transition:
+		background ${ CONFIG.transitionDurationFast } linear,
+		color ${ CONFIG.transitionDurationFast } linear,
+		font-weight 60ms linear;
 	${ reduceMotion( 'transition' ) }
 	user-select: none;
 	width: 100%;
@@ -82,7 +84,8 @@ const deselectable = css`
 	color: ${ COLORS.gray[ 900 ] };
 
 	&:focus {
-		box-shadow: inset 0 0 0 1px ${ COLORS.white },
+		box-shadow:
+			inset 0 0 0 1px ${ COLORS.white },
 			0 0 0 ${ CONFIG.borderWidthFocus } ${ COLORS.theme.accent };
 		outline: 2px solid transparent;
 	}
@@ -109,3 +112,14 @@ const isIconStyles = ( {
 		padding-right: 0;
 	`;
 };
+
+export const backdropView = css`
+	background: ${ COLORS.gray[ 900 ] };
+	border-radius: ${ CONFIG.controlBorderRadius };
+	position: absolute;
+	inset: 0;
+	z-index: 1;
+	// Windows High Contrast mode will show this outline, but not the box-shadow.
+	outline: 2px solid transparent;
+	outline-offset: -3px;
+`;

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

@@ -1,14 +1,13 @@
 /**
  * External dependencies
  */
-import type { MutableRefObject, ReactNode, ReactText } from 'react';
-// eslint-disable-next-line no-restricted-imports
-import type { RadioStateReturn } from 'reakit';
+import type { ReactNode } from 'react';
 
 /**
  * Internal dependencies
  */
 import type { BaseControlProps } from '../base-control/types';
+import type { TooltipProps } from '../tooltip/types';
 
 export type ToggleGroupControlOptionBaseProps = {
 	children: ReactNode;
@@ -18,7 +17,7 @@ export type ToggleGroupControlOptionBaseProps = {
 	 * @default false
 	 */
 	isIcon?: boolean;
-	value: ReactText;
+	value: string | number;
 	/**
 	 * Whether to display a Tooltip for the control option. If set to `true`, the tooltip will
 	 * show the aria-label or the label prop text.
@@ -58,7 +57,7 @@ export type WithToolTipProps = {
 	/**
 	 * React children
 	 */
-	children: ReactNode;
+	children: TooltipProps[ 'children' ];
 	/**
 	 * Label for the Tooltip component.
 	 */
@@ -107,11 +106,11 @@ export type ToggleGroupControlProps = Pick<
 	/**
 	 * Callback when a segment is selected.
 	 */
-	onChange?: ( value: ReactText | undefined ) => void;
+	onChange?: ( value: string | number | undefined ) => void;
 	/**
 	 * The selected value.
 	 */
-	value?: ReactText;
+	value?: string | number;
 	/**
 	 * The options to render in the `ToggleGroupControl`, using either the `ToggleGroupControlOption` or
 	 * `ToggleGroupControlOptionIcon` components.
@@ -125,33 +124,16 @@ export type ToggleGroupControlProps = Pick<
 	size?: 'default' | '__unstable-large';
 };
 
-type ToggleGroupControlAsRadioContext = {
-	isDeselectable?: false;
-} & RadioStateReturn;
-
-type ToggleGroupControlAsButtonContext = { isDeselectable: true } & Pick<
-	RadioStateReturn,
-	'state' | 'setState'
->;
-
-export type ToggleGroupControlContextProps = Pick<
-	ToggleGroupControlProps,
-	'isBlock' | 'size'
-> & {
+export type ToggleGroupControlContextProps = {
+	isDeselectable?: boolean;
 	baseId: string;
-} & ( ToggleGroupControlAsRadioContext | ToggleGroupControlAsButtonContext );
-
-export type ToggleGroupControlBackdropProps = {
-	containerRef: MutableRefObject< HTMLElement | undefined >;
-	containerWidth?: number | null;
-	isAdaptiveWidth?: boolean;
-	state?: any;
+	isBlock: ToggleGroupControlProps[ 'isBlock' ];
+	size: ToggleGroupControlProps[ 'size' ];
+	value: ToggleGroupControlProps[ 'value' ];
+	setValue: ( newValue: string | number | undefined ) => void;
 };
 
 export type ToggleGroupControlMainControlProps = Pick<
 	ToggleGroupControlProps,
-	'children' | 'isAdaptiveWidth' | 'label' | 'size'
-> & {
-	onChange: ( value: ReactText | undefined ) => void;
-	value?: ReactText;
-};
+	'children' | 'isAdaptiveWidth' | 'label' | 'size' | 'onChange' | 'value'
+>;

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import type { Meta, StoryFn } from '@storybook/react';
 
 /**
  * WordPress dependencies
@@ -37,9 +37,19 @@ import {
 } from '..';
 import DropdownMenu from '../../dropdown-menu';
 
-const meta: ComponentMeta< typeof Toolbar > = {
+const meta: Meta< typeof Toolbar > = {
 	title: 'Components/Toolbar',
 	component: Toolbar,
+	subcomponents: {
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		ToolbarButton,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		ToolbarGroup,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		ToolbarItem,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		ToolbarDropdownMenu,
+	},
 	argTypes: {
 		children: { control: { type: null } },
 	},
@@ -59,7 +69,7 @@ function InlineImageIcon() {
 	);
 }
 
-const Template: ComponentStory< typeof Toolbar > = ( props ) => (
+const Template: StoryFn< typeof Toolbar > = ( props ) => (
 	<div style={ { height: 280 } }>
 		<Toolbar { ...props } />
 	</div>
@@ -107,9 +117,8 @@ Default.args = {
 				<ToolbarButton icon={ link } label="Link" />
 				<ToolbarGroup
 					isCollapsed
-					// @ts-expect-error TODO: Remove when ToolbarGroup is typed
-					icon={ false }
-					label="More rich text controls"
+					icon={ null }
+					title="More rich text controls"
 					controls={ [
 						{ icon: code, title: 'Inline code' },
 						{ icon: <InlineImageIcon />, title: 'Inline image' },
@@ -121,9 +130,8 @@ Default.args = {
 				/>
 			</ToolbarGroup>
 			<ToolbarGroup
-				// @ts-expect-error TODO: Remove when ToolbarGroup is typed
 				icon={ more }
-				label="Align"
+				title="Align"
 				isCollapsed
 				controls={ [
 					{

package/src/toolbar/test/toolbar-group.tsx

@@ -8,6 +8,11 @@ import { fireEvent, render, screen } from '@testing-library/react';
  */
 import { ToolbarGroup } from '..';
 
+/**
+ * WordPress dependencies
+ */
+import { wordpress } from '@wordpress/icons';
+
 describe( 'ToolbarGroup', () => {
 	describe( 'basic rendering', () => {
 		it( 'should render an empty node, when controls are not passed', () => {
@@ -23,10 +28,11 @@ describe( 'ToolbarGroup', () => {
 		} );
 
 		it( 'should render a list of controls with buttons', () => {
-			const clickHandler = ( event: Event ) => event;
+			const clickHandler = ( event?: React.MouseEvent ) => event;
+
 			const controls = [
 				{
-					icon: 'wordpress',
+					icon: wordpress,
 					title: 'WordPress',
 					onClick: clickHandler,
 					isActive: false,
@@ -41,10 +47,10 @@ describe( 'ToolbarGroup', () => {
 		} );
 
 		it( 'should render a list of controls with buttons and active control', () => {
-			const clickHandler = ( event: Event ) => event;
+			const clickHandler = ( event?: React.MouseEvent ) => event;
 			const controls = [
 				{
-					icon: 'wordpress',
+					icon: wordpress,
 					title: 'WordPress',
 					onClick: clickHandler,
 					isActive: true,
@@ -63,14 +69,14 @@ describe( 'ToolbarGroup', () => {
 				[
 					// First set.
 					{
-						icon: 'wordpress',
+						icon: wordpress,
 						title: 'WordPress',
 					},
 				],
 				[
 					// Second set.
 					{
-						icon: 'wordpress',
+						icon: wordpress,
 						title: 'WordPress',
 					},
 				],
@@ -95,7 +101,7 @@ describe( 'ToolbarGroup', () => {
 			const clickHandler = jest.fn();
 			const controls = [
 				{
-					icon: 'wordpress',
+					icon: wordpress,
 					title: 'WordPress',
 					onClick: clickHandler,
 					isActive: true,

package/src/toolbar/toolbar/index.tsx

@@ -42,7 +42,15 @@ function UnforwardedToolbar(
 			alternative: 'ToolbarGroup component',
 			link: 'https://developer.wordpress.org/block-editor/components/toolbar/',
 		} );
-		return <ToolbarGroup { ...props } className={ className } />;
+		// Extracting title from `props` because `ToolbarGroup` doesn't accept it.
+		const { title: _title, ...restProps } = props;
+		return (
+			<ToolbarGroup
+				isCollapsed={ false }
+				{ ...restProps }
+				className={ className }
+			/>
+		);
 	}
 	// `ToolbarGroup` already uses components-toolbar for compatibility reasons.
 	const finalClassName = classnames(

package/src/toolbar/toolbar-dropdown-menu/{index.js → index.tsx}

@@ -1,25 +1,32 @@
-// @ts-nocheck
-
 /**
  * WordPress dependencies
  */
 import { forwardRef, useContext } from '@wordpress/element';
 
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * Internal dependencies
  */
 import ToolbarItem from '../toolbar-item';
 import ToolbarContext from '../toolbar-context';
 import DropdownMenu from '../../dropdown-menu';
+import type { DropdownMenuProps } from '../../dropdown-menu/types';
 
-function ToolbarDropdownMenu( props, ref ) {
+function ToolbarDropdownMenu(
+	props: DropdownMenuProps,
+	ref: ForwardedRef< any >
+) {
 	const accessibleToolbarState = useContext( ToolbarContext );
 
 	if ( ! accessibleToolbarState ) {
 		return <DropdownMenu { ...props } />;
 	}
 
-	// ToobarItem will pass all props to the render prop child, which will pass
+	// ToolbarItem will pass all props to the render prop child, which will pass
 	// all props to the toggle of DropdownMenu. This means that ToolbarDropdownMenu
 	// has the same API as DropdownMenu.
 	return (

package/src/toolbar/toolbar-group/README.md

@@ -1,6 +1,6 @@
 # ToolbarGroup
 
-A ToolbarGroup can be used to create subgroups of controls inside a [Toolbar](/packages/components/src/toolbar/README.md).
+A ToolbarGroup can be used to create subgroups of controls inside a [Toolbar](/packages/components/src/toolbar/toolbar/README.md).
 
 ## Usage
 
@@ -30,4 +30,4 @@ ToolbarGroup will pass all HTML props to the underlying element.
 
 ## Related components
 
--   ToolbarGroup may contain [ToolbarButton](/packages/components/src/toolbar-button/README.md) and [ToolbarItem](/packages/components/src/toolbar-Item/README.md) as children.
+-   ToolbarGroup may contain [ToolbarButton](/packages/components/src/toolbar/toolbar-button/README.md) and [ToolbarItem](/packages/components/src/toolbar/toolbar-item/README.md) as children.

package/src/toolbar/toolbar-group/{index.js → index.tsx}

@@ -1,5 +1,3 @@
-// @ts-nocheck
-
 /**
  * External dependencies
  */
@@ -17,6 +15,11 @@ import ToolbarButton from '../toolbar-button';
 import ToolbarGroupContainer from './toolbar-group-container';
 import ToolbarGroupCollapsed from './toolbar-group-collapsed';
 import ToolbarContext from '../toolbar-context';
+import type { ToolbarGroupProps, ToolbarGroupControls } from './types';
+
+function isNestedArray< T = any >( arr: T[] | T[][] ): arr is T[][] {
+	return Array.isArray( arr ) && Array.isArray( arr[ 0 ] );
+}
 
 /**
  * Renders a collapsible group of controls
@@ -41,12 +44,12 @@ import ToolbarContext from '../toolbar-context';
  * Either `controls` or `children` is required, otherwise this components
  * renders nothing.
  *
- * @param {Object}    props               Component props.
- * @param {Array}     [props.controls]    The controls to render in this toolbar.
- * @param {WPElement} [props.children]    Any other things to render inside the toolbar besides the controls.
- * @param {string}    [props.className]   Class to set on the container div.
- * @param {boolean}   [props.isCollapsed] Turns ToolbarGroup into a dropdown menu.
- * @param {string}    [props.title]       ARIA label for dropdown menu if is collapsed.
+ * @param props               Component props.
+ * @param [props.controls]    The controls to render in this toolbar.
+ * @param [props.children]    Any other things to render inside the toolbar besides the controls.
+ * @param [props.className]   Class to set on the container div.
+ * @param [props.isCollapsed] Turns ToolbarGroup into a dropdown menu.
+ * @param [props.title]       ARIA label for dropdown menu if is collapsed.
  */
 function ToolbarGroup( {
 	controls = [],
@@ -55,7 +58,7 @@ function ToolbarGroup( {
 	isCollapsed,
 	title,
 	...props
-} ) {
+}: ToolbarGroupProps ) {
 	// It'll contain state if `ToolbarGroup` is being used within
 	// `<Toolbar label="label" />`
 	const accessibleToolbarState = useContext( ToolbarContext );
@@ -74,9 +77,11 @@ function ToolbarGroup( {
 	);
 
 	// Normalize controls to nested array of objects (sets of controls)
-	let controlSets = controls;
-	if ( ! Array.isArray( controlSets[ 0 ] ) ) {
-		controlSets = [ controlSets ];
+	let controlSets: ToolbarGroupControls[][];
+	if ( isNestedArray( controls ) ) {
+		controlSets = controls;
+	} else {
+		controlSets = [ controls ];
 	}
 
 	if ( isCollapsed ) {
@@ -94,13 +99,13 @@ function ToolbarGroup( {
 	return (
 		<ToolbarGroupContainer className={ finalClassName } { ...props }>
 			{ controlSets?.flatMap( ( controlSet, indexOfSet ) =>
-				controlSet.map( ( control, indexOfControl ) => (
+				controlSet.map( ( control, indexOfControl: number ) => (
 					<ToolbarButton
 						key={ [ indexOfSet, indexOfControl ].join() }
 						containerClassName={
 							indexOfSet > 0 && indexOfControl === 0
 								? 'has-left-divider'
-								: null
+								: undefined
 						}
 						{ ...control }
 					/>