@automattic/charts 4.0.0 → 4.1.1

package/src/test-utils/zoned-parsing-suite.ts

@@ -0,0 +1,90 @@
+import { parseAsLocalDate } from '../utils/date-parsing';
+
+// `@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 > {
+			toHaveWarnedWith( ...args: unknown[] ): R;
+		}
+	}
+}
+
+// Every case asserts an absolute instant, so running the suite from more than one
+// worker zone is what proves the result does not depend on the viewer's.
+const CASES: Array< [ string, string, string ] > = [
+	// The shape the Stats payload gives for a day bucket.
+	[ '2026-08-02', 'Asia/Tokyo', '2026-08-01T15:00:00.000Z' ],
+	[ '2026-08-02 09:30:00', 'Asia/Tokyo', '2026-08-02T00:30:00.000Z' ],
+	[ '2026-08-02T09:30:00', 'Asia/Tokyo', '2026-08-02T00:30:00.000Z' ],
+	// Santiago springs forward at midnight, deleting this reading entirely.
+	[ '2026-09-06', 'America/Santiago', '2026-09-06T04:00:00.000Z' ],
+	// Berlin's gap runs the other way, its offset growing rather than shrinking, which is
+	// the shape most of Europe and North America has. Only this case tells the smaller of
+	// the two candidate offsets apart from the later probe.
+	[ '2026-03-29 02:30:00', 'Europe/Berlin', '2026-03-29T01:30:00.000Z' ],
+	// And Santiago falls back at midnight, so this reading happens twice.
+	[ '2026-04-04 23:00:00', 'America/Santiago', '2026-04-05T02:00:00.000Z' ],
+	// Which of the two an overlap resolves to follows the sign of the offset, so a zone
+	// east of UTC settles on the other one. Auckland is where this PR's own stories sit.
+	[ '2026-04-05 02:30:00', 'Pacific/Auckland', '2026-04-04T14:30:00.000Z' ],
+	// Hours past a fall-back, where the first offset probe lands on the wrong side
+	// of the transition and only the second one is right.
+	[ '2026-11-01 08:00:00', 'America/Los_Angeles', '2026-11-01T16:00:00.000Z' ],
+	// Nothing about this reading is remarkable in Tokyo; it is the worker zones that make it
+	// worth asserting, since Santiago deletes this local midnight and used to drag the
+	// answer an hour with it.
+	[ '2026-09-06', 'Asia/Tokyo', '2026-09-05T15:00:00.000Z' ],
+	// date-fns reads each field as one to N digits, so an unpadded string must land on the
+	// same instant as its padded twin. A one-digit fraction is 5ms to date-fns, not 500.
+	[ '2026-8-2', 'Asia/Tokyo', '2026-08-01T15:00:00.000Z' ],
+	[ '2026-08-02 9:30', 'Asia/Tokyo', '2026-08-02T00:30:00.000Z' ],
+	[ '2026-08-02T9:30:5.5', 'Asia/Tokyo', '2026-08-02T00:30:05.005Z' ],
+];
+
+// A string carrying its own offset is already an instant, so the zone must not move it.
+const INSTANT_CASES: Array< [ string, string ] > = [
+	[ '2026-08-02T00:00:00Z', '2026-08-02T00:00:00.000Z' ],
+	[ '2026-08-02T00:00:00+05:00', '2026-08-01T19:00:00.000Z' ],
+];
+
+/**
+ * The zone-aware half of `parseAsLocalDate`, run from whatever zone the caller's
+ * environment pins.
+ */
+export const describeZonedParsing = () => {
+	describe( 'parseAsLocalDate with a time zone', () => {
+		test.each( CASES )( 'reads %s in %s', ( dateString, timeZone, expected ) => {
+			expect( parseAsLocalDate( dateString, timeZone ).toISOString() ).toBe( expected );
+		} );
+
+		test.each( INSTANT_CASES )( 'leaves %s where it is', ( dateString, expected ) => {
+			expect( parseAsLocalDate( dateString, 'Asia/Tokyo' ).toISOString() ).toBe( expected );
+		} );
+
+		it( 'falls back to the runtime zone where Intl rejects the zone, and says so', () => {
+			const fallback = parseAsLocalDate( '2026-08-02', 'Not/AZone' );
+
+			expect( fallback.getTime() ).toBe( parseAsLocalDate( '2026-08-02' ).getTime() );
+			expect( console ).toHaveWarnedWith(
+				'[Charts] timeZone "Not/AZone" 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".'
+			);
+		} );
+
+		it( 'keeps a year below 100 out of the 1900s', () => {
+			expect( parseAsLocalDate( '0099-08-02', 'Asia/Tokyo' ).getUTCFullYear() ).toBe( 99 );
+			expect( parseAsLocalDate( '99-08-02', 'Asia/Tokyo' ).getUTCFullYear() ).toBe( 99 );
+		} );
+
+		it( 'reads a naive string in the runtime zone when no zone is supplied', () => {
+			const local = parseAsLocalDate( '2026-08-02' );
+
+			expect( [
+				local.getFullYear(),
+				local.getMonth(),
+				local.getDate(),
+				local.getHours(),
+			] ).toEqual( [ 2026, 7, 2, 0 ] );
+		} );
+	} );
+};

