plcode-windows-x64-baseline 2.1.0

package/.plcode/skill/experimental/document-docx/docx-js.md

@@ -0,0 +1,488 @@
+# DOCX Library Tutorial
+
+Generate .docx files with JavaScript/TypeScript.
+
+**Important: Read this entire document before starting.** Critical formatting rules and common pitfalls are covered throughout - skipping sections may result in corrupted files or rendering issues.
+
+## Setup
+
+Assumes docx is already installed globally
+If not installed: `npm install -g docx`
+
+```javascript
+const {
+  Document,
+  Packer,
+  Paragraph,
+  TextRun,
+  Table,
+  TableRow,
+  TableCell,
+  ImageRun,
+  Media,
+  Header,
+  Footer,
+  AlignmentType,
+  PageOrientation,
+  LevelFormat,
+  ExternalHyperlink,
+  InternalHyperlink,
+  TableOfContents,
+  HeadingLevel,
+  BorderStyle,
+  WidthType,
+  TabStopType,
+  TabStopPosition,
+  UnderlineType,
+  ShadingType,
+  VerticalAlign,
+  SymbolRun,
+  PageNumber,
+  FootnoteReferenceRun,
+  Footnote,
+  PageBreak,
+} = require("docx")
+
+// Create & Save
+const doc = new Document({
+  sections: [
+    {
+      children: [
+        /* content */
+      ],
+    },
+  ],
+})
+Packer.toBuffer(doc).then((buffer) => fs.writeFileSync("doc.docx", buffer)) // Node.js
+Packer.toBlob(doc).then((blob) => {
+  /* download logic */
+}) // Browser
+```
+
+## Text & Formatting
+
+```javascript
+// IMPORTANT: Never use \n for line breaks - always use separate Paragraph elements
+// ❌ WRONG: new TextRun("Line 1\nLine 2")
+// ✅ CORRECT: new Paragraph({ children: [new TextRun("Line 1")] }), new Paragraph({ children: [new TextRun("Line 2")] })
+
+// Basic text with all formatting options
+new Paragraph({
+  alignment: AlignmentType.CENTER,
+  spacing: { before: 200, after: 200 },
+  indent: { left: 720, right: 720 },
+  children: [
+    new TextRun({ text: "Bold", bold: true }),
+    new TextRun({ text: "Italic", italics: true }),
+    new TextRun({ text: "Underlined", underline: { type: UnderlineType.DOUBLE, color: "FF0000" } }),
+    new TextRun({ text: "Colored", color: "FF0000", size: 28, font: "Arial" }), // Arial default
+    new TextRun({ text: "Highlighted", highlight: "yellow" }),
+    new TextRun({ text: "Strikethrough", strike: true }),
+    new TextRun({ text: "x2", superScript: true }),
+    new TextRun({ text: "H2O", subScript: true }),
+    new TextRun({ text: "SMALL CAPS", smallCaps: true }),
+    new SymbolRun({ char: "2022", font: "Symbol" }), // Bullet •
+    new SymbolRun({ char: "00A9", font: "Arial" }), // Copyright © - Arial for symbols
+  ],
+})
+```
+
+## Styles & Professional Formatting
+
+```javascript
+const doc = new Document({
+  styles: {
+    default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt default
+    paragraphStyles: [
+      // Document title style - override built-in Title style
+      {
+        id: "Title",
+        name: "Title",
+        basedOn: "Normal",
+        run: { size: 56, bold: true, color: "000000", font: "Arial" },
+        paragraph: { spacing: { before: 240, after: 120 }, alignment: AlignmentType.CENTER },
+      },
+      // IMPORTANT: Override built-in heading styles by using their exact IDs
+      {
+        id: "Heading1",
+        name: "Heading 1",
+        basedOn: "Normal",
+        next: "Normal",
+        quickFormat: true,
+        run: { size: 32, bold: true, color: "000000", font: "Arial" }, // 16pt
+        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 },
+      }, // Required for TOC
+      {
+        id: "Heading2",
+        name: "Heading 2",
+        basedOn: "Normal",
+        next: "Normal",
+        quickFormat: true,
+        run: { size: 28, bold: true, color: "000000", font: "Arial" }, // 14pt
+        paragraph: { spacing: { before: 180, after: 180 }, outlineLevel: 1 },
+      },
+      // Custom styles use your own IDs
+      {
+        id: "myStyle",
+        name: "My Style",
+        basedOn: "Normal",
+        run: { size: 28, bold: true, color: "000000" },
+        paragraph: { spacing: { after: 120 }, alignment: AlignmentType.CENTER },
+      },
+    ],
+    characterStyles: [
+      {
+        id: "myCharStyle",
+        name: "My Char Style",
+        run: { color: "FF0000", bold: true, underline: { type: UnderlineType.SINGLE } },
+      },
+    ],
+  },
+  sections: [
+    {
+      properties: { page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } } },
+      children: [
+        new Paragraph({ heading: HeadingLevel.TITLE, children: [new TextRun("Document Title")] }), // Uses overridden Title style
+        new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Heading 1")] }), // Uses overridden Heading1 style
+        new Paragraph({ style: "myStyle", children: [new TextRun("Custom paragraph style")] }),
+        new Paragraph({
+          children: [new TextRun("Normal with "), new TextRun({ text: "custom char style", style: "myCharStyle" })],
+        }),
+      ],
+    },
+  ],
+})
+```
+
+**Professional Font Combinations:**
+
+- **Arial (Headers) + Arial (Body)** - Most universally supported, clean and professional
+- **Times New Roman (Headers) + Arial (Body)** - Classic serif headers with modern sans-serif body
+- **Georgia (Headers) + Verdana (Body)** - Optimized for screen reading, elegant contrast
+
+**Key Styling Principles:**
+
+- **Override built-in styles**: Use exact IDs like "Heading1", "Heading2", "Heading3" to override Word's built-in heading styles
+- **HeadingLevel constants**: `HeadingLevel.HEADING_1` uses "Heading1" style, `HeadingLevel.HEADING_2` uses "Heading2" style, etc.
+- **Include outlineLevel**: Set `outlineLevel: 0` for H1, `outlineLevel: 1` for H2, etc. to ensure TOC works correctly
+- **Use custom styles** instead of inline formatting for consistency
+- **Set a default font** using `styles.default.document.run.font` - Arial is universally supported
+- **Establish visual hierarchy** with different font sizes (titles > headers > body)
+- **Add proper spacing** with `before` and `after` paragraph spacing
+- **Use colors sparingly**: Default to black (000000) and shades of gray for titles and headings (heading 1, heading 2, etc.)
+- **Set consistent margins** (1440 = 1 inch is standard)
+
+## Lists (ALWAYS USE PROPER LISTS - NEVER USE UNICODE BULLETS)
+
+```javascript
+// Bullets - ALWAYS use the numbering config, NOT unicode symbols
+// CRITICAL: Use LevelFormat.BULLET constant, NOT the string "bullet"
+const doc = new Document({
+  numbering: {
+    config: [
+      {
+        reference: "bullet-list",
+        levels: [
+          {
+            level: 0,
+            format: LevelFormat.BULLET,
+            text: "•",
+            alignment: AlignmentType.LEFT,
+            style: { paragraph: { indent: { left: 720, hanging: 360 } } },
+          },
+        ],
+      },
+      {
+        reference: "first-numbered-list",
+        levels: [
+          {
+            level: 0,
+            format: LevelFormat.DECIMAL,
+            text: "%1.",
+            alignment: AlignmentType.LEFT,
+            style: { paragraph: { indent: { left: 720, hanging: 360 } } },
+          },
+        ],
+      },
+      {
+        reference: "second-numbered-list", // Different reference = restarts at 1
+        levels: [
+          {
+            level: 0,
+            format: LevelFormat.DECIMAL,
+            text: "%1.",
+            alignment: AlignmentType.LEFT,
+            style: { paragraph: { indent: { left: 720, hanging: 360 } } },
+          },
+        ],
+      },
+    ],
+  },
+  sections: [
+    {
+      children: [
+        // Bullet list items
+        new Paragraph({
+          numbering: { reference: "bullet-list", level: 0 },
+          children: [new TextRun("First bullet point")],
+        }),
+        new Paragraph({
+          numbering: { reference: "bullet-list", level: 0 },
+          children: [new TextRun("Second bullet point")],
+        }),
+        // Numbered list items
+        new Paragraph({
+          numbering: { reference: "first-numbered-list", level: 0 },
+          children: [new TextRun("First numbered item")],
+        }),
+        new Paragraph({
+          numbering: { reference: "first-numbered-list", level: 0 },
+          children: [new TextRun("Second numbered item")],
+        }),
+        // ⚠️ CRITICAL: Different reference = INDEPENDENT list that restarts at 1
+        // Same reference = CONTINUES previous numbering
+        new Paragraph({
+          numbering: { reference: "second-numbered-list", level: 0 },
+          children: [new TextRun("Starts at 1 again (because different reference)")],
+        }),
+      ],
+    },
+  ],
+})
+
+// ⚠️ CRITICAL NUMBERING RULE: Each reference creates an INDEPENDENT numbered list
+// - Same reference = continues numbering (1, 2, 3... then 4, 5, 6...)
+// - Different reference = restarts at 1 (1, 2, 3... then 1, 2, 3...)
+// Use unique reference names for each separate numbered section!
+
+// ⚠️ CRITICAL: NEVER use unicode bullets - they create fake lists that don't work properly
+// new TextRun("• Item")           // WRONG
+// new SymbolRun({ char: "2022" }) // WRONG
+// ✅ ALWAYS use numbering config with LevelFormat.BULLET for real Word lists
+```
+
+## Tables
+
+```javascript
+// Complete table with margins, borders, headers, and bullet points
+const tableBorder = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" }
+const cellBorders = { top: tableBorder, bottom: tableBorder, left: tableBorder, right: tableBorder }
+
+new Table({
+  columnWidths: [4680, 4680], // ⚠️ CRITICAL: Set column widths at table level - values in DXA (twentieths of a point)
+  margins: { top: 100, bottom: 100, left: 180, right: 180 }, // Set once for all cells
+  rows: [
+    new TableRow({
+      tableHeader: true,
+      children: [
+        new TableCell({
+          borders: cellBorders,
+          width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
+          // ⚠️ CRITICAL: Always use ShadingType.CLEAR to prevent black backgrounds in Word.
+          shading: { fill: "D5E8F0", type: ShadingType.CLEAR },
+          verticalAlign: VerticalAlign.CENTER,
+          children: [
+            new Paragraph({
+              alignment: AlignmentType.CENTER,
+              children: [new TextRun({ text: "Header", bold: true, size: 22 })],
+            }),
+          ],
+        }),
+        new TableCell({
+          borders: cellBorders,
+          width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
+          shading: { fill: "D5E8F0", type: ShadingType.CLEAR },
+          children: [
+            new Paragraph({
+              alignment: AlignmentType.CENTER,
+              children: [new TextRun({ text: "Bullet Points", bold: true, size: 22 })],
+            }),
+          ],
+        }),
+      ],
+    }),
+    new TableRow({
+      children: [
+        new TableCell({
+          borders: cellBorders,
+          width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
+          children: [new Paragraph({ children: [new TextRun("Regular data")] })],
+        }),
+        new TableCell({
+          borders: cellBorders,
+          width: { size: 4680, type: WidthType.DXA }, // ALSO set width on each cell
+          children: [
+            new Paragraph({
+              numbering: { reference: "bullet-list", level: 0 },
+              children: [new TextRun("First bullet point")],
+            }),
+            new Paragraph({
+              numbering: { reference: "bullet-list", level: 0 },
+              children: [new TextRun("Second bullet point")],
+            }),
+          ],
+        }),
+      ],
+    }),
+  ],
+})
+```
+
+**IMPORTANT: Table Width & Borders**
+
+- Use BOTH `columnWidths: [width1, width2, ...]` array AND `width: { size: X, type: WidthType.DXA }` on each cell
+- Values in DXA (twentieths of a point): 1440 = 1 inch, Letter usable width = 9360 DXA (with 1" margins)
+- Apply borders to individual `TableCell` elements, NOT the `Table` itself
+
+**Precomputed Column Widths (Letter size with 1" margins = 9360 DXA total):**
+
+- **2 columns:** `columnWidths: [4680, 4680]` (equal width)
+- **3 columns:** `columnWidths: [3120, 3120, 3120]` (equal width)
+
+## Links & Navigation
+
+```javascript
+// TOC (requires headings) - CRITICAL: Use HeadingLevel only, NOT custom styles
+// ❌ WRONG: new Paragraph({ heading: HeadingLevel.HEADING_1, style: "customHeader", children: [new TextRun("Title")] })
+// ✅ CORRECT: new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun("Title")] })
+new TableOfContents("Table of Contents", { hyperlink: true, headingStyleRange: "1-3" }),
+
+// External link
+new Paragraph({
+  children: [new ExternalHyperlink({
+    children: [new TextRun({ text: "Google", style: "Hyperlink" })],
+    link: "https://www.google.com"
+  })]
+}),
+
+// Internal link & bookmark
+new Paragraph({
+  children: [new InternalHyperlink({
+    children: [new TextRun({ text: "Go to Section", style: "Hyperlink" })],
+    anchor: "section1"
+  })]
+}),
+new Paragraph({
+  children: [new TextRun("Section Content")],
+  bookmark: { id: "section1", name: "section1" }
+}),
+```
+
+## Images & Media
+
+```javascript
+// Basic image with sizing & positioning
+// CRITICAL: Always specify 'type' parameter - it's REQUIRED for ImageRun
+new Paragraph({
+  alignment: AlignmentType.CENTER,
+  children: [
+    new ImageRun({
+      type: "png", // NEW REQUIREMENT: Must specify image type (png, jpg, jpeg, gif, bmp, svg)
+      data: fs.readFileSync("image.png"),
+      transformation: { width: 200, height: 150, rotation: 0 }, // rotation in degrees
+      altText: { title: "Logo", description: "Company logo", name: "Name" }, // IMPORTANT: All three fields are required
+    }),
+  ],
+})
+```
+
+## Page Breaks
+
+```javascript
+// Manual page break
+;(new Paragraph({ children: [new PageBreak()] }),
+  // Page break before paragraph
+  new Paragraph({
+    pageBreakBefore: true,
+    children: [new TextRun("This starts on a new page")],
+  }))
+
+// ⚠️ CRITICAL: NEVER use PageBreak standalone - it will create invalid XML that Word cannot open
+// ❌ WRONG: new PageBreak()
+// ✅ CORRECT: new Paragraph({ children: [new PageBreak()] })
+```
+
+## Headers/Footers & Page Setup
+
+```javascript
+const doc = new Document({
+  sections: [
+    {
+      properties: {
+        page: {
+          margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 }, // 1440 = 1 inch
+          size: { orientation: PageOrientation.LANDSCAPE },
+          pageNumbers: { start: 1, formatType: "decimal" }, // "upperRoman", "lowerRoman", "upperLetter", "lowerLetter"
+        },
+      },
+      headers: {
+        default: new Header({
+          children: [
+            new Paragraph({
+              alignment: AlignmentType.RIGHT,
+              children: [new TextRun("Header Text")],
+            }),
+          ],
+        }),
+      },
+      footers: {
+        default: new Footer({
+          children: [
+            new Paragraph({
+              alignment: AlignmentType.CENTER,
+              children: [
+                new TextRun("Page "),
+                new TextRun({ children: [PageNumber.CURRENT] }),
+                new TextRun(" of "),
+                new TextRun({ children: [PageNumber.TOTAL_PAGES] }),
+              ],
+            }),
+          ],
+        }),
+      },
+      children: [
+        /* content */
+      ],
+    },
+  ],
+})
+```
+
+## Tabs
+
+```javascript
+new Paragraph({
+  tabStops: [
+    { type: TabStopType.LEFT, position: TabStopPosition.MAX / 4 },
+    { type: TabStopType.CENTER, position: TabStopPosition.MAX / 2 },
+    { type: TabStopType.RIGHT, position: (TabStopPosition.MAX * 3) / 4 },
+  ],
+  children: [new TextRun("Left\tCenter\tRight")],
+})
+```
+
+## Constants & Quick Reference
+
+- **Underlines:** `SINGLE`, `DOUBLE`, `WAVY`, `DASH`
+- **Borders:** `SINGLE`, `DOUBLE`, `DASHED`, `DOTTED`
+- **Numbering:** `DECIMAL` (1,2,3), `UPPER_ROMAN` (I,II,III), `LOWER_LETTER` (a,b,c)
+- **Tabs:** `LEFT`, `CENTER`, `RIGHT`, `DECIMAL`
+- **Symbols:** `"2022"` (•), `"00A9"` (©), `"00AE"` (®), `"2122"` (™), `"00B0"` (°), `"F070"` (✓), `"F0FC"` (✗)
+
+## Critical Issues & Common Mistakes
+
+- **CRITICAL: PageBreak must ALWAYS be inside a Paragraph** - standalone PageBreak creates invalid XML that Word cannot open
+- **ALWAYS use ShadingType.CLEAR for table cell shading** - Never use ShadingType.SOLID (causes black background).
+- Measurements in DXA (1440 = 1 inch) | Each table cell needs ≥1 Paragraph | TOC requires HeadingLevel styles only
+- **ALWAYS use custom styles** with Arial font for professional appearance and proper visual hierarchy
+- **ALWAYS set a default font** using `styles.default.document.run.font` - Arial recommended
+- **ALWAYS use columnWidths array for tables** + individual cell widths for compatibility
+- **NEVER use unicode symbols for bullets** - always use proper numbering configuration with `LevelFormat.BULLET` constant (NOT the string "bullet")
+- **NEVER use \n for line breaks anywhere** - always use separate Paragraph elements for each line
+- **ALWAYS use TextRun objects within Paragraph children** - never use text property directly on Paragraph
+- **CRITICAL for images**: ImageRun REQUIRES `type` parameter - always specify "png", "jpg", "jpeg", "gif", "bmp", or "svg"
+- **CRITICAL for bullets**: Must use `LevelFormat.BULLET` constant, not string "bullet", and include `text: "•"` for the bullet character
+- **CRITICAL for numbering**: Each numbering reference creates an INDEPENDENT list. Same reference = continues numbering (1,2,3 then 4,5,6). Different reference = restarts at 1 (1,2,3 then 1,2,3). Use unique reference names for each separate numbered section!
+- **CRITICAL for TOC**: When using TableOfContents, headings must use HeadingLevel ONLY - do NOT add custom styles to heading paragraphs or TOC will break
+- **Tables**: Set `columnWidths` array + individual cell widths, apply borders to cells not table
+- **Set table margins at TABLE level** for consistent cell padding (avoids repetition per cell)