An archivable PDF/A-3 form

//! Writes an archival form: a PDF/A-3 file a reader fills in.
//!
//! A form and an archival file pull in opposite directions. A form leaves its
//! fields for the reader's software to draw; an archival file forbids exactly
//! that, and demands every mark be baked into the page. This reconciles them:
//! each field carries its own appearance — a text value drawn as glyphs, a tick
//! or dot drawn as a vector — so the file needs no reader help and no font it
//! does not embed.
//!
//! A form field draws no border of its own: the PDF standard leaves widgets
//! borderless by default, so a reader sees only what the page draws behind
//! them. This example gives every field a border, so the boxes a reader clicks
//! are plain to see, and says as much on the page. The borders are optional —
//! the same form is valid without them.
//!
//! Whether the result is really PDF/A-3 is not for us to say. `veraPDF` says,
//! and `scripts/check_pdfa.sh` asks it.
//!
//! The labels, the options and the metadata are held in `Words`, once per
//! language, and `HQF_PDF_LANG` picks which set is drawn. A field's name is not
//! among them: it is what a filled form's data comes back under, so it stays
//! the same whichever language the page is drawn in.
//!
//! Usage: `cargo run --example write_archival_form -- tmp/archival_form.pdf
//! [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_archival_form --
//! tmp/formulaire_archive.pdf`

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

use hqf_pdf::content::Content;
use hqf_pdf::metadata::xmp::{Metadata, PdfA};
use hqf_pdf::{
    CheckBox, ChoiceField, Document, Font, FontHandle, FormField, License, Page, RadioGroup, 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")
}

/// When the form was drawn up. The library never reads the clock — a document
/// that stamped itself with the time would be a different file on every build —
/// so the caller says when.
const ISSUED: &str = "2026-07-14T09:30:00+02:00";

/// Who drew the form up, and the value the name field starts with. Neither is
/// language.
const AUTHOR: &str = "Olivier Pons";
const REGISTERED_NAME: &str = "Ada Lovelace";

/// The names the two radio buttons send back, in the order they are drawn.
const PAYMENT_VALUES: [&str; 2] = ["card", "transfer"];

