@wordpress/components 19.10.0 → 19.11.0

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

@@ -3,10 +3,17 @@
  */
 import moment from 'moment';
 import classnames from 'classnames';
-
-// react-dates doesn't tree-shake correctly, so we import from the individual
-// component here, to avoid including too much of the library
-import DayPickerSingleDateController from 'react-dates/lib/components/DayPickerSingleDateController';
+import type { Moment } from 'moment';
+import { noop } from 'lodash';
+
+// `react-dates` doesn't tree-shake correctly, so we import from the individual
+// component here.
+// @ts-expect-error TypeScript won't find any type declarations at
+// `react-dates/lib/components/DayPickerSingleDateController` as they're located
+// at `react-dates`.
+import UntypedDayPickerSingleDateController from 'react-dates/lib/components/DayPickerSingleDateController';
+import type { DayPickerSingleDateController } from 'react-dates';
+const TypedDayPickerSingleDateController = UntypedDayPickerSingleDateController as DayPickerSingleDateController;
 
 /**
  * WordPress dependencies
@@ -18,15 +25,13 @@ import { isRTL, _n, sprintf } from '@wordpress/i18n';
  * Internal dependencies
  */
 import { getMomentDate } from './utils';
+import type { DatePickerDayProps, DatePickerProps } from './types';
 
-/**
- * Module Constants
- */
 const TIMEZONELESS_FORMAT = 'YYYY-MM-DDTHH:mm:ss';
 const ARIAL_LABEL_TIME_FORMAT = 'dddd, LL';
 
