@airalogy/aimd-renderer 2.7.0 → 2.8.0

package/src/common/citationNumbering.ts

@@ -0,0 +1,265 @@
+import type { Element, Root as HastRoot, RootContent, Text as HastText } from "hast"
+import type { AimdNode, AimdReferenceEntry, ExtractedAimdFields } from "@airalogy/aimd-core/types"
+
+export interface AimdCitationReferenceDisplay {
+  id: string
+  label: string
+  summary: string
+}
+
+type AimdCitationNodeWithDisplay = AimdNode & {
+  refs?: string[]
+  citationRefs?: AimdCitationReferenceDisplay[]
+}
+
+function isElementNode(node: RootContent | HastRoot): node is Element {
+  return node.type === "element"
+}
+
+function createTextNode(value: string): HastText {
+  return { type: "text", value }
+}
+
+function readStringProperty(properties: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = properties[key]
+    if (typeof value === "string") {
+      return value
+    }
+  }
+  return undefined
+}
+
+function splitCsv(value: string | undefined): string[] {
+  return (value || "")
+    .split(",")
+    .map(part => part.trim())
+    .filter(Boolean)
+}
+
+function hasClass(element: Element, className: string): boolean {
+  const value = element.properties?.className ?? element.properties?.class
+  if (Array.isArray(value)) {
+    return value.includes(className)
+  }
+  if (typeof value === "string") {
+    return value.split(/\s+/).includes(className)
+  }
+  return false
+}
+
+function isReferenceSectionElement(element: Element): boolean {
+  const properties = element.properties || {}
+  const aimdType = properties["data-aimd-type"] || properties.dataAimdType
+  const aimdData = (element.data as { aimd?: AimdNode } | undefined)?.aimd
+  return aimdType === "refs" || aimdData?.fieldType === "refs" || hasClass(element, "aimd-refs")
+}
+
+function isCitationElement(element: Element): boolean {
+  const properties = element.properties || {}
+  const aimdType = properties["data-aimd-type"] || properties.dataAimdType
+  const aimdData = (element.data as { aimd?: AimdNode } | undefined)?.aimd
+  return aimdType === "cite" || aimdData?.fieldType === "cite" || hasClass(element, "aimd-cite")
+}
+
+function getReferenceContainer(entry: AimdReferenceEntry): string | undefined {
+  return entry.journal || entry.booktitle || entry.publisher
+}
+
+export function formatCitationReferenceSummary(entry: AimdReferenceEntry | undefined, fallbackId: string): string {
+  if (!entry) {
+    return fallbackId
+  }
+
+  const parts = [
+    entry.author,
+    entry.year ? `(${entry.year})` : undefined,
+    entry.title,
+    getReferenceContainer(entry),
+    entry.doi ? `doi:${entry.doi}` : undefined,
+    entry.url,
+  ]
+    .map(part => part?.trim())
+    .filter((part): part is string => Boolean(part))
+
+  return parts.length > 0 ? parts.join(" ") : fallbackId
+}
+
+function getCitationRefIds(element: Element): string[] {
+  const aimdData = (element.data as { aimd?: AimdCitationNodeWithDisplay } | undefined)?.aimd
+  if (aimdData?.fieldType === "cite" && Array.isArray(aimdData.refs)) {
+    return aimdData.refs.map(ref => String(ref).trim()).filter(Boolean)
+  }
+
+  const properties = element.properties || {}
+  const refs = readStringProperty(properties as Record<string, unknown>, ["data-aimd-refs", "dataAimdRefs"])
+  const parsedRefs = splitCsv(refs)
+  if (parsedRefs.length > 0) {
+    return parsedRefs
+  }
+
+  const id = readStringProperty(properties as Record<string, unknown>, ["data-aimd-id", "dataAimdId"])
+  return id ? [id] : []
+}
+
+function buildCitationLabelMap(fields: ExtractedAimdFields): Map<string, string> {
+  const labels = new Map<string, string>()
+  for (const [index, entry] of (fields.refs || []).entries()) {
+    const id = entry.id?.trim()
+    if (id && !labels.has(id)) {
+      labels.set(id, String(index + 1))
+    }
+  }
+  return labels
+}
+
+function buildCitationSummaryMap(fields: ExtractedAimdFields): Map<string, string> {
+  const summaries = new Map<string, string>()
+  for (const entry of fields.refs || []) {
+    const id = entry.id?.trim()
+    if (id && !summaries.has(id)) {
+      summaries.set(id, formatCitationReferenceSummary(entry, id))
+    }
+  }
+  return summaries
+}
+
+function buildCitationRefs(
+  refIds: string[],
+  labelByRefId: Map<string, string>,
+  summaryByRefId: Map<string, string>,
+): AimdCitationReferenceDisplay[] {
+  return refIds.map(id => ({
+    id,
+    label: labelByRefId.get(id) || id,
+    summary: summaryByRefId.get(id) || id,
+  }))
+}
+
+function createCitationReferenceElement(citationRef: AimdCitationReferenceDisplay): Element {
+  return {
+    type: "element",
+    tagName: "span",
+    properties: {
+      className: ["aimd-cite__ref"],
+      role: "doc-noteref",
+      tabIndex: 0,
+      title: citationRef.summary,
+      "data-aimd-ref-id": citationRef.id,
+      "data-aimd-ref-summary": citationRef.summary,
+      "aria-label": citationRef.label === citationRef.id
+        ? `Reference ${citationRef.summary}`
+        : `Reference ${citationRef.label}: ${citationRef.summary}`,
+    },
+    children: [
+      {
+        type: "element",
+        tagName: "span",
+        properties: { className: ["aimd-cite__label"] },
+        children: [createTextNode(citationRef.label)],
+      } as Element,
+      {
+        type: "element",
+        tagName: "span",
+        properties: {
+          className: ["aimd-cite__popover"],
+          role: "tooltip",
+        },
+        children: [createTextNode(citationRef.summary)],
+      } as Element,
+    ],
+  } as Element
+}
+
+function createCitationChildren(citationRefs: AimdCitationReferenceDisplay[]): Array<Element | HastText> {
+  const children: Array<Element | HastText> = [createTextNode("[")]
+
+  citationRefs.forEach((citationRef, index) => {
+    if (index > 0) {
+      children.push(createTextNode(", "))
+    }
+
+    children.push(createCitationReferenceElement(citationRef))
+  })
+
+  children.push(createTextNode("]"))
+  return children
+}
+
+function annotateCitationElement(element: Element, citationRefs: AimdCitationReferenceDisplay[]): void {
+  const properties = element.properties || {}
+  element.properties = {
+    ...properties,
+    "data-aimd-citation-labels": citationRefs.map(ref => ref.label).join(","),
+    "data-aimd-citation-summaries": JSON.stringify(citationRefs.map(ref => ref.summary)),
+  }
+
+  const data = ((element as any).data || {}) as { aimd?: AimdCitationNodeWithDisplay }
+  if (data.aimd?.fieldType === "cite") {
+    data.aimd.citationRefs = citationRefs
+    data.aimd.refs = citationRefs.map(ref => ref.id)
+    ;(element as any).data = data
+  }
+
+  element.children = createCitationChildren(citationRefs)
+}
+
+function walk(node: HastRoot | RootContent, visitor: (element: Element) => void): void {
+  if (!isElementNode(node) && node.type !== "root") {
+    return
+  }
+
+  if (isElementNode(node)) {
+    visitor(node)
+  }
+
+  const children = node.children || []
+  for (const child of children) {
+    walk(child, visitor)
+  }
+}
+
+function extractReferenceSections(children: RootContent[], sections: Element[]): RootContent[] {
+  const nextChildren: RootContent[] = []
+
+  for (const child of children) {
+    if (isElementNode(child)) {
+      if (isReferenceSectionElement(child)) {
+        sections.push(child)
+        continue
+      }
+
+      child.children = extractReferenceSections(child.children || [], sections) as Element["children"]
+    }
+
+    nextChildren.push(child)
+  }
+
+  return nextChildren
+}
+
+export function moveReferenceSectionsToEnd(tree: HastRoot): void {
+  const sections: Element[] = []
+  tree.children = extractReferenceSections(tree.children, sections)
+  if (sections.length > 0) {
+    tree.children.push(...sections)
+  }
+}
+
+export function annotateCitationReferenceLabels(tree: HastRoot, fields: ExtractedAimdFields): void {
+  const labelByRefId = buildCitationLabelMap(fields)
+  const summaryByRefId = buildCitationSummaryMap(fields)
+
+  walk(tree, (element) => {
+    if (!isCitationElement(element)) {
+      return
+    }
+
+    const refIds = getCitationRefIds(element)
+    if (refIds.length === 0) {
+      return
+    }
+
+    annotateCitationElement(element, buildCitationRefs(refIds, labelByRefId, summaryByRefId))
+  })
+}

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,7 @@ 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"
 
