PDF export (Rust-native)

[jorgedanisc]

Hi! Would you consider adding PDF export support (e.g., export a worksheet to a paginated PDF)?

A Rust-native PDF export would fit nicely with with the project's Rust-first approach and would also be useful for WASM/server environments.

Implementation idea (optional):
This could be done by introducing a render/layout layer that produces “drawing primitives” (rects/lines/text/images) and then a PDF backend.

Possible Rust PDF backends I found:

• printpdf (MIT): https://github.com/fschutt/printpdf
• pdf-writer (MIT/Apache-2.0): https://github.com/typst/pdf-writer
• hipdf (MIT/Apache-2.0) (my wrapper over lopdf for lower-level control): https://github.com/ducflair/hipdf
• lopdf (MIT/Apache-2.0) (very low level): https://github.com/J-F-Liu/lopdf

If this is something you’d be open to, I’m happy to help — especially the PDF backend portion.

[nhatcher]

Hi, excellent idea! Do you think this would be a completely independent tool?

Would you want to print to PDF the canvas as it is or are you thinking in creating a completely new backend?

[jorgedanisc]

I think it should be modularized into a library/module (since it would be kind of a data adapter), but still inside this monorepo, depending on the project preference. It would be nice to test on the existing IronCalc spreadsheet editor app as an export, for example.

As for the pdf output content - Maybe the first implementation could be each spreadsheet canvas as a PDF page (so a file with multiple sheets would export into a pdf with multiple pages)

Of course there is the problem that a PDF file has size limits, so later, extremely big sheets would need to be paginated or scaled to fit, depending on user preference (similar to how commercial systems like MS Excel and Google Sheets export a PDF)

[jorgedanisc]

I'm very interested in giving some help developing this adapter. However, I'm currently tied up with other commitments and realistically won't be able to contribute for now.

That said, I'd like to share something that might be useful in the meantime: here's a link to the PDF export logic/code we implemented for a file format -> pdf in one of our projects. It could be helpful to investigate, or at the very least serve as a reference resource.

actual full rust code:
https://github.com/ducflair/duc/tree/main/packages/ducpdf/src/duc2pdf

library as whole bundled with js and wasm:
https://github.com/ducflair/duc/tree/main/packages/ducpdf

[jorgedanisc]

After some research and thinking more about this, I think the more robust direction is a dedicated print-layout pipeline:

1. Resolve workbook print metadata and explicit export options into a deterministic page layout.
2. Paginate sheets/ranges according to print areas, page size, orientation, margins, scaling, page breaks, repeated titles, headers/footers, etc.
3. Render the resulting pages through a PDF backend.

So the PDF backend itself could still be modular, but the important part is probably the intermediate print layout model. That avoids coupling PDF export too tightly to the interactive spreadsheet canvas, while still allowing the existing editor to call it as an export feature.

A simple first version could support active-sheet export with practical defaults, but I think the API should avoid assuming “one sheet = one PDF page”. Large sheets may span multiple pages, selected ranges may be exported, print areas may define separate page blocks, and multi-sheet exports may need per-sheet settings.

The shape I would imagine is something like:

• export scope: active sheet, selected sheets, entire workbook, explicit ranges
• page setup: paper size, orientation, margins
• layout: scaling, manual/automatic page breaks, page order
• ranges: print area, used range fallback, hidden rows/columns
• repeated titles: rows/columns repeated across pages
• content: gridlines, headings, charts, images, shapes, comments
• PDF behavior: font embedding, image DPI, hyperlinks, bookmarks

I have a more detailed pseudo-API sketch if useful, but the core idea is: The PDF export should probably be modeled as a spreadsheet print/export pipeline, not as a direct canvas snapshot. Therefore a separate package.

[jorgedanisc]

Adding a more concrete pseudo-API sketch for the export configuration.

This is not intended as finalized Rust code or a proposed public API shape. It is more of a design sketch to show the kinds of layout decisions that an PDF exporter may need to model explicitly.

Possible pseudo-API in Rust

#[derive(Debug, Clone)]
pub struct PdfExportOptions {
    pub scope: ExportScope,
    pub print_settings: PrintSettingsPolicy,
    pub page: PageOptions,
    pub layout: LayoutOptions,
    pub range: RangeOptions,
    pub repeat: RepeatOptions,
    pub content: ContentOptions,
    pub header_footer: HeaderFooterOptions,
    pub pdf: PdfDocumentOptions,
}

