DataForm: Communicate the timezone in the datetime control

packages/dataviews/CHANGELOG.md

@@ -33,6 +33,10 @@
 
     If a combined field relied on a same-id field's `isValid` rules being applied to the group, move those rules to the child fields.
 
+### Enhancements
+
+-   DataForm: Communicate the timezone a `datetime` value is edited in. When the site timezone differs from the visitor's, the control renders help text under the input naming the site timezone: the zone name (e.g. `(CEST) Europe/Madrid`) or the UTC offset for sites pinned to one ([#82291](https://github.com/WordPress/gutenberg/pull/82291)).
+
 ### Internal
 
 -   Remove unused dependency `@wordpress/primitives` ([#82103](https://github.com/WordPress/gutenberg/pull/82103)).

packages/dataviews/src/components/dataform-controls/datetime.tsx

@@ -12,6 +12,7 @@ import toCalendarDate from './utils/to-calendar-date';
 import useDisabledDateMatchers from './utils/use-disabled-date-matchers';
 import getCustomValidity from './utils/get-custom-validity';
 import getCalendarLocale from './utils/get-calendar-locale';
+import getTimezoneDescription from './utils/get-timezone-description';
 import parseDateTime from '../../field-types/utils/parse-date-time';
 
 const formatDateTime = ( value?: string ): string => {
@@ -179,6 +180,7 @@ function CalendarDateTimeControl< Item >( {
 					value={ formatDateTime( value ) }
 					onValueChange={ handleManualDateTimeChange }
 					disabled={ disabled }
+					description={ getTimezoneDescription() }
 					min={
 						minConstraint
 							? formatDateTime( minConstraint )

packages/dataviews/src/components/dataform-controls/test/datetime.jsdom.test.tsx

@@ -290,4 +290,91 @@ describe( 'DateTime control', () => {
 			} )
 		).toBeInTheDocument();
 	} );
+
+	describe( 'timezone help', () => {
+		it( 'is not rendered when the site and browser timezones match', () => {
+			render(
+				<DateTimeHarness initialValue="2026-08-15T12:30:00.000Z" />
+			);
+
+			expect(
+				screen.getByLabelText( 'Date time' )
+			).not.toHaveAccessibleDescription();
+		} );
+
+		it( 'names the timezone for a site with a named timezone', () => {
+			setSettings( {
+				...originalSettings,
+				timezone: {
+					offset: -6,
+					offsetFormatted: '-6',
+					string: 'America/Costa_Rica',
+					abbr: 'CST',
+				},
+			} );
+
+			render(
+				<DateTimeHarness initialValue="2026-08-15T12:30:00.000Z" />
+			);
+
+			// Underscores in the zone name are replaced for display.
+			expect(
+				screen.getByLabelText( 'Date time' )
+			).toHaveAccessibleDescription(
+				'Timezone: (CST) America/Costa Rica'
+			);
+		} );
+
+		// The manual offset reaches Calendar as a raw offset identifier,
+		// which Node 20 rejects — see `supportsOffsetTimeZones`.
+		describeWithOffsetTimeZones( 'on a site with a manual offset', () => {
+			it( 'falls back to the UTC offset', () => {
+				setSiteOffset( 14 );
+
+				render(
+					<DateTimeHarness initialValue="2026-08-15T12:30:00.000Z" />
+				);
+
+				expect(
+					screen.getByLabelText( 'Date time' )
+				).toHaveAccessibleDescription( 'Timezone: UTC+14' );
+			} );
+		} );
+
+		it( 'spells out a UTC site timezone for a non-UTC visitor', () => {
+			setSettings( {
+				...originalSettings,
+				timezone: {
+					offset: 0,
+					offsetFormatted: '0',
+					string: 'UTC',
+					abbr: 'UTC',
+				},
+			} );
+			// Jest pins the browser to UTC, so this mismatch is created from
+			// the browser side: UTC+1, i.e. an offset of -60 minutes.
+			const offsetSpy = jest
+				.spyOn( Date.prototype, 'getTimezoneOffset' )
+				.mockReturnValue( -60 );
+
+			try {
+				render(
+					<DateTime
+						data={ { published: '2026-08-15T12:30:00.000Z' } }
+						field={ field }
+						onChange={ noop }
+						config={ { compact: true } }
+					/>
+				);
+
+				expect(
+					screen.getByLabelText( 'Date time' )
+				).toHaveAccessibleDescription(
+					'Timezone: Coordinated Universal Time'
+				);
+			} finally {
+				offsetSpy.mockRestore();
+			}
+		} );
+	} );
 } );

packages/dataviews/src/components/dataform-controls/utils/get-timezone-description.ts

@@ -0,0 +1,41 @@
+import { getSettings } from '@wordpress/date';
+import { __, sprintf } from '@wordpress/i18n';
+
+/**
+ * Help text communicating the timezone a datetime value is edited in.
+ * Returns `undefined` when the site timezone matches the visitor's, where
+ * spelling out the frame would be noise.
+ */
+export default function getTimezoneDescription(): string | undefined {
+	const { timezone } = getSettings();
+
+	const userTimezoneOffset = -1 * ( new Date().getTimezoneOffset() / 60 );
+	// Compare as numbers because the site offset comes over as a string.
+	if ( Number( timezone.offset ) === userTimezoneOffset ) {
+		return undefined;
+	}
+
+	const offsetSymbol = Number( timezone.offset ) >= 0 ? '+' : '';
+	const zoneAbbr =
+		'' !== timezone.abbr && isNaN( Number( timezone.abbr ) )
+			? timezone.abbr
+			: `UTC${ offsetSymbol }${ timezone.offsetFormatted }`;
+
+	// Replace underscores with spaces in strings like `America/Costa_Rica`.
+	// A site set to a manual UTC offset has no zone name, and is described by
+	// the offset alone.
+	const prettyTimezoneString = timezone.string.replaceAll( '_', ' ' );
+
+	let timezoneDetail = zoneAbbr;
+	if ( 'UTC' === timezone.string ) {
+		timezoneDetail = __( 'Coordinated Universal Time' );
+	} else if ( prettyTimezoneString.trim().length > 0 ) {
+		timezoneDetail = `(${ zoneAbbr }) ${ prettyTimezoneString }`;
+	}
+
+	return sprintf(
+		/* translators: %s: timezone detail, e.g. "(CEST) Europe/Madrid" or "UTC+3". */
+		__( 'Timezone: %s' ),
+		timezoneDetail
+	);
+}