feat: 🎸 rendering improvements

Author: prc5

packages/core/package.json

@@ -16,6 +16,7 @@
     "clean": "npx rimraf dist",
     "test": "jest --watchAll --maxWorkers=3",
     "test:pipeline": "jest --watchAll=false --maxWorkers=1 --no-cache --detectOpenHandles --forceExit",
+    "test:update-snapshot": "jest --watchAll --maxWorkers=3 --updateSnapshot",
     "start": "tsc && (concurrently \"tsc -w\" \"tsc-alias -w\")",
     "build": "yarn clean && tsc -p tsconfig.build.json && tsc-alias",
     "lint": "eslint . --ext .js,.jsx,.tsx,.ts --fix",

packages/core/src/docs/docs.tsx

@@ -6,8 +6,7 @@ import { PluginOptions, PkgMeta } from "../types/package.types";
 import { pluginOptionsPath, packageConfigPath } from "../constants/paths.constants";
 import { cleanFileName } from "../parsing/generator/utils/file.utils";
 import { getPackageDocsPath } from "../parsing/generator/utils/package.utils";
-import { ComponentsProps } from "importer/components/component.types";
-import { getComponent } from "importer/components/component-map.utils";
+import { DocsComponents, getComponent, GetComponentProps } from "importer/components/component-map.utils";
 import { getFile, getMatchingElement } from "importer/utils/docs.utils";
 
 // TODO FIGURE OUT HOW TO MAKE THIS WORK
@@ -18,7 +17,9 @@ const file = {} as any;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const options = {} as any;
 
