@wordpress/components 19.10.0 → 19.13.0

package/src/draggable/index.native.js

@@ -0,0 +1,234 @@
+/**
+ * External dependencies
+ */
+import {
+	Gesture,
+	GestureDetector,
+	LongPressGestureHandler,
+} from 'react-native-gesture-handler';
+import Animated, {
+	useSharedValue,
+	runOnJS,
+	useAnimatedReaction,
+	useAnimatedGestureHandler,
+} from 'react-native-reanimated';
+
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext, useRef, useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import styles from './style.scss';
+
+const Context = createContext( {} );
+const { Provider } = Context;
+
+/**
+ * Draggable component.
+ *
+ * @param {Object}      props               Component props.
+ * @param {JSX.Element} props.children      Children to be rendered.
+ * @param {Function}    [props.onDragEnd]   Callback when dragging ends.
+ * @param {Function}    [props.onDragOver]  Callback when dragging happens over an element.
+ * @param {Function}    [props.onDragStart] Callback when dragging starts.
+ * @param {string}      [props.testID]      Id used for querying the pan gesture in tests.
+ *
+ * @return {JSX.Element} The component to be rendered.
+ */
+const Draggable = ( {
+	children,
+	onDragEnd,
+	onDragOver,
+	onDragStart,
+	testID,
+} ) => {
+	const isDragging = useSharedValue( false );
+	const isPanActive = useSharedValue( false );
+	const draggingId = useSharedValue( '' );
+	const panGestureRef = useRef();
+	const currentFirstTouchId = useSharedValue( null );
+
+	const initialPosition = {
+		x: useSharedValue( 0 ),
+		y: useSharedValue( 0 ),
+	};
+	const lastPosition = {
+		x: useSharedValue( 0 ),
+		y: useSharedValue( 0 ),
+	};
+
+	useAnimatedReaction(
+		() => isDragging.value,
+		( result, previous ) => {
+			if ( result === previous || previous === null ) {
+				return;
+			}
+
+			if ( result ) {
+				if ( onDragStart ) {
+					onDragStart( {
+						x: initialPosition.x.value,
+						y: initialPosition.y.value,
+						id: draggingId.value,
+					} );
+				}
+			} else if ( onDragEnd ) {
+				onDragEnd( {
+					x: lastPosition.x.value,
+					y: lastPosition.y.value,
+					id: draggingId.value,
+				} );
+			}
+		}
+	);
+
+	function getFirstTouchEvent( event ) {
+		'worklet';
+
+		return event.allTouches.find(
+			( touch ) => touch.id === currentFirstTouchId.value
+		);
+	}
+
+	const panGesture = Gesture.Pan()
+		.manualActivation( true )
+		.onTouchesDown( ( event ) => {
+			if ( ! currentFirstTouchId.value ) {
+				const firstEvent = event.allTouches[ 0 ];
+				const { x = 0, y = 0 } = firstEvent;
+
+				currentFirstTouchId.value = firstEvent.id;
+
+				initialPosition.x.value = x;
+				initialPosition.y.value = y;
+			}
+		} )
+		.onTouchesMove( ( event, state ) => {
+			if ( ! isPanActive.value && isDragging.value ) {
+				isPanActive.value = true;
+				state.activate();
+			}
+
+			if ( isPanActive.value && isDragging.value ) {
+				const firstEvent = getFirstTouchEvent( event );
+
+				if ( ! firstEvent ) {
+					state.end();
+					return;
+				}
+
+				lastPosition.x.value = firstEvent.x;
+				lastPosition.y.value = firstEvent.y;
+
+				if ( onDragOver ) {
+					onDragOver( firstEvent );
+				}
+			}
+		} )
+		.onTouchesCancelled( ( _event, state ) => {
+			state.end();
+		} )
+		.onEnd( () => {
+			currentFirstTouchId.value = null;
+			isPanActive.value = false;
+			isDragging.value = false;
+		} )
+		.withRef( panGestureRef )
+		.shouldCancelWhenOutside( false )
+		.withTestId( testID );
+
+	const providerValue = useMemo( () => {
+		return { panGestureRef, isDragging, isPanActive, draggingId };
+	}, [
+		// `isDragging`, `isPanActive` and `draggingId` are created using the
+		// `useSharedValue` hook provided by the `react-native-reanimated`, which in
+		// theory should guarantee that the value of these variables remains stable.
+		// ESLint can't pick this up, and that's why they have to be specified as
+		// dependencies for this hook call.
+		isDragging,
+		isPanActive,
+		draggingId,
+	] );
+
+	return (
+		<GestureDetector gesture={ panGesture }>
+			<Animated.View style={ styles.draggable__container }>
+				<Provider value={ providerValue }>{ children }</Provider>
+			</Animated.View>
+		</GestureDetector>
+	);
+};
+
+/**
+ * Draggable trigger component.
+ *
+ * This component acts as the trigger for the dragging functionality.
+ *
+ * @param {Object}      props                  Component props.
+ * @param {JSX.Element} props.children         Children to be rendered.
+ * @param {*}           props.id               Identifier passed within the event callbacks.
+ * @param {boolean}     [props.enabled]        Enables the long-press gesture.
+ * @param {number}      [props.maxDistance]    Maximum distance, that defines how far the finger is allowed to travel during a long press gesture.
+ * @param {number}      [props.minDuration]    Minimum time, that a finger must remain pressed on the corresponding view.
+ * @param {Function}    [props.onLongPress]    Callback when long-press gesture is triggered over an element.
+ * @param {Function}    [props.onLongPressEnd] Callback when long-press gesture ends.
+ * @param {string}      [props.testID]         Id used for querying the long-press gesture handler in tests.
+ *
+ * @return {JSX.Element} The component to be rendered.
+ */
+const DraggableTrigger = ( {
+	children,
+	enabled = true,
+	id,
+	maxDistance = 1000,
+	minDuration = 500,
+	onLongPress,
+	onLongPressEnd,
+	testID,
+} ) => {
+	const { panGestureRef, isDragging, isPanActive, draggingId } =
+		useContext( Context );
+
+	const gestureHandler = useAnimatedGestureHandler( {
+		onActive: () => {
+			if ( isDragging.value ) {
+				return;
+			}
+
+			draggingId.value = id;
+			isDragging.value = true;
+			if ( onLongPress ) {
+				runOnJS( onLongPress )( id );
+			}
+		},
+		onEnd: () => {
+			if ( ! isPanActive.value ) {
+				isDragging.value = false;
+			}
+
+			if ( onLongPressEnd ) {
+				runOnJS( onLongPressEnd )( id );
+			}
+		},
+	} );
+
+	return (
+		<LongPressGestureHandler
+			enabled={ enabled }
+			minDurationMs={ minDuration }
+			maxDist={ maxDistance }
+			simultaneousHandlers={ panGestureRef }
+			shouldCancelWhenOutside={ false }
+			onGestureEvent={ gestureHandler }
+			testID={ testID }
+		>
+			{ children }
+		</LongPressGestureHandler>
+	);
+};
+
+export { DraggableTrigger };
+export default Draggable;

