docs: create correct prop header to be displayed in TOC (#4018)

Author: lukewalczak

docs/component-docs-plugin/generatePageMDX.js

@@ -2,6 +2,13 @@ const config = require('../docusaurus.config');
 
 const { baseUrl, customFields } = config;
 
+function renderBadge(annotation) {
+  const [annotType, ...annotLabel] = annotation.split(' ');
+
+  // eslint-disable-next-line prettier/prettier
+  return `<span class="badge badge-${annotType.replace('@', '')} "><span class="badge-text">${annotLabel.join(' ')}</span></span>`;
+}
+
 function generateKnownIssues(componentName) {
   const componentKnownIssues = customFields.knownIssues[componentName];
 
@@ -79,6 +86,54 @@ function generateScreenshots(componentName, screenshotData) {
   `;
 }
 
+function generatePropsTable(data, link) {
+  const ANNOTATION_OPTIONAL = '@optional';
+  const ANNOTATION_INTERNAL = '@internal';
+
+  const props = Object.entries(data)
+    .map(([prop, value]) => {
+      if (!value.description) {
+        value.description = '';
+      }
+      // Remove @optional annotations from descriptions.
+      if (value.description.includes(ANNOTATION_OPTIONAL)) {
+        value.description = value.description.replace(ANNOTATION_OPTIONAL, '');
+      }
+      // Hide props with @internal annotations.
+      if (value.description.includes(ANNOTATION_INTERNAL)) {
+        return;
+      }
+
+      let leadingBadge = '';
+      let descriptionByLines = value.description?.split('\n');
+
+      // Find leading badge and put it next after prop name.
+      if (descriptionByLines?.[0].includes('@')) {
+        leadingBadge = descriptionByLines[0];
+      }
+
+      return `
+<div>
+
+### ${prop} ${value.required ? '(required)' : ''} ${
+        leadingBadge && renderBadge(leadingBadge)
+      }
+
+</div>
+  
+  <PropTable componentLink="${link}" prop="${prop}" />
+
+  ---
+  `;
+    })
+    .join('');
+
+  return `
+  ## Props
+  ${props}
+  `;
+}
+
 function generatePageMDX(doc, link) {
   const summaryRegex = /([\s\S]*?)## Usage/;
 
@@ -111,11 +166,9 @@ ${generateScreenshots(doc.title, screenshotData)}
 
 ${usage}
 
-${generateMoreExamples(doc.title)}
-
-## Props
+${generatePropsTable(doc.data.props, link)}
 
-<PropTable link="${link}" />
+${generateMoreExamples(doc.title)}
 
 ${generateThemeColors(doc.title, themeColorsData)}
 

docs/src/components/PropTable.tsx

@@ -17,8 +17,6 @@ const typeDefinitions = {
   'StyleProp<TextStyle>': 'https://reactnative.dev/docs/text-style-props',
 };
 
-const ANNOTATION_OPTIONAL = '@optional';
-const ANNOTATION_INTERNAL = '@internal';
 const ANNOTATION_EXTENDS = '@extends';
 
 const renderBadge = (annotation: string) => {
@@ -60,42 +58,31 @@ const renderExtendsLink = (description: string) => {
   ));
 };
 
-export default function PropTable({ link }: { link: string }) {
-  const doc = useDoc(link);
+export default function PropTable({
+  componentLink,
+  prop,
+}: {
+  componentLink: string;
+  prop: string;
+}) {
+  const doc = useDoc(componentLink);
 
   if (!doc || !doc.data || !doc.data.props) {
     return null;
   }
 
   const props = doc.data.props;
 
-  for (const prop in props) {
-    if (!props[prop].description) {
-      props[prop].description = '';
-    }
-
-    // Remove @optional annotations from descriptions.
-    if (props[prop].description.includes(ANNOTATION_OPTIONAL)) {
-      props[prop].description = props[prop].description.replace(
-        ANNOTATION_OPTIONAL,
-        ''
-      );
-    }
-    // Hide props with @internal annotations.
-    if (props[prop].description.includes(ANNOTATION_INTERNAL)) {
-      delete props[prop];
-    }
-  }
-
   return (
     <div>
       {Object.keys(props).map((key) => {
-        let leadingBadge = '';
+        if (key !== prop) {
+          return null;
+        }
         let descriptionByLines = props[key].description.split('\n');
 
-        // Find leading badge and put it next after prop name.
+        // Slice leading badge - it's handled in `generatePageMDX`
         if (descriptionByLines[0].includes('@')) {
-          leadingBadge = descriptionByLines[0];
           descriptionByLines = descriptionByLines.slice(1);
         }
         descriptionByLines = descriptionByLines.map((line: string) => {
@@ -116,16 +103,6 @@ export default function PropTable({ link }: { link: string }) {
 
         return (
           <div key={key}>
-            <h3>
-              {key} {props[key].required ? '(required)' : ''}
-              {leadingBadge && (
-                <span
-                  dangerouslySetInnerHTML={{
-                    __html: renderBadge(leadingBadge),
-                  }}
-                />
-              )}
-            </h3>
             <p>
               Type:{' '}
               {tsTypeLink ? (

docs/src/css/custom.css

@@ -187,6 +187,17 @@ html[data-theme='light'] .gallery-dark {
   src: url('../../node_modules/react-native-vector-icons/Fonts/MaterialCommunityIcons.ttf') format('truetype');
 }
 
+.badge:is(a .badge) {
+  padding: 0px;
+  height: 8px;
+  width: 8px;
+  border-radius: 4px;
+}
+
+a .badge .badge-text {
+  display: none;
+}
+
 .badge {
   background-color: black;
   color: white;
@@ -215,7 +226,6 @@ html[data-theme='light'] .gallery-dark {
   color: rgba(176, 0, 32, 1);
   background-color: rgba(176, 0, 32, 0.2);
   border-color: rgba(176, 0, 32, 1);
-
 }
 
 .badge-renamed {

src/components/Card/CardTitle.tsx

@@ -108,10 +108,6 @@ const LEFT_SIZE = 40;
 /**
  * A component to show a title, subtitle and an avatar inside a Card.
  *
- * <div class="screenshots">
- *   <img class="small" src="screenshots/card-title-1.png" />
- * </div>
- *
  * ## Usage
  * ```js
  * import * as React from 'react';

src/components/FAB/AnimatedFAB.tsx

@@ -105,6 +105,9 @@ export type Props = $Omit<$RemoveChildren<typeof Surface>, 'mode'> & {
    * @optional
    */
   theme?: ThemeProp;
+  /**
+   * TestID used for testing purposes
+   */
   testID?: string;
 };
 

src/components/FAB/FAB.tsx

@@ -133,6 +133,9 @@ export type Props = $Omit<$RemoveChildren<typeof Surface>, 'mode'> & {
    * @optional
    */
   theme?: ThemeProp;
+  /**
+   * TestID used for testing purposes
+   */
   testID?: string;
   ref?: React.RefObject<View>;
 } & IconOrLabel;