metanorma-document 0.2.9 → 0.2.12

data/frontend/src/types/__tests__/rendering-contract.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect } from 'vitest'
+import {
+  MARK_TYPES,
+  SECTION_TYPES,
+  BLOCK_TYPES,
+  BLOCK_NODE_TYPES,
+  SECTION_NODE_TYPES,
+  ALL_NODE_TYPES,
+} from '../rendering-contract'
+import { getBlockComponent } from '../../components/blocks'
+import { SECTION_TYPES as UI_SECTION_TYPES, SECTION_META } from '../../utils/typeMetadata'
+import ParagraphBlock from '../../components/blocks/ParagraphBlock.vue'
+import AdmonitionBlock from '../../components/blocks/AdmonitionBlock.vue'
+import TableBlock from '../../components/blocks/TableBlock.vue'
+import FigureBlock from '../../components/blocks/FigureBlock.vue'
+import SourcecodeBlock from '../../components/blocks/SourcecodeBlock.vue'
+import NoteBlock from '../../components/blocks/NoteBlock.vue'
+import ExampleBlock from '../../components/blocks/ExampleBlock.vue'
+import ListBlocks from '../../components/blocks/ListBlocks.vue'
+import QuoteBlock from '../../components/blocks/QuoteBlock.vue'
+import ReviewBlock from '../../components/blocks/ReviewBlock.vue'
+import FootnotesBlock from '../../components/blocks/FootnotesBlock.vue'
+import FallbackBlock from '../../components/blocks/FallbackBlock.vue'
+
+describe('rendering-contract', () => {
+  describe('MARK_TYPES', () => {
+    it('covers all marks produced by Ruby Mirror::Mark subclasses', () => {
+      const expected = [
+        'emphasis', 'strong', 'subscript', 'superscript',
+        'code', 'underline', 'strike', 'smallcap',
+        'link', 'xref', 'eref', 'footnote',
+        'stem', 'concept', 'bcp14', 'span',
+      ]
+      for (const mark of expected) {
+        expect(MARK_TYPES).toContain(mark)
+      }
+    })
+
+    it('has no duplicates', () => {
+      expect(MARK_TYPES.length).toBe(new Set(MARK_TYPES).size)
+    })
+  })
+
+  describe('SECTION_TYPES', () => {
+    it('matches UI typeMetadata SECTION_TYPES set', () => {
+      for (const t of SECTION_TYPES) {
+        expect(UI_SECTION_TYPES.has(t), `contract section type "${t}" missing from UI SECTION_TYPES`).toBe(true)
+      }
+    })
+
+    it('has metadata for every section type', () => {
+      for (const t of SECTION_TYPES) {
+        expect(SECTION_META[t], `SECTION_META missing for "${t}"`).toBeDefined()
+      }
+    })
+
+    it('every section type has tag and headingTag', () => {
+      for (const t of SECTION_TYPES) {
+        const meta = SECTION_META[t]
+        expect(meta.tag, `${t} should have tag`).toMatch(/^(section|article)$/)
+        expect(meta.headingTag, `${t} should have headingTag`).toBeTruthy()
+      }
+    })
+  })
+
+  describe('BLOCK_TYPES', () => {
+    it('every block type has a registered Vue component', () => {
+      for (const spec of BLOCK_TYPES) {
+        const component = getBlockComponent(spec.nodeType)
+        expect(component).not.toBe(FallbackBlock)
+        expect(component, `block type "${spec.nodeType}" should have a component`).toBeDefined()
+      }
+    })
+
+    it('every block type spec has required fields', () => {
+      for (const spec of BLOCK_TYPES) {
+        expect(spec.nodeType, 'nodeType should be set').toBeTruthy()
+        expect(spec.rubyCssClass, `${spec.nodeType} should have rubyCssClass`).toBeTruthy()
+        expect(spec.children, `${spec.nodeType} should define children kind`).toMatch(/^(inline|block|mixed|none)$/)
+        expect(Array.isArray(spec.attrs), `${spec.nodeType} attrs should be array`).toBe(true)
+      }
+    })
+  })
+
+  describe('BLOCK_NODE_TYPES set', () => {
+    it('contains all node types from BLOCK_TYPES', () => {
+      for (const spec of BLOCK_TYPES) {
+        expect(BLOCK_NODE_TYPES.has(spec.nodeType)).toBe(true)
+      }
+    })
+
+    it('does not contain section types', () => {
+      for (const t of SECTION_TYPES) {
+        expect(BLOCK_NODE_TYPES.has(t), `section type "${t}" should not be in BLOCK_NODE_TYPES`).toBe(false)
+      }
+    })
+  })
+
+  describe('SECTION_NODE_TYPES set', () => {
+    it('contains all section types', () => {
+      for (const t of SECTION_TYPES) {
+        expect(SECTION_NODE_TYPES.has(t)).toBe(true)
+      }
+    })
+  })
+
+  describe('ALL_NODE_TYPES set', () => {
+    it('includes structural node types', () => {
+      expect(ALL_NODE_TYPES.has('doc')).toBe(true)
+      expect(ALL_NODE_TYPES.has('text')).toBe(true)
+      expect(ALL_NODE_TYPES.has('soft_break')).toBe(true)
+      expect(ALL_NODE_TYPES.has('footnote_marker')).toBe(true)
+    })
+
+    it('includes table structural types', () => {
+      expect(ALL_NODE_TYPES.has('table_head')).toBe(true)
+      expect(ALL_NODE_TYPES.has('table_body')).toBe(true)
+      expect(ALL_NODE_TYPES.has('table_row')).toBe(true)
+      expect(ALL_NODE_TYPES.has('table_cell')).toBe(true)
+    })
+
+    it('includes list structural types', () => {
+      expect(ALL_NODE_TYPES.has('list_item')).toBe(true)
+      expect(ALL_NODE_TYPES.has('dt')).toBe(true)
+      expect(ALL_NODE_TYPES.has('dd')).toBe(true)
+    })
+
+    it('covers all section and block types', () => {
+      for (const t of SECTION_TYPES) {
+        expect(ALL_NODE_TYPES.has(t), `missing section type ${t}`).toBe(true)
+      }
+      for (const spec of BLOCK_TYPES) {
+        expect(ALL_NODE_TYPES.has(spec.nodeType), `missing block type ${spec.nodeType}`).toBe(true)
+      }
+    })
+  })
+
+  describe('block component mapping coverage', () => {
+    const expectedMappings: Record<string, any> = {
+      paragraph: ParagraphBlock,
+      admonition: AdmonitionBlock,
+      note: NoteBlock,
+      example: ExampleBlock,
+      table: TableBlock,
+      figure: FigureBlock,
+      image: FigureBlock,
+      sourcecode: SourcecodeBlock,
+      formula: SourcecodeBlock,
+      bullet_list: ListBlocks,
+      ordered_list: ListBlocks,
+      dl: ListBlocks,
+      quote: QuoteBlock,
+      review: ReviewBlock,
+      footnotes: FootnotesBlock,
+      floating_title: ParagraphBlock,
+    }
+
+    for (const [type, expected] of Object.entries(expectedMappings)) {
+      it(`maps "${type}" to ${expected.__name || expected.name}`, () => {
+        expect(getBlockComponent(type)).toBe(expected)
+      })
+    }
+
+    it('returns FallbackBlock for unknown types', () => {
+      expect(getBlockComponent('unknown_block')).toBe(FallbackBlock)
+    })
+
+    it('returns FallbackBlock for empty string', () => {
+      expect(getBlockComponent('')).toBe(FallbackBlock)
+    })
+  })
+})

