@carlonicora/nextjs-jsonapi 6.14.0 → 6.15.0

package/src/components/editors/server/__tests__/renderBlockNoteMarkdown.spec.ts

@@ -0,0 +1,45 @@
+// @vitest-environment node
+// The server render runs in Node, where there is no window or document of our own:
+// BlockNote's ServerBlockNoteEditor brings its JSDOM.
+import type { PartialBlock } from "@blocknote/core";
+import { describe, expect, it } from "vitest";
+import { renderBlockNoteHTML } from "../renderBlockNoteHTML";
+import { renderBlockNoteMarkdown } from "../renderBlockNoteMarkdown";
+
+const blocks: PartialBlock[] = [
+  { type: "heading", props: { level: 2 }, content: "Think of the Campaign as the lid on the box" },
+  { type: "paragraph", content: "One Campaign is one story arc." },
+  { type: "bulletListItem", content: "Characters" },
+  {
+    type: "paragraph",
+    content: [{ type: "link", href: "https://wyrd.li/help", content: "help" }],
+  },
+  { type: "image", props: { url: "https://wyrd.li/marketing/og.png", caption: "Wyrdli" } },
+  { type: "image", props: { url: "https://wyrd.li/marketing/plain.png" } },
+];
+
+describe("renderBlockNoteMarkdown", () => {
+  it("renders headings, paragraphs, bullet lists and links", async () => {
+    const markdown = await renderBlockNoteMarkdown(blocks);
+
+    expect(markdown).toContain("## Think of the Campaign as the lid on the box");
+    expect(markdown).toContain("One Campaign is one story arc.");
+    expect(markdown).toMatch(/^\s*[-*+] Characters\s*$/m);
+    expect(markdown).toContain("[help](https://wyrd.li/help)");
+    // blocksToMarkdownLossy keeps a captioned image as an HTML <figure> (valid
+    // CommonMark HTML block); an image with no caption becomes ![](url).
+    expect(markdown).toMatch(/<img[^>]*src="https:\/\/wyrd\.li\/marketing\/og\.png"/);
+    expect(markdown).toContain("<figcaption>Wyrdli</figcaption>");
+    expect(markdown).toMatch(/!\[[^\]]*\]\(https:\/\/wyrd\.li\/marketing\/plain\.png\)/);
+  });
+
+  it("two overlapping calls both resolve and leave no JSDOM window on globalThis", async () => {
+    const before = typeof (globalThis as { window?: unknown }).window;
+
+    const [markdown, html] = await Promise.all([renderBlockNoteMarkdown(blocks), renderBlockNoteHTML(blocks)]);
+
+    expect(markdown).toContain("One Campaign is one story arc.");
+    expect(html).toContain("One Campaign is one story arc.");
+    expect(typeof (globalThis as { window?: unknown }).window).toBe(before);
+  });
+});

package/src/components/editors/server/renderBlockNoteHTML.ts

@@ -1,26 +1,10 @@
 import type { PartialBlock } from "@blocknote/core";
-import { ServerBlockNoteEditor } from "@blocknote/server-util";
-
-// Default schema only, the same one BlockNoteViewer uses: the editor's mention
-// and diff inline specs are React specs from "use client" modules (next/link,
-// hover cards), so they cannot run here.
-let editor: ServerBlockNoteEditor | undefined;
-
-// ServerBlockNoteEditor swaps globalThis.window/document for its JSDOM around
-// each call and restores them after an await. Two overlapping calls would
-// restore each other's values and could leave the JSDOM window on the server's
-// globals, so calls run one at a time.
-let queue: Promise<unknown> = Promise.resolve();
+import { runWithServerEditor } from "./serverEditor";
 
 /**
  * Renders a BlockNote blocks array to the HTML the editor itself would render,
  * through BlockNote's own server editor (`blocksToFullHTML`). Server only.
  */
 export function renderBlockNoteHTML(blocks: PartialBlock[]): Promise<string> {
-  const run = queue.then(() => {
-    editor ??= ServerBlockNoteEditor.create();
-    return editor.blocksToFullHTML(blocks);
-  });
-  queue = run.catch(() => undefined);
-  return run;
+  return runWithServerEditor((editor) => editor.blocksToFullHTML(blocks));
 }

package/src/components/editors/server/renderBlockNoteMarkdown.ts

@@ -0,0 +1,10 @@
+import type { PartialBlock } from "@blocknote/core";
+import { runWithServerEditor } from "./serverEditor";
+
+/**
+ * Renders a BlockNote blocks array to Markdown through BlockNote's own server
+ * editor (`blocksToMarkdownLossy`). Server only.
+ */
+export function renderBlockNoteMarkdown(blocks: PartialBlock[]): Promise<string> {
+  return runWithServerEditor((editor) => editor.blocksToMarkdownLossy(blocks));
+}

