UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

446 lines • 14.2 kB
/** * Legal Numbering Module * * Handles OOXML numbering corner cases for legal documents. * Implements continuation pattern detection for proper rendering of * "orphan" list items. * * @example * Word exhibits behavior where orphan list items render at level 0: * - Para 1: ilvl=0 → "1." * - Para 2: ilvl=0 → "2." * - Para 3: ilvl=0 → "3." * - Para 4: ilvl=1, start=4 → Word displays "4." (NOT "3.4") */ import { childElements } from './primitives/index.js'; // ============================================================================= // Continuation Pattern Detection // ============================================================================= /** * Detect if a paragraph is using a continuation pattern. * * A continuation pattern occurs when a list item at ilvl > 0 should render * at level 0 because its start value indicates it's continuing the parent * level's sequence rather than starting a nested list. * * @param ilvl - The indentation level of the paragraph * @param startValue - The start value for this level * @param levelNumbers - Current counter values for each level * @returns Continuation info with effective level * * @example * // Level numbers [3, 0] means level 0 is at "3", level 1 hasn't been used * detectContinuationPattern(1, 4, [3, 0]) * // Returns: { isContinuation: true, effectiveLevel: 0 } * // Because start=4 equals levelNumbers[0]+1, this continues as "4." */ export function detectContinuationPattern(ilvl, startValue, levelNumbers) { // Must be at a level > 0 to be a continuation if (ilvl <= 0) { return { isContinuation: false, effectiveLevel: ilvl }; } // Check if start value equals parent level's counter + 1 const parentLevel = ilvl - 1; const parentValue = levelNumbers[parentLevel] ?? 0; if (startValue === parentValue + 1) { return { isContinuation: true, effectiveLevel: 0 }; } return { isContinuation: false, effectiveLevel: ilvl }; } /** * Get the effective level for rendering, accounting for continuation patterns. * * @param ilvl - The declared indentation level * @param startValue - The start value for this level * @param levelNumbers - Current counter values for each level * @returns The effective level for rendering (0 for continuation patterns) */ export function getEffectiveLevel(ilvl, startValue, levelNumbers) { const info = detectContinuationPattern(ilvl, startValue, levelNumbers); return info.effectiveLevel; } /** * Create initial numbering state. */ export function createNumberingState() { return { counters: new Map(), levelUsed: new Map(), }; } /** * Get the key for numbering state lookup. */ function getNumKey(numId) { return `num:${numId}`; } /** * Get or initialize counter array for a numbering definition. * * @param state - The numbering state * @param numId - The numbering definition ID * @param maxLevels - Maximum number of levels (default 9) * @returns The counter array for this numbering definition */ export function getCounters(state, numId, maxLevels = 9) { const key = getNumKey(numId); let counters = state.counters.get(key); if (!counters) { counters = new Array(maxLevels).fill(0); state.counters.set(key, counters); } return counters; } /** * Get or initialize level used tracking for a numbering definition. */ function getLevelUsed(state, numId, maxLevels = 9) { const key = getNumKey(numId); let used = state.levelUsed.get(key); if (!used) { used = new Array(maxLevels).fill(false); state.levelUsed.set(key, used); } return used; } /** * Track the last used level for each numbering definition. */ const lastUsedLevel = new Map(); /** * Process a numbered paragraph and return its display number. * * Updates the numbering state and returns the appropriate number to display, * accounting for continuation patterns and level resets. * * @param state - The numbering state to update * @param numId - The numbering definition ID * @param ilvl - The indentation level * @param levelInfo - Level properties from the numbering definition * @returns The number to display at this level */ export function processNumberedParagraph(state, numId, ilvl, levelInfo) { const counters = getCounters(state, numId); const levelUsed = getLevelUsed(state, numId); const key = `num:${numId}`; // Check for continuation pattern const continuation = detectContinuationPattern(ilvl, levelInfo.start, counters); if (continuation.isContinuation) { // Continuation pattern: use level 0's counter incremented const current = counters[0] ?? 0; counters[0] = current + 1; lastUsedLevel.set(key, 0); return counters[0] ?? 1; } // Check if we moved from a deeper level to a shallower level const prevLevel = lastUsedLevel.get(key) ?? -1; if (prevLevel > ilvl) { // Reset all deeper levels when moving to a shallower level for (let i = ilvl + 1; i < counters.length; i++) { counters[i] = 0; levelUsed[i] = false; } } // Check if this level has been used before if (!levelUsed[ilvl]) { // First use of this level: set to start value counters[ilvl] = levelInfo.start; levelUsed[ilvl] = true; } else { // Subsequent use: increment const current = counters[ilvl] ?? 0; counters[ilvl] = current + 1; } lastUsedLevel.set(key, ilvl); return counters[ilvl] ?? levelInfo.start; } // ============================================================================= // Number Format Rendering // ============================================================================= /** * Convert a number to the specified format. * * @param value - The numeric value * @param format - The number format (decimal, lowerLetter, upperLetter, lowerRoman, upperRoman, etc.) * @returns The formatted string */ export function formatNumber(value, format) { switch (format) { case 'decimal': case 'decimalZero': return value.toString(); case 'lowerLetter': return toLowerLetter(value); case 'upperLetter': return toUpperLetter(value); case 'lowerRoman': return toRoman(value).toLowerCase(); case 'upperRoman': return toRoman(value); case 'ordinal': return toOrdinal(value); case 'cardinalText': return toCardinalText(value); case 'ordinalText': return toOrdinalText(value); case 'bullet': return '•'; case 'none': return ''; default: return value.toString(); } } /** * Convert number to lowercase letter (a, b, c, ... z, aa, ab, ...). */ function toLowerLetter(value) { let result = ''; let n = value; while (n > 0) { n--; result = String.fromCharCode(97 + (n % 26)) + result; n = Math.floor(n / 26); } return result; } /** * Convert number to uppercase letter (A, B, C, ... Z, AA, AB, ...). */ function toUpperLetter(value) { return toLowerLetter(value).toUpperCase(); } /** * Convert number to Roman numeral. */ function toRoman(value) { const romanNumerals = [ [1000, 'M'], [900, 'CM'], [500, 'D'], [400, 'CD'], [100, 'C'], [90, 'XC'], [50, 'L'], [40, 'XL'], [10, 'X'], [9, 'IX'], [5, 'V'], [4, 'IV'], [1, 'I'], ]; let result = ''; let remaining = value; for (const [num, roman] of romanNumerals) { while (remaining >= num) { result += roman; remaining -= num; } } return result; } /** * Convert number to ordinal (1st, 2nd, 3rd, 4th, ...). */ function toOrdinal(value) { const suffixes = ['th', 'st', 'nd', 'rd']; const v = value % 100; const suffix = suffixes[(v - 20) % 10] ?? suffixes[v] ?? suffixes[0] ?? 'th'; return value + suffix; } /** * Convert number to cardinal text (one, two, three, ...). */ function toCardinalText(value) { const ones = [ '', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen', 'seventeen', 'eighteen', 'nineteen', ]; const tens = [ '', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety', ]; if (value < 20) { return ones[value] || value.toString(); } if (value < 100) { const ten = Math.floor(value / 10); const one = value % 10; return tens[ten] + (one > 0 ? '-' + ones[one] : ''); } // For larger numbers, fall back to decimal return value.toString(); } /** * Convert number to ordinal text (first, second, third, ...). */ function toOrdinalText(value) { const ordinals = { 1: 'first', 2: 'second', 3: 'third', 4: 'fourth', 5: 'fifth', 6: 'sixth', 7: 'seventh', 8: 'eighth', 9: 'ninth', 10: 'tenth', 11: 'eleventh', 12: 'twelfth', }; return ordinals[value] || toOrdinal(value); } // ============================================================================= // Level Text Expansion // ============================================================================= /** * Expand a level text format string with actual numbers. * * Level text uses placeholders like %1, %2, %3 for level values. * * @param lvlText - The level text format (e.g., "%1.", "%1.%2") * @param counters - Current counter values for each level * @param levels - Level definitions for format lookup * @returns The expanded text (e.g., "1.", "1.2") */ export function expandLevelText(lvlText, counters, levels) { let result = lvlText; // Replace %1 through %9 with corresponding level values for (let i = 0; i < 9; i++) { const placeholder = `%${i + 1}`; if (result.includes(placeholder)) { const value = counters[i] ?? 0; const level = levels[i]; const formatted = level ? formatNumber(value, level.numFmt) : value.toString(); result = result.replace(placeholder, formatted); } } return result; } // ============================================================================= // Legal Numbering (isLgl) Support // ============================================================================= /** * Check if legal numbering is active for a level. * * Legal numbering (w:isLgl) changes how nested levels display, * using decimal format regardless of the level's numFmt. * * @param levels - Level definitions * @param currentLevel - The current level index * @returns True if legal numbering is active */ export function isLegalNumberingActive(levels, currentLevel) { // Legal numbering applies when any ancestor level has isLgl=true for (let i = 0; i <= currentLevel; i++) { if (levels[i]?.isLgl) { return true; } } return false; } /** * Expand level text with legal numbering rules. * * When legal numbering is active, all level placeholders use decimal * format regardless of the level's defined numFmt. * * @param lvlText - The level text format * @param counters - Current counter values * @param levels - Level definitions * @param currentLevel - The current level index * @returns The expanded text with legal numbering applied */ export function expandLevelTextWithLegal(lvlText, counters, levels, currentLevel) { const useLegal = isLegalNumberingActive(levels, currentLevel); let result = lvlText; for (let i = 0; i < 9; i++) { const placeholder = `%${i + 1}`; if (result.includes(placeholder)) { const value = counters[i] ?? 0; const level = levels[i]; const format = useLegal ? 'decimal' : level?.numFmt ?? 'decimal'; const formatted = formatNumber(value, format); result = result.replace(placeholder, formatted); } } return result; } // ============================================================================= // Numbering Definition Parsing // ============================================================================= /** * Extract list level info from a w:lvl element. * * @param lvlElement - The w:lvl XML element * @returns The extracted level info */ export function parseLevelElement(lvlElement) { const ilvl = parseInt(lvlElement.getAttribute('w:ilvl') || '0', 10); let start = 1; let numFmt = 'decimal'; let lvlText = ''; let isLgl = false; for (const child of childElements(lvlElement)) { switch (child.tagName) { case 'w:start': start = parseInt(child.getAttribute('w:val') || '1', 10); break; case 'w:numFmt': numFmt = child.getAttribute('w:val') || 'decimal'; break; case 'w:lvlText': lvlText = child.getAttribute('w:val') ?? ''; break; case 'w:isLgl': isLgl = child.getAttribute('w:val') !== 'false' && child.getAttribute('w:val') !== '0'; break; } } return { ilvl, start, numFmt, lvlText, isLgl }; } /** * Parse an abstract numbering definition. * * @param abstractNumElement - The w:abstractNum XML element * @returns Array of level info for all defined levels */ export function parseAbstractNumElement(abstractNumElement) { const levels = []; for (const child of childElements(abstractNumElement)) { if (child.tagName === 'w:lvl') { const levelInfo = parseLevelElement(child); levels[levelInfo.ilvl] = levelInfo; } } return levels; } //# sourceMappingURL=numbering.js.map