@dogsbay/docs-layout 0.2.0-beta.10 → 0.2.0-beta.100

package/src/nav-filter.ts

@@ -1,18 +1,17 @@
 /**
  * Multi-source nav filtering.
  *
- * When a docs site has multiple versions (or, in PR 5, locales)
- * configured, every page's emitted nav.json contains entries
- * from EVERY version. Without filtering, the sidebar shows
- * duplicate sections — once per version — which is confusing
- * UX (writers see "Glossary" twice).
+ * When a docs site has multiple products/versions/locales, every page's
+ * emitted nav.json contains entries from EVERY bucket. Without filtering,
+ * the sidebar shows a product's sections once per version, and every other
+ * product too — confusing UX. The fix: filter the nav tree to the current
+ * page's (namespace, locale, version) bucket.
  *
- * The fix: filter the nav tree to entries that match the
- * current page's version (or, eventually, locale). Pure
- * function; takes nav + axis filter, returns a pruned copy.
- *
- * The axis switchers handle navigation BETWEEN versions; the
- * sidebar nav reflects only the active axis bucket.
+ * The match is a single COMPOSED prefix in the canonical URL order
+ * `/<basePath>/<namespace>/<locale>/<version>/...` — whichever of those
+ * axes the current page carries. The axis switchers handle navigation
+ * BETWEEN buckets; the sidebar reflects only the active one. Pure
+ * function: nav + filter → pruned copy.
  */
 
 interface NavItem {
@@ -22,145 +21,59 @@ interface NavItem {
 }
 
 export interface NavFilter {
-  /** Site basePath (e.g. "/docs"). Used to compose the version prefix. */
+  /** Site basePath (e.g. "" for root, "/docs"). */
   basePath: string;
-  /**
-   * Current page's effective version. When undefined, no
-   * version filtering is applied — single-version sites pass
-   * the full nav through unchanged.
-   */
-  version?: string;
-  /**
-   * Current page's effective locale. When set, nav items are
-   * filtered to those whose href starts with the corresponding
-   * locale segment (`<basePath>/<locale>/`).
-   */
+  /** Current page's product/namespace segment (outermost), if any. */
+  namespace?: string;
+  /** Current page's locale segment (after namespace), if any. */
   locale?: string;
+  /** Current page's version segment (innermost, next to the page), if any. */
+  version?: string;
 }
 
 /**
- * Walk the nav tree and drop entries that don't belong to the
- * current version + locale. Group nodes (no `href`, with
- * `children`) survive iff any descendant survives — empty
- * groups are pruned.
- *
- * Items without `href` AND without `children` are unusual but
- * pass through unchanged (defensive — never silently drop a
- * node we don't understand).
- *
- * Both filters apply concurrently: a multi-version multi-locale
- * site filters by BOTH simultaneously, so an item must match
- * /<basePath>/<locale>/.../<version>/... structurally.
+ * Prune the nav to the current page's bucket. Group nodes (no `href`,
+ * with `children`) survive iff a descendant survives; empty groups and
+ * childless/href-less nodes are dropped (else a non-current bucket's group
+ * lingers as a phantom header).
  */
-export function filterNavByAxis(
-  items: NavItem[],
-  filter: NavFilter,
-): NavItem[] {
-  if (!filter.version && !filter.locale) return items;
+export function filterNavByAxis(items: NavItem[], filter: NavFilter): NavItem[] {
+  // Canonical order: namespace → locale → version. Only the axes the
+  // current page actually carries contribute to the match prefix.
+  const segs = [filter.namespace, filter.locale, filter.version].filter(
+    (s): s is string => s !== undefined && s !== "",
+  );
+  if (segs.length === 0) return items;
 
-  // Locale axis prefix is the OUTERMOST per the canonical URL
-  // composition: /<basePath>/<locale>/<version>/<ns>/<slug>.
-  // We check the locale prefix first (basePath/<locale>/), then
-  // (when version is also active) check that <version> is the
-  // immediately-following segment.
-  const localePrefix = filter.locale
-    ? prefixFor(filter.basePath, filter.locale)
-    : null;
-  const versionSegment = filter.version ?? null;
+  const base = filter.basePath.replace(/\/$/, "");
+  const prefix = `${base}/${segs.join("/")}/`;
+  const prefixNoSlash = prefix.replace(/\/$/, "");
 
-  return items.flatMap((item) =>
-    filterOne(item, localePrefix, versionSegment, filter.basePath),
-  );
+  return items.flatMap((item) => filterOne(item, prefix, prefixNoSlash));
 }
 
-function filterOne(
-  item: NavItem,
-  localePrefix: string | null,
-  versionSegment: string | null,
-  basePath: string,
-): NavItem[] {
+function filterOne(item: NavItem, prefix: string, prefixNoSlash: string): NavItem[] {
   if (item.children && item.children.length > 0) {
-    const kept = item.children.flatMap((c) =>
-      filterOne(c, localePrefix, versionSegment, basePath),
-    );
+    const kept = item.children.flatMap((c) => filterOne(c, prefix, prefixNoSlash));
     if (kept.length === 0) return [];
     return [{ ...item, children: kept }];
   }
   if (item.href !== undefined) {
-    if (!hrefMatchesAxes(item.href, localePrefix, versionSegment, basePath)) {
-      return [];
-    }
-    return [item];
+    return hrefMatchesPrefix(item.href, prefix, prefixNoSlash) ? [item] : [];
   }
-  return [item];
-}
-
-/**
- * Check that an href belongs to the requested (locale, version)
- * combination. Either prefix can be null — meaning that axis
- * isn't being filtered.
- */
-function hrefMatchesAxes(
-  href: string,
-  localePrefix: string | null,
-  versionSegment: string | null,
-  basePath: string,
-): boolean {
-  // External URLs aren't axis-bucketed.
-  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(href) || href.startsWith("mailto:")) {
-    return false;
-  }
-
-  // Step 1: locale check. If locale axis is active, the href
-  // must be inside /<basePath>/<locale>/.
-  if (localePrefix !== null) {
-    if (!hrefMatchesPrefix(href, localePrefix)) return false;
-  }
-
-  // Step 2: version check. The version segment is positioned
-  // AFTER the locale segment when both are active, otherwise
-  // immediately after basePath.
-  if (versionSegment !== null) {
-    const baseTrimmed = basePath.replace(/\/$/, "");
-    const localeSegStart = localePrefix
-      ? localePrefix.replace(/\/$/, "")
-      : baseTrimmed;
-    const versionPrefix = `${localeSegStart}/${versionSegment}/`;
-    const versionPrefixNoSlash = versionPrefix.replace(/\/$/, "");
-    if (
-      !href.startsWith(versionPrefix) &&
-      href !== versionPrefixNoSlash
-    ) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-/**
- * Compose the URL prefix for a given version under the
- * configured basePath. Always ends in `/` so prefix-matching
- * doesn't accept partial segments (`/docs/v1` shouldn't match
- * `/docs/v10/...`).
- */
-function prefixFor(basePath: string, segment: string): string {
-  const base = basePath.replace(/\/$/, "");
-  return `${base}/${segment}/`;
+  // Childless AND href-less: no navigation, no bucket membership. In a
+  // filtered view it must be dropped.
+  return [];
 }
 
 /**
- * Whether an href belongs to the given version prefix. Tolerates
- * trailing slashes and missing-trailing-slash variants — nav
- * importers don't all canonicalise the same way.
+ * Whether an href belongs to the composed bucket prefix. Tolerates the
+ * bucket's landing page itself (`/<prefix>` with no trailing slash);
+ * external URLs never match.
  */
-function hrefMatchesPrefix(href: string, prefix: string): boolean {
-  // Skip external URLs.
+function hrefMatchesPrefix(href: string, prefix: string, prefixNoSlash: string): boolean {
   if (/^[a-z][a-z0-9+.-]*:\/\//i.test(href) || href.startsWith("mailto:")) {
     return false;
   }
-  // Match `/docs/v1/...` AND `/docs/v1` (the version's landing
-  // page itself, if a writer linked to it directly).
-  const trimmedPrefix = prefix.replace(/\/$/, "");
-  return href.startsWith(prefix) || href === trimmedPrefix;
+  return href.startsWith(prefix) || href === prefixNoSlash;
 }