@airalogy/aimd-renderer 2.4.1

package/dist/vue.js

@@ -0,0 +1,17 @@
+import { D as a, c as d, f as s, g as n, h as t, i as o, j as R, k as c, l as m, m as A, n as E, o as l, q as i, e as C } from "./processor-Cv8E7QsA.js";
+export {
+  a as DEFAULT_AIMD_RENDERER_LOCALE,
+  d as createAimdRendererMessages,
+  s as createAssetRenderer,
+  n as createCodeBlockRenderer,
+  t as createComponentRenderer,
+  o as createEmbeddedRenderer,
+  R as createMermaidRenderer,
+  c as createRenderer,
+  m as createStepCardRenderer,
+  A as defaultRenderer,
+  E as hastToVue,
+  l as renderToVNodes,
+  i as renderToVue,
+  C as resolveAimdRendererLocale
+};

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@airalogy/aimd-renderer",
+  "type": "module",
+  "version": "2.4.1",
+  "description": "AIMD rendering engines for HTML and Vue",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/airalogy/aimd.git",
+    "directory": "packages/aimd-renderer"
+  },
+  "bugs": {
+    "url": "https://github.com/airalogy/aimd/issues"
+  },
+  "homepage": "https://github.com/airalogy/aimd/tree/main/packages/aimd-renderer#readme",
+  "keywords": [
+    "aimd",
+    "markdown",
+    "renderer",
+    "vue",
+    "html"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./html": {
+      "types": "./src/html/index.ts",
+      "import": "./src/html/index.ts"
+    },
+    "./vue": {
+      "types": "./src/vue/index.ts",
+      "import": "./src/vue/index.ts"
+    },
+    "./styles": {
+      "import": "./src/styles/katex.css",
+      "default": "./src/styles/katex.css"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "build": "vite build && pnpm run build:types",
+    "dev": "vite build --watch",
+    "test": "pnpm run build && node --test ./tests/*.test.mjs"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.17"
+  },
+  "dependencies": {
+    "@airalogy/aimd-core": "workspace:^",
+    "@types/hast": "^3.0.4",
+    "hast-util-to-html": "^9.0.5",
+    "katex": "catalog:",
+    "rehype-katex": "^7.0.1",
+    "rehype-raw": "^7.0.0",
+    "remark-breaks": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "shiki": "^2.5.0",
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "typescript": "5.8.3",
+    "vite": "^7.1.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vue": "^3.5.17"
+  }
+}

package/src/__tests__/renderer.test.ts

