Document Outline

/**
 * Access the document outline for adding bookmarks
 * Available as a property on the PDFDocument instance
 */
document.outline: PDFOutline;

interface PDFOutline {
  /**
   * Add an item to the document outline
   * @param title - Display title for the bookmark
   * @param options - Outline item options
   * @returns The created outline item
   */
  addItem(title: string, options?: OutlineOptions): PDFOutlineItem;
}

interface OutlineOptions {
  /** Whether the outline item is expanded by default */
  expanded?: boolean;
  /** Named destination to link to */
  destination?: string;
  /** Page number to link to (0-indexed) */
  page?: number;
  /** Specific coordinates on the page */
  x?: number;
  y?: number;
  /** Zoom level for the destination view */
  zoom?: number;
}

interface PDFOutlineItem {
  /** The title of this outline item */
  title: string;
  /** Child outline items */
  children: PDFOutlineItem[];
  /** Add a child item to this outline item */
  addItem(title: string, options?: OutlineOptions): PDFOutlineItem;
}

// Create basic outline structure
const chapter1 = doc.outline.addItem('Chapter 1: Introduction');
const chapter2 = doc.outline.addItem('Chapter 2: Getting Started');
const chapter3 = doc.outline.addItem('Chapter 3: Advanced Topics');

// Add sub-sections to chapters
chapter1.addItem('1.1 Overview');
chapter1.addItem('1.2 Requirements');
chapter1.addItem('1.3 Installation');

chapter2.addItem('2.1 Basic Usage');
chapter2.addItem('2.2 Configuration');

chapter3.addItem('3.1 Advanced Features');
chapter3.addItem('3.2 Best Practices');

/**
 * Add a named destination for navigation
 * @param name - Unique name for the destination
 * @param type - Destination type ('XYZ', 'Fit', 'FitH', etc.)
 * @param x - X coordinate (optional)
 * @param y - Y coordinate (optional)  
 * @param zoom - Zoom level (optional)
 * @returns Document instance for chaining
 */
addNamedDestination(name: string, type?: string, x?: number, y?: number, zoom?: number): PDFDocument;

// Create named destinations for different sections
doc.addNamedDestination('intro', 'XYZ', 100, 700, 1.0);
doc.addNamedDestination('chapter1', 'FitH', null, 600);
doc.addNamedDestination('conclusion', 'Fit');

// Link outline items to named destinations
doc.outline.addItem('Introduction', { destination: 'intro' });
doc.outline.addItem('Chapter 1', { destination: 'chapter1' });
doc.outline.addItem('Conclusion', { destination: 'conclusion' });

// Create comprehensive document outline
const titlePage = doc.outline.addItem('Title Page', { page: 0 });

const toc = doc.outline.addItem('Table of Contents', { page: 1 });

const part1 = doc.outline.addItem('Part I: Fundamentals', { expanded: true });
const chapter1 = part1.addItem('Chapter 1: Introduction');
chapter1.addItem('1.1 What is PDFKit?', { destination: 'section_1_1' });
chapter1.addItem('1.2 Key Features', { destination: 'section_1_2' });
chapter1.addItem('1.3 Getting Started', { destination: 'section_1_3' });

const chapter2 = part1.addItem('Chapter 2: Basic Usage');
chapter2.addItem('2.1 Creating Documents', { destination: 'section_2_1' });
chapter2.addItem('2.2 Adding Content', { destination: 'section_2_2' });

const part2 = doc.outline.addItem('Part II: Advanced Topics', { expanded: false });
const chapter3 = part2.addItem('Chapter 3: Advanced Features');
chapter3.addItem('3.1 Custom Fonts', { destination: 'section_3_1' });
chapter3.addItem('3.2 Vector Graphics', { destination: 'section_3_2' });
chapter3.addItem('3.3 Interactive Elements', { destination: 'section_3_3' });

const appendix = doc.outline.addItem('Appendices');
appendix.addItem('Appendix A: API Reference', { destination: 'appendix_a' });
appendix.addItem('Appendix B: Examples', { destination: 'appendix_b' });

// Create outline with mixed expansion states
const userGuide = doc.outline.addItem('User Guide', { expanded: true });
const quickStart = userGuide.addItem('Quick Start', { expanded: true });
const advanced = userGuide.addItem('Advanced Usage', { expanded: false });

// Link to specific page coordinates
const figures = doc.outline.addItem('List of Figures');
figures.addItem('Figure 1: Architecture', { 
  page: 5, 
  x: 100, 
  y: 400,
  zoom: 1.5 
});
figures.addItem('Figure 2: Workflow', { 
  page: 8, 
  x: 50, 
  y: 300,
  zoom: 1.25 
});

// Use consistent naming conventions
const manual = doc.outline.addItem('User Manual');

// Group related sections
const installation = manual.addItem('Installation');
installation.addItem('System Requirements');
installation.addItem('Download and Install');
installation.addItem('Configuration');

const usage = manual.addItem('Usage');
usage.addItem('Basic Operations');
usage.addItem('Advanced Features');
usage.addItem('Troubleshooting');

// Build outline from content structure
const sections = [
  { title: 'Introduction', page: 0 },
  { title: 'Installation', page: 2 },
  { title: 'Usage', page: 5 },
  { title: 'API Reference', page: 10 }
];

sections.forEach(section => {
  doc.outline.addItem(section.title, { page: section.page });
});

// Create destinations as content is added
doc.addNamedDestination('fig_1', 'XYZ', 100, 400, 1.0);
doc.text('Figure 1: System Architecture', 100, 380);

// Reference in outline
doc.outline.addItem('Figures')
  .addItem('Figure 1: System Architecture', { destination: 'fig_1' });