@@ -52,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[]
@@ -557,6 +562,7 @@ const EMPTY_EXTRACTED_FIELDS: ExtractedAimdFields = {
   ref_fig: [],
   cite: [],
   fig: [],
+  refs: [],
 }
 
 async function ensureMathStylesLoaded(mathEnabled: boolean | undefined): Promise<void> {
@@ -602,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 || [])],
   }
 }
 
@@ -807,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 }
 }
@@ -994,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
@@ -1026,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)[] = []
@@ -1091,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",
@@ -1358,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,
@@ -1392,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"
     }
   }
 
@@ -1463,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
@@ -1474,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)
@@ -1578,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)
@@ -1586,6 +1751,7 @@ export async function renderToHtml(
     groupCheckBodies(hastTree)
   }
   await highlightVisibleAssigners(hastTree, options)
+  moveReferenceSectionsToEnd(hastTree)
   const html = toHtml(hastTree, { allowDangerousHtml: true })
 
   return { html, fields }
@@ -1608,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)
@@ -1616,6 +1783,7 @@ export async function renderToVue(
     groupCheckBodies(hastTree)
   }
   await highlightVisibleAssigners(hastTree, options)
+  moveReferenceSectionsToEnd(hastTree)
   const nodes = renderToVNodes(hastTree, options)
 
   return { nodes, fields }
@@ -1653,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,

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",