@wordpress/components 19.10.0 → 19.11.0

package/src/date-time/{time.js → time.tsx}

@@ -4,6 +4,8 @@
 import classnames from 'classnames';
 import { isInteger } from 'lodash';
 import moment from 'moment';
+import type { FocusEvent } from 'react';
+import type { Moment } from 'moment';
 
 /**
  * WordPress dependencies
@@ -22,25 +24,18 @@ import { __ } from '@wordpress/i18n';
 import Button from '../button';
 import ButtonGroup from '../button-group';
 import TimeZone from './timezone';
+import type { WordPressComponentProps } from '../ui/context';
+import type { UpdateOnBlurAsIntegerFieldProps, TimePickerProps } from './types';
 
-/**
- * Module Constants
- */
 const TIMEZONELESS_FORMAT = 'YYYY-MM-DDTHH:mm:ss';
 
-function from12hTo24h( hours, isPm ) {
+function from12hTo24h( hours: number, isPm: boolean ) {
 	return isPm ? ( ( hours % 12 ) + 12 ) % 24 : hours % 12;
 }
 
 /**
- * <UpdateOnBlurAsIntegerField>
- * A shared component to parse, validate, and handle remounting of the underlying form field element like <input> and <select>.
- *
- * @param {Object}        props             Component props.
- * @param {string}        props.as          Render the component as specific element tag, defaults to "input".
- * @param {number|string} props.value       The default value of the component which will be parsed to integer.
- * @param {Function}      props.onUpdate    Call back when blurred and validated.
- * @param {string}        [props.className]
+ * A shared component to parse, validate, and handle remounting of the
+ * underlying form field element like <input> and <select>.
  */
 function UpdateOnBlurAsIntegerField( {
 	as,
@@ -48,11 +43,11 @@ function UpdateOnBlurAsIntegerField( {
 	onUpdate,
 	className,
 	...props
-} ) {
-	function handleBlur( event ) {
+}: WordPressComponentProps< UpdateOnBlurAsIntegerFieldProps, 'input', true > ) {
+	function handleBlur( event: FocusEvent< HTMLInputElement > ) {
 		const { target } = event;
 
-		if ( value === target.value ) {
+		if ( String( value ) === target.value ) {
 			return;
 		}
 
@@ -65,10 +60,10 @@ function UpdateOnBlurAsIntegerField( {
 			( typeof props.min !== 'undefined' && parsedValue < props.min )
 		) {
 			// If validation failed, reset the value to the previous valid value.
-			target.value = value;
+			target.value = String( value );
 		} else {
 			// Otherwise, it's valid, call onUpdate.
-			onUpdate( target.name, parsedValue );
+			onUpdate( parsedValue );
 		}
 	}
 
@@ -86,19 +81,33 @@ function UpdateOnBlurAsIntegerField( {
 }
 
 /**
- * <TimePicker>
+ * TimePicker is a React component that renders a clock for time selection.
+ *
+ * ```jsx
+ * import { TimePicker } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
  *
- * @typedef {Date|string|number} WPValidDateTimeFormat
+ * const MyTimePicker = () => {
+ *   const [ time, setTime ] = useState( new Date() );
  *
- * @param {Object}                props             Component props.
- * @param {boolean}               props.is12Hour    Should the time picker showed in 12 hour format or 24 hour format.
- * @param {WPValidDateTimeFormat} props.currentTime The initial current time the time picker should render.
- * @param {Function}              props.onChange    Callback function when the date changed.
+ *   return (
+ *     <TimePicker
+ *       currentTime={ date }
+ *       onChange={ ( newTime ) => setTime( newTime ) }
+ *       is12Hour
+ *     />
+ *   );
+ * };
+ * ```
  */
-export function TimePicker( { is12Hour, currentTime, onChange } ) {
+export function TimePicker( {
+	is12Hour,
+	currentTime,
+	onChange,
+}: TimePickerProps ) {
 	const [ date, setDate ] = useState( () =>
 		// Truncate the date at the minutes, see: #15495.
-		moment( currentTime ).startOf( 'minutes' )
+		currentTime ? moment( currentTime ).startOf( 'minutes' ) : moment()
 	);
 
 	// Reset the state when currentTime changed.
@@ -115,7 +124,7 @@ export function TimePicker( { is12Hour, currentTime, onChange } ) {
 			year: date.format( 'YYYY' ),
 			minutes: date.format( 'mm' ),
 			hours: date.format( is12Hour ? 'hh' : 'HH' ),
-			am: date.format( 'H' ) <= 11 ? 'AM' : 'PM',
+			am: Number( date.format( 'H' ) ) <= 11 ? 'AM' : 'PM',
 		} ),
 		[ date, is12Hour ]
 	);
@@ -124,28 +133,30 @@ export function TimePicker( { is12Hour, currentTime, onChange } ) {
 	 * Function that sets the date state and calls the onChange with a new date.
 	 * The date is truncated at the minutes.
 	 *
-	 * @param {Object} newDate The date object.
+	 * @param {Moment} newDate The date object.
 	 */
-	function changeDate( newDate ) {
+	function changeDate( newDate: Moment ) {
 		setDate( newDate );
-		onChange( newDate.format( TIMEZONELESS_FORMAT ) );
+		onChange?.( newDate.format( TIMEZONELESS_FORMAT ) );
 	}
 
-	function update( name, value ) {
-		// If the 12-hour format is being used and the 'PM' period is selected, then
-		// the incoming value (which ranges 1-12) should be increased by 12 to match
-		// the expected 24-hour format.
-		let adjustedValue = value;
-		if ( name === 'hours' && is12Hour ) {
-			adjustedValue = from12hTo24h( value, am === 'PM' );
-		}
+	function update( name: 'date' | 'month' | 'year' | 'hours' | 'minutes' ) {
+		return ( value: number ) => {
+			// If the 12-hour format is being used and the 'PM' period is selected, then
+			// the incoming value (which ranges 1-12) should be increased by 12 to match
+			// the expected 24-hour format.
+			let adjustedValue = value;
+			if ( name === 'hours' && is12Hour ) {
+				adjustedValue = from12hTo24h( value, am === 'PM' );
+			}
 
-		// Clone the date and call the specific setter function according to `name`.
-		const newDate = date.clone()[ name ]( adjustedValue );
-		changeDate( newDate );
+			// Clone the date and call the specific setter function according to `name`.
+			const newDate = date.clone()[ name ]( adjustedValue );
+			changeDate( newDate );
+		};
 	}
 
-	function updateAmPm( value ) {
+	function updateAmPm( value: 'AM' | 'PM' ) {
 		return () => {
 			if ( am === value ) {
 				return;
@@ -173,7 +184,7 @@ export function TimePicker( { is12Hour, currentTime, onChange } ) {
 				step={ 1 }
 				min={ 1 }
 				max={ 31 }
-				onUpdate={ update }
+				onUpdate={ update( 'date' ) }
 			/>
 		</div>
 	);
@@ -187,7 +198,7 @@ export function TimePicker( { is12Hour, currentTime, onChange } ) {
 				name="month"
 				value={ month }
 				// The value starts from 0, so we have to -1 when setting month.
-				onUpdate={ ( key, value ) => update( key, value - 1 ) }
+				onUpdate={ ( value ) => update( 'month' )( value - 1 ) }
 			>
 				<option value="01">{ __( 'January' ) }</option>
 				<option value="02">{ __( 'February' ) }</option>
@@ -236,7 +247,7 @@ export function TimePicker( { is12Hour, currentTime, onChange } ) {
 							min={ 0 }
 							max={ 9999 }
 							value={ year }
-							onUpdate={ update }
+							onUpdate={ update( 'year' ) }
 						/>
 					</div>
 				</div>
@@ -257,7 +268,7 @@ export function TimePicker( { is12Hour, currentTime, onChange } ) {
 							min={ is12Hour ? 1 : 0 }
 							max={ is12Hour ? 12 : 23 }
 							value={ hours }
-							onUpdate={ update }
+							onUpdate={ update( 'hours' ) }
 						/>
 						<span
 							className="components-datetime__time-separator"
@@ -274,7 +285,7 @@ export function TimePicker( { is12Hour, currentTime, onChange } ) {
 							min={ 0 }
 							max={ 59 }
 							value={ minutes }
-							onUpdate={ update }
+							onUpdate={ update( 'minutes' ) }
 						/>
 					</div>
 					{ is12Hour && (

package/src/date-time/{timezone.js → timezone.tsx}

@@ -10,7 +10,8 @@ import { __experimentalGetSettings as getDateSettings } from '@wordpress/date';
 import Tooltip from '../tooltip';
 
 /**
- * Displays timezone information when user timezone is different from site timezone.
+ * Displays timezone information when user timezone is different from site
+ * timezone.
  */
 const TimeZone = () => {
 	const { timezone } = getDateSettings();
@@ -24,9 +25,9 @@ const TimeZone = () => {
 		return null;
 	}
 
-	const offsetSymbol = timezone.offset >= 0 ? '+' : '';
+	const offsetSymbol = Number( timezone.offset ) >= 0 ? '+' : '';
 	const zoneAbbr =
-		'' !== timezone.abbr && isNaN( timezone.abbr )
+		'' !== timezone.abbr && isNaN( Number( timezone.abbr ) )
 			? timezone.abbr
 			: `UTC${ offsetSymbol }${ timezone.offset }`;
 

package/src/date-time/types.ts

@@ -0,0 +1,106 @@
+/**
+ * External dependencies
+ */
+import type { Moment } from 'moment';
+import type { ReactNode } from 'react';
+
+export type UpdateOnBlurAsIntegerFieldProps = {
+	/**
+	 * The value of the integer field.
+	 */
+	value: number | string;
+
+	/**
+	 * Called when the field is changed.
+	 */
+	onUpdate: ( value: number ) => void;
+
+	/**
+	 * Children to render inside the field.
+	 */
+	children?: ReactNode;
+};
+
+export type TimePickerProps = {
+	/**
+	 * The initial current time the time picker should render.
+	 */
+	currentTime?: Date | string | number | null;
+
+	/**
+	 * Whether we use a 12-hour clock. With a 12-hour clock, an AM/PM widget is
+	 * displayed and the time format is assumed to be `MM-DD-YYYY` (as opposed
+	 * to the default format `DD-MM-YYYY`).
+	 */
+	is12Hour?: boolean;
+
+	/**
+	 * The function called when a new time has been selected. It is passed the
+	 * time as an argument.
+	 */
+	onChange?: ( time: string ) => void;
+};
+
+export type DatePickerEvent = {
+	/**
+	 * The date of the event.
+	 */
+	date: Date;
+};
+
+export type DatePickerDayProps = {
+	/**
+	 * The day to display.
+	 */
+	day: Moment;
+
+	/**
+	 * List of events to show on this day.
+	 *
+	 * @default []
+	 */
+	events?: DatePickerEvent[];
+};
+
+export type DatePickerProps = {
+	/**
+	 * The current date and time at initialization. Optionally pass in a `null`
+	 * value to specify no date is currently selected.
+	 */
+	currentDate?: Date | string | number | null;
+
+	/**
+	 * The function called when a new date has been selected. It is passed the
+	 * date as an argument.
+	 */
+	onChange?: ( date: string ) => void;
+
+	/**
+	 * A callback function which receives a Date object representing a day as an
+	 * argument, and should return a Boolean to signify if the day is valid or
+	 * not.
+	 */
+	isInvalidDate?: ( date: Date ) => boolean;
+
+	/**
+	 * A callback invoked when selecting the previous/next month in the date
+	 * picker. The callback receives the new month date in the ISO format as an
+	 * argument.
+	 */
+	onMonthPreviewed?: ( date: string ) => void;
+
+	/**
+	 * List of events to show in the date picker. Each event will appear as a
+	 * dot on the day of the event.
+	 */
+	events?: DatePickerEvent[];
+};
+
+export type DateTimePickerProps = Omit< DatePickerProps, 'onChange' > &
+	Omit< TimePickerProps, 'currentTime' | 'onChange' > & {
+		/**
+		 * The function called when a new date or time has been selected. It is
+		 * passed the date and time as an argument.
+		 */
+		onChange?: ( date: string | null ) => void;
+	};

package/src/date-time/utils.ts

@@ -0,0 +1,20 @@
+/**
+ * External dependencies
+ */
+import moment from 'moment';
+
+/**
+ * Create a Moment object from a date string. With no date supplied, default to
+ * a Moment object representing now. If a null value is passed, return a null
+ * value.
+ *
+ * @param  [date] Date representing the currently selected
+ *                date or null to signify no selection.
+ * @return Moment object for selected date or null.
+ */
+export const getMomentDate = ( date?: Date | string | number | null ) => {
+	if ( null === date ) {
+		return null;
+	}
+	return date ? moment( date ) : moment();
+};

package/src/disabled/index.js

@@ -6,7 +6,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { __experimentalUseDisabled as useDisabled } from '@wordpress/compose';
+import { useDisabled } from '@wordpress/compose';
 import { createContext } from '@wordpress/element';
 
 /**

package/src/draggable/index.native.js

@@ -0,0 +1,215 @@
+/**
+ * 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.
+ *
+ * @return {JSX.Element} The component to be rendered.
+ */
+const Draggable = ( { children, onDragEnd, onDragOver, onDragStart } ) => {
+	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 );
+
+	const providerValue = useMemo( () => {
+		return { panGestureRef, 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.
+ *
+ * @return {JSX.Element} The component to be rendered.
+ */
+const DraggableTrigger = ( {
+	children,
+	enabled = true,
+	id,
+	maxDistance = 1000,
+	minDuration = 500,
+	onLongPress,
+	onLongPressEnd,
+} ) => {
+	const { panGestureRef, isDragging, isPanActive, draggingId } = useContext(
+		Context
+	);
+
+	const gestureHandler = useAnimatedGestureHandler( {
+		onActive: () => {
+			if ( isDragging.value ) {
+				return;
+			}
+
+			isDragging.value = true;
+			draggingId.value = id;
+			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 }
+		>
+			{ children }
+		</LongPressGestureHandler>
+	);
+};
+
+export { DraggableTrigger };
+export default Draggable;

package/src/draggable/style.native.scss

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

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,
@@ -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,11 @@ export default function Dropdown( props ) {
 					expandOnMobile={ expandOnMobile }
 					headerTitle={ headerTitle }
 					focusOnMount={ focusOnMount }
+					// This value is used to ensure that the dropdowns
+					// align with the editor header by default.
+					offset={ 13 }
+					anchorRef={ ! hasAnchorRef ? containerRef : undefined }
 					{ ...popoverProps }
-					anchorRef={
-						popoverProps?.anchorRef ?? containerRef.current
-					}
 					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/focal-point-picker/index.native.js

@@ -105,7 +105,7 @@ function FocalPointPicker( props ) {
 					// coordinates to workaround a bug affecting Android's PanResponder.
 					// Specifically, dragging the handle outside the bounds of the image
 					// results in inaccurate locationX and locationY coordinates to be
-					// reported. https://git.io/JtWmi
+					// reported. https://github.com/facebook/react-native/issues/15290#issuecomment-435494944
 					const x = pageX - locationPageOffsetX;
 					const y = pageY - locationPageOffsetY;
 					onChange( {
@@ -116,7 +116,7 @@ function FocalPointPicker( props ) {
 					} );
 					// Slider (child of RangeCell) is uncontrolled, so we must increment a
 					// key to re-mount and sync the pan gesture values to the sliders
-					// https://git.io/JTe4A
+					// https://github.com/callstack/react-native-slider/tree/v3.0.3#value
 					setSliderKey( ( prevState ) => prevState + 1 );
 				},
 			} ),
@@ -193,7 +193,7 @@ function FocalPointPicker( props ) {
 		setVideoNaturalSize( { height, width } );
 		setDisplayPlaceholder( false );
 		// Avoid invisible, paused video on Android, presumably related to
-		// https://git.io/Jt6Dr
+		// https://github.com/react-native-video/react-native-video/issues/1979
 		videoRef?.current.seek( 0 );
 	};
 	const onXCoordinateChange = ( x ) =>

package/src/form-file-upload/test/index.js

@@ -14,10 +14,6 @@ import FormFileUpload from '../';
  */
 const { File } = window;
 
-const user = userEvent.setup( {
-	advanceTimers: jest.advanceTimersByTime,
-} );
-
 // @testing-library/user-event considers changing <input type="file"> to a string as a change, but it do not occur on real browsers, so the comparisons will be against this result
 const fakePath = expect.objectContaining( {
 	target: expect.objectContaining( {
@@ -45,6 +41,10 @@ describe( 'FormFileUpload', () => {
 	} );
 
 	it( 'should not fire a change event after selecting the same file', async () => {
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
+
 		const onChange = jest.fn();
 
 		render(
@@ -68,6 +68,10 @@ describe( 'FormFileUpload', () => {
 	} );
 
 	it( 'should fire a change event after selecting the same file if the value was reset in between', async () => {
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
+
 		const onChange = jest.fn();
 
 		render(