@@ -0,0 +1,388 @@
+import { describe, expect, it } from 'vitest'
+
+import { resolveQuizPreviewOptions } from '../common/quiz-preview'
+import {
+  createCustomElementAimdRenderer,
+  parseAndExtract,
+  renderToHtmlSync,
+  renderToVue,
+  createRenderer,
+} from '../common/processor'
+import { getFinalIndent, parseFieldTag } from '../index'
+import { createStepCardRenderer } from '../vue/vue-renderer'
+
+function findVNodeByType(node: any, expectedType: string): any | null {
+  if (!node || typeof node !== 'object') {
+    return null
+  }
+
+  if (node.type === expectedType) {
+    return node
+  }
+
+  const children = Array.isArray(node.children)
+    ? node.children
+    : Array.isArray(node.component?.subTree?.children)
+      ? node.component.subTree.children
+      : []
+
+  for (const child of children) {
+    const match = findVNodeByType(child, expectedType)
+    if (match) {
+      return match
+    }
+  }
+
+  return null
+}
+
+function collectVNodeText(node: any): string {
+  if (node == null) {
+    return ''
+  }
+
+  if (typeof node === 'string') {
+    return node
+  }
+
+  if (Array.isArray(node)) {
+    return node.map((item) => collectVNodeText(item)).join(' ')
+  }
+
+  if (typeof node === 'object') {
+    return collectVNodeText(node.children)
+  }
+
+  return ''
+}
+
+// ---------------------------------------------------------------------------
+// resolveQuizPreviewOptions
+// ---------------------------------------------------------------------------
+
+describe('resolveQuizPreviewOptions', () => {
+  it('defaults to hidden in preview mode', () => {
+    const result = resolveQuizPreviewOptions('preview')
+    expect(result.showAnswers).toBe(false)
+    expect(result.showRubric).toBe(false)
+  })
+
+  it('defaults to revealed in report mode', () => {
+    const result = resolveQuizPreviewOptions('report')
+    expect(result.showAnswers).toBe(true)
+    expect(result.showRubric).toBe(true)
+  })
+
+  it('normalizes timeline to preview', () => {
+    const result = resolveQuizPreviewOptions('timeline')
+    expect(result.showAnswers).toBe(false)
+    expect(result.showRubric).toBe(false)
+  })
+
+  it('respects explicit overrides', () => {
+    const result = resolveQuizPreviewOptions('preview', {
+      showAnswers: true,
+      showRubric: false,
+    })
+    expect(result.showAnswers).toBe(true)
+    expect(result.showRubric).toBe(false)
+  })
+
+  it('overrides report defaults', () => {
+    const result = resolveQuizPreviewOptions('report', {
+      showAnswers: false,
+    })
+    expect(result.showAnswers).toBe(false)
+    expect(result.showRubric).toBe(true)
+  })
+
+  it('handles unknown modes as non-report', () => {
+    const result = resolveQuizPreviewOptions('unknown')
+    expect(result.showAnswers).toBe(false)
+    expect(result.showRubric).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// parseAndExtract
+// ---------------------------------------------------------------------------
+
+describe('parseAndExtract', () => {
+  it('extracts var fields', () => {
+    const fields = parseAndExtract('{{var|temperature: float = 36.5}}')
+    expect(fields.var).toContain('temperature')
+  })
+
+  it('extracts step fields', () => {
+    const fields = parseAndExtract('{{step|wash_hands}}')
+    expect(fields.step.length).toBeGreaterThan(0)
+  })
+
+  it('extracts check fields', () => {
+    const fields = parseAndExtract('{{check|verify_result}}')
+    expect(fields.check.length).toBeGreaterThan(0)
+  })
+
+  it('returns empty fields for plain markdown', () => {
+    const fields = parseAndExtract('# Hello World\n\nJust some text.')
+    expect(fields.var).toHaveLength(0)
+    expect(fields.step).toHaveLength(0)
+    expect(fields.quiz).toHaveLength(0)
+  })
+
+  it('extracts multiple fields from mixed content', () => {
+    const content = [
+      '{{var|name: str = "Alice"}}',
+      '{{var|age: int = 25}}',
+      '{{step|step1}}',
+    ].join('\n\n')
+    const fields = parseAndExtract(content)
+    expect(fields.var).toContain('name')
+    expect(fields.var).toContain('age')
+    expect(fields.step.length).toBeGreaterThan(0)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// renderToHtmlSync
+// ---------------------------------------------------------------------------
+
+describe('renderToHtmlSync', () => {
+  it('renders plain markdown to HTML', () => {
+    const { html } = renderToHtmlSync('# Hello')
+    expect(html).toContain('<h1')
+    expect(html).toContain('Hello')
+  })
+
+  it('renders AIMD var fields', () => {
+    const { html, fields } = renderToHtmlSync('{{var|temperature}}')
+    expect(fields.var).toContain('temperature')
+    expect(html).toContain('temperature')
+  })
+
+  it('returns extracted fields alongside HTML', () => {
+    const { fields } = renderToHtmlSync('{{step|wash}} and {{check|verify}}')
+    expect(fields.step.length).toBeGreaterThan(0)
+    expect(fields.check.length).toBeGreaterThan(0)
+  })
+
+  it('renders GFM tables', () => {
+    const content = '| A | B |\n|---|---|\n| 1 | 2 |'
+    const { html } = renderToHtmlSync(content)
+    expect(html).toContain('<table')
+    expect(html).toContain('<td')
+  })
+
+  it('supports host custom element renderers for AIMD nodes', () => {
+    const { html } = renderToHtmlSync(
+      "{{step|verify, 2, title='Verify Output', subtitle='Cross-check', check=True, result=True}}\n\nStep body content.",
+      {
+        groupStepBodies: true,
+        aimdElementRenderers: {
+          step: createCustomElementAimdRenderer('step-card', (node) => {
+            const stepNode = node as any
+            return {
+              'step-id': stepNode.id,
+              'step-number': stepNode.step,
+              title: stepNode.title,
+              subtitle: stepNode.subtitle,
+              level: String(stepNode.level),
+              'has-check': stepNode.check ? 'true' : undefined,
+              'is-result': stepNode.result ? 'true' : undefined,
+            }
+          }, {
+            container: true,
+            stripDefaultChildren: true,
+          }),
+        },
+      },
+    )
+
+    expect(html).toContain('<step-card')
+    expect(html).toContain('step-id="verify"')
+    expect(html).toContain('step-number="1"')
+    expect(html).toContain('title="Verify Output"')
+    expect(html).toContain('subtitle="Cross-check"')
+    expect(html).toContain('has-check="true"')
+    expect(html).toContain('is-result="true"')
+    expect(html).toContain('data-aimd-step-body="true"')
+    expect(html).toContain('Step body content.')
+  })
+
+  it('stops grouped step bodies at headings and dividers', () => {
+    const { html } = renderToHtmlSync(
+      [
+        '## Section',
+        '',
+        "{{step|step1, title='Step One'}}",
+        '',
+        'Body one.',
+        '',
+        '---',
+        '',
+        '## Next',
+        '',
+        '{{step|step2}}',
+        '',
+        'Body two.',
+      ].join('\n'),
+      {
+        groupStepBodies: true,
+        aimdElementRenderers: {
+          step: createCustomElementAimdRenderer('step-card', (node) => ({
+            'step-id': node.id,
+            'step-number': (node as any).step,
+            title: (node as any).title || node.id,
+          }), {
+            container: true,
+            stripDefaultChildren: true,
+          }),
+        },
+      },
+    )
+
+    expect(html).toContain('<h2>Section</h2>')
+    expect(html).toContain('<hr>')
+    expect(html).toContain('<h2>Next</h2>')
+    expect(html).toContain('step-id="step1"')
+    expect(html).toContain('step-id="step2"')
+    expect(html).toContain('Body one.')
+    expect(html).toContain('Body two.')
+    expect(html.indexOf('Body one.')).toBeLessThan(html.indexOf('<hr>'))
+    expect(html.indexOf('<hr>')).toBeLessThan(html.indexOf('step-id="step2"'))
+  })
+
+  it('can lift block-style var types out of inline paragraphs', () => {
+    const { html } = renderToHtmlSync(
+      'Experiment summary: {{var|summary: AiralogyMarkdown}}',
+      { blockVarTypes: ['AiralogyMarkdown'] },
+    )
+
+    expect(html).toContain('<p>Experiment summary: </p>')
+    expect(html).toContain('<div class="aimd-field aimd-field--var aimd-block-var"')
+    expect(html).not.toContain('<p>Experiment summary: <span')
+  })
+
+  it('can lift block-style var types out of tight list items', () => {
+    const { html } = renderToHtmlSync(
+      '- Experiment summary: {{var|summary: AiralogyMarkdown}}',
+      { blockVarTypes: ['AiralogyMarkdown'] },
+    )
+
+    expect(html).toContain('<li><p>Experiment summary: </p><div class="aimd-field aimd-field--var aimd-block-var"')
+    expect(html).not.toContain('<li>Experiment summary: <span')
+  })
+})
+
+describe('renderToVue', () => {
+  it('renders host-ready step cards with grouped body content', async () => {
+    const { nodes } = await renderToVue(
+      "{{step|verify, 2, title='Verify Output', subtitle='Cross-check', check=True}}\n\nStep body content.",
+      {
+        groupStepBodies: true,
+        aimdRenderers: {
+          step: createStepCardRenderer(),
+        },
+      },
+    )
+
+    expect(nodes).toHaveLength(1)
+    const card = findVNodeByType(nodes[0], 'article') as any
+    expect(card).toBeTruthy()
+    expect(card.props.class).toContain('aimd-step-card')
+    expect(card.props['data-aimd-step-id']).toBe('verify')
+    const header = card.children[0] as any
+    const leftCluster = header.children[0] as any
+    const contentStack = leftCluster.children[1] as any
+    expect(contentStack.children[1].children).toBe('Verify Output')
+    expect(contentStack.children[2].children).toBe('Cross-check')
+    const body = card.children[1] as any
+    expect(body.props.class).toContain('aimd-step-card__body')
+    expect(collectVNodeText(body)).toContain('Step body content.')
+  })
+
+  it('groups inline check body copy into the check renderer when enabled', async () => {
+    const { nodes } = await renderToVue(
+      '{{check|measurement_complete, checked_message="量子测量完成"}} 确认所有孔位的量子共振值已记录完毕。',
+      {
+        groupCheckBodies: true,
+        aimdRenderers: {
+          check: (node, _ctx, children) => ({
+            type: 'section',
+            props: { 'data-test-check-id': node.id },
+            children,
+          }) as any,
+        },
+      },
+    )
+
+    expect(nodes).toHaveLength(1)
+    const card = findVNodeByType(nodes[0], 'section') as any
+    expect(card).toBeTruthy()
+    expect(card.props['data-test-check-id']).toBe('measurement_complete')
+    expect(collectVNodeText(card)).toContain('确认所有孔位的量子共振值已记录完毕')
+    expect(collectVNodeText(card)).not.toContain('measurement_complete')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// createRenderer
+// ---------------------------------------------------------------------------
+
+describe('createRenderer', () => {
+  it('creates a reusable renderer', () => {
+    const renderer = createRenderer()
+    expect(renderer).toHaveProperty('toHtml')
+    expect(renderer).toHaveProperty('toVue')
+    expect(renderer).toHaveProperty('extractFields')
+  })
+
+  it('renderer.extractFields works', () => {
+    const renderer = createRenderer()
+    const fields = renderer.extractFields('{{var|x}}')
+    expect(fields.var).toContain('x')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// getFinalIndent
+// ---------------------------------------------------------------------------
+
+describe('getFinalIndent', () => {
+  it('returns simple index for level 1', () => {
+    expect(getFinalIndent({ sequence: 0, level: 1 })).toBe('1')
+    expect(getFinalIndent({ sequence: 4, level: 1 })).toBe('5')
+  })
+
+  it('builds hierarchical indent from parent chain', () => {
+    const parent = { sequence: 0, level: 1, parent: undefined }
+    expect(getFinalIndent({ parent, sequence: 1, level: 2 })).toBe('1.2')
+  })
+
+  it('handles deeply nested parents', () => {
+    const grandparent = { sequence: 0, level: 1, parent: undefined }
+    const parent = { sequence: 2, level: 2, parent: grandparent }
+    expect(getFinalIndent({ parent, sequence: 0, level: 3 })).toBe('1.3.1')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// parseFieldTag
+// ---------------------------------------------------------------------------
+
+describe('parseFieldTag', () => {
+  it('parses simple var tag', () => {
+    const result = parseFieldTag('var|temperature')
+    expect(result).toEqual([{ type: 'var', name: 'temperature' }])
+  })
+
+  it('parses step tag', () => {
+    const result = parseFieldTag('step|wash_hands')
+    expect(result).toEqual([{ type: 'step', name: 'wash_hands' }])
+  })
+
+  it('parses var_table tag', () => {
+    const result = parseFieldTag('var_table|measurements|col1,col2')
+    expect(result[0].type).toBe('var_table')
+  })
+})

package/src/common/annotateStepReferences.ts

@@ -0,0 +1,110 @@
+import type { Element, Root as HastRoot } from "hast"
+import type { ExtractedAimdFields } from "@airalogy/aimd-core/types"
+import type { AimdNode } from "@airalogy/aimd-core/types"
+import type { AimdRendererOptions } from "./processor"
+import { createAimdRendererMessages } from "../locales"
+
+// ---------------------------------------------------------------------------
+// Step sequence map
+// ---------------------------------------------------------------------------
+
+function buildStepSequenceMap(fields: ExtractedAimdFields): Map<string, string> {
+  const sequenceMap = new Map<string, string>()
+
+  for (const step of fields.step_hierarchy || []) {
+    if (typeof step.id === "string" && step.id.trim() && typeof step.step === "string" && step.step.trim()) {
+      sequenceMap.set(step.id, step.step)
+    }
+  }
+
+  return sequenceMap
+}
+
+// ---------------------------------------------------------------------------
+// HAST annotation pass
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk a HAST tree and inject the resolved step-sequence numbers into every
+ * `ref_step` element so the rendered output shows e.g. "Step 2.1" instead of
+ * the raw id.
+ */
+export function annotateStepReferenceSequence(
+  tree: HastRoot,
+  fields: ExtractedAimdFields,
+  options: AimdRendererOptions,
+): void {
+  const stepSequenceMap = buildStepSequenceMap(fields)
+  if (stepSequenceMap.size === 0) {
+    return
+  }
+
+  const messages = createAimdRendererMessages(options.locale, options.messages)
+
+  const visitNode = (node: HastRoot | Element): void => {
+    if (node.type === "element") {
+      const element = node as Element
+      const aimdType = element.properties?.["data-aimd-type"] || element.properties?.dataAimdType
+
+      if (aimdType === "ref_step") {
+        const refTarget = element.properties?.["data-aimd-id"] || element.properties?.dataAimdId
+        if (typeof refTarget === "string") {
+          const stepSequence = stepSequenceMap.get(refTarget)
+          if (stepSequence) {
+            element.properties["data-aimd-step-sequence"] = stepSequence
+            element.properties.title = refTarget
+
+            const aimdData = (element.data as { aimd?: AimdNode } | undefined)?.aimd
+            if (aimdData) {
+              ;(aimdData as any).stepSequence = stepSequence
+            }
+
+            const jsonData = element.properties["data-aimd-json"]
+            if (typeof jsonData === "string") {
+              try {
+                const parsed = JSON.parse(jsonData) as Record<string, unknown>
+                parsed.stepSequence = stepSequence
+                element.properties["data-aimd-json"] = JSON.stringify(parsed)
+              }
+              catch {
+                // Ignore malformed fallback JSON and keep runtime metadata only.
+              }
+            }
+
+            element.children = [{
+              type: "element",
+              tagName: "span",
+              properties: { className: ["aimd-ref__content"] },
+              children: [{
+                type: "element",
+                tagName: "span",
+                properties: { className: ["aimd-field", "aimd-field--step", "aimd-field--readonly"] },
+                children: [{
+                  type: "element",
+                  tagName: "span",
+                  properties: { className: ["research-step__sequence"] },
+                  children: [{ type: "text", value: messages.step.reference(stepSequence) }],
+                } as Element],
+              } as Element],
+            } as Element]
+          }
+        }
+      }
+
+      for (const child of element.children || []) {
+        if (child.type === "element") {
+          visitNode(child)
+        }
+      }
+      return
+    }
+
+    for (const child of node.children) {
+      if (child.type === "element") {
+        visitNode(child)
+      }
+    }
+  }
+
+  visitNode(tree)
+}