@automattic/charts 4.1.0 → 4.2.0

package/src/charts/heatmap-chart/{private/build-calendar-data.ts → build-calendar-data.ts}

@@ -1,47 +1,24 @@
-import { createDateFormatter, sanitizeFormatting } from '../../../utils/date-formatting';
-import { warnOnce } from '../../../utils/warn-once';
+import { sanitizeFormatting } from '../../utils/date-formatting';
+import { warnOnce } from '../../utils/warn-once';
 import {
 	addCivilDays,
 	civilDate,
 	civilKey,
+	civilLabelFormatters,
 	civilWeekSpan,
 	instantDayReader,
 	pointDayKey,
 	startOfCivilWeek,
 	writtenDayKey,
-} from './civil-day';
-import type { DataPointDate } from '../../../types';
-import type { HeatmapCell, HeatmapColumn } from '../types';
-import type { CivilDate, DayKey } from './civil-day';
-
-export type CalendarHeatmapResult = {
-	data: HeatmapColumn[];
-	rowLabels: string[];
-};
-
-export type CalendarHeatmapOptions = {
-	weekStartsOn?: 0 | 1;
-	/**
-	 * Mark the days completing the first and last week outside the series' span as
-	 * hidden cells rather than blank ones, giving the calendar ragged edges. Days
-	 * inside the span stay blank even where the series has no entry.
-	 */
-	hideOutOfRangeDays?: boolean;
-	/**
-	 * Draw the grid over this span (`yyyy-MM-dd` bounds) instead of the series' own.
-	 * Days inside the grid but outside the series become placeholder cells: painted,
-	 * but reporting nothing, since they were never measured. A start bound opens from
-	 * the beginning of its week, and bounds narrower than the series are ignored.
-	 */
-	gridSpan?: { start?: string; end?: string };
-	/** BCP-47 tag the labels are written in. Defaults to the runtime's locale. */
-	locale?: string;
-	/**
-	 * IANA zone the series' instants are bucketed into days in. Defaults to the
-	 * runtime's zone. A `dateString` carrying no offset is taken as written.
-	 */
-	timeZone?: string;
-};
+} from './private/civil-day';
+import type { CivilDate, DayKey } from './private/civil-day';
+import type {
+	CalendarHeatmapOptions,
+	CalendarHeatmapResult,
+	HeatmapCell,
+	HeatmapColumn,
+} from './types';
+import type { DataPointDate } from '../../types';
 
 /** Rows that get a weekday label (Mon, Wed, Fri with a Monday week start). */
 const LABELLED_ROWS = [ 0, 2, 4 ];
@@ -114,7 +91,7 @@ export const buildCalendarHeatmapData = (
 				offending
 					? `${ JSON.stringify(
 							offending
-					  ) } is not a day this can read, so its point is left out of the calendar. A \`dateString\` must start \`yyyy-MM-dd\`.`
+						) } is not a day this can read, so its point is left out of the calendar. A \`dateString\` must start \`yyyy-MM-dd\`.`
 					: 'A point carries neither `date` nor `dateString`, so it is left out of the calendar.'
 			);
 			continue;
