docgen-utils 1.0.12 → 1.0.13

package/dist/packages/docs/convert.js

@@ -19,7 +19,92 @@ const HEADING_SPACING = {
     h1: { before: 160, after: 240 }, // 0.67em / 1em
     h2: { before: 480, after: 240 }, // margin-top: 2rem, margin-bottom: 1rem
     h3: { before: 360, after: 240 }, // margin-top: 1.5rem
+    h4: { before: 320, after: 200 }, // margin-top: 1.33em
+    h5: { before: 320, after: 200 }, // margin-top: 1.33em
+    h6: { before: 320, after: 200 }, // margin-top: 1.33em
 };
+/** Invisible border used to suppress default DOCX borders. */
+const NIL_BORDER = { style: BorderStyle.NIL, size: 0, color: "FFFFFF" };
+/** All-sides invisible border for table cells and tables. */
+const NIL_BORDERS = { top: NIL_BORDER, bottom: NIL_BORDER, left: NIL_BORDER, right: NIL_BORDER };
+/** All-sides invisible border including inside borders for tables. */
+const NIL_TABLE_BORDERS = { ...NIL_BORDERS, insideHorizontal: NIL_BORDER, insideVertical: NIL_BORDER };
+/**
+ * Apply text-transform (uppercase, lowercase, capitalize) to a string.
+ */
+function applyTextTransform(text, transform) {
+    if (!transform)
+        return text;
+    if (transform === "uppercase")
+        return text.toUpperCase();
+    if (transform === "lowercase")
+        return text.toLowerCase();
+    if (transform === "capitalize")
+        return text.replace(/\b\w/g, c => c.toUpperCase());
+    return text;
+}
+/**
+ * Convert underline type string to DOCX UnderlineType enum.
+ */
+function getUnderlineType(type) {
+    switch (type) {
+        case "single": return UnderlineType.SINGLE;
+        case "dotted": return UnderlineType.DOTTED;
+        case "double": return UnderlineType.DOUBLE;
+        case "wave": return UnderlineType.WAVE;
+        default: return UnderlineType.SINGLE;
+    }
+}
+/**
+ * Create a chart/SVG placeholder paragraph (for charts that can't be rendered as images).
+ */
+function createChartPlaceholderParagraph(title) {
+    const text = title ? `[Chart: ${title}]` : "[Chart]";
+    return new Paragraph({
+        children: [
+            new TextRun({
+                text,
+                italics: true,
+                color: "808080",
+            }),
+        ],
+        alignment: AlignmentType.CENTER,
+        border: {
+            top: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
+            bottom: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
+            left: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
+            right: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
+        },
+        shading: {
+            type: ShadingType.CLEAR,
+            color: "auto",
+            fill: "F9FAFB",
+        },
+        spacing: {
+            before: 200,
+            after: 200,
+        },
+    });
+}
+/**
+ * Create an image caption paragraph (italic, 10pt, gray, centered).
+ */
+function createCaptionParagraph(caption) {
+    return new Paragraph({
+        children: [
+            new TextRun({
+                text: caption,
+                italics: true,
+                size: 20, // 10pt
+                color: "6B7280",
+            }),
+        ],
+        alignment: AlignmentType.CENTER,
+        spacing: {
+            after: 200,
+        },
+    });
+}
 /**
  * Concrete XmlComponent implementation for building custom XML elements.
  */