impl Default for PdfExportOptions {
    fn default() -> Self {
        Self {
            scope: ExportScope::ActiveSheet,
            print_settings: PrintSettingsPolicy::HonorWorkbookSettings,

            page: PageOptions {
                paper_size: PaperSizePolicy::FromDocumentOr(PaperSize::A4),
                orientation: OrientationPolicy::FromDocumentOr(Orientation::Portrait),
                margins: MarginPolicy::FromDocumentOr(Margins::normal()),
                center_on_page: CenterOnPagePolicy::FromDocumentOr {
                    horizontal: false,
                    vertical: false,
                },
                first_page_number: FirstPageNumberPolicy::FromDocumentOrAuto,
            },

            layout: LayoutOptions {
                scaling: ScalingPolicy::FromDocumentOr(Scaling::FitToWidth {
                    pages_wide: 1,
                    pages_tall: None,
                }),
                manual_page_breaks: PageBreakPolicy::Honor,
                automatic_page_breaks: AutomaticPageBreakPolicy::Compute,
                page_order: PageOrderPolicy::FromDocumentOr(PageOrder::DownThenOver),
                allow_sheet_to_span_multiple_pages: true,
            },

            range: RangeOptions {
                print_area: PrintAreaPolicy::HonorDefinedPrintAreas,
                fallback_when_no_print_area: RangeFallback::UsedRange,
                multiple_print_areas: MultiplePrintAreasPolicy::SeparatePageBlocks,
                hidden_rows_columns: HiddenContentPolicy::Omit,
            },

            repeat: RepeatOptions {
                titles: RepeatTitlePolicy::HonorDefinedPrintTitles,
                frozen_panes: FrozenPanePrintPolicy::DoNotRepeat,
            },

            content: ContentOptions {
                gridlines: SheetBooleanPolicy::FromDocumentOr(false),
                row_column_headings: SheetBooleanPolicy::FromDocumentOr(false),
                charts: ObjectPrintPolicy::Render,
                images: ObjectPrintPolicy::Render,
                shapes: ObjectPrintPolicy::Render,
                comments: CommentPrintPolicy::FromDocumentOr(CommentPrintMode::None),
                cell_errors: CellErrorPolicy::FromDocumentOr(CellErrorMode::DisplayAsStored),
                formulas: FormulaPrintPolicy::CalculatedValues,
            },

            header_footer: HeaderFooterOptions {
                mode: HeaderFooterMode::FromDocumentOrNone,
                scale_with_document: true,
                align_with_page_margins: true,
            },

            pdf: PdfDocumentOptions {
                profile: PdfProfile::StandardPdf,
                optimization: PdfOptimization::StandardQuality,
                font_embedding: FontEmbeddingPolicy::SubsetEmbeddableFonts,
                raster_image_dpi: 300,
                external_hyperlinks: HyperlinkPolicy::Preserve,
                internal_hyperlinks: HyperlinkPolicy::BestEffort,
                bookmarks: BookmarkPolicy::SheetBookmarksWhenExportingMultipleSheets,
                accessibility_tags: false,
                open_after_export: false,
            },
        }
    }
}

/*
   Export scope
*/

/// Defines which workbook content is included in the PDF.
#[derive(Debug, Clone)]
pub enum ExportScope {
    ActiveSheet,
    SelectedSheets(Vec<SheetId>),
    EntireWorkbook,
    Selection {
        sheet: SheetId,
        range: CellRange,
    },
    ExplicitRanges(Vec<SheetRange>),
}

/// Controls how persisted workbook print settings interact with explicit export options.
#[derive(Debug, Clone)]
pub enum PrintSettingsPolicy {
    /**
     * Existing workbook settings are used whenever present. Explicit export options
     * still override the corresponding document settings.
     */
    HonorWorkbookSettings,

    /// Ignore persisted print metadata and use only the export configuration.
    IgnoreWorkbookSettings,

    /// Fail when relevant workbook print settings cannot be represented faithfully.
    RequireFaithfulWorkbookSettings,
}

/*
   Page setup
*/

#[derive(Debug, Clone)]
pub struct PageOptions {
    pub paper_size: PaperSizePolicy,
    pub orientation: OrientationPolicy,
    pub margins: MarginPolicy,
    pub center_on_page: CenterOnPagePolicy,
    pub first_page_number: FirstPageNumberPolicy,
}

#[derive(Debug, Clone)]
pub enum PaperSizePolicy {
    FromDocumentOr(PaperSize),
    Fixed(PaperSize),
    Custom { width_mm: f32, height_mm: f32 },
}

#[derive(Debug, Clone)]
pub enum PaperSize {
    A4,
    Letter,
    Legal,
    A3,
    Custom { width_mm: f32, height_mm: f32 },
}

#[derive(Debug, Clone)]
pub enum OrientationPolicy {
    FromDocumentOr(Orientation),
    Fixed(Orientation),
}

#[derive(Debug, Clone)]
pub enum Orientation {
    Portrait,
    Landscape,
}

#[derive(Debug, Clone)]
pub enum MarginPolicy {
    FromDocumentOr(Margins),
    Fixed(Margins),
}

