fix(stories): unwrap extra <p> tags in mdx jsx (#96351)

Follow-up to (and revert of) #96343.

Rather than shifting the burden of wrapping all JSX-in-MDX content in
expressions to authors, this PR fixes the issue by adding a new `remark`
plugin that unwraps problematic `<p>` tags.

Problematic situations where MDX introduces `<p>` tags are:
- Paragraph contains only `mdxJsxTextElement` nodes and whitespace-only
`text` nodes.
- MDX JSX element contains a single child which is a paragraph.

---------

Co-authored-by: Jonas <jonas.badalic@sentry.io>
Co-authored-by: cursor[bot] <206951365+cursor[bot]@users.noreply.github.com>

Author: 3 people

build-utils/remark-unwrap-mdx-paragraphs.ts

@@ -0,0 +1,60 @@
+import type {Node, Literal, Parent} from 'hast';
+
+import {visit} from 'unist-util-visit';
+
+/**
+ * Remark plugin that unwraps paragraphs with only JSX elements and paragraphs inside MDX components
+ *
+ * - Find paragraphs that only contain MDX JSX text and/or whitespace, replace with children
+ * - Find paragraphs that are the only children of MDX JSX elements, replace with children
+ *
+ */
+export function remarkUnwrapMdxParagraphs() {
+  return function (tree: Node) {
+    // unwrap paragraphs with only JSX text and whitespace
+    visit(tree, (node, index, parent: Parent) => {
+      if (isParagraph(node)) {
+        const hasOnlyJsxAndWhitespace = node.children.every(child => {
+          switch (true) {
+            case child.type === 'mdxJsxTextElement':
+              return true;
+            case isText(child):
+              // Allow only whitespace text nodes
+              return child.value.trim() === '';
+            default:
+              return false;
+          }
+        });
+        if (hasOnlyJsxAndWhitespace && parent && index !== undefined) {
+          // replace paragraph with its children
+          parent.children.splice(index, 1, ...node.children);
+          // return new index
+          return index + node.children.length - 1;
+        }
+      }
+      return;
+    });
+    // unwrap paragraphs that are only children of MDX JSX elements
+    visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], node => {
+      if (
+        isMdxJsxNode(node) &&
+        node.children.length === 1 &&
+        isParagraph(node.children[0])
+      ) {
+        node.children = node.children[0].children;
+        return node.children.length - 1;
+      }
+      return;
+    });
+  };
+}
+
+function isParagraph(node?: Node): node is Parent {
+  return node?.type === 'paragraph';
+}
+function isText(node: Node): node is Literal {
+  return node.type === 'text';
+}
+function isMdxJsxNode(node: Node): node is Parent {
+  return node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement';
+}

rspack.config.ts

@@ -24,6 +24,8 @@ import {TsCheckerRspackPlugin} from 'ts-checker-rspack-plugin';
 
 // @ts-expect-error: ts(5097) importing `.ts` extension is required for resolution, but not enabled until `allowImportingTsExtensions` is added to tsconfig
 import LastBuiltPlugin from './build-utils/last-built-plugin.ts';
+// @ts-expect-error: ts(5097) importing `.ts` extension is required for resolution, but not enabled until `allowImportingTsExtensions` is added to tsconfig
+import {remarkUnwrapMdxParagraphs} from './build-utils/remark-unwrap-mdx-paragraphs.ts';
 import packageJson from './package.json' with {type: 'json'};
 
 const {env} = process;
