Skip to content

Open-source status page, incident response and uptime monitoring

feat(status-page): append (UTC) to formatted report timestamps (#2303)

Maximilian Kaske72b46873d351
diff --git a/apps/status-page/src/components/i18n/status-blocks-provider.tsx b/apps/status-page/src/components/i18n/status-blocks-provider.tsx
index 36840be97..9b3700949 100644
--- a/apps/status-page/src/components/i18n/status-blocks-provider.tsx
+++ b/apps/status-page/src/components/i18n/status-blocks-provider.tsx
@@ -14,6 +14,9 @@ import {
formatDateTime,
} from "@/lib/formatter";
+// Status-page timestamps render in UTC; the suffix tells viewers which zone.
+const withUTC = (value: string) => `${value} (UTC)`;
+
/**
* StatusBlocksProvider
*
@@ -113,13 +116,18 @@ export function StatusBlocksProvider({
durationAcross: (duration: string) =>
t("across {duration}", { duration }),
- formatDate: (d: Date) => formatDate(d, { locale }),
- formatDateShort: (d: Date) => formatDate(d, { month: "short", locale }),
- formatDateTime: (d: Date) => formatDateTime(d, locale),
- formatDateRange: (from?: Date, to?: Date) =>
- formatDateRange(from, to, locale),
- formatDateRangeParts: (from: Date, to: Date) =>
- formatDateRangeParts(from, to, locale),
+ formatDate: (d: Date) => withUTC(formatDate(d, { locale })),
+ formatDateShort: (d: Date) =>
+ withUTC(formatDate(d, { month: "short", locale })),
+ formatDateTime: (d: Date) => withUTC(formatDateTime(d, locale)),
+ formatDateRange: (from?: Date, to?: Date) => {
+ const range = formatDateRange(from, to, locale);
+ return from || to ? withUTC(range) : range;
+ },
+ formatDateRangeParts: (from: Date, to: Date) => {
+ const { from: start, to: end } = formatDateRangeParts(from, to, locale);
+ return { from: start, to: withUTC(end) };
+ },
}),
[t, locale],
);
diff --git a/apps/status-page/src/lib/formatter.test.ts b/apps/status-page/src/lib/formatter.test.ts
new file mode 100644
index 000000000..d9e59b032
--- /dev/null
+++ b/apps/status-page/src/lib/formatter.test.ts
@@ -0,0 +1,142 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+ formatDate,
+ formatDateRange,
+ formatDateRangeParts,
+ formatDateTime,
+ formatTime,
+} from "./formatter";
+
+// Timestamps must render in UTC so every viewer sees the authored time,
+// independent of their local timezone (see #2302).
+describe("formatter UTC rendering", () => {
+ describe("formatDate", () => {
+ test("renders the UTC day with a long month", () => {
+ expect(formatDate(new Date("2024-01-15T14:30:00Z"))).toBe(
+ "January 15, 2024",
+ );
+ });
+
+ test("honors a short month override", () => {
+ expect(
+ formatDate(new Date("2024-01-15T14:30:00Z"), { month: "short" }),
+ ).toBe("Jan 15, 2024");
+ });
+
+ test("keeps a late-UTC timestamp on its UTC day", () => {
+ expect(formatDate(new Date("2024-01-15T23:30:00Z"))).toBe(
+ "January 15, 2024",
+ );
+ });
+
+ test("ignores a caller attempt to override the timezone", () => {
+ // 01:00 UTC is still Jan 14 in New York, so a leaked override would read "January 14".
+ expect(
+ formatDate(new Date("2024-01-15T01:00:00Z"), {
+ timeZone: "America/New_York",
+ }),
+ ).toBe("January 15, 2024");
+ });
+ });
+
+ describe("formatDateTime", () => {
+ test("renders the UTC wall-clock time", () => {
+ expect(formatDateTime(new Date("2024-01-15T14:30:00Z"))).toBe(
+ "January 15 at 2:30 PM",
+ );
+ });
+ });
+
+ describe("formatTime", () => {
+ test("renders the UTC wall-clock time", () => {
+ expect(formatTime(new Date("2024-01-15T14:30:00Z"))).toBe("2:30 PM");
+ });
+
+ test("does not shift a late-UTC time into the next day's hours", () => {
+ expect(formatTime(new Date("2024-01-15T23:30:00Z"))).toBe("11:30 PM");
+ });
+ });
+});
+
+describe("formatDateRange", () => {
+ test("collapses the `to` side to a time when both fall on the same UTC day", () => {
+ expect(
+ formatDateRange(
+ new Date("2024-01-15T10:00:00Z"),
+ new Date("2024-01-15T15:00:00Z"),
+ ),
+ ).toBe("January 15 at 10:00 AM - 3:00 PM");
+ });
+
+ test("renders date-only when the range spans whole UTC days", () => {
+ expect(
+ formatDateRange(
+ new Date("2024-01-15T00:00:00.000Z"),
+ new Date("2024-01-17T23:59:59.999Z"),
+ ),
+ ).toBe("January 15, 2024 - January 17, 2024");
+ });
+
+ test("keeps both timestamps for a partial multi-day range", () => {
+ expect(
+ formatDateRange(
+ new Date("2024-01-15T10:00:00Z"),
+ new Date("2024-01-17T12:00:00Z"),
+ ),
+ ).toBe("January 15 at 10:00 AM - January 17 at 12:00 PM");
+ });
+
+ test("renders a single timestamp when from and to are equal", () => {
+ const date = new Date("2024-01-15T10:00:00Z");
+ expect(formatDateRange(date, date)).toBe("January 15 at 10:00 AM");
+ });
+
+ test("renders `Until` for an open-start range", () => {
+ expect(formatDateRange(undefined, new Date("2024-01-15T15:00:00Z"))).toBe(
+ "Until January 15 at 3:00 PM",
+ );
+ });
+
+ test("renders `Since` for an open-end range", () => {
+ expect(formatDateRange(new Date("2024-01-15T10:00:00Z"), undefined)).toBe(
+ "Since January 15 at 10:00 AM",
+ );
+ });
+
+ test("renders `All time` when no bounds are given", () => {
+ expect(formatDateRange()).toBe("All time");
+ });
+});
+
+describe("formatDateRangeParts", () => {
+ test("collapses the `to` side to a time on the same UTC day", () => {
+ expect(
+ formatDateRangeParts(
+ new Date("2024-01-15T10:00:00Z"),
+ new Date("2024-01-15T15:00:00Z"),
+ ),
+ ).toEqual({ from: "January 15 at 10:00 AM", to: "3:00 PM" });
+ });
+
+ test("renders date-only parts for whole UTC days", () => {
+ expect(
+ formatDateRangeParts(
+ new Date("2024-01-15T00:00:00.000Z"),
+ new Date("2024-01-17T23:59:59.999Z"),
+ ),
+ ).toEqual({ from: "January 15, 2024", to: "January 17, 2024" });
+ });
+
+ test("keeps both timestamps for a partial multi-day range", () => {
+ expect(
+ formatDateRangeParts(
+ new Date("2024-01-15T10:00:00Z"),
+ new Date("2024-01-17T12:00:00Z"),
+ ),
+ ).toEqual({
+ from: "January 15 at 10:00 AM",
+ to: "January 17 at 12:00 PM",
+ });
+ });
+});
diff --git a/apps/status-page/src/lib/formatter.ts b/apps/status-page/src/lib/formatter.ts
index de1cd0d73..1ceff5799 100644
--- a/apps/status-page/src/lib/formatter.ts
+++ b/apps/status-page/src/lib/formatter.ts
@@ -54,8 +54,9 @@ export function formatDate(
year: "numeric",
month: "long",
day: "numeric",
- timeZone: "UTC",
...rest,
+ // last so callers can't override away from UTC (the "(UTC)" label depends on it)
+ timeZone: "UTC",
});
}
diff --git a/apps/status-page/src/lib/status-blocks-labels.test.ts b/apps/status-page/src/lib/status-blocks-labels.test.ts
new file mode 100644
index 000000000..dfb222d85
--- /dev/null
+++ b/apps/status-page/src/lib/status-blocks-labels.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+
+import { defaultStatusBlocksLabels as labels } from "@openstatus/ui/components/blocks/status.utils";
+
+// Status-page timestamps render in UTC, so the user-facing labels carry a
+// trailing "(UTC)" to tell viewers which zone they are reading (see #2302).
+describe("defaultStatusBlocksLabels UTC suffix", () => {
+ const date = new Date("2024-01-15T14:30:00Z");
+
+ test("formatDate appends the UTC suffix", () => {
+ expect(labels.formatDate(date)).toBe("January 15, 2024 (UTC)");
+ });
+
+ test("formatDateShort appends the UTC suffix", () => {
+ expect(labels.formatDateShort(date)).toBe("Jan 15, 2024 (UTC)");
+ });
+
+ test("formatDateTime appends the UTC suffix", () => {
+ expect(labels.formatDateTime(date)).toBe("January 15 at 2:30 PM (UTC)");
+ });
+
+ describe("formatDateRange", () => {
+ test("appends a single UTC suffix to the whole range", () => {
+ expect(
+ labels.formatDateRange(
+ new Date("2024-01-15T10:00:00Z"),
+ new Date("2024-01-15T15:00:00Z"),
+ ),
+ ).toBe("January 15 at 10:00 AM - 3:00 PM (UTC)");
+ });
+
+ test("appends the UTC suffix to an open-ended range", () => {
+ expect(
+ labels.formatDateRange(new Date("2024-01-15T10:00:00Z"), undefined),
+ ).toBe("Since January 15 at 10:00 AM (UTC)");
+ });
+
+ test("appends the UTC suffix to an open-start range", () => {
+ expect(
+ labels.formatDateRange(undefined, new Date("2024-01-15T15:00:00Z")),
+ ).toBe("Until January 15 at 3:00 PM (UTC)");
+ });
+
+ test("leaves `All time` without a UTC suffix", () => {
+ expect(labels.formatDateRange()).toBe("All time");
+ });
+ });
+
+ test("formatDateRangeParts marks only the trailing `to` part", () => {
+ expect(
+ labels.formatDateRangeParts(
+ new Date("2024-01-15T10:00:00Z"),
+ new Date("2024-01-15T15:00:00Z"),
+ ),
+ ).toEqual({ from: "January 15 at 10:00 AM", to: "3:00 PM (UTC)" });
+ });
+});
diff --git a/packages/ui/src/components/blocks/status.utils.ts b/packages/ui/src/components/blocks/status.utils.ts
index d3074180d..71b5de222 100644
--- a/packages/ui/src/components/blocks/status.utils.ts
+++ b/packages/ui/src/components/blocks/status.utils.ts
@@ -73,8 +73,9 @@ export function formatDate(
year: "numeric",
month: "long",
day: "numeric",
- timeZone: "UTC",
...options,
+ // last so callers can't override away from UTC (the "(UTC)" label depends on it)
+ timeZone: "UTC",
});
}
@@ -126,6 +127,27 @@ export function formatTime(date: Date, locale = "en-US") {
});
}
+/**
+ * Returns the start/end of a closed range as separate strings, collapsing the
+ * `to` side to a time-only render when `from` and `to` fall on the same UTC day.
+ * Use `formatDateRange` for open-ended cases (`Until …` / `Since …`).
+ */
+export function formatDateRangeParts(
+ from: Date,
+ to: Date,
+): { from: string; to: string } {
+ if (isSameDay(new UTCDate(from), new UTCDate(to))) {
+ return { from: formatDateTime(from), to: formatTime(to) };
+ }
+ const isFromStartDay =
+ startOfDay(new UTCDate(from)).getTime() === from.getTime();
+ const isToEndDay = endOfDay(new UTCDate(to)).getTime() === to.getTime();
+ if (isFromStartDay && isToEndDay) {
+ return { from: formatDate(from), to: formatDate(to) };
+ }
+ return { from: formatDateTime(from), to: formatDateTime(to) };
+}
+
import type {
StatusReportImpact,
StatusReportUpdateType,
@@ -269,6 +291,9 @@ export const statusColors: Record<StatusType, string> = {
*/
export const colors = statusColors;
+// Timestamps render in UTC; the suffix tells viewers which zone.
+const withUTC = (value: string) => `${value} (UTC)`;
+
/**
* Default labels consumed by blocks when no StatusBlocksI18nProvider is mounted.
* Registry/web preview render with this set; the status-page app overrides via the provider.
@@ -321,20 +346,15 @@ export const defaultStatusBlocksLabels = {
durationFor: (s: string) => `(for ${s})`,
durationAcross: (s: string) => `across ${s}`,
- formatDate: (d: Date) => formatDate(d),
- formatDateShort: (d: Date) => formatDateShort(d),
- formatDateTime: (d: Date) => formatDateTime(d),
- formatDateRange: (from?: Date, to?: Date) => formatDateRange(from, to),
+ formatDate: (d: Date) => withUTC(formatDate(d)),
+ formatDateShort: (d: Date) => withUTC(formatDateShort(d)),
+ formatDateTime: (d: Date) => withUTC(formatDateTime(d)),
+ formatDateRange: (from?: Date, to?: Date) => {
+ const range = formatDateRange(from, to);
+ return from || to ? withUTC(range) : range;
+ },
formatDateRangeParts: (from: Date, to: Date) => {
- if (isSameDay(new UTCDate(from), new UTCDate(to))) {
- return { from: formatDateTime(from), to: formatTime(to) };
- }
- const isFromStartDay =
- startOfDay(new UTCDate(from)).getTime() === from.getTime();
- const isToEndDay = endOfDay(new UTCDate(to)).getTime() === to.getTime();
- if (isFromStartDay && isToEndDay) {
- return { from: formatDate(from), to: formatDate(to) };
- }
- return { from: formatDateTime(from), to: formatDateTime(to) };
+ const { from: start, to: end } = formatDateRangeParts(from, to);
+ return { from: start, to: withUTC(end) };
},
} as const satisfies StatusBlocksLabels;