@airalogy/aimd-renderer 2.5.0 → 2.6.0

package/src/vue/vue-renderer.ts

@@ -1,6 +1,13 @@
 import type { Element, Root as HastRoot, Text as HastText, RootContent } from "hast"
 import type { Component, VNode, VNodeChild } from "vue"
 import type { AimdNode, AimdQuizNode, AimdStepNode, RenderContext } from "@airalogy/aimd-core/types"
+import {
+  formatAimdExampleValue,
+  getAimdFieldDescription,
+  getAimdFieldDisplayLabel,
+  getAimdFieldExamples,
+  getAimdFieldTitle,
+} from "@airalogy/aimd-core/utils"
 import { Fragment, h } from "vue"
 import type { AimdRendererI18nOptions, AimdRendererLocale, AimdRendererMessages } from "../locales"
 import { resolveQuizPreviewOptions, type ResolvedQuizPreviewOptions } from "../common/quiz-preview"
@@ -152,6 +159,74 @@ function buildScaleBandChildren(quizNode: AimdQuizNode): VNodeChild[] {
   ]
 }
 
+interface FieldMetadataHelp {
+  tooltip: string
+  description?: string
+  examples: string[]
+}
+
+function getFieldHelpText(definition: { kwargs?: Record<string, unknown> } | undefined): FieldMetadataHelp {
+  const description = getAimdFieldDescription(definition)
+  const examples = getAimdFieldExamples(definition)
+    .map(formatAimdExampleValue)
+    .map(example => example.trim())
+    .filter(Boolean)
+  const exampleText = examples.length > 0 ? `e.g. ${examples.join(", ")}` : undefined
+  const tooltipLines = [description, exampleText].filter((value): value is string => Boolean(value))
+
+  return {
+    tooltip: tooltipLines.join("\n"),
+    description,
+    examples,
+  }
+}
+
+function renderFieldMetadataPopover(help: FieldMetadataHelp): VNode | null {
+  if (!help.description && help.examples.length === 0) {
+    return null
+  }
+  const children: VNode[] = []
+  if (help.description) {
+    children.push(h("span", {
+      class: "aimd-field__metadata-popover-line",
+    }, help.description))
+  }
+  if (help.examples.length > 0) {
+    children.push(h("span", { class: "aimd-field__metadata-examples" }, [
+      h("span", { class: "aimd-field__metadata-examples-label" }, "e.g."),
+      ...help.examples.map((example, index) => h("span", {
+        key: `${index}-${example}`,
+        class: "aimd-field__metadata-example",
+      }, example)),
+    ]))
+  }
+  return h("span", {
+    class: "aimd-field__metadata-popover",
+    role: "tooltip",
+  }, children)
+}
+
+function renderFieldName(id: string, definition: { kwargs?: Record<string, unknown> } | undefined): VNode {
+  const displayTitle = getAimdFieldDisplayLabel(id, definition)
+  const hasCustomTitle = getAimdFieldTitle(definition) !== undefined && displayTitle !== id
+  const help = getFieldHelpText(definition)
+  const hasHelp = Boolean(help.description) || help.examples.length > 0
+
+  return h("span", {
+    class: [
+      "aimd-field__name",
+      (hasCustomTitle || hasHelp) ? "aimd-field__name--with-metadata" : undefined,
+      hasHelp ? "aimd-field__metadata-host" : undefined,
+    ],
+    tabindex: hasHelp ? 0 : undefined,
+    "aria-label": help.tooltip || undefined,
+  }, [
+    h("span", { class: "aimd-field__title" }, displayTitle),
+    hasCustomTitle ? h("span", { class: "aimd-field__key" }, id) : null,
+    renderFieldMetadataPopover(help),
+  ])
+}
+
 function isStepBodyVNode(node: unknown): node is VNode {
   if (!node || typeof node !== "object") {
     return false
@@ -209,11 +284,11 @@ const defaultAimdRenderers: Record<string, AimdComponentRenderer> = {
         "data-aimd-type": "var",
         "data-aimd-id": id,
         "data-aimd-scope": scope,
-      }, [
-        h("span", { class: "aimd-field__scope" }, getAimdRendererScopeLabel(scope, ctx.messages)),
-        h("span", { class: "aimd-field__name" }, id),
-        definition?.type ? h("span", { class: "aimd-field__type" }, `: ${definition.type}`) : null,
-      ])
+	      }, [
+	        h("span", { class: "aimd-field__scope" }, getAimdRendererScopeLabel(scope, ctx.messages)),
+	        renderFieldName(id, definition),
+	        definition?.type ? h("span", { class: "aimd-field__type" }, `: ${definition.type}`) : null,
+	      ])
     }
 
     // Edit mode - render as editable field with value display
