@dogsbay/docs-layout 0.2.0-beta.14 → 0.2.0-beta.140

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,87 @@ 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.
-   */
+  /** 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;
   /**
-   * Current page's effective locale. When set, nav items are
-   * filtered to those whose href starts with the corresponding
-   * locale segment (`<basePath>/<locale>/`).
+   * The version served at the site root (`versions[].path: ""`): its pages
+   * have no version segment. When `version` is this one, the bucket is the
+   * namespace/locale prefix minus the other versions' folders
+   * (`versionSegments`) — the longest matching prefix wins.
    */
-  locale?: string;
+  rootVersion?: string;
+  /** The other versions' URL segments, left out of the root version's bucket. */
+  versionSegments?: 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.
+ * The root-version fields of a `NavFilter`, from the switcherMap header
+ * (`versions[].root`). Empty when no version is served at the root.
  */
-export function filterNavByAxis(
-  items: NavItem[],
-  filter: NavFilter,
-): NavItem[] {
-  if (!filter.version && !filter.locale) 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;
+export function rootVersionFilter(
+  versions: Array<{ id: string; root?: boolean }> | undefined,
+): Pick<NavFilter, "rootVersion" | "versionSegments"> {
+  const root = versions?.find((v) => v.root)?.id;
+  if (!root) return {};
+  return { rootVersion: root, versionSegments: versions!.map((v) => v.id).filter((id) => id !== root) };
+}
 
-  return items.flatMap((item) =>
-    filterOne(item, localePrefix, versionSegment, filter.basePath),
+/**
+ * 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[] {
+  // Canonical order: namespace → locale → version. Only the axes the
+  // current page actually carries contribute to the match prefix.
+  const atRoot = filter.rootVersion !== undefined && filter.version === filter.rootVersion;
+  const segs = [filter.namespace, filter.locale, atRoot ? undefined : filter.version].filter(
+    (s): s is string => s !== undefined && s !== "",
   );
+  // The root version's bucket leaves out the other versions' folders under its prefix.
+  const others = atRoot ? (filter.versionSegments ?? []).filter((v) => v && v !== filter.rootVersion) : [];
+  if (segs.length === 0 && others.length === 0) return items;
+
+  const base = filter.basePath.replace(/\/$/, "");
+  const prefix = `${base}/${segs.join("/")}${segs.length ? "/" : ""}`;
+  const prefixNoSlash = segs.length ? prefix.replace(/\/$/, "") : base || "/";
+  const excluded = others.map((v) => `${prefix}${v}`);
+
+  return items.flatMap((item) => filterOne(item, prefix, prefixNoSlash, excluded));
 }
 
-function filterOne(
-  item: NavItem,
-  localePrefix: string | null,
-  versionSegment: string | null,
-  basePath: string,
-): NavItem[] {
+function filterOne(item: NavItem, prefix: string, prefixNoSlash: string, excluded: 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, excluded));
     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) &&
+      !excluded.some((x) => hrefMatchesPrefix(item.href!, `${x}/`, x))
+      ? [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/pagefind-base-url.ts

@@ -0,0 +1,59 @@
+/**
+ * Pagefind result URLs, and the base they need.
+ *
+ * Pagefind stores each page's URL relative to the directory it indexed
+ * (`pagefind --site dist`), then prefixes every result with `baseUrl`. When
+ * the caller sets none, Pagefind derives it from where the bundle was loaded:
+ * the folder above `pagefind/`.
+ *
+ * That default is right for one of our two subpath layouts and wrong for the
+ * other, measured by decoding index fragments on live sites:
+ *
+ * | Deploy | Pages built into | Stored URL | Default base | Result |
+ * |---|---|---|---|---|
+ * | Workers subpath mount | `dist/<mount>/` (nested) | `/<mount>/page/` | `/<mount>/` | `/<mount>/<mount>/page/` — 404 |
+ * | GitHub Pages project | `dist/` (Astro `base`) | `/page/` | `/<repo>/` | `/<repo>/page/` — correct |
+ *
+ * So no single constant works: forcing `/` fixes the Workers mount and breaks
+ * every GitHub Pages project site. The emitter knows which layout it built and
+ * passes the base explicitly; this applies it.
+ */
+
+/** The slice of the Pagefind module this touches. */
+export interface PagefindOptionsModule {
+  options?: (opts: { baseUrl?: string }) => Promise<void> | void;
+}
+
+/**
+ * The base Pagefind should prefix results with: the served path that the
+ * INDEXED directory maps to.
+ *
+ * - Workers subpath mount — pages are built INTO `dist/<mount>/`, so the
+ *   index already carries the mount in every URL: `/`.
+ * - Anything else — pages sit at the `dist/` root and Astro's `base` (the
+ *   site.url path) is added at serve time, so that is the missing prefix:
+ *   `<urlBase>/`, or `/` at the host root.
+ *
+ * Note `basePath` (dogsbay's own prefix) is never part of it: pages are
+ * physically written under it, so the index already contains it.
+ */
+export function pagefindBaseUrl(urlBase: string, nestedOutDir: boolean): string {
+  if (nestedOutDir) return "/";
+  const base = urlBase.replace(/\/+$/, "");
+  return base ? `${base}/` : "/";
+}
+
+/**
+ * Apply an emitted base to a loaded Pagefind module. A missing base (a page
+ * emitted before the base was passed) leaves Pagefind's own default, so an
+ * un-rebuilt site behaves exactly as before rather than changing under it.
+ */
+export async function applyPagefindBaseUrl(
+  mod: PagefindOptionsModule,
+  baseUrl: string | undefined,
+): Promise<boolean> {
+  if (!baseUrl) return false;
+  if (typeof mod.options !== "function") return false;
+  await mod.options({ baseUrl });
+  return true;
+}