@mintlify/common 1.0.1252 → 1.0.1253

package/dist/navigation/clientNavView.d.ts

@@ -0,0 +1,3 @@
+import type { DecoratedPageOrGroupConfig } from '@mintlify/validation';
+export declare function clientNavView(entries: DecoratedPageOrGroupConfig[]): unknown[];
+export declare function paginationDescriptions(entries: DecoratedPageOrGroupConfig[], currentPath: string): [unknown, unknown];

package/dist/navigation/clientNavView.js

@@ -0,0 +1,44 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { isEqualIgnoringLeadingSlash } from '../paths/isEqualIgnoringLeadingSlash.js';
+import { replaceSlashIndex } from '../slug/replaceSlashIndex.js';
+import { isPage } from './isPage.js';
+import { CLIENT_NAV_PAGE_FIELDS } from './trimScopedNavPages.js';
+function clientPage(page) {
+    return Object.fromEntries(CLIENT_NAV_PAGE_FIELDS.filter((field) => Object.hasOwn(page, field)).map((field) => [
+        field,
+        page[field],
+    ]));
+}
+export function clientNavView(entries) {
+    return entries.map((entry) => {
+        if (isPage(entry))
+            return clientPage(entry);
+        const { root, pages } = entry, rest = __rest(entry, ["root", "pages"]);
+        return Object.assign(Object.assign(Object.assign({}, rest), (root ? { root: clientPage(root) } : {})), { pages: clientNavView(pages) });
+    });
+}
+function flattenPages(entries) {
+    return entries.flatMap((entry) => {
+        if (isPage(entry))
+            return [entry];
+        return [...(entry.root ? [entry.root] : []), ...flattenPages(entry.pages)];
+    });
+}
+export function paginationDescriptions(entries, currentPath) {
+    var _a, _b;
+    const pages = flattenPages(entries);
+    const index = pages.findIndex((page) => isEqualIgnoringLeadingSlash(replaceSlashIndex(page.href), currentPath));
+    if (index === -1)
+        return [undefined, undefined];
+    return [(_a = pages[index - 1]) === null || _a === void 0 ? void 0 : _a.description, (_b = pages[index + 1]) === null || _b === void 0 ? void 0 : _b.description];
+}

package/dist/navigation/getScopedNavForPath.test.js

@@ -1,3 +1,4 @@
+import { clientNavView, paginationDescriptions } from './clientNavView.js';
 import { decoratedNavigationConfig } from './decoratedNavigationConfig.js';
 import { filterDivisions } from './filterDivisions.js';
 import { getAllPathsInDecoratedNav } from './getAllPathsInDecoratedNav.js';
@@ -99,7 +100,8 @@ function assertInvariantForEveryPath(nav, includeProductVersionMetadata = false)
         });
         const full = filterWith(nav, currentPath, scoped.currentVersion, scoped.currentLanguage);
         const rescoped = filterWith(scoped.scopedNav, currentPath, scoped.currentVersion, scoped.currentLanguage);
-        expect(rescoped.groupsOrPages, currentPath).toEqual(full.groupsOrPages);
+        expect(clientNavView(rescoped.groupsOrPages), currentPath).toEqual(clientNavView(full.groupsOrPages));
+        expect(paginationDescriptions(rescoped.groupsOrPages, currentPath), currentPath).toEqual(paginationDescriptions(full.groupsOrPages, currentPath));
         expect(divisionSummary(rescoped), currentPath).toEqual(divisionSummary(full));
         expect(mapHrefs(rescoped.firstHrefInVersion), currentPath).toEqual(mapHrefs(full.firstHrefInVersion));
         expect(mapHrefs(rescoped.firstHrefInLanguage), currentPath).toEqual(mapHrefs(full.firstHrefInLanguage));

package/dist/navigation/scopeNavStateFlip.test.js

@@ -1,4 +1,5 @@
 import { isEqualIgnoringLeadingSlash } from '../paths/isEqualIgnoringLeadingSlash.js';
