@airalogy/aimd-renderer 2.5.0 → 2.7.0

package/src/common/processor.ts

@@ -21,6 +21,7 @@ import { resolveQuizPreviewOptions } from "./quiz-preview"
 import { remarkInsertVisibleAssigners, remarkStripAssignerCodeBlocks } from "./assignerVisibility"
 import { highlightVisibleAssigners } from "./assignerHighlighting"
 import { annotateStepReferenceSequence } from "./annotateStepReferences"
+import { criticMarkupHandlers } from "./criticMarkup"
 import { buildFigureChildren, assignFigureSequenceNumbers } from "./figureNumbering"
 
 // ---------------------------------------------------------------------------
@@ -511,7 +512,21 @@ import remarkParse from "remark-parse"
 import remarkRehype from "remark-rehype"
 import { unified } from "unified"
 
-import { protectAimdInlineTemplates, remarkAimd } from "@airalogy/aimd-core/parser"
+import {
+  CRITIC_MARKUP_SUBSTITUTIONS_DATA_KEY,
+  protectAimdInlineTemplates,
+  protectCriticMarkupSubstitutions,
+  remarkAimd,
+  remarkCriticMarkup,
+} from "@airalogy/aimd-core/parser"
+import {
+  formatAimdExampleValue,
+  formatAimdExamples,
+  getAimdFieldDescription,
+  getAimdFieldDisplayLabel,
+  getAimdFieldExamples,
+  getAimdFieldTitle,
+} from "@airalogy/aimd-core/utils"
 import {
   createAimdRendererMessages,
   getAimdRendererQuizTypeLabel,
@@ -559,14 +574,16 @@ async function ensureMathStylesLoaded(mathEnabled: boolean | undefined): Promise
 
 function createAimdParseInput(content: string) {
   const { content: protectedContent, templates } = protectAimdInlineTemplates(content)
+  const { content: criticProtectedContent, substitutions } = protectCriticMarkupSubstitutions(protectedContent)
   const file: VFile = {
     data: {
       aimdInlineTemplates: templates,
+      [CRITIC_MARKUP_SUBSTITUTIONS_DATA_KEY]: substitutions,
     },
   } as unknown as VFile
 
   return {
-    content: protectedContent,
+    content: criticProtectedContent,
     file,
   }
 }
@@ -790,6 +807,121 @@ function buildScaleBandChildren(quizNode: AimdQuizNode): Array<Element | HastTex
   } as Element]
 }
 
+function createTextNode(value: string): HastText {
+  return { type: "text", value }
+}
+
+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 createFieldMetadataPopover(help: FieldMetadataHelp): Element | null {
+  if (!help.description && help.examples.length === 0) {
+    return null
+  }
+  const children: Array<Element | HastText> = []
+  if (help.description) {
+    children.push({
+      type: "element",
+      tagName: "span",
+      properties: { className: ["aimd-field__metadata-popover-line"] },
+      children: [createTextNode(help.description)],
+    } as Element)
+  }
+  if (help.examples.length > 0) {
+    children.push({
+      type: "element",
+      tagName: "span",
+      properties: { className: ["aimd-field__metadata-examples"] },
+      children: [
+        {
+          type: "element",
+          tagName: "span",
+          properties: { className: ["aimd-field__metadata-examples-label"] },
+          children: [createTextNode("e.g.")],
+        } as Element,
+        ...help.examples.map((example) => ({
+          type: "element",
+          tagName: "span",
+          properties: { className: ["aimd-field__metadata-example"] },
+          children: [createTextNode(example)],
+        } as Element)),
+      ],
+    } as Element)
+  }
+  return {
+    type: "element",
+    tagName: "span",
+    properties: { className: ["aimd-field__metadata-popover"], role: "tooltip" },
+    children,
+  } as Element
+}
+
+function createFieldNameElement(id: string, definition: { kwargs?: Record<string, unknown> } | undefined): Element {
+  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
+  const className = ["aimd-field__name"]
+  if (hasCustomTitle || hasHelp) {
+    className.push("aimd-field__name--with-metadata")
+  }
+  if (hasHelp) {
+    className.push("aimd-field__metadata-host")
+  }
+  const children: Array<Element | HastText> = [
+    {
+      type: "element",
+      tagName: "span",
+      properties: { className: ["aimd-field__title"] },
+      children: [createTextNode(displayTitle)],
+    } as Element,
+  ]
+
+  if (hasCustomTitle) {
+    children.push({
+      type: "element",
+      tagName: "span",
+      properties: { className: ["aimd-field__key"] },
+      children: [createTextNode(id)],
+    } as Element)
+  }
+
+  const popover = createFieldMetadataPopover(help)
+  if (popover) {
+    children.push(popover)
+  }
+
+  return {
+    type: "element",
+    tagName: "span",
+    properties: cleanProperties({
+      className,
+      tabIndex: hasHelp ? 0 : undefined,
+      "aria-label": help.tooltip || undefined,
+    }),
+    children,
+  } as Element
+}
+
 // ---------------------------------------------------------------------------
 // AIMD handler (remark-rehype custom handler)
 // ---------------------------------------------------------------------------