@@ -296,6 +298,7 @@ const appConfig: Configuration = {
             loader: '@mdx-js/loader',
             options: {
               remarkPlugins: [
+                remarkUnwrapMdxParagraphs,
                 remarkFrontmatter,
                 remarkMdxFrontmatter,
                 remarkGfm,

static/app/components/core/text/index.mdx

@@ -12,6 +12,7 @@ resources:
     WCAG 1.4.12: https://www.w3.org/TR/WCAG22/#text-spacing
 ---
 
+import {Flex} from 'sentry/components/core/layout';
 import {Heading, Text} from 'sentry/components/core/text';
 import * as Storybook from 'sentry/stories';
 
@@ -177,39 +178,32 @@ Control line height with the `density` prop: `compressed` (1.0), default (1.2),
 <Storybook.Demo>
   <Storybook.SideBySide vertical>
     <div style={{width: '300px', marginBottom: '16px'}}>
-      <Text bold as="p">
-        {`Compressed density.`}
+      <Heading as="h4">Compressed density</Heading>
+      <Text as="p" density="compressed">
+        Compressed density text. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
       </Text>
-      <Text
-        density="compressed"
-        as="p"
-      >{`Compressed density text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`}</Text>
     </div>
     <div style={{width: '300px', marginBottom: '16px'}}>
-      <Text bold as="p">
-        {`Default density.`}
+      <Heading as="h4">Default density</Heading>
+      <Text as="p">
+        Default density text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed
+        do eiusmod tempor incididunt ut labore et dolore magna aliqua.
       </Text>
-      <Text as="p">{`Default density text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`}</Text>
     </div>
     <div style={{width: '300px'}}>
-      <Text bold as="p">
-        {`Comfortable density.`}
+      <Heading as="h4">Comfortable density</Heading>
+      <Text as="p" density="comfortable">
+        Comfortable density text. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+        Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
       </Text>
-      <Text
-        density="comfortable"
-        as="p"
-      >{`Comfortable density text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.`}</Text>
     </div>
   </Storybook.SideBySide>
 </Storybook.Demo>
 ```jsx
-<Text density="compressed" as="p">
-  Compressed density text...
-</Text>
-<Text as="p">Default density text...</Text>
-<Text density="comfortable" as="p">
-  Comfortable density text...
-</Text>
+<Text density="compressed">Compressed density text...</Text>
+<Text>Default density text...</Text>
+<Text density="comfortable">Comfortable density text...</Text>
 ```
 
 ### Ellipsis Overflow
@@ -233,20 +227,18 @@ Use `monospace` for fixed-width text.
 
 <Storybook.Demo>
   <Storybook.SideBySide vertical>
-    <div
-      style={{marginBottom: '16px', display: 'flex', alignItems: 'center', gap: '16px'}}
-    >
+    <Flex align="center" gap="xl" style={{marginBottom: '16px'}}>
       <Text>1234567890</Text>
       <Text size="sm" variant="muted">
-        {`Regular`}
+        Regular
       </Text>
-    </div>
-    <div style={{display: 'flex', alignItems: 'center', gap: '16px'}}>
+    </Flex>
+    <Flex align="center" gap="xl">
       <Text monospace>1234567890</Text>
       <Text size="sm" variant="muted">
-        {`Monospace`}
+        Monospace
       </Text>
-    </div>
+    </Flex>
   </Storybook.SideBySide>
 </Storybook.Demo>
 ```jsx
@@ -260,36 +252,30 @@ Use `tabular` for consistent number alignment and `fraction` for diagonal fracti
 
 <Storybook.Demo>
   <Storybook.SideBySide vertical>
-    <div
-      style={{marginBottom: '16px', display: 'flex', alignItems: 'center', gap: '16px'}}
-    >
+    <Flex align="center" gap="xl" style={{marginBottom: '16px'}}>
       <Text>1234567890</Text>
       <Text size="sm" variant="muted">
-        {`Regular numbers`}
+        Regular numbers
       </Text>
-    </div>
-    <div
-      style={{marginBottom: '16px', display: 'flex', alignItems: 'center', gap: '16px'}}
-    >
+    </Flex>
+    <Flex align="center" gap="xl" style={{marginBottom: '16px'}}>
       <Text tabular>1234567890</Text>
       <Text size="sm" variant="muted">
-        {`Tabular numbers`}
+        Tabular numbers
       </Text>
-    </div>
-    <div
-      style={{marginBottom: '16px', display: 'flex', alignItems: 'center', gap: '16px'}}
-    >
+    </Flex>
+    <Flex align="center" gap="xl" style={{marginBottom: '16px'}}>
       <Text>1/2 3/4 5/8</Text>
       <Text size="sm" variant="muted">
-        {`Regular fractions`}
+        Regular fractions
       </Text>
-    </div>
-    <div style={{display: 'flex', alignItems: 'center', gap: '16px'}}>
+    </Flex>
+    <Flex align="center" gap="xl">
       <Text fraction>1/2 3/4 5/8</Text>
       <Text size="sm" variant="muted">
-        {`Diagonal fractions`}
+        Diagonal fractions
       </Text>
-    </div>
+    </Flex>
   </Storybook.SideBySide>
 </Storybook.Demo>
 ```jsx