@wordpress/components 19.11.0 → 19.14.0

package/src/draggable/test/index.native.js

@@ -0,0 +1,130 @@
+/**
+ * External dependencies
+ */
+import { render } from 'test/helpers';
+import {
+	fireGestureHandler,
+	getByGestureTestId,
+} from 'react-native-gesture-handler/jest-utils';
+import { State } from 'react-native-gesture-handler';
+import Animated from 'react-native-reanimated';
+
+/**
+ * WordPress dependencies
+ */
+import { Draggable, DraggableTrigger } from '@wordpress/components';
+
+// Touch event type constants have been extracted from original source code, as they are not exported in the package.
+// Reference: https://github.com/software-mansion/react-native-gesture-handler/blob/90895e5f38616a6be256fceec6c6a391cd9ad7c7/src/TouchEventType.ts
+const TouchEventType = {
+	UNDETERMINED: 0,
+	TOUCHES_DOWN: 1,
+	TOUCHES_MOVE: 2,
+	TOUCHES_UP: 3,
+	TOUCHES_CANCELLED: 4,
+};
+
+// Reanimated uses "requestAnimationFrame" for notifying shared value updates when using "useAnimatedReaction" hook.
+// For testing, we mock the "requestAnimationFrame" so it calls the callback passed instantly.
+let requestAnimationFrameCopy;
+beforeEach( () => {
+	requestAnimationFrameCopy = global.requestAnimationFrame;
+	global.requestAnimationFrame = ( callback ) => callback();
+} );
+afterEach( () => {
+	global.requestAnimationFrame = requestAnimationFrameCopy;
+} );
+
+describe( 'Draggable', () => {
+	it( 'triggers onLongPress handler', () => {
+		const triggerId = 'trigger-id';
+		const onLongPress = jest.fn();
+		const { getByTestId } = render(
+			<Draggable>
+				<DraggableTrigger
+					id={ triggerId }
+					enabled={ true }
+					minDuration={ 500 }
+					onLongPress={ onLongPress }
+					testID="draggableTrigger"
+				>
+					<Animated.View />
+				</DraggableTrigger>
+			</Draggable>
+		);
+
+		const draggableTrigger = getByTestId( 'draggableTrigger' );
+		fireGestureHandler( draggableTrigger, [
+			{ oldState: State.BEGAN, state: State.ACTIVE },
+			{ state: State.ACTIVE },
+		] );
+
+		expect( onLongPress ).toBeCalledTimes( 1 );
+		expect( onLongPress ).toHaveBeenCalledWith( triggerId );
+	} );
+
+	it( 'triggers dragging handlers', () => {
+		const triggerId = 'trigger-id';
+		const onDragStart = jest.fn();
+		const onDragOver = jest.fn();
+		const onDragEnd = jest.fn();
+		const { getByTestId } = render(
+			<Draggable
+				onDragStart={ onDragStart }
+				onDragOver={ onDragOver }
+				onDragEnd={ onDragEnd }
+				testID="draggable"
+			>
+				<DraggableTrigger id={ triggerId } testID="draggableTrigger">
+					<Animated.View />
+				</DraggableTrigger>
+			</Draggable>
+		);
+
+		const draggableTrigger = getByTestId( 'draggableTrigger' );
+		const draggable = getByGestureTestId( 'draggable' );
+		const touchEventId = 1;
+		const touchEvents = [
+			{ id: touchEventId, x: 0, y: 0 },
+			{ id: touchEventId, x: 100, y: 100 },
+			{ id: touchEventId, x: 50, y: 50 },
+		];
+		fireGestureHandler( draggableTrigger, [
+			{ oldState: State.BEGAN, state: State.ACTIVE },
+			{ state: State.ACTIVE },
+		] );
+		fireGestureHandler( draggable, [
+			// TOUCHES_DOWN event is only received on ACTIVE state, so we have to fire it manually.
+			{ oldState: State.BEGAN, state: State.ACTIVE },
+			{
+				allTouches: [ touchEvents[ 0 ] ],
+				eventType: TouchEventType.TOUCHES_DOWN,
+			},
+			{
+				allTouches: [ touchEvents[ 1 ] ],
+				eventType: TouchEventType.TOUCHES_MOVE,
+			},
+			{
+				allTouches: [ touchEvents[ 2 ] ],
+				eventType: TouchEventType.TOUCHES_MOVE,
+			},
+			{ state: State.END },
+		] );
+
+		expect( onDragStart ).toBeCalledTimes( 1 );
+		expect( onDragStart ).toHaveBeenCalledWith( {
+			id: triggerId,
+			x: touchEvents[ 0 ].x,
+			y: touchEvents[ 0 ].y,
+		} );
+		expect( onDragOver ).toBeCalledTimes( 2 );
+		expect( onDragOver ).toHaveBeenNthCalledWith( 1, touchEvents[ 1 ] );
+		expect( onDragOver ).toHaveBeenNthCalledWith( 2, touchEvents[ 2 ] );
+		expect( onDragEnd ).toBeCalledTimes( 1 );
+		expect( onDragEnd ).toHaveBeenCalledWith( {
+			id: triggerId,
+			x: touchEvents[ 2 ].x,
+			y: touchEvents[ 2 ].y,
+		} );
+	} );
+} );