@@ -968,23 +1100,18 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
       children: [{ type: "text", value: `[${refs.join(", ")}]` }],
     } as Element)
   }
-  else if (fieldType === "var") {
-    // Variable: type label + id + optional type annotation
-    const definition = "definition" in node ? node.definition : undefined
-    children.push(
-      {
-        type: "element",
-        tagName: "span",
-        properties: { className: ["aimd-field__scope"] },
-        children: [{ type: "text", value: getAimdRendererScopeLabel("var", messages) }],
-      } as Element,
+	  else if (fieldType === "var") {
+	    // Variable: type label + id + optional type annotation
+	    const definition = "definition" in node ? node.definition : undefined
+	    children.push(
       {
         type: "element",
         tagName: "span",
-        properties: { className: ["aimd-field__name"] },
-        children: [{ type: "text", value: id }],
-      } as Element,
-    )
+	        properties: { className: ["aimd-field__scope"] },
+	        children: [{ type: "text", value: getAimdRendererScopeLabel("var", messages) }],
+	      } as Element,
+	      createFieldNameElement(id, definition),
+	    )
     if (definition?.type) {
       children.push({
         type: "element",
@@ -994,11 +1121,13 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
       } as Element)
     }
   }
-  else if (fieldType === "var_table") {
-    // var_table: render header + table preview
-    const columns = "columns" in node ? (node as any).columns as string[] : []
-    children.push(
-      {
+	  else if (fieldType === "var_table") {
+	    // var_table: render header + table preview
+	    const columns = "columns" in node ? (node as any).columns as string[] : []
+	    const definition = "definition" in node ? node.definition : undefined
+	    const subvarDefs = definition?.subvars
+	    children.push(
+	      {
         type: "element",
         tagName: "div",
         properties: { className: ["aimd-field__header"] },
@@ -1006,17 +1135,12 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
           {
             type: "element",
             tagName: "span",
-            properties: { className: ["aimd-field__scope"] },
-            children: [{ type: "text", value: getAimdRendererScopeLabel("var_table", messages) }],
-          } as Element,
-          {
-            type: "element",
-            tagName: "span",
-            properties: { className: ["aimd-field__name"] },
-            children: [{ type: "text", value: id }],
-          } as Element,
-        ],
-      } as Element,
+	            properties: { className: ["aimd-field__scope"] },
+	            children: [{ type: "text", value: getAimdRendererScopeLabel("var_table", messages) }],
+	          } as Element,
+	          createFieldNameElement(id, definition),
+	        ],
+	      } as Element,
     )
     if (columns && columns.length > 0) {
       children.push({
@@ -1033,12 +1157,14 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
                 type: "element",
                 tagName: "tr",
                 properties: {},
-                children: columns.map(col => ({
-                  type: "element",
-                  tagName: "th",
-                  properties: {},
-                  children: [{ type: "text", value: col }],
-                } as Element)),
+	                children: columns.map(col => ({
+	                  type: "element",
+	                  tagName: "th",
+	                  properties: cleanProperties({
+	                    "data-column-id": col,
+	                  }),
+	                  children: [createFieldNameElement(col, subvarDefs?.[col])],
+	                } as Element)),
               } as Element,
             ],
           } as Element,