package/src/components/editors/server/serverEditor.ts

@@ -0,0 +1,25 @@
+import { ServerBlockNoteEditor } from "@blocknote/server-util";
+
+// Default schema only, the same one BlockNoteViewer uses: the editor's mention
+// and diff inline specs are React specs from "use client" modules (next/link,
+// hover cards), so they cannot run here.
+let editor: ServerBlockNoteEditor | undefined;
+
+// ServerBlockNoteEditor swaps globalThis.window/document for its JSDOM around
+// each call and restores them after an await. Two overlapping calls would
+// restore each other's values and could leave the JSDOM window on the server's
+// globals, so calls run one at a time.
+let queue: Promise<unknown> = Promise.resolve();
+
+/**
+ * Runs `fn` with the shared server editor, one call at a time. Server only.
+ * Internal to the library: not exported from the barrel.
+ */
+export function runWithServerEditor<T>(fn: (editor: ServerBlockNoteEditor) => T | Promise<T>): Promise<T> {
+  const run = queue.then(() => {
+    editor ??= ServerBlockNoteEditor.create();
+    return fn(editor);
+  });
+  queue = run.catch(() => undefined);
+  return run;
+}

package/src/components/editors/server-entry.ts

@@ -5,3 +5,4 @@
 // `serverExternalPackages` so Node loads it instead of the bundler.
 
 export { BlockNoteServerContent } from "./server/BlockNoteServerContent";
+export { renderBlockNoteMarkdown } from "./server/renderBlockNoteMarkdown";

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

@@ -299,4 +299,65 @@ describe("usePageTracker", () => {
 
     await waitFor(() => expect(pages(store)[0]?.title).toBe("Venezia Obscura"));
   });
+
+  describe("most-specific-first titles (`Name · Type · Context | App`)", () => {
+    it("records the entity name on a hard load", async () => {
+      pathnameRef.current = "/npcs/npc-1";
+      document.title = "Charlie · NPC · Venezia Obscura | 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("records a single-part title such as a campaign's", async () => {
+      pathnameRef.current = "/campaigns/camp-1";
+      document.title = "Venezia Obscura | App";
+      const store = createStore();
+      store.set(recentPagesAtom, []);
+
+      mount(store);
+
+      await waitFor(() => expect(pages(store)[0]?.title).toBe("Venezia Obscura"));
+    });
+
+    it("never stamps an entity with the previous page's name, then upgrades when the title lands", async () => {
+      pathnameRef.current = "/campaigns/camp-1";
+      document.title = "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";
+      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");
+
+      document.title = "Charlie · NPC · Venezia Obscura | App";
+
+      await waitFor(() => expect(pages(store)[0]?.title).toBe("Charlie"));
+      expect(pages(store).find((page) => page.url === "/campaigns/camp-1")?.title).toBe("Venezia Obscura");
+    });
+
+    it("keeps the module name when the title is only the app name", async () => {
+      pathnameRef.current = "/npcs/npc-1";
+      document.title = "App";
+      const store = createStore();
+      store.set(recentPagesAtom, []);
+
+      mount(store);
+
+      await waitFor(() => expect(pages(store)).toHaveLength(1));
+      expect(pages(store)[0].title).toBe("npcs");
+    });
+  });
 });

package/src/hooks/usePageTracker.ts

@@ -10,18 +10,28 @@ import { getTrackablePages } from "../client/config";
 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>.
+ * Detail pages title themselves in one of two shapes:
+ *
+ *   `[Entity type] Entity name | App name`        (bracketed)
+ *   `Entity name · Entity type · Context | App name` (most-specific-first)
+ *
+ * Returns the entity name, or null when the document title carries no page
+ * name — just the bare app name. Whether the title belongs to THIS route (and
+ * not the page we left) is decided by the caller, not here.
  */
 function readEntityTitle(): string | null {
   if (typeof document === "undefined") return null;
 
-  const afterEntityType = document.title.split("]")[1];
-  if (!afterEntityType) return null;
+  const title = document.title;
 
-  return afterEntityType.split("|")[0]?.trim() || null;
+  if (title.includes("]")) {
+    const afterEntityType = title.split("]")[1];
+    return afterEntityType?.split("|")[0]?.trim() || null;
+  }
+
+  if (!title.includes("|")) return null;
+
+  return title.split("|")[0].split("·")[0]?.trim() || null;
 }
 
 export function usePageTracker() {