rtf-codec 2.0.0 → 3.0.0

package/dist/write.js

@@ -3,6 +3,7 @@ import { RtfDiagnosticCodes, RtfUnsupportedDocumentKindError } from "./diagnosti
 import { pointsToHalfPoints, pointsToTwips } from "./units.js";
 import { borderControlWords } from "./cell-format.js";
 import { bookmarkResidueControlWords, dttmFromIso, isBookmarkAnchor } from "./constructs.js";
+import { writeEmbeddedObjectData } from "./embedded-object.js";
 import { parseRtfListNumId } from "./list-id.js";
 import { clampHeadingLevel, colorToRgbHex, flattenTree, resolveCellFillColor } from "document-schema.js";
 //#region src/write.ts
@@ -13,6 +14,11 @@ const LIST_MARKER_HANG_TWIPS = 360;
 const BULLET_LEVEL_TEXT = "\\'01\\u183 ?";
 const ARABIC_LEVEL_TEXT = "\\'02\\'00.";
 const OUTPUT_CODEPAGE = 1252;
+const CELL_BLOCK_KINDS = /* @__PURE__ */ new Set([
+	"paragraph",
+	"image",
+	"embeddedObject"
+]);
 const SECTION_BREAK_CONTROL_WORDS = /* @__PURE__ */ new Map([
 	["continuous", "\\sbknone"],
 	["evenPage", "\\sbkeven"],
@@ -124,6 +130,112 @@ function bookmarkStartGroup(descriptor) {
 	if (!isBookmarkAnchor(descriptor)) return "";
 	return `{\\*\\bkmkstart${bookmarkResidueControlWords(descriptor)} ${escapeText(descriptor.name)}}`;
 }
+const FORM_FIELD_SPEC = /* @__PURE__ */ new Map([
+	["plainText", {
+		instruction: "FORMTEXT",
+		fftype: 0
+	}],
+	["checkbox", {
+		instruction: "FORMCHECKBOX",
+		fftype: 1
+	}],
+	["dropDown", {
+		instruction: "FORMDROPDOWN",
+		fftype: 2
+	}]
+]);
+const MAX_DROPDOWN_OPTIONS = 25;
+function formFieldPayload(descriptor, fftype, sink) {
+	const fftypeFragment = `\\fftype${String(fftype)}`;
+	let ffNameString = "";
+	let ffDefTextString = "";
+	let ffHelpTextString = "";
+	let fflEntries = "";
+	let ffOwnHelpFragment = "";
+	if (descriptor.alias !== void 0 && descriptor.alias.trim().length > 0) {
+		ffOwnHelpFragment = "\\ffownhelp1";
+		ffHelpTextString = `{\\*\\ffhelptext ${escapeText(descriptor.alias)}}`;
+	}
+	let ffProtFragment = "";
+	if (descriptor.lock === "content" || descriptor.lock === "both") ffProtFragment = "\\ffprot1";
+	if (descriptor.lock === "container" || descriptor.lock === "both") {
+		const message = descriptor.lock === "both" ? `a contentControl's 'both' lock also protects the control from removal, which RTF's \\ffprot ([MS-DOC] 2.9.79 FFDataBits.fProt) cannot express -- \\ffprot1 above already carries the content-protection half of 'both', so only the container-removal half is dropped here` : `a contentControl's 'container' lock protects the control from removal, which RTF's \\ffprot ([MS-DOC] 2.9.79 FFDataBits.fProt) cannot express at all -- it names only whether the field's own value can be changed, and a 'container' lock leaves that value editable, so nothing is written for it and the whole lock is dropped, not merely half of it`;
+		sink({
+			code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+			severity: "warning",
+			message
+		});
+	}
+	let controlTypeParams = "";
+	if (descriptor.controlType === "checkbox") {
+		const value = descriptor.checked === true ? "1" : "0";
+		controlTypeParams += `\\ffdefres${value}\\ffres${value}`;
+		if (descriptor.value !== void 0 && descriptor.value.length > 0) sink({
+			code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+			severity: "warning",
+			message: `a checkbox contentControl's value '${descriptor.value}' (its on-state export name) is dropped: RTF's \\ffres/\\ffdefres can only carry the field's boolean checked state, with no spelling for a named export value at all`
+		});
+		if (descriptor.options !== void 0 && descriptor.options.length > 0) sink({
+			code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+			severity: "warning",
+			message: `a checkbox contentControl's options list (${String(descriptor.options.length)} entries) is dropped: a checkbox has no choice list at all, in RTF or in the harmonised contentControl vocabulary itself`
+		});
+	} else if (descriptor.controlType === "dropDown") {
+		controlTypeParams += "\\ffhaslistbox1";
+		const allOptions = descriptor.options;
+		let options = allOptions;
+		if (allOptions !== void 0 && allOptions.length > MAX_DROPDOWN_OPTIONS) {
+			sink({
+				code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+				severity: "warning",
+				message: `a dropDown contentControl's ${String(allOptions.length)} options exceed [MS-DOC] 2.9.78 FFData.hsttbDropList's own ${String(MAX_DROPDOWN_OPTIONS)}-entry limit; only the first ${String(MAX_DROPDOWN_OPTIONS)} are written`
+			});
+			options = allOptions.slice(0, MAX_DROPDOWN_OPTIONS);
+		}
+		const selectedIndex = options === void 0 || descriptor.value === void 0 ? void 0 : options.indexOf(descriptor.value);
+		if (selectedIndex !== void 0 && selectedIndex !== -1) controlTypeParams += `\\ffdefres${String(selectedIndex)}\\ffres${String(selectedIndex)}`;
+		else if (descriptor.value !== void 0 && descriptor.value.length > 0) {
+			const truncatedAway = allOptions !== void 0 && options !== allOptions && allOptions.includes(descriptor.value);
+			sink({
+				code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+				severity: "warning",
+				message: truncatedAway ? `a dropDown contentControl's selected value '${descriptor.value}' is dropped: its matching option was truncated away by [MS-DOC] 2.9.78 FFData.hsttbDropList's own ${String(MAX_DROPDOWN_OPTIONS)}-entry limit, and \\ffres/\\ffdefres can only name a real index into the entries actually written` : `a dropDown contentControl's selected value '${descriptor.value}' is dropped: it does not match any of the field's own options, and \\ffres/\\ffdefres can only name a real index into that list`
+			});
+		}
+		if (options !== void 0) for (const option of options) fflEntries += `{\\*\\ffl ${escapeText(option)}}`;
+		if (descriptor.checked !== void 0) sink({
+			code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+			severity: "warning",
+			message: `a dropDown contentControl's checked state (${String(descriptor.checked)}) is dropped: a dropdown has no boolean checked state at all, in RTF or in the harmonised contentControl vocabulary itself`
+		});
+	} else if (descriptor.controlType === "plainText") {
+		if (descriptor.value !== void 0 && descriptor.value.length > 0) {
+			ffDefTextString = `{\\*\\ffdeftext ${escapeText(descriptor.value)}}`;
+			sink({
+				code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+				severity: "warning",
+				message: `a plainText contentControl's value '${descriptor.value}' is written into {\\*\\ffdeftext ...}, FFData.xstzTextDef's default/reset text, not a slot for the field's current value: this codec's own reader does not restore \\ffdeftext back onto \`value\`, so this does not round-trip`
+			});
+		}
+		if (descriptor.checked !== void 0) sink({
+			code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+			severity: "warning",
+			message: `a plainText contentControl's checked state (${String(descriptor.checked)}) is dropped: a text field has no boolean checked state at all, in RTF or in the harmonised contentControl vocabulary itself`
+		});
+		if (descriptor.options !== void 0 && descriptor.options.length > 0) sink({
+			code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+			severity: "warning",
+			message: `a plainText contentControl's options list (${String(descriptor.options.length)} entries) is dropped: a text field has no choice list at all, in RTF or in the harmonised contentControl vocabulary itself`
+		});
+	}
+	if (descriptor.tag !== void 0 && descriptor.tag.trim().length > 0) ffNameString = `{\\*\\ffname ${escapeText(descriptor.tag)}}`;
+	return fftypeFragment + ffOwnHelpFragment + ffProtFragment + controlTypeParams + ffNameString + ffDefTextString + ffHelpTextString + fflEntries;
+}
+function formFieldOpenGroup(descriptor, sink) {
+	const spec = FORM_FIELD_SPEC.get(descriptor.controlType);
+	if (spec === void 0) return;
+	return `{\\field{\\*\\fldinst ${spec.instruction} {\\*\\formfield{${formFieldPayload(descriptor, spec.fftype, sink)}}}}{\\fldrslt `;
+}
 const CHREV_CONTROL_WORDS = {
 	insertion: {
 		flag: "\\revised",
@@ -174,9 +286,35 @@ function verticalMergeCoverage(table) {
 function nameOf(descriptor) {
 	return isBookmarkAnchor(descriptor) ? descriptor.name : "";
 }
+function isContentControlExtent(extent) {
+	return extent.descriptor.kind === "contentControl";
+}
+function selectNestableFormFields(extents, sink) {
+	const sorted = [...extents].sort((a, b) => a.startRun - b.startRun || b.endRun - a.endRun);
+	const stack = [];
+	const accepted = [];
+	for (const extent of sorted) {
+		let top = stack[stack.length - 1];
+		while (top !== void 0 && top.endRun <= extent.startRun) {
+			stack.pop();
+			top = stack[stack.length - 1];
+		}
+		if (top !== void 0 && extent.endRun > top.endRun) {
+			sink({
+				code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+				severity: "warning",
+				message: "a contentControl construct is dropped: it crosses another contentControl extent in the same paragraph (starts before that extent ends but ends after it too), and RTF's \\*\\formfield destination can only nest properly, never cross"
+			});
+			continue;
+		}
+		stack.push(extent);
+		accepted.push(extent);
+	}
+	return accepted;
+}
 function describeConstructGap(descriptor) {
 	switch (descriptor.kind) {
-		case "contentControl": return "structured-document-tag equivalent; its own \\*\\formfield production is a narrower construct this writer does not yet mint";
+		case "contentControl": return "block-scoped structured-document-tag equivalent -- a run-scoped plainText/checkbox/dropDown form field mints its own \\*\\formfield instead; any other controlType (richText, comboBox, date, and the rest) has no \\*\\formfield spelling at all";
 		case "provenance": return "block-scoped revision mark: its <chrev> production is a character property, so a tracked change reaches RTF only as a run-level extent";
 		case "anchor": return `spelling for a '${descriptor.anchorType}' anchor, whose body would need the note or annotation destination this reader does not place`;
 		case "field": return "block-scoped field: a field is a character-stream construct, written from a run's own hyperlink rather than from a block marker";
@@ -184,6 +322,9 @@ function describeConstructGap(descriptor) {
 		default: return "equivalent construct";
 	}
 }
+function describeFormFieldGap(descriptor) {
+	return `\\*\\formfield spelling for a '${descriptor.controlType}' controlType -- only plainText/checkbox/dropDown form fields mint one`;
+}
 var RtfWriter = class {
 	tables;
 	sink;
@@ -300,11 +441,7 @@ var RtfWriter = class {
 				this.line("\\page\\pard");
 				return;
 			case "embeddedObject":
-				this.sink({
-					code: RtfDiagnosticCodes.EMBEDDED_OBJECT_DROPPED,
-					severity: "warning",
-					message: `an embedded ${block.objectKind} object is dropped: writing it as an RTF \\object would need the OLE container this package does not build`
-				});
+				this.writeEmbeddedObjectBlock(block);
 				return;
 			case "constructStart":
 				this.openConstruct(block.descriptor);
@@ -339,13 +476,22 @@ var RtfWriter = class {
 		this.raw(" ");
 		const bookmarks = (paragraph.constructs ?? []).filter((extent) => isBookmarkAnchor(extent.descriptor));
 		const revisions = (paragraph.constructs ?? []).filter((extent) => extent.descriptor.kind === "provenance");
+		const formFields = selectNestableFormFields((paragraph.constructs ?? []).filter(isContentControlExtent), this.sink);
+		const openedFormFields = [];
 		for (const [index, run] of paragraph.runs.entries()) {
 			this.writeRunBoundaries(bookmarks, index);
+			this.writeFormFieldBoundaries(formFields, index, openedFormFields);
 			this.writeRun(run, revisionsCovering(revisions, index));
 		}
 		this.writeRunBoundaries(bookmarks, paragraph.runs.length);
+		this.writeFormFieldBoundaries(formFields, paragraph.runs.length, openedFormFields);
+		this.drainOpenedFormFields(openedFormFields);
 		if (!inTable) this.line("\\par");
 	}
+	drainOpenedFormFields(opened) {
+		for (let remaining = opened.length; remaining > 0; remaining -= 1) this.raw("}}");
+		opened.length = 0;
+	}
 	writeRunBoundaries(extents, position) {
 		for (const extent of extents) if (extent.endRun === position && extent.startRun !== position) this.raw(`{\\*\\bkmkend ${escapeText(nameOf(extent.descriptor))}}`);
 		for (const extent of extents) if (extent.startRun === position) {
@@ -353,6 +499,32 @@ var RtfWriter = class {
 			if (extent.endRun === position) this.raw(`{\\*\\bkmkend ${escapeText(nameOf(extent.descriptor))}}`);
 		}
 	}
+	writeFormFieldBoundaries(extents, position, opened) {
+		let top = opened[opened.length - 1];
+		while (top?.endRun === position) {
+			opened.pop();
+			this.raw("}}");
+			top = opened[opened.length - 1];
+		}
+		for (const extent of extents) {
+			if (extent.startRun !== position) continue;
+			const open = formFieldOpenGroup(extent.descriptor, this.sink);
+			if (open === void 0) {
+				this.sink({
+					code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+					severity: "warning",
+					message: `a contentControl construct is dropped: RTF has no ${describeFormFieldGap(extent.descriptor)}`
+				});
+				continue;
+			}
+			this.raw(open);
+			opened.push(extent);
+			if (extent.endRun === position) {
+				opened.pop();
+				this.raw("}}");
+			}
+		}
+	}
 	paragraphProperties(paragraph) {
 		let out = "";
 		const level = paragraph.headingLevel === void 0 ? void 0 : clampHeadingLevel(paragraph.headingLevel);
@@ -466,17 +638,48 @@ var RtfWriter = class {
 		return `${out}\\cellx${String(rightTwips)}`;
 	}
 	writeCellBlocks(blocks) {
-		const paragraphs = blocks.filter((block) => block.kind === "paragraph");
-		if (paragraphs.length === 0) {
-			this.raw("\\pard\\plain\\intbl ");
-			return;
-		}
-		for (const [index, paragraph] of paragraphs.entries()) {
-			this.writeParagraph(paragraph, true);
-			if (index < paragraphs.length - 1) this.raw("\\par");
+		let wroteBlock = false;
+		let blockPending = false;
+		for (const [index, block] of blocks.entries()) {
+			if (block.kind === "constructStart" || block.kind === "constructEnd") {
+				if (blockPending && blocks.slice(index + 1).some((later) => CELL_BLOCK_KINDS.has(later.kind))) {
+					this.raw("\\par");
+					blockPending = false;
+				}
+				if (block.kind === "constructStart") this.openConstruct(block.descriptor);
+				else this.closeConstruct();
+				continue;
+			}
+			if (!CELL_BLOCK_KINDS.has(block.kind)) {
+				this.sink({
+					code: RtfDiagnosticCodes.CONSTRUCT_UNREPRESENTED,
+					severity: "warning",
+					message: `a ${block.kind} block inside a table cell is dropped: this writer cannot yet splice a ${block.kind}'s own destination grammar into a table row's own \\intbl flow`
+				});
+				continue;
+			}
+			if (block.kind === "image") {
+				const decoded = this.decodeImageOrWarn(block);
+				if (decoded === void 0) continue;
+				if (blockPending) this.raw("\\par");
+				this.writeImagePict(decoded, block, true);
+				wroteBlock = true;
+				blockPending = false;
+				continue;
+			}
+			if (blockPending) this.raw("\\par");
+			if (block.kind === "paragraph") {
+				this.writeParagraph(block, true);
+				blockPending = true;
+			} else if (block.kind === "embeddedObject") {
+				this.writeEmbeddedObjectBlock(block, true);
+				blockPending = false;
+			}
+			wroteBlock = true;
 		}
+		if (!wroteBlock) this.raw("\\pard\\plain\\intbl ");
 	}
-	writeImageParagraph(base64, image) {
+	decodeImageOrWarn(image) {
 		if (image.format === "svg" || image.format === "gif") {
 			this.sink({
 				code: RtfDiagnosticCodes.UNSUPPORTED_PICTURE_FORMAT,
@@ -485,7 +688,7 @@ var RtfWriter = class {
 			});
 			return;
 		}
-		const bytes = base64ToBytes(base64);
+		const bytes = base64ToBytes(image.base64);
 		if (bytes === void 0 || bytes.length === 0) {
 			this.sink({
 				code: RtfDiagnosticCodes.UNSUPPORTED_PICTURE_FORMAT,
@@ -494,9 +697,30 @@ var RtfWriter = class {
 			});
 			return;
 		}
+		return bytes;
+	}
+	writeImagePict(bytes, image, inTable) {
 		const widthTwips = pointsToTwips(image.widthPt);
 		const heightTwips = pointsToTwips(image.heightPt);
-		this.line(`\\pard\\plain {\\*\\shppict{\\pict\\${image.format === "png" ? "pngblip" : "jpegblip"}\\picwgoal${String(widthTwips)}\\pichgoal${String(heightTwips)}${this.lineEnding}${wrapHex(bytesToHex(bytes), this.lineEnding)}}}\\par`);
+		const pict = `\\pard\\plain${inTable ? "\\intbl" : ""} {\\*\\shppict{\\pict\\${image.format === "png" ? "pngblip" : "jpegblip"}\\picwgoal${String(widthTwips)}\\pichgoal${String(heightTwips)}${this.lineEnding}${wrapHex(bytesToHex(bytes), this.lineEnding)}}}`;
+		if (inTable) this.raw(pict);
+		else this.line(`${pict}\\par`);
+	}
+	writeImageParagraph(base64, image) {
+		const bytes = this.decodeImageOrWarn({
+			...image,
+			base64
+		});
+		if (bytes === void 0) return;
+		this.writeImagePict(bytes, image, false);
+	}
+	writeEmbeddedObjectBlock(block, inTable = false) {
+		const widthTwips = pointsToTwips(block.frame.widthPt);
+		const heightTwips = pointsToTwips(block.frame.heightPt);
+		const objdataBytes = writeEmbeddedObjectData(block);
+		const object = `\\pard\\plain${inTable ? "\\intbl" : ""} {\\object\\objemb\\objw${String(widthTwips)}\\objh${String(heightTwips)}{\\*\\objclass ${escapeText(block.objectKind)}}{\\*\\objdata${this.lineEnding}${wrapHex(bytesToHex(objdataBytes), this.lineEnding)}}{\\result{\\pard\\plain ${escapeText(`[embedded ${block.objectKind} object]`)}\\par}}}`;
+		if (inTable) this.raw(object);
+		else this.line(`${object}\\par`);
 	}
 };
 function colorIndexOf(color, colors) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rtf-codec",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Hand-written Rich Text Format (RTF 1.9.1) reader and writer against the shared document-schema.js content pivot.",
   "type": "module",
   "repository": {
@@ -62,6 +62,8 @@
     "test:watch": "vitest --project unit",
     "test:coverage": "turbo run _test:coverage",
     "_test:coverage": "vitest run --project unit --coverage",
+    "test:mutation": "turbo run _test:mutation",
+    "_test:mutation": "stryker run stryker.config.mjs",
     "test:smoke": "turbo run _test:smoke",
     "_test:smoke": "vitest run --project smoke",
     "prepare": "husky",
@@ -78,16 +80,21 @@
   "license": "MIT",
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "document-schema.js": "^6.0.0",
+    "archive-codec": "^1.6.0",
+    "document-schema.js": "^6.1.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@cloudflare/vitest-pool-workers": "^0.21.2",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/typescript-checker": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.8.0",
     "husky": "^9.1.7",
+    "jiti": "2.7.0",
     "publint": "^0.3.21",
     "semantic-release": "^25.0.8",
     "tsdown": "^0.22.13",