@stll/folio-core 0.54.2 → 0.55.0

package/dist/docx/serializer/noteSerializer.js

@@ -1,9 +1,11 @@
+import { hasNoteReferenceMark } from "../noteReferenceMark.js";
 import { serializeBlockCustomXml } from "./blockCustomXmlSerializer.js";
 import { serializeBlockSdt } from "./blockSdtSerializer.js";
 import { serializeBookmarkMarker } from "./markupRangeAttributes.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializePartElement } from "./partNamespaces.js";
 import { serializeTable } from "./tableSerializer.js";
+import { noteUsesCustomMark } from "@stll/docx-core/ops";
 //#region src/docx/serializer/noteSerializer.ts
 const NOTE_BASELINE_PREFIXES = [
 	"wpc",
@@ -66,8 +68,9 @@ const NOTE_SEPARATOR_BODY = "<w:p><w:pPr><w:spacing w:after=\"0\" w:line=\"240\"
 function serializeRequiredNoteSeparators(elementName) {
 	return `<w:${elementName} w:type="separator" w:id="-1">${NOTE_SEPARATOR_BODY}<w:r><w:separator/></w:r></w:p></w:${elementName}><w:${elementName} w:type="continuationSeparator" w:id="0">${NOTE_SEPARATOR_BODY}<w:r><w:continuationSeparator/></w:r></w:p></w:${elementName}>`;
 }
-function insertNoteReferenceMark(xml, elementName) {
-	if (new RegExp(`<(?:[\\w.-]+:)?${elementName}Ref[\\s/>]`, "u").test(xml)) return xml;
+function insertNoteReferenceMark({ xml, elementName, note, customMark }) {
+	if (customMark) return xml;
+	if (hasNoteReferenceMark(elementName, note.content)) return xml;
 	const paragraphOpen = /<w:p(?=[\s>])[^>]*>/u.exec(xml);
 	if (!paragraphOpen) return `${`<w:p><w:r><w:rPr><w:rStyle w:val="${elementName === "footnote" ? "FootnoteReference" : "EndnoteReference"}"/></w:rPr><w:${elementName}Ref/></w:r></w:p>`}${xml}`;
 	const paragraphStart = paragraphOpen.index + paragraphOpen[0].length;
@@ -77,8 +80,13 @@ function insertNoteReferenceMark(xml, elementName) {
 	const referenceRun = `<w:r><w:rPr><w:rStyle w:val="${elementName === "footnote" ? "FootnoteReference" : "EndnoteReference"}"/></w:rPr><w:${elementName}Ref/></w:r>`;
 	return `${xml.slice(0, insertAt)}${referenceRun}${xml.slice(insertAt)}`;
 }
-function serializeNewNotePart(elementName, notes) {
-	const serializedNotes = notes.map((note) => insertNoteReferenceMark(serializeNote(elementName, note), elementName)).join("");
+function serializeNewNotePart({ elementName, notes, document }) {
+	const serializedNotes = notes.map((note) => insertNoteReferenceMark({
+		xml: serializeNote(elementName, note),
+		elementName,
+		note,
+		customMark: document ? noteUsesCustomMark(document, note) : false
+	})).join("");
 	return serializeNotePart(elementName, serializeRequiredNoteSeparators(elementName) + serializedNotes);
 }
 /**
@@ -101,13 +109,21 @@ function serializeEndnotes(endnotes) {
 }
 /** Serialize a brand-new footnote part, including Word's required separators
 * and the automatic reference mark at the start of every normal note. */
-function serializeNewFootnotesPart(footnotes) {
-	return serializeNewNotePart("footnote", footnotes);
+function serializeNewFootnotesPart(footnotes, document) {
+	return serializeNewNotePart({
+		elementName: "footnote",
+		notes: footnotes,
+		...document ? { document } : {}
+	});
 }
 /** Serialize a brand-new endnote part, including Word's required separators
 * and the automatic reference mark at the start of every normal note. */
-function serializeNewEndnotesPart(endnotes) {
-	return serializeNewNotePart("endnote", endnotes);
+function serializeNewEndnotesPart(endnotes, document) {
+	return serializeNewNotePart({
+		elementName: "endnote",
+		notes: endnotes,
+		...document ? { document } : {}
+	});
 }
 //#endregion
 export { serializeEndnotes, serializeFootnotes, serializeNewEndnotesPart, serializeNewFootnotesPart };

package/dist/docx/serializer/paragraphSerializer.js

@@ -2,7 +2,9 @@ import { modelParagraphFormattingEmission, serializeParagraphPropertySet } from
 import { serializePreservedAttributes } from "../attributeRemainder.js";
 import { CONTAINER_CHILDREN } from "../containerChildren.gen.js";
 import { fieldStateAttributes } from "../fieldState.js";
+import { serializeEmptyMarkProperties } from "../paragraphMarkPropertyPresence.js";
 import { getParagraphPropertySource, paragraphPropertySourceMatchesEmission } from "../paragraphPropertySource.js";
+import { ReviewResolutionProvenanceError, paragraphMarkResolutionJoinAttributes, serializeParagraphMarkResolutionJoin, serializeResolutionJoins } from "../reviewResolutionProvenance.js";
 import { DATE_UTC_ATTRIBUTE } from "../trackedChangeInfo.js";
 import { toTransitionalNamespaceUri } from "../transitionalSpelling.js";
 import { captureVerbatimXml, createCapturedXmlSanitizer } from "../verbatimCapture.js";
@@ -20,11 +22,22 @@ import { PARAGRAPH_MARK_CHANGE_KINDS } from "@stll/docx-core/model";
 import { SEQUENCE_CHILDREN } from "@stll/docx-core/schema";
 //#region src/docx/serializer/paragraphSerializer.ts
 /**
+* Paragraph Serializer - Serialize paragraphs to OOXML XML
+*
+* Converts Paragraph objects back to <w:p> XML format for DOCX files.
+* Handles all paragraph properties and child content (runs, hyperlinks, fields, bookmarks).
+*
+* OOXML Reference:
+* - Paragraph: w:p
+* - Paragraph properties: w:pPr
+* - Runs, hyperlinks, bookmarks, fields as child elements
+*/
+/**
 * Serialize paragraph formatting properties to w:pPr XML
 */
 function serializeParagraphMarkChange(mark) {
 	const attrs = serializeTrackedChangeAttributes(mark.info);
-	return `<w:${mark.kind} ${attrs}/>`;
+	return `<w:${mark.kind} ${attrs}${serializeParagraphMarkResolutionJoin(mark)}/>`;
 }
 const RESERVED_PARAGRAPH_PROPERTY_CHILDREN = /* @__PURE__ */ new Set(["pPrChange", "sectPr"]);
 /**
@@ -212,7 +225,10 @@ const withTrailingParagraphPropertyChildren = (sourceXml, children) => {
 const withParagraphMarkChange = (sourceXml, mark) => {
 	const root = parseXml(sourceXml, OOXML_NAMESPACE_SCOPE).elements?.at(0);
 	if (!root || root.type !== "element") panic("A validated paragraph-property capture could not be parsed for composition");
-	const attributes = trackedChangeAttributeRecord(mark.info);
+	const attributes = {
+		...trackedChangeAttributeRecord(mark.info),
+		...paragraphMarkResolutionJoinAttributes(mark)
+	};
 	const markElement = cloneElement(root, {
 		name: `w:${mark.kind}`,
 		attributes,
@@ -339,6 +355,20 @@ function serializeComplexField(field) {
 	parts.push(`<w:r>${rPrXml}<w:fldChar w:fldCharType="end"/></w:r>`);
 	return parts.join("");
 }
+var UnrepresentableTrackedCaptureError = class extends TaggedError("UnrepresentableTrackedCaptureError") {};
+/**
+* Preserved markup inside a removal. Markup captured from a removal already
+* spells its text as deleted text. Markup captured outside one and put under
+* a removal afterwards does not: plain runs are respelled here, as a deleted
+* run is. A folded list-number capture that cannot be respelled is refused,
+* rather than written as live text inside the removal.
+*/
+function serializeRemovedPreservedInline(item) {
+	if (!/<w:(?:t|instrText)[\s>]/u.test(item.xml)) return item.xml;
+	if (/^<w:r[\s>]/u.test(item.xml) && !/<w:(?:drawing|pict|object)\b|<mc:AlternateContent\b/u.test(item.xml)) return rewriteRunTextAsDeleted(item.xml);
+	if (item.foldedListNumber) throw new UnrepresentableTrackedCaptureError({ message: "A folded list-number field holds markup that cannot be written as deleted content." });
+	return item.xml;
+}
 var UnrepresentableTrackedSimpleFieldError = class extends TaggedError("UnrepresentableTrackedSimpleFieldError") {};
 /** A revision can contain run-level field characters, but not `w:fldSimple`. */
 function serializeTrackedSimpleField(field) {
@@ -429,7 +459,12 @@ function trackedChangeTag(change) {
 	}
 }
 function serializeTrackedChange(tag, change) {
-	const attrs = serializeTrackedChangeAttributes(change.info);
+	if (change.resolutionJoins !== void 0 && change.content.some((item) => item.type === "hyperlink")) throw new ReviewResolutionProvenanceError({
+		attribute: "resolutionJoins",
+		reason: "unrepresentable",
+		message: "Tracked-resolution provenance cannot be repartitioned across serialized hyperlinks."
+	});
+	const attrs = serializeTrackedChangeAttributes(change.info) + serializeResolutionJoins(change.resolutionJoins);
 	const disposition = tag === "del" || tag === "moveFrom" ? "removed" : "kept";
 	const serializeContentRun = (run) => serializeInlineRun(run, disposition);
 	const serializeWrappedItem = (item) => {
@@ -451,7 +486,7 @@ function serializeTrackedChange(tag, change) {
 			case "moveFromRangeEnd": return `<w:moveFromRangeEnd ${markupRangeAttributes(item).join(" ")}/>`;
 			case "moveToRangeStart": return serializeMoveRangeStart("moveToRangeStart", item);
 			case "moveToRangeEnd": return `<w:moveToRangeEnd ${markupRangeAttributes(item).join(" ")}/>`;
-			case "preservedInline": return item.xml;
+			case "preservedInline": return disposition === "removed" ? serializeRemovedPreservedInline(item) : item.xml;
 			case "inlineWrapper":
 			case "inlineSdt": return serializeParagraphContent(item, disposition);
 			default: return item;
@@ -574,6 +609,8 @@ function serializeParagraph(paragraph) {
 	if (paragraph.paraId) attrs.push(`w14:paraId="${escapeXmlAttribute(paragraph.paraId)}"`);
 	if (paragraph.textId) attrs.push(`w14:textId="${escapeXmlAttribute(paragraph.textId)}"`);
 	if (paragraph.reviewCarrier) attrs.push(`folio:reviewCarrier="${paragraph.reviewCarrier}"`);
+	const emptyMarkProperties = serializeEmptyMarkProperties(paragraph);
+	if (emptyMarkProperties !== void 0) attrs.push(emptyMarkProperties);
 	const written = serializePreservedAttributes(attrs, paragraph.preservedAttributes);
 	const attrsStr = written.length > 0 ? ` ${written.join(" ")}` : "";
 	parts.push(serializeParagraphFormattingWithOptions(paragraph.formatting, {

package/dist/docx/serializer/partNamespaces.js

@@ -1,3 +1,4 @@
+import { FOLIO_REVIEW_HISTORY_NAMESPACE } from "../reviewHistoryNamespace.js";
 import { toTransitionalNamespaceUri } from "../transitionalSpelling.js";
 import { TaggedError } from "better-result";
 import { assertValidOoxmlNumericIds, escapeXmlAttribute } from "@stll/docx-core";
@@ -144,7 +145,7 @@ const OOXML_NAMESPACES = {
 		ignorable: true
 	},
 	folio: {
-		uri: "urn:stella:folio:review-history:1",
+		uri: FOLIO_REVIEW_HISTORY_NAMESPACE,
 		ignorable: true
 	},
 	wpg: {

package/dist/docx/serializer/runSerializer.js

@@ -7,6 +7,7 @@ import { serializeGraphicFrameLocks } from "../graphicFrameLocks.js";
 import { DECORATIVE_EXTENSION_URI, DECORATIVE_NAMESPACE } from "../imageParser.js";
 import { canReplayEditableImageRawXml } from "../imageRawXml.js";
 import { serializeNonVisualDrawingNames } from "../nonVisualDrawingProps.js";
+import { serializeBoundaryJoins } from "../reviewResolutionProvenance.js";
 import { runHoldsPayload } from "../runPayload.js";
 import { replayableShapeAlternateContent } from "../shapeAlternateContent.js";
 import { requiredWrapPolygon, serializeWrapPolygon } from "../wrapPolygon.js";
@@ -51,7 +52,7 @@ function getUniqueId(id) {
 }
 function serializeRunPropertyChange(change) {
 	const previousRPrXml = serializeTextFormatting(change.previousFormatting) || "<w:rPr/>";
-	return `<w:rPrChange ${serializeTrackedChangeAttributes(change.info)}>${previousRPrXml}</w:rPrChange>`;
+	return `<w:rPrChange ${serializeTrackedChangeAttributes(change.info)}${serializeBoundaryJoins(change.boundaryJoins)}>${previousRPrXml}</w:rPrChange>`;
 }
 function serializeRunProperties(formatting, propertyChanges) {
 	const propertyChange = getSingularRunPropertyChange(propertyChanges);
@@ -537,6 +538,7 @@ function serializeRunContent(content) {
 		case "symbol": return serializeSymbolContent(content);
 		case "footnoteRef":
 		case "endnoteRef": return serializeNoteReference(content);
+		case "noteMarker": return content.kind === "footnote" ? "<w:footnoteRef/>" : "<w:endnoteRef/>";
 		case "fieldChar": return serializeFieldChar(content);
 		case "instrText": return serializeInstrText(content);
 		case "softHyphen": return serializeSoftHyphen(content);

package/dist/docx/settingsHeaderFooterUpdate.d.ts

@@ -0,0 +1,5 @@
+//#region src/docx/settingsHeaderFooterUpdate.d.ts
+/** Null means the source is malformed or outside the supported namespace profiles. */
+declare const updateEvenAndOddHeaders: (xml: string, enabled: boolean | undefined) => string | null;
+//#endregion
+export { updateEvenAndOddHeaders };

package/dist/docx/settingsHeaderFooterUpdate.js

@@ -0,0 +1,90 @@
+import { spliceXml } from "./selectiveXmlPatch.js";
+import { WORDPROCESSINGML_NAMESPACE_URIS, getChildElements, getLocalName, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
+import { panic } from "better-result";
+import { SETTINGS_CHILDREN } from "@stll/docx-core/schema";
+//#region src/docx/settingsHeaderFooterUpdate.ts
+/** Preserve producer settings while updating the document-wide header/footer switch. */
+const XML_TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\?[\s\S]*?\?>|<(?:"[^"]*"|'[^']*'|[^'">])*>/gu;
+const SETTINGS_CHILD_ORDINALS = new Map(SETTINGS_CHILDREN.map((name, index) => [name, index]));
+const EVEN_AND_ODD_HEADERS_ORDER = SETTINGS_CHILD_ORDINALS.get("evenAndOddHeaders");
+/** Null means the source is malformed or outside the supported namespace profiles. */
+const updateEvenAndOddHeaders = (xml, enabled) => {
+	const root = parseXmlDocument(xml);
+	if (!root || getLocalName(root.name) !== "settings" || !WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(root) ?? "")) return null;
+	const children = getChildElements(root);
+	const spans = [];
+	const stack = [];
+	let childIndex = 0;
+	let childStart = -1;
+	let rootEnd = -1;
+	let rootOpenEnd = -1;
+	let selfClosingRootStart = -1;
+	let firstFollowingChildStart = -1;
+	if (EVEN_AND_ODD_HEADERS_ORDER === void 0) panic("Generated CT_Settings schema does not define evenAndOddHeaders");
+	for (const token of xml.matchAll(XML_TOKEN)) {
+		const tag = token[0];
+		if (tag.startsWith("<!") || tag.startsWith("<?")) continue;
+		const closing = tag.startsWith("</");
+		const name = tag.slice(closing ? 2 : 1).split(/[\s/>]/u).at(0);
+		if (!name) return null;
+		if (closing) {
+			if (stack.pop() !== name) return null;
+			if (stack.length === 1) {
+				const child = children[childIndex++];
+				if (!child || childStart < 0) return null;
+				if (getLocalName(child.name) === "evenAndOddHeaders" && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "")) spans.push({
+					start: childStart,
+					end: token.index + tag.length,
+					newXml: ""
+				});
+				childStart = -1;
+			}
+			if (stack.length === 0) rootEnd = token.index;
+			continue;
+		}
+		if (stack.length === 0) {
+			rootOpenEnd = token.index + tag.length;
+			if (tag.endsWith("/>")) selfClosingRootStart = token.index;
+		}
+		if (stack.length === 1) {
+			const child = children[childIndex];
+			if (child?.name !== name) return null;
+			if (firstFollowingChildStart < 0 && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "") && (SETTINGS_CHILD_ORDINALS.get(getLocalName(child.name)) ?? -1) > EVEN_AND_ODD_HEADERS_ORDER) firstFollowingChildStart = token.index;
+			childStart = token.index;
+			if (tag.endsWith("/>")) {
+				childIndex += 1;
+				if (getLocalName(child.name) === "evenAndOddHeaders" && WORDPROCESSINGML_NAMESPACE_URIS.has(getNamespaceUri(child) ?? "")) spans.push({
+					start: token.index,
+					end: token.index + tag.length,
+					newXml: ""
+				});
+				childStart = -1;
+			}
+		}
+		if (!tag.endsWith("/>")) stack.push(name);
+	}
+	if (stack.length !== 0 || childIndex !== children.length) return null;
+	const flag = enabled === void 0 ? "" : `<folioW:evenAndOddHeaders xmlns:folioW="${getNamespaceUri(root)}"${enabled ? "" : " folioW:val=\"0\""}/>`;
+	if (selfClosingRootStart >= 0) {
+		if (!flag) return xml;
+		return spliceXml(xml, [{
+			start: rootOpenEnd - 2,
+			end: rootOpenEnd,
+			newXml: `>${flag}</${root.name}>`
+		}]);
+	}
+	if (rootEnd < 0) return null;
+	const existingFlag = spans.at(0);
+	if (flag && existingFlag) existingFlag.newXml = flag;
+	else if (flag) {
+		const insertAt = firstFollowingChildStart >= 0 ? firstFollowingChildStart : rootEnd;
+		spans.push({
+			start: insertAt,
+			end: insertAt,
+			newXml: flag
+		});
+	}
+	return spliceXml(xml, spans);
+};
+//#endregion
+export { updateEvenAndOddHeaders };

package/dist/docx/settingsParser.d.ts

@@ -1,7 +1,6 @@
 import { document_d_exports } from "../types/document.js";
+import { DEFAULT_TAB_STOP_TWIPS } from "@stll/docx-core/model";
 //#region src/docx/settingsParser.d.ts
-/** OOXML default per §17.6.13 when `w:defaultTabStop` is absent. */
-declare const DEFAULT_TAB_STOP_TWIPS = 720;
 declare function parseSettings(xml: string | null): document_d_exports.DocumentSettings;
 //#endregion
 export { DEFAULT_TAB_STOP_TWIPS, parseSettings };

package/dist/docx/settingsParser.js

@@ -1,8 +1,7 @@
 import { parseEndnoteProperties } from "./notePropertiesParser.js";
 import { WORDPROCESSINGML_NAMESPACE_URIS, findChild, findChildByNamespaceUri, findChildren, getAttribute, parseBooleanElement, parseXmlDocument } from "./xmlParser.js";
+import { DEFAULT_TAB_STOP_TWIPS, DEFAULT_TAB_STOP_TWIPS as DEFAULT_TAB_STOP_TWIPS$1 } from "@stll/docx-core/model";
 //#region src/docx/settingsParser.ts
-/** OOXML default per §17.6.13 when `w:defaultTabStop` is absent. */
-const DEFAULT_TAB_STOP_TWIPS = 720;
 /**
 * Sanity cap on `w:defaultTabStop`. Word's maximum margin is ~22 inches
 * (31 680 twips); anything past that is corruption or a hostile input and
@@ -111,13 +110,13 @@ function parseKinsokuOverride(root, name) {
 	};
 }
 function parseDefaultTabStop(root) {
-	if (!root) return 720;
+	if (!root) return DEFAULT_TAB_STOP_TWIPS$1;
 	const el = findChild(root, "w", "defaultTabStop");
-	if (!el) return 720;
+	if (!el) return DEFAULT_TAB_STOP_TWIPS$1;
 	const raw = getAttribute(el, "w", "val");
-	if (raw === null) return 720;
+	if (raw === null) return DEFAULT_TAB_STOP_TWIPS$1;
 	const parsed = Number.parseInt(raw, 10);
-	if (!Number.isFinite(parsed) || parsed < MIN_TAB_STOP_TWIPS || parsed > MAX_TAB_STOP_TWIPS) return 720;
+	if (!Number.isFinite(parsed) || parsed < MIN_TAB_STOP_TWIPS || parsed > MAX_TAB_STOP_TWIPS) return DEFAULT_TAB_STOP_TWIPS$1;
 	return parsed;
 }
 //#endregion

package/dist/docx/storyBlockReplay.d.ts

@@ -0,0 +1,11 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/storyBlockReplay.d.ts
+type StoryBlockReplayOptions = {
+  sourceXml: string;
+  baselineContent: readonly document_d_exports.BlockContent[];
+  currentContent: readonly document_d_exports.BlockContent[];
+  serializedXml: string;
+};
+declare const buildStoryBlockReplay: (options: StoryBlockReplayOptions) => string | null;
+//#endregion
+export { buildStoryBlockReplay };