@wordpress/components 21.0.2 → 21.1.2-next.4d3b314fd5.0

package/src/popover/test/index.tsx

@@ -0,0 +1,230 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import type { CSSProperties } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { positionToPlacement, placementToMotionAnimationProps } from '../utils';
+import Popover from '..';
+import type { PopoverProps } from '../types';
+
+type PositionToPlacementTuple = [
+	NonNullable< PopoverProps[ 'position' ] >,
+	NonNullable< PopoverProps[ 'placement' ] >
+];
+type PlacementToAnimationOriginTuple = [
+	NonNullable< PopoverProps[ 'placement' ] >,
+	number,
+	number
+];
+type PlacementToInitialTranslationTuple = [
+	NonNullable< PopoverProps[ 'placement' ] >,
+	'translateY' | 'translateX',
+	CSSProperties[ 'translate' ]
+];
+
+// There's no matching `placement` for 'middle center' positions,
+// fallback to 'bottom' (same as `floating-ui`'s default.)
+const FALLBACK_FOR_MIDDLE_CENTER_POSITIONS = 'bottom';
+
+const ALL_POSITIONS_TO_EXPECTED_PLACEMENTS: PositionToPlacementTuple[] = [
+	// Format: [yAxis]
+	[ 'middle', FALLBACK_FOR_MIDDLE_CENTER_POSITIONS ],
+	[ 'bottom', 'bottom' ],
+	[ 'top', 'top' ],
+	// Format: [yAxis] [xAxis]
+	[ 'middle left', 'left' ],
+	[ 'middle center', FALLBACK_FOR_MIDDLE_CENTER_POSITIONS ],
+	[ 'middle right', 'right' ],
+	[ 'bottom left', 'bottom-end' ],
+	[ 'bottom center', 'bottom' ],
+	[ 'bottom right', 'bottom-start' ],
+	[ 'top left', 'top-end' ],
+	[ 'top center', 'top' ],
+	[ 'top right', 'top-start' ],
+	// Format: [yAxis] [xAxis] [corner]
+	[ 'middle left left', 'left' ],
+	[ 'middle left right', 'left' ],
+	[ 'middle left bottom', 'left-end' ],
+	[ 'middle left top', 'left-start' ],
+	[ 'middle center left', FALLBACK_FOR_MIDDLE_CENTER_POSITIONS ],
+	[ 'middle center right', FALLBACK_FOR_MIDDLE_CENTER_POSITIONS ],
+	[ 'middle center bottom', FALLBACK_FOR_MIDDLE_CENTER_POSITIONS ],
+	[ 'middle center top', FALLBACK_FOR_MIDDLE_CENTER_POSITIONS ],
+	[ 'middle right left', 'right' ],
+	[ 'middle right right', 'right' ],
+	[ 'middle right bottom', 'right-end' ],
+	[ 'middle right top', 'right-start' ],
+	[ 'bottom left left', 'bottom-end' ],
+	[ 'bottom left right', 'bottom-end' ],
+	[ 'bottom left bottom', 'bottom-end' ],
+	[ 'bottom left top', 'bottom-end' ],
+	[ 'bottom center left', 'bottom' ],
+	[ 'bottom center right', 'bottom' ],
+	[ 'bottom center bottom', 'bottom' ],
+	[ 'bottom center top', 'bottom' ],
+	[ 'bottom right left', 'bottom-start' ],
+	[ 'bottom right right', 'bottom-start' ],
+	[ 'bottom right bottom', 'bottom-start' ],
+	[ 'bottom right top', 'bottom-start' ],
+	[ 'top left left', 'top-end' ],
+	[ 'top left right', 'top-end' ],
+	[ 'top left bottom', 'top-end' ],
+	[ 'top left top', 'top-end' ],
+	[ 'top center left', 'top' ],
+	[ 'top center right', 'top' ],
+	[ 'top center bottom', 'top' ],
+	[ 'top center top', 'top' ],
+	[ 'top right left', 'top-start' ],
+	[ 'top right right', 'top-start' ],
+	[ 'top right bottom', 'top-start' ],
+	[ 'top right top', 'top-start' ],
+];
+
+describe( 'Popover', () => {
+	describe( 'Component', () => {
+		describe( 'basic behavior', () => {
+			it( 'should render content', () => {
+				render( <Popover>Hello</Popover> );
+
+				expect( screen.getByText( 'Hello' ) ).toBeInTheDocument();
+			} );
+
+			it( 'should forward additional props to portaled element', () => {
+				render( <Popover role="tooltip">Hello</Popover> );
+
+				expect( screen.getByRole( 'tooltip' ) ).toBeInTheDocument();
+			} );
+		} );
+
+		describe( 'anchor', () => {
+			it( 'should render correctly when anchor is provided', () => {
+				const PopoverWithAnchor = ( args: PopoverProps ) => {
+					// Use internal state instead of a ref to make sure that the component
+					// re-renders when the popover's anchor updates.
+					const [ anchor, setAnchor ] =
+						useState< HTMLParagraphElement | null >( null );
+
+					return (
+						<div>
+							<p ref={ setAnchor }>Anchor</p>
+							<Popover { ...args } anchor={ anchor } />
+						</div>
+					);
+				};
+
+				render(
+					<PopoverWithAnchor>Popover content</PopoverWithAnchor>
+				);
+
+				expect(
+					screen.getByText( 'Popover content' )
+				).toBeInTheDocument();
+			} );
+		} );
+
+		describe( 'focus behavior', () => {
+			it( 'should focus the popover by default when opened', () => {
+				render( <Popover>Popover content</Popover> );
+
+				expect(
+					screen.getByText( 'Popover content' ).parentElement
+				).toHaveFocus();
+			} );
+
+			it( 'should allow focus-on-open behavior to be disabled', () => {
+				render(
+					<Popover focusOnMount={ false }>Popover content</Popover>
+				);
+
+				expect( document.body ).toHaveFocus();
+			} );
+		} );
+	} );
+
+	describe( 'positionToPlacement', () => {
+		it.each( ALL_POSITIONS_TO_EXPECTED_PLACEMENTS )(
+			'converts `%s` to `%s`',
+			( inputPosition, expectedPlacement ) => {
+				expect( positionToPlacement( inputPosition ) ).toEqual(
+					expectedPlacement
+				);
+			}
+		);
+	} );
+
+	describe( 'placementToMotionAnimationProps', () => {
+		describe( 'animation origin', () => {
+			it.each( [
+				[ 'top', 0.5, 1 ],
+				[ 'top-start', 0, 1 ],
+				[ 'top-end', 1, 1 ],
+				[ 'right', 0, 0.5 ],
+				[ 'right-start', 0, 0 ],
+				[ 'right-end', 0, 1 ],
+				[ 'bottom', 0.5, 0 ],
+				[ 'bottom-start', 0, 0 ],
+				[ 'bottom-end', 1, 0 ],
+				[ 'left', 1, 0.5 ],
+				[ 'left-start', 1, 0 ],
+				[ 'left-end', 1, 1 ],
+			] as PlacementToAnimationOriginTuple[] )(
+				'for the `%s` placement computes an animation origin of (%d, %d)',
+				( inputPlacement, expectedOriginX, expectedOriginY ) => {
+					expect(
+						placementToMotionAnimationProps( inputPlacement )
+					).toEqual(
+						expect.objectContaining( {
+							style: expect.objectContaining( {
+								originX: expectedOriginX,
+								originY: expectedOriginY,
+							} ),
+						} )
+					);
+				}
+			);
+		} );
+		describe( 'initial translation', () => {
+			it.each( [
+				[ 'top', 'translateY', '2em' ],
+				[ 'top-start', 'translateY', '2em' ],
+				[ 'top-end', 'translateY', '2em' ],
+				[ 'right', 'translateX', '-2em' ],
+				[ 'right-start', 'translateX', '-2em' ],
+				[ 'right-end', 'translateX', '-2em' ],
+				[ 'bottom', 'translateY', '-2em' ],
+				[ 'bottom-start', 'translateY', '-2em' ],
+				[ 'bottom-end', 'translateY', '-2em' ],
+				[ 'left', 'translateX', '2em' ],
+				[ 'left-start', 'translateX', '2em' ],
+				[ 'left-end', 'translateX', '2em' ],
+			] as PlacementToInitialTranslationTuple[] )(
+				'for the `%s` placement computes an initial `%s` of `%s',
+				(
+					inputPlacement,
+					expectedTranslationProp,
+					expectedTranslationValue
+				) => {
+					expect(
+						placementToMotionAnimationProps( inputPlacement )
+					).toEqual(
+						expect.objectContaining( {
+							initial: expect.objectContaining( {
+								[ expectedTranslationProp ]:
+									expectedTranslationValue,
+							} ),
+						} )
+					);
+				}
+			);
+		} );
+	} );
+} );

