feat(twoslash): support custom renderer

Author: antfu

packages/shikiji-twoslash/README.md

@@ -31,6 +31,38 @@ const html = await codeToHtml(code, {
 
 Same as `shiki-twoslash`, the output is unstyled. You need to add some extra CSS to make them look good.
 
+## Renderers
+
+Thanks to the flexibility of [`hast`](https://github.com/syntax-tree/hast), this transformer allows customizing how each piece of information is rendered in the output HTML with ASTs.
+
+We provide two renderers built-in, while you can also create your own:
+
+### `rendererClassic`
+
+[Source code](./src/renderer-classic.ts)
+
+This is the default renderer that aligns with the output of [`shiki-twoslash`](https://shikijs.github.io/twoslash/).
+
+You might need to reference `shiki-twoslash`'s CSS to make them look good. [Here](./style-shiki-twoslash.css) we also copied the CSS from `shiki-twoslash` but it might need some cleanup.
+
+### `rendererRich`
+
+[Source code](./src/renderer-rich.ts)
+
+This renderer provides a more explicit class name that is always prefixed with `twoslash-` for better scoping. In addition, it runs syntax highlighting on the hover information as well.
+
+```ts
+import { rendererRich, transformerTwoSlash } from 'shikiji-twoslash'
+
+transformerTwoSlash({
+  renderer: rendererRich // <--
+})
+```
+
+Here is an example with the [`style-rich.css`](./style-rich.css):
+
+![](https://github.com/antfu/shikiji/assets/11247099/41f75799-e652-4331-ab75-39dbe8772c81)
+
 ## Integrations
 
 ### VitePress

packages/shikiji-twoslash/package.json

@@ -22,6 +22,8 @@
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
     },
+    "./style-rich.css": "./style-rich.css",
+    "./style-shiki-twoslash.css": "./style-shiki-twoslash.css",
     "./*": "./dist/*"
   },
   "main": "./dist/index.mjs",
@@ -36,6 +38,7 @@
     }
   },
   "files": [
+    "*.css",
     "dist"
   ],
   "scripts": {

packages/shikiji-twoslash/src/index.ts

@@ -7,6 +7,7 @@ import type { TransformerTwoSlashOptions } from './types'
 
 export * from './types'
 export * from './renderer-classic'
+export * from './renderer-rich'
 
 export function transformerTwoSlash(options: TransformerTwoSlashOptions = {}): ShikijiTransformer {
   const {
@@ -20,6 +21,7 @@ export function transformerTwoSlash(options: TransformerTwoSlashOptions = {}): S
       yml: 'yaml',
     },
     renderer = rendererClassic,
+    throws = true,
   } = options
   const filter = options.filter || (lang => langs.includes(lang))
   return {
@@ -52,72 +54,77 @@ export function transformerTwoSlash(options: TransformerTwoSlashOptions = {}): S
         else {
           const lineEl = this.lines[line]
           index = codeEl.children.indexOf(lineEl)
-          if (index === -1)
-            return false
+          if (index === -1) {
+            if (throws)
+              throw new Error(`[shikiji-twoslash] Cannot find line ${line} in code element`)
+            return
+          }
         }
 
         // If there is a newline after this line, remove it because we have the error element take place.
         const nodeAfter = codeEl.children[index + 1]
         if (nodeAfter && nodeAfter.type === 'text' && nodeAfter.value === '\n')
           codeEl.children.splice(index + 1, 1)
         codeEl.children.splice(index + 1, 0, ...nodes)
-        return true
       }
 
-      for (const info of twoslash.staticQuickInfos) {
-        const token = locateTextToken(this, info.line, info.character)
-        if (!token || token.type !== 'text')
-          continue
+      const locateTextToken = (
+        line: number,
+        character: number,
+      ) => {
+        const lineEl = this.lines[line]
+        if (!lineEl) {
+          if (throws)
+            throw new Error(`[shikiji-twoslash] Cannot find line ${line} in code element`)
+        }
+        const textNodes = lineEl.children.flatMap(i => i.type === 'element' ? i.children || [] : []) as (Text | Element)[]
+        let index = 0
+        for (const token of textNodes) {
+          if ('value' in token && typeof token.value === 'string')
+            index += token.value.length
 
-        const clone = { ...token }
-        Object.assign(token, renderer.nodeStaticInfo(info, clone))
+          if (index > character)
+            return token
+        }
+        if (throws)
+          throw new Error(`[shikiji-twoslash] Cannot find token at L${line}:${character}`)
       }
 
       for (const error of twoslash.errors) {
         if (error.line == null || error.character == null)
           return
-        const token = locateTextToken(this, error.line, error.character)
+        const token = locateTextToken(error.line, error.character)
         if (!token)
           continue
 
         const clone = { ...token }
-        Object.assign(token, renderer.nodeError(error, clone))
+        Object.assign(token, renderer.nodeError.call(this, error, clone))
 
-        insertAfterLine(error.line, renderer.lineError(error))
+        insertAfterLine(error.line, renderer.lineError.call(this, error))
+      }
+
+      for (const info of twoslash.staticQuickInfos) {
+        const token = locateTextToken(info.line, info.character)
+        if (!token || token.type !== 'text')
+          continue
+
+        const clone = { ...token }
+        Object.assign(token, renderer.nodeStaticInfo.call(this, info, clone))
       }
 
       for (const query of twoslash.queries) {
         insertAfterLine(
           query.line,
           query.kind === 'completions'
-            ? renderer.lineCompletions(query)
+            ? renderer.lineCompletions.call(this, query)
             : query.kind === 'query'
-              ? renderer.lineQuery(query, locateTextToken(this, query.line, query.offset))
+              ? renderer.lineQuery.call(this, query, locateTextToken(query.line - 1, query.offset))
               : [],
         )
       }
 
       for (const tag of twoslash.tags)
-        insertAfterLine(tag.line, renderer.lineCustomTag(tag))
+        insertAfterLine(tag.line, renderer.lineCustomTag.call(this, tag))
     },
   }
 }