#[derive(Debug, Clone, Copy)]
pub struct Margins {
    pub top_mm: f32,
    pub right_mm: f32,
    pub bottom_mm: f32,
    pub left_mm: f32,
    pub header_mm: f32,
    pub footer_mm: f32,
}

impl Margins {
    pub fn normal() -> Self {
        Self {
            top_mm: 19.0,
            right_mm: 18.0,
            bottom_mm: 19.0,
            left_mm: 18.0,
            header_mm: 8.0,
            footer_mm: 8.0,
        }
    }

    pub fn narrow() -> Self {
        Self {
            top_mm: 6.35,
            right_mm: 6.35,
            bottom_mm: 6.35,
            left_mm: 6.35,
            header_mm: 8.0,
            footer_mm: 8.0,
        }
    }
}

#[derive(Debug, Clone)]
pub enum CenterOnPagePolicy {
    FromDocumentOr { horizontal: bool, vertical: bool },
    Fixed { horizontal: bool, vertical: bool },
}

#[derive(Debug, Clone)]
pub enum FirstPageNumberPolicy {
    FromDocumentOrAuto,
    Auto,
    Number(u32),
}

/* 
   Layout and pagination
*/

#[derive(Debug, Clone)]
pub struct LayoutOptions {
    pub scaling: ScalingPolicy,
    pub manual_page_breaks: PageBreakPolicy,
    pub automatic_page_breaks: AutomaticPageBreakPolicy,
    pub page_order: PageOrderPolicy,
    pub allow_sheet_to_span_multiple_pages: bool,
}

#[derive(Debug, Clone)]
pub enum ScalingPolicy {
    FromDocumentOr(Scaling),
    Fixed(Scaling),
}

#[derive(Debug, Clone)]
pub enum Scaling {
    ActualSize,
    Percent(u16),

    /**
     * Fits the sheet to a fixed number of pages horizontally while allowing vertical
     * pagination. This is usually a safer default than forcing the whole sheet onto
     * one page, which often makes dense spreadsheets unreadable.
     */
    FitToWidth {
        pages_wide: u16,
        pages_tall: Option<u16>,
    },

    FitToHeight {
        pages_wide: Option<u16>,
        pages_tall: u16,
    },

    FitToPages {
        pages_wide: u16,
        pages_tall: u16,
    },

    FitSheetOnOnePage,
}

#[derive(Debug, Clone)]
pub enum PageBreakPolicy {
    Honor,
    Ignore,
}

#[derive(Debug, Clone)]
pub enum AutomaticPageBreakPolicy {
    Compute,
    Disable,
}

#[derive(Debug, Clone)]
pub enum PageOrderPolicy {
    FromDocumentOr(PageOrder),
    Fixed(PageOrder),
}

#[derive(Debug, Clone)]
pub enum PageOrder {
    DownThenOver,
    OverThenDown,
}

/*
   Ranges and visible content
*/

#[derive(Debug, Clone)]
pub struct RangeOptions {
    pub print_area: PrintAreaPolicy,
    pub fallback_when_no_print_area: RangeFallback,
    pub multiple_print_areas: MultiplePrintAreasPolicy,
    pub hidden_rows_columns: HiddenContentPolicy,
}

#[derive(Debug, Clone)]
pub enum PrintAreaPolicy {
    HonorDefinedPrintAreas,
    IgnoreDefinedPrintAreas,
    OnlyExplicitRange(CellRange),
}

#[derive(Debug, Clone)]
pub enum RangeFallback {
    UsedRange,
    EntireSheet,
    CurrentSelection,
}

#[derive(Debug, Clone)]
pub enum MultiplePrintAreasPolicy {
    /**
     * Each print area starts its own page block. This preserves the author's
     * explicit print intent and avoids unexpectedly merging unrelated regions.
     */
    SeparatePageBlocks,
    MergeIfAdjacent,
    Error,
}

#[derive(Debug, Clone)]
pub enum HiddenContentPolicy {
    Omit,
    Include,
}

/* 
   Repeated rows and columns
*/

#[derive(Debug, Clone)]
pub struct RepeatOptions {
    pub titles: RepeatTitlePolicy,
    pub frozen_panes: FrozenPanePrintPolicy,
}

#[derive(Debug, Clone)]
pub enum RepeatTitlePolicy {
    HonorDefinedPrintTitles,
    None,
    Explicit {
        rows: Option<RowRange>,
        columns: Option<ColumnRange>,
    },
}

#[derive(Debug, Clone)]
pub enum FrozenPanePrintPolicy {
    /**
     * Frozen panes are primarily a viewport feature. They should only become repeated
     * print titles when explicitly requested or when the product chooses that behavior.
     */
    DoNotRepeat,
    RepeatAsPrintTitles,
}

/*
   Spreadsheet content rendering
*/

