A commercial invoice

//! Draws a commercial invoice: a letterhead, a billed-lines table, totals, and
//! a payment block whose amount can be paid by scanning a code.
//!
//! This is the document the library is sold to make. It puts a logo, styled
//! text, a paginating table, and a QR code on one page, and the code it draws
//! is a SEPA credit transfer: a phone's banking app reads it and offers to pay
//! the exact amount to the exact account, so a person never types an IBAN by
//! hand.
//!
//! Whether that code pays is not for the page to say, and not for an eye: a
//! scanner says. `scripts/check_qr.sh` points a decoder at the rendered page
//! and reads back the transfer.
//!
//! Every word the page draws is held in `Words`, once per language, and
//! `HQF_PDF_LANG` picks which one is drawn. Figures, dates in the file's own
//! name, the account number and the invoice's number are the same in both.
//!
//! Usage: `cargo run --example write_invoice -- tmp/invoice.pdf [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_invoice -- tmp/facture.pdf`

use std::env;
use std::fs;
use std::path::{Path, PathBuf};

use hqf_pdf::content::Content;
use hqf_pdf::cos::Name;
use hqf_pdf::layout::{
    Border, Cell, ColumnWidth, Columns, Margin, Padding, RichText, Row, Rule, Stroke, Style, Table,
    VAlign,
};
use hqf_pdf::{Align, Document, Font, FontHandle, Image, ImageHandle, Page, QrCode, Rgb};

#[path = "shared/out.rs"]
mod out;

#[path = "shared/licence.rs"]
mod licence;

#[path = "shared/language.rs"]
mod language;

use language::Language;

/// The font the example draws with when none is given on the command line.
fn default_font() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fonts")
        .join("DejaVuSans.ttf")
}

/// The logo the letterhead carries: the committed fixture, so the example runs
/// on any machine. It stands in for the seller's mark.
fn logo_path() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("images")
        .join("hqf_development.png")
}

/// A4, in points.
const PAGE_WIDTH: f64 = 595.276;
const PAGE_HEIGHT: f64 = 841.89;
/// The page's left edge and, mirrored, its right.
const LEFT: f64 = 56.0;
const RIGHT: f64 = PAGE_WIDTH - LEFT;
/// The width the table is fitted across.
const TABLE_WIDTH: f64 = PAGE_WIDTH - 2.0 * LEFT;

/// The ink the headings and rules are drawn in, and the grey of the small
/// print.
const ACCENT: Rgb = Rgb {
    r: 0.11,
    g: 0.33,
    b: 0.55,
};
const MUTED: Rgb = Rgb {
    r: 0.42,
    g: 0.42,
    b: 0.45,
};
const INK: Rgb = Rgb {
    r: 0.1,
    g: 0.1,
    b: 0.12,
};

/// How many lines the invoice bills.
const ITEM_COUNT: usize = 4;

/// What one line of the invoice sells, apart from what it is called: the
/// figures read the same whatever language the page is set in.
struct Item {
    /// How many.
    quantity: u32,
    /// The price of one, before tax.
    unit_price: f64,
}

/// The lines this invoice bills, in the order `Words::items` names them.
const ITEMS: [Item; ITEM_COUNT] = [
    Item {
        quantity: 14,
        unit_price: 620.0,
    },
    Item {
        quantity: 6,
        unit_price: 480.0,
    },
    Item {
        quantity: 1,
        unit_price: 1440.0,
    },
    Item {
        quantity: 2,
        unit_price: 950.0,
    },
];

/// The rate the invoice charges tax at.
const VAT_RATE: f64 = 0.2;

/// What the invoice is called.
const NUMBER: &str = "2026-0142";

/// The seller, and the numbers a French invoice has to carry.
const SELLER: &str = "HQF Development";
const SELLER_ADDRESS: &str = "42 lot les Genêts, 13480 Calas, France";
const SELLER_SITE: &str = "www.hqf.fr";
const SELLER_SIRET: &str = "SIRET 752 492 777 00012";
const SELLER_APE: &str = "APE 6202A";
const SELLER_VAT: &str = "FR59 752 492 777";

/// Who the invoice is billed to.
const BUYER: &str = "Northwind Trading SARL";
const BUYER_STREET: &str = "18 quai du Port";
const BUYER_CITY: &str = "13002 Marseille, France";

