@airalogy/aimd-renderer 2.7.0 → 2.8.0

package/src/styles/katex.css

@@ -1,6 +1,154 @@
 /* Re-export KaTeX base styles for AIMD renderer consumers. */
 @import "katex/dist/katex.min.css";
 
+.aimd-figure {
+  display: block;
+  box-sizing: border-box;
+  width: fit-content;
+  max-width: min(100%, 920px);
+  margin: 1.2em auto 1.45em;
+  overflow: hidden;
+  border: 1px solid #d8e2ef;
+  border-radius: 10px;
+  background: #ffffff;
+}
+
+.aimd-figure > .aimd-figure__image {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin: 0 auto;
+  border-radius: 0;
+  background: #f3f7fc;
+  object-fit: contain;
+}
+
+.aimd-figure__caption {
+  display: block;
+  margin: 0;
+  padding: 10px 14px 12px 16px;
+  border-top: 1px solid #d8e2ef;
+  background: linear-gradient(180deg, #ffffff 0%, #fbfdff 100%);
+  color: #253247;
+  line-height: 1.45;
+}
+
+.aimd-figure__title {
+  margin: 0;
+  color: #172033;
+  font-size: 0.94em;
+  font-weight: 700;
+  line-height: 1.38;
+}
+
+.aimd-figure__legend {
+  margin: 4px 0 0;
+  color: #526176;
+  font-size: 0.9em;
+  line-height: 1.5;
+}
+
+@media (max-width: 640px) {
+  .aimd-figure {
+    width: 100%;
+    margin-right: 0;
+    margin-left: 0;
+  }
+
+  .aimd-figure > .aimd-figure__image {
+    width: 100%;
+  }
+}
+
+.aimd-ref[data-aimd-ref-target] {
+  cursor: pointer;
+}
+
+.aimd-ref[data-aimd-ref-target]:focus-visible {
+  outline: 2px solid rgba(25, 118, 210, 0.36);
+  outline-offset: 3px;
+}
+
+.aimd-cite {
+  display: inline;
+  color: #1976d2;
+  font-size: 13px;
+  text-decoration: none;
+}
+
+.aimd-cite__refs {
+  font-weight: 500;
+}
+
+.aimd-cite__ref {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  border-radius: 999px;
+  outline: none;
+  color: inherit;
+  cursor: help;
+  font-weight: 600;
+  line-height: 1;
+  text-decoration: none;
+}
+
+.aimd-cite__ref:hover,
+.aimd-cite__ref:focus-visible {
+  text-decoration: underline;
+}
+
+.aimd-cite__label {
+  display: inline-flex;
+  align-items: center;
+}
+
+.aimd-cite__popover {
+  position: absolute;
+  left: 50%;
+  top: calc(100% + 8px);
+  z-index: 30;
+  width: max-content;
+  max-width: min(420px, 80vw);
+  padding: 8px 10px;
+  border: 1px solid #d6e1f0;
+  border-radius: 8px;
+  background: #ffffff;
+  box-shadow: 0 12px 30px rgba(15, 23, 42, 0.14);
+  color: #1f2937;
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 1.45;
+  opacity: 0;
+  overflow-wrap: anywhere;
+  pointer-events: none;
+  user-select: text;
+  text-align: left;
+  text-decoration: none;
+  transform: translate(-50%, -4px);
+  transition: opacity 120ms ease, transform 120ms ease, visibility 120ms ease;
+  visibility: hidden;
+  white-space: normal;
+}
+
+.aimd-cite__popover::before {
+  content: "";
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: -10px;
+  height: 10px;
+}
+
+.aimd-cite__ref:hover .aimd-cite__popover,
+.aimd-cite__ref:focus .aimd-cite__popover,
+.aimd-cite__ref:focus-within .aimd-cite__popover {
+  opacity: 1;
+  pointer-events: auto;
+  transform: translate(-50%, 0);
+  visibility: visible;
+}
+
 .aimd-field__metadata-host {
   position: relative;
   cursor: help;

package/src/vue/index.ts

@@ -60,6 +60,10 @@ export type {
 } from '@airalogy/aimd-core/types'
 
 export type { AimdAssignerVisibility, AimdRendererOptions, RenderResult } from '../common/processor'
+export type {
+  AimdAssetUrlResolver,
+  AimdAssetUrlResolveContext,
+} from '../common/assetUrls'
 export type {
   AimdRendererI18nOptions,
   AimdRendererLocale,

package/src/vue/vue-renderer.ts

@@ -1,6 +1,8 @@
 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 type { AimdNode, AimdQuizNode, AimdReferenceEntry, AimdStepNode, RenderContext } from "@airalogy/aimd-core/types"
+import type { AimdCitationReferenceDisplay } from "../common/citationNumbering"
+import type { AimdAssetUrlResolver } from "../common/assetUrls"
 import {
   formatAimdExampleValue,
   getAimdFieldDescription,
@@ -10,6 +12,8 @@ import {
 } from "@airalogy/aimd-core/utils"
 import { Fragment, h } from "vue"
 import type { AimdRendererI18nOptions, AimdRendererLocale, AimdRendererMessages } from "../locales"
+import { resolveAimdAssetUrl } from "../common/assetUrls"
+import { formatCitationReferenceSummary, moveReferenceSectionsToEnd } from "../common/citationNumbering"
 import { resolveQuizPreviewOptions, type ResolvedQuizPreviewOptions } from "../common/quiz-preview"
 import {
   createAimdRendererMessages,
@@ -48,6 +52,7 @@ export type ElementRenderer = (
 export interface AimdRendererContext extends RenderContext {
   locale: AimdRendererLocale
   messages: AimdRendererMessages
+  resolveAssetUrl?: AimdAssetUrlResolver
 }
 
 export interface AimdStepCardRendererOptions {
@@ -159,6 +164,66 @@ function buildScaleBandChildren(quizNode: AimdQuizNode): VNodeChild[] {
   ]
 }
 
+function getReferenceContainer(entry: AimdReferenceEntry): string | undefined {
+  return entry.journal || entry.booktitle || entry.publisher
+}
+
+function buildReferenceChildren(entry: AimdReferenceEntry): VNodeChild[] {
+  const children: VNodeChild[] = []
+  const pushText = (value: string | undefined, suffix = "") => {
+    const normalized = value?.trim()
+    if (!normalized) {
+      return
+    }
+    if (children.length > 0) {
+      children.push(" ")
+    }
+    children.push(`${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(" ")
+    }
+    const doiHref = entry.doi.startsWith("http")
+      ? entry.doi
+      : `https://doi.org/${entry.doi}`
+    children.push(h("a", { class: "aimd-refs__doi", href: doiHref }, `doi:${entry.doi}`))
+  }
+  else if (entry.url) {
+    if (children.length > 0) {
+      children.push(" ")
+    }
+    children.push(h("a", { class: "aimd-refs__url", href: entry.url }, entry.url))
+  }
+
+  return children.length > 0 ? children : [entry.id]
+}
+
+function getCitationReferenceDisplays(node: AimdNode): AimdCitationReferenceDisplay[] {
+  const citationRefs = (node as any).citationRefs
+  if (Array.isArray(citationRefs) && citationRefs.length > 0) {
+    return citationRefs
+      .map(ref => ({
+        id: String(ref?.id || "").trim(),
+        label: String(ref?.label || ref?.id || "").trim(),
+        summary: String(ref?.summary || ref?.id || "").trim(),
+      }))
+      .filter(ref => ref.id && ref.label)
+  }
+
+  const refs: unknown[] = Array.isArray((node as any).refs) ? (node as any).refs : [node.id]
+  return refs
+    .map((ref: unknown) => String(ref).trim())
+    .filter(Boolean)
+    .map((ref: string) => ({ id: ref, label: ref, summary: formatCitationReferenceSummary(undefined, ref) }))
+}
+
 interface FieldMetadataHelp {
   tooltip: string
   description?: string
@@ -560,7 +625,10 @@ const defaultAimdRenderers: Record<string, AimdComponentRenderer> = {
       "class": "aimd-ref aimd-ref--step",
       "data-aimd-type": "ref_step",
       "data-aimd-ref": refTarget,
+      "data-aimd-ref-target": refTarget,
+      "data-aimd-ref-kind": "step",
       "data-aimd-step-sequence": stepSequence,
+      "tabindex": 0,
       "title": refTarget,
     }, [
       h("span", { class: "aimd-ref__content" }, [
@@ -580,6 +648,9 @@ const defaultAimdRenderers: Record<string, AimdComponentRenderer> = {
       "class": "aimd-ref aimd-ref--var",
       "data-aimd-type": "ref_var",
       "data-aimd-ref": refTarget,
+      "data-aimd-ref-target": refTarget,
+      "data-aimd-ref-kind": "var",
+      "tabindex": 0,
       "title": refTarget,
     }, [
       h("span", { class: "aimd-ref__content" }, [
@@ -607,36 +678,64 @@ const defaultAimdRenderers: Record<string, AimdComponentRenderer> = {
     // Display figure number if available, otherwise show ID
     const displayText = ctx.messages.figure.reference(figureNumber !== undefined ? figureNumber : refTarget)
 
-    // Render as link reference to the figure
-    return h("a", {
+    return h("span", {
       "class": "aimd-ref aimd-ref--fig",
       "data-aimd-type": "ref_fig",
       "data-aimd-ref": refTarget,
-      "href": `#fig-${refTarget}`,
+      "data-aimd-ref-target": refTarget,
+      "data-aimd-ref-kind": "fig",
+      "tabindex": 0,
+      "title": refTarget,
     }, [
       h("span", { class: "aimd-ref__content" }, displayText),
     ])
   },
 
   cite: (node, ctx) => {
-    const refs = "refs" in node ? (node as any).refs : [node.id]
+    const citationRefs = getCitationReferenceDisplays(node)
 
     return h("span", {
       "class": "aimd-cite",
       "data-aimd-type": "cite",
-      "data-aimd-refs": refs.join(","),
+      "data-aimd-refs": citationRefs.map(ref => ref.id).join(","),
+      "data-aimd-citation-labels": citationRefs.map(ref => ref.label).join(","),
     }, [
-      h("span", { class: "aimd-cite__refs" }, `[${refs.join(", ")}]`),
+      "[",
+      ...citationRefs.flatMap((ref, index) => [
+        index > 0 ? ", " : "",
+        h("span", {
+          class: "aimd-cite__ref",
+          role: "doc-noteref",
+          tabindex: 0,
+          title: ref.summary,
+          "data-aimd-ref-id": ref.id,
+          "data-aimd-ref-summary": ref.summary,
+          "aria-label": ref.label === ref.id
+            ? `Reference ${ref.summary}`
+            : `Reference ${ref.label}: ${ref.summary}`,
+        }, [
+          h("span", { class: "aimd-cite__label" }, ref.label),
+          h("span", {
+            class: "aimd-cite__popover",
+            role: "tooltip",
+          }, ref.summary),
+        ]),
+      ]),
+      "]",
     ])
   },
 
   fig: (node, ctx) => {
     const figNode = node as any
     const figId = figNode.id || node.id
-    const figSrc = figNode.src || ""
     const figTitle = figNode.title
     const figLegend = figNode.legend
     const figSequence = figNode.sequence
+    const figSrc = resolveAimdAssetUrl(figNode.src || "", ctx.resolveAssetUrl, {
+      kind: "fig",
+      id: figId,
+      title: figTitle,
+    }) || ""
 
     const children: VNodeChild[] = []
 
@@ -684,6 +783,29 @@ const defaultAimdRenderers: Record<string, AimdComponentRenderer> = {
       "id": `fig-${figId}`,
     }, children)
   },
+
+  refs: (node, ctx) => {
+    const entries = Array.isArray((node as any).entries)
+      ? (node as any).entries as AimdReferenceEntry[]
+      : []
+
+    return h("section", {
+      "class": "aimd-refs",
+      "data-aimd-type": "refs",
+      "data-aimd-id": node.id,
+      "id": "refs",
+    }, [
+      h("div", { class: "aimd-refs__title" }, ctx.messages.references.title),
+      h("ol", { class: "aimd-refs__list" }, entries.map(entry =>
+        h("li", {
+          id: `ref-${entry.id}`,
+          class: "aimd-refs__item",
+          "data-aimd-ref-id": entry.id,
+          "data-aimd-ref-type": entry.entry_type,
+        }, buildReferenceChildren(entry)),
+      )),
+    ])
+  },
 }
 
 /**
@@ -709,7 +831,11 @@ export interface VueRendererOptions {
   /**
    * Render context
    */
-  context?: RenderContext & Partial<Pick<AimdRendererContext, "locale" | "messages">>
+  context?: RenderContext & Partial<Pick<AimdRendererContext, "locale" | "messages" | "resolveAssetUrl">>
+  /**
+   * Resolve protocol-local figure assets to displayable URLs.
+   */
+  resolveAssetUrl?: AimdAssetUrlResolver
   /**
    * Custom AIMD component renderers
    * Override default renderers or add new ones
@@ -751,6 +877,7 @@ function resolveRenderContext(options: VueRendererOptions): AimdRendererContext
     quizPreview: context?.quizPreview ?? topLevelQuizPreview ?? undefined,
     locale,
     messages,
+    resolveAssetUrl: context?.resolveAssetUrl ?? options.resolveAssetUrl,
   }
 }
 
@@ -817,6 +944,29 @@ function preprocessFigures(node: HastRoot | RootContent, figCtx: FigureContext):
 /**
  * Parse AIMD node from HAST element properties
  */
+function splitCsvProp(value: unknown): string[] {
+  return String(value || "")
+    .split(",")
+    .map(part => part.trim())
+    .filter(Boolean)
+}
+
+function parseStringArrayProp(value: unknown): string[] {
+  if (typeof value !== "string" || !value.trim()) {
+    return []
+  }
+
+  try {
+    const parsed = JSON.parse(value)
+    return Array.isArray(parsed)
+      ? parsed.map(item => String(item || "").trim()).filter(Boolean)
+      : []
+  }
+  catch {
+    return []
+  }
+}
+
 function parseAimdFromProps(props: Record<string, unknown>): AimdNode | undefined {
   let parsedFromJson: Record<string, unknown> | undefined
 
@@ -850,10 +1000,23 @@ function parseAimdFromProps(props: Record<string, unknown>): AimdNode | undefine
   }
 
   const stepSequence = props["data-aimd-step-sequence"] || props.dataAimdStepSequence
+  const citationRefIds = splitCsvProp(props["data-aimd-refs"] || props.dataAimdRefs)
+  const citationLabels = splitCsvProp(props["data-aimd-citation-labels"] || props.dataAimdCitationLabels)
+  const citationSummaries = parseStringArrayProp(props["data-aimd-citation-summaries"] || props.dataAimdCitationSummaries)
+  const citationRefs = citationRefIds.map((refId, index) => ({
+    id: refId,
+    label: citationLabels[index] || refId,
+    summary: citationSummaries[index] || refId,
+  }))
+
   if (parsedFromJson) {
     if (typeof stepSequence === "string" && stepSequence.trim()) {
       parsedFromJson.stepSequence = stepSequence
     }
+    if (fieldType === "cite" && citationRefs.length > 0) {
+      parsedFromJson.refs = citationRefs.map(ref => ref.id)
+      parsedFromJson.citationRefs = citationRefs
+    }
     return parsedFromJson as unknown as AimdNode
   }
 
@@ -888,6 +1051,16 @@ function parseAimdFromProps(props: Record<string, unknown>): AimdNode | undefine
     } as AimdNode
   }
 
+  if (fieldType === "cite") {
+    const refs = citationRefIds.length > 0 ? citationRefIds : [id]
+    return {
+      ...baseNode,
+      fieldType: "cite",
+      refs,
+      ...(citationRefs.length > 0 ? { citationRefs } : {}),
+    } as unknown as AimdNode
+  }
+
   // Add quiz-specific properties
   if (fieldType === "quiz") {
     const quizType = (props["data-aimd-quiz-type"] || props.dataAimdQuizType || "open") as string
@@ -1145,6 +1318,7 @@ export function renderToVNodes(
   tree: HastRoot,
   options: VueRendererOptions = {},
 ): VNode[] {
+  moveReferenceSectionsToEnd(tree)
   const result = hastToVue(tree, options)
 
   if (result === null || result === undefined) {