@wordpress/components 30.9.1-next.8b30e05b0.0 → 31.0.1-next.738bb1424.0

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

@@ -58,17 +58,17 @@ describe( 'DateTimePicker', () => {
 			} )
 		).toBeVisible();
 
-		onChange.mockImplementation( ( newDate ) => {
-			rerender(
-				<DateTimePicker currentDate={ newDate } onChange={ onChange } />
-			);
-		} );
-
 		await user.click(
 			screen.getByRole( 'button', { name: 'November 20, 2025' } )
 		);
 
 		expect( onChange ).toHaveBeenCalledWith( '2025-11-20T00:00:00' );
+
+		const nextDate = onChange.mock.calls[ 0 ][ 0 ];
+		rerender(
+			<DateTimePicker currentDate={ nextDate } onChange={ onChange } />
+		);
+
 		expect(
 			screen.getByRole( 'button', {
 				name: 'November 20, 2025. Selected',
@@ -156,34 +156,251 @@ describe( 'DateTimePicker', () => {
 							} )
 						).toBeVisible();
 
-						onChange.mockImplementation( ( newDate ) => {
-							rerender(
-								<DateTimePicker
-									currentDate={ newDate }
-									onChange={ onChange }
-								/>
-							);
-						} );
-
 						await user.click(
 							screen.getByRole( 'button', { name: clickButton } )
 						);
 
+						expect( onChange ).toHaveBeenCalledWith( expectedDate );
+
+						const nextDate = onChange.mock.calls[ 0 ][ 0 ];
+						rerender(
+							<DateTimePicker
+								currentDate={ nextDate }
+								onChange={ onChange }
+							/>
+						);
+
 						expect( screen.getByLabelText( 'Day' ) ).toHaveValue(
 							expectedDay
 						);
-						expect( onChange ).toHaveBeenCalledWith( expectedDate );
 						expect(
 							screen.getByRole( 'button', {
 								name: selectedButton,
 							} )
 						).toBeVisible();
 					} );
+
+					it( 'should display event indicators correctly', () => {
+						// Test event indicators, where Date objects constructed
+						// from timezoneless strings are passed to the component
+						// and thus are interpreted in browser timezone.
+
+						timezoneMock.register( timezone );
+
+						render(
+							<DateTimePicker
+								currentDate={ initialDate }
+								events={ [ { date: new Date( initialDate ) } ] }
+							/>
+						);
+
+						expect(
+							screen.getByRole( 'button', {
+								name: `${ initialButton }. There is 1 event`,
+							} )
+						).toBeVisible();
+					} );
 				}
 			);
 		} );
 	} );
 
