@carlonicora/nextjs-jsonapi 2.1.3 → 2.2.0

package/src/hooks/__tests__/usePageTracker.spec.tsx

@@ -0,0 +1,296 @@
+import { render, waitFor } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { recentPagesAtom, type RecentPage } from "../../atoms";
+import { usePageTracker } from "../usePageTracker";
+
+// usePathname is globally mocked to "/" in vitest.setup.ts. Override it here so
+// navigations can be simulated. A spec-level vi.mock takes precedence.
+//
+// The hook's stale-observer guard reads the REAL browser location
+// (window.location.pathname), not this mock, so every write to
+// pathnameRef.current also pushes the browser history entry. Individual tests
+// still just say `pathnameRef.current = "..."` — this only keeps the two in
+// sync underneath that.
+let _pathname = "/";
+const pathnameRef = {
+  get current() {
+    return _pathname;
+  },
+  set current(value: string) {
+    _pathname = value;
+    window.history.pushState({}, "", value);
+  },
+};
+vi.mock("next/navigation", () => ({
+  usePathname: () => pathnameRef.current,
+  useRouter: () => ({
+    push: vi.fn(),
+    replace: vi.fn(),
+    prefetch: vi.fn(),
+    back: vi.fn(),
+    forward: vi.fn(),
+    refresh: vi.fn(),
+  }),
+  useSearchParams: () => new URLSearchParams(),
+  useParams: () => ({}),
+  redirect: vi.fn(),
+  notFound: vi.fn(),
+}));
+
+vi.mock("../../client/config", () => ({
+  getTrackablePages: () => [
+    { pageUrl: "/npcs", name: "npcs" },
+    { pageUrl: "/campaigns", name: "campaigns" },
+  ],
+}));
+
+function Harness() {
+  usePageTracker();
+  return null;
+}
+
+function mount(store: ReturnType<typeof createStore>) {
+  return render(
+    <Provider store={store}>
+      <Harness />
+    </Provider>,
+  );
+}
+
+function pages(store: ReturnType<typeof createStore>): RecentPage[] {
+  return store.get(recentPagesAtom);
+}
+
+beforeEach(() => {
+  pathnameRef.current = "/";
+  document.title = "Home | App";
+});
+
+describe("usePageTracker", () => {
+  it("records the entity name on a hard load, where the title is already ours", async () => {
+    pathnameRef.current = "/npcs/npc-1";
+    document.title = "[NPC] Charlie | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+
+    mount(store);
+
+    await waitFor(() => expect(pages(store)).toHaveLength(1));
+    expect(pages(store)[0]).toMatchObject({ url: "/npcs/npc-1", title: "Charlie", moduleType: "npcs" });
+  });
+
+  it("never stamps an entity with the previous page's name, then upgrades when the title lands", async () => {
+    // The defect this fixes: the route commits before its streamed metadata, so
+    // document.title still belongs to the page we came from.
+    pathnameRef.current = "/campaigns/camp-1";
+    document.title = "[Campaign] Venezia Obscura | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    const view = mount(store);
+    await waitFor(() => expect(pages(store)[0]?.title).toBe("Venezia Obscura"));
+
+    // Client-side navigate to an NPC. The title has NOT changed yet.
+    pathnameRef.current = "/npcs/npc-1";
+    view.rerender(
+      <Provider store={store}>
+        <Harness />
+      </Provider>,
+    );
+
+    await waitFor(() => expect(pages(store)[0]?.url).toBe("/npcs/npc-1"));
+    expect(pages(store)[0].title).toBe("npcs");
+    expect(pages(store)[0].title).not.toBe("Venezia Obscura");
+
+    // Now the route's own metadata streams in.
+    document.title = "[NPC] Charlie | App";
+
+    await waitFor(() => expect(pages(store)[0]?.title).toBe("Charlie"));
+    expect(pages(store)).toHaveLength(2);
+  });
+
+  it("records the entity name immediately when the title arrives in the same commit as the navigation", async () => {
+    // The prefetched-production ordering: the link's payload (including the new
+    // <title>) is already cached, so React updates the route AND the title in
+    // the same commit. There is no intermediate tick where the NPC's route is
+    // live but document.title still reads the campaign's — which is the signal
+    // the "seed with the module name, let the observer correct it" path above
+    // depends on. This is the exact scenario an earlier version of this test
+    // suite was written to assert and then reordered away from without a guard
+    // in place: it described a real case the code did not yet handle.
+    pathnameRef.current = "/campaigns/camp-1";
+    document.title = "[Campaign] Venezia Obscura | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    const view = mount(store);
+    await waitFor(() => expect(pages(store)[0]?.title).toBe("Venezia Obscura"));
+
+    // Client-side navigate to an NPC. The title has ALREADY changed, before
+    // rerender() is even called.
+    pathnameRef.current = "/npcs/npc-1";
+    document.title = "[NPC] Charlie | App";
+    view.rerender(
+      <Provider store={store}>
+        <Harness />
+      </Provider>,
+    );
+
+    await waitFor(() => expect(pages(store)[0]?.url).toBe("/npcs/npc-1"));
+    expect(pages(store)[0].title).toBe("Charlie");
+    expect(pages(store)[0].title).not.toBe("npcs");
+  });
+
+  it("does not let a stale observer rename the entry we left", async () => {
+    // React runs a route's effect cleanup (disconnecting its observer) as part
+    // of the SAME synchronous flush that mounts the next route's effect — so a
+    // plain `rerender()` in this test harness can never catch the campaign's
+    // observer still connected; cleanup would always have already run by the
+    // time any queued mutation callback got a chance to fire. The real bug
+    // needs the browser to have already moved on (window.location changed)
+    // while the campaign's MutationObserver is still live, i.e. a mutation
+    // that lands and is allowed to flush BEFORE React reconciles the
+    // navigation. So: change the pathname (which pushes real browser history,
+    // see pathnameRef above) and the title, then yield to the microtask queue
+    // — WITHOUT calling rerender() yet — so the still-mounted campaign
+    // effect's observer is the one that receives the mutation, exactly as it
+    // would in production between the DOM commit and the deferred passive
+    // effect cleanup.
+    pathnameRef.current = "/campaigns/camp-1";
+    document.title = "[Campaign] Venezia Obscura | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    const view = mount(store);
+    await waitFor(() => expect(pages(store)[0]?.title).toBe("Venezia Obscura"));
+
+    pathnameRef.current = "/npcs/npc-1";
+    document.title = "[NPC] Charlie | App";
+    // Let the campaign's still-connected observer see this mutation before its
+    // cleanup ever runs.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    const campaignEntry = () => pages(store).find((page) => page.url === "/campaigns/camp-1");
+    expect(campaignEntry()?.title).toBe("Venezia Obscura");
+
+    // Now let React actually reconcile the navigation.
+    view.rerender(
+      <Provider store={store}>
+        <Harness />
+      </Provider>,
+    );
+
+    await waitFor(() => expect(pages(store)[0]?.url).toBe("/npcs/npc-1"));
+    expect(campaignEntry()?.title).toBe("Venezia Obscura");
+  });
+
+  it("ignores head mutations that do not change the resolved title", async () => {
+    pathnameRef.current = "/npcs/npc-1";
+    document.title = "[NPC] Charlie | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    mount(store);
+    await waitFor(() => expect(pages(store)).toHaveLength(1));
+    const firstTimestamp = pages(store)[0].timestamp;
+
+    // Dev servers mutate <head> constantly for HMR styles.
+    const style = document.createElement("style");
+    document.head.appendChild(style);
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(pages(store)).toHaveLength(1);
+    expect(pages(store)[0].timestamp).toBe(firstTimestamp);
+  });
+
+  it("records nothing for a list route with no entity id", async () => {
+    pathnameRef.current = "/npcs";
+    document.title = "[NPC] npcs | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    mount(store);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(pages(store)).toHaveLength(0);
+  });
+
+  it("records nothing for a module that is not trackable", async () => {
+    pathnameRef.current = "/secrets/secret-1";
+    document.title = "[Secret] Hidden | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    mount(store);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(pages(store)).toHaveLength(0);
+  });
+
+  it("stops observing once unmounted", async () => {
+    pathnameRef.current = "/npcs/npc-1";
+    document.title = "[NPC] Charlie | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    const view = mount(store);
+    await waitFor(() => expect(pages(store)[0]?.title).toBe("Charlie"));
+
+    view.unmount();
+    document.title = "[NPC] Bob | App";
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(pages(store)[0].title).toBe("Charlie");
+  });
+
+  it("refreshes an entity's entry from a sub-page without renaming it", async () => {
+    // Sub-pages title themselves after the section — "[Campaign] NPCs Venezia
+    // Obscura" — so they must never overwrite the entity's own name.
+    pathnameRef.current = "/campaigns/camp-1";
+    document.title = "[Campaign] Venezia Obscura | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    const view = mount(store);
+    await waitFor(() => expect(pages(store)[0]?.title).toBe("Venezia Obscura"));
+    const firstTimestamp = pages(store)[0].timestamp;
+
+    pathnameRef.current = "/campaigns/camp-1//npcs";
+    document.title = "[Campaign] NPCs Venezia Obscura | App";
+    view.rerender(
+      <Provider store={store}>
+        <Harness />
+      </Provider>,
+    );
+
+    await waitFor(() => expect(pages(store)[0]?.timestamp).not.toBe(firstTimestamp));
+    expect(pages(store)[0].title).toBe("Venezia Obscura");
+    expect(pages(store)[0].url).toBe("/campaigns/camp-1");
+    expect(pages(store)).toHaveLength(1);
+  });
+
+  it("falls back to the module name when a sub-page is the first thing recorded", async () => {
+    pathnameRef.current = "/campaigns/camp-1//npcs";
+    document.title = "[Campaign] NPCs Venezia Obscura | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    mount(store);
+
+    await waitFor(() => expect(pages(store)).toHaveLength(1));
+    expect(pages(store)[0]).toMatchObject({ url: "/campaigns/camp-1", title: "campaigns" });
+  });
+
+  it("still upgrades the title when the entity's own page is opened later", async () => {
+    pathnameRef.current = "/campaigns/camp-1//npcs";
+    document.title = "[Campaign] NPCs Venezia Obscura | App";
+    const store = createStore();
+    store.set(recentPagesAtom, []);
+    const view = mount(store);
+    await waitFor(() => expect(pages(store)[0]?.title).toBe("campaigns"));
+
+    // Navigate to the entity's own page. As in the real app, the route commits
+    // BEFORE its metadata streams in, so the title still reads the sub-page's
+    // until after the rerender — which is exactly what the observer is for.
+    pathnameRef.current = "/campaigns/camp-1";
+    view.rerender(
+      <Provider store={store}>
+        <Harness />
+      </Provider>,
+    );
+
+    document.title = "[Campaign] Venezia Obscura | App";
+
+    await waitFor(() => expect(pages(store)[0]?.title).toBe("Venezia Obscura"));
+  });
+});

