@airalogy/aimd-renderer 2.6.0 → 2.8.0

package/src/common/processor.ts

@@ -1,10 +1,12 @@
 import type { Element, Properties, Root as HastRoot, Text as HastText } from "hast"
 import type { VFile } from "vfile"
 import type { VNode } from "vue"
+import type { AimdAssetUrlResolver } from "./assetUrls"
 import type {
   AimdFieldType,
   AimdNode,
   AimdQuizNode,
+  AimdReferenceEntry,
   AimdStepNode,
   ProcessorOptions,
   RenderContext,
@@ -13,6 +15,7 @@ import type { ExtractedAimdFields } from "@airalogy/aimd-core/types"
 import type { AimdRendererI18nOptions } from "../locales"
 import type { VueRendererOptions } from "../vue/vue-renderer"
 import { resolveQuizPreviewOptions } from "./quiz-preview"
+import { resolveAimdAssetUrl } from "./assetUrls"
 
 // ---------------------------------------------------------------------------
 // Sub-module imports
@@ -21,6 +24,8 @@ import { resolveQuizPreviewOptions } from "./quiz-preview"
 import { remarkInsertVisibleAssigners, remarkStripAssignerCodeBlocks } from "./assignerVisibility"
 import { highlightVisibleAssigners } from "./assignerHighlighting"
 import { annotateStepReferenceSequence } from "./annotateStepReferences"
+import { annotateCitationReferenceLabels, moveReferenceSectionsToEnd } from "./citationNumbering"
+import { criticMarkupHandlers } from "./criticMarkup"
 import { buildFigureChildren, assignFigureSequenceNumbers } from "./figureNumbering"
 
 // ---------------------------------------------------------------------------
@@ -51,6 +56,7 @@ export type AimdHtmlNodeRenderer = (
 export interface AimdRendererOptions extends ProcessorOptions, AimdRendererI18nOptions {
   assignerVisibility?: AimdAssignerVisibility
   aimdElementRenderers?: Partial<Record<AimdFieldType, AimdHtmlNodeRenderer>>
+  resolveAssetUrl?: AimdAssetUrlResolver
   groupStepBodies?: boolean
   groupCheckBodies?: boolean
   blockVarTypes?: string[]
@@ -511,7 +517,13 @@ 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,
@@ -550,6 +562,7 @@ const EMPTY_EXTRACTED_FIELDS: ExtractedAimdFields = {
   ref_fig: [],
   cite: [],
   fig: [],
+  refs: [],
 }
 
 async function ensureMathStylesLoaded(mathEnabled: boolean | undefined): Promise<void> {
@@ -567,14 +580,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,
   }
 }
@@ -593,6 +608,7 @@ function createEmptyExtractedFields(): ExtractedAimdFields {
     ref_fig: [...(EMPTY_EXTRACTED_FIELDS.ref_fig || [])],
     cite: [...(EMPTY_EXTRACTED_FIELDS.cite || [])],
     fig: [...(EMPTY_EXTRACTED_FIELDS.fig || [])],
+    refs: [...(EMPTY_EXTRACTED_FIELDS.refs || [])],
   }
 }
 
@@ -798,6 +814,94 @@ function buildScaleBandChildren(quizNode: AimdQuizNode): Array<Element | HastTex
   } as Element]
 }
 