@@ -236,24 +311,28 @@ const defaultAimdRenderers: Record<string, AimdComponentRenderer> = {
   },
 
   var_table: (node, ctx) => {
-    const { id } = node
-    const columns = "columns" in node ? node.columns : []
+	    const { id } = node
+	    const columns = "columns" in node ? node.columns : []
+	    const definition = "definition" in node ? node.definition : undefined
+	    const subvarDefs = definition?.subvars
 
-    if (ctx.mode === "preview") {
+	    if (ctx.mode === "preview") {
       // Preview mode: render tag with table preview inside
       const children: VNodeChild[] = [
-        h("div", { class: "aimd-field__header" }, [
-          h("span", { class: "aimd-field__scope" }, ctx.messages.scope.table),
-          h("span", { class: "aimd-field__name" }, id),
-        ]),
-      ]
+	        h("div", { class: "aimd-field__header" }, [
+	          h("span", { class: "aimd-field__scope" }, ctx.messages.scope.table),
+	          renderFieldName(id, definition),
+	        ]),
+	      ]
       // Add table preview inside the container
       if (columns && columns.length > 0) {
         children.push(
           h("table", { class: "aimd-field__table-preview" }, [
-            h("thead", [
-              h("tr", columns.map(col => h("th", col))),
-            ]),
+	            h("thead", [
+	              h("tr", columns.map(col => h("th", {
+	                "data-column-id": col,
+	              }, [renderFieldName(col, subvarDefs?.[col])]))),
+	            ]),
             h("tbody", [
               h("tr", columns.map(() => h("td", "..."))),
             ]),
@@ -1285,9 +1364,167 @@ export function createStepCardRenderer(
  */
 export interface ShikiHighlighter {
   codeToHtml: (code: string, options: { lang: string, theme: string }) => string
+  codeToTokensBase?: (code: string, options: { lang: string, theme: string }) => Array<Array<{ content: string, color?: string, bgColor?: string, fontStyle?: number, htmlStyle?: string | Record<string, string> }>>
   codeToTokensWithThemes?: (code: string, options: { lang: string, themes: Record<string, string> }) => Array<Array<{ content: string, variants: Record<string, { color: string }> }>>
 }
 
+export interface CodeBlockRendererOptions {
+  theme?: string
+  lineNumbers?: boolean
+  wrap?: boolean
+  className?: string
+}
+
+export interface LoadShikiHighlighterOptions {
+  themes?: string[]
+  langs?: string[]
+}
+
+type CodeBlockToken = {
+  content: string
+  color?: string
+  bgColor?: string
+  fontStyle?: number
+  htmlStyle?: string | Record<string, string>
+}
+
+const DEFAULT_CODE_BLOCK_THEME = "github-light"
+const DEFAULT_CODE_HIGHLIGHTER_THEMES = [DEFAULT_CODE_BLOCK_THEME]
+const DEFAULT_CODE_HIGHLIGHTER_LANGS = [
+  "bash",
+  "css",
+  "html",
+  "javascript",
+  "json",
+  "jsonc",
+  "markdown",
+  "python",
+  "shellscript",
+  "sql",
+  "toml",
+  "typescript",
+  "xml",
+  "yaml",
+]
+let defaultCodeHighlighterPromise: Promise<ShikiHighlighter> | null = null
+
+export async function loadShikiHighlighter(
+  options: LoadShikiHighlighterOptions = {},
+): Promise<ShikiHighlighter> {
+  const hasCustomOptions = Boolean(options.themes || options.langs)
+  const create = async () => {
+    const { createHighlighter } = await import("shiki")
+    return createHighlighter({
+      themes: (options.themes ?? DEFAULT_CODE_HIGHLIGHTER_THEMES) as never,
+      langs: (options.langs ?? DEFAULT_CODE_HIGHLIGHTER_LANGS) as never,
+    }) as Promise<unknown> as Promise<ShikiHighlighter>
+  }
+
+  if (hasCustomOptions) {
+    return create()
+  }
+
+  defaultCodeHighlighterPromise ??= create()
+  return defaultCodeHighlighterPromise
+}
+
+function resolveCodeBlockRendererOptions(
+  optionsOrTheme: string | CodeBlockRendererOptions | undefined,
+): Required<CodeBlockRendererOptions> {
+  if (typeof optionsOrTheme === "string") {
+    return {
+      theme: optionsOrTheme,
+      lineNumbers: false,
+      wrap: false,
+      className: "",
+    }
+  }
+
+  return {
+    theme: optionsOrTheme?.theme ?? DEFAULT_CODE_BLOCK_THEME,
+    lineNumbers: optionsOrTheme?.lineNumbers ?? false,
+    wrap: optionsOrTheme?.wrap ?? false,
+    className: optionsOrTheme?.className ?? "",
+  }
+}
+
+function getCodeLanguage(codeNode: Element): string {
+  const className = codeNode.properties?.className
+  if (Array.isArray(className)) {
+    const langClass = className.find(c => typeof c === "string" && c.startsWith("language-"))
+    return typeof langClass === "string" ? langClass.replace("language-", "") : "text"
+  }
+
+  return typeof className === "string" && className.startsWith("language-")
+    ? className.replace("language-", "")
+    : "text"
+}
+
+function getCodeContent(codeNode: Element): string {
+  return codeNode.children
+    .map(child => (child.type === "text" ? child.value : ""))
+    .join("")
+}
+
+function normalizeCodeContent(code: string): string {
+  return code.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\n$/, "")
+}
+
+function splitCodeLines(code: string): CodeBlockToken[][] {
+  const lines = code.split(/\r\n|\r|\n/)
+  return (lines.length ? lines : [""]).map(line => [{ content: line }])
+}
+
+function getLineIndentColumns(tokens: CodeBlockToken[]): number {
+  const line = tokens.map(token => token.content).join("")
+  let columns = 0
+  for (const char of line) {
+    if (char === " ") {
+      columns += 1
+    }
+    else if (char === "\t") {
+      columns += 2
+    }
+    else {
+      break
+    }
+  }
+  return Math.min(columns, 24)
+}
+
+function hasCodeTokenContent(tokens: CodeBlockToken[]): boolean {
+  return tokens.some(token => token.content.length > 0)
+}
+
+function getCodeTokenStyle(token: CodeBlockToken): string | Record<string, string> | undefined {
+  if (token.htmlStyle) {
+    return token.htmlStyle
+  }
+
+  const style: Record<string, string> = {}
+  if (token.color) {
+    style.color = token.color
+  }
+  if (token.bgColor) {
+    style.backgroundColor = token.bgColor
+  }
+  if (typeof token.fontStyle === "number") {
+    if (token.fontStyle & 1) style.fontStyle = "italic"
+    if (token.fontStyle & 2) style.fontWeight = "700"
+    if (token.fontStyle & 4) style.textDecoration = "underline"
+  }
+
+  return Object.keys(style).length > 0 ? style : undefined
+}
+
+function renderLegacyPlainCodeBlock(lang: string, codeContent: string): VNode {
+  return h("pre", {
+    class: `language-${lang}`,
+  }, h("code", {
+    class: `language-${lang}`,
+  }, codeContent))
+}
+
 /**
  * Create code block element renderer with Shiki support
  * @param highlighter - Shiki highlighter instance (can be reactive ref)
@@ -1295,8 +1532,11 @@ export interface ShikiHighlighter {
  */
 export function createCodeBlockRenderer(
   highlighter: ShikiHighlighter | null | (() => ShikiHighlighter | null),
-  defaultTheme = "github-dark",
+  optionsOrTheme: string | CodeBlockRendererOptions = DEFAULT_CODE_BLOCK_THEME,
 ): ElementRenderer {
+  const options = resolveCodeBlockRendererOptions(optionsOrTheme)
+  const useLegacyHtmlOutput = typeof optionsOrTheme === "string"
+
   return (node, children, ctx) => {
     // Find code element inside pre
     const codeNode = node.children.find(
@@ -1307,39 +1547,38 @@ export function createCodeBlockRenderer(
       return h("pre", {}, children)
     }
 
-    // Get language from class
-    const className = codeNode.properties?.className
-    let lang = "text"
-    if (Array.isArray(className)) {
-      const langClass = className.find(c => typeof c === "string" && c.startsWith("language-"))
-      if (langClass && typeof langClass === "string") {
-        lang = langClass.replace("language-", "")
+    const lang = getCodeLanguage(codeNode)
+    const codeContent = normalizeCodeContent(getCodeContent(codeNode))
+    const hl = typeof highlighter === "function" ? highlighter() : highlighter
+    let tokenLines = splitCodeLines(codeContent)
+
+    if (useLegacyHtmlOutput) {
+      if (hl?.codeToHtml) {
+        try {
+          const highlightedHtml = hl.codeToHtml(codeContent, {
+            lang,
+            theme: options.theme,
+          })
+
+          return h("div", {
+            "class": "shiki-code-block",
+            "data-lang": lang,
+            "innerHTML": highlightedHtml,
+          })
+        }
+        catch (error) {
+          console.error("Failed to highlight code:", error)
+        }
       }
-    }
-    else if (typeof className === "string" && className.startsWith("language-")) {
-      lang = className.replace("language-", "")
-    }
-
-    // Get code content
-    const codeContent = codeNode.children
-      .map(child => (child.type === "text" ? child.value : ""))
-      .join("")
 
-    // Get highlighter
-    const hl = typeof highlighter === "function" ? highlighter() : highlighter
+      return renderLegacyPlainCodeBlock(lang, codeContent)
+    }
 
-    // Use Shiki if available
-    if (hl) {
+    if (hl?.codeToTokensBase) {
       try {
-        const highlightedHtml = hl.codeToHtml(codeContent, {
+        tokenLines = hl.codeToTokensBase(codeContent, {
           lang,
-          theme: defaultTheme,
-        })
-
-        return h("div", {
-          "class": "shiki-code-block",
-          "data-lang": lang,
-          "innerHTML": highlightedHtml,
+          theme: options.theme,
         })
       }
       catch (error) {
@@ -1347,9 +1586,40 @@ export function createCodeBlockRenderer(
       }
     }
 
-    // Fallback: render without highlighting
-    return h("pre", { class: `language-${lang}` }, h("code", { class: `language-${lang}` }, codeContent),
-    )
+    return h("pre", {
+      "class": [
+        "aimd-code-block",
+        options.lineNumbers ? "aimd-code-block--line-numbers" : "",
+        options.wrap ? "aimd-code-block--wrap" : "",
+        options.className,
+        `language-${lang}`,
+      ].filter(Boolean).join(" "),
+      "data-lang": lang,
+    }, h("code", {
+      class: [
+        "aimd-code-block__code",
+        `language-${lang}`,
+      ],
+    }, tokenLines.map((lineTokens, lineIndex) => h("span", {
+      class: "aimd-code-block__line",
+      "data-line": String(lineIndex + 1),
+    }, [
+      options.lineNumbers
+        ? h("span", {
+            class: "aimd-code-block__line-number",
+            "aria-hidden": "true",
+          }, String(lineIndex + 1))
+        : null,
+      h("span", {
+        class: "aimd-code-block__line-code",
+        style: { "--aimd-code-wrap-indent": `${getLineIndentColumns(lineTokens)}ch` },
+      }, hasCodeTokenContent(lineTokens)
+        ? lineTokens.map((token, tokenIndex) => h("span", {
+            key: `${lineIndex}:${tokenIndex}`,
+            style: getCodeTokenStyle(token),
+          }, token.content))
+        : "\u00a0"),
+    ]))))
   }
 }