TypeScript & UI: Support displaying parameters & return types in Type Table

Author: fuma-nama

.changeset/cyan-mice-sell.md

@@ -0,0 +1,6 @@
+---
+'fumadocs-typescript': patch
+'fumadocs-ui': patch
+---
+
+Type Table: Support displaying parameters & return types

apps/docs/content/docs/ui/components/auto-type-table.mdx

@@ -11,7 +11,14 @@ description: Auto-generated type table
      *
      * See https://fumadocs.vercel.app/docs/ui/components/type-table
      */
-    name: string;
+    name: boolean | null;
+
+    /**
+    * @param name - user name.
+    * @param allowNull - is null value allowed.
+    * @returns user ID
+    **/
+    fn: (name: string, allowNull?: boolean) => string
 
     /**
     * We love Shiki.
@@ -21,7 +28,7 @@ description: Auto-generated type table
     * \`\`\`
     * @default { a: "test" }
     */
-    options: Partial<{ a: unknown }>;
+    options?: Partial<{ a: unknown }>;
 
 }`} />
 

packages/typescript/src/lib/base.ts

@@ -28,11 +28,16 @@ export interface DocEntry {
   type: string;
   simplifiedType: string;
 
-  tags: Record<string, string>;
+  tags: RawTag[];
   required: boolean;
   deprecated: boolean;
 }
 
+export interface RawTag {
+  name: string;
+  text: string;
+}
+
 interface EntryContext {
   program: Project;
   transform?: Transformer;
@@ -201,16 +206,21 @@ function getDocEntry(
     .getTypeChecker()
     .getTypeOfSymbolAtLocation(prop, context.declaration);
   const isOptional = prop.isOptional();
-  const tags = Object.fromEntries(
-    prop
-      .getJsDocTags()
-      .map((tag) => [tag.getName(), ts.displayPartsToString(tag.getText())]),
+  const tags = prop.getJsDocTags().map(
+    (tag) =>
+      ({
+        name: tag.getName(),
+        text: ts.displayPartsToString(tag.getText()),
+      }) satisfies RawTag,
   );
 
-  let type = getFullType(subType, isOptional);
+  let type = getFullType(subType);
 
-  if ('remarks' in tags) {
-    type = /^`(?<name>.+)`/.exec(tags.remarks)?.[1] ?? type;
+  for (const tag of tags) {
+    if (tag.name !== 'remarks') continue;
+
+    // replace type with @remarks
+    type = /^`(?<name>.+)`/.exec(tag.text)?.[1] ?? type;
   }
 
   const entry: DocEntry = {
@@ -222,37 +232,27 @@ function getDocEntry(
     ),
     tags,
     type,
-    simplifiedType: getSimpleForm(subType, program.getTypeChecker()),
+    simplifiedType: getSimpleForm(
+      subType,
+      program.getTypeChecker(),
+      isOptional,
+    ),
     required: !isOptional,
-    deprecated: prop
-      .getJsDocTags()
-      .some((tag) => tag.getName() === 'deprecated'),
+    deprecated: tags.some((tag) => tag.name === 'deprecated'),
   };
 
   transform?.call(context, entry, subType, prop);
 
   return entry;
 }
 
-function getFullType(type: Type, isOptional: boolean): string {
-  if (type.isUnion() && isOptional) {
-    const t = type.compilerType as ts.UnionType;
-    const originalTypes = t.types;
-
-    t.types = t.types.filter((v) => v.flags !== ts.TypeFlags.Undefined);
-    const result = getFullType(type, false);
-    t.types = originalTypes;
-
-    return result;
-  }
-
-  let typeName = type
-    .getNonNullableType()
-    .getText(
-      undefined,
-      ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope &
-        ts.TypeFormatFlags.NoTruncation,
-    );
+function getFullType(type: Type): string {
+  let typeName = type.getText(
+    undefined,
+    ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope |
+      ts.TypeFormatFlags.NoTruncation |
+      ts.TypeFormatFlags.InTypeAlias,
+  );
 
   if (type.getAliasSymbol() && type.getAliasTypeArguments().length === 0) {
     typeName = type.getAliasSymbol()?.getEscapedName() ?? typeName;

packages/typescript/src/lib/get-simple-form.ts

@@ -1,22 +1,35 @@
 import * as ts from 'ts-morph';
 
-function simplifyType(type: ts.Type, checker: ts.TypeChecker): string {
-  // Handle union types
+export function getSimpleForm(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  noUndefined = false,
+): string {
+  if (type.isUndefined() && noUndefined) return '';
+
+  const alias = type.getAliasSymbol();
+  if (alias && type.getAliasTypeArguments().length === 0) {
+    return alias.getEscapedName();
+  }
+
   if (type.isUnion()) {
     const types: string[] = [];
     for (const t of type.getUnionTypes()) {
-      const str = simplifyType(t, checker);
-      if (str !== 'never') types.unshift(str);
+      const str = getSimpleForm(t, checker, noUndefined);
+      if (str.length > 0 && str !== 'never') types.unshift(str);
     }
 
-    return types.length > 0 ? types.join(' | ') : 'never';
+    return types.length > 0
+      ? // boolean | null will become true | false | null, need to ensure it's still returned as boolean
+        types.join(' | ').replace('true | false', 'boolean')
+      : 'never';
   }
 
-  // Handle intersection types
   if (type.isIntersection()) {
     const types: string[] = [];
     for (const t of type.getIntersectionTypes()) {
-      types.unshift(simplifyType(t, checker));
+      const str = getSimpleForm(t, checker, noUndefined);
+      if (str.length > 0 && str !== 'never') types.unshift(str);
     }
 
     return types.join(' & ');
@@ -25,17 +38,12 @@ function simplifyType(type: ts.Type, checker: ts.TypeChecker): string {
   if (type.isTuple()) {
     const elements = type
       .getTupleElements()
-      .map((t) => simplifyType(t, checker))
+      .map((t) => getSimpleForm(t, checker))
       .join(', ');
 
     return `[${elements}]`;
   }
 
-  const alias = type.getAliasSymbol();
-  if (alias && type.getAliasTypeArguments().length === 0) {
-    return alias.getEscapedName();
-  }
-
   if (type.isArray() || type.isReadonlyArray()) {
     return 'array';
   }
@@ -48,9 +56,9 @@ function simplifyType(type: ts.Type, checker: ts.TypeChecker): string {
     return 'object';
   }
 
-  return type.getText();
-}
-
-export function getSimpleForm(type: ts.Type, checker: ts.TypeChecker): string {
-  return simplifyType(type, checker);
+  return type.getText(
+    undefined,
+    ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope |
+      ts.TypeFormatFlags.InTypeAlias,
+  );
 }

packages/typescript/src/lib/mdx.ts

@@ -2,8 +2,8 @@ import * as path from 'node:path';
 import {
   type DocEntry,
   type GeneratedDoc,
-  type Generator,
   type GenerateOptions,
+  type Generator,
 } from './base';
 
 interface Templates {
@@ -39,8 +39,8 @@ ${doc.description}
 
 ${c.description || 'No Description'}
 
-${Object.entries(c.tags)
-  .map(([tag, value]) => `- ${tag}:\n${replaceJsDocLinks(value)}`)
+${c.tags
+  .map((tag) => `- ${tag.name}:\n${replaceJsDocLinks(tag.text)}`)
   .join('\n')}
 
 </div>`,

packages/typescript/src/lib/parse-tags.ts

@@ -0,0 +1,43 @@
+import { RawTag } from '@/lib/base';
+
+export interface ParameterTag {
+  name: string;
+  description?: string;
+}
+
+export interface TypedTags {
+  default?: string;
+  params?: ParameterTag[];
+  returns?: string;
+}
+
+/**
+ * Parse tags, only returns recognized fields.
+ */
+export function parseTags(tags: RawTag[]): TypedTags {
+  const typed: TypedTags = {};
+
+  for (const { name: key, text } of tags) {
+    if (key === 'default' || key === 'defaultValue') {
+      typed.default = text;
+      continue;
+    }
+
+    if (key === 'param') {
+      const [param, description] = text.split('-', 2);
+
+      typed.params ??= [];
+      typed.params.push({
+        name: param.trim(),
+        description: description.trim(),
+      });
+      continue;
+    }
+
+    if (key === 'returns') {
+      typed.returns = text;
+    }
+  }
+
+  return typed;
+}