@@ -1242,14 +1368,29 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
   }
 
   // Build properties
-  const properties: Properties = {
-    "className": [baseClass, modifierClass],
-    "data-aimd-type": node.fieldType,
+	  const properties: Properties = {
+	    "className": [baseClass, modifierClass],
+	    "data-aimd-type": node.fieldType,
     "data-aimd-id": node.id,
     "data-aimd-scope": node.scope,
     "data-aimd-raw": node.raw,
-    "data-aimd-json": aimdJson,
-  }
+	    "data-aimd-json": aimdJson,
+	  }
+
+	  if ((node.fieldType === "var" || node.fieldType === "var_table") && "definition" in node) {
+	    const title = getAimdFieldTitle(node.definition)
+	    const description = getAimdFieldDescription(node.definition)
+	    const examples = formatAimdExamples(getAimdFieldExamples(node.definition))
+	    if (title) {
+	      properties["data-aimd-title"] = title
+	    }
+	    if (description) {
+	      properties["data-aimd-description"] = description
+	    }
+	    if (examples) {
+	      properties["data-aimd-examples"] = examples
+	    }
+	  }
 
   // Add reference href
   if (isRef) {
@@ -1380,6 +1521,7 @@ function createBaseProcessor(options: AimdRendererOptions = {}) {
   // to properly parse multiline AIMD syntax like var_table with subvars
   processor.use(remarkAimd)
   processor.use(remarkStripAssignerCodeBlocks)
+  processor.use(remarkCriticMarkup)
 
   // Single line break to <br> conversion (default enabled for AIMD)
   if (breaks) {
@@ -1402,6 +1544,7 @@ export function createHtmlProcessor(options: AimdRendererOptions = {}) {
       handlers: {
         // Custom handler for AIMD nodes
         aimd: aimdHandler,
+        ...criticMarkupHandlers,
       },
     } as any)
     .use(rehypeRaw)

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

@@ -41,6 +41,24 @@ export {
 } from './common/unified-token-renderer'
 
 // Vue renderer exports
+export {
+  AIMD_RECORD_RENDER_SCOPES,
+  createReadonlyRecordAimdRenderers,
+  createReadonlyRecordElementRenderers,
+  createReadonlyRecordRenderContext,
+  normalizeRecordRenderValue,
+  renderReadonlyRecordToVue,
+  type AimdRecordRenderScope,
+  type AimdRecordRenderValue,
+  type ReadonlyRecordAsset,
+  type ReadonlyRecordAssetKind,
+  type ReadonlyRecordAssetResolveContext,
+  type ReadonlyRecordAssetResolver,
+  type ReadonlyRecordMarkdownRenderOptions,
+  type ReadonlyRecordRenderContextInput,
+  type ReadonlyRecordVueRendererOptions,
+} from './vue/readonly-record-renderer'
+
 export {
   type AimdComponentRenderer,
   type AimdRendererContext,
@@ -51,9 +69,12 @@ export {
   createEmbeddedRenderer,
   createMermaidRenderer,
   createStepCardRenderer,
+  loadShikiHighlighter,
+  type CodeBlockRendererOptions,
   type ElementRenderer,
   hastToVue,
   renderToVNodes,
+  type LoadShikiHighlighterOptions,
   type AimdStepCardRendererOptions,
   type ShikiHighlighter,
   type VueRendererOptions,