package/src/drop-zone/provider.js

@@ -6,8 +6,7 @@ import deprecated from '@wordpress/deprecated';
 export default function DropZoneProvider( { children } ) {
 	deprecated( 'wp.components.DropZoneProvider', {
 		since: '5.8',
-		hint:
-			'wp.component.DropZone no longer needs a provider. wp.components.DropZoneProvider is safe to remove from your code.',
+		hint: 'wp.component.DropZone no longer needs a provider. wp.components.DropZoneProvider is safe to remove from your code.',
 	} );
 	return children;
 }

package/src/dropdown/index.js

@@ -46,11 +46,11 @@ export default function Dropdown( props ) {
 
 	useEffect(
 		() => () => {
-			if ( onToggle ) {
+			if ( onToggle && isOpen ) {
 				onToggle( false );
 			}
 		},
-		[]
+		[ onToggle, isOpen ]
 	);
 
 	function toggle() {
@@ -108,7 +108,11 @@ export default function Dropdown( props ) {
 					// This value is used to ensure that the dropdowns
 					// align with the editor header by default.
 					offset={ 13 }
-					anchorRef={ ! hasAnchorRef ? containerRef : undefined }
+					anchorRef={
+						! hasAnchorRef
+							? containerRef?.current?.firstChild // Anchor to the rendered toggle.
+							: undefined
+					}
 					{ ...popoverProps }
 					className={ classnames(
 						'components-dropdown__content',

package/src/dropdown-menu/index.js

@@ -3,7 +3,7 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { flatMap, isEmpty, isFunction } from 'lodash';
+import { flatMap, isEmpty } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -34,6 +34,16 @@ function mergeProps( defaultProps = {}, props = {} ) {
 	return mergedProps;
 }
 
+/**
+ * Whether the argument is a function.
+ *
+ * @param {*} maybeFunc The argument to check.
+ * @return {boolean} True if the argument is a function, false otherwise.
+ */
+function isFunction( maybeFunc ) {
+	return typeof maybeFunc === 'function';
+}
+
 function DropdownMenu( dropdownMenuProps ) {
 	const {
 		children,

package/src/dropdown-menu/index.native.js

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { flatMap, isEmpty, isFunction } from 'lodash';
+import { flatMap, isEmpty } from 'lodash';
 import { Platform } from 'react-native';
 /**
  * WordPress dependencies
@@ -34,6 +34,16 @@ function mergeProps( defaultProps = {}, props = {} ) {
 	return mergedProps;
 }
 
+/**
+ * Whether the argument is a function.
+ *
+ * @param {*} maybeFunc The argument to check.
+ * @return {boolean} True if the argument is a function, false otherwise.
+ */
+function isFunction( maybeFunc ) {
+	return typeof maybeFunc === 'function';
+}
+
 function DropdownMenu( {
 	children,
 	className,

package/src/duotone-picker/duotone-picker.js

@@ -20,6 +20,7 @@ import { getDefaultColors, getGradientFromCSSColors } from './utils';
 
 function DuotonePicker( {
 	clearable = true,
+	unsetable = true,
 	colorPalette,
 	duotonePalette,
 	disableCustomColors,
@@ -32,43 +33,60 @@ function DuotonePicker( {
 		[ colorPalette ]
 	);
 
+	const isUnset = value === 'unset';
+
+	const unsetOption = (
+		<CircularOptionPicker.Option
+			key="unset"
+			value="unset"
+			isSelected={ isUnset }
+			tooltipText={ __( 'Unset' ) }
+			className="components-duotone-picker__color-indicator"
+			onClick={ () => {
+				onChange( isUnset ? undefined : 'unset' );
+			} }
+		/>
+	);
+
+	const options = duotonePalette.map( ( { colors, slug, name } ) => {
+		const style = {
+			background: getGradientFromCSSColors( colors, '135deg' ),
+			color: 'transparent',
+		};
+		const tooltipText =
+			name ??
+			sprintf(
+				// translators: %s: duotone code e.g: "dark-grayscale" or "7f7f7f-ffffff".
+				__( 'Duotone code: %s' ),
+				slug
+			);
+		const label = name
+			? sprintf(
+					// translators: %s: The name of the option e.g: "Dark grayscale".
+					__( 'Duotone: %s' ),
+					name
+			  )
+			: tooltipText;
+		const isSelected = isEqual( colors, value );
+
+		return (
+			<CircularOptionPicker.Option
+				key={ slug }
+				value={ colors }
+				isSelected={ isSelected }
+				aria-label={ label }
+				tooltipText={ tooltipText }
+				style={ style }
+				onClick={ () => {
+					onChange( isSelected ? undefined : colors );
+				} }
+			/>
+		);
+	} );
+
 	return (
 		<CircularOptionPicker
-			options={ duotonePalette.map( ( { colors, slug, name } ) => {
-				const style = {
-					background: getGradientFromCSSColors( colors, '135deg' ),
-					color: 'transparent',
-				};
-				const tooltipText =
-					name ??
-					sprintf(
-						// translators: %s: duotone code e.g: "dark-grayscale" or "7f7f7f-ffffff".
-						__( 'Duotone code: %s' ),
-						slug
-					);
-				const label = name
-					? sprintf(
-							// translators: %s: The name of the option e.g: "Dark grayscale".
-							__( 'Duotone: %s' ),
-							name
-					  )
-					: tooltipText;
-				const isSelected = isEqual( colors, value );
-
-				return (
-					<CircularOptionPicker.Option
-						key={ slug }
-						value={ colors }
-						isSelected={ isSelected }
-						aria-label={ label }
-						tooltipText={ tooltipText }
-						style={ style }
-						onClick={ () => {
-							onChange( isSelected ? undefined : colors );
-						} }
-					/>
-				);
-			} ) }
+			options={ unsetable ? [ unsetOption, ...options ] : options }
 			actions={
 				!! clearable && (
 					<CircularOptionPicker.ButtonAction
@@ -80,13 +98,16 @@ function DuotonePicker( {
 			}
 		>
 			{ ! disableCustomColors && ! disableCustomDuotone && (
-				<CustomDuotoneBar value={ value } onChange={ onChange } />
+				<CustomDuotoneBar
+					value={ isUnset ? undefined : value }
+					onChange={ onChange }
+				/>
 			) }
 			{ ! disableCustomDuotone && (
 				<ColorListPicker
 					labels={ [ __( 'Shadows' ), __( 'Highlights' ) ] }
 					colors={ colorPalette }
-					value={ value }
+					value={ isUnset ? undefined : value }
 					disableCustomColors={ disableCustomColors }
 					enableAlpha
 					onChange={ ( newColors ) => {

package/src/duotone-picker/style.scss

@@ -0,0 +1,19 @@
+.components-duotone-picker__color-indicator::before {
+	background: transparent;
+}
+
+.components-duotone-picker__color-indicator > .components-button {
+	// Show a diagonal line (crossed out) for empty swatches.
+	background: linear-gradient(-45deg, transparent 48%, $gray-300 48%, $gray-300 52%, transparent 52%);
+	color: transparent;
+
+	&.is-pressed:hover:not(:disabled) {
+		// Hover state has to be overridden too.
+		background: linear-gradient(-45deg, transparent 48%, $gray-300 48%, $gray-300 52%, transparent 52%);
+		color: transparent;
+	}
+
+	&:not([aria-disabled="true"]):active {
+		color: transparent;
+	}
+}

package/src/elevation/hook.js

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import { css } from '@emotion/react';
-import { isNil } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -16,6 +15,7 @@ import { useContextSystem } from '../ui/context';
 import * as styles from './styles';
 import { CONFIG, reduceMotion } from '../utils';
 import { useCx } from '../utils/hooks/use-cx';
+import { isValueDefined } from '../utils/values';
 
 /**
  * @param {number} value
@@ -49,13 +49,13 @@ export function useElevation( props ) {
 
 	const classes = useMemo( () => {
 		/** @type {number | undefined} */
-		let hoverValue = ! isNil( hover ) ? hover : value * 2;
+		let hoverValue = isValueDefined( hover ) ? hover : value * 2;
 		/** @type {number | undefined} */
-		let activeValue = ! isNil( active ) ? active : value / 2;
+		let activeValue = isValueDefined( active ) ? active : value / 2;
 
 		if ( ! isInteractive ) {
-			hoverValue = ! isNil( hover ) ? hover : undefined;
-			activeValue = ! isNil( active ) ? active : undefined;
+			hoverValue = isValueDefined( hover ) ? hover : undefined;
+			activeValue = isValueDefined( active ) ? active : undefined;
 		}
 
 		const transition = `box-shadow ${ CONFIG.transitionDuration } ${ CONFIG.transitionTimingFunction }`;
@@ -76,7 +76,7 @@ export function useElevation( props ) {
 			reduceMotion( 'transition' )
 		);
 
-		if ( ! isNil( hoverValue ) ) {
+		if ( isValueDefined( hoverValue ) ) {
 			sx.hover = css`
 				*:hover > & {
 					box-shadow: ${ getBoxShadow( hoverValue ) };
@@ -84,7 +84,7 @@ export function useElevation( props ) {
 			`;
 		}
 
-		if ( ! isNil( activeValue ) ) {
+		if ( isValueDefined( activeValue ) ) {
 			sx.active = css`
 				*:active > & {
 					box-shadow: ${ getBoxShadow( activeValue ) };
@@ -92,7 +92,7 @@ export function useElevation( props ) {
 			`;
 		}
 
-		if ( ! isNil( focus ) ) {
+		if ( isValueDefined( focus ) ) {
 			sx.focus = css`
 				*:focus > & {
 					box-shadow: ${ getBoxShadow( focus ) };

package/src/external-link/README.md

@@ -1,5 +1,7 @@
 # ExternalLink
 
+Link to an external resource.
+
 ## Usage
 
 ```jsx
@@ -9,3 +11,19 @@ const MyExternalLink = () => (
 	<ExternalLink href="https://wordpress.org">WordPress.org</ExternalLink>
 );
 ```
+
+## Props
+
+The component accepts the following props. Any other props will be passed through to the `a`.
+
+### `children`: `ReactNode`
+
+The content to be displayed within the link.
+
+-   Required: Yes
+
+### `href`: `string`
+
+The URL of the external resource.
+
+-   Required: Yes

package/src/external-link/{index.js → index.tsx}

@@ -3,6 +3,7 @@
  */
 import classnames from 'classnames';
 import { compact, uniq } from 'lodash';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -16,12 +17,18 @@ import { external } from '@wordpress/icons';
  */
 import { VisuallyHidden } from '../visually-hidden';
 import { StyledIcon } from './styles/external-link-styles';
+import type { ExternalLinkProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-export function ExternalLink(
-	{ href, children, className, rel = '', ...additionalProps },
-	ref
+function UnforwardedExternalLink(
+	props: Omit<
+		WordPressComponentProps< ExternalLinkProps, 'a', false >,
+		'target'
+	>,
+	ref: ForwardedRef< HTMLAnchorElement >
 ) {
-	rel = uniq(
+	const { href, children, className, rel = '', ...additionalProps } = props;
+	const optimizedRel = uniq(
 		compact( [ ...rel.split( ' ' ), 'external', 'noreferrer', 'noopener' ] )
 	).join( ' ' );
 	const classes = classnames( 'components-external-link', className );
@@ -32,7 +39,7 @@ export function ExternalLink(
 			className={ classes }
 			href={ href }
 			target="_blank"
-			rel={ rel }
+			rel={ optimizedRel }
 			ref={ ref }
 		>
 			{ children }
@@ -51,4 +58,17 @@ export function ExternalLink(
 	);
 }
 
-export default forwardRef( ExternalLink );
+/**
+ * Link to an external resource.
+ *
+ * ```jsx
+ * import { ExternalLink } from '@wordpress/components';
+ *
+ * const MyExternalLink = () => (
+ *   <ExternalLink href="https://wordpress.org">WordPress.org</ExternalLink>
+ * );
+ * ```
+ */
+export const ExternalLink = forwardRef( UnforwardedExternalLink );
+
+export default ExternalLink;

package/src/external-link/stories/index.tsx

@@ -0,0 +1,36 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import ExternalLink from '..';
+
+const meta: ComponentMeta< typeof ExternalLink > = {
+	component: ExternalLink,
+	title: 'Components/ExternalLink',
+	argTypes: {
+		children: { control: { type: 'text' } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof ExternalLink > = ( { ...args } ) => {
+	return <ExternalLink { ...args } />;
+};
+
+export const Default: ComponentStory< typeof ExternalLink > = Template.bind(
+	{}
+);
+Default.args = {
+	children: 'WordPress',
+	href: 'https://wordpress.org',
+};

package/src/external-link/types.ts

@@ -0,0 +1,15 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+export type ExternalLinkProps = {
+	/**
+	 * The content to be displayed within the link.
+	 */
+	children: ReactNode;
+	/**
+	 * The URL of the external resource.
+	 */
+	href: string;
+};

package/src/flex/flex/README.md

@@ -1,9 +1,5 @@
 # Flex
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
 `Flex` is a primitive layout component that adaptively aligns child content horizontally or vertically. `Flex` powers components like `HStack` and `VStack`.
 
 ## Usage
@@ -12,20 +8,19 @@ This feature is still experimental. “Experimental” means this is an early im
 
 ```jsx
 import {
-	__experimentalFlex as Flex,
-	__experimentalFlexBlock as FlexBlock,
-	__experimentalFlexItem as FlexItem,
-	__experimentalText as Text,
+	Flex,
+	FlexBlock,
+	FlexItem,
 } from '@wordpress/components';
 
 function Example() {
 	return (
 		<Flex>
 			<FlexItem>
-				<Text>Code</Text>
+				<p>Code</p>
 			</FlexItem>
 			<FlexBlock>
-				<Text>Poetry</Text>
+				<p>Poetry</p>
 			</FlexBlock>
 		</Flex>
 	);

package/src/flex/flex/hook.js

@@ -64,6 +64,7 @@ export function useFlex( props ) {
 		typeof direction === 'string' && direction.includes( 'reverse' );
 
 	const cx = useCx();
+	const rtlWatchResult = rtl.watch();
 
 	const classes = useMemo( () => {
 		const sx = {};
@@ -123,6 +124,8 @@ export function useFlex( props ) {
 			isColumn ? styles.ItemsColumn : styles.ItemsRow,
 			className
 		);
+		// rtlWatchResult is needed to refresh styles when the writing direction changes
+		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [
 		align,
 		className,
@@ -134,7 +137,7 @@ export function useFlex( props ) {
 		isReverse,
 		justify,
 		wrap,
-		rtl.watch(),
+		rtlWatchResult,
 	] );
 
 	return { ...otherProps, className: classes, isColumn };

package/src/flex/flex-item/README.md

@@ -8,7 +8,7 @@ A layout component to contain items of a fixed width within `Flex`.
 
 ## Usage
 
-See [`flex/README.md#usage`](/packages/components/src/flex/README.md#usage) for how to use `FlexItem`.
+See [`flex/README.md#usage`](/packages/components/src/flex/flex/README.md#usage) for how to use `FlexItem`.
 
 ## Props
 

package/src/focal-point-picker/controls.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { noop } from 'lodash';
-
 /**
  * WordPress dependencies
  */
@@ -19,6 +14,7 @@ import { fractionToPercentage } from './utils';
 
 const TEXTCONTROL_MIN = 0;
 const TEXTCONTROL_MAX = 100;
+const noop = () => {};
 
 export default function FocalPointPickerControls( {
 	onChange = noop,

package/src/focal-point-picker/index.js

@@ -272,14 +272,8 @@ export class FocalPointPicker extends Component {
 		};
 	}
 	render() {
-		const {
-			autoPlay,
-			className,
-			help,
-			instanceId,
-			label,
-			url,
-		} = this.props;
+		const { autoPlay, className, help, instanceId, label, url } =
+			this.props;
 		const { bounds, isDragging, percentages } = this.state;
 		const iconCoordinates = this.iconCoordinates();
 

package/src/focal-point-picker/index.native.js

@@ -3,7 +3,6 @@
  */
 import { Animated, PanResponder, View } from 'react-native';
 import Video from 'react-native-video';
-import { clamp } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -24,6 +23,7 @@ import FocalPoint from './focal-point';
 import Tooltip from './tooltip';
 import styles from './style.scss';
 import { isVideoType } from './utils';
+import { clamp } from '../utils/math';
 
 const MIN_POSITION_VALUE = 0;
 const MAX_POSITION_VALUE = 100;