Styling and Formatting

/**
 * Text alignment constants for paragraphs and table content
 */
const AlignmentType = {
  /** Start alignment (left in LTR, right in RTL) */
  START: "start",
  /** Center alignment */
  CENTER: "center",
  /** End alignment (right in LTR, left in RTL) */
  END: "end",
  /** Justified alignment (both left and right) */
  BOTH: "both",
  /** Medium kashida justification */
  MEDIUM_KASHIDA: "mediumKashida",
  /** Distribute alignment */
  DISTRIBUTE: "distribute",
  /** Numeric tab alignment */
  NUM_TAB: "numTab",
  /** High kashida justification */
  HIGH_KASHIDA: "highKashida",
  /** Low kashida justification */
  LOW_KASHIDA: "lowKashida",
  /** Thai distribute alignment */
  THAI_DISTRIBUTE: "thaiDistribute",
  /** Left alignment */
  LEFT: "left",
  /** Right alignment */
  RIGHT: "right",
  /** Justified alignment (alias for BOTH) */
  JUSTIFIED: "both"
} as const;

type AlignmentType = typeof AlignmentType[keyof typeof AlignmentType];

import { Paragraph, AlignmentType } from "docx";

const centeredParagraph = new Paragraph({
  text: "This text is centered",
  alignment: AlignmentType.CENTER,
});

const justifiedParagraph = new Paragraph({
  text: "This paragraph is justified on both sides",
  alignment: AlignmentType.JUSTIFIED,
});

/**
 * Predefined heading style levels
 */
const HeadingLevel = {
  /** Level 1 heading (largest) */
  HEADING_1: "Heading1",
  /** Level 2 heading */
  HEADING_2: "Heading2",
  /** Level 3 heading */
  HEADING_3: "Heading3",
  /** Level 4 heading */
  HEADING_4: "Heading4",
  /** Level 5 heading */
  HEADING_5: "Heading5",
  /** Level 6 heading (smallest) */
  HEADING_6: "Heading6",
  /** Title style */
  TITLE: "Title"
} as const;

type HeadingLevel = typeof HeadingLevel[keyof typeof HeadingLevel];

import { Paragraph, HeadingLevel } from "docx";

const titleParagraph = new Paragraph({
  text: "Document Title",
  heading: HeadingLevel.TITLE,
});

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

const sectionHeading = new Paragraph({
  text: "Section 1.1: Overview",
  heading: HeadingLevel.HEADING_2,
});

/**
 * Text underline style options
 */
const UnderlineType = {
  /** Single line underline */
  SINGLE: "single",
  /** Underline words only (not spaces) */
  WORDS: "words",
  /** Double line underline */
  DOUBLE: "double",
  /** Thick underline */
  THICK: "thick",
  /** Dotted underline */
  DOTTED: "dotted",
  /** Heavy dotted underline */
  DOTTEDHEAVY: "dottedHeavy",
  /** Dashed underline */
  DASH: "dash",
  /** Heavy dashed underline */
  DASHEDHEAVY: "dashedHeavy",
  /** Long dashed underline */
  DASHLONG: "dashLong",
  /** Heavy long dashed underline */
  DASHLONGHEAVY: "dashLongHeavy",
  /** Dot-dash underline */
  DOTDASH: "dotDash",
  /** Heavy dot-dash underline */
  DASHDOTHEAVY: "dashDotHeavy",
  /** Dot-dot-dash underline */
  DOTDOTDASH: "dotDotDash",
  /** Heavy dot-dot-dash underline */
  DASHDOTDOTHEAVY: "dashDotDotHeavy",
  /** Wavy underline */
  WAVE: "wave",
  /** Heavy wavy underline */
  WAVYHEAVY: "wavyHeavy",
  /** Double wavy underline */
  WAVYDOUBLE: "wavyDouble",
  /** No underline */
  NONE: "none"
} as const;

type UnderlineType = typeof UnderlineType[keyof typeof UnderlineType];

import { TextRun, UnderlineType } from "docx";

const underlinedText = new TextRun({
  text: "Important text",
  underline: {
    type: UnderlineType.SINGLE,
    color: "FF0000", // Red underline
  },
});

const wavyUnderline = new TextRun({
  text: "Wavy underlined text",
  underline: {
    type: UnderlineType.WAVE,
    color: "0000FF", // Blue wavy underline
  },
});

/**
 * Border style options for tables and elements
 */
const BorderStyle = {
  /** Single line border */
  SINGLE: "single",
  /** Dash-dot-stroked border */
  DASH_DOT_STROKED: "dashDotStroked",
  /** Dashed border */
  DASHED: "dashed",
  /** Dashed border with small gaps */
  DASH_SMALL_GAP: "dashSmallGap",
  /** Dot-dash border */
  DOT_DASH: "dotDash",
  /** Dot-dot-dash border */
  DOT_DOT_DASH: "dotDotDash",
  /** Dotted border */
  DOTTED: "dotted",
  /** Double line border */
  DOUBLE: "double",
  /** Double wavy border */
  DOUBLE_WAVE: "doubleWave",
  /** Inset border effect */
  INSET: "inset",
  /** No border (nil) */
  NIL: "nil",
  /** No border */
  NONE: "none",
  /** Outset border effect */
  OUTSET: "outset",
  /** Thick border */
  THICK: "thick"
} as const;

