@mintlify/common 1.0.1023 → 1.0.1024

package/dist/navigation/scopeNavToPath.js

@@ -0,0 +1,455 @@
+import { locales } from '@mintlify/models';
+import { generatePathToLanguageDict, generatePathToVersionDict } from '../divisions/index.js';
+import { optionallyRemoveLeadingSlash } from '../fs/optionallySlash.js';
+import { isEqualIgnoringLeadingSlash } from '../paths/isEqualIgnoringLeadingSlash.js';
+import { filterDivisions } from './filterDivisions.js';
+import { getFirstPageFromNavigation } from './getFirstPageFromNavigation.js';
+import { getVersionOrLanguageFromPath } from './getVersionOrLanguageFromPath.js';
+import { pathsDifferByOneSegment } from './updateFirstHrefInDivision.js';
+const SCOPED_DIVISION_KEYS = ['versions', 'languages'];
+const DIVISION_TYPE_BY_KEY = {
+    versions: 'version',
+    languages: 'language',
+};
+const CONTAINER_KEYS = [
+    'versions',
+    'languages',
+    'tabs',
+    'anchors',
+    'dropdowns',
+    'products',
+    'menu',
+];
+const STUB_STRIPPED_KEYS = new Set([
+    'anchors',
+    'asyncapi',
+    'dropdowns',
+    'global',
+    'groups',
+    'languages',
+    'menu',
+    'openapi',
+    'pages',
+    'products',
+    'tabs',
+    'versions',
+]);
+function isNavNode(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isScopedDivisionKey(key) {
+    return key === 'versions' || key === 'languages';
+}
+function isDecoratedPageNode(node) {
+    return typeof node.href === 'string' && typeof node.title === 'string';
+}
+function pageAccessGroups(node) {
+    if (!Array.isArray(node.groups))
+        return undefined;
+    const groups = node.groups.filter((group) => typeof group === 'string');
+    return groups.length === node.groups.length ? groups : undefined;
+}
+// inHiddenSubtree propagates hidden from ancestor groups/divisions: a visible
+// page under a hidden group is unreachable in getFirstPageFromNavigation
+// order, and a stub baked from it would resurrect an invisible division
+function collectPageCandidates(node, candidates, inHiddenSubtree = false) {
+    if (Array.isArray(node)) {
+        for (const entry of node) {
+            collectPageCandidates(entry, candidates, inHiddenSubtree);
+        }
+        return;
+    }
+    if (!isNavNode(node))
+        return;
+    const hidden = inHiddenSubtree || node.hidden === true;
+    if (isDecoratedPageNode(node)) {
+        candidates.push({
+            href: node.href,
+            isRaw: false,
+            hidden,
+            groups: pageAccessGroups(node),
+        });
+        return;
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'pages' && Array.isArray(value)) {
+            for (const entry of value) {
+                if (typeof entry === 'string') {
+                    candidates.push({ href: entry, isRaw: true, hidden });
+                }
+                else {
+                    collectPageCandidates(entry, candidates, hidden);
+                }
+            }
+        }
+        else if (Array.isArray(value) || isNavNode(value)) {
+            collectPageCandidates(value, candidates, hidden);
+        }
+    }
+}
+function divisionContainsPath(division, currentPath) {
+    const candidates = [];
+    collectPageCandidates(division, candidates);
+    return candidates.some((candidate) => isEqualIgnoringLeadingSlash(candidate.href, currentPath));
+}
+function collectContainingProductNames(node, currentPath, names) {
+    if (Array.isArray(node)) {
+        for (const entry of node) {
+            if (isNavNode(entry) || Array.isArray(entry)) {
+                collectContainingProductNames(entry, currentPath, names);
+            }
+        }
+        return;
+    }
+    const products = node.products;
+    if (Array.isArray(products)) {
+        for (const product of products) {
+            if (isNavNode(product) && divisionContainsPath(product, currentPath)) {
+                names.add(typeof product.product === 'string' ? product.product : undefined);
+            }
+        }
+    }
+    for (const value of Object.values(node)) {
+        if (isNavNode(value) || Array.isArray(value)) {
+            collectContainingProductNames(value, currentPath, names);
+        }
+    }
+}
+function pickStubTarget(division, ctx, type) {
+    const candidates = [];
+    collectPageCandidates(division, candidates);
+    // groups: [] means no group grants access (checkNavAccess denies it), so
+    // only a candidate with no groups key at all is anonymously visible
+    const visible = candidates.filter((candidate) => !candidate.hidden && candidate.groups === undefined);
+    const nonHidden = candidates.filter((candidate) => !candidate.hidden);
+    const pool = ctx.isPreview
+        ? candidates
+        : visible.length
+            ? visible
+            : nonHidden.length
+                ? nonHidden
+                : candidates;
+    const exact = pool.find((candidate) => isEqualIgnoringLeadingSlash(candidate.href, ctx.currentPath));
+    if (exact)
+        return exact;
+    const pathMatch = pool.find((candidate) => pathsDifferByOneSegment(candidate.href, ctx.currentPath, type));
+    return pathMatch !== null && pathMatch !== void 0 ? pathMatch : pool[0];
+}
+// carrying the target's hidden/groups keeps a division with no anonymously
+// visible page just as invisible when the client re-runs its access checks
+// over the stub
+function makeStubPage(title, target) {
+    const stub = { title, href: target.href };
+    if (target.hidden)
+        stub.hidden = true;
+    if (target.groups)
+        stub.groups = target.groups;
+    return stub;
+}
+function divisionLabel(division, key) {
+    const label = key === 'versions' ? division.version : division.language;
+    return typeof label === 'string' ? label : '';
+}
+function divisionValue(division, key) {
+    const value = key === 'versions' ? division.version : division.language;
+    return typeof value === 'string' ? value : undefined;
+}
+function resolveStubTarget(division, key, ctx) {
+    const targets = key === 'versions' ? ctx.versionTargets : ctx.languageTargets;
+    const value = divisionValue(division, key);
+    const resolved = targets === null || targets === void 0 ? void 0 : targets.get(value);
+    const fallback = pickStubTarget(division, ctx, DIVISION_TYPE_BY_KEY[key]);
+    // the jump-map walk records targets without access checks, so a precomputed
+    // entry only supplies the switch destination; hidden/groups still come from
+    // the division's real pages or an access-invisible division would resurface
+    if (resolved) {
+        return {
+            href: resolved.href,
+            isRaw: false,
+            hidden: (fallback === null || fallback === void 0 ? void 0 : fallback.hidden) === true,
+            groups: fallback === null || fallback === void 0 ? void 0 : fallback.groups,
+        };
+    }
+    return fallback;
+}
+function stubDivision(division, key, ctx) {
+    if (typeof division.href === 'string')
+        return division;
+    const target = resolveStubTarget(division, key, ctx);
+    // a division with no page candidates carries no page payload worth stripping,
+    // so keep it unchanged rather than inventing a switch target
+    if (!target)
+        return division;
+    const stub = {};
+    for (const [entryKey, value] of Object.entries(division)) {
+        if (!STUB_STRIPPED_KEYS.has(entryKey)) {
+            stub[entryKey] = value;
+        }
+    }
+    // stub pages exist only so firstHrefInVersion/Language resolves a switch
+    // target; they are never rendered, so the division identifier stands in for
+    // a display title
+    stub.pages = target.isRaw ? [target.href] : [makeStubPage(divisionLabel(division, key), target)];
+    return stub;
+}
+const SIMPLE_DIVISION_KEYS = ['tabs', 'anchors'];
+function isSimpleDivisionKey(key) {
+    return key === 'tabs' || key === 'anchors';
+}
+function simpleDivisionLabel(division, key) {
+    const label = key === 'tabs' ? division.tab : division.anchor;
+    return typeof label === 'string' ? label : '';
+}
+// versions/languages feed switch-target derivation, dropdowns feed the
+// client's stateful dropdownCache hrefs, and the active product is client
+// session state — divisions containing any of them stay whole
+const STATEFUL_DIVISION_KEYS = new Set(['versions', 'languages', 'dropdowns', 'products']);
+function containsStatefulDivision(node) {
+    if (Array.isArray(node))
+        return node.some(containsStatefulDivision);
+    if (!isNavNode(node))
+        return false;
+    for (const [key, value] of Object.entries(node)) {
+        if (STATEFUL_DIVISION_KEYS.has(key) && Array.isArray(value))
+            return true;
+        if ((Array.isArray(value) || isNavNode(value)) && containsStatefulDivision(value))
+            return true;
+    }
+    return false;
+}
+// mirrors buildDivisionItem's anonymous href resolution (first page in
+// getFirstPageFromNavigation order that is neither hidden nor group-gated);
+// falls back to the first raw candidate so a division with no anonymously
+// visible page keeps its inaccessibility via the carried hidden/groups
+function resolveVisibleTarget(division, ctx) {
+    var _a;
+    const page = getFirstPageFromNavigation(
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
+    division, (_a = ctx.userGroups) !== null && _a !== void 0 ? _a : new Set(), true, ctx.isPreview === true);
+    if (page) {
+        return { href: page.href, isRaw: false, hidden: page.hidden === true, groups: page.groups };
+    }
+    // preview renders every division even when no page is reachable (href '/');
+    // only the real subtree reproduces that, so signal keep-whole
+    if (ctx.isPreview)
+        return undefined;
+    const candidates = [];
+    collectPageCandidates(division, candidates);
+    return candidates[0];
+}
+function hasViewerVisiblePage(node, ctx) {
+    var _a;
+    return (getFirstPageFromNavigation(
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
+    node, (_a = ctx.userGroups) !== null && _a !== void 0 ? _a : new Set(), true, ctx.isPreview === true) !== undefined);
+}
+const MENU_STUBBABLE_KEYS = new Set(['pages', 'groups']);
+// inactive tabs/products still render their full hover menu, so menu items
+// survive stubbing with their metadata and a single resolved page each
+function stubMenuItem(item, ctx) {
+    if (!isNavNode(item))
+        return item;
+    if (typeof item.href === 'string')
+        return item;
+    const subtreeKeys = Object.keys(item).filter((key) => STUB_STRIPPED_KEYS.has(key));
+    if (!subtreeKeys.length || !subtreeKeys.every((key) => MENU_STUBBABLE_KEYS.has(key))) {
+        return scopeNode(item, ctx);
+    }
+    const target = resolveVisibleTarget(item, ctx);
+    if (!target)
+        return item;
+    const stub = {};
+    for (const [entryKey, value] of Object.entries(item)) {
+        if (!STUB_STRIPPED_KEYS.has(entryKey)) {
+            stub[entryKey] = value;
+        }
+    }
+    stub.pages = target.isRaw
+        ? [target.href]
+        : [makeStubPage(typeof item.item === 'string' ? item.item : '', target)];
+    return stub;
+}
+function stubSimpleDivision(division, key, ctx) {
+    if (typeof division.href === 'string')
+        return division;
+    if (containsStatefulDivision(division))
+        return scopeNode(division, ctx);
+    const target = resolveVisibleTarget(division, ctx);
+    if (!target)
+        return division;
+    const stub = {};
+    for (const [entryKey, value] of Object.entries(division)) {
+        if (entryKey === 'menu' && Array.isArray(value)) {
+            stub.menu = value.map((item) => stubMenuItem(item, ctx));
+        }
+        else if (!STUB_STRIPPED_KEYS.has(entryKey)) {
+            stub[entryKey] = value;
+        }
+    }
+    stub.pages = target.isRaw
+        ? [target.href]
+        : [makeStubPage(simpleDivisionLabel(division, key), target)];
+    return stub;
+}
+function scopeSimpleDivisionArray(entries, key, ctx) {
+    const activeIndex = entries.findIndex((entry) => isNavNode(entry) && divisionContainsPath(entry, ctx.currentPath));
+    // when the path-containing division is invisible to the viewer (hidden-only
+    // or group-gated), the client's active-division fallback lands on a sibling
+    // instead — that sibling must keep its real subtree, so nothing is stubbed
+    const activeEntry = activeIndex === -1 ? undefined : entries[activeIndex];
+    const activeVisible = isNavNode(activeEntry) && hasViewerVisiblePage(activeEntry, ctx);
+    return entries.map((entry, index) => {
+        if (!isNavNode(entry))
+            return entry;
+        // without a path match the active division is unknowable, so nothing is stubbed
+        if (!activeVisible || index === activeIndex)
+            return scopeNode(entry, ctx);
+        return stubSimpleDivision(entry, key, ctx);
+    });
+}
+// the same collapse applied to stubbed tabs' menus, but inside the active
+// tab/anchor: the item containing the path keeps its subtree (it feeds the
+// sidebar), siblings survive as hover-menu metadata plus one resolved page
+function scopeMenuArray(entries, ctx) {
+    const activeIndex = entries.findIndex((entry) => isNavNode(entry) && divisionContainsPath(entry, ctx.currentPath));
+    const activeEntry = activeIndex === -1 ? undefined : entries[activeIndex];
+    const activeVisible = isNavNode(activeEntry) && hasViewerVisiblePage(activeEntry, ctx);
+    return entries.map((entry, index) => {
+        if (!isNavNode(entry))
+            return entry;
+        if (!activeVisible || index === activeIndex)
+            return scopeNode(entry, ctx);
+        return stubMenuItem(entry, ctx);
+    });
+}
+function scopeDivisionArray(entries, key, ctx) {
+    if (ctx.skipVersionLanguageStubs) {
+        return entries.map((entry) => (isNavNode(entry) ? scopeNode(entry, ctx) : entry));
+    }
+    const currentValue = key === 'versions' ? ctx.currentVersion : ctx.currentLanguage;
+    let activeIndex = -1;
+    if (currentValue) {
+        activeIndex = entries.findIndex((entry) => isNavNode(entry) &&
+            divisionValue(entry, key) === currentValue &&
+            divisionContainsPath(entry, ctx.currentPath));
+        if (activeIndex === -1) {
+            activeIndex = entries.findIndex((entry) => isNavNode(entry) && divisionValue(entry, key) === currentValue);
+        }
+    }
+    if (activeIndex === -1) {
+        activeIndex = entries.findIndex((entry) => isNavNode(entry) && divisionContainsPath(entry, ctx.currentPath));
+    }
+    if (activeIndex === -1) {
+        activeIndex = entries.findIndex((entry) => isNavNode(entry) && entry.default === true);
+    }
+    if (activeIndex === -1)
+        activeIndex = 0;
+    return entries.map((entry, index) => {
+        if (!isNavNode(entry))
+            return entry;
+        if (index === activeIndex)
+            return scopeNode(entry, ctx);
+        return stubDivision(entry, key, ctx);
+    });
+}
+function scopeNode(node, ctx) {
+    const scoped = Object.assign({}, node);
+    for (const key of CONTAINER_KEYS) {
+        const value = scoped[key];
+        if (!Array.isArray(value))
+            continue;
+        if (isScopedDivisionKey(key) && value.length > 1) {
+            scoped[key] = scopeDivisionArray(value, key, ctx);
+        }
+        else if (isSimpleDivisionKey(key) && value.length > 1) {
+            scoped[key] = scopeSimpleDivisionArray(value, key, ctx);
+        }
+        else if (key === 'menu' &&
+            value.length > 1 &&
+            (typeof scoped.tab === 'string' || typeof scoped.anchor === 'string')) {
+            // menus on products stay whole: the active product is client session
+            // state, so the server cannot know which product's menu will render
+            scoped[key] = scopeMenuArray(value, ctx);
+        }
+        else {
+            scoped[key] = value.map((entry) => (isNavNode(entry) ? scopeNode(entry, ctx) : entry));
+        }
+    }
+    return scoped;
+}
+export function scopeDecoratedNavToPath(nav, currentPath) {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
+    return scopeNode(nav, { currentPath });
+}
+export function scopeDocsConfigNavToPath(docsConfig, currentPath) {
+    return Object.assign(Object.assign({}, docsConfig), { 
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
+        navigation: scopeNode(docsConfig.navigation, { currentPath }) });
+}
+export function getScopedNavForPath({ decoratedNav, currentPath, userGroups = new Set(), isPreview = false, }) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const containingProductNames = new Set();
+    collectContainingProductNames(
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
+    decoratedNav, currentPath, containingProductNames);
+    const soleProductName = containingProductNames.size === 1 ? [...containingProductNames][0] : undefined;
+    const currentProduct = typeof soleProductName === 'string' ? soleProductName : undefined;
+    const productAmbiguous = containingProductNames.size > 1;
+    const initial = filterDivisions({
+        currentPath,
+        decoratedNav,
+        userGroups,
+        currentVersion: undefined,
+        currentLanguage: undefined,
+        currentProduct,
+        shouldUseDivisionMatch: false,
+        cache: { dropdownCache: new Map() },
+        isPreview,
+    });
+    let currentVersion;
+    let currentLanguage;
+    if (initial.versions.length || initial.languages.length) {
+        const defaultVersion = (_a = initial.versions.find((version) => version.default)) === null || _a === void 0 ? void 0 : _a.version;
+        const defaultLanguage = (_b = initial.languages.find((language) => language.default)) === null || _b === void 0 ? void 0 : _b.language;
+        const initialVersion = getVersionOrLanguageFromPath('version', decoratedNav, currentPath, defaultVersion, (_d = (_c = initial.versions[0]) === null || _c === void 0 ? void 0 : _c.name) !== null && _d !== void 0 ? _d : '');
+        const initialLanguage = getVersionOrLanguageFromPath('language', decoratedNav, currentPath, defaultLanguage, (_f = (_e = initial.languages[0]) === null || _e === void 0 ? void 0 : _e.language) !== null && _f !== void 0 ? _f : undefined);
+        const strippedPath = optionallyRemoveLeadingSlash(currentPath);
+        const dictLanguage = generatePathToLanguageDict(decoratedNav).get(strippedPath);
+        currentVersion =
+            generatePathToVersionDict(decoratedNav).get(strippedPath) || initialVersion || undefined;
+        currentLanguage =
+            (_h = (_g = locales.find((locale) => locale === dictLanguage)) !== null && _g !== void 0 ? _g : initialLanguage) !== null && _h !== void 0 ? _h : undefined;
+    }
+    const filtered = filterDivisions({
+        currentPath,
+        decoratedNav,
+        userGroups,
+        currentVersion,
+        currentLanguage,
+        currentProduct,
+        shouldUseDivisionMatch: true,
+        cache: { dropdownCache: new Map() },
+        isPreview,
+    });
+    const scopedNav = scopeNode(
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
+    decoratedNav, {
+        currentPath,
+        currentVersion,
+        currentLanguage,
+        versionTargets: filtered.firstHrefInVersion,
+        languageTargets: filtered.firstHrefInLanguage,
+        userGroups,
+        isPreview,
+        skipVersionLanguageStubs: productAmbiguous,
+    }
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
+    );
+    return {
+        scopedNav,
+        firstHrefInVersion: productAmbiguous ? new Map() : filtered.firstHrefInVersion,
+        firstHrefInLanguage: productAmbiguous ? new Map() : filtered.firstHrefInLanguage,
+        currentVersion,
+        currentLanguage,
+    };
+}

