@mintlify/common 1.0.1152 → 1.0.1154

package/dist/mdx/plugins/remark/remarkUserMentions.d.ts

@@ -3,4 +3,5 @@ import { type UserMentionNameResolver } from '../../mentions/userMentionToken.js
 export type RemarkUserMentionsOptions = {
     resolveUserName?: UserMentionNameResolver;
 };
+export declare function collectUserMentionText(tree: Root): string[];
 export declare const remarkUserMentions: ({ resolveUserName }?: RemarkUserMentionsOptions) => (tree: Root) => void;

package/dist/mdx/plugins/remark/remarkUserMentions.js

@@ -1,12 +1,12 @@
 import { visit } from 'unist-util-visit';
-import { escapeMentionNameForSource, flattenUserMentionTokens, hasUserMentionTokens, isMentionTextAttribute, isUserMentionId, } from '../../mentions/userMentionToken.js';
+import { escapeMentionNameForSource, extractUserMentionIds, flattenUserMentionTokens, hasUserMentionTokens, isMentionTextAttribute, isUserMentionId, userMentionToken, } from '../../mentions/userMentionToken.js';
 import { isPromptBodySourceAttribute } from './remarkPrompt.js';
 import { TITLE_COMPONENTS } from './remarkTitleMarkdown.js';
 const IN_TEXT = { inText: true };
 const isMdxJsxElement = (node) => node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement';
 const isParent = (node) => 'children' in node && Array.isArray(node.children);
 const isRecord = (value) => typeof value === 'object' && value !== null;
