@puredesktop/puredesktop-ui-bridge 1.0.0-beta.1

package/src/bridge/pureRender/normalize.ts

@@ -0,0 +1,682 @@
+import { escapeHtml } from '../printDocument.js'
+import type {
+  PureRenderMetadata,
+  PureRenderNormalizeResult,
+  PureRenderOptions,
+  PureRenderProfile,
+  PureRenderValidationError,
+} from './types.js'
+
+const ALLOWED_DATA_TYPES = new Set([
+  'abstract',
+  'part',
+  'chapter',
+  'appendix',
+  'references',
+  'acknowledgments',
+  'toc',
+  'frontmatter',
+  'backmatter',
+  'footnotes',
+  'endnotes',
+])
+
+const XREF_SELECTORS = [
+  'a.xref-fig[href^="#"]',
+  'a.xref-tbl[href^="#"]',
+  'a.xref-eq[href^="#"]',
+  'a.xref-sec[href^="#"]',
+  'a.fnref[href^="#"]',
+]
+
+export function normalizePureRenderHtml(options: {
+  html: string
+  profile: PureRenderProfile
+  metadata?: PureRenderMetadata
+  options?: PureRenderOptions
+}): PureRenderNormalizeResult {
+  const doc = parseHtml(options.html)
+  const errors: PureRenderValidationError[] = []
+
+  stripEditorTablePresentation(doc)
+  collectHardErrors(doc, errors)
+  stripEmptyParagraphs(doc)
+  wrapBareTables(doc)
+  normalizeReferenceableBlocks(doc)
+  normalizeCrossReferenceLinks(doc)
+  normalizeFootnotes(doc)
+  normalizeInlineFootnoteMarkers(doc)
+  normalizeHeadings(doc)
+  normalizeSections(doc, errors)
+  assignMissingIds(doc)
+  materializeReferenceLabels(doc, options.profile)
+  normalizeCitationLinks(doc)
+  validateCrossReferences(doc, errors)
+
+  const article = buildCanonicalArticle(doc, options.metadata)
+  const lang = article.getAttribute('lang')?.trim() || 'en'
+  article.setAttribute('lang', lang)
+  if (options.options?.variant) {
+    article.setAttribute('data-variant', options.options.variant)
+  }
+
+  const title =
+    options.metadata?.title?.trim() ||
+    article.querySelector('.doc-title')?.textContent?.trim() ||
+    titleFromDocument(doc.body.innerHTML) ||
+    'Document'
+
+  return { html: article.outerHTML, title, errors }
+}
+
+function stripEditorTablePresentation(doc: Document): void {
+  doc.body.querySelectorAll('table,colgroup,col').forEach(element => {
+    element.removeAttribute('style')
+  })
+}
+
+function normalizeFootnotes(doc: Document): void {
+  const notes = new Map<string, string>()
+  doc.body
+    .querySelectorAll<HTMLElement>(
+      'section.footnotes, aside.footnotes, section[data-type="footnotes"]',
+    )
+    .forEach(container => {
+      container.querySelectorAll<HTMLElement>('li[id]').forEach(item => {
+        const id = item.id.trim()
+        if (!id) return
+        const clone = item.cloneNode(true) as HTMLElement
+        clone
+          .querySelectorAll<HTMLAnchorElement>(
+            'a[href^="#fnref"],a[rev="footnote"]',
+          )
+          .forEach(backlink => backlink.remove())
+        notes.set(id, clone.innerHTML.trim())
+      })
+      container.remove()
+    })
+
+  if (notes.size === 0) return
+
+  doc.body.querySelectorAll<HTMLAnchorElement>('a[href^="#"]').forEach(link => {
+    const targetId = link.getAttribute('href')?.slice(1)
+    const noteHtml = targetId ? notes.get(targetId) : undefined
+    if (!targetId || !noteHtml) return
+    link.classList.add('fnref')
+    if (!link.textContent?.trim()) {
+      link.textContent = String(noteIndexFromId(targetId) ?? notes.size)
+    }
+    if (doc.getElementById(targetId)) return
+    const note = doc.createElement('span')
+    note.className = 'fn'
+    note.id = targetId
+    note.innerHTML = noteHtml
+    const wrapper = link.closest('sup') ?? link
+    wrapper.replaceWith(note)
+  })
+}
+
+function normalizeInlineFootnoteMarkers(doc: Document): void {
+  doc.body.querySelectorAll<HTMLElement>('.fn[id]').forEach(note => {
+    const id = note.id.trim()
+    if (!id) return
+    doc.body
+      .querySelectorAll<HTMLAnchorElement>(
+        `a.fnref[href="#${cssEscape(id)}"],a[href="#${cssEscape(id)}"]`,
+      )
+      .forEach(link => {
+        const wrapper = link.closest('sup') ?? link
+        if (wrapper.nextElementSibling === note) {
+          wrapper.remove()
+        }
+      })
+  })
+}
+
+function cssEscape(value: string): string {
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
+    return CSS.escape(value)
+  }
+  return value.replace(/["\\]/g, '\\$&')
+}
+
+function noteIndexFromId(id: string): number | undefined {
+  const match = /(\d+)$/.exec(id)
+  return match ? Number.parseInt(match[1], 10) : undefined
+}
+
+function parseHtml(html: string): Document {
+  return new DOMParser().parseFromString(html || '', 'text/html')
+}
+
+function collectHardErrors(
+  doc: Document,
+  errors: PureRenderValidationError[],
+): void {
+  doc.body.querySelectorAll('[style]').forEach(element => {
+    errors.push({
+      code: 'forbidden-style-attribute',
+      message: `<${element.tagName.toLowerCase()}> includes a style attribute`,
+    })
+  })
+  doc.body
+    .querySelectorAll('script, style, link, font, center')
+    .forEach(element => {
+      errors.push({
+        code: 'forbidden-element',
+        message: `<${element.tagName.toLowerCase()}> is not allowed in print content`,
+      })
+    })
+  doc.body.querySelectorAll('h1').forEach(element => {
+    if (!element.classList.contains('doc-title')) {
+      errors.push({
+        code: 'invalid-h1',
+        message: 'Only the canonical .doc-title may use h1',
+      })
+    }
+  })
+}
+
+function stripEmptyParagraphs(doc: Document): void {
+  doc.body.querySelectorAll('p').forEach(paragraph => {
+    if (!paragraph.textContent?.trim() && paragraph.children.length === 0) {
+      paragraph.remove()
+    }
+  })
+}
+
+function wrapBareTables(doc: Document): void {
+  doc.body.querySelectorAll('table').forEach(table => {
+    if (table.parentElement?.classList.contains('table-wrap')) return
+    const wrapper = doc.createElement('div')
+    wrapper.className = 'table-wrap'
+    const assetId = table.getAttribute('data-asset-id')
+    if (assetId) {
+      wrapper.setAttribute('data-asset-id', assetId)
+      table.removeAttribute('data-asset-id')
+    }
+    table.replaceWith(wrapper)
+    const caption = table.querySelector('caption')
+    if (caption) {
+      const tcaption = doc.createElement('div')
+      tcaption.className = 'tcaption'
+      tcaption.innerHTML = caption.innerHTML
+      caption.remove()
+      wrapper.append(tcaption)
+    }
+    wrapper.append(table)
+  })
+}
+
+function normalizeReferenceableBlocks(doc: Document): void {
+  doc.body.querySelectorAll<HTMLElement>('[data-asset-id]').forEach(element => {
+    const assetId = element.getAttribute('data-asset-id')?.trim()
+    if (assetId && !element.id) element.id = assetId
+  })
+
+  doc.body
+    .querySelectorAll<HTMLElement>(
+      '[data-type="block-math"],[data-asset-id^="asset_blockMath_"]',
+    )
+    .forEach(element => {
+      element.classList.add('equation')
+      if (!element.querySelector('.eq-body')) {
+        const body = doc.createElement('span')
+        body.className = 'eq-body'
+        body.innerHTML = element.innerHTML
+        element.replaceChildren(body)
+      }
+      if (!element.querySelector('.eq-num')) {
+        const number = doc.createElement('span')
+        number.className = 'eq-num'
+        element.append(number)
+      }
+    })
+}
+
+function normalizeCrossReferenceLinks(doc: Document): void {
+  doc.body
+    .querySelectorAll<HTMLAnchorElement>('a[data-xref-target]')
+    .forEach(link => {
+      const targetId = link.getAttribute('data-xref-target')?.trim()
+      if (!targetId) return
+      link.setAttribute('href', `#${targetId}`)
+      const kind = xrefKindFromTargetId(targetId)
+      if (kind) {
+        link.classList.add(`xref-${kind}`)
+        link.textContent = `${xrefLabelPrefix(kind)} `
+      }
+    })
+}
+
+function xrefKindFromTargetId(targetId: string): 'fig' | 'tbl' | 'eq' | null {
+  if (/^asset_(fig|figure)_/.test(targetId)) return 'fig'
+  if (/^asset_table_/.test(targetId)) return 'tbl'
+  if (/^asset_blockMath_/.test(targetId)) return 'eq'
+  return null
+}
+
+function xrefLabelPrefix(kind: 'fig' | 'tbl' | 'eq'): string {
+  if (kind === 'fig') return 'Figure'
+  if (kind === 'tbl') return 'Table'
+  return 'Equation'
+}
+
+function normalizeHeadings(doc: Document): void {
+  doc.body.querySelectorAll('h1:not(.doc-title)').forEach(heading => {
+    const next = doc.createElement('h2')
+    next.innerHTML = heading.innerHTML
+    copySafeAttributes(heading, next)
+    heading.replaceWith(next)
+  })
+}
+
+function normalizeSections(
+  doc: Document,
+  errors: PureRenderValidationError[],
+): void {
+  doc.body.querySelectorAll('section[data-type]').forEach(section => {
+    const type = section.getAttribute('data-type')?.trim()
+    if (type && !ALLOWED_DATA_TYPES.has(type)) {
+      errors.push({
+        code: 'unknown-data-type',
+        message: `Unknown section data-type "${type}"`,
+      })
+    }
+  })
+}
+
+function assignMissingIds(doc: Document): void {
+  const used = new Set<string>()
+  doc.body.querySelectorAll('[id]').forEach(element => {
+    const id = element.id.trim()
+    if (id) used.add(id)
+  })
+  doc.body
+    .querySelectorAll('h2,h3,h4,figure,.table-wrap,.equation')
+    .forEach((element, index) => {
+      if (element.id) return
+      const base =
+        slugify(element.textContent?.trim() || element.className || 'item') ||
+        `item-${index + 1}`
+      let id = base
+      let suffix = 2
+      while (used.has(id)) {
+        id = `${base}-${suffix}`
+        suffix += 1
+      }
+      element.id = id
+      used.add(id)
+    })
+}
+
+function materializeReferenceLabels(
+  doc: Document,
+  profile: PureRenderProfile,
+): void {
+  if (profile === 'book') {
+    assignChapterScopedLabels(doc, 'figure', 'figure')
+    assignChapterScopedLabels(doc, '.table-wrap', 'table')
+    assignChapterScopedLabels(doc, '.equation', 'equation')
+  } else {
+    assignSequentialLabels(doc, 'figure', 'figure')
+    assignSequentialLabels(doc, '.table-wrap', 'table')
+    assignSequentialLabels(doc, '.equation', 'equation')
+  }
+
+  doc.body
+    .querySelectorAll<HTMLAnchorElement>(
+      'a.xref-fig[href^="#"],a.xref-tbl[href^="#"],a.xref-eq[href^="#"]',
+    )
+    .forEach(link => {
+      const id = link.getAttribute('href')?.slice(1)
+      const target = id ? doc.getElementById(id) : null
+      const label = target?.getAttribute('data-label')?.trim()
+      const kind = link.classList.contains('xref-fig')
+        ? 'fig'
+        : link.classList.contains('xref-tbl')
+        ? 'tbl'
+        : 'eq'
+      link.textContent = label
+        ? `${xrefLabelPrefix(kind)} ${label}`
+        : xrefLabelPrefix(kind)
+    })
+}
+
+function normalizeCitationLinks(doc: Document): void {
+  const referenceIds = new Set<string>()
+  doc.body
+    .querySelectorAll<HTMLElement>(
+      'section[data-type="references"] [id],.pm-references [id],.paper-references [id]',
+    )
+    .forEach(element => referenceIds.add(element.id))
+
+  doc.body
+    .querySelectorAll<HTMLElement>('cite[data-ref-ids]')
+    .forEach(cite => {
+      const refIds = (cite.getAttribute('data-ref-ids') ?? '')
+        .split(',')
+        .map(id => id.trim())
+        .filter(Boolean)
+      if (refIds.length === 0) return
+
+      const targets = refIds.map(refId => citationTargetFor(refId, referenceIds))
+      if (targets.some(target => !target)) return
+
+      cite.classList.add('ps-citation')
+      const labels = citationLabels(cite.textContent ?? '', refIds.length)
+      cite.replaceChildren()
+      if (targets.length === 1) {
+        cite.append(citationAnchor(doc, targets[0] as string, labels[0]))
+        return
+      }
+      cite.append(doc.createTextNode('['))
+      targets.forEach((target, index) => {
+        if (index > 0) cite.append(doc.createTextNode(', '))
+        cite.append(citationAnchor(doc, target as string, labels[index]))
+      })
+      cite.append(doc.createTextNode(']'))
+    })
+}
+
+function citationTargetFor(
+  refId: string,
+  referenceIds: Set<string>,
+): string | null {
+  const entryId = `ref-entry-${refId}`
+  if (referenceIds.has(entryId)) return entryId
+  if (referenceIds.has(refId)) return refId
+  return null
+}
+
+function citationLabels(text: string, count: number): string[] {
+  if (count === 1) return [text.trim() || '[?]']
+  const numbers = text.match(/\d+/g) ?? []
+  if (numbers.length >= count) return numbers.slice(0, count)
+  return Array.from({ length: count }, (_, index) => String(index + 1))
+}
+
+function citationAnchor(doc: Document, targetId: string, label: string): Element {
+  const anchor = doc.createElement('a')
+  anchor.setAttribute('href', `#${targetId}`)
+  anchor.textContent = label
+  return anchor
+}
+
+function assignChapterScopedLabels(
+  doc: Document,
+  selector: string,
+  labelName: 'figure' | 'table' | 'equation',
+): void {
+  const labelled = new Set<HTMLElement>()
+  let chapterIndex = 0
+  doc.body
+    .querySelectorAll<HTMLElement>('section[data-type="chapter"]')
+    .forEach(chapter => {
+      chapterIndex += 1
+      let itemIndex = 0
+      chapter.querySelectorAll<HTMLElement>(selector).forEach(element => {
+        itemIndex += 1
+        applyMaterializedLabel(
+          element,
+          `${chapterIndex}.${itemIndex}`,
+          labelName,
+        )
+        labelled.add(element)
+      })
+    })
+
+  let fallbackIndex = 0
+  doc.body.querySelectorAll<HTMLElement>(selector).forEach(element => {
+    if (labelled.has(element)) return
+    fallbackIndex += 1
+    applyMaterializedLabel(element, String(fallbackIndex), labelName)
+  })
+}
+
+function assignSequentialLabels(
+  doc: Document,
+  selector: string,
+  labelName: 'figure' | 'table' | 'equation',
+): void {
+  let index = 0
+  doc.body.querySelectorAll<HTMLElement>(selector).forEach(element => {
+    index += 1
+    applyMaterializedLabel(element, String(index), labelName)
+  })
+}
+
+function applyMaterializedLabel(
+  element: HTMLElement,
+  label: string,
+  labelName: 'figure' | 'table' | 'equation',
+): void {
+  element.setAttribute('data-label', label)
+  element.setAttribute('data-label-kind', labelName)
+  if (labelName === 'figure') {
+    element.querySelector('figcaption')?.setAttribute('data-label', label)
+  } else if (labelName === 'table') {
+    element.querySelector('.tcaption')?.setAttribute('data-label', label)
+  } else {
+    element.querySelector('.eq-num')?.setAttribute('data-label', label)
+  }
+}
+
+function validateCrossReferences(
+  doc: Document,
+  errors: PureRenderValidationError[],
+): void {
+  const ids = new Set<string>()
+  doc.body.querySelectorAll('[id]').forEach(element => ids.add(element.id))
+  for (const selector of XREF_SELECTORS) {
+    doc.body.querySelectorAll<HTMLAnchorElement>(selector).forEach(link => {
+      const id = link.getAttribute('href')?.slice(1)
+      if (id && !ids.has(id)) {
+        errors.push({
+          code: 'unresolved-xref',
+          message: `Cross-reference target "#${id}" does not exist`,
+        })
+      }
+    })
+  }
+}
+
+function buildCanonicalArticle(
+  doc: Document,
+  metadata: PureRenderMetadata | undefined,
+): HTMLElement {
+  const existingArticle = doc.body.querySelector('article')
+  const article = doc.createElement('article')
+  const lang =
+    existingArticle?.getAttribute('lang') ||
+    doc.documentElement.getAttribute('lang') ||
+    'en'
+  article.setAttribute('lang', lang)
+
+  const contentSource = existingArticle ?? doc.body
+  const existingTitle = contentSource.querySelector('.doc-title')
+  const existingTitleHtml = existingTitle?.outerHTML
+  if (existingTitle && !metadata?.title?.trim()) existingTitle.remove()
+  const metadataTitle = metadata?.title?.trim()
+  const content = removeDuplicateLeadingTitle(
+    contentSource.innerHTML,
+    metadataTitle,
+  )
+
+  const frontMatter = buildFrontMatter(metadata, existingTitleHtml)
+  article.innerHTML = `${frontMatter}${content}`.trim()
+  return article
+}
+
+function buildFrontMatter(
+  metadata: PureRenderMetadata | undefined,
+  existingTitleHtml: string | undefined,
+): string {
+  const parts: string[] = []
+  if (metadata?.title?.trim()) {
+    parts.push(
+      `<h1 class="doc-title">${escapeHtml(metadata.title.trim())}</h1>`,
+    )
+  } else if (existingTitleHtml) {
+    parts.push(existingTitleHtml)
+  }
+
+  const authors = metadata?.authorsHtml ?? metadata?.authorsText
+  if (authors?.trim()) {
+    parts.push(
+      `<p class="authors">${
+        metadata?.authorsHtml
+          ? sanitizeMetadataInlineHtml(authors)
+          : escapeHtml(authors.trim())
+      }</p>`,
+    )
+  }
+
+  const affiliations = metadata?.affiliationsHtml ?? metadata?.affiliationsText
+  if (affiliations?.trim()) {
+    parts.push(
+      `<p class="affil">${
+        metadata?.affiliationsHtml
+          ? sanitizeMetadataInlineHtml(affiliations)
+          : escapeHtml(affiliations.trim())
+      }</p>`,
+    )
+  }
+
+  const abstract = metadata?.abstractHtml ?? metadata?.abstractText
+  if (abstract?.trim()) {
+    const abstractHtml = metadata?.abstractHtml
+      ? sanitizeMetadataBlockHtml(abstract)
+      : abstract
+          .trim()
+          .split(/\n{2,}/)
+          .map(paragraph => `<p>${escapeHtml(paragraph.trim())}</p>`)
+          .join('\n')
+    parts.push(
+      `<section data-type="abstract"><h2>Abstract</h2>\n${abstractHtml}</section>`,
+    )
+  }
+
+  if (metadata?.keywords?.length) {
+    parts.push(
+      `<p class="keywords"><b>Keywords:</b> ${metadata.keywords
+        .map(keyword => escapeHtml(keyword))
+        .join(', ')}</p>`,
+    )
+  }
+
+  return parts.join('\n')
+}
+
+function sanitizeMetadataInlineHtml(html: string): string {
+  const doc = parseHtml(`<div>${html}</div>`)
+  const root = doc.body.firstElementChild
+  if (!root) return ''
+  sanitizeMetadataNode(root, 'inline')
+  return root.innerHTML.trim()
+}
+
+function sanitizeMetadataBlockHtml(html: string): string {
+  const doc = parseHtml(`<div>${html}</div>`)
+  const root = doc.body.firstElementChild
+  if (!root) return ''
+  sanitizeMetadataNode(root, 'block')
+  return root.innerHTML.trim()
+}
+
+function sanitizeMetadataNode(node: Element, mode: 'inline' | 'block'): void {
+  for (const child of Array.from(node.children)) {
+    const tag = child.tagName.toLowerCase()
+    if (['script', 'style', 'link', 'font', 'center'].includes(tag)) {
+      child.remove()
+      continue
+    }
+    if (!isAllowedMetadataTag(tag, mode)) {
+      sanitizeMetadataNode(child, mode)
+      child.replaceWith(...Array.from(child.childNodes))
+      continue
+    }
+    sanitizeMetadataAttributes(child)
+    sanitizeMetadataNode(child, mode)
+  }
+}
+
+function isAllowedMetadataTag(tag: string, mode: 'inline' | 'block'): boolean {
+  const inlineTags = [
+    'a',
+    'span',
+    'sup',
+    'sub',
+    'strong',
+    'b',
+    'em',
+    'i',
+    'code',
+    'br',
+  ]
+  const blockTags = ['p', 'ul', 'ol', 'li', 'blockquote']
+  return (
+    inlineTags.includes(tag) || (mode === 'block' && blockTags.includes(tag))
+  )
+}
+
+function sanitizeMetadataAttributes(element: Element): void {
+  for (const attr of Array.from(element.attributes)) {
+    const name = attr.name.toLowerCase()
+    if (
+      name === 'style' ||
+      name.startsWith('on') ||
+      (!['class', 'id', 'href', 'title', 'aria-label'].includes(name) &&
+        !name.startsWith('data-'))
+    ) {
+      element.removeAttribute(attr.name)
+      continue
+    }
+    if (name === 'href' && !/^(https?:|mailto:|#)/i.test(attr.value.trim())) {
+      element.removeAttribute(attr.name)
+    }
+  }
+}
+
+function copySafeAttributes(from: Element, to: Element): void {
+  for (const attr of Array.from(from.attributes)) {
+    if (attr.name === 'style') continue
+    to.setAttribute(attr.name, attr.value)
+  }
+}
+
+function removeDuplicateLeadingTitle(
+  html: string,
+  title: string | undefined,
+): string {
+  const normalizedTitle = normalizeText(title ?? '')
+  if (!normalizedTitle) return html
+  const match = /^\s*<h[12]\b[^>]*>([\s\S]*?)<\/h[12]>/i.exec(html)
+  if (!match) return html
+  const headingText = normalizeText(match[1].replace(/<[^>]+>/g, ' '))
+  if (headingText !== normalizedTitle) return html
+  return html.slice(match[0].length)
+}
+
+function titleFromDocument(html: string): string | null {
+  const match = /<h[12]\b[^>]*>([\s\S]*?)<\/h[12]>/i.exec(html)
+  if (!match) return null
+  const text = displayText(match[1].replace(/<[^>]+>/g, ' '))
+  return text || null
+}
+
+function displayText(value: string): string {
+  return value.replace(/\s+/g, ' ').trim()
+}
+
+function normalizeText(value: string): string {
+  return value.replace(/\s+/g, ' ').trim().toLowerCase()
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/<[^>]+>/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}