/// The account the QR code pays into, ungrouped as the standard wants it, and
/// grouped as the page shows it. The number is a documentation IBAN, not a live
/// account: what the example demonstrates is the transfer, not the destination.
const IBAN: &str = "FR1420041010050500013M02606";
const IBAN_SHOWN: &str = "FR14 2004 1010 0505 0001 3M02 606";

/// Every word the page draws, in one language.
///
/// What is not language stays out of it: the figures, the account number, the
/// invoice's number and the seller's and buyer's names and addresses are drawn
/// from constants of their own and read the same in every language.
#[derive(Debug)]
struct Words {
    /// The word the payment reference and the document's title are built from.
    invoice: &'static str,
    /// The word set large at the head of the page.
    heading: &'static str,
    /// What stands before the invoice's number.
    number_label: &'static str,
    /// What stands before the day the invoice was issued.
    issue_label: &'static str,
    /// That day, written as this language writes a date.
    issue_date: &'static str,
    /// What stands before the day the invoice falls due.
    due_label: &'static str,
    /// That day, written as this language writes a date.
    due_date: &'static str,
    /// The short form of the same, set under the amount owed.
    due_short: &'static str,
    /// The heading over the buyer.
    bill_to: &'static str,
    /// The heading over what is owed.
    amount_due: &'static str,
    /// What each billed line is called, in the order `ITEMS` bills them.
    items: [&'static str; ITEM_COUNT],
    /// The four column headings of the table.
    description: &'static str,
    quantity: &'static str,
    unit_price: &'static str,
    amount: &'static str,
    /// The three totals under the billed lines.
    subtotal: &'static str,
    tax: &'static str,
    total: &'static str,
    /// The heading over the payment block.
    payment: &'static str,
    /// The sentence the payment block sets, cut where the amount and the
    /// invoice's number go into it.
    terms_before: &'static str,
    terms_around_number: &'static str,
    terms_after: &'static str,
    /// What stands before the account number.
    iban_label: &'static str,
    /// What stands under the code.
    caption: &'static str,
    /// The word before the seller's tax number in the footer.
    vat: &'static str,
}

impl Words {
    /// The words the invoice is written in, in `language`.
    fn of(language: Language) -> &'static Self {
        language::pick(&WORDS, language)
    }
}

/// The invoice in English.
const ENGLISH: Words = Words {
    invoice: "Invoice",
    heading: "INVOICE",
    number_label: "Invoice No.",
    issue_label: "Issue date",
    issue_date: "19 July 2026",
    due_label: "Due date",
    due_date: "18 August 2026",
    due_short: "Due",
    bill_to: "BILL TO",
    amount_due: "AMOUNT DUE",
    items: [
        "Web application development",
        "UX and graphic design",
        "Managed hosting — annual plan",
        "On-site training (Django, per day)",
    ],
    description: "Description",
    quantity: "Qty",
    unit_price: "Unit price",
    amount: "Amount",
    subtotal: "Subtotal",
    tax: "VAT at 20 %",
    total: "Total due",
    payment: "PAYMENT",
    terms_before: "Please transfer ",
    terms_around_number: " within 30 days, quoting invoice ",
    terms_after: ". Scan the code to pay the exact amount to the account below.",
    iban_label: "IBAN",
    caption: "Scan to pay — SEPA",
    vat: "VAT",
};

/// The invoice in French.
const FRENCH: Words = Words {
    invoice: "Facture",
    heading: "FACTURE",
    number_label: "Facture n°",
    issue_label: "Date d'émission",
    issue_date: "19 juillet 2026",
    due_label: "Échéance",
    due_date: "18 août 2026",
    due_short: "Échéance",
    bill_to: "FACTURÉ À",
    amount_due: "MONTANT DÛ",
    items: [
        "Développement d'application web",
        "Conception graphique et UX",
        "Hébergement infogéré — forfait annuel",
        "Formation sur site (Django, par jour)",
    ],
    description: "Désignation",
    quantity: "Qté",
    unit_price: "Prix unitaire",
    amount: "Montant",
    subtotal: "Total HT",
    tax: "TVA 20 %",
    total: "Total TTC",
    payment: "PAIEMENT",
    terms_before: "Payable par virement de ",
    terms_around_number: " sous 30 jours. Merci de rappeler le numéro de facture ",
    terms_after: ". Scannez le code pour payer le montant exact sur le compte ci-dessous.",
    iban_label: "IBAN",
    caption: "Scannez pour payer — SEPA",
    vat: "TVA",
};

