Page Designer - Reports Documentation

Version: 2.0
Last Updated: March 13, 2026
Scope: Report design, multi-page reports, print-optimized layouts, document generation

---

Overview

The Report Designer enables creation of professional, print-optimized reports with:

• Multi-page reports with headers, footers, and page breaks
• Print optimization for PDF, paper, and digital distribution
• Template components including tables, charts, and data visualization
• Special elements like barcodes, QR codes, and watermarks
• Dynamic content from data sources
• Export to PDF, Excel, Word

---

Page Mode: "report"

All report configurations must set pageMode: "report" in the root configuration.

interface ReportPage {
  id: string;
  name: string;
  pageMode: 'report';
  components: ReportComponent[];
  settings?: ReportSettings;
}

interface ReportSettings {
  pageSize: 'A4' | 'Letter' | 'A3' | 'Legal' | 'A5';
  orientation: 'portrait' | 'landscape';
  margins: {
    top: string;      // e.g., "1in" or "2.5cm"
    right: string;
    bottom: string;
    left: string;
  };
  headerFooter?: {
    showHeader: boolean;
    showFooter: boolean;
  };
  printSettings?: {
    paperSource?: string;
    colorMode: 'color' | 'grayscale' | 'blackAndWhite';
    quality: 'draft' | 'normal' | 'high';
  };
}

---

Report Page Settings

Page Configuration

Page Dimensions:
  - A4 (210mm x 297mm) - Default, standard international
  - Letter (8.5in x 11in) - North America
  - A3 (297mm x 420mm) - Large documents
  - Legal (8.5in x 14in) - Legal documents
  - A5 (148mm x 210mm) - Small pages

Orientation:
  - portrait: 210mm x 297mm (A4)
  - landscape: 297mm x 210mm (A4)

Margins:
  - Standard: top: 1in, right: 1in, bottom: 1in, left: 1in
  - Narrow: top: 0.5in, margins: 0.75in
  - Custom: Set individual sides

Example:

{
  pageSize: 'A4',
  orientation: 'portrait',
  margins: {
    top: '1in',
    right: '1in',
    bottom: '1.2in',  // Extra space for footer
    left: '1in'
  },
  headerFooter: {
    showHeader: true,
    showFooter: true
  },
  printSettings: {
    colorMode: 'color',
    quality: 'high'
  }
}

---

Header & Footer Templates

1. Page Header

Type: 'page-header'
Purpose: Repeating header on each page
When to Use: Report title, date, company info
Parameters:
  - content: string | Component[] | header content
  - height?: string | "0.5in"
  - backgroundColor?: string
  - borderBottom?: boolean | true
  - alignment: 'left' | 'center' | 'right'
  - padding?: string | "10px"

Example: Company Header
  {
    id: 'reportHeader',
    type: 'page-header',
    height: '0.75in',
    alignment: 'center',
    components: [
      {
        type: 'heading',
        level: 'h2',
        text: 'Annual Report 2024'
      }
    ]
  }

Example: Simple Header with Logo
  {
    id: 'headerWithLogo',
    type: 'page-header',
    components: [
      {
        type: 'image',
        src: '/company-logo.png',
        height: '0.5in',
        width: 'auto'
      }
    ]
  }

2. Page Footer

Type: 'page-footer'
Purpose: Repeating footer on each page
When to Use: Page number, date, company name
Parameters:
  - content: Component[] | footer content
  - height?: string | "0.4in"
  - backgroundColor?: string
  - borderTop?: boolean | true
  - padding?: string | "10px"

Example: Standard Footer
  {
    id: 'reportFooter',
    type: 'page-footer',
    borderTop: true,
    components: [
      {
        type: 'content',
        components: [
          {
            type: 'paragraph',
            text: 'Page {{pageNumber}} of {{totalPages}} | Generated: {{currentDate}}'
          }
        ]
      }
    ]
  }

Example: Footer with Multiple Elements
  {
    id: 'advancedFooter',
    type: 'page-footer',
    components: [
      {
        type: 'text-content',
        format: 'html',
        content: '<div style="display: flex; justify-content: space-between;"><span>Report ID: #12345</span><span>Page {{pageNumber}}</span><span>© 2024 Company</span></div>'
      }
    ]
  }

---

Page Break & Structure

3. Page Break

Type: 'page-break'
Purpose: Force a new page
When to Use: Section breaks, separate tables
Parameters:
  - style?: 'break-before' | 'break-after'

Example:
  {
    id: 'pageBreak1',
    type: 'page-break'
  }

4. Section (Content Grouping)

Type: 'section'
Purpose: Group related content
When to Use: Logical content grouping
Parameters:
  - title?: string | section title
  - level: 1 | 2 | 3 | hierarchy level
  - startNewPage?: boolean | false
  - components: Component[] | section content

