@carlonicora/nextjs-jsonapi 3.28.2 → 4.0.0

package/src/components/forms/__tests__/EditorSheet.test.tsx

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { act, render, screen } from "@testing-library/react";
+import { Activity } from "react";
 import userEvent from "@testing-library/user-event";
 import { useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
@@ -257,4 +258,27 @@ describe("EditorSheet", () => {
       expect(submitButton).toBeDisabled();
     });
   });
+
+  describe("Activity hide and reveal (back/forward)", () => {
+    it("uncontrolled sheet is closed and the form reset after Activity reveal", async () => {
+      const page = (mode: "visible" | "hidden") => (
+        <Activity mode={mode}>
+          <TestEditor />
+        </Activity>
+      );
+      const r = render(page("visible"));
+
+      await userEvent.click(screen.getByText("ui.buttons.create"));
+      await userEvent.type(screen.getByTestId("name-input"), "Left behind");
+      expect(screen.getByTestId("name-input")).toHaveValue("Left behind");
+
+      act(() => r.rerender(page("hidden")));
+      act(() => r.rerender(page("visible")));
+
+      expect(screen.queryByTestId("name-input")).toBeNull();
+
+      await userEvent.click(screen.getByText("ui.buttons.create"));
+      expect(screen.getByTestId("name-input")).toHaveValue("");
+    });
+  });
 });

package/src/components/forms/__tests__/useEditorDialog.test.ts

@@ -1,7 +1,80 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { renderHook, act } from "@testing-library/react";
+import { renderHook, act, render } from "@testing-library/react";
+import { Activity, StrictMode, createElement, useState } from "react";
 import { useEditorDialog } from "../useEditorDialog";
 
+type ActivityMode = "visible" | "hidden";
+type HookApi = ReturnType<typeof useEditorDialog>;
+
+/**
+ * Mounts a sheet driven by `useEditorDialog` inside a React `<Activity>`, the
+ * way Next 16.4 keeps a route mounted but hidden across back/forward. The page
+ * component sits inside the Activity, so its own state (the parent's
+ * `dialogOpen`) survives the hide exactly as a route's state does.
+ */
+function renderInActivity(opts: {
+  controlled?: boolean;
+  initialParentOpen?: boolean;
+  forceShow?: boolean;
+  strict?: boolean;
+  isFormDirty?: () => boolean;
+  onClose?: () => void;
+}) {
+  const renders: boolean[] = [];
+  const parentSpy = vi.fn();
+  let api!: HookApi;
+  let parentOpen: boolean | undefined;
+  let setParentOpen!: (open: boolean) => void;
+
+  function Sheet(props: { dialogOpen?: boolean; onDialogOpenChange?: (open: boolean) => void }) {
+    api = useEditorDialog(opts.isFormDirty ?? (() => false), {
+      ...props,
+      forceShow: opts.forceShow,
+      onClose: opts.onClose,
+    });
+    renders.push(api.open);
+    return null;
+  }
+
+  function Page() {
+    const [open, setOpen] = useState(opts.initialParentOpen ?? false);
+    parentOpen = open;
+    setParentOpen = setOpen;
+    if (!opts.controlled) return createElement(Sheet);
+    return createElement(Sheet, {
+      dialogOpen: open,
+      onDialogOpenChange: (next: boolean) => {
+        parentSpy(next);
+        setOpen(next);
+      },
+    });
+  }
+
+  function App({ mode }: { mode: ActivityMode }) {
+    return createElement(Activity, { mode }, createElement(Page));
+  }
+
+  // StrictMode only double-invokes effects when it wraps the ROOT element.
+  const root = (mode: ActivityMode) =>
+    opts.strict ? createElement(StrictMode, null, createElement(App, { mode })) : createElement(App, { mode });
+
+  const r = render(root("visible"));
+
+  return {
+    renders,
+    parentSpy,
+    get api() {
+      return api;
+    },
+    get parentOpen() {
+      return parentOpen;
+    },
+    openFromParent: () => act(() => setParentOpen(true)),
+    hide: () => act(() => r.rerender(root("hidden"))),
+    reveal: () => act(() => r.rerender(root("visible"))),
+  };
+}
+
 describe("useEditorDialog", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -281,4 +354,94 @@ describe("useEditorDialog", () => {
       expect(outer.result.current.open).toBe(true);
     });
   });
