A delivery note

//! Draws a delivery note: what left the warehouse, line by line, each article
//! carrying the barcode a scanner reads it back by, and a box the receiver
//! ticks.
//!
//! This is the document that travels with the goods. It shows a table put to a
//! use text alone cannot serve: every line's box is asked for by position, so a
//! barcode lands against its own article and a tick box against its own line.
//! [`Placement::row_top`] and [`Placement::row_height`] are what make that
//! possible — the table decides the geometry, and the page draws into it.
//!
//! Whether the barcodes scan is not for the page to say, and not for an eye: a
//! scanner says. `scripts/check_barcode.sh` points a decoder at the rendered
//! page and reads the article numbers back.
//!
//! Every word the page draws is held in `Words`, once per language, and
//! `HQF_PDF_LANG` picks which one is drawn. The article numbers, the
//! quantities, the weight and the numbers the note and the consignment answer
//! to are the same in both, and so is what a scanner reads off the page.
//!
//! Usage: `cargo run --example write_delivery_note -- tmp/delivery.pdf
//! [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_delivery_note --
//! tmp/bon.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::{
    Cell, ColumnWidth, Columns, Padding, Placement, Row, Rule, Stroke, Table, VAlign,
};
use hqf_pdf::{Align, Code128, Document, Ean13, Font, FontHandle, Image, ImageHandle, Page, 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 sender'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,
};

/// The columns the table is cut into, in points. The description takes whatever
/// the others leave it.
const ARTICLE_WIDTH: f64 = 104.0;
const ORDERED_WIDTH: f64 = 52.0;
const DELIVERED_WIDTH: f64 = 56.0;
const RECEIVED_WIDTH: f64 = 58.0;

/// The width of the narrowest bar of an article's barcode, in points. An EAN-13
/// is 95 of them wide, and the quiet zone either side is ten more.
const MODULE: f64 = 0.62;
/// How tall those bars are drawn, in points.
const BAR_HEIGHT: f64 = 21.0;

/// How many lines the note delivers.
const LINE_COUNT: usize = 6;

/// One line of the delivery note, apart from what the article is called: the
/// figures read the same whatever language the page is set in.
struct Line {
    /// The article number, thirteen digits, check digit included.
    article: &'static str,
    /// How many the order asked for.
    ordered: u32,
    /// How many actually went into the parcels.
    delivered: u32,
}

/// The lines this note delivers, in the order `Words::labels` names them. The
/// fourth is short: the note says so rather than quietly billing what never
/// left.
const LINES: [Line; LINE_COUNT] = [
    Line {
        article: "3760012844104",
        ordered: 12,
        delivered: 12,
    },
    Line {
        article: "3760012844272",
        ordered: 50,
        delivered: 50,
    },
    Line {
        article: "3760012844340",
        ordered: 8,
        delivered: 8,
    },
    Line {
        article: "3760012844418",
        ordered: 4,
        delivered: 2,
    },
    Line {
        article: "3760012844586",
        ordered: 12,
        delivered: 12,
    },
    Line {
        article: "3760012844654",
        ordered: 20,
        delivered: 20,
    },
];

/// What the note is called, the order it answers, and who carried the goods.
const NUMBER: &str = "DN-2026-0871";
const ORDER: &str = "PO-4471-NW";
const CARRIER: &str = "Northlight Express";
/// The number the carrier tracks the consignment by, and which the code at the
/// foot of the page carries.
const CONSIGNMENT: &str = "GX-2026-0871-004";

/// How many parcels the consignment came to, and what they weigh together.
const PARCELS: u32 = 4;
const WEIGHT: &str = "38.4 kg";