#[derive(Debug, Clone)]
pub struct ContentOptions {
    pub gridlines: SheetBooleanPolicy,
    pub row_column_headings: SheetBooleanPolicy,
    pub charts: ObjectPrintPolicy,
    pub images: ObjectPrintPolicy,
    pub shapes: ObjectPrintPolicy,
    pub comments: CommentPrintPolicy,
    pub cell_errors: CellErrorPolicy,
    pub formulas: FormulaPrintPolicy,
}

#[derive(Debug, Clone)]
pub enum SheetBooleanPolicy {
    FromDocumentOr(bool),
    Fixed(bool),
}

#[derive(Debug, Clone)]
pub enum ObjectPrintPolicy {
    Render,
    Skip
}

#[derive(Debug, Clone)]
pub enum CommentPrintPolicy {
    FromDocumentOr(CommentPrintMode),
    Fixed(CommentPrintMode),
}

#[derive(Debug, Clone)]
pub enum CommentPrintMode {
    None,
    AsDisplayed,
    AtEndOfSheet,
}

#[derive(Debug, Clone)]
pub enum CellErrorPolicy {
    FromDocumentOr(CellErrorMode),
    Fixed(CellErrorMode),
}

#[derive(Debug, Clone)]
pub enum CellErrorMode {
    DisplayAsStored,
    Blank,
    Dash,
    NotAvailable,
}

#[derive(Debug, Clone)]
pub enum FormulaPrintPolicy {
    CalculatedValues,
    FormulaText,
}

/*
   Headers and footers
*/

#[derive(Debug, Clone)]
pub struct HeaderFooterOptions {
    pub mode: HeaderFooterMode,
    pub scale_with_document: bool,
    pub align_with_page_margins: bool,
}

#[derive(Debug, Clone)]
pub enum HeaderFooterMode {
    FromDocumentOrNone,
    None,
    Explicit {
        header: HeaderFooterLayout,
        footer: HeaderFooterLayout,
    },
}

#[derive(Debug, Clone)]
pub struct HeaderFooterLayout {
    pub left: HeaderFooterField,
    pub center: HeaderFooterField,
    pub right: HeaderFooterField,
}

#[derive(Debug, Clone)]
pub enum HeaderFooterField {
    Empty,
    Text(String),
    PageNumber,
    PageNumberOfTotal,
    SheetName,
    WorkbookName,
    Date,
    Time,
    Custom(Vec<HeaderFooterToken>),
}

#[derive(Debug, Clone)]
pub enum HeaderFooterToken {
    Text(String),
    PageNumber,
    TotalPages,
    SheetName,
    WorkbookName,
    Date,
    Time,
    FontName(String),
    FontSize(u16),
    Bold,
    Italic,
    Underline,
}

/* 
   PDF document behavior
*/

#[derive(Debug, Clone)]
pub struct PdfDocumentOptions {
    pub profile: PdfProfile,
    pub optimization: PdfOptimization,
    pub font_embedding: FontEmbeddingPolicy,
    pub raster_image_dpi: u16,
    pub external_hyperlinks: HyperlinkPolicy,
    pub internal_hyperlinks: HyperlinkPolicy,
    pub bookmarks: BookmarkPolicy,
    pub accessibility_tags: bool,
    pub open_after_export: bool,
}

#[derive(Debug, Clone)]
pub enum PdfProfile {
    StandardPdf,
    PdfA1,
    PdfA2,
    PdfUa,
}

#[derive(Debug, Clone)]
pub enum PdfOptimization {
    StandardQuality,
    MinimumSize,
    PrintQuality,
}

#[derive(Debug, Clone)]
pub enum FontEmbeddingPolicy {
    None,
    SubsetEmbeddableFonts,
    EmbedAllEmbeddableFonts,
}

#[derive(Debug, Clone)]
pub enum HyperlinkPolicy {
    Preserve,
    Drop,
    BestEffort,
}

#[derive(Debug, Clone)]
pub enum BookmarkPolicy {
    None,
    SheetBookmarksWhenExportingMultipleSheets,
    AlwaysBySheet,
}

[nhatcher]

Hi @jorgedanisc, maybe worth having a chat about this? At the moment we can't priotize PDF export as things stand. But if this is something useful for you (as opposed to a nice thing to build) we can definitely invest some resources into this.

[jorgedanisc]

Hi @nhatcher, thanks for the reply.

Yes, this would be useful for us. We’re currently looking at PDF export as part of how we handle spreadsheet/table outputs, so it is more than just a nice-to-have on our side.

I’d actually be interested in helping with the implementation myself, just probably not right away. For now, I’m mostly trying to validate whether the approach I sketched fits with how you’d want PDF export to be implemented in IronCalc.

There’s no need for you to prioritize this or invest resources into it. If the direction seems aligned with your architecture views, I can try to create a PR when I have time. I’d mainly like to avoid building in a direction that doesn’t make sense for the project.