Core & UI: redesign type table

Author: fuma-nama

.changeset/green-lizards-divide.md

@@ -0,0 +1,6 @@
+---
+'fumadocs-typescript': patch
+'fumadocs-ui': patch
+---
+
+Redesign Type Table

.changeset/new-lines-teach.md

@@ -0,0 +1,5 @@
+---
+'fumadocs-core': patch
+---
+
+Expose `highlightHast` API

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

@@ -5,8 +5,6 @@ description: Auto-generated type table
 
 <Wrapper>
 
-<div className="bg-fd-background p-4 rounded-xl">
-
 <AutoTypeTable name="AutoTypeTableExample" type={`export interface AutoTypeTableExample {
     /**
      * Markdown syntax like links, \`code\` are supported.
@@ -26,8 +24,6 @@ description: Auto-generated type table
 
 }`} />
 
-</div>
-
 </Wrapper>
 
 <Callout title="Server Component only" type="warn">

packages/core/src/highlight/index.ts

@@ -1,6 +1,7 @@
 export {
   highlight,
   getHighlighter,
+  highlightHast,
   type HighlightOptions,
   type HighlightOptionsCommon,
   type HighlightOptionsThemes,

packages/core/src/highlight/shiki.ts

@@ -34,7 +34,10 @@ export type HighlightOptions = HighlightOptionsCommon &
 
 const highlighters = new Map<string, Promise<Highlighter>>();
 
-export async function _highlight(code: string, options: HighlightOptions) {
+export async function highlightHast(
+  code: string,
+  options: HighlightOptions,
+): Promise<Root> {
   const {
     lang: initialLang,
     fallbackLanguage,
@@ -155,5 +158,5 @@ export async function highlight(
   code: string,
   options: HighlightOptions,
 ): Promise<ReactNode> {
-  return _renderHighlight(await _highlight(code, options), options);
+  return _renderHighlight(await highlightHast(code, options), options);
 }

packages/typescript/src/lib/base.ts

@@ -14,6 +14,7 @@ import {
 } from '@/lib/type-table';
 import { createCache } from '@/lib/cache';
 import path from 'node:path';
+import { getSimpleForm } from '@/lib/get-simple-form';
 
 export interface GeneratedDoc {
   name: string;
@@ -25,6 +26,8 @@ export interface DocEntry {
   name: string;
   description: string;
   type: string;
+  simplifiedType: string;
+
   tags: Record<string, string>;
   required: boolean;
   deprecated: boolean;
@@ -190,40 +193,24 @@ function getDocEntry(
   context: EntryContext,
 ): DocEntry | undefined {
   const { transform, program } = context;
-
   if (context.type.isClass() && prop.getName().startsWith('#')) {
     return;
   }
 
   const subType = program
     .getTypeChecker()
     .getTypeOfSymbolAtLocation(prop, context.declaration);
+  const isOptional = prop.isOptional();
   const tags = Object.fromEntries(
     prop
       .getJsDocTags()
       .map((tag) => [tag.getName(), ts.displayPartsToString(tag.getText())]),
   );
 
-  let typeName = subType.getText(
-    undefined,
-    ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope,
-  );
-
-  if (
-    subType.getAliasSymbol() &&
-    subType.getAliasTypeArguments().length === 0
-  ) {
-    typeName = subType.getAliasSymbol()?.getEscapedName() ?? typeName;
-  }
-
-  if (prop.isOptional() && typeName.endsWith('| undefined')) {
-    typeName = typeName
-      .slice(0, typeName.length - '| undefined'.length)
-      .trimEnd();
-  }
+  let type = getFullType(subType, isOptional);
 
   if ('remarks' in tags) {
-    typeName = /^`(?<name>.+)`/.exec(tags.remarks)?.[1] ?? typeName;
+    type = /^`(?<name>.+)`/.exec(tags.remarks)?.[1] ?? type;
   }
 
   const entry: DocEntry = {
@@ -234,8 +221,9 @@ function getDocEntry(
       ),
     ),
     tags,
-    type: typeName,
-    required: !prop.isOptional(),
+    type,
+    simplifiedType: getSimpleForm(subType, program.getTypeChecker()),
+    required: !isOptional,
     deprecated: prop
       .getJsDocTags()
       .some((tag) => tag.getName() === 'deprecated'),
@@ -245,3 +233,30 @@ function getDocEntry(
 
   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,
+    );
+
+  if (type.getAliasSymbol() && type.getAliasTypeArguments().length === 0) {
+    typeName = type.getAliasSymbol()?.getEscapedName() ?? typeName;
+  }
+
+  return typeName;
+}

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

@@ -0,0 +1,56 @@
+import * as ts from 'ts-morph';
+
+function simplifyType(type: ts.Type, checker: ts.TypeChecker): string {
+  // Handle union types
+  if (type.isUnion()) {
+    const types: string[] = [];
+    for (const t of type.getUnionTypes()) {
+      const str = simplifyType(t, checker);
+      if (str !== 'never') types.unshift(str);
+    }
+
+    return types.length > 0 ? types.join(' | ') : 'never';
+  }
+
+  // Handle intersection types
+  if (type.isIntersection()) {
+    const types: string[] = [];
+    for (const t of type.getIntersectionTypes()) {
+      types.unshift(simplifyType(t, checker));
+    }
+
+    return types.join(' & ');
+  }
+
+  if (type.isTuple()) {
+    const elements = type
+      .getTupleElements()
+      .map((t) => simplifyType(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';
+  }
+
+  if (type.getCallSignatures().length > 0) {
+    return 'function';
+  }
+
+  if (type.isClassOrInterface() || type.isObject()) {
+    return 'object';
+  }
+
+  return type.getText();
+}
+
+export function getSimpleForm(type: ts.Type, checker: ts.TypeChecker): string {
+  return simplifyType(type, checker);
+}

packages/typescript/src/lib/remark-auto-type-table.tsx

@@ -1,4 +1,5 @@
 import type { Root } from 'mdast';
+import type { Nodes } from 'hast';
 import type { Transformer } from 'unified';
 import type {
   ExpressionStatement,
@@ -7,7 +8,7 @@ import type {
   Property,
 } from 'estree';
 import { createGenerator, type DocEntry, type Generator } from '@/lib/base';
-import { renderMarkdownToHast } from '@/markdown';
+import { renderMarkdownToHast, renderTypeToHast } from '@/markdown';
 import { valueToEstree } from 'estree-util-value-to-estree';
 import { visit } from 'unist-util-visit';
 import {
@@ -19,16 +20,18 @@ import { dirname } from 'node:path';
 
 async function mapProperty(
   entry: DocEntry,
-  renderMarkdown: typeof renderMarkdownToHast,
+  {
+    renderMarkdown = renderMarkdownToHast,
+    renderType = renderTypeToHast,
+  }: RemarkAutoTypeTableOptions,
 ): Promise<Property> {
   const value = valueToEstree({
-    type: entry.type,
     default: entry.tags.default || entry.tags.defaultValue,
     required: entry.required,
   }) as ObjectExpression;
 
-  if (entry.description) {
-    const hast = toEstree(await renderMarkdown(entry.description), {
+  function addJsxProperty(key: string, hast: Nodes) {
+    const estree = toEstree(hast, {
       elementAttributeNameCase: 'react',
     }).body[0] as ExpressionStatement;
 
@@ -39,13 +42,20 @@ async function mapProperty(
       computed: false,
       key: {
         type: 'Identifier',
-        name: 'description',
+        name: key,
       },
       kind: 'init',
-      value: hast.expression,
+      value: estree.expression,
     });
   }
 
+  addJsxProperty('type', await renderType(entry.simplifiedType));
+  addJsxProperty('typeDescription', await renderType(entry.type));
+
+  if (entry.description) {
+    addJsxProperty('description', await renderMarkdown(entry.description));
+  }
+
   return {
     type: 'Property',
     method: false,
@@ -72,6 +82,7 @@ export interface RemarkAutoTypeTableOptions {
   outputName?: string;
 
   renderMarkdown?: typeof renderMarkdownToHast;
+  renderType?: typeof renderTypeToHast;
 
   /**
    * Customise type table generation
@@ -91,18 +102,20 @@ export interface RemarkAutoTypeTableOptions {
  *
  * MDX is required to use this plugin.
  */
-export function remarkAutoTypeTable({
-  name = 'auto-type-table',
-  outputName = 'TypeTable',
-  renderMarkdown = renderMarkdownToHast,
-  options = {},
-  remarkStringify = true,
-  generator = createGenerator(),
-}: RemarkAutoTypeTableOptions = {}): Transformer<Root, Root> {
+export function remarkAutoTypeTable(
+  config: RemarkAutoTypeTableOptions = {},
+): Transformer<Root, Root> {
+  const {
+    name = 'auto-type-table',
+    outputName = 'TypeTable',
+    options: generateOptions = {},
+    remarkStringify = true,
+    generator = createGenerator(),
+  } = config;
+
   return async (tree, file) => {
     const queue: Promise<void>[] = [];
-    let basePath = options?.basePath;
-    if (!basePath && file.path) basePath = dirname(file.path);
+    const defaultBasePath = file.path ? dirname(file.path) : undefined;
 
     visit(tree, 'mdxJsxFlowElement', (node) => {
       if (node.name !== name) return;
@@ -121,14 +134,14 @@ export function remarkAutoTypeTable({
         const output = await generator.generateTypeTable(
           props as BaseTypeTableProps,
           {
-            ...options,
-            basePath,
+            ...generateOptions,
+            basePath: generateOptions.basePath ?? defaultBasePath,
           },
         );
 
         const rendered = output.map(async (doc) => {
           const properties = await Promise.all(
-            doc.entries.map((entry) => mapProperty(entry, renderMarkdown)),
+            doc.entries.map((entry) => mapProperty(entry, config)),
           );
 
           return {