data/frontend/src/types/rendering-contract.ts

@@ -0,0 +1,209 @@
+/**
+ * Rendering contract between Ruby HtmlRenderer and Vue MirrorRenderer.
+ *
+ * Single source of truth for the mirror node format.
+ * Both renderers must handle every node type listed here.
+ *
+ * When adding a new block type:
+ *   1. Add it to BLOCK_TYPES below
+ *   2. Implement render_{type} in Ruby HtmlRenderer
+ *   3. Add a Vue block component and register it in blocks/index.ts
+ *   4. Update the cross-validation spec
+ */
+
+// ── Inline mark types ──────────────────────────────────────────────
+
+export const MARK_TYPES = [
+  'emphasis',
+  'strong',
+  'subscript',
+  'superscript',
+  'code',
+  'underline',
+  'strike',
+  'smallcap',
+  'link',
+  'xref',
+  'eref',
+  'footnote',
+  'stem',
+  'concept',
+  'bcp14',
+  'span',
+] as const
+
+export type MarkType = (typeof MARK_TYPES)[number]
+
+// ── Section types (rendered by ClauseBlock) ───────────────────────
+
+export const SECTION_TYPES = [
+  'clause',
+  'annex',
+  'content_section',
+  'abstract',
+  'foreword',
+  'introduction',
+  'acknowledgements',
+  'terms',
+  'definitions',
+  'references',
+  'bibliography',
+  'preface',
+  'sections',
+] as const
+
+export type SectionType = (typeof SECTION_TYPES)[number]
+
+// ── Block type specification ───────────────────────────────────────
+
+export type ChildrenKind = 'inline' | 'block' | 'mixed' | 'none'
+
+export interface BlockTypeSpec {
+  /** Mirror node type string */
+  nodeType: string
+  /** Primary CSS class used by Ruby HtmlRenderer */
+  rubyCssClass: string
+  /** Expected attrs keys (excluding id which is universal) */
+  attrs: string[]
+  /** What kind of children this node contains */
+  children: ChildrenKind
+}
+
+export const BLOCK_TYPES: BlockTypeSpec[] = [
+  // ── Prose ──
+  {
+    nodeType: 'paragraph',
+    rubyCssClass: 'mn-paragraph',
+    attrs: ['id'],
+    children: 'inline',
+  },
+  {
+    nodeType: 'floating_title',
+    rubyCssClass: 'mn-floating-title',
+    attrs: ['id', 'title', 'level'],
+    children: 'none',
+  },
+  {
+    nodeType: 'quote',
+    rubyCssClass: 'mn-quote',
+    attrs: ['id'],
+    children: 'block',
+  },
+  {
+    nodeType: 'review',
+    rubyCssClass: 'mn-review',
+    attrs: ['id', 'review_type', 'reviewer', 'date'],
+    children: 'block',
+  },
+
+  // ── Code ──
+  {
+    nodeType: 'sourcecode',
+    rubyCssClass: 'mn-sourcecode',
+    attrs: ['id', 'language', 'text', 'title'],
+    children: 'none',
+  },
+
+  // ── Admonition ──
+  {
+    nodeType: 'admonition',
+    rubyCssClass: 'mn-admonition',
+    attrs: ['id', 'type', 'title'],
+    children: 'block',
+  },
+  {
+    nodeType: 'note',
+    rubyCssClass: 'mn-note',
+    attrs: ['id', 'type', 'title'],
+    children: 'block',
+  },
+  {
+    nodeType: 'example',
+    rubyCssClass: 'mn-example',
+    attrs: ['id', 'type', 'title'],
+    children: 'block',
+  },
+
+  // ── Media ──
+  {
+    nodeType: 'figure',
+    rubyCssClass: 'mn-figure',
+    attrs: ['id', 'title'],
+    children: 'block',
+  },
+  {
+    nodeType: 'image',
+    rubyCssClass: 'mn-image',
+    attrs: ['id', 'src', 'alt', 'title'],
+    children: 'none',
+  },
+
+  // ── Table ──
+  {
+    nodeType: 'table',
+    rubyCssClass: 'mn-table',
+    attrs: ['id', 'title'],
+    children: 'block',
+  },
+
+  // ── Lists ──
+  {
+    nodeType: 'ordered_list',
+    rubyCssClass: 'mn-ordered-list',
+    attrs: ['id'],
+    children: 'block',
+  },
+  {
+    nodeType: 'bullet_list',
+    rubyCssClass: 'mn-bullet-list',
+    attrs: ['id'],
+    children: 'block',
+  },
+  {
+    nodeType: 'dl',
+    rubyCssClass: 'mn-definition-list',
+    attrs: ['id'],
+    children: 'block',
+  },
+
+  // ── Formula ──
+  {
+    nodeType: 'formula',
+    rubyCssClass: 'mn-formula',
+    attrs: ['id', 'text'],
+    children: 'none',
+  },
+
+  // ── Footnotes ──
+  {
+    nodeType: 'footnotes',
+    rubyCssClass: 'mn-footnotes',
+    attrs: [],
+    children: 'block',
+  },
+]
+
+// ── Derived lookup maps ────────────────────────────────────────────
+
+/** All block node types handled by the block component registry */
+export const BLOCK_NODE_TYPES: Set<string> = new Set(BLOCK_TYPES.map((b) => b.nodeType))
+
+/** All section node types handled by ClauseBlock */
+export const SECTION_NODE_TYPES: Set<string> = new Set(SECTION_TYPES)
+
+/** Complete set of all rendered node types */
+export const ALL_NODE_TYPES: Set<string> = new Set([
+  ...SECTION_TYPES,
+  ...BLOCK_TYPES.map((b) => b.nodeType),
+  'doc',
+  'soft_break',
+  'text',
+  'footnote_marker',
+  'list_item',
+  'dt',
+  'dd',
+  'table_head',
+  'table_body',
+  'table_row',
+  'table_cell',
+])

