@automattic/charts 3.2.0 → 4.1.0

package/src/utils/date-parsing.ts

@@ -1,49 +1,26 @@
 /**
- * @file Date parsing utilities using date-fns for local timezone handling
+ * @file Date parsing: a naive string is dated in a supplied IANA zone, or the runtime's own
  *
- * This module provides utilities for parsing various date string formats and converting
- * them to local timezone dates using the battle-tested date-fns library. For formats
- * without timezone info, they're treated as local. For formats with timezone info,
- * they're converted to the equivalent local time.
+ * A string carrying an offset is already an instant and parses the same everywhere. A string
+ * without one is only a wall-clock reading, so it means nothing until a zone is named. See
+ * `parseAsLocalDate` for the supported formats.
  *
- * Note: And specifically it prevents format `YYYY-MM-DD` being parsed as UTC date.
- *
- * Key Features:
- * - All parsed dates are in local timezone
- * - Converts timezone-aware strings to local equivalent
- * - Robust input validation and error handling using date-fns
- * - TypeScript type safety
- * - Much smaller codebase than custom parsing
- *
- * Supported Formats:
- * - YYYY-MM-DD (treated as local)
- * - YYYY-MM-DD HH:mm:ss (treated as local)
- * - YYYY-MM-DD HH:mm (treated as local)
- * - YYYY-MM-DDTHH:mm:ss (treated as local)
- * - YYYY-MM-DDTHH:mm:ss.SSS (treated as local)
- * - YYYY-MM-DDTHH:mm (treated as local)
- * - YYYY-MM-DDTHH:mm:ssZ (converted to local)
- * - YYYY-MM-DDTHH:mm:ss±HH:mm (converted to local)
- *
- * @example
- * ```typescript
- * parseAsLocalDate("2025-01-01");                     // Local timezone
- * parseAsLocalDate("2025-01-01 14:30:00");            // Local timezone
- * parseAsLocalDate("2025-01-01 14:30");               // Local timezone
- * parseAsLocalDate("2025-01-01T14:30:45.123");        // Local timezone
- * parseAsLocalDate("2025-01-01T14:30:00Z");           // UTC 14:30 → Local equivalent
- * parseAsLocalDate("2025-01-01T14:30:00+05:00");      // +05:00 14:30 → Local equivalent
- * ```
+ * Note: this specifically avoids date-fns's default of parsing `YYYY-MM-DD` as a UTC date.
  */
 
+import { tzOffset } from '@date-fns/tz';
 import { parse, parseISO, isValid } from 'date-fns';
+import { warnOnce } from './warn-once';
 
 /**
  * Checks if a date string contains timezone information
+ *
+ * The minutes are optional because ISO 8601 allows a bare `±hh`, which `parseISO` reads.
+ *
  * @param {string} dateString - The date string to check for timezone information
  * @return {boolean} True if the date string contains timezone information, false otherwise
  */