+import { clientNavView, paginationDescriptions } from './clientNavView.js';
 import { decoratedNavigationConfig } from './decoratedNavigationConfig.js';
 import { filterDivisions } from './filterDivisions.js';
 import { getAllPathsInDecoratedNav } from './getAllPathsInDecoratedNav.js';
@@ -56,7 +57,8 @@ function assertStateFlipSafety(nav) {
             const label = `${currentPath} -> version ${version.name}`;
             const flippedFull = filterWith(nav, currentPath, version.name, scoped.currentLanguage);
             const flippedScoped = filterWith(scoped.scopedNav, currentPath, version.name, scoped.currentLanguage);
-            expect(flippedScoped.groupsOrPages, label).toEqual(flippedFull.groupsOrPages);
+            expect(clientNavView(flippedScoped.groupsOrPages), label).toEqual(clientNavView(flippedFull.groupsOrPages));
+            expect(paginationDescriptions(flippedScoped.groupsOrPages, currentPath), label).toEqual(paginationDescriptions(flippedFull.groupsOrPages, currentPath));
             expect(divisionSummary(flippedScoped), label).toEqual(divisionSummary(flippedFull));
         }
         // deliberately unguarded (no stays check): even a flip to a stubbed,
@@ -66,7 +68,8 @@ function assertStateFlipSafety(nav) {
             const label = `${currentPath} -> product ${product.name}`;
             const flippedFull = filterWith(nav, currentPath, scoped.currentVersion, scoped.currentLanguage, product.name);
             const flippedScoped = filterWith(scoped.scopedNav, currentPath, scoped.currentVersion, scoped.currentLanguage, product.name);
-            expect(flippedScoped.groupsOrPages, label).toEqual(flippedFull.groupsOrPages);
+            expect(clientNavView(flippedScoped.groupsOrPages), label).toEqual(clientNavView(flippedFull.groupsOrPages));
+            expect(paginationDescriptions(flippedScoped.groupsOrPages, currentPath), label).toEqual(paginationDescriptions(flippedFull.groupsOrPages, currentPath));
             expect(divisionSummary(flippedScoped), label).toEqual(divisionSummary(flippedFull));
         }
         for (const language of full.languages) {
@@ -77,7 +80,8 @@ function assertStateFlipSafety(nav) {
             const label = `${currentPath} -> language ${language.language}`;
             const flippedFull = filterWith(nav, currentPath, scoped.currentVersion, language.language);
             const flippedScoped = filterWith(scoped.scopedNav, currentPath, scoped.currentVersion, language.language);
-            expect(flippedScoped.groupsOrPages, label).toEqual(flippedFull.groupsOrPages);
+            expect(clientNavView(flippedScoped.groupsOrPages), label).toEqual(clientNavView(flippedFull.groupsOrPages));
+            expect(paginationDescriptions(flippedScoped.groupsOrPages, currentPath), label).toEqual(paginationDescriptions(flippedFull.groupsOrPages, currentPath));
             expect(divisionSummary(flippedScoped), label).toEqual(divisionSummary(flippedFull));
         }
     }

package/dist/navigation/scopeNavToPath.js

@@ -18,6 +18,7 @@ import { filterDivisions } from './filterDivisions.js';
 import { getFirstPageFromNavigation } from './getFirstPageFromNavigation.js';
 import { getVersionOrLanguageFromPath } from './getVersionOrLanguageFromPath.js';
 import { isPageGroups } from './groupAccess.js';
