Content Elements

/**
 * Paragraph element containing text runs and other inline content
 * @param options - Paragraph configuration or simple text string
 */
class Paragraph {
  constructor(options: string | IParagraphOptions);
  
  /** Add a run to the front of the paragraph */
  addRunToFront(run: Run): Paragraph;
}

/**
 * Configuration options for paragraphs
 */
interface IParagraphOptions extends IParagraphPropertiesOptions {
  /** Simple text content for the paragraph */
  readonly text?: string;
  /** Child elements (runs, images, etc.) */
  readonly children?: readonly ParagraphChild[];
}

import { Paragraph, TextRun } from "docx";

// Simple text paragraph
const simpleParagraph = new Paragraph("This is a simple paragraph");

// Complex paragraph with multiple runs
const complexParagraph = new Paragraph({
  children: [
    new TextRun("Normal text "),
    new TextRun({ text: "bold text", bold: true }),
    new TextRun({ text: " and italic text", italics: true }),
  ],
  alignment: AlignmentType.CENTER,
});

// Paragraph with heading style
const headingParagraph = new Paragraph({
  text: "Chapter 1: Introduction",
  heading: HeadingLevel.HEADING_1,
});

/**
 * Text run with specific formatting within a paragraph
 * @param options - Text run configuration or simple text string
 */
class TextRun {
  constructor(options: IRunOptions | string);
}

/**
 * Configuration options for text runs
 */
interface IRunOptions {
  /** Text content */
  readonly text?: string;
  /** Bold formatting */
  readonly bold?: boolean;
  /** Italic formatting */
  readonly italics?: boolean;
  /** Underline formatting */
  readonly underline?: {
    readonly type?: UnderlineType;
    readonly color?: string;
  };
  /** Text color */
  readonly color?: string;
  /** Font size in half-points */
  readonly size?: number;
  /** Font family */
  readonly font?: string;
  /** Highlight color */
  readonly highlight?: string;
  /** Strike through formatting */
  readonly strike?: boolean;
  /** Double strike through formatting */
  readonly doubleStrike?: boolean;
  /** Superscript formatting */
  readonly superScript?: boolean;
  /** Subscript formatting */
  readonly subScript?: boolean;
}

import { TextRun, UnderlineType } from "docx";

// Simple text run
const simpleRun = new TextRun("Plain text");

// Formatted text run
const formattedRun = new TextRun({
  text: "Formatted text",
  bold: true,
  italics: true,
  color: "FF0000",
  size: 24,
  font: "Arial",
});

// Underlined text run
const underlinedRun = new TextRun({
  text: "Underlined text",
  underline: {
    type: UnderlineType.SINGLE,
    color: "0000FF",
  },
});

/**
 * Image run within a paragraph
 * @param options - Image configuration including data and transformation
 */
class ImageRun {
  constructor(options: IImageOptions);
}

/**
 * Image configuration options
 */
type IImageOptions = (RegularImageOptions | SvgMediaOptions) & CoreImageOptions;

/**
 * Regular image options for standard formats
 */
interface RegularImageOptions {
  readonly type: "jpg" | "png" | "gif" | "bmp";
  readonly data: Buffer | string | Uint8Array | ArrayBuffer;
}

/**
 * SVG image options with fallback
 */
interface SvgMediaOptions {
  readonly type: "svg";
  readonly data: Buffer | string | Uint8Array | ArrayBuffer;
  readonly fallback: RegularImageOptions;
}

/**
 * Core image configuration options
 */
interface CoreImageOptions {
  /** Size and positioning transformation */
  readonly transformation: IMediaTransformation;
  /** Floating properties for text wrapping */
  readonly floating?: IFloating;
  /** Alternative text for accessibility */
  readonly altText?: DocPropertiesOptions;
  /** Image outline styling */
  readonly outline?: OutlineOptions;
}

/**
 * Media transformation for sizing images
 */
interface IMediaTransformation {
  readonly width: number;
  readonly height: number;
}

import { ImageRun } from "docx";
import * as fs from "fs";

// Image from file buffer
const imageRun = new ImageRun({
  data: fs.readFileSync("./my-image.png"),
  transformation: {
    width: 200,
    height: 150,
  },
  type: "png",
});

// SVG image with fallback
const svgRun = new ImageRun({
  type: "svg",
  data: fs.readFileSync("./my-image.svg"),
  fallback: {
    type: "png",
    data: fs.readFileSync("./my-image.png"),
  },
  transformation: {
    width: 300,
    height: 200,
  },
});

/**
 * Table element for structured data presentation
 * @param options - Table configuration including rows and styling
 */
class Table {
  constructor(options: ITableOptions);
}

/**
 * Table configuration options
 */
