@carlonicora/nextjs-jsonapi 6.23.0 → 6.25.0

package/src/components/tables/cells/cell.dateTime.tsx

@@ -1,13 +1,9 @@
 import { ColumnDef } from "@tanstack/react-table";
-import { useI18nLocale } from "../../../i18n";
+import { useDateFormatter } from "../../../contexts/DateLocaleContext";
 
 function DateTimeCell({ date }: { date: Date }) {
-  const locale = useI18nLocale();
-  return (
-    <span className="text-muted-foreground text-xs">
-      {date.toLocaleString(locale, { dateStyle: "medium", timeStyle: "short", hour12: false })}
-    </span>
-  );
+  const { format } = useDateFormatter();
+  return <span className="text-muted-foreground text-xs">{format(date, "dateTimeMedium")}</span>;
 }
 
 export const cellDateTime = (params: { name: string; title: string }): ColumnDef<any> => {

package/src/contexts/DateLocaleContext.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import * as React from "react";
+import { useI18nLocale } from "../i18n/config";
+import type { SessionSnapshot } from "../server/ServerSession";
+import {
+  type DateFormatStyle,
+  formatDateStyle,
+  formatRelativeDate,
+  resolveDateLocale,
+  usesTwelveHourClock,
+} from "../utils/date-formatter";
+import { mapThenable } from "../utils/map-thenable";
+
+/**
+ * The locale every real-world date is formatted in.
+ *
+ * Signed-in shells pass the request's session promise: the provider maps it to
+ * the `Accept-Language` header once and never awaits it, so its children render
+ * at once; only `useDateLocale()` callers suspend until it settles (the shape of
+ * `ViewportProvider`). Public layouts pass `mode="public"`: the app language,
+ * with all-numeric styles spelled out. Without a provider: the app language.
+ *
+ * THIS LIVES IN `contexts/` for the same reason as `ViewportProvider`: the
+ * server layouts render it directly, so it needs the "use client" boundary that
+ * tsup stamps onto `dist/contexts/*`.
+ */
+export type DateLocaleSource = { mode: "session"; acceptLanguage: Promise<string | undefined> } | { mode: "public" };
+
+const DateLocaleContext = React.createContext<DateLocaleSource | null>(null);
+
+export function DateLocaleProvider(
+  props:
+    | { session: Promise<SessionSnapshot>; mode?: "session"; children: React.ReactNode }
+    | { mode: "public"; session?: never; children: React.ReactNode },
+) {
+  const { session, children } = props;
+  const value = React.useMemo<DateLocaleSource>(
+    () =>
+      props.mode === "public" || !session
+        ? { mode: "public" }
+        : { mode: "session", acceptLanguage: mapThenable(session, (snapshot) => snapshot.acceptLanguage) },
+    // Created once, like ViewportProvider's seed.
+    [],
+  );
+
+  return <DateLocaleContext.Provider value={value}>{children}</DateLocaleContext.Provider>;
+}
+
+/** The provider's raw context value (mapped thenable + mode), read WITHOUT suspending — for re-providing it to a tree rendered outside the provider (sonner toasts). */
+export function useDateLocaleSource(): DateLocaleSource | null {
+  return React.useContext(DateLocaleContext);
+}
+
+export function DateLocaleSourceProvider({
+  value,
+  children,
+}: {
+  value: DateLocaleSource | null;
+  children: React.ReactNode;
+}) {
+  return <DateLocaleContext.Provider value={value}>{children}</DateLocaleContext.Provider>;
+}
+
+export type DateLocale = { locale: string; isPublic: boolean };
+
+/** Suspends on the session (put the caller behind its own `<Suspense>`) when a session provider is above it. */
+export function useDateLocale(): DateLocale {
+  const source = React.useContext(DateLocaleContext);
+  const appLocale = useI18nLocale();
+  const acceptLanguage = source?.mode === "session" ? React.use(source.acceptLanguage) : undefined;
+  const isPublic = source?.mode === "public";
+  const locale = source?.mode === "session" ? resolveDateLocale({ appLocale, acceptLanguage }) : appLocale;
+
+  return React.useMemo(() => ({ locale, isPublic }), [locale, isPublic]);
+}
+
+export type DateFormatter = DateLocale & {
+  format(date: Date | string | undefined, style: DateFormatStyle, options?: { timeZone?: string }): string;
+  relative(date: Date | string, options: { now: Date }): string;
+  twelveHourClock: boolean;
+};
+
+export function useDateFormatter(): DateFormatter {
+  const { locale, isPublic } = useDateLocale();
+
+  return React.useMemo<DateFormatter>(
+    () => ({
+      locale,
+      isPublic,
+      format: (date, style, options) => formatDateStyle({ date, style, locale, timeZone: options?.timeZone, isPublic }),
+      relative: (date, options) => formatRelativeDate({ date, locale, now: options.now }),
+      twelveHourClock: usesTwelveHourClock(locale),
+    }),
+    [locale, isPublic],
+  );
+}
+
+/** undefined on the server render and the first client render; the current time after mount (set in useEffect). */
+export function useMountedNow(): Date | undefined {
+  const [now, setNow] = React.useState<Date | undefined>(undefined);
+  React.useEffect(() => {
+    setNow(new Date());
+  }, []);
+  return now;
+}

package/src/contexts/__tests__/DateLocaleContext.spec.tsx

@@ -0,0 +1,175 @@
+import { act, render, screen } from "@testing-library/react";
+import { Suspense, useEffect, useSyncExternalStore } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureI18n } from "../../i18n/config";
+import type { SessionSnapshot } from "../../server/ServerSession";
+import {
+  type DateLocaleSource,
+  DateLocaleProvider,
+  DateLocaleSourceProvider,
+  useDateFormatter,
+  useDateLocaleSource,
+  useMountedNow,
+} from "../DateLocaleContext";
+
+const sample = new Date("2026-04-25T21:30:00Z");
+
+let appLocale = "en";
+const listeners = new Set<() => void>();
+const setAppLocale = (next: string) => {
+  appLocale = next;
+  listeners.forEach((listener) => listener());
+};
+const useStubLocale = () =>
+  useSyncExternalStore(
+    (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    () => appLocale,
+  );
+
+const snapshot = (acceptLanguage?: string): SessionSnapshot => ({
+  isLogged: true,
+  isAdministrator: false,
+  sidebarOpen: true,
+  isMobile: false,
+  acceptLanguage,
+});
+
+function Probe() {
+  const { format, locale, isPublic } = useDateFormatter();
+  return (
+    <span data-testid="probe" data-locale={locale} data-public={String(isPublic)}>
+      {format(sample, "date", { timeZone: "UTC" })}
+    </span>
+  );
+}
+
+beforeEach(() => {
+  appLocale = "en";
+  configureI18n({
+    useRouter: () => ({
+      push: () => {},
+      replace: () => {},
+      back: () => {},
+      forward: () => {},
+      refresh: () => {},
+      prefetch: () => {},
+    }),
+    useTranslations: () => (key: string) => key,
+    useLocale: useStubLocale,
+    Link: ({ children }) => <>{children}</>,
+    usePathname: () => "/",
+    getLocale: async () => appLocale,
+  });
+});
+
+describe("DateLocaleProvider", () => {
+  it("resolves the browser's regional locale from the session", async () => {
+    const session = Promise.resolve(snapshot("en-GB"));
+    await act(async () => {
+      render(
+        <DateLocaleProvider session={session}>
+          <Suspense fallback={<span>loading</span>}>
+            <Probe />
+          </Suspense>
+        </DateLocaleProvider>,
+      );
+    });
+    expect(await screen.findByTestId("probe")).toHaveTextContent("25/04/2026");
+    expect(screen.getByTestId("probe")).toHaveAttribute("data-locale", "en-GB");
+  });
+
+  it("uses the app language and month-as-word in public mode", () => {
+    render(
+      <DateLocaleProvider mode="public">
+        <Probe />
+      </DateLocaleProvider>,
+    );
+    // Rule 3: the app language ("en"), never the browser's region; numeric "date" becomes dateMedium.
+    expect(screen.getByTestId("probe")).toHaveTextContent("Apr 25, 2026");
+    expect(screen.getByTestId("probe")).toHaveAttribute("data-public", "true");
+    expect(screen.getByTestId("probe")).toHaveAttribute("data-locale", "en");
+  });
+
+  it("falls back to the app language without a provider", () => {
+    render(<Probe />);
+    expect(screen.getByTestId("probe")).toHaveTextContent("04/25/2026");
+    expect(screen.getByTestId("probe")).toHaveAttribute("data-public", "false");
+  });
+
+  it("useDateLocale re-resolves when the app locale changes", async () => {
+    const session = Promise.resolve(snapshot("en-US,en;q=0.9"));
+    await act(async () => {
+      render(
+        <DateLocaleProvider session={session}>
+          <Suspense fallback={<span>loading</span>}>
+            <Probe />
+          </Suspense>
+        </DateLocaleProvider>,
+      );
+    });
+    expect(await screen.findByTestId("probe")).toHaveTextContent("04/25/2026");
+
+    act(() => setAppLocale("it"));
+
+    expect(screen.getByTestId("probe")).toHaveTextContent("25/04/2026");
+    expect(screen.getByTestId("probe")).toHaveAttribute("data-locale", "it");
+  });
+});
+
+describe("useDateLocaleSource + DateLocaleSourceProvider", () => {
+  it("re-provides a captured source to a tree mounted outside the provider", async () => {
+    let captured: DateLocaleSource | null = null;
+    function Capture() {
+      captured = useDateLocaleSource();
+      return null;
+    }
+    const session = Promise.resolve(snapshot("en-GB"));
+    await act(async () => {
+      render(
+        <DateLocaleProvider session={session}>
+          <Capture />
+        </DateLocaleProvider>,
+      );
+    });
+    expect(captured).not.toBeNull();
+
+    await act(async () => {
+      render(
+        <DateLocaleSourceProvider value={captured}>
+          <Suspense fallback={<span>loading</span>}>
+            <Probe />
+          </Suspense>
+        </DateLocaleSourceProvider>,
+      );
+    });
+    expect(await screen.findByTestId("probe")).toHaveTextContent("25/04/2026");
+  });
+});
+
+describe("useMountedNow", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("useMountedNow is undefined until mounted", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(sample);
+    const seen: Array<Date | undefined> = [];
+    function NowProbe() {
+      const now = useMountedNow();
+      useEffect(() => {
+        seen.push(now);
+      });
+      seen.push(now);
+      return null;
+    }
+    render(<NowProbe />);
+    expect(seen[0]).toBeUndefined();
+    const last = seen[seen.length - 1];
+    expect(last).toBeInstanceOf(Date);
+    expect(last?.getTime()).toBe(sample.getTime());
+  });
+});