+function getReferenceContainer(entry: AimdReferenceEntry): string | undefined {
+  return entry.journal || entry.booktitle || entry.publisher
+}
+
+function createReferenceTextChildren(entry: AimdReferenceEntry): Array<Element | HastText> {
+  const children: Array<Element | HastText> = []
+  const pushText = (value: string | undefined, suffix = "") => {
+    const normalized = value?.trim()
+    if (!normalized) {
+      return
+    }
+    if (children.length > 0) {
+      children.push(createTextNode(" "))
+    }
+    children.push(createTextNode(`${normalized}${suffix}`))
+  }
+
+  pushText(entry.author)
+  pushText(entry.year ? `(${entry.year})` : undefined)
+  pushText(entry.title, entry.title && !/[.!?]$/.test(entry.title) ? "." : "")
+  pushText(getReferenceContainer(entry), ".")
+
+  if (entry.doi) {
+    if (children.length > 0) {
+      children.push(createTextNode(" "))
+    }
+    const doiHref = entry.doi.startsWith("http")
+      ? entry.doi
+      : `https://doi.org/${entry.doi}`
+    children.push({
+      type: "element",
+      tagName: "a",
+      properties: {
+        className: ["aimd-refs__doi"],
+        href: doiHref,
+      },
+      children: [createTextNode(`doi:${entry.doi}`)],
+    } as Element)
+  }
+  else if (entry.url) {
+    if (children.length > 0) {
+      children.push(createTextNode(" "))
+    }
+    children.push({
+      type: "element",
+      tagName: "a",
+      properties: {
+        className: ["aimd-refs__url"],
+        href: entry.url,
+      },
+      children: [createTextNode(entry.url)],
+    } as Element)
+  }
+
+  if (children.length === 0) {
+    children.push(createTextNode(entry.id))
+  }
+
+  return children
+}
+
+function buildReferencesChildren(entries: AimdReferenceEntry[], title: string): Array<Element | HastText> {
+  return [
+    {
+      type: "element",
+      tagName: "div",
+      properties: { className: ["aimd-refs__title"] },
+      children: [createTextNode(title)],
+    } as Element,
+    {
+      type: "element",
+      tagName: "ol",
+      properties: { className: ["aimd-refs__list"] },
+      children: entries.map(entry => ({
+        type: "element",
+        tagName: "li",
+        properties: {
+          id: `ref-${entry.id}`,
+          className: ["aimd-refs__item"],
+          "data-aimd-ref-id": entry.id,
+          "data-aimd-ref-type": entry.entry_type,
+        },
+        children: createReferenceTextChildren(entry),
+      } as Element)),
+    } as Element,
+  ]
+}
+
 function createTextNode(value: string): HastText {
   return { type: "text", value }
 }
@@ -985,6 +1089,16 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
     nodeData.sequence = figNode.sequence
   }
 
+  // Add refs-specific fields
+  if (node.fieldType === "refs") {
+    nodeData.entries = (node as any).entries
+  }
+
+  // Add cite-specific fields
+  if (node.fieldType === "cite") {
+    nodeData.refs = (node as any).refs
+  }
+
   // Add step-specific fields
   if (node.fieldType === "step") {
     const stepNode = node as AimdStepNode
@@ -1017,12 +1131,13 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
   const isCite = fieldType === "cite"
   const isQuiz = fieldType === "quiz"
   const isFig = fieldType === "fig"
+  const isRefs = fieldType === "refs"
   const baseClass = isRef
     ? "aimd-ref"
-    : (isCite ? "aimd-cite" : (isFig ? "aimd-figure" : "aimd-field"))
+    : (isCite ? "aimd-cite" : (isFig ? "aimd-figure" : (isRefs ? "aimd-refs" : "aimd-field")))
   const modifierClass = isRef
     ? `aimd-ref--${fieldType === "ref_step" ? "step" : (fieldType === "ref_var" ? "var" : "fig")}`
-    : (isCite ? "" : (isFig ? "" : `aimd-field--${typeClass}`))
+    : (isCite ? "" : (isFig || isRefs ? "" : `aimd-field--${typeClass}`))
 
   // Generate children based on field type
   const children: (Element | HastText)[] = []
@@ -1082,27 +1197,66 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
     }
   }
   else if (isCite) {
-    // Citation: [refs]
+    // Citation: compact reference markers; details are attached during citation annotation.
     const refs = "refs" in node ? (node as any).refs : [id]
+    children.push(createTextNode("["))
+    refs.forEach((ref: string, index: number) => {
+      if (index > 0) {
+        children.push(createTextNode(", "))
+      }
+      children.push({
+        type: "element",
+        tagName: "span",
+        properties: {
+          className: ["aimd-cite__ref"],
+          role: "doc-noteref",
+          tabIndex: 0,
+          title: ref,
+          "data-aimd-ref-id": ref,
+          "data-aimd-ref-summary": ref,
+        },
+        children: [
+          {
+            type: "element",
+            tagName: "span",
+            properties: { className: ["aimd-cite__label"] },
+            children: [createTextNode(ref)],
+          } as Element,
+          {
+            type: "element",
+            tagName: "span",
+            properties: {
+              className: ["aimd-cite__popover"],
+              role: "tooltip",
+            },
+            children: [createTextNode(ref)],
+          } as Element,
+        ],
+      } as Element)
+    })
+    children.push(createTextNode("]"))
+  }
+  else if (isRefs) {
+    const entries = Array.isArray((node as any).entries) ? (node as any).entries : []
     children.push({
       type: "element",
-      tagName: "span",
-      properties: { className: ["aimd-cite__refs"] },
-      children: [{ type: "text", value: `[${refs.join(", ")}]` }],
+      tagName: "div",
+      properties: { className: ["aimd-refs__content"] },
+      children: buildReferencesChildren(entries, messages.references.title),
     } as Element)
   }
