Stage 11: polish, cross-cutting concerns & hardening

- 11.1 MainLayout health indicator: warning MessageBar when fail2ban offline
- 11.2 formatDate utility + TimezoneProvider + GET /api/setup/timezone
- 11.3 Responsive sidebar: auto-collapse <640px, media query listener
- 11.4 PageFeedback (PageLoading/PageError/PageEmpty), BanTable updated
- 11.5 prefers-reduced-motion: disable sidebar transition
- 11.6 WorldMap ARIA: role/tabIndex/aria-label/onKeyDown for countries
- 11.7 Health transition logging (fail2ban_came_online/went_offline)
- 11.8 Global handlers: Fail2BanConnectionError/ProtocolError -> 502
- 11.9 379 tests pass, 82% coverage, ruff+mypy+tsc+eslint clean
- Timezone endpoint: setup_service.get_timezone, 5 new tests

frontend/src/utils/formatDate.ts

@@ -0,0 +1,132 @@
+/**
+ * Date formatting utility.
+ *
+ * All timestamps stored and transmitted by the backend are in UTC (ISO 8601
+ * strings).  This module provides helper functions that convert them to the
+ * IANA timezone configured during the BanGUI setup wizard and format them
+ * for display.
+ *
+ * Usage:
+ * ```ts
+ * import { formatDate, formatDateShort } from "../utils/formatDate";
+ *
+ * // Full date + time
+ * formatDate("2024-06-15T13:45:00Z", "Europe/Berlin");
+ * // → "15/06/2024, 15:45:00"
+ *
+ * // Date only
+ * formatDateShort("2024-06-15T13:45:00Z", "Europe/Berlin");
+ * // → "15/06/2024"
+ * ```
+ */
+
+/** Fallback timezone used when no timezone is provided. */
+const DEFAULT_TIMEZONE = "UTC";
+
+/**
+ * Validate that *tz* is a recognised IANA timezone identifier.
+ *
+ * Returns the validated string or ``DEFAULT_TIMEZONE`` on failure so that
+ * callers always receive a safe value rather than an exception.
+ *
+ * @param tz - IANA timezone string to validate.
+ * @returns The original *tz* if valid, otherwise ``"UTC"``.
+ */
+function safeTimezone(tz: string | undefined | null): string {
+  if (!tz) return DEFAULT_TIMEZONE;
+  try {
+    // Intl.DateTimeFormat throws a RangeError for unknown timezone identifiers.
+    Intl.DateTimeFormat(undefined, { timeZone: tz });
+    return tz;
+  } catch {
+    return DEFAULT_TIMEZONE;
+  }
+}
+
+/**
+ * Format an ISO 8601 UTC timestamp as a localised date-and-time string.
+ *
+ * The exact format depends on the user's browser locale in combination with
+ * the provided timezone (e.g. ``"15/06/2024, 15:45:00"`` for ``en-GB``).
+ *
+ * @param isoUtc  - UTC timestamp string, e.g. ``"2024-06-15T13:45:00Z"``.
+ * @param timezone - IANA timezone identifier, e.g. ``"Europe/Berlin"``.
+ *   Defaults to ``"UTC"``.
+ * @returns A human-readable date-time string in the specified timezone.
+ */
+export function formatDate(
+  isoUtc: string | null | undefined,
+  timezone: string | null | undefined = DEFAULT_TIMEZONE,
+): string {
+  if (!isoUtc) return "—";
+  try {
+    return new Intl.DateTimeFormat(undefined, {
+      timeZone: safeTimezone(timezone),
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    }).format(new Date(isoUtc));
+  } catch {
+    return isoUtc;
+  }
+}
+
+/**
+ * Format an ISO 8601 UTC timestamp as a localised date-only string.
+ *
+ * @param isoUtc  - UTC timestamp string.
+ * @param timezone - IANA timezone identifier.  Defaults to ``"UTC"``.
+ * @returns A date-only string, e.g. ``"15/06/2024"``.
+ */
+export function formatDateShort(
+  isoUtc: string | null | undefined,
+  timezone: string | null | undefined = DEFAULT_TIMEZONE,
+): string {
+  if (!isoUtc) return "—";
+  try {
+    return new Intl.DateTimeFormat(undefined, {
+      timeZone: safeTimezone(timezone),
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    }).format(new Date(isoUtc));
+  } catch {
+    return isoUtc;
+  }
+}
+
+/**
+ * Format an ISO 8601 UTC timestamp as a relative time string (e.g. "3 minutes
+ * ago") using the browser's `Intl.RelativeTimeFormat`.
+ *
+ * Falls back to {@link formatDate} when the difference cannot be computed.
+ *
+ * @param isoUtc  - UTC timestamp string.
+ * @param timezone - IANA timezone identifier used for the fallback format.
+ * @returns A relative time string or a full date-time string as fallback.
+ */
+export function formatRelative(
+  isoUtc: string | null | undefined,
+  timezone: string | null | undefined = DEFAULT_TIMEZONE,
+): string {
+  if (!isoUtc) return "—";
+  try {
+    const then = new Date(isoUtc).getTime();
+    const now = Date.now();
+    const diffSeconds = Math.round((then - now) / 1000);
+    const absDiff = Math.abs(diffSeconds);
+
+    const rtf = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" });
+
+    if (absDiff < 60) return rtf.format(diffSeconds, "second");
+    if (absDiff < 3600) return rtf.format(Math.round(diffSeconds / 60), "minute");
+    if (absDiff < 86400) return rtf.format(Math.round(diffSeconds / 3600), "hour");
+    if (absDiff < 86400 * 30) return rtf.format(Math.round(diffSeconds / 86400), "day");
+    return formatDate(isoUtc, timezone);
+  } catch {
+    return formatDate(isoUtc, timezone);
+  }
+}