[docs] use mostly new components to render MDX files, unify links appearance (expo#20429)

Author: Simek

docs/common/create-permalinked-component.tsx

@@ -8,7 +8,9 @@ type Options = {
   sidebarType?: HeadingType;
 };
 
-type PermalinkedComponentProps = React.PropsWithChildren<{ level?: number } & AdditionalProps>;
+type PermalinkedComponentProps = React.PropsWithChildren<
+  { level?: number; id?: string } & AdditionalProps
+>;
 
 const isDev = process.env.NODE_ENV === 'development';
 
@@ -17,7 +19,7 @@ export const createPermalinkedComponent = (
   options?: Options
 ) => {
   const { baseNestingLevel, sidebarType = HeadingType.Text } = options || {};
-  return ({ children, level, ...props }: PermalinkedComponentProps) => {
+  return ({ children, level, id, ...props }: PermalinkedComponentProps) => {
     const cleanChildren = React.Children.map(children, child => {
       if (React.isValidElement(child) && child?.props?.href) {
         isDev &&
@@ -31,7 +33,7 @@ export const createPermalinkedComponent = (
     });
     const nestingLevel = baseNestingLevel != null ? (level ?? 0) + baseNestingLevel : undefined;
     return (
-      <Permalink nestingLevel={nestingLevel} additionalProps={{ ...props, sidebarType }}>
+      <Permalink nestingLevel={nestingLevel} additionalProps={{ ...props, sidebarType }} id={id}>
         <BaseComponent>{cleanChildren}</BaseComponent>
       </Permalink>
     );

docs/common/headingManager.ts

@@ -41,6 +41,7 @@ export type AdditionalProps = {
   sidebarDepth?: number;
   sidebarType?: HeadingType;
   tags?: string[];
+  style?: React.CSSProperties;
 };
 
 type Metadata = Partial<PageMetadata> & { headings: (RemarkHeading & { _processed?: boolean })[] };

docs/common/translate-markdown.tsx

@@ -11,6 +11,7 @@ import { LinkBase } from '~/ui/components/Text';
 type BaseProps = React.PropsWithChildren<{
   component: any;
   className?: string;
+  style?: React.CSSProperties;
 }>;
 
 type EnhancedProps = React.PropsWithChildren<{
@@ -89,7 +90,10 @@ const Permalink: React.FC<EnhancedProps> = withHeadingManager(
     const permalinkKey = props.id ?? heading?.slug;
 
     return (
-      <PermalinkBase component={component} data-components-heading>
+      <PermalinkBase
+        component={component}
+        data-components-heading
+        style={props.additionalProps?.style}>
         <LinkBase css={STYLES_PERMALINK_LINK} href={'#' + permalinkKey} ref={heading?.ref}>
           <span css={STYLES_PERMALINK_TARGET} id={permalinkKey} />
           <span css={STYLED_PERMALINK_CONTENT}>{children}</span>

docs/components/Permalink.tsx

@@ -203,9 +203,10 @@ export class Code extends React.Component<React.PropsWithChildren<Props>> {
   render() {
     // note(simek): MDX dropped `inlineCode` pseudo-tag, and we need to relay on `pre` and `code` now,
     // which results in this nesting mess, we should fix it in the future
-    const child = this.props.className
-      ? this
-      : (React.Children.toArray(this.props.children)[0] as JSX.Element);
+    const child =
+      this.props.className && this.props.className.startsWith('language')
+        ? this
+        : (React.Children.toArray(this.props.children)[0] as JSX.Element);
 
     const value = this.parseValue(child?.props?.children?.toString() || '');
     let html = value.value;

docs/components/base/code.tsx

@@ -1,5 +1,5 @@
 import { css } from '@emotion/react';
-import { typography, spacing, breakpoints } from '@expo/styleguide';
+import { typography, spacing } from '@expo/styleguide';
 import { PropsWithChildren } from 'react';
 
 import { paragraph } from './typography';
@@ -28,36 +28,3 @@ const STYLES_BOLD_PARAGRAPH = css`
 export const B = ({ children }: PropsWithChildren<object>) => (
   <strong css={STYLES_BOLD_PARAGRAPH}>{children}</strong>
 );
-
-const STYLES_PARAGRAPH_DIV = css`
-  ${STYLES_PARAGRAPH}
-  display: block;
-
-  &.is-wider {
-    max-width: 1200px;
-  }
-
-  @media screen and (max-width: ${breakpoints.medium + 124}px) {
-    &.is-wider {
-      max-width: 100%;
-      width: 100%;
-    }
-  }
-`;
-
-export const PDIV = ({ children }: PropsWithChildren<object>) => {
-  const isWider = (children as JSX.Element)?.props?.snackId;
-  return (
-    <div {...getAttributes()} css={STYLES_PARAGRAPH_DIV} className={isWider ? 'is-wider' : ''}>
-      {children}
-    </div>
-  );
-};
-
-export const PDIVHEADER = ({ children }: PropsWithChildren<object>) => {
-  return (
-    <div {...getAttributes(true)} css={STYLES_PARAGRAPH_DIV}>
-      {children}
-    </div>
-  );
-};

docs/components/base/link.tsx

@@ -1,5 +1,3 @@
-import React from 'react';
-
 import { P } from '~/components/base/paragraph';
 import { ClassDefinitionData, GeneratedData } from '~/components/plugins/api/APIDataTypes';
 import APISectionClasses from '~/components/plugins/api/APISectionClasses';

docs/components/base/paragraph.tsx

@@ -2,15 +2,12 @@ import { css } from '@emotion/react';
 import { borderRadius, breakpoints, spacing, theme, typography } from '@expo/styleguide';
 import ReactMarkdown from 'react-markdown';
 
-import { InlineCode } from '../base/code';
-
 import { createPermalinkedComponent } from '~/common/create-permalinked-component';
 import { HeadingType } from '~/common/headingManager';
-import { PDIVHEADER } from '~/components/base/paragraph';
 import { APIBox } from '~/components/plugins/APIBox';
 import { mdComponents, mdInlineComponents } from '~/components/plugins/api/APISectionUtils';
 import { Collapsible } from '~/ui/components/Collapsible';
-import { CALLOUT } from '~/ui/components/Text';
+import { P, CALLOUT, CODE } from '~/ui/components/Text';
 
 type PropertyMeta = {
   regexHuman?: string;
@@ -53,17 +50,19 @@ type AppConfigSchemaProps = {
   schema: Record<string, Property>;
 };
 
-const Anchor = createPermalinkedComponent(PDIVHEADER, {
+const Anchor = createPermalinkedComponent(P, {
   baseNestingLevel: 3,
   sidebarType: HeadingType.InlineCode,
 });
 
 const PropertyName = ({ name, nestingLevel }: { name: string; nestingLevel: number }) => (
-  <Anchor level={nestingLevel} data-testid={name} data-heading="true">
-    <InlineCode css={typography.fontSizes[16]}>{name}</InlineCode>
+  <Anchor level={nestingLevel} data-testid={name} data-heading="true" css={propertyNameStyle}>
+    <CODE css={typography.fontSizes[16]}>{name}</CODE>
   </Anchor>
 );
 
+const propertyNameStyle = css({ marginBottom: spacing[4] });
+
 export function formatSchema(rawSchema: [string, Property][]) {
   const formattedSchema: FormattedProperty[] = [];
 
@@ -140,15 +139,15 @@ const AppConfigSchemaPropertiesTable = ({ schema }: AppConfigSchemaProps) => {
   const formattedSchema = formatSchema(rawSchema);
 
   return (
-    <div>
+    <>
       {formattedSchema.map((formattedProperty, index) => (
         <AppConfigProperty
           {...formattedProperty}
           key={`${formattedProperty.name}-${index}`}
           nestingLevel={0}
         />
       ))}
-    </div>
+    </>
   );
 };
 
@@ -166,7 +165,7 @@ const AppConfigProperty = ({
   <APIBox css={boxStyle}>
     <PropertyName name={name} nestingLevel={nestingLevel} />
     <CALLOUT theme="secondary" data-text="true">
-      Type: <InlineCode>{type || 'undefined'}</InlineCode>
+      Type: <CODE>{type || 'undefined'}</CODE>
       {nestingLevel > 0 && (
         <>
           &emsp;&bull;&emsp;Path:{' '}

docs/components/plugins/APISection.tsx

@@ -1,15 +1,16 @@
-import React, { PropsWithChildren, useEffect } from 'react';
+import { PropsWithChildren, useEffect } from 'react';
 
-import { InlineCode } from '~/components/base/code';
 import { Collapsible } from '~/ui/components/Collapsible';
+import { CODE } from '~/ui/components/Text';
 
 type Props = PropsWithChildren<object>;
 
 export const ConfigClassic = ({ children }: Props) => {
   useEffect(() => {
     if (typeof children === 'string') {
       throw new Error(
-        `Content inside 'ConfigClassic' needs to be surrounded by new lines to be parsed as markdown.\n\nMake sure there is a blank new line before and after this content: '${children}'`
+        `Content inside 'ConfigClassic' needs to be surrounded by new lines to be parsed as markdown.\n\n` +
+          `Make sure there is a blank new line before and after this content: '${children}'`
       );
     }
   }, [children]);
@@ -18,8 +19,7 @@ export const ConfigClassic = ({ children }: Props) => {
     <Collapsible
       summary={
         <span>
-          Are you using the classic build system? (<InlineCode>expo build:[android|ios]</InlineCode>
-          )
+          Are you using the classic build system? (<CODE>expo build:[android|ios]</CODE>)
         </span>
       }>
       {children}

docs/components/plugins/AppConfigSchemaPropertiesTable.tsx

@@ -1,10 +1,9 @@
 import React, { PropsWithChildren } from 'react';
 
-import { InlineCode } from '~/components/base/code';
-import { P } from '~/components/base/paragraph';
 import { H3 } from '~/components/plugins/Headings';
 import { APISectionPlatformTags } from '~/components/plugins/api/APISectionPlatformTags';
 import { Cell, HeaderCell, Row, Table, TableHead } from '~/ui/components/Table';
+import { P, CODE } from '~/ui/components/Text';
 
 type Props = PropsWithChildren<{
   properties: PluginProperty[];
@@ -26,9 +25,9 @@ export const ConfigPluginProperties = ({ children, properties }: Props) => (
         {properties.map(property => (
           <Row key={property.name}>
             <Cell fitContent>
-              <InlineCode>{property.name}</InlineCode>
+              <CODE>{property.name}</CODE>
             </Cell>
-            <Cell>{!property.default ? '-' : <InlineCode>{property.default}</InlineCode>}</Cell>
+            <Cell>{!property.default ? '-' : <CODE>{property.default}</CODE>}</Cell>
             <Cell>
               {!!property.platform && (
                 <APISectionPlatformTags