-function flattenStringLiteralExpression(expression, resolve, { escapeNames, rawSource }) {
+function stringLiteralSurface(expression, { escapeNames, scan }, onSurface) {
     var _a;
     const program = (_a = expression.data) === null || _a === void 0 ? void 0 : _a.estree;
     const statement = program === null || program === void 0 ? void 0 : program.body[0];
@@ -15,45 +15,63 @@ function flattenStringLiteralExpression(expression, resolve, { escapeNames, rawS
     const literal = statement.expression;
     if (!isRecord(literal) || literal.type !== 'Literal' || typeof literal.value !== 'string')
         return;
-    const scan = rawSource ? undefined : IN_TEXT;
-    if (!hasUserMentionTokens(literal.value, scan))
-        return;
-    const flat = flattenUserMentionTokens(literal.value, (userId) => {
-        const name = resolve === null || resolve === void 0 ? void 0 : resolve(userId);
-        return name === undefined || !escapeNames ? name : escapeMentionNameForSource(name);
-    }, scan);
-    literal.value = flat;
-    literal.raw = JSON.stringify(flat);
-    expression.value = JSON.stringify(flat);
+    onSurface({
+        value: literal.value,
+        scan,
+        escapeNames,
+        set: (next) => {
+            literal.value = next;
+            literal.raw = JSON.stringify(next);
+            expression.value = JSON.stringify(next);
+        },
+    });
 }
-function foldShortcutReferences(parent, resolve) {
+function shortcutMentionId(text, reference) {
     var _a;
+    if (text.type !== 'text' || !text.value.endsWith('@'))
+        return undefined;
+    if (reference.type !== 'linkReference' || reference.referenceType !== 'shortcut')
+        return undefined;
+    const label = (_a = reference.label) !== null && _a !== void 0 ? _a : reference.identifier;
+    if (!isUserMentionId(label))
+        return undefined;
+    const [only, ...rest] = reference.children;
+    if (rest.length > 0 || !only || only.type !== 'text' || only.value !== label)
+        return undefined;
+    return label;
+}
+function shortcutReferenceSurfaces(parent, onSurface) {
     const children = parent.children;
     for (let index = 0; index < children.length - 1; index++) {
         const text = children[index];
         const reference = children[index + 1];
-        if (!text || !reference || text.type !== 'text' || !text.value.endsWith('@'))
-            continue;
-        if (reference.type !== 'linkReference' || reference.referenceType !== 'shortcut')
-            continue;
-        const label = (_a = reference.label) !== null && _a !== void 0 ? _a : reference.identifier;
-        if (!isUserMentionId(label))
+        if (!text || !reference || text.type !== 'text')
             continue;
-        const [only, ...rest] = reference.children;
-        if (rest.length > 0 || !only || only.type !== 'text' || only.value !== label)
+        const label = shortcutMentionId(text, reference);
+        if (label === undefined)
             continue;
-        text.value = text.value.slice(0, -1) + flattenUserMentionTokens(`@[${label}]`, resolve);
-        children.splice(index + 1, 1);
-        const next = children[index + 1];
-        if ((next === null || next === void 0 ? void 0 : next.type) === 'text') {
-            text.value += next.value;
-            children.splice(index + 1, 1);
-        }
-        index--;
+        let folded = false;
+        onSurface({
+            value: userMentionToken(label),
+            scan: undefined,
+            escapeNames: false,
+            set: (next) => {
+                text.value = text.value.slice(0, -1) + next;
+                children.splice(index + 1, 1);
+                const following = children[index + 1];
+                if ((following === null || following === void 0 ? void 0 : following.type) === 'text') {
+                    text.value += following.value;
+                    children.splice(index + 1, 1);
+                }
+                folded = true;
+            },
+        });
+        if (folded)
+            index--;
     }
 }
 // A Prompt body is plain text on the page, so code and math inside it are text there too.
-function flattenPromptCode(prompt, resolve) {
+function promptCodeSurfaces(prompt, onSurface) {
     visit(prompt, (child) => {
         if (child.type !== 'inlineCode' &&
             child.type !== 'code' &&
@@ -61,47 +79,78 @@ function flattenPromptCode(prompt, resolve) {
             child.type !== 'math') {
             return;
         }
-        if (hasUserMentionTokens(child.value)) {
-            child.value = flattenUserMentionTokens(child.value, resolve);
-        }
+        onSurface({
+            value: child.value,
+            scan: undefined,
+            escapeNames: false,
+            set: (next) => {
+                child.value = next;
+            },
+        });
     });
 }
-export const remarkUserMentions = ({ resolveUserName } = {}) => (tree) => {
-    // Body text and text-bearing component attributes only: image alt/title, link and definition titles are HTML attributes and stay as written.
+// Body text and text-bearing component attributes only: image alt/title, link
+// and definition titles are HTML attributes and stay as written.
+function visitUserMentionSurfaces(tree, onSurface) {
     visit(tree, (node) => {
         if (node.type === 'text') {
-            if (hasUserMentionTokens(node.value, IN_TEXT)) {
-                node.value = flattenUserMentionTokens(node.value, resolveUserName, IN_TEXT);
-            }
+            const text = node;
+            onSurface({
+                value: text.value,
+                scan: IN_TEXT,
+                escapeNames: false,
+                set: (next) => {
+                    text.value = next;
+                },
+            });
             return;
         }
         if (isMdxJsxElement(node)) {
             if (node.name === 'Prompt')
-                flattenPromptCode(node, resolveUserName);
+                promptCodeSurfaces(node, onSurface);
             const titleIsMarkdown = node.name !== null && TITLE_COMPONENTS.has(node.name);
             for (const attribute of node.attributes) {
                 if (attribute.type !== 'mdxJsxAttribute' || !isMentionTextAttribute(attribute.name)) {
                     continue;
                 }
+                const escapeNames = titleIsMarkdown && attribute.name === 'title';
                 if (typeof attribute.value === 'string') {
-                    if (!hasUserMentionTokens(attribute.value, IN_TEXT))
-                        continue;
-                    const escape = titleIsMarkdown && attribute.name === 'title';
-                    attribute.value = flattenUserMentionTokens(attribute.value, (userId) => {
-                        const name = resolveUserName === null || resolveUserName === void 0 ? void 0 : resolveUserName(userId);
-                        return name === undefined || !escape ? name : escapeMentionNameForSource(name);
-                    }, IN_TEXT);
+                    onSurface({
+                        value: attribute.value,
+                        scan: IN_TEXT,
+                        escapeNames,
+                        set: (next) => {
+                            attribute.value = next;
+                        },
+                    });
                 }
                 else if (attribute.value && typeof attribute.value === 'object') {
-                    flattenStringLiteralExpression(attribute.value, resolveUserName, {
-                        escapeNames: titleIsMarkdown && attribute.name === 'title',
-                        rawSource: isPromptBodySourceAttribute(attribute),
-                    });
+                    stringLiteralSurface(attribute.value, { escapeNames, scan: isPromptBodySourceAttribute(attribute) ? undefined : IN_TEXT }, onSurface);
                 }
             }
         }
         if (isParent(node) && node.children.some((child) => child.type === 'linkReference')) {
-            foldShortcutReferences(node, resolveUserName);
+            shortcutReferenceSurfaces(node, onSurface);
         }
     });
+}
+export function collectUserMentionText(tree) {
+    const out = [];
+    visitUserMentionSurfaces(tree, ({ value, scan }) => {
+        if (scan === IN_TEXT)
+            out.push(value);
+        else
+            out.push(...extractUserMentionIds(value).map(userMentionToken));
+    });
+    return out;
+}
+export const remarkUserMentions = ({ resolveUserName } = {}) => (tree) => {
+    visitUserMentionSurfaces(tree, ({ value, scan, escapeNames, set }) => {
+        if (!hasUserMentionTokens(value, scan))
+            return;
+        set(flattenUserMentionTokens(value, (userId) => {
+            const name = resolveUserName === null || resolveUserName === void 0 ? void 0 : resolveUserName(userId);
+            return name === undefined || !escapeNames ? name : escapeMentionNameForSource(name);
+        }, scan));
+    });
 };

package/dist/navigation/decoratedNavTree.d.ts

@@ -0,0 +1,11 @@
+import type { DecoratedDivisionConfig, DecoratedGroupConfig, DecoratedNavigationConfig, DecoratedPageConfig } from '@mintlify/validation';
+export type DecoratedNavNode = DecoratedNavigationConfig | DecoratedDivisionConfig | DecoratedGroupConfig | DecoratedPageConfig;
+export type DecoratedNavPageEntry = {
+    title: string;
+    mode?: string;
+};
+export declare function decoratedNavDivisions(node: DecoratedNavNode): DecoratedDivisionConfig[];
+export declare function decoratedNavChildren(node: DecoratedNavNode): DecoratedNavNode[];
+export declare const decoratedNavContains: (node: DecoratedNavNode, path: string) => boolean;
+export declare const findDecoratedNavPage: (node: DecoratedNavNode, path: string) => DecoratedNavPageEntry | null;
+export declare function decoratedNavSections(nav: DecoratedNavNode, path: string): DecoratedNavNode[];

package/dist/navigation/decoratedNavTree.js

@@ -0,0 +1,72 @@
+import { replaceSlashIndex } from '../slug/replaceSlashIndex.js';
+import { isPage } from './isPage.js';
+const normalizeNavPath = (p) => replaceSlashIndex(p.replace(/^\/+/, '').replace(/\/+$/, ''));
+const hrefOf = (node) => isPage(node) ? node.href : 'href' in node ? node.href : undefined;
+export function decoratedNavDivisions(node) {
+    if (isPage(node))
+        return [];
+    if ('languages' in node)
+        return node.languages;
+    if ('versions' in node)
+        return node.versions;
+    if ('products' in node)
+        return node.products;
+    if ('tabs' in node)
+        return node.tabs;
+    if ('anchors' in node)
+        return node.anchors;
+    if ('dropdowns' in node)
+        return node.dropdowns;
+    return [];
+}
+export function decoratedNavChildren(node) {
+    if (isPage(node))
+        return [];
+    if ('group' in node)
+        return node.root ? [node.root, ...node.pages] : node.pages;
+    if ('pages' in node)
+        return node.pages;
+    if ('groups' in node)
+        return node.groups;
+    if ('menu' in node)
+        return node.menu;
+    return [];
+}
+const matches = (node, path) => {
+    const href = hrefOf(node);
+    return href !== undefined && normalizeNavPath(href) === path;
+};
+function contains(node, path) {
+    if (matches(node, path))
+        return true;
+    return (decoratedNavChildren(node).some((c) => contains(c, path)) ||
+        decoratedNavDivisions(node).some((c) => contains(c, path)));
+}
+function findPage(node, path) {
+    if (isPage(node))
+        return matches(node, path) ? { title: node.title, mode: node.mode } : null;
+    for (const child of [...decoratedNavChildren(node), ...decoratedNavDivisions(node)]) {
+        const found = findPage(child, path);
+        if (found)
+            return found;
+    }
+    return null;
+}
+export const decoratedNavContains = (node, path) => contains(node, normalizeNavPath(path));
+export const findDecoratedNavPage = (node, path) => findPage(node, normalizeNavPath(path));
+// the nodes whose own pages (not a nested division's) hold the path: the
+// root for a flat nav, else the innermost division chain down to the page
+export function decoratedNavSections(nav, path) {
+    const target = normalizeNavPath(path);
+    const out = [];
+    const walk = (node) => {
+        for (const division of decoratedNavDivisions(node)) {
+            if (contains(division, target))
+                walk(division);
+        }
+        if (decoratedNavChildren(node).some((c) => contains(c, target)))
+            out.push(node);
+    };
+    walk(nav);
+    return out;
+}

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

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

package/dist/navigation/decoratedNavTree.test.js

@@ -0,0 +1,51 @@
+import { decoratedNavContains, decoratedNavSections, findDecoratedNavPage, } from './decoratedNavTree.js';
+const nav = {
+    tabs: [
+        {
+            tab: 'Guides',
+            groups: [
+                { group: 'Start', pages: [{ href: '/guides/intro', title: 'Intro' }] },
+                { group: 'More', pages: [{ href: '/guides/deploy', title: 'Deploy', mode: 'custom' }] },
+            ],
+        },
+        { tab: 'API', pages: [{ href: '/api/overview', title: 'Overview' }] },
+    ],
+};
+describe('decoratedNavContains', () => {
+    it('finds pages through divisions and groups, ignoring slashes and /index', () => {
+        expect(decoratedNavContains(nav, '/guides/deploy')).toBe(true);
+        expect(decoratedNavContains(nav, 'guides/deploy/')).toBe(true);
+        expect(decoratedNavContains(nav, '/api/overview/index')).toBe(true);
+        expect(decoratedNavContains(nav, '/nowhere')).toBe(false);
+    });
+});
+describe('findDecoratedNavPage', () => {
+    it('returns the page title and mode', () => {
+        expect(findDecoratedNavPage(nav, '/guides/deploy')).toEqual({
+            title: 'Deploy',
+            mode: 'custom',
+        });
+        expect(findDecoratedNavPage(nav, '/api/overview')).toEqual({
+            title: 'Overview',
+            mode: undefined,
+        });
+        expect(findDecoratedNavPage(nav, '/nowhere')).toBeNull();
+    });
+});
+describe('decoratedNavSections', () => {
+    it('returns the division whose own pages hold the path', () => {
+        const sections = decoratedNavSections(nav, '/guides/intro');
+        expect(sections).toHaveLength(1);
+        expect(sections[0]).toBe(nav.tabs[0]);
+        expect(decoratedNavSections(nav, '/nowhere')).toEqual([]);
+    });
+    it('returns the root for a flat nav', () => {
+        const flat = {
+            pages: [
+                { href: '/a', title: 'A' },
+                { href: '/b', title: 'B' },
+            ],
+        };
+        expect(decoratedNavSections(flat, '/a')).toEqual([flat]);
+    });
+});

package/dist/navigation/index.d.ts

@@ -4,6 +4,7 @@ export * from './generatePathToBreadcrumbsMap.js';
 export * from './getFirstPageFromNavigation.js';
 export * from './generatePathToBreadcrumbsMapForDocsConfig.js';
 export * from './getAllPathsInDocsNav.js';
+export * from './decoratedNavTree.js';
 export * from './getAllPathsInDecoratedNav.js';
 export * from './checkNavAccess.js';
 export * from './filterDivisions.js';

package/dist/navigation/index.js

@@ -4,6 +4,7 @@ export * from './generatePathToBreadcrumbsMap.js';
 export * from './getFirstPageFromNavigation.js';
 export * from './generatePathToBreadcrumbsMapForDocsConfig.js';
 export * from './getAllPathsInDocsNav.js';
+export * from './decoratedNavTree.js';
 export * from './getAllPathsInDecoratedNav.js';
 export * from './checkNavAccess.js';
 export * from './filterDivisions.js';