/// Every word the page draws, in one language.
///
/// What is not language stays out of it: the article numbers, the quantities,
/// the weight, the numbers the note and the consignment answer to, and the
/// sender's and receiver's names and addresses are drawn from constants of
/// their own and read the same in every language.
#[derive(Debug)]
struct Words {
    /// The words the document's title is built from.
    note: &'static str,
    /// The words set large at the head of the page.
    heading: &'static str,
    /// What stands before the note's own number.
    number_label: &'static str,
    /// What stands before the order the note answers.
    order_label: &'static str,
    /// What stands before the day the goods left, and that day as this language
    /// writes it.
    shipped_label: &'static str,
    shipped_date: &'static str,
    /// The heading over the receiver, and the line that sends the goods to the
    /// door that takes them in.
    deliver_to: &'static str,
    goods_inwards: &'static str,
    /// The heading over the carrier, and what the parcels are counted in.
    carried_by: &'static str,
    parcels: &'static str,
    /// What each article is called, in the order `LINES` delivers them.
    labels: [&'static str; LINE_COUNT],
    /// The five column headings of the table.
    article: &'static str,
    description: &'static str,
    ordered: &'static str,
    delivered: &'static str,
    received: &'static str,
    /// The heading over the foot of the page, and the two lines of small print
    /// under it.
    receipt: &'static str,
    terms_first: &'static str,
    terms_second: &'static str,
    /// What each of the two signature lines is for.
    driver: &'static str,
    received_by: &'static str,
    /// The word before the sender's tax number in the footer.
    vat: &'static str,
}

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

/// The note in English.
const ENGLISH: Words = Words {
    note: "Delivery note",
    heading: "DELIVERY NOTE",
    number_label: "Note No.",
    order_label: "Your order",
    shipped_label: "Shipped",
    shipped_date: "20 July 2026",
    deliver_to: "DELIVER TO",
    goods_inwards: "Goods inwards",
    carried_by: "CARRIED BY",
    parcels: "parcels",
    labels: [
        "Rack server rail kit, 1U",
        "Patch cable Cat 6A, 2 m, grey",
        "SFP+ transceiver, 10G, multimode",
        "Fibre patch panel, 24 port",
        "Cable management arm",
        "Blanking panel, 1U, toolless",
    ],
    article: "Article",
    description: "Description",
    ordered: "Ordered",
    delivered: "Delivered",
    received: "Received",
    receipt: "RECEIPT",
    terms_first: "Tick each line received, then sign. Damage or shortage must be noted",
    terms_second: "here on delivery: a claim made later cannot be traced to the carrier.",
    driver: "Driver",
    received_by: "Received by (name and date)",
    vat: "VAT",
};

/// The note in French.
const FRENCH: Words = Words {
    note: "Bon de livraison",
    heading: "BON DE LIVRAISON",
    number_label: "Bon n°",
    order_label: "Votre commande",
    shipped_label: "Expédié le",
    shipped_date: "20 juillet 2026",
    deliver_to: "LIVRER À",
    goods_inwards: "Service réception",
    carried_by: "TRANSPORTEUR",
    parcels: "colis",
    labels: [
        "Kit de rails pour serveur en baie, 1U",
        "Cordon de brassage Cat 6A, 2 m, gris",
        "Module SFP+ 10G, multimode",
        "Panneau de brassage fibre, 24 ports",
        "Bras de guidage des câbles",
        "Plastron d'obturation, 1U, sans outil",
    ],
    article: "Article",
    description: "Désignation",
    ordered: "Qté cdée",
    delivered: "Qté livrée",
    received: "Reçu",
    receipt: "RÉCEPTION",
    terms_first: "Cochez chaque ligne reçue, puis signez. Toute avarie ou tout manquant doit",
    terms_second: "être signalé ici à la livraison : une réserve tardive n'est plus \
        opposable au transporteur.",
    driver: "Chauffeur",
    received_by: "Reçu par (nom et date)",
    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)];

/// 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,
    );
}

