@mintlify/common 1.0.1267 → 1.0.1268

package/dist/navigation/filterDivisions.js

@@ -3,7 +3,7 @@ import { divisions, } from '@mintlify/validation';
 import { readObjectArrayProperty } from '../divisions/iterateObjectArrayProperty.js';
 import { optionallyAddLeadingSlash } from '../fs/optionallySlash.js';
 import { isAbsoluteUrl } from '../isAbsoluteUrl.js';
-import { isEqualIgnoringLeadingSlash } from '../paths/isEqualIgnoringLeadingSlash.js';
+import { isEqualIgnoringLeadingSlash, normalizeComparablePath, } from '../paths/isEqualIgnoringLeadingSlash.js';
 import { checkNavAccess } from './checkNavAccess.js';
 import { getFirstPageFromNavigation } from './getFirstPageFromNavigation.js';
 import { isPage } from './isPage.js';
@@ -169,6 +169,7 @@ export const filterDivisions = ({ currentPath, currentVersion, currentLanguage,
                             menuDivision,
                             isPreview,
                             parentDivisionNames: ancestorDivisionNames,
+                            rootNav: decoratedNav,
                         });
                     })
                         .filter(Boolean);
@@ -269,8 +270,8 @@ function upsertGlobalDivisions(navigationDivisions, globalConfig) {
     });
 }
 function buildDivisionItem(param) {
-    var _a, _b;
-    const { item, isActive, cache, currentPath, currentVersion, currentLanguage, userGroups, divisionKey, menuDivision, isPreview = false, parentDivisionNames = [], } = param;
+    var _a, _b, _c;
+    const { item, isActive, cache, currentPath, currentVersion, currentLanguage, userGroups, divisionKey, menuDivision, isPreview = false, parentDivisionNames = [], rootNav, } = param;
     const { dropdownCache } = cache;
     let href = '';
     // TODO: support this for other divisions (versions, languages, etc.)
@@ -293,7 +294,7 @@ function buildDivisionItem(param) {
         const isUserDefinedHref = 'href' in item && isAbsoluteUrl(item.href);
         if (!isUserDefinedHref && divisionKey === 'dropdowns' && !isActive && currentPath) {
             href =
-                (_b = findCorrespondingDropdownHref(item, currentPath, userGroups !== null && userGroups !== void 0 ? userGroups : new Set(), isPreview)) !== null && _b !== void 0 ? _b : '';
+                (_c = (_b = findCorrespondingDropdownHref(item, currentPath, userGroups !== null && userGroups !== void 0 ? userGroups : new Set(), isPreview)) !== null && _b !== void 0 ? _b : findSamePageInDropdownVersion(page === null || page === void 0 ? void 0 : page.href, findDivisionName(item), currentPath, rootNav, userGroups !== null && userGroups !== void 0 ? userGroups : new Set(), isPreview)) !== null && _c !== void 0 ? _c : '';
         }
         if (!href) {
             href = isUserDefinedHref ? item.href : (page === null || page === void 0 ? void 0 : page.href) || '/';
@@ -327,6 +328,7 @@ function buildDivisionItem(param) {
                 userGroups,
                 divisionKey: 'menu',
                 isPreview,
+                rootNav,
                 parentDivisionNames: [
                     ...parentDivisionNames,
                     ...(parentDivisionName ? [parentDivisionName] : []),
@@ -384,6 +386,102 @@ function findCorrespondingDropdownHref(item, currentPath, userGroups, isPreview)
     walk(item);
     return exactMatch !== null && exactMatch !== void 0 ? exactMatch : segmentMatch;
 }
+/**
+ * The same page in the dropdown's version when that page lives in a different part of the
+ * navigation, e.g. `docs/v3/webhooks` under one tab but `docs/v2/webhooks` under another.
+ * The version segment is read off the dropdown's first page at the first segment where it differs
+ * from the current path. That segment is swapped in, added (`/webhooks` -> `/v1/webhooks`) or
+ * removed (`/v1/webhooks` -> `/webhooks`), and a candidate is used only if that exact page is in a
+ * dropdown of the same name. Without this the switcher lands on the dropdown's first page.
+ */
+function findSamePageInDropdownVersion(dropdownFirstHref, dropdownName, currentPath, rootNav, userGroups, isPreview) {
+    if (!dropdownFirstHref || !dropdownName || !rootNav)
+        return undefined;
+    const target = dropdownFirstHref.split('/').filter(Boolean);
+    const current = currentPath.split('/').filter(Boolean);
+    const index = current.findIndex((segment, i) => segment !== target[i]);
+    if (index === -1)
+        return undefined;
+    const versionSegment = target[index];
+    const candidates = [];
+    if (versionSegment !== undefined && index < current.length - 1) {
+        candidates.push(current.map((segment, i) => (i === index ? versionSegment : segment)));
+    }
+    if (versionSegment !== undefined) {
+        candidates.push([...current.slice(0, index), versionSegment, ...current.slice(index)]);
+    }
+    if (index < current.length - 1) {
+        candidates.push([...current.slice(0, index), ...current.slice(index + 1)]);
+    }
+    const pages = getDropdownPages(rootNav, userGroups, isPreview).get(dropdownName);
+    for (const segments of candidates) {
+        const found = pages === null || pages === void 0 ? void 0 : pages.get(normalizeComparablePath(segments.join('/')));
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+const dropdownPagesCache = new WeakMap();
+function getDropdownPages(rootNav, userGroups, isPreview) {
+    let byGroups = dropdownPagesCache.get(rootNav);
+    if (!byGroups)
+        dropdownPagesCache.set(rootNav, (byGroups = new WeakMap()));
+    let byPreview = byGroups.get(userGroups);
+    if (!byPreview)
+        byGroups.set(userGroups, (byPreview = new Map()));
+    let pages = byPreview.get(isPreview);
+    if (!pages) {
+        pages = collectDropdownPages(rootNav, userGroups, isPreview);
+        byPreview.set(isPreview, pages);
+    }
+    return pages;
+}
+function collectDropdownPages(rootNav, userGroups, isPreview) {
+    const pagesByDropdown = new Map();
+    function walk(entry, dropdownNames) {
+        if (typeof entry !== 'object')
+            return;
+        if (isPage(entry)) {
+            if (!dropdownNames.length || !checkNavAccess(entry, userGroups, isPreview))
+                return;
+            const key = normalizeComparablePath(entry.href);
+            for (const name of dropdownNames) {
+                let pages = pagesByDropdown.get(name);
+                if (!pages)
+                    pagesByDropdown.set(name, (pages = new Map()));
+                if (!pages.has(key))
+                    pages.set(key, entry.href);
+            }
+            return;
+        }
+        if ('hidden' in entry && entry.hidden)
+            return;
+        if ('root' in entry && typeof entry.root === 'object') {
+            walk(entry.root, dropdownNames);
+        }
+        if ('pages' in entry && Array.isArray(entry.pages)) {
+            for (const page of entry.pages) {
+                if (typeof page === 'object')
+                    walk(page, dropdownNames);
+            }
+        }
+        if ('groups' in entry && Array.isArray(entry.groups)) {
+            for (const group of entry.groups) {
+                walk(group, dropdownNames);
+            }
+        }
+        for (const key of divisions) {
+            const subDivisions = readObjectArrayProperty(entry, key);
+            if (!subDivisions)
+                continue;
+            for (const subDivision of subDivisions) {
+                walk(subDivision, key === 'dropdowns' ? [...dropdownNames, findDivisionName(subDivision)] : dropdownNames);
+            }
+        }
+    }
+    walk(rootNav, []);
+    return pagesByDropdown;
+}
 function getFirstPageFromCurrentDivisions(item, currentVersion, currentLanguage, userGroups, isPreview = false) {
     var _a, _b;
     if ('versions' in item && currentVersion) {
@@ -698,6 +796,7 @@ function findMostRelevantDivisions(currentPath, decoratedNav, currentVersion, cu
                                 divisionKey: key,
                                 isPreview,
                                 parentDivisionNames: ancestorDivisionNames,
+                                rootNav: decoratedNav,
                             });
                         })
                             .filter(Boolean);

package/dist/navigation/filterDivisions.test.js

@@ -858,4 +858,115 @@ describe('filterDivisions dropdown corresponding pages', () => {
             }, currentPath: '/vega/0.21/install' }));
         expect((_a = result.dropdowns.find((d) => d.name === 'Version 0.22')) === null || _a === void 0 ? void 0 : _a.href).toBe('/vega/0.22/install');
     });
+    describe('when the page sits in a different tab in the target version', () => {
+        const movedPageNav = {
+            tabs: [
+                {
+                    tab: 'Guides',
+                    dropdowns: [
+                        {
+                            dropdown: 'v3',
+                            pages: [
+                                { title: 'Quickstart', href: '/docs/v3/quickstart' },
+                                { title: 'Webhooks', href: '/docs/v3/webhooks' },
+                            ],
+                        },
+                        { dropdown: 'v2', pages: [{ title: 'Quickstart', href: '/docs/v2/quickstart' }] },
+                        { dropdown: 'v1', pages: [{ title: 'Quickstart', href: '/docs/v1/quickstart' }] },
+                    ],
+                },
+                {
+                    tab: 'Reference',
+                    dropdowns: [
+                        {
+                            dropdown: 'v2',
+                            pages: [
+                                { title: 'Errors', href: '/docs/v2/errors' },
+                                { title: 'Webhooks', href: '/docs/v2/webhooks' },
+                            ],
+                        },
+                        {
+                            dropdown: 'v1',
+                            pages: [
+                                { title: 'Errors', href: '/docs/v1/errors' },
+                                { title: 'Webhooks', href: '/docs/v1/webhooks', groups: ['admin'] },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        };
+        it('links to the same page in that version wherever it is in the navigation', () => {
+            var _a;
+            const result = filterDivisions(Object.assign(Object.assign({}, defaultArgs), { decoratedNav: movedPageNav, currentPath: '/docs/v3/webhooks' }));
+            expect((_a = result.dropdowns.find((d) => d.name === 'v2')) === null || _a === void 0 ? void 0 : _a.href).toBe('/docs/v2/webhooks');
+        });
+        it('falls back to the first page when that version has no page the viewer can access', () => {
+            var _a;
+            const result = filterDivisions(Object.assign(Object.assign({}, defaultArgs), { decoratedNav: movedPageNav, currentPath: '/docs/v3/webhooks' }));
+            expect((_a = result.dropdowns.find((d) => d.name === 'v1')) === null || _a === void 0 ? void 0 : _a.href).toBe('/docs/v1/quickstart');
+        });
+    });
+    describe('when only one version has a path prefix', () => {
+        const prefixNav = {
+            tabs: [
+                {
+                    tab: 'Guides',
+                    dropdowns: [
+                        {
+                            dropdown: 'Latest',
+                            pages: [
+                                { title: 'Quickstart', href: '/quickstart' },
+                                { title: 'Webhooks', href: '/webhooks' },
+                            ],
+                        },
+                        { dropdown: 'v1', pages: [{ title: 'Quickstart', href: '/v1/quickstart' }] },
+                    ],
+                },
+                {
+                    tab: 'Reference',
+                    dropdowns: [
+                        {
+                            dropdown: 'v1',
+                            pages: [
+                                { title: 'Errors', href: '/v1/errors' },
+                                { title: 'Webhooks', href: '/v1/webhooks' },
+                            ],
+                        },
+                        { dropdown: 'Latest', pages: [{ title: 'Errors', href: '/errors' }] },
+                        { dropdown: 'v2', pages: [{ title: 'Errors', href: '/v2/errors' }] },
+                    ],
+                },
+            ],
+        };
+        it('adds the version prefix when switching from an unprefixed page', () => {
+            var _a;
+            const result = filterDivisions(Object.assign(Object.assign({}, defaultArgs), { decoratedNav: prefixNav, currentPath: '/webhooks' }));
+            expect((_a = result.dropdowns.find((d) => d.name === 'v1')) === null || _a === void 0 ? void 0 : _a.href).toBe('/v1/webhooks');
+        });
+        it('drops the version prefix when switching to an unprefixed version', () => {
+            var _a;
+            const result = filterDivisions(Object.assign(Object.assign({}, defaultArgs), { decoratedNav: prefixNav, currentPath: '/v1/errors' }));
+            expect((_a = result.dropdowns.find((d) => d.name === 'Latest')) === null || _a === void 0 ? void 0 : _a.href).toBe('/errors');
+        });
+        it('never links to a page from another version', () => {
+            var _a;
+            const result = filterDivisions(Object.assign(Object.assign({}, defaultArgs), { decoratedNav: prefixNav, currentPath: '/v1/webhooks' }));
+            expect((_a = result.dropdowns.find((d) => d.name === 'v2')) === null || _a === void 0 ? void 0 : _a.href).toBe('/v2/errors');
+        });
+        it('never links to a page inside a hidden tab', () => {
+            var _a;
+            const result = filterDivisions(Object.assign(Object.assign({}, defaultArgs), { decoratedNav: {
+                    tabs: [
+                        ...prefixNav.tabs,
+                        {
+                            tab: 'Internal',
+                            hidden: true,
+                            dropdowns: [{ dropdown: 'v2', pages: [{ title: 'Webhooks', href: '/v2/webhooks' }] }],
+                        },
+                    ],
+                }, currentPath: '/v1/webhooks' }));
+            expect((_a = result.dropdowns.find((d) => d.name === 'v2')) === null || _a === void 0 ? void 0 : _a.href).toBe('/v2/errors');
+        });
+    });
 });