Added back tiny NavAPI call to track folder title/sortOrder vals

jdcmsd · jdcmsd · commit b669e38245d4 · 2026-04-18T16:33:09.000-04:00
diff --git a/services/docs/getNavSections.ts b/services/docs/getNavSections.ts
@@ -7,7 +7,14 @@ import {
   type ApiNavItem,
   type NavSection,
 } from "@/util/navTransform";
-import { buildMenulinksUrl, navPayloadToApiNavTree } from "@/util/menulinksToApiNav";
+import {
+  applyNavFolderOverlayToMenulinksTree,
+  buildMenulinksUrl,
+  buildNavApiUrl,
+  extractNavApiFolderOverlay,
+  navPayloadToApiNavTree,
+  resortMenulinksDerivedTree,
+} from "@/util/menulinksToApiNav";
 import fallbackNavData from "@/components/navigation/fallback.json";
 
 type FetchOptions = {
@@ -61,12 +68,14 @@ export async function getNavSections(options: FetchOptions = {}): Promise<NavSec
   const folderPath = options.path ?? Config.NavFolderPath;
   const depth = options.depth ?? Config.NavMenuDepth;
   const ttlSeconds = options.ttlSeconds ?? 900;
+  const navOverlayDepth = Config.NavFolderOverlayDepth;
+  const languageId = options.languageId ?? Config.LanguageId;
 
   const pathsCacheKey = getCacheKey(
-    `menulinks|${Config.NavSiteId}|${folderPath}|${depth}|allPaths`
+    `menulinks|${Config.NavSiteId}|${folderPath}|${depth}|nav${navOverlayDepth}|allPaths`
   );
   const slugCacheKey = getCacheKey(
-    `menulinks|${Config.NavSiteId}|${folderPath}|${depth}|${options.currentSlug ?? ""}`
+    `menulinks|${Config.NavSiteId}|${folderPath}|${depth}|nav${navOverlayDepth}|${options.currentSlug ?? ""}`
   );
 
   let sectionsAllForPaths: NavSection[] | undefined =
@@ -80,25 +89,49 @@ export async function getNavSections(options: FetchOptions = {}): Promise<NavSec
 
   try {
     const menulinksUrl = buildMenulinksUrl(Config.DotCMSHost, Config.NavSiteId, folderPath, depth);
-
-    const res = await fetch(menulinksUrl, {
-      method: "GET",
-      headers: Config.Headers,
-      next: { revalidate: ttlSeconds },
-    });
-
-    if (!res.ok) {
+    const navUrl = buildNavApiUrl(Config.DotCMSHost, folderPath, navOverlayDepth, languageId);
+
+    const [mlRes, navRes] = await Promise.all([
+      fetch(menulinksUrl, {
+        method: "GET",
+        headers: Config.Headers,
+        next: { revalidate: ttlSeconds },
+      }),
+      fetch(navUrl, {
+        method: "GET",
+        headers: Config.Headers,
+        next: { revalidate: ttlSeconds },
+      }),
+    ]);
+
+    if (!mlRes.ok) {
       console.warn(
-        `Menulinks API returned ${res.status} ${res.statusText} — falling back to static navigation`,
+        `Menulinks API returned ${mlRes.status} ${mlRes.statusText} — falling back to static navigation`,
         menulinksUrl
       );
       return loadFallbackNavSections(options.currentSlug);
     }
 
-    const json: unknown = await res.json();
+    const json: unknown = await mlRes.json();
 
     const apiTree = navPayloadToApiNavTree(json, folderPath);
 
+    if (navRes.ok) {
+      try {
+        const navJson: unknown = await navRes.json();
+        const overlay = extractNavApiFolderOverlay(navJson, folderPath);
+        applyNavFolderOverlayToMenulinksTree(apiTree, overlay);
+        resortMenulinksDerivedTree(apiTree);
+      } catch (navErr) {
+        console.warn("Nav folder overlay failed — using menulinks-only folder order/titles", navErr);
+      }
+    } else {
+      console.warn(
+        `Nav API returned ${navRes.status} ${navRes.statusText} — menulinks-only folder order/titles`,
+        navUrl
+      );
+    }
+
     if (!sectionsAllForPaths?.length) {
       sectionsAllForPaths = transformApiResponseToNavSections(
         filterApiNavKeepAllLeaves(apiTree)
diff --git a/util/config.ts b/util/config.ts
@@ -31,6 +31,18 @@ export const Config = {
   NavFolderPath: navFolderPath,
   /** Menulinks `depth` (default 2 to match typical plugin queries). */
   NavMenuDepth: Math.max(1, Number(process.env.NEXT_PUBLIC_DOTCMS_NAV_MENU_DEPTH ?? 2) || 2),
+  /**
+   * `GET /api/v1/nav` depth for the folder overlay only (order + titles on synthetic `.nav.*` folders).
+   * DotCMS counts the **requested folder as depth 1**, then each step outward is +1: depth 2 is
+   * immediate children of `/docs/nav`, depth 3 is **grandchildren** (the second tier of section
+   * folders, e.g. under “Getting Started”). Two UI “folder rows” under the nav root therefore need **3** here.
+   * Deeper values add payload (more links under expanded nodes) for little gain unless the tree grows.
+   * Override with `NEXT_PUBLIC_DOTCMS_NAV_FOLDER_OVERLAY_DEPTH`.
+   */
+  NavFolderOverlayDepth: Math.max(
+    1,
+    Number(process.env.NEXT_PUBLIC_DOTCMS_NAV_FOLDER_OVERLAY_DEPTH ?? 3) || 3
+  ),
   GraphqlUrl: process.env.NEXT_PUBLIC_API_GRAPH_URL || ((normalizedDotCMSHost + '/api/v1/graphql') as string),
   AuthToken: process.env.NEXT_PUBLIC_DOTCMS_AUTH_TOKEN as string,
   SwaggerUrl: ((process.env.NEXT_PUBLIC_API_SWAGGER_URL || normalizedDotCMSHost) + '/api/openapi.json') as string,
diff --git a/util/menulinksToApiNav.ts b/util/menulinksToApiNav.ts
@@ -177,16 +177,129 @@ function getOrCreateFolderChild(parent: ApiNavItem, segmentKey: string, orderHin
   return f;
 }
 
+function compareNavSiblings(a: ApiNavItem, b: ApiNavItem): number {
+  if (a.order !== b.order) return a.order - b.order;
+  return a.title.localeCompare(b.title);
+}
+
 function sortTreeRecursive(node: ApiNavItem): void {
-  node.children.sort((a, b) => {
-    if (a.order !== b.order) return a.order - b.order;
-    return a.title.localeCompare(b.title);
-  });
+  node.children.sort(compareNavSiblings);
   for (const c of node.children) {
     if (c.type === "folder") sortTreeRecursive(c);
   }
 }
 
+/** Re-sort siblings after mutating folder `order` (e.g. Nav API overlay). */
+export function resortMenulinksDerivedTree(items: ApiNavItem[]): void {
+  items.sort(compareNavSiblings);
+  for (const c of items) {
+    if (c.type === "folder") sortTreeRecursive(c);
+  }
+}
+
+export type NavFolderOverlayEntry = { order: number; title: string };
+
+/** Path under `navRoot`: `development/apis` (no leading slash, lowercased). */
+export function navHrefToFolderOverlayKey(
+  href: string | undefined,
+  navRoot: string
+): string | null {
+  const h = href?.trim();
+  if (!h) return null;
+  let pathname = h;
+  if (/^https?:\/\//i.test(h) || h.startsWith("//")) {
+    try {
+      pathname = new URL(h.startsWith("//") ? `https:${h}` : h).pathname;
+    } catch {
+      return null;
+    }
+  }
+  const p = pathname.replace(/\/+$/, "");
+  const root = navRoot.trim().replace(/\/+$/, "");
+  const normRoot = root.toLowerCase();
+  const idx = p.toLowerCase().indexOf(normRoot);
+  if (idx === -1) return null;
+  const rest = p.slice(idx + root.length).replace(/^\/+/, "").replace(/\/+$/, "");
+  return rest.length > 0 ? rest.toLowerCase() : null;
+}
+
+function collectNavFolderOverlay(
+  nodes: ApiNavItem[] | undefined,
+  navRoot: string,
+  out: Map<string, NavFolderOverlayEntry>
+): void {
+  if (!nodes?.length) return;
+  for (const n of nodes) {
+    if (n.type === "folder") {
+      const key = navHrefToFolderOverlayKey(n.href, navRoot);
+      if (key) {
+        out.set(key, {
+          order: Number(n.order) || 0,
+          title: (n.title ?? "").trim(),
+        });
+      }
+      collectNavFolderOverlay(n.children, navRoot, out);
+    }
+  }
+}
+
+/**
+ * Folder path → CMS `order` and display title from `GET /api/v1/nav` (menulinks-only trees lack
+ * Nav Tool folder metadata; synthetic titles would otherwise come from slug segments, e.g. "Apis").
+ */
+export function extractNavApiFolderOverlay(
+  navApiJson: unknown,
+  navRoot: string
+): Map<string, NavFolderOverlayEntry> {
+  const out = new Map<string, NavFolderOverlayEntry>();
+  if (!navApiJson || typeof navApiJson !== "object") return out;
+  const children = (navApiJson as { entity?: { children?: ApiNavItem[] } }).entity?.children;
+  if (Array.isArray(children)) {
+    collectNavFolderOverlay(children, navRoot, out);
+  }
+  return out;
+}
+
+/** Mutates menulinks-built folders whose `code` is `.nav.<segment>` (see {@link folderMarker}). */
+export function applyNavFolderOverlayToMenulinksTree(
+  items: ApiNavItem[],
+  overlay: Map<string, NavFolderOverlayEntry>
+): void {
+  const walk = (nodes: ApiNavItem[], pathPrefix: string): void => {
+    for (const node of nodes) {
+      if (node.type !== "folder") continue;
+      const code = node.code ?? "";
+      if (!code.startsWith(".nav.")) {
+        walk(node.children ?? [], pathPrefix);
+        continue;
+      }
+      const seg = code.slice(".nav.".length);
+      const key = pathPrefix ? `${pathPrefix}/${seg}` : seg;
+      const low = key.toLowerCase();
+      const meta = overlay.get(low);
+      if (meta) {
+        node.order = meta.order;
+        if (meta.title) node.title = meta.title;
+      }
+      walk(node.children ?? [], low);
+    }
+  };
+  walk(items, "");
+}
+
+/** Same path pattern as legacy `getNavSections`: `/api/v1/nav/docs/nav?depth=…&languageId=…`. */
+export function buildNavApiUrl(
+  dotcmsHost: string,
+  navPath: string,
+  depth: number,
+  languageId: number
+): string {
+  const base = dotcmsHost.replace(/\/+$/, "");
+  const p = navPath.startsWith("/") ? navPath : `/${navPath}`;
+  const d = Math.max(1, depth);
+  return `${base}/api/v1/nav${p}?depth=${d}&languageId=${languageId}`;
+}
+
 /**
  * Build top-level section folders (ApiNavItem tree) from flat menulinks rows.
  */
diff --git a/util/page.utils.js b/util/page.utils.js
@@ -1,7 +1,14 @@
 import { Config } from "./config";
 import { client } from "./dotcmsClient";
 import { navCache, getCacheKey } from "./cacheService";
-import { buildMenulinksUrl, navPayloadToApiNavTree } from "./menulinksToApiNav";
+import {
+    applyNavFolderOverlayToMenulinksTree,
+    buildMenulinksUrl,
+    buildNavApiUrl,
+    extractNavApiFolderOverlay,
+    navPayloadToApiNavTree,
+    resortMenulinksDerivedTree,
+} from "./menulinksToApiNav";
 import { filterApiNavForMenuAndSlug, filterApiNavKeepAllLeaves } from "./navTransform";
 
 export const fetchPageData = async (params) => {
@@ -27,26 +34,45 @@ export const fetchNavData = async (dataIn) => {
     const depth = dataIn.depth ?? Config.NavMenuDepth;
     const navMenuSlug = dataIn.navMenuSlug ?? dataIn.currentSlug;
 
+    const navOverlayDepth = Config.NavFolderOverlayDepth;
+    const languageId = Config.LanguageId ?? 1;
     const rawCacheKey = getCacheKey(
-        `menulinks|${Config.NavSiteId}|${folderPath}|${depth}|tree`
+        `menulinks|${Config.NavSiteId}|${folderPath}|${depth}|nav${navOverlayDepth}|tree`
     );
 
     let tree = navCache.get(rawCacheKey);
 
     const menulinksUrl = buildMenulinksUrl(Config.DotCMSHost, Config.NavSiteId, folderPath, depth);
+    const navUrl = buildNavApiUrl(Config.DotCMSHost, folderPath, navOverlayDepth, languageId);
 
     try {
         if (!tree) {
-            const res = await fetch(menulinksUrl, {
-                method: "GET",
-                headers: Config.Headers,
-            });
-            if (!res.ok) {
-                console.warn("Menulinks fetch failed:", res.status, menulinksUrl);
+            const [mlRes, navRes] = await Promise.all([
+                fetch(menulinksUrl, {
+                    method: "GET",
+                    headers: Config.Headers,
+                }),
+                fetch(navUrl, {
+                    method: "GET",
+                    headers: Config.Headers,
+                }),
+            ]);
+            if (!mlRes.ok) {
+                console.warn("Menulinks fetch failed:", mlRes.status, menulinksUrl);
                 return { nav: null, navAllForPaths: null };
             }
-            const json = await res.json();
+            const json = await mlRes.json();
             tree = navPayloadToApiNavTree(json, folderPath);
+            if (navRes.ok) {
+                try {
+                    const navJson = await navRes.json();
+                    const overlay = extractNavApiFolderOverlay(navJson, folderPath);
+                    applyNavFolderOverlayToMenulinksTree(tree, overlay);
+                    resortMenulinksDerivedTree(tree);
+                } catch (navErr) {
+                    console.warn("Nav folder overlay failed — using menulinks-only folders", navErr);
+                }
+            }
             if (tree && tree.length > 0) {
                 navCache.set(rawCacheKey, tree, cacheTTL);
             }
