@mintlify/common 1.0.1023 → 1.0.1024

package/dist/navigation/updateFirstHrefInDivision.js

@@ -0,0 +1,383 @@
+import { locales } from '@mintlify/models';
+import { divisions, } from '@mintlify/validation';
+import { readObjectArrayProperty } from '../divisions/iterateObjectArrayProperty.js';
+import { isEqualIgnoringLeadingSlash } from '../paths/isEqualIgnoringLeadingSlash.js';
+import { isPage } from './isPage.js';
+export var DivisionMatchLevel;
+(function (DivisionMatchLevel) {
+    DivisionMatchLevel[DivisionMatchLevel["EXACT"] = 0] = "EXACT";
+    DivisionMatchLevel[DivisionMatchLevel["PATH"] = 1] = "PATH";
+    DivisionMatchLevel[DivisionMatchLevel["GROUP"] = 2] = "GROUP";
+    DivisionMatchLevel[DivisionMatchLevel["DIVISION"] = 3] = "DIVISION";
+    DivisionMatchLevel[DivisionMatchLevel["NONE"] = 4] = "NONE";
+})(DivisionMatchLevel || (DivisionMatchLevel = {}));
+const ACCEPTED_BASE_PATHS = ['docs', 'doc', 'documentation', 'help'];
+export function updateFirstHrefInDivision({ type, currentPath, entry, parentGroups, nearestDivisionValue, isActiveGroup, inActiveDivision, currentDivisionValue, allDivisionValues, firstHrefInDivision, navigationDivisions, isHiddenPage, activeGroupNames, }) {
+    if (typeof entry !== 'object')
+        return;
+    if (isPage(entry)) {
+        maybeUpdateFirstHrefInDivision(type, entry.href, nearestDivisionValue, isActiveGroup, inActiveDivision, currentPath, currentDivisionValue, allDivisionValues, firstHrefInDivision, isHiddenPage);
+    }
+    if ('pages' in entry && Array.isArray(entry.pages)) {
+        const root = 'root' in entry && entry.root != null && typeof entry.root === 'object'
+            ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- root is a DecoratedNavigationPage
+                entry.root
+            : undefined;
+        const isRootActive = root !== undefined &&
+            isPage(root) &&
+            isEqualIgnoringLeadingSlash(root.href, currentPath) &&
+            currentDivisionValue === nearestDivisionValue;
+        const isActivePages = entry.pages.some((subEntry) => isPage(subEntry) && isEqualIgnoringLeadingSlash(subEntry.href, currentPath)) && currentDivisionValue === nearestDivisionValue;
+        if (root !== undefined) {
+            updateFirstHrefInDivision({
+                type,
+                currentPath,
+                entry: root,
+                parentGroups: parentGroups.length ? parentGroups : entry.pages,
+                nearestDivisionValue,
+                isActiveGroup: isActiveGroup || isActivePages || isRootActive,
+                inActiveDivision,
+                currentDivisionValue,
+                allDivisionValues,
+                firstHrefInDivision,
+                navigationDivisions,
+                isHiddenPage,
+                activeGroupNames,
+            });
+        }
+        for (const page of entry.pages) {
+            if (typeof page === 'object') {
+                updateFirstHrefInDivision({
+                    type,
+                    currentPath,
+                    entry: page,
+                    parentGroups: parentGroups.length ? parentGroups : entry.pages,
+                    nearestDivisionValue,
+                    isActiveGroup: isActiveGroup || isActivePages || isRootActive,
+                    inActiveDivision,
+                    currentDivisionValue,
+                    allDivisionValues,
+                    firstHrefInDivision,
+                    navigationDivisions,
+                    isHiddenPage,
+                    activeGroupNames,
+                });
+            }
+        }
+    }
+    if ('groups' in entry && !isPage(entry)) {
+        for (const group of entry.groups) {
+            if (typeof group !== 'object')
+                continue;
+            const groupName = 'group' in group && typeof group.group === 'string' ? group.group : undefined;
+            const matchesCurrentDivisionGroup = checkActiveGroup(group, currentPath) && currentDivisionValue === nearestDivisionValue;
+            const matchesActiveSiblingGroup = type === 'version' &&
+                currentDivisionValue !== nearestDivisionValue &&
+                !!groupName &&
+                (activeGroupNames === null || activeGroupNames === void 0 ? void 0 : activeGroupNames.has(groupName)) === true;
+            const isActiveGroup = matchesCurrentDivisionGroup || matchesActiveSiblingGroup;
+            updateFirstHrefInDivision({
+                type,
+                currentPath,
+                entry: group,
+                parentGroups: entry.groups,
+                nearestDivisionValue,
+                isActiveGroup,
+                inActiveDivision,
+                currentDivisionValue,
+                allDivisionValues,
+                firstHrefInDivision,
+                navigationDivisions,
+                isHiddenPage,
+                activeGroupNames,
+            });
+        }
+    }
+    for (const key of [...divisions, 'groups']) {
+        const subDivisions = readObjectArrayProperty(entry, key);
+        if (!subDivisions)
+            continue;
+        let inActiveDivision = false;
+        if (allDivisionValues && allDivisionValues.length) {
+            if (type === 'version' && key === 'versions') {
+                const localDivisionValueCount = navigationDivisions.versions.filter((version) => !version.isGlobal).length;
+                inActiveDivision =
+                    subDivisions.length === localDivisionValueCount &&
+                        subDivisions.every((subDivision) => 
+                        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                        allDivisionValues.includes(subDivision.version));
+            }
+            else if (type === 'language' && key === 'languages') {
+                const localDivisionValueCount = navigationDivisions.languages.filter((language) => !language.isGlobal).length;
+                inActiveDivision =
+                    subDivisions.length === localDivisionValueCount &&
+                        subDivisions.every((subDivision) => 
+                        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                        allDivisionValues.includes(subDivision.language));
+            }
+        }
+        let activeGroupsInVersionContext = activeGroupNames;
+        if (type === 'version' && key === 'versions' && currentDivisionValue) {
+            const currentVersionDivision = subDivisions.find((subDivision) => 'version' in subDivision &&
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                subDivision.version === currentDivisionValue);
+            if (currentVersionDivision) {
+                activeGroupsInVersionContext = findActiveGroupNames(
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                currentVersionDivision, currentPath);
+            }
+        }
+        for (const subDivision of subDivisions) {
+            let divisionValue;
+            if (type === 'version' && key === 'versions') {
+                divisionValue =
+                    'version' in subDivision
+                        ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                            subDivision.version
+                        : undefined;
+            }
+            else if (type === 'language' && key === 'languages') {
+                divisionValue =
+                    'language' in subDivision
+                        ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                            subDivision.language
+                        : undefined;
+            }
+            updateFirstHrefInDivision({
+                type,
+                currentPath,
+                entry: subDivision,
+                parentGroups: key === 'groups' && 'groups' in entry
+                    ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                        entry.groups
+                    : parentGroups,
+                nearestDivisionValue: divisionValue !== null && divisionValue !== void 0 ? divisionValue : nearestDivisionValue,
+                isActiveGroup,
+                inActiveDivision: inActiveDivision,
+                currentDivisionValue,
+                allDivisionValues,
+                firstHrefInDivision,
+                navigationDivisions,
+                isHiddenPage,
+                activeGroupNames: activeGroupsInVersionContext,
+            });
+        }
+    }
+}
+function findActiveGroupNames(entry, currentPath, activeGroupNames = new Set()) {
+    if (typeof entry !== 'object')
+        return activeGroupNames;
+    if ('groups' in entry && !isPage(entry)) {
+        for (const group of entry.groups) {
+            if (typeof group !== 'object')
+                continue;
+            if ('group' in group &&
+                typeof group.group === 'string' &&
+                checkActiveGroup(group, currentPath)) {
+                activeGroupNames.add(group.group);
+            }
+            findActiveGroupNames(group, currentPath, activeGroupNames);
+        }
+    }
+    if ('pages' in entry && Array.isArray(entry.pages)) {
+        if ('root' in entry && typeof entry.root === 'object') {
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+            findActiveGroupNames(entry.root, currentPath, activeGroupNames);
+        }
+        for (const page of entry.pages) {
+            if (typeof page === 'object') {
+                findActiveGroupNames(page, currentPath, activeGroupNames);
+            }
+        }
+    }
+    for (const key of divisions) {
+        const subDivisions = readObjectArrayProperty(entry, key);
+        if (!subDivisions)
+            continue;
+        for (const subDivision of subDivisions) {
+            findActiveGroupNames(subDivision, currentPath, activeGroupNames);
+        }
+    }
+    return activeGroupNames;
+}
+function parseLanguagePath(segments) {
+    let index = 0;
+    let locale;
+    let hasDocsBase = false;
+    const firstSegment = segments[0];
+    const firstIsDocsBase = !!firstSegment && ACCEPTED_BASE_PATHS.includes(firstSegment);
+    const firstIsLocale = !!firstSegment &&
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+        locales.includes(firstSegment);
+    if (firstIsDocsBase) {
+        hasDocsBase = true;
+        index = 1;
+        const maybeLocale = segments[index];
+        if (maybeLocale &&
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+            locales.includes(maybeLocale)) {
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+            locale = maybeLocale;
+            index++;
+        }
+    }
+    else if (firstIsLocale) {
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+        locale = firstSegment;
+        index = 1;
+        const maybeDocsBase = segments[index];
+        if (maybeDocsBase && ACCEPTED_BASE_PATHS.includes(maybeDocsBase)) {
+            hasDocsBase = true;
+            index++;
+        }
+    }
+    let contentSegments = segments.slice(index);
+    if (contentSegments.at(-1) === 'index') {
+        contentSegments = contentSegments.slice(0, -1);
+    }
+    return { hasDocsBase, locale, contentSegments };
+}
+/**
+ * This function attempts to maintain some context when switching versions by following these rules:
+ * 1. stay on the active page, if it is in the new version (unversioned)
+ * 2. navigate to the first page that is in the new version AND in the active group, if one exists
+ * 3. navigate to the first page that is in the new version
+ *
+ * @param href The href of the page being processed
+ * @param finalVersion The version of the page being processed
+ * @param inActiveGroup Whether the page being processed is in the same group as the active page
+ * @param currentPath The path of the active page
+ * @param currentVersion The version of the active page
+ * @param versionStrings If defined, the array of version strings
+ * @param firstHrefInDivision A map from version strings to the href that should be navigated to when switching to that version
+ */
+function maybeUpdateFirstHrefInDivision(type, href, finalVersion, inActiveGroup, inActiveDivision, currentPath, currentVersion, versionStrings, firstHrefInDivision, isHiddenPage) {
+    const versionsToUpdate = finalVersion !== undefined ? [finalVersion] : (versionStrings !== null && versionStrings !== void 0 ? versionStrings : []);
+    // now that we support index.mdx, the href might empty string
+    // router.push cannot take empty string as url
+    href = href || '/';
+    // always use the current page if the current page is unversioned
+    if (href === currentPath) {
+        for (const version of versionsToUpdate) {
+            firstHrefInDivision.set(version, { href, matchLevel: DivisionMatchLevel.EXACT });
+        }
+        return;
+    }
+    // if the page is hidden, assign the current path to the current version with EXACT match level
+    if (isHiddenPage && currentVersion !== undefined) {
+        firstHrefInDivision.set(currentVersion, {
+            href: currentPath,
+            matchLevel: DivisionMatchLevel.EXACT,
+        });
+    }
+    // if currentPath and href differ by exactly one path segment, and it's not the last,
+    // we make the BOLD assumption that href is a different version of the same page
+    if (currentVersion !== undefined && finalVersion !== undefined) {
+        const existingRef = firstHrefInDivision.get(finalVersion);
+        if ((existingRef === undefined || DivisionMatchLevel.PATH < existingRef.matchLevel) &&
+            pathsDifferByOneSegment(href, currentPath, type)) {
+            firstHrefInDivision.set(finalVersion, { href, matchLevel: DivisionMatchLevel.PATH });
+        }
+    }
+    if (inActiveGroup) {
+        for (const version of versionsToUpdate) {
+            const existingHref = firstHrefInDivision.get(version);
+            if (existingHref === undefined || DivisionMatchLevel.GROUP < existingHref.matchLevel) {
+                firstHrefInDivision.set(version, { href, matchLevel: DivisionMatchLevel.GROUP });
+            }
+        }
+        return;
+    }
+    if (inActiveDivision) {
+        for (const version of versionsToUpdate) {
+            const existingHref = firstHrefInDivision.get(version);
+            if (existingHref === undefined || DivisionMatchLevel.DIVISION < existingHref.matchLevel) {
+                firstHrefInDivision.set(version, { href, matchLevel: DivisionMatchLevel.DIVISION });
+            }
+        }
+        return;
+    }
+    for (const version of versionsToUpdate) {
+        if (!firstHrefInDivision.has(version)) {
+            firstHrefInDivision.set(version, { href, matchLevel: DivisionMatchLevel.NONE });
+        }
+    }
+}
+export function pathsDifferByOneSegment(a, b, type) {
+    const aSegments = a.split('/').filter(Boolean);
+    const bSegments = b.split('/').filter(Boolean);
+    // For language switching, we need to be more strict - paths should be identical except for the language segment
+    // once normalized, content segments should be identical and only locale prefix may differ.
+    if (type === 'language') {
+        const aPath = parseLanguagePath(aSegments);
+        const bPath = parseLanguagePath(bSegments);
+        if (aPath.hasDocsBase !== bPath.hasDocsBase)
+            return false;
+        // For language switching, the content parts (including version segments) must be identical.
+        if (aPath.contentSegments.length !== bPath.contentSegments.length)
+            return false;
+        for (let i = 0; i < aPath.contentSegments.length; i++) {
+            if (aPath.contentSegments[i] !== bPath.contentSegments[i]) {
+                return false;
+            }
+        }
+        // The paths are language variants if locale presence/value differs.
+        if (!aPath.locale && !bPath.locale)
+            return false;
+        return aPath.locale !== bPath.locale;
+    }
+    const aStartsWithDocs = aSegments[0] && ACCEPTED_BASE_PATHS.includes(aSegments[0]);
+    const bStartsWithDocs = bSegments[0] && ACCEPTED_BASE_PATHS.includes(bSegments[0]);
+    // Only compare like-for-like paths (both with docs base prefix or both without)
+    if (aStartsWithDocs !== bStartsWithDocs)
+        return false;
+    const aContentSegments = aStartsWithDocs ? aSegments.slice(1) : aSegments;
+    const bContentSegments = bStartsWithDocs ? bSegments.slice(1) : bSegments;
+    // Existing behavior: same-length paths are version variants if exactly one non-terminal segment differs.
+    if (aContentSegments.length === bContentSegments.length &&
+        aContentSegments.length >= 2 &&
+        aContentSegments.at(-1) === bContentSegments.at(-1)) {
+        let mismatchFound = false;
+        for (let i = 0; i < aContentSegments.length - 1; i++) {
+            if (aContentSegments[i] !== bContentSegments[i]) {
+                if (mismatchFound)
+                    return false;
+                mismatchFound = true;
+            }
+        }
+        return mismatchFound;
+    }
+    // New behavior: handle root-vs-prefixed version paths by allowing one leading segment difference.
+    const longerContentSegments = aContentSegments.length > bContentSegments.length ? aContentSegments : bContentSegments;
+    const shorterContentSegments = aContentSegments.length > bContentSegments.length ? bContentSegments : aContentSegments;
+    if (longerContentSegments.length !== shorterContentSegments.length + 1)
+        return false;
+    if (shorterContentSegments.length === 0)
+        return false;
+    for (let i = 0; i < shorterContentSegments.length; i++) {
+        if (longerContentSegments[i + 1] !== shorterContentSegments[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+function checkActiveGroup(group, currentPath) {
+    if (isPage(group)) {
+        return isEqualIgnoringLeadingSlash(group.href, currentPath);
+    }
+    if ('pages' in group) {
+        if ('root' in group && typeof group.root === 'object') {
+            const isActivePage = checkActiveGroup(group.root, currentPath);
+            if (isActivePage) {
+                return true;
+            }
+        }
+        for (const page of group.pages) {
+            const isActivePage = checkActiveGroup(page, currentPath);
+            if (isActivePage) {
+                return true;
+            }
+        }
+    }
+    return false;
+}

package/dist/paths/isEqualIgnoringLeadingSlash.d.ts

@@ -0,0 +1 @@
+export declare function isEqualIgnoringLeadingSlash(path1: string | undefined, path2: string | undefined): boolean;

package/dist/paths/isEqualIgnoringLeadingSlash.js

@@ -0,0 +1,21 @@
+import { optionallyRemoveLeadingSlash, optionallyRemoveTrailingSlash, } from '../fs/optionallySlash.js';
+import { replaceSlashIndex } from '../slug/replaceSlashIndex.js';
+function normalizeIndexPath(path) {
+    if (path === '')
+        return 'index';
+    if (path === 'index')
+        return path;
+    if (path.endsWith('/index')) {
+        const normalized = replaceSlashIndex(path);
+        return normalized === '' ? 'index' : normalized;
+    }
+    return path;
+}
+export function isEqualIgnoringLeadingSlash(path1, path2) {
+    if (path1 == null || path2 == null || typeof path1 !== 'string' || typeof path2 !== 'string') {
+        return false;
+    }
+    const first = optionallyRemoveTrailingSlash(optionallyRemoveLeadingSlash(path1));
+    const second = optionallyRemoveTrailingSlash(optionallyRemoveLeadingSlash(path2));
+    return normalizeIndexPath(first) === normalizeIndexPath(second);
+}

package/dist/paths/isEqualIgnoringLeadingSlash.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/paths/isEqualIgnoringLeadingSlash.test.js

@@ -0,0 +1,43 @@
+import { isEqualIgnoringLeadingSlash } from './isEqualIgnoringLeadingSlash.js';
+describe('isEqualIgnoringLeadingSlash', () => {
+    test('false when non-string inputs are passed', () => {
+        expect(isEqualIgnoringLeadingSlash({}, {})).toEqual(false);
+        expect(isEqualIgnoringLeadingSlash(undefined, '')).toEqual(false);
+        expect(isEqualIgnoringLeadingSlash(0, null)).toEqual(false);
+    });
+    test('true when strings match ignoring leading slash', () => {
+        expect(isEqualIgnoringLeadingSlash('', '/')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/path/to', 'path/to')).toEqual(true);
+    });
+    test('handles index paths', () => {
+        expect(isEqualIgnoringLeadingSlash('', 'index')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/', 'index')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('path/to/index', 'path/to')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/path/to/index', 'path/to')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('path/to/index', '/path/to')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/index', '')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/index', '/')).toEqual(true);
+    });
+    test('handles complex index paths', () => {
+        expect(isEqualIgnoringLeadingSlash('/api/v1/index', '/api/v1')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('indexing/guide', 'ing/guide')).toEqual(false);
+        expect(isEqualIgnoringLeadingSlash('reindex/data', 'rein/data')).toEqual(false);
+        expect(isEqualIgnoringLeadingSlash('index/subpath/index', 'index/subpath')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('index/subpath', 'index/subpath/index')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/', 'index')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/index/index', 'index')).toEqual(true);
+    });
+    test('normal paths work', () => {
+        expect(isEqualIgnoringLeadingSlash('path/to/resource', 'path/to/different')).toEqual(false);
+        expect(isEqualIgnoringLeadingSlash('/a/b/c', '/x/y/z')).toEqual(false);
+        expect(isEqualIgnoringLeadingSlash('Path/To', 'path/to')).toEqual(false);
+        expect(isEqualIgnoringLeadingSlash('INDEX', 'index')).toEqual(false);
+        expect(isEqualIgnoringLeadingSlash('path/to', 'path/to')).toEqual(true);
+    });
+    test('weird cases work', () => {
+        expect(isEqualIgnoringLeadingSlash('', 'index')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/index', '/index')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/index', 'index')).toEqual(true);
+        expect(isEqualIgnoringLeadingSlash('/index', '')).toEqual(true);
+    });
+});