fix(toc): prevent misnamed mdx components from breaking TOC (#1242)

dannobytes · web-flow · commit fcb5f7d13c79 · 2025-12-01T11:51:01.000-08:00
| [![PR App][icn]][demo] | Fix CX-2543 | | :--------------------: | :---------: | ## 🧰 Changes Discovered through [this ticket](https://linear.app/readme-io/issue/CX-2543/tabapay-toc-does-not-respect-headers-nesting) that the TOC generated by the MDX renderer would become broken with miscalculated nesting depths and exposing `h3`s or other heading depths that shouldn't be included. This happened when a jsx element was embedded inside the MDX body and the custom component name did not match the exported jsx elements. For example: <img width="2130" height="1016" alt="image" src="https://github.com/user-attachments/assets/27d9cc8e-cfdd-4b9c-bd55-968df40624a8" /> I'm not entirely sure whether this is an edge-case we should be guarding against from inside our custom component editor. Like, adding validation to ensure that the component name matches what's being exported from it. My gut tells me it'd be really hard to enforce that. So, the fix (for now) is to simply take this edge-case into account and add protections for the cases where this happens. When a component name doesn't match the jsx element name, it previously was making its way into the `plugin/toc` flow. But b/c it has no `tagName`, the `getDepth()` calculation would break and return a `NaN` instead of a valid integer. This would break the nesting logic in `toctoHast()` and cause all headers to render at the first level. Fixed this by: 1. filtering away these mismatched components that make it through 1. additionally updating the `getDepth()` function to be more fail-proof and handle the case where `tagName` is undefined | before | after | |--------|--------| | <img width="246" height="544" alt="image" src="https://github.com/user-attachments/assets/d1fe2919-d0be-4c55-b829-44d89e035a6c" /> | <img width="218" height="396" alt="image" src="https://github.com/user-attachments/assets/53c6a079-7c41-4450-a428-a37fe5f87512" /> | ## 🧬 QA & Testing Tests should pass - [Broken on production][prod]. - [Working in this PR app][demo]. [demo]: https://markdown-pr-PR_NUMBER.herokuapp.com [prod]: https://SUBDOMAIN.readme.io [icn]: https://user-images.githubusercontent.com/886627/160426047-1bee9488-305a-4145-bb2b-09d8b757d38a.svg
diff --git a/__tests__/plugins/toc.test.tsx b/__tests__/plugins/toc.test.tsx
@@ -175,4 +175,40 @@ export const toc = [
       </ul></li></ul></nav>"
     `);
   });
+
+  it('preserves nesting when component names differ from exported elements', () => {
+    const md = `
+# Title
+
+## SubHeading
+
+<Comp>
+  First
+</Comp>
+`;
+
+    const components = {
+      Comp: 'export const Comp = ({ children }) => { return children; }',
+    };
+
+    const compModule = run(compile(components.Comp));
+    const { Toc } = run(compile(md, { components }), {
+      components: {
+        // 👇🏼 this is what we're guarding against
+        CompDoesNotMatchExportedModule: compModule,
+      },
+    });
+
+    const html = renderToString(<Toc />);
+    expect(html).toMatchInlineSnapshot(`
+      "<nav aria-label="Table of contents" role="navigation"><ul class="toc-list"><li><a class="tocHeader" href="#"><i class="icon icon-text-align-left"></i>Table of Contents</a></li><li class="toc-children"><ul>
+      <li><a href="#title">Title</a></li>
+      <li>
+      <ul>
+      <li><a href="#subheading">SubHeading</a></li>
+      </ul>
+      </li>
+      </ul></li></ul></nav>"
+    `);
+  });
 });
diff --git a/processor/plugin/toc.ts b/processor/plugin/toc.ts
@@ -58,14 +58,31 @@ export const rehypeToc = ({ components = {} }: Options): Transformer<Root, Root>
 };
 
 const MAX_DEPTH = 2;
-const getDepth = (el: HastHeading) => parseInt(el.tagName?.match(/^h(\d)/)[1], 10);
+
+/**
+ * Get the depth of a heading element based on its tag name.
+ *
+ * ⚠️ Be extra defensive to non-heading elements somehow making it here. This
+ * should not happen, but if it does, we avoid breaking TOC depth calculations
+ * by returning `Infinity`, thus removing them from depth considerations.
+ * @link https://linear.app/readme-io/issue/CX-2543/tabapay-toc-does-not-respect-headers-nesting
+ *
+ * @example
+ * getDepth({ tagName: 'h1' }) // 1
+ * getDepth({ tagName: 'h2' }) // 2
+ */
+const getDepth = (el: HastHeading) => {
+  if (!el.tagName) return Infinity;
+  return parseInt(el.tagName?.match(/^h(\d)/)[1], 10);
+};
 
 /*
  * `tocToHast` consumes the list generated by `rehypeToc` and produces a hast
  * of nested lists to be rendered as a table of contents.
  */
 const tocToHast = (headings: HastHeading[] = []): TocList => {
-  const min = Math.min(...headings.map(getDepth));
+  const headingDepths = headings.map(getDepth);
+  const min = Math.min(...headingDepths);
   const ast = h('ul') as TocList;
   const stack: TocList[] = [ast];
 
@@ -105,7 +122,10 @@ export const tocHastToMdx = (toc: IndexableElements[] | undefined, components: R
   if (typeof toc === 'undefined') return '';
 
   const injected = toc.flatMap(node => {
-    return node.type === 'mdxJsxFlowElement' && node.name in components ? components[node.name] || [] : node;
+    if (node.type === 'mdxJsxFlowElement') {
+      return components[node.name] || [];
+    }
+    return node;
   });
 
   const tocHast = tocToHast(injected as HastHeading[]);