/// The words the page is written in, one set per language.
///
/// A field's name is not here: it is the name a filled form's data comes back
/// under, and a reader that changed language would send back something else.
/// The metadata is, because a reader reads it beside the page.
#[derive(Debug)]
struct Words {
    /// The line at the head of the page.
    title: &'static str,
    /// What the two lines under the title say the boxes are.
    boxes_are_fields: &'static str,
    /// What the second of them says about their borders.
    borders_are_optional: &'static str,
    /// The label beside the field a reader gives a name in.
    name: &'static str,
    /// The label beside the field a reader gives an address in.
    email: &'static str,
    /// The line beside the check box.
    subscribe: &'static str,
    /// The label beside the drop-down.
    plan: &'static str,
    /// The options the drop-down offers; the second is the one it starts on.
    plans: [&'static str; 2],
    /// The label beside the radio buttons.
    payment: &'static str,
    /// The line beside each radio button, in the order they are drawn.
    payments: [&'static str; 2],
    /// The title the document carries in its metadata.
    document_title: &'static str,
    /// What its metadata says the document is.
    document_subject: &'static str,
}

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

/// The page in English.
const ENGLISH: Words = Words {
    title: "Registration",
    boxes_are_fields: "The boxes below are clickable form fields.",
    borders_are_optional: "Their borders are optional: the standard draws none by default.",
    name: "Name",
    email: "Email",
    subscribe: "Subscribe to the newsletter",
    plan: "Plan",
    plans: ["Monthly", "Yearly"],
    payment: "Payment",
    payments: ["Card", "Transfer"],
    document_title: "A registration form",
    document_subject: "A fillable form that is also an archival file",
};

/// The page in French.
const FRENCH: Words = Words {
    title: "Inscription",
    boxes_are_fields: "Les cases ci-dessous sont des champs à remplir.",
    borders_are_optional: "Leur bordure est facultative : la norme n'en dessine aucune.",
    name: "Nom",
    email: "Courriel",
    subscribe: "S'abonner à la lettre d'information",
    plan: "Formule",
    plans: ["Mensuelle", "Annuelle"],
    payment: "Paiement",
    payments: ["Carte", "Virement"],
    document_title: "Un formulaire d'inscription",
    document_subject: "Un formulaire à remplir qui est aussi un fichier d'archive",
};

/// 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)];

/// The size the labels and the field text are set at.
const SIZE: f64 = 12.0;

/// The colour every field's border is stroked in.
const BORDER: Rgb = Rgb::gray(0.6);
/// The width every field's border is stroked at, in points.
const BORDER_WIDTH: f64 = 0.75;

/// Draws one line of text, with its baseline at `(x, y)`.
fn draw(
    content: &mut Content,
    font: &FontHandle,
    x: f64,
    y: f64,
    text: &str,
) -> Result<(), hqf_pdf::Error> {
    content.begin_text();
    content.set_font(font.name(), SIZE)?;
    content.text_origin(x, y)?;
    content.show_glyphs(&font.glyphs(text));
    content.end_text();
    Ok(())
}

/// The form page: a label and a fillable box for each field, one of every kind.
fn form_page(font: &FontHandle, words: &'static Words) -> Result<Page, hqf_pdf::Error> {
    let mut content = Content::new();
    let mut page = Page::a4();

    draw(&mut content, font, 72.0, 760.0, words.title)?;
    draw(&mut content, font, 72.0, 738.0, words.boxes_are_fields)?;
    draw(&mut content, font, 72.0, 722.0, words.borders_are_optional)?;

    // A filled text field and an empty one: the empty field's baked appearance
    // is empty, which is what makes the file archival without hiding the field.
    draw(&mut content, font, 72.0, 700.0, words.name)?;
    page.fields.push(
        FormField::new("Name", 180.0, 697.0, 240.0, SIZE + 4.0, font.name(), SIZE)
            .value(REGISTERED_NAME)
            .border(BORDER, BORDER_WIDTH)
            .into(),
    );

    draw(&mut content, font, 72.0, 664.0, words.email)?;
    page.fields.push(
        FormField::new("Email", 180.0, 661.0, 240.0, SIZE + 4.0, font.name(), SIZE)
            .border(BORDER, BORDER_WIDTH)
            .into(),
    );

    draw(&mut content, font, 90.0, 628.0, words.subscribe)?;
    page.fields.push(
        CheckBox::new("Subscribe", 72.0, 626.0, SIZE, SIZE)
            .checked()
            .border(BORDER, BORDER_WIDTH)
            .into(),
    );

    draw(&mut content, font, 72.0, 592.0, words.plan)?;
    page.fields.push(
        ChoiceField::new("Plan", 180.0, 589.0, 240.0, SIZE + 4.0, font.name(), SIZE)
            .option(words.plans[0])
            .option(words.plans[1])
            .selected(words.plans[1])
            .dropdown()
            .border(BORDER, BORDER_WIDTH)
            .into(),
    );

    draw(&mut content, font, 72.0, 556.0, words.payment)?;
    page.fields.push(
        RadioGroup::new("Payment")
            .option(PAYMENT_VALUES[0], 180.0, 553.0, SIZE, SIZE)
            .option(PAYMENT_VALUES[1], 320.0, 553.0, SIZE, SIZE)
            .selected(PAYMENT_VALUES[0])
            .border(BORDER, BORDER_WIDTH)
            .into(),
    );
    draw(&mut content, font, 198.0, 556.0, words.payments[0])?;
    draw(&mut content, font, 338.0, 556.0, words.payments[1])?;

    page.content = content.into_bytes();
    Ok(page)
}

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

    let mut args: Vec<String> = env::args().skip(1).collect();

    let evaluation = args.iter().any(|arg| arg == "--evaluation");
    args.retain(|arg| !arg.starts_with("--"));

    let mut args = args.into_iter();
    // 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("archival_form")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

    let mut doc = Document::new();
    doc.set_license(if evaluation {
        License::evaluation()
    } else {
        licence::licensed()
    });
    doc.set_conformance(PdfA::A3B);
    doc.set_metadata(Metadata {
        title: Some(words.document_title.to_owned()),
        author: Some(AUTHOR.to_owned()),
        subject: Some(words.document_subject.to_owned()),
        producer: Some("hqf-pdf".to_owned()),
        created: Some(ISSUED.to_owned()),
        ..Metadata::default()
    });

    let font = doc.add_font(Font::parse(fs::read(&font_path)?)?);
    doc.add_page(form_page(&font, words)?)?;

    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", bytes.len());
    Ok(())
}

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

    /// The lines two languages are allowed to write the same way. There are
    /// none: every word on this page and in its metadata differs.
    const SPARED: [&str; 0] = [];

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

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