-export const Docs = (props: ComponentsProps & { packageName: string; componentName: string }) => {
+export const Docs = (
+  props: GetComponentProps<keyof DocsComponents> & { packageName: string; componentName: string },
+) => {
   const { packageName, componentName } = props;
 
   const currentVersionedDir = file.history[0]

packages/core/src/importer/components/component-map.utils.tsx

@@ -1,7 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import React from "react";
-
-import { PagePropsType } from "../../types/page.types";
 import { Definition } from "../../pages/components/definition";
 import { Returns } from "../../pages/components/returns";
 import { Generics } from "../../pages/components/generics";
@@ -18,76 +14,44 @@ import { Description } from "../../pages/components/description";
 import { Signature } from "../../pages/components/signature";
 import { Sources } from "../../pages/components/sources";
 import { Type } from "../../pages/components/type";
-import { ComponentsProps } from "./component.types";
 import { ReturnsPreview } from "../../pages/components/returns-preview";
 import { Npm } from "pages/components/npm";
 import { Details } from "pages/components/details";
 
-export const getComponent = (options: ComponentsProps): React.FC<PagePropsType> => {
+const components = {
+  definition: Definition,
+  npm: Npm,
+  import: Import,
+  details: Details,
+  description: Description,
+  generics: Generics,
+  method: Method,
+  methods: Methods,
+  name: Name,
+  parameter: Parameter,
+  parameters: Parameters,
+  preview: Preview,
+  property: Property,
+  properties: Properties,
+  returns: Returns,
+  returnsPreview: ReturnsPreview,
+  signature: Signature,
+  sources: Sources,
+  type: Type,
+};
+
+export type DocsComponents = typeof components;
+
+export type GetComponentProps<Name extends keyof DocsComponents> = {
+  type: Name;
+} & React.ComponentPropsWithoutRef<(typeof components)[Name]>;
+
+export const getComponent = <Name extends keyof DocsComponents>(options: GetComponentProps<Name>) => {
   const { type: componentType } = options;
-  switch (componentType) {
-    case "definition": {
-      return Definition;
-    }
-    case "npm": {
-      return Npm;
-    }
-    case "import": {
-      return Import;
-    }
-    case "details": {
-      return Details;
-    }
-    case "description": {
-      return Description;
-    }
-    case "generics": {
-      return Generics as any;
-    }
-    case "method": {
-      return Method;
-    }
-    case "methods": {
-      return Methods;
-    }
-    case "name": {
-      return Name;
-    }
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    case "parameter": {
-      return Parameter;
-    }
-    case "parameters": {
-      return Parameters;
-    }
-    case "preview": {
-      return Preview as any;
-    }
-    case "property": {
-      return Property;
-    }
-    case "properties": {
-      return Properties;
-    }
-    case "returns": {
-      return Returns;
-    }
-    case "returnsPreview": {
-      return ReturnsPreview;
-    }
-    case "signature": {
-      return Signature as any;
-    }
-    case "sources": {
-      return Sources;
-    }
-    case "type": {
-      return Type as React.FC<PagePropsType>;
-    }
-    // Todo display page
-    default: {
-      throw new Error(`Component type not found - ${componentType}`);
-    }
+
+  if (!components[componentType]) {
+    throw new Error(`Component type not found - ${componentType}`);
   }
+
+  return components[componentType];
 };

packages/core/src/importer/components/component.types.ts

@@ -1,4 +1,5 @@
 import path from "path";
+import React from "react";
 // TS fails to import it at build
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore
@@ -13,11 +14,10 @@ import { parse } from "@reins/query-params";
 import { PluginOptions, PkgMeta } from "../types/package.types";
 import { pluginOptionsPath, packageConfigPath } from "../constants/paths.constants";
 import { getFile, getMatchingElement } from "./utils/docs.utils";
-import { getComponent } from "./components/component-map.utils";
+import { DocsComponents, getComponent, GetComponentProps } from "./components/component-map.utils";
 import { cleanFileName } from "../parsing/generator/utils/file.utils";
 import { renderer } from "../parsing/renderer/renderer";
 import { getPackageDocsPath } from "../parsing/generator/utils/package.utils";
-import { ComponentsProps } from "./components/component.types";
 
 function escapeRegExp(string: string) {
   return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
@@ -135,9 +135,9 @@ export const importer = (options: { packageRoute: string; apiDir: string; versio
           if (optionsNormalization[optionsNormalization.length - 1] === "&") {
             optionsNormalization = optionsNormalization.slice(0, -1);
           }
-          const parsedOptions: ComponentsProps = parse(optionsNormalization) as ComponentsProps;
+          const parsedOptions = parse(optionsNormalization) as GetComponentProps<keyof DocsComponents>;
           const Component = getComponent(parsedOptions);
-          const html = renderer(Component, {
+          const html = renderer(Component as React.FC, {
             ...parsedOptions,
             reflection,
             reflectionsTree: packagesReflections,

packages/core/src/importer/importer.ts

@@ -12,6 +12,7 @@ export const Description: React.FC<PagePropsType & DescriptionProps> = (props) =
   const { reflection, className = "" } = props;
 
   const signature = getSignature(reflection);
+  const children = getCommentNode(signature || reflection) || getCommentNode(reflection);
 
-  return <div className={`api-docs__description ${className}`}>{getCommentNode(signature || reflection)}</div>;
+  return <div className={`api-docs__description ${className}`}>{children}</div>;
 };

packages/core/src/pages/components/description.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 
-import { getTag } from "pages/handlers/tags";
+import { getTags } from "pages/handlers/tags";
 import { getSignature } from "pages/utils/signature.utils";
 import { PagePropsType } from "types/page.types";
 import { HeadingType } from "types/components.types";
@@ -17,7 +17,7 @@ export const Examples: React.FC<PagePropsType & ExamplesProps> = (props) => {
 
   const signature = getSignature(reflection);
   const comment = signature?.comment || reflection.comment;
-  const examples = getTag(comment, "@example");
+  const examples = getTags(comment, "@example");
 
   if (!examples.length) {
     return null;

packages/core/src/pages/components/examples.tsx

@@ -19,7 +19,6 @@ export * from "./returns-preview";
 export * from "./returns";
 export * from "./section";
 export * from "./separator";
-export * from "./signature";
 export * from "./sources";
 export * from "./tag";
 export * from "./type";

packages/core/src/pages/components/index.ts

@@ -21,7 +21,7 @@ export type MethodProps = {
 };
 
 export const Method: React.FC<PagePropsType & MethodProps> = (props) => {
-  const { reflection, className = "", display, withParams = false } = props;
+  const { reflection, reflectionsTree, className = "", display, withParams = false } = props;
   const { name } = reflection;
   const methodSignature = getSignature(reflection);
 
@@ -43,6 +43,7 @@ export const Method: React.FC<PagePropsType & MethodProps> = (props) => {
         pageProps={props}
         title="Parameters"
         reflections={methodSignature.parameters}
+        reflectionsTree={reflectionsTree}
       />
     );
   }
@@ -59,6 +60,7 @@ export const Method: React.FC<PagePropsType & MethodProps> = (props) => {
         pageProps={props}
         title="Parameters"
         reflections={methodSignature.parameters}
+        reflectionsTree={reflectionsTree}
       />
     );
   }
@@ -82,7 +84,7 @@ export const Method: React.FC<PagePropsType & MethodProps> = (props) => {
       <Section headingSize="h6" title="Parameters">
         <Parameters {...props} headingSize="h4" />
       </Section>
-      <Section headingSize="h6" title="Return">
+      <Section headingSize="h6" title="Returns">
         <Returns {...props} />
       </Section>
       <hr />

packages/core/src/pages/components/method.tsx

@@ -3,7 +3,7 @@ import React from "react";
 import { PagePropsType } from "../../types/page.types";
 import { getMethods } from "../utils/methods.utils";
 import { Method } from "./method";
-import { getTypesArray } from "../utils/properties.utils";
+import { getTypes } from "../utils/properties.utils";
 import { DisplayType } from "types/components.types";
 import { Table } from "../modules/table/table";
 import { Grid } from "../modules/grid/grid";
@@ -15,7 +15,7 @@ export type MethodsProps = {
 
 export const Methods: React.FC<PagePropsType & MethodsProps> = (props) => {
   const { reflection, reflectionsTree, className = "", display } = props;
-  const children = getTypesArray(reflectionsTree, reflection);
+  const children = getTypes(reflectionsTree, reflection);
 
   if (!children) return null;
 
@@ -25,13 +25,25 @@ export const Methods: React.FC<PagePropsType & MethodsProps> = (props) => {
 
   if (display === "grid") {
     return (
-      <Grid className={`api-docs__methods ${className}`} pageProps={props} title="Methods" reflections={methods} />
+      <Grid
+        className={`api-docs__methods ${className}`}
+        pageProps={props}
+        title="Methods"
+        reflections={methods}
+        reflectionsTree={reflectionsTree}
+      />
     );
   }
 
   if (display === "table") {
     return (
-      <Table className={`api-docs__methods ${className}`} pageProps={props} title="Methods" reflections={methods} />
+      <Table
+        className={`api-docs__methods ${className}`}
+        pageProps={props}
+        title="Methods"
+        reflections={methods}
+        reflectionsTree={reflectionsTree}
+      />
     );
   }