package/src/hooks/usePageTracker.ts

@@ -2,20 +2,40 @@
 
 import { useAtom } from "jotai";
 import { usePathname } from "next/navigation";
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { RecentPage, recentPagesAtom } from "../atoms";
 import { getTrackablePages } from "../client/config";
 
 // Routes to exclude from tracking
 const EXCLUDED_ROUTES = ["/", "/login", "/register", "/forgot-password", "/reset-password", "/activate"];
 
+/**
+ * Detail pages title themselves `[Entity type] Entity name | App name`. Returns
+ * the entity name, or null when the document title is not (yet) a detail-page
+ * title — the normal state for the first tick after a client-side navigation,
+ * before the route's streamed metadata replaces the <title>.
+ */
+function readEntityTitle(): string | null {
+  if (typeof document === "undefined") return null;
+
+  const afterEntityType = document.title.split("]")[1];
+  if (!afterEntityType) return null;
+
+  return afterEntityType.split("|")[0]?.trim() || null;
+}
+
 export function usePageTracker() {
   const pathname = usePathname();
   const [_recentPages, setRecentPages] = useAtom(recentPagesAtom);
+  const previousPathname = useRef<string | null>(null);
+  const previousTitle = useRef<string | null>(null);
 
   useEffect(() => {
     if (!pathname) return;
 
+    const arrivedByClientNavigation = previousPathname.current !== null && previousPathname.current !== pathname;
+    previousPathname.current = pathname;
+
     // Exclude certain routes
     if (EXCLUDED_ROUTES.some((route) => pathname === route || pathname.endsWith(route))) {
       return;
@@ -42,28 +62,97 @@ export function usePageTracker() {
     // Only use base path (module/id), ignoring any sub-paths
     const baseUrl = `/${moduleName}/${entityId}`;
 
-    let pageTitle = foundModule.name;
-    if (typeof document !== "undefined") {
-      const titleParts = document.title.split("]");
-      if (titleParts[1]) {
-        const cleanTitle = titleParts[1].split("|")[0]?.trim();
-        pageTitle = cleanTitle || foundModule.name;
-      }
+    // A parsed title is only trustworthy on the entity's OWN page. Deeper paths
+    // collapse onto the same entry but title themselves after the section —
+    // "[Campaign] NPCs Venezia Obscura" — so they refresh the entry's recency
+    // without renaming it. An entity first seen through a sub-page keeps the
+    // module name until its own page is opened.
+    if (pathParts.length > 2) {
+      setRecentPages((prev) => {
+        const existing = prev.find((page) => page.url === baseUrl);
+        const refreshed: RecentPage = {
+          url: baseUrl,
+          title: existing?.title ?? foundModule.name,
+          moduleType: foundModule.name,
+          timestamp: Date.now(),
+        };
+        return [refreshed, ...prev.filter((page) => page.url !== baseUrl)].slice(0, 10);
+      });
+      // This branch never seeds from document.title, but it must still track it:
+      // the next navigation's "has the title already changed" comparison (below)
+      // is meaningful only when compared against the title we last actually
+      // observed. Leaving previousTitle at whatever it was BEFORE this sub-page
+      // (e.g. still the entity's own page, several navigations back) would
+      // compare the next route's title against the wrong baseline — the
+      // comparison could go either way depending on incidental string overlap,
+      // rather than reflecting whether the next route's title has truly arrived.
+      previousTitle.current = document.title;
+      return;
     }
 
-    const newPage: RecentPage = {
-      url: baseUrl,
-      title: pageTitle,
-      moduleType: foundModule.name,
-      timestamp: Date.now(),
-    };
+    let lastRecordedTitle: string | null = null;
+
+    const record = (pageTitle: string) => {
+      if (pageTitle === lastRecordedTitle) return;
+      lastRecordedTitle = pageTitle;
 
-    setRecentPages((prev) => {
-      // Remove if already exists (to move to top)
-      const filtered = prev.filter((page) => page.url !== newPage.url);
+      const newPage: RecentPage = {
+        url: baseUrl,
+        title: pageTitle,
+        moduleType: foundModule.name,
+        timestamp: Date.now(),
+      };
 
-      // Add to beginning and limit to 10
-      return [newPage, ...filtered].slice(0, 10);
+      setRecentPages((prev) => {
+        // Remove if already exists (to move to top)
+        const filtered = prev.filter((page) => page.url !== newPage.url);
+
+        // Add to beginning and limit to 10
+        return [newPage, ...filtered].slice(0, 10);
+      });
+    };
+
+    // A route commits BEFORE its streamed metadata lands, so on a client-side
+    // navigation document.title normally still belongs to the page we left.
+    // Seeding from it would stamp this entity with the previous entity's name,
+    // so the default is to seed with the module name and let the observer below
+    // correct it once the real title lands. On a hard load the title was
+    // server-rendered into the initial HTML and is already ours.
+    //
+    // But when the route's payload was already prefetched, the new title can
+    // land in the SAME commit as the navigation — there is no later mutation
+    // for the observer to catch, so the module-name fallback would stick
+    // forever. Comparing document.title against the title we last consumed
+    // (previousTitle) distinguishes the two cases: unchanged means it's still
+    // the page we left (ignore it, as above); changed means this route's own
+    // title has already arrived (trust it immediately).
+    const titleAlreadyChanged = document.title !== previousTitle.current;
+    const seededTitle = !arrivedByClientNavigation || titleAlreadyChanged ? readEntityTitle() : null;
+
+    record(seededTitle ?? foundModule.name);
+    previousTitle.current = document.title;
+
+    if (typeof document === "undefined") return;
+
+    const observer = new MutationObserver(() => {
+      // This effect's cleanup (which disconnects this observer) runs as a
+      // passive-effect flush, which React defers to AFTER the current
+      // microtask checkpoint. A MutationObserver callback fires as a
+      // microtask, immediately once its target mutates — including a mutation
+      // that belongs to the NEXT route, if we are still connected when it
+      // lands. Bail if the browser has already moved off this entry's page, so
+      // a stale observer never stamps the next route's title onto this one.
+      // window.location.pathname may carry a locale prefix, hence `includes`.
+      if (!window.location.pathname.includes(baseUrl)) return;
+
+      const title = readEntityTitle();
+      if (title) {
+        record(title);
+        previousTitle.current = document.title;
+      }
     });
+    observer.observe(document.head, { childList: true, subtree: true, characterData: true });
+
+    return () => observer.disconnect();
   }, [pathname, setRecentPages]);
 }