feat(vitepress-twoslash): support rendering jsdoc tags

Author: antfu

package.json

@@ -62,7 +62,7 @@
     "vitepress-plugin-twoslash": "workspace:*",
     "vitest": "^1.2.0",
     "vue-tsc": "^1.8.27",
-    "wrangler": "^3.22.4"
+    "wrangler": "^3.22.5"
   },
   "resolutions": {
     "@types/hast": "^3.0.3",

packages/shikiji-twoslash/package.json

@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "shikiji-core": "workspace:*",
-    "twoslash": "^0.0.8"
+    "twoslash": "^0.0.9"
   },
   "devDependencies": {
     "@iconify-json/carbon": "^1.1.27",

packages/vitepress-plugin-twoslash/package.json

@@ -59,7 +59,7 @@
     "mdast-util-to-hast": "^13.1.0",
     "shikiji": "workspace:*",
     "shikiji-twoslash": "workspace:*",
-    "twoslash-vue": "^0.0.8",
+    "twoslash-vue": "^0.0.9",
     "vue": "^3.4.14"
   }
 }

packages/vitepress-plugin-twoslash/src/renderer-floating-vue.ts

@@ -1,6 +1,7 @@
 import { defaultCompletionIcons, defaultHoverInfoProcessor, rendererRich } from 'shikiji-twoslash'
 import type { RendererRichOptions, TwoslashRenderer } from 'shikiji-twoslash'
-import type { Element, Text } from 'hast'
+import type { NodeHover, NodeQuery } from 'twoslash'
+import type { Element, ElementContent, Text } from 'hast'
 import type { ShikijiTransformerContext } from 'shikiji'
 import { gfmFromMarkdown } from 'mdast-util-gfm'
 import { fromMarkdown } from 'mdast-util-from-markdown'
@@ -21,10 +22,9 @@ export function rendererFloatingVue(options: VitePressPluginTwoslashOptions & Re
     ...options,
   })
 
-  function createFloatingVueWarpper(this: ShikijiTransformerContext, text: string, docs: string | undefined, node: Element | Text, presisted = false): Element | undefined {
-    const content = processHoverInfo(text)
-
-    if ((!content || content === 'any'))
+  function createFloatingVueWarpper(this: ShikijiTransformerContext, info: NodeHover | NodeQuery, node: Element | Text, presisted = false): Element | undefined {
+    const content = processHoverInfo(info.text)
+    if (!content || content === 'any')
       return undefined
 
     const themedContent = (this.codeToHast(
@@ -41,12 +41,11 @@ export function rendererFloatingVue(options: VitePressPluginTwoslashOptions & Re
       addClassToHast(node, 'twoslash-popup-type')
     })
 
-    if (docs) {
-      docs = processHoverDocs(docs) ?? docs
-      const mdast = fromMarkdown(docs, {
+    const markdownToHast = (md: string): ElementContent[] => {
+      const mdast = fromMarkdown(md, {
         mdastExtensions: [gfmFromMarkdown()],
       })
-      const hast = toHast(mdast, {
+      return (toHast(mdast, {
         handlers: {
           code: (state, node) => {
             const lang = node.lang || ''
@@ -63,14 +62,71 @@ export function rendererFloatingVue(options: VitePressPluginTwoslashOptions & Re
             return defaultHandlers.code(state, node)
           },
         },
-      })
+      }) as Element).children
+    }
+
+    const markdownInlineToHast = (md: string): ElementContent[] => {
+      const children = markdownToHast(md)
+      if (children.length === 1 && children[0].type === 'element' && children[0].tagName === 'p')
+        return children[0].children
+      return children
+    }
+
+    if (info.docs) {
+      const docs = processHoverDocs(info.docs) ?? info.docs
+      const children = markdownToHast(docs)
+
       themedContent.push({
         type: 'element',
         tagName: 'div',
         properties: {
           class: 'twoslash-popup-jsdoc vp-doc',
         },
-        children: (hast as any).children,
+        children,
+      })
+    }
+
+    if (info.tags?.length) {
+      themedContent.push({
+        type: 'element',
+        tagName: 'div',
+        properties: {
+          class: 'twoslash-popup-jsdoc twoslash-popup-jsdoc-tags vp-doc',
+        },
+        children: info.tags.map(tag => (<Element>{
+          type: 'element',
+          tagName: 'span',
+          properties: {
+            class: `twoslash-popup-jsdoc-tag`,
+          },
+          children: [
+            {
+              type: 'element',
+              tagName: 'span',
+              properties: {
+                class: 'twoslash-popup-jsdoc-tag-name',
+              },
+              children: [
+                {
+                  type: 'text',
+                  value: `@${tag[0]}`,
+                },
+              ],
+            },
+            ...tag[1]
+              ? [
+                    <Element>{
+                      type: 'element',
+                      tagName: 'span',
+                      properties: {
+                        class: 'twoslash-popup-jsdoc-tag-value',
+                      },
+                      children: markdownInlineToHast(tag[1]),
+                    },
+                ]
+              : [],
+          ],
+        })),
       })
     }
 
@@ -129,12 +185,12 @@ export function rendererFloatingVue(options: VitePressPluginTwoslashOptions & Re
   return {
     ...rich,
     nodeStaticInfo(info, node) {
-      return createFloatingVueWarpper.call(this, info.text, info.docs, node) || {}
+      return createFloatingVueWarpper.call(this, info, node) || {}
     },
     nodeQuery(query, node) {
       if (!query.text)
         return {}
-      return createFloatingVueWarpper.call(this, query.text, query.docs, node, true) || {}
+      return createFloatingVueWarpper.call(this, query, node, true) || {}
     },
     nodeCompletion(query, node) {
       if (node.type !== 'text')

packages/vitepress-plugin-twoslash/src/style.css

@@ -78,6 +78,21 @@
   overflow-x: auto;
 }
 
+.floating-vue-twoslash .twoslash-popup-jsdoc-tags {
+  display: flex;
+  flex-direction: column;
+  padding: 8px 12px !important;
+}
+
+.floating-vue-twoslash
+  .twoslash-popup-jsdoc-tags
+  .twoslash-popup-jsdoc-tag-name {
+  font-family: var(--vp-font-family-mono);
+  color: var(--vp-c-brand-1);
+  margin-right: 0.5em;
+  font-size: 0.9em;
+}
+
 .twoslash-completion-cursor {
   height: 1.2em;
   width: 2px;