Text Rendering

/**
 * Render text with comprehensive options
 * @param text - Text to render
 * @param x - X coordinate (optional)
 * @param y - Y coordinate (optional)
 * @param options - Text rendering options
 * @returns Document instance for chaining
 */
text(text: string, x?: number, y?: number, options?: TextOptions): PDFDocument;

interface TextOptions {
  /** Text width for wrapping */
  width?: number;
  /** Maximum text height */
  height?: number;
  /** Text alignment */
  align?: 'left' | 'center' | 'right' | 'justify';
  /** Baseline alignment */
  baseline?: 'alphabetic' | 'top' | 'hanging' | 'middle' | 'ideographic' | 'bottom' | 'svg-middle' | 'svg-central' | 'mathematical' | number;
  /** Number of columns */
  columns?: number;
  /** Gap between columns */
  columnGap?: number;
  /** Text indent */
  indent?: number;
  /** Gap between paragraphs */
  paragraphGap?: number;
  /** Gap between lines */
  lineGap?: number;
  /** Extra word spacing */
  wordSpacing?: number;
  /** Extra character spacing */
  characterSpacing?: number;
  /** Horizontal text scaling (percentage) */
  horizontalScaling?: number;
  /** Enable text fill */
  fill?: boolean;
  /** Enable text stroke */
  stroke?: boolean;
  /** Text fill color */
  fillColor?: ColorValue;
  /** Text stroke color */
  strokeColor?: ColorValue;
  /** Add underline */
  underline?: boolean;
  /** Add strikethrough */
  strike?: boolean;
  /** Add hyperlink */
  link?: string;
  /** Add internal link */
  goTo?: string;
  /** Add named destination */
  destination?: string;
  /** Continue text on next call */
  continued?: boolean;
  /** OpenType font features */
  features?: string[];
  /** Text rotation in degrees */
  rotation?: number;
  /** Oblique text (skew angle or boolean) */
  oblique?: number | boolean;
}

// Basic text
doc.text('Hello World', 100, 100);

// Text with wrapping and alignment
doc.text('This is a long paragraph that will wrap to multiple lines within the specified width.', 100, 150, {
  width: 400,
  align: 'justify'
});

// Multi-column text
doc.text('Lorem ipsum...', 100, 200, {
  width: 400,
  columns: 2,
  columnGap: 20
});

// Styled text with effects
doc.text('Important Notice', 100, 300, {
  fill: true,
  fillColor: 'red',
  underline: true,
  fontSize: 18
});

// Text with hyperlink
doc.text('Visit our website', 100, 350, {
  link: 'https://example.com',
  fillColor: 'blue',
  underline: true
});

/**
 * Calculate the width of a string
 * @param string - String to measure
 * @param options - Text options affecting measurement
 * @returns Width in points
 */
widthOfString(string: string, options?: TextOptions): number;

/**
 * Calculate the height of text
 * @param text - Text to measure
 * @param options - Text options affecting measurement
 * @returns Height in points
 */
heightOfString(text: string, options?: TextOptions): number;

/**
 * Get bounding box of text
 * @param string - String to measure
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param options - Text options
 * @returns Bounding box
 */
boundsOfString(string: string, x?: number, y?: number, options?: TextOptions): BoundingBox;

interface BoundingBox {
  x: number;
  y: number;
  width: number;
  height: number;
}

// Measure text for positioning
const text = 'Sample Text';
const width = doc.widthOfString(text);
const height = doc.heightOfString(text);

// Center text on page
const pageWidth = doc.page.width;
const centerX = (pageWidth - width) / 2;
doc.text(text, centerX, 100);

// Check if text fits in area
const maxWidth = 200;
if (doc.widthOfString('Long text content') > maxWidth) {
  // Use text wrapping
  doc.text('Long text content', 100, 100, { width: maxWidth });
}

/**
 * Set current font
 * @param src - Font source (path, Buffer, or font name)
 * @param family - Font family name
 * @param size - Font size
 * @returns Document instance for chaining
 */
font(src: string | Buffer, family?: string, size?: number): PDFDocument;

