feat: mdx TOC (#883)

| [![PR App][icn]][demo] | Fix RM-9179 |
| :--------------------: | :---------: |

## 🧰 Changes

TOC!!1!1

The old TOC worked by parsing the `mdast` for `heading` via
`mdast-util-toc`. This produces an `mdast` suitable for rendering via
the `TableOfContents` component. The package `remark-slug` appears to be
abandoned, and the [mdx
maintainers](https://github.com/orgs/mdx-js/discussions/2085) recommend
using `rehype-slug` and `rehype-extract-oc`. `rehype-extract-toc`
generates a POJO that represent the TOC, and it doesn't appear to have
any functions for parsing component imports. So, I've implemented a
plugin that parses the main doc and it's components `hast`'s during the
`compile` step. Then it can be rendered in the `TableOfContents` during
the `run` step. This changes the return signatures to be an object
instead of a single component, to prevent requiring 2 separate compile
and run steps when rendering.

Other notable changes:

- Refactored `run`, `compile`, `mdx`, `astProcessor` into their own
files under `./lib`
- Deleted the `Style` component.
- Deleted some tests (maybe not a great idea?).
- Added `execute` test helper.

## 🧬 QA & Testing

- [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

---------

Co-authored-by: Rafe Goldberg <[email protected]>

.gitignore

@@ -16,3 +16,5 @@ example/demo.js*
 example/demo.css
 
 dist
+
+.env

__tests__/components/CodeTabs.test.tsx

@@ -1,6 +1,6 @@
 import { render } from '@testing-library/react';
 import React from 'react';
-import { compile, run } from '../../index';
+import { execute } from '../helpers';
 
 describe('CodeTabs', () => {
   it.skip('render _all_ its children', async () => {
@@ -12,7 +12,7 @@ assert('theme', 'dark');
 assert('theme', 'light');
 \`\`\`
     `;
-    const Component = await run(compile(md));
+    const Component = await execute(md);
     const { container } = render(<Component />);
 
     expect(container).toHaveTextContent(`assert('theme', 'dark')`);

__tests__/components/Glossary.test.tsx

@@ -1,12 +1,12 @@
 import { render, screen } from '@testing-library/react';
 import React from 'react';
 
-import { run, compile } from '../../index';
+import { execute } from '../helpers';
 
 describe('Glossary', () => {
   it('renders a glossary item', async () => {
     const md = `<Glossary>parliament</Glossary>`;
-    const Content = await run(compile(md));
+    const Content = await execute(md);
     render(<Content />);
 
     expect(screen.getByText('parliament')).toBeVisible();

__tests__/components/HTMLBlock.test.tsx

@@ -4,7 +4,7 @@ import { renderToStaticMarkup, renderToString } from 'react-dom/server';
 import { vi } from 'vitest';
 
 import HTMLBlock from '../../components/HTMLBlock';
-import { compile, run } from '../../index';
+import { execute } from '../helpers';
 
 describe('HTML Block', () => {
   beforeEach(() => {
@@ -55,8 +55,7 @@ describe('HTML Block', () => {
 
   it('renders the html in a `<pre>` tag if safeMode={true}', async () => {
     const md = '<HTMLBlock safeMode={true}>{`<button onload="alert(\'gotcha!\')"/>`}</HTMLBlock>';
-    const code = compile(md);
-    const Component = await run(code);
+    const Component = await execute(md);
     expect(renderToStaticMarkup(<Component />)).toMatchInlineSnapshot(
       '"<pre class="html-unsafe"><code>&lt;button onload=&quot;alert(&#x27;gotcha!&#x27;)&quot;/&gt;</code></pre>"',
     );

__tests__/components/Variable.test.tsx

@@ -1,12 +1,12 @@
 import { render, screen } from '@testing-library/react';
 import React from 'react';
-
-import { run, compile } from '../../index';
+import { execute } from '../helpers';
 
 describe('Variable', () => {
   it('render a variable', async () => {
     const md = `<Variable variable="name" />`;
-    const Content = await run(compile(md));
+    const Content = await execute(md);
+
     render(<Content />);
 
     expect(screen.getByText('NAME')).toBeVisible();

__tests__/components/index.test.ts

@@ -1,45 +1,7 @@
 import { cleanup, fireEvent, render } from '@testing-library/react';
 import React from 'react';
-import { vi } from 'vitest';
-
-import { compile, run, utils } from '../../index';
-
-describe.skip('Data Replacements', () => {
-  it('Variables', () => {
-    const { container } = render(
-      React.createElement(
-        utils.VariablesContext.Provider,
-        {
-          value: {
-            defaults: [{ test: 'Default Value' }],
-            user: { test: 'User Override' },
-          },
-        },
-        compile('<<test>>'),
-      ),
-    );
-    expect(container).toContainHTML('<p><span>User Override</span></p>');
-  });
 
-  it('Glossary Term', () => {
-    const { container } = render(
-      React.createElement(
-        utils.GlossaryContext.Provider,
-        {
-          value: [
-            {
-              term: 'term',
-              definition: 'a word or phrase used to describe a thing or to express a concept.',
-              _id: '1',
-            },
-          ],
-        },
-        compile('<<glossary:term>>'),
-      ),
-    );
-    expect(container).toContainHTML('<p><span class="GlossaryItem-trigger">term</span></p>');
-  });
-});
+import { execute } from '../helpers';
 
 describe('Components', () => {
   it('Callout', async () => {
@@ -56,16 +18,16 @@ describe('Components', () => {
 `,
     ];
 
-    const code0 = compile(callout[0]);
-    let component = await run(code0);
+    let md = callout[0];
+    let component = await execute(md);
     let { container } = render(React.createElement(component));
 
     expect(container.innerHTML).toMatchSnapshot();
 
     cleanup();
 
-    const code1 = compile(callout[1]);
-    component = await run(code1);
+    md = callout[1];
+    component = await execute(md);
     ({ container } = render(React.createElement(component)));
 
     expect(container.innerHTML).toMatchInlineSnapshot(
@@ -75,18 +37,6 @@ describe('Components', () => {
     cleanup();
   });
 
-  it.skip('Multi Code Block', () => {
-    const tabs = '```\nhello\n```\n```php\nworld\n```\n\n';
-    const rdmd = compile(tabs);
-    const { container } = render(rdmd);
-
-    expect(container.querySelectorAll('pre')[1]).not.toHaveClass();
-
-    fireEvent.click(container.querySelectorAll('.CodeTabs-toolbar button')[1]);
-
-    expect(container.querySelectorAll('pre')[1]).toHaveClass('CodeTabs_active');
-  });
-
   it('Embed', () => {
     const fixtures = {
       html: `<Embed
@@ -115,7 +65,7 @@ describe('Components', () => {
     };
 
     Object.values(fixtures).map(async fx => {
-      const component = await run(compile(fx));
+      const component = await execute(fx);
       const { container } = render(React.createElement(component));
       return expect(container.innerHTML).toMatchSnapshot();
     });
@@ -125,8 +75,7 @@ describe('Components', () => {
     const text =
       '![Bro eats pizza and makes an OK gesture.](https://files.readme.io/6f52e22-man-eating-pizza-and-making-an-ok-gesture.jpg "Pizza Face")';
 
-    const code = compile(text);
-    const component = await run(code);
+    const component = await execute(text);
     const { container } = render(React.createElement(component));
 
     expect(container.innerHTML).toMatchSnapshot();
@@ -149,66 +98,4 @@ describe('Components', () => {
     fireEvent.keyDown(img, { key: '.', metaKey: true });
     expect(box).not.toHaveClass('open');
   });
-
-  it.skip('Heading', () => {
-    let { container } = render(compile('### Heading Level 3\n\n### Heading Level 3'));
-    expect(container.querySelectorAll('.heading')).toHaveLength(2);
-
-    cleanup();
-
-    ({ container } = render(compile('Pretest.\n\n###\n\nPosttest.')));
-    expect(container.querySelector('.heading')).toHaveTextContent('');
-  });
-
-  it.skip('Heading no children', () => {
-    const { container } = render(compile('### Heading Level 3'));
-    expect(container.querySelectorAll('.heading')).toHaveLength(1);
-  });
-});
-
-describe.skip('Compatibility Mode', () => {
-  global.eval = vi.fn();
-  const tabs = `[block:api-header]
-{
-  "title": "I am a magical, mystical heading."
-}
-[/block]
-<div id="custom-target">Loading...</div>
-[block:html]
-${JSON.stringify({
-  html: '<script>\nconsole.log("World");\n</script>\n\n<b>Hello!</b>\n\n<script>\nconsole.log("World");\n</script>',
-})}
-[/block]
-
-[block:parameters]
-${JSON.stringify({
-  data: {
-    '0-0': "```js Tab Zed\nconsole.log('tab zed');\n```\n```js Tab One\nconsole.log('tab one')\n```",
-    '0-1':
-      '> Lorem ipsum dolor sit amet, consectetur adipisicing elit. Maxime repellat placeat expedita voluptatum fugiat rerum, accusamus eius dolorum sequi eveniet esse, adipisci soluta quia mollitia? Dolorem minus, dolores, rerum, pariatur sit quia eum esse voluptatibus ea veritatis non.',
-    '0-2': '',
-    'h-0': 'Hello',
-    'h-1': 'Bonjour',
-    'h-2': 'Willkommen',
-  },
-  cols: 2,
-  rows: 1,
-})}
-[/block]`;
-
-  let rdmd;
-  let container;
-  beforeEach(() => {
-    rdmd = compile(tabs, { compatibilityMode: true });
-    // eslint-disable-next-line testing-library/no-render-in-setup
-    ({ container } = render(rdmd));
-  });
-
-  it('Should use h1 tags for magic heading blocks.', () => expect(container.querySelectorAll('h1')).toHaveLength(1));
-
-  it('Should allow block-level RDMD compoonents in tables.', () => {
-    const table = container.querySelector('table');
-    expect(table.querySelectorAll('.CodeTabs')).toHaveLength(1);
-    expect(table.querySelectorAll('blockquote')).toHaveLength(1);
-  });
 });

__tests__/custom-components/index.test.tsx

@@ -1,7 +1,7 @@
-import { compile, run } from '../../index';
 import React from 'react';
 
 import { render, screen } from '@testing-library/react';
+import { execute } from '../helpers';
 
 describe('Custom Components', () => {
   const Example = () => <div>It works!</div>;
@@ -16,7 +16,7 @@ describe('Custom Components', () => {
     const doc = `
 <Example />
     `;
-    const Page = await run(compile(doc), { components: { Example } });
+    const Page = await execute(doc, undefined, { components: { Example } });
     render(<Page />);
 
     expect(screen.getByText('It works!')).toBeVisible();
@@ -27,7 +27,7 @@ describe('Custom Components', () => {
 <Composite />
     `;
 
-    const Page = await run(compile(doc), { components: { Example, Composite } });
+    const Page = await execute(doc, undefined, { components: { Example, Composite } });
     render(<Page />);
 
     expect(screen.getByText('It works!')).toBeVisible();

__tests__/helpers.ts

@@ -1,6 +1,7 @@
 import { vi } from 'vitest';
+import { run, compile } from '../index';
 
-const silenceConsole =
+export const silenceConsole =
   (prop: keyof Console = 'error', impl = () => {}) =>
   fn => {
     let spy;
@@ -14,4 +15,7 @@ const silenceConsole =
     }
   };
 
-export { silenceConsole };
+export const execute = async (doc: string, compileOpts = {}, runOpts = {}) => {
+  const module = await run(compile(doc, compileOpts), runOpts);
+  return module.default;
+};