@mintlify/common 1.0.1023 → 1.0.1025

package/dist/navigation/scopeNavStateFlip.test.js

@@ -0,0 +1,567 @@
+import { isEqualIgnoringLeadingSlash } from '../paths/isEqualIgnoringLeadingSlash.js';
+import { decoratedNavigationConfig } from './decoratedNavigationConfig.js';
+import { filterDivisions } from './filterDivisions.js';
+import { getAllPathsInDecoratedNav } from './getAllPathsInDecoratedNav.js';
+import { getScopedNavForPath } from './scopeNavToPath.js';
+function filterWith(decoratedNav, currentPath, currentVersion, currentLanguage, currentProduct) {
+    return filterDivisions({
+        currentPath,
+        decoratedNav,
+        userGroups: new Set(),
+        currentVersion,
+        currentLanguage,
+        currentProduct,
+        shouldUseDivisionMatch: true,
+        cache: { dropdownCache: new Map() },
+    });
+}
+function divisionSummary(result) {
+    return {
+        tabs: result.tabs.map(({ name, isActive }) => ({ name, isActive })),
+        anchors: result.anchors.map(({ name, isActive }) => ({ name, isActive })),
+        versions: result.versions.map(({ name, isActive }) => ({ name, isActive })),
+        languages: result.languages.map(({ name, isActive }) => ({ name, isActive })),
+        dropdowns: result.dropdowns.map(({ name, isActive }) => ({ name, isActive })),
+        products: result.products.map(({ name, isActive }) => ({ name, isActive })),
+    };
+}
+/**
+ * The correctness property behind same-url division switches: for every path
+ * and every selectable version/language, EITHER the precomputed jump target
+ * navigates away (the destination's own payload takes over) OR the switch
+ * keeps the url — in which case the client re-renders the scoped tree with
+ * flipped session state, and that render must match the full nav exactly.
+ */
+function assertStateFlipSafety(nav) {
+    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 full = filterWith(nav, currentPath, scoped.currentVersion, scoped.currentLanguage);
+        const rescoped = filterWith(scoped.scopedNav, currentPath, scoped.currentVersion, scoped.currentLanguage);
+        // the picker only offers divisions present in the chrome, so parity is
+        // asserted for those; full-nav maps can carry unreachable entries from
+        // other products' divisions that stubs rightly no longer contribute
+        const selectableVersions = new Set(full.versions.map(({ name }) => name));
+        const selectableLanguages = new Set(full.languages.map(({ language }) => language));
+        const selectable = (map, keys) => new Map([...map.entries()].filter(([key]) => keys.has(key)).map(([k, v]) => [k, v.href]));
+        expect(selectable(rescoped.firstHrefInVersion, selectableVersions), currentPath).toEqual(selectable(full.firstHrefInVersion, selectableVersions));
+        expect(selectable(rescoped.firstHrefInLanguage, selectableLanguages), currentPath).toEqual(selectable(full.firstHrefInLanguage, selectableLanguages));
+        for (const version of full.versions) {
+            const target = full.firstHrefInVersion.get(version.name);
+            const stays = target !== undefined && isEqualIgnoringLeadingSlash(target.href, currentPath);
+            if (!stays)
+                continue;
+            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(divisionSummary(flippedScoped), label).toEqual(divisionSummary(flippedFull));
+        }
+        // deliberately unguarded (no stays check): even a flip to a stubbed,
+        // non-containing product must render identically, because the sidebar is
+        // path-driven and the selector chrome survives in product stubs
+        for (const product of full.products) {
+            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(divisionSummary(flippedScoped), label).toEqual(divisionSummary(flippedFull));
+        }
+        for (const language of full.languages) {
+            const target = full.firstHrefInLanguage.get(language.language);
+            const stays = target !== undefined && isEqualIgnoringLeadingSlash(target.href, currentPath);
+            if (!stays)
+                continue;
+            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(divisionSummary(flippedScoped), label).toEqual(divisionSummary(flippedFull));
+        }
+    }
+}
+function versionWithTabs(version, isDefault, sharedPages) {
+    return Object.assign(Object.assign({ version }, (isDefault ? { default: true } : {})), { tabs: [
+            {
+                tab: 'Docs',
+                pages: [
+                    ...sharedPages.map((href) => ({ title: `Shared ${href}`, href })),
+                    { title: 'Overview', href: `/docs/${version}/overview` },
+                    { title: 'Install', href: `/docs/${version}/install` },
+                ],
+            },
+            {
+                tab: 'Reference',
+                pages: [
+                    { title: 'API', href: `/docs/${version}/reference/api` },
+                    { title: 'SQL', href: `/docs/${version}/reference/sql` },
+                ],
+            },
+        ] });
+}
+// cockroachlabs shape: products wrap version divisions, the docs home and a
+// molt-style tool tab are duplicated into every version at identical hrefs,
+// and a second product has no versions at all
+const productSharedNav = {
+    products: [
+        {
+            product: 'Database',
+            versions: [
+                {
+                    version: 'v26',
+                    default: true,
+                    tabs: [
+                        {
+                            tab: 'Docs',
+                            pages: [
+                                { title: 'Home', href: '/docs' },
+                                { title: 'Overview', href: '/docs/v26/overview' },
+                            ],
+                        },
+                        {
+                            tab: 'Migrate',
+                            pages: [
+                                { title: 'Migration Overview', href: '/docs/molt/overview' },
+                                { title: 'Bulk Load', href: '/docs/molt/bulk-load' },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    version: 'v25',
+                    tabs: [
+                        {
+                            tab: 'Docs',
+                            pages: [
+                                { title: 'Home', href: '/docs' },
+                                { title: 'Overview', href: '/docs/v25/overview' },
+                            ],
+                        },
+                        {
+                            tab: 'Migrate',
+                            pages: [
+                                { title: 'Migration Overview', href: '/docs/molt/overview' },
+                                { title: 'Bulk Load', href: '/docs/molt/bulk-load' },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        },
+        {
+            product: 'Cloud',
+            tabs: [
+                {
+                    tab: 'Deploy',
+                    pages: [
+                        { title: 'Get Started', href: '/docs/cloud/get-started' },
+                        { title: 'Clusters', href: '/docs/cloud/clusters' },
+                    ],
+                },
+            ],
+        },
+    ],
+};
+// the shared home exists in v26 and v25 but NOT v24: switching to v24 from it
+// must navigate (into v24, per the unversioned-fallback fix) instead of
+// staying on a url v24 cannot render
+const partialSharedNav = {
+    versions: [
+        versionWithTabs('v26', true, ['/docs']),
+        versionWithTabs('v25', false, ['/docs']),
+        versionWithTabs('v24', false, []),
+    ],
+};
+// pages that live OUTSIDE every version division: their sidebar never derives
+// from a version division, so stubs are safe there — pinned by the harness
+const unversionedPagesNav = {
+    global: {
+        anchors: [{ anchor: 'External', href: 'https://example.com' }],
+    },
+    tabs: [
+        {
+            tab: 'Company',
+            pages: [
+                { title: 'About', href: '/docs/about' },
+                { title: 'Pricing', href: '/docs/pricing' },
+            ],
+        },
+        {
+            tab: 'Product',
+            versions: [
+                versionWithTabs('v2', true, ['/docs/shared-note']),
+                versionWithTabs('v1', false, ['/docs/shared-note']),
+            ],
+        },
+    ],
+};
+// a page shared across language divisions at the same href — the language
+// analog of the cockroachlabs home page
+const languageSharedNav = {
+    languages: [
+        {
+            language: 'en',
+            groups: [
+                {
+                    group: 'Guides',
+                    pages: [
+                        { title: 'Legal', href: '/docs/legal' },
+                        { title: 'Overview', href: '/docs/en/overview' },
+                    ],
+                },
+            ],
+        },
+        {
+            language: 'es',
+            groups: [
+                {
+                    group: 'Guides',
+                    pages: [
+                        { title: 'Legal', href: '/docs/legal' },
+                        { title: 'Overview', href: '/docs/es/overview' },
+                    ],
+                },
+            ],
+        },
+    ],
+};
+// sharing at BOTH nesting levels: the home page exists in every version and,
+// within each version, in every language
+const nestedSharedNav = {
+    versions: [
+        {
+            version: 'v2',
+            default: true,
+            languages: [
+                {
+                    language: 'en',
+                    groups: [
+                        {
+                            group: 'Guides',
+                            pages: [
+                                { title: 'Home', href: '/docs' },
+                                { title: 'Overview', href: '/docs/v2/en/overview' },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    language: 'es',
+                    groups: [
+                        {
+                            group: 'Guides',
+                            pages: [
+                                { title: 'Home', href: '/docs' },
+                                { title: 'Overview', href: '/docs/v2/es/overview' },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        },
+        {
+            version: 'v1',
+            languages: [
+                {
+                    language: 'en',
+                    groups: [
+                        {
+                            group: 'Guides',
+                            pages: [
+                                { title: 'Home', href: '/docs' },
+                                { title: 'Overview', href: '/docs/v1/en/overview' },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    language: 'es',
+                    groups: [
+                        {
+                            group: 'Guides',
+                            pages: [
+                                { title: 'Home', href: '/docs' },
+                                { title: 'Overview', href: '/docs/v1/es/overview' },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        },
+    ],
+};
+// a tool page listed in BOTH products at the same href, plus product menus
+const ambiguousProductNav = {
+    products: [
+        {
+            product: 'Server',
+            menu: [
+                {
+                    item: 'Guides',
+                    pages: [
+                        { title: 'Install', href: '/docs/server/install' },
+                        { title: 'Configure', href: '/docs/server/configure' },
+                    ],
+                },
+            ],
+            tabs: [
+                {
+                    tab: 'Docs',
+                    pages: [
+                        { title: 'Shared Tool', href: '/docs/shared-tool' },
+                        { title: 'Install', href: '/docs/server/install' },
+                        { title: 'Configure', href: '/docs/server/configure' },
+                    ],
+                },
+            ],
+        },
+        {
+            product: 'Cloud',
+            menu: [
+                {
+                    item: 'Guides',
+                    pages: [
+                        { title: 'Sign Up', href: '/docs/cloud/sign-up' },
+                        { title: 'Billing', href: '/docs/cloud/billing' },
+                    ],
+                },
+            ],
+            tabs: [
+                {
+                    tab: 'Docs',
+                    pages: [
+                        { title: 'Shared Tool', href: '/docs/shared-tool' },
+                        { title: 'Sign Up', href: '/docs/cloud/sign-up' },
+                        { title: 'Billing', href: '/docs/cloud/billing' },
+                    ],
+                },
+            ],
+        },
+    ],
+};
+// pages beside the products array, outside every product
+const outsideProductsNav = {
+    tabs: [
+        {
+            tab: 'Company',
+            pages: [
+                { title: 'About', href: '/docs/about' },
+                { title: 'Careers', href: '/docs/careers' },
+            ],
+        },
+        {
+            tab: 'Product',
+            products: [
+                {
+                    product: 'Server',
+                    pages: [
+                        { title: 'Install', href: '/docs/server/install' },
+                        { title: 'Configure', href: '/docs/server/configure' },
+                    ],
+                },
+                {
+                    product: 'Cloud',
+                    pages: [
+                        { title: 'Sign Up', href: '/docs/cloud/sign-up' },
+                        { title: 'Billing', href: '/docs/cloud/billing' },
+                    ],
+                },
+            ],
+        },
+    ],
+};
+function tripleLanguage(product, version, language, shared) {
+    return {
+        language,
+        groups: [
+            {
+                group: 'Guides',
+                pages: [
+                    ...shared.map((href) => ({ title: `Shared ${href}`, href })),
+                    { title: 'Overview', href: `/docs/${product}/${version}/${language}/overview` },
+                    { title: 'Install', href: `/docs/${product}/${version}/${language}/install` },
+                ],
+            },
+        ],
+    };
+}
+// all three axes nested: products -> versions -> languages, with the home
+// page shared across every version and language of the first product
+const tripleNestedNav = {
+    products: [
+        {
+            product: 'Server',
+            versions: [
+                {
+                    version: 'v2',
+                    default: true,
+                    languages: [
+                        tripleLanguage('server', 'v2', 'en', ['/docs', '/docs/all-shared']),
+                        tripleLanguage('server', 'v2', 'es', ['/docs', '/docs/all-shared']),
+                    ],
+                },
+                {
+                    version: 'v1',
+                    languages: [
+                        tripleLanguage('server', 'v1', 'en', ['/docs', '/docs/all-shared']),
+                        tripleLanguage('server', 'v1', 'es', ['/docs', '/docs/all-shared']),
+                    ],
+                },
+            ],
+        },
+        {
+            product: 'Cloud',
+            versions: [
+                {
+                    version: 'v2',
+                    default: true,
+                    languages: [
+                        tripleLanguage('cloud', 'v2', 'en', ['/docs/all-shared']),
+                        tripleLanguage('cloud', 'v2', 'es', ['/docs/all-shared']),
+                    ],
+                },
+            ],
+        },
+    ],
+};
+describe('state-flip safety under scoped nav', () => {
+    it('holds for the versioned fixture corpus', () => {
+        assertStateFlipSafety(decoratedNavigationConfig);
+    });
+    it('holds for products wrapping versions with shared home and tool pages', () => {
+        assertStateFlipSafety(productSharedNav);
+    });
+    it('holds when the shared page exists in only some versions', () => {
+        assertStateFlipSafety(partialSharedNav);
+    });
+    it('holds for pages outside every version division', () => {
+        assertStateFlipSafety(unversionedPagesNav);
+    });
+    it('holds for pages shared across language divisions', () => {
+        assertStateFlipSafety(languageSharedNav);
+    });
+    it('holds for a page shared across products', () => {
+        assertStateFlipSafety(ambiguousProductNav);
+    });
+    it('holds for pages outside every product', () => {
+        assertStateFlipSafety(outsideProductsNav);
+    });
+    it('holds for pages shared at both version and language level', () => {
+        assertStateFlipSafety(nestedSharedNav);
+    });
+    it('holds for products wrapping versions wrapping languages', () => {
+        assertStateFlipSafety(tripleNestedNav);
+    });
+});
+describe('triple-nested stripping', () => {
+    it('strips each axis independently on an owned page', () => {
+        const scoped = getScopedNavForPath({
+            decoratedNav: tripleNestedNav,
+            currentPath: '/docs/server/v2/en/overview',
+        });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        expect(serialized).toContain('/docs/server/v2/en/install');
+        expect(serialized).not.toContain('/docs/server/v2/es/install');
+        expect(serialized).not.toContain('/docs/server/v1/en/install');
+        expect(serialized).not.toContain('/docs/cloud/v2/en/install');
+    });
+    it('keeps every division on a page shared across products, versions, and languages at once', () => {
+        const scoped = getScopedNavForPath({
+            decoratedNav: tripleNestedNav,
+            currentPath: '/docs/all-shared',
+        });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        for (const href of [
+            '/docs/server/v2/en/install',
+            '/docs/server/v2/es/install',
+            '/docs/server/v1/en/install',
+            '/docs/server/v1/es/install',
+            '/docs/cloud/v2/en/install',
+            '/docs/cloud/v2/es/install',
+        ]) {
+            expect(serialized, href).toContain(href);
+        }
+    });
+    it('keeps every version-language pair containing the shared home, still stubbing the other product', () => {
+        const scoped = getScopedNavForPath({ decoratedNav: tripleNestedNav, currentPath: '/docs' });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        for (const href of [
+            '/docs/server/v2/en/install',
+            '/docs/server/v2/es/install',
+            '/docs/server/v1/en/install',
+            '/docs/server/v1/es/install',
+        ]) {
+            expect(serialized, href).toContain(href);
+        }
+        expect(serialized).toContain('"product":"Cloud"');
+        expect(serialized).not.toContain('/docs/cloud/v2/en/install');
+    });
+});
+describe('shared-page scoping details', () => {
+    it('keeps both containing versions through the product wrapper on the shared home', () => {
+        const scoped = getScopedNavForPath({ decoratedNav: productSharedNav, currentPath: '/docs' });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        expect(serialized).toContain('/docs/v26/overview');
+        expect(serialized).toContain('/docs/v25/overview');
+        expect(serialized).toContain('/docs/cloud/get-started');
+    });
+    it('stubs the non-containing product down to selector chrome', () => {
+        const scoped = getScopedNavForPath({ decoratedNav: productSharedNav, currentPath: '/docs' });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        expect(serialized).toContain('"product":"Cloud"');
+        expect(serialized).toContain('/docs/cloud/get-started');
+        expect(serialized).not.toContain('/docs/cloud/clusters');
+    });
+    it('keeps every product containing an ambiguous page', () => {
+        const scoped = getScopedNavForPath({
+            decoratedNav: ambiguousProductNav,
+            currentPath: '/docs/shared-tool',
+        });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        expect(serialized).toContain('/docs/server/configure');
+        expect(serialized).toContain('/docs/cloud/billing');
+    });
+    it('preserves a stubbed product menu with one resolved page per item', () => {
+        const scoped = getScopedNavForPath({
+            decoratedNav: ambiguousProductNav,
+            currentPath: '/docs/server/install',
+        });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        expect(serialized).toContain('"item":"Guides"');
+        expect(serialized).toContain('/docs/cloud/sign-up');
+        expect(serialized).not.toContain('/docs/cloud/billing');
+    });
+    it('stubs no product when the path lives outside all of them', () => {
+        const scoped = getScopedNavForPath({
+            decoratedNav: outsideProductsNav,
+            currentPath: '/docs/about',
+        });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        expect(serialized).toContain('/docs/server/configure');
+        expect(serialized).toContain('/docs/cloud/billing');
+    });
+    it('sends the switch into the target version when the shared page is absent there', () => {
+        const scoped = getScopedNavForPath({ decoratedNav: partialSharedNav, currentPath: '/docs' });
+        const target = scoped.firstHrefInVersion.get('v24');
+        expect(target).toBeDefined();
+        expect(target === null || target === void 0 ? void 0 : target.href).not.toBe('/docs');
+        expect(target === null || target === void 0 ? void 0 : target.href.startsWith('/docs/v24/')).toBe(true);
+    });
+    it('stubs the absent version division on the partially shared page', () => {
+        const scoped = getScopedNavForPath({ decoratedNav: partialSharedNav, currentPath: '/docs' });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        expect(serialized).toContain('/docs/v25/overview');
+        expect(serialized).not.toContain('/docs/v24/reference/sql');
+    });
+    it('still stubs everything for a page owned by a single version', () => {
+        const scoped = getScopedNavForPath({
+            decoratedNav: partialSharedNav,
+            currentPath: '/docs/v26/reference/api',
+        });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        expect(serialized).not.toContain('/docs/v25/reference/sql');
+        expect(serialized).not.toContain('/docs/v24/reference/sql');
+    });
+});

package/dist/navigation/scopeNavToPath.d.ts

@@ -0,0 +1,18 @@
+import { LocaleType } from '@mintlify/models';
+import type { DecoratedNavigationConfig, DocsConfig } from '@mintlify/validation';
+import { DivisionMatch } from './updateFirstHrefInDivision.js';
+export declare function scopeDecoratedNavToPath(nav: DecoratedNavigationConfig, currentPath: string): DecoratedNavigationConfig;
+export declare function scopeDocsConfigNavToPath(docsConfig: DocsConfig, currentPath: string): DocsConfig;
+export type ScopedNavForPath = {
+    scopedNav: DecoratedNavigationConfig;
+    firstHrefInVersion: Map<string | undefined, DivisionMatch>;
+    firstHrefInLanguage: Map<LocaleType | undefined, DivisionMatch>;
+    currentVersion: string | undefined;
+    currentLanguage: LocaleType | undefined;
+};
+export declare function getScopedNavForPath({ decoratedNav, currentPath, userGroups, isPreview, }: {
+    decoratedNav: DecoratedNavigationConfig;
+    currentPath: string;
+    userGroups?: Set<string>;
+    isPreview?: boolean;
+}): ScopedNavForPath;