open-agreements
Version:
Open-source legal template filling CLI and library
395 lines • 17.5 kB
JavaScript
// DOCX → HTML serializer (semantic tier, mammoth.js-style).
//
// Like `serialize_markdown.ts`, this is a *serializer over the existing structured document
// model* — it does no OOXML parsing. `DocxDocument.buildDocumentView({ showFormatting: true })`
// already yields a `DocumentViewNode[]` carrying headings, list metadata, grid-aware table
// context, injected `[^n]` footnote markers, and an HTML-shaped inline-tag string
// (`tagged_text`). This module turns that model into semantic HTML.
//
// It renders the *same* inline tokens as the Markdown emitter via the shared
// `tokenizeToonInline` core, so the two serializers never re-derive the tag grammar and drift
// from the emitter in `formatting_tags.ts`. Where Markdown is lossy, HTML is richer: highlight
// becomes `<mark>`, font runs become a styled `<span>`, and lists nest as real `<ul>/<ol>`.
//
// This is the *semantic* tier, not pixel-faithful HTML+CSS: exact layout is not reproduced.
import { tokenizeToonInline } from './document_view.js';
import { escapeHtmlAttribute } from './formatting_tags.js';
/** Footnote markers already injected into `tagged_text`, e.g. `[^1]`, `[^12]`. */
const FOOTNOTE_MARKER_RE = /\[\^(\d+)\]/g;
/** Escape the characters that are significant in HTML *text* content. */
function escapeHtmlText(text) {
return text.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>');
}
/**
* Escape literal text and turn any injected `[^n]` footnote marker into a trusted superscript
* anchor. Order matters: the literal spans are escaped, but the generated `<sup>` is emitted
* verbatim (escaping it would render the markup literally).
*
* When a `refs` registry is supplied, the first marker for footnote N keeps `id="fnref-N"` (the
* definition's back-link target); later repeats get a unique `id="fnref-N-k"` so the document
* never carries duplicate ids.
*/
function renderTextWithFootnotes(raw, refs) {
let out = '';
let last = 0;
for (const match of raw.matchAll(FOOTNOTE_MARKER_RE)) {
const idx = match.index ?? 0;
out += escapeHtmlText(raw.slice(last, idx));
const n = match[1];
let id = `fnref-${n}`;
if (refs) {
const k = (refs.get(Number(n)) ?? 0) + 1;
refs.set(Number(n), k);
if (k > 1)
id = `fnref-${n}-${k}`;
}
out += `<sup id="${id}"><a href="#fn-${n}">${n}</a></sup>`;
last = idx + match[0].length;
}
out += escapeHtmlText(raw.slice(last));
return out;
}
/**
* Allow only schemes that are safe to follow from a rendered document. The href arrives already
* attribute-escaped from `formatting_tags.ts`; a `javascript:`/`data:`/`vbscript:` URL would
* otherwise pass through and execute on click. Relative URLs and fragments (no scheme) are kept.
*/
const SAFE_URL_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
export function isSafeHref(href) {
// Strip whitespace/control chars browsers ignore (e.g. `java\tscript:`) before scheme-matching.
const v = href.replace(/[\u0000-\u0020]/g, '').toLowerCase();
const scheme = /^([a-z][a-z0-9+.-]*):/.exec(v);
return scheme ? SAFE_URL_SCHEMES.has(scheme[1]) : true;
}
// ── Font (`<font ...>`) → sanitized inline style ─────────────────────────────
// The values come from `formatting_tags.ts`: color is a raw hex string (no `#`), size is in
// *points* (display units), face is a font name. Every value is sanitized so a hostile font
// name cannot break out of the `style` attribute.
function sanitizeColor(raw) {
if (!raw)
return null;
const hex = raw.replace(/^#/, '');
return /^[0-9A-Fa-f]{3,8}$/.test(hex) ? `#${hex}` : null;
}
function sanitizeFontSize(raw) {
if (!raw)
return null;
const n = Number(raw);
return Number.isFinite(n) && n > 0 ? `${n}pt` : null;
}
function sanitizeFontFamily(raw) {
if (!raw)
return null;
// Strip anything that could terminate the value or the attribute; keep ordinary name chars.
const clean = raw.replace(/[<>"';{}()]/g, '').trim();
return clean ? `'${clean}'` : null;
}
function fontTagToSpan(tag) {
const color = sanitizeColor(/color="([^"]*)"/.exec(tag)?.[1]);
const size = sanitizeFontSize(/size="([^"]*)"/.exec(tag)?.[1]);
const face = sanitizeFontFamily(/face="([^"]*)"/.exec(tag)?.[1]);
const decls = [];
if (color)
decls.push(`color:${color}`);
if (size)
decls.push(`font-size:${size}`);
if (face)
decls.push(`font-family:${face}`);
// A `<font>` with no usable attribute degrades to a bare span (still balances `</font>`).
if (decls.length === 0)
return '<span>';
return `<span style="${escapeHtmlAttribute(decls.join(';'))}">`;
}
/**
* Convert one TOON inline-tag string (a `DocumentViewNode.tagged_text` value) to inline HTML.
* This is the HTML parallel of `inlineTagsToMarkdown` and the reusable core of the serializer.
*
* Tag mapping:
* - `<b>`/`<i>`/`<u>`/`<a href="...">` → passed through verbatim (already valid, attribute-escaped HTML)
* - `<highlight>` → `<mark>`
* - `<font color=… size=… face=…>` → `<span style="…">` (values sanitized)
*
* Literal text spans are HTML-escaped; injected `[^n]` footnote markers become `<sup>` anchors.
*/
export function inlineTagsToHtml(text, refs) {
let out = '';
for (const token of tokenizeToonInline(text)) {
if (token.kind === 'text') {
out += renderTextWithFootnotes(token.value, refs);
continue;
}
const tag = token.value;
// The serializer renders compact-mode views, but tolerate the full-mode attributed form
// (<highlight color="...">) so a full-mode tagged_text can't leak raw markup into HTML.
if (tag === '<highlight>' || tag.startsWith('<highlight '))
out += '<mark>';
else if (tag === '</highlight>')
out += '</mark>';
else if (tag.startsWith('<font '))
out += fontTagToSpan(tag);
else if (tag === '</font>')
out += '</span>';
else if (tag.startsWith('<a ')) {
// Drop the href for unsafe schemes (e.g. `javascript:`); keep the anchor so `</a>` still
// balances and the link text survives as plain text.
const href = /href="([^"]*)"/.exec(tag)?.[1] ?? '';
out += isSafeHref(href) ? tag : '<a>';
}
// <b>/<i>/<u> and `</a>` and the closers are already valid HTML — pass through.
else
out += tag;
}
return out;
}
/** A heading is structural (gets `<hN>`) only when Word's style told us so and gave a level. */
function isStructuralHeading(node) {
return node.heading?.source === 'word_style' && typeof node.heading.level === 'number';
}
/**
* Render a run of nodes that share a `table_context.table_id` as an HTML `<table>`.
*
* Lossy by design (the view model discards `gridSpan`/`vMerge` span width):
* - Horizontally merged cells (`gridSpan`) advance `col_index`, leaving grid gaps that we fill
* with empty cells so every row has the full column count.
* - Vertically merged cells and nested tables flatten into the body-level grid; multi-paragraph
* cells join with `<br/>`.
*/
function renderTable(group, refs) {
let totalCols = 0;
for (const n of group) {
const tc = n.table_context;
if (!tc)
continue;
totalCols = Math.max(totalCols, tc.total_cols, tc.col_index + 1);
}
if (totalCols <= 0)
return '';
const rows = new Map();
const rowOrder = [];
const headerRows = new Set();
for (const n of group) {
const tc = n.table_context;
if (!tc)
continue;
if (!rows.has(tc.row_index)) {
rows.set(tc.row_index, new Map());
rowOrder.push(tc.row_index);
}
const cellMap = rows.get(tc.row_index);
const cellHtml = inlineTagsToHtml(n.tagged_text, refs).replace(/\s*\n+\s*/g, '<br/>').trim();
const parts = cellMap.get(tc.col_index) ?? [];
if (cellHtml)
parts.push(cellHtml);
cellMap.set(tc.col_index, parts);
if (tc.is_header_row)
headerRows.add(tc.row_index);
}
rowOrder.sort((a, b) => a - b);
if (rowOrder.length === 0)
return '';
const cellsFor = (rowIndex) => {
const cellMap = rows.get(rowIndex) ?? new Map();
const cells = [];
for (let c = 0; c < totalCols; c++)
cells.push((cellMap.get(c) ?? []).join('<br/>'));
return cells;
};
// Prefer the first row Word flagged as a header; otherwise treat the first row as the header.
const headerRowIndex = rowOrder.find((ri) => headerRows.has(ri)) ?? rowOrder[0];
const lines = ['<table>'];
lines.push('<thead>');
lines.push(`<tr>${cellsFor(headerRowIndex).map((c) => `<th>${c}</th>`).join('')}</tr>`);
lines.push('</thead>');
lines.push('<tbody>');
for (const ri of rowOrder) {
if (ri === headerRowIndex)
continue;
lines.push(`<tr>${cellsFor(ri).map((c) => `<td>${c}</td>`).join('')}</tr>`);
}
lines.push('</tbody>');
lines.push('</table>');
return lines.join('\n');
}
/**
* Stateful nested-list builder. Auto list levels come straight from OOXML `ilvl` with no
* monotonicity guarantee, so the open/close logic must be robust to level jumps, interruptions,
* and same-level kind changes — a naive open-on-increase/close-on-decrease stack would emit
* malformed HTML.
*/
class ListBuilder {
// Each open list records its tag AND the item `level` that opened it. Storing the level (not
// just depth) is what keeps consecutive same-level items siblings even after a level jump that
// skipped intermediate depths — depth alone would drift deeper on every repeated jumped level.
stack = [];
out = [];
/** Append one list item at the given 0-based level with the given list tag. */
item(level, tag, content) {
const lvl = Math.max(0, level);
// Close any lists deeper than this item's level.
while (this.stack.length > 0 && this.stack[this.stack.length - 1].level > lvl) {
this.out.push('</li>');
this.out.push(`</${this.stack.pop().tag}>`);
}
const top = this.stack[this.stack.length - 1];
if (top && top.level === lvl) {
// Sibling at the same list level: close the previous item; swap list kind if it changed.
this.out.push('</li>');
if (top.tag !== tag) {
this.out.push(`</${this.stack.pop().tag}>`);
this.out.push(`<${tag}>`);
this.stack.push({ tag, level: lvl });
}
}
else {
// Deeper than the current top (or the first item): open one nested list inside the open
// <li>. We record the item's actual level, so a jump of >1 opens a single step and a later
// same-level item lands here as a sibling rather than nesting further.
this.out.push(`<${tag}>`);
this.stack.push({ tag, level: lvl });
}
this.out.push(`<li>${content}`);
}
/** True when at least one list is currently open. */
get isOpen() {
return this.stack.length > 0;
}
/** Close every open list and return the accumulated HTML. */
flush() {
while (this.stack.length > 0) {
this.out.push('</li>');
this.out.push(`</${this.stack.pop().tag}>`);
}
const html = this.out.join('\n');
this.out = [];
return html;
}
}
function renderListContent(node, refs) {
const lm = node.list_metadata;
const html = inlineTagsToHtml(node.tagged_text, refs).trim();
// Auto-numbered lists become <ol> (the renderer numbers them). Manual/legal labels keep their
// literal text (`Section 2.1`, `(a)`) prefixed inside a <ul> item — a bare number would
// silently destroy meaningful legal labels. `is_auto_numbered` is the reliable signal:
// an auto `1.` can classify as NUMBERED_HEADING, so label_type alone is not enough.
if (lm.is_auto_numbered)
return { tag: 'ol', content: html };
const label = lm.label_string?.trim() ?? '';
return { tag: 'ul', content: label ? `${escapeHtmlText(label)} ${html}` : html };
}
function renderFootnotes(footnotes, refs) {
const defs = footnotes.filter((fn) => fn.displayNumber > 0);
if (defs.length === 0)
return '';
const items = defs.map((fn) => {
const body = escapeHtmlText(fn.text.replace(/\s+/g, ' ').trim());
// Only link back when the marker was actually rendered in the body — otherwise the `#fnref-n`
// target does not exist (an unreferenced/orphan footnote definition), so omit the back-link.
const backlink = refs.has(fn.displayNumber) ? ` <a href="#fnref-${fn.displayNumber}">↩</a>` : '';
return `<li id="fn-${fn.displayNumber}">${body}${backlink}</li>`;
});
return ['<section class="footnotes">', '<hr/>', '<ol>', ...items, '</ol>', '</section>'].join('\n');
}
const DOCUMENT_STYLE = `
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 50rem; margin: 2rem auto; padding: 0 1rem; line-height: 1.5; color: #1a1a1a; }
table { border-collapse: collapse; margin: 1rem 0; }
th, td { border: 1px solid #ccc; padding: 0.3rem 0.6rem; text-align: left; vertical-align: top; }
th { background: #f5f5f5; }
mark { background: #fef08a; }
.footnotes { margin-top: 2rem; font-size: 0.9em; color: #444; }
.footnotes hr { border: none; border-top: 1px solid #ccc; }
sup a { text-decoration: none; }
`.trim();
/** Strip inline tags from a heading's tagged text to make a plain-text `<title>`. */
function deriveTitle(nodes) {
const first = nodes.find(isStructuralHeading);
if (!first)
return 'Document';
const plain = tokenizeToonInline(first.tagged_text)
.filter((t) => t.kind === 'text')
.map((t) => t.value)
.join('')
.replace(/\[\^\d+\]/g, '')
.trim();
return plain || 'Document';
}
/**
* Serialize a structured document view to semantic HTML.
*
* @param nodes Block nodes from `buildDocumentView({ showFormatting: true }).nodes`.
* @param footnotes Footnotes from `DocxDocument.getFootnotes()` (already sorted by
* `displayNumber`); rendered as a footnotes `<section>` with back-links.
*/
export function serializeToHtml(nodes, footnotes = [], opts = {}) {
const blocks = [];
// Footnote markers rendered in the body, used to dedupe ids and gate definition back-links.
const refs = new Map();
let lists = null;
const closeLists = () => {
if (lists && lists.isOpen)
blocks.push(lists.flush());
lists = null;
};
for (let i = 0; i < nodes.length; i++) {
const node = nodes[i];
// ── Tables: consume the whole run of same-table_id nodes at once ──
if (node.table_context) {
closeLists();
const tableId = node.table_context.table_id;
const group = [];
while (i < nodes.length && nodes[i].table_context?.table_id === tableId) {
group.push(nodes[i]);
i++;
}
i--; // for-loop will re-increment
const table = renderTable(group, refs);
if (table)
blocks.push(table);
continue;
}
// ── Structural (Word-styled) headings ──
if (isStructuralHeading(node)) {
closeLists();
const level = Math.min(6, Math.max(1, node.heading.level));
blocks.push(`<h${level}>${inlineTagsToHtml(node.tagged_text, refs).trim()}</h${level}>`);
continue;
}
// ── List items: accumulated in a stateful nested-list builder ──
if (node.list_metadata.list_level >= 0) {
if (!lists)
lists = new ListBuilder();
const { tag, content } = renderListContent(node, refs);
lists.item(Math.max(0, node.list_metadata.list_level), tag, content);
continue;
}
// ── Normal paragraphs (heuristic headings land here: their run-in bold is already in the
// inline tags, so they stay <p> rather than being promoted to a heading). ──
closeLists();
const html = inlineTagsToHtml(node.tagged_text, refs).trim();
if (html)
blocks.push(`<p>${html}</p>`);
}
closeLists();
const footnotesHtml = renderFootnotes(footnotes, refs);
if (footnotesHtml)
blocks.push(footnotesHtml);
const body = blocks.join('\n');
if (opts.fragment)
return `${body}\n`;
const title = escapeHtmlText(opts.title ?? deriveTitle(nodes));
return [
'<!DOCTYPE html>',
'<html lang="en">',
'<head>',
'<meta charset="utf-8"/>',
'<meta name="viewport" content="width=device-width, initial-scale=1"/>',
`<title>${title}</title>`,
`<style>\n${DOCUMENT_STYLE}\n</style>`,
'</head>',
'<body>',
body,
'</body>',
'</html>',
'',
].join('\n');
}
//# sourceMappingURL=serialize_html.js.map