/// Draws a line of text centred on `centre`.
fn text_centred(
    content: &mut Content,
    font: &FontHandle,
    size: f64,
    centre: f64,
    y: f64,
    color: Rgb,
    s: &str,
) {
    text(
        content,
        font,
        size,
        centre - font.measure(s, size) / 2.0,
        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 note's table: a heading row, then one row per line delivered.
///
/// The article column is left empty of everything but its digits: the barcode
/// is drawn into the space above them once the table has said where the row
/// sits. The rows are given a height that space needs.
fn lines_table<'a>(
    font: &'a FontHandle,
    words: &'static Words,
) -> Result<Table<'a>, hqf_pdf::Error> {
    let columns = Columns::new(
        vec![
            ColumnWidth::Points(ARTICLE_WIDTH),
            ColumnWidth::Fraction(1.0),
            ColumnWidth::Points(ORDERED_WIDTH),
            ColumnWidth::Points(DELIVERED_WIDTH),
            ColumnWidth::Points(RECEIVED_WIDTH),
        ],
        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::VerticalOther, Stroke::new(0.25, Rgb::gray(0.85)))
        .rule(Rule::Horizontal(1), Stroke::new(0.8, ACCENT));

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

    table.push(
        Row::new()
            .cell(heading(words.article).align(Align::Center))
            .cell(heading(words.description))
            .cell(heading(words.ordered).align(Align::Right))
            .cell(heading(words.delivered).align(Align::Right))
            .cell(heading(words.received).align(Align::Center))
            .min_height(22.0),
    );

    for (line, label) in LINES.iter().zip(words.labels) {
        // A line delivered short is called out where the eye lands on it.
        let short = line.delivered < line.ordered;
        let delivered_ink = if short {
            Rgb {
                r: 0.70,
                g: 0.18,
                b: 0.12,
            }
        } else {
            INK
        };

        table.push(
            Row::new()
                .cell(
                    Cell::new(font, 6.5, line.article)
                        .padding(pad)
                        .align(Align::Center)
                        .valign(VAlign::Bottom),
                )
                .cell(
                    Cell::new(font, 9.0, label)
                        .padding(pad)
                        .valign(VAlign::Middle),
                )
                .cell(
                    Cell::new(font, 9.0, line.ordered.to_string())
                        .padding(pad)
                        .align(Align::Right)
                        .valign(VAlign::Middle),
                )
                .cell(
                    Cell::new(font, 9.0, line.delivered.to_string())
                        .padding(pad)
                        .align(Align::Right)
                        .valign(VAlign::Middle)
                        .color(delivered_ink),
                )
                .cell(Cell::new(font, 9.0, "").padding(pad))
                .min_height(44.0),
        );
    }

    Ok(table)
}

/// Draws each line's barcode above its article number, and the box the receiver
/// ticks, into the rows the table has already placed.
///
/// Row 0 is the heading, so the lines start at row 1. Asking the placement for
/// a row it never placed gives nothing back, which is what stops the walk at
/// the foot of the page.
fn marks_on_rows(
    content: &mut Content,
    placed: &Placement<'_>,
) -> Result<(), Box<dyn std::error::Error>> {
    // An EAN-13 is a fixed 95 modules wide, and the quiet zone the standard
    // asks for either side is ten more. The column holds all of it.
    let bar_width =
        f64::from(u32::try_from(Ean13::new(LINES[0].article)?.module_count())?) * MODULE;
    let bars_left = LEFT + (ARTICLE_WIDTH - bar_width) / 2.0;
    let tick_left = LEFT + TABLE_WIDTH - RECEIVED_WIDTH / 2.0 - 6.0;

    for (index, line) in LINES.iter().enumerate() {
        let Some(top) = placed.row_top(index + 1) else {
            break;
        };
        let Some(height) = placed.row_height(index + 1) else {
            break;
        };
        let bottom = top - height;

        // The bars sit above the digits the cell drew, and the quiet zone
        // either side of them stays empty: the column is wide enough to hold
        // both.
        content.set_fill(INK)?;
        let code = Ean13::new(line.article)?;
        content.draw_ean13(&code, bars_left, bottom + 15.0, bar_width, BAR_HEIGHT)?;

        // A box to tick, centred in its column and in the row.
        content.set_stroke(Rgb::gray(0.45))?;
        content.set_line_width(0.7)?;
        content.rect(tick_left, bottom + (height - 12.0) / 2.0, 12.0, 12.0)?;
        content.stroke();
    }

    Ok(())
}

/// Draws the letterhead: the mark, the sender's name, what the page is, and the
/// numbers it answers to, 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,
        "42 lot les Genêts, 13480 Calas, France",
    );
    text(content, font, 8.5, LEFT, 756.0, MUTED, "www.hqf.fr");

    text_right(content, font, 26.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!("{}  {ORDER}", words.order_label),
    );
    text_right(
        content,
        font,
        9.5,
        RIGHT,
        744.0,
        MUTED,
        &format!("{}  {}", words.shipped_label, words.shipped_date),
    );

    rule(content, 730.0, 1.2, ACCENT)
}