type BorderStyle = typeof BorderStyle[keyof typeof BorderStyle];

import { Table, TableRow, TableCell, BorderStyle } from "docx";

const table = new Table({
  borders: {
    top: {
      style: BorderStyle.SINGLE,
      size: 1,
      color: "000000",
    },
    bottom: {
      style: BorderStyle.DOUBLE,
      size: 2,
      color: "000000",
    },
    left: {
      style: BorderStyle.DASHED,
      size: 1,
      color: "808080",
    },
    right: {
      style: BorderStyle.DOTTED,
      size: 1, 
      color: "808080",
    },
  },
  rows: [...],
});

/**
 * Comprehensive formatting options for text runs
 */
interface IRunOptions {
  /** Text content */
  readonly text?: string;
  /** Bold formatting */
  readonly bold?: boolean;
  /** Italic formatting */
  readonly italics?: boolean;
  /** Underline configuration */
  readonly underline?: {
    readonly type?: UnderlineType;
    readonly color?: string;
  };
  /** Text color (hex format without #) */
  readonly color?: string;
  /** Font size in half-points (e.g., 24 = 12pt) */
  readonly size?: number;
  /** Font family name */
  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;
  /** All caps formatting */
  readonly allCaps?: boolean;
  /** Small caps formatting */
  readonly smallCaps?: boolean;
  /** Character spacing adjustment */
  readonly characterSpacing?: number;
  /** Emboss effect */
  readonly emboss?: boolean;
  /** Imprint effect */
  readonly imprint?: boolean;
  /** Shadow effect */
  readonly shadow?: boolean;
  /** Outline effect */
  readonly outline?: boolean;
  /** Style reference */
  readonly style?: string;
}

import { TextRun, UnderlineType } from "docx";

// Basic formatting
const basicRun = new TextRun({
  text: "Basic formatted text",
  bold: true,
  italics: true,
  color: "FF0000",
  size: 24,
});

// Advanced formatting
const advancedRun = new TextRun({
  text: "Advanced formatted text",
  font: "Times New Roman",
  underline: {
    type: UnderlineType.DOUBLE,
    color: "0000FF",
  },
  highlight: "FFFF00", // Yellow highlight
  characterSpacing: 20, // Extra spacing between characters
  shadow: true,
  emboss: true,
});

// Scientific notation
const formulaRun = new TextRun({
  text: "H",
});
const subscriptRun = new TextRun({
  text: "2",
  subScript: true,
});
const normalRun = new TextRun({
  text: "O",
});

/**
 * Paragraph formatting properties interface
 */
interface IParagraphPropertiesOptions {
  /** Text alignment */
  readonly alignment?: AlignmentType;
  /** Heading level */
  readonly heading?: HeadingLevel;
  /** Paragraph style reference */
  readonly style?: string;
  /** Paragraph spacing */
  readonly spacing?: {
    readonly before?: number;
    readonly after?: number;
    readonly line?: number;
    readonly lineRule?: LineRuleType;
  };
  /** Paragraph indentation */
  readonly indent?: {
    readonly left?: number;
    readonly right?: number;
    readonly firstLine?: number;
    readonly hanging?: number;
  };
  /** Paragraph borders */
  readonly border?: {
    readonly top?: IBorderOptions;
    readonly bottom?: IBorderOptions;
    readonly left?: IBorderOptions;
    readonly right?: IBorderOptions;
  };
  /** Paragraph shading/background */
  readonly shading?: {
    readonly fill?: string;
    readonly color?: string;
    readonly type?: ShadingType;
  };
  /** Keep paragraph with next */
  readonly keepNext?: boolean;
  /** Keep paragraph lines together */
  readonly keepLines?: boolean;
  /** Page break before paragraph */
  readonly pageBreakBefore?: boolean;
  /** Widow/orphan control */
  readonly widowControl?: boolean;
  /** Outline level for TOC */
  readonly outlineLevel?: number;
}

/**
 * Border options interface
 */
interface IBorderOptions {
  readonly style?: BorderStyle;
  readonly size?: number;
  readonly color?: string;
  readonly space?: number;
}

import { Paragraph, AlignmentType, BorderStyle } from "docx";

const styledParagraph = new Paragraph({
  text: "Styled paragraph with formatting",
  alignment: AlignmentType.CENTER,
  spacing: {
    before: 200,  // Space before paragraph
    after: 200,   // Space after paragraph
    line: 360,    // Line spacing (1.5x)
  },
  indent: {
    left: 720,    // Left indent (0.5 inch)
    firstLine: 360, // First line indent (0.25 inch)
  },
  border: {
    bottom: {
      style: BorderStyle.SINGLE,
      size: 6,
      color: "000000",
      space: 1,
    },
  },
  shading: {
    fill: "F0F0F0", // Light gray background
  },
});

/**
 * Convert millimeters to twips (twentieths of a point)
 * @param millimeters - Value in millimeters
 * @returns Value in twips
 */