+	describe( 'input types with timezone variations', () => {
+		afterEach( () => {
+			jest.useRealTimers();
+			timezoneMock.unregister();
+		} );
+
+		function transformOnChangeToDate( nextValue: string ): Date {
+			// Timezoneless string represents site timezone. Convert to UTC
+			// instant in site timezone. In typical usage, consumers should
+			// align `@wordpress/date` settings to match their browser timezone
+			// when working with dates, to avoid having to manage this
+			// conversion themselves.
+			const settings = getSettings();
+			const offsetMs = settings.timezone.offset * 60 * 60 * 1000;
+			const asUTC = new Date( nextValue + 'Z' );
+			return new Date( asUTC.getTime() - offsetMs );
+		}
+
+		describe.each( [
+			{
+				direction: 'browser behind site',
+				timezone: 'US/Pacific' as const,
+			},
+			{
+				direction: 'browser matches site',
+				timezone: 'US/Eastern' as const,
+			},
+			{
+				direction: 'browser ahead of site',
+				timezone: 'Australia/Adelaide' as const,
+			},
+		] )( '$direction', ( { timezone } ) => {
+			// Input types should be treated assuming the timezone offset configured
+			// through `@wordpress/date` settings, i.e. the site's timezone. Inputs
+			// representing the same site timezone time should display and output
+			// identically. The site timezone in these tests is UTC-5 (set in
+			// beforeAll), where 20:00 site time = 01:00 UTC the next day.
+			describe.each( [
+				{
+					type: 'timezoneless string',
+					initialDate: '2025-11-15T20:00:00',
+					transformOnChange: ( nextValue: string ) => nextValue,
+				},
+				{
+					type: 'string with timezone',
+					initialDate: '2025-11-16T01:00:00Z',
+					transformOnChange: ( nextValue: string ) =>
+						transformOnChangeToDate( nextValue ).toISOString(),
+				},
+				{
+					type: 'Date object',
+					initialDate: new Date( Date.UTC( 2025, 10, 16, 1, 0, 0 ) ),
+					transformOnChange: transformOnChangeToDate,
+				},
+				{
+					type: 'timestamp',
+					initialDate: Date.UTC( 2025, 10, 16, 1, 0, 0 ),
+					transformOnChange: ( nextValue: string ) =>
+						transformOnChangeToDate( nextValue ).getTime(),
+				},
+				{
+					type: 'undefined',
+					initialDate: undefined,
+					transformOnChange: ( nextValue: string ) => nextValue,
+				},
+			] )( 'with $type', ( { initialDate, transformOnChange } ) => {
+				it( 'should display and select dates according to site timezone', async () => {
+					timezoneMock.register( timezone );
+
+					// Normalize "current" time to the same time, so we can
+					// assert the same behavior between undefined or explicitly
+					// set initial dates.
+					let user: ReturnType< typeof userEvent.setup >;
+					if ( initialDate === undefined ) {
+						jest.useFakeTimers();
+						jest.setSystemTime( Date.UTC( 2025, 10, 16, 1, 0, 0 ) );
+						user = userEvent.setup( {
+							advanceTimers: jest.advanceTimersByTime,
+						} );
+					} else {
+						user = userEvent.setup();
+					}
+
+					const onChange = jest.fn();
+					const { rerender } = render(
+						<DateTimePicker
+							currentDate={ initialDate }
+							onChange={ onChange }
+						/>
+					);
+
+					// Should display the correct initial date and time assuming
+					// settings for the current site. If incorrectly using UTC,
+					// this would show Nov 16 at 01:00 instead of Nov 15 at 20:00.
+					//
+					// When initialDate is undefined, the fake time is set to
+					// Nov 16 01:00 UTC (Nov 15 20:00 site time), in which case the
+					// current date of Nov 15 is both "Selected" and "Today".
+					expect(
+						screen.getByRole( 'button', {
+							name:
+								initialDate === undefined
+									? 'November 15, 2025. Selected. Today'
+									: 'November 15, 2025. Selected',
+						} )
+					).toBeVisible();
+					expect( screen.getByLabelText( 'Hours' ) ).toHaveValue(
+						20
+					);
+					expect( screen.getByLabelText( 'Minutes' ) ).toHaveValue(
+						0
+					);
+
+					await user.click(
+						screen.getByRole( 'button', {
+							name: 'November 20, 2025',
+						} )
+					);
+
+					// Changing date should preserve the time, calling onChange with
+					// a timezoneless string. The timezoneless string is assumed to
+					// represent the site timezone.
+					expect( onChange ).toHaveBeenCalledWith(
+						'2025-11-20T20:00:00'
+					);
+
+					let nextDate = onChange.mock.calls[ 0 ][ 0 ];
+					rerender(
+						<DateTimePicker
+							currentDate={ transformOnChange( nextDate ) }
+							onChange={ onChange }
+						/>
+					);
+
+					expect(
+						screen.getByRole( 'button', {
+							name: 'November 20, 2025. Selected',
+						} )
+					).toBeVisible();
+					expect( screen.getByLabelText( 'Hours' ) ).toHaveValue(
+						20
+					);
+					expect( screen.getByLabelText( 'Minutes' ) ).toHaveValue(
+						0
+					);
+
+					// Changing the time should output timezoneless string with
+					// only the updated hour, and not changing the date.
+					onChange.mockClear();
+					const hoursInput = screen.getByLabelText( 'Hours' );
+					await user.clear( hoursInput );
+					await user.type( hoursInput, '22' );
+					await user.keyboard( '{Tab}' );
+					expect( onChange ).toHaveBeenCalledWith(
+						'2025-11-20T22:00:00'
+					);
+
+					nextDate = onChange.mock.calls[ 0 ][ 0 ];
+					rerender(
+						<DateTimePicker
+							currentDate={ transformOnChange( nextDate ) }
+							onChange={ onChange }
+						/>
+					);
+
+					expect( screen.getByLabelText( 'Hours' ) ).toHaveValue(
+						22
+					);
+					expect( screen.getByLabelText( 'Minutes' ) ).toHaveValue(
+						0
+					);
+
+					// Ensure week boundaries keyboard navigation is calculated
+					// correctly in the configured timezone, not the browser's.
+					await user.click(
+						screen.getByRole( 'button', {
+							name: 'November 20, 2025. Selected',
+						} )
+					);
+					await user.keyboard( '{Home}' );
+					expect(
+						screen.getByRole( 'button', {
+							name: 'November 16, 2025',
+						} )
+					).toHaveFocus();
+					await user.keyboard( '{End}' );
+					expect(
+						screen.getByRole( 'button', {
+							name: 'November 22, 2025',
+						} )
+					).toHaveFocus();
+				} );
+			} );
+		} );
+	} );
+
 	it( 'should preserve time when changing date', async () => {
 		const user = userEvent.setup();
 		const onChange = jest.fn();

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

@@ -3,13 +3,46 @@
  */
 import timezoneMock from 'timezone-mock';
 
+/**
+ * WordPress dependencies
+ */
+import { getSettings, setSettings, type DateSettings } from '@wordpress/date';
+
 /**
  * Internal dependencies
  */
 import { inputToDate } from '../utils';
 
 describe( 'inputToDate', () => {
-	describe( 'timezoneless strings parsed as UTC', () => {
+	let originalSettings: DateSettings;
+
+	beforeAll( () => {
+		originalSettings = getSettings();
+	} );
+
+	afterEach( () => {
+		timezoneMock.unregister();
+	} );
+
+	afterAll( () => {
+		setSettings( originalSettings );
+	} );
+
+	describe( 'timezoneless strings', () => {
+		beforeEach( () => {
+			// Default settings are UTC, but make it explicit so these tests
+			// don't depend on global settings state.
+			setSettings( {
+				...originalSettings,
+				timezone: {
+					offset: 0,
+					offsetFormatted: '0',
+					string: '',
+					abbr: '',
+				},
+			} );
+		} );
+
 		describe.each( [
 			{
 				timezone: 'US/Pacific' as const,
@@ -28,10 +61,6 @@ describe( 'inputToDate', () => {
 				timezoneMock.register( timezone );
 			} );
 
-			afterEach( () => {
-				timezoneMock.unregister();
-			} );
-
 			it( 'should parse midnight as UTC midnight, preventing day shifts', () => {
 				const result = inputToDate( '2025-11-01T00:00:00' );
 
@@ -68,6 +97,55 @@ describe( 'inputToDate', () => {
 		} );
 	} );
 
+	describe( 'timezoneless strings with a site timezone string (DST-aware)', () => {
+		beforeEach( () => {
+			setSettings( {
+				...originalSettings,
+				timezone: {
+					offset: -5,
+					offsetFormatted: '-5',
+					string: 'America/New_York',
+					abbr: 'EST',
+				},
+			} );
+		} );
+
+		describe.each( [
+			{
+				timezone: 'US/Pacific' as const,
+				description: 'Pacific time (behind UTC)',
+			},
+			{
+				timezone: 'UTC' as const,
+				description: 'UTC (zero offset)',
+			},
+			{
+				timezone: 'Australia/Adelaide' as const,
+				description: 'Adelaide (ahead of UTC)',
+			},
+		] )( 'in $description', ( { timezone } ) => {
+			beforeEach( () => {
+				timezoneMock.register( timezone );
+			} );
+
+			it( 'should interpret midnight using site timezone (winter)', () => {
+				// Jan 10 is Eastern Standard Time in New York (UTC-5)
+				const result = inputToDate( '2025-01-10T00:00:00' );
+				expect( result.toISOString() ).toBe(
+					'2025-01-10T05:00:00.000Z'
+				);
+			} );
+
+			it( 'should interpret midnight using site timezone (summer/DST)', () => {
+				// Mar 10 is Eastern Daylight Time in New York (UTC-4)
+				const result = inputToDate( '2025-03-10T00:00:00' );
+				expect( result.toISOString() ).toBe(
+					'2025-03-10T04:00:00.000Z'
+				);
+			} );
+		} );
+	} );
+
 	describe( 'strings with timezone indicators', () => {
 		describe.each( [
 			{
@@ -106,23 +184,44 @@ describe( 'inputToDate', () => {
 		} );
 	} );
 
-	describe( 'non-string inputs', () => {
-		it( 'should handle Date objects', () => {
-			const input = new Date( '2025-11-01T00:00:00Z' );
+	describe( 'Date objects', () => {
+		it( 'should extract the UTC timestamp, not local time components', () => {
+			// Mock Pacific timezone where local time differs from UTC.
+			// This ensures the test fails on trunk if we incorrectly preserve
+			// local components instead of extracting the UTC timestamp.
+			timezoneMock.register( 'US/Pacific' );
+
+			// Create Nov 1, 2025 at 15:30:45 UTC
+			const timestamp = Date.UTC( 2025, 10, 1, 15, 30, 45 );
+			const input = new Date( timestamp );
 			const result = inputToDate( input );
 
+			// Should preserve the exact UTC moment (15:30:45), not the local
+			// Pacific time components (7:30:45 or 8:30:45 depending on DST).
 			expect( result.getUTCFullYear() ).toBe( 2025 );
-			expect( result.getUTCMonth() ).toBe( 10 );
+			expect( result.getUTCMonth() ).toBe( 10 ); // November
 			expect( result.getUTCDate() ).toBe( 1 );
+			expect( result.getUTCHours() ).toBe( 15 ); // UTC hour, not 7 or 8
+			expect( result.getUTCMinutes() ).toBe( 30 );
+			expect( result.getUTCSeconds() ).toBe( 45 );
 		} );
+	} );
+
+	describe( 'timestamps', () => {
+		it( 'should preserve the UTC moment exactly', () => {
+			// Ensure we're using a different timezone from UTC (the tests use
+			// UTC by default).
+			timezoneMock.register( 'US/Pacific' );
 
-		it( 'should convert timestamps to Date', () => {
-			const timestamp = Date.UTC( 2025, 10, 1, 0, 0, 0 );
+			const timestamp = Date.UTC( 2025, 10, 1, 15, 30, 45 );
 			const result = inputToDate( timestamp );
 
 			expect( result.getUTCFullYear() ).toBe( 2025 );
-			expect( result.getUTCMonth() ).toBe( 10 );
+			expect( result.getUTCMonth() ).toBe( 10 ); // November
 			expect( result.getUTCDate() ).toBe( 1 );
+			expect( result.getUTCHours() ).toBe( 15 );
+			expect( result.getUTCMinutes() ).toBe( 30 );
+			expect( result.getUTCSeconds() ).toBe( 45 );
 		} );
 	} );
 } );

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

@@ -1,13 +1,14 @@
 /**
  * External dependencies
  */
-import { startOfMinute, format, set, setMonth } from 'date-fns';
+import { startOfMinute } from 'date-fns';
 
 /**
  * WordPress dependencies
  */
 import { useState, useMemo, useEffect } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
+import { date as formatDate } from '@wordpress/date';
 
 /**
  * Internal dependencies
@@ -31,6 +32,7 @@ import {
 	inputToDate,
 	buildPadInputStateReducer,
 	validateInputElementTarget,
+	setInConfiguredTimezone,
 } from '../utils';
 import { TIMEZONELESS_FORMAT } from '../constants';
 import { TimeInput } from './time-input';
@@ -66,17 +68,13 @@ export function TimePicker( {
 }: TimePickerProps ) {
 	const [ date, setDate ] = useState( () =>
 		// Truncate the date at the minutes, see: #15495.
-		currentTime ? startOfMinute( inputToDate( currentTime ) ) : new Date()
+		startOfMinute( inputToDate( currentTime ?? new Date() ) )
 	);
 
 	// Reset the state when currentTime changed.
 	// TODO: useEffect() shouldn't be used like this, causes an unnecessary render
 	useEffect( () => {
-		setDate(
-			currentTime
-				? startOfMinute( inputToDate( currentTime ) )
-				: new Date()
-		);
+		setDate( startOfMinute( inputToDate( currentTime ?? new Date() ) ) );
 	}, [ currentTime ] );
 
 	const monthOptions = [
@@ -96,15 +94,14 @@ export function TimePicker( {
 
 	const { day, month, year, minutes, hours } = useMemo(
 		() => ( {
-			day: format( date, 'dd' ),
-			month: format(
-				date,
-				'MM'
+			day: formatDate( 'd', date ),
+			month: formatDate(
+				'm',
+				date
 			) as ( typeof monthOptions )[ number ][ 'value' ],
-			year: format( date, 'yyyy' ),
-			minutes: format( date, 'mm' ),
-			hours: format( date, 'HH' ),
-			am: format( date, 'a' ),
+			year: formatDate( 'Y', date ),
+			minutes: formatDate( 'i', date ),
+			hours: formatDate( 'H', date ),
 		} ),
 		[ date ]
 	);
@@ -118,9 +115,13 @@ export function TimePicker( {
 			// We can safely assume value is a number if target is valid.
 			const numberValue = Number( value );
 
-			const newDate = set( date, { [ method ]: numberValue } );
+			// Internal date is UTC-normalized, but the field should be updated
+			// as if in the configured timezone.
+			const newDate = setInConfiguredTimezone( date, {
+				[ method ]: numberValue,
+			} );
 			setDate( newDate );
-			onChange?.( format( newDate, TIMEZONELESS_FORMAT ) );
+			onChange?.( formatDate( TIMEZONELESS_FORMAT, newDate ) );
 		};
 		return callback;
 	};
@@ -129,12 +130,14 @@ export function TimePicker( {
 		hours: newHours,
 		minutes: newMinutes,
 	}: TimeInputValue ) => {
-		const newDate = set( date, {
+		// Internal date is UTC-normalized, but the field should be updated
+		// as if in the configured timezone.
+		const newDate = setInConfiguredTimezone( date, {
 			hours: newHours,
 			minutes: newMinutes,
 		} );
 		setDate( newDate );
-		onChange?.( format( newDate, TIMEZONELESS_FORMAT ) );
+		onChange?.( formatDate( TIMEZONELESS_FORMAT, newDate ) );
 	};
 
 	const dayField = (
@@ -164,13 +167,16 @@ export function TimePicker( {
 				label={ __( 'Month' ) }
 				hideLabelFromVision
 				__next40pxDefaultSize
-				__nextHasNoMarginBottom
 				value={ month }
 				options={ monthOptions }
 				onChange={ ( value ) => {
-					const newDate = setMonth( date, Number( value ) - 1 );
+					// Internal date is UTC-normalized, but the field should be updated
+					// as if in the configured timezone.
+					const newDate = setInConfiguredTimezone( date, {
+						month: Number( value ) - 1,
+					} );
 					setDate( newDate );
-					onChange?.( format( newDate, TIMEZONELESS_FORMAT ) );
+					onChange?.( formatDate( TIMEZONELESS_FORMAT, newDate ) );
 				} }
 			/>
 		</MonthSelectWrapper>