@@ -142,15 +119,8 @@ export const buildCalendarHeatmapData = (
 	const requestedMinDate = civilDate( requestedMinDayKey ) as CivilDate;
 	const gridMaxDate = civilDate( gridMaxDayKey ) as CivilDate;
 
-	// The grid walks UTC proxies, so the label formatters read UTC. The host's zone
-	// was already spent on bucketing.
-	const labelFormatting = { locale, timeZone: 'UTC' };
-	const formatWeekday = createDateFormatter( { weekday: 'short' }, labelFormatting );
-	const formatMonth = createDateFormatter( { month: 'short' }, labelFormatting );
-	const formatDay = createDateFormatter(
-		{ weekday: 'short', month: 'short', day: 'numeric', year: 'numeric' },
-		labelFormatting
-	);
+	// The host's zone was already spent on bucketing; labels read the UTC proxies.
+	const { formatWeekday, formatMonth, formatDay } = civilLabelFormatters( locale );
 
 	const gridStart = startOfCivilWeek( requestedMinDate, weekStartsOn );
 

package/src/charts/heatmap-chart/build-month-calendar-data.ts

@@ -0,0 +1,124 @@
+import { sanitizeFormatting } from '../../utils/date-formatting';
+import { warnOnce } from '../../utils/warn-once';
+import {
+	addCivilDays,
+	civilDate,
+	civilKey,
+	civilLabelFormatters,
+	startOfCivilWeek,
+} from './private/civil-day';
+import { isPresent } from './private/use-heatmap-colors';
+import type { CivilDate, DayKey } from './private/civil-day';
+import type {
+	HeatmapCell,
+	HeatmapColumn,
+	HeatmapColumnGroup,
+	MonthCalendarHeatmapOptions,
+	MonthCalendarHeatmapRange,
+	MonthCalendarHeatmapResult,
+} from './types';
+
+/** Week rows per month, fixed so every month block is the same height. */
+const MONTH_ROWS = 6;
+
+const DAYS_PER_WEEK = 7;
+
+const startOfCivilMonth = ( date: CivilDate ): CivilDate => {
+	const first = new Date( date.getTime() ) as CivilDate;
+	first.setUTCDate( 1 );
+	return first;
+};
+
+const startOfNextCivilMonth = ( date: CivilDate ): CivilDate => {
+	const next = startOfCivilMonth( date );
+	next.setUTCMonth( next.getUTCMonth() + 1 );
+	return next;
+};
+
+/**
+ * Lay a day-keyed map out as one month calendar per month, weekdays across and
+ * weeks down, for `HeatmapChart` with `columnGroups`.
+ *
+ * @param valueByDay - Value per `yyyy-MM-dd`. A missing day is `null`.
+ * @param range      - The measured days; every month from `start`'s through `end`'s is drawn.
+ * @param options    - Week start and label locale.
+ * @return Columns and one group per month; empty for an invalid or reversed range.
+ */
+export const buildMonthCalendarHeatmapData = (
+	valueByDay: Record< string, number | null >,
+	range: MonthCalendarHeatmapRange,
+	options: MonthCalendarHeatmapOptions = {}
+): MonthCalendarHeatmapResult => {
+	const start = civilDate( range.start );
+	const end = civilDate( range.end );
+	if ( ! start || ! end || start.getTime() > end.getTime() ) {
+		warnOnce(
+			`heatmap:monthRange:${ range.start }:${ range.end }`,
+			`range ${ JSON.stringify(
+				range
+			) } must be two \`yyyy-MM-dd\` days with start on or before end, so the calendar is empty.`
+		);
+		return { data: [], columnGroups: [] };
+	}
+	const startKey = civilKey( start );
+	const endKey = civilKey( end );
+	const weekStartsOn = options.weekStartsOn ?? 1;
+	const { locale } = sanitizeFormatting( { locale: options.locale } );
+
+	for ( const key of Object.keys( valueByDay ) ) {
+		if ( ! civilDate( key ) ) {
+			warnOnce(
+				`heatmap:monthKey:${ key }`,
+				`${ JSON.stringify(
+					key
+				) } is not a \`yyyy-MM-dd\` day, so its value is left out of the calendar.`
+			);
+		}
+	}
+	const readValue = ( key: DayKey ): number | null => {
+		const value = valueByDay[ key ];
+		return isPresent( value ) ? value : null;
+	};
+
+	const { formatMonth, formatMonthYear, formatDay } = civilLabelFormatters( locale );
+
+	const data: HeatmapColumn[] = [];
+	const columnGroups: HeatmapColumnGroup[] = [];
+	const lastMonthStart = startOfCivilMonth( end );
+	// Past twelve months a month name would repeat, so the year tells them apart.
+	const monthCount =
+		( lastMonthStart.getUTCFullYear() - start.getUTCFullYear() ) * 12 +
+		lastMonthStart.getUTCMonth() -
+		start.getUTCMonth() +
+		1;
+	const formatGroup = monthCount > 12 ? formatMonthYear : formatMonth;
+
+	for (
+		let monthStart = startOfCivilMonth( start );
+		monthStart.getTime() <= lastMonthStart.getTime();
+		monthStart = startOfNextCivilMonth( monthStart )
+	) {
+		const monthStartKey = civilKey( monthStart );
+		const monthEndKey = civilKey( addCivilDays( startOfNextCivilMonth( monthStart ), -1 ) );
+		const gridStart = startOfCivilWeek( monthStart, weekStartsOn );
+
+		for ( let weekday = 0; weekday < DAYS_PER_WEEK; weekday++ ) {
+			const cells: HeatmapCell[] = [];
+			for ( let week = 0; week < MONTH_ROWS; week++ ) {
+				const day = addCivilDays( gridStart, week * DAYS_PER_WEEK + weekday );
+				const key = civilKey( day );
+				if ( key < monthStartKey || key > monthEndKey ) {
+					cells.push( { value: null, hidden: true } );
+				} else if ( key < startKey || key > endKey ) {
+					cells.push( { label: formatDay( day ), value: null, placeholder: true } );
+				} else {
+					cells.push( { label: formatDay( day ), value: readValue( key ) } );
+				}
+			}
+			data.push( { data: cells } );
+		}
+		columnGroups.push( { label: formatGroup( monthStart ), span: DAYS_PER_WEEK } );
+	}
+
+	return { data, columnGroups };
+};

package/src/charts/heatmap-chart/heatmap-chart.module.scss

@@ -5,6 +5,8 @@ $focus-ring-width: var(--wpds-border-width-focus);
 
 .heatmap-chart {
 	position: relative;
+	// Keeps the tooltip's z-index inside the chart, as `.xy-plot` does.
+	isolation: isolate;
 	width: 100%;
 	height: 100%;
 	min-height: 0;
@@ -53,6 +55,13 @@ $focus-ring-width: var(--wpds-border-width-focus);
 	min-height: 0;
 }
 
+// Grouped compact grids fill the container so the flexible gap tracks can share
+// the leftover width, and never shrink below the cells plus the minimum gaps.
+.heatmap-chart__grid--flex-gaps {
+	width: 100%;
+	min-width: max-content;
+}
+
 // A cell-height cap makes the row tracks content-bound, so the grid must not
 // stretch: leftover container height would otherwise be absorbed by the auto
 // label row. A width-only cap does not change vertical flex sizing.
@@ -70,6 +79,8 @@ $focus-ring-width: var(--wpds-border-width-focus);
 .heatmap-chart__row-label {
 	color: var(--a8c-charts-color-label-secondary);
 	font-size: var(--wpds-typography-font-size-xs);
+	// Pinned so the label height does not follow the host's line-height.
+	line-height: var(--wpds-typography-line-height-xs);
 	white-space: nowrap;
 	overflow: visible;
 }
@@ -79,6 +90,16 @@ $focus-ring-width: var(--wpds-border-width-focus);
 	text-align: left;
 }
 
+// Beneath its columns, set off from the last row by more than the cell gap.
+.heatmap-chart__group-label {
+	color: var(--a8c-charts-color-label-secondary);
+	font-size: var(--wpds-typography-font-size-xs);
+	line-height: var(--wpds-typography-line-height-xs);
+	white-space: nowrap;
+	text-align: center;
+	padding-block-start: var(--wpds-dimension-padding-xs);
+}
+
 .heatmap-chart__row-label {
 	align-self: center;
 	justify-self: end;
@@ -178,3 +199,14 @@ $focus-ring-width: var(--wpds-border-width-focus);
 	border-radius: var(--a8c-charts-border-radius-cell);
 	background: color-mix(in sRGB, var(--a8c-charts-color-heatmap-primary) calc((0.15 + 0.85 * var(--a8c-charts-heatmap-cell-intensity)) * 100%), var(--a8c-charts-color-background, #fff));
 }
+
+// One band: the steps butt against each other and only the band's ends round.
+.heatmap-chart__legend-scale--bar {
+	overflow: hidden;
+	border-radius: var(--a8c-charts-border-radius-cell);
+
+	.heatmap-chart__legend-swatch {
+		width: var(--wpds-dimension-size-sm);
+		border-radius: 0;
+	}
+}