/// Every language the example is written in. A language is added by writing its
/// own set of words and naming it here.
static WORDS: [(Language, &Words); 2] =
    [(Language::English, &ENGLISH), (Language::French, &FRENCH)];

/// An amount, as an invoice writes it: "4 250.00 EUR".
fn amount(value: f64) -> String {
    let fixed = format!("{value:.2}");
    let (units, hundredths) = fixed.split_once('.').unwrap_or((fixed.as_str(), "00"));

    let mut grouped = String::new();
    for (index, digit) in units.chars().enumerate() {
        if index > 0 && (units.len() - index) % 3 == 0 {
            grouped.push(' ');
        }
        grouped.push(digit);
    }

    format!("{grouped}.{hundredths} EUR")
}

/// The line the QR code carries: a SEPA credit transfer in the EPC069-12
/// format, the one a banking app reads to offer a transfer of `total` to the
/// seller. The BIC line is left empty, which the standard allows for an account
/// reachable in the single euro payments area, and the reference travels as
/// free text, in the language the page is set in.
fn sepa_transfer(words: &Words, total: f64) -> String {
    [
        "BCD",
        "002",
        "1",
        "SCT",
        "",
        SELLER,
        IBAN,
        &format!("EUR{total:.2}"),
        "",
        "",
        &format!("{} {NUMBER}", words.invoice),
    ]
    .join("\n")
}

/// Draws a line of text, left-aligned, in a colour of its own.
fn text(content: &mut Content, font: &FontHandle, size: f64, x: f64, y: f64, color: Rgb, s: &str) {
    let _ = content.set_fill(color);
    content.begin_text();
    let _ = content.set_font(font.name(), size);
    let _ = content.text_origin(x, y);
    content.show_glyphs(&font.glyphs(s));
    content.end_text();
}

/// Draws a line of text whose right edge sits at `right`.
fn text_right(
    content: &mut Content,
    font: &FontHandle,
    size: f64,
    right: f64,
    y: f64,
    color: Rgb,
    s: &str,
) {
    text(
        content,
        font,
        size,
        right - font.measure(s, size),
        y,
        color,
        s,
    );
}

/// A horizontal rule from `LEFT` to `RIGHT` at height `y`.
fn rule(content: &mut Content, y: f64, width: f64, color: Rgb) -> Result<(), hqf_pdf::Error> {
    content.set_stroke(color)?;
    content.set_line_width(width)?;
    content.move_to(LEFT, y)?;
    content.line_to(RIGHT, y)?;
    content.stroke();
    Ok(())
}

/// The invoice's table: a heading row, the billed lines, and the totals.
fn invoice_table<'a>(
    font: &'a FontHandle,
    words: &'static Words,
) -> Result<Table<'a>, hqf_pdf::Error> {
    // The description takes whatever the three figure columns leave it.
    let columns = Columns::new(
        vec![
            ColumnWidth::Fraction(1.0),
            ColumnWidth::Points(46.0),
            ColumnWidth::Points(94.0),
            ColumnWidth::Points(94.0),
        ],
        TABLE_WIDTH,
    )?;

    let mut table = Table::new(columns);
    table.header(1);
    table
        .rule(Rule::Frame, Stroke::new(0.8, ACCENT))
        .rule(Rule::HorizontalOther, Stroke::new(0.25, Rgb::gray(0.78)))
        .rule(Rule::Horizontal(1), Stroke::new(0.8, ACCENT))
        .rule(Rule::HorizontalFromEnd(1), Stroke::new(0.8, ACCENT));

    let pad = Padding::symmetric(6.0, 5.0);
    let heading = |label: &str| {
        Cell::new(font, 9.0, label)
            .padding(pad)
            .fill(ACCENT)
            .color(Rgb::gray(1.0))
            .valign(VAlign::Middle)
    };

    table.push(
        Row::new()
            .cell(heading(words.description))
            .cell(heading(words.quantity).align(Align::Right))
            .cell(heading(words.unit_price).align(Align::Right))
            .cell(heading(words.amount).align(Align::Right))
            .min_height(22.0),
    );

    let mut total = 0.0;
    for (index, (item, label)) in ITEMS.iter().zip(words.items).enumerate() {
        let line_total = f64::from(item.quantity) * item.unit_price;
        total += line_total;

        let figure = |value: String| {
            Cell::new(font, 9.0, value)
                .padding(pad)
                .align(Align::Right)
                .valign(VAlign::Middle)
        };

        let mut row = Row::new()
            .cell(
                Cell::new(font, 9.0, label)
                    .padding(pad)
                    .valign(VAlign::Middle),
            )
            .cell(figure(item.quantity.to_string()))
            .cell(figure(amount(item.unit_price)))
            .cell(figure(amount(line_total)))
            .min_height(19.0);

        if index % 2 == 1 {
            row = row.fill(Rgb::gray(0.96));
        }
        table.push(row);
    }

    let tax = total * VAT_RATE;
    for (label, value, size, is_grand_total) in [
        (words.subtotal, total, 9.0, false),
        (words.tax, tax, 9.0, false),
        (words.total, total + tax, 10.0, true),
    ] {
        // The grand total is boxed off the grid so it reads as a total, not as
        // one more line: the label carries the box's left edge and the figure
        // its right, so the two trace one box between them.
        let (label_border, value_border, box_margin) = if is_grand_total {
            let stroke = Stroke::new(0.8, ACCENT);
            (
                Border::none().top(&stroke).bottom(&stroke).left(&stroke),
                Border::none().top(&stroke).bottom(&stroke).right(&stroke),
                Margin::symmetric(0.0, 2.0),
            )
        } else {
            (Border::none(), Border::none(), Margin::NONE)
        };

        table.push(
            Row::new()
                .cell(
                    Cell::new(font, size, label)
                        .span(3)
                        .align(Align::Right)
                        .padding(pad)
                        .margin(box_margin)
                        .border(&label_border),
                )
                .cell(
                    Cell::new(font, size, amount(value))
                        .align(Align::Right)
                        .padding(pad)
                        .margin(box_margin)
                        .border(&value_border),
                )
                .min_height(18.0),
        );
    }

    Ok(table)
}

