Integration updates (#786)

danez · web-flow · commit 0a2481df6328 · 2023-04-29T13:01:51.000+02:00
* Rename Documentation to DocumentationBuilder

Rename DocumentationObjet to Documentation
Rename toObject to build

* Re-export types from babel

* Remove unnecessary Node types
diff --git a/.changeset/healthy-moles-explain.md b/.changeset/healthy-moles-explain.md
@@ -0,0 +1,5 @@
+---
+'react-docgen': minor
+---
+
+Export the type for the DocumentationBuilder.
diff --git a/.changeset/heavy-plums-repair.md b/.changeset/heavy-plums-repair.md
@@ -0,0 +1,9 @@
+---
+'react-docgen': minor
+---
+
+The types `NodePath` and `babelTypes` are now exported.
+
+These types are useful when building integrations in TypeScript.
+
+`babelTypes` includes all types from `@babel/types`.
diff --git a/.changeset/smart-trainers-film.md b/.changeset/smart-trainers-film.md
@@ -0,0 +1,7 @@
+---
+'react-docgen': major
+---
+
+Renamed the method `toObject` to `build` in the DocumentationBuilder.
+
+This method might be used by integrations.
diff --git a/packages/react-docgen/src/Documentation.ts b/packages/react-docgen/src/Documentation.ts
@@ -1,4 +1,4 @@
-export interface DocumentationObject {
+export interface Documentation {
   childContext?: Record<string, PropDescriptor>;
   composes?: string[];
   context?: Record<string, PropDescriptor>;
@@ -141,7 +141,7 @@ export interface PropDescriptor {
   description?: string;
 }
 
-export default class Documentation {
+export default class DocumentationBuilder {
   #props: Map<string, PropDescriptor>;
   #context: Map<string, PropDescriptor>;
   #childContext: Map<string, PropDescriptor>;
@@ -199,8 +199,8 @@ export default class Documentation {
     return propDescriptor;
   }
 
-  toObject(): DocumentationObject {
-    const obj: DocumentationObject = {};
+  build(): Documentation {
+    const obj: Documentation = {};
 
     for (const [key, value] of this.#data) {
       obj[key] = value;
diff --git a/packages/react-docgen/src/handlers/__tests__/codeTypeHandler-test.ts b/packages/react-docgen/src/handlers/__tests__/codeTypeHandler-test.ts
@@ -1,5 +1,5 @@
 import { parse, makeMockImporter } from '../../../tests/utils';
-import Documentation from '../../Documentation';
+import DocumentationBuilder from '../../Documentation';
 import codeTypeHandler from '../codeTypeHandler.js';
 import type DocumentationMock from '../../__mocks__/Documentation';
 import type {
@@ -20,10 +20,11 @@ vi.mock('../../utils/getFlowType.js', () => ({
 }));
 
 describe('codeTypeHandler', () => {
-  let documentation: Documentation & DocumentationMock;
+  let documentation: DocumentationBuilder & DocumentationMock;
 
   beforeEach(() => {
-    documentation = new Documentation() as Documentation & DocumentationMock;
+    documentation = new DocumentationBuilder() as DocumentationBuilder &
+      DocumentationMock;
   });
 
   const mockImporter = makeMockImporter({
diff --git a/packages/react-docgen/src/handlers/__tests__/componentDocblockHandler-test.ts b/packages/react-docgen/src/handlers/__tests__/componentDocblockHandler-test.ts
@@ -1,6 +1,6 @@
 import { makeMockImporter, parse } from '../../../tests/utils';
 import componentDocblockHandler from '../componentDocblockHandler.js';
-import Documentation from '../../Documentation';
+import DocumentationBuilder from '../../Documentation';
 import type DocumentationMock from '../../__mocks__/Documentation';
 import type { NodePath } from '@babel/traverse';
 import type {
@@ -20,10 +20,11 @@ import { beforeEach, describe, expect, test, vi } from 'vitest';
 vi.mock('../../Documentation.js');
 
 describe('componentDocblockHandler', () => {
-  let documentation: Documentation & DocumentationMock;
+  let documentation: DocumentationBuilder & DocumentationMock;
 
   beforeEach(() => {
-    documentation = new Documentation() as Documentation & DocumentationMock;
+    documentation = new DocumentationBuilder() as DocumentationBuilder &
+      DocumentationMock;
   });
 
   function testDockblockHandler(
diff --git a/packages/react-docgen/src/handlers/__tests__/componentMethodsHandler-test.ts b/packages/react-docgen/src/handlers/__tests__/componentMethodsHandler-test.ts
@@ -1,6 +1,6 @@
 import { parse, makeMockImporter } from '../../../tests/utils';
 import componentMethodsHandler from '../componentMethodsHandler.js';
-import Documentation from '../../Documentation';
+import DocumentationBuilder from '../../Documentation';
 import type DocumentationMock from '../../__mocks__/Documentation';
 import type {
   ArrowFunctionExpression,
@@ -18,10 +18,11 @@ import { beforeEach, describe, expect, test, vi } from 'vitest';
 vi.mock('../../Documentation.js');
 
 describe('componentMethodsHandler', () => {
-  let documentation: Documentation & DocumentationMock;
+  let documentation: DocumentationBuilder & DocumentationMock;
 
   beforeEach(() => {
-    documentation = new Documentation() as Documentation & DocumentationMock;
+    documentation = new DocumentationBuilder() as DocumentationBuilder &
+      DocumentationMock;
   });
 
   const mockImporter = makeMockImporter({
diff --git a/packages/react-docgen/src/handlers/__tests__/componentMethodsJsDocHandler-test.ts b/packages/react-docgen/src/handlers/__tests__/componentMethodsJsDocHandler-test.ts
@@ -1,15 +1,16 @@
 import type { NodePath } from '@babel/traverse';
-import Documentation from '../../Documentation';
+import DocumentationBuilder from '../../Documentation';
 import type { ComponentNode } from '../../resolver';
 import type DocumentationMock from '../../__mocks__/Documentation';
 import componentMethodsJsDocHandler from '../componentMethodsJsDocHandler.js';
 import { beforeEach, describe, expect, test } from 'vitest';
 
 describe('componentMethodsJsDocHandler', () => {
-  let documentation: Documentation & DocumentationMock;
+  let documentation: DocumentationBuilder & DocumentationMock;
 
   beforeEach(() => {
-    documentation = new Documentation() as Documentation & DocumentationMock;
+    documentation = new DocumentationBuilder() as DocumentationBuilder &
+      DocumentationMock;
   });
 
   test('stays the same when no docblock is present', () => {
diff --git a/packages/react-docgen/src/handlers/__tests__/defaultPropsHandler-test.ts b/packages/react-docgen/src/handlers/__tests__/defaultPropsHandler-test.ts
@@ -8,18 +8,19 @@ import type {
   VariableDeclaration,
 } from '@babel/types';
 import { parse, makeMockImporter } from '../../../tests/utils';
-import Documentation from '../../Documentation';
+import DocumentationBuilder from '../../Documentation';
 import type DocumentationMock from '../../__mocks__/Documentation';
 import defaultPropsHandler from '../defaultPropsHandler.js';
 import { beforeEach, describe, expect, test, vi } from 'vitest';
 
 vi.mock('../../Documentation.js');
 
 describe('defaultPropsHandler', () => {
-  let documentation: Documentation & DocumentationMock;
+  let documentation: DocumentationBuilder & DocumentationMock;
 
   beforeEach(() => {
-    documentation = new Documentation() as Documentation & DocumentationMock;
+    documentation = new DocumentationBuilder() as DocumentationBuilder &
+      DocumentationMock;
   });
 
   const mockImporter = makeMockImporter({
diff --git a/packages/react-docgen/src/handlers/__tests__/displayNameHandler-test.ts b/packages/react-docgen/src/handlers/__tests__/displayNameHandler-test.ts
@@ -1,5 +1,5 @@
 import { parse, makeMockImporter } from '../../../tests/utils';
-import Documentation from '../../Documentation';
+import DocumentationBuilder from '../../Documentation';
 import displayNameHandler from '../displayNameHandler.js';
 import type DocumentationMock from '../../__mocks__/Documentation';
 import type {
@@ -17,10 +17,11 @@ import { beforeEach, describe, expect, test, vi } from 'vitest';
 vi.mock('../../Documentation.js');
 
 describe('defaultPropsHandler', () => {
-  let documentation: Documentation & DocumentationMock;
+  let documentation: DocumentationBuilder & DocumentationMock;
 
   beforeEach(() => {
-    documentation = new Documentation() as Documentation & DocumentationMock;
+    documentation = new DocumentationBuilder() as DocumentationBuilder &
+      DocumentationMock;
   });
 
   const mockImporter = makeMockImporter({
diff --git a/packages/react-docgen/src/handlers/__tests__/propDocblockHandler-test.ts b/packages/react-docgen/src/handlers/__tests__/propDocblockHandler-test.ts
@@ -1,7 +1,7 @@
 import type { NodePath } from '@babel/traverse';
 import type { ClassDeclaration, ObjectExpression } from '@babel/types';
 import { parse, makeMockImporter, noopImporter } from '../../../tests/utils';
-import Documentation from '../../Documentation';
+import DocumentationBuilder from '../../Documentation';
 import type { Importer } from '../../importer';
 import type { ComponentNode } from '../../resolver';
 import type DocumentationMock from '../../__mocks__/Documentation';
@@ -11,10 +11,11 @@ import { beforeEach, describe, expect, test, vi } from 'vitest';
 vi.mock('../../Documentation.js');
 
 describe('propDocblockHandler', () => {
-  let documentation: Documentation & DocumentationMock;
+  let documentation: DocumentationBuilder & DocumentationMock;
 
   beforeEach(() => {
-    documentation = new Documentation() as Documentation & DocumentationMock;
+    documentation = new DocumentationBuilder() as DocumentationBuilder &
+      DocumentationMock;
   });
 
   const mockImporter = makeMockImporter({
diff --git a/packages/react-docgen/src/handlers/__tests__/propTypeCompositionHandler-test.ts b/packages/react-docgen/src/handlers/__tests__/propTypeCompositionHandler-test.ts
@@ -1,6 +1,6 @@
 import { parse, makeMockImporter, noopImporter } from '../../../tests/utils';
 import propTypeCompositionHandler from '../propTypeCompositionHandler.js';
-import Documentation from '../../Documentation';
+import DocumentationBuilder from '../../Documentation';
 import type DocumentationMock from '../../__mocks__/Documentation';
 import type { NodePath } from '@babel/traverse';
 import type { Importer } from '../../importer';
@@ -12,10 +12,11 @@ vi.mock('../../Documentation.js');
 vi.mock('../../utils/getPropType.js', () => () => ({}));
 
 describe('propTypeCompositionHandler', () => {
-  let documentation: Documentation & DocumentationMock;
+  let documentation: DocumentationBuilder & DocumentationMock;
 
   beforeEach(() => {
-    documentation = new Documentation() as Documentation & DocumentationMock;
+    documentation = new DocumentationBuilder() as DocumentationBuilder &
+      DocumentationMock;
   });
 
   const mockImporter = makeMockImporter({
@@ -49,7 +50,8 @@ describe('propTypeCompositionHandler', () => {
       propTypeCompositionHandler(documentation, definition);
       expect(documentation.composes).toEqual(['Foo.react']);
 
-      documentation = new Documentation() as Documentation & DocumentationMock;
+      documentation = new DocumentationBuilder() as DocumentationBuilder &
+        DocumentationMock;
       definition = parseSrc(`
         ${getSrc('SharedProps')}
         var SharedProps = require("SharedProps");
diff --git a/packages/react-docgen/src/handlers/__tests__/propTypeHandler-test.ts b/packages/react-docgen/src/handlers/__tests__/propTypeHandler-test.ts
@@ -1,5 +1,5 @@
 import { parse, makeMockImporter, noopImporter } from '../../../tests/utils';
-import Documentation from '../../Documentation';
+import DocumentationBuilder from '../../Documentation';
 import type DocumentationMock from '../../__mocks__/Documentation';
 import { propTypeHandler } from '../propTypeHandler.js';
 import getPropType from '../../utils/getPropType';
@@ -20,10 +20,11 @@ vi.mock('../../Documentation.js');
 vi.mock('../../utils/getPropType.js', () => ({ default: vi.fn(() => ({})) }));
 
 describe('propTypeHandler', () => {
-  let documentation: Documentation & DocumentationMock;
+  let documentation: DocumentationBuilder & DocumentationMock;
 
   beforeEach(() => {
-    documentation = new Documentation() as Documentation & DocumentationMock;
+    documentation = new DocumentationBuilder() as DocumentationBuilder &
+      DocumentationMock;
   });
 
   const mockImporter = makeMockImporter({
diff --git a/packages/react-docgen/src/handlers/componentDocblockHandler.ts b/packages/react-docgen/src/handlers/componentDocblockHandler.ts
@@ -2,7 +2,7 @@ import type Documentation from '../Documentation.js';
 import { getDocblock } from '../utils/docblock.js';
 import isReactForwardRefCall from '../utils/isReactForwardRefCall.js';
 import resolveToValue from '../utils/resolveToValue.js';
-import type { NodePath, Node } from '@babel/traverse';
+import type { NodePath } from '@babel/traverse';
 import type { ComponentNode } from '../resolver/index.js';
 import type { Handler } from './index.js';
 
@@ -21,7 +21,7 @@ function getDocblockFromComponent(path: NodePath): string | null {
   }
   if (description == null) {
     // Find parent statement (e.g. var Component = React.createClass(<path>);)
-    let searchPath: NodePath<Node> | null = path;
+    let searchPath: NodePath | null = path;
 
     while (searchPath && !searchPath.isStatement()) {
       searchPath = searchPath.parentPath;
diff --git a/packages/react-docgen/src/handlers/defaultPropsHandler.ts b/packages/react-docgen/src/handlers/defaultPropsHandler.ts
@@ -9,7 +9,6 @@ import type Documentation from '../Documentation.js';
 import type { DefaultValueDescriptor } from '../Documentation.js';
 import type { NodePath } from '@babel/traverse';
 import type {
-  Node,
   ObjectMethod,
   ObjectProperty,
   RestElement,
@@ -70,7 +69,7 @@ function getStatelessPropsPath(
 function getDefaultPropsPath(
   componentDefinition: NodePath<ComponentNode>,
 ): NodePath | null {
-  let defaultPropsPath: NodePath<Node> | null = getMemberValuePath(
+  let defaultPropsPath: NodePath | null = getMemberValuePath(
     componentDefinition,
     'defaultProps',
   );
diff --git a/packages/react-docgen/src/handlers/propDocblockHandler.ts b/packages/react-docgen/src/handlers/propDocblockHandler.ts
@@ -1,5 +1,4 @@
 import type { NodePath } from '@babel/traverse';
-import type { Node } from '@babel/types';
 import getMemberValuePath from '../utils/getMemberValuePath.js';
 import resolveToValue from '../utils/resolveToValue.js';
 import setPropDescription from '../utils/setPropDescription.js';
@@ -33,7 +32,7 @@ const propDocblockHandler: Handler = function (
   documentation: Documentation,
   componentDefinition: NodePath<ComponentNode>,
 ): void {
-  let propTypesPath: NodePath<Node> | null = getMemberValuePath(
+  let propTypesPath: NodePath | null = getMemberValuePath(
     componentDefinition,
     'propTypes',
   );
diff --git a/packages/react-docgen/src/handlers/propTypeCompositionHandler.ts b/packages/react-docgen/src/handlers/propTypeCompositionHandler.ts
@@ -3,7 +3,7 @@ import resolveToModule from '../utils/resolveToModule.js';
 import resolveToValue from '../utils/resolveToValue.js';
 import type Documentation from '../Documentation.js';
 import type { NodePath } from '@babel/traverse';
-import type { ObjectExpression, Node } from '@babel/types';
+import type { ObjectExpression } from '@babel/types';
 import type { Handler } from './index.js';
 import type { ComponentNode } from '../resolver/index.js';
 
@@ -37,7 +37,7 @@ const propTypeCompositionHandler: Handler = function (
   documentation: Documentation,
   componentDefinition: NodePath<ComponentNode>,
 ): void {
-  let propTypesPath: NodePath<Node> | null = getMemberValuePath(
+  let propTypesPath: NodePath | null = getMemberValuePath(
     componentDefinition,
     'propTypes',
   );
diff --git a/packages/react-docgen/src/handlers/propTypeHandler.ts b/packages/react-docgen/src/handlers/propTypeHandler.ts
@@ -9,7 +9,6 @@ import resolveToValue from '../utils/resolveToValue.js';
 import type Documentation from '../Documentation.js';
 import type { PropDescriptor, PropTypeDescriptor } from '../Documentation.js';
 import type { NodePath } from '@babel/traverse';
-import type { Node } from '@babel/types';
 import type { Handler } from './index.js';
 import type { ComponentNode } from '../resolver/index.js';
 
@@ -65,7 +64,7 @@ function getPropTypeHandler(propName: string): Handler {
     documentation: Documentation,
     componentDefinition: NodePath<ComponentNode>,
   ): void {
-    let propTypesPath: NodePath<Node> | null = getMemberValuePath(
+    let propTypesPath: NodePath | null = getMemberValuePath(
       componentDefinition,
       propName,
     );
diff --git a/packages/react-docgen/src/main.ts b/packages/react-docgen/src/main.ts
@@ -7,7 +7,8 @@ import {
   makeFsImporter,
 } from './importer/index.js';
 import * as utils from './utils/index.js';
-import type { DocumentationObject as Documentation } from './Documentation.js';
+import type { Documentation } from './Documentation.js';
+import type DocumentationBuilder from './Documentation.js';
 import type {
   Resolver,
   ResolverClass,
@@ -60,6 +61,9 @@ function defaultParse(
   return parse(String(src), defaultConfig);
 }
 
+export type { NodePath } from '@babel/traverse';
+export type * as babelTypes from '@babel/types';
+
 export {
   builtinHandlers,
   builtinResolvers,
@@ -80,4 +84,5 @@ export type {
   FileState,
   Config,
   Documentation,
+  DocumentationBuilder,
 };
diff --git a/packages/react-docgen/src/parse.ts b/packages/react-docgen/src/parse.ts
diff --git a/packages/react-docgen/src/utils/__tests__/setPropDescription-test.ts b/packages/react-docgen/src/utils/__tests__/setPropDescription-test.ts
diff --git a/packages/react-docgen/src/utils/expressionTo.ts b/packages/react-docgen/src/utils/expressionTo.ts
diff --git a/packages/react-docgen/src/utils/isRequiredPropType.ts b/packages/react-docgen/src/utils/isRequiredPropType.ts
diff --git a/packages/react-docgen/src/utils/postProcessDocumentation.ts b/packages/react-docgen/src/utils/postProcessDocumentation.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'react-docgen': minor
 +---
++
 +Export the type for the DocumentationBuilder.