@airalogy/aimd-renderer 2.5.0 → 2.6.0

package/src/common/unified-token-renderer.ts

@@ -13,6 +13,13 @@ import type {
 } from "@airalogy/aimd-core/types"
 import type { AimdNode, QuizPreviewOptions, RenderContext } from "@airalogy/aimd-core/types"
 import type { ExtractedAimdFields } from "@airalogy/aimd-core/types"
+import {
+  formatAimdExampleValue,
+  getAimdFieldDescription,
+  getAimdFieldDisplayLabel,
+  getAimdFieldExamples,
+  getAimdFieldTitle,
+} from "@airalogy/aimd-core/utils"
 import type { AimdRendererI18nOptions, AimdRendererMessages } from "../locales"
 import type { AimdComponentRenderer, ElementRenderer, ShikiHighlighter, VueRendererOptions } from "../vue/vue-renderer"
 import type { AimdRendererOptions, RenderResult } from "./processor"
@@ -226,6 +233,74 @@ function buildScaleBandChildren(quizNode: AimdQuizNode): VNode[] {
   ]
 }
 
+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),
+  ])
+}
+
 /**
  * Render preview tag for AIMD field
  */
@@ -234,6 +309,7 @@ function renderPreviewTag(
   id: string,
   messages: AimdRendererMessages,
   columns?: string[],
+  definition?: { kwargs?: Record<string, unknown>, subvars?: Record<string, { kwargs?: Record<string, unknown> }> },
 ): VNode {
   const scopeKey = getScopeKey(scope)
   const scopeLabel = getAimdRendererScopeLabel(scope, messages)
@@ -241,17 +317,19 @@ function renderPreviewTag(
   // var_table: render tag with table preview inside
   if (scope === "var_table") {
     const children: VNode[] = [
-      h("div", { class: "aimd-field__header" }, [
-        h("span", { class: "aimd-field__scope" }, messages.scope.table),
-        h("span", { class: "aimd-field__name" }, id),
-      ]),
+	      h("div", { class: "aimd-field__header" }, [
+	        h("span", { class: "aimd-field__scope" }, 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("tr", columns.map(col => h("th", {
+	              "data-column-id": col,
+	            }, [renderFieldName(col, definition?.subvars?.[col])]))),
           ]),
           h("tbody", [
             h("tr", columns.map(() => h("td", "..."))),
@@ -272,10 +350,10 @@ function renderPreviewTag(
     "class": `aimd-field aimd-field--${classSuffix}`,
     "data-aimd-type": scopeKey,
     "data-aimd-id": id,
-  }, [
-    h("span", { class: "aimd-field__scope" }, scopeLabel),
-    h("span", { class: "aimd-field__name" }, id),
-  ])
+	}, [
+	  h("span", { class: "aimd-field__scope" }, scopeLabel),
+	  renderFieldName(id, definition),
+	])
 }
 
 /**
@@ -299,19 +377,20 @@ function createAimdRenderers(options: UnifiedTokenRendererOptions): Record<strin
     resolveQuizPreviewOptions(getMode(), options.quizPreview)
 
   return {
-    var: async (node, ctx, children) => {
-      const varNode = node as AimdVarNode
-      const { id, scope } = varNode
+	    var: async (node, ctx, children) => {
+	      const varNode = node as AimdVarNode
+	      const { id, scope } = varNode
+	      const definition = varNode.definition
 
-      if (isPreview()) {
+	      if (isPreview()) {
         if (PreviewRenderer) {
           return h(PreviewRenderer, { type: "var" }, {
             default: () => children,
             name: () => id,
           })
         }
-        return renderPreviewTag(scope, id, messages)
-      }
+	        return renderPreviewTag(scope, id, messages, undefined, definition)
+	      }
 
       // Edit mode
       if (getTokenProps && AIMDItem) {
@@ -325,12 +404,13 @@ function createAimdRenderers(options: UnifiedTokenRendererOptions): Record<strin
         }
       }
 
-      return renderPreviewTag(scope, id, messages)
-    },
+	      return renderPreviewTag(scope, id, messages, undefined, definition)
+	    },
 
-    var_table: async (node, ctx, children) => {
-      const tableNode = node as AimdVarTableNode
-      const { id, scope, columns } = tableNode
+	    var_table: async (node, ctx, children) => {
+	      const tableNode = node as AimdVarTableNode
+	      const { id, scope, columns } = tableNode
+	      const definition = tableNode.definition
 
       if (isPreview()) {
         if (PreviewRenderer) {
@@ -340,8 +420,8 @@ function createAimdRenderers(options: UnifiedTokenRendererOptions): Record<strin
           })
         }
         // Preview mode: render inline tag with columns info
-        return renderPreviewTag(scope, id, messages, columns)
-      }
+	        return renderPreviewTag(scope, id, messages, columns, definition)
+	      }
 
       // Edit mode
       if (getTokenProps && AIMDTag) {
@@ -349,8 +429,8 @@ function createAimdRenderers(options: UnifiedTokenRendererOptions): Record<strin
         return h(AIMDTag, { ...item, props: columns })
       }
 
-      return renderPreviewTag(scope, id, messages, columns)
-    },
+	      return renderPreviewTag(scope, id, messages, columns, definition)
+	    },
 
     quiz: async (node, ctx, children) => {
       const quizNode = node as AimdQuizNode

package/src/index.ts

@@ -51,9 +51,12 @@ export {
   createEmbeddedRenderer,
   createMermaidRenderer,
   createStepCardRenderer,
+  loadShikiHighlighter,
+  type CodeBlockRendererOptions,
   type ElementRenderer,
   hastToVue,
   renderToVNodes,
+  type LoadShikiHighlighterOptions,
   type AimdStepCardRendererOptions,
   type ShikiHighlighter,
   type VueRendererOptions,

package/src/styles/katex.css

@@ -1,2 +1,111 @@
 /* Re-export KaTeX base styles for AIMD renderer consumers. */
 @import "katex/dist/katex.min.css";
+
+.aimd-field__metadata-host {
+  position: relative;
+  cursor: help;
+  outline: none;
+}
+
+.aimd-field__metadata-host:hover,
+.aimd-field__metadata-host:focus,
+.aimd-field__metadata-host:focus-within {
+  z-index: 90;
+}
+
+.aimd-field__metadata-host:focus-visible {
+  border-radius: 4px;
+  box-shadow: 0 0 0 2px rgba(65, 129, 253, 0.24);
+}
+
+.aimd-field__metadata-host .aimd-field__title {
+  text-decoration-line: underline;
+  text-decoration-style: dotted;
+  text-decoration-color: rgba(15, 23, 42, 0.36);
+  text-underline-offset: 3px;
+}
+
+.aimd-field__metadata-popover {
+  position: absolute;
+  z-index: 80;
+  inset-inline-start: 0;
+  top: calc(100% + 7px);
+  display: inline-flex;
+  flex-direction: column;
+  gap: 4px;
+  width: max-content;
+  min-width: 220px;
+  max-width: min(360px, 82vw);
+  padding: 8px 10px;
+  border-radius: 8px;
+  background: rgba(15, 23, 42, 0.96);
+  color: #f8fafc;
+  box-shadow: 0 12px 30px rgba(15, 23, 42, 0.28);
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 1.45;
+  letter-spacing: 0;
+  text-align: left;
+  text-transform: none;
+  white-space: normal;
+  pointer-events: none;
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(-2px);
+  transition:
+    opacity 120ms ease,
+    transform 120ms ease,
+    visibility 120ms ease;
+}
+
+.aimd-field__metadata-popover::before {
+  content: "";
+  position: absolute;
+  inset-inline-start: 14px;
+  top: -5px;
+  width: 10px;
+  height: 10px;
+  background: rgba(15, 23, 42, 0.96);
+  transform: rotate(45deg);
+}
+
+.aimd-field__metadata-popover-line {
+  display: block;
+  color: inherit;
+}
+
+.aimd-field__metadata-examples {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+  padding-top: 1px;
+}
+
+.aimd-field__metadata-examples-label {
+  color: rgba(226, 232, 240, 0.78);
+}
+
+.aimd-field__metadata-example {
+  display: inline-flex;
+  align-items: center;
+  max-width: 100%;
+  padding: 1px 6px;
+  border: 1px solid rgba(248, 250, 252, 0.18);
+  border-radius: 5px;
+  background: rgba(248, 250, 252, 0.1);
+  color: #f8fafc;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+
+.aimd-field__metadata-host:hover > .aimd-field__metadata-popover,
+.aimd-field__metadata-host:focus > .aimd-field__metadata-popover,
+.aimd-field__metadata-host:focus-within > .aimd-field__metadata-popover {
+  opacity: 1;
+  visibility: visible;
+  transform: translateY(0);
+}

package/src/vue/index.ts

@@ -12,9 +12,12 @@ export {
   createEmbeddedRenderer,
   createMermaidRenderer,
   createStepCardRenderer,
+  loadShikiHighlighter,
+  type CodeBlockRendererOptions,
   type ElementRenderer,
   hastToVue,
   renderToVNodes,
+  type LoadShikiHighlighterOptions,
   type AimdStepCardRendererOptions,
   type ShikiHighlighter,
   type VueRendererOptions,