-function DatePickerDay( { day, events = [] } ) {
-	const ref = useRef();
+function DatePickerDay( { day, events = [] }: DatePickerDayProps ) {
+	const ref = useRef< HTMLDivElement >( null );
 
 	/*
 	 * a11y hack to make the `There is/are n events` string
@@ -36,7 +41,7 @@ function DatePickerDay( { day, events = [] } ) {
 	 */
 	useEffect( () => {
 		// Bail when no parent node.
-		if ( ! ref?.current?.parentNode ) {
+		if ( ! ( ref?.current?.parentNode instanceof Element ) ) {
 			return;
 		}
 
@@ -75,15 +80,34 @@ function DatePickerDay( { day, events = [] } ) {
 	);
 }
 
-function DatePicker( {
+/**
+ * DatePicker is a React component that renders a calendar for date selection.
+ *
+ * ```jsx
+ * import { DatePicker } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyDatePicker = () => {
+ *   const [ date, setDate ] = useState( new Date() );
+ *
+ *   return (
+ *     <DatePicker
+ *       currentDate={ date }
+ *       onChange={ ( newDate ) => setDate( newDate ) }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function DatePicker( {
 	currentDate,
 	onChange,
 	events,
 	isInvalidDate,
 	onMonthPreviewed,
-} ) {
-	const nodeRef = useRef();
-	const onMonthPreviewedHandler = ( newMonthDate ) => {
+}: DatePickerProps ) {
+	const nodeRef = useRef< HTMLDivElement >( null );
+	const onMonthPreviewedHandler = ( newMonthDate: Moment ) => {
 		onMonthPreviewed?.( newMonthDate.toISOString() );
 		keepFocusInside();
 	};
@@ -111,7 +135,7 @@ function DatePicker( {
 			const focusRegion = nodeRef.current.querySelector(
 				'.DayPicker_focusRegion'
 			);
-			if ( ! focusRegion ) {
+			if ( ! ( focusRegion instanceof HTMLElement ) ) {
 				return;
 			}
 			// Keep the focus on focus region.
@@ -119,7 +143,11 @@ function DatePicker( {
 		}
 	};
 
-	const onChangeMoment = ( newDate ) => {
+	const onChangeMoment = ( newDate: Moment | null ) => {
+		if ( ! newDate ) {
+			return;
+		}
+
 		// If currentDate is null, use now as momentTime to designate hours, minutes, seconds.
 		const momentDate = currentDate ? moment( currentDate ) : moment();
 		const momentTime = {
@@ -128,13 +156,13 @@ function DatePicker( {
 			seconds: 0,
 		};
 
-		onChange( newDate.set( momentTime ).format( TIMEZONELESS_FORMAT ) );
+		onChange?.( newDate.set( momentTime ).format( TIMEZONELESS_FORMAT ) );
 
 		// Keep focus on the date picker.
 		keepFocusInside();
 	};
 
-	const getEventsPerDay = ( day ) => {
+	const getEventsPerDay = ( day: Moment ) => {
 		if ( ! events?.length ) {
 			return [];
 		}
@@ -148,7 +176,7 @@ function DatePicker( {
 
 	return (
 		<div className="components-datetime__date" ref={ nodeRef }>
-			<DayPickerSingleDateController
+			<TypedDayPickerSingleDateController
 				date={ momentDate }
 				daySize={ 30 }
 				focused
@@ -166,7 +194,7 @@ function DatePicker( {
 				dayAriaLabelFormat={ ARIAL_LABEL_TIME_FORMAT }
 				isRTL={ isRTL() }
 				isOutsideRange={ ( date ) => {
-					return isInvalidDate && isInvalidDate( date.toDate() );
+					return !! isInvalidDate && isInvalidDate( date.toDate() );
 				} }
 				onPrevMonthClick={ onMonthPreviewedHandler }
 				onNextMonthClick={ onMonthPreviewedHandler }
@@ -176,6 +204,7 @@ function DatePicker( {
 						events={ getEventsPerDay( day ) }
 					/>
 				) }
+				onFocusChange={ noop }
 			/>
 		</div>
 	);

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

@@ -5,6 +5,7 @@
 // See: https://github.com/airbnb/react-dates#initialize
 import 'react-dates/initialize';
 import { noop } from 'lodash';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -18,10 +19,11 @@ import { __, _x } from '@wordpress/i18n';
 import Button from '../button';
 import { default as DatePicker } from './date';
 import { default as TimePicker } from './time';
+import type { DateTimePickerProps } from './types';
 
 export { DatePicker, TimePicker };
 
-function DateTimePicker(
+function UnforwardedDateTimePicker(
 	{
 		currentDate,
 		is12Hour,
@@ -29,8 +31,8 @@ function DateTimePicker(
 		onMonthPreviewed = noop,
 		onChange,
 		events,
-	},
-	ref
+	}: DateTimePickerProps,
+	ref: ForwardedRef< any >
 ) {
 	const [ calendarHelpIsVisible, setCalendarHelpIsVisible ] = useState(
 		false
@@ -148,7 +150,7 @@ function DateTimePicker(
 					<Button
 						className="components-datetime__date-reset-button"
 						variant="link"
-						onClick={ () => onChange( null ) }
+						onClick={ () => onChange?.( null ) }
 					>
 						{ __( 'Reset' ) }
 					</Button>
@@ -167,4 +169,28 @@ function DateTimePicker(
 	);
 }
 
-export default forwardRef( DateTimePicker );
+/**
+ * DateTimePicker is a React component that renders a calendar and clock for
+ * date and time selection. The calendar and clock components can be accessed
+ * individually using the `DatePicker` and `TimePicker` components respectively.
+ *
+ * ```jsx
+ * import { DateTimePicker } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyDateTimePicker = () => {
+ *   const [ date, setDate ] = useState( new Date() );
+ *
+ *   return (
+ *     <DateTimePicker
+ *       currentDate={ date }
+ *       onChange={ ( newDate ) => setDate( newDate ) }
+ *       is12Hour
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export const DateTimePicker = forwardRef( UnforwardedDateTimePicker );
+
+export default DateTimePicker;

package/src/date-time/stories/date.tsx

@@ -0,0 +1,73 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState, useEffect } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import DatePicker from '../date';
+import { daysFromNow, isWeekend } from './utils';
+
+const meta: ComponentMeta< typeof DatePicker > = {
+	title: 'Components/DatePicker',
+	component: DatePicker,
+	argTypes: {
+		currentDate: { control: 'date' },
+		onChange: { action: 'onChange', control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof DatePicker > = ( {
+	currentDate,
+	onChange,
+	...args
+} ) => {
+	const [ date, setDate ] = useState( currentDate );
+	useEffect( () => {
+		setDate( currentDate );
+	}, [ currentDate ] );
+	return (
+		<DatePicker
+			{ ...args }
+			currentDate={ date }
+			onChange={ ( newDate ) => {
+				setDate( newDate );
+				onChange?.( newDate );
+			} }
+		/>
+	);
+};
+
+export const Default: ComponentStory< typeof DatePicker > = Template.bind( {} );
+
+export const WithEvents: ComponentStory< typeof DatePicker > = Template.bind(
+	{}
+);
+WithEvents.args = {
+	currentDate: new Date(),
+	events: [
+		{ date: daysFromNow( 2 ) },
+		{ date: daysFromNow( 4 ) },
+		{ date: daysFromNow( 6 ) },
+		{ date: daysFromNow( 8 ) },
+	],
+};
+
+export const WithInvalidDates: ComponentStory<
+	typeof DatePicker
+> = Template.bind( {} );
+WithInvalidDates.args = {
+	currentDate: new Date(),
+	isInvalidDate: isWeekend,
+};

package/src/date-time/stories/index.tsx

@@ -0,0 +1,75 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState, useEffect } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import DateTimePicker from '..';
+import { daysFromNow, isWeekend } from './utils';
+
+const meta: ComponentMeta< typeof DateTimePicker > = {
+	title: 'Components/DateTimePicker',
+	component: DateTimePicker,
+	argTypes: {
+		currentDate: { control: 'date' },
+		onChange: { action: 'onChange', control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof DateTimePicker > = ( {
+	currentDate,
+	onChange,
+	...args
+} ) => {
+	const [ date, setDate ] = useState( currentDate );
+	useEffect( () => {
+		setDate( currentDate );
+	}, [ currentDate ] );
+	return (
+		<DateTimePicker
+			{ ...args }
+			currentDate={ date }
+			onChange={ ( newDate ) => {
+				setDate( newDate );
+				onChange?.( newDate );
+			} }
+		/>
+	);
+};
+
+export const Default: ComponentStory< typeof DateTimePicker > = Template.bind(
+	{}
+);
+
+export const WithEvents: ComponentStory<
+	typeof DateTimePicker
+> = Template.bind( {} );
+WithEvents.args = {
+	currentDate: new Date(),
+	events: [
+		{ date: daysFromNow( 2 ) },
+		{ date: daysFromNow( 4 ) },
+		{ date: daysFromNow( 6 ) },
+		{ date: daysFromNow( 8 ) },
+	],
+};
+
+export const WithInvalidDates: ComponentStory<
+	typeof DateTimePicker
+> = Template.bind( {} );
+WithInvalidDates.args = {
+	currentDate: new Date(),
+	isInvalidDate: isWeekend,
+};

package/src/date-time/stories/time.tsx

@@ -0,0 +1,51 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState, useEffect } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import TimePicker from '../time';
+
+const meta: ComponentMeta< typeof TimePicker > = {
+	title: 'Components/TimePicker',
+	component: TimePicker,
+	argTypes: {
+		currentTime: { control: 'date' },
+		onChange: { action: 'onChange', control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof TimePicker > = ( {
+	currentTime,
+	onChange,
+	...args
+} ) => {
+	const [ time, setTime ] = useState( currentTime );
+	useEffect( () => {
+		setTime( currentTime );
+	}, [ currentTime ] );
+	return (
+		<TimePicker
+			{ ...args }
+			currentTime={ time }
+			onChange={ ( newTime ) => {
+				setTime( newTime );
+				onChange?.( newTime );
+			} }
+		/>
+	);
+};
+
+export const Default: ComponentStory< typeof TimePicker > = Template.bind( {} );

package/src/date-time/stories/utils.ts

@@ -0,0 +1,9 @@
+export function daysFromNow( days: number ) {
+	const date = new Date();
+	date.setDate( date.getDate() + days );
+	return date;
+}
+
+export function isWeekend( date: Date ) {
+	return date.getDay() === 0 || date.getDay() === 6;
+}

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

@@ -19,8 +19,9 @@ describe( 'DatePicker', () => {
 			screen.getByRole( 'button', { name: 'Monday, May 2, 2022' } )
 		).toHaveClass( 'CalendarDay__selected' );
 
-		// Expect React deprecation warning due to outdated 'react-dates' package.
-		// TODO: Update 'react-dates'.
+		// Expect React deprecation warning due to 'react-dates' using outdated
+		// React lifecycle methods.
+		// https://github.com/react-dates/react-dates/issues/1748
 		expect( console ).toHaveWarned();
 	} );
 

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

@@ -237,11 +237,21 @@ describe( 'TimePicker', () => {
 			/>
 		);
 
-		expect( screen.getByLabelText( 'Month' ).value ).toBe( '07' );
-		expect( screen.getByLabelText( 'Day' ).value ).toBe( '13' );
-		expect( screen.getByLabelText( 'Year' ).value ).toBe( '2020' );
-		expect( screen.getByLabelText( 'Hours' ).value ).toBe( '06' );
-		expect( screen.getByLabelText( 'Minutes' ).value ).toBe( '00' );
+		expect(
+			( screen.getByLabelText( 'Month' ) as HTMLInputElement ).value
+		).toBe( '07' );
+		expect(
+			( screen.getByLabelText( 'Day' ) as HTMLInputElement ).value
+		).toBe( '13' );
+		expect(
+			( screen.getByLabelText( 'Year' ) as HTMLInputElement ).value
+		).toBe( '2020' );
+		expect(
+			( screen.getByLabelText( 'Hours' ) as HTMLInputElement ).value
+		).toBe( '06' );
+		expect(
+			( screen.getByLabelText( 'Minutes' ) as HTMLInputElement ).value
+		).toBe( '00' );
 		/**
 		 * This is not ideal, but best of we can do for now until we refactor
 		 * AM/PM into accessible elements, like radio buttons.
@@ -267,14 +277,12 @@ describe( 'TimePicker', () => {
 			</form>
 		);
 
-		const form = screen.getByRole( 'form' );
+		const form = screen.getByRole( 'form' ) as HTMLFormElement;
 
-		let monthInputIndex = [].indexOf.call(
-			form.elements,
+		let monthInputIndex = Array.from( form.elements ).indexOf(
 			screen.getByLabelText( 'Month' )
 		);
-		let dayInputIndex = [].indexOf.call(
-			form.elements,
+		let dayInputIndex = Array.from( form.elements ).indexOf(
 			screen.getByLabelText( 'Day' )
 		);
 
@@ -290,12 +298,10 @@ describe( 'TimePicker', () => {
 			</form>
 		);
 
-		monthInputIndex = [].indexOf.call(
-			form.elements,
+		monthInputIndex = Array.from( form.elements ).indexOf(
 			screen.getByLabelText( 'Month' )
 		);
-		dayInputIndex = [].indexOf.call(
-			form.elements,
+		dayInputIndex = Array.from( form.elements ).indexOf(
 			screen.getByLabelText( 'Day' )
 		);
 
@@ -313,11 +319,20 @@ describe( 'TimePicker', () => {
 			/>
 		);
 
-		const monthInput = screen.getByLabelText( 'Month' ).value;
-		const dayInput = screen.getByLabelText( 'Day' ).value;
-		const yearInput = screen.getByLabelText( 'Year' ).value;
-		const hoursInput = screen.getByLabelText( 'Hours' ).value;
-		const minutesInput = screen.getByLabelText( 'Minutes' ).value;
+		const monthInput = ( screen.getByLabelText(
+			'Month'
+		) as HTMLInputElement ).value;
+		const dayInput = ( screen.getByLabelText( 'Day' ) as HTMLInputElement )
+			.value;
+		const yearInput = ( screen.getByLabelText(
+			'Year'
+		) as HTMLInputElement ).value;
+		const hoursInput = ( screen.getByLabelText(
+			'Hours'
+		) as HTMLInputElement ).value;
+		const minutesInput = ( screen.getByLabelText(
+			'Minutes'
+		) as HTMLInputElement ).value;
 
 		expect( Number.isNaN( parseInt( monthInput, 10 ) ) ).toBe( false );
 		expect( Number.isNaN( parseInt( dayInput, 10 ) ) ).toBe( false );

package/src/date-time/test/{utils.js → utils.ts}

@@ -14,7 +14,7 @@ describe( 'getMomentDate', () => {
 		const momentDate = getMomentDate( currentDate );
 
 		expect( moment.isMoment( momentDate ) ).toBe( true );
-		expect( momentDate.isSame( moment( currentDate ) ) ).toBe( true );
+		expect( momentDate?.isSame( moment( currentDate ) ) ).toBe( true );
 	} );
 
 	it( 'should return null when given a null argument', () => {