/**
 * Set font size with flexible units
 * @param size - Font size with optional units
 * @returns Document instance for chaining
 */
fontSize(size: SizeValue): PDFDocument;

/**
 * Register a font for later use
 * @param name - Font name for referencing
 * @param src - Font source
 * @param family - Font family name
 * @returns Document instance for chaining
 */
registerFont(name: string, src: string | Buffer, family?: string): PDFDocument;

/**
 * Get current line height
 * @param includeGap - Include line gap in calculation
 * @returns Line height in points
 */
currentLineHeight(includeGap?: boolean): number;

type SizeValue = number | `${number}` | `${number}${SizeUnit}`;
type SizeUnit = 'pt' | 'in' | 'px' | 'cm' | 'mm' | 'pc' | 'em' | 'ex' | 'ch' | 'rem' | 'vw' | 'vh' | 'vmin' | 'vmax' | '%';

// Use built-in fonts
doc.font('Helvetica', 12)
   .text('Standard font', 100, 100);

doc.font('Times-Bold', 16)
   .text('Bold serif font', 100, 120);

// Load custom font
doc.registerFont('MyFont', './fonts/custom.ttf');
doc.font('MyFont', 14)
   .text('Custom font text', 100, 140);

// Font size with units
doc.fontSize('14pt')
   .text('14 point text', 100, 160);

doc.fontSize('1.2em')
   .text('1.2em text', 100, 180);

// Get line height for spacing
const lineHeight = doc.currentLineHeight();
doc.text('Line 1', 100, 200)
   .text('Line 2', 100, 200 + lineHeight);

/**
 * Move cursor down by specified number of lines
 * @param lines - Number of lines to move (default: 1)
 * @returns Document instance for chaining
 */
moveDown(lines?: number): PDFDocument;

/**
 * Move cursor up by specified number of lines
 * @param lines - Number of lines to move (default: 1)
 * @returns Document instance for chaining
 */
moveUp(lines?: number): PDFDocument;

/**
 * Set line gap for future text
 * @param gap - Gap between lines in points
 * @returns Document instance for chaining
 */
lineGap(gap: number): PDFDocument;

doc.text('First line', 100, 100)
   .moveDown()
   .text('Second line (default spacing)')
   .moveDown(2)
   .text('Third line (double spacing)');

// Custom line gap
doc.lineGap(5)
   .text('Text with 5pt line gap', 100, 200)
   .moveDown()
   .text('Next line with same gap');

/**
 * Render bulleted or numbered list
 * @param list - Array of list items
 * @param x - X coordinate
 * @param y - Y coordinate  
 * @param options - List options
 * @param wrapper - Text wrapper instance
 * @returns Document instance for chaining
 */
list(list: string[], x?: number, y?: number, options?: ListOptions, wrapper?: any): PDFDocument;

interface ListOptions extends TextOptions {
  /** List bullet character or numbering */
  bulletRadius?: number;
  /** Text indent for list items */
  textIndent?: number;
  /** Bullet indent */
  bulletIndent?: number;
}

// Bulleted list
doc.list([
  'First item',
  'Second item',
  'Third item'
], 100, 100);

// Numbered list with custom options
doc.list([
  'Introduction',
  'Methods',
  'Results',
  'Conclusion'
], 100, 200, {
  textIndent: 20,
  bulletIndent: 10
});

/**
 * Convert size value to points
 * @param size - Size with optional units
 * @param defaultValue - Default value if size is invalid
 * @param page - Page context for percentage calculations
 * @param percentageWidth - Reference width for percentage
 * @returns Size in points
 */
sizeToPoint(size: SizeValue, defaultValue?: number, page?: any, percentageWidth?: number): number;

// Standard fonts (no loading required)
type StandardFont = 
  | 'Courier' | 'Courier-Bold' | 'Courier-Oblique' | 'Courier-BoldOblique'
  | 'Helvetica' | 'Helvetica-Bold' | 'Helvetica-Oblique' | 'Helvetica-BoldOblique'  
  | 'Times-Roman' | 'Times-Bold' | 'Times-Italic' | 'Times-BoldItalic'
  | 'Symbol' | 'ZapfDingbats';