package/src/popover/types.ts

@@ -121,6 +121,7 @@ export type PopoverProps = {
 	 * _Note: this prop is deprecated. Use the `placement` prop instead._
 	 */
 	position?:
+		| `${ PositionYAxis }`
 		| `${ PositionYAxis } ${ PositionXAxis }`
 		| `${ PositionYAxis } ${ PositionXAxis } ${ PositionCorner }`;
 	/**

package/src/popover/utils.ts

@@ -14,6 +14,62 @@ import type {
 	PopoverAnchorRefTopBottom,
 } from './types';
 
+const POSITION_TO_PLACEMENT: Record<
+	NonNullable< PopoverProps[ 'position' ] >,
+	NonNullable< PopoverProps[ 'placement' ] >
+> = {
+	bottom: 'bottom',
+	top: 'top',
+	'middle left': 'left',
+	'middle right': 'right',
+	'bottom left': 'bottom-end',
+	'bottom center': 'bottom',
+	'bottom right': 'bottom-start',
+	'top left': 'top-end',
+	'top center': 'top',
+	'top right': 'top-start',
+	'middle left left': 'left',
+	'middle left right': 'left',
+	'middle left bottom': 'left-end',
+	'middle left top': 'left-start',
+	'middle right left': 'right',
+	'middle right right': 'right',
+	'middle right bottom': 'right-end',
+	'middle right top': 'right-start',
+	'bottom left left': 'bottom-end',
+	'bottom left right': 'bottom-end',
+	'bottom left bottom': 'bottom-end',
+	'bottom left top': 'bottom-end',
+	'bottom center left': 'bottom',
+	'bottom center right': 'bottom',
+	'bottom center bottom': 'bottom',
+	'bottom center top': 'bottom',
+	'bottom right left': 'bottom-start',
+	'bottom right right': 'bottom-start',
+	'bottom right bottom': 'bottom-start',
+	'bottom right top': 'bottom-start',
+	'top left left': 'top-end',
+	'top left right': 'top-end',
+	'top left bottom': 'top-end',
+	'top left top': 'top-end',
+	'top center left': 'top',
+	'top center right': 'top',
+	'top center bottom': 'top',
+	'top center top': 'top',
+	'top right left': 'top-start',
+	'top right right': 'top-start',
+	'top right bottom': 'top-start',
+	'top right top': 'top-start',
+	// `middle`/`middle center [corner?]` positions are associated to a fallback
+	// `bottom` placement because there aren't any corresponding placement values.
+	middle: 'bottom',
+	'middle center': 'bottom',
+	'middle center bottom': 'bottom',
+	'middle center left': 'bottom',
+	'middle center right': 'bottom',
+	'middle center top': 'bottom',
+};
+
 /**
  * Converts the `Popover`'s legacy "position" prop to the new "placement" prop
  * (used by `floating-ui`).
@@ -23,22 +79,8 @@ import type {
  */
 export const positionToPlacement = (
 	position: NonNullable< PopoverProps[ 'position' ] >
-): NonNullable< PopoverProps[ 'placement' ] > => {
-	const [ x, y, z ] = position.split( ' ' );
-
-	if ( [ 'top', 'bottom' ].includes( x ) ) {
-		let suffix = '';
-		if ( ( !! z && z === 'left' ) || y === 'right' ) {
-			suffix = '-start';
-		} else if ( ( !! z && z === 'right' ) || y === 'left' ) {
-			suffix = '-end';
-		}
-
-		return ( x + suffix ) as NonNullable< PopoverProps[ 'placement' ] >;
-	}
-
-	return y as NonNullable< PopoverProps[ 'placement' ] >;
-};
+): NonNullable< PopoverProps[ 'placement' ] > =>
+	POSITION_TO_PLACEMENT[ position ] ?? 'bottom';
 
 /**
  * @typedef AnimationOrigin

package/src/range-control/README.md

@@ -16,15 +16,14 @@ A RangeControl for volume
 
 ### Anatomy
 
-![](https://make.wordpress.org/design/files/2018/12/rangecontrol-anatomy.png)
-
 A RangeControl can contain the following elements:
 
-1. **Track**: The track shows the range available for user selection. For left-to-right (LTR) languages, the smallest value appears on the far left, and the largest value on the far right. For right-to-left (RTL) languages this orientation is reversed, with the smallest value on the far right and the largest value on the far left.
-2. **Thumb**: The thumb slides along the track, displaying the selected value through its position.
-3. **Value entry field**: The value entry field displays the currently selected, specific numerical value.
-4. **Icon** (optional): An icon can be displayed before or after the slider.
-5. **Tick mark** (optional): Tick marks represent predetermined values to which the user can move the slider.
+1. **Rail**: The rail represents the entire surface area of the slider, from the minimum value selectable by the user to the maximum value selectable by the user. For left-to-right (LTR) languages, the minimum value appears on the far left, and the maximum value on the far right. For right-to-left (RTL) languages this orientation is reversed, with the minimum value on the far right and the maximum value on the far left.
+2. **Track**: The track represents the portion of the rail from the minimum value to the currently selected value.
+3. **Thumb**: The thumb slides along the track, displaying the selected value through its position.
+4. **Value entry field**: The value entry field displays the currently selected, specific numerical value.
+5. **Icon** (optional): An icon can be displayed before or after the slider.
+6. **Tick mark** (optional): Tick marks represent predetermined values to which the user can move the slider.
 
 ### Types
 

package/src/range-control/input-range.tsx

@@ -7,39 +7,19 @@ import { forwardRef } from '@wordpress/element';
  * Internal dependencies
  */
 import { InputRange as BaseInputRange } from './styles/range-control-styles';