data/frontend/src/utils/__tests__/typeMetadata.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest'
+import { SECTION_TYPES, isSectionType, SECTION_META, getTypeLabel, getTypeBadgeClass } from '../typeMetadata'
+import { SECTION_TYPES as CONTRACT_SECTIONS } from '../../types/rendering-contract'
+
+describe('isSectionType', () => {
+  it('returns true for section-like types', () => {
+    const types = ['clause', 'annex', 'content_section', 'abstract', 'foreword',
+      'introduction', 'acknowledgements', 'terms', 'definitions',
+      'references', 'bibliography', 'preface', 'sections']
+
+    for (const t of types) {
+      expect(isSectionType(t)).toBe(true)
+    }
+  })
+
+  it('returns false for non-section types', () => {
+    expect(isSectionType('paragraph')).toBe(false)
+    expect(isSectionType('sourcecode')).toBe(false)
+    expect(isSectionType('figure')).toBe(false)
+    expect(isSectionType('table')).toBe(false)
+    expect(isSectionType('admonition')).toBe(false)
+    expect(isSectionType('bullet_list')).toBe(false)
+  })
+
+  it('matches rendering contract SECTION_TYPES', () => {
+    for (const t of CONTRACT_SECTIONS) {
+      expect(isSectionType(t), `contract type "${t}" not in UI SECTION_TYPES`).toBe(true)
+    }
+  })
+})
+
+describe('SECTION_META', () => {
+  it('defines metadata for all section types', () => {
+    for (const type of SECTION_TYPES) {
+      expect(SECTION_META[type], `${type} should have SECTION_META entry`).toBeDefined()
+    }
+  })
+
+  it('all entries have tag and headingTag', () => {
+    for (const [type, meta] of Object.entries(SECTION_META)) {
+      expect(meta.tag, `${type} should have tag`).toMatch(/^section$/)
+      expect(meta.headingTag, `${type} should have headingTag`).toBeTruthy()
+      expect(meta.headingClass, `${type} should have headingClass`).toBeTruthy()
+    }
+  })
+
+  it('clause uses h2', () => {
+    expect(SECTION_META.clause.headingTag).toBe('h2')
+  })
+
+  it('annex uses h2', () => {
+    expect(SECTION_META.annex.headingTag).toBe('h2')
+  })
+
+  it('preface uses h1', () => {
+    expect(SECTION_META.preface.headingTag).toBe('h1')
+  })
+
+  it('sections uses h1', () => {
+    expect(SECTION_META.sections.headingTag).toBe('h1')
+  })
+})
+
+describe('getTypeLabel', () => {
+  it('returns non-empty for major types', () => {
+    expect(getTypeLabel('clause')).toBeTruthy()
+    expect(getTypeLabel('annex')).toBeTruthy()
+    expect(getTypeLabel('terms')).toBeTruthy()
+    expect(getTypeLabel('references')).toBeTruthy()
+  })
+
+  it('returns empty for unknown', () => {
+    expect(getTypeLabel('foobar')).toBe('')
+  })
+})
+
+describe('getTypeBadgeClass', () => {
+  it('returns badge-neutral for unknown', () => {
+    expect(getTypeBadgeClass('foobar')).toBe('badge-neutral')
+  })
+
+  it('returns different classes for different types', () => {
+    const classes = new Set([
+      getTypeBadgeClass('clause'),
+      getTypeBadgeClass('annex'),
+      getTypeBadgeClass('terms'),
+    ])
+    expect(classes.size).toBeGreaterThan(1)
+  })
+
+  it('returns badge-accent for clause', () => {
+    expect(getTypeBadgeClass('clause')).toBe('badge-accent')
+  })
+
+  it('returns badge-info for terms', () => {
+    expect(getTypeBadgeClass('terms')).toBe('badge-info')
+  })
+
+  it('returns badge-reference for references', () => {
+    expect(getTypeBadgeClass('references')).toBe('badge-reference')
+  })
+})