Example:
  {
    id: 'section2',
    type: 'section',
    title: 'Financial Summary',
    level: 1,
    components: [/* content */]
  }

---

Data Display Components

5. Report Table

Type: 'report-table'
Purpose: Data table for reports
When to Use: Tabular data, data summary
Parameters:
  - title?: string | table title
  - dataSource: string | API endpoint or resource
  - columns: {
      field: string;           # Field name from data
      header: string;          # Column header text
      width?: string;          # Column width
      align?: 'left' | 'center' | 'right';
      format?: 'currency' | 'date' | 'number' | 'percent';
      footer?: 'sum' | 'avg' | 'count' | 'max' | 'min';
    }[]
  - pageBreakRows?: number | break table across pages
  - alternateRowColor?: boolean | false
  - striped?: boolean | true (zebra striping)
  - bordered?: boolean | true

Example: Sales Report Table
  {
    id: 'salesTable',
    type: 'report-table',
    title: 'Sales by Region',
    dataSource: '/api/sales-data',
    striped: true,
    bordered: true,
    columns: [
      {
        field: 'region',
        header: 'Region',
        width: '20%',
        align: 'left'
      },
      {
        field: 'revenue',
        header: 'Revenue',
        width: '20%',
        align: 'right',
        format: 'currency'
      },
      {
        field: 'growth',
        header: 'Growth %',
        width: '15%',
        align: 'right',
        format: 'percent'
      },
      {
        field: 'units_sold',
        header: 'Units Sold',
        width: '15%',
        align: 'center',
        format: 'number'
      }
    ]
  }

Example: Financial Summary Table
  {
    id: 'summaryTable',
    type: 'report-table',
    dataSource: '/api/financial-summary',
    columns: [
      { field: 'account', header: 'Account', width: '40%' },
      {
        field: 'amount',
        header: 'Amount',
        width: '20%',
        align: 'right',
        format: 'currency',
        footer: 'sum'  # Show total
      },
      {
        field: 'percentage',
        header: '% of Total',
        width: '20%',
        format: 'percent',
        footer: 'sum'
      }
    ]
  }

6. Report Chart

Type: 'report-chart'
Purpose: Chart for report visualization
When to Use: Trends, comparisons, visualization
Parameters:
  - title?: string | chart title
  - type: 'line' | 'bar' | 'pie' | 'doughnut' | 'area' | 'scatter'
  - dataSource: string | data source
  - xAxisField: string | x-axis data field
  - yAxisField: string | y-axis data field
  - width?: string | "100%"
  - height?: string | "3in"
  - showLegend?: boolean | true
  - showGrid?: boolean | true
  - colors?: string[] | custom colors

Example: Revenue Trend Chart
  {
    id: 'revenueChart',
    type: 'report-chart',
    title: 'Revenue Trend',
    type: 'line',
    dataSource: '/api/revenue-monthly',
    xAxisField: 'month',
    yAxisField: 'revenue',
    height: '3in',
    showLegend: true,
    colors: ['#1976D2', '#388E3C']
  }

Example: Sales Distribution Pie Chart
  {
    id: 'salesPie',
    type: 'report-chart',
    title: 'Sales by Product Category',
    type: 'pie',
    dataSource: '/api/sales-by-category',
    xAxisField: 'category',
    yAxisField: 'sales_amount',
    height: '2.5in'
  }

---

Special Elements

7. Barcode

Type: 'barcode'
Purpose: Generate barcodes
When to Use: Product codes, tracking numbers
Parameters:
  - value: string | barcode value
  - format: 'CODE128' | 'CODE39' | 'EAN13' | 'UPC'
  - width?: string | "2in"
  - height?: string | "0.5in"
  - showValue?: boolean | true (display text)
  - align?: 'left' | 'center' | 'right'

Example: Product Barcode
  {
    id: 'productBarcode',
    type: 'barcode',
    value: 'EAN{{orderNumber}}',  # Dynamic value
    format: 'EAN13',
    width: '2in',
    height: '0.5in',
    showValue: true,
    align: 'center'
  }

8. QR Code

Type: 'qr-code'
Purpose: Generate QR codes
When to Use: URLs, contact info, tracking
Parameters:
  - value: string | QR code content
  - size?: string | "1in" (width = height)
  - errorCorrection?: 'L' | 'M' | 'Q' | 'H'
  - align?: 'left' | 'center' | 'right'
  - label?: string | text below QR code

Example: Invoice QR Code
  {
    id: 'invoiceQR',
    type: 'qr-code',
    value: 'https://example.com/invoice/{{invoiceId}}',
    size: '1.2in',
    errorCorrection: 'H',
    align: 'center',
    label: 'Scan for details'
  }

Example: Contact QR Code
  {
    id: 'contactQR',
    type: 'qr-code',
    value: 'BEGIN:VCARD\nFN:John Doe\nTEL:+1-555-1234\nEND:VCARD',
    size: '1in'
  }

