@mintlify/common 1.0.1273 → 1.0.1275

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

@@ -1,10 +1,10 @@
 import { jsx, toJs } from 'estree-util-to-js';
 import { isObject } from '../../../types/guards.js';
-import { collectModuleWrites, collectPatternNames, forEachCodeChild, } from '../../estreeReferences.js';
+import { collectDeclaredNames, collectModuleWrites, collectPatternNames, forEachCodeChild, visitReferences, } from '../../estreeReferences.js';
 import { getJsxEsmTree } from '../../snippets/getJsxEsmTree.js';
 import { BLOCK_LINK_LABEL, FIRST_PARTY_MARKDOWN_COMPONENT_SOURCE, } from './firstPartyMarkdownComponents.js';
 import { VISIBILITY_FOR_EXPECTED, isVisibilityAudience } from './remarkVisibilityForMarkdown.js';
-import { bindPattern, collectContextFromTree, EVAL_FAILED, evaluateStatic, identifierName, isNoOpSpreadValue, isStaticObject, nodeType, serializeStaticValue, unbindPattern, } from './staticEvaluator.js';
+import { bindPattern, collectContextFromTree, EVAL_FAILED, evaluateStatic, identifierName, isNoOpSpreadValue, isStaticObject, nodeType, readsMarkdownChildren, serializeStaticValue, staticPropertyName, unbindPattern, } from './staticEvaluator.js';
 export const MAX_UNFOLD_OUTPUT_BYTES = 2000000;
 // Charged before each materialization so branching definition chains cannot run
 // exponential call volumes under the byte budget.