/// Draws who the goods went to, and how they travelled.
fn parties(content: &mut Content, font: &FontHandle, words: &Words) {
    text(content, font, 8.0, LEFT, 712.0, MUTED, words.deliver_to);
    text(
        content,
        font,
        11.0,
        LEFT,
        697.0,
        INK,
        "Northwind Trading SARL",
    );
    text(content, font, 9.0, LEFT, 683.0, MUTED, words.goods_inwards);
    text(content, font, 9.0, LEFT, 671.0, MUTED, "18 quai du Port");
    text(
        content,
        font,
        9.0,
        LEFT,
        659.0,
        MUTED,
        "13002 Marseille, France",
    );

    text_right(content, font, 8.0, RIGHT, 712.0, MUTED, words.carried_by);
    text_right(content, font, 11.0, RIGHT, 697.0, INK, CARRIER);
    text_right(
        content,
        font,
        9.0,
        RIGHT,
        683.0,
        MUTED,
        &format!("{PARCELS} {} · {WEIGHT}", words.parcels),
    );
    text_right(content, font, 9.0, RIGHT, 671.0, MUTED, CONSIGNMENT);
}

/// Draws the foot of the page: the consignment's own code, what the receiver is
/// agreeing to, and the two lines they sign it on.
fn receipt(
    content: &mut Content,
    font: &FontHandle,
    words: &Words,
    table_bottom: f64,
) -> Result<(), Box<dyn std::error::Error>> {
    let top = table_bottom - 34.0;

    text(content, font, 10.0, LEFT, top, ACCENT, words.receipt);
    text(
        content,
        font,
        8.5,
        LEFT,
        top - 15.0,
        MUTED,
        words.terms_first,
    );
    text(
        content,
        font,
        8.5,
        LEFT,
        top - 26.0,
        MUTED,
        words.terms_second,
    );

    // The consignment travels as one code, which is what the carrier scans at
    // each hand-over.
    let code = Code128::new(CONSIGNMENT)?;
    let module = 0.85;
    let width = f64::from(u32::try_from(code.module_count())?) * module;
    let bars_left = RIGHT - width;
    content.set_fill(INK)?;
    content.draw_barcode(&code, bars_left, top + 2.0, width, 26.0)?;
    text_centred(
        content,
        font,
        7.5,
        bars_left + width / 2.0,
        top - 8.0,
        MUTED,
        CONSIGNMENT,
    );

    // Two lines to sign on, side by side, held down at the foot of the page
    // rather than under the words: that is where a hand reaches for them, and
    // where the space left for a note about damage ends up.
    let sign_y = 150.0;
    let column = (TABLE_WIDTH - 40.0) / 2.0;
    for (offset, who) in [(0.0, words.driver), (column + 40.0, words.received_by)] {
        let x = LEFT + offset;
        content.set_stroke(Rgb::gray(0.55))?;
        content.set_line_width(0.6)?;
        content.move_to(x, sign_y)?;
        content.line_to(x + column, sign_y)?;
        content.stroke();
        text(content, font, 8.0, x, sign_y - 11.0, MUTED, who);
    }

    // The foot of the page: who sent the goods.
    rule(content, 74.0, 0.5, Rgb::gray(0.8))?;
    let mentions = format!(
        "HQF Development · 42 lot les Genêts, 13480 Calas, France · \
        SIRET 752 492 777 00012 · APE 6202A · {} FR59 752 492 777",
        words.vat
    );
    text_centred(
        content,
        font,
        7.0,
        LEFT + TABLE_WIDTH / 2.0,
        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("delivery_note")));
    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.note));

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

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

    // The lines, fitted onto this page, and then drawn into: the table settles
    // the geometry first so the barcodes and tick boxes know where to land.
    let table = lines_table(&font, words)?;
    let table_top = 630.0;
    let placed = table.fit(LEFT, table_top, table_top - 250.0, 0)?;
    placed.draw(&mut content)?;
    marks_on_rows(&mut content, &placed)?;

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

    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)?;

    let short: u32 = LINES.iter().map(|line| line.ordered - line.delivered).sum();
    println!(
        "wrote {path}: {} bytes, {} lines, {short} short",
        bytes.len(),
        LINES.len()
    );
    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] = [
        // A stock line is headed by the same word in French as in English.
        r#"article: "Article""#,
    ];

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

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