9. Watermark

Type: 'watermark'
Purpose: Background text (DRAFT, CONFIDENTIAL, etc.)
When to Use: Draft documents, confidential marking
Parameters:
  - text: string | watermark text
  - opacity?: number | 0-100
  - fontSize?: string | large font
  - color?: string | watermark color
  - angle?: number | -45 (diagonal)

Example:
  {
    id: 'draftWatermark',
    type: 'watermark',
    text: 'DRAFT',
    opacity: 30,
    fontSize: '60pt',
    color: '#CCCCCC',
    angle: -45
  }

---

Complete Report Examples

Example 1: Invoice Report

{
  id: 'invoiceReport',
  pageMode: 'report',
  name: 'Invoice',
  settings: {
    pageSize: 'A4',
    orientation: 'portrait',
    margins: {
      top: '0.5in',
      right: '0.75in',
      bottom: '0.75in',
      left: '0.75in'
    },
    headerFooter: {
      showHeader: false,
      showFooter: true
    }
  },
  components: [
    // Company Header
    {
      id: 'invoiceHeader',
      type: 'content',
      padding: '20px 0',
      components: [
        {
          type: 'heading',
          level: 'h1',
          text: 'INVOICE',
          align: 'center'
        }
      ]
    },
    
    // Company Info & Invoice Details (Two Column)
    {
      id: 'invoiceInfo',
      type: 'content',
      margin: '30px 0',
      components: [
        {
          type: 'content',
          components: [
            {
              type: 'heading',
              level: 'h3',
              text: 'From'
            },
            {
              type: 'paragraph',
              text: 'Your Company Name\n123 Business St\nCity, State 12345\nphone@example.com'
            }
          ]
        }
      ]
    },
    
    // Invoice Details Table
    {
      id: 'invoiceDetails',
      type: 'report-table',
      title: 'Invoice Items',
      dataSource: '/api/invoice/{{invoiceId}}/items',
      columns: [
        { field: 'description', header: 'Description', width: '40%' },
        { field: 'quantity', header: 'Qty', width: '15%', align: 'center' },
        { field: 'unit_price', header: 'Unit Price', width: '20%', align: 'right', format: 'currency' },
        { field: 'amount', header: 'Amount', width: '20%', align: 'right', format: 'currency', footer: 'sum' }
      ]
    },
    
    // Page Break
    {
      id: 'pageBreak1',
      type: 'page-break'
    },
    
    // Terms & Conditions
    {
      id: 'termsSection',
      type: 'section',
      title: 'Terms & Conditions',
      components: [
        {
          type: 'paragraph',
          text: 'Payment is due within 30 days. Late payments subject to 1.5% monthly interest.'
        }
      ]
    }
  ]
}

Example 2: Financial Report with Chart

{
  id: 'financialReport',
  pageMode: 'report',
  name: 'Annual Financial Report',
  settings: {
    pageSize: 'A4',
    orientation: 'landscape',
    margins: {
      top: '1in',
      right: '1in',
      bottom: '1in',
      left: '1in'
    }
  },
  components: [
    // Report Title
    {
      id: 'titleSection',
      type: 'section',
      title: 'Annual Financial Report 2024',
      level: 1,
      components: [
        {
          type: 'paragraph',
          text: 'Prepared for: Board of Directors'
        }
      ]
    },
    
    // Executive Summary
    {
      id: 'summarySection',
      type: 'section',
      title: 'Executive Summary',
      level: 2,
      components: [
        {
          type: 'paragraph',
          text: 'This report summarizes financial performance...'
        }
      ]
    },
    
    // Page Break
    {
      id: 'pageBreak1',
      type: 'page-break'
    },
    
    // Revenue Section with Chart
    {
      id: 'revenueSection',
      type: 'section',
      title: 'Revenue Analysis',
      level: 2,
      components: [
        {
          type: 'report-chart',
          title: 'Monthly Revenue Trend',
          type: 'line',
          dataSource: '/api/reports/monthly-revenue',
          xAxisField: 'month',
          yAxisField: 'revenue',
          height: '3.5in'
        },
        
        {
          type: 'report-table',
          title: 'Revenue Summary',
          dataSource: '/api/reports/revenue-summary',
          columns: [
            { field: 'category', header: 'Category', width: '30%' },
            { field: 'q1', header: 'Q1', align: 'right', format: 'currency' },
            { field: 'q2', header: 'Q2', align: 'right', format: 'currency' },
            { field: 'q3', header: 'Q3', align: 'right', format: 'currency' },
            { field: 'q4', header: 'Q4', align: 'right', format: 'currency' }
          ]
        }
      ]
    },
    
    // Page Break
    {
      id: 'pageBreak2',
      type: 'page-break'
    },
    
    // Expense Section with Pie Chart
    {
      id: 'expenseSection',
      type: 'section',
      title: 'Expense Breakdown',
      level: 2,
      components: [
        {
          type: 'report-chart',
          title: 'Expenses by Category',
          type: 'pie',
          dataSource: '/api/reports/expense-breakdown',
          xAxisField: 'category',
          yAxisField: 'amount',
          height: '3.5in'
        }
      ]
    },
    
    // Footer will be added automatically
  ]
}

