@stll/folio-core 0.46.0 → 0.47.1

package/dist/docx/serializer/runSerializer.js

@@ -1,12 +1,14 @@
 import { isValidHexColor } from "../../utils/colorResolver.js";
 import { normalizeImageLuminancePercent } from "../../utils/imageLuminance.js";
 import { serializePreservedAttributes } from "../attributeRemainder.js";
-import { THEME_COLOR_TO_DRAWING_SCHEME } from "../drawingUtils.js";
+import { resolveEffectExtents, resolveWrapDistances, serializeAnchorAttributes, serializeEffectExtent, serializeInlineAttributes, serializeSimplePos, serializeWrapDistances } from "../drawingAnchor.js";
 import { fieldStateAttributes } from "../fieldState.js";
 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 { runHoldsPayload } from "../runPayload.js";
+import { requiredWrapPolygon, serializeWrapPolygon } from "../wrapPolygon.js";
 import { serializeParagraph } from "./paragraphSerializer.js";
 import { serializeTable } from "./tableSerializer.js";
 import { serializeTextFormatting } from "./textFormattingSerializer.js";
@@ -14,6 +16,7 @@ import { getSingularRunPropertyChange, serializeTrackedChangeAttributes } from "
 import { intAttr } from "./xmlUtils.js";
 import { panic } from "better-result";
 import { escapeXmlAttribute, escapeXmlText, requiresXmlSpacePreserve } from "@stll/docx-core";
+import { SCHEME_COLOR_VALUE_BY_THEME_COLOR, knownThemeColor, presetLineDashToken } from "@stll/docx-core/model";
 //#region src/docx/serializer/runSerializer.ts
 /**
 * Run Serializer - Serialize runs to OOXML XML
@@ -44,21 +47,13 @@ function getUniqueId(id) {
 	if (id !== void 0 && id !== "" && id !== 0) return String(id);
 	return String(nextAutoId++);
 }
-function extractRPrInner(rPrXml) {
-	if (!rPrXml.startsWith("<w:rPr>") || !rPrXml.endsWith("</w:rPr>")) return "";
-	return rPrXml.slice(7, -8);
-}
 function serializeRunPropertyChange(change) {
 	const previousRPrXml = serializeTextFormatting(change.previousFormatting) || "<w:rPr/>";
 	return `<w:rPrChange ${serializeTrackedChangeAttributes(change.info)}>${previousRPrXml}</w:rPrChange>`;
 }
 function serializeRunProperties(formatting, propertyChanges) {
-	const currentRPrXml = serializeTextFormatting(formatting);
-	const currentInner = currentRPrXml ? extractRPrInner(currentRPrXml) : "";
 	const propertyChange = getSingularRunPropertyChange(propertyChanges);
-	const combined = `${currentInner}${propertyChange ? serializeRunPropertyChange(propertyChange) : ""}`;
-	if (!combined) return "";
-	return `<w:rPr>${combined}</w:rPr>`;
+	return serializeTextFormatting(formatting, propertyChange ? [["rPrChange", serializeRunPropertyChange(propertyChange)]] : []);
 }
 /**
 * Serialize text content (w:t)
@@ -130,8 +125,10 @@ function serializeNoBreakHyphen(_content) {
 function serializeDrawingColor(color) {
 	if (!color) return "";
 	if (color.rgb && isValidHexColor(color.rgb)) return `<a:srgbClr val="${escapeXmlAttribute(color.rgb.replace("#", ""))}"/>`;
-	if (color.themeColor) {
-		let clr = `<a:schemeClr val="${THEME_COLOR_TO_DRAWING_SCHEME[color.themeColor]}"`;
+	const themeColor = color.themeColor && knownThemeColor(color.themeColor);
+	const schemeColor = themeColor ? SCHEME_COLOR_VALUE_BY_THEME_COLOR[themeColor] : null;
+	if (schemeColor !== null) {
+		let clr = `<a:schemeClr val="${schemeColor}"`;
 		if (color.themeTint) clr += `><a:tint val="${escapeXmlAttribute(color.themeTint)}"/></a:schemeClr>`;
 		else if (color.themeShade) clr += `><a:shade val="${escapeXmlAttribute(color.themeShade)}"/></a:schemeClr>`;
 		else clr += `/>`;
@@ -171,7 +168,7 @@ function serializeOutline(outline) {
 	if (outline.cap) attrs.push(`cap="${serializeLineCap(outline.cap)}"`);
 	const parts = [];
 	if (outline.color) parts.push(`<a:solidFill>${serializeDrawingColor(outline.color)}</a:solidFill>`);
-	if (outline.style) parts.push(`<a:prstDash val="${outline.style}"/>`);
+	if (outline.dash) parts.push(`<a:prstDash val="${escapeXmlAttribute(presetLineDashToken(outline.dash))}"/>`);
 	if (outline.join === "bevel") parts.push("<a:bevel/>");
 	else if (outline.join === "round") parts.push("<a:round/>");
 	else if (outline.join === "miter") parts.push("<a:miter/>");
@@ -195,14 +192,60 @@ function serializePosition(pos) {
 	parts.push("</wp:positionV>");
 	return parts.join("");
 }
+/**
+* The insets each `EG_WrapType` member's own type declares.
+*
+* Total over the wrap kinds, so a kind added to the model has to say which of
+* the four its element may carry. A key this map does not list cannot be
+* written on that element without failing the schema, whatever the drawing's
+* slots hold.
+*/
+const WRAP_CHILD_DISTANCE_KEYS = {
+	square: [
+		"distT",
+		"distB",
+		"distL",
+		"distR"
+	],
+	tight: ["distL", "distR"],
+	through: ["distL", "distR"],
+	topAndBottom: ["distT", "distB"],
+	behind: [],
+	inFront: [],
+	inline: []
+};
+/**
+* Which `EG_WrapType` members declare a `wp:effectExtent` of their own.
+*
+* Total over the wrap kinds for {@link WRAP_CHILD_DISTANCE_KEYS}'s reason: a
+* kind added to the model has to say whether its element may carry one, and
+* writing it where the type does not declare it fails the schema.
+*/
+const WRAP_CHILD_DECLARES_EFFECT_EXTENT = {
+	square: true,
+	tight: false,
+	through: false,
+	topAndBottom: true,
+	behind: false,
+	inFront: false,
+	inline: false
+};
 /** Serialize wrap type to wp:wrap* element */
