docx landscape skill

HELPER REFERENCE
================

1) createHeading(text, level)
   Params: text (string) - exact heading text; level (docx.HeadingLevel.*, optional, defaults to HEADING_1)
   Returns: docx.Paragraph configured as a heading (so it is TOC/outline-visible)
   Example: createHeading("Vendor Onboarding Notes", docx.HeadingLevel.HEADING_1)

2) createParagraph(text)
   Params: text (string) - exact paragraph text
   Returns: docx.Paragraph with a single plain TextRun
   Example: createParagraph("Please submit expense forms by the fifth business day of each month.")

3) createHeader(text)
   Params: text (string) - exact header text
   Returns: docx.Header instance containing one paragraph with that text; pass into createDocumentSection's headerText option (that option calls this internally) or use directly as section.headers.default
   Example: const hdr = createHeader("Vendor Onboarding Notes - Appendix");

4) createTableCell(text, widthDxa, opts)
   Params: text (string|number), widthDxa (number, DXA width for this cell), opts (optional {bold: boolean, shade: hex-string-without-#})
   Returns: docx.TableCell with width set in DXA and a single paragraph/run
   Example: createTableCell("Item", 6000, { bold: true, shade: "D9D9D9" })

5) createItemCountTable(headerRow, rows, columnWidths)
   Params: headerRow (array of 2 strings, e.g. ["Item","Count"]); rows (array of arrays, each [itemText, countText]); columnWidths (array of 2 numbers in DXA, must sum to table width)
   Returns: docx.Table with columnWidths set on the table and matching DXA widths on every cell (header row shaded/bold, tableHeader:true so it repeats)
   Example: createItemCountTable(["Item","Count"], [["Hi-vis vests","13"],["Fall arrest harness","13"]], [6000,3000])

6) createDocumentSection(children, options)
   Params: children (array of Paragraph/Table elements for this section's body); options (optional object):
     - orientation: docx.PageOrientation.PORTRAIT (default) or docx.PageOrientation.LANDSCAPE
     - pageWidth / pageHeight: DXA numbers, default US Letter portrait dims 12240 x 15840 (pass these same portrait numbers even for landscape; docx-js swaps them when orientation is LANDSCAPE)
     - headerText: string, if provided a page header with exactly that text is attached to this section
   Returns: a plain object suitable for inclusion in the `sections` array passed to `new docx.Document({ sections: [...] })`
   Example: createDocumentSection([createHeading("Title"), createParagraph("Body")], { orientation: docx.PageOrientation.LANDSCAPE, headerText: "Appendix" })

TYPICAL USAGE PATTERN (portrait section + heading/paragraph, then landscape section + header/table):

  const section1 = createDocumentSection(
    [ createHeading("Title Text"), createParagraph("Body text.") ],
    { orientation: docx.PageOrientation.PORTRAIT }
  );

  const table = createItemCountTable(
    ["Item", "Count"],
    [["A","1"], ["B","2"]],
    [6000, 3000]
  );

  const section2 = createDocumentSection(
    [ table ],
    { orientation: docx.PageOrientation.LANDSCAPE, headerText: "Appendix Header" }
  );

  const doc = new docx.Document({ sections: [section1, section2] });

function createHeading(text, level) {
  const HeadingLevel = docx.HeadingLevel;
  return new docx.Paragraph({
    heading: level || HeadingLevel.HEADING_1,
    children: [new docx.TextRun({ text: text })]
  });
}

function createParagraph(text) {
  return new docx.Paragraph({
    children: [new docx.TextRun({ text: text })]
  });
}

function createHeader(text) {
  return new docx.Header({
    children: [
      new docx.Paragraph({
        children: [new docx.TextRun({ text: text })]
      })
    ]
  });
}

function createTableCell(text, widthDxa, opts) {
  opts = opts || {};
  const runProps = {};
  if (opts.bold) runProps.bold = true;
  const paragraph = new docx.Paragraph({
    children: [new docx.TextRun(Object.assign({ text: String(text) }, runProps))]
  });
  const cellConfig = {
    width: { size: widthDxa, type: docx.WidthType.DXA },
    children: [paragraph]
  };
  if (opts.shade) {
    cellConfig.shading = {
      type: docx.ShadingType.CLEAR,
      fill: opts.shade,
      color: 'auto'
    };
  }
  return new docx.TableCell(cellConfig);
}

function createItemCountTable(headerRow, rows, columnWidths) {
  const totalWidth = columnWidths.reduce((a, b) => a + b, 0);

  const headerCells = headerRow.map((h, i) =>
    createTableCell(h, columnWidths[i], { bold: true, shade: 'D9D9D9' })
  );
  const headerTableRow = new docx.TableRow({ children: headerCells, tableHeader: true });

  const bodyRows = rows.map((row) => {
    const cells = row.map((val, i) => createTableCell(val, columnWidths[i]));
    return new docx.TableRow({ children: cells });
  });

  return new docx.Table({
    width: { size: totalWidth, type: docx.WidthType.DXA },
    columnWidths: columnWidths,
    rows: [headerTableRow, ...bodyRows]
  });
}

function createDocumentSection(children, options) {
  options = options || {};
  const orientation = options.orientation || docx.PageOrientation.PORTRAIT;
  const pageWidth = options.pageWidth || 12240;
  const pageHeight = options.pageHeight || 15840;

  const section = {
    properties: {
      page: {
        size: {
          width: pageWidth,
          height: pageHeight,
          orientation: orientation
        }
      }
    },
    children: children
  };

  if (options.headerText) {
    section.headers = { default: createHeader(options.headerText) };
  }

  return section;
}