@mintlify/common 1.0.1031 → 1.0.1032

package/dist/navigation/getScopedNavForPath.test.js

@@ -87,12 +87,16 @@ function divisionSummary(result) {
 function mapHrefs(map) {
     return new Map([...map.entries()].map(([key, value]) => [key, value.href]));
 }
-function assertInvariantForEveryPath(nav) {
+function assertInvariantForEveryPath(nav, includeProductVersionMetadata = false) {
     const paths = getAllPathsInDecoratedNav(nav);
     expect(paths.length).toBeGreaterThan(0);
     for (const path of paths) {
         const currentPath = `/${path.replace(/^\//, '')}`;
-        const scoped = getScopedNavForPath({ decoratedNav: nav, currentPath });
+        const scoped = getScopedNavForPath({
+            decoratedNav: nav,
+            currentPath,
+            includeProductVersionMetadata,
+        });
         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);
@@ -132,4 +136,149 @@ describe(getScopedNavForPath, () => {
         expect(serialized).not.toContain('/v1/es/guides/overview');
         expect(serialized).toContain('/en/guides/new-in-v2');
     });
+    describe('includeProductVersionMetadata', () => {
+        const productNav = {
+            products: [
+                {
+                    product: 'Model Serving',
+                    versions: [
+                        {
+                            version: '6.0',
+                            default: true,
+                            groups: [
+                                {
+                                    group: 'Guides',
+                                    pages: [
+                                        { title: 'Quickstart', href: '/serving/6.0/quickstart' },
+                                        { title: 'Endpoints', href: '/serving/6.0/endpoints' },
+                                    ],
+                                },
+                            ],
+                        },
+                        {
+                            version: '5.9',
+                            groups: [
+                                {
+                                    group: 'Guides',
+                                    pages: [{ title: 'Quickstart', href: '/serving/5.9/quickstart' }],
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    product: 'Workbench',
+                    global: {
+                        versions: [{ version: 'external-9.9', href: 'https://legacy.example.com' }],
+                    },
+                    versions: [
+                        {
+                            version: '3.2',
+                            name: 'Workbench 3.2',
+                            default: true,
+                            groups: [
+                                { group: 'Guides', pages: [{ title: 'Setup', href: '/workbench/3.2/setup' }] },
+                            ],
+                        },
+                        {
+                            version: '3.1',
+                            groups: [
+                                { group: 'Guides', pages: [{ title: 'Setup', href: '/workbench/3.1/setup' }] },
+                            ],
+                        },
+                        {
+                            version: '3.0-beta',
+                            hidden: true,
+                            groups: [
+                                { group: 'Guides', pages: [{ title: 'Setup', href: '/workbench/3.0/setup' }] },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        };
+        const currentPath = '/serving/6.0/quickstart';
+        function findProduct(nav, name) {
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
+            const products = nav.products;
+            return products.find((product) => product.product === name);
+        }
+        it('drops sibling product versions by default', () => {
+            var _a;
+            const scoped = getScopedNavForPath({ decoratedNav: productNav, currentPath });
+            expect((_a = findProduct(scoped.scopedNav, 'Workbench')) === null || _a === void 0 ? void 0 : _a.versions).toBeUndefined();
+        });
+        it('keeps pageless version metadata on sibling product stubs when enabled', () => {
+            var _a;
+            const scoped = getScopedNavForPath({
+                decoratedNav: productNav,
+                currentPath,
+                includeProductVersionMetadata: true,
+            });
+            expect((_a = findProduct(scoped.scopedNav, 'Workbench')) === null || _a === void 0 ? void 0 : _a.versions).toEqual([
+                { version: '3.2', name: 'Workbench 3.2' },
+                { version: '3.1' },
+            ]);
+            expect(JSON.stringify(scoped.scopedNav)).not.toContain('/workbench/3.1/setup');
+            expect(JSON.stringify(scoped.scopedNav)).not.toContain('external-9.9');
+        });
+        it('leaves the active product and jump maps unchanged when enabled', () => {
+            const scoped = getScopedNavForPath({ decoratedNav: productNav, currentPath });
+            const withMetadata = getScopedNavForPath({
+                decoratedNav: productNav,
+                currentPath,
+                includeProductVersionMetadata: true,
+            });
+            expect(findProduct(withMetadata.scopedNav, 'Model Serving')).toEqual(findProduct(scoped.scopedNav, 'Model Serving'));
+            expect(withMetadata.firstHrefInVersion).toEqual(scoped.firstHrefInVersion);
+            expect(withMetadata.firstHrefInLanguage).toEqual(scoped.firstHrefInLanguage);
+            expect(withMetadata.currentVersion).toBe(scoped.currentVersion);
+        });
+        it('filters identically to the full nav for every path when enabled', () => {
+            assertInvariantForEveryPath(multiDivisionNav, true);
+            assertInvariantForEveryPath(decoratedNavigationConfig, true);
+        });
+        it('changes nothing but the added metadata for every path', () => {
+            const paths = getAllPathsInDecoratedNav(productNav);
+            expect(paths.length).toBeGreaterThan(0);
+            for (const path of paths) {
+                const currentPath = `/${path.replace(/^\//, '')}`;
+                const scopedOff = getScopedNavForPath({ decoratedNav: productNav, currentPath });
+                const scopedOn = getScopedNavForPath({
+                    decoratedNav: productNav,
+                    currentPath,
+                    includeProductVersionMetadata: true,
+                });
+                expect(stripMetadataVersions(scopedOn.scopedNav), currentPath).toEqual(scopedOff.scopedNav);
+                expect(scopedOn.firstHrefInVersion, currentPath).toEqual(scopedOff.firstHrefInVersion);
+                expect(scopedOn.firstHrefInLanguage, currentPath).toEqual(scopedOff.firstHrefInLanguage);
+                expect(scopedOn.currentVersion, currentPath).toBe(scopedOff.currentVersion);
+                expect(scopedOn.currentLanguage, currentPath).toBe(scopedOff.currentLanguage);
+                const filteredOff = filterWith(scopedOff.scopedNav, currentPath, scopedOff.currentVersion, scopedOff.currentLanguage);
+                const filteredOn = filterWith(scopedOn.scopedNav, currentPath, scopedOn.currentVersion, scopedOn.currentLanguage);
+                expect(divisionSummary(filteredOn), currentPath).toEqual(divisionSummary(filteredOff));
+                expect(filteredOn.groupsOrPages, currentPath).toEqual(filteredOff.groupsOrPages);
+                expect(mapHrefs(filteredOn.firstHrefInVersion), currentPath).toEqual(mapHrefs(filteredOff.firstHrefInVersion));
+            }
+        });
+    });
 });
+function stripMetadataVersions(value) {
+    if (Array.isArray(value))
+        return value.map(stripMetadataVersions);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const entries = Object.entries(value).flatMap(([key, entry]) => {
+        if (key === 'versions' &&
+            Array.isArray(entry) &&
+            entry.every((version) => typeof version === 'object' &&
+                version !== null &&
+                !('pages' in version) &&
+                !('groups' in version) &&
+                !('href' in version))) {
+            return [];
+        }
+        return [[key, stripMetadataVersions(entry)]];
+    });
+    return Object.fromEntries(entries);
+}

package/dist/navigation/scopeNavToPath.d.ts

@@ -10,9 +10,10 @@ export type ScopedNavForPath = {
     currentVersion: string | undefined;
     currentLanguage: LocaleType | undefined;
 };
-export declare function getScopedNavForPath({ decoratedNav, currentPath, userGroups, isPreview, }: {
+export declare function getScopedNavForPath({ decoratedNav, currentPath, userGroups, isPreview, includeProductVersionMetadata, }: {
     decoratedNav: DecoratedNavigationConfig;
     currentPath: string;
     userGroups?: Set<string>;
     isPreview?: boolean;
+    includeProductVersionMetadata?: boolean;
 }): ScopedNavForPath;

package/dist/navigation/scopeNavToPath.js

@@ -357,6 +357,40 @@ function scopeDivisionArray(entries, key, ctx) {
         return stubDivision(entry, key, ctx);
     });
 }
+function collectProductVersionMetadata(node, out, seen) {
+    if (Array.isArray(node)) {
+        for (const entry of node) {
+            collectProductVersionMetadata(entry, out, seen);
+        }
+        return;
+    }
+    if (!isNavNode(node))
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        // versions under a nested product belong to that product, and global
+        // holds external links never attributed to a product by the consumer
+        if (key === 'products' || key === 'global')
+            continue;
+        if (key === 'versions' && Array.isArray(value)) {
+            for (const version of value) {
+                if (!isNavNode(version))
+                    continue;
+                if (typeof version.version !== 'string' || version.hidden === true)
+                    continue;
+                if (seen.has(version.version))
+                    continue;
+                seen.add(version.version);
+                const metadata = { version: version.version };
+                if (typeof version.name === 'string')
+                    metadata.name = version.name;
+                out.push(metadata);
+            }
+        }
+        if (Array.isArray(value) || isNavNode(value)) {
+            collectProductVersionMetadata(value, out, seen);
+        }
+    }
+}
 function stubProduct(product, ctx) {
     if (typeof product.href === 'string')
         return product;
@@ -373,6 +407,14 @@ function stubProduct(product, ctx) {
             stub[entryKey] = value;
         }
     }
+    if (ctx.includeProductVersionMetadata) {
+        const versionMetadata = [];
+        collectProductVersionMetadata(product, versionMetadata, new Set());
+        // pageless version entries so the search version filter can list a
+        // non-active product's versions; invisible to sidebar/dict consumers
+        if (versionMetadata.length)
+            stub.versions = versionMetadata;
+    }
     stub.pages = target.isRaw
         ? [target.href]
         : [makeStubPage(typeof product.product === 'string' ? product.product : '', target)];
@@ -433,7 +475,7 @@ export function scopeDocsConfigNavToPath(docsConfig, currentPath) {
         // 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, }) {
+export function getScopedNavForPath({ decoratedNav, currentPath, userGroups = new Set(), isPreview = false, includeProductVersionMetadata = false, }) {
     var _a, _b, _c, _d, _e, _f, _g, _h;
     const containingProductNames = new Set();
     collectContainingProductNames(
@@ -489,6 +531,7 @@ export function getScopedNavForPath({ decoratedNav, currentPath, userGroups = ne
         userGroups,
         isPreview,
         skipVersionLanguageStubs: productAmbiguous,
+        includeProductVersionMetadata,
     }
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
     );