docxmlater 10.0.1 → 10.0.3

package/src/xml/XMLBuilder.ts

@@ -0,0 +1,871 @@
+/**
+ * XMLBuilder - Utility for building XML content
+ * Provides a simple fluent API for generating WordprocessingML XML
+ */
+
+import { removeInvalidXmlChars } from "../utils/xmlSanitization";
+import type { ShadingConfig } from "../elements/CommonTypes";
+import { buildShadingAttributes } from "../elements/CommonTypes";
+
+/** Represents a parsed XML object from XMLParser.parseToObject() */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- parsed XML has dynamic keys and recursive structure
+type ParsedXmlObject = Record<string, any>;
+
+/**
+ * Represents an XML element with attributes and children
+ */
+export interface XMLElement {
+  name: string;
+  attributes?: Record<string, string | number | boolean | undefined>;
+  children?: (XMLElement | string)[];
+  selfClosing?: boolean;
+  /** Raw XML content to include without escaping (used for VML passthrough) */
+  rawXml?: string;
+}
+
+/**
+ * XML Builder for creating WordprocessingML XML
+ */
+export class XMLBuilder {
+  private elements: (XMLElement | string)[] = [];
+
+  /**
+   * Elements that must NEVER be self-closing in Word XML per ECMA-376.
+   * Self-closing these elements causes Word to not parse correctly or lose content.
+   */
+  private static readonly 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", // Deletion revisions - container element, must have closing tag
+    "w:ins", // Insertion revisions - container element, must have closing tag
+    "w:moveFrom", // Move source markers - container element
+    "w:moveTo", // Move destination markers - container element
+    // Note: w:bookmarkStart and w:bookmarkEnd MUST be self-closing per ECMA-376
+  ];
+
+  /**
+   * Adds an element to the builder
+   * @param name - Element name (with namespace prefix if needed)
+   * @param attributes - Element attributes
+   * @param children - Child elements or text
+   * @returns This builder for chaining
+   */
+  element(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>,
+    children?: (XMLElement | string)[]
+  ): XMLBuilder {
+    this.elements.push({
+      name,
+      attributes,
+      children,
+    });
+    return this;
+  }
+
+  /**
+   * Adds a self-closing element
+   * @param name - Element name
+   * @param attributes - Element attributes
+   * @returns This builder for chaining
+   * @throws {Error} If attempting to create self-closing w:t element (not allowed per ECMA-376)
+   */
+  selfClosingElement(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>
+  ): XMLBuilder {
+    // Validation: Text elements (<w:t>) cannot be self-closing per ECMA-376
+    // Self-closing <w:t/> elements cause Word to fail opening the document
+    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;
+  }
+
+  /**
+   * Adds text content
+   * @param text - Text to add
+   * @returns This builder for chaining
+   */
+  text(text: string): XMLBuilder {
+    this.elements.push(text);
+    return this;
+  }
+
+  /**
+   * Builds the XML string
+   * @param includeDeclaration - Whether to include XML declaration
+   * @returns Generated XML string
+   */
+  build(includeDeclaration = false): string {
+    let xml = "";
+
+    if (includeDeclaration) {
+      xml += '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+    }
+
+    xml += this.elementsToString(this.elements);
+    return xml;
+  }
+
+  /**
+   * Converts elements to XML string
+   */
+  private elementsToString(elements: (XMLElement | string)[]): string {
+    let xml = "";
+
+    for (const element of elements) {
+      if (typeof element === "string") {
+        xml += this.escapeXml(element);
+      } else {
+        xml += this.elementToString(element);
+      }
+    }
+
+    return xml;
+  }
+
+  /**
+   * Converts a single element to XML string
+   */
+  private elementToString(element: XMLElement): string {
+    // Special case: raw XML passthrough (no wrapper element)
+    // Used for VML and other legacy content that must be preserved exactly
+    if (element.name === "__rawXml" && element.rawXml) {
+      return element.rawXml;
+    }
+
+    let xml = `<${element.name}`;
+
+    // Add attributes
+    if (element.attributes) {
+      for (const [key, value] of Object.entries(element.attributes)) {
+        if (value !== undefined && value !== null && value !== false) {
+          // Handle boolean attributes
+          const attrValue = value === true ? key : String(value);
+          // Use escapeXmlAttribute for attribute values (Issue #8)
+          xml += ` ${key}="${XMLBuilder.escapeXmlAttribute(attrValue)}"`;
+        }
+      }
+    }
+
+    // Self-closing element validation
+    if (element.selfClosing) {
+      if (XMLBuilder.CANNOT_SELF_CLOSE.includes(element.name)) {
+        // Instead of throwing, force open/close tags for safety
+        xml += "></" + element.name + ">";
+        return xml;
+      }
+      xml += "/>";
+      return xml;
+    }
+
+    xml += ">";
+
+    // Add raw XML content if present (for VML passthrough)
+    if (element.rawXml) {
+      xml += element.rawXml;
+    }
+
+    // Add children
+    if (element.children && element.children.length > 0) {
+      xml += this.elementsToString(element.children);
+    }
+
+    xml += `</${element.name}>`;
+    return xml;
+  }
+
+  /**
+   * Escapes special XML characters for text content
+   * (Issue #8 fix: Use escapeXmlText for element text, escapeXmlAttribute called directly for attrs)
+   */
+  private escapeXml(text: string): string {
+    // This method is now only used for text content in elementsToString()
+    // Attributes call escapeXmlAttribute() directly in elementToString()
+    // Text content should NOT escape quotes (only & < >)
+    return XMLBuilder.escapeXmlText(text);
+  }
+
+  /**
+   * Escapes XML text content (element text nodes)
+   * Removes invalid XML 1.0 control characters and escapes: & < >
+   *
+   * Per XML 1.0 spec, control chars 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F are invalid.
+   * Tab (0x09), newline (0x0A), and CR (0x0D) are preserved.
+   *
+   * @param text Text to escape
+   * @returns Escaped text safe for XML content
+   */
+  static escapeXmlText(text: string): string {
+    return removeInvalidXmlChars(text)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;");
+  }
+
+  /**
+   * Escapes XML attribute values
+   * Removes invalid XML 1.0 control characters and escapes: & < > " '
+   *
+   * Per XML 1.0 spec, control chars 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F are invalid.
+   * Tab (0x09), newline (0x0A), and CR (0x0D) are preserved.
+   *
+   * @param value Attribute value to escape
+   * @returns Escaped value safe for XML attributes
+   */
+  static escapeXmlAttribute(value: string): string {
+    return removeInvalidXmlChars(value)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&apos;");
+  }
+
+  /**
+   * Unescapes XML entities back to original characters
+   * @param text Text with XML entities
+   * @returns Unescaped text
+   */
+  static unescapeXml(text: string): string {
+    return text
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'")
+      .replace(/&amp;/g, "&"); // Must be last to avoid double-unescaping
+  }
+
+  /**
+   * Sanitizes and escapes XML content for safe inclusion in XML documents
+   * Removes control characters, null bytes, and escapes special XML characters
+   * Use this for user-provided content that may contain unsafe characters
+   *
+   * Per XML 1.0 spec, control chars 0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F are invalid.
+   * Tab (0x09), newline (0x0A), and CR (0x0D) are preserved.
+   *
+   * @param text Text to sanitize and escape
+   * @returns Sanitized text safe for XML content
+   *
+   * **Issue #11 fix:** Prevents malformed XML from CDATA markers, control chars, etc.
+   */
+  static sanitizeXmlContent(text: string): string {
+    return (
+      removeInvalidXmlChars(text)
+        // Escape CDATA end marker to prevent CDATA injection
+        .replace(/\]\]>/g, "]]&gt;")
+        // Standard XML escaping (& must be first to avoid double-escaping)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+    );
+  }
+
+  /**
+   * Creates a WordprocessingML namespace attribute object
+   */
+  static createNamespaces(): Record<string, string> {
+    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",
+    };
+  }
+
+  /**
+   * Converts a single XMLElement to its XML string representation
+   * Useful for merging elements into existing XML
+   *
+   * @param element - The XMLElement to convert
+   * @returns XML string representation of the element
+   */
+  static elementToString(element: XMLElement): string {
+    const builder = new XMLBuilder();
+    // Use the private elementToString via the elements array + build
+    (builder as any).elements.push(element);
+    return builder.build();
+  }
+
+  /**
+   * Helper method to create a WordprocessingML element
+   * @param name - Element name (without 'w:' prefix)
+   * @param attributes - Element attributes
+   * @param children - Child elements
+   * @returns XMLElement
+   */
+  static w(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>,
+    children?: (XMLElement | string)[]
+  ): XMLElement {
+    return {
+      name: `w:${name}`,
+      attributes,
+      children,
+    };
+  }
+
+  /**
+   * Helper method to create a self-closing WordprocessingML element
+   * @param name - Element name (without 'w:' prefix)
+   * @param attributes - Element attributes
+   * @returns XMLElement
+   */
+  static wSelf(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>
+  ): XMLElement {
+    return {
+      name: `w:${name}`,
+      attributes,
+      selfClosing: true,
+    };
+  }
+
+  /**
+   * Helper method to create a w14 element (Word 2010+ features)
+   * @param name - Element name (without 'w14:' prefix)
+   * @param attributes - Element attributes
+   * @param children - Child elements
+   * @returns XMLElement
+   */
+  static w14(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>,
+    children?: (XMLElement | string)[]
+  ): XMLElement {
+    return {
+      name: `w14:${name}`,
+      attributes,
+      children,
+    };
+  }
+
+  /**
+   * Helper method to create a self-closing w14 element
+   * @param name - Element name (without 'w14:' prefix)
+   * @param attributes - Element attributes
+   * @returns XMLElement
+   */
+  static w14Self(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>
+  ): XMLElement {
+    return {
+      name: `w14:${name}`,
+      attributes,
+      selfClosing: true,
+    };
+  }
+
+  /**
+   * Helper method to create a DrawingML element (a: namespace)
+   * @param name - Element name (without 'a:' prefix)
+   * @param attributes - Element attributes
+   * @param children - Child elements
+   * @returns XMLElement
+   */
+  static a(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>,
+    children?: (XMLElement | string)[]
+  ): XMLElement {
+    return {
+      name: `a:${name}`,
+      attributes,
+      children,
+    };
+  }
+
+  /**
+   * Helper method to create a self-closing DrawingML element
+   * @param name - Element name (without 'a:' prefix)
+   * @param attributes - Element attributes
+   * @returns XMLElement
+   */
+  static aSelf(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>
+  ): XMLElement {
+    return {
+      name: `a:${name}`,
+      attributes,
+      selfClosing: true,
+    };
+  }
+
+  /**
+   * Helper method to create a Picture element (pic: namespace)
+   * @param name - Element name (without 'pic:' prefix)
+   * @param attributes - Element attributes
+   * @param children - Child elements
+   * @returns XMLElement
+   */
+  static pic(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>,
+    children?: (XMLElement | string)[]
+  ): XMLElement {
+    return {
+      name: `pic:${name}`,
+      attributes,
+      children,
+    };
+  }
+
+  /**
+   * Helper method to create a self-closing Picture element
+   * @param name - Element name (without 'pic:' prefix)
+   * @param attributes - Element attributes
+   * @returns XMLElement
+   */
+  static picSelf(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>
+  ): XMLElement {
+    return {
+      name: `pic:${name}`,
+      attributes,
+      selfClosing: true,
+    };
+  }
+
+  /**
+   * Helper method to create a Wordprocessing Drawing element (wp: namespace)
+   * @param name - Element name (without 'wp:' prefix)
+   * @param attributes - Element attributes
+   * @param children - Child elements
+   * @returns XMLElement
+   */
+  static wp(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>,
+    children?: (XMLElement | string)[]
+  ): XMLElement {
+    return {
+      name: `wp:${name}`,
+      attributes,
+      children,
+    };
+  }
+
+  /**
+   * Helper method to create a self-closing Wordprocessing Drawing element
+   * @param name - Element name (without 'wp:' prefix)
+   * @param attributes - Element attributes
+   * @returns XMLElement
+   */
+  static wpSelf(
+    name: string,
+    attributes?: Record<string, string | number | boolean | undefined>
+  ): XMLElement {
+    return {
+      name: `wp:${name}`,
+      attributes,
+      selfClosing: true,
+    };
+  }
+
+  /**
+   * Helper to create cx/cy extent attributes (for a:ext, wp:extent, etc.)
+   * @param name - Element name (e.g., 'ext')
+   * @param cx - Width in EMUs
+   * @param cy - Height in EMUs
+   * @returns Self-closing XMLElement
+   */
+  static cxCy(
+    name: string,
+    cx: number,
+    cy: number
+  ): XMLElement {
+    return {
+      name,
+      attributes: { cx, cy },
+      selfClosing: true
+    };
+  }
+
+  /**
+   * Creates an SDT (Structured Document Tag) wrapper for content
+   * @param content - Content to wrap (paragraphs, tables, etc.)
+   * @param options - SDT options
+   * @returns XMLElement representing the SDT wrapper
+   */
+  static createSDT(
+    content: XMLElement[],
+    options?: {
+      id?: number;
+      docPartGallery?: string;
+      docPartUnique?: boolean;
+    }
+  ): XMLElement {
+    const sdtId = options?.id ?? Math.floor(Math.random() * 2000000000) - 1000000000;
+
+    // Build SDT properties
+    const sdtPrChildren: XMLElement[] = [
+      XMLBuilder.wSelf('id', { 'w:val': sdtId })
+    ];
+
+    // Add docPartObj if docPartGallery is specified
+    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'
+          })
+        ])
+      );
+    }
+
+    // Create complete SDT structure
+    return XMLBuilder.w('sdt', undefined, [
+      XMLBuilder.w('sdtPr', undefined, sdtPrChildren),
+      XMLBuilder.w('sdtContent', undefined, content)
+    ]);
+  }
+
+  /**
+   * Creates a complete WordprocessingML document structure
+   * @param bodyContent - Content for the document body
+   * @returns XML string for word/document.xml
+   */
+  static createDocument(
+    bodyContent: XMLElement[],
+    namespaces: Record<string, string> = {},
+    preBodyContent?: XMLElement[]
+  ): string {
+    const builder = new XMLBuilder();
+
+    // Preserve document's original namespace order, then fill in framework defaults
+    const allNamespaces: Record<string, string> = {};
+    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;
+      }
+    }
+
+    // Ensure mc:Ignorable is present when extended namespaces are declared.
+    // Per ECMA-376, mc:Ignorable tells Word which namespace prefixes can be
+    // safely ignored if the processor doesn't support them. Without it,
+    // attributes like w14:paraId in raw XML passthrough zones cause corruption.
+    if (!allNamespaces["mc:Ignorable"]) {
+      const ignorable: string[] = [];
+      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 {
+      // mc:Ignorable was loaded from the original document — ensure every
+      // prefix referenced in mc:Ignorable has a matching xmlns declaration.
+      // Without this, the validator rejects prefixes that appear in
+      // mc:Ignorable but lack namespace declarations in the root element.
+      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: XMLElement[] = [];
+    if (preBodyContent) {
+      documentChildren.push(...preBodyContent);
+    }
+    documentChildren.push(XMLBuilder.w("body", undefined, bodyContent));
+    builder.element("w:document", allNamespaces, documentChildren);
+
+    return builder.build(true);
+  }
+
+  /**
+   * Builds an XML string from a JavaScript object.
+   * This is the reverse of XMLParser.parseToObject
+   */
+  static buildObject(obj: ParsedXmlObject, rootName: string): string {
+    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();
+  }
+
+  /**
+   * Converts a JavaScript object to an XMLElement.
+   * @private
+   */
+  private static objectToElement(
+    obj: ParsedXmlObject | string | number | boolean | null | undefined,
+    name: string
+  ): XMLElement | string | null {
+    if (obj === null || obj === undefined) {
+      return null;
+    }
+
+    if (typeof obj !== "object" || obj === null) {
+      return String(obj);
+    }
+
+    const attributes: Record<string, string | number | boolean> = {};
+    const children: (XMLElement | string)[] = [];
+
+    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);
+        // Validate attribute name is not empty after prefix removal
+        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: XMLElement = {
+      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;
+  }
+
+  /**
+   * Helper method to build attributes object, filtering out undefined/null values
+   * This simplifies the common pattern of conditionally adding attributes
+   *
+   * @param mapping - Map of attribute names to values
+   * @returns Filtered attributes object with only defined values
+   *
+   * @example
+   * ```typescript
+   * const attrs = XMLBuilder.buildAttributes({
+   *   'w:before': spacing?.before,
+   *   'w:after': spacing?.after,
+   *   'w:line': spacing?.line
+   * });
+   * // Returns only attributes with defined values
+   * ```
+   */
+  static buildAttributes(mapping: Record<string, any>): Record<string, string | number> {
+    const attrs: Record<string, string | number> = {};
+    for (const [key, value] of Object.entries(mapping)) {
+      if (value !== undefined && value !== null) {
+        attrs[key] = value;
+      }
+    }
+    return attrs;
+  }
+
+  /**
+   * Creates a border element for WordprocessingML
+   * Used for table borders, cell borders, and paragraph borders
+   *
+   * @param side - Border side (e.g., 'top', 'left', 'bottom', 'right', 'insideH', 'insideV')
+   * @param border - Border definition
+   * @returns XML element for border
+   *
+   * @example
+   * ```typescript
+   * const border = XMLBuilder.createBorder('top', {
+   *   style: 'single',
+   *   size: 4,
+   *   color: 'FF0000',
+   *   space: 0
+   * });
+   * ```
+   */
+  static createBorder(
+    side: string,
+    border: {
+      style?: string;
+      size?: number;
+      color?: string;
+      space?: number;
+    }
+  ): XMLElement {
+    const attrs = XMLBuilder.buildAttributes({
+      'w:val': border.style || 'single',
+      'w:sz': border.size,
+      'w:color': border.color,
+      'w:space': border.space
+    });
+
+    return XMLBuilder.wSelf(side, attrs);
+  }
+
+  /**
+   * Creates a shading element for WordprocessingML
+   * Used for paragraph shading, table shading, and cell shading
+   *
+   * @param shading - Shading definition (ShadingConfig with theme support)
+   * @returns XML element for shading, or null if no shading properties
+   *
+   * @example
+   * ```typescript
+   * const shading = XMLBuilder.createShading({
+   *   fill: 'FFFF00',
+   *   pattern: 'clear',
+   *   color: '000000'
+   * });
+   * ```
+   */
+  static createShading(shading: ShadingConfig): XMLElement | null {
+    const attrs = buildShadingAttributes(shading);
+    // Default w:val to "clear" if not specified but other attrs exist
+    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;
+  }
+
+  /**
+   * Creates a margins element (tcMar, pgMar, etc.)
+   * Used for cell margins, page margins, etc.
+   *
+   * @param type - Margin type element name (e.g., 'tcMar', 'pgMar')
+   * @param margins - Margin values in twips
+   * @returns XML element for margins, or null if no margins defined
+   *
+   * @example
+   * ```typescript
+   * const margins = XMLBuilder.createMargins('tcMar', {
+   *   top: 100,
+   *   bottom: 100,
+   *   left: 100,
+   *   right: 100
+   * });
+   * ```
+   */
+  static createMargins(
+    type: string,
+    margins: {
+      top?: number;
+      bottom?: number;
+      left?: number;
+      right?: number;
+      start?: number;
+      end?: number;
+    }
+  ): XMLElement | null {
+    const children: XMLElement[] = [];
+
+    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;
+  }
+}