UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

296 lines • 10.2 kB
/** * Footnote Numbering Module * * Handles sequential footnote/endnote numbering by document order. * * `w:id` on `w:footnoteReference` is a reference identifier, NOT the display * number. Display numbers are sequential based on document order. * * @example * Document has 91 footnotes with XML IDs 2-92 (IDs 0, 1 are reserved): * - Incorrect: Display as 2, 3, 4, ..., 92 * - Correct: Display as 1, 2, 3, ..., 91 * * @conformance ECMA-376 edition 5, Part 1 § 17.11.14 */ import { RESERVED_FOOTNOTE_IDS, } from './core-types.js'; import { childElements, getLeafText } from './primitives/index.js'; // ============================================================================= // Footnote Reference Finding // ============================================================================= /** * Find all footnote or endnote references in document order. * * Recursively traverses the document tree to find references in reading order. * * @param element - The root element to search from * @param tagName - The reference tag to find ('w:footnoteReference' or 'w:endnoteReference') * @returns Array of reference elements in document order */ export function findReferencesInOrder(element, tagName) { const refs = []; function traverse(node) { if (node.tagName === tagName) { refs.push(node); } for (const child of childElements(node)) { traverse(child); } } traverse(element); return refs; } /** * Check if a footnote/endnote ID is reserved. * * IDs 0 and 1 are treated as reserved, matching the special separator and * continuation-separator footnote examples in ECMA-376 5th edition Part 1 * §17.11.9 / §17.11.10. * * @param xmlId - The XML ID to check * @returns True if this is a reserved ID * @conformance ECMA-376 edition 5, Part 1 § 17.11.14 */ export function isReservedId(xmlId) { return (xmlId === RESERVED_FOOTNOTE_IDS.SEPARATOR || xmlId === RESERVED_FOOTNOTE_IDS.CONTINUATION_SEPARATOR); } // ============================================================================= // FootnoteNumberingTracker Class // ============================================================================= /** * Tracks sequential footnote/endnote numbering by document order. * * Scans the document for footnote/endnote references and builds a mapping * from XML IDs to display numbers. * * @example * const tracker = new FootnoteNumberingTracker(documentRoot); * const displayNum = tracker.getDisplayNumber('42'); // Returns 1 if '42' is the first footnote */ export class FootnoteNumberingTracker { footnoteIdToDisplayNumber = new Map(); endnoteIdToDisplayNumber = new Map(); footnoteCustomMarks = new Set(); endnoteCustomMarks = new Set(); /** * Create a new tracker by scanning the document. * * @param documentRoot - The root element of the main document (w:document or w:body) */ constructor(documentRoot) { this.scanDocument(documentRoot); } /** * Scan the document for footnote and endnote references. */ scanDocument(documentRoot) { // Scan for footnote references const footnoteRefs = findReferencesInOrder(documentRoot, 'w:footnoteReference'); this.buildNumbering(footnoteRefs, this.footnoteIdToDisplayNumber, this.footnoteCustomMarks); // Scan for endnote references const endnoteRefs = findReferencesInOrder(documentRoot, 'w:endnoteReference'); this.buildNumbering(endnoteRefs, this.endnoteIdToDisplayNumber, this.endnoteCustomMarks); } /** * Build the ID to display number mapping. */ buildNumbering(refs, idToNumber, customMarks) { let displayNum = 1; for (const ref of refs) { const xmlId = ref.getAttribute('w:id'); if (!xmlId) continue; // Skip reserved IDs if (isReservedId(xmlId)) continue; // Check for custom mark const hasCustomMark = ref.getAttribute('w:customMarkFollows') === '1' || ref.getAttribute('w:customMarkFollows') === 'true'; if (hasCustomMark) { customMarks.add(xmlId); // Custom marks don't get automatic numbers but still reserve a slot // Some implementations skip numbering, others don't - we follow Word behavior } // Only assign number if not already seen (handles duplicate references) if (!idToNumber.has(xmlId)) { if (!hasCustomMark) { idToNumber.set(xmlId, displayNum); displayNum++; } } } } /** * Get the display number for a footnote by its XML ID. * * @param xmlId - The XML ID (w:id attribute) * @returns The display number, or undefined if not found or uses custom mark */ getFootnoteDisplayNumber(xmlId) { return this.footnoteIdToDisplayNumber.get(xmlId); } /** * Get the display number for an endnote by its XML ID. * * @param xmlId - The XML ID (w:id attribute) * @returns The display number, or undefined if not found or uses custom mark */ getEndnoteDisplayNumber(xmlId) { return this.endnoteIdToDisplayNumber.get(xmlId); } /** * Get the display number for a footnote or endnote by its XML ID. * * Convenience method that checks both footnotes and endnotes. * * @param xmlId - The XML ID * @returns The display number, or undefined if not found */ getDisplayNumber(xmlId) { return (this.footnoteIdToDisplayNumber.get(xmlId) ?? this.endnoteIdToDisplayNumber.get(xmlId)); } /** * Check if a footnote uses a custom mark. * * @param xmlId - The XML ID * @returns True if this footnote has w:customMarkFollows */ hasFootnoteCustomMark(xmlId) { return this.footnoteCustomMarks.has(xmlId); } /** * Check if an endnote uses a custom mark. * * @param xmlId - The XML ID * @returns True if this endnote has w:customMarkFollows */ hasEndnoteCustomMark(xmlId) { return this.endnoteCustomMarks.has(xmlId); } /** * Get the total number of footnotes (excluding custom marks). */ getFootnoteCount() { return this.footnoteIdToDisplayNumber.size; } /** * Get the total number of endnotes (excluding custom marks). */ getEndnoteCount() { return this.endnoteIdToDisplayNumber.size; } /** * Get all footnote references as structured data. * * @returns Array of FootnoteReference objects */ getFootnoteReferences() { const refs = []; for (const [xmlId, displayNumber] of this.footnoteIdToDisplayNumber) { refs.push({ xmlId, displayNumber, customMarkFollows: this.footnoteCustomMarks.has(xmlId), }); } // Add custom mark footnotes (no display number) for (const xmlId of this.footnoteCustomMarks) { if (!this.footnoteIdToDisplayNumber.has(xmlId)) { refs.push({ xmlId, customMarkFollows: true, }); } } return refs; } /** * Get all endnote references as structured data. * * @returns Array of FootnoteReference objects */ getEndnoteReferences() { const refs = []; for (const [xmlId, displayNumber] of this.endnoteIdToDisplayNumber) { refs.push({ xmlId, displayNumber, customMarkFollows: this.endnoteCustomMarks.has(xmlId), }); } // Add custom mark endnotes (no display number) for (const xmlId of this.endnoteCustomMarks) { if (!this.endnoteIdToDisplayNumber.has(xmlId)) { refs.push({ xmlId, customMarkFollows: true, }); } } return refs; } } // ============================================================================= // Footnote Content Extraction // ============================================================================= /** * Find a footnote element by its ID in the footnotes.xml part. * * @param footnotesRoot - The root of the footnotes.xml document * @param xmlId - The XML ID to find * @returns The w:footnote element, or undefined if not found */ export function findFootnoteById(footnotesRoot, xmlId) { if (footnotesRoot.tagName !== 'w:footnotes') { return undefined; } for (const child of childElements(footnotesRoot)) { if (child.tagName === 'w:footnote' && child.getAttribute('w:id') === xmlId) { return child; } } return undefined; } /** * Find an endnote element by its ID in the endnotes.xml part. * * @param endnotesRoot - The root of the endnotes.xml document * @param xmlId - The XML ID to find * @returns The w:endnote element, or undefined if not found */ export function findEndnoteById(endnotesRoot, xmlId) { if (endnotesRoot.tagName !== 'w:endnotes') { return undefined; } for (const child of childElements(endnotesRoot)) { if (child.tagName === 'w:endnote' && child.getAttribute('w:id') === xmlId) { return child; } } return undefined; } /** * Extract plain text content from a footnote/endnote element. * * @param noteElement - The w:footnote or w:endnote element * @returns Plain text content */ export function extractNoteText(noteElement) { const texts = []; function traverse(node) { if (node.tagName === 'w:t') { const text = getLeafText(node) ?? ''; if (text) { texts.push(text); } } for (const child of childElements(node)) { traverse(child); } } traverse(noteElement); return texts.join(''); } //# sourceMappingURL=footnotes.js.map