@nguyenphp/antigravity-marketing 1.0.18 → 1.0.20

package/templates/.agent/skills/minimax-docx/scripts/dotnet/MiniMaxAIDocx.Core/Samples/DocumentCreationSamples.cs

@@ -0,0 +1,1121 @@
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.CustomProperties;
+using DocumentFormat.OpenXml.ExtendedProperties;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.VariantTypes;
+using DocumentFormat.OpenXml.Wordprocessing;
+using MiniMaxAIDocx.Core.OpenXml;
+using MiniMaxAIDocx.Core.Typography;
+using WpPageSize = DocumentFormat.OpenXml.Wordprocessing.PageSize;
+
+namespace MiniMaxAIDocx.Core.Samples;
+
+/// <summary>
+/// Compilable reference examples for DOCX document creation and setup.
+/// Every method is self-contained and demonstrates a specific aspect of
+/// document creation using the OpenXML SDK 3.x strongly-typed API.
+/// </summary>
+public static class DocumentCreationSamples
+{
+    // ────────────────────────────────────────────────────────────────────
+    // 1. MINIMAL DOCUMENT
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Creates the absolute minimum valid DOCX file: a single empty paragraph
+    /// inside a body, with a final section properties element.
+    /// This is the smallest file Word/LibreOffice will open without error.
+    /// </summary>
+    /// <remarks>
+    /// Produces this XML in word/document.xml:
+    /// <code>
+    /// &lt;w:document&gt;
+    ///   &lt;w:body&gt;
+    ///     &lt;w:p/&gt;
+    ///     &lt;w:sectPr&gt;
+    ///       &lt;w:pgSz w:w="12240" w:h="15840"/&gt;
+    ///       &lt;w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"
+    ///                w:header="720" w:footer="720" w:gutter="0"/&gt;
+    ///     &lt;/w:sectPr&gt;
+    ///   &lt;/w:body&gt;
+    /// &lt;/w:document&gt;
+    /// </code>
+    /// </remarks>
+    public static void CreateMinimalDocument(string path)
+    {
+        // IMPORTANT: OpenXML SDK 3.x uses IDisposable — always wrap in using.
+        // Never call .Close() — it was removed in SDK 3.x.
+        using var doc = WordprocessingDocument.Create(path, WordprocessingDocumentType.Document);
+
+        // Every DOCX needs exactly one MainDocumentPart
+        var mainPart = doc.AddMainDocumentPart();
+
+        // The Document element is the root of word/document.xml
+        mainPart.Document = new Document(
+            new Body(
+                // At least one paragraph is required for a valid document
+                new Paragraph(),
+                // SectionProperties must be the LAST child of Body
+                // WARNING: If sectPr is not last, Word may silently move it or corrupt the file
+                new SectionProperties(
+                    // PageSize: Letter = 8.5" x 11" = 12240 x 15840 DXA (1 inch = 1440 DXA)
+                    new WpPageSize
+                    {
+                        Width = (UInt32Value)12240U,
+                        Height = (UInt32Value)15840U
+                    },
+                    // PageMargin: 1 inch all sides = 1440 DXA each
+                    // Header/footer distance: 0.5 inch = 720 DXA
+                    new PageMargin
+                    {
+                        Top = 1440,
+                        Right = (UInt32Value)1440U,
+                        Bottom = 1440,
+                        Left = (UInt32Value)1440U,
+                        Header = (UInt32Value)720U,
+                        Footer = (UInt32Value)720U,
+                        Gutter = (UInt32Value)0U
+                    }
+                )
+            )
+        );
+
+        // Save is called automatically by Dispose, but explicit save ensures
+        // all parts are flushed before the stream closes
+        mainPart.Document.Save();
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // 2. FULL DOCUMENT (all parts)
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Creates a production-ready DOCX with all standard parts:
+    /// styles, settings, numbering definitions, font table, and theme.
+    /// This mirrors the structure Word generates for a "New Blank Document".
+    /// </summary>
+    public static void CreateFullDocument(string path)
+    {
+        using var doc = WordprocessingDocument.Create(path, WordprocessingDocumentType.Document);
+        var mainPart = doc.AddMainDocumentPart();
+
+        // ── StyleDefinitionsPart ──
+        // Contains all named styles (Normal, Heading1, etc.)
+        var stylesPart = mainPart.AddNewPart<StyleDefinitionsPart>();
+        stylesPart.Styles = new Styles();
+        // Populate styles using the StyleSystemSamples helper
+        StyleSystemSamples.SetupDocDefaults(stylesPart);
+        StyleSystemSamples.CreateBasicStyles(stylesPart);
+        stylesPart.Styles.Save();
+
+        // ── DocumentSettingsPart ──
+        // Contains zoom, compatibility, proofing state, etc.
+        var settingsPart = mainPart.AddNewPart<DocumentSettingsPart>();
+        settingsPart.Settings = new Settings();
+        AddDocumentSettings(mainPart);
+        settingsPart.Settings.Save();
+
+        // ── NumberingDefinitionsPart ──
+        // Required if any paragraph uses numbered/bulleted lists
+        var numberingPart = mainPart.AddNewPart<NumberingDefinitionsPart>();
+        numberingPart.Numbering = new Numbering();
+        // Add a basic bullet list abstract numbering definition
+        var abstractNum = new AbstractNum(
+            new Level(
+                new NumberingFormat { Val = NumberFormatValues.Bullet },
+                new LevelText { Val = "\u2022" }, // bullet character
+                new LevelJustification { Val = LevelJustificationValues.Left },
+                new ParagraphProperties(
+                    new Indentation
+                    {
+                        Left = "720",   // 0.5 inch = 720 DXA
+                        Hanging = "360" // 0.25 inch hanging indent
+                    }
+                )
+            )
+            { LevelIndex = 0 }
+        )
+        { AbstractNumberId = 1 };
+
+        // IMPORTANT: AbstractNum elements must come BEFORE NumberingInstance elements
+        // in the Numbering part, or Word will report corruption
+        numberingPart.Numbering.Append(abstractNum);
+        numberingPart.Numbering.Append(
+            new NumberingInstance(
+                new AbstractNumId { Val = 1 }
+            )
+            { NumberID = 1 }
+        );
+        numberingPart.Numbering.Save();
+
+        // ── FontTablePart ──
+        // Declares fonts used in the document; Word auto-populates on save,
+        // but pre-creating it avoids a repair prompt
+        var fontTablePart = mainPart.AddNewPart<FontTablePart>();
+        fontTablePart.Fonts = new Fonts(
+            new Font(
+                new Panose1Number { Val = "020B0604020202020204" },
+                new FontCharSet { Val = "00" },
+                new FontFamily { Val = FontFamilyValues.Swiss }
+            )
+            { Name = "Calibri" },
+            new Font(
+                new Panose1Number { Val = "020B0604020202020204" },
+                new FontCharSet { Val = "00" },
+                new FontFamily { Val = FontFamilyValues.Swiss }
+            )
+            { Name = "Calibri Light" }
+        );
+        fontTablePart.Fonts.Save();
+
+        // ── ThemePart ──
+        // Defines the document's theme colors and fonts.
+        // IMPORTANT: We use a minimal theme; for full Office themes, copy from a .docx template
+        var themePart = mainPart.AddNewPart<ThemePart>();
+        // Write minimal theme XML directly since the strongly-typed API for themes
+        // lives in DocumentFormat.OpenXml.Drawing and is very verbose
+        using (var writer = new System.IO.StreamWriter(themePart.GetStream()))
+        {
+            writer.Write("""
+                <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+                <a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Office Theme">
+                  <a:themeElements>
+                    <a:clrScheme name="Office">
+                      <a:dk1><a:sysClr val="windowText" lastClr="000000"/></a:dk1>
+                      <a:lt1><a:sysClr val="window" lastClr="FFFFFF"/></a:lt1>
+                      <a:dk2><a:srgbClr val="44546A"/></a:dk2>
+                      <a:lt2><a:srgbClr val="E7E6E6"/></a:lt2>
+                      <a:accent1><a:srgbClr val="4472C4"/></a:accent1>
+                      <a:accent2><a:srgbClr val="ED7D31"/></a:accent2>
+                      <a:accent3><a:srgbClr val="A5A5A5"/></a:accent3>
+                      <a:accent4><a:srgbClr val="FFC000"/></a:accent4>
+                      <a:accent5><a:srgbClr val="5B9BD5"/></a:accent5>
+                      <a:accent6><a:srgbClr val="70AD47"/></a:accent6>
+                      <a:hlink><a:srgbClr val="0563C1"/></a:hlink>
+                      <a:folHlink><a:srgbClr val="954F72"/></a:folHlink>
+                    </a:clrScheme>
+                    <a:fontScheme name="Office">
+                      <a:majorFont><a:latin typeface="Calibri Light"/><a:ea typeface=""/><a:cs typeface=""/></a:majorFont>
+                      <a:minorFont><a:latin typeface="Calibri"/><a:ea typeface=""/><a:cs typeface=""/></a:minorFont>
+                    </a:fontScheme>
+                    <a:fmtScheme name="Office">
+                      <a:fillStyleLst>
+                        <a:solidFill><a:schemeClr val="phClr"/></a:solidFill>
+                        <a:solidFill><a:schemeClr val="phClr"/></a:solidFill>
+                        <a:solidFill><a:schemeClr val="phClr"/></a:solidFill>
+                      </a:fillStyleLst>
+                      <a:lnStyleLst>
+                        <a:ln w="6350"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill></a:ln>
+                        <a:ln w="6350"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill></a:ln>
+                        <a:ln w="6350"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill></a:ln>
+                      </a:lnStyleLst>
+                      <a:effectStyleLst>
+                        <a:effectStyle><a:effectLst/></a:effectStyle>
+                        <a:effectStyle><a:effectLst/></a:effectStyle>
+                        <a:effectStyle><a:effectLst/></a:effectStyle>
+                      </a:effectStyleLst>
+                      <a:bgFillStyleLst>
+                        <a:solidFill><a:schemeClr val="phClr"/></a:solidFill>
+                        <a:solidFill><a:schemeClr val="phClr"/></a:solidFill>
+                        <a:solidFill><a:schemeClr val="phClr"/></a:solidFill>
+                      </a:bgFillStyleLst>
+                    </a:fmtScheme>
+                  </a:themeElements>
+                </a:theme>
+                """);
+        }
+
+        // ── Document body ──
+        mainPart.Document = new Document(
+            new Body(
+                new Paragraph(
+                    new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+                    new Run(new Text("Sample Document"))
+                ),
+                new Paragraph(
+                    new Run(new Text("This document includes all standard parts."))
+                ),
+                // Final section properties
+                new SectionProperties(
+                    new WpPageSize
+                    {
+                        Width = (UInt32Value)(uint)PageSizes.A4.WidthDxa,
+                        Height = (UInt32Value)(uint)PageSizes.A4.HeightDxa
+                    },
+                    new PageMargin
+                    {
+                        Top = PageSizes.StandardMargins.TopDxa,
+                        Right = (UInt32Value)(uint)PageSizes.StandardMargins.RightDxa,
+                        Bottom = PageSizes.StandardMargins.BottomDxa,
+                        Left = (UInt32Value)(uint)PageSizes.StandardMargins.LeftDxa,
+                        Header = (UInt32Value)720U,
+                        Footer = (UInt32Value)720U,
+                        Gutter = (UInt32Value)0U
+                    }
+                )
+            )
+        );
+
+        // Set document-level metadata
+        SetDocumentProperties(doc);
+
+        mainPart.Document.Save();
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // 3. CREATE FROM STREAM (for web/API)
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Creates a DOCX entirely in memory, returning a MemoryStream.
+    /// Ideal for ASP.NET / Web API scenarios where you return FileStreamResult.
+    /// </summary>
+    /// <remarks>
+    /// Usage in ASP.NET:
+    /// <code>
+    /// var stream = DocumentCreationSamples.CreateFromStream();
+    /// return File(stream, "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "report.docx");
+    /// </code>
+    /// </remarks>
+    public static MemoryStream CreateFromStream()
+    {
+        // IMPORTANT: The MemoryStream must remain open after WordprocessingDocument is disposed.
+        // Do NOT wrap the stream in a using statement here — the caller owns its lifetime.
+        var stream = new MemoryStream();
+
+        // WARNING: You MUST pass 'true' for the 'leaveOpen' parameter (via the overload that
+        // accepts a stream) so that disposing the WordprocessingDocument does NOT close the stream.
+        // The Create overload with Stream does this correctly in SDK 3.x.
+        using (var doc = WordprocessingDocument.Create(stream, WordprocessingDocumentType.Document))
+        {
+            var mainPart = doc.AddMainDocumentPart();
+            mainPart.Document = new Document(
+                new Body(
+                    new Paragraph(
+                        new Run(new Text("Generated in memory"))
+                    ),
+                    new SectionProperties(
+                        new WpPageSize
+                        {
+                            Width = (UInt32Value)(uint)PageSizes.Letter.WidthDxa,
+                            Height = (UInt32Value)(uint)PageSizes.Letter.HeightDxa
+                        },
+                        new PageMargin
+                        {
+                            Top = 1440,
+                            Right = (UInt32Value)1440U,
+                            Bottom = 1440,
+                            Left = (UInt32Value)1440U,
+                            Header = (UInt32Value)720U,
+                            Footer = (UInt32Value)720U,
+                            Gutter = (UInt32Value)0U
+                        }
+                    )
+                )
+            );
+            mainPart.Document.Save();
+        }
+        // Disposing the WordprocessingDocument flushes all data to the stream.
+
+        // IMPORTANT: Reset position so the caller can read from the beginning.
+        stream.Position = 0;
+        return stream;
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // 4. OPEN AND EDIT EXISTING DOCUMENT
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Opens an existing DOCX, modifies its content, and saves.
+    /// Demonstrates the read-modify-write pattern.
+    /// </summary>
+    public static void OpenAndEdit(string path)
+    {
+        // Open for editing (isEditable = true)
+        // WARNING: If the file is read-only on disk, this will throw IOException.
+        // For read-only access, pass false and use a copy-to-stream pattern instead.
+        using var doc = WordprocessingDocument.Open(path, isEditable: true);
+
+        var body = doc.MainDocumentPart?.Document.Body;
+        if (body is null)
+            return;
+
+        // Add a new paragraph at the end, BEFORE the final SectionProperties
+        // WARNING: Always insert before sectPr — it must remain the last child of Body
+        var sectPr = body.Elements<SectionProperties>().FirstOrDefault();
+
+        var newParagraph = new Paragraph(
+            new ParagraphProperties(
+                // Apply Normal style explicitly (usually inherited, but being explicit is safer)
+                new ParagraphStyleId { Val = "Normal" },
+                new Justification { Val = JustificationValues.Left }
+            ),
+            new Run(
+                new RunProperties(
+                    new Bold(),
+                    new Color { Val = "FF0000" } // red, RGB hex without #
+                ),
+                // IMPORTANT: When text has leading/trailing whitespace, you must set
+                // SpaceProcessingModeValues.Preserve or Word will strip it
+                new Text("This paragraph was added programmatically.") { Space = SpaceProcessingModeValues.Preserve }
+            )
+        );
+
+        if (sectPr is not null)
+        {
+            // Insert before the final section properties
+            body.InsertBefore(newParagraph, sectPr);
+        }
+        else
+        {
+            // No sectPr found (unusual but possible); just append
+            body.Append(newParagraph);
+        }
+
+        // Modify an existing paragraph — change the text of the first paragraph
+        var firstPara = body.Elements<Paragraph>().FirstOrDefault();
+        if (firstPara is not null)
+        {
+            var firstRun = firstPara.Elements<Run>().FirstOrDefault();
+            if (firstRun is not null)
+            {
+                var textElement = firstRun.Elements<Text>().FirstOrDefault();
+                if (textElement is not null)
+                {
+                    textElement.Text = "Modified: " + textElement.Text;
+                }
+            }
+        }
+
+        // Save is called automatically on Dispose, but calling explicitly
+        // ensures errors surface at a known point
+        doc.MainDocumentPart!.Document.Save();
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // 5. DOCUMENT DEFAULTS (DocDefaults)
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Sets RunPropertiesDefault and ParagraphPropertiesDefault in the styles part.
+    /// These defaults apply to ALL paragraphs and runs unless overridden by a style or direct formatting.
+    /// </summary>
+    /// <remarks>
+    /// Produces in styles.xml:
+    /// <code>
+    /// &lt;w:docDefaults&gt;
+    ///   &lt;w:rPrDefault&gt;
+    ///     &lt;w:rPr&gt;
+    ///       &lt;w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:eastAsia="SimSun" w:cs="Arial"/&gt;
+    ///       &lt;w:sz w:val="22"/&gt;
+    ///       &lt;w:szCs w:val="22"/&gt;
+    ///       &lt;w:lang w:val="en-US" w:eastAsia="zh-CN" w:bidi="ar-SA"/&gt;
+    ///     &lt;/w:rPr&gt;
+    ///   &lt;/w:rPrDefault&gt;
+    ///   &lt;w:pPrDefault&gt;
+    ///     &lt;w:pPr&gt;
+    ///       &lt;w:spacing w:after="160" w:line="259" w:lineRule="auto"/&gt;
+    ///     &lt;/w:pPr&gt;
+    ///   &lt;/w:pPrDefault&gt;
+    /// &lt;/w:docDefaults&gt;
+    /// </code>
+    /// </remarks>
+    public static void SetDocDefaults(MainDocumentPart mainPart)
+    {
+        // Ensure StyleDefinitionsPart exists
+        var stylesPart = mainPart.StyleDefinitionsPart
+            ?? mainPart.AddNewPart<StyleDefinitionsPart>();
+        stylesPart.Styles ??= new Styles();
+
+        var docDefaults = new DocDefaults();
+
+        // ── Run Properties Default ──
+        // These become the "base" formatting for all text in the document
+        var runPropsDefault = new RunPropertiesDefault(
+            new RunPropertiesBaseStyle(
+                // RunFonts has 4 slots for different Unicode ranges:
+                //   Ascii    — Latin characters (U+0000–U+007F)
+                //   HighAnsi — extended Latin (U+0080–U+FFFF, non-EastAsian)
+                //   EastAsia — CJK characters
+                //   ComplexScript — RTL scripts (Arabic, Hebrew, etc.)
+                new RunFonts
+                {
+                    Ascii = "Calibri",
+                    HighAnsi = "Calibri",
+                    EastAsia = "SimSun",        // 宋体 — standard CJK body font
+                    ComplexScript = "Arial"
+                },
+                // Font size is in HALF-POINTS: 22 half-pt = 11pt
+                new FontSize { Val = "22" },
+                // Complex script size (for Arabic/Hebrew text)
+                new FontSizeComplexScript { Val = "22" },
+                // Language tags control spell-check and hyphenation
+                new Languages
+                {
+                    Val = "en-US",
+                    EastAsia = "zh-CN",
+                    Bidi = "ar-SA"
+                }
+            )
+        );
+
+        // ── Paragraph Properties Default ──
+        // Spacing that applies to all paragraphs unless overridden
+        var paraPropsDefault = new ParagraphPropertiesDefault(
+            new ParagraphPropertiesBaseStyle(
+                new SpacingBetweenLines
+                {
+                    // After = space after paragraph in DXA twentieths-of-a-point
+                    // 160 DXA = 8pt after each paragraph (Word 2016+ default)
+                    After = "160",
+                    // Line = line spacing:
+                    //   For "auto" rule: value is in 240ths of a line
+                    //   259 = 1.0791... ≈ 1.08 line spacing (Word's "single" with body text font)
+                    //   For "exact"/"atLeast": value is in DXA twentieths-of-a-point
+                    Line = "259",
+                    LineRule = LineSpacingRuleValues.Auto
+                }
+            )
+        );
+
+        docDefaults.Append(runPropsDefault);
+        docDefaults.Append(paraPropsDefault);
+
+        // IMPORTANT: DocDefaults must be the FIRST child of w:styles.
+        // If there are existing children, prepend it.
+        var existingDocDefaults = stylesPart.Styles.DocDefaults;
+        if (existingDocDefaults is not null)
+        {
+            existingDocDefaults.Remove();
+        }
+        stylesPart.Styles.PrependChild(docDefaults);
+        stylesPart.Styles.Save();
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // 6. DOCUMENT SETTINGS
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Adds document-level settings: zoom, default tab stop, proofing,
+    /// compatibility options, field update behavior, and character spacing control.
+    /// </summary>
+    /// <remarks>
+    /// Produces in word/settings.xml:
+    /// <code>
+    /// &lt;w:settings&gt;
+    ///   &lt;w:zoom w:percent="100"/&gt;
+    ///   &lt;w:defaultTabStop w:val="720"/&gt;
+    ///   &lt;w:characterSpacingControl w:val="doNotCompress"/&gt;
+    ///   &lt;w:proofState w:spelling="clean" w:grammar="clean"/&gt;
+    ///   &lt;w:updateFields w:val="true"/&gt;
+    ///   &lt;w:compat&gt;
+    ///     &lt;w:compatSetting w:name="compatibilityMode" w:uri="..." w:val="15"/&gt;
+    ///   &lt;/w:compat&gt;
+    /// &lt;/w:settings&gt;
+    /// </code>
+    /// </remarks>
+    public static void AddDocumentSettings(MainDocumentPart mainPart)
+    {
+        var settingsPart = mainPart.DocumentSettingsPart
+            ?? mainPart.AddNewPart<DocumentSettingsPart>();
+        settingsPart.Settings ??= new Settings();
+        var settings = settingsPart.Settings;
+
+        // ── Zoom level ──
+        // 100 = 100%. Word remembers this for the next open.
+        settings.Append(new Zoom { Percent = "100" });
+
+        // ── Default tab stop ──
+        // 720 DXA = 0.5 inch. This is the interval for default tab stops
+        // across the entire document. Common values:
+        //   720 = 0.5 inch (US default)
+        //   420 = ~0.74cm (common in Chinese docs)
+        settings.Append(new DefaultTabStop { Val = 720 });
+
+        // ── Character spacing control ──
+        // Controls how CJK character spacing is handled
+        //   DoNotCompress — no compression of punctuation
+        //   CompressPunctuation — compress CJK punctuation at line start/end
+        //   CompressPunctuationAndJapaneseKanaWhitespace — full CJK compression
+        settings.Append(new CharacterSpacingControl
+        {
+            Val = CharacterSpacingValues.DoNotCompress
+        });
+
+        // ── Proofing state ──
+        // Tells Word that spell/grammar check is clean; avoids the squiggly-line
+        // check running immediately on open
+        settings.Append(new ProofState
+        {
+            Spelling = ProofingStateValues.Clean,
+            Grammar = ProofingStateValues.Clean
+        });
+
+        // ── Update fields on open ──
+        // WARNING: Setting this to true causes Word to prompt "This document contains
+        // fields that may refer to other files. Do you want to update the fields?"
+        // Useful for TOC/TOF fields that need refreshing
+        settings.Append(new UpdateFieldsOnOpen { Val = true });
+
+        // ── Compatibility settings ──
+        // compatibilityMode = 15 means "Word 2013+ mode" — the highest stable mode.
+        // This controls layout behavior: line breaking, table widths, spacing, etc.
+        // WARNING: Using a lower value (e.g., 11 for Word 2003) changes layout
+        // significantly and is almost never what you want.
+        var compat = new Compatibility();
+        compat.Append(new CompatibilitySetting
+        {
+            Name = CompatSettingNameValues.CompatibilityMode,
+            Uri = "http://schemas.microsoft.com/office/word",
+            Val = "15"
+        });
+        // Additional CJK compatibility settings
+        compat.Append(new CompatibilitySetting
+        {
+            Name = CompatSettingNameValues.OverrideTableStyleFontSizeAndJustification,
+            Uri = "http://schemas.microsoft.com/office/word",
+            Val = "1"
+        });
+        compat.Append(new CompatibilitySetting
+        {
+            Name = CompatSettingNameValues.EnableOpenTypeFeatures,
+            Uri = "http://schemas.microsoft.com/office/word",
+            Val = "1"
+        });
+        settings.Append(compat);
+
+        settings.Save();
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // 7. DOCUMENT PROPERTIES (metadata)
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Sets core properties (Dublin Core: title, author, dates),
+    /// extended properties (company, application name),
+    /// and custom properties (arbitrary key-value pairs).
+    /// </summary>
+    /// <remarks>
+    /// Core properties go into docProps/core.xml (Dublin Core + CP namespaces).
+    /// Extended properties go into docProps/app.xml.
+    /// Custom properties go into docProps/custom.xml.
+    /// </remarks>
+    public static void SetDocumentProperties(WordprocessingDocument doc)
+    {
+        // ── Core Properties ──
+        // These map to Dublin Core metadata elements in docProps/core.xml
+        doc.PackageProperties.Title = "Quarterly Report";
+        doc.PackageProperties.Subject = "Financial Summary";
+        doc.PackageProperties.Creator = "MiniMax AI";          // Author
+        doc.PackageProperties.Keywords = "report, finance, Q4";
+        doc.PackageProperties.Description = "Auto-generated financial report";
+        doc.PackageProperties.Category = "Reports";
+        doc.PackageProperties.ContentStatus = "Draft";
+
+        // Dates — PackageProperties uses DateTimeOffset?
+        doc.PackageProperties.Created = DateTimeOffset.UtcNow.DateTime;
+        doc.PackageProperties.Modified = DateTimeOffset.UtcNow.DateTime;
+        doc.PackageProperties.LastModifiedBy = "DocBuilder Agent";
+
+        // ── Extended Properties ──
+        // These go into docProps/app.xml
+        var extendedProps = doc.AddExtendedFilePropertiesPart();
+        extendedProps.Properties = new DocumentFormat.OpenXml.ExtendedProperties.Properties
+        {
+            Company = new Company("MiniMax Inc."),
+            Application = new Application("MiniMaxAIDocx"),
+            ApplicationVersion = new ApplicationVersion("1.0.0")
+        };
+        extendedProps.Properties.Save();
+
+        // ── Custom Properties ──
+        // Arbitrary key-value pairs; visible in File > Properties > Custom in Word
+        var customProps = doc.AddCustomFilePropertiesPart();
+        customProps.Properties = new DocumentFormat.OpenXml.CustomProperties.Properties();
+
+        // Each custom property needs a unique PID starting at 2
+        // (PID 0 and 1 are reserved by the system)
+        int pid = 2;
+
+        // String property
+        customProps.Properties.Append(new CustomDocumentProperty
+        {
+            FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}",
+            PropertyId = pid++,
+            Name = "Department",
+            VTLPWSTR = new VTLPWSTR("Engineering")
+        });
+
+        // Integer property
+        customProps.Properties.Append(new CustomDocumentProperty
+        {
+            FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}",
+            PropertyId = pid++,
+            Name = "ReviewCount",
+            VTInt32 = new VTInt32("3")
+        });
+
+        // Boolean property
+        customProps.Properties.Append(new CustomDocumentProperty
+        {
+            FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}",
+            PropertyId = pid++,
+            Name = "IsApproved",
+            VTBool = new VTBool("true")
+        });
+
+        // Date property
+        customProps.Properties.Append(new CustomDocumentProperty
+        {
+            FormatId = "{D5CDD505-2E9C-101B-9397-08002B2CF9AE}",
+            PropertyId = pid++,
+            Name = "ReviewDate",
+            VTFileTime = new VTFileTime(DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"))
+        });
+
+        customProps.Properties.Save();
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // 8. PAGE SETUP (sizes, margins, orientation)
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Creates a document demonstrating various page setups:
+    /// A4/Letter sizes, standard/narrow/wide/公文 margins,
+    /// and both portrait and landscape orientations (as separate sections).
+    /// </summary>
+    public static void CreateDocumentWithPageSetup(string path)
+    {
+        using var doc = WordprocessingDocument.Create(path, WordprocessingDocumentType.Document);
+        var mainPart = doc.AddMainDocumentPart();
+
+        var body = new Body();
+
+        // ════════════════════════════════════════════════════════════
+        // SECTION 1: A4 Portrait with Standard Margins (1 inch all)
+        // ════════════════════════════════════════════════════════════
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+                new Run(new Text("Section 1: A4 Portrait, Standard Margins"))
+            )
+        );
+        body.Append(
+            new Paragraph(new Run(new Text("Standard 1-inch margins all around.")))
+        );
+
+        // IMPORTANT: This is a "continuous" section break that ends section 1.
+        // The sectPr inside a pPr defines the properties FOR THE PRECEDING section.
+        // The FINAL section's properties are in the body-level sectPr.
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(
+                    new SectionProperties(
+                        new WpPageSize
+                        {
+                            // A4: 210mm x 297mm = 11906 x 16838 DXA
+                            Width = (UInt32Value)(uint)PageSizes.A4.WidthDxa,
+                            Height = (UInt32Value)(uint)PageSizes.A4.HeightDxa
+                            // IMPORTANT: No Orient attribute = portrait (default)
+                        },
+                        new PageMargin
+                        {
+                            Top = PageSizes.StandardMargins.TopDxa,     // 1440 = 1 inch
+                            Right = (UInt32Value)(uint)PageSizes.StandardMargins.RightDxa,
+                            Bottom = PageSizes.StandardMargins.BottomDxa,
+                            Left = (UInt32Value)(uint)PageSizes.StandardMargins.LeftDxa,
+                            Header = (UInt32Value)720U,
+                            Footer = (UInt32Value)720U,
+                            Gutter = (UInt32Value)0U
+                        }
+                    )
+                )
+            )
+        );
+
+        // ════════════════════════════════════════════════════════════
+        // SECTION 2: Letter Portrait with Narrow Margins
+        // ════════════════════════════════════════════════════════════
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+                new Run(new Text("Section 2: Letter Portrait, Narrow Margins"))
+            )
+        );
+        body.Append(
+            new Paragraph(new Run(new Text("Narrow 0.5-inch margins for maximum content area.")))
+        );
+
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(
+                    new SectionProperties(
+                        new WpPageSize
+                        {
+                            // US Letter: 8.5" x 11" = 12240 x 15840 DXA
+                            Width = (UInt32Value)(uint)PageSizes.Letter.WidthDxa,
+                            Height = (UInt32Value)(uint)PageSizes.Letter.HeightDxa
+                        },
+                        new PageMargin
+                        {
+                            Top = PageSizes.NarrowMargins.TopDxa,       // 720 = 0.5 inch
+                            Right = (UInt32Value)(uint)PageSizes.NarrowMargins.RightDxa,
+                            Bottom = PageSizes.NarrowMargins.BottomDxa,
+                            Left = (UInt32Value)(uint)PageSizes.NarrowMargins.LeftDxa,
+                            Header = (UInt32Value)720U,
+                            Footer = (UInt32Value)720U,
+                            Gutter = (UInt32Value)0U
+                        }
+                    )
+                )
+            )
+        );
+
+        // ════════════════════════════════════════════════════════════
+        // SECTION 3: A4 Landscape with Wide Margins
+        // ════════════════════════════════════════════════════════════
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+                new Run(new Text("Section 3: A4 Landscape, Wide Margins"))
+            )
+        );
+        body.Append(
+            new Paragraph(new Run(new Text("Landscape orientation — width and height are SWAPPED.")))
+        );
+
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(
+                    new SectionProperties(
+                        new WpPageSize
+                        {
+                            // IMPORTANT: For landscape, SWAP width and height values
+                            // AND set Orient = Landscape
+                            Width = (UInt32Value)(uint)PageSizes.A4.HeightDxa,   // 16838 (was height)
+                            Height = (UInt32Value)(uint)PageSizes.A4.WidthDxa,   // 11906 (was width)
+                            Orient = PageOrientationValues.Landscape
+                        },
+                        new PageMargin
+                        {
+                            // Wide margins: 1" top/bottom, 1.5" left/right
+                            Top = PageSizes.WideMargins.TopDxa,        // 1440
+                            Right = (UInt32Value)(uint)PageSizes.WideMargins.RightDxa, // 2160
+                            Bottom = PageSizes.WideMargins.BottomDxa,  // 1440
+                            Left = (UInt32Value)(uint)PageSizes.WideMargins.LeftDxa,   // 2160
+                            Header = (UInt32Value)720U,
+                            Footer = (UInt32Value)720U,
+                            Gutter = (UInt32Value)0U
+                        }
+                    )
+                )
+            )
+        );
+
+        // ════════════════════════════════════════════════════════════
+        // SECTION 4 (FINAL): A4 Portrait with Chinese 公文 Margins
+        // ════════════════════════════════════════════════════════════
+        // Chinese government document standard (GB/T 9704-2012):
+        //   Page: A4 (210mm x 297mm)
+        //   Top: 37mm ≈ 2098 DXA    Bottom: 35mm ≈ 1984 DXA
+        //   Left: 28mm ≈ 1587 DXA   Right: 26mm ≈ 1474 DXA
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+                new Run(new Text("Section 4: A4 Portrait, 公文 Margins (GB/T 9704)"))
+            )
+        );
+        body.Append(
+            new Paragraph(new Run(new Text("Chinese government document standard margins.")))
+        );
+
+        // The FINAL section's SectionProperties goes as a direct child of Body (not in pPr)
+        body.Append(
+            new SectionProperties(
+                new WpPageSize
+                {
+                    Width = (UInt32Value)(uint)PageSizes.A4.WidthDxa,
+                    Height = (UInt32Value)(uint)PageSizes.A4.HeightDxa
+                },
+                new PageMargin
+                {
+                    // 公文 margins per GB/T 9704-2012
+                    Top = UnitConverter.CmToDxa(3.7),        // 37mm top
+                    Right = (UInt32Value)(uint)UnitConverter.CmToDxa(2.6),  // 26mm right
+                    Bottom = UnitConverter.CmToDxa(3.5),     // 35mm bottom
+                    Left = (UInt32Value)(uint)UnitConverter.CmToDxa(2.8),   // 28mm left
+                    Header = (UInt32Value)(uint)UnitConverter.CmToDxa(1.5), // 15mm header
+                    Footer = (UInt32Value)(uint)UnitConverter.CmToDxa(1.75),// 17.5mm footer
+                    Gutter = (UInt32Value)0U
+                },
+                // Document grid for Chinese text layout:
+                // 28 lines per page, 28 characters per line (公文 standard)
+                new DocGrid
+                {
+                    Type = DocGridValues.LinesAndChars,
+                    LinePitch = 579,       // vertical pitch in DXA: ~28 lines on A4
+                    CharacterSpace = 210   // character spacing adjustment
+                }
+            )
+        );
+
+        mainPart.Document = new Document(body);
+        mainPart.Document.Save();
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // 9. MULTI-SECTION DOCUMENT
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Creates a document with three sections demonstrating:
+    /// - Portrait intro with "first page" header
+    /// - Landscape table section with different header
+    /// - Portrait conclusion with page number restart
+    /// Each section has its own headers and page numbering.
+    /// </summary>
+    public static void CreateMultiSectionDocument(string path)
+    {
+        using var doc = WordprocessingDocument.Create(path, WordprocessingDocumentType.Document);
+        var mainPart = doc.AddMainDocumentPart();
+
+        // ── Create headers for each section ──
+        // Each section can reference its own header/footer parts.
+
+        // --- Section 1 headers: "first page" + "default" ---
+        var header1Default = CreateHeaderPart(mainPart, "Introduction — Page ");
+        var header1FirstPage = CreateHeaderPart(mainPart, "CONFIDENTIAL DRAFT");
+
+        // --- Section 2 header: landscape section ---
+        var header2Default = CreateHeaderPart(mainPart, "Data Tables — Landscape View");
+
+        // --- Section 3 header: conclusion ---
+        var header3Default = CreateHeaderPart(mainPart, "Conclusion — Page ");
+
+        var body = new Body();
+
+        // ════════════════════════════════════════════════════════════
+        // SECTION 1: Portrait Introduction
+        // ════════════════════════════════════════════════════════════
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+                new Run(new Text("Introduction"))
+            )
+        );
+        body.Append(
+            new Paragraph(new Run(new Text(
+                "This section uses portrait orientation with a special first-page header.")))
+        );
+        body.Append(
+            new Paragraph(new Run(new Text(
+                "The first page shows 'CONFIDENTIAL DRAFT', subsequent pages show the section name.")))
+        );
+
+        // Section 1 properties (embedded in paragraph = section break)
+        var sect1Props = new SectionProperties(
+            // Header references link to header parts via relationship IDs
+            // HeaderFooterType: Default = all pages, First = first page only, Even = even pages
+            new HeaderReference
+            {
+                Type = HeaderFooterValues.Default,
+                Id = mainPart.GetIdOfPart(header1Default)
+            },
+            new HeaderReference
+            {
+                Type = HeaderFooterValues.First,
+                Id = mainPart.GetIdOfPart(header1FirstPage)
+            },
+            // IMPORTANT: SectionType controls how the section break renders:
+            //   NextPage — starts on a new page (default if omitted)
+            //   Continuous — no page break, flows on same page
+            //   EvenPage / OddPage — starts on next even/odd page
+            new SectionType { Val = SectionMarkValues.NextPage },
+            new WpPageSize
+            {
+                Width = (UInt32Value)(uint)PageSizes.A4.WidthDxa,
+                Height = (UInt32Value)(uint)PageSizes.A4.HeightDxa
+            },
+            new PageMargin
+            {
+                Top = 1440, Right = (UInt32Value)1440U, Bottom = 1440,
+                Left = (UInt32Value)1440U, Header = (UInt32Value)720U,
+                Footer = (UInt32Value)720U, Gutter = (UInt32Value)0U
+            },
+            // PageNumberType: start numbering from 1
+            new PageNumberType { Start = 1 },
+            // TitlePage: enables the "Different First Page" header/footer
+            // Without this, the First header reference is ignored!
+            new TitlePage()
+        );
+
+        body.Append(new Paragraph(new ParagraphProperties(sect1Props)));
+
+        // ════════════════════════════════════════════════════════════
+        // SECTION 2: Landscape Data Tables
+        // ════════════════════════════════════════════════════════════
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+                new Run(new Text("Data Tables"))
+            )
+        );
+
+        // Add a simple table to justify landscape orientation
+        var table = new Table(
+            new TableProperties(
+                new TableWidth { Width = "5000", Type = TableWidthUnitValues.Pct },
+                new TableBorders(
+                    new TopBorder { Val = BorderValues.Single, Size = 4 },
+                    new BottomBorder { Val = BorderValues.Single, Size = 4 },
+                    new LeftBorder { Val = BorderValues.Single, Size = 4 },
+                    new RightBorder { Val = BorderValues.Single, Size = 4 },
+                    new InsideHorizontalBorder { Val = BorderValues.Single, Size = 4 },
+                    new InsideVerticalBorder { Val = BorderValues.Single, Size = 4 }
+                )
+            ),
+            new TableGrid(
+                new GridColumn { Width = "3000" },
+                new GridColumn { Width = "3000" },
+                new GridColumn { Width = "3000" }
+            ),
+            // Header row
+            new TableRow(
+                new TableCell(new Paragraph(new Run(new Text("Column A")))),
+                new TableCell(new Paragraph(new Run(new Text("Column B")))),
+                new TableCell(new Paragraph(new Run(new Text("Column C"))))
+            ),
+            // Data row
+            new TableRow(
+                new TableCell(new Paragraph(new Run(new Text("Data 1")))),
+                new TableCell(new Paragraph(new Run(new Text("Data 2")))),
+                new TableCell(new Paragraph(new Run(new Text("Data 3"))))
+            )
+        );
+        body.Append(table);
+
+        // Section 2 properties (landscape)
+        var sect2Props = new SectionProperties(
+            new HeaderReference
+            {
+                Type = HeaderFooterValues.Default,
+                Id = mainPart.GetIdOfPart(header2Default)
+            },
+            new SectionType { Val = SectionMarkValues.NextPage },
+            new WpPageSize
+            {
+                // IMPORTANT: Landscape = swap width/height AND set Orient
+                Width = (UInt32Value)(uint)PageSizes.A4.HeightDxa,
+                Height = (UInt32Value)(uint)PageSizes.A4.WidthDxa,
+                Orient = PageOrientationValues.Landscape
+            },
+            new PageMargin
+            {
+                Top = 1440, Right = (UInt32Value)1440U, Bottom = 1440,
+                Left = (UInt32Value)1440U, Header = (UInt32Value)720U,
+                Footer = (UInt32Value)720U, Gutter = (UInt32Value)0U
+            },
+            // Continue page numbering from previous section (no Start attribute)
+            new PageNumberType()
+        );
+
+        body.Append(new Paragraph(new ParagraphProperties(sect2Props)));
+
+        // ════════════════════════════════════════════════════════════
+        // SECTION 3 (FINAL): Portrait Conclusion with Restart Numbering
+        // ════════════════════════════════════════════════════════════
+        body.Append(
+            new Paragraph(
+                new ParagraphProperties(new ParagraphStyleId { Val = "Heading1" }),
+                new Run(new Text("Conclusion"))
+            )
+        );
+        body.Append(
+            new Paragraph(new Run(new Text(
+                "This section restarts page numbering from 1.")))
+        );
+
+        // Final section: SectionProperties as direct child of Body
+        body.Append(
+            new SectionProperties(
+                new HeaderReference
+                {
+                    Type = HeaderFooterValues.Default,
+                    Id = mainPart.GetIdOfPart(header3Default)
+                },
+                new WpPageSize
+                {
+                    Width = (UInt32Value)(uint)PageSizes.A4.WidthDxa,
+                    Height = (UInt32Value)(uint)PageSizes.A4.HeightDxa
+                },
+                new PageMargin
+                {
+                    Top = 1440, Right = (UInt32Value)1440U, Bottom = 1440,
+                    Left = (UInt32Value)1440U, Header = (UInt32Value)720U,
+                    Footer = (UInt32Value)720U, Gutter = (UInt32Value)0U
+                },
+                // Restart page numbering from 1 for this section
+                new PageNumberType { Start = 1 }
+            )
+        );
+
+        mainPart.Document = new Document(body);
+        mainPart.Document.Save();
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // HELPER: Create a header part with text and optional page number field
+    // ────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// Creates a HeaderPart with the given text. If the text ends with a space,
+    /// a PAGE field is appended to show the page number.
+    /// </summary>
+    private static HeaderPart CreateHeaderPart(MainDocumentPart mainPart, string text)
+    {
+        var headerPart = mainPart.AddNewPart<HeaderPart>();
+        var header = new Header();
+
+        var para = new Paragraph(
+            new ParagraphProperties(
+                new Justification { Val = JustificationValues.Center }
+            )
+        );
+
+        // Add the text run
+        para.Append(new Run(
+            new RunProperties(
+                new FontSize { Val = "18" } // 9pt for header text
+            ),
+            new Text(text) { Space = SpaceProcessingModeValues.Preserve }
+        ));
+
+        // If text ends with space, add a PAGE field (auto page number)
+        if (text.EndsWith(' '))
+        {
+            // PAGE field uses three runs: begin, instruction, end
+            // This is the "complex field" pattern used by Word
+            para.Append(new Run(
+                new RunProperties(new FontSize { Val = "18" }),
+                new FieldChar { FieldCharType = FieldCharValues.Begin }
+            ));
+            para.Append(new Run(
+                new RunProperties(new FontSize { Val = "18" }),
+                new FieldCode(" PAGE ") { Space = SpaceProcessingModeValues.Preserve }
+            ));
+            para.Append(new Run(
+                new RunProperties(new FontSize { Val = "18" }),
+                new FieldChar { FieldCharType = FieldCharValues.End }
+            ));
+        }
+
+        header.Append(para);
+        headerPart.Header = header;
+        headerPart.Header.Save();
+        return headerPart;
+    }
+}