-	  else if (fieldType === "var") {
-	    // Variable: type label + id + optional type annotation
-	    const definition = "definition" in node ? node.definition : undefined
-	    children.push(
+  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,
-	      createFieldNameElement(id, definition),
-	    )
+        properties: { className: ["aimd-field__scope"] },
+        children: [{ type: "text", value: getAimdRendererScopeLabel("var", messages) }],
+      } as Element,
+      createFieldNameElement(id, definition),
+    )
     if (definition?.type) {
       children.push({
         type: "element",
@@ -1349,9 +1503,15 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
   else if (fieldType === "fig") {
     // Figure: delegate to figureNumbering module
     const figNode = node as any
+    const figId = figNode.id || id
+    const figSrc = resolveAimdAssetUrl(figNode.src, options.resolveAssetUrl, {
+      kind: "fig",
+      id: figId,
+      title: figNode.title,
+    })
     children.push(...buildFigureChildren({
-      id: figNode.id || id,
-      src: figNode.src,
+      id: figId,
+      src: figSrc,
       title: figNode.title,
       legend: figNode.legend,
       sequence: figNode.sequence,
@@ -1383,16 +1543,20 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
 	    }
 	  }
 
-  // Add reference href
+  // Add internal reference metadata for host-level scrolling.
   if (isRef) {
+    properties.title = id
+    properties.tabIndex = 0
+    properties["data-aimd-ref-target"] = id
+
     if (fieldType === "ref_step") {
-      properties.href = `#step-${id}`
+      properties["data-aimd-ref-kind"] = "step"
     }
     else if (fieldType === "ref_var") {
-      properties.href = `#var-${id}`
+      properties["data-aimd-ref-kind"] = "var"
     }
     else if (fieldType === "ref_fig") {
-      properties.href = `#fig-${id}`
+      properties["data-aimd-ref-kind"] = "fig"
     }
   }
 
@@ -1454,6 +1618,15 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
     properties["data-aimd-fig-src"] = figNode.src
   }
 
+  if (node.fieldType === "cite") {
+    const refs = "refs" in node ? (node as any).refs : [id]
+    properties["data-aimd-refs"] = refs.join(",")
+  }
+
+  if (node.fieldType === "refs") {
+    properties.id = "refs"
+  }
+
   // Add quiz metadata for fallback reconstruction
   if (node.fieldType === "quiz") {
     const quizNode = node as AimdQuizNode
@@ -1465,8 +1638,8 @@ function createAimdHandler(options: AimdRendererOptions = {}) {
   const element: Element = assignAimdNodeData({
     type: "element",
     tagName: isRef
-      ? "a"
-      : (isFig ? "figure" : ((fieldType === "var_table" || isQuiz || isGroupedStepContainer) ? "div" : "span")),
+      ? "span"
+      : (isFig ? "figure" : (isRefs ? "section" : ((fieldType === "var_table" || isQuiz || isGroupedStepContainer) ? "div" : "span"))),
     properties,
     children,
   }, node)
@@ -1512,6 +1685,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) {
@@ -1534,6 +1708,7 @@ export function createHtmlProcessor(options: AimdRendererOptions = {}) {
       handlers: {
         // Custom handler for AIMD nodes
         aimd: aimdHandler,
+        ...criticMarkupHandlers,
       },
     } as any)
     .use(rehypeRaw)
@@ -1567,6 +1742,7 @@ export async function renderToHtml(
   const fields = getExtractedFields(file)
   annotateStepReferenceSequence(hastTree, fields, options)
   assignFigureSequenceNumbers(hastTree, fields)
+  annotateCitationReferenceLabels(hastTree, fields)
   liftBlockVarElements(hastTree, options.blockVarTypes)
   if (options.groupStepBodies) {
     groupStepBodies(hastTree)
@@ -1575,6 +1751,7 @@ export async function renderToHtml(
     groupCheckBodies(hastTree)
   }
   await highlightVisibleAssigners(hastTree, options)
+  moveReferenceSectionsToEnd(hastTree)
   const html = toHtml(hastTree, { allowDangerousHtml: true })
 
   return { html, fields }
@@ -1597,6 +1774,7 @@ export async function renderToVue(
   const fields = getExtractedFields(file)
   annotateStepReferenceSequence(hastTree, fields, options)
   assignFigureSequenceNumbers(hastTree, fields)
+  annotateCitationReferenceLabels(hastTree, fields)
   liftBlockVarElements(hastTree, options.blockVarTypes)
   if (options.groupStepBodies) {
     groupStepBodies(hastTree)
@@ -1605,6 +1783,7 @@ export async function renderToVue(
     groupCheckBodies(hastTree)
   }
   await highlightVisibleAssigners(hastTree, options)
+  moveReferenceSectionsToEnd(hastTree)
   const nodes = renderToVNodes(hastTree, options)
 
   return { nodes, fields }
@@ -1642,10 +1821,12 @@ export function renderToHtmlSync(
   const fields = getExtractedFields(file)
   annotateStepReferenceSequence(hastTree, fields, options)
   assignFigureSequenceNumbers(hastTree, fields)
+  annotateCitationReferenceLabels(hastTree, fields)
   liftBlockVarElements(hastTree, options.blockVarTypes)
   if (options.groupStepBodies) {
     groupStepBodies(hastTree)
   }
+  moveReferenceSectionsToEnd(hastTree)
   const html = toHtml(hastTree, { allowDangerousHtml: true })
 
   return { html, fields }

package/src/html/index.ts

@@ -25,6 +25,10 @@ export type {
   AimdRendererOptions,
   RenderResult,
 } from '../common/processor'
+export type {
+  AimdAssetUrlResolver,
+  AimdAssetUrlResolveContext,
+} from '../common/assetUrls'
 export type {
   AimdRendererI18nOptions,
   AimdRendererLocale,

package/src/index.ts

@@ -23,6 +23,11 @@ export {
   resolveAimdRendererLocale,
 } from './locales'
 
+export type {
+  AimdAssetUrlResolver,
+  AimdAssetUrlResolveContext,
+} from './common/assetUrls'
+
 export {
   bubbleMenuEventKey,
   draftEventKey,
@@ -41,6 +46,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,

package/src/locales.ts

@@ -43,6 +43,9 @@ export interface AimdRendererMessages {
     reference: (value: string | number) => string
     captionTitle: (sequence: number, title?: string) => string
   }
+  references: {
+    title: string
+  }
   assigner: {
     clientSummary: string
     serverSummary: string
@@ -104,6 +107,9 @@ const EN_US_MESSAGES: AimdRendererMessages = {
     reference: value => `figure ${value}`,
     captionTitle: (sequence, title) => title ? `figure ${sequence}: ${title}` : `figure ${sequence}`,
   },
+  references: {
+    title: "References",
+  },
   assigner: {
     clientSummary: "Client assigner",
     serverSummary: "Server assigner",
@@ -141,6 +147,9 @@ const ZH_CN_MESSAGES: AimdRendererMessages = {
     reference: value => `图 ${value}`,
     captionTitle: (sequence, title) => title ? `图 ${sequence}：${title}` : `图 ${sequence}`,
   },
+  references: {
+    title: "参考文献",
+  },
   assigner: {
     clientSummary: "前端 assigner",
     serverSummary: "服务端 assigner",