@mintlify/common 1.0.1221 → 1.0.1222

package/dist/mdx/islands/island-module-builder.js

@@ -0,0 +1,472 @@
+import { jsx as jsxHandlers, toJs } from 'estree-util-to-js';
+import { parseInlineStyle } from '../../parse-inline-style.js';
+import { resolveRelativeUrl } from '../plugins/remark/remarkResolveRelativeLinks.js';
+import { allowedComponents } from '../utils.js';
+import { bindingHead, lineOf } from './island-bindings.js';
+import { isIntrinsic, isListLoose } from './island-placement.js';
+import { UNSAFE_KEYS, identifier, literal, toStaticExpression, valueToExpression, } from './static-expressions.js';
+const BLOCKED_ELEMENTS = new Set([
+    'script',
+    'style',
+    'iframe',
+    'object',
+    'embed',
+    'form',
+    'base',
+    'meta',
+    'link',
+    'foreignobject',
+]);
+export const MOVE_TO_SNIPPET = 'Move this into a snippet.';
+const MINTLIFY_COMPONENTS = new Set(allowedComponents);
+const URL_ATTRIBUTES = new Map([
+    ['a', 'href'],
+    ['img', 'src'],
+    ['source', 'src'],
+]);
+const container = (expression) => ({
+    type: 'JSXExpressionContainer',
+    expression,
+});
+const jsxName = (name) => {
+    if (name.includes(':')) {
+        const [namespace = '', local = ''] = name.split(':');
+        return {
+            type: 'JSXNamespacedName',
+            namespace: { type: 'JSXIdentifier', name: namespace },
+            name: { type: 'JSXIdentifier', name: local },
+        };
+    }
+    const [first = '', ...rest] = name.split('.');
+    let result = { type: 'JSXIdentifier', name: first };
+    for (const part of rest) {
+        result = {
+            type: 'JSXMemberExpression',
+            object: result,
+            property: { type: 'JSXIdentifier', name: part },
+        };
+    }
+    return result;
+};
+const jsxElement = (name, attributes, children) => {
+    const elementName = jsxName(name);
+    const selfClosing = children.length === 0;
+    return {
+        type: 'JSXElement',
+        openingElement: { type: 'JSXOpeningElement', name: elementName, attributes, selfClosing },
+        closingElement: selfClosing ? null : { type: 'JSXClosingElement', name: jsxName(name) },
+        children,
+    };
+};
+const jsxAttribute = (name, value) => {
+    const attributeName = jsxName(name);
+    return {
+        type: 'JSXAttribute',
+        name: attributeName.type === 'JSXMemberExpression'
+            ? { type: 'JSXIdentifier', name }
+            : attributeName,
+        value: value ? container(value) : null,
+    };
+};
+const newline = () => container(literal('\n'));
+const wrap = (units) => [
+    newline(),
+    ...units.flatMap((unit, index) => (index > 0 ? [newline(), ...unit] : unit)),
+    ...(units.length > 0 ? [newline()] : []),
+];
+const trimLines = (value) => value.replace(/[\t ]*(\r?\n|\r)[\t ]*/g, '$1');
+const trimStart = (value) => value.replace(/^[\t ]+/, '');
+const codeText = (value) => value.replace(/\r?\n|\r/g, ' ');
+const trimAfterBreak = (node) => {
+    switch (node.type) {
+        case 'text':
+            return Object.assign(Object.assign({}, node), { value: trimStart(node.value) });
+        case 'inlineCode':
+            return Object.assign(Object.assign({}, node), { value: trimStart(codeText(node.value)) });
+        case 'strong':
+        case 'emphasis':
+        case 'delete':
+        case 'link': {
+            const [head, ...rest] = node.children;
+            return (head === null || head === void 0 ? void 0 : head.type) === 'text'
+                ? Object.assign(Object.assign({}, node), { children: [Object.assign(Object.assign({}, head), { value: trimStart(head.value) }), ...rest] }) : node;
+        }
+        default:
+            return node;
+    }
+};
+const isJsxPhrasing = (node) => node.type === 'mdxJsxTextElement' || node.type === 'mdxTextExpression';
+const unravel = (nodes) => nodes.flatMap((node) => node.type === 'paragraph' &&
+    node.children.some(isJsxPhrasing) &&
+    node.children.every((child) => isJsxPhrasing(child) || (child.type === 'text' && /^[\t\n\v\f\r ]*$/.test(child.value)))
+    ? node.children.filter((child) => child.type !== 'text' || !/^[\t\r\n ]+$/.test(child.value))
+    : [node]);
+const truncate = (value, max = 40) => value.length > max ? `${value.slice(0, max - 1)}…` : value;
+export class IslandModuleBuilder {
+    constructor(rootName, pagePath, bindings, undeclared, consts, sideEffects, order) {
+        this.rootName = rootName;
+        this.pagePath = pagePath;
+        this.bindings = bindings;
+        this.undeclared = undeclared;
+        this.consts = consts;
+        this.sideEffects = sideEffects;
+        this.order = order;
+        this.usedBindings = new Map();
+        this.usedConsts = new Set();
+        this.errors = [];
+    }
+    url(value, isPageLink) {
+        return literal(resolveRelativeUrl(this.pagePath, value, isPageLink));
+    }
+    fail(node, message) {
+        this.errors.push({ line: lineOf(node), message });
+    }
+    insideRoot() {
+        return `the package component <${this.rootName}>`;
+    }
+    element(node) {
+        if (!node.name) {
+            const children = this.children(node.children);
+            return {
+                type: 'JSXFragment',
+                openingFragment: { type: 'JSXOpeningFragment' },
+                closingFragment: { type: 'JSXClosingFragment' },
+                children,
+            };
+        }
+        const name = node.name;
+        const head = bindingHead(name);
+        const binding = head === undefined ? undefined : this.bindings.get(head);
+        if (binding === null || binding === void 0 ? void 0 : binding.invalidName) {
+            this.fail(node, `<${name}> is imported from "${binding.source}" by the string name ${JSON.stringify(binding.imported)}, which isn't a valid identifier. Import it by an identifier name, or move this into a snippet.`);
+            return undefined;
+        }
+        else if (binding && head !== undefined) {
+            this.usedBindings.set(head, binding);
+        }
+        else if (isIntrinsic(name)) {
+            if (BLOCKED_ELEMENTS.has(name.toLowerCase())) {
+                this.fail(node, `<${name}> isn't allowed inside ${this.insideRoot()}.`);
+                return undefined;
+            }
+        }
+        else if (head !== undefined && this.undeclared.has(head)) {
+            this.fail(node, `<${name}> is imported from "${this.undeclared.get(head)}", which isn't listed in package.json dependencies.`);
+            return undefined;
+        }
+        else if (MINTLIFY_COMPONENTS.has(name)) {
+            this.fail(node, `<${name}> is a Mintlify component and can't render inside ${this.insideRoot()}. Move <${name}> outside <${this.rootName}>.`);
+            return undefined;
+        }
+        else {
+            this.fail(node, `<${name}> isn't imported from a package or a package snippet, so it can't render inside ${this.insideRoot()}. ${MOVE_TO_SNIPPET}`);
+            return undefined;
+        }
+        const attributes = [];
+        for (const attribute of node.attributes) {
+            const converted = this.attribute(node, name, attribute);
+            if (converted)
+                attributes.push(converted);
+        }
+        return jsxElement(name, attributes, this.children(node.children));
+    }
+    attribute(node, elementName, attribute) {
+        var _a;
+        const at = attribute.position ? attribute : node;
+        if (attribute.type === 'mdxJsxExpressionAttribute') {
+            this.fail(at, `<${elementName}> spreads props ({...}), which can't be evaluated at build time. ${MOVE_TO_SNIPPET}`);
+            return undefined;
+        }
+        const prop = `Prop "${attribute.name}" on <${elementName}>`;
+        if (/^on[A-Z]/.test(attribute.name) ||
+            (isIntrinsic(elementName) && /^on/i.test(attribute.name))) {
+            this.fail(at, `${prop} is an event handler, and package components in MDX only take static props. ${MOVE_TO_SNIPPET}`);
+            return undefined;
+        }
+        if (attribute.name === 'dangerouslySetInnerHTML' || attribute.name === 'ref') {
+            this.fail(at, `${prop} isn't allowed inside ${this.insideRoot()}.`);
+            return undefined;
+        }
+        if (attribute.value === null || attribute.value === undefined) {
+            return jsxAttribute(attribute.name, null);
+        }
+        if (typeof attribute.value === 'string') {
+            if (attribute.name === 'style' && isIntrinsic(elementName)) {
+                const style = parseInlineStyle(attribute.value);
+                const expression = valueToExpression(style);
+                if (expression)
+                    return jsxAttribute('style', expression);
+                const key = Object.keys(style).find((name) => UNSAFE_KEYS.has(name));
+                this.fail(at, this.propFailure(prop, { reason: 'key', name: key }));
+                return undefined;
+            }
+            return jsxAttribute(attribute.name, URL_ATTRIBUTES.get(elementName) === attribute.name
+                ? this.url(attribute.value, attribute.name === 'href')
+                : literal(attribute.value));
+        }
+        const program = (_a = attribute.value.data) === null || _a === void 0 ? void 0 : _a.estree;
+        const statement = program === null || program === void 0 ? void 0 : program.body[0];
+        if (!program || program.body.length !== 1 || (statement === null || statement === void 0 ? void 0 : statement.type) !== 'ExpressionStatement') {
+            this.fail(at, `${prop} is an expression that can't be evaluated at build time. ${MOVE_TO_SNIPPET}`);
+            return undefined;
+        }
+        const converted = toStaticExpression(statement.expression, this.consts, this.usedConsts);
+        if (converted.ok)
+            return jsxAttribute(attribute.name, converted.expression);
+        this.fail(at, this.propFailure(prop, converted));
+        return undefined;
+    }
+    propFailure(prop, failure) {
+        switch (failure.reason) {
+            case 'function':
+                return `${prop} is a function, and package components in MDX only take static props. ${MOVE_TO_SNIPPET}`;
+            case 'jsx':
+                return `${prop} is JSX, and package components in MDX only take static props. ${MOVE_TO_SNIPPET}`;
+            case 'identifier':
+                return `${prop} uses "${failure.name}", which isn't a literal \`export const\` in this page. ${MOVE_TO_SNIPPET}`;
+            case 'const':
+                return `${prop} uses \`export const ${failure.name}\`, whose value isn't a literal (strings, numbers, booleans, arrays and objects only). ${MOVE_TO_SNIPPET}`;
+            case 'key':
+                return `${prop} uses the object key "${failure.name}", which isn't allowed.`;
+            case 'expression':
+                return `${prop} is an expression that can't be evaluated at build time. ${MOVE_TO_SNIPPET}`;
+        }
+    }
+    intrinsic(name, children, attributes = []) {
+        return jsxElement(name, attributes, this.children(children));
+    }
+    children(nodes) {
+        const result = [];
+        let afterBreak = false;
+        for (const node of unravel(nodes)) {
+            const converted = this.child(afterBreak ? trimAfterBreak(node) : node);
+            afterBreak = node.type === 'break';
+            if (converted)
+                result.push(...converted);
+        }
+        return result;
+    }
+    child(node) {
+        var _a, _b;
+        switch (node.type) {
+            case 'mdxJsxFlowElement':
+            case 'mdxJsxTextElement': {
+                const element = this.element(node);
+                return element ? [element] : undefined;
+            }
+            case 'text': {
+                const value = trimLines(node.value);
+                return value === '' ? [] : [container(literal(value))];
+            }
+            case 'paragraph':
+                return [this.intrinsic('p', node.children)];
+            case 'strong':
+                return [this.intrinsic('strong', node.children)];
+            case 'emphasis':
+                return [this.intrinsic('em', node.children)];
+            case 'delete':
+                return [this.intrinsic('del', node.children)];
+            case 'inlineCode':
+                return [jsxElement('code', [], [container(literal(codeText(node.value)))])];
+            case 'break':
+                return [jsxElement('br', [], []), newline()];
+            case 'thematicBreak':
+                return [jsxElement('hr', [], [])];
+            case 'blockquote':
+                return [
+                    jsxElement('blockquote', [], wrap(unravel(node.children).map((child) => { var _a; return (_a = this.child(child)) !== null && _a !== void 0 ? _a : []; }))),
+                ];
+            case 'heading':
+                return [this.intrinsic(`h${node.depth}`, node.children)];
+            case 'link': {
+                const attributes = [jsxAttribute('href', this.url(node.url, true))];
+                if (node.title)
+                    attributes.push(jsxAttribute('title', literal(node.title)));
+                return [this.intrinsic('a', node.children, attributes)];
+            }
+            case 'image': {
+                const attributes = [
+                    jsxAttribute('src', this.url(node.url, false)),
+                    jsxAttribute('alt', literal((_a = node.alt) !== null && _a !== void 0 ? _a : '')),
+                ];
+                if (node.title)
+                    attributes.push(jsxAttribute('title', literal(node.title)));
+                return [jsxElement('img', attributes, [])];
+            }
+            case 'code': {
+                const attributes = node.lang
+                    ? [jsxAttribute('className', literal(`language-${node.lang}`))]
+                    : [];
+                return [
+                    jsxElement('pre', [], [jsxElement('code', attributes, [container(literal(node.value))])]),
+                ];
+            }
+            case 'list': {
+                const loose = isListLoose(node);
+                const attributes = node.ordered && typeof node.start === 'number' && node.start !== 1
+                    ? [jsxAttribute('start', literal(node.start))]
+                    : [];
+                if (node.children.some((item) => typeof item.checked === 'boolean')) {
+                    attributes.push(jsxAttribute('className', literal('contains-task-list')));
+                }
+                return [
+                    jsxElement(node.ordered ? 'ol' : 'ul', attributes, wrap(node.children.map((item) => [this.listItem(item, loose)]))),
+                ];
+            }
+            case 'table': {
+                const [head, ...body] = node.children;
+                const row = (cells, cell) => jsxElement('tr', [], cells.map((entry) => this.intrinsic(cell, 'children' in entry ? entry.children : [])));
+                const sections = [];
+                if (head)
+                    sections.push(jsxElement('thead', [], [row(head.children, 'th')]));
+                if (body.length > 0) {
+                    sections.push(jsxElement('tbody', [], body.map((entry) => row(entry.children, 'td'))));
+                }
+                return [jsxElement('table', [], sections)];
+            }
+            case 'mdxFlowExpression':
+            case 'mdxTextExpression': {
+                const program = (_b = node.data) === null || _b === void 0 ? void 0 : _b.estree;
+                if (program && program.body.length === 0)
+                    return [];
+                const statement = program === null || program === void 0 ? void 0 : program.body[0];
+                if ((program === null || program === void 0 ? void 0 : program.body.length) === 1 && (statement === null || statement === void 0 ? void 0 : statement.type) === 'ExpressionStatement') {
+                    const converted = toStaticExpression(statement.expression, this.consts, this.usedConsts);
+                    if (converted.ok && this.isRenderableText(converted.expression)) {
+                        return [container(converted.expression)];
+                    }
+                }
+                this.fail(node, `{${truncate(node.value.trim())}} inside ${this.insideRoot()} can't be evaluated at build time. ${MOVE_TO_SNIPPET}`);
+                return undefined;
+            }
+            default:
+                this.fail(node, `Markdown ${node.type} content isn't supported inside ${this.insideRoot()}. ${MOVE_TO_SNIPPET}`);
+                return undefined;
+        }
+    }
+    listItem(item, loose) {
+        const results = unravel(item.children).map((child) => {
+            var _a;
+            return child.type === 'paragraph'
+                ? { p: true, empty: child.children.length === 0, children: this.children(child.children) }
+                : { p: false, empty: false, children: (_a = this.child(child)) !== null && _a !== void 0 ? _a : [] };
+        });
+        const attributes = [];
+        if (typeof item.checked === 'boolean') {
+            const checkbox = jsxElement('input', [
+                jsxAttribute('type', literal('checkbox')),
+                jsxAttribute('checked', literal(item.checked)),
+                jsxAttribute('disabled', null),
+            ], []);
+            const [head] = results;
+            if (head === null || head === void 0 ? void 0 : head.p)
+                head.children.unshift(checkbox, ...(head.empty ? [] : [container(literal(' '))]));
+            else
+                results.unshift({ p: true, empty: true, children: [checkbox] });
+            attributes.push(jsxAttribute('className', literal('task-list-item')));
+        }
+        const children = results.flatMap(({ p, children: content }, index) => [
+            ...(loose || index > 0 || !p ? [newline()] : []),
+            ...(p && loose ? [jsxElement('p', [], content)] : content),
+        ]);
+        const tail = results.at(-1);
+        if (tail && (loose || !tail.p))
+            children.push(newline());
+        return jsxElement('li', attributes, children);
+    }
+    isRenderableText(expression) {
+        var _a;
+        if (expression.type === 'Literal') {
+            return typeof expression.value === 'string' || typeof expression.value === 'number';
+        }
+        if (expression.type === 'UnaryExpression')
+            return true;
+        if (expression.type !== 'Identifier' || expression.name === 'undefined')
+            return false;
+        const value = (_a = this.consts.get(expression.name)) === null || _a === void 0 ? void 0 : _a.expression;
+        return value !== undefined && this.isRenderableText(value) && value.type !== 'Identifier';
+    }
+    module(root) {
+        var _a, _b, _c;
+        const body = [];
+        const bySource = new Map();
+        for (const binding of [...this.usedBindings.values()].sort((a, b) => compare(a.local, b.local))) {
+            bySource.set(binding.source, [...((_a = bySource.get(binding.source)) !== null && _a !== void 0 ? _a : []), binding]);
+        }
+        const sources = this.sideEffects.size === 0
+            ? [...bySource.keys()].sort(compare)
+            : this.order.filter((source) => bySource.has(source) || this.sideEffects.has(source));
+        for (const source of sources) {
+            const bindings = (_b = bySource.get(source)) !== null && _b !== void 0 ? _b : [];
+            const declaration = (specifiers) => ({
+                type: 'ImportDeclaration',
+                specifiers,
+                source: { type: 'Literal', value: source },
+            });
+            const [firstDefault, ...otherDefaults] = bindings.filter((binding) => binding.imported === 'default');
+            const named = bindings.filter((binding) => binding.imported !== 'default' && binding.imported !== '*');
+            const mainSpecifiers = [];
+            if (firstDefault) {
+                mainSpecifiers.push({
+                    type: 'ImportDefaultSpecifier',
+                    local: identifier(firstDefault.local),
+                });
+            }
+            for (const binding of named) {
+                mainSpecifiers.push({
+                    type: 'ImportSpecifier',
+                    imported: identifier(binding.imported),
+                    local: identifier(binding.local),
+                });
+            }
+            if (mainSpecifiers.length > 0 || bindings.length === 0) {
+                body.push(declaration(mainSpecifiers));
+            }
+            for (const binding of otherDefaults) {
+                body.push(declaration([{ type: 'ImportDefaultSpecifier', local: identifier(binding.local) }]));
+            }
+            for (const binding of bindings.filter((entry) => entry.imported === '*')) {
+                body.push(declaration([{ type: 'ImportNamespaceSpecifier', local: identifier(binding.local) }]));
+            }
+        }
+        for (const name of [...this.usedConsts].sort(compare)) {
+            const expression = (_c = this.consts.get(name)) === null || _c === void 0 ? void 0 : _c.expression;
+            if (!expression)
+                continue;
+            body.push({
+                type: 'VariableDeclaration',
+                kind: 'const',
+                declarations: [{ type: 'VariableDeclarator', id: identifier(name), init: expression }],
+            });
+        }
+        const taken = new Set([...this.usedBindings.keys(), ...this.usedConsts]);
+        let functionName = 'Island';
+        while (taken.has(functionName))
+            functionName = `${functionName}_`;
+        body.push({
+            type: 'ExportDefaultDeclaration',
+            declaration: {
+                type: 'FunctionDeclaration',
+                id: identifier(functionName),
+                params: [],
+                generator: false,
+                async: false,
+                body: { type: 'BlockStatement', body: [{ type: 'ReturnStatement', argument: root }] },
+            },
+        });
+        const program = { type: 'Program', sourceType: 'module', body };
+        return toJs(program, { handlers: jsxHandlers }).value;
+    }
+    imports() {
+        return [...this.usedBindings.values()]
+            .map(({ local, source, imported }) => ({ local, pkg: source, imported }))
+            .sort((a, b) => compare(a.local, b.local));
+    }
+}
+const compare = (a, b) => {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+};

package/dist/mdx/islands/island-placement.d.ts

@@ -0,0 +1,10 @@
+import type { List, ListItem } from 'mdast';
+import type { LocatedStatement } from './island-bindings.js';
+export type Blocker = string | false;
+type ChildrenPlacements = Map<string, (string | null)[][]>;
+export declare const isItemLoose: (item: ListItem) => boolean;
+export declare const isListLoose: (list: List) => boolean;
+export declare const isIntrinsic: (name: string) => boolean;
+export declare const childrenPlacements: (statements: LocatedStatement[]) => ChildrenPlacements;
+export declare const blockerWithin: (name: string | null, blocker: Blocker, placements: ChildrenPlacements, seen?: ReadonlySet<string>) => Blocker;
+export {};