+
+  describe("Activity hide and reveal (back/forward)", () => {
+    it("controlled sheet does not reopen after Activity reveal", () => {
+      const t = renderInActivity({ controlled: true, initialParentOpen: true });
+      expect(t.api.open).toBe(true);
+      t.parentSpy.mockClear();
+
+      t.hide();
+      const revealedAt = t.renders.length;
+      t.reveal();
+
+      expect(t.parentSpy.mock.calls).toEqual([[false]]);
+      expect(t.parentOpen).toBe(false);
+      expect(t.api.open).toBe(false);
+      expect(t.renders.slice(revealedAt)).not.toContain(true);
+    });
+
+    it("sheet opened after mount is closed after Activity reveal", () => {
+      const t = renderInActivity({});
+      expect(t.api.open).toBe(false);
+      act(() => t.api.setOpen(true));
+      expect(t.api.open).toBe(true);
+
+      t.hide();
+      t.reveal();
+
+      expect(t.api.open).toBe(false);
+    });
+
+    it("forceShow sheet stays closed after Activity reveal", () => {
+      const t = renderInActivity({ forceShow: true });
+      expect(t.api.open).toBe(true);
+
+      t.hide();
+      t.reveal();
+
+      expect(t.api.open).toBe(false);
+    });
+
+    it("stays closed under StrictMode reveal", () => {
+      const t = renderInActivity({ controlled: true, strict: true });
+      t.openFromParent();
+      expect(t.api.open).toBe(true);
+
+      t.hide();
+      const revealedAt = t.renders.length;
+      t.reveal();
+
+      // Strict Mode doubles the notify effect too, so parent calls are not counted.
+      expect(t.renders.slice(revealedAt)).not.toContain(true);
+      expect(t.api.open).toBe(false);
+      expect(t.parentOpen).toBe(false);
+    });
+
+    it("controlled sheet still opens on first mount under StrictMode", () => {
+      const t = renderInActivity({ controlled: true, initialParentOpen: true, strict: true });
+      expect(t.api.open).toBe(true);
+      expect(t.parentOpen).toBe(true);
+    });
+
+    it("discard confirmation is closed after Activity reveal", () => {
+      const t = renderInActivity({ isFormDirty: () => true });
+      act(() => t.api.setOpen(true));
+      act(() => t.api.handleOpenChange(false));
+      expect(t.api.discardDialogProps.open).toBe(true);
+
+      t.hide();
+      t.reveal();
+
+      expect(t.api.discardDialogProps.open).toBe(false);
+      expect(t.api.open).toBe(false);
+    });
+
+    it("onClose is called once per hide and reveal", () => {
+      const onClose = vi.fn();
+      const t = renderInActivity({ onClose });
+      act(() => t.api.setOpen(true));
+      onClose.mockClear();
+
+      t.hide();
+      t.reveal();
+
+      expect(onClose).toHaveBeenCalledTimes(1);
+    });
+
+    it("forceShow sheet still opens on first mount under StrictMode", () => {
+      const t = renderInActivity({ forceShow: true, strict: true });
+      expect(t.api.open).toBe(true);
+    });
+  });
 });

package/src/components/forms/useEditorDialog.ts

