Unit

The unit module provides standard billing units mapped to their UNECE Recommendation 20 (ZUGFeRD) keys. These units automatically translate their names depending on the active document locale (German, English, Spanish, French, and Italian are supported).

---

Dynamic Unit Resolution

All units are defined as builder functions that accept the document locale.

You can either pass the evaluated unit dictionary directly or pass the function (e.g., unit.hour) to an item or bundle. When a unit function is passed, the engine automatically resolves it using the document's global locale context, ensuring clean and dry document code.

Example Usage:

#import "@preview/invoice-pro:0.4.0": *

#show: invoice.with(
  locale: locale.de-de, // Sets document language to German
  // ...
)

#line-items[
  // Passing the builder function (resolved dynamically to "Stunde" with ZUGFeRD code "HUR")
  #item([IT Consulting], price: 120.00, quantity: 8, unit: unit.hour)

  // Or using shorthand aliases (resolved dynamically to "Meter" with ZUGFeRD code "MTR")
  #item([Network Cable], price: 1.50, quantity: 50, unit: unit.m)

  // Grouping items under a bundle (resolved dynamically to "Satz" with ZUGFeRD code "SET")
  #bundle([Server Rack Bundle], unit: unit.sets)[
    #item([Rack Case], price: 300.00, quantity: 1)
    #item([Power Distribution Unit], price: 80.00, quantity: 2)
  ]
]

---

Predefined Units and Aliases

Below is a complete index of all predefined units, their ZUGFeRD XML codes, and their available shorter/longer aliases.

Standard Function	Code	Shorthand / Alternative Aliases
piece(locale)	H87	pieces, stk, pc, pcs (default unit for item/bundle)
unit-set(locale)	SET	set-unit, sets
pair(locale)	PR	pairs, pr
lump-sum(locale)	LS	lumpsum, ls, pauschal, flat
hour(locale)	HUR	hours, h, hr, hrs
day(locale)	DAY	days, d
month(locale)	MON	months, mo
year(locale)	ANN	years, y, yr
kilogram(locale)	KGM	kilograms, kg
gram(locale)	GRM	grams, g
tonne(locale)	TNE	tonnes, t
metre(locale)	MTR	metres, meter, meters, m
square-metre(locale)	MTK	square-metres, square-meter, square-meters, sqm, m2
millimetre(locale)	MMT	millimetres, millimeter, millimeters, mm
centimetre(locale)	CMT	centimetres, centimeter, centimeters, cm
kilometre(locale)	KMT	kilometres, kilometer, kilometers, km
litre(locale)	LTR	litres, liter, liters, l
cubic-metre(locale)	MTQ	cubic-metres, cubic-meter, cubic-meters, m3

---

Unit Dictionary Schema

Evaluating any unit builder function returns a dictionary with the following format:

(
  code: "HUR",          // UN/CEFACT Recommendation 20 XML code
  name: "Stunde",       // Localized unit name (used for calculations/logic)
  display: "Stunde",    // String/content rendered on the PDF layout
)