@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

package/dist/docx/numberingParser.js

@@ -0,0 +1,735 @@
+import { findChild, findChildren, getAttribute, parseBooleanElement, parseNumericAttribute, parseXmlDocument } from "./xmlParser.js";
+import { LevelSuffixSchema, ThemeColorSlotSchema, narrowEnum } from "./parserEnums.js";
+//#region src/docx/numberingParser.ts
+const NUMBER_FORMAT_MAP = {
+	decimal: "decimal",
+	upperRoman: "upperRoman",
+	lowerRoman: "lowerRoman",
+	upperLetter: "upperLetter",
+	lowerLetter: "lowerLetter",
+	ordinal: "ordinal",
+	cardinalText: "cardinalText",
+	ordinalText: "ordinalText",
+	hex: "hex",
+	chicago: "chicago",
+	bullet: "bullet",
+	none: "none",
+	decimalZero: "decimalZero",
+	ganada: "ganada",
+	chosung: "chosung",
+	ideographDigital: "ideographDigital",
+	japaneseCounting: "japaneseCounting",
+	aiueo: "aiueo",
+	iroha: "iroha",
+	decimalFullWidth: "decimalFullWidth",
+	decimalHalfWidth: "decimalHalfWidth",
+	japaneseLegal: "japaneseLegal",
+	japaneseDigitalTenThousand: "japaneseDigitalTenThousand",
+	decimalEnclosedCircle: "decimalEnclosedCircle",
+	decimalFullWidth2: "decimalFullWidth2",
+	aiueoFullWidth: "aiueoFullWidth",
+	irohaFullWidth: "irohaFullWidth",
+	decimalEnclosedFullstop: "decimalEnclosedFullstop",
+	decimalEnclosedParen: "decimalEnclosedParen",
+	decimalEnclosedCircleChinese: "decimalEnclosedCircleChinese",
+	ideographEnclosedCircle: "ideographEnclosedCircle",
+	ideographTraditional: "ideographTraditional",
+	ideographZodiac: "ideographZodiac",
+	ideographZodiacTraditional: "ideographZodiacTraditional",
+	taiwaneseCounting: "taiwaneseCounting",
+	ideographLegalTraditional: "ideographLegalTraditional",
+	taiwaneseCountingThousand: "taiwaneseCountingThousand",
+	taiwaneseDigital: "taiwaneseDigital",
+	chineseCounting: "chineseCounting",
+	chineseLegalSimplified: "chineseLegalSimplified",
+	chineseCountingThousand: "chineseCountingThousand",
+	koreanDigital: "koreanDigital",
+	koreanCounting: "koreanCounting",
+	koreanLegal: "koreanLegal",
+	koreanDigital2: "koreanDigital2",
+	vietnameseCounting: "vietnameseCounting",
+	russianLower: "russianLower",
+	russianUpper: "russianUpper",
+	numberInDash: "numberInDash",
+	hebrew1: "hebrew1",
+	hebrew2: "hebrew2",
+	arabicAlpha: "arabicAlpha",
+	arabicAbjad: "arabicAbjad",
+	hindiVowels: "hindiVowels",
+	hindiConsonants: "hindiConsonants",
+	hindiNumbers: "hindiNumbers",
+	hindiCounting: "hindiCounting",
+	thaiLetters: "thaiLetters",
+	thaiNumbers: "thaiNumbers",
+	thaiCounting: "thaiCounting"
+};
+/**
+* Parse numbering.xml into NumberingDefinitions
+*
+* @param numberingXml - Raw XML string from word/numbering.xml (or null if not present)
+* @returns NumberingMap with definitions and helper functions
+*/
+function parseNumbering(numberingXml) {
+	const definitions = {
+		abstractNums: [],
+		nums: []
+	};
+	if (!numberingXml) return createNumberingMap(definitions);
+	const root = parseXmlDocument(numberingXml);
+	if (!root) return createNumberingMap(definitions);
+	const abstractNumElements = findChildren(root, "w", "abstractNum");
+	for (const abstractNum of abstractNumElements) {
+		const parsed = parseAbstractNumbering(abstractNum);
+		if (parsed) definitions.abstractNums.push(parsed);
+	}
+	const numElements = findChildren(root, "w", "num");
+	for (const num of numElements) {
+		const parsed = parseNumberingInstance(num);
+		if (parsed) definitions.nums.push(parsed);
+	}
+	return createNumberingMap(definitions);
+}
+/**
+* Parse a single w:abstractNum element
+*/
+function parseAbstractNumbering(element) {
+	const abstractNumIdStr = getAttribute(element, "w", "abstractNumId");
+	if (abstractNumIdStr === null) return null;
+	const abstractNumId = Number.parseInt(abstractNumIdStr, 10);
+	if (Number.isNaN(abstractNumId)) return null;
+	const abstractNum = {
+		abstractNumId,
+		levels: []
+	};
+	let multiLevelTypeEl;
+	let nameEl;
+	let numStyleLinkEl;
+	let styleLinkEl;
+	const levelElements = [];
+	for (const child of element.elements ?? []) {
+		if (child.type !== "element") continue;
+		switch (child.name) {
+			case "w:multiLevelType":
+				multiLevelTypeEl ??= child;
+				break;
+			case "w:name":
+				nameEl ??= child;
+				break;
+			case "w:numStyleLink":
+				numStyleLinkEl ??= child;
+				break;
+			case "w:styleLink":
+				styleLinkEl ??= child;
+				break;
+			case "w:lvl":
+				levelElements.push(child);
+				break;
+			default: break;
+		}
+	}
+	if (multiLevelTypeEl) {
+		const mlType = getAttribute(multiLevelTypeEl, "w", "val");
+		if (mlType === "hybridMultilevel" || mlType === "multilevel" || mlType === "singleLevel") abstractNum.multiLevelType = mlType;
+	}
+	if (nameEl) {
+		const nameVal = getAttribute(nameEl, "w", "val");
+		if (nameVal != null) abstractNum.name = nameVal;
+	}
+	if (numStyleLinkEl) {
+		const numStyleLinkVal = getAttribute(numStyleLinkEl, "w", "val");
+		if (numStyleLinkVal != null) abstractNum.numStyleLink = numStyleLinkVal;
+	}
+	if (styleLinkEl) {
+		const styleLinkVal = getAttribute(styleLinkEl, "w", "val");
+		if (styleLinkVal != null) abstractNum.styleLink = styleLinkVal;
+	}
+	for (const lvlEl of levelElements) {
+		const level = parseListLevel(lvlEl);
+		if (level) abstractNum.levels.push(level);
+	}
+	abstractNum.levels.sort((a, b) => a.ilvl - b.ilvl);
+	return abstractNum;
+}
+/**
+* Parse a single w:num element (numbering instance)
+*/
+function parseNumberingInstance(element) {
+	const numIdStr = getAttribute(element, "w", "numId");
+	if (numIdStr === null) return null;
+	const numId = Number.parseInt(numIdStr, 10);
+	if (Number.isNaN(numId)) return null;
+	let abstractNumIdEl;
+	const overrideElements = [];
+	for (const child of element.elements ?? []) {
+		if (child.type !== "element") continue;
+		if (child.name === "w:abstractNumId") {
+			abstractNumIdEl ??= child;
+			continue;
+		}
+		if (child.name === "w:lvlOverride") overrideElements.push(child);
+	}
+	if (!abstractNumIdEl) return null;
+	const abstractNumIdStr = getAttribute(abstractNumIdEl, "w", "val");
+	if (abstractNumIdStr === null) return null;
+	const abstractNumId = Number.parseInt(abstractNumIdStr, 10);
+	if (Number.isNaN(abstractNumId)) return null;
+	const instance = {
+		numId,
+		abstractNumId
+	};
+	if (overrideElements.length > 0) {
+		instance.levelOverrides = [];
+		for (const overrideEl of overrideElements) {
+			const ilvlStr = getAttribute(overrideEl, "w", "ilvl");
+			if (ilvlStr === null) continue;
+			const ilvl = Number.parseInt(ilvlStr, 10);
+			if (Number.isNaN(ilvl)) continue;
+			const override = { ilvl };
+			let startOverrideEl;
+			let lvlEl;
+			for (const child of overrideEl.elements ?? []) {
+				if (child.type !== "element") continue;
+				if (child.name === "w:startOverride") {
+					startOverrideEl ??= child;
+					continue;
+				}
+				if (child.name === "w:lvl") lvlEl ??= child;
+			}
+			if (startOverrideEl) {
+				const startVal = getAttribute(startOverrideEl, "w", "val");
+				if (startVal !== null) {
+					const startNum = Number.parseInt(startVal, 10);
+					if (!Number.isNaN(startNum)) override.startOverride = startNum;
+				}
+			}
+			if (lvlEl) {
+				const parsedLvl = parseListLevel(lvlEl);
+				if (parsedLvl != null) override.lvl = parsedLvl;
+			}
+			instance.levelOverrides.push(override);
+		}
+	}
+	return instance;
+}
+/**
+* Parse a single w:lvl element (list level definition)
+*/
+function parseListLevel(element) {
+	const ilvlStr = getAttribute(element, "w", "ilvl");
+	if (ilvlStr === null) return null;
+	const ilvl = Number.parseInt(ilvlStr, 10);
+	if (Number.isNaN(ilvl) || ilvl < 0 || ilvl > 8) return null;
+	const level = {
+		ilvl,
+		numFmt: "decimal",
+		lvlText: ""
+	};
+	let startEl;
+	let numFmtEl;
+	let alternateEl;
+	let lvlTextEl;
+	let lvlJcEl;
+	let suffEl;
+	let isLglEl;
+	let lvlRestartEl;
+	let legacyEl;
+	let pPrEl;
+	let rPrEl;
+	for (const child of element.elements ?? []) {
+		if (child.type !== "element") continue;
+		switch (child.name) {
+			case "w:start":
+				startEl ??= child;
+				break;
+			case "w:numFmt":
+				numFmtEl ??= child;
+				break;
+			case "mc:AlternateContent":
+				alternateEl ??= child;
+				break;
+			case "w:lvlText":
+				lvlTextEl ??= child;
+				break;
+			case "w:lvlJc":
+				lvlJcEl ??= child;
+				break;
+			case "w:suff":
+				suffEl ??= child;
+				break;
+			case "w:isLgl":
+				isLglEl ??= child;
+				break;
+			case "w:lvlRestart":
+				lvlRestartEl ??= child;
+				break;
+			case "w:legacy":
+				legacyEl ??= child;
+				break;
+			case "w:pPr":
+				pPrEl ??= child;
+				break;
+			case "w:rPr":
+				rPrEl ??= child;
+				break;
+			default: break;
+		}
+	}
+	if (startEl) {
+		const startVal = getAttribute(startEl, "w", "val");
+		if (startVal !== null) {
+			const startNum = Number.parseInt(startVal, 10);
+			if (!Number.isNaN(startNum)) level.start = startNum;
+		}
+	}
+	if (numFmtEl) level.numFmt = resolveNumFmt(numFmtEl) ?? "decimal";
+	else if (alternateEl) {
+		const choiceFmt = resolveNumFmt(findChild(findChild(alternateEl, "mc", "Choice"), "w", "numFmt"));
+		const fallbackFmt = resolveNumFmt(findChild(findChild(alternateEl, "mc", "Fallback"), "w", "numFmt"));
+		level.numFmt = choiceFmt ?? fallbackFmt ?? level.numFmt;
+	}
+	if (lvlTextEl) level.lvlText = getAttribute(lvlTextEl, "w", "val") ?? "";
+	if (lvlJcEl) {
+		const jcVal = getAttribute(lvlJcEl, "w", "val");
+		if (jcVal === "left" || jcVal === "center" || jcVal === "right") level.lvlJc = jcVal;
+	}
+	if (suffEl) {
+		const suffix = narrowEnum(getAttribute(suffEl, "w", "val"), LevelSuffixSchema);
+		if (suffix) level.suffix = suffix;
+	}
+	if (isLglEl) level.isLgl = parseBooleanElement(isLglEl);
+	if (lvlRestartEl) {
+		const restartVal = getAttribute(lvlRestartEl, "w", "val");
+		if (restartVal !== null) {
+			const restartNum = Number.parseInt(restartVal, 10);
+			if (!Number.isNaN(restartNum)) level.lvlRestart = restartNum;
+		}
+	}
+	if (legacyEl) {
+		const legacySpace = parseNumericAttribute(legacyEl, "w", "legacySpace");
+		const legacyIndent = parseNumericAttribute(legacyEl, "w", "legacyIndent");
+		level.legacy = {
+			legacy: parseBooleanElement(legacyEl),
+			...legacySpace !== void 0 ? { legacySpace } : {},
+			...legacyIndent !== void 0 ? { legacyIndent } : {}
+		};
+	}
+	if (pPrEl) level.pPr = parseLevelParagraphProps(pPrEl);
+	if (rPrEl) level.rPr = parseLevelRunProps(rPrEl);
+	return level;
+}
+/**
+* Resolve a `<w:numFmt>` element to a NumberFormat we can render, or null
+* when the element is absent or its format is one we don't implement (an
+* mc:Fallback can then supply a closer rendering).
+*/
+function resolveNumFmt(numFmtEl) {
+	if (!numFmtEl) return null;
+	const fmtVal = getAttribute(numFmtEl, "w", "val");
+	if (!fmtVal) return null;
+	if (fmtVal === "custom") return parseCustomNumberFormat(getAttribute(numFmtEl, "w", "format"));
+	return NUMBER_FORMAT_MAP[fmtVal] ?? null;
+}
+/**
+* Map a `w:numFmt w:val="custom"` format string (ECMA-376 §17.9.17 — an XSLT
+* `format` token list like "0001, 0002, 0003, ...") to a NumberFormat. Word
+* only emits zero-padded decimal customs this way; the pad width is the digit
+* count of the first token (clamped to 5). Unknown patterns return null so
+* the caller can fall back to an mc:Fallback or plain decimal.
+*/
+function parseCustomNumberFormat(format) {
+	const firstToken = format?.split(",")[0]?.trim() ?? "";
+	if (/^0+1$/u.test(firstToken)) switch (Math.min(firstToken.length, 5)) {
+		case 2: return "decimalZero";
+		case 3: return "decimalZero3";
+		case 4: return "decimalZero4";
+		case 5: return "decimalZero5";
+	}
+	return null;
+}
+/**
+* Parse paragraph properties for a list level (subset of full pPr)
+* Main concern: indentation and tabs
+*/
+function parseLevelParagraphProps(pPr) {
+	const formatting = {};
+	let indEl;
+	let tabsEl;
+	for (const child of pPr.elements ?? []) {
+		if (child.type !== "element") continue;
+		if (child.name === "w:ind") {
+			indEl ??= child;
+			continue;
+		}
+		if (child.name === "w:tabs") tabsEl ??= child;
+	}
+	if (indEl) {
+		const left = parseNumericAttribute(indEl, "w", "left");
+		const right = parseNumericAttribute(indEl, "w", "right");
+		const start = parseNumericAttribute(indEl, "w", "start");
+		const end = parseNumericAttribute(indEl, "w", "end");
+		const firstLine = parseNumericAttribute(indEl, "w", "firstLine");
+		const hanging = parseNumericAttribute(indEl, "w", "hanging");
+		const resolvedLeft = left ?? start;
+		const resolvedRight = right ?? end;
+		if (resolvedLeft !== void 0) formatting.indentLeft = resolvedLeft;
+		if (resolvedRight !== void 0) formatting.indentRight = resolvedRight;
+		if (hanging !== void 0) {
+			formatting.indentFirstLine = -hanging;
+			formatting.hangingIndent = true;
+		} else if (firstLine !== void 0) formatting.indentFirstLine = firstLine;
+	}
+	if (tabsEl) {
+		formatting.tabs = [];
+		const tabElements = findChildren(tabsEl, "w", "tab");
+		for (const tabEl of tabElements) {
+			const pos = parseNumericAttribute(tabEl, "w", "pos");
+			const val = getAttribute(tabEl, "w", "val");
+			const leader = getAttribute(tabEl, "w", "leader");
+			if (pos !== void 0 && val) {
+				const parsedLeader = parseTabLeader(leader);
+				formatting.tabs.push({
+					position: pos,
+					alignment: parseTabAlignment(val),
+					...parsedLeader !== void 0 ? { leader: parsedLeader } : {}
+				});
+			}
+		}
+	}
+	return formatting;
+}
+/**
+* Parse tab alignment value
+*/
+function parseTabAlignment(val) {
+	switch (val) {
+		case "left": return "left";
+		case "center": return "center";
+		case "right": return "right";
+		case "decimal": return "decimal";
+		case "bar": return "bar";
+		case "clear": return "clear";
+		case "num": return "num";
+		default: return "left";
+	}
+}
+/**
+* Parse tab leader value
+*/
+function parseTabLeader(val) {
+	if (!val) return;
+	switch (val) {
+		case "none": return "none";
+		case "dot": return "dot";
+		case "hyphen": return "hyphen";
+		case "underscore": return "underscore";
+		case "heavy": return "heavy";
+		case "middleDot": return "middleDot";
+		default: return;
+	}
+}
+/**
+* Parse run properties for a list level (subset of full rPr)
+* Main concern: fonts for bullet characters
+*/
+function parseLevelRunProps(rPr) {
+	const formatting = {};
+	let rFontsEl;
+	let szEl;
+	let colorEl;
+	let bEl;
+	let iEl;
+	let vanishEl;
+	for (const child of rPr.elements ?? []) {
+		if (child.type !== "element") continue;
+		switch (child.name) {
+			case "w:rFonts":
+				rFontsEl ??= child;
+				break;
+			case "w:sz":
+				szEl ??= child;
+				break;
+			case "w:color":
+				colorEl ??= child;
+				break;
+			case "w:b":
+				bEl ??= child;
+				break;
+			case "w:i":
+				iEl ??= child;
+				break;
+			case "w:vanish":
+				vanishEl ??= child;
+				break;
+			default: break;
+		}
+	}
+	if (rFontsEl) {
+		const ascii = getAttribute(rFontsEl, "w", "ascii");
+		const hAnsi = getAttribute(rFontsEl, "w", "hAnsi");
+		const eastAsia = getAttribute(rFontsEl, "w", "eastAsia");
+		const cs = getAttribute(rFontsEl, "w", "cs");
+		formatting.fontFamily = {
+			...ascii != null ? { ascii } : {},
+			...hAnsi != null ? { hAnsi } : {},
+			...eastAsia != null ? { eastAsia } : {},
+			...cs != null ? { cs } : {}
+		};
+	}
+	if (szEl) {
+		const size = parseNumericAttribute(szEl, "w", "val");
+		if (size !== void 0) formatting.fontSize = size;
+	}
+	if (colorEl) {
+		const val = getAttribute(colorEl, "w", "val");
+		const validatedThemeColor = narrowEnum(getAttribute(colorEl, "w", "themeColor"), ThemeColorSlotSchema);
+		if (val === "auto") formatting.color = { auto: true };
+		else if (validatedThemeColor) {
+			const themeTint = getAttribute(colorEl, "w", "themeTint");
+			const themeShade = getAttribute(colorEl, "w", "themeShade");
+			formatting.color = {
+				themeColor: validatedThemeColor,
+				...themeTint != null ? { themeTint } : {},
+				...themeShade != null ? { themeShade } : {}
+			};
+		} else if (val) formatting.color = { rgb: val };
+	}
+	if (bEl) formatting.bold = parseBooleanElement(bEl);
+	if (iEl) formatting.italic = parseBooleanElement(iEl);
+	if (vanishEl) formatting.hidden = parseBooleanElement(vanishEl);
+	return formatting;
+}
+/**
+* Per-definitions cache for `createNumberingMap`. Style application rebuilds
+* the lookup map on every picker click otherwise; the definitions object is
+* stable for a document's lifetime, so cache by identity.
+*/
+const numberingMapCache = /* @__PURE__ */ new WeakMap();
+function getCachedNumberingMap(definitions) {
+	let map = numberingMapCache.get(definitions);
+	if (!map) {
+		map = createNumberingMap(definitions);
+		numberingMapCache.set(definitions, map);
+	}
+	return map;
+}
+/**
+* Create a NumberingMap with helper functions
+*/
+function createNumberingMap(definitions) {
+	const abstractMap = /* @__PURE__ */ new Map();
+	for (const abs of definitions.abstractNums) abstractMap.set(abs.abstractNumId, abs);
+	const numMap = /* @__PURE__ */ new Map();
+	for (const num of definitions.nums) numMap.set(num.numId, num);
+	return {
+		definitions,
+		getLevel(numId, ilvl) {
+			const num = numMap.get(numId);
+			if (!num) return null;
+			if (num.levelOverrides) {
+				const override = num.levelOverrides.find((o) => o.ilvl === ilvl);
+				if (override) {
+					if (override.lvl) return override.lvl;
+					const abstractNum = abstractMap.get(num.abstractNumId);
+					if (abstractNum) {
+						const baseLevel = abstractNum.levels.find((l) => l.ilvl === ilvl);
+						if (baseLevel && override.startOverride !== void 0) return {
+							...baseLevel,
+							start: override.startOverride
+						};
+					}
+				}
+			}
+			let abstractNum = abstractMap.get(num.abstractNumId);
+			if (!abstractNum) return null;
+			if (abstractNum.numStyleLink && abstractNum.levels.length === 0) {
+				for (const candidate of abstractMap.values()) if (candidate.styleLink === abstractNum.numStyleLink && candidate.levels.length > 0) {
+					abstractNum = candidate;
+					break;
+				}
+			}
+			return abstractNum.levels.find((l) => l.ilvl === ilvl) ?? null;
+		},
+		getAbstractNumId(numId) {
+			return numMap.get(numId)?.abstractNumId ?? null;
+		},
+		getAbstract(abstractNumId) {
+			return abstractMap.get(abstractNumId) ?? null;
+		},
+		getInstance(numId) {
+			return numMap.get(numId) ?? null;
+		},
+		hasNumbering(numId) {
+			return numMap.has(numId);
+		}
+	};
+}
+/**
+* Resolve a paragraph's `numPr` against the numbering definitions into the
+* base `ListRendering` the layout pipeline needs (marker template, per-level
+* numFmts, counter key, start override). Returns null when the numPr doesn't
+* name a real level — including `numId === 0`, "no numbering" per ECMA-376.
+*
+* Shared by the style picker (`listAttrsFromResolvedStyle`) so a style-attached
+* list renders the same marker the document loader produces. The loader's
+* `parseParagraph` block additionally folds inline LISTNUM markers and computes
+* the second-slot offset from the paragraph's content; those fields are absent
+* here because the picker has no paragraph content to inspect.
+*/
+function computeListRendering(numPr, numbering) {
+	const { numId, ilvl = 0 } = numPr;
+	if (numId === void 0 || numId === 0) return null;
+	const level = numbering.getLevel(numId, ilvl);
+	if (!level) return null;
+	const levelNumFmts = [];
+	for (let i = 0; i <= ilvl; i += 1) levelNumFmts.push(level.isLgl ? "decimal" : numbering.getLevel(numId, i)?.numFmt ?? "decimal");
+	const instance = numbering.getInstance(numId);
+	const overrideForLevel = instance?.levelOverrides?.find((override) => override.ilvl === ilvl);
+	const rendering = {
+		level: ilvl,
+		numId,
+		marker: level.lvlText,
+		isBullet: level.numFmt === "bullet",
+		numFmt: level.isLgl ? "decimal" : level.numFmt,
+		levelNumFmts
+	};
+	if (level.isLgl) rendering.isLegal = true;
+	if (level.rPr?.hidden) rendering.markerHidden = true;
+	const markerFont = level.rPr?.fontFamily?.ascii || level.rPr?.fontFamily?.hAnsi;
+	if (markerFont) rendering.markerFontFamily = markerFont;
+	if (level.rPr?.fontSize) rendering.markerFontSize = level.rPr.fontSize / 2;
+	if (level.rPr?.allCaps) rendering.markerAllCaps = true;
+	if (level.suffix) rendering.markerSuffix = level.suffix;
+	if (instance?.abstractNumId !== void 0) rendering.abstractNumId = instance.abstractNumId;
+	if (overrideForLevel?.startOverride !== void 0) rendering.startOverride = overrideForLevel.startOverride;
+	return rendering;
+}
+/**
+* Format a number according to the specified format
+*
+* @param num - The number to format
+* @param format - The number format
+* @returns Formatted string
+*/
+function formatNumber(num, format) {
+	switch (format) {
+		case "decimal": return num.toString();
+		case "decimalZero": return padDecimal(num, 2);
+		case "decimalZero3": return padDecimal(num, 3);
+		case "decimalZero4": return padDecimal(num, 4);
+		case "decimalZero5": return padDecimal(num, 5);
+		case "upperRoman": return toRoman(num).toUpperCase();
+		case "lowerRoman": return toRoman(num).toLowerCase();
+		case "upperLetter": return toLetter(num).toUpperCase();
+		case "lowerLetter": return toLetter(num).toLowerCase();
+		case "ordinal": return toOrdinal(num);
+		case "bullet": return "•";
+		case "none": return "";
+		case "decimalEnclosedParen": return `(${num})`;
+		case "numberInDash": return `-${num}-`;
+		default: return num.toString();
+	}
+}
+/** Zero-pad a counter to `width` digits ("decimalZero" family, §17.18.59). */
+function padDecimal(num, width) {
+	if (num < 0) return num.toString();
+	return num.toString().padStart(width, "0");
+}
+/**
+* Compare two `numPr` references by value — `numId` plus `ilvl` (a missing
+* `ilvl` is level 0). Used for the style-sourced-numbering provenance check;
+* avoids JSON.stringify equality, which is sensitive to key order.
+*/
+function numPrEqual(a, b) {
+	if (a == null || b == null) return a == null && b == null;
+	return a.numId === b.numId && (a.ilvl ?? 0) === (b.ilvl ?? 0);
+}
+/**
+* Convert number to Roman numerals
+*/
+function toRoman(num) {
+	if (num <= 0 || num > 3999) return num.toString();
+	const romanNumerals = [
+		[1e3, "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 = num;
+	for (const [value, numeral] of romanNumerals) while (remaining >= value) {
+		result += numeral;
+		remaining -= value;
+	}
+	return result;
+}
+function toLetter(num) {
+	if (num <= 0) return "";
+	const zeroBased = num - 1;
+	return String.fromCodePoint(97 + zeroBased % 26).repeat(Math.floor(zeroBased / 26) + 1);
+}
+/**
+* Convert number to ordinal (1st, 2nd, 3rd, ...)
+*/
+function toOrdinal(num) {
+	const suffix = [
+		"th",
+		"st",
+		"nd",
+		"rd"
+	];
+	const v = num % 100;
+	return num + (suffix[(v - 20) % 10] ?? suffix[v] ?? suffix[0] ?? "th");
+}
+/**
+* Render list marker text by replacing placeholders with formatted numbers
+*
+* @param lvlText - The level text pattern (e.g., "%1.", "%1.%2")
+* @param counters - Array of counter values for each level (index 0 = level 0, etc.)
+* @param formats - Array of number formats for each level
+* @returns Rendered marker text
+*/
+function renderListMarker(lvlText, counters, formats) {
+	let result = lvlText;
+	for (let i = 1; i <= 9; i++) {
+		const placeholder = `%${i}`;
+		if (result.includes(placeholder)) {
+			const counterIndex = i - 1;
+			const formatted = formatNumber(counters[counterIndex] ?? 1, formats[counterIndex] ?? "decimal");
+			result = result.replaceAll(placeholder, formatted);
+		}
+	}
+	return result;
+}
+/**
+* Get the bullet character for a bullet list level
+*
+* @param level - The list level definition
+* @returns The bullet character to display
+*/
+function getBulletCharacter(level) {
+	if (level.lvlText) return level.lvlText;
+	const fontFamily = level.rPr?.fontFamily?.ascii || level.rPr?.fontFamily?.hAnsi;
+	if (fontFamily) {
+		const fontLower = fontFamily.toLowerCase();
+		if (fontLower === "symbol") return "•";
+		if (fontLower.includes("wingding")) return "❑";
+	}
+	return "•";
+}
+/**
+* Check if a list level is a bullet (not numbered)
+*/
+function isBulletLevel(level) {
+	return level.numFmt === "bullet" || level.numFmt === "none";
+}
+//#endregion
+export { computeListRendering, createNumberingMap, formatNumber, getBulletCharacter, getCachedNumberingMap, isBulletLevel, numPrEqual, padDecimal, parseNumbering, renderListMarker };