Example 3: Shipping Label with Barcode

{
  id: 'shippingLabel',
  pageMode: 'report',
  name: 'Shipping Label',
  settings: {
    pageSize: 'Letter',
    orientation: 'portrait',
    margins: {
      top: '0.25in',
      right: '0.25in',
      bottom: '0.25in',
      left: '0.25in'
    }
  },
  components: [
    // Ship To Section (Large)
    {
      id: 'shipToSection',
      type: 'content',
      padding: '20px',
      backgroundColor: '#F5F5F5',
      components: [
        {
          type: 'heading',
          level: 'h4',
          text: 'SHIP TO'
        },
        {
          type: 'paragraph',
          text: '{{customerName}}\n{{address}}\n{{city}}, {{state}} {{zip}}\n{{country}}',
          fontSize: '14pt'
        }
      ]
    },
    
    // Barcode Section
    {
      id: 'barcodeSection',
      type: 'content',
      padding: '20px',
      align: 'center',
      components: [
        {
          type: 'barcode',
          value: '{{trackingNumber}}',
          format: 'CODE128',
          width: '3in',
          height: '0.75in',
          showValue: true
        },
        {
          type: 'paragraph',
          text: 'Tracking: {{trackingNumber}}',
          fontSize: '12pt',
          margin: '10px 0 0 0'
        }
      ]
    },
    
    // Shipping Details
    {
      id: 'shippingDetails',
      type: 'report-table',
      dataSource: '/api/shipment/{{shipmentId}}/items',
      columns: [
        { field: 'sku', header: 'SKU' },
        { field: 'description', header: 'Description' },
        { field: 'qty', header: 'Qty', align: 'center' }
      ]
    }
  ]
}

---

Print Optimization Guide

Color Mode Selection

color        - Full color printing
grayscale    - Black & white with shades of gray
blackAndWhite - Pure black ink only

Print Quality Settings

draft   - Fast printing, lower quality (for proofs)
normal  - Balanced quality and speed
high    - Best quality, slower printing

Page Setup for Different Scenarios

Business Documents (Letterhead)

{
  pageSize: 'Letter',
  orientation: 'portrait',
  margins: { top: '1in', right: '1in', bottom: '1in', left: '1.25in' }  // Extra left for punch holes
}

Landscape Reports (Financial)

{
  pageSize: 'A4',
  orientation: 'landscape',
  margins: { top: '0.75in', right: '0.75in', bottom: '0.75in', left: '0.75in' }
}

Small Labels (Shipping, Product)

{
  pageSize: 'A5',
  orientation: 'portrait',
  margins: { top: '0.25in', right: '0.25in', bottom: '0.25in', left: '0.25in' }
}

---

Dynamic Content & Data Binding

Template Variables

{{fieldName}}         - Simple value substitution
{{array[0].property}} - Nested property access
{{formula(x, y)}}     - Formula evaluation
{{currentDate}}       - Current date
{{pageNumber}}        - Current page number
{{totalPages}}        - Total number of pages

Example: Dynamic Invoice

components: [
  {
    type: 'paragraph',
    text: 'Invoice #{{invoiceNumber}} dated {{invoiceDate | formatDate:"MMM DD, YYYY"}}'
  }
]

---

Export Formats

Reports can be exported to multiple formats:

PDF:
  - Preserves all formatting and layout
  - Recommended for distribution and printing
  - Supports barcodes and QR codes

EXCEL:
  - Table data exported to worksheets
  - Supports multiple sheets
  - Good for data analysis

WORD:
  - Editable document format
  - Preserves structure and styling
  - Suitable for further customization

PNG/JPG:
  - Image-based export
  - Use for embedding in other documents
  - Lower quality than PDF

---

Best Practices

1. Margins: Set appropriate margins for binding and printing (0.5-1 inch)
2. Page Breaks: Use page breaks to separate logical sections
3. Headers/Footers: Include page numbers and dates for reference
4. Table Height: Prevent table rows from breaking awkwardly across pages
5. Colors: Test print output in both color and grayscale
6. Fonts: Use standard fonts for consistent rendering
7. Images: Optimize image resolution (150-300 DPI for print)
8. Spacing: Use page-relative spacing for better formatting
9. Barcodes: Test barcode readability with actual printers
10. Watermarks: Use subtle watermarks for branding (20-30% opacity)

---

Next: See Page Designer for component reference and navigation.