/// Draws the letterhead: the mark, the seller's name, the word the page is, and
/// the invoice's number and dates, closed off by a rule.
fn letterhead(
    content: &mut Content,
    font: &FontHandle,
    logo: &ImageHandle,
    words: &Words,
) -> Result<(), hqf_pdf::Error> {
    let (logo_w, logo_h) = logo.fit_within(84.0, 84.0)?;
    content.draw_image(logo, LEFT, 826.5 - logo_h, logo_w, logo_h)?;

    text(content, font, 8.5, LEFT, 768.0, MUTED, SELLER_ADDRESS);
    text(content, font, 8.5, LEFT, 756.0, MUTED, SELLER_SITE);

    text_right(content, font, 30.0, RIGHT, 796.0, ACCENT, words.heading);
    text_right(
        content,
        font,
        9.5,
        RIGHT,
        770.0,
        INK,
        &format!("{} {NUMBER}", words.number_label),
    );
    text_right(
        content,
        font,
        9.5,
        RIGHT,
        757.0,
        MUTED,
        &format!("{} {}", words.issue_label, words.issue_date),
    );
    text_right(
        content,
        font,
        9.5,
        RIGHT,
        744.0,
        MUTED,
        &format!("{} {}", words.due_label, words.due_date),
    );

    rule(content, 730.0, 1.2, ACCENT)
}

/// Draws who the invoice is to, and — set apart on the right — what it comes
/// to.
fn parties(content: &mut Content, font: &FontHandle, words: &Words, total: f64) {
    text(content, font, 8.0, LEFT, 712.0, MUTED, words.bill_to);
    text(content, font, 11.0, LEFT, 697.0, INK, BUYER);
    text(content, font, 9.0, LEFT, 683.0, MUTED, BUYER_STREET);
    text(content, font, 9.0, LEFT, 671.0, MUTED, BUYER_CITY);

    text_right(content, font, 8.0, RIGHT, 712.0, MUTED, words.amount_due);
    text_right(content, font, 17.0, RIGHT, 694.0, ACCENT, &amount(total));
    text_right(
        content,
        font,
        9.0,
        RIGHT,
        678.0,
        MUTED,
        &format!("{} {}", words.due_short, words.due_date),
    );
}

