@dogsbay/docs-layout 0.2.0-beta.74 → 0.2.0-beta.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/docs-layout",
-  "version": "0.2.0-beta.74",
+  "version": "0.2.0-beta.75",
   "description": "Standard documentation layout components for Dogsbay",
   "type": "module",
   "exports": {
@@ -29,8 +29,8 @@
     "./json-ld": "./src/json-ld.ts"
   },
   "dependencies": {
-    "@dogsbay/ui": "0.2.0-beta.74",
-    "@dogsbay/primitives": "0.2.0-beta.74"
+    "@dogsbay/ui": "0.2.0-beta.75",
+    "@dogsbay/primitives": "0.2.0-beta.75"
   },
   "devDependencies": {
     "vitest": "^3.0.0"

package/src/search-facets.ts

@@ -376,7 +376,16 @@ export function buildFacetTree(
 
   const slashEncoded = entries.some((e) => e.value.includes("/"));
   if (slashEncoded) {
-    return buildSlashTree(facetName, entries, options.display);
+    // When nav is supplied, derive document-order. Otherwise fall
+    // back to count-desc + alpha. The map keys are full cumulative
+    // paths (matching Pagefind entry values 1:1).
+    const navOrder = options.nav
+      ? buildNavOrderMap(
+          options.nav,
+          new Set(entries.map((e) => e.value)),
+        )
+      : undefined;
+    return buildSlashTree(facetName, entries, options.display, navOrder);
   }
   return buildSegmentTree(facetName, entries, options.nav, options.display);
 }
@@ -387,11 +396,20 @@ export function buildFacetTree(
  * nodes. Synthetic intermediate nodes (a path component used by a
  * descendant but absent from `entries`) get `hasValue: false` and
  * `count: 0` so they render but don't contribute to selection.
+ *
+ * Sort order at every depth:
+ *   1. `navOrder` index if present (document order from nav.json).
+ *      Without this, deep API-reference subtrees with high page
+ *      counts would dominate the top of the tree even though they
+ *      sit at the BOTTOM of the rendered nav.
+ *   2. Count desc (more pages → higher).
+ *   3. Alpha (final tiebreak).
  */
 function buildSlashTree(
   facetName: string,
   entries: FacetEntry[],
   display?: TaxonomyDisplayMap,
+  navOrder?: Map<string, number>,
 ): FacetTreeNode[] {
   // Trie keyed by full slash-path. Children are tracked on each
   // node's own `children` array (built unsorted in pass 1, sorted
@@ -428,26 +446,86 @@ function buildSlashTree(
     }
   }
 
-  // Pass 2: sort children at every depth. Mirrors sortFacetEntries
-  // (count desc, alpha tiebreaker).
+  // Pass 2: sort children at every depth.
+  const cmp = (a: FacetTreeNode, b: FacetTreeNode): number => {
+    if (navOrder) {
+      const oa = navOrder.get(a.value);
+      const ob = navOrder.get(b.value);
+      if (oa !== undefined && ob !== undefined && oa !== ob) return oa - ob;
+      // Nodes IN the nav sort before nodes not in nav
+      if (oa !== undefined && ob === undefined) return -1;
+      if (oa === undefined && ob !== undefined) return 1;
+    }
+    if (a.count !== b.count) return b.count - a.count;
+    return a.value.localeCompare(b.value);
+  };
   const sortChildren = (node: FacetTreeNode): void => {
     if (node.children.length === 0) return;
-    node.children.sort((a, b) => {
-      if (a.count !== b.count) return b.count - a.count;
-      return a.value.localeCompare(b.value);
-    });
+    node.children.sort(cmp);
     for (const c of node.children) sortChildren(c);
   };
 
   const rootList = rootValues.map((v) => byPath.get(v)!);
-  rootList.sort((a, b) => {
-    if (a.count !== b.count) return b.count - a.count;
-    return a.value.localeCompare(b.value);
-  });
+  rootList.sort(cmp);
   for (const r of rootList) sortChildren(r);
   return rootList;
 }
 
+/**
+ * Walk `nav` and assign each cumulative slash-path (matching a
+ * Pagefind facet value in `knownValues`) a sequential index in
+ * first-encounter order. Used by `buildSlashTree` to sort children
+ * in document order rather than count-desc.
+ *
+ * Auto-detects and strips a leading basePath: for each nav leaf, we
+ * try each starting offset of the href's parent segments. The first
+ * offset whose initial cumulative path is in `knownValues` is the
+ * "real" content root; the dropped prefix is the basePath. This way
+ * the helper works on any site without needing the basePath threaded
+ * through explicitly.
+ *
+ * Hrefs whose parents don't match anything in `knownValues` at any
+ * offset are skipped (e.g. top-level pages with no auto-derived
+ * category, or pages outside the indexed corpus).
+ *
+ * Exported for use by `buildFacetTree`. Pure — no I/O.
+ */
+export function buildNavOrderMap(
+  nav: NavLike[],
+  knownValues: Set<string>,
+): Map<string, number> {
+  const order = new Map<string, number>();
+  let n = 0;
+  const walk = (items: NavLike[]): void => {
+    for (const item of items) {
+      if (item.href) {
+        const parents = hrefToCategorySegments(item.href);
+        // Try each starting offset; first one whose initial cumulative
+        // path is in knownValues wins (auto-detects basePath).
+        for (let start = 0; start < parents.length; start++) {
+          const first = parents[start];
+          if (!knownValues.has(first)) continue;
+          // Record all cumulative paths starting from `start` that
+          // exist in knownValues. The check at line below filters out
+          // synthetic intermediates the corpus didn't tag (e.g. a
+          // user-supplied frontmatter category that skipped a level).
+          let cumulative = "";
+          for (let i = start; i < parents.length; i++) {
+            cumulative = cumulative ? `${cumulative}/${parents[i]}` : parents[i];
+            if (knownValues.has(cumulative) && !order.has(cumulative)) {
+              order.set(cumulative, n++);
+            }
+          }
+          break;
+        }
+      }
+      if (item.children && item.children.length > 0) walk(item.children);
+    }
+  };
+  walk(nav);
+  return order;
+}
+
 /**
  * Segment-encoded tree builder. Walks `nav` to discover the
  * canonical document hierarchy, then attaches Pagefind counts to