-import { useDebouncedHoverInteraction } from './utils';
 
 import type { InputRangeProps } from './types';
 import type { WordPressComponentProps } from '../ui/context';
 
-const noop = () => {};
-
 function InputRange(
 	props: WordPressComponentProps< InputRangeProps, 'input' >,
 	ref: React.ForwardedRef< HTMLInputElement >
 ) {
-	const {
-		describedBy,
-		label,
-		onHideTooltip = noop,
-		onMouseLeave = noop,
-		onMouseMove = noop,
-		onShowTooltip = noop,
-		value,
-		...otherProps
-	} = props;
-
-	const hoverInteractions = useDebouncedHoverInteraction( {
-		onHide: onHideTooltip,
-		onMouseLeave,
-		onMouseMove,
-		onShow: onShowTooltip,
-	} );
+	const { describedBy, label, value, ...otherProps } = props;
 
 	return (
 		<BaseInputRange
 			{ ...otherProps }
-			{ ...hoverInteractions }
 			aria-describedby={ describedBy }
 			aria-label={ label }
 			aria-hidden={ false }

package/src/range-control/stories/index.tsx

@@ -35,7 +35,7 @@ const meta: ComponentMeta< typeof RangeControl > = {
 		icon: { control: { type: null } },
 		marks: { control: { type: 'object' } },
 		onBlur: { control: { type: null } },
-		onChange: { action: 'onChange' },
+		onChange: { control: { type: null } },
 		onFocus: { control: { type: null } },
 		onMouseLeave: { control: { type: null } },
 		onMouseMove: { control: { type: null } },
@@ -46,6 +46,7 @@ const meta: ComponentMeta< typeof RangeControl > = {
 		value: { control: { type: null } },
 	},
 	parameters: {
+		actions: { argTypesRegex: '^on.*' },
 		controls: { expanded: true },
 		docs: { source: { state: 'open' } },
 	},

package/src/range-control/tooltip.tsx

@@ -59,7 +59,7 @@ function useTooltipPosition( { inputRef, tooltipPosition }: TooltipProps ) {
 		if ( inputRef && inputRef.current ) {
 			setPosition( tooltipPosition );
 		}
-	}, [ tooltipPosition ] );
+	}, [ tooltipPosition, inputRef ] );
 
 	useEffect( () => {
 		setTooltipPosition();

package/src/range-control/types.ts

@@ -236,10 +236,8 @@ export type RailProps = MarksProps & {
 export type InputRangeProps = {
 	describedBy?: string;
 	label?: string;
-	onHideTooltip?: () => void;
 	onMouseLeave?: MouseEventHandler< HTMLInputElement >;
 	onMouseMove?: MouseEventHandler< HTMLInputElement >;
-	onShowTooltip?: () => void;
 	value?: number | '';
 };
 
@@ -292,39 +290,6 @@ export type UseControlledRangeValueArgs = {
 	value: number | null;
 };
 
-export type UseDebouncedHoverInteractionArgs = {
-	/**
-	 *  A callback function invoked when the element is hidden.
-	 *
-	 * @default () => {}
-	 */
-	onHide?: () => void;
-	/**
-	 * A callback function invoked when the mouse is moved out of the element.
-	 *
-	 * @default () => {}
-	 */
-	onMouseLeave?: MouseEventHandler< HTMLInputElement >;
-	/**
-	 * A callback function invoked when the mouse is moved.
-	 *
-	 * @default () => {}
-	 */
-	onMouseMove?: MouseEventHandler< HTMLInputElement >;
-	/**
-	 * A callback function invoked when the element is shown.
-	 *
-	 * @default () => {}
-	 */
-	onShow?: () => void;
-	/**
-	 * Timeout before the element is shown or hidden.
-	 *
-	 * @default 300
-	 */
-	timeout?: number;
-};
-
 export type UseMarksArgs = NumericProps & {
 	marks: RangeMarks;
 	step: number;

package/src/range-control/utils.ts

@@ -1,12 +1,7 @@
-/**
- * External dependencies
- */
-import type { MouseEventHandler } from 'react';
-
 /**
  * WordPress dependencies
  */
-import { useCallback, useRef, useEffect, useState } from '@wordpress/element';
+import { useCallback } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -14,12 +9,7 @@ import { useCallback, useRef, useEffect, useState } from '@wordpress/element';
 import { useControlledState } from '../utils/hooks';
 import { clamp } from '../utils/math';
 
-import type {
-	UseControlledRangeValueArgs,
-	UseDebouncedHoverInteractionArgs,
-} from './types';
-
-const noop = () => {};
+import type { UseControlledRangeValueArgs } from './types';
 
 /**
  * A float supported clamp function for a specific value.
@@ -64,72 +54,10 @@ export function useControlledRangeValue(
 				setInternalState( floatClamp( nextValue, min, max ) );
 			}
 		},
-		[ min, max ]
+		[ min, max, setInternalState ]
 	);
 
 	// `state` can't be an empty string because we specified a fallback value of
 	// `null` in `useControlledState`
 	return [ state as Exclude< typeof state, '' >, setState ] as const;
 }
-
-/**
- * Hook to encapsulate the debouncing "hover" to better handle the showing
- * and hiding of the Tooltip.
- *
- * @param  settings
- * @return Bound properties for use on a React.Node.
- */
-export function useDebouncedHoverInteraction(
-	settings: UseDebouncedHoverInteractionArgs
-) {
-	const {
-		onHide = noop,
-		onMouseLeave = noop as MouseEventHandler,
-		onMouseMove = noop as MouseEventHandler,
-		onShow = noop,
-		timeout = 300,
-	} = settings;
-
-	const [ show, setShow ] = useState( false );
-	const timeoutRef = useRef< number | undefined >();
-
-	const setDebouncedTimeout = useCallback(
-		( callback ) => {
-			window.clearTimeout( timeoutRef.current );
-
-			timeoutRef.current = window.setTimeout( callback, timeout );
-		},
-		[ timeout ]
-	);
-
-	const handleOnMouseMove = useCallback( ( event ) => {
-		onMouseMove( event );
-
-		setDebouncedTimeout( () => {
-			if ( ! show ) {
-				setShow( true );
-				onShow();
-			}
-		} );
-	}, [] );
-
-	const handleOnMouseLeave = useCallback( ( event ) => {
-		onMouseLeave( event );
-
-		setDebouncedTimeout( () => {
-			setShow( false );
-			onHide();
-		} );
-	}, [] );
-
-	useEffect( () => {
-		return () => {
-			window.clearTimeout( timeoutRef.current );
-		};
-	} );
-
-	return {
-		onMouseMove: handleOnMouseMove,
-		onMouseLeave: handleOnMouseLeave,
-	};
-}

package/src/tools-panel/stories/index.js

@@ -29,11 +29,13 @@ export const _default = () => {
 	const [ height, setHeight ] = useState();
 	const [ minHeight, setMinHeight ] = useState();
 	const [ width, setWidth ] = useState();
+	const [ scale, setScale ] = useState();
 
 	const resetAll = () => {
 		setHeight( undefined );
 		setWidth( undefined );
 		setMinHeight( undefined );
+		setScale( undefined );
 	};
 
 	return (
@@ -79,6 +81,31 @@ export const _default = () => {
 							onChange={ ( next ) => setMinHeight( next ) }
 						/>
 					</ToolsPanelItem>
+					<ToolsPanelItem
+						hasValue={ () => !! scale }
+						label="Scale"
+						onDeselect={ () => setScale( undefined ) }
+					>
+						<ToggleGroupControl
+							label="Scale"
+							value={ scale }
+							onChange={ ( next ) => setScale( next ) }
+							isBlock
+						>
+							<ToggleGroupControlOption
+								value="cover"
+								label="Cover"
+							/>
+							<ToggleGroupControlOption
+								value="contain"
+								label="Contain"
+							/>
+							<ToggleGroupControlOption
+								value="fill"
+								label="Fill"
+							/>
+						</ToggleGroupControl>
+					</ToolsPanelItem>
 				</ToolsPanel>
 			</Panel>
 		</PanelWrapperView>

package/src/tools-panel/styles.ts

@@ -1,6 +1,7 @@
 /**
  * External dependencies
  */
+import styled from '@emotion/styled';
 import { css } from '@emotion/react';
 
 /**
@@ -12,7 +13,7 @@ import {
 	Wrapper as BaseControlWrapper,
 } from '../base-control/styles/base-control-styles';
 import { LabelWrapper } from '../input-control/styles/input-control-styles';
-import { COLORS, CONFIG } from '../utils';
+import { COLORS, CONFIG, rtl } from '../utils';
 import { space } from '../ui/utils/space';
 
 const toolsPanelGrid = {
@@ -145,3 +146,29 @@ export const ToolsPanelItemPlaceholder = css`
 export const DropdownMenu = css`
 	min-width: 200px;
 `;
+
+export const ResetLabel = styled.span`
+	color: var( --wp-admin-theme-color-darker-10 );
+	font-size: 11px;
+	font-weight: 500;
+	line-height: 1.4;
+	${ rtl( { marginLeft: space( 3 ) } ) }
+	text-transform: uppercase;
+`;
+
+export const DefaultControlsItem = css`
+	color: ${ COLORS.gray[ 900 ] };
+
+	&&[aria-disabled='true'] {
+		color: ${ COLORS.gray[ 700 ] };
+		opacity: 1;
+
+		&:hover {
+			color: ${ COLORS.gray[ 700 ] };
+		}
+
+		${ ResetLabel } {
+			opacity: 0.3;
+		}
+	}
+`;