-function serializeWrap(wrap) {
+function serializeWrap(wrap, effectExtent) {
 	const wrapText = wrap.wrapText ? ` wrapText="${wrap.wrapText}"` : " wrapText=\"bothSides\"";
+	const authored = resolveWrapDistances(wrap).wrapChild;
+	const distances = {};
+	for (const key of WRAP_CHILD_DISTANCE_KEYS[wrap.type]) {
+		const value = authored[key];
+		if (value !== void 0) distances[key] = value;
+	}
+	const dist = serializeWrapDistances(distances);
+	const extent = effectExtent !== void 0 && WRAP_CHILD_DECLARES_EFFECT_EXTENT[wrap.type] ? serializeEffectExtent(effectExtent) : "";
 	switch (wrap.type) {
-		case "square": return `<wp:wrapSquare${wrapText}/>`;
-		case "tight": return `<wp:wrapTight${wrapText}><wp:wrapPolygon edited="0"><wp:start x="0" y="0"/><wp:lineTo x="0" y="21600"/><wp:lineTo x="21600" y="21600"/><wp:lineTo x="21600" y="0"/><wp:lineTo x="0" y="0"/></wp:wrapPolygon></wp:wrapTight>`;
-		case "through": return `<wp:wrapThrough${wrapText}><wp:wrapPolygon edited="0"><wp:start x="0" y="0"/><wp:lineTo x="0" y="21600"/><wp:lineTo x="21600" y="21600"/><wp:lineTo x="21600" y="0"/><wp:lineTo x="0" y="0"/></wp:wrapPolygon></wp:wrapThrough>`;
-		case "topAndBottom": return "<wp:wrapTopAndBottom/>";
+		case "square": return extent ? `<wp:wrapSquare${wrapText}${dist}>${extent}</wp:wrapSquare>` : `<wp:wrapSquare${wrapText}${dist}/>`;
+		case "tight": return `<wp:wrapTight${wrapText}${dist}>${serializeWrapPolygon(requiredWrapPolygon(wrap.polygon))}</wp:wrapTight>`;
+		case "through": return `<wp:wrapThrough${wrapText}${dist}>${serializeWrapPolygon(requiredWrapPolygon(wrap.polygon))}</wp:wrapThrough>`;
+		case "topAndBottom": return extent ? `<wp:wrapTopAndBottom${dist}>${extent}</wp:wrapTopAndBottom>` : `<wp:wrapTopAndBottom${dist}/>`;
 		case "behind":
 		case "inFront": return "<wp:wrapNone/>";
 		case "inline": return "<wp:wrapNone/>";
@@ -231,7 +274,10 @@ function serializePicGraphic(image, imageRId, sharedId) {
 	const cy = image.size.height;
 	const rId = escapeXmlAttribute(imageRId);
 	const id = sharedId;
-	const name = image.filename || `image${id}`;
+	const picNames = serializeNonVisualDrawingNames({
+		...image.pictureNames,
+		name: image.pictureNames?.name ?? image.filename ?? `image${id}`
+	});
 	const xfrmAttrs = serializeTransformAttrs(image.transform);
 	const cropAttrs = [];
 	if (image.crop?.left) cropAttrs.push(`l="${Math.round(image.crop.left * 1e5)}"`);
@@ -249,7 +295,7 @@ function serializePicGraphic(image, imageRId, sharedId) {
 		"<a:graphicData uri=\"http://schemas.openxmlformats.org/drawingml/2006/picture\">",
 		"<pic:pic xmlns:pic=\"http://schemas.openxmlformats.org/drawingml/2006/picture\">",
 		"<pic:nvPicPr>",
-		`<pic:cNvPr id="${id}" name="${escapeXmlAttribute(name)}"${image.alt ? ` descr="${escapeXmlAttribute(image.alt)}"` : ""}/>`,
+		`<pic:cNvPr id="${id}"${picNames}/>`,
 		"<pic:cNvPicPr/>",
 		"</pic:nvPicPr>",
 		"<pic:blipFill>",
@@ -271,18 +317,6 @@ function serializePicGraphic(image, imageRId, sharedId) {
 	].join("");
 }
 /**
-* Serialize only authored wrap-distance attributes. OOXML defaults omitted
-* values to zero, but preserving absence keeps untouched models stable.
-*/
-function serializeWrapDistanceAttrs(wrap) {
-	const attrs = [];
-	if (wrap?.distT !== void 0) attrs.push(`distT="${intAttr(wrap.distT)}"`);
-	if (wrap?.distB !== void 0) attrs.push(`distB="${intAttr(wrap.distB)}"`);
-	if (wrap?.distL !== void 0) attrs.push(`distL="${intAttr(wrap.distL)}"`);
-	if (wrap?.distR !== void 0) attrs.push(`distR="${intAttr(wrap.distR)}"`);
-	return attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
-}
-/**
 * Serialize the `wp:docPr` extension list.
 *
 * The decorative flag is the one extension folio models; every other `a:ext`
@@ -296,6 +330,23 @@ function serializeDocPrExtensions(image) {
 	return entries ? `<a:extLst>${entries}</a:extLst>` : "";
 }
 /**
+* Serialize `wp:docPr`'s two link children, in the order the schema declares.
+*
+* The click element is replayed from the source while the model still names the
+* target it named, which keeps `tooltip`, `tgtFrame`, `history` and the rest of
+* `CT_Hyperlink` that the model has no field for. A link the editor retargeted
+* no longer agrees with those bytes, so it is rebuilt from the target instead —
+* the alternative is writing a tooltip that points somewhere else. The hover
+* element has no modelled half to disagree with it, so it always replays.
+*/
+function serializeDocPrLinks(image) {
+	const hover = image.hlinkHoverXml ?? "";
+	const source = image.hlinkClickSource;
+	if (source !== void 0 && source.rId === image.hlinkRId) return `${source.xml}${hover}`;
+	if (image.hlinkRId === void 0) return hover;
+	return `<a:hlinkClick r:id="${escapeXmlAttribute(image.hlinkRId)}"/>${hover}`;
+}
+/**
 * Serialize drawing/image content (w:drawing) to full DrawingML XML
 */
 function serializeDrawingContent(content) {
@@ -303,19 +354,15 @@ function serializeDrawingContent(content) {
 	const isFloating = image.wrap.type !== "inline";
 	const cx = image.size.width;
 	const cy = image.size.height;
-	const wrapDistanceAttrs = serializeWrapDistanceAttrs(image.wrap);
-	const effL = image.padding?.left ?? 0;
-	const effT = image.padding?.top ?? 0;
-	const effR = image.padding?.right ?? 0;
-	const effB = image.padding?.bottom ?? 0;
-	const effectExtentEl = `<wp:effectExtent l="${intAttr(effL)}" t="${intAttr(effT)}" r="${intAttr(effR)}" b="${intAttr(effB)}"/>`;
+	const effectExtents = resolveEffectExtents(image.wrap, image.padding);
+	const effectExtentEl = serializeEffectExtent(effectExtents.drawing);
 	const docPrId = getUniqueId(image.id);
 	const docPrNames = serializeNonVisualDrawingNames({
 		...image.docPrName !== void 0 ? { name: image.docPrName } : {},
 		...image.alt !== void 0 ? { alt: image.alt } : {},
 		...image.title !== void 0 ? { title: image.title } : {}
 	});
-	const hlinkClick = image.hlinkRId ? `<a:hlinkClick r:id="${escapeXmlAttribute(image.hlinkRId)}"/>` : "";
+	const hlinkClick = serializeDocPrLinks(image);
 	const docPrAttrs = `id="${docPrId}"${docPrNames}${image.hidden === void 0 ? "" : ` hidden="${image.hidden ? "1" : "0"}"`}`;
 	const docPrChildren = `${hlinkClick}${serializeDocPrExtensions(image)}`;
 	const docPr = docPrChildren ? `<wp:docPr ${docPrAttrs}>${docPrChildren}</wp:docPr>` : `<wp:docPr ${docPrAttrs}/>`;
@@ -323,7 +370,7 @@ function serializeDrawingContent(content) {
 	const graphic = image.rId === void 0 ? "" : serializePicGraphic(image, image.rId, docPrId);
 	if (!isFloating) return [
 		"<w:drawing>",
-		`<wp:inline${wrapDistanceAttrs}>`,
+		`<wp:inline${serializeInlineAttributes(image.wrap)}>`,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		effectExtentEl,
 		docPr,
@@ -332,13 +379,16 @@ function serializeDrawingContent(content) {
 		"</wp:inline>",
 		"</w:drawing>"
 	].join("");
-	const behindDoc = image.wrap.type === "behind" ? "1" : "0";
 	const position = image.position ? serializePosition(image.position) : "<wp:positionH relativeFrom=\"column\"><wp:posOffset>0</wp:posOffset></wp:positionH><wp:positionV relativeFrom=\"paragraph\"><wp:posOffset>0</wp:posOffset></wp:positionV>";
-	const wrap = serializeWrap(image.wrap);
+	const wrap = serializeWrap(image.wrap, effectExtents.wrapChild);
 	return [
 		"<w:drawing>",
-		`<wp:anchor${wrapDistanceAttrs} simplePos="0" relativeHeight="251658240" behindDoc="${behindDoc}" locked="0" layoutInCell="${image.layoutInCell === false ? "0" : "1"}" allowOverlap="${image.allowOverlap === false ? "0" : "1"}">`,
-		"<wp:simplePos x=\"0\" y=\"0\"/>",
+		`<wp:anchor${serializeAnchorAttributes({
+			anchor: image.anchor,
+			wrap: image.wrap,
+			behindDoc: image.wrap.type === "behind"
+		})}>`,
+		serializeSimplePos(image.anchor),
 		position,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
 		effectExtentEl,
@@ -377,13 +427,13 @@ function serializeShapeContent(content) {
 	const cy = shape.size.height;
 	const isTextBox = shape.shapeType === "textBox";
 	const isFloating = shape.wrap && shape.wrap.type !== "inline";
-	const wrapDistances = serializeWrapDistanceAttrs(shape.wrap);
 	const docPrId = getUniqueId(shape.id);
 	const docPrNames = serializeNonVisualDrawingNames({
 		...shape.name !== void 0 ? { name: shape.name } : {},
 		...shape.alt !== void 0 ? { alt: shape.alt } : {},
 		...shape.title !== void 0 ? { title: shape.title } : {}
 	});
+	const shapeNames = shape.shapeNames === void 0 ? "" : `<wps:cNvPr id="${docPrId}"${serializeNonVisualDrawingNames(shape.shapeNames)}/>`;
 	const spPr = [
 		"<wps:spPr>",
 		`<a:xfrm${serializeTransformAttrs(shape.transform)}>`,
@@ -428,6 +478,7 @@ function serializeShapeContent(content) {
 		"<a:graphicData uri=\"http://schemas.microsoft.com/office/word/2010/wordprocessingShape\">",
 		[
 			"<wps:wsp>",
+			shapeNames,
 			`<wps:cNvSpPr${isTextBox ? " txBox=\"1\"" : ""}/>`,
 			spPr,
 			textBody === "" ? "<wps:bodyPr/>" : textBody,
@@ -436,28 +487,32 @@ function serializeShapeContent(content) {
 		"</a:graphicData>",
 		"</a:graphic>"
 	].join("");
+	const shapeEffectExtents = resolveEffectExtents(shape.wrap, shape.wrap?.effectExtentSlots?.drawing);
 	if (!isFloating) return [
 		"<w:drawing>",
-		`<wp:inline${wrapDistances}>`,
+		`<wp:inline${serializeInlineAttributes(shape.wrap)}>`,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
-		"<wp:effectExtent l=\"0\" t=\"0\" r=\"0\" b=\"0\"/>",
+		serializeEffectExtent(shapeEffectExtents.drawing),
 		`<wp:docPr id="${docPrId}"${docPrNames}/>`,
 		"<wp:cNvGraphicFramePr/>",
 		graphic,
 		"</wp:inline>",
 		"</w:drawing>"
 	].join("");
-	const behindDoc = shape.wrap?.type === "behind" ? "1" : "0";
 	const position = shape.position ? serializePosition(shape.position) : "<wp:positionH relativeFrom=\"column\"><wp:posOffset>0</wp:posOffset></wp:positionH><wp:positionV relativeFrom=\"paragraph\"><wp:posOffset>0</wp:posOffset></wp:positionV>";
 	if (!shape.wrap) panic("Floating shape must have a wrap property");
-	const wrap = serializeWrap(shape.wrap);
+	const wrap = serializeWrap(shape.wrap, shapeEffectExtents.wrapChild);
 	return [
 		"<w:drawing>",
-		`<wp:anchor${wrapDistances} simplePos="0" relativeHeight="251658240" behindDoc="${behindDoc}" locked="0" layoutInCell="1" allowOverlap="1">`,
-		"<wp:simplePos x=\"0\" y=\"0\"/>",
+		`<wp:anchor${serializeAnchorAttributes({
+			anchor: shape.anchor,
+			wrap: shape.wrap,
+			behindDoc: shape.wrap.type === "behind"
+		})}>`,
+		serializeSimplePos(shape.anchor),
 		position,
 		`<wp:extent cx="${intAttr(cx)}" cy="${intAttr(cy)}"/>`,
-		"<wp:effectExtent l=\"0\" t=\"0\" r=\"0\" b=\"0\"/>",
+		serializeEffectExtent(shapeEffectExtents.drawing),
 		wrap,
 		`<wp:docPr id="${docPrId}"${docPrNames}/>`,
 		"<wp:cNvGraphicFramePr/>",
@@ -497,6 +552,7 @@ function serializeRunContent(content) {
 * @returns XML string for the run
 */
 function serializeRun(run) {
+	if (!runHoldsPayload(run)) return "";
 	const parts = [];
 	const rPrXml = serializeRunProperties(run.formatting, run.propertyChanges);
 	if (rPrXml) parts.push(rPrXml);
@@ -517,12 +573,6 @@ function serializeRuns(runs) {
 	return runs.map(serializeRun).join("");
 }
 /**
-* Check if a run has any content
-*/
-function hasRunContent(run) {
-	return run.content.length > 0;
-}
-/**
 * Check if a run has formatting
 */
 function hasRunFormatting(run) {
@@ -580,4 +630,4 @@ function createTabRun(formatting) {
 	};
 }
 //#endregion
-export { createBreakRun, createEmptyRun, createTabRun, createTextRun, getRunPlainText, hasRunContent, hasRunFormatting, resetAutoIdCounter, serializeRun, serializeRuns };
+export { createBreakRun, createEmptyRun, createTabRun, createTextRun, getRunPlainText, hasRunFormatting, resetAutoIdCounter, serializeRun, serializeRuns };

package/dist/docx/serializer/sdtPropertiesSerializer.d.ts

@@ -0,0 +1,26 @@
+import { document_d_exports } from "../../types/document.js";
+//#region src/docx/serializer/sdtPropertiesSerializer.d.ts
+/**
+ * `<w:sdtPr>` from the model: the modelled children, the preserved ones, in
+ * schema order.
+ *
+ * An empty property set is written as an empty element rather than left out.
+ * `<w:sdtPr/>` and no `w:sdtPr` at all are different documents — the first is
+ * a richText control that states nothing, the second is markup the schema does
+ * not admit under `w:sdt` — and folio used to write the second for both.
+ */
+declare const serializeSdtProperties: (props: document_d_exports.SdtProperties) => string;
+/**
+ * `w:sdtEndPr`, replayed when the parse captured it and written from the
+ * record otherwise.
+ *
+ * The record's presence is the element's: `<w:sdtEndPr/>` with no `w:rPr` is
+ * what Word writes for most controls and differs from a missing element.
+ */
+declare const serializeSdtEndProperties: (properties: document_d_exports.SdtProperties) => string;
+/** `w:sdtPr` followed by `w:sdtEndPr`, in schema order. */
+declare const serializeSdtPropertyElements: (properties: document_d_exports.SdtProperties) => string;
+/** The one writer of an SDT wrapper at every content-model level. */
+declare const serializeSdtWrapper: (properties: document_d_exports.SdtProperties, contentXml: string) => string;
+//#endregion
+export { serializeSdtEndProperties, serializeSdtProperties, serializeSdtPropertyElements, serializeSdtWrapper };

package/dist/docx/serializer/sdtPropertiesSerializer.js

@@ -0,0 +1,111 @@
+import { statesControlKind } from "../sdtProperties.js";
+import { withModelledControlState } from "../sdtPropertiesPatch.js";
+import { serializeTextFormatting } from "./textFormattingSerializer.js";
+import { isSingleWellFormedElement } from "./xmlUtils.js";
+import { escapeXmlAttribute, serializeOnOffElement } from "@stll/docx-core";
+import { assertSafePreservedMarkup, serializeSequenceChildren } from "@stll/docx-core/schema";
+//#region src/docx/serializer/sdtPropertiesSerializer.ts
+/**
+* The one writer of `<w:sdtPr>`.
+*
+* Every content control — block, inline, row and cell — writes its property
+* set here. There used to be three producers: a fallback projection on the
+* block path, a second one on the inline path, and a regex pass over the
+* source's captured bytes that patched an interactive change back into them.
+* The three agreed on nothing in particular, and the patching pass existed
+* only because the replay was the serialization source.
+*
+* It is not any more. `parseSdtProperties` puts every child folio does not
+* model into `SdtProperties.preserved` at its `CT_SdtPr` ordinal, so the model
+* holds the whole element and the writer merges its two halves back in schema
+* order — which `CT_SdtPr` demands, and Word repairs a file that disregards.
+*/
+const listElement = (name, props) => {
+	return `<w:${name}${props.dropdownLastValue === void 0 ? "" : ` w:lastValue="${escapeXmlAttribute(props.dropdownLastValue)}"`}>${(props.listItems ?? []).map((item) => `<w:listItem w:displayText="${escapeXmlAttribute(item.displayText)}" w:value="${escapeXmlAttribute(item.value)}"/>`).join("")}</w:${name}>`;
+};
+/**
+* The kind marker for a control that carries none of its own.
+*
+* Only reached for a control built in code rather than parsed: a parsed one
+* keeps the element its author wrote, in the sink, glyph elements and all.
+* `richText` is the format's default and `unknown` is folio's word for a kind
+* it could not read, so neither writes a marker — a bare `w:sdtPr` already
+* means richText.
+*
+* A checkbox has no declared kind element at all: `w14:checkbox` is an
+* extension the Transitional content model does not know, so it is filed
+* under the slot the kind choice occupies, which is where Word writes it.
+*/
+const synthesizedKind = (props) => {
+	switch (props.sdtType) {
+		case "plainText": return ["text", "<w:text/>"];
+		case "date": return ["date", `<w:date${props.dateValueISO ? ` w:fullDate="${escapeXmlAttribute(props.dateValueISO)}"` : ""}>${props.dateFormat ? `<w:dateFormat w:val="${escapeXmlAttribute(props.dateFormat)}"/>` : ""}</w:date>`];
+		case "dropdown": return ["dropDownList", listElement("dropDownList", props)];
+		case "comboBox": return ["comboBox", listElement("comboBox", props)];
+		case "checkbox": return ["equation", `<w14:checkbox><w14:checked w14:val="${props.checked ? "1" : "0"}"/></w14:checkbox>`];
+		case "picture": return ["picture", "<w:picture/>"];
+		case "buildingBlockGallery": return ["docPartObj", "<w:docPartObj/>"];
+		case "group": return ["group", "<w:group/>"];
+		case "richText":
+		case "unknown": return ["richText", ""];
+		default: return props.sdtType;
+	}
+};
+/**
+* `<w:sdtPr>` from the model: the modelled children, the preserved ones, in
+* schema order.
+*
+* An empty property set is written as an empty element rather than left out.
+* `<w:sdtPr/>` and no `w:sdtPr` at all are different documents — the first is
+* a richText control that states nothing, the second is markup the schema does
+* not admit under `w:sdt` — and folio used to write the second for both.
+*/
+const serializeSdtProperties = (props) => {
+	assertSafePreservedMarkup(props.preserved);
+	const modelled = [];
+	if (props.alias !== void 0) modelled.push(["alias", `<w:alias w:val="${escapeXmlAttribute(props.alias)}"/>`]);
+	if (props.tag !== void 0) modelled.push(["tag", `<w:tag w:val="${escapeXmlAttribute(props.tag)}"/>`]);
+	if (props.id !== void 0) modelled.push(["id", `<w:id w:val="${props.id}"/>`]);
+	if (props.lock !== void 0) modelled.push(["lock", `<w:lock w:val="${props.lock}"/>`]);
+	if (props.placeholder !== void 0) modelled.push(["placeholder", `<w:placeholder><w:docPart w:val="${escapeXmlAttribute(props.placeholder)}"/></w:placeholder>`]);
+	if (props.showingPlaceholder !== void 0) modelled.push(["showingPlcHdr", serializeOnOffElement(props.showingPlaceholder, "showingPlcHdr")]);
+	const captured = props.preserved?.children ?? [];
+	let statedKind = false;
+	const preserved = captured.map((child) => {
+		if (!statesControlKind(child.xml)) return child;
+		statedKind = true;
+		return {
+			index: child.index,
+			xml: withModelledControlState(child.xml, props)
+		};
+	});
+	if (!statedKind) modelled.push(synthesizedKind(props));
+	const body = serializeSequenceChildren({
+		container: "content-control-properties",
+		modelled,
+		preserved: props.preserved === void 0 ? void 0 : { children: preserved }
+	}).join("");
+	return body.length === 0 ? "<w:sdtPr/>" : `<w:sdtPr>${body}</w:sdtPr>`;
+};
+/**
+* `w:sdtEndPr`, replayed when the parse captured it and written from the
+* record otherwise.
+*
+* The record's presence is the element's: `<w:sdtEndPr/>` with no `w:rPr` is
+* what Word writes for most controls and differs from a missing element.
+*/
+const serializeSdtEndProperties = (properties) => {
+	if (properties.rawEndPropertiesXml && isSingleWellFormedElement(properties.rawEndPropertiesXml, "sdtEndPr")) return properties.rawEndPropertiesXml;
+	const endProperties = properties.endProperties;
+	if (endProperties === void 0) return "";
+	const runProperties = serializeTextFormatting(endProperties.runProperties);
+	return runProperties.length > 0 ? `<w:sdtEndPr>${runProperties}</w:sdtEndPr>` : "<w:sdtEndPr/>";
+};
+/** `w:sdtPr` followed by `w:sdtEndPr`, in schema order. */
+const serializeSdtPropertyElements = (properties) => `${serializeSdtProperties(properties)}${serializeSdtEndProperties(properties)}`;
+/** The one writer of an SDT wrapper at every content-model level. */
+const serializeSdtWrapper = (properties, contentXml) => {
+	return `<w:sdt>${serializeSdtPropertyElements(properties)}${properties.rawSdtChildrenBeforeContent ?? ""}<w:sdtContent>${contentXml}</w:sdtContent>${properties.rawSdtChildrenAfterContent ?? ""}</w:sdt>`;
+};
+//#endregion
+export { serializeSdtEndProperties, serializeSdtProperties, serializeSdtPropertyElements, serializeSdtWrapper };

package/dist/docx/serializer/sectionPropertiesSerializer.js

@@ -1,10 +1,11 @@
 import { serializePreservedAttributes } from "../attributeRemainder.js";
-import { getUnserializedSectionPropertyChildNames } from "../sectionParser.js";
 import { serializeSectionReferenceHistory } from "../sectionReferenceHistory.js";
 import { serializeBorder } from "./borderSerializer.js";
 import { serializeTrackedChangeAttributes } from "./trackedChangeAttributes.js";
 import { intAttr } from "./xmlUtils.js";
-import { escapeXmlAttribute } from "@stll/docx-core";
+import { escapeXmlAttribute, serializeOnOffElement } from "@stll/docx-core";
+import { themeColorToken } from "@stll/docx-core/model";
+import { serializeSequenceChildren } from "@stll/docx-core/schema";
 //#region src/docx/serializer/sectionPropertiesSerializer.ts
 const serializeHeaderReference = (ref) => `<w:headerReference w:type="${ref.type}" r:id="${escapeXmlAttribute(ref.rId)}"/>`;
 const serializeFooterReference = (ref) => `<w:footerReference w:type="${ref.type}" r:id="${escapeXmlAttribute(ref.rId)}"/>`;
@@ -77,7 +78,7 @@ function serializeLineNumbers(props) {
 	if (ln.start !== void 0) attrs.push(`w:start="${intAttr(ln.start)}"`);
 	if (ln.distance !== void 0) attrs.push(`w:distance="${intAttr(ln.distance)}"`);
 	if (ln.restart) attrs.push(`w:restart="${ln.restart}"`);
-	return attrs.length > 0 ? `<w:lnNumType ${attrs.join(" ")}/>` : "";
+	return attrs.length > 0 ? `<w:lnNumType ${attrs.join(" ")}/>` : "<w:lnNumType/>";
 }
 function serializePageNumbering(props) {
 	if (!props.pageNumbering) return "";
@@ -106,7 +107,6 @@ function serializePageBorders(props) {
 		const xml = serializeBorder(pb[key], elementName);
 		if (xml) borderElements.push(xml);
 	}
-	if (borderElements.length === 0 && attrs.length === 0) return "";
 	const attrsStr = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
 	if (borderElements.length === 0) return `<w:pgBorders${attrsStr}/>`;
 	return `<w:pgBorders${attrsStr}>${borderElements.join("")}</w:pgBorders>`;
@@ -117,7 +117,8 @@ function serializeBackground(props) {
 	const { background } = props;
 	if (background.color?.auto) attrs.push("w:color=\"auto\"");
 	else if (background.color?.rgb) attrs.push(`w:color="${escapeXmlAttribute(background.color.rgb)}"`);
-	if (background.themeColor ?? background.color?.themeColor) attrs.push(`w:themeColor="${escapeXmlAttribute(background.themeColor ?? background.color?.themeColor ?? "")}"`);
+	const backgroundThemeColor = background.themeColor ?? background.color?.themeColor;
+	if (backgroundThemeColor !== void 0) attrs.push(`w:themeColor="${escapeXmlAttribute(themeColorToken(backgroundThemeColor))}"`);
 	if (background.themeTint ?? background.color?.themeTint) attrs.push(`w:themeTint="${escapeXmlAttribute(background.themeTint ?? background.color?.themeTint ?? "")}"`);
 	if (background.themeShade ?? background.color?.themeShade) attrs.push(`w:themeShade="${escapeXmlAttribute(background.themeShade ?? background.color?.themeShade ?? "")}"`);
 	return attrs.length > 0 ? `<w:background ${attrs.join(" ")}/>` : "";
@@ -131,10 +132,6 @@ function serializeDocGrid(props) {
 	if (dg.charSpace !== void 0) attrs.push(`w:charSpace="${intAttr(dg.charSpace)}"`);
 	return attrs.length > 0 ? `<w:docGrid ${attrs.join(" ")}/>` : "<w:docGrid/>";
 }
-function serializeOnOffElement(value, name) {
-	if (value === void 0) return "";
-	return value ? `<w:${name}/>` : `<w:${name} w:val="0"/>`;
-}
 function serializeSectionPropertyChange(change) {
 	const { headerReferences: _headers, footerReferences: _footers, ...previous } = change.previousProperties ?? {};
 	const previousSectPrXml = serializeSectionProperties(previous) || "<w:sectPr/>";
@@ -143,42 +140,34 @@ function serializeSectionPropertyChange(change) {
 }
 function serializeSectionProperties(props) {
 	if (!props) return "";
-	const parts = [];
-	for (const ref of props.headerReferences ?? []) parts.push(serializeHeaderReference(ref));
-	for (const ref of props.footerReferences ?? []) parts.push(serializeFooterReference(ref));
-	const footnotePrXml = serializeFootnoteProperties(props.footnotePr);
-	if (footnotePrXml) parts.push(footnotePrXml);
-	const footnoteColumnsXml = serializeFootnoteColumns(props);
-	if (footnoteColumnsXml) parts.push(footnoteColumnsXml);
-	const endnotePrXml = serializeEndnoteProperties(props.endnotePr);
-	if (endnotePrXml) parts.push(endnotePrXml);
-	if (props.sectionStart) parts.push(`<w:type w:val="${props.sectionStart}"/>`);
-	for (const xml of [
-		serializePageSize(props),
-		serializePageMargins(props),
-		serializePaperSource(props),
-		serializePageBorders(props),
-		serializeBackground(props),
-		serializeLineNumbers(props),
-		serializePageNumbering(props),
-		serializeColumns(props),
-		serializeDocGrid(props)
-	]) if (xml) parts.push(xml);
-	if (props.verticalAlign) parts.push(`<w:vAlign w:val="${props.verticalAlign}"/>`);
-	if (props.textDirection) parts.push(`<w:textDirection w:val="${props.textDirection}"/>`);
-	const titlePgXml = serializeOnOffElement(props.titlePg, "titlePg");
-	if (titlePgXml) parts.push(titlePgXml);
-	const bidiXml = serializeOnOffElement(props.bidi, "bidi");
-	if (bidiXml) parts.push(bidiXml);
-	for (const xml of [
-		serializeOnOffElement(props.formProtection, "formProt"),
-		serializeOnOffElement(props.noEndnote, "noEndnote"),
-		serializeOnOffElement(props.rtlGutter, "rtlGutter")
-	]) if (xml) parts.push(xml);
-	if (props.printerSettingsRelationshipId) parts.push(`<w:printerSettings r:id="${escapeXmlAttribute(props.printerSettingsRelationshipId)}"/>`);
-	for (const change of props.propertyChanges ?? []) parts.push(serializeSectionPropertyChange(change));
-	const unserializedChildNames = getUnserializedSectionPropertyChildNames(props);
-	if (unserializedChildNames && unserializedChildNames.length > 0) return "";
+	const parts = serializeSequenceChildren({
+		container: "section-properties",
+		modelled: [
+			["headerReference", (props.headerReferences ?? []).map(serializeHeaderReference).join("")],
+			["footerReference", (props.footerReferences ?? []).map(serializeFooterReference).join("")],
+			["footnotePr", serializeFootnoteProperties(props.footnotePr) + serializeFootnoteColumns(props)],
+			["endnotePr", serializeEndnoteProperties(props.endnotePr)],
+			["type", props.sectionStart ? `<w:type w:val="${props.sectionStart}"/>` : ""],
+			["pgSz", serializePageSize(props)],
+			["pgMar", serializePageMargins(props)],
+			["paperSrc", serializePaperSource(props)],
+			["pgBorders", serializePageBorders(props) + serializeBackground(props)],
+			["lnNumType", serializeLineNumbers(props)],
+			["pgNumType", serializePageNumbering(props)],
+			["cols", serializeColumns(props)],
+			["formProt", serializeOnOffElement(props.formProtection, "formProt")],
+			["vAlign", props.verticalAlign ? `<w:vAlign w:val="${props.verticalAlign}"/>` : ""],
+			["noEndnote", serializeOnOffElement(props.noEndnote, "noEndnote")],
+			["titlePg", serializeOnOffElement(props.titlePg, "titlePg")],
+			["textDirection", props.textDirection ? `<w:textDirection w:val="${props.textDirection}"/>` : ""],
+			["bidi", serializeOnOffElement(props.bidi, "bidi")],
+			["rtlGutter", serializeOnOffElement(props.rtlGutter, "rtlGutter")],
+			["docGrid", serializeDocGrid(props)],
+			["printerSettings", props.printerSettingsRelationshipId ? `<w:printerSettings r:id="${escapeXmlAttribute(props.printerSettingsRelationshipId)}"/>` : ""],
+			["sectPrChange", (props.propertyChanges ?? []).map(serializeSectionPropertyChange).join("")]
+		],
+		preserved: props.preserved
+	});
 	const attributes = serializePreservedAttributes([], props.preservedAttributes);
 	const startTag = attributes.length > 0 ? `<w:sectPr ${attributes.join(" ")}` : "<w:sectPr";
 	if (parts.length > 0) return `${startTag}>${parts.join("")}</w:sectPr>`;

package/dist/docx/serializer/settingsSerializer.js

@@ -1,11 +1,13 @@
 import { serializePartElement } from "./partNamespaces.js";
 import { intAttr } from "./xmlUtils.js";
-import { escapeXmlAttribute } from "@stll/docx-core";
+import { escapeXmlAttribute, serializeOnOffElement } from "@stll/docx-core";
 //#region src/docx/serializer/settingsSerializer.ts
 const serializeSettingsXml = (settings) => {
-	const parts = [`<w:defaultTabStop w:val="${intAttr(settings.defaultTabStop)}"/>`];
-	if (settings.evenAndOddHeaders) parts.push("<w:evenAndOddHeaders/>");
-	if (settings.updateFields) parts.push("<w:updateFields w:val=\"true\"/>");
+	const parts = [
+		`<w:defaultTabStop w:val="${intAttr(settings.defaultTabStop)}"/>`,
+		serializeOnOffElement(settings.evenAndOddHeaders, "evenAndOddHeaders"),
+		serializeOnOffElement(settings.updateFields, "updateFields")
+	];
 	if (settings.themeFontLang) {
 		const attrs = [];
 		if (settings.themeFontLang.eastAsia) attrs.push(`w:eastAsia="${escapeXmlAttribute(settings.themeFontLang.eastAsia)}"`);