workforce-pay-bill-p/PDF_EXPORT.md

PDF Export Documentation

Overview

The PDF export functionality provides comprehensive report generation capabilities for the WorkForce Pro platform. Users can export data tables, financial reports, and custom reports to PDF format with professional formatting.

Features

Core Capabilities

• Table Export: Export data tables with customizable columns and formatting
• Report Generation: Create multi-section reports with titles, headings, tables, and metadata
• Page Management: Automatic page breaks and pagination
• Customization: Configure page size, orientation, timestamps, and page numbers
• Professional Formatting: Clean, readable output with proper spacing and alignment

Supported Export Formats

• CSV (Comma-Separated Values)
• Excel/XLSX (Microsoft Excel)
• JSON (JavaScript Object Notation)
• PDF (Portable Document Format) ⭐ NEW

Usage

1. Basic Table Export

import { usePDFExport, type PDFTableColumn } from '@/hooks/use-pdf-export'

const { exportTableToPDF } = usePDFExport()

const columns: PDFTableColumn[] = [
  { header: 'Name', key: 'name', align: 'left' },
  { header: 'Amount', key: 'amount', align: 'right', format: (val) => `$${val}` }
]

const data = [
  { name: 'Item 1', amount: 1000 },
  { name: 'Item 2', amount: 2000 }
]

exportTableToPDF(data, columns, {
  filename: 'report',
  title: 'Financial Report',
  orientation: 'portrait',
  pageSize: 'a4'
})

2. Advanced Report with Multiple Sections

import { usePDFExport, type PDFSection } from '@/hooks/use-pdf-export'

const { exportReportToPDF } = usePDFExport()

const sections: PDFSection[] = [
  {
    type: 'heading',
    content: 'Executive Summary'
  },
  {
    type: 'paragraph',
    content: 'This report covers Q4 2025 financial performance.'
  },
  {
    type: 'spacer',
    height: 20
  },
  {
    type: 'divider'
  },
  {
    type: 'table',
    data: tableData,
    columns: tableColumns
  }
]

exportReportToPDF(
  {
    title: 'Q4 2025 Financial Report',
    summary: 'Comprehensive quarterly analysis',
    sections
  },
  {
    filename: 'q4-2025-report',
    orientation: 'landscape',
    includeTimestamp: true,
    includePageNumbers: true
  }
)

3. Using Data Export Hook (All Formats)

import { useDataExport } from '@/hooks/use-data-export'

const { exportData, exportToPDF } = useDataExport()

// Export to any format
exportData(data, { 
  format: 'pdf',
  filename: 'export',
  title: 'Data Export',
  columns: ['id', 'name', 'amount']
})

// Or directly to PDF
exportToPDF(data, {
  filename: 'report',
  title: 'Report Title',
  columnHeaders: {
    id: 'ID',
    name: 'Name',
    amount: 'Amount'
  }
})

Components with PDF Export

1. Reports View

The main Reports view includes a dedicated PDF export button for financial reports:

• Margin analysis tables
• Revenue and cost breakdowns
• Forecast data
• Summary metrics

Location: src/components/ReportsView.tsx

2. Advanced Data Table

All data tables automatically include PDF export in their export menu:

• Timesheets
• Invoices
• Payroll runs
• Expenses
• Compliance documents

Location: src/components/AdvancedDataTable.tsx

3. Custom Report Builder

Custom reports can be exported to PDF with full formatting:

• Grouped data
• Aggregated metrics
• Filtered results

Location: src/components/reports/ReportResultTable.tsx

4. Scheduled Reports

Scheduled automatic reports support PDF as an output format:

• Daily, weekly, monthly, or quarterly reports
• Automatic generation and distribution
• Email delivery support

Location: src/components/ScheduledReportsManager.tsx

Configuration Options

PDF Export Options

interface PDFExportOptions {
  filename?: string              // Output filename (without .pdf extension)
  title?: string                 // Document title
  orientation?: 'portrait' | 'landscape'  // Page orientation
  pageSize?: 'a4' | 'letter' | 'legal'   // Paper size
  includeTimestamp?: boolean     // Add generation timestamp
  includePageNumbers?: boolean   // Add page numbers
  metadata?: {
    author?: string
    subject?: string
    keywords?: string
  }
}

PDF Table Column Options

interface PDFTableColumn {
  header: string                 // Column header text
  key: string                    // Data key
  width?: number                 // Column width (optional)
  align?: 'left' | 'center' | 'right'  // Text alignment
  format?: (value: any) => string      // Custom formatter
}

