@dogsbay/docs-layout 0.2.0-beta.92 → 0.2.0-beta.94

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;
 }

package/src/switcher.ts

@@ -11,6 +11,14 @@ export interface AxisEntry {
   id: string;
   label?: string;
   eol?: boolean;
+  /** Pre-release mark (version axis only) — the moving next/beta head. */
+  prerelease?: boolean;
+  /**
+   * Served but kept OFF the switcher (version axis only). Marks the number
+   * a `latest` alias points at, so the dropdown shows one "3.32 (latest)"
+   * row instead of both "latest" and "3.32".
+   */
+  hidden?: boolean;
   default?: boolean;
 }
 
@@ -73,9 +81,32 @@ export interface BuildRowsInput {
   multiSource: MultiSourceMeta;
 }
 
+/**
+ * Order two version ids. Compares numeric components left-to-right
+ * (`3.32` > `3.31`, `3.23-2` > `3.23-1`); a non-numeric alias (`latest`,
+ * `next`) sorts ABOVE any numbered version so descending order puts it
+ * first. When NEITHER id has any digits — a non-semver / codename scheme
+ * (`Boron`, `Argon`) — returns 0 so the sort is a no-op and the author's
+ * DECLARED order is preserved (JS sort is stable), rather than silently
+ * alphabetising and putting the newest release at the bottom.
+ */
+export function compareVersionIds(a: string, b: string): number {
+  const na = (a.match(/\d+/g) ?? []).map(Number);
+  const nb = (b.match(/\d+/g) ?? []).map(Number);
+  if (na.length === 0 && nb.length === 0) return 0; // codenames → keep declared order
+  if (na.length === 0) return 1; // alias > number
+  if (nb.length === 0) return -1;
+  const len = Math.max(na.length, nb.length);
+  for (let i = 0; i < len; i++) {
+    const d = (na[i] ?? 0) - (nb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return a.localeCompare(b);
+}
+
 export function buildSwitcherRows(input: BuildRowsInput): SwitcherRow[] {
   const { axis, switcherMap, multiSource } = input;
-  const entries = axis === "version" ? switcherMap.versions : switcherMap.locales;
+  const allEntries = axis === "version" ? switcherMap.versions : switcherMap.locales;
   const currentId =
     axis === "version" ? multiSource.version : multiSource.locale;
   const otherAxis: SwitcherAxis = axis === "version" ? "locale" : "version";
@@ -84,6 +115,56 @@ export function buildSwitcherRows(input: BuildRowsInput): SwitcherRow[] {
 
   const variants = switcherMap.byLogicalKey[logicalKeyFor(multiSource)] ?? [];
 
+  // On a MULTI-PRODUCT (namespace-active) site the declared version list
+  // is the UNION across products, but a page's variants are same-namespace
+  // (the logical key is namespaced). Scope the version switcher to the
+  // versions this page's product actually has, so a Calico page never
+  // offers a Calico-Enterprise version. Single-product sites (no
+  // namespace) keep the full declared list, with fallbacks for pages
+  // missing in some version.
+  let entries = allEntries;
+  if (axis === "version" && multiSource.namespace !== undefined) {
+    const available = new Set(
+      variants.map((v) => v.version).filter((v): v is string => v !== undefined),
+    );
+    entries = allEntries.filter((e) => available.has(e.id) || e.id === currentId);
+  }
+
+  // The version dropdown always reads newest → oldest (3.32, 3.31, …),
+  // regardless of the declared order. Aliases (e.g. "latest") that don't
+  // parse as versions sort to the top, ahead of the numbers.
+  //
+  // `latest` alias + its target: a version marked `hidden` is the number
+  // the `latest` alias points at (Docusaurus's lastVersion). Show ONE row
+  // "3.32 (latest)" (linking to /latest/), derive its label from the hidden
+  // sibling, and drop hidden rows from the dropdown.
+  //
+  // The hidden number is DECLARED but NOT SERVED: `migrate-docusaurus
+  // --latest-alias` emits one source for the newest branch, at `latest`.
+  // That mirrors the source, where `versions: { "3.32": { path: "latest" } }`
+  // REPLACES the segment — docs.tigera.io has /calico/latest/ and no
+  // /calico/3.32/. Serving both invented a URL tree the source never had
+  // and duplicated every page of the newest release (338 on Calico) with
+  // no canonical. So the hidden entry is label-only metadata.
+  //
+  // `currentFoldedIntoLatest` still matters for a corpus that DOES serve
+  // the number (a hand-written config may), so a reader on `/3.32/…` has
+  // the merged `latest` row highlighted rather than no row at all. No
+  // `hidden` sibling → no merge.
+  let currentFoldedIntoLatest = false;
+  if (axis === "version") {
+    entries = [...entries].sort((a, b) => compareVersionIds(b.id, a.id));
+    const hiddenTarget = entries.find((e) => e.hidden && /\d/.test(e.id));
+    currentFoldedIntoLatest = hiddenTarget?.id === currentId;
+    entries = entries
+      .filter((e) => !e.hidden)
+      .map((e) =>
+        e.id === "latest" && hiddenTarget
+          ? { ...e, label: `${hiddenTarget.label ?? hiddenTarget.id} (latest)` }
+          : e,
+      );
+  }
+
   return entries.map((entry) => {
     const match = variants.find((v) => {
       // Match on this axis.
@@ -98,7 +179,7 @@ export function buildSwitcherRows(input: BuildRowsInput): SwitcherRow[] {
     return {
       entry,
       url: match?.url ?? null,
-      isCurrent: entry.id === currentId,
+      isCurrent: entry.id === currentId || (entry.id === "latest" && currentFoldedIntoLatest),
     };
   });
 }