@mintlify/common 1.0.1266 → 1.0.1268

package/dist/mdx/islands/package-sources.js

@@ -25,19 +25,27 @@ const parse = (content, path) => {
         return messageOf(error);
     }
 };
-const topLevelImports = (tree) => tree.children.flatMap((node) => {
+const IMPORT_STATEMENTS = new Set(['ImportDeclaration']);
+const MODULE_SOURCE_STATEMENTS = new Set([
+    'ImportDeclaration',
+    'ExportNamedDeclaration',
+    'ExportAllDeclaration',
+]);
+const topLevelSources = (tree, statementTypes = IMPORT_STATEMENTS) => tree.children.flatMap((node) => {
     var _a, _b, _c;
     if (!isMdxJsEsm(node))
         return [];
     return ((_c = (_b = (_a = node.data) === null || _a === void 0 ? void 0 : _a.estree) === null || _b === void 0 ? void 0 : _b.body) !== null && _c !== void 0 ? _c : []).flatMap((statement) => {
-        var _a, _b, _c;
-        if (statement.type !== 'ImportDeclaration' || typeof statement.source.value !== 'string') {
+        var _a, _b, _c, _d;
+        if (!statementTypes.has(statement.type) ||
+            !('source' in statement) ||
+            typeof ((_a = statement.source) === null || _a === void 0 ? void 0 : _a.value) !== 'string') {
             return [];
         }
         return [
             {
                 source: statement.source.value,
-                line: (_b = (_a = statement.loc) === null || _a === void 0 ? void 0 : _a.start.line) !== null && _b !== void 0 ? _b : (_c = node.position) === null || _c === void 0 ? void 0 : _c.start.line,
+                line: (_c = (_b = statement.loc) === null || _b === void 0 ? void 0 : _b.start.line) !== null && _c !== void 0 ? _c : (_d = node.position) === null || _d === void 0 ? void 0 : _d.start.line,
             },
         ];
     });
@@ -46,14 +54,14 @@ export const sortPackageProblems = (problems) => [...problems].sort((a, b) => {
 export const classifyPackageSources = (files, { packageNames, variables, normalizeImportSource = (source) => source, }) => {
     var _a;
     const resolve = (source, importer) => resolveImportPath(normalizeImportSource(source, importer), importer);
-    const usesPackages = ({ path, content }) => [...replaceVariables(content, variables).matchAll(IMPORT_SOURCE)].some(([, from, bare]) => {
-        var _a;
-        const source = normalizeImportSource((_a = from !== null && from !== void 0 ? from : bare) !== null && _a !== void 0 ? _a : '', path);
+    const importsPackage = (from, path) => {
+        const source = normalizeImportSource(from, path);
         if (isDeclaredPackageImport(source, packageNames))
             return true;
         const resolved = resolveImportPath(source, path);
         return resolved !== null && isPackageSnippetPath(resolved);
-    });
+    };
+    const textUsesPackages = ({ path, content }) => [...replaceVariables(content, variables).matchAll(IMPORT_SOURCE)].some(([, from, bare]) => { var _a; return importsPackage((_a = from !== null && from !== void 0 ? from : bare) !== null && _a !== void 0 ? _a : '', path); });
     const parsed = [];
     const failed = [];
     for (const file of [...files].sort((a, b) => compare(a.path, b.path))) {
@@ -61,7 +69,7 @@ export const classifyPackageSources = (files, { packageNames, variables, normali
         if (typeof tree === 'string')
             failed.push(Object.assign(Object.assign({}, file), { message: tree }));
         else
-            parsed.push(Object.assign(Object.assign({}, file), { tree, imports: topLevelImports(tree) }));
+            parsed.push(Object.assign(Object.assign({}, file), { tree, imports: topLevelSources(tree) }));
     }
     const importedFiles = new Set();
     for (const file of parsed) {
@@ -90,12 +98,13 @@ export const classifyPackageSources = (files, { packageNames, variables, normali
     for (const file of failed) {
         const category = categoryOf(file.path);
         result.unparsed.push({ path: file.path, content: file.content, category });
-        if (usesPackages(file))
+        if (textUsesPackages(file))
             result.errors.push({ file: file.path, message: file.message });
     }
     for (const file of parsed) {
         const category = categoryOf(file.path);
-        if (category === 'legacySnippet' && usesPackages(file)) {
+        if (category === 'legacySnippet' &&
+            topLevelSources(file.tree, MODULE_SOURCE_STATEMENTS).some(({ source }) => importsPackage(source, file.path))) {
             result.errors.push({
                 file: file.path,
                 message: "uses npm package components, which don't work in files included with <Snippet>. Import it into the page instead.",

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');
+        });
+    });
 });