-
-function locateTextToken(
-  context: ShikijiTransformerContext,
-  line: number,
-  character: number,
-) {
-  const lineEl = context.lines[line]
-  if (!lineEl)
-    return
-  const textNodes = lineEl.children.flatMap(i => i.type === 'element' ? i.children || [] : []) as (Text | Element)[]
-  let index = 0
-  for (const token of textNodes) {
-    if ('value' in token && typeof token.value === 'string')
-      index += token.value.length
-
-    if (index > character)
-      return token
-  }
-}

packages/shikiji-twoslash/src/renderer-rich.ts

@@ -0,0 +1,194 @@
+import type { Element, ElementContent } from 'hast'
+import type { TwoSlashRenderers } from './types'
+
+/**
+ * An alternative renderer that providers better prefixed class names,
+ * with syntax highlight for the info text.
+ */
+export const rendererRich: TwoSlashRenderers = {
+  nodeStaticInfo(info, node) {
+    let themed: ElementContent
+
+    try {
+      themed = (this.codeToHast(info.text, {
+        ...this.options,
+        transformers: [],
+        transforms: undefined,
+      }).children[0] as Element).children[0]
+    }
+    catch (e) {
+      themed = {
+        type: 'text',
+        value: info.text,
+      }
+    }
+
+    return {
+      type: 'element',
+      tagName: 'span',
+      properties: {
+        class: 'twoslash-hover',
+      },
+      children: [
+        node,
+        {
+          type: 'element',
+          tagName: 'span',
+          properties: {
+            class: 'twoslash-hover-info',
+          },
+          children: [
+            themed,
+          ],
+        },
+      ],
+    }
+  },
+
+  nodeError(_, node) {
+    return {
+      type: 'element',
+      tagName: 'span',
+      properties: {
+        class: 'twoslash-error',
+      },
+      children: [node],
+    }
+  },
+
+  lineError(error) {
+    return [
+      {
+        type: 'element',
+        tagName: 'div',
+        properties: {
+          class: 'twoslash-meta-line twoslash-error-line',
+        },
+        children: [
+          {
+            type: 'text',
+            value: error.renderedMessage,
+          },
+        ],
+      },
+    ]
+  },
+
+  lineCompletions(query) {
+    return [
+      {
+        type: 'element',
+        tagName: 'div',
+        properties: { class: 'twoslash-meta-line' },
+        children: [
+          { type: 'text', value: ' '.repeat(query.offset) },
+          {
+            type: 'element',
+            tagName: 'span',
+            properties: { class: 'twoslash-completions' },
+            children: [{
+              type: 'element',
+              tagName: 'ul',
+              properties: { },
+              children: query.completions!
+                .filter(i => i.name.startsWith(query.completionsPrefix || '____'))
+                .map(i => ({
+                  type: 'element',
+                  tagName: 'li',
+                  properties: {
+                    class: i.kindModifiers?.split(',').includes('deprecated')
+                      ? 'deprecated'
+                      : undefined,
+                  },
+                  children: [{
+                    type: 'element',
+                    tagName: 'span',
+                    properties: {},
+                    children: [
+                      {
+                        type: 'element',
+                        tagName: 'span',
+                        properties: { class: 'twoslash-completions-matched' },
+                        children: [
+                          {
+                            type: 'text',
+                            value: query.completionsPrefix || '',
+                          },
+                        ],
+                      },
+                      {
+                        type: 'text',
+                        value: i.name.slice(query.completionsPrefix?.length || 0),
+                      },
+                    ],
+                  }],
+                })),
+            }],
+          },
+        ],
+      },
+    ]
+  },
+
+  lineQuery(query, targetNode) {
+    const targetText = targetNode?.type === 'text' ? targetNode.value : ''
+    const offset = Math.max(0, (query.offset || 0) - Math.round(targetText.length / 2) - 1)
+
+    let themed: ElementContent
+
+    try {
+      themed = (this.codeToHast(query.text || '', {
+        ...this.options,
+        transformers: [],
+        transforms: undefined,
+      }).children[0] as Element).children[0]
+    }
+    catch (e) {
+      themed = {
+        type: 'text',
+        value: query.text || '',
+      }
+    }
+
+    return [
+      {
+        type: 'element',
+        tagName: 'div',
+        properties: { class: 'twoslash-meta-line' },
+        children: [
+          { type: 'text', value: ' '.repeat(offset) },
+          {
+            type: 'element',
+            tagName: 'span',
+            properties: { class: 'twoslash-popover' },
+            children: [
+              {
+                type: 'element',
+                tagName: 'div',
+                properties: { class: 'twoslash-popover-arrow' },
+                children: [],
+              },
+              themed,
+            ],
+          },
+        ],
+      },
+    ]
+  },
+
+  lineCustomTag(tag) {
+    return [
+      {
+        type: 'element',
+        tagName: 'div',
+        properties: { class: `twoslash-meta-line twoslash-tag-${tag.name}` },
+        children: [
+          {
+            type: 'text',
+            value: tag.annotation || '',
+          },
+        ],
+      },
+    ]
+  },
+}