package/dist/navigation/scopeNavToPath.test.d.ts

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

package/dist/navigation/scopeNavToPath.test.js

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { scopeDecoratedNavToPath, scopeDocsConfigNavToPath } from './scopeNavToPath.js';
+const page = (href, title = href) => ({ title, href });
+const loose = (value) => value;
+const decoratedNav = {
+    languages: [
+        {
+            language: 'en',
+            default: true,
+            groups: [
+                {
+                    group: 'Getting started',
+                    pages: [page('/get-started/intro'), page('/get-started/install')],
+                },
+            ],
+        },
+        {
+            language: 'es',
+            navbar: { links: [{ label: 'Soporte', href: 'https://example.com' }] },
+            groups: [
+                {
+                    group: 'Comenzar',
+                    pages: [page('/es/get-started/intro'), page('/es/get-started/install')],
+                },
+            ],
+        },
+        {
+            language: 'fr',
+            groups: [{ group: 'Démarrer', pages: [page('/fr/other/page')] }],
+        },
+    ],
+};
+describe('scopeDecoratedNavToPath', () => {
+    it('keeps the active division subtree and stubs siblings with an equivalent-page href', () => {
+        const scoped = scopeDecoratedNavToPath(decoratedNav, '/get-started/intro');
+        const [en, es, fr] = loose(scoped).languages;
+        if (!en || !es || !fr)
+            throw new Error('missing languages');
+        expect(en).toEqual(loose(decoratedNav).languages[0]);
+        expect(es.groups).toBeUndefined();
+        expect(es.language).toBe('es');
+        expect(es.navbar).toBeDefined();
+        expect(es.pages).toEqual([{ title: 'es', href: '/es/get-started/intro' }]);
+        expect(fr.pages).toEqual([{ title: 'fr', href: '/fr/other/page' }]);
+    });
+    it('falls back to the default division when the path is not found', () => {
+        const scoped = scopeDecoratedNavToPath(decoratedNav, '/does/not/exist');
+        const [en, es] = loose(scoped).languages;
+        if (!en || !es)
+            throw new Error('missing languages');
+        expect(en.groups).toBeDefined();
+        expect(es.pages).toHaveLength(1);
+    });
+    it('scopes nested versions inside the active language', () => {
+        var _a;
+        const nav = {
+            languages: [
+                {
+                    language: 'en',
+                    versions: [
+                        { version: 'v2', groups: [{ group: 'Docs', pages: [page('/v2/a'), page('/v2/b')] }] },
+                        { version: 'v1', groups: [{ group: 'Docs', pages: [page('/v1/a')] }] },
+                    ],
+                },
+                { language: 'es', pages: [page('/es/a')] },
+            ],
+        };
+        const scoped = scopeDecoratedNavToPath(nav, '/v1/a');
+        const [en, es] = loose(scoped).languages;
+        if (!en || !es)
+            throw new Error('missing languages');
+        const [v2, v1] = (_a = en.versions) !== null && _a !== void 0 ? _a : [];
+        if (!v2 || !v1)
+            throw new Error('missing versions');
+        expect(v1.groups).toBeDefined();
+        expect(v2.groups).toBeUndefined();
+        expect(v2.pages).toEqual([{ title: 'v2', href: '/v2/a' }]);
+        expect(es.pages).toEqual([{ title: 'es', href: '/es/a' }]);
+    });
+    it('leaves href-only divisions untouched', () => {
+        const nav = {
+            versions: [
+                { version: 'v3', pages: [page('/v3/a')] },
+                { version: 'v2', href: 'https://v2.example.com' },
+            ],
+        };
+        const scoped = scopeDecoratedNavToPath(nav, '/v3/a');
+        const [, v2] = loose(scoped).versions;
+        expect(v2).toEqual({ version: 'v2', href: 'https://v2.example.com' });
+    });
+});
+describe('scopeDocsConfigNavToPath', () => {
+    it('stubs sibling raw-language trees with a single page path while keeping metadata', () => {
+        const docsConfig = {
+            name: 'Test',
+            navigation: {
+                languages: [
+                    { language: 'en', default: true, pages: ['get-started/intro', 'get-started/install'] },
+                    {
+                        language: 'es',
+                        navbar: { links: [] },
+                        footer: { socials: {} },
+                        pages: ['es/get-started/intro', 'es/get-started/install'],
+                    },
+                ],
+            },
+        };
+        const scoped = scopeDocsConfigNavToPath(docsConfig, '/get-started/install');
+        const [en, es] = loose(scoped.navigation).languages;
+        if (!en || !es)
+            throw new Error('missing languages');
+        expect(en.pages).toHaveLength(2);
+        expect(es.pages).toEqual(['es/get-started/install']);
+        expect(es.navbar).toBeDefined();
+        expect(es.footer).toBeDefined();
+    });
+});

package/dist/navigation/scopeOffPathDivisions.test.d.ts

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