+import { trimScopedNavPages } from './trimScopedNavPages.js';
 import { pathsDifferByOneSegment } from './updateFirstHrefInDivision.js';
 const SCOPED_DIVISION_KEYS = ['versions', 'languages'];
 const DIVISION_TYPE_BY_KEY = {
@@ -621,7 +622,7 @@ export function getScopedNavForPath({ decoratedNav, currentPath, userGroups = ne
         cache: { dropdownCache: new Map() },
         isPreview,
     });
-    const scopedNav = scopeNode(
+    const scopedNav = trimScopedNavPages(scopeNode(
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
     decoratedNav, {
         currentPath,
@@ -634,7 +635,7 @@ export function getScopedNavForPath({ decoratedNav, currentPath, userGroups = ne
         isPreview,
         skipVersionLanguageStubs: productAmbiguous,
         includeProductVersionMetadata,
-    }
+    }), currentPath
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
     );
     return {

package/dist/navigation/trimScopedNavPages.d.ts

@@ -0,0 +1,4 @@
+type NavNode = Record<string, unknown>;
+export declare const CLIENT_NAV_PAGE_FIELDS: readonly ["href", "title", "hidden", "groups", "sidebarTitle", "url", "icon", "iconType", "tag", "api", "openapi", "asyncapi", "graphql", "deprecated", "hideApiMarker", "mode", "playground", "version"];
+export declare function trimScopedNavPages(nav: NavNode, currentPath: string): NavNode;
+export {};

package/dist/navigation/trimScopedNavPages.js

@@ -0,0 +1,134 @@
+import { normalizeComparablePath } from '../paths/isEqualIgnoringLeadingSlash.js';
+import { replaceSlashIndex } from '../slug/replaceSlashIndex.js';
+function pageFieldAllowlist(fields) {
+    return fields;
+}
+export const CLIENT_NAV_PAGE_FIELDS = pageFieldAllowlist([
+    'href',
+    'title',
+    'hidden',
+    'groups',
+    'sidebarTitle',
+    'url',
+    'icon',
+    'iconType',
+    'tag',
+    'api',
+    'openapi',
+    'asyncapi',
+    'graphql',
+    'deprecated',
+    'hideApiMarker',
+    'mode',
+    'playground',
+    'version',
+]);
+const isNavNode = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isPageNode = (node) => Object.hasOwn(node, 'href') && Object.hasOwn(node, 'title');
+const hrefMatches = (href, target) => typeof href === 'string' && normalizeComparablePath(replaceSlashIndex(href)) === target;
+function collectPagesInOrder(node, out, inHidden = false) {
+    if (Array.isArray(node)) {
+        for (const entry of node)
+            collectPagesInOrder(entry, out, inHidden);
+        return;
+    }
+    if (!isNavNode(node))
+        return;
+    if (isPageNode(node)) {
+        out.push({
+            page: node,
+            visibleToEveryone: !inHidden && node.hidden !== true && node.groups === undefined,
+        });
+        return;
+    }
+    const hidden = inHidden || node.hidden === true;
+    if (isNavNode(node.root) && isPageNode(node.root))
+        collectPagesInOrder(node.root, out, hidden);
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'root' || key === 'global')
+            continue;
+        if (Array.isArray(value))
+            collectPagesInOrder(value, out, hidden);
+    }
+}
+function addPaginationNeighbors(nav, target, keep) {
+    const pages = [];
+    collectPagesInOrder(nav, pages);
+    pages.forEach(({ page }, index) => {
+        if (!hrefMatches(page.href, target))
+            return;
+        keepUntilVisible(pages, index, -1, keep);
+        keepUntilVisible(pages, index, 1, keep);
+    });
+}
+function keepUntilVisible(pages, from, step, keep) {
+    for (let i = from + step; i >= 0 && i < pages.length; i += step) {
+        const entry = pages[i];
+        if (!entry)
+            return;
+        keep.add(entry.page);
+        if (entry.visibleToEveryone)
+            return;
+    }
+}
+function addDirectPages(group, keep) {
+    if (!Array.isArray(group.pages))
+        return;
+    for (const entry of group.pages) {
+        if (isNavNode(entry) && isPageNode(entry))
+            keep.add(entry);
+    }
+}
+function addDirectoryChildren(node, target, keep) {
+    if (Array.isArray(node)) {
+        for (const entry of node)
+            addDirectoryChildren(entry, target, keep);
+        return;
+    }
+    if (!isNavNode(node) || isPageNode(node))
+        return;
+    if (isNavNode(node.root) && hrefMatches(node.root.href, target)) {
+        addDirectPages(node, keep);
+        if (Array.isArray(node.pages)) {
+            for (const entry of node.pages) {
+                if (isNavNode(entry) && !isPageNode(entry))
+                    addDirectPages(entry, keep);
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (key !== 'global' && Array.isArray(value))
+            addDirectoryChildren(value, target, keep);
+    }
+}
+const CLIENT_FIELDS = new Set(CLIENT_NAV_PAGE_FIELDS);
+function trimPage(page, keepDescription) {
+    const trimmed = {};
+    for (const key of Object.keys(page)) {
+        if (CLIENT_FIELDS.has(key) || (keepDescription && key === 'description')) {
+            trimmed[key] = page[key];
+        }
+    }
+    return trimmed;
+}
+function trimNode(node, keepDescription) {
+    if (Array.isArray(node))
+        return node.map((entry) => trimNode(entry, keepDescription));
+    if (!isNavNode(node))
+        return node;
+    if (isPageNode(node))
+        return trimPage(node, keepDescription.has(node));
+    const trimmed = {};
+    for (const [key, value] of Object.entries(node)) {
+        trimmed[key] = key === 'global' ? value : trimNode(value, keepDescription);
+    }
+    return trimmed;
+}
+export function trimScopedNavPages(nav, currentPath) {
+    const keepDescription = new Set();
+    const target = normalizeComparablePath(replaceSlashIndex(currentPath));
+    addPaginationNeighbors(nav, target, keepDescription);
+    addDirectoryChildren(nav, target, keepDescription);
+    const trimmed = trimNode(nav, keepDescription);
+    return isNavNode(trimmed) ? trimmed : nav;
+}

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

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

package/dist/navigation/trimScopedNavPages.test.js

@@ -0,0 +1,194 @@
+import { trimScopedNavPages } from './trimScopedNavPages.js';
+const page = (slug, extra = {}) => (Object.assign({ title: slug, href: `/${slug}`, description: `${slug} description` }, extra));
+function descriptions(nav) {
+    const out = {};
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.forEach(walk);
+        if (typeof node !== 'object' || node === null)
+            return;
+        if ('href' in node && 'title' in node && typeof node.href === 'string') {
+            out[node.href] = 'description' in node ? node.description : undefined;
+            return;
+        }
+        Object.values(node).forEach(walk);
+    };
+    walk(nav);
+    return out;
+}
+describe('trimScopedNavPages', () => {
+    it('keeps only client fields on pages', () => {
+        const nav = {
+            pages: [
+                page('a', {
+                    sidebarTitle: 'A',
+                    openapi: 'get /a',
+                    deprecated: true,
+                    playground: 'simple',
+                    version: 'v2',
+                    mode: 'wide',
+                    autogeneratedByOpenApi: true,
+                    authors: [{ name: 'x' }],
+                    keywords: ['k'],
+                    customFrontmatter: 'x',
+                }),
+            ],
+        };
+        expect(trimScopedNavPages(nav, '/a')).toEqual({
+            pages: [
+                {
+                    title: 'a',
+                    href: '/a',
+                    sidebarTitle: 'A',
+                    openapi: 'get /a',
+                    deprecated: true,
+                    playground: 'simple',
+                    version: 'v2',
+                    mode: 'wide',
+                },
+            ],
+        });
+    });
+    it('keeps descriptions only on pagination neighbors', () => {
+        const nav = {
+            groups: [
+                { group: 'One', pages: [page('a'), page('b')] },
+                { group: 'Two', pages: [page('c'), page('d')] },
+            ],
+        };
+        expect(descriptions(trimScopedNavPages(nav, '/b'))).toEqual({
+            '/a': 'a description',
+            '/b': undefined,
+            '/c': 'c description',
+            '/d': undefined,
+        });
+    });
+    it('orders a group root before its pages', () => {
+        const nav = {
+            groups: [{ group: 'G', root: page('root'), pages: [page('a'), page('b')] }],
+        };
+        expect(descriptions(trimScopedNavPages(nav, '/a'))).toEqual({
+            '/root': 'root description',
+            '/a': undefined,
+            '/b': 'b description',
+        });
+    });
+    it('steps past neighbors some viewers cannot see', () => {
+        const nav = {
+            pages: [
+                page('a'),
+                page('hidden', { hidden: true }),
+                page('current'),
+                page('gated', { groups: ['admin'] }),
+                page('b'),
+                page('c'),
+            ],
+        };
+        expect(descriptions(trimScopedNavPages(nav, '/current'))).toEqual({
+            '/a': 'a description',
+            '/hidden': 'hidden description',
+            '/current': undefined,
+            '/gated': 'gated description',
+            '/b': 'b description',
+            '/c': undefined,
+        });
+    });
+    it('steps past pages under a hidden group or division', () => {
+        const nav = {
+            tabs: [
+                {
+                    tab: 'Docs',
+                    groups: [
+                        { group: 'One', pages: [page('current')] },
+                        { group: 'Drafts', hidden: true, root: page('draft-root'), pages: [page('draft')] },
+                        { group: 'Two', pages: [page('next'), page('after')] },
+                    ],
+                },
+                { tab: 'Hidden', hidden: true, pages: [page('hidden-tab')] },
+                { tab: 'Other', pages: [page('other')] },
+            ],
+        };
+        expect(descriptions(trimScopedNavPages(nav, '/current'))).toEqual({
+            '/current': undefined,
+            '/draft-root': 'draft-root description',
+            '/draft': 'draft description',
+            '/next': 'next description',
+            '/after': undefined,
+            '/hidden-tab': undefined,
+            '/other': undefined,
+        });
+        expect(descriptions(trimScopedNavPages(nav, '/after'))).toMatchObject({
+            '/hidden-tab': 'hidden-tab description',
+            '/other': 'other description',
+        });
+    });
+    it('keeps descriptions a directory root lists', () => {
+        const nav = {
+            groups: [
+                {
+                    group: 'Dir',
+                    directory: 'card',
+                    root: page('dir'),
+                    pages: [
+                        page('child'),
+                        {
+                            group: 'Sub',
+                            pages: [page('grandchild'), { group: 'Deep', pages: [page('deep')] }],
+                        },
+                    ],
+                },
+                { group: 'Other', pages: [page('x'), page('y')] },
+            ],
+        };
+        expect(descriptions(trimScopedNavPages(nav, '/dir'))).toEqual({
+            '/dir': undefined,
+            '/child': 'child description',
+            '/grandchild': 'grandchild description',
+            '/deep': undefined,
+            '/x': undefined,
+            '/y': undefined,
+        });
+    });
+    it('matches index hrefs like the client', () => {
+        const nav = { pages: [page('a'), page('guide/index'), page('b')] };
+        expect(descriptions(trimScopedNavPages(nav, '/guide'))).toEqual({
+            '/a': 'a description',
+            '/guide/index': undefined,
+            '/b': 'b description',
+        });
+    });
+    it('leaves division descriptions and global links alone', () => {
+        const nav = {
+            global: {
+                anchors: [{ anchor: 'Blog', href: 'https://example.com', description: 'kept' }],
+            },
+            dropdowns: [
+                {
+                    dropdown: 'D',
+                    description: 'dropdown description',
+                    pages: [page('a')],
+                },
+            ],
+        };
+        expect(trimScopedNavPages(nav, '/a')).toEqual({
+            global: {
+                anchors: [{ anchor: 'Blog', href: 'https://example.com', description: 'kept' }],
+            },
+            dropdowns: [
+                {
+                    dropdown: 'D',
+                    description: 'dropdown description',
+                    pages: [{ title: 'a', href: '/a' }],
+                },
+            ],
+        });
+    });
+    it('does not mutate the input', () => {
+        const nav = {
+            pages: [page('a', { keywords: ['k'] }), page('b'), page('c')],
+        };
+        const before = structuredClone(nav);
+        trimScopedNavPages(nav, '/a');
+        expect(nav).toEqual(before);
+    });
+});

package/dist/paths/isEqualIgnoringLeadingSlash.d.ts

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

package/dist/paths/isEqualIgnoringLeadingSlash.js

@@ -15,7 +15,8 @@ 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);
+    return normalizeComparablePath(path1) === normalizeComparablePath(path2);
+}
+export function normalizeComparablePath(path) {
+    return normalizeIndexPath(optionallyRemoveTrailingSlash(optionallyRemoveLeadingSlash(path)));
 }