refactor ts info extract (using ts-morph); support complex type. (#124)

Author: csr632

packages/create-project/template-lib-monorepo/packages/button/README.md

@@ -17,9 +17,11 @@ You can import demos like this:
 
 <Demo src="./demos/demo2.tsx" />
 
-## Extract API info from Typescript code
+## Extract Type info from Typescript code
 
-You can extract API from Typescript interface and render it into page.
+You can extract Typescript type info and render it into page. This is very useful for API documentation.
+
+### Render Interface
 
 The following markdown
 
@@ -33,7 +35,19 @@ will result in:
 
 <TsInfo src="./src/types.ts" name="ButtonProps" />
 
-In jsx page, You can render TsInfo like this:
+### Render Type Alias
+
+Besides interface, TsInfo API also support type alias.
+
+SomeObjectLiteralType (Object Literal):
+<TsInfo src="./src/types.ts" name="SomeObjectLiteralType" />
+
+SomeComplexType (Complex Type):
+<TsInfo src="./src/types.ts" name="SomeComplexType" />
+
+### Using TsInfo API in JS files
+
+In jsx page, You can import and render tsInfo like this:
 
 ```tsx
 import tsInfoData from './types.ts?tsInfo=ButtonProps'

packages/create-project/template-lib-monorepo/packages/button/src/types.ts

@@ -1,7 +1,7 @@
 /**
  * This is the description of the Button component's props
  */
-export interface ButtonProps {
+export interface ButtonProps<TestGenerics extends string> extends Base {
   /**
    * the type of button
    * @defaultValue 'default'
@@ -11,7 +11,7 @@ export interface ButtonProps {
    * the size of button
    * @defaultValue 'middle'
    */
-  size?: 'large' | 'middle' | 'small'
+  size?: 'large' | 'middle' | 'small' | TestGenerics
   /**
    * loading state of button
    * @defaultValue false
@@ -21,8 +21,46 @@ export interface ButtonProps {
    * click handler
    */
   onClick?: (event: React.MouseEvent) => void
+  /** test method declaration */
+  testMethod(param: string): void
+  /** test required property */
+  testRequired: boolean
+}
+
+interface Base {
   /**
-   * button content
+   * children content
    */
   children: React.ReactNode
 }
+
+export type SomeObjectLiteralType<TestGenerics> = {
+  /**
+   * the type of button
+   * @defaultValue 'default'
+   */
+  type?: 'primary' | 'default' | 'text'
+  /**
+   * the size of button
+   * @defaultValue 'middle'
+   */
+  size?: 'large' | 'middle' | 'small' | TestGenerics
+  /**
+   * loading state of button
+   * @defaultValue false
+   */
+  loading?: boolean
+  /**
+   * click handler
+   */
+  onClick?: (event: React.MouseEvent) => void
+  /** test method declaration */
+  testMethod(param: string): void
+  /** test required property */
+  testRequired: boolean
+}
+
+/**
+ * Description of SomeComplexType ...
+ */
+export type SomeComplexType = 0 | 1 | 'a' | 'b' | { key: string }

packages/create-project/template-lib/src/Button/README.md

@@ -17,9 +17,11 @@ You can import demos like this:
 
 <Demo src="./demos/demo2.tsx" />
 
-## Extract API info from Typescript code
+## Extract Type info from Typescript code
 
-You can extract API from Typescript interface and render it into page.
+You can extract Typescript type info and render it into page. This is very useful for API documentation.
+
+### Render Interface
 
 The following markdown
 
@@ -33,7 +35,19 @@ will result in:
 
 <TsInfo src="./types.ts" name="ButtonProps" />
 
-In jsx page, You can render TsInfo like this:
+### Render Type Alias
+
+Besides interface, TsInfo API also support type alias.
+
+SomeObjectLiteralType (Object Literal):
+<TsInfo src="./types.ts" name="SomeObjectLiteralType" />
+
+SomeComplexType (Complex Type):
+<TsInfo src="./types.ts" name="SomeComplexType" />
+
+### Using TsInfo API in JS files
+
+In jsx page, You can import and render tsInfo like this:
 
 ```tsx
 import tsInfoData from './types.ts?tsInfo=ButtonProps'

packages/create-project/template-lib/src/Button/types.ts

@@ -1,7 +1,7 @@
 /**
  * This is the description of the Button component's props
  */
-export interface ButtonProps {
+export interface ButtonProps<TestGenerics extends string> extends Base {
   /**
    * the type of button
    * @defaultValue 'default'
@@ -11,7 +11,7 @@ export interface ButtonProps {
    * the size of button
    * @defaultValue 'middle'
    */
-  size?: 'large' | 'middle' | 'small'
+  size?: 'large' | 'middle' | 'small' | TestGenerics
   /**
    * loading state of button
    * @defaultValue false
@@ -21,8 +21,46 @@ export interface ButtonProps {
    * click handler
    */
   onClick?: (event: React.MouseEvent) => void
+  /** test method declaration */
+  testMethod(param: string): void
+  /** test required property */
+  testRequired: boolean
+}
+
+interface Base {
   /**
-   * button content
+   * children content
    */
   children: React.ReactNode
 }
+
+export type SomeObjectLiteralType<TestGenerics> = {
+  /**
+   * the type of button
+   * @defaultValue 'default'
+   */
+  type?: 'primary' | 'default' | 'text'
+  /**
+   * the size of button
+   * @defaultValue 'middle'
+   */
+  size?: 'large' | 'middle' | 'small' | TestGenerics
+  /**
+   * loading state of button
+   * @defaultValue false
+   */
+  loading?: boolean
+  /**
+   * click handler
+   */
+  onClick?: (event: React.MouseEvent) => void
+  /** test method declaration */
+  testMethod(param: string): void
+  /** test required property */
+  testRequired: boolean
+}
+
+/**
+ * Description of SomeComplexType ...
+ */
+export type SomeComplexType = 0 | 1 | 'a' | 'b' | { key: string }

packages/playground/use-theme-doc/pages/components/button/index$.md

@@ -8,8 +8,14 @@ subGroup: general
 demo1:
 <Demo src="./demos/demo1.tsx" />
 
-ButtonProps:
+ButtonProps (Interface):
 <TsInfo src="./types.ts" name="ButtonProps" />
 
-ButtonProps by FileText:
-<FileText src="./types.ts" syntax="ts" />
+SomeObjectLiteralType (Object Literal):
+<TsInfo src="./types.ts" name="SomeObjectLiteralType" />
+
+SomeComplexType (Complex Type):
+<TsInfo src="./types.ts" name="SomeComplexType" />
+
+FileText:
+<FileText src="./types.ts" syntax="ts" />

packages/playground/use-theme-doc/pages/components/button/types.ts

@@ -1,7 +1,7 @@
 /**
  * This is the description of the Button component's props
  */
-export interface ButtonProps<TestGenerics extends string> {
+export interface ButtonProps<TestGenerics extends string> extends Base {
   /**
    * the type of button
    * @defaultValue 'default'
@@ -21,8 +21,46 @@ export interface ButtonProps<TestGenerics extends string> {
    * click handler
    */
   onClick?: (event: React.MouseEvent) => void
+  /** test method declaration */
+  testMethod(param: string): void
+  /** test required property */
+  testRequired: boolean
+}
+
+interface Base {
   /**
-   * button content
+   * children content
    */
   children: React.ReactNode
 }
+
+export type SomeObjectLiteralType<TestGenerics> = {
+  /**
+   * the type of button
+   * @defaultValue 'default'
+   */
+  type?: 'primary' | 'default' | 'text'
+  /**
+   * the size of button
+   * @defaultValue 'middle'
+   */
+  size?: 'large' | 'middle' | 'small' | TestGenerics
+  /**
+   * loading state of button
+   * @defaultValue false
+   */
+  loading?: boolean
+  /**
+   * click handler
+   */
+  onClick?: (event: React.MouseEvent) => void
+  /** test method declaration */
+  testMethod(param: string): void
+  /** test required property */
+  testRequired: boolean
+}
+
+/**
+ * Description of SomeComplexType ...
+ */
+export type SomeComplexType = 0 | 1 | 'a' | 'b' | { key: string }

packages/react-pages/clientTypes.d.ts

@@ -11,21 +11,34 @@ export interface PagesInternal {
 }
 
 // the result of tsInfo extraction
-export interface TsInterfaceInfo {
+export type TsInfo =
+  | {
+      // example: type A = { k: v }
+      type: 'object-literal'
+      name: string
+      description: string
+      properties: TsPropertyOrMethodInfo[]
+    }
+  | {
+      // example: interface MyInterface { k: v }
+      type: 'interface'
+      name: string
+      description: string
+      properties: TsPropertyOrMethodInfo[]
+    }
+  | {
+      // complex type literal
+      // example: type A = 'asd' | 123
+      type: 'other'
+      name: string
+      description: string
+      text: string
+    }
+export interface TsPropertyOrMethodInfo {
   name: string
-  // commentText: string
-  description: string
-  // fullText: string
-  properties: TsInterfacePropertyInfo[]
-}
-
-export interface TsInterfacePropertyInfo {
-  name: string
-  // commentText: string
   type: string
   description: string
   defaultValue: string | undefined
-  // fullText: string
   optional: boolean
 }
 

packages/react-pages/package.json

@@ -88,6 +88,7 @@
     "remark-mdx-images": "^2.0.0",
     "slash": "^3.0.0",
     "tiny-invariant": "^1.3.1",
+    "ts-morph": "^17.0.1",
     "typescript": "^4.9.4",
     "unist-util-visit": "^4.1.1"
   }

packages/react-pages/src/node/index.ts

@@ -234,8 +234,8 @@ export type {
   LoadState,
   PagesLoaded,
   PagesStaticData,
-  TsInterfaceInfo,
-  TsInterfacePropertyInfo,
+  TsInfo,
+  TsPropertyOrMethodInfo,
 } from '../../clientTypes'
 
 export type { FileHandler } from './page-strategy/types.doc'

packages/react-pages/src/node/virtual-module-plugins/demo-modules/mdx-plugin.ts

@@ -28,7 +28,7 @@ export function DemoMdxPlugin() {
           const nextIndex = addImports.length
           const varName = `_demo${nextIndex}`
           // add import:
-          // import * as varName from "${srcValue}?tsInfo=${nameValue}"
+          // import * as varName from "${srcValue}?demo"
           addImports.push(
             createNameSpaceImportNode({
               name: varName,