package/src/draggable/style.native.scss

@@ -0,0 +1,3 @@
+.draggable__container {
+	flex: 1;
+}

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

@@ -31,12 +31,12 @@ export default function Dropdown( props ) {
 	const {
 		renderContent,
 		renderToggle,
-		position = 'bottom right',
 		className,
 		contentClassName,
 		expandOnMobile,
 		headerTitle,
 		focusOnMount,
+		position,
 		popoverProps,
 		onClose,
 		onToggle,
@@ -46,11 +46,11 @@ export default function Dropdown( props ) {
 
 	useEffect(
 		() => () => {
-			if ( onToggle ) {
+			if ( onToggle && isOpen ) {
 				onToggle( false );
 			}
 		},
-		[]
+		[ onToggle, isOpen ]
 	);
 
 	function toggle() {
@@ -82,6 +82,10 @@ export default function Dropdown( props ) {
 	}
 
 	const args = { isOpen, onToggle: toggle, onClose: close };
+	const hasAnchorRef =
+		!! popoverProps?.anchorRef ||
+		!! popoverProps?.getAnchorRect ||
+		!! popoverProps?.anchorRect;
 
 	return (
 		<div
@@ -101,10 +105,15 @@ export default function Dropdown( props ) {
 					expandOnMobile={ expandOnMobile }
 					headerTitle={ headerTitle }
 					focusOnMount={ focusOnMount }
-					{ ...popoverProps }
+					// This value is used to ensure that the dropdowns
+					// align with the editor header by default.
+					offset={ 13 }
 					anchorRef={
-						popoverProps?.anchorRef ?? containerRef.current
+						! hasAnchorRef
+							? containerRef?.current?.firstChild // Anchor to the rendered toggle.
+							: undefined
 					}
+					{ ...popoverProps }
 					className={ classnames(
 						'components-dropdown__content',
 						popoverProps ? popoverProps.className : undefined,

package/src/dropdown/style.scss

@@ -3,7 +3,7 @@
 }
 
 .components-dropdown__content {
-	.components-popover__content > div {
+	.components-popover__content {
 		padding: $grid-unit-10;
 	}
 

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/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/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/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();