function convertMillimetersToTwip(millimeters: number): number;

/**
 * Convert inches to twips
 * @param inches - Value in inches
 * @returns Value in twips
 */
function convertInchesToTwip(inches: number): number;

/**
 * Measurement type for universal measurements
 */
type UniversalMeasure = `${"-" | ""}${number}${"mm" | "cm" | "in" | "pt" | "pc" | "pi"}`;

/**
 * Percentage type for relative measurements
 */
type Percentage = `${"-" | ""}${number}%`;

import { convertInchesToTwip, convertMillimetersToTwip, Paragraph } from "docx";

const paragraph = new Paragraph({
  text: "Paragraph with converted measurements",
  indent: {
    left: convertInchesToTwip(1),      // 1 inch left indent
    right: convertMillimetersToTwip(25), // 25mm right indent
  },
  spacing: {
    before: convertInchesToTwip(0.5),  // 0.5 inch before
    after: convertInchesToTwip(0.5),   // 0.5 inch after
  },
});

/**
 * Table layout algorithms
 */
const TableLayoutType = {
  /** Automatic width adjustment based on content */
  AUTOFIT: "autofit",
  /** Fixed table layout with specified widths */
  FIXED: "fixed"
} as const;

type TableLayoutType = typeof TableLayoutType[keyof typeof TableLayoutType];

/**
 * Width measurement types for tables and cells
 */
const WidthType = {
  /** Automatic width based on content */
  AUTO: "auto",
  /** Value in twentieths of a point (twips) */
  DXA: "dxa",
  /** No (empty) value */
  NIL: "nil",
  /** Value in percentage */
  PERCENTAGE: "pct"
} as const;

type WidthType = typeof WidthType[keyof typeof WidthType];

import { Table, TableLayoutType, WidthType } from "docx";

const table = new Table({
  layout: TableLayoutType.FIXED,
  width: {
    size: 100,
    type: WidthType.PERCENTAGE,
  },
  rows: [/* table rows */],
});

/**
 * Shading pattern types for backgrounds
 */
const ShadingType = {
  /** Clear/transparent */
  CLEAR: "clear",
  /** Diagonal cross pattern */
  DIAGONAL_CROSS: "diagCross", 
  /** Diagonal stripe pattern */
  DIAGONAL_STRIPE: "diagStripe",
  /** Horizontal cross pattern */
  HORIZONTAL_CROSS: "horzCross",
  /** Horizontal stripe pattern */
  HORIZONTAL_STRIPE: "horzStripe",
  /** No pattern (nil) */
  NIL: "nil",
  /** 5% fill pattern */
  PERCENT_5: "pct5",
  /** 10% fill pattern */
  PERCENT_10: "pct10",
  /** 12.5% fill pattern */
  PERCENT_12: "pct12",
  /** 15% fill pattern */
  PERCENT_15: "pct15",
  /** 20% fill pattern */
  PERCENT_20: "pct20",
  /** 25% fill pattern */
  PERCENT_25: "pct25",
  /** 30% fill pattern */
  PERCENT_30: "pct30",
  /** 35% fill pattern */
  PERCENT_35: "pct35",
  /** 37.5% fill pattern */
  PERCENT_37: "pct37",
  /** 40% fill pattern */
  PERCENT_40: "pct40",
  /** 45% fill pattern */
  PERCENT_45: "pct45",
  /** 50% fill pattern */
  PERCENT_50: "pct50",
  /** 55% fill pattern */
  PERCENT_55: "pct55",
  /** 60% fill pattern */
  PERCENT_60: "pct60",
  /** 62.5% fill pattern */
  PERCENT_62: "pct62",
  /** 65% fill pattern */
  PERCENT_65: "pct65",
  /** 70% fill pattern */
  PERCENT_70: "pct70",
  /** 75% fill pattern */
  PERCENT_75: "pct75",
  /** 80% fill pattern */
  PERCENT_80: "pct80",
  /** 85% fill pattern */
  PERCENT_85: "pct85",
  /** 87.5% fill pattern */
  PERCENT_87: "pct87",
  /** 90% fill pattern */
  PERCENT_90: "pct90",
  /** 95% fill pattern */
  PERCENT_95: "pct95",
  /** Reverse diagonal stripe pattern */
  REVERSE_DIAGONAL_STRIPE: "reverseDiagStripe",
  /** Solid fill */
  SOLID: "solid",
  /** Thin diagonal cross pattern */
  THIN_DIAGONAL_CROSS: "thinDiagCross",
  /** Thin vertical stripe pattern */
  THIN_VERTICAL_STRIPE: "thinVertStripe",
  /** Vertical stripe pattern */
  VERTICAL_STRIPE: "vertStripe"
} as const;

type ShadingType = typeof ShadingType[keyof typeof ShadingType];

import { Paragraph, ShadingType } from "docx";

const shadedParagraph = new Paragraph({
  text: "Paragraph with pattern background",
  shading: {
    fill: "FFFF00",           // Yellow background
    color: "000000",          // Black pattern
    type: ShadingType.PERCENT_25, // 25% pattern density
  },
});