@@ -75,11 +160,11 @@ class GradientTextFill extends XmlElement {
         gradFill.addChildElement(gsLst);
         // Create lin (linear gradient) element
         // Angle is in 1/60000ths of a degree (so 135deg = 135 * 60000 = 8100000)
-        // Word uses a different angle system: 0 = right, 90 = down, etc.
-        // CSS: 0 = up, 90 = right, 180 = down, 270 = left
-        // Word: needs to be converted (Word 0 = right, going counterclockwise)
-        // Formula: wordAngle = (450 - cssAngle) % 360
-        const wordAngle = ((450 - gradient.angle) % 360) * 60000;
+        // Word w14 uses the same angle system as DrawingML:
+        //   0 = left-to-right (east), 90 = top-to-bottom (south), clockwise
+        // CSS angles: 0 = bottom-to-top (north), 90 = left-to-right (east), clockwise
+        // Conversion: DML_angle = CSS_angle - 90 (both clockwise, just different zero point)
+        const wordAngle = ((gradient.angle - 90 + 360) % 360) * 60000;
         const lin = new XmlElement("w14:lin", {
             "w14:ang": wordAngle.toString(),
             "w14:scaled": "0",
@@ -271,8 +356,9 @@ class GradientBackgroundDrawing extends XmlElement {
         gradFill.addChildElement(gsLst);
         // Linear gradient direction
         // CSS angle: 0deg = to top, 90deg = to right, 135deg = to bottom-right
-        // DrawingML: 0 = left to right, angles in 1/60000ths of a degree
-        const normalizedAngle = ((90 - gradient.angle) % 360 + 360) % 360;
+        // DrawingML: 0 = left to right (east), angles in 1/60000ths of a degree, clockwise
+        // Conversion: DML_angle = CSS_angle - 90 (both clockwise, just different zero point)
+        const normalizedAngle = ((gradient.angle - 90 + 360) % 360);
         const drawingAngle = normalizedAngle * 60000;
         gradFill.addChildElement(new XmlElement("a:lin", {
             ang: drawingAngle.toString(),
@@ -367,28 +453,6 @@ function textAlignmentToDocx(alignment) {
  */
 function inlineRunsToTextRuns(runs, textTransform) {
     const result = [];
-    // Helper to apply text transform
-    const applyTransform = (text) => {
-        if (!textTransform)
-            return text;
-        if (textTransform === "uppercase")
-            return text.toUpperCase();
-        if (textTransform === "lowercase")
-            return text.toLowerCase();
-        if (textTransform === "capitalize")
-            return text.replace(/\b\w/g, c => c.toUpperCase());
-        return text;
-    };
-    // Helper to convert underline type
-    const getUnderlineType = (type) => {
-        switch (type) {
-            case "single": return UnderlineType.SINGLE;
-            case "dotted": return UnderlineType.DOTTED;
-            case "double": return UnderlineType.DOUBLE;
-            case "wave": return UnderlineType.WAVE;
-            default: return UnderlineType.SINGLE;
-        }
-    };
     for (const run of runs) {
         // Split text by newlines to handle <br> tags
         const parts = run.text.split('\n');
@@ -398,7 +462,7 @@ function inlineRunsToTextRuns(runs, textTransform) {
             color: run.underline.color,
         } : undefined;
         for (let i = 0; i < parts.length; i++) {
-            const part = applyTransform(parts[i]);
+            const part = applyTextTransform(parts[i], textTransform);
             // Add a line break before this part (except for the first part)
             if (i > 0) {
                 result.push(new TextRun({
@@ -410,11 +474,13 @@ function inlineRunsToTextRuns(runs, textTransform) {
                     font: run.fontFamily,
                     superScript: run.superscript,
                     subScript: run.subscript,
+                    strike: run.strike,
+                    characterSpacing: run.letterSpacing,
                     underline: underlineConfig,
                     shading: run.backgroundColor ? {
-                        type: ShadingType.SOLID,
+                        type: ShadingType.CLEAR,
                         fill: run.backgroundColor,
-                        color: run.backgroundColor,
+                        color: "auto",
                     } : undefined,
                 }));
             }
@@ -442,11 +508,13 @@ function inlineRunsToTextRuns(runs, textTransform) {
                         font: run.fontFamily,
                         superScript: run.superscript,
                         subScript: run.subscript,
+                        strike: run.strike,
+                        characterSpacing: run.letterSpacing,
                         underline: underlineConfig,
                         shading: run.backgroundColor ? {
-                            type: ShadingType.SOLID,
+                            type: ShadingType.CLEAR,
                             fill: run.backgroundColor,
-                            color: run.backgroundColor,
+                            color: "auto",
                         } : undefined,
                     }));
                 }
@@ -490,35 +558,38 @@ function createTableRow(cells, isHeaderRow, columnCount, cellPadding, headerBack
                     font: run.fontFamily,
                     superScript: run.superscript,
                     subScript: run.subscript,
+                    strike: run.strike,
+                    characterSpacing: run.letterSpacing,
                     underline: run.underline ? {
                         type: getUnderlineTypeForTable(run.underline.type),
                         color: run.underline.color,
                     } : undefined,
+                    // Preserve inline background colors for badge/pill styling in table cells
+                    shading: run.backgroundColor ? {
+                        type: ShadingType.CLEAR,
+                        fill: run.backgroundColor,
+                        color: "auto",
+                    } : undefined,
                 }));
             // Determine cell shading: header row uses headerBackgroundColor, even rows use rowBackgroundColor
             let shading;
             if (isHeaderRow && headerBackgroundColor) {
                 shading = {
-                    type: ShadingType.SOLID,
-                    color: headerBackgroundColor,
+                    type: ShadingType.CLEAR,
+                    color: "auto",
                     fill: headerBackgroundColor,
                 };
             }
             else if (!isHeaderRow && rowBackgroundColor) {
                 shading = {
-                    type: ShadingType.SOLID,
-                    color: rowBackgroundColor,
+                    type: ShadingType.CLEAR,
+                    color: "auto",
                     fill: rowBackgroundColor,
                 };
             }
-            else if (isHeaderRow) {
-                // Default header shading if no custom color specified
-                shading = {
-                    type: ShadingType.SOLID,
-                    color: "F9FAFB",
-                    fill: "F9FAFB",
-                };
-            }
+            // Note: No default header shading is applied when the CSS doesn't specify one.
+            // Previously, a light gray F9FAFB was applied to all header rows, but this added
+            // unwanted shading to tables in clean/minimal designs.
             // When this row has fewer cells than the table's column count,
             // the last cell must span the remaining grid columns via columnSpan.
             // Without this, the OOXML is structurally invalid (cells don't cover
@@ -604,16 +675,7 @@ export function convertElementToDocx(element) {
             const spacingKey = `h${element.level}`;
             const headingSpacing = HEADING_SPACING[spacingKey] || { before: 240, after: 240 };
             // Apply text-transform if specified
-            let displayText = element.text;
-            if (element.textTransform === "uppercase") {
-                displayText = displayText.toUpperCase();
-            }
-            else if (element.textTransform === "lowercase") {
-                displayText = displayText.toLowerCase();
-            }
-            else if (element.textTransform === "capitalize") {
-                displayText = displayText.replace(/\b\w/g, c => c.toUpperCase());
-            }
+            const displayText = applyTextTransform(element.text, element.textTransform);
             // Use runs array if available (for headings with inline badges/badges)
             // Otherwise fallback to simple text with color
             let children;
@@ -630,9 +692,17 @@ export function convertElementToDocx(element) {
                 if (element.fontFamily) {
                     textRunOptions.font = element.fontFamily;
                 }
+                // Apply font-size from CSS (overrides document style defaults)
+                if (element.fontSize) {
+                    textRunOptions.size = element.fontSize;
+                }
+                // Apply letter-spacing from CSS
+                if (element.letterSpacing) {
+                    textRunOptions.characterSpacing = element.letterSpacing;
+                }
                 children = [new TextRun(textRunOptions)];
             }
-            // Build paragraph options with optional border-bottom
+            // Build paragraph options with optional border-bottom and border-left
             const paragraphOptions = {
                 children,
                 heading: headingLevel,
@@ -641,30 +711,42 @@ export function convertElementToDocx(element) {
                     // GENERALIZED: Use lineSpacing from CSS if available, otherwise use default
                     line: element.lineSpacing !== undefined ? element.lineSpacing : HEADING_LINE_SPACING.line,
                     lineRule: HEADING_LINE_SPACING.lineRule,
-                    before: headingSpacing.before,
+                    before: element.spacingBefore !== undefined ? element.spacingBefore : headingSpacing.before,
                     after: element.spacingAfter !== undefined ? element.spacingAfter : headingSpacing.after,
                 },
             };
             // Add border-bottom if present (heading underline style)
             if (element.borderBottom) {
                 paragraphOptions.border = {
+                    ...paragraphOptions.border,
                     bottom: { style: BorderStyle.SINGLE, size: 6, color: element.borderBottom },
                 };
             }
+            // Add border-left if present (heading left accent bar)
+            if (element.borderLeft) {
+                // Use CSS-extracted border width if available, otherwise default to 24 (3pt ≈ 4px)
+                const borderLeftSize = element.borderLeftWidth || 24;
+                paragraphOptions.border = {
+                    ...paragraphOptions.border,
+                    left: { style: BorderStyle.SINGLE, size: borderLeftSize, color: element.borderLeft, space: 8 },
+                };
+                // Add left indent to give space for the accent bar
+                paragraphOptions.indent = { left: convertInchesToTwip(0.15) };
+            }
+            // Add background color if present (heading with highlight background)
+            if (element.backgroundColor) {
+                const bgColor = element.backgroundColor.replace("#", "");
+                paragraphOptions.shading = {
+                    type: ShadingType.CLEAR,
+                    color: "auto",
+                    fill: bgColor,
+                };
+            }
             return [new Paragraph(paragraphOptions)];
         }
         case "paragraph": {
             // Apply text-transform if specified
-            let displayText = element.text;
-            if (element.textTransform === "uppercase") {
-                displayText = displayText.toUpperCase();
-            }
-            else if (element.textTransform === "lowercase") {
-                displayText = displayText.toLowerCase();
-            }
-            else if (element.textTransform === "capitalize") {
-                displayText = displayText.replace(/\b\w/g, c => c.toUpperCase());
-            }
+            const displayText = applyTextTransform(element.text, element.textTransform);
             // Use runs array if available for inline formatting, otherwise fallback to simple text
             const children = element.runs
                 ? inlineRunsToTextRuns(element.runs, element.textTransform)
@@ -686,12 +768,18 @@ export function convertElementToDocx(element) {
             if (element.hangingIndent) {
                 // Hanging indent: left margin equals the hanging amount, first line outdented
                 indent.hanging = element.hangingIndent;
-                indent.left = element.hangingIndent;
+                indent.left = element.leftIndent || element.hangingIndent;
+            }
+            else if (element.leftIndent) {
+                // Left indent without hanging (plain padding-left)
+                indent.left = element.leftIndent;
             }
             // GENERALIZED: Use element's spacingAfter if provided, otherwise default
             const afterSpacing = element.spacingAfter !== undefined ? element.spacingAfter : PARAGRAPH_SPACING.after;
             // GENERALIZED: Use element's lineSpacing if provided, otherwise default
             const lineSpacing = element.lineSpacing !== undefined ? element.lineSpacing : PARAGRAPH_SPACING.line;
+            // GENERALIZED: Use element's spacingBefore if provided
+            const beforeSpacing = element.spacingBefore !== undefined ? element.spacingBefore : undefined;
             return [
                 new Paragraph({
                     children,
@@ -701,6 +789,7 @@ export function convertElementToDocx(element) {
                         line: lineSpacing,
                         lineRule: PARAGRAPH_SPACING.lineRule,
                         after: afterSpacing,
+                        before: beforeSpacing,
                     },
                 }),
             ];
@@ -727,7 +816,9 @@ export function convertElementToDocx(element) {
             // strict parsers like Azure Document Intelligence reject.
             const maxColumnCount = Math.max(...element.rows.map(row => row.length));
             const tableRows = element.rows.map((row, rowIndex) => createTableRow(row, useHeaderStyling && rowIndex === 0, maxColumnCount, element.cellPadding, element.headerBackgroundColor, element.headerTextColor, 
-            // Apply even row background color for alternating row styling (rowIndex > 0 and odd = even rows in 0-indexed)
+            // Apply even row background color for alternating row styling
+            // Header is at rowIndex 0, so body rows start at rowIndex 1.
+            // CSS nth-child(even) targets the 2nd,4th,6th body rows = rowIndex 2,4,6 (even indices)
             rowIndex > 0 && rowIndex % 2 === 0 ? element.evenRowBackgroundColor : undefined));
             // Default table border color (light gray), or no borders
             const borderColor = "E5E7EB";
@@ -735,6 +826,9 @@ export function convertElementToDocx(element) {
             const borderStyle = element.noBorders
                 ? noBorderStyle
                 : { style: BorderStyle.SINGLE, size: 4, color: borderColor };
+            // Support horizontal-only borders (no vertical grid lines)
+            const verticalBorderStyle = element.horizontalBordersOnly ? noBorderStyle : borderStyle;
+            const sideBorderStyle = element.horizontalBordersOnly ? noBorderStyle : borderStyle;
             const dataTable = new Table({
                 rows: tableRows,
                 width: {
@@ -744,10 +838,10 @@ export function convertElementToDocx(element) {
                 borders: {
                     top: borderStyle,
                     bottom: borderStyle,
-                    left: borderStyle,
-                    right: borderStyle,
+                    left: sideBorderStyle,
+                    right: sideBorderStyle,
                     insideHorizontal: borderStyle,
-                    insideVertical: borderStyle,
+                    insideVertical: verticalBorderStyle,
                 },
             });
             // Add spacing paragraphs before and after the table to ensure proper separation
@@ -779,6 +873,8 @@ export function convertElementToDocx(element) {
                         right: { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" },
                     },
                     shading: {
+                        type: ShadingType.CLEAR,
+                        color: "auto",
                         fill: "F5F5F5",
                     },
                 }),
@@ -794,9 +890,13 @@ export function convertElementToDocx(element) {
             const isCallout = element.variant === "callout";
             const hasFullBorder = element.borderStyle === "full";
             const hasNoBorder = element.borderStyle === "none";
-            // Callout label uses darker blue color (#1d4ed8)
-            const labelColor = isCallout ? "1D4ED8" : borderColor;
-            // Convert all inner content to paragraphs for the cell
+            // Callout label uses the border color to match the accent style
+            // Previously hardcoded to blue (#1d4ed8), now uses the actual border color
+            // so labels match their callout's theme (brown for objectives, blue for examples, etc.)
+            // For borderless callouts (style="none"), don't use the gray fallback — let the
+            // heading/paragraph use its own color or the document default.
+            const labelColor = hasNoBorder ? undefined : borderColor;
+            // Convert all inner content to paragraphs (and tables for nested blockquotes) for the cell
             const cellContent = [];
             for (const innerElement of element.content) {
                 if (innerElement.type === "paragraph") {
@@ -812,14 +912,19 @@ export function convertElementToDocx(element) {
                                 bold: innerElement.bold,
                                 italics: innerElement.italic,
                                 color: paragraphColor,
+                                font: innerElement.fontFamily,
                             }),
                         ];
                     cellContent.push(new Paragraph({
                         children: textChildren,
+                        alignment: innerElement.alignment ? textAlignmentToDocx(innerElement.alignment) : undefined,
                         spacing: {
-                            line: PARAGRAPH_SPACING.line,
+                            // Use paragraph's CSS line-height if available, otherwise default
+                            line: innerElement.lineSpacing !== undefined ? innerElement.lineSpacing : PARAGRAPH_SPACING.line,
                             lineRule: PARAGRAPH_SPACING.lineRule,
-                            after: 120,
+                            // Use paragraph's CSS margin-bottom if available, otherwise compact spacing for boxes
+                            after: innerElement.spacingAfter !== undefined ? innerElement.spacingAfter : 120,
+                            before: innerElement.spacingBefore,
                         }, // Space between elements inside the box
                     }));
                 }
@@ -869,8 +974,10 @@ export function convertElementToDocx(element) {
                 else if (innerElement.type === "heading") {
                     // Handle headings inside blockquotes
                     // Use the heading's own color if available (from CSS like .key-takeaways h3 { color: ... })
-                    // Otherwise fall back to the blockquote's border color
-                    const headingColor = innerElement.color || borderColor;
+                    // Only fall back to blockquote's border color when the blockquote has a visible border
+                    // (left accent or full border). For borderless callouts (style="none"), the heading
+                    // should use its own color or default — not the gray fallback "CCCCCC".
+                    const headingColor = innerElement.color || (hasNoBorder ? undefined : borderColor);
                     const textChildren = innerElement.runs
                         ? inlineRunsToTextRuns(innerElement.runs)
                         : [
@@ -924,6 +1031,43 @@ export function convertElementToDocx(element) {
                     // For regular tables inside blockquotes, we could add full table rendering,
                     // but for now we skip them as nested tables in Word can be problematic
                 }
+                else if (innerElement.type === "image") {
+                    // Render images inside blockquote/callout cells
+                    if (innerElement.imageData) {
+                        // Scale image to fit within the blockquote cell width (approx 580px after padding)
+                        const maxCellWidth = 580;
+                        let imgWidth = innerElement.imageData.width;
+                        let imgHeight = innerElement.imageData.height;
+                        if (imgWidth > maxCellWidth) {
+                            const scale = maxCellWidth / imgWidth;
+                            imgWidth = maxCellWidth;
+                            imgHeight = Math.round(imgHeight * scale);
+                        }
+                        cellContent.push(new Paragraph({
+                            children: [
+                                new ImageRun({
+                                    data: innerElement.imageData.data,
+                                    transformation: {
+                                        width: imgWidth,
+                                        height: imgHeight,
+                                    },
+                                    type: "png",
+                                }),
+                            ],
+                            alignment: AlignmentType.CENTER,
+                            spacing: {
+                                before: 120,
+                                after: 120,
+                            },
+                        }));
+                    }
+                }
+                else if (innerElement.type === "blockquote") {
+                    // Handle nested blockquotes/callouts (e.g., .famous-for inside .country-section)
+                    // Render the nested blockquote as its own table-based box within the parent cell
+                    const nestedDocx = convertElementToDocx(innerElement);
+                    cellContent.push(...nestedDocx);
+                }
             }
             // Create table to act as the box
             // For gradient backgrounds, the DrawingML shape is already inserted in the first paragraph
@@ -943,6 +1087,7 @@ export function convertElementToDocx(element) {
             let effectiveBackgroundColor = backgroundColor;
             if (backgroundGradient && hasNoBorder) {
                 // Use the color at ~40% position (second stop in typical gradients)
+                // This provides a mid-tone that better approximates the gradient's overall appearance
                 const sortedStops = [...backgroundGradient.stops].sort((a, b) => a.position - b.position);
                 if (sortedStops.length >= 2) {
                     effectiveBackgroundColor = sortedStops[1]?.color || sortedStops[0]?.color || backgroundColor;
@@ -952,8 +1097,8 @@ export function convertElementToDocx(element) {
                 }
             }
             const cellShading = {
-                type: ShadingType.SOLID,
-                color: effectiveBackgroundColor,
+                type: ShadingType.CLEAR,
+                color: "auto",
                 fill: effectiveBackgroundColor,
             };
             tableRows.push(new TableRow({
@@ -962,18 +1107,15 @@ export function convertElementToDocx(element) {
                         children: finalCellContent,
                         shading: cellShading,
                         margins: {
-                            top: convertInchesToTwip(0.25), // ~18pt padding top
-                            bottom: convertInchesToTwip(0.25), // ~18pt padding bottom
-                            left: convertInchesToTwip(0.35), // ~25pt padding left (after border)
-                            right: convertInchesToTwip(0.35), // ~25pt padding right
+                            top: element.padding?.top ?? convertInchesToTwip(0.25), // ~18pt padding top
+                            bottom: element.padding?.bottom ?? convertInchesToTwip(0.25), // ~18pt padding bottom
+                            left: element.padding?.left ?? convertInchesToTwip(0.35), // ~25pt padding left (after border)
+                            right: element.padding?.right ?? convertInchesToTwip(0.35), // ~25pt padding right
                         },
                         borders: hasNoBorder
                             ? {
                                 // No border - just background color (for title blocks, hero sections)
-                                top: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                                bottom: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                                left: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                                right: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
+                                ...NIL_BORDERS,
                             }
                             : hasFullBorder
                                 ? {
@@ -985,10 +1127,8 @@ export function convertElementToDocx(element) {
                                 }
                                 : {
                                     // Left accent border only (callout style)
-                                    top: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                                    bottom: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
+                                    ...NIL_BORDERS,
                                     left: { style: BorderStyle.SINGLE, size: 24, color: borderColor }, // Thick left border
-                                    right: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
                                 },
                     }),
                 ],
@@ -1000,14 +1140,7 @@ export function convertElementToDocx(element) {
                     type: WidthType.PERCENTAGE,
                 },
                 // Remove outer table borders - we only want the cell's left border
-                borders: {
-                    top: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    bottom: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    left: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    right: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    insideHorizontal: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    insideVertical: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                },
+                borders: NIL_TABLE_BORDERS,
             });
             // Add spacing paragraphs before and after the table to ensure proper separation
             // from surrounding content (especially other tables)
@@ -1021,68 +1154,10 @@ export function convertElementToDocx(element) {
             });
             return [spacingBefore, boxTable, spacingAfter];
         }
-        case "chart-placeholder": {
-            // Render a placeholder for charts that can't be converted
-            const text = element.title ? `[Chart: ${element.title}]` : "[Chart]";
-            return [
-                new Paragraph({
-                    children: [
-                        new TextRun({
-                            text,
-                            italics: true,
-                            color: "808080",
-                        }),
-                    ],
-                    alignment: AlignmentType.CENTER,
-                    border: {
-                        top: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
-                        bottom: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
-                        left: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
-                        right: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
-                    },
-                    shading: {
-                        type: ShadingType.SOLID,
-                        color: "F9FAFB",
-                        fill: "F9FAFB",
-                    },
-                    spacing: {
-                        before: 200,
-                        after: 200,
-                    },
-                }),
-            ];
-        }
+        case "chart-placeholder":
         case "svg-chart": {
-            // SVG charts need to be converted to images before reaching here
-            // Fall back to placeholder if not converted
-            const text = element.title ? `[Chart: ${element.title}]` : "[Chart]";
-            return [
-                new Paragraph({
-                    children: [
-                        new TextRun({
-                            text,
-                            italics: true,
-                            color: "808080",
-                        }),
-                    ],
-                    alignment: AlignmentType.CENTER,
-                    border: {
-                        top: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
-                        bottom: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
-                        left: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
-                        right: { style: BorderStyle.SINGLE, size: 1, color: "E5E7EB" },
-                    },
-                    shading: {
-                        type: ShadingType.SOLID,
-                        color: "F9FAFB",
-                        fill: "F9FAFB",
-                    },
-                    spacing: {
-                        before: 200,
-                        after: 200,
-                    },
-                }),
-            ];
+            // Render a placeholder for charts that can't be converted (or SVGs not yet rendered)
+            return [createChartPlaceholderParagraph(element.title)];
         }
         case "chart-image": {
             // Render chart as an embedded image
@@ -1129,24 +1204,7 @@ export function convertElementToDocx(element) {
                             after: caption ? 80 : 200,
                         },
                     }),
-                    ...(caption
-                        ? [
-                            new Paragraph({
-                                children: [
-                                    new TextRun({
-                                        text: caption,
-                                        italics: true,
-                                        size: 20, // 10pt
-                                        color: "6B7280",
-                                    }),
-                                ],
-                                alignment: AlignmentType.CENTER,
-                                spacing: {
-                                    after: 200,
-                                },
-                            }),
-                        ]
-                        : []),
+                    ...(caption ? [createCaptionParagraph(caption)] : []),
                 ];
             }
             // Render the actual image
@@ -1171,20 +1229,7 @@ export function convertElementToDocx(element) {
             ];
             // Add caption if present
             if (caption) {
-                paragraphs.push(new Paragraph({
-                    children: [
-                        new TextRun({
-                            text: caption,
-                            italics: true,
-                            size: 20, // 10pt
-                            color: "6B7280",
-                        }),
-                    ],
-                    alignment: AlignmentType.CENTER,
-                    spacing: {
-                        after: 200,
-                    },
-                }));
+                paragraphs.push(createCaptionParagraph(caption));
             }
             return paragraphs;
         }
@@ -1271,8 +1316,8 @@ export function convertElementToDocx(element) {
                         right: convertInchesToTwip(0.1),
                     },
                     shading: card.backgroundColor ? {
-                        type: ShadingType.SOLID,
-                        color: card.backgroundColor,
+                        type: ShadingType.CLEAR,
+                        color: "auto",
                         fill: card.backgroundColor,
                     } : undefined,
                     borders: card.borderColor ? {
@@ -1349,8 +1394,8 @@ export function convertElementToDocx(element) {
                     type: WidthType.PERCENTAGE,
                 },
                 shading: sidebar.backgroundColor ? {
-                    type: ShadingType.SOLID,
-                    color: sidebar.backgroundColor,
+                    type: ShadingType.CLEAR,
+                    color: "auto",
                     fill: sidebar.backgroundColor,
                 } : undefined,
                 margins: {
@@ -1359,12 +1404,7 @@ export function convertElementToDocx(element) {
                     left: convertInchesToTwip(0.2),
                     right: convertInchesToTwip(0.2),
                 },
-                borders: {
-                    top: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    bottom: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    left: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    right: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                },
+                borders: NIL_BORDERS,
             });
             // Create main content cell
             const mainCell = new DocxTableCell({
@@ -1379,12 +1419,7 @@ export function convertElementToDocx(element) {
                     left: convertInchesToTwip(0.3),
                     right: convertInchesToTwip(0.2),
                 },
-                borders: {
-                    top: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    bottom: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    left: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    right: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                },
+                borders: NIL_BORDERS,
             });
             // Create the two-column table
             const twoColumnTable = new Table({
@@ -1397,14 +1432,7 @@ export function convertElementToDocx(element) {
                     size: 100,
                     type: WidthType.PERCENTAGE,
                 },
-                borders: {
-                    top: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    bottom: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    left: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    right: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    insideHorizontal: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                    insideVertical: { style: BorderStyle.NIL, size: 0, color: "FFFFFF" },
-                },
+                borders: NIL_TABLE_BORDERS,
             });
             return [twoColumnTable];
         }