package/src/contexts/index.ts

@@ -10,6 +10,7 @@ export * from "../features/assistant/contexts/AssistantContext";
 export * from "./ActionBarContext";
 export * from "./BreadcrumbRootContext";
 export * from "./CommonContext";
+export * from "./DateLocaleContext";
 export * from "./DirectionContext";
 export * from "./HeaderChildrenContext";
 export * from "./HeaderLeftContentContext";

package/src/date-locale/index.ts

@@ -0,0 +1,12 @@
+// Client-only barrel for the date-locale hooks, consumed via
+// `@carlonicora/nextjs-jsonapi/date-locale`. Tsup adds a top-level "use client"
+// directive to the bundled output via clientEntries.
+//
+// The same exports are on `@carlonicora/nextjs-jsonapi/contexts`. This entry
+// exists for modules an app loads on the server outside any component tree:
+// the app's `useDateFnsLocale`, handed to `configureI18n` from `config/env.ts`,
+// which every page imports. Importing `contexts` there pulls the contexts bundle,
+// whose shared chunk holds the `next/dynamic` BlockNote import, into that server
+// graph, and Turbopack dev then fails every page with "Parent client reference
+// not found for next/dynamic import". This entry reaches only the light chunks.
+export * from "../contexts/DateLocaleContext";

