@wordpress/components 19.10.0 → 19.13.0

package/src/date-time/README.md

@@ -26,6 +26,8 @@ const MyDateTimePicker = () => {
 			currentDate={ date }
 			onChange={ ( newDate ) => setDate( newDate ) }
 			is12Hour={ true }
+			__nextRemoveHelpButton
+			__nextRemoveResetButton
 		/>
 	);
 };
@@ -35,22 +37,20 @@ const MyDateTimePicker = () => {
 
 The component accepts the following props:
 
-### currentDate
+### `currentDate`: `Date | string | number | null`
 
 The current date and time at initialization. Optionally pass in a `null` value to specify no date is currently selected.
 
--   Type: `string`
 -   Required: No
 -   Default: today's date
 
-### onChange
+### `onChange`: `( date: string | null ) => void`
 
 The function called when a new date or time has been selected. It is passed the `currentDate` as an argument.
 
--   Type: `Function`
--   Required: Yes
+-   Required: No
 
-### is12Hour
+### `is12Hour`: `boolean`
 
 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`).
 
@@ -58,16 +58,35 @@ Whether we use a 12-hour clock. With a 12-hour clock, an AM/PM widget is display
 -   Required: No
 -   Default: false
 
-### isInvalidDate
+### `isInvalidDate`: `( date: Date ) => boolean`
 
 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.
 
--   Type: `Function`
 -   Required: No
 
-### onMonthPreviewed
+### `onMonthPreviewed`: `( date: Date ) => void`
 
 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.
 
--   Type: `Function`
 -   Required: No
+
+### `events`: `{ date: Date }[]`
+
+List of events to show in the date picker. Each event will appear as a dot on the day of the event.
+
+-   Type: `Array`
+-   Required: No
+
+### `__nextRemoveHelpButton`: `boolean`
+
+Start opting in to not displaying a Help button which will become the default in a future version.
+
+- Required: No
+- Default: `false`
+
+### `__nextRemoveResetButton`: `boolean`
+
+Start opting in to not displaying a Reset button which will become the default in a future version.
+
+- Required: No
+- Default: `false`

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

@@ -2,10 +2,12 @@
  * External dependencies
  */
 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 type { Moment } from 'moment';
+// Needed to initialise the default datepicker styles.
+// See: https://github.com/airbnb/react-dates#initialize
+import 'react-dates/initialize';
+// `react-dates` doesn't tree-shake correctly, so we import from the individual
+// component here.
 import DayPickerSingleDateController from 'react-dates/lib/components/DayPickerSingleDateController';
 
 /**
@@ -13,20 +15,21 @@ import DayPickerSingleDateController from 'react-dates/lib/components/DayPickerS
  */
 import { useEffect, useRef } from '@wordpress/element';
 import { isRTL, _n, sprintf } from '@wordpress/i18n';
+import { arrowLeft, arrowRight } from '@wordpress/icons';
 
 /**
  * Internal dependencies
  */
 import { getMomentDate } from './utils';
+import type { DatePickerDayProps, DatePickerProps } from '../types';
+import { Day, NavPrevButton, NavNextButton } from './styles';
 
-/**
- * Module Constants
- */
 const TIMEZONELESS_FORMAT = 'YYYY-MM-DDTHH:mm:ss';
 const ARIAL_LABEL_TIME_FORMAT = 'dddd, LL';
+const noop = () => {};
 
-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 +39,7 @@ function DatePickerDay( { day, events = [] } ) {
 	 */
 	useEffect( () => {
 		// Bail when no parent node.
-		if ( ! ref?.current?.parentNode ) {
+		if ( ! ( ref?.current?.parentNode instanceof Element ) ) {
 			return;
 		}
 
@@ -61,29 +64,49 @@ function DatePickerDay( { day, events = [] } ) {
 		);
 
 		parentNode.setAttribute( 'aria-label', dayWithEventsDescription );
-	}, [ events.length ] );
+	}, [ day, events.length ] );
 
 	return (
-		<div
+		<Day
 			ref={ ref }
-			className={ classnames( 'components-datetime__date__day', {
-				'has-events': events?.length,
-			} ) }
+			className="components-datetime__date__day" // Unused, for backwards compatibility.
+			hasEvents={ !! events?.length }
+			alignment="center"
 		>
 			{ day.format( 'D' ) }
-		</div>
+		</Day>
 	);
 }
 
-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 +134,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 +142,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 +155,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 [];
 		}
@@ -150,7 +177,9 @@ function DatePicker( {
 		<div className="components-datetime__date" ref={ nodeRef }>
 			<DayPickerSingleDateController
 				date={ momentDate }
+				initialVisibleMonth={ null }
 				daySize={ 30 }
+				horizontalMonthPadding={ 0 }
 				focused
 				hideKeyboardShortcutsPanel
 				// This is a hack to force the calendar to update on month or year change
@@ -166,7 +195,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 +205,29 @@ function DatePicker( {
 						events={ getEventsPerDay( day ) }
 					/>
 				) }
+				renderMonthElement={ ( { month } ) => (
+					<>
+						<strong>{ month.format( 'MMMM' ) }</strong>{ ' ' }
+						{ month.format( 'YYYY' ) }
+					</>
+				) }
+				renderNavPrevButton={ ( { ariaLabel, ...props } ) => (
+					<NavPrevButton
+						icon={ arrowLeft }
+						variant="tertiary"
+						aria-label={ ariaLabel }
+						{ ...props }
+					/>
+				) }
+				renderNavNextButton={ ( { ariaLabel, ...props } ) => (
+					<NavNextButton
+						icon={ arrowRight }
+						variant="tertiary"
+						aria-label={ ariaLabel }
+						{ ...props }
+					/>
+				) }
+				onFocusChange={ noop }
 			/>
 		</div>
 	);

package/src/date-time/date/style.scss

@@ -0,0 +1,85 @@
+@import "./datepicker.scss";
+
+// Styles that overrides the calendar styling provided by react-dates go here.
+// Everything else goes in styles.ts.
+
+.components-datetime__date {
+	//
+	// Margin overrides
+	//
+
+	// Remove the left and right margin from the calendar by setting all the
+	// containers' widths to 100%. This means that the slide left / slide right
+	// animation won't work but we don't want that, anyway.
+
+	.CalendarMonthGrid__horizontal,
+	.DayPicker_weekHeader_li {
+		transform: none !important; // Override inline style.
+		width: 100% !important; // Override inline style.
+	}
+
+	.CalendarMonthGrid_month__horizontal,
+	.CalendarMonth_table,
+	.DayPicker_weekHeader {
+		width: 100%;
+	}
+
+	.DayPicker_weekHeaders__horizontal {
+		margin: 0;
+	}
+
+	.DayPicker_weekHeader_ul {
+		display: flex;
+	}
+
+	//
+	// Theming
+	//
+
+	.DayPicker_weekHeader {
+		top: 50px;
+	}
+
+	.CalendarMonth_caption {
+		font-size: $default-font-size;
+	}
+
+	.CalendarMonth_table {
+		border-collapse: separate;
+		border-spacing: 2px;
+	}
+
+	.CalendarDay {
+		border: none;
+		font-size: $default-font-size;
+		border-radius: $radius-round;
+		background: $white;
+
+		&:hover {
+			color: var(--wp-admin-theme-color);
+		}
+
+		&:focus {
+			box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color), inset 0 0 0 #{ $border-width-focus + $border-width } $white;
+			outline: 2px solid transparent; // Shown in Windows 10 high contrast mode.
+		}
+	}
+
+	.CalendarDay__today {
+		background: $gray-100;
+	}
+
+	.CalendarDay__selected {
+		background: var(--wp-admin-theme-color);
+		border: 2px solid transparent; // This indicates selection in Windows 10 high contrast mode.
+
+		&:hover {
+			background: var(--wp-admin-theme-color-darker-20);
+			color: $white;
+		}
+
+		&:focus {
+			box-shadow: inset 0 0 0 $border-width $white;
+		}
+	}
+}

package/src/date-time/date/styles.ts

@@ -0,0 +1,55 @@
+/**
+ * External dependencies
+ */
+import styled from '@emotion/styled';
+import { css } from '@emotion/react';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../button';
+import { COLORS } from '../../utils';
+import { VStack } from '../../v-stack';
+
+// Styles that overrides the calendar styling provided by react-dates go in
+// style.scss. Everything else goes here.
+
+export const Day = styled( VStack )< { hasEvents: boolean } >`
+	height: 100%;
+	position: relative;
+
+	${ ( props ) =>
+		props.hasEvents &&
+		`
+		::before {
+			background: var(--wp-admin-theme-color);
+			border-radius: 2px;
+			bottom: 0;
+			content: " ";
+			height: 4px;
+			left: 50%;
+			margin-left: -2px;
+			position: absolute;
+			width: 4px;
+
+			.CalendarDay__selected & {
+				background: ${ COLORS.white };
+			}
+		}
+		` }
+`;
+
+const baseNavButton = css`
+	position: absolute;
+	top: 15px;
+`;
+
+export const NavPrevButton = styled( Button )`
+	${ baseNavButton }
+	left: 0;
+`;
+
+export const NavNextButton = styled( Button )`
+	${ baseNavButton }
+	right: 0;
+`;

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

@@ -9,7 +9,7 @@ import 'react-dates/initialize';
 /**
  * Internal dependencies
  */
-import DatePicker from '../date';
+import DatePicker from '..';
 
 describe( 'DatePicker', () => {
 	it( 'should highlight the current date', () => {
@@ -19,15 +19,16 @@ 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();
 	} );
 
 	it( "should highlight today's date when not provided a currentDate", () => {
 		render( <DatePicker /> );
 
-		const todayDescription = moment().format( 'dddd, MMM D, YYYY' );
+		const todayDescription = moment().format( 'dddd, MMMM D, YYYY' );
 		expect(
 			screen.getByRole( 'button', { name: todayDescription } )
 		).toHaveClass( 'CalendarDay__selected' );

package/src/date-time/{test/utils.js → date/test/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', () => {

package/src/date-time/date/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/date-time/date-time/index.tsx

@@ -0,0 +1,215 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState, forwardRef } from '@wordpress/element';
+import { __, _x } from '@wordpress/i18n';
+import deprecated from '@wordpress/deprecated';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../button';
+import { default as DatePicker } from '../date';
+import { default as TimePicker } from '../time';
+import type { DateTimePickerProps } from '../types';
+import { CalendarHelp } from './styles';
+import { HStack } from '../../h-stack';
+import { Heading } from '../../heading';
+import { Spacer } from '../../spacer';
+
+export { DatePicker, TimePicker };
+
+const noop = () => {};
+
+function UnforwardedDateTimePicker(
+	{
+		currentDate,
+		is12Hour,
+		isInvalidDate,
+		onMonthPreviewed = noop,
+		onChange,
+		events,
+		__nextRemoveHelpButton = false,
+		__nextRemoveResetButton = false,
+	}: DateTimePickerProps,
+	ref: ForwardedRef< any >
+) {
+	if ( ! __nextRemoveHelpButton ) {
+		deprecated( 'Help button in wp.components.DateTimePicker', {
+			since: '13.4',
+			version: '14.6', // Six months of plugin releases.
+			hint: 'Set the `__nextRemoveHelpButton` prop to `true` to remove this warning and opt in to the new behaviour, which will become the default in a future version.',
+		} );
+	}
+	if ( ! __nextRemoveResetButton ) {
+		deprecated( 'Reset button in wp.components.DateTimePicker', {
+			since: '13.4',
+			version: '14.6', // Six months of plugin releases.
+			hint: 'Set the `__nextRemoveResetButton` prop to `true` to remove this warning and opt in to the new behaviour, which will become the default in a future version.',
+		} );
+	}
+
+	const [ calendarHelpIsVisible, setCalendarHelpIsVisible ] =
+		useState( false );
+
+	function onClickDescriptionToggle() {
+		setCalendarHelpIsVisible( ! calendarHelpIsVisible );
+	}
+
+	return (
+		<div ref={ ref } className="components-datetime">
+			{ ! calendarHelpIsVisible && (
+				<>
+					<TimePicker
+						currentTime={ currentDate }
+						onChange={ onChange }
+						is12Hour={ is12Hour }
+					/>
+					<DatePicker
+						currentDate={ currentDate }
+						onChange={ onChange }
+						isInvalidDate={ isInvalidDate }
+						events={ events }
+						onMonthPreviewed={ onMonthPreviewed }
+					/>
+				</>
+			) }
+			{ calendarHelpIsVisible && (
+				<CalendarHelp
+					className="components-datetime__calendar-help" // Unused, for backwards compatibility.
+				>
+					<Heading level={ 4 }>{ __( 'Click to Select' ) }</Heading>
+					<ul>
+						<li>
+							{ __(
+								'Click the right or left arrows to select other months in the past or the future.'
+							) }
+						</li>
+						<li>{ __( 'Click the desired day to select it.' ) }</li>
+					</ul>
+					<Heading level={ 4 }>
+						{ __( 'Navigating with a keyboard' ) }
+					</Heading>
+					<ul>
+						<li>
+							<abbr
+								aria-label={ _x( 'Enter', 'keyboard button' ) }
+							>
+								↵
+							</abbr>
+							{
+								' ' /* JSX removes whitespace, but a space is required for screen readers. */
+							}
+							<span>{ __( 'Select the date in focus.' ) }</span>
+						</li>
+						<li>
+							<abbr aria-label={ __( 'Left and Right Arrows' ) }>
+								←/→
+							</abbr>
+							{
+								' ' /* JSX removes whitespace, but a space is required for screen readers. */
+							}
+							{ __(
+								'Move backward (left) or forward (right) by one day.'
+							) }
+						</li>
+						<li>
+							<abbr aria-label={ __( 'Up and Down Arrows' ) }>
+								↑/↓
+							</abbr>
+							{
+								' ' /* JSX removes whitespace, but a space is required for screen readers. */
+							}
+							{ __(
+								'Move backward (up) or forward (down) by one week.'
+							) }
+						</li>
+						<li>
+							<abbr aria-label={ __( 'Page Up and Page Down' ) }>
+								{ __( 'PgUp/PgDn' ) }
+							</abbr>
+							{
+								' ' /* JSX removes whitespace, but a space is required for screen readers. */
+							}
+							{ __(
+								'Move backward (PgUp) or forward (PgDn) by one month.'
+							) }
+						</li>
+						<li>
+							<abbr aria-label={ __( 'Home and End' ) }>
+								{ /* Translators: Home/End reffer to the 'Home' and 'End' buttons on the keyboard.*/ }
+								{ __( 'Home/End' ) }
+							</abbr>
+							{
+								' ' /* JSX removes whitespace, but a space is required for screen readers. */
+							}
+							{ __(
+								'Go to the first (Home) or last (End) day of a week.'
+							) }
+						</li>
+					</ul>
+				</CalendarHelp>
+			) }
+			{ ( ! __nextRemoveResetButton || ! __nextRemoveHelpButton ) && (
+				<HStack
+					className="components-datetime__buttons" // Unused, for backwards compatibility.
+				>
+					{ ! __nextRemoveResetButton &&
+						! calendarHelpIsVisible &&
+						currentDate && (
+							<Button
+								className="components-datetime__date-reset-button" // Unused, for backwards compatibility.
+								variant="link"
+								onClick={ () => onChange?.( null ) }
+							>
+								{ __( 'Reset' ) }
+							</Button>
+						) }
+					<Spacer />
+					{ ! __nextRemoveHelpButton && (
+						<Button
+							className="components-datetime__date-help-toggle" // Unused, for backwards compatibility.
+							variant="link"
+							onClick={ onClickDescriptionToggle }
+						>
+							{ calendarHelpIsVisible
+								? __( 'Close' )
+								: __( 'Calendar Help' ) }
+						</Button>
+					) }
+				</HStack>
+			) }
+		</div>
+	);
+}
+
+/**
+ * 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/date-time/styles.ts

@@ -0,0 +1,8 @@
+/**
+ * External dependencies
+ */
+import styled from '@emotion/styled';
+
+export const CalendarHelp = styled.div`
+	min-width: 260px;
+`;