-const hasTimezone = ( dateString: string ): boolean => {
+export const hasTimezone = ( dateString: string ): boolean => {
 	const tIndex = dateString.indexOf( 'T' );
 	if ( tIndex === -1 ) {
 		return false;
@@ -53,29 +30,93 @@ const hasTimezone = ( dateString: string ): boolean => {
 		return true;
 	}
 
-	return /[+-]\d{2}:?\d{2}$/.test( dateString.slice( tIndex + 1 ) );
+	return /[+-]\d{2}(?::?\d{2})?$/.test( dateString.slice( tIndex + 1 ) );
+};
+
+// The wall clock, read off the string rather than back out of the parsed `Date`: date-fns
+// builds that with local setters, so a runtime zone whose own DST gap swallows the reading
+// hands back fields an hour out. Covers every naive shape in `formats` below, at the one to
+// N digits date-fns reads each field as; it takes a short fraction literally, so `.5` is 5ms.
+const NAIVE =
+	/^(\d{1,4})-(\d{1,2})-(\d{1,2})(?:[T ](\d{1,2}):(\d{1,2})(?::(\d{1,2})(?:\.(\d{1,3}))?)?)?$/;
+
+// `Date.UTC` reads a year below 100 as 1900 + year, which would silently re-date the first
+// century. `setUTCFullYear` has no such mapping.
+const asUtcMs = ( [ , ...fields ]: RegExpExecArray ): number => {
+	const [ year, month, day, hour, minute, second, ms ] = fields.map( field =>
+		Number( field ?? 0 )
+	);
+	const date = new Date( 0 );
+	date.setUTCFullYear( year, month - 1, day );
+	date.setUTCHours( hour, minute, second, ms );
+	return date.getTime();
+};
+
+/**
+ * The instant a wall-clock reading names in a given zone.
+ *
+ * A reading a spring-forward gap deleted moves forward past the gap, and one a fall-back
+ * repeated resolves to a single instant. Neither is configurable: see CHARTS-268.
+ *
+ * @param wallClock - The reading, as the milliseconds it would be if it were UTC.
+ * @param timeZone  - IANA zone the reading is dated in.
+ * @return The instant, or `null` where `timeZone` is not a zone Intl accepts.
+ */
+const wallClockToInstant = ( wallClock: number, timeZone: string ): Date | null => {
+	// `tzOffset` answers NaN for a zone Intl cannot use. Falling back to the runtime's zone
+	// keeps the contract that this never throws, but it silently reinstates the very defect
+	// the argument exists to fix, so say so where a developer can see it.
+	const first = tzOffset( timeZone, new Date( wallClock ) );
+
+	if ( Number.isNaN( first ) ) {
+		warnOnce(
+			`parse:timeZone:${ timeZone }`,
+			`timeZone ${ JSON.stringify(
+				timeZone
+			) } is not a zone Intl accepts, so dates are read in the browser's zone. Pass an IANA name or a UTC offset such as "+05:30".`
+		);
+		return null;
+	}
+
+	// The offset depends on the instant, so the first answer is only a guess: a DST
+	// transition between the two moves it. Re-reading the offset at the guess settles
+	// every reading the zone actually has.
+	const guess = wallClock - first * 60000;
+	const second = tzOffset( timeZone, new Date( guess ) );
+
+	if ( first === second ) {
+		return new Date( guess );
+	}
+
+	const corrected = wallClock - second * 60000;
+	const third = tzOffset( timeZone, new Date( corrected ) );
+
+	if ( second === third ) {
+		return new Date( corrected );
+	}
+
+	// The smaller offset moves the reading forward past the gap, so a day bucket in a zone
+	// that springs forward at midnight keeps its own calendar day.
+	return new Date( wallClock - Math.min( second, third ) * 60000 );
 };
 
 /**
- * Parses any supported date string format and returns a local timezone date
+ * Parses any supported date string format into an instant, dated in `timeZone` or the runtime's own
  *
- * Uses date-fns for robust parsing and validation. For strings without timezone
- * info, treats as local timezone. For strings with timezone info, converts to
- * local timezone equivalent.
+ * Uses date-fns for robust parsing and validation. A string carrying timezone info
+ * is already an instant and is returned as one, whatever `timeZone` says. A string
+ * without it is a wall-clock reading, dated in `timeZone` when one is supplied and
+ * in the runtime's own zone when none is.
  *
- * Supports:
- * - YYYY-MM-DD (local)
- * - YYYY-MM-DD HH:mm:ss (local)
- * - YYYY-MM-DD HH:mm (local)
- * - YYYY-MM-DDTHH:mm:ss (local)
- * - YYYY-MM-DDTHH:mm:ss.SSS (local)
- * - YYYY-MM-DDTHH:mm (local)
- * - YYYY-MM-DDTHH:mm:ssZ (UTC → local)
- * - YYYY-MM-DDTHH:mm:ss±HH:mm (offset → local)
- * @param {string} dateString - The date string to parse into a local timezone date
- * @return {Date} A Date object representing the parsed date in local timezone, or an invalid Date if parsing fails
+ * A wall clock a DST gap deleted is moved forward past the gap; one a fall-back repeated
+ * resolves to a single instant. Neither policy is selectable. A zone `Intl` rejects falls
+ * back to the runtime's own, and warns once outside production.
+ *
+ * @param {string} dateString - The date string to parse into a date
+ * @param {string} [timeZone] - IANA zone a naive string is read in; the runtime's own when absent, and ignored by a string that carries its own offset
+ * @return {Date} A Date object representing the parsed instant, or an invalid Date if parsing fails
  */
-export const parseAsLocalDate = ( dateString: string ): Date => {
+export const parseAsLocalDate = ( dateString: string, timeZone?: string ): Date => {
 	const trimmedString = dateString.trim();
 
 	// If it has timezone information, parse as ISO and convert to local
@@ -101,10 +142,20 @@ export const parseAsLocalDate = ( dateString: string ): Date => {
 	];
 
 	for ( const format of formats ) {
+		// date-fns still decides whether the string is a date at all, calendar rules included;
+		// only the fields it read are untrustworthy, and only when a zone was named.
 		const result = parse( trimmedString, format, new Date() );
-		if ( isValid( result ) ) {
+		if ( ! isValid( result ) ) {
+			continue;
+		}
+
+		if ( ! timeZone ) {
 			return result;
 		}
+
+		const fields = NAIVE.exec( trimmedString );
+
+		return ( fields && wallClockToInstant( asUtcMs( fields ), timeZone ) ) ?? result;
 	}
 
 	// If no format matched, return invalid date

package/src/utils/get-edge-tick-widths.ts

@@ -0,0 +1,33 @@
+import { getStringWidth } from '@visx/text';
+import type { TickFormatter } from '@visx/axis';
+import type { AnyD3Scale, ScaleInput } from '@visx/scale';
+
+/**
+ * Rendered widths of the first and last tick labels on an axis.
+ *
+ * An unmeasurable label reserves nothing, which is what a width of 0 already
+ * means to every caller, so it is reported as 0 rather than as its own case.
+ *
+ * @param          ticks      - Tick values, in axis order.
+ * @param          formatTick - Function to format a tick.
+ * @param {object} labelStyle - Style object for the label.
+ * @return {object} - Widths in pixels.
+ */
+export const getEdgeTickWidths = < T extends AnyD3Scale >(
+	ticks: ScaleInput< T >[],
+	formatTick?: TickFormatter< ScaleInput< T > >,
+	labelStyle?: object
+): { first: number; last: number } => {
+	if ( ! ticks.length ) {
+		return { first: 0, last: 0 };
+	}
+
+	const lastIndex = ticks.length - 1;
+	const label = ( tick: ScaleInput< T >, index: number ) =>
+		String( formatTick ? formatTick( tick, index, [] ) ?? '' : tick );
+
+	return {
+		first: getStringWidth( label( ticks[ 0 ], 0 ), labelStyle ) ?? 0,
+		last: getStringWidth( label( ticks[ lastIndex ], lastIndex ), labelStyle ) ?? 0,
+	};
+};

package/src/utils/index.ts

@@ -1,6 +1,9 @@
 // Chart composition utilities
 export { attachSubComponents } from './create-composition';
 
+// Date bucket classification
+export { getBucketInfo } from './bucket-info';
+
 // Date parsing utilities
 export { parseAsLocalDate } from './date-parsing';
 
@@ -10,6 +13,7 @@ export type { MetricValueType } from './format-metric-value';
 export { formatPercentage } from './format-percentage';
 
 // Chart measurement utilities
+export { getEdgeTickWidths } from './get-edge-tick-widths';
 export { getLongestTickWidth } from './get-longest-tick-width';
 
 // Style and theming utilities

package/src/utils/test/bucket-info.test.ts

@@ -0,0 +1,185 @@
+import { getBucketInfo, getBucketResolution } from '../bucket-info';
+import type { SeriesData } from '../../types';
+
+const at = ( hoursFromStart: number ) =>
+	new Date( Date.UTC( 2026, 7, 1 ) + hoursFromStart * 60 * 60 * 1000 );
+
+const seriesOf = ( offsetsInHours: number[] ): SeriesData[] => [
+	{
+		label: 'views',
+		data: offsetsInHours.map( ( offset, index ) => ( { date: at( offset ), value: index } ) ),
+	},
+];
+
+const seriesSpacedHours = ( hours: number, count: number ): SeriesData[] =>
+	seriesOf( Array.from( { length: count }, ( _, index ) => index * hours ) );
+
+const pad = ( value: number ) => String( value ).padStart( 2, '0' );
+
+// Built from local components so it round-trips through `parseAsLocalDate`,
+// which reads a `dateString` as wall-clock time in the runtime's own zone.
+const seriesOfStrings = ( offsetsInHours: number[] ): SeriesData[] => [
+	{
+		label: 'views',
+		data: offsetsInHours.map( ( offset, index ) => {
+			const date = at( offset );
+			return {
+				dateString: `${ date.getFullYear() }-${ pad( date.getMonth() + 1 ) }-${ pad(
+					date.getDate()
+				) }T${ pad( date.getHours() ) }:${ pad( date.getMinutes() ) }:00`,
+				value: index,
+			};
+		} ),
+	},
+];
+
+const stringSeriesSpacedHours = ( hours: number, count: number ): SeriesData[] =>
+	seriesOfStrings( Array.from( { length: count }, ( _, index ) => index * hours ) );
+
+const hourlyDates = ( start: Date, hours: number ): Date[] =>
+	Array.from( { length: hours }, ( _, i ) => new Date( start.getTime() + i * 60 * 60 * 1000 ) );
+
+const dailyDates = ( start: Date, days: number ): Date[] =>
+	Array.from( { length: days }, ( _, i ) => new Date( start.getTime() + i * 24 * 60 * 60 * 1000 ) );
+
+const toSeries = ( dates: Date[] ): SeriesData[] => [
+	{
+		label: 'series',
+		data: dates.map( date => ( { date, value: 1 } ) ),
+	},
+];
+
+describe( 'getBucketInfo', () => {
+	it( 'preserves a declared week in bucket and collapses it for display', () => {
+		const data = seriesSpacedHours( 24 * 7, 6 );
+
+		expect( getBucketInfo( data, 'week' ) ).toEqual( {
+			bucket: 'week',
+			displayResolution: 'day',
+		} );
+	} );
+
+	it( 'passes a declared resolution through unchanged otherwise', () => {
+		const data = seriesSpacedHours( 1, 6 );
+
+		expect( getBucketInfo( data, 'hour' ) ).toEqual( {
+			bucket: 'hour',
+			displayResolution: 'hour',
+		} );
+	} );
+
+	it( 'infers from spacing when nothing is declared', () => {
+		expect( getBucketInfo( seriesSpacedHours( 1, 6 ) ) ).toEqual( {
+			bucket: 'hour',
+			displayResolution: 'hour',
+		} );
+		expect( getBucketInfo( seriesSpacedHours( 24, 6 ) ) ).toEqual( {
+			bucket: 'day',
+			displayResolution: 'day',
+		} );
+	} );
+
+	it( 'infers from dateString points, which the chart parses before it draws them', () => {
+		expect( getBucketInfo( stringSeriesSpacedHours( 1, 6 ) ) ).toEqual( {
+			bucket: 'hour',
+			displayResolution: 'hour',
+		} );
+		expect( getBucketInfo( stringSeriesSpacedHours( 24, 6 ) ) ).toEqual( {
+			bucket: 'day',
+			displayResolution: 'day',
+		} );
+	} );
+
+	it( 'reads a series the same whichever date field carries it', () => {
+		const offsets = [ 0, 1, 2, 3 ];
+
+		expect( getBucketInfo( seriesOfStrings( offsets ) ) ).toEqual(
+			getBucketInfo( seriesOf( offsets ) )
+		);
+	} );
+
+	it( 'never infers week, only reports it when declared', () => {
+		expect( getBucketInfo( seriesSpacedHours( 24 * 7, 6 ) ).bucket ).toBe( 'day' );
+	} );
+
+	it( 'reads the same bucket whatever order the points arrive in', () => {
+		const offsets = [ 0, 24, 48 ];
+		const shuffled = [ 0, 48, 24 ];
+
+		expect( getBucketInfo( seriesOf( shuffled ) ) ).toEqual( getBucketInfo( seriesOf( offsets ) ) );
+		expect( getBucketInfo( seriesOf( shuffled ) ).bucket ).toBe( 'day' );
+	} );
+
+	it( 'ignores a repeated instant, which pads a series rather than dating it', () => {
+		// A shorter comparison series can repeat its last date to match length.
+		expect( getBucketInfo( seriesOf( [ 0, 24, 48, 48 ] ) ).bucket ).toBe( 'day' );
+	} );
+} );
+
+describe( 'getBucketResolution', () => {
+	it( 'infers hourly buckets from sub-daily spacing', () => {
+		expect(
+			getBucketResolution( toSeries( hourlyDates( new Date( '2026-08-02T00:00:00' ), 6 ) ) )
+		).toBe( 'hour' );
+	} );
+
+	it( 'infers daily buckets from daily spacing', () => {
+		expect(
+			getBucketResolution( toSeries( dailyDates( new Date( '2026-08-01T00:00:00' ), 5 ) ) )
+		).toBe( 'day' );
+	} );
+
+	it( 'infers daily buckets from weekly spacing, which labels the same way', () => {
+		const weeklyDates = Array.from(
+			{ length: 5 },
+			( _, i ) => new Date( Date.UTC( 2026, 0, 5 + i * 7 ) )
+		);
+
+		expect( getBucketResolution( toSeries( weeklyDates ) ) ).toBe( 'day' );
+	} );
+
+	it( 'infers monthly buckets from a shortest-month gap', () => {
+		expect(
+			getBucketResolution(
+				toSeries( [ new Date( '2026-02-01T00:00:00' ), new Date( '2026-03-01T00:00:00' ) ] )
+			)
+		).toBe( 'month' );
+	} );
+
+	it( 'infers yearly buckets from a yearly gap', () => {
+		expect(
+			getBucketResolution(
+				toSeries( [ new Date( '2025-06-01T00:00:00' ), new Date( '2026-06-01T00:00:00' ) ] )
+			)
+		).toBe( 'year' );
+	} );
+
+	it( 'keeps a daily gap across spring-forward out of the hourly bucket', () => {
+		const start = new Date( '2026-03-08T00:00:00' );
+		const dstDates = [ 0, 23, 47 ].map(
+			offsetHours => new Date( start.getTime() + offsetHours * 60 * 60 * 1000 )
+		);
+
+		expect( getBucketResolution( toSeries( dstDates ) ) ).toBe( 'day' );
+	} );
+
+	it( 'reports daily buckets when no series has two points', () => {
+		// Unmeasurable spacing reads as Infinity, which must not be mistaken for a
+		// very coarse bucket.
+		expect( getBucketResolution( toSeries( [ new Date( '2026-08-02T00:00:00' ) ] ) ) ).toBe(
+			'day'
+		);
+	} );
+
+	it( 'reports a declared resolution over the measured spacing', () => {
+		const hourly = toSeries( hourlyDates( new Date( '2026-08-02T00:00:00' ), 6 ) );
+
+		expect( getBucketResolution( hourly, 'month' ) ).toBe( 'month' );
+	} );
+
+	it( 'reports a declared weekly resolution as daily', () => {
+		// Weeks and days are both calendar-date buckets as far as labelling goes,
+		// and 'week' is not a label format of its own.
+		expect( getBucketResolution( toSeries( [] ), 'week' ) ).toBe( 'day' );
+	} );
+} );

package/src/utils/test/color-utils.test.ts

@@ -7,7 +7,6 @@ import {
 	hexToRgba,
 	validateHexColor,
 	parseHslString,
-	parseRgbString,
 	normalizeColorToHex,
 	relativeLuminance,
 	prefersLightText,
@@ -547,7 +546,7 @@ describe( 'lightenHexColor', () => {
 			expect( result ).toBe( '#8080ff' );
 		} );
 
-		it( 'lightens a theme color by 80%', () => {
+		it( 'lightens a color by 80%', () => {
 			const result = lightenHexColor( '#98C8DF', 0.8 );
 			// R: 152 + (255-152)*0.8 = 152 + 82.4 = 234
 			// G: 200 + (255-200)*0.8 = 200 + 44 = 244
@@ -668,52 +667,6 @@ describe( 'parseHslString', () => {
 	} );
 } );
 
-describe( 'parseRgbString', () => {
-	describe( 'Valid RGB strings', () => {
-		it( 'parses rgb(255, 0, 0) to #ff0000', () => {
-			expect( parseRgbString( 'rgb(255, 0, 0)' ) ).toBe( '#ff0000' );
-		} );
-
-		it( 'parses rgb(0, 255, 0) to #00ff00', () => {
-			expect( parseRgbString( 'rgb(0, 255, 0)' ) ).toBe( '#00ff00' );
-		} );
-
-		it( 'parses rgb(0, 0, 255) to #0000ff', () => {
-			expect( parseRgbString( 'rgb(0, 0, 255)' ) ).toBe( '#0000ff' );
-		} );
-
-		it( 'parses rgb with no spaces', () => {
-			expect( parseRgbString( 'rgb(128,128,128)' ) ).toBe( '#808080' );
-		} );
-
-		it( 'clamps values above 255', () => {
-			expect( parseRgbString( 'rgb(300, 0, 0)' ) ).toBe( '#ff0000' );
-		} );
-
-		it( 'clamps negative values to 0', () => {
-			expect( parseRgbString( 'rgb(-50, 0, 0)' ) ).toBe( '#000000' );
-		} );
-	} );
-
-	describe( 'Invalid RGB strings', () => {
-		it( 'returns null for hsl strings', () => {
-			expect( parseRgbString( 'hsl(0, 100%, 50%)' ) ).toBeNull();
-		} );
-
-		it( 'returns null for hex colors', () => {
-			expect( parseRgbString( '#ff0000' ) ).toBeNull();
-		} );
-
-		it( 'returns null for rgba strings', () => {
-			expect( parseRgbString( 'rgba(255, 0, 0, 1)' ) ).toBeNull();
-		} );
-
-		it( 'returns null for empty string', () => {
-			expect( parseRgbString( '' ) ).toBeNull();
-		} );
-	} );
-} );
-
 describe( 'normalizeColorToHex', () => {
 	describe( 'Hex colors', () => {
 		it( 'returns valid 6-digit hex as-is', () => {

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

@@ -0,0 +1,89 @@
+import { createDateFormatter, createZonedClock, sanitizeFormatting } from '../date-formatting';
+
+// `@wordpress/jest-console` registers the matcher but ships no types for it.
+declare global {
+	// eslint-disable-next-line @typescript-eslint/no-namespace
+	namespace jest {
+		interface Matchers< R > {
+			toHaveWarned(): R;
+		}
+	}
+}
+
+describe( 'createDateFormatter', () => {
+	it( 'renders an invalid date rather than throwing', () => {
+		const format = createDateFormatter(
+			{ month: 'short', day: 'numeric' },
+			{ locale: 'de-DE', timeZone: 'Asia/Tokyo' }
+		);
+
+		expect( format( NaN ) ).toBe( 'Invalid Date' );
+		expect( format( new Date( 'nope' ) ) ).toBe( 'Invalid Date' );
+	} );
+} );
+
+describe( 'createZonedClock', () => {
+	it( 'reads calendar fields in the supplied zone', () => {
+		// 00:30 on Aug 3 in Tokyo.
+		expect( createZonedClock( 'Asia/Tokyo' )( new Date( '2026-08-02T15:30:00Z' ) ) ).toEqual( {
+			month: 8,
+			hour: 0,
+		} );
+	} );
+
+	it.each( [
+		[ 'with a zone', 'Asia/Tokyo' ],
+		[ 'without one', undefined ],
+	] )( 'answers NaN for an invalid date %s', ( _label, timeZone ) => {
+		expect( createZonedClock( timeZone )( new Date( 'nope' ) ) ).toEqual( {
+			month: NaN,
+			hour: NaN,
+		} );
+	} );
+} );
+
+describe( 'sanitizeFormatting', () => {
+	it( 'keeps a usable locale and zone', () => {
+		const formatting = { locale: 'de-DE', timeZone: 'Asia/Tokyo' };
+
+		expect( sanitizeFormatting( formatting ) ).toEqual( formatting );
+	} );
+
+	it( 'keeps a UTC offset, which a WordPress site may store instead of a zone name', () => {
+		expect( sanitizeFormatting( { timeZone: '+05:30' } ) ).toEqual( {
+			locale: undefined,
+			timeZone: '+05:30',
+		} );
+	} );
+
+	it( 'repairs the underscored locale WordPress reports', () => {
+		expect( sanitizeFormatting( { locale: 'en_US', timeZone: 'Asia/Tokyo' } ) ).toEqual( {
+			locale: 'en-US',
+			timeZone: 'Asia/Tokyo',
+		} );
+	} );
+
+	it( 'drops a locale no underscore swap can rescue, keeping the zone', () => {
+		expect( sanitizeFormatting( { locale: 'nope!', timeZone: 'Asia/Tokyo' } ) ).toEqual( {
+			locale: undefined,
+			timeZone: 'Asia/Tokyo',
+		} );
+		expect( console ).toHaveWarned();
+	} );
+
+	it( 'drops the empty zone a site set to a manual offset reports, keeping the locale', () => {
+		expect( sanitizeFormatting( { locale: 'de-DE', timeZone: '' } ) ).toEqual( {
+			locale: 'de-DE',
+			timeZone: undefined,
+		} );
+		expect( console ).toHaveWarned();
+	} );
+
+	it( 'drops both when neither is usable', () => {
+		expect( sanitizeFormatting( { locale: '', timeZone: 'Mars/Olympus' } ) ).toEqual( {
+			locale: undefined,
+			timeZone: undefined,
+		} );
+		expect( console ).toHaveWarned();
+	} );
+} );

package/src/utils/test/date-parsing.auckland.test.ts

@@ -0,0 +1,6 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-auckland.mjs
+ */
+import { describeZonedParsing } from '../../test-utils/zoned-parsing-suite';
+
+describeZonedParsing();

package/src/utils/test/date-parsing.santiago.test.ts

@@ -0,0 +1,6 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-santiago.mjs
+ */
+import { describeZonedParsing } from '../../test-utils/zoned-parsing-suite';
+
+describeZonedParsing();

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

@@ -6,6 +6,7 @@
  *
  */
 
+import { describeZonedParsing } from '../../test-utils/zoned-parsing-suite';
 import { parseAsLocalDate } from '../date-parsing';
 
 describe( 'parseAsLocalDate', () => {
@@ -173,6 +174,16 @@ describe( 'parseAsLocalDate', () => {
 			expect( isNaN( result.getTime() ) ).toBe( false );
 		} );
 
+		test( 'should read an hour-only offset as the instant it names', () => {
+			// ISO 8601 allows a bare `±hh`, and it must not be read as a naive wall clock.
+			expect( parseAsLocalDate( '2025-01-15T14:30:45+05', 'Asia/Tokyo' ).toISOString() ).toBe(
+				parseAsLocalDate( '2025-01-15T14:30:45+05:00', 'Asia/Tokyo' ).toISOString()
+			);
+			expect( parseAsLocalDate( '2025-01-15T14:30:45+05' ).toISOString() ).toBe(
+				'2025-01-15T09:30:45.000Z'
+			);
+		} );
+
 		test( 'should handle UTC with milliseconds', () => {
 			const result = parseAsLocalDate( '2025-01-15T14:30:45.123Z' );
 
@@ -304,7 +315,7 @@ describe( 'parseAsLocalDate', () => {
 			];
 
 			const startTime = performance.now();
-			const results = testDates.map( parseAsLocalDate );
+			const results = testDates.map( dateString => parseAsLocalDate( dateString ) );
 			const endTime = performance.now();
 
 			// Should complete quickly (this is more of a smoke test)
@@ -316,3 +327,7 @@ describe( 'parseAsLocalDate', () => {
 		} );
 	} );
 } );
+
+// The test script pins TZ=UTC, so this run is a second viewer zone for the same
+// table `date-parsing.auckland.test.ts` asserts.
+describeZonedParsing();