Font Management

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

// Use built-in font
doc.font('Helvetica-Bold');

// Load custom font from file
doc.font('./assets/custom-font.ttf');

// Load font from Buffer
const fontBuffer = fs.readFileSync('./assets/font.otf');
doc.font(fontBuffer);

// Set font with family name and size
doc.font('./assets/custom.ttf', 'Custom Font', 14);

/**
 * Set the current font size
 * @param size - Font size (supports various units)
 * @returns Document instance for chaining
 */
fontSize(size: SizeValue): PDFDocument;

// Set font size in points
doc.fontSize(12);

// Set font size with units
doc.fontSize('14pt');
doc.fontSize('1.2em');
doc.fontSize('16px');

// Chain with text
doc.fontSize(18).text('Large heading', 100, 100);

/**
 * Register a font for use by name
 * @param name - Name to register the font under
 * @param src - Font source (file path or Buffer)
 * @param family - Font family name (optional)
 * @returns Document instance for chaining
 */
registerFont(name: string, src: string | Buffer | ArrayBuffer, family?: string): PDFDocument;

// Register custom fonts
doc.registerFont('MyFont', './assets/custom.ttf')
   .registerFont('MyBold', './assets/custom-bold.ttf')
   .registerFont('MyItalic', './assets/custom-italic.ttf');

// Use registered fonts by name
doc.font('MyFont').text('Regular text', 100, 100);
doc.font('MyBold').text('Bold text', 100, 120);
doc.font('MyItalic').text('Italic text', 100, 140);

/**
 * Get current line height
 * @param includeGap - Whether to include line gap in calculation
 * @returns Current line height in points
 */
currentLineHeight(includeGap?: boolean): number;

/**
 * Convert size value to points
 * @param size - Size value to convert
 * @param defaultValue - Default value if size is invalid
 * @param page - Page for percentage calculations (optional)
 * @param percentageWidth - Width for percentage calculations (optional)
 * @returns Size in points
 */
sizeToPoint(size: SizeValue, defaultValue?: number, page?: PDFPage, percentageWidth?: number): number;

// Get line height for current font
const lineHeight = doc.currentLineHeight();
console.log(`Current line height: ${lineHeight}pt`);

// Include line gap in calculation
const lineHeightWithGap = doc.currentLineHeight(true);

// Convert different size units to points
const pointSize = doc.sizeToPoint('1em');      // Convert 1em to points
const pxSize = doc.sizeToPoint('16px');        // Convert 16px to points
const percentSize = doc.sizeToPoint('120%');   // Convert 120% to points

// Use in layout calculations
const spacing = doc.currentLineHeight() * 1.5;
doc.text('Line 1', 100, 100);
doc.text('Line 2', 100, 100 + spacing);

type SizeValue = number | string;

// Supported size unit strings
type SizeUnit = 
  | 'pt'    // Points (default)
  | 'px'    // Pixels
  | 'em'    // Em units (relative to current font size)
  | 'rem'   // Root em units
  | 'in'    // Inches
  | 'cm'    // Centimeters  
  | 'mm'    // Millimeters
  | 'pc'    // Picas
  | 'ex'    // Ex units (x-height)
  | 'ch'    // Character units (0-width)
  | 'vw'    // Viewport width percentage
  | 'vh'    // Viewport height percentage
  | 'vmin'  // Viewport minimum dimension percentage
  | 'vmax'  // Viewport maximum dimension percentage
  | '%';    // Percentage

// Font source types
type FontSource = string | Buffer | ArrayBuffer;

// Load multiple font weights/styles
doc.registerFont('Inter-Regular', './fonts/Inter-Regular.ttf')
   .registerFont('Inter-Bold', './fonts/Inter-Bold.ttf')
   .registerFont('Inter-Italic', './fonts/Inter-Italic.ttf');

// Use semantic naming
doc.registerFont('body', './fonts/source-sans-pro.ttf')
   .registerFont('heading', './fonts/playfair-display.ttf')
   .registerFont('code', './fonts/fira-code.ttf');

// Only characters used in the document will be included
doc.font('./fonts/large-font.ttf')
   .text('Only these characters will be embedded: Hello World!');

try {
  doc.font('./fonts/missing-font.ttf');
} catch (error) {
  console.error('Font loading failed:', error.message);
  // Fallback to built-in font
  doc.font('Helvetica');
}