interface ITableOptions {
  /** Table rows */
  readonly rows: readonly TableRow[];
  /** Table width properties */
  readonly width?: ITableWidthProperties;
  /** Column width specifications */
  readonly columnWidths?: readonly number[];
  /** Table cell margins */
  readonly margins?: ITableCellMarginOptions;
  /** Table indentation */
  readonly indent?: ITableWidthProperties;
  /** Table floating properties */
  readonly float?: ITableFloatOptions;
  /** Table layout algorithm */
  readonly layout?: TableLayoutType;
  /** Table style reference */
  readonly style?: string;
  /** Table border configuration */
  readonly borders?: ITableBordersOptions;
  /** Table alignment */
  readonly alignment?: AlignmentType;
  /** Right-to-left visual layout */
  readonly visuallyRightToLeft?: boolean;
  /** Cell spacing configuration */
  readonly cellSpacing?: ITableCellSpacingProperties;
}

/**
 * Table row containing cells
 * @param options - Row configuration including cells and properties
 */
class TableRow {
  constructor(options: ITableRowOptions);
}

/**
 * Table row configuration options
 */
interface ITableRowOptions {
  /** Cells in this row */
  readonly children: readonly TableCell[];
  /** Row height specification */
  readonly height?: ITableRowHeightOptions;
  /** Whether row can break across pages */
  readonly cantSplit?: boolean;
  /** Whether this is a header row */
  readonly tableHeader?: boolean;
}

/**
 * Table cell containing paragraphs and content
 * @param options - Cell configuration including content and properties
 */
class TableCell {
  constructor(options: ITableCellOptions);
}

/**
 * Table cell configuration options
 */
interface ITableCellOptions {
  /** Cell content elements */
  readonly children: readonly Paragraph[];
  /** Cell width specification */
  readonly width?: ITableCellWidthOptions;
  /** Cell vertical alignment */
  readonly verticalAlign?: VerticalAlign;
  /** Cell margins */
  readonly margins?: ITableCellMarginOptions;
  /** Cell borders */
  readonly borders?: ITableCellBordersOptions;
  /** Cell shading/background */
  readonly shading?: ITableCellShadingOptions;
  /** Column span for merged cells */
  readonly columnSpan?: number;
  /** Row span for merged cells */
  readonly rowSpan?: number;
}

import { Table, TableRow, TableCell, Paragraph, TextRun } from "docx";

const table = new Table({
  width: {
    size: 100,
    type: WidthType.PERCENTAGE,
  },
  rows: [
    new TableRow({
      children: [
        new TableCell({
          children: [new Paragraph("Header 1")],
          width: { size: 50, type: WidthType.PERCENTAGE },
        }),
        new TableCell({
          children: [new Paragraph("Header 2")],
          width: { size: 50, type: WidthType.PERCENTAGE },
        }),
      ],
    }),
    new TableRow({
      children: [
        new TableCell({
          children: [new Paragraph("Cell 1")],
        }),
        new TableCell({
          children: [new Paragraph("Cell 2")],
        }),
      ],
    }),
  ],
});

/**
 * Symbol character run for special characters
 * @param options - Symbol configuration including character and font
 */
class SymbolRun {
  constructor(options: ISymbolRunOptions);
}

/**
 * Symbol run configuration options
 */
interface ISymbolRunOptions {
  readonly char: string;
  readonly font?: string;
  readonly size?: number;
}

/**
 * Document bookmark for navigation and cross-references
 */
class Bookmark {
  constructor(options: IBookmarkOptions);
}

/**
 * Page break element
 */
class PageBreak {
  constructor();
}

/**
 * Column break element for multi-column layouts
 */
class ColumnBreak {
  constructor();
}

/**
 * Mathematical equation element
 */
class Math {
  constructor(options: IMathOptions);
}

/**
 * Table of contents element
 */
class TableOfContents {
  constructor(options: ITableOfContentsOptions);
}

/**
 * Form checkbox element
 */
class CheckBox {
  constructor(options: ICheckBoxOptions);
}

/**
 * External hyperlink to web URLs
 */
class ExternalHyperlink {
  constructor(options: IExternalHyperlinkOptions);
}

/**
 * Internal hyperlink to bookmarks within document
 */
class InternalHyperlink {
  constructor(options: IInternalHyperlinkOptions);
}

/**
 * External hyperlink configuration
 */
interface IExternalHyperlinkOptions {
  readonly children: readonly TextRun[];
  readonly link: string;
}

/**
 * Internal hyperlink configuration
 */
interface IInternalHyperlinkOptions {
  readonly children: readonly TextRun[];
  readonly anchor: string;
}

import { ExternalHyperlink, InternalHyperlink, TextRun, Bookmark } from "docx";

// External hyperlink
const externalLink = new ExternalHyperlink({
  children: [
    new TextRun({
      text: "Visit our website",
      style: "Hyperlink",
    }),
  ],
  link: "https://example.com",
});

// Internal hyperlink with bookmark
const bookmark = new Bookmark({
  id: "section1",
  children: [new TextRun("Section 1")],
});

const internalLink = new InternalHyperlink({
  children: [new TextRun("Go to Section 1")],
  anchor: "section1",
});