PDF Section Types

type PDFSection = {
  type: 'title'       // Large title (24pt)
  content: string
} | {
  type: 'heading'     // Section heading (16pt)
  content: string
} | {
  type: 'paragraph'   // Body text (11pt)
  content: string
} | {
  type: 'table'       // Data table
  data: any[]
  columns: PDFTableColumn[]
} | {
  type: 'spacer'      // Vertical spacing
  height?: number
} | {
  type: 'divider'     // Horizontal line
}

Page Sizes and Dimensions

Size	Portrait (W×H)	Landscape (W×H)
A4	595 × 842 pts	842 × 595 pts
Letter	612 × 792 pts	792 × 612 pts
Legal	612 × 1008 pts	1008 × 612 pts

Best Practices

1. Column Configuration

• Use clear, descriptive headers
• Apply right alignment for numbers
• Add format functions for currency, dates, and percentages
• Limit columns to 5-7 for portrait, 8-10 for landscape

2. Report Structure

• Start with a title section
• Add summary paragraphs for context
• Use spacers for visual breathing room
• Include dividers to separate major sections
• Add tables after explanatory text

3. Performance

• Limit tables to 100-200 rows per page for readability
• Use pagination for larger datasets
• Consider generating reports server-side for very large datasets

4. Formatting

• Keep text content under 200 characters per line
• Use consistent spacing (20px standard, 10px tight)
• Test both orientations for different data shapes
• Always include timestamps for audit trails

Examples

Financial Report

const sections: PDFSection[] = [
  { type: 'title', content: 'Monthly Financial Report' },
  { type: 'spacer', height: 10 },
  { type: 'paragraph', content: 'Report Period: January 2025' },
  { type: 'spacer', height: 20 },
  { type: 'heading', content: 'Revenue Summary' },
  { type: 'spacer', height: 10 },
  {
    type: 'table',
    data: revenueData,
    columns: [
      { header: 'Source', key: 'source', align: 'left' },
      { header: 'Amount', key: 'amount', align: 'right', 
        format: (v) => `$${v.toLocaleString()}` }
    ]
  }
]

Timesheet Report

exportTableToPDF(timesheets, [
  { header: 'Worker', key: 'workerName', align: 'left' },
  { header: 'Date', key: 'date', align: 'left' },
  { header: 'Hours', key: 'hours', align: 'right' },
  { header: 'Rate', key: 'rate', align: 'right', 
    format: (v) => `£${v}/hr` },
  { header: 'Total', key: 'amount', align: 'right',
    format: (v) => `£${v.toLocaleString()}` }
], {
  filename: 'timesheet-report',
  title: 'Weekly Timesheet Report',
  orientation: 'landscape'
})

Technical Details

PDF Generation

• Uses PDF 1.4 specification
• Direct PDF generation (no external dependencies)
• Client-side processing
• Automatic page break handling
• Font: Helvetica (standard PDF font)

Browser Compatibility

• Chrome/Edge: Full support
• Firefox: Full support
• Safari: Full support
• Mobile browsers: Download support varies

File Size

• Typical report: 50-200 KB
• Large tables (1000+ rows): 500 KB - 2 MB
• Depends on data density and formatting

Troubleshooting

Common Issues

Issue: PDF not downloading

• Solution: Check browser pop-up blockers
• Solution: Ensure user initiated the action (not auto-triggered)

Issue: Text appears truncated

• Solution: Limit text to 200 characters
• Solution: Use multiple paragraph sections for long content

Issue: Table columns don't fit

• Solution: Switch to landscape orientation
• Solution: Reduce number of columns
• Solution: Use shorter header names

Issue: Page breaks in wrong places

• Solution: Add manual spacers to control layout
• Solution: Reduce table row count per page

Future Enhancements

Planned improvements:

• Chart/graph rendering
• Images and logos
• Custom fonts
• Color customization
• Multi-page tables with headers
• Table of contents
• Watermarks
• Digital signatures
• PDF/A compliance

API Reference

See the following files for complete API documentation:

• src/hooks/use-pdf-export.ts - Core PDF generation hook
• src/hooks/use-data-export.ts - Unified export interface
• src/components/ui/export-button.tsx - Export UI component

Support

For issues or questions:

1. Check this documentation
2. Review code examples in components
3. Check TypeScript types for parameter details
4. Review browser console for error messages