/// Draws the payment block: how to pay in words, the account in figures, and
/// the same transfer as a scannable code beside it, then the legal footer.
fn payment(
    content: &mut Content,
    font: &FontHandle,
    words: &Words,
    table_bottom: f64,
    total: f64,
) -> Result<(), hqf_pdf::Error> {
    let block_top = table_bottom - 40.0;
    text(content, font, 10.0, LEFT, block_top, ACCENT, words.payment);

    // The due amount is underlined mid-line, which is what rich text is for.
    let body = Style::new(font, 9.5);
    let marked = Style::new(font, 9.5).underline();
    let terms = RichText::new()
        .push(words.terms_before, &body)
        .push(amount(total), &marked)
        .push(
            format!("{}{NUMBER}{}", words.terms_around_number, words.terms_after),
            &body,
        );
    let terms_top = block_top - 16.0;
    let lines = terms.break_lines(300.0);
    content.set_fill(INK)?;
    terms.draw(content, &lines, LEFT, terms_top, 300.0)?;

    let iban_y = terms_top - RichText::height(&lines) - 10.0;
    text(content, font, 9.0, LEFT, iban_y, MUTED, words.iban_label);
    text(content, font, 9.5, LEFT + 34.0, iban_y, INK, IBAN_SHOWN);

    // The code sits at the right, drawn as a square from its lower-left corner,
    // level with the payment words and clear of the table above.
    let code = QrCode::new(&sepa_transfer(words, total))?;
    let side = 104.0;
    let code_x = RIGHT - side;
    let code_bottom = block_top + 4.0 - side;
    content.set_fill(Rgb::gray(0.0))?;
    content.draw_qr(&code, code_x, code_bottom, side)?;
    let caption_x = code_x + (side - font.measure(words.caption, 8.0)) / 2.0;
    text(
        content,
        font,
        8.0,
        caption_x,
        code_bottom - 12.0,
        MUTED,
        words.caption,
    );

    // The foot of the page: what the law asks a French invoice to carry.
    rule(content, 74.0, 0.5, Rgb::gray(0.8))?;
    let mentions = format!(
        "{SELLER} · {SELLER_ADDRESS} · {SELLER_SIRET} · {SELLER_APE} · {} {SELLER_VAT}",
        words.vat
    );
    let mentions_x = LEFT + (TABLE_WIDTH - font.measure(&mentions, 7.0)) / 2.0;
    text(content, font, 7.0, mentions_x, 62.0, MUTED, &mentions);

    Ok(())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let language = Language::from_environment()?;
    let words = Words::of(language);

    let mut args = env::args().skip(1);
    // A named file is written as named; the default one carries the language,
    // so the two languages do not overwrite each other in `tmp/`.
    let path = args
        .next()
        .unwrap_or_else(|| language.file_name(&out::default_path("invoice")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    doc.set_info(Name::new("Title"), &format!("{} {NUMBER}", words.invoice));

    let font = doc.add_font(Font::parse(fs::read(&font_path)?)?);
    let logo = doc.add_image(Image::parse(fs::read(logo_path())?)?);

    let total = ITEMS
        .iter()
        .map(|item| f64::from(item.quantity) * item.unit_price)
        .sum::<f64>()
        * (1.0 + VAT_RATE);

    let mut content = Content::new();
    letterhead(&mut content, &font, &logo, words)?;
    parties(&mut content, &font, words, total);

    // The billed lines, fitted onto this page: the invoice is short enough to
    // sit on one, but the table would continue onto the next were it not.
    let table = invoice_table(&font, words)?;
    let table_top = 645.0;
    let placed = table.fit(LEFT, table_top, table_top - 250.0, 0)?;
    placed.draw(&mut content)?;

    payment(
        &mut content,
        &font,
        words,
        table_top - placed.height(),
        total,
    )?;

    let mut page = Page::new(PAGE_WIDTH, PAGE_HEIGHT);
    page.content = content.into_bytes();
    doc.add_page(page)?;

    let bytes = doc.to_bytes()?;
    if let Some(parent) = Path::new(&path).parent() {
        fs::create_dir_all(parent)?;
    }
    fs::write(&path, &bytes)?;

    println!("wrote {path}: {} bytes, {} due", bytes.len(), amount(total));
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::{WORDS, language};

    /// The lines two languages are allowed to write the same way, each with
    /// what makes the two the same word.
    const SPARED: [&str; 1] = [
        // An account number goes by its four letters in French as in English.
        r#"iban_label: "IBAN""#,
    ];

    #[test]
    fn every_language_draws_the_invoice_in_its_own_words() {
        let untranslated = language::untranslated_lines(&WORDS, &SPARED);

        assert!(
            untranslated.is_empty(),
            "the invoice says these in more than one language: {untranslated:?}"
        );
    }
}