@@ -62,11 +62,75 @@ export function useEditorDialog(isFormDirty: () => boolean, options?: UseEditorD
   // each other every render → "Maximum update depth exceeded".
   const syncingFromProp = useRef(false);
 
+  // Mirrors `open` on every render. The reset effect below has an empty
+  // dependency list, so its cleanup closes over the FIRST render's `open`; it
+  // must read the current value from here instead.
+  const openRef = useRef(open);
+  openRef.current = open;
+  const showDiscardRef = useRef(showDiscardConfirm);
+  showDiscardRef.current = showDiscardConfirm;
+
+  // Set by the reset cleanup when the route was hidden with the sheet (or its
+  // discard confirmation) open; consumed by the reset effect on reveal.
+  const hiddenWhileOpen = useRef(false);
+  // Latch armed on reveal: the parent's `dialogOpen` is still the stale `true`
+  // it held when the route was hidden, and must not re-open the sheet. Cleared
+  // by the first `dialogOpen === false`.
+  const ignoreTrueFromParent = useRef(false);
+
+  // Reset when <Activity> hides the route (Next 16.4 keeps routes mounted across
+  // back/forward). After back/forward an editor sheet must be closed with its
+  // form reset, exactly as before 16.4. Measured in React 19.3:
+  //  1. Hiding runs every effect cleanup and revealing re-runs every effect with
+  //     mount semantics, while `useState` survives. A setState in the cleanup is
+  //     applied while hidden, so the sheet is already closed on reveal and
+  //     EditorSheet's close branch resets the form.
+  //  2. An empty-dependency cleanup reads the first render's `open`, hence
+  //     `openRef`.
+  //  3. Effects run in declaration order. This effect is declared BEFORE the
+  //     dialogOpen sync effect, so the latch is armed before the sync effect sees
+  //     the parent's stale `true`; declared after, the sheet re-opens.
+  //  4. It never calls `onDialogOpenChange`. The notify effect re-runs on reveal
+  //     with `open === false` and tells the parent once; calling it here too
+  //     would tell the parent twice.
+  // Strict Mode's fake unmount on first mount finds `openRef` still false, so
+  // the latch is never armed then and a controlled or forceShow sheet still
+  // opens on mount.
+  // A real unmount also runs the cleanup; the setStates on an unmounted
+  // component are no-ops.
+  useEffect(() => {
+    if (hiddenWhileOpen.current) {
+      hiddenWhileOpen.current = false;
+      ignoreTrueFromParent.current = true;
+    }
+    return () => {
+      const wasOpen = openRef.current || showDiscardRef.current;
+      hiddenWhileOpen.current = wasOpen;
+      // Only when something is open: on Strict Mode's fake unmount the
+      // forceShow effect's setOpen(true) is still pending (`openRef` is false),
+      // and an unconditional setOpen(false) here would cancel it for good — the
+      // forceShow guard below does not open again for an unchanged prop.
+      if (wasOpen) {
+        setOpen(false);
+        setShowDiscardConfirm(false);
+      }
+    };
+  }, []);
+
   // Sync open state from external dialogOpen prop.
   // `open` is intentionally NOT a dependency: this effect must run only when the
   // prop changes. Adding `open` would re-fire on internal closes and immediately
   // re-open the dialog (dialogOpen still true while open just went false).
+  // After an <Activity> reveal it also re-runs with mount semantics while the
+  // parent's `dialogOpen` is still the stale `true`: the `ignoreTrueFromParent`
+  // latch drops that `true` until the parent reports `false` (the notify effect
+  // tells it). A latch, not a one-shot flag: under Strict Mode the reveal runs
+  // this effect twice, and a one-shot flag let the second pass re-open the sheet.
   useEffect(() => {
+    if (ignoreTrueFromParent.current) {
+      if (options?.dialogOpen === true) return;
+      if (options?.dialogOpen === false) ignoreTrueFromParent.current = false;
+    }
     if (options?.dialogOpen !== undefined && options.dialogOpen !== open) {
       syncingFromProp.current = true;
       setOpen(options.dialogOpen);
@@ -94,9 +158,12 @@ export function useEditorDialog(isFormDirty: () => boolean, options?: UseEditorD
     onDialogOpenChangeRef.current?.(open);
   }, [open]);
 
-  // Force show
+  // Force show — only on a change to `true`. The effect re-runs on an
+  // <Activity> reveal with the prop unchanged; opening then would undo the reset.
+  const lastForceShow = useRef<boolean | undefined>(undefined);
   useEffect(() => {
-    if (options?.forceShow) setOpen(true);
+    if (options?.forceShow && lastForceShow.current !== true) setOpen(true);
+    lastForceShow.current = options?.forceShow;
   }, [options?.forceShow]);
 
   // Call onClose when dialog closes

package/src/contexts/SessionContext.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { createContext, use, type ReactNode } from "react";
+import type { SessionSnapshot } from "../server/ServerSession";
+
+const SessionContext = createContext<Promise<SessionSnapshot> | null>(null);
+
+export function SessionProvider({ session, children }: { session: Promise<SessionSnapshot>; children: ReactNode }) {
+  return <SessionContext.Provider value={session}>{children}</SessionContext.Provider>;
+}
+
+/**
+ * Unwraps the session promise with `use()`. Suspends the caller until the
+ * promise resolves, so call it only from a leaf behind its own `<Suspense>`.
+ */
+export function useSession(): SessionSnapshot {
+  const session = use(SessionContext);
+  if (!session) throw new Error("useSession must be used within a SessionProvider");
+  return use(session);
+}

package/src/contexts/SocketContext.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import React, { createContext, useContext } from "react";
+import React, { createContext, useContext, useEffect, useState } from "react";
 import { NotificationInterface } from "../features/notification/data";
 import { useSocket } from "../hooks";
+import type { SessionSnapshot } from "../server/ServerSession";
 
 interface SocketContextProps {
   socket: ReturnType<typeof useSocket>["socket"];
@@ -32,11 +33,37 @@ export const SocketContext = createContext<SocketContextProps>(defaultContextVal
 
 interface SocketProviderProps {
   token?: string;
+  /**
+   * The request's session snapshot as a promise. The token is resolved in an
+   * effect, so this provider never suspends and its children render at once;
+   * the socket connects when the promise settles.
+   */
+  session?: Promise<SessionSnapshot>;
   children: React.ReactNode;
 }
 
-export const SocketProvider: React.FC<SocketProviderProps> = ({ token, children }) => {
-  const socketHookData = token ? useSocket({ token }) : null;
+export const SocketProvider: React.FC<SocketProviderProps> = ({ token, session, children }) => {
+  const [sessionToken, setSessionToken] = useState<string | undefined>(undefined);
+
+  useEffect(() => {
+    if (!session) return;
+    let active = true;
+    // Callback form: a server-passed promise's then() returns undefined, so it
+    // cannot be chained (see utils/map-thenable).
+    session.then(
+      (snapshot) => {
+        if (active) setSessionToken(snapshot.token);
+      },
+      () => {},
+    );
+    return () => {
+      active = false;
+    };
+  }, [session]);
+
+  const resolvedToken = token ?? sessionToken;
+  // Called unconditionally: useSocket returns early while the token is falsy.
+  const socketHookData = useSocket({ token: resolvedToken as string });
 
   const sendMessage = (event: string, data: any) => {
     const currentSocket = socketHookData ? socketHookData.socket : defaultContextValue.socket;

package/src/contexts/ViewportContext.tsx

@@ -1,6 +1,8 @@
 "use client";
 
 import * as React from "react";
+import type { SessionSnapshot } from "../server/ServerSession";
+import { mapThenable } from "../utils/map-thenable";
 import { getViewportContext, measureViewport, persistViewport, subscribeViewport } from "../utils/use-mobile";
 
 /**
@@ -24,13 +26,26 @@ import { getViewportContext, measureViewport, persistViewport, subscribeViewport
  */
 export function ViewportProvider({
   initialIsMobile,
+  session,
   children,
 }: {
-  initialIsMobile: boolean;
+  initialIsMobile?: boolean;
+  /**
+   * Alternative to `initialIsMobile` (pass exactly one): the request's session
+   * snapshot as a promise. The provider never awaits it, so its children render
+   * at once; only `useIsMobile()` callers suspend until it settles. The first
+   * client measurement replaces it with a boolean, as with `initialIsMobile`.
+   */
+  session?: Promise<SessionSnapshot>;
   children: React.ReactNode;
 }) {
   const ViewportContext = getViewportContext();
-  const [isMobile, setIsMobile] = React.useState<boolean>(initialIsMobile);
+  const seed = React.useMemo<boolean | Promise<boolean>>(
+    () => (session ? mapThenable(session, (snapshot) => snapshot.isMobile) : (initialIsMobile ?? false)),
+    // Created once: later measurements own the value.
+    [],
+  );
+  const [isMobile, setIsMobile] = React.useState<boolean | Promise<boolean>>(seed);
 
   React.useEffect(
     () =>

package/src/contexts/__tests__/SessionContext.test.tsx

@@ -0,0 +1,58 @@
+import { act, render, renderHook, screen } from "@testing-library/react";
+import { Suspense } from "react";
+import { describe, expect, it } from "vitest";
+import type { SessionSnapshot } from "../../server/ServerSession";
+import { SessionProvider, useSession } from "../SessionContext";
+
+const snapshot: SessionSnapshot = {
+  isLogged: true,
+  isAdministrator: false,
+  token: "t1",
+  sidebarOpen: true,
+  isMobile: false,
+};
+
+function Leaf() {
+  return <span>{useSession().token}</span>;
+}
+
+describe("SessionContext", () => {
+  it("renders children without waiting for the session", () => {
+    render(
+      <SessionProvider session={new Promise<SessionSnapshot>(() => {})}>
+        <p>child</p>
+      </SessionProvider>,
+    );
+
+    expect(screen.getByText("child")).toBeInTheDocument();
+  });
+
+  it("useSession suspends until the promise resolves and then returns it", async () => {
+    let resolve!: (value: SessionSnapshot) => void;
+    const session = new Promise<SessionSnapshot>((r) => {
+      resolve = r;
+    });
+
+    // An async act around the suspending render lets React schedule the retry
+    // when the promise resolves; a plain render() never re-renders the leaf.
+    await act(async () => {
+      render(
+        <SessionProvider session={session}>
+          <Suspense fallback="waiting">
+            <Leaf />
+          </Suspense>
+        </SessionProvider>,
+      );
+    });
+
+    expect(screen.getByText("waiting")).toBeInTheDocument();
+
+    await act(async () => resolve(snapshot));
+
+    expect(screen.getByText("t1")).toBeInTheDocument();
+  });
+
+  it("useSession throws outside a provider", () => {
+    expect(() => renderHook(() => useSession())).toThrow(/SessionProvider/);
+  });
+});

package/src/contexts/__tests__/SocketContext.session.test.tsx

@@ -0,0 +1,77 @@
+import { act, render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { SessionSnapshot } from "../../server/ServerSession";
+
+const { useSocketMock } = vi.hoisted(() => ({
+  useSocketMock: vi.fn((_options: { token?: string }) => ({
+    socket: null,
+    isConnected: false,
+    messages: [],
+    socketNotifications: [],
+    sendMessage: () => {},
+    removeMessage: () => {},
+    removeSocketNotification: () => {},
+    clearMessages: () => {},
+    clearSocketNotifications: () => {},
+  })),
+}));
+
+vi.mock("../../hooks/useSocket", () => ({ useSocket: useSocketMock }));
+
+import { SocketProvider } from "../SocketContext";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+const snapshot = (token: string): SessionSnapshot => ({
+  isLogged: true,
+  isAdministrator: false,
+  token,
+  sidebarOpen: true,
+  isMobile: false,
+});
+
+beforeEach(() => {
+  useSocketMock.mockClear();
+});
+
+describe("SocketProvider with a session", () => {
+  it("renders children before the session resolves", () => {
+    const pending = deferred<SessionSnapshot>();
+    render(
+      <SocketProvider session={pending.promise}>
+        <span>child</span>
+      </SocketProvider>,
+    );
+    expect(screen.getByText("child")).toBeInTheDocument();
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: undefined });
+  });
+
+  it("connects with the token once the session resolves", async () => {
+    const pending = deferred<SessionSnapshot>();
+    render(
+      <SocketProvider session={pending.promise}>
+        <span>child</span>
+      </SocketProvider>,
+    );
+    await act(async () => {
+      pending.resolve(snapshot("t1"));
+      await pending.promise;
+    });
+    expect(useSocketMock).toHaveBeenLastCalledWith({ token: "t1" });
+  });
+
+  it("still accepts a plain token", () => {
+    render(
+      <SocketProvider token="t2">
+        <span>child</span>
+      </SocketProvider>,
+    );
+    expect(useSocketMock.mock.calls[0][0]).toEqual({ token: "t2" });
+  });
+});

package/src/contexts/index.ts

@@ -15,6 +15,7 @@ export * from "./HeaderChildrenContext";
 export * from "./HeaderLeftContentContext";
 export * from "./HeaderLogoContext";
 export * from "./MobileNavigationContext";
+export * from "./SessionContext";
 export * from "./SharedContext";
 export * from "./SocketContext";
 export * from "./ViewportContext";

package/src/core/abstracts/AbstractService.ts

@@ -1,6 +1,7 @@
 import { ApiRequestDataTypeInterface } from "../interfaces/ApiRequestDataTypeInterface";
 import { ApiResponseInterface } from "../interfaces/ApiResponseInterface";
 import { setLastApiResponse } from "./lastApiResponse";
+import { getI18nServerLocale } from "../../i18n/config";
 
 export enum HttpMethod {
   GET = "GET",
@@ -158,8 +159,7 @@ export abstract class AbstractService {
     // Get language based on environment
     let language = "en";
     if (typeof window === "undefined") {
-      const { getLocale } = await import("next-intl/server");
-      language = (await getLocale()) ?? "en";
+      language = await getI18nServerLocale();
     } else {
       // Client-side: extract locale from URL pathname
       language = this.getClientLocale();
@@ -279,8 +279,7 @@ export abstract class AbstractService {
     // Get language based on environment
     let language = "en";
     if (typeof window === "undefined") {
-      const { getLocale } = await import("next-intl/server");
-      language = (await getLocale()) ?? "en";
+      language = await getI18nServerLocale();
     } else {
       // Client-side: extract locale from URL pathname
       language = this.getClientLocale();
@@ -378,8 +377,7 @@ export abstract class AbstractService {
     let language = "en";
 
     if (typeof window === "undefined") {
-      const { getLocale } = await import("next-intl/server");
-      language = (await getLocale()) ?? "en";
+      language = await getI18nServerLocale();
     } else {
       // Client-side: extract locale from URL pathname
       language = this.getClientLocale();

package/src/core/abstracts/__tests__/AbstractService.locale.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// The library must not import next-intl itself: instrumentation loads the library, and
+// next-intl's getLocale pulls in the app's i18n/request.ts, which reads `next/root-params`
+// (only allowed inside the app directory). The locale comes from configureI18n instead.
+const { nextIntlServer, jsonApiGet } = vi.hoisted(() => ({
+  nextIntlServer: vi.fn(),
+  jsonApiGet: vi.fn(),
+}));
+
+vi.mock("next-intl/server", () => {
+  nextIntlServer();
+  return { getLocale: vi.fn(async () => "xx") };
+});
+
+vi.mock("../../../unified/JsonApiRequest", () => ({
+  JsonApiGet: jsonApiGet,
+  JsonApiPost: vi.fn(),
+  JsonApiPut: vi.fn(),
+  JsonApiPatch: vi.fn(),
+  JsonApiDelete: vi.fn(),
+}));
+
+import { configureI18n, type I18nConfig } from "../../../i18n/config";
+import { AbstractService, HttpMethod } from "../AbstractService";
+
+class TestService extends AbstractService {
+  static read() {
+    return this.callApi({ type: { name: "tests" } as any, method: HttpMethod.GET, endpoint: "https://api.test/tests" });
+  }
+}
+
+describe("AbstractService server locale", () => {
+  beforeEach(() => {
+    vi.stubGlobal("window", undefined);
+    jsonApiGet.mockResolvedValue({ ok: true, response: 200, data: [], included: [] });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    configureI18n(null as unknown as I18nConfig);
+  });
+
+  it("reads the server locale from configureI18n, never from next-intl", async () => {
+    configureI18n({
+      useRouter: vi.fn(),
+      useTranslations: vi.fn(),
+      Link: vi.fn() as unknown as I18nConfig["Link"],
+      usePathname: vi.fn(),
+      getLocale: async () => "it",
+    });
+
+    await TestService.read().catch(() => undefined);
+
+    expect(typeof window).toBe("undefined");
+    expect(jsonApiGet).toHaveBeenCalledWith(expect.objectContaining({ language: "it" }));
+    expect(nextIntlServer).not.toHaveBeenCalled();
+  });
+
+  it("fails loudly when configureI18n has no getLocale", async () => {
+    await expect(TestService.read()).rejects.toThrow(/configureI18n/);
+    expect(jsonApiGet).not.toHaveBeenCalled();
+  });
+});

package/src/features/analytics/components/server/AnalyticsAdminPage.tsx

@@ -18,7 +18,11 @@ type Props = {
   deniedRedirect?: string;
 };
 
-/** Server page for the administrative analytics dashboard: role gate, then the client container. */
+/**
+ * Server page for the administrative analytics dashboard: role gate, then the client container.
+ *
+ * Reads the session: render inside a `<Suspense>` boundary (Cache Components).
+ */
 export async function AnalyticsAdminPage({ adminRoleId, pageUrl, sessionPageUrl, deniedRedirect = "/" }: Props) {
   if (!(await ServerSession.hasRole(adminRoleId))) {
     redirect(deniedRedirect);