docxmlater 10.4.0 → 11.0.4

package/dist/esm/xml/XMLBuilder.js

@@ -0,0 +1,434 @@
+import { removeInvalidXmlChars } from '../utils/xmlSanitization.js';
+import { buildShadingAttributes } from '../elements/CommonTypes.js';
+export class XMLBuilder {
+    elements = [];
+    static CANNOT_SELF_CLOSE = [
+        'w:t',
+        'w:r',
+        'w:p',
+        'w:tbl',
+        'w:tr',
+        'w:tc',
+        'w:body',
+        'w:document',
+        'w:hyperlink',
+        'w:sdt',
+        'w:sdtContent',
+        'w:sdtPr',
+        'w:pPr',
+        'w:rPr',
+        'w:sectPr',
+        'w:del',
+        'w:ins',
+        'w:moveFrom',
+        'w:moveTo',
+    ];
+    element(name, attributes, children) {
+        this.elements.push({
+            name,
+            attributes,
+            children,
+        });
+        return this;
+    }
+    selfClosingElement(name, attributes) {
+        if (name === 'w:t' || name === 't') {
+            throw new Error('Text elements (<w:t>) cannot be self-closing per ECMA-376. ' +
+                'Use element() with empty text content instead: XMLBuilder.w("t", attrs, [""])');
+        }
+        this.elements.push({
+            name,
+            attributes,
+            selfClosing: true,
+        });
+        return this;
+    }
+    text(text) {
+        this.elements.push(text);
+        return this;
+    }
+    build(includeDeclaration = false) {
+        let xml = '';
+        if (includeDeclaration) {
+            xml += '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+        }
+        xml += this.elementsToString(this.elements);
+        return xml;
+    }
+    elementsToString(elements) {
+        let xml = '';
+        for (const element of elements) {
+            if (typeof element === 'string') {
+                xml += this.escapeXml(element);
+            }
+            else {
+                xml += this.elementToString(element);
+            }
+        }
+        return xml;
+    }
+    elementToString(element) {
+        if (element.name === '__rawXml' && element.rawXml) {
+            return element.rawXml;
+        }
+        let xml = `<${element.name}`;
+        if (element.attributes) {
+            for (const [key, value] of Object.entries(element.attributes)) {
+                if (value !== undefined && value !== null && value !== false) {
+                    const attrValue = value === true ? key : String(value);
+                    xml += ` ${key}="${XMLBuilder.escapeXmlAttribute(attrValue)}"`;
+                }
+            }
+        }
+        if (element.selfClosing) {
+            if (XMLBuilder.CANNOT_SELF_CLOSE.includes(element.name)) {
+                xml += '></' + element.name + '>';
+                return xml;
+            }
+            xml += '/>';
+            return xml;
+        }
+        xml += '>';
+        if (element.rawXml) {
+            xml += element.rawXml;
+        }
+        if (element.children && element.children.length > 0) {
+            xml += this.elementsToString(element.children);
+        }
+        xml += `</${element.name}>`;
+        return xml;
+    }
+    escapeXml(text) {
+        return XMLBuilder.escapeXmlText(text);
+    }
+    static escapeXmlText(text) {
+        return removeInvalidXmlChars(text)
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;');
+    }
+    static escapeXmlAttribute(value) {
+        return removeInvalidXmlChars(value)
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+    }
+    static unescapeXml(text) {
+        return text
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"')
+            .replace(/&apos;/g, "'")
+            .replace(/&amp;/g, '&');
+    }
+    static sanitizeXmlContent(text) {
+        return (removeInvalidXmlChars(text)
+            .replace(/\]\]>/g, ']]&gt;')
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;'));
+    }
+    static createNamespaces() {
+        return {
+            'xmlns:w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
+            'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+            'xmlns:wp': 'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing',
+            'xmlns:a': 'http://schemas.openxmlformats.org/drawingml/2006/main',
+            'xmlns:pic': 'http://schemas.openxmlformats.org/drawingml/2006/picture',
+            'xmlns:w14': 'http://schemas.microsoft.com/office/word/2010/wordml',
+            'xmlns:wpc': 'http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas',
+            'xmlns:mc': 'http://schemas.openxmlformats.org/markup-compatibility/2006',
+            'xmlns:o': 'urn:schemas-microsoft-com:office:office',
+            'xmlns:v': 'urn:schemas-microsoft-com:vml',
+            'xmlns:wp14': 'http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing',
+            'xmlns:w10': 'urn:schemas-microsoft-com:office:word',
+            'xmlns:w15': 'http://schemas.microsoft.com/office/word/2012/wordml',
+            'xmlns:wpg': 'http://schemas.microsoft.com/office/word/2010/wordprocessingGroup',
+            'xmlns:wpi': 'http://schemas.microsoft.com/office/word/2010/wordprocessingInk',
+            'xmlns:wne': 'http://schemas.microsoft.com/office/word/2006/wordml',
+            'xmlns:wps': 'http://schemas.microsoft.com/office/word/2010/wordprocessingShape',
+            'xmlns:asvg': 'http://schemas.microsoft.com/office/drawing/2016/SVG/main',
+        };
+    }
+    static elementToString(element) {
+        const builder = new XMLBuilder();
+        builder.elements.push(element);
+        return builder.build();
+    }
+    static w(name, attributes, children) {
+        return {
+            name: `w:${name}`,
+            attributes,
+            children,
+        };
+    }
+    static wSelf(name, attributes) {
+        return {
+            name: `w:${name}`,
+            attributes,
+            selfClosing: true,
+        };
+    }
+    static w14(name, attributes, children) {
+        return {
+            name: `w14:${name}`,
+            attributes,
+            children,
+        };
+    }
+    static w14Self(name, attributes) {
+        return {
+            name: `w14:${name}`,
+            attributes,
+            selfClosing: true,
+        };
+    }
+    static a(name, attributes, children) {
+        return {
+            name: `a:${name}`,
+            attributes,
+            children,
+        };
+    }
+    static aSelf(name, attributes) {
+        return {
+            name: `a:${name}`,
+            attributes,
+            selfClosing: true,
+        };
+    }
+    static pic(name, attributes, children) {
+        return {
+            name: `pic:${name}`,
+            attributes,
+            children,
+        };
+    }
+    static picSelf(name, attributes) {
+        return {
+            name: `pic:${name}`,
+            attributes,
+            selfClosing: true,
+        };
+    }
+    static wp(name, attributes, children) {
+        return {
+            name: `wp:${name}`,
+            attributes,
+            children,
+        };
+    }
+    static wpSelf(name, attributes) {
+        return {
+            name: `wp:${name}`,
+            attributes,
+            selfClosing: true,
+        };
+    }
+    static cxCy(name, cx, cy) {
+        return {
+            name,
+            attributes: { cx, cy },
+            selfClosing: true,
+        };
+    }
+    static createSDT(content, options) {
+        const sdtId = options?.id ?? Math.floor(Math.random() * 2000000000) - 1000000000;
+        const sdtPrChildren = [XMLBuilder.wSelf('id', { 'w:val': sdtId })];
+        if (options?.docPartGallery) {
+            sdtPrChildren.push(XMLBuilder.w('docPartObj', undefined, [
+                XMLBuilder.wSelf('docPartGallery', { 'w:val': options.docPartGallery }),
+                XMLBuilder.wSelf('docPartUnique', {
+                    'w:val': options?.docPartUnique !== false ? '1' : '0',
+                }),
+            ]));
+        }
+        return XMLBuilder.w('sdt', undefined, [
+            XMLBuilder.w('sdtPr', undefined, sdtPrChildren),
+            XMLBuilder.w('sdtContent', undefined, content),
+        ]);
+    }
+    static createDocument(bodyContent, namespaces = {}, preBodyContent) {
+        const builder = new XMLBuilder();
+        const allNamespaces = {};
+        for (const [key, value] of Object.entries(namespaces)) {
+            allNamespaces[key] = value;
+        }
+        for (const [key, value] of Object.entries(XMLBuilder.createNamespaces())) {
+            if (!(key in allNamespaces)) {
+                allNamespaces[key] = value;
+            }
+        }
+        if (!allNamespaces['mc:Ignorable']) {
+            const ignorable = [];
+            if (allNamespaces['xmlns:w14'])
+                ignorable.push('w14');
+            if (allNamespaces['xmlns:w15'])
+                ignorable.push('w15');
+            if (allNamespaces['xmlns:wp14'])
+                ignorable.push('wp14');
+            if (allNamespaces['xmlns:w16se'])
+                ignorable.push('w16se');
+            if (allNamespaces['xmlns:w16cid'])
+                ignorable.push('w16cid');
+            if (allNamespaces['xmlns:w16'])
+                ignorable.push('w16');
+            if (allNamespaces['xmlns:w16cex'])
+                ignorable.push('w16cex');
+            if (allNamespaces['xmlns:w16sdtdh'])
+                ignorable.push('w16sdtdh');
+            if (allNamespaces['xmlns:w16sdtfl'])
+                ignorable.push('w16sdtfl');
+            if (allNamespaces['xmlns:w16du'])
+                ignorable.push('w16du');
+            if (allNamespaces['xmlns:asvg'])
+                ignorable.push('asvg');
+            if (ignorable.length > 0) {
+                allNamespaces['mc:Ignorable'] = ignorable.join(' ');
+            }
+        }
+        else {
+            const defaults = XMLBuilder.createNamespaces();
+            const prefixes = allNamespaces['mc:Ignorable'].split(/\s+/);
+            for (const prefix of prefixes) {
+                const nsKey = `xmlns:${prefix}`;
+                if (!allNamespaces[nsKey] && defaults[nsKey]) {
+                    allNamespaces[nsKey] = defaults[nsKey];
+                }
+            }
+        }
+        const documentChildren = [];
+        if (preBodyContent) {
+            documentChildren.push(...preBodyContent);
+        }
+        documentChildren.push(XMLBuilder.w('body', undefined, bodyContent));
+        builder.element('w:document', allNamespaces, documentChildren);
+        return builder.build(true);
+    }
+    static buildObject(obj, rootName) {
+        const builder = new XMLBuilder();
+        const element = XMLBuilder.objectToElement(obj, rootName);
+        if (element) {
+            if (typeof element === 'string') {
+                builder.text(element);
+            }
+            else {
+                builder.elements.push(element);
+            }
+        }
+        return builder.build();
+    }
+    static objectToElement(obj, name) {
+        if (obj === null || obj === undefined) {
+            return null;
+        }
+        if (typeof obj !== 'object' || obj === null) {
+            return String(obj);
+        }
+        const attributes = {};
+        const children = [];
+        if (obj['#text'] && Object.keys(obj).length === 1) {
+            return String(obj['#text']);
+        }
+        for (const key in obj) {
+            if (key.startsWith('@_')) {
+                const attrName = key.substring(2);
+                if (attrName.length > 0) {
+                    attributes[attrName] = obj[key];
+                }
+            }
+            else if (key === '#text') {
+                children.push(String(obj[key]));
+            }
+            else {
+                const childObj = obj[key];
+                if (Array.isArray(childObj)) {
+                    childObj.forEach((item) => {
+                        const childElement = XMLBuilder.objectToElement(item, key);
+                        if (childElement) {
+                            children.push(childElement);
+                        }
+                    });
+                }
+                else {
+                    const childElement = XMLBuilder.objectToElement(childObj, key);
+                    if (childElement) {
+                        children.push(childElement);
+                    }
+                }
+            }
+        }
+        const element = {
+            name,
+            attributes,
+            children: children.length > 0 ? children : undefined,
+        };
+        if (!element.children || element.children.length === 0) {
+            if (!XMLBuilder.CANNOT_SELF_CLOSE.includes(name)) {
+                element.selfClosing = true;
+            }
+        }
+        return element;
+    }
+    static buildAttributes(mapping) {
+        const attrs = {};
+        for (const [key, value] of Object.entries(mapping)) {
+            if (value !== undefined && value !== null) {
+                attrs[key] = value;
+            }
+        }
+        return attrs;
+    }
+    static createBorder(side, border) {
+        const attrs = XMLBuilder.buildAttributes({
+            'w:val': border.style || 'single',
+            'w:sz': border.size,
+            'w:color': border.color,
+            'w:space': border.space,
+            'w:themeColor': border.themeColor,
+            'w:themeTint': border.themeTint,
+            'w:themeShade': border.themeShade,
+            'w:shadow': border.shadow === undefined ? undefined : border.shadow ? '1' : '0',
+            'w:frame': border.frame === undefined ? undefined : border.frame ? '1' : '0',
+        });
+        return XMLBuilder.wSelf(side, attrs);
+    }
+    static createShading(shading) {
+        const attrs = buildShadingAttributes(shading);
+        if (!attrs['w:val'] && Object.keys(attrs).length > 0) {
+            attrs['w:val'] = 'clear';
+        }
+        if (Object.keys(attrs).length > 0) {
+            return XMLBuilder.wSelf('shd', attrs);
+        }
+        return null;
+    }
+    static createMargins(type, margins) {
+        const children = [];
+        if (margins.top !== undefined) {
+            children.push(XMLBuilder.wSelf('top', { 'w:w': margins.top, 'w:type': 'dxa' }));
+        }
+        if (margins.bottom !== undefined) {
+            children.push(XMLBuilder.wSelf('bottom', { 'w:w': margins.bottom, 'w:type': 'dxa' }));
+        }
+        if (margins.left !== undefined) {
+            children.push(XMLBuilder.wSelf('left', { 'w:w': margins.left, 'w:type': 'dxa' }));
+        }
+        if (margins.right !== undefined) {
+            children.push(XMLBuilder.wSelf('right', { 'w:w': margins.right, 'w:type': 'dxa' }));
+        }
+        if (margins.start !== undefined) {
+            children.push(XMLBuilder.wSelf('start', { 'w:w': margins.start, 'w:type': 'dxa' }));
+        }
+        if (margins.end !== undefined) {
+            children.push(XMLBuilder.wSelf('end', { 'w:w': margins.end, 'w:type': 'dxa' }));
+        }
+        if (children.length > 0) {
+            return XMLBuilder.w(type, undefined, children);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=XMLBuilder.js.map

package/dist/esm/xml/XMLBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XMLBuilder.js","sourceRoot":"","sources":["../../../src/xml/XMLBuilder.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAqBpE,MAAM,OAAO,UAAU;IACb,QAAQ,GAA4B,EAAE,CAAC;IAMvC,MAAM,CAAU,iBAAiB,GAAG;QAC1C,KAAK;QACL,KAAK;QACL,KAAK;QACL,OAAO;QACP,MAAM;QACN,MAAM;QACN,QAAQ;QACR,YAAY;QACZ,aAAa;QACb,OAAO;QACP,cAAc;QACd,SAAS;QACT,OAAO;QACP,OAAO;QACP,UAAU;QACV,OAAO;QACP,OAAO;QACP,YAAY;QACZ,UAAU;KAEX,CAAC;IASF,OAAO,CACL,IAAY,EACZ,UAAkE,EAClE,QAAkC;QAElC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACjB,IAAI;YACJ,UAAU;YACV,QAAQ;SACT,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IASD,kBAAkB,CAChB,IAAY,EACZ,UAAkE;QAIlE,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,6DAA6D;gBAC3D,+EAA+E,CAClF,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACjB,IAAI;YACJ,UAAU;YACV,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAOD,IAAI,CAAC,IAAY;QACf,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAOD,KAAK,CAAC,kBAAkB,GAAG,KAAK;QAC9B,IAAI,GAAG,GAAG,EAAE,CAAC;QAEb,IAAI,kBAAkB,EAAE,CAAC;YACvB,GAAG,IAAI,2DAA2D,CAAC;QACrE,CAAC;QAED,GAAG,IAAI,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5C,OAAO,GAAG,CAAC;IACb,CAAC;IAKO,gBAAgB,CAAC,QAAiC;QACxD,IAAI,GAAG,GAAG,EAAE,CAAC;QAEb,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAChC,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,GAAG,IAAI,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC;IAKO,eAAe,CAAC,OAAmB;QAGzC,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YAClD,OAAO,OAAO,CAAC,MAAM,CAAC;QACxB,CAAC;QAED,IAAI,GAAG,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAG7B,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC9D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;oBAE7D,MAAM,SAAS,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBAEvD,GAAG,IAAI,IAAI,GAAG,KAAK,UAAU,CAAC,kBAAkB,CAAC,SAAS,CAAC,GAAG,CAAC;gBACjE,CAAC;YACH,CAAC;QACH,CAAC;QAGD,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YACxB,IAAI,UAAU,CAAC,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBAExD,GAAG,IAAI,KAAK,GAAG,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC;gBAClC,OAAO,GAAG,CAAC;YACb,CAAC;YACD,GAAG,IAAI,IAAI,CAAC;YACZ,OAAO,GAAG,CAAC;QACb,CAAC;QAED,GAAG,IAAI,GAAG,CAAC;QAGX,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC;QACxB,CAAC;QAGD,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,GAAG,IAAI,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjD,CAAC;QAED,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,GAAG,CAAC;QAC5B,OAAO,GAAG,CAAC;IACb,CAAC;IAMO,SAAS,CAAC,IAAY;QAI5B,OAAO,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAYD,MAAM,CAAC,aAAa,CAAC,IAAY;QAC/B,OAAO,qBAAqB,CAAC,IAAI,CAAC;aAC/B,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;aACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;aACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3B,CAAC;IAYD,MAAM,CAAC,kBAAkB,CAAC,KAAa;QACrC,OAAO,qBAAqB,CAAC,KAAK,CAAC;aAChC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;aACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;aACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;aACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;aACvB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAOD,MAAM,CAAC,WAAW,CAAC,IAAY;QAC7B,OAAO,IAAI;aACR,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;aACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;aACrB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;aACvB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;aACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC5B,CAAC;IAeD,MAAM,CAAC,kBAAkB,CAAC,IAAY;QACpC,OAAO,CACL,qBAAqB,CAAC,IAAI,CAAC;aAExB,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC;aAE3B,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;aACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;aACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CACzB,CAAC;IACJ,CAAC;IAKD,MAAM,CAAC,gBAAgB;QACrB,OAAO;YACL,SAAS,EAAE,8DAA8D;YACzE,SAAS,EAAE,qEAAqE;YAChF,UAAU,EAAE,wEAAwE;YACpF,SAAS,EAAE,uDAAuD;YAClE,WAAW,EAAE,0DAA0D;YACvE,WAAW,EAAE,sDAAsD;YACnE,WAAW,EAAE,oEAAoE;YACjF,UAAU,EAAE,6DAA6D;YACzE,SAAS,EAAE,yCAAyC;YACpD,SAAS,EAAE,+BAA+B;YAC1C,YAAY,EAAE,qEAAqE;YACnF,WAAW,EAAE,uCAAuC;YACpD,WAAW,EAAE,sDAAsD;YACnE,WAAW,EAAE,mEAAmE;YAChF,WAAW,EAAE,iEAAiE;YAC9E,WAAW,EAAE,sDAAsD;YACnE,WAAW,EAAE,mEAAmE;YAChF,YAAY,EAAE,2DAA2D;SAC1E,CAAC;IACJ,CAAC;IASD,MAAM,CAAC,eAAe,CAAC,OAAmB;QACxC,MAAM,OAAO,GAAG,IAAI,UAAU,EAAE,CAAC;QAEhC,OAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IASD,MAAM,CAAC,CAAC,CACN,IAAY,EACZ,UAAkE,EAClE,QAAkC;QAElC,OAAO;YACL,IAAI,EAAE,KAAK,IAAI,EAAE;YACjB,UAAU;YACV,QAAQ;SACT,CAAC;IACJ,CAAC;IAQD,MAAM,CAAC,KAAK,CACV,IAAY,EACZ,UAAkE;QAElE,OAAO;YACL,IAAI,EAAE,KAAK,IAAI,EAAE;YACjB,UAAU;YACV,WAAW,EAAE,IAAI;SAClB,CAAC;IACJ,CAAC;IASD,MAAM,CAAC,GAAG,CACR,IAAY,EACZ,UAAkE,EAClE,QAAkC;QAElC,OAAO;YACL,IAAI,EAAE,OAAO,IAAI,EAAE;YACnB,UAAU;YACV,QAAQ;SACT,CAAC;IACJ,CAAC;IAQD,MAAM,CAAC,OAAO,CACZ,IAAY,EACZ,UAAkE;QAElE,OAAO;YACL,IAAI,EAAE,OAAO,IAAI,EAAE;YACnB,UAAU;YACV,WAAW,EAAE,IAAI;SAClB,CAAC;IACJ,CAAC;IASD,MAAM,CAAC,CAAC,CACN,IAAY,EACZ,UAAkE,EAClE,QAAkC;QAElC,OAAO;YACL,IAAI,EAAE,KAAK,IAAI,EAAE;YACjB,UAAU;YACV,QAAQ;SACT,CAAC;IACJ,CAAC;IAQD,MAAM,CAAC,KAAK,CACV,IAAY,EACZ,UAAkE;QAElE,OAAO;YACL,IAAI,EAAE,KAAK,IAAI,EAAE;YACjB,UAAU;YACV,WAAW,EAAE,IAAI;SAClB,CAAC;IACJ,CAAC;IASD,MAAM,CAAC,GAAG,CACR,IAAY,EACZ,UAAkE,EAClE,QAAkC;QAElC,OAAO;YACL,IAAI,EAAE,OAAO,IAAI,EAAE;YACnB,UAAU;YACV,QAAQ;SACT,CAAC;IACJ,CAAC;IAQD,MAAM,CAAC,OAAO,CACZ,IAAY,EACZ,UAAkE;QAElE,OAAO;YACL,IAAI,EAAE,OAAO,IAAI,EAAE;YACnB,UAAU;YACV,WAAW,EAAE,IAAI;SAClB,CAAC;IACJ,CAAC;IASD,MAAM,CAAC,EAAE,CACP,IAAY,EACZ,UAAkE,EAClE,QAAkC;QAElC,OAAO;YACL,IAAI,EAAE,MAAM,IAAI,EAAE;YAClB,UAAU;YACV,QAAQ;SACT,CAAC;IACJ,CAAC;IAQD,MAAM,CAAC,MAAM,CACX,IAAY,EACZ,UAAkE;QAElE,OAAO;YACL,IAAI,EAAE,MAAM,IAAI,EAAE;YAClB,UAAU;YACV,WAAW,EAAE,IAAI;SAClB,CAAC;IACJ,CAAC;IASD,MAAM,CAAC,IAAI,CAAC,IAAY,EAAE,EAAU,EAAE,EAAU;QAC9C,OAAO;YACL,IAAI;YACJ,UAAU,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;YACtB,WAAW,EAAE,IAAI;SAClB,CAAC;IACJ,CAAC;IAQD,MAAM,CAAC,SAAS,CACd,OAAqB,EACrB,OAIC;QAED,MAAM,KAAK,GAAG,OAAO,EAAE,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,UAAU,CAAC;QAGjF,MAAM,aAAa,GAAiB,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAGjF,IAAI,OAAO,EAAE,cAAc,EAAE,CAAC;YAC5B,aAAa,CAAC,IAAI,CAChB,UAAU,CAAC,CAAC,CAAC,YAAY,EAAE,SAAS,EAAE;gBACpC,UAAU,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;gBACvE,UAAU,CAAC,KAAK,CAAC,eAAe,EAAE;oBAChC,OAAO,EAAE,OAAO,EAAE,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;iBACtD,CAAC;aACH,CAAC,CACH,CAAC;QACJ,CAAC;QAGD,OAAO,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE;YACpC,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC;YAC/C,UAAU,CAAC,CAAC,CAAC,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC;SAC/C,CAAC,CAAC;IACL,CAAC;IAOD,MAAM,CAAC,cAAc,CACnB,WAAyB,EACzB,aAAqC,EAAE,EACvC,cAA6B;QAE7B,MAAM,OAAO,GAAG,IAAI,UAAU,EAAE,CAAC;QAGjC,MAAM,aAAa,GAA2B,EAAE,CAAC;QACjD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YACtD,aAAa,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC7B,CAAC;QACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,EAAE,CAAC;YACzE,IAAI,CAAC,CAAC,GAAG,IAAI,aAAa,CAAC,EAAE,CAAC;gBAC5B,aAAa,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC7B,CAAC;QACH,CAAC;QAMD,IAAI,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,CAAC;YACnC,MAAM,SAAS,GAAa,EAAE,CAAC;YAC/B,IAAI,aAAa,CAAC,WAAW,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtD,IAAI,aAAa,CAAC,WAAW,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtD,IAAI,aAAa,CAAC,YAAY,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACxD,IAAI,aAAa,CAAC,aAAa,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1D,IAAI,aAAa,CAAC,cAAc,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5D,IAAI,aAAa,CAAC,WAAW,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtD,IAAI,aAAa,CAAC,cAAc,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5D,IAAI,aAAa,CAAC,gBAAgB,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAChE,IAAI,aAAa,CAAC,gBAAgB,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAChE,IAAI,aAAa,CAAC,aAAa,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1D,IAAI,aAAa,CAAC,YAAY,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACxD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;aAAM,CAAC;YAKN,MAAM,QAAQ,GAAG,UAAU,CAAC,gBAAgB,EAAE,CAAC;YAC/C,MAAM,QAAQ,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC5D,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,MAAM,KAAK,GAAG,SAAS,MAAM,EAAE,CAAC;gBAChC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC7C,aAAa,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;gBACzC,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,gBAAgB,GAAiB,EAAE,CAAC;QAC1C,IAAI,cAAc,EAAE,CAAC;YACnB,gBAAgB,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,CAAC;QAC3C,CAAC;QACD,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;QACpE,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,aAAa,EAAE,gBAAgB,CAAC,CAAC;QAE/D,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAMD,MAAM,CAAC,WAAW,CAAC,GAAoB,EAAE,QAAgB;QACvD,MAAM,OAAO,GAAG,IAAI,UAAU,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,UAAU,CAAC,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC1D,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAMO,MAAM,CAAC,eAAe,CAC5B,GAAmE,EACnE,IAAY;QAEZ,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC5C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QAED,MAAM,UAAU,GAA8C,EAAE,CAAC;QACjE,MAAM,QAAQ,GAA4B,EAAE,CAAC;QAE7C,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9B,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;YACtB,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,MAAM,QAAQ,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;gBAElC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxB,UAAU,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;gBAClC,CAAC;YACH,CAAC;iBAAM,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;gBAC3B,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAClC,CAAC;iBAAM,CAAC;gBACN,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;gBAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC5B,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;wBACxB,MAAM,YAAY,GAAG,UAAU,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;wBAC3D,IAAI,YAAY,EAAE,CAAC;4BACjB,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;wBAC9B,CAAC;oBACH,CAAC,CAAC,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACN,MAAM,YAAY,GAAG,UAAU,CAAC,eAAe,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;oBAC/D,IAAI,YAAY,EAAE,CAAC;wBACjB,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;oBAC9B,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAe;YAC1B,IAAI;YACJ,UAAU;YACV,QAAQ,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;SACrD,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvD,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACjD,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;YAC7B,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAmBD,MAAM,CAAC,eAAe,CAAC,OAA4B;QACjD,MAAM,KAAK,GAAoC,EAAE,CAAC;QAClD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBAC1C,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACrB,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAoBD,MAAM,CAAC,YAAY,CACjB,IAAY,EACZ,MAUC;QAED,MAAM,KAAK,GAAG,UAAU,CAAC,eAAe,CAAC;YACvC,OAAO,EAAE,MAAM,CAAC,KAAK,IAAI,QAAQ;YACjC,MAAM,EAAE,MAAM,CAAC,IAAI;YACnB,SAAS,EAAE,MAAM,CAAC,KAAK;YACvB,SAAS,EAAE,MAAM,CAAC,KAAK;YACvB,cAAc,EAAE,MAAM,CAAC,UAAU;YACjC,aAAa,EAAE,MAAM,CAAC,SAAS;YAC/B,cAAc,EAAE,MAAM,CAAC,UAAU;YACjC,UAAU,EAAE,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;YAC/E,SAAS,EAAE,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;SAC7E,CAAC,CAAC;QAEH,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAkBD,MAAM,CAAC,aAAa,CAAC,OAAsB;QACzC,MAAM,KAAK,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;QAE9C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrD,KAAK,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;QAC3B,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAoBD,MAAM,CAAC,aAAa,CAClB,IAAY,EACZ,OAOC;QAED,MAAM,QAAQ,GAAiB,EAAE,CAAC;QAElC,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAClF,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC","sourcesContent":["/**\n * XMLBuilder - Utility for building XML content\n * Provides a simple fluent API for generating WordprocessingML XML\n */\n\nimport { removeInvalidXmlChars } from '../utils/xmlSanitization.js';\nimport type { ShadingConfig } from '../elements/CommonTypes.js';\nimport { buildShadingAttributes } from '../elements/CommonTypes.js';\n\n/** Represents a parsed XML object from XMLParser.parseToObject() */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any -- parsed XML has dynamic keys and recursive structure\ntype ParsedXmlObject = Record<string, any>;\n\n/**\n * Represents an XML element with attributes and children\n */\nexport interface XMLElement {\n  name: string;\n  attributes?: Record<string, string | number | boolean | undefined>;\n  children?: (XMLElement | string)[];\n  selfClosing?: boolean;\n  /** Raw XML content to include without escaping (used for VML passthrough) */\n  rawXml?: string;\n}\n\n/**\n * XML Builder for creating WordprocessingML XML\n */\nexport class XMLBuilder {\n  private elements: (XMLElement | string)[] = [];\n\n  /**\n   * Elements that must NEVER be self-closing in Word XML per ECMA-376.\n   * Self-closing these elements causes Word to not parse correctly or lose content.\n   */\n  private static readonly CANNOT_SELF_CLOSE = [\n    'w:t',\n    'w:r',\n    'w:p',\n    'w:tbl',\n    'w:tr',\n    'w:tc',\n    'w:body',\n    'w:document',\n    'w:hyperlink',\n    'w:sdt',\n    'w:sdtContent',\n    'w:sdtPr',\n    'w:pPr',\n    'w:rPr',\n    'w:sectPr',\n    'w:del', // Deletion revisions - container element, must have closing tag\n    'w:ins', // Insertion revisions - container element, must have closing tag\n    'w:moveFrom', // Move source markers - container element\n    'w:moveTo', // Move destination markers - container element\n    // Note: w:bookmarkStart and w:bookmarkEnd MUST be self-closing per ECMA-376\n  ];\n\n  /**\n   * Adds an element to the builder\n   * @param name - Element name (with namespace prefix if needed)\n   * @param attributes - Element attributes\n   * @param children - Child elements or text\n   * @returns This builder for chaining\n   */\n  element(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>,\n    children?: (XMLElement | string)[]\n  ): XMLBuilder {\n    this.elements.push({\n      name,\n      attributes,\n      children,\n    });\n    return this;\n  }\n\n  /**\n   * Adds a self-closing element\n   * @param name - Element name\n   * @param attributes - Element attributes\n   * @returns This builder for chaining\n   * @throws {Error} If attempting to create self-closing w:t element (not allowed per ECMA-376)\n   */\n  selfClosingElement(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>\n  ): XMLBuilder {\n    // Validation: Text elements (<w:t>) cannot be self-closing per ECMA-376\n    // Self-closing <w:t/> elements cause Word to fail opening the document\n    if (name === 'w:t' || name === 't') {\n      throw new Error(\n        'Text elements (<w:t>) cannot be self-closing per ECMA-376. ' +\n          'Use element() with empty text content instead: XMLBuilder.w(\"t\", attrs, [\"\"])'\n      );\n    }\n\n    this.elements.push({\n      name,\n      attributes,\n      selfClosing: true,\n    });\n    return this;\n  }\n\n  /**\n   * Adds text content\n   * @param text - Text to add\n   * @returns This builder for chaining\n   */\n  text(text: string): XMLBuilder {\n    this.elements.push(text);\n    return this;\n  }\n\n  /**\n   * Builds the XML string\n   * @param includeDeclaration - Whether to include XML declaration\n   * @returns Generated XML string\n   */\n  build(includeDeclaration = false): string {\n    let xml = '';\n\n    if (includeDeclaration) {\n      xml += '<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\\n';\n    }\n\n    xml += this.elementsToString(this.elements);\n    return xml;\n  }\n\n  /**\n   * Converts elements to XML string\n   */\n  private elementsToString(elements: (XMLElement | string)[]): string {\n    let xml = '';\n\n    for (const element of elements) {\n      if (typeof element === 'string') {\n        xml += this.escapeXml(element);\n      } else {\n        xml += this.elementToString(element);\n      }\n    }\n\n    return xml;\n  }\n\n  /**\n   * Converts a single element to XML string\n   */\n  private elementToString(element: XMLElement): string {\n    // Special case: raw XML passthrough (no wrapper element)\n    // Used for VML and other legacy content that must be preserved exactly\n    if (element.name === '__rawXml' && element.rawXml) {\n      return element.rawXml;\n    }\n\n    let xml = `<${element.name}`;\n\n    // Add attributes\n    if (element.attributes) {\n      for (const [key, value] of Object.entries(element.attributes)) {\n        if (value !== undefined && value !== null && value !== false) {\n          // Handle boolean attributes\n          const attrValue = value === true ? key : String(value);\n          // Use escapeXmlAttribute for attribute values (Issue #8)\n          xml += ` ${key}=\"${XMLBuilder.escapeXmlAttribute(attrValue)}\"`;\n        }\n      }\n    }\n\n    // Self-closing element validation\n    if (element.selfClosing) {\n      if (XMLBuilder.CANNOT_SELF_CLOSE.includes(element.name)) {\n        // Instead of throwing, force open/close tags for safety\n        xml += '></' + element.name + '>';\n        return xml;\n      }\n      xml += '/>';\n      return xml;\n    }\n\n    xml += '>';\n\n    // Add raw XML content if present (for VML passthrough)\n    if (element.rawXml) {\n      xml += element.rawXml;\n    }\n\n    // Add children\n    if (element.children && element.children.length > 0) {\n      xml += this.elementsToString(element.children);\n    }\n\n    xml += `</${element.name}>`;\n    return xml;\n  }\n\n  /**\n   * Escapes special XML characters for text content\n   * (Issue #8 fix: Use escapeXmlText for element text, escapeXmlAttribute called directly for attrs)\n   */\n  private escapeXml(text: string): string {\n    // This method is now only used for text content in elementsToString()\n    // Attributes call escapeXmlAttribute() directly in elementToString()\n    // Text content should NOT escape quotes (only & < >)\n    return XMLBuilder.escapeXmlText(text);\n  }\n\n  /**\n   * Escapes XML text content (element text nodes)\n   * Removes invalid XML 1.0 control characters and escapes: & < >\n   *\n   * Per XML 1.0 spec, control chars 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F are invalid.\n   * Tab (0x09), newline (0x0A), and CR (0x0D) are preserved.\n   *\n   * @param text Text to escape\n   * @returns Escaped text safe for XML content\n   */\n  static escapeXmlText(text: string): string {\n    return removeInvalidXmlChars(text)\n      .replace(/&/g, '&amp;')\n      .replace(/</g, '&lt;')\n      .replace(/>/g, '&gt;');\n  }\n\n  /**\n   * Escapes XML attribute values\n   * Removes invalid XML 1.0 control characters and escapes: & < > \" '\n   *\n   * Per XML 1.0 spec, control chars 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F are invalid.\n   * Tab (0x09), newline (0x0A), and CR (0x0D) are preserved.\n   *\n   * @param value Attribute value to escape\n   * @returns Escaped value safe for XML attributes\n   */\n  static escapeXmlAttribute(value: string): string {\n    return removeInvalidXmlChars(value)\n      .replace(/&/g, '&amp;')\n      .replace(/</g, '&lt;')\n      .replace(/>/g, '&gt;')\n      .replace(/\"/g, '&quot;')\n      .replace(/'/g, '&apos;');\n  }\n\n  /**\n   * Unescapes XML entities back to original characters\n   * @param text Text with XML entities\n   * @returns Unescaped text\n   */\n  static unescapeXml(text: string): string {\n    return text\n      .replace(/&lt;/g, '<')\n      .replace(/&gt;/g, '>')\n      .replace(/&quot;/g, '\"')\n      .replace(/&apos;/g, \"'\")\n      .replace(/&amp;/g, '&'); // Must be last to avoid double-unescaping\n  }\n\n  /**\n   * Sanitizes and escapes XML content for safe inclusion in XML documents\n   * Removes control characters, null bytes, and escapes special XML characters\n   * Use this for user-provided content that may contain unsafe characters\n   *\n   * Per XML 1.0 spec, control chars 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F are invalid.\n   * Tab (0x09), newline (0x0A), and CR (0x0D) are preserved.\n   *\n   * @param text Text to sanitize and escape\n   * @returns Sanitized text safe for XML content\n   *\n   * **Issue #11 fix:** Prevents malformed XML from CDATA markers, control chars, etc.\n   */\n  static sanitizeXmlContent(text: string): string {\n    return (\n      removeInvalidXmlChars(text)\n        // Escape CDATA end marker to prevent CDATA injection\n        .replace(/\\]\\]>/g, ']]&gt;')\n        // Standard XML escaping (& must be first to avoid double-escaping)\n        .replace(/&/g, '&amp;')\n        .replace(/</g, '&lt;')\n        .replace(/>/g, '&gt;')\n    );\n  }\n\n  /**\n   * Creates a WordprocessingML namespace attribute object\n   */\n  static createNamespaces(): Record<string, string> {\n    return {\n      'xmlns:w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main',\n      'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',\n      'xmlns:wp': 'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing',\n      'xmlns:a': 'http://schemas.openxmlformats.org/drawingml/2006/main',\n      'xmlns:pic': 'http://schemas.openxmlformats.org/drawingml/2006/picture',\n      'xmlns:w14': 'http://schemas.microsoft.com/office/word/2010/wordml',\n      'xmlns:wpc': 'http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas',\n      'xmlns:mc': 'http://schemas.openxmlformats.org/markup-compatibility/2006',\n      'xmlns:o': 'urn:schemas-microsoft-com:office:office',\n      'xmlns:v': 'urn:schemas-microsoft-com:vml',\n      'xmlns:wp14': 'http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing',\n      'xmlns:w10': 'urn:schemas-microsoft-com:office:word',\n      'xmlns:w15': 'http://schemas.microsoft.com/office/word/2012/wordml',\n      'xmlns:wpg': 'http://schemas.microsoft.com/office/word/2010/wordprocessingGroup',\n      'xmlns:wpi': 'http://schemas.microsoft.com/office/word/2010/wordprocessingInk',\n      'xmlns:wne': 'http://schemas.microsoft.com/office/word/2006/wordml',\n      'xmlns:wps': 'http://schemas.microsoft.com/office/word/2010/wordprocessingShape',\n      'xmlns:asvg': 'http://schemas.microsoft.com/office/drawing/2016/SVG/main',\n    };\n  }\n\n  /**\n   * Converts a single XMLElement to its XML string representation\n   * Useful for merging elements into existing XML\n   *\n   * @param element - The XMLElement to convert\n   * @returns XML string representation of the element\n   */\n  static elementToString(element: XMLElement): string {\n    const builder = new XMLBuilder();\n    // Use the private elementToString via the elements array + build\n    (builder as any).elements.push(element);\n    return builder.build();\n  }\n\n  /**\n   * Helper method to create a WordprocessingML element\n   * @param name - Element name (without 'w:' prefix)\n   * @param attributes - Element attributes\n   * @param children - Child elements\n   * @returns XMLElement\n   */\n  static w(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>,\n    children?: (XMLElement | string)[]\n  ): XMLElement {\n    return {\n      name: `w:${name}`,\n      attributes,\n      children,\n    };\n  }\n\n  /**\n   * Helper method to create a self-closing WordprocessingML element\n   * @param name - Element name (without 'w:' prefix)\n   * @param attributes - Element attributes\n   * @returns XMLElement\n   */\n  static wSelf(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>\n  ): XMLElement {\n    return {\n      name: `w:${name}`,\n      attributes,\n      selfClosing: true,\n    };\n  }\n\n  /**\n   * Helper method to create a w14 element (Word 2010+ features)\n   * @param name - Element name (without 'w14:' prefix)\n   * @param attributes - Element attributes\n   * @param children - Child elements\n   * @returns XMLElement\n   */\n  static w14(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>,\n    children?: (XMLElement | string)[]\n  ): XMLElement {\n    return {\n      name: `w14:${name}`,\n      attributes,\n      children,\n    };\n  }\n\n  /**\n   * Helper method to create a self-closing w14 element\n   * @param name - Element name (without 'w14:' prefix)\n   * @param attributes - Element attributes\n   * @returns XMLElement\n   */\n  static w14Self(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>\n  ): XMLElement {\n    return {\n      name: `w14:${name}`,\n      attributes,\n      selfClosing: true,\n    };\n  }\n\n  /**\n   * Helper method to create a DrawingML element (a: namespace)\n   * @param name - Element name (without 'a:' prefix)\n   * @param attributes - Element attributes\n   * @param children - Child elements\n   * @returns XMLElement\n   */\n  static a(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>,\n    children?: (XMLElement | string)[]\n  ): XMLElement {\n    return {\n      name: `a:${name}`,\n      attributes,\n      children,\n    };\n  }\n\n  /**\n   * Helper method to create a self-closing DrawingML element\n   * @param name - Element name (without 'a:' prefix)\n   * @param attributes - Element attributes\n   * @returns XMLElement\n   */\n  static aSelf(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>\n  ): XMLElement {\n    return {\n      name: `a:${name}`,\n      attributes,\n      selfClosing: true,\n    };\n  }\n\n  /**\n   * Helper method to create a Picture element (pic: namespace)\n   * @param name - Element name (without 'pic:' prefix)\n   * @param attributes - Element attributes\n   * @param children - Child elements\n   * @returns XMLElement\n   */\n  static pic(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>,\n    children?: (XMLElement | string)[]\n  ): XMLElement {\n    return {\n      name: `pic:${name}`,\n      attributes,\n      children,\n    };\n  }\n\n  /**\n   * Helper method to create a self-closing Picture element\n   * @param name - Element name (without 'pic:' prefix)\n   * @param attributes - Element attributes\n   * @returns XMLElement\n   */\n  static picSelf(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>\n  ): XMLElement {\n    return {\n      name: `pic:${name}`,\n      attributes,\n      selfClosing: true,\n    };\n  }\n\n  /**\n   * Helper method to create a Wordprocessing Drawing element (wp: namespace)\n   * @param name - Element name (without 'wp:' prefix)\n   * @param attributes - Element attributes\n   * @param children - Child elements\n   * @returns XMLElement\n   */\n  static wp(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>,\n    children?: (XMLElement | string)[]\n  ): XMLElement {\n    return {\n      name: `wp:${name}`,\n      attributes,\n      children,\n    };\n  }\n\n  /**\n   * Helper method to create a self-closing Wordprocessing Drawing element\n   * @param name - Element name (without 'wp:' prefix)\n   * @param attributes - Element attributes\n   * @returns XMLElement\n   */\n  static wpSelf(\n    name: string,\n    attributes?: Record<string, string | number | boolean | undefined>\n  ): XMLElement {\n    return {\n      name: `wp:${name}`,\n      attributes,\n      selfClosing: true,\n    };\n  }\n\n  /**\n   * Helper to create cx/cy extent attributes (for a:ext, wp:extent, etc.)\n   * @param name - Element name (e.g., 'ext')\n   * @param cx - Width in EMUs\n   * @param cy - Height in EMUs\n   * @returns Self-closing XMLElement\n   */\n  static cxCy(name: string, cx: number, cy: number): XMLElement {\n    return {\n      name,\n      attributes: { cx, cy },\n      selfClosing: true,\n    };\n  }\n\n  /**\n   * Creates an SDT (Structured Document Tag) wrapper for content\n   * @param content - Content to wrap (paragraphs, tables, etc.)\n   * @param options - SDT options\n   * @returns XMLElement representing the SDT wrapper\n   */\n  static createSDT(\n    content: XMLElement[],\n    options?: {\n      id?: number;\n      docPartGallery?: string;\n      docPartUnique?: boolean;\n    }\n  ): XMLElement {\n    const sdtId = options?.id ?? Math.floor(Math.random() * 2000000000) - 1000000000;\n\n    // Build SDT properties\n    const sdtPrChildren: XMLElement[] = [XMLBuilder.wSelf('id', { 'w:val': sdtId })];\n\n    // Add docPartObj if docPartGallery is specified\n    if (options?.docPartGallery) {\n      sdtPrChildren.push(\n        XMLBuilder.w('docPartObj', undefined, [\n          XMLBuilder.wSelf('docPartGallery', { 'w:val': options.docPartGallery }),\n          XMLBuilder.wSelf('docPartUnique', {\n            'w:val': options?.docPartUnique !== false ? '1' : '0',\n          }),\n        ])\n      );\n    }\n\n    // Create complete SDT structure\n    return XMLBuilder.w('sdt', undefined, [\n      XMLBuilder.w('sdtPr', undefined, sdtPrChildren),\n      XMLBuilder.w('sdtContent', undefined, content),\n    ]);\n  }\n\n  /**\n   * Creates a complete WordprocessingML document structure\n   * @param bodyContent - Content for the document body\n   * @returns XML string for word/document.xml\n   */\n  static createDocument(\n    bodyContent: XMLElement[],\n    namespaces: Record<string, string> = {},\n    preBodyContent?: XMLElement[]\n  ): string {\n    const builder = new XMLBuilder();\n\n    // Preserve document's original namespace order, then fill in framework defaults\n    const allNamespaces: Record<string, string> = {};\n    for (const [key, value] of Object.entries(namespaces)) {\n      allNamespaces[key] = value;\n    }\n    for (const [key, value] of Object.entries(XMLBuilder.createNamespaces())) {\n      if (!(key in allNamespaces)) {\n        allNamespaces[key] = value;\n      }\n    }\n\n    // Ensure mc:Ignorable is present when extended namespaces are declared.\n    // Per ECMA-376, mc:Ignorable tells Word which namespace prefixes can be\n    // safely ignored if the processor doesn't support them. Without it,\n    // attributes like w14:paraId in raw XML passthrough zones cause corruption.\n    if (!allNamespaces['mc:Ignorable']) {\n      const ignorable: string[] = [];\n      if (allNamespaces['xmlns:w14']) ignorable.push('w14');\n      if (allNamespaces['xmlns:w15']) ignorable.push('w15');\n      if (allNamespaces['xmlns:wp14']) ignorable.push('wp14');\n      if (allNamespaces['xmlns:w16se']) ignorable.push('w16se');\n      if (allNamespaces['xmlns:w16cid']) ignorable.push('w16cid');\n      if (allNamespaces['xmlns:w16']) ignorable.push('w16');\n      if (allNamespaces['xmlns:w16cex']) ignorable.push('w16cex');\n      if (allNamespaces['xmlns:w16sdtdh']) ignorable.push('w16sdtdh');\n      if (allNamespaces['xmlns:w16sdtfl']) ignorable.push('w16sdtfl');\n      if (allNamespaces['xmlns:w16du']) ignorable.push('w16du');\n      if (allNamespaces['xmlns:asvg']) ignorable.push('asvg');\n      if (ignorable.length > 0) {\n        allNamespaces['mc:Ignorable'] = ignorable.join(' ');\n      }\n    } else {\n      // mc:Ignorable was loaded from the original document — ensure every\n      // prefix referenced in mc:Ignorable has a matching xmlns declaration.\n      // Without this, the validator rejects prefixes that appear in\n      // mc:Ignorable but lack namespace declarations in the root element.\n      const defaults = XMLBuilder.createNamespaces();\n      const prefixes = allNamespaces['mc:Ignorable'].split(/\\s+/);\n      for (const prefix of prefixes) {\n        const nsKey = `xmlns:${prefix}`;\n        if (!allNamespaces[nsKey] && defaults[nsKey]) {\n          allNamespaces[nsKey] = defaults[nsKey];\n        }\n      }\n    }\n\n    const documentChildren: XMLElement[] = [];\n    if (preBodyContent) {\n      documentChildren.push(...preBodyContent);\n    }\n    documentChildren.push(XMLBuilder.w('body', undefined, bodyContent));\n    builder.element('w:document', allNamespaces, documentChildren);\n\n    return builder.build(true);\n  }\n\n  /**\n   * Builds an XML string from a JavaScript object.\n   * This is the reverse of XMLParser.parseToObject\n   */\n  static buildObject(obj: ParsedXmlObject, rootName: string): string {\n    const builder = new XMLBuilder();\n    const element = XMLBuilder.objectToElement(obj, rootName);\n    if (element) {\n      if (typeof element === 'string') {\n        builder.text(element);\n      } else {\n        builder.elements.push(element);\n      }\n    }\n    return builder.build();\n  }\n\n  /**\n   * Converts a JavaScript object to an XMLElement.\n   * @private\n   */\n  private static objectToElement(\n    obj: ParsedXmlObject | string | number | boolean | null | undefined,\n    name: string\n  ): XMLElement | string | null {\n    if (obj === null || obj === undefined) {\n      return null;\n    }\n\n    if (typeof obj !== 'object' || obj === null) {\n      return String(obj);\n    }\n\n    const attributes: Record<string, string | number | boolean> = {};\n    const children: (XMLElement | string)[] = [];\n\n    if (obj['#text'] && Object.keys(obj).length === 1) {\n      return String(obj['#text']);\n    }\n\n    for (const key in obj) {\n      if (key.startsWith('@_')) {\n        const attrName = key.substring(2);\n        // Validate attribute name is not empty after prefix removal\n        if (attrName.length > 0) {\n          attributes[attrName] = obj[key];\n        }\n      } else if (key === '#text') {\n        children.push(String(obj[key]));\n      } else {\n        const childObj = obj[key];\n        if (Array.isArray(childObj)) {\n          childObj.forEach((item) => {\n            const childElement = XMLBuilder.objectToElement(item, key);\n            if (childElement) {\n              children.push(childElement);\n            }\n          });\n        } else {\n          const childElement = XMLBuilder.objectToElement(childObj, key);\n          if (childElement) {\n            children.push(childElement);\n          }\n        }\n      }\n    }\n\n    const element: XMLElement = {\n      name,\n      attributes,\n      children: children.length > 0 ? children : undefined,\n    };\n\n    if (!element.children || element.children.length === 0) {\n      if (!XMLBuilder.CANNOT_SELF_CLOSE.includes(name)) {\n        element.selfClosing = true;\n      }\n    }\n\n    return element;\n  }\n\n  /**\n   * Helper method to build attributes object, filtering out undefined/null values\n   * This simplifies the common pattern of conditionally adding attributes\n   *\n   * @param mapping - Map of attribute names to values\n   * @returns Filtered attributes object with only defined values\n   *\n   * @example\n   * ```typescript\n   * const attrs = XMLBuilder.buildAttributes({\n   *   'w:before': spacing?.before,\n   *   'w:after': spacing?.after,\n   *   'w:line': spacing?.line\n   * });\n   * // Returns only attributes with defined values\n   * ```\n   */\n  static buildAttributes(mapping: Record<string, any>): Record<string, string | number> {\n    const attrs: Record<string, string | number> = {};\n    for (const [key, value] of Object.entries(mapping)) {\n      if (value !== undefined && value !== null) {\n        attrs[key] = value;\n      }\n    }\n    return attrs;\n  }\n\n  /**\n   * Creates a border element for WordprocessingML\n   * Used for table borders, cell borders, and paragraph borders\n   *\n   * @param side - Border side (e.g., 'top', 'left', 'bottom', 'right', 'insideH', 'insideV')\n   * @param border - Border definition\n   * @returns XML element for border\n   *\n   * @example\n   * ```typescript\n   * const border = XMLBuilder.createBorder('top', {\n   *   style: 'single',\n   *   size: 4,\n   *   color: 'FF0000',\n   *   space: 0\n   * });\n   * ```\n   */\n  static createBorder(\n    side: string,\n    border: {\n      style?: string;\n      size?: number;\n      color?: string;\n      space?: number;\n      themeColor?: string;\n      themeTint?: string;\n      themeShade?: string;\n      shadow?: boolean;\n      frame?: boolean;\n    }\n  ): XMLElement {\n    const attrs = XMLBuilder.buildAttributes({\n      'w:val': border.style || 'single',\n      'w:sz': border.size,\n      'w:color': border.color,\n      'w:space': border.space,\n      'w:themeColor': border.themeColor,\n      'w:themeTint': border.themeTint,\n      'w:themeShade': border.themeShade,\n      'w:shadow': border.shadow === undefined ? undefined : border.shadow ? '1' : '0',\n      'w:frame': border.frame === undefined ? undefined : border.frame ? '1' : '0',\n    });\n\n    return XMLBuilder.wSelf(side, attrs);\n  }\n\n  /**\n   * Creates a shading element for WordprocessingML\n   * Used for paragraph shading, table shading, and cell shading\n   *\n   * @param shading - Shading definition (ShadingConfig with theme support)\n   * @returns XML element for shading, or null if no shading properties\n   *\n   * @example\n   * ```typescript\n   * const shading = XMLBuilder.createShading({\n   *   fill: 'FFFF00',\n   *   pattern: 'clear',\n   *   color: '000000'\n   * });\n   * ```\n   */\n  static createShading(shading: ShadingConfig): XMLElement | null {\n    const attrs = buildShadingAttributes(shading);\n    // Default w:val to \"clear\" if not specified but other attrs exist\n    if (!attrs['w:val'] && Object.keys(attrs).length > 0) {\n      attrs['w:val'] = 'clear';\n    }\n    if (Object.keys(attrs).length > 0) {\n      return XMLBuilder.wSelf('shd', attrs);\n    }\n    return null;\n  }\n\n  /**\n   * Creates a margins element (tcMar, pgMar, etc.)\n   * Used for cell margins, page margins, etc.\n   *\n   * @param type - Margin type element name (e.g., 'tcMar', 'pgMar')\n   * @param margins - Margin values in twips\n   * @returns XML element for margins, or null if no margins defined\n   *\n   * @example\n   * ```typescript\n   * const margins = XMLBuilder.createMargins('tcMar', {\n   *   top: 100,\n   *   bottom: 100,\n   *   left: 100,\n   *   right: 100\n   * });\n   * ```\n   */\n  static createMargins(\n    type: string,\n    margins: {\n      top?: number;\n      bottom?: number;\n      left?: number;\n      right?: number;\n      start?: number;\n      end?: number;\n    }\n  ): XMLElement | null {\n    const children: XMLElement[] = [];\n\n    if (margins.top !== undefined) {\n      children.push(XMLBuilder.wSelf('top', { 'w:w': margins.top, 'w:type': 'dxa' }));\n    }\n    if (margins.bottom !== undefined) {\n      children.push(XMLBuilder.wSelf('bottom', { 'w:w': margins.bottom, 'w:type': 'dxa' }));\n    }\n    if (margins.left !== undefined) {\n      children.push(XMLBuilder.wSelf('left', { 'w:w': margins.left, 'w:type': 'dxa' }));\n    }\n    if (margins.right !== undefined) {\n      children.push(XMLBuilder.wSelf('right', { 'w:w': margins.right, 'w:type': 'dxa' }));\n    }\n    if (margins.start !== undefined) {\n      children.push(XMLBuilder.wSelf('start', { 'w:w': margins.start, 'w:type': 'dxa' }));\n    }\n    if (margins.end !== undefined) {\n      children.push(XMLBuilder.wSelf('end', { 'w:w': margins.end, 'w:type': 'dxa' }));\n    }\n\n    if (children.length > 0) {\n      return XMLBuilder.w(type, undefined, children);\n    }\n    return null;\n  }\n}\n"]}