data/frontend/src/utils/typeMetadata.ts

@@ -0,0 +1,121 @@
+/**
+ * Canonical metadata for Metanorma section/block types.
+ */
+
+export const SECTION_TYPES = new Set([
+  'clause', 'annex', 'content_section', 'abstract', 'foreword',
+  'introduction', 'acknowledgements', 'terms', 'definitions',
+  'references', 'bibliography', 'preface', 'sections',
+])
+
+export function isSectionType(type: string): boolean {
+  return SECTION_TYPES.has(type)
+}
+
+export interface SectionMeta {
+  tag: 'section' | 'article'
+  headingTag: string
+  headingClass: string
+  noAnchor?: boolean
+  noNumbering?: boolean
+}
+
+export const SECTION_META: Record<string, SectionMeta> = {
+  clause: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  annex: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  content_section: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  abstract: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-lg font-semibold mb-3 italic',
+  },
+  foreword: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  introduction: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  acknowledgements: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  terms: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  definitions: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  references: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  bibliography: {
+    tag: 'section',
+    headingTag: 'h2',
+    headingClass: 'text-xl font-semibold mb-3',
+  },
+  preface: {
+    tag: 'section',
+    headingTag: 'h1',
+    headingClass: 'text-2xl font-bold mb-4',
+  },
+  sections: {
+    tag: 'section',
+    headingTag: 'h1',
+    headingClass: 'text-2xl font-bold mb-4',
+  },
+}
+
+export function getTypeBadgeClass(type: string): string {
+  switch (type) {
+    case 'clause': return 'badge-accent'
+    case 'annex': return 'badge-warning'
+    case 'terms': return 'badge-info'
+    case 'definitions': return 'badge-info'
+    case 'references': return 'badge-reference'
+    case 'bibliography': return 'badge-reference'
+    case 'abstract': return 'badge-neutral'
+    case 'foreword': return 'badge-neutral'
+    case 'introduction': return 'badge-neutral'
+    case 'acknowledgements': return 'badge-neutral'
+    default: return 'badge-neutral'
+  }
+}
+
+export function getTypeLabel(type: string): string {
+  switch (type) {
+    case 'clause': return '§'
+    case 'annex': return 'Annex'
+    case 'terms': return 'Terms'
+    case 'definitions': return 'Def'
+    case 'references': return 'Ref'
+    case 'bibliography': return 'Bib'
+    case 'abstract': return 'Abs'
+    case 'foreword': return 'Fwd'
+    case 'introduction': return 'Intro'
+    case 'acknowledgements': return 'Ack'
+    default: return ''
+  }
+}

data/frontend/tailwind.config.js

@@ -0,0 +1,18 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    './src/**/*.{vue,ts,html}',
+  ],
+  darkMode: 'class',
+  theme: {
+    extend: {
+      colors: {
+        cream: '#faf8f5',
+        charcoal: '#2d2d2d',
+        teal: '#0d9488',
+        navy: '#1e3a5f'
+      }
+    }
+  },
+  plugins: [],
+}