package/src/features/account-deletion/components/AccountDeletionAdminTrigger.tsx

@@ -5,7 +5,7 @@ import { useTranslations } from "next-intl";
 import { useEffect, useState } from "react";
 import { errorToast } from "../../../components/errors/errorToast";
 import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
-import { useI18nLocale } from "../../../i18n";
+import { useDateFormatter } from "../../../contexts/DateLocaleContext";
 import { getRoleId } from "../../../roles";
 import {
   AlertDialog,
@@ -47,7 +47,7 @@ function matchesConfirmation(status: AccountDeletionInterface, email: string, va
 
 function AccountDeletionAdminTriggerInternal({ user }: AccountDeletionAdminTriggerProps) {
   const t = useTranslations();
-  const locale = useI18nLocale();
+  const dates = useDateFormatter();
   const [status, setStatus] = useState<AccountDeletionInterface | undefined>();
   const [open, setOpen] = useState<boolean>(false);
   const [confirmation, setConfirmation] = useState<string>("");
@@ -69,8 +69,7 @@ function AccountDeletionAdminTriggerInternal({ user }: AccountDeletionAdminTrigg
 
   if (!status) return null;
 
-  const formatDate = (date: Date) =>
-    date.toLocaleDateString(locale, { day: "numeric", month: "long", year: "numeric" });
+  const formatDate = (date: Date) => dates.format(date, "dateLong");
 
   if (status.scheduledAt) {
     return (

package/src/features/analytics/components/AnalyticsJourneyContainer.tsx

@@ -1,9 +1,10 @@
 "use client";
 
 import { useLocale, useTranslations } from "next-intl";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useState } from "react";
 import { DetailField, RoundPageContainer } from "../../../components";
 import { SharedProvider } from "../../../contexts";
+import { useDateFormatter } from "../../../contexts/DateLocaleContext";
 import { Modules } from "../../../core";
 import { usePageUrlGenerator } from "../../../hooks";
 import { BreadcrumbItemData } from "../../../interfaces";
@@ -52,6 +53,7 @@ type Props = {
 export function AnalyticsJourneyContainer({ sessionId, pageUrl = ANALYTICS_ADMIN_PAGE_URL }: Props) {
   const t = useTranslations();
   const locale = useLocale();
+  const dates = useDateFormatter();
   const generateUrl = usePageUrlGenerator();
 
   const [session, setSession] = useState<AnalyticsSessionInterface | undefined>(undefined);
@@ -103,11 +105,6 @@ export function AnalyticsJourneyContainer({ sessionId, pageUrl = ANALYTICS_ADMIN
     };
   }, [sessionId]);
 
-  const dateTime = useMemo(
-    () => new Intl.DateTimeFormat(locale, { dateStyle: "short", timeStyle: "medium" }),
-    [locale],
-  );
-
   /** Time since the previous page view, in the largest whole unit that fits. */
   const formatGap = (milliseconds: number): string => {
     const seconds = Math.max(0, Math.round(milliseconds / 1000));
@@ -166,7 +163,10 @@ export function AnalyticsJourneyContainer({ sessionId, pageUrl = ANALYTICS_ADMIN
                 )}
               </div>
               <div className="grid gap-3 sm:grid-cols-3">
-                <DetailField label={t("analytics.admin.columns.started")} value={dateTime.format(session.startedAt)} />
+                <DetailField
+                  label={t("analytics.admin.columns.started")}
+                  value={dates.format(session.startedAt, "dateTimeSeconds")}
+                />
                 <DetailField label={t("analytics.admin.columns.source")} value={source} />
                 <DetailField label={t("analytics.admin.columns.landing")} value={session.landingRoute} />
                 <DetailField label={t("analytics.admin.columns.device")} value={session.deviceType} />
@@ -205,7 +205,7 @@ export function AnalyticsJourneyContainer({ sessionId, pageUrl = ANALYTICS_ADMIN
                         return (
                           <TableRow key={pageView.id} data-testid={`analytics-pageview-row-${pageView.id}`}>
                             <TableCell className="text-xs tabular-nums">
-                              {dateTime.format(pageView.createdAt)}
+                              {dates.format(pageView.createdAt, "dateTimeSeconds")}
                             </TableCell>
                             <TableCell className="text-end text-xs tabular-nums">
                               {previous ? formatGap(pageView.createdAt.getTime() - previous.createdAt.getTime()) : "—"}

package/src/features/analytics/components/AnalyticsSessionsTable.tsx

@@ -1,7 +1,7 @@
 "use client";
 
-import { useLocale, useTranslations } from "next-intl";
-import { useMemo } from "react";
+import { useTranslations } from "next-intl";
+import { useDateFormatter } from "../../../contexts/DateLocaleContext";
 import { usePageUrlGenerator } from "../../../hooks";
 import { Badge, Button, Link, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../shadcnui";
 import { useUsageFormatters } from "../../tokenusage/lib/formatters";
@@ -28,12 +28,10 @@ const VISITOR_SUFFIX_LENGTH = 6;
  */
 export function AnalyticsSessionsTable({ rows, sessionPageUrl, onLoadMore, hasMore }: Props) {
   const t = useTranslations();
-  const locale = useLocale();
+  const dates = useDateFormatter();
   const generateUrl = usePageUrlGenerator();
   const { decimal } = useUsageFormatters();
 
-  const dateTime = useMemo(() => new Intl.DateTimeFormat(locale, { dateStyle: "short", timeStyle: "short" }), [locale]);
-
   if (rows.length === 0) {
     return <p className="text-muted-foreground text-sm">{t("analytics.admin.no_data")}</p>;
   }
@@ -66,7 +64,7 @@ export function AnalyticsSessionsTable({ rows, sessionPageUrl, onLoadMore, hasMo
                       href={generateUrl({ page: sessionPageUrl, id: row.id })}
                       data-testid={`analytics-session-link-${row.id}`}
                     >
-                      {dateTime.format(row.startedAt)}
+                      {dates.format(row.startedAt, "dateTime")}
                     </Link>
                   </TableCell>
                   <TableCell className="text-xs">

package/src/features/auth/components/two-factor/PasskeyList.tsx

@@ -4,7 +4,7 @@ import { Edit, Key, Trash2 } from "lucide-react";
 import { useTranslations } from "next-intl";
 import { useState } from "react";
 import { errorToast } from "../../../../components/errors/errorToast";
-import { useI18nLocale } from "../../../../i18n";
+import { useDateFormatter } from "../../../../contexts/DateLocaleContext";
 import {
   AlertDialog,
   AlertDialogAction,
@@ -34,7 +34,7 @@ interface PasskeyListProps {
 
 export function PasskeyList({ passkeys, onRefresh }: PasskeyListProps) {
   const t = useTranslations();
-  const locale = useI18nLocale();
+  const dates = useDateFormatter();
   const [renameDialogOpen, setRenameDialogOpen] = useState(false);
   const [selectedPasskey, setSelectedPasskey] = useState<PasskeyInterface | null>(null);
   const [newName, setNewName] = useState("");
@@ -108,7 +108,7 @@ export function PasskeyList({ passkeys, onRefresh }: PasskeyListProps) {
                 <p className="text-sm text-muted-foreground">
                   {passkey.backedUp && "☁️ "}
                   {passkey.lastUsedAt
-                    ? `${t("auth.two_factor.last_used")}: ${new Date(passkey.lastUsedAt).toLocaleDateString(locale)}`
+                    ? `${t("auth.two_factor.last_used")}: ${dates.format(passkey.lastUsedAt, "dateMedium")}`
                     : t("auth.two_factor.never_used")}
                 </p>
               </div>

package/src/features/auth/components/two-factor/TotpAuthenticatorList.tsx

@@ -4,7 +4,7 @@ import { Smartphone, Trash2 } from "lucide-react";
 import { useTranslations } from "next-intl";
 import { useState } from "react";
 import { errorToast } from "../../../../components/errors/errorToast";
-import { useI18nLocale } from "../../../../i18n";
+import { useDateFormatter } from "../../../../contexts/DateLocaleContext";
 import {
   AlertDialog,
   AlertDialogAction,
@@ -30,7 +30,7 @@ interface TotpAuthenticatorListProps {
 
 export function TotpAuthenticatorList({ authenticators, onDelete }: TotpAuthenticatorListProps) {
   const t = useTranslations();
-  const locale = useI18nLocale();
+  const dates = useDateFormatter();
   const [deletingId, setDeletingId] = useState<string | null>(null);
 
   const handleDelete = async (id: string) => {
@@ -64,7 +64,7 @@ export function TotpAuthenticatorList({ authenticators, onDelete }: TotpAuthenti
                 <p className="font-medium">{auth.name}</p>
                 {auth.lastUsedAt && (
                   <p className="text-xs text-muted-foreground">
-                    {t("auth.two_factor.last_used")}: {auth.lastUsedAt.toLocaleDateString(locale)}
+                    {t("auth.two_factor.last_used")}: {dates.format(auth.lastUsedAt, "dateMedium")}
                   </p>
                 )}
               </div>

package/src/features/billing/components/utils/__tests__/billing-formatters.spec.ts

@@ -41,17 +41,25 @@ describe("formatCurrency", () => {
 describe("formatDate", () => {
   const date = new Date(2025, 0, 15, 12);
 
-  it("uses en-GB day-month order without options", () => {
-    expect(formatDate(date)).toBe("15 Jan 2025");
+  it("uses the app language without options (no forced en-GB)", () => {
+    expect(formatDate(date)).toBe("Jan 15, 2025");
     expect(formatDate(undefined)).toBe("N/A");
     expect(formatDate(new Date("not a date"))).toBe("Invalid Date");
   });
 
-  it("maps the English app locale to en-GB, never US order", () => {
+  it("formats with the app language when no dateLocale is given", () => {
     const feb6 = new Date(2026, 1, 6, 12);
-    expect(formatDate(feb6, { locale: "en", t })).toBe("6 Feb 2026");
-    expect(formatDate(feb6, { locale: "en-US", t })).toBe("6 Feb 2026");
-    expect(formatDate("2026-02-06T12:00:00Z", { locale: "en", t })).toBe("6 Feb 2026");
+    expect(formatDate(feb6, { locale: "en", t })).toBe("Feb 6, 2026");
+    expect(formatDate(feb6, { locale: "en-US", t })).toBe("Feb 6, 2026");
+    expect(formatDate("2026-02-06T12:00:00Z", { locale: "en", t })).toBe("Feb 6, 2026");
+  });
+
+  it("uses the resolved dateLocale over the app language", () => {
+    const apr25 = new Date("2026-04-25T12:00:00Z");
+    expect(formatDate(apr25, { locale: "en", dateLocale: "en-GB" })).toBe("25 Apr 2026");
+    expect(formatDate(apr25, { locale: "en" })).toBe("Apr 25, 2026");
+    expect(formatDate(apr25, { locale: "it" })).toBe("25 apr 2026");
+    expect(formatDate(undefined, { locale: "en", dateLocale: "en-GB" })).toBe("N/A");
   });
 
   it("formats Italian with the Italian locale", () => {

package/src/features/billing/components/utils/date.ts

@@ -4,19 +4,19 @@ import { BillingFormatOptions } from "./format-options";
 /**
  * Format a date to a localized date string
  * @param date - Date object or ISO string
- * @param options - `locale` is the app locale, mapped through `dateFormatLocale` (English and
- *   no locale give "en-GB"); `t` translates the placeholder shown for a missing or invalid date
+ * @param options - `dateLocale` is the resolved regional locale; without it `locale` (the app
+ *   locale) is mapped through `dateFormatLocale` (no locale gives "en"); `t` translates the placeholder shown for a missing or invalid date
  *   (default English)
- * @returns Formatted date string (e.g., "15 Jan 2025", "15 gen 2025")
+ * @returns Formatted date string (e.g., "Jan 15, 2025", "15 Jan 2025", "15 gen 2025")
  */
 export function formatDate(date: Date | string | undefined, options: BillingFormatOptions = {}): string {
-  const { locale, t } = options;
+  const { locale, dateLocale, t } = options;
   if (!date) return t ? t("billing.ui.not_available") : "N/A";
 
   const dateObj = typeof date === "string" ? new Date(date) : date;
 
   try {
-    return new Intl.DateTimeFormat(dateFormatLocale(locale), {
+    return new Intl.DateTimeFormat(dateLocale ?? dateFormatLocale(locale), {
       month: "short",
       day: "numeric",
       year: "numeric",

package/src/features/billing/components/utils/format-options.ts

@@ -6,14 +6,16 @@ export type BillingTranslator = (key: string, values?: Record<string, any>) => s
  * formatters are plain functions and cannot call hooks, so a component reads
  * `useI18nLocale()` and `useTranslations()` and passes both here.
  *
- * Both are optional so existing callers keep their output: without a `locale`
- * the number formatters use "en-US" and `formatDate` uses "en-GB" (via
- * `dateFormatLocale`), without `t` they return the English literals they always
- * returned.
+ * All are optional so existing callers keep their output: without a `locale`
+ * the number formatters use "en-US"; `formatDate` uses `dateLocale`, else
+ * `dateFormatLocale(locale)` (the app language, "en" without one); without `t`
+ * they return the English literals they always returned.
  */
 export type BillingFormatOptions = {
   /** BCP 47 locale for `Intl` (the app's active locale, from `useI18nLocale()`). */
   locale?: string;
+  /** BCP 47 locale for dates only (the resolved regional locale, from `useDateFormatter().locale`). Numbers keep `locale`. */
+  dateLocale?: string;
   /** Translator for the words the formatters emit. */
   t?: BillingTranslator;
 };

package/src/features/billing/components/utils/useBillingFormatOptions.ts

@@ -1,11 +1,17 @@
 import { useTranslations } from "next-intl";
 import { useMemo } from "react";
+import { useDateFormatter } from "../../../../contexts/DateLocaleContext";
 import { useI18nLocale } from "../../../../i18n";
 import { BillingFormatOptions } from "./format-options";
 
-/** The active locale and translator, ready to pass to the billing formatters. */
+/**
+ * The active locale, the resolved date locale and the translator, ready to pass to the billing
+ * formatters. Suspends on the session under a session `DateLocaleProvider` (via
+ * `useDateFormatter()`), so its callers sit behind a page `loading.tsx` or their own `<Suspense>`.
+ */
 export function useBillingFormatOptions(): Required<BillingFormatOptions> {
   const t = useTranslations();
   const locale = useI18nLocale();
-  return useMemo(() => ({ locale, t }), [locale, t]);
+  const { locale: dateLocale } = useDateFormatter();
+  return useMemo(() => ({ locale, dateLocale, t }), [locale, dateLocale, t]);
 }

package/src/features/billing/stripe-usage/components/details/UsageSummaryCard.tsx

@@ -3,7 +3,7 @@
 import { useTranslations } from "next-intl";
 import { Activity } from "lucide-react";
 import { Card, CardContent, CardHeader } from "../../../../../shadcnui";
-import { dateFormatLocale } from "../../../../../utils";
+import { formatDateStyle } from "../../../../../utils";
 import { type BillingFormatOptions, formatFixed, useBillingFormatOptions } from "../../../components/utils";
 import { MeterInterface, MeterSummaryInterface } from "../../data/stripe-usage.interface";
 
@@ -23,19 +23,11 @@ function getProgressColor(percentage: number | null): string {
 }
 
 /**
- * Format a Unix timestamp to readable date
+ * Format a period boundary in the resolved date locale
  */
-function formatDate(date: Date | undefined, { locale, t }: Required<BillingFormatOptions>): string {
+function formatDate(date: Date | undefined, { dateLocale, t }: Required<BillingFormatOptions>): string {
   if (!date) return t("billing.ui.not_available");
-
-  try {
-    return new Intl.DateTimeFormat(dateFormatLocale(locale), {
-      month: "short",
-      day: "numeric",
-    }).format(new Date(date));
-  } catch (_error) {
-    return t("billing.ui.invalid_date");
-  }
+  return formatDateStyle({ date, style: "dateMedium", locale: dateLocale }) || t("billing.ui.invalid_date");
 }
 
 export function UsageSummaryCard({ meter, summary }: UsageSummaryCardProps) {