@@ -99,7 +99,12 @@ export function collectMarkdownComponentContext(tree) {
     const defs = new Map(getFirstPartyComponentDefs());
     for (const [name, def] of context.defs)
         defs.set(name, def);
-    return { defs, moduleScope: context.moduleScope, literalScope: context.literalScope };
+    return {
+        defs,
+        moduleScope: context.moduleScope,
+        literalScope: context.literalScope,
+        declaredNames: context.declaredNames,
+    };
 }
 let firstPartyDefsCache;
 export function getFirstPartyComponentDefs() {
@@ -131,6 +136,49 @@ export const DROP_ELEMENTS = new Set([
     'template',
     'canvas',
 ]);
+// Elements whose content is running text, so a component inside them stands for a word or phrase
+const PHRASING_PARENTS = new Set([
+    'p',
+    'a',
+    'span',
+    'strong',
+    'b',
+    'em',
+    'i',
+    'code',
+    'del',
+    's',
+    'small',
+    'u',
+    'sub',
+    'sup',
+    'mark',
+    'abbr',
+    'q',
+    'cite',
+    'label',
+    'button',
+    'h1',
+    'h2',
+    'h3',
+    'h4',
+    'h5',
+    'h6',
+    'summary',
+    'figcaption',
+]);
+// Form controls hold interactive state, not readable content
+export const FORM_CONTROL_ELEMENTS = new Set([
+    'input',
+    'select',
+    'textarea',
+    'option',
+    'optgroup',
+    'datalist',
+    'output',
+    'progress',
+    'meter',
+]);
 export const UNWRAP_BLOCK_ELEMENTS = new Set([
     'div',
     'section',
@@ -232,6 +280,17 @@ export function prefixBlockquoteLines(text) {
         .map((line) => (line.trim() === '' ? '>' : `> ${line}`))
         .join('\n');
 }
+/** The first of `names` whose static attribute is a string with visible text. */
+function firstTextAttribute(node, names, ctx) {
+    for (const attributeName of names) {
+        const value = findStaticAttribute(node, attributeName, ctx);
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
+    }
+    return undefined;
+}
+// Text an inline component shows when it has no children. `path` names a location, not a label.
+const INLINE_TEXT_ATTRIBUTES = ['title', 'label', 'name', 'description', 'alt', 'aria-label'];
 function unfoldForeignComponent(node, ctx) {
     let children = serializeJsxChildren(node.children, ctx).trim();
     if (children === '') {
@@ -241,6 +300,19 @@ function unfoldForeignComponent(node, ctx) {
         else if (typeof childrenAttr === 'number')
             children = String(childrenAttr);
     }
+    // Inside running text the component stands for a word or phrase, not a block with a headline
+    if (ctx.inline === true) {
+        const attributeText = firstTextAttribute(node, INLINE_TEXT_ATTRIBUTES, ctx);
+        const text = children !== ''
+            ? children
+            : attributeText === undefined
+                ? ''
+                : escapeInterpolatedText(attributeText);
+        const inlineHref = findStaticAttribute(node, 'href', ctx);
+        if (text === '' || typeof inlineHref !== 'string' || inlineHref === '')
+            return text;
+        return `[${escapeLinkLabel(text)}](${markdownLinkDestination(inlineHref)})`;
+    }
     const description = findStaticAttribute(node, 'description', ctx);
     const alt = findStaticAttribute(node, 'alt', ctx);
     const body = children !== ''
@@ -547,6 +619,11 @@ function regenerateTag(node, name, children, ctx) {
             setAttribute(attrName.name, renderAttribute(attrName.name, resolved.value));
             continue;
         }
+        // An HTML attribute that cannot be resolved would print code, so it is left out
+        if (isIntrinsic) {
+            attrs.delete(attrName.name);
+            continue;
+        }
         const value = attribute.value;
         const source = nodeType(value) === 'JSXExpressionContainer' && isObject(value)
             ? serializeExpressionSource(value.expression)
@@ -562,13 +639,34 @@ function regenerateTag(node, name, children, ctx) {
     }
     return `<${name}${rendered}>${children}</${name}>`;
 }
+/**
+ * Whether a sibling puts the element beside it inside running text: text on the same line, or an
+ * interpolated value. A line break between them means the element stands on its own line.
+ */
+function touchesRunningText(sibling, side) {
+    if (!isObject(sibling))
+        return false;
+    if (sibling.type === 'JSXExpressionContainer') {
+        const type = nodeType(sibling.expression);
+        return type !== 'JSXEmptyExpression' && type !== 'JSXElement' && type !== 'JSXFragment';
+    }
+    if (sibling.type !== 'JSXText' || typeof sibling.value !== 'string')
+        return false;
+    if (sibling.value.trim() === '')
+        return false;
+    return side === 'before' ? !/\n[ \t]*$/.test(sibling.value) : !/^[ \t]*\n/.test(sibling.value);
+}
 function serializeJsxChildren(children, ctx) {
     if (!Array.isArray(children))
         return '';
+    const kept = dropPairedDarkOnly(children, (node) => jsxClassName(node, ctx));
     let result = '';
-    for (const child of dropPairedDarkOnly(children, (node) => jsxClassName(node, ctx))) {
-        result += serializeJsxNode(child, ctx);
-    }
+    kept.forEach((child, index) => {
+        const inline = ctx.inline === true ||
+            touchesRunningText(kept[index - 1], 'before') ||
+            touchesRunningText(kept[index + 1], 'after');
+        result += serializeJsxNode(child, inline === (ctx.inline === true) ? ctx : Object.assign(Object.assign({}, ctx), { inline }));
+    });
     return result;
 }
 function jsxClassName(node, ctx) {
@@ -649,10 +747,124 @@ function serializeJsxExpression(expression, ctx) {
         const text = String(value);
         return ctx.verbatim === true ? text : escapeInterpolatedText(text);
     }
-    return '';
+    // A transformation of markdown children, such as uppercasing or truncating, cannot apply to
+    // their markdown; the children are kept as written so no words or links are lost
+    return producesMarkdownChildren(expression, ctx) ? ctx.childrenMarkdown : '';
+}
+// String methods whose result is a version of the text they are called on
+const TEXT_TRANSFORMING_METHODS = new Set([
+    'toUpperCase',
+    'toLowerCase',
+    'toLocaleUpperCase',
+    'toLocaleLowerCase',
+    'trim',
+    'trimStart',
+    'trimEnd',
+    'slice',
+    'substring',
+    'replace',
+    'replaceAll',
+    'padStart',
+    'padEnd',
+    'concat',
+    'normalize',
+    'toString',
+    'valueOf',
+]);
+// Wrappers that leave the value of the expression inside them unchanged
+const TRANSPARENT_WRAPPERS = new Set([
+    'ParenthesizedExpression',
+    'ChainExpression',
+    'TSAsExpression',
+    'TSSatisfiesExpression',
+    'TSNonNullExpression',
+    'TSTypeAssertion',
+]);
+/**
+ * Whether `node` evaluates to a version of the component's markdown children: a text method on
+ * them, a template or JSX that renders them, or a branch that does. An expression that only
+ * inspects them, such as a count or a comparison, does not.
+ */
+function producesMarkdownChildren(node, ctx) {
+    var _a;
+    let value = node;
+    while (isObject(value) &&
+        typeof value.type === 'string' &&
+        TRANSPARENT_WRAPPERS.has(value.type)) {
+        value = value.expression;
+    }
+    if (!isObject(value))
+        return false;
+    if (readsMarkdownChildren(value, ctx))
+        return true;
+    switch (value.type) {
+        case 'CallExpression': {
+            const callee = value.callee;
+            return (isObject(callee) &&
+                callee.type === 'MemberExpression' &&
+                TEXT_TRANSFORMING_METHODS.has((_a = staticPropertyName(callee)) !== null && _a !== void 0 ? _a : '') &&
+                producesMarkdownChildren(callee.object, ctx));
+        }
+        case 'ConditionalExpression':
+            return (producesMarkdownChildren(value.consequent, ctx) ||
+                producesMarkdownChildren(value.alternate, ctx));
+        case 'LogicalExpression':
+            return (producesMarkdownChildren(value.left, ctx) || producesMarkdownChildren(value.right, ctx));
+        case 'TemplateLiteral':
+        case 'JSXElement':
+        case 'JSXFragment':
+            return mentionsMarkdownChildren(value, ctx);
+        default:
+            return false;
+    }
+}
+/** Identifiers read as the object of a `.children` member, such as `props` in `props.children`. */
+function collectChildrenMemberObjects(node, objects) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            collectChildrenMemberObjects(child, objects);
+        return;
+    }
+    if (!isObject(node))
+        return;
+    if (node.type === 'MemberExpression' &&
+        staticPropertyName(node) === 'children' &&
+        isObject(node.object) &&
+        node.object.type === 'Identifier') {
+        objects.add(node.object);
+    }
+    forEachCodeChild(node, (child) => collectChildrenMemberObjects(child, objects));
+}
+/**
+ * Whether `node` reads the component's own markdown children: the children parameter, or
+ * `.children` on its props or rest object. Property names, object keys, and shadowing bindings
+ * named `children` are not reads of it.
+ */
+function mentionsMarkdownChildren(node, ctx) {
+    if (ctx.markdownChildren !== true)
+        return false;
+    const childrenObjects = new WeakSet();
+    collectChildrenMemberObjects(node, childrenObjects);
+    let found = false;
+    visitReferences(node, new Set(), {
+        reference: (identifier) => {
+            var _a, _b;
+            if (identifier.name === ctx.childrenName) {
+                found || (found = !((_b = (_a = ctx.failedProps) === null || _a === void 0 ? void 0 : _a.has('children')) !== null && _b !== void 0 ? _b : false));
+                return;
+            }
+            found || (found = childrenObjects.has(identifier) &&
+                (identifier.name === ctx.propsObjectName || identifier.name === ctx.restName));
+        },
+    });
+    return found;
 }
-function serializeJsxElement(node, ctx) {
+function serializeJsxElement(node, elementCtx) {
     const name = getJsxElementName(node);
+    // The content of a phrasing element is running text; a block element starts its own flow
+    const ctx = name !== undefined && PHRASING_PARENTS.has(name)
+        ? Object.assign(Object.assign({}, elementCtx), { inline: true }) : name !== undefined && UNWRAP_BLOCK_ELEMENTS.has(name)
+        ? Object.assign(Object.assign({}, elementCtx), { inline: false }) : elementCtx;
     if (name === undefined)
         return '';
     if (isAriaHidden(node, ctx))
@@ -670,6 +882,8 @@ function serializeJsxElement(node, ctx) {
     if (isIntrinsic) {
         if (DROP_ELEMENTS.has(name))
             return accessibleFallback(node, ctx);
+        if (FORM_CONTROL_ELEMENTS.has(name))
+            return '';
         if (name === 'br')
             return '\n';
         if (name === 'hr')
@@ -1177,7 +1391,10 @@ function isResolvedReturn(expression, env) {
     return true;
 }
 /** A definition's scope for one usage: `base` plus its parameters bound from `props`. */
-function bindComponentScope(paramInfo, base, props, failedProps, childrenMarkdown, effectiveChildren) {
+// Markdown a usage's children were serialized to, beyond plain words: links, emphasis, code,
+// escapes, HTML, or more than one line
+const MARKDOWN_SYNTAX = /[\\`*_[\]<>|~]|\n/;
+function bindComponentScope(paramInfo, base, props, failedProps, childrenMarkdown, effectiveChildren, declaredNames, markdownChildren = false) {
     const scope = new Map(base);
     if (paramInfo.propsObjectName !== undefined) {
         const propsObject = {};
@@ -1209,6 +1426,9 @@ function bindComponentScope(paramInfo, base, props, failedProps, childrenMarkdow
         failedProps,
         restName: paramInfo.restName,
         restFailedProps,
+        declaredNames,
+        childrenName: paramInfo.childrenName,
+        markdownChildren,
     };
     // Supplied children are bound first, so later parameter defaults can read them
     if (childrenMarkdown !== '')
@@ -1262,31 +1482,6 @@ function bindComponentScope(paramInfo, base, props, failedProps, childrenMarkdow
     }
     return env;
 }
-/** Every name a function body declares or binds, at any depth. */
-function collectDeclaredNames(node, names = new Set()) {
-    if (Array.isArray(node)) {
-        for (const child of node)
-            collectDeclaredNames(child, names);
-        return names;
-    }
-    if (!isObject(node))
-        return names;
-    if (node.type === 'VariableDeclarator')
-        collectPatternNames(node.id, names);
-    if ((node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration') &&
-        isObject(node.id) &&
-        typeof node.id.name === 'string') {
-        names.add(node.id.name);
-    }
-    if (Array.isArray(node.params)) {
-        for (const param of node.params)
-            collectPatternNames(param, names);
-    }
-    if (node.type === 'CatchClause')
-        collectPatternNames(node.param, names);
-    forEachCodeChild(node, (child) => collectDeclaredNames(child, names));
-    return names;
-}
 export function materializeComponent(def, name, props, childrenMarkdown, ctx, failedProps, 
 // The static value of a body made of one expression, which `children` keeps over its markdown
 bodyValue, trusted) {
@@ -1310,10 +1505,10 @@ bodyValue, trusted) {
     const effectiveChildren = scopeChildren !== null && scopeChildren !== void 0 ? scopeChildren : childrenMarkdown;
     const paramInfo = analyzeParams(def.params);
     const named = new Set(paramInfo.bindings.map((binding) => binding.propName));
-    const env = bindComponentScope(paramInfo, ctx.moduleScope, props, failedProps, childrenMarkdown, effectiveChildren);
+    const env = bindComponentScope(paramInfo, ctx.moduleScope, props, failedProps, childrenMarkdown, effectiveChildren, ctx.declaredNames, scopeChildren === undefined && MARKDOWN_SYNTAX.test(childrenMarkdown));
     // Props not supplied from trusted values are unknown here, so a default cannot stand in for them
     const untrusted = new Set([...props.keys()].filter((key) => (trusted === null || trusted === void 0 ? void 0 : trusted.props.has(key)) !== true));
-    const trustedEnvironment = bindComponentScope(paramInfo, trustedEnv(ctx).scope, (_a = trusted === null || trusted === void 0 ? void 0 : trusted.props) !== null && _a !== void 0 ? _a : new Map(), new Set([...((_b = trusted === null || trusted === void 0 ? void 0 : trusted.failedProps) !== null && _b !== void 0 ? _b : []), ...untrusted, ...(failedProps !== null && failedProps !== void 0 ? failedProps : [])]), '', '');
+    const trustedEnvironment = bindComponentScope(paramInfo, trustedEnv(ctx).scope, (_a = trusted === null || trusted === void 0 ? void 0 : trusted.props) !== null && _a !== void 0 ? _a : new Map(), new Set([...((_b = trusted === null || trusted === void 0 ? void 0 : trusted.failedProps) !== null && _b !== void 0 ? _b : []), ...untrusted, ...(failedProps !== null && failedProps !== void 0 ? failedProps : [])]), '', '', ctx.declaredNames);
     // Locals may shadow trusted names with values that are not
     for (const local of collectDeclaredNames(def.body))
         trustedEnvironment.scope.delete(local);
@@ -1324,7 +1519,7 @@ bodyValue, trusted) {
         return '';
     if (!isResolvedReturn(returnExpression, env))
         return undefined;
-    const serializeContext = Object.assign(Object.assign({ defs: ctx.defs, moduleScope: ctx.moduleScope, literalScope: ctx.literalScope, stack: [...ctx.stack, def], budget: ctx.budget }, env), { trusted: trustedEnvironment, restCarriesChildren: !named.has('children'), childrenMarkdown, childrenName: paramInfo.childrenName });
+    const serializeContext = Object.assign(Object.assign({ defs: ctx.defs, moduleScope: ctx.moduleScope, literalScope: ctx.literalScope, declaredNames: ctx.declaredNames, stack: [...ctx.stack, def], budget: ctx.budget }, env), { trusted: trustedEnvironment, restCarriesChildren: !named.has('children'), childrenMarkdown, childrenName: paramInfo.childrenName });
     return serializeJsxExpression(returnExpression, serializeContext);
 }
 export function collectUsageProps(node, ctx, failed) {
@@ -1334,6 +1529,7 @@ export function collectUsageProps(node, ctx, failed) {
         if (attribute.type === 'mdxJsxExpressionAttribute') {
             const spread = evaluateStatic(extractProgramExpression((_a = attribute.data) === null || _a === void 0 ? void 0 : _a.estree), {
                 scope: ctx.moduleScope,
+                declaredNames: ctx.declaredNames,
             });
             if (spread.ok && isStaticObject(spread.value)) {
                 for (const [key, value] of Object.entries(spread.value)) {
@@ -1357,7 +1553,10 @@ export function collectUsageProps(node, ctx, failed) {
         }
         const estree = (_b = attribute.value.data) === null || _b === void 0 ? void 0 : _b.estree;
         const expression = extractProgramExpression(estree);
-        const evaluated = evaluateStatic(expression, { scope: ctx.moduleScope });
+        const evaluated = evaluateStatic(expression, {
+            scope: ctx.moduleScope,
+            declaredNames: ctx.declaredNames,
+        });
         if (evaluated.ok)
             setKnownProp(props, failed, attribute.name, evaluated.value);
         else
@@ -1404,6 +1603,7 @@ export function serializeExpressionJsx(expression, ctx) {
         defs: ctx.defs,
         moduleScope: ctx.moduleScope,
         literalScope: ctx.literalScope,
+        declaredNames: ctx.declaredNames,
         stack: ctx.stack,
         budget: ctx.budget,
         scope: new Map(ctx.moduleScope),