fix(editor): better scope unsupported content rendering (#4794)

sbawabe · web-flow · commit 80db87d0e35a · 2025-11-05T10:59:03.000-05:00
diff --git a/packages/fern-dashboard/src/components/editor/editor-mdx-renderer/FernEditorMDXRenderer.tsx b/packages/fern-dashboard/src/components/editor/editor-mdx-renderer/FernEditorMDXRenderer.tsx
@@ -5,7 +5,6 @@ import {
     type MdastNodes,
     type MdxJsxAttribute,
     type MdxJsxExpressionAttribute,
-    mdxToAST,
     mdxToHtml
 } from "@fern-docs/mdx";
 import { useMDXComponents } from "@mdx-js/react";
@@ -17,70 +16,13 @@ import { EditorComponentProvider } from "@/components/editor/editor-component/Ed
 import { CustomElementHoverWrapper } from "@/components/editor/NodeHoverWrapper";
 import TiptapEditor from "@/components/editor/TiptapEditor";
 import { ErrorBoundary } from "@/docs/components/error-boundary";
-import { MDX_COMPONENTS } from "@/docs/mdx/components";
 import { useDebounce } from "@/hooks/useDebounce";
 import type { EncodedDocsUrl } from "@/utils/types";
 import { UnsupportedContentDisplayOnly } from "../UnsupportedContent";
 import { cachedBundleMDX } from "./cache";
 import { boundaryElements, parseMDX } from "./parse";
 import type { AttributeValue, JSXElement, ParsedMarkdownElement } from "./types";
 
-/**
- * Check if MDX contains unsupported custom components
- * Returns the name of the first unsupported component found, or null if all are supported
- */
-function findUnsupportedComponent(mdx: string): string | null {
-    const IGNORED_COMPONENTS = new Set(["InterceptedChildren"]);
-
-    try {
-        const { mdast } = mdxToAST(mdx);
-
-        function traverse(node: any): string | null {
-            if (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") {
-                const componentName = node.name;
-
-                if (!componentName) {
-                    return null;
-                }
-
-                if (IGNORED_COMPONENTS.has(componentName)) {
-                    return null;
-                }
-
-                if (componentName === componentName.toLowerCase()) {
-                    return null;
-                }
-
-                if (!Object.hasOwn(MDX_COMPONENTS, componentName)) {
-                    return componentName;
-                }
-            }
-
-            if (node.children && Array.isArray(node.children)) {
-                for (const child of node.children) {
-                    const unsupported = traverse(child);
-                    if (unsupported) {
-                        return unsupported;
-                    }
-                }
-            }
-
-            return null;
-        }
-
-        for (const child of mdast.children) {
-            const unsupported = traverse(child);
-            if (unsupported) {
-                return unsupported;
-            }
-        }
-
-        return null;
-    } catch (error) {
-        return null;
-    }
-}
-
 function buildMdxElement(
     name: string,
     keyedAttributes: Record<string, AttributeValue>,
@@ -221,19 +163,8 @@ interface MDXRendererProps {
     branch?: string;
 }
 
-const CustomErrorFallback = ({ mdx, unsupportedComponent }: { mdx: string; unsupportedComponent?: string | null }) => {
-    const computedUnsupportedComponent = useMemo(() => {
-        if (unsupportedComponent != null) {
-            return unsupportedComponent;
-        }
-        return findUnsupportedComponent(mdx);
-    }, [unsupportedComponent, mdx]);
-
-    const displayMessage = computedUnsupportedComponent
-        ? `Unsupported markdown tag: ${computedUnsupportedComponent}`
-        : !mdx.includes("<InterceptedChildren />")
-          ? mdx
-          : "Unsupported markdown";
+const CustomErrorFallback = ({ mdx }: { mdx: string }) => {
+    const displayMessage = !mdx.includes("<InterceptedChildren />") ? mdx : "Unsupported markdown";
 
     return <UnsupportedContentDisplayOnly>{displayMessage}</UnsupportedContentDisplayOnly>;
 };
@@ -273,14 +204,7 @@ const MDXRenderer = React.memo(({ mdx, docsUrl, branch }: MDXRendererProps) => {
     const components = useMDXComponents();
     const isBoundary = useMemo(() => isBoundaryElement(mdx), [mdx]);
 
-    const unsupportedComponent = useMemo(() => findUnsupportedComponent(mdx), [mdx]);
-
     useEffect(() => {
-        if (unsupportedComponent) {
-            setState({ type: "ERROR", message: `Unsupported component: ${unsupportedComponent}` });
-            return;
-        }
-
         let cancelled = false;
 
         void (async () => {
@@ -300,7 +224,7 @@ const MDXRenderer = React.memo(({ mdx, docsUrl, branch }: MDXRendererProps) => {
         return () => {
             cancelled = true;
         };
-    }, [mdx, docsUrl, branch, unsupportedComponent]);
+    }, [mdx, docsUrl, branch]);
 
     // Compute content based on state - all hooks must be called before this point
     const content = useMemo(() => {
@@ -309,21 +233,17 @@ const MDXRenderer = React.memo(({ mdx, docsUrl, branch }: MDXRendererProps) => {
         }
 
         if (state.type === "ERROR") {
-            const displayMessage = unsupportedComponent
-                ? `Unsupported markdown tag: ${unsupportedComponent}`
-                : !mdx.includes("<InterceptedChildren />")
-                  ? mdx
-                  : "Unsupported markdown";
+            const displayMessage = !mdx.includes("<InterceptedChildren />") ? mdx : "Unsupported markdown";
 
             return <UnsupportedContentDisplayOnly>{displayMessage}</UnsupportedContentDisplayOnly>;
         }
 
         return (
-            <ErrorBoundary fallback={<CustomErrorFallback mdx={mdx} unsupportedComponent={unsupportedComponent} />}>
+            <ErrorBoundary fallback={<CustomErrorFallback mdx={mdx} />}>
                 <TerminalMDXRenderer code={state.code} components={components} />
             </ErrorBoundary>
         );
-    }, [state, mdx, components, unsupportedComponent]);
+    }, [state, mdx, components]);
 
     if (isBoundary) {
         // Only wrap with CustomElementHoverWrapper if it's a boundary element
diff --git a/packages/fern-dashboard/src/components/editor/editor-mdx-renderer/parse.ts b/packages/fern-dashboard/src/components/editor/editor-mdx-renderer/parse.ts
@@ -1,4 +1,5 @@
 import { astToMDX, type MdastNodes, type MdxJsxExpressionAttribute, mdxToAST } from "@fern-docs/mdx";
+import { MDX_COMPONENTS } from "@/docs/mdx/components";
 
 import type { AttributeValue, JSXElement, JSXElementChildren, ParsedMarkdownElement } from "./types";
 
@@ -36,10 +37,70 @@ const contentDraggingDisabledComponents = ["Button"];
 // HTML elements that mark boundaries - these and all their children will be treated as terminal/non-editable
 const boundaryElements = ["div", "span", "section", "article", "body", "aside"];
 
+const IGNORED_COMPONENTS = new Set(["InterceptedChildren"]);
+
+/**
+ * Check if a component is supported
+ */
+function isComponentSupported(componentName: string | null | undefined): boolean {
+    if (!componentName) {
+        return true;
+    }
+
+    if (IGNORED_COMPONENTS.has(componentName)) {
+        return true;
+    }
+
+    // lowercase components are HTML elements, which are supported
+    if (componentName === componentName.toLowerCase()) {
+        return true;
+    }
+
+    return Object.hasOwn(MDX_COMPONENTS, componentName);
+}
+
+/**
+ * Replace unsupported components in the AST with a placeholder
+ */
+function replaceUnsupportedComponents(node: MdastNodes): MdastNodes {
+    // Check if this node is an unsupported component
+    if ((node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && !isComponentSupported(node.name)) {
+        // Replace with a placeholder that shows what component was unsupported
+        return {
+            type: "mdxJsxFlowElement",
+            name: "UnsupportedContentPlaceholder",
+            attributes: [
+                {
+                    type: "mdxJsxAttribute",
+                    name: "componentName",
+                    value: node.name || "unknown"
+                }
+            ],
+            children: []
+        };
+    }
+
+    // Recursively process children
+    if ("children" in node && node.children && Array.isArray(node.children)) {
+        return {
+            ...node,
+            children: node.children.map((child) => replaceUnsupportedComponents(child)) as any
+        };
+    }
+
+    return node;
+}
+
 export function parseMDX(mdx: string): ParsedMarkdownElement[] {
     // Parse MDX to AST using mdxToAST
     const { mdast } = mdxToAST(mdx);
 
+    // Replace unsupported components before processing
+    const processedMdast = {
+        ...mdast,
+        children: mdast.children.map((child) => replaceUnsupportedComponents(child))
+    };
+
     const result: ParsedMarkdownElement[] = [];
 
     // Function to traverse the AST and extract parent-child relationships
@@ -168,7 +229,7 @@ export function parseMDX(mdx: string): ParsedMarkdownElement[] {
     }
 
     // Start traversing from the root's children
-    const rootNode = mdast;
+    const rootNode = processedMdast;
     for (const child of rootNode.children) {
         const element = traverse(child);
         // Handle case where traverse returns multiple elements (e.g., paragraph with only images)
diff --git a/packages/fern-dashboard/src/docs/mdx/components/index.tsx b/packages/fern-dashboard/src/docs/mdx/components/index.tsx
@@ -4,6 +4,7 @@ import type { MDXComponents } from "@fern-docs/mdx";
 import dynamic from "next/dynamic";
 import React, { type ComponentProps } from "react";
 
+import { UnsupportedContentDisplayOnly } from "@/components/editor/UnsupportedContent";
 import { ErrorBoundary, ErrorBoundaryFallback } from "@/docs/components/error-boundary";
 import { Embed } from "@/editor/components/Embed";
 
@@ -103,6 +104,11 @@ const FERN_COMPONENTS = {
 const INTERNAL_COMPONENTS = {
     ErrorBoundary,
     ElevenLabsWaveform,
+    UnsupportedContentPlaceholder: ({ componentName }: { componentName?: string }) => (
+        <UnsupportedContentDisplayOnly>
+            {componentName ? `Unsupported markdown tag: ${componentName}` : "Unsupported markdown"}
+        </UnsupportedContentDisplayOnly>
+    ),
 
     /**
      * deprecated but kept for backwards compatibility
