Support TypeScript builtin prop types (#862)

.changeset/perfect-turtles-reply.md

@@ -0,0 +1,8 @@
+---
+'react-docgen': minor
+---
+
+Support `PropsWithoutRef`, `PropsWithRef` and `PropsWithChildren` in TypeScript.
+
+Component props are now detected correctly when these builtin types are used,
+but they do currently not add any props to the documentation.

packages/react-docgen/src/handlers/codeTypeHandler.ts

@@ -98,7 +98,7 @@ function setPropDescriptor(
 }
 
 /**
- * This handler tries to find flow Type annotated react components and extract
+ * This handler tries to find flow and TS Type annotated react components and extract
  * its types to the documentation. It also extracts docblock comments which are
  * inlined in the type definition.
  */

packages/react-docgen/src/utils/__tests__/__snapshots__/getTypeFromReactComponent-test.ts.snap

@@ -258,6 +258,18 @@ exports[`getTypeFromReactComponent > TypeScript > stateless > finds variable typ
 ]
 `;
 
+exports[`getTypeFromReactComponent > TypeScript > stateless > finds wrapped param type annotation 1`] = `
+[
+  Node {
+    "type": "TSTypeReference",
+    "typeName": Node {
+      "name": "Props",
+      "type": "Identifier",
+    },
+  },
+]
+`;
+
 exports[`getTypeFromReactComponent > handles no class props 1`] = `[]`;
 
 exports[`getTypeFromReactComponent > handles no stateless props 1`] = `[]`;

packages/react-docgen/src/utils/__tests__/__snapshots__/unwrapBuiltinTSPropTypes-test.ts.snap

@@ -0,0 +1,71 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`unwrapBuiltinTSPropTypes > React.PropsWithChildren 1`] = `
+Node {
+  "type": "TSTypeReference",
+  "typeName": Node {
+    "name": "Props",
+    "type": "Identifier",
+  },
+}
+`;
+
+exports[`unwrapBuiltinTSPropTypes > React.PropsWithRef 1`] = `
+Node {
+  "type": "TSTypeReference",
+  "typeName": Node {
+    "name": "Props",
+    "type": "Identifier",
+  },
+}
+`;
+
+exports[`unwrapBuiltinTSPropTypes > React.PropsWithoutRef 1`] = `
+Node {
+  "type": "TSTypeReference",
+  "typeName": Node {
+    "name": "Props",
+    "type": "Identifier",
+  },
+}
+`;
+
+exports[`unwrapBuiltinTSPropTypes > does not follow reassignment 1`] = `
+Node {
+  "type": "TSTypeReference",
+  "typeName": Node {
+    "name": "bar",
+    "type": "Identifier",
+  },
+}
+`;
+
+exports[`unwrapBuiltinTSPropTypes > multiple 1`] = `
+Node {
+  "type": "TSTypeReference",
+  "typeName": Node {
+    "name": "Props",
+    "type": "Identifier",
+  },
+}
+`;
+
+exports[`unwrapBuiltinTSPropTypes > with named import 1`] = `
+Node {
+  "type": "TSTypeReference",
+  "typeName": Node {
+    "name": "Props",
+    "type": "Identifier",
+  },
+}
+`;
+
+exports[`unwrapBuiltinTSPropTypes > with require 1`] = `
+Node {
+  "type": "TSTypeReference",
+  "typeName": Node {
+    "name": "Props",
+    "type": "Identifier",
+  },
+}
+`;

packages/react-docgen/src/utils/__tests__/getTypeFromReactComponent-test.ts

@@ -40,6 +40,18 @@ describe('getTypeFromReactComponent', () => {
         expect(getTypeFromReactComponent(path)).toMatchSnapshot();
       });
 
+      test('finds wrapped param type annotation', () => {
+        const path = parseTypescript
+          .statementLast<VariableDeclaration>(
+            `import React from 'react';
+             const x = (props: React.PropsWithChildren<Props>) => {}`,
+          )
+          .get('declarations')[0]
+          .get('init') as NodePath<ArrowFunctionExpression>;
+
+        expect(getTypeFromReactComponent(path)).toMatchSnapshot();
+      });
+
       test('finds param inline type', () => {
         const path = parseTypescript
           .statementLast<VariableDeclaration>(

packages/react-docgen/src/utils/__tests__/unwrapBuiltinTSPropTypes-test.ts

@@ -0,0 +1,99 @@
+import type { TSTypeReference, VariableDeclaration } from '@babel/types';
+import { parseTypescript } from '../../../tests/utils';
+import unwrapBuiltinTSPropTypes from '../unwrapBuiltinTSPropTypes.js';
+import { describe, expect, test } from 'vitest';
+import type { NodePath } from '@babel/traverse';
+
+describe('unwrapBuiltinTSPropTypes', () => {
+  test('React.PropsWithChildren', () => {
+    const path = parseTypescript
+      .statementLast<VariableDeclaration>(
+        `import React from 'react';
+         var foo: React.PropsWithChildren<Props>`,
+      )
+      .get(
+        'declarations.0.id.typeAnnotation.typeAnnotation',
+      ) as NodePath<TSTypeReference>;
+
+    expect(unwrapBuiltinTSPropTypes(path)).toMatchSnapshot();
+  });
+
+  test('React.PropsWithoutRef', () => {
+    const path = parseTypescript
+      .statementLast<VariableDeclaration>(
+        `import React from 'react';
+         var foo: React.PropsWithoutRef<Props>`,
+      )
+      .get(
+        'declarations.0.id.typeAnnotation.typeAnnotation',
+      ) as NodePath<TSTypeReference>;
+
+    expect(unwrapBuiltinTSPropTypes(path)).toMatchSnapshot();
+  });
+
+  test('React.PropsWithRef', () => {
+    const path = parseTypescript
+      .statementLast<VariableDeclaration>(
+        `import React from 'react';
+         var foo: React.PropsWithRef<Props>`,
+      )
+      .get(
+        'declarations.0.id.typeAnnotation.typeAnnotation',
+      ) as NodePath<TSTypeReference>;
+
+    expect(unwrapBuiltinTSPropTypes(path)).toMatchSnapshot();
+  });
+
+  test('multiple', () => {
+    const path = parseTypescript
+      .statementLast<VariableDeclaration>(
+        `import React from 'react';
+         var foo: React.PropsWithChildren<React.PropsWithRef<Props>>`,
+      )
+      .get(
+        'declarations.0.id.typeAnnotation.typeAnnotation',
+      ) as NodePath<TSTypeReference>;
+
+    expect(unwrapBuiltinTSPropTypes(path)).toMatchSnapshot();
+  });
+
+  test('does not follow reassignment', () => {
+    const path = parseTypescript
+      .statementLast<VariableDeclaration>(
+        `import React from 'react';
+         type bar = React.PropsWithRef<Props>
+         var foo: React.PropsWithChildren<bar>`,
+      )
+      .get(
+        'declarations.0.id.typeAnnotation.typeAnnotation',
+      ) as NodePath<TSTypeReference>;
+
+    expect(unwrapBuiltinTSPropTypes(path)).toMatchSnapshot();
+  });
+
+  test('with require', () => {
+    const path = parseTypescript
+      .statementLast<VariableDeclaration>(
+        `const React = require('react');
+         var foo: React.PropsWithRef<Props>`,
+      )
+      .get(
+        'declarations.0.id.typeAnnotation.typeAnnotation',
+      ) as NodePath<TSTypeReference>;
+
+    expect(unwrapBuiltinTSPropTypes(path)).toMatchSnapshot();
+  });
+
+  test('with named import', () => {
+    const path = parseTypescript
+      .statementLast<VariableDeclaration>(
+        `import { PropsWithRef } from 'react';
+         var foo: PropsWithRef<Props>`,
+      )
+      .get(
+        'declarations.0.id.typeAnnotation.typeAnnotation',
+      ) as NodePath<TSTypeReference>;
+
+    expect(unwrapBuiltinTSPropTypes(path)).toMatchSnapshot();
+  });
+});

packages/react-docgen/src/utils/getTypeFromReactComponent.ts

@@ -23,6 +23,7 @@ import type {
 } from '@babel/types';
 import getTypeIdentifier from './getTypeIdentifier.js';
 import isReactBuiltinReference from './isReactBuiltinReference.js';
+import unwrapBuiltinTSPropTypes from './unwrapBuiltinTSPropTypes.js';
 
 // TODO TESTME
 
@@ -62,13 +63,11 @@ function findAssignedVariableType(
       isReactBuiltinReference(typeName, 'VoidFunctionComponent') ||
       isReactBuiltinReference(typeName, 'VFC')
     ) {
-      const typeParameters = typeAnnotation.get(
-        'typeParameters',
-      ) as NodePath<TSTypeParameterInstantiation>;
+      const typeParameters = typeAnnotation.get('typeParameters');
 
-      if (!typeParameters.hasNode()) return null;
-
-      return typeParameters.get('params')[0] ?? null;
+      if (typeParameters.hasNode()) {
+        return typeParameters.get('params')[0] ?? null;
+      }
     }
   }
 
@@ -106,27 +105,25 @@ export default (componentDefinition: NodePath): NodePath[] => {
         typePaths.push(typeAnnotation);
       }
     }
+  } else {
+    const propsParam = getStatelessPropsPath(componentDefinition);
 
-    return typePaths;
-  }
-
-  const propsParam = getStatelessPropsPath(componentDefinition);
-
-  if (propsParam) {
-    const typeAnnotation = getTypeAnnotation(propsParam);
+    if (propsParam) {
+      const typeAnnotation = getTypeAnnotation(propsParam);
 
-    if (typeAnnotation) {
-      typePaths.push(typeAnnotation);
+      if (typeAnnotation) {
+        typePaths.push(typeAnnotation);
+      }
     }
-  }
 
-  const assignedVariableType = findAssignedVariableType(componentDefinition);
+    const assignedVariableType = findAssignedVariableType(componentDefinition);
 
-  if (assignedVariableType) {
-    typePaths.push(assignedVariableType);
+    if (assignedVariableType) {
+      typePaths.push(assignedVariableType);
+    }
   }
 
-  return typePaths;
+  return typePaths.map((typePath) => unwrapBuiltinTSPropTypes(typePath));
 };
 
 export function applyToTypeProperties(

packages/react-docgen/src/utils/unwrapBuiltinTSPropTypes.ts

@@ -0,0 +1,31 @@
+import type { NodePath } from '@babel/traverse';
+import isReactBuiltinReference from './isReactBuiltinReference.js';
+
+/**
+ * Unwraps NodePaths from the builtin TS types `PropsWithoutRef`,
+ * `PropsWithRef` and `PropsWithChildren` and returns the inner type param.
+ * If none of the builtin types is detected the path is returned as-is
+ */
+export default function unwrapBuiltinTSPropTypes(typePath: NodePath): NodePath {
+  if (typePath.isTSTypeReference()) {
+    const typeName = typePath.get('typeName');
+
+    if (
+      isReactBuiltinReference(typeName, 'PropsWithoutRef') ||
+      isReactBuiltinReference(typeName, 'PropsWithRef') ||
+      isReactBuiltinReference(typeName, 'PropsWithChildren')
+    ) {
+      const typeParameters = typePath.get('typeParameters');
+
+      if (typeParameters.hasNode()) {
+        const innerType = typeParameters.get('params')[0];
+
+        if (innerType) {
+          return unwrapBuiltinTSPropTypes(innerType);
+        }
+      }
+    }
+  }
+
+  return typePath;
+}