package/src/types.ts

@@ -478,8 +478,8 @@ export type BucketInfo = {
  * `timeZone` re-dates the instants the host supplies, so a value that is really a
  * calendar day shifts under it: `new Date( '2026-08-02' )` is UTC midnight and
  * labels as Aug 1 in `America/Los_Angeles`. Supply true instants alongside a
- * `timeZone`, or set only `locale` for day-bucketed data. `HeatmapChart`'s
- * calendar labels take neither — see `buildCalendarHeatmapData`.
+ * `timeZone`, or set only `locale` for day-bucketed data. `buildCalendarHeatmapData`
+ * is the exception: it reads a bare `yyyy-MM-dd` as the day it names.
  */
 export type ChartFormatting = {
 	/** BCP-47 language tag, e.g. `de-DE`. Defaults to the runtime's locale. */

package/src/utils/date-formatting.ts

@@ -1,11 +1,6 @@
+import { warnOnce } from './warn-once';
 import type { ChartFormatting } from '../types';
 
-/**
- * `process.env.NODE_ENV` is replaced by the bundler at build time. Declare a
- * minimal `process` locally so this file type-checks as source under `jetpack:src`.
- */
-declare const process: { env: Record< string, string | undefined > };
-
 // One `Intl.DateTimeFormat` per locale, zone and options triple. The axis formats
 // every bucket in the domain, and rebuilding the formatter is what costs; the tick
 // formats themselves are rebuilt on every resize, so a per-closure cache is not
@@ -27,18 +22,6 @@ const getFormatter = (
 	return formatter;
 };
 
-const warned = new Set< string >();
-
-const warnOnce = ( key: string, message: string ): void => {
-	if ( warned.has( key ) || process.env.NODE_ENV === 'production' ) {
-		return;
-	}
-
-	warned.add( key );
-	// eslint-disable-next-line no-console
-	console.warn( `[Charts] ${ message }` );
-};
-
 const isUsable = ( formatting: ChartFormatting ): boolean => {
 	try {
 		// Constructing is the check: `Intl` throws on a tag or zone it cannot use.

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

@@ -13,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/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();

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

@@ -0,0 +1,55 @@
+import { getEdgeTickWidths } from '../get-edge-tick-widths';
+
+const mockGetStringWidth = jest.fn();
+jest.mock( '@visx/text', () => ( {
+	...jest.requireActual( '@visx/text' ),
+	getStringWidth: ( ...args: unknown[] ) => mockGetStringWidth( ...args ),
+} ) );
+
+describe( 'getEdgeTickWidths', () => {
+	beforeEach( () => {
+		mockGetStringWidth.mockReset();
+		mockGetStringWidth.mockImplementation( ( label: string ) => label.length );
+	} );
+
+	it( 'measures the formatted first and last ticks', () => {
+		const style = { fontSize: 11 };
+
+		const widths = getEdgeTickWidths( [ 1, 2, 3 ], value => `tick-${ value }`, style );
+
+		expect( widths ).toEqual( { first: 6, last: 6 } );
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( 'tick-1', style );
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( 'tick-3', style );
+	} );
+
+	it( 'passes each tick its own index', () => {
+		getEdgeTickWidths( [ 'a', 'b', 'c' ], ( value, index ) => `${ index }:${ value }` );
+
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( '0:a', undefined );
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( '2:c', undefined );
+	} );
+
+	it( 'measures a single tick as both edges', () => {
+		expect( getEdgeTickWidths( [ 42 ], value => `${ value }` ) ).toEqual( { first: 2, last: 2 } );
+	} );
+
+	it( 'measures the raw value when there is no formatter', () => {
+		getEdgeTickWidths( [ 'abcd' ] );
+
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( 'abcd', undefined );
+	} );
+
+	it( 'returns nothing to reserve for an axis with no ticks', () => {
+		expect( getEdgeTickWidths( [] ) ).toEqual( { first: 0, last: 0 } );
+		expect( mockGetStringWidth ).not.toHaveBeenCalled();
+	} );
+
+	it( 'reserves nothing for a label the measurer cannot size', () => {
+		mockGetStringWidth.mockReturnValue( null );
+
+		expect( getEdgeTickWidths( [ 1, 2, 3 ], value => `tick-${ value }` ) ).toEqual( {
+			first: 0,
+			last: 0,
+		} );
+	} );
+} );

package/src/utils/warn-once.ts

@@ -0,0 +1,23 @@
+/**
+ * `process.env.NODE_ENV` is replaced by the bundler at build time. Declare a
+ * minimal `process` locally so this file type-checks as source under `jetpack:src`.
+ */
+declare const process: { env: Record< string, string | undefined > };
+
+const warned = new Set< string >();
+
+/**
+ * Warns about a host-supplied value once per process, and never in production.
+ *
+ * @param key     - Identifies the value, so a bad prop on every point warns once.
+ * @param message - What the host got wrong and what happens instead.
+ */
+export const warnOnce = ( key: string, message: string ): void => {
+	if ( warned.has( key ) || process.env.NODE_ENV === 'production' ) {
+		return;
+	}
+
+	warned.add( key );
+	// eslint-disable-next-line no-console
+	console.warn( `[Charts] ${ message }` );
+};

package/src/visx/types.ts

@@ -1,7 +1,7 @@
 import type { PickD3Scale } from '@visx/scale';
 import type { TooltipProps as VisxTooltipProps, UseTooltipPortalOptions } from '@visx/tooltip';
 import type { GlyphProps, TooltipContextType } from '@visx/xychart';
-import type { ReactNode, SVGProps } from 'react';
+import type { CSSProperties, ReactNode, SVGProps } from 'react';
 
 export type RenderTooltipParams< Datum extends object > = TooltipContextType< Datum > & {
 	colorScale?: PickD3Scale< 'ordinal', string, string >;
@@ -12,23 +12,47 @@ export interface RenderTooltipGlyphProps< Datum extends object > extends GlyphPr
 	isNearestDatum: boolean;
 }
 
+export type TooltipPlacement = 'auto' | 'below-axis';
+
+type CrosshairPaintProperty =
+	| 'stroke'
+	| 'strokeWidth'
+	| 'strokeOpacity'
+	| 'strokeDasharray'
+	| 'strokeLinecap'
+	| 'opacity';
+
+export type CrosshairStyle = Pick< SVGProps< SVGLineElement >, CrosshairPaintProperty > & {
+	className?: string;
+	style?: Pick< CSSProperties, CrosshairPaintProperty >;
+};
+
 export type XyChartTooltipProps< Datum extends object > = {
 	renderTooltip: ( params: RenderTooltipParams< Datum > ) => ReactNode;
 	renderGlyph?: ( params: RenderTooltipGlyphProps< Datum > ) => ReactNode;
+	/**
+	 * Keep the panel below the x-axis label band, centered at the datum x and horizontally clamped.
+	 * Vertical bounds do not move this placement; clipping ancestors can still cut it off.
+	 * @default 'auto'
+	 */
+	tooltipPlacement?: TooltipPlacement;
+	/** Merge overrides with the default box styles; use `unstyled` to strip the box styling. */
+	style?: VisxTooltipProps[ 'style' ];
 	snapTooltipToDatumX?: boolean;
 	snapTooltipToDatumY?: boolean;
 	showVerticalCrosshair?: boolean;
 	showHorizontalCrosshair?: boolean;
 	showDatumGlyph?: boolean;
 	showSeriesGlyphs?: boolean;
-	verticalCrosshairStyle?: SVGProps< SVGLineElement >;
-	horizontalCrosshairStyle?: SVGProps< SVGLineElement >;
+	verticalCrosshairStyle?: CrosshairStyle;
+	horizontalCrosshairStyle?: CrosshairStyle;
 	glyphStyle?: SVGProps< SVGCircleElement >;
 	/**
 	 * Flip and clamp the tooltip box so it stays inside the nearest ancestor
 	 * that clips its overflow, or the viewport when there is none. The box may
 	 * leave the chart wrapper. (It used to keep a body-level portal inside the
 	 * viewport.)
+	 * Ignored by `below-axis`.
 	 * @default true
 	 */
 	detectBounds?: boolean;