@formfeed/engine 0.3.4 → 0.3.6

package/index.cjs

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   DEFAULT_CHROME_PADDING: () => DEFAULT_CHROME_PADDING,
   DefaultHelperRegistry: () => DefaultHelperRegistry,
+  EPC_MAX_BYTES: () => EPC_MAX_BYTES,
   EngineSyntaxError: () => EngineSyntaxError,
   OFFICE_FILLED_MAX_BYTES: () => OFFICE_FILLED_MAX_BYTES,
   OfficeTemplateError: () => OfficeTemplateError,
@@ -68,6 +69,7 @@ __export(index_exports, {
   getEngine: () => getEngine,
   handlebarsEngine: () => handlebarsEngine,
   helperDocs: () => helperDocs,
+  ibanChecksum: () => ibanChecksum,
   imageMarkup: () => imageMarkup,
   imageOutput: () => imageOutput,
   importApitemplate: () => importApitemplate,
@@ -92,6 +94,7 @@ __export(index_exports, {
   mergeSettings: () => mergeSettings,
   mergeSnippetCss: () => mergeSnippetCss,
   mergeSnippetI18n: () => mergeSnippetI18n,
+  normaliseIban: () => normaliseIban,
   normalisePartialName: () => normalisePartialName,
   nunjucksBuiltinFilters: () => nunjucksBuiltinFilters,
   officeDrawingLimits: () => officeDrawingLimits,
@@ -122,8 +125,10 @@ __export(index_exports, {
   starterDocument: () => starterDocument,
   starterPresentation: () => starterPresentation,
   strftimeToDateFns: () => strftimeToDateFns,
+  svgDataUri: () => svgDataUri,
   toDate: () => toDate,
   toNumber: () => toNumber,
+  validateEpc: () => validateEpc,
   zoomGestureScript: () => zoomGestureScript
 });
 module.exports = __toCommonJS(index_exports);
@@ -207,8 +212,234 @@ function depthGuard(resolve2, includeDepth) {
 
 // packages/engine/src/lib/helpers/codes.ts
 var import_bwip_js = require("bwip-js");
+
+// packages/engine/src/lib/values.ts
+function toNumber(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const n = Number(value.replace(/\s/g, "").replace(",", "."));
+    return Number.isFinite(n) ? n : NaN;
+  }
+  if (typeof value === "bigint") return Number(value);
+  return NaN;
+}
+
+// packages/engine/src/lib/codes/epc.ts
+function epcPayload(input) {
+  const amount = input.amount === void 0 || input.amount === "" ? "" : `EUR${toNumber(input.amount).toFixed(2)}`;
+  return [
+    "BCD",
+    "002",
+    "1",
+    "SCT",
+    (input.bic ?? "").replace(/\s/g, ""),
+    String(input.name ?? "").slice(0, 70),
+    String(input.iban ?? "").replace(/\s/g, ""),
+    amount,
+    (input.purpose ?? "").slice(0, 4),
+    (input.reference ?? "").slice(0, 35),
+    input.reference ? "" : (input.text ?? "").slice(0, 140),
+    ""
+  ].join("\n");
+}
+var IBAN_LENGTHS = {
+  AD: 24,
+  AT: 20,
+  BE: 16,
+  BG: 22,
+  CH: 21,
+  CY: 28,
+  CZ: 24,
+  DE: 22,
+  DK: 18,
+  EE: 20,
+  ES: 24,
+  FI: 18,
+  FO: 18,
+  FR: 27,
+  GB: 22,
+  GI: 23,
+  GL: 18,
+  GR: 27,
+  HR: 21,
+  HU: 28,
+  IE: 22,
+  IS: 26,
+  IT: 27,
+  LI: 21,
+  LT: 20,
+  LU: 20,
+  LV: 21,
+  MC: 27,
+  MT: 31,
+  NL: 18,
+  NO: 15,
+  PL: 28,
+  PT: 25,
+  RO: 24,
+  SE: 24,
+  SI: 19,
+  SK: 24,
+  SM: 27,
+  VA: 22
+};
+var EPC_MAX_BYTES = 331;
+var byteLength = (value) => new TextEncoder().encode(value).length;
+var normaliseIban = (iban) => iban.replace(/\s/g, "").toUpperCase();
+function ibanChecksum(iban) {
+  const rearranged = normaliseIban(iban).slice(4) + normaliseIban(iban).slice(0, 4);
+  const digits = [...rearranged].map((c) => c >= "A" && c <= "Z" ? String(c.charCodeAt(0) - 55) : c).join("");
+  let remainder = 0;
+  for (const digit of digits) remainder = (remainder * 10 + Number(digit)) % 97;
+  return remainder === 1;
+}
+function validateEpc(input) {
+  const problems = [];
+  const name = String(input.name ?? "").trim();
+  if (!name) problems.push({ field: "name", code: "required" });
+  else if (name.length > 70) problems.push({ field: "name", code: "too_long", max: 70, actual: name.length });
+  const iban = normaliseIban(String(input.iban ?? ""));
+  if (!iban) problems.push({ field: "iban", code: "required" });
+  else if (!/^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$/.test(iban)) problems.push({ field: "iban", code: "iban_characters" });
+  else {
+    const expected = IBAN_LENGTHS[iban.slice(0, 2)];
+    if (expected !== void 0 && iban.length !== expected)
+      problems.push({ field: "iban", code: "iban_country_length", max: expected, actual: iban.length });
+    else if (!ibanChecksum(iban)) problems.push({ field: "iban", code: "iban_checksum" });
+  }
+  const bic = String(input.bic ?? "").replace(/\s/g, "").toUpperCase();
+  if (bic && !/^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/.test(bic)) problems.push({ field: "bic", code: "bic_format" });
+  if (input.amount !== void 0 && input.amount !== "") {
+    const amount = toNumber(input.amount);
+    if (Number.isNaN(amount)) problems.push({ field: "amount", code: "not_a_number" });
+    else if (amount < 0.01 || amount > 99999999999e-2) problems.push({ field: "amount", code: "out_of_range" });
+  }
+  const purpose = String(input.purpose ?? "");
+  if (purpose.length > 4) problems.push({ field: "purpose", code: "too_long", max: 4, actual: purpose.length });
+  const reference = String(input.reference ?? "").trim();
+  const text = String(input.text ?? "").trim();
+  if (reference && text) problems.push({ field: "reference", code: "reference_or_text" });
+  if (reference.length > 35)
+    problems.push({ field: "reference", code: "too_long", max: 35, actual: reference.length });
+  if (text.length > 140) problems.push({ field: "text", code: "too_long", max: 140, actual: text.length });
+  const bytes = byteLength(epcPayload(input));
+  if (bytes > EPC_MAX_BYTES)
+    problems.push({ field: "payload", code: "too_long", max: EPC_MAX_BYTES, actual: bytes });
+  return problems;
+}
+
+// packages/engine/src/lib/codes/qr.ts
 var import_qrcode = require("qrcode");
 var import_svg_tag = require("qrcode/lib/renderer/svg-tag.js");
+function qrSvg(value, options = {}) {
+  const qr = (0, import_qrcode.create)(value, { errorCorrectionLevel: options.ecc ?? "M" });
+  return (0, import_svg_tag.render)(qr, {
+    width: options.size ?? 160,
+    margin: options.margin ?? 1,
+    color: {
+      dark: (options.color ?? "#000000").replace(/^(#?)/, "#").slice(0, 9),
+      light: (options.background ?? "#ffffff").replace(/^(#?)/, "#")
+    }
+  });
+}
+var svgDataUri = (svg) => `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`;
+
+// packages/engine/src/lib/helpers/codes.ts
+var barcodeTypes = {
+  code128: "code128",
+  ean13: "ean13",
+  ean8: "ean8",
+  upc: "upca",
+  upca: "upca",
+  itf14: "itf14",
+  code39: "code39",
+  qrcode: "qrcode",
+  datamatrix: "datamatrix",
+  pdf417: "pdf417"
+};
+var codeHelpers = [
+  {
+    name: "qrcode",
+    aliases: ["qr"],
+    doc: {
+      signature: "qrcode(value, { size = 160, ecc = 'M', margin = 1, color, background })",
+      description: "QR code as an SVG data URI for an <img> src.",
+      examples: {
+        jinja2: '<img src="{{ qrcode(order.url, { size: 120 }) }}">',
+        liquid: '<img src="{{ order.url | qrcode: size: 120 }}">',
+        handlebars: '<img src="{{qrcode order.url size=120}}">'
+      },
+      category: "code"
+    },
+    fn: (ctx, value, options) => {
+      const o = options ?? {};
+      const svg = qrSvg(String(value ?? ""), o);
+      if (ctx.drawing) return ctx.drawing({ kind: "svg", svg, width: o.size, height: o.size, alt: "QR code" });
+      return svgDataUri(svg);
+    }
+  },
+  {
+    name: "barcode",
+    doc: {
+      signature: "barcode(value, { type = 'code128', height = 12, width, text = true, scale = 2 })",
+      description: "Barcode (code128, ean13, ean8, upc, itf14, code39, datamatrix, pdf417) as an SVG data URI.",
+      examples: {
+        jinja2: `<img src="{{ barcode(item.sku, { type: 'code128' }) }}">`,
+        liquid: `<img src="{{ item.sku | barcode: type: 'code128' }}">`,
+        handlebars: `<img src="{{barcode item.sku type='code128'}}">`
+      },
+      category: "code"
+    },
+    fn: (ctx, value, options) => {
+      const o = options ?? {};
+      const bcid = barcodeTypes[String(o.type ?? "code128").toLowerCase()] ?? "code128";
+      const svg = (0, import_bwip_js.toSVG)({
+        bcid,
+        text: String(value ?? ""),
+        height: o.height ?? 12,
+        ...o.width === void 0 ? {} : { width: o.width },
+        scale: o.scale ?? 2,
+        includetext: o.text !== false,
+        textxalign: "center"
+      });
+      if (ctx.drawing) return ctx.drawing({ kind: "svg", svg, alt: `Barcode ${String(value ?? "")}` });
+      return svgDataUri(svg);
+    }
+  },
+  {
+    name: "epcQr",
+    aliases: ["epc_qr", "girocode"],
+    doc: {
+      signature: "epcQr({ name, iban, bic?, amount?, reference?, text? }, { size })",
+      description: "SEPA credit transfer QR code (EPC069-12 / GiroCode) that banking apps scan to prefill a payment.",
+      examples: {
+        jinja2: '<img src="{{ epcQr({ name: company.name, iban: company.iban, amount: invoice.total, reference: invoice.number }) }}">',
+        liquid: '<img src="{{ company.iban | epcQr: name: company.name, amount: invoice.total, reference: invoice.number }}">',
+        handlebars: '<img src="{{epcQr name=company.name iban=company.iban amount=invoice.total reference=invoice.number}}">'
+      },
+      category: "code"
+    },
+    // Payment fields and QR options may arrive together: Jinja2 passes two objects, Handlebars one
+    // hash (`{{epcQr name=… iban=… size=200}}`), and Liquid, which cannot build an object literal,
+    // keyword arguments (`{{ company.iban | epcQr: name: company.name, amount: invoice.total }}`,
+    // where a string input is the IBAN). They are merged and split by field name.
+    fn: (ctx, input, options) => {
+      const fields = {
+        ...input && typeof input === "object" ? input : typeof input === "string" && input ? { iban: input } : {},
+        ...options ?? {}
+      };
+      const payment = {};
+      const qr = {};
+      for (const [key, value] of Object.entries(fields))
+        (EPC_FIELDS.has(key) ? payment : qr)[key] = value;
+      const o = { ecc: "M", ...qr };
+      const svg = qrSvg(epcPayload(payment), o);
+      if (ctx.drawing) return ctx.drawing({ kind: "svg", svg, width: o.size, height: o.size, alt: "GiroCode" });
+      return svgDataUri(svg);
+    }
+  }
+];
+var EPC_FIELDS = /* @__PURE__ */ new Set(["name", "iban", "bic", "amount", "reference", "text", "purpose"]);
 
 // packages/engine/src/lib/helpers/format.ts
 var import_tz = require("@date-fns/tz");
@@ -242,15 +473,6 @@ var dateLocales = {
 function dateLocale(locale) {
   return dateLocales[locale] ?? dateLocales[locale.split("-")[0] ?? ""] ?? import_locale.enGB;
 }
-function toNumber(value) {
-  if (typeof value === "number") return value;
-  if (typeof value === "string") {
-    const n = Number(value.replace(/\s/g, "").replace(",", "."));
-    return Number.isFinite(n) ? n : NaN;
-  }
-  if (typeof value === "bigint") return Number(value);
-  return NaN;
-}
 function toDate(value, tz) {
   if (value === "now" || value === void 0 || value === null || value === "")
     return new import_tz.TZDate(Date.now(), tz);
@@ -273,6 +495,10 @@ function escapeHtml(value) {
 var isNamedArgs = (v) => !!v && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date);
 var str = (v) => v === void 0 || v === null ? "" : String(v);
 var opt = (v, fallback) => v === void 0 || v === null || v === "" ? fallback : v;
+function requireFinite(helper, value) {
+  if (typeof value === "number" && !Number.isFinite(value))
+    throw new Error(`${helper}: got ${value}, the result of a calculation with a value that is missing or not a number`);
+}
 var wordsByLang = {
   de: import_de.toCardinal,
   en: import_en.toCardinal,
@@ -288,11 +514,16 @@ var formatHelpers = [
     deprecatedAlias: { currency_format: "money" },
     doc: {
       signature: "money(value, currency?, locale?)",
-      description: "Formats a number as currency with Intl.NumberFormat. Defaults come from the template settings.",
-      example: "{{ line.total | money('EUR') }} \u2192 1.234,50 \u20AC",
+      description: "Formats a number as currency with Intl.NumberFormat. Defaults come from the template settings. Text that is not a number is printed as it is; a calculation that came out as NaN stops the render.",
+      examples: {
+        jinja2: "{{ line.total | money('EUR') }} \u2192 1.234,50 \u20AC",
+        liquid: "{{ line.total | money: 'EUR' }} \u2192 1.234,50 \u20AC",
+        handlebars: "{{money line.total 'EUR'}} \u2192 1.234,50 \u20AC"
+      },
       category: "format"
     },
     fn: (ctx, value, currency, locale) => {
+      requireFinite("money", value);
       const n = toNumber(value);
       if (Number.isNaN(n)) return str(value);
       return new Intl.NumberFormat(opt(locale, ctx.locale), {
@@ -306,10 +537,15 @@ var formatHelpers = [
     doc: {
       signature: "number(value, decimals?, locale?)",
       description: "Formats a number with grouping. With decimals, exactly that many (rounded half away from zero); without, the decimals the number has, at most three, so 1234.5 \u2192 1.234,5 and 2.34567 \u2192 2,346. Use number(0) for whole numbers.",
-      example: "{{ qty | number(2) }} \u2192 1.234,00",
+      examples: {
+        jinja2: "{{ qty | number(2) }} \u2192 1.234,00",
+        liquid: "{{ qty | number: 2 }} \u2192 1.234,00",
+        handlebars: "{{number qty 2}} \u2192 1.234,00"
+      },
       category: "format"
     },
     fn: (ctx, value, decimals, locale) => {
+      requireFinite("number", value);
       const n = toNumber(value);
       if (Number.isNaN(n)) return str(value);
       const d = decimals === void 0 || decimals === null ? void 0 : Number(decimals);
@@ -324,7 +560,11 @@ var formatHelpers = [
     doc: {
       signature: "date(value, format?, tz?, locale?)",
       description: "Formats a date with date-fns tokens (e.g. 'dd.MM.yyyy', 'PPP'). Accepts ISO strings, epoch numbers and 'now'.",
-      example: "{{ invoice.date | date('dd.MM.yyyy') }}",
+      examples: {
+        jinja2: "{{ invoice.date | date('dd.MM.yyyy') }}",
+        liquid: "{{ invoice.date | date: 'dd.MM.yyyy' }}",
+        handlebars: "{{date invoice.date 'dd.MM.yyyy'}}"
+      },
       category: "format"
     },
     fn: (ctx, value, format, tz, locale) => {
@@ -341,7 +581,11 @@ var formatHelpers = [
     doc: {
       signature: "dateAdd(value, amount, unit)",
       description: "Adds days, weeks, months or years to a date; returns an ISO string for further formatting.",
-      example: "{{ invoice.date | dateAdd(14, 'days') | date('PP') }}",
+      examples: {
+        jinja2: "{{ invoice.date | dateAdd(14, 'days') | date('PP') }}",
+        liquid: "{{ invoice.date | dateAdd: 14, 'days' | date: 'PP' }}",
+        handlebars: "{{date (dateAdd invoice.date 14 'days') 'PP'}}"
+      },
       category: "format"
     },
     fn: (ctx, value, amount, unit) => {
@@ -358,7 +602,11 @@ var formatHelpers = [
     doc: {
       signature: "add(a, b)",
       description: "a + b (Handlebars has no arithmetic of its own).",
-      example: "{{add @index 1}}",
+      examples: {
+        jinja2: "{{ line.qty | add(1) }}",
+        liquid: "{{ line.qty | add: 1 }}",
+        handlebars: "{{#each invoice.lines}}{{add @index 1}}{{/each}}"
+      },
       category: "format"
     },
     fn: (_ctx, a, b) => toNumber(a) + toNumber(b)
@@ -369,7 +617,11 @@ var formatHelpers = [
     doc: {
       signature: "subtract(a, b)",
       description: "a minus b.",
-      example: "{{subtract total discount}}",
+      examples: {
+        jinja2: "{{ total | subtract(discount) }}",
+        liquid: "{{ total | subtract: discount }}",
+        handlebars: "{{subtract total discount}}"
+      },
       category: "format"
     },
     fn: (_ctx, a, b) => toNumber(a) - toNumber(b)
@@ -380,7 +632,11 @@ var formatHelpers = [
     doc: {
       signature: "multiply(a, b)",
       description: "a times b.",
-      example: "{{money (multiply line.qty line.price)}}",
+      examples: {
+        jinja2: "{{ line.qty | multiply(line.price) | money }}",
+        liquid: "{{ line.qty | multiply: line.price | money }}",
+        handlebars: "{{money (multiply line.qty line.price)}}"
+      },
       category: "format"
     },
     fn: (_ctx, a, b) => toNumber(a) * toNumber(b)
@@ -391,7 +647,11 @@ var formatHelpers = [
     doc: {
       signature: "divide(a, b)",
       description: "a divided by b; empty when b is 0.",
-      example: "{{divide total count}}",
+      examples: {
+        jinja2: "{{ total | divide(count) }}",
+        liquid: "{{ total | divide: count }}",
+        handlebars: "{{divide total count}}"
+      },
       category: "format"
     },
     fn: (_ctx, a, b) => toNumber(b) === 0 ? "" : toNumber(a) / toNumber(b)
@@ -401,7 +661,11 @@ var formatHelpers = [
     doc: {
       signature: "round(value, decimals = 0, method = 'common')",
       description: "Rounds to the given decimals, as Jinja2's round does: 'common' rounds half away from zero, 'floor' always down and 'ceil' always up.",
-      example: "{{ 2.345 | round(2) }} gives 2.35, {{ 2.349 | round(2, 'floor') }} gives 2.34",
+      examples: {
+        jinja2: "{{ 2.345 | round(2) }} gives 2.35, {{ 2.349 | round(2, 'floor') }} gives 2.34",
+        liquid: "{{ 2.345 | round: 2 }} gives 2.35, {{ 2.349 | round: 2, 'floor' }} gives 2.34",
+        handlebars: "{{round 2.345 2}} gives 2.35, {{round 2.349 2 'floor'}} gives 2.34"
+      },
       category: "format"
     },
     // `round(2, method='floor')` (Jinja2) and `round: 2, method: 'floor'` (Liquid) arrive as a
@@ -427,7 +691,11 @@ var formatHelpers = [
     doc: {
       signature: "upper(value)",
       description: "Upper-cases a string.",
-      example: "{{ name | upper }}",
+      examples: {
+        jinja2: "{{ name | upper }}",
+        liquid: "{{ name | upper }}",
+        handlebars: "{{upper name}}"
+      },
       category: "text"
     },
     fn: (_ctx, value) => str(value).toUpperCase()
@@ -438,7 +706,11 @@ var formatHelpers = [
     doc: {
       signature: "lower(value)",
       description: "Lower-cases a string.",
-      example: "{{ name | lower }}",
+      examples: {
+        jinja2: "{{ name | lower }}",
+        liquid: "{{ name | lower }}",
+        handlebars: "{{lower name}}"
+      },
       category: "text"
     },
     fn: (_ctx, value) => str(value).toLowerCase()
@@ -449,7 +721,11 @@ var formatHelpers = [
     doc: {
       signature: "title(value)",
       description: "Capitalises every word.",
-      example: "{{ 'hello world' | title }} \u2192 Hello World",
+      examples: {
+        jinja2: "{{ 'hello world' | title }} \u2192 Hello World",
+        liquid: "{{ 'hello world' | title }} \u2192 Hello World",
+        handlebars: "{{title 'hello world'}} \u2192 Hello World"
+      },
       category: "text"
     },
     fn: (_ctx, value) => str(value).replace(
@@ -462,7 +738,11 @@ var formatHelpers = [
     doc: {
       signature: "truncate(value, length = 255, suffix = '\u2026')",
       description: "Cuts a string to `length` characters and appends the suffix when cut.",
-      example: "{{ description | truncate(40) }}",
+      examples: {
+        jinja2: "{{ description | truncate(40) }}",
+        liquid: "{{ description | truncate: 40 }}",
+        handlebars: "{{truncate description 40}}"
+      },
       category: "text"
     },
     fn: (_ctx, value, length, suffix) => {
@@ -477,7 +757,11 @@ var formatHelpers = [
     doc: {
       signature: "replace(value, search, replacement)",
       description: "Replaces every occurrence of `search`.",
-      example: "{{ iban | replace(' ', '') }}",
+      examples: {
+        jinja2: "{{ iban | replace(' ', '') }}",
+        liquid: "{{ iban | replace: ' ', '' }}",
+        handlebars: "{{replace iban ' ' ''}}"
+      },
       category: "text"
     },
     fn: (_ctx, value, search, replacement) => str(value).split(str(search)).join(str(replacement))
@@ -487,7 +771,11 @@ var formatHelpers = [
     doc: {
       signature: "split(value, separator = ',')",
       description: "Splits a string into a list.",
-      example: "{% for tag in tags | split(',') %}",
+      examples: {
+        jinja2: "{% for tag in keywords | split(',') %}{{ tag }}{% endfor %}",
+        liquid: "{% assign tags = keywords | split: ',' %}{% for tag in tags %}{{ tag }}{% endfor %}",
+        handlebars: "{{#each (split keywords ',')}}{{this}}{{/each}}"
+      },
       category: "text"
     },
     fn: (_ctx, value, separator) => str(value).split(str(opt(separator, ",")))
@@ -497,7 +785,11 @@ var formatHelpers = [
     doc: {
       signature: "join(list, separator = ', ')",
       description: "Joins a list into a string.",
-      example: "{{ tags | join(' \xB7 ') }}",
+      examples: {
+        jinja2: "{{ tags | join(' \xB7 ') }}",
+        liquid: "{{ tags | join: ' \xB7 ' }}",
+        handlebars: "{{join tags ' \xB7 '}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value, separator) => Array.isArray(value) ? value.map(str).join(str(opt(separator, ", "))) : str(value)
@@ -508,7 +800,11 @@ var formatHelpers = [
     doc: {
       signature: "default(value, fallback)",
       description: "Returns the fallback when the value is empty, null or undefined.",
-      example: "{{ customer.vat | default('\u2014') }}",
+      examples: {
+        jinja2: "{{ customer.vat | default('\u2014') }}",
+        liquid: "{{ customer.vat | default: '\u2014' }}",
+        handlebars: "{{default customer.vat '\u2014'}}"
+      },
       category: "text"
     },
     fn: (_ctx, value, fallback) => value === void 0 || value === null || value === "" ? fallback : value
@@ -519,7 +815,11 @@ var formatHelpers = [
     doc: {
       signature: "nl2br(value)",
       description: "Escapes the text and turns line breaks into <br>.",
-      example: "{{ address | nl2br }}",
+      examples: {
+        jinja2: "{{ address | nl2br }}",
+        liquid: "{{ address | nl2br }}",
+        handlebars: "{{nl2br address}}"
+      },
       category: "text"
     },
     // office templates turn line breaks into breaks themselves, and escape the text once
@@ -531,7 +831,11 @@ var formatHelpers = [
     doc: {
       signature: "markdown(value)",
       description: "Renders Markdown to HTML (no sanitiser: template data is trusted by the author).",
-      example: "{{ notes | markdown }}",
+      examples: {
+        jinja2: "{{ notes | markdown }}",
+        liquid: "{{ notes | markdown }}",
+        handlebars: "{{markdown notes}}"
+      },
       category: "text"
     },
     fn: (ctx, value) => {
@@ -550,7 +854,11 @@ var formatHelpers = [
     doc: {
       signature: "safe(value)",
       description: "Marks a string as HTML so the engine does not escape it.",
-      example: "{{ html_snippet | safe }}",
+      examples: {
+        jinja2: "{{ html_snippet | safe }}",
+        liquid: "{{ html_snippet | safe }}",
+        handlebars: "{{safe html_snippet}}"
+      },
       category: "text"
     },
     fn: (_ctx, value) => str(value)
@@ -561,7 +869,11 @@ var formatHelpers = [
     doc: {
       signature: "json(value, indent = 2)",
       description: "Serialises a value as JSON; handy while building a template.",
-      example: "<pre>{{ invoice | json }}</pre>",
+      examples: {
+        jinja2: "<pre>{{ invoice | json }}</pre>",
+        liquid: "<pre>{{ invoice | json }}</pre>",
+        handlebars: "<pre>{{json invoice}}</pre>"
+      },
       category: "debug"
     },
     fn: (_ctx, value, indent) => JSON.stringify(value, null, opt(Number(indent), 2))
@@ -572,10 +884,15 @@ var formatHelpers = [
     doc: {
       signature: "numToWords(value, locale?)",
       description: "Spells a number out in words (de, en, fr, es, it, nl).",
-      example: "{{ total | numToWords('de') }} \u2192 zweihundertdreiundvierzig",
+      examples: {
+        jinja2: "{{ total | numToWords('de') }} \u2192 zweihundertdreiundvierzig",
+        liquid: "{{ total | numToWords: 'de' }} \u2192 zweihundertdreiundvierzig",
+        handlebars: "{{numToWords total 'de'}} \u2192 zweihundertdreiundvierzig"
+      },
       category: "format"
     },
     fn: (ctx, value, locale) => {
+      requireFinite("numToWords", value);
       const n = toNumber(value);
       if (Number.isNaN(n)) return str(value);
       const lang = str(opt(locale, ctx.locale)).split("-")[0] ?? "en";
@@ -588,7 +905,11 @@ var formatHelpers = [
     doc: {
       signature: "t(key, params?)",
       description: "Looks a key up in the template's i18n dictionary for the request locale; `{name}` placeholders come from params.",
-      example: "{{ t('invoice.title', { number: invoice.number }) }}",
+      examples: {
+        jinja2: "{{ t('invoice.title', { number: invoice.number }) }}",
+        liquid: "{{ 'invoice.title' | t: number: invoice.number }}",
+        handlebars: "{{t 'invoice.title' number=invoice.number}}"
+      },
       category: "text"
     },
     fn: (ctx, key, params) => {
@@ -604,7 +925,11 @@ var formatHelpers = [
     doc: {
       signature: "asset(name)",
       description: "URL of a file in the workspace library (logo, background) on the CDN. Upload it on the Files page or with `POST /files` and use the name it has there; relative image paths resolve against the same library.",
-      example: `<img src="{{ asset('logo.png') }}">`,
+      examples: {
+        jinja2: `<img src="{{ asset('logo.png') }}">`,
+        liquid: `<img src="{{ 'logo.png' | asset }}">`,
+        handlebars: `<img src="{{asset 'logo.png'}}">`
+      },
       category: "document"
     },
     fn: (ctx, name) => `${(ctx.assetBaseUrl ?? "").replace(/\/$/, "")}/${str(name).replace(/^\//, "")}`
@@ -616,128 +941,17 @@ var formatHelpers = [
     doc: {
       signature: "pageBreak()",
       description: "Starts a new page in PDF output.",
-      example: "{{ pageBreak() }}",
+      examples: {
+        jinja2: "{{ pageBreak() }}",
+        liquid: "{{ '' | pageBreak }}",
+        handlebars: "{{pageBreak}}"
+      },
       category: "document"
     },
     fn: (ctx) => ctx.drawing ? ctx.drawing({ kind: "page-break" }) : '<div class="page-break" style="break-after:page"></div>'
   }
 ];
 
-// packages/engine/src/lib/helpers/codes.ts
-var svgDataUri = (svg) => `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`;
-var barcodeTypes = {
-  code128: "code128",
-  ean13: "ean13",
-  ean8: "ean8",
-  upc: "upca",
-  upca: "upca",
-  itf14: "itf14",
-  code39: "code39",
-  qrcode: "qrcode",
-  datamatrix: "datamatrix",
-  pdf417: "pdf417"
-};
-function qrSvg(value, options = {}) {
-  const qr = (0, import_qrcode.create)(value, { errorCorrectionLevel: options.ecc ?? "M" });
-  const svg = (0, import_svg_tag.render)(qr, {
-    width: options.size ?? 160,
-    margin: options.margin ?? 1,
-    color: {
-      dark: (options.color ?? "#000000").replace(/^(#?)/, "#").slice(0, 9),
-      light: (options.background ?? "#ffffff").replace(/^(#?)/, "#")
-    }
-  });
-  return svg;
-}
-function epcPayload(input) {
-  const amount = input.amount === void 0 || input.amount === "" ? "" : `EUR${toNumber(input.amount).toFixed(2)}`;
-  return [
-    "BCD",
-    "002",
-    "1",
-    "SCT",
-    (input.bic ?? "").replace(/\s/g, ""),
-    String(input.name ?? "").slice(0, 70),
-    String(input.iban ?? "").replace(/\s/g, ""),
-    amount,
-    (input.purpose ?? "").slice(0, 4),
-    (input.reference ?? "").slice(0, 35),
-    input.reference ? "" : (input.text ?? "").slice(0, 140),
-    ""
-  ].join("\n");
-}
-var codeHelpers = [
-  {
-    name: "qrcode",
-    aliases: ["qr"],
-    doc: {
-      signature: "qrcode(value, { size = 160, ecc = 'M', margin = 1, color, background })",
-      description: "QR code as an SVG data URI for an <img> src.",
-      example: '<img src="{{ qrcode(order.url, { size: 120 }) }}">',
-      category: "code"
-    },
-    fn: (ctx, value, options) => {
-      const o = options ?? {};
-      const svg = qrSvg(String(value ?? ""), o);
-      if (ctx.drawing) return ctx.drawing({ kind: "svg", svg, width: o.size, height: o.size, alt: "QR code" });
-      return svgDataUri(svg);
-    }
-  },
-  {
-    name: "barcode",
-    doc: {
-      signature: "barcode(value, { type = 'code128', height = 12, width, text = true, scale = 2 })",
-      description: "Barcode (code128, ean13, ean8, upc, itf14, code39, datamatrix, pdf417) as an SVG data URI.",
-      example: `<img src="{{ barcode(item.sku, { type: 'code128' }) }}">`,
-      category: "code"
-    },
-    fn: (ctx, value, options) => {
-      const o = options ?? {};
-      const bcid = barcodeTypes[String(o.type ?? "code128").toLowerCase()] ?? "code128";
-      const svg = (0, import_bwip_js.toSVG)({
-        bcid,
-        text: String(value ?? ""),
-        height: o.height ?? 12,
-        ...o.width === void 0 ? {} : { width: o.width },
-        scale: o.scale ?? 2,
-        includetext: o.text !== false,
-        textxalign: "center"
-      });
-      if (ctx.drawing) return ctx.drawing({ kind: "svg", svg, alt: `Barcode ${String(value ?? "")}` });
-      return svgDataUri(svg);
-    }
-  },
-  {
-    name: "epcQr",
-    aliases: ["epc_qr", "girocode"],
-    doc: {
-      signature: "epcQr({ name, iban, bic?, amount?, reference?, text? }, { size })",
-      description: "SEPA credit transfer QR code (EPC069-12 / GiroCode) that banking apps scan to prefill a payment.",
-      example: '<img src="{{ epcQr({ name: company.name, iban: company.iban, amount: invoice.total, reference: invoice.number }) }}">',
-      category: "code"
-    },
-    // Payment fields and QR options may arrive together: Jinja2 passes two objects, Handlebars one
-    // hash (`{{epcQr name=… iban=… size=200}}`), and Liquid, which cannot build an object literal,
-    // keyword arguments (`{{ company.iban | epcQr: name: company.name, amount: invoice.total }}`,
-    // where a string input is the IBAN). They are merged and split by field name.
-    fn: (ctx, input, options) => {
-      const fields = {
-        ...input && typeof input === "object" ? input : typeof input === "string" && input ? { iban: input } : {},
-        ...options ?? {}
-      };
-      const payment = {};
-      const qr = {};
-      for (const [key, value] of Object.entries(fields))
-        (EPC_FIELDS.has(key) ? payment : qr)[key] = value;
-      const o = { ecc: "M", ...qr };
-      const svg = qrSvg(epcPayload(payment), o);
-      if (ctx.drawing) return ctx.drawing({ kind: "svg", svg, width: o.size, height: o.size, alt: "GiroCode" });
-      return svgDataUri(svg);
-    }
-  }
-];
-var EPC_FIELDS = /* @__PURE__ */ new Set(["name", "iban", "bic", "amount", "reference", "text", "purpose"]);
-
 // packages/engine/src/lib/helpers/collections.ts
 var list = (v) => Array.isArray(v) ? v : v === void 0 || v === null ? [] : [v];
 var get = (item, path) => String(path ?? "").split(".").filter(Boolean).reduce(
@@ -751,7 +965,11 @@ var collectionHelpers = [
     doc: {
       signature: "sum(list, path?)",
       description: "Sum of the items, or of `path` inside each item.",
-      example: "{{ invoice.lines | sum('total') | money }}",
+      examples: {
+        jinja2: "{{ invoice.lines | sum('total') | money }}",
+        liquid: "{{ invoice.lines | sum: 'total' | money }}",
+        handlebars: "{{money (sum invoice.lines 'total')}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value, path) => numbers(value, path).reduce((a, b) => a + b, 0)
@@ -761,7 +979,11 @@ var collectionHelpers = [
     doc: {
       signature: "avg(list, path?)",
       description: "Average of the items or of `path` inside each item.",
-      example: "{{ scores | avg | number(1) }}",
+      examples: {
+        jinja2: "{{ scores | avg | number(1) }}",
+        liquid: "{{ scores | avg | number: 1 }}",
+        handlebars: "{{number (avg scores) 1}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value, path) => {
@@ -774,7 +996,11 @@ var collectionHelpers = [
     doc: {
       signature: "min(list, path?)",
       description: "Smallest number.",
-      example: "{{ prices | min }}",
+      examples: {
+        jinja2: "{{ prices | min }}",
+        liquid: "{{ prices | min }}",
+        handlebars: "{{min prices}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value, path) => Math.min(...numbers(value, path))
@@ -784,7 +1010,11 @@ var collectionHelpers = [
     doc: {
       signature: "max(list, path?)",
       description: "Largest number.",
-      example: "{{ prices | max }}",
+      examples: {
+        jinja2: "{{ prices | max }}",
+        liquid: "{{ prices | max }}",
+        handlebars: "{{max prices}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value, path) => Math.max(...numbers(value, path))
@@ -795,7 +1025,11 @@ var collectionHelpers = [
     doc: {
       signature: "groupBy(list, path)",
       description: "Groups items by a field; returns a list of `{ key, items }`.",
-      example: "{% for group in lines | groupBy('category') %}{{ group.key }}{% endfor %}",
+      examples: {
+        jinja2: "{% for group in lines | groupBy('category') %}{{ group.key }}{% endfor %}",
+        liquid: "{% assign groups = lines | groupBy: 'category' %}{% for group in groups %}{{ group.key }}{% endfor %}",
+        handlebars: "{{#each (groupBy lines 'category')}}{{key}}{{/each}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value, path) => {
@@ -813,7 +1047,11 @@ var collectionHelpers = [
     doc: {
       signature: "sortBy(list, path?, direction = 'asc')",
       description: "Sorts items by a field (numbers numerically, strings by locale).",
-      example: "{% for l in lines | sortBy('position') %}",
+      examples: {
+        jinja2: "{% for l in lines | sortBy('position') %}{{ l.sku }}{% endfor %}",
+        liquid: "{% assign sorted = lines | sortBy: 'position' %}{% for l in sorted %}{{ l.sku }}{% endfor %}",
+        handlebars: "{{#each (sortBy lines 'position')}}{{sku}}{{/each}}"
+      },
       category: "collection"
     },
     fn: (ctx, value, path, direction) => {
@@ -834,7 +1072,11 @@ var collectionHelpers = [
     doc: {
       signature: "where(list, path, value?)",
       description: "Keeps items whose field equals `value` (or is truthy when omitted).",
-      example: "{% for l in lines | where('taxable', true) %}",
+      examples: {
+        jinja2: "{% for l in lines | where('taxable', true) %}{{ l.sku }}{% endfor %}",
+        liquid: "{% assign taxable = lines | where: 'taxable', true %}{% for l in taxable %}{{ l.sku }}{% endfor %}",
+        handlebars: "{{#each (where lines 'taxable' true)}}{{sku}}{{/each}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value, path, expected) => list(value).filter((item) => {
@@ -848,7 +1090,11 @@ var collectionHelpers = [
     doc: {
       signature: "pluck(list, path)",
       description: "Extracts one field from every item.",
-      example: "{{ lines | pluck('sku') | join(', ') }}",
+      examples: {
+        jinja2: "{{ lines | pluck('sku') | join(', ') }}",
+        liquid: "{{ lines | pluck: 'sku' | join: ', ' }}",
+        handlebars: "{{join (pluck lines 'sku') ', '}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value, path) => list(value).map((item) => get(item, path))
@@ -859,7 +1105,11 @@ var collectionHelpers = [
     doc: {
       signature: "chunk(list, size)",
       description: "Splits a list into lists of `size` items (rows of labels, columns).",
-      example: "{% for row in labels | chunk(3) %}",
+      examples: {
+        jinja2: "{% for row in labels | chunk(3) %}{{ row | join(', ') }}{% endfor %}",
+        liquid: "{% assign rows = labels | chunk: 3 %}{% for row in rows %}{{ row | join: ', ' }}{% endfor %}",
+        handlebars: "{{#each (chunk labels 3)}}{{join this ', '}}{{/each}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value, size) => {
@@ -875,7 +1125,11 @@ var collectionHelpers = [
     doc: {
       signature: "range(start, end?, step = 1)",
       description: "List of numbers from start to end (exclusive).",
-      example: "{% for i in range(1, 4) %}",
+      examples: {
+        jinja2: "{% for i in range(1, 4) %}{{ i }}{% endfor %}",
+        liquid: "{% assign nums = 1 | range: 4 %}{% for i in nums %}{{ i }}{% endfor %}",
+        handlebars: "{{#each (range 1 4)}}{{this}}{{/each}}"
+      },
       category: "collection"
     },
     fn: (_ctx, start, end, step) => {
@@ -893,7 +1147,11 @@ var collectionHelpers = [
     doc: {
       signature: "first(list)",
       description: "First item.",
-      example: "{{ lines | first }}",
+      examples: {
+        jinja2: "{{ tags | first }}",
+        liquid: "{{ tags | first }}",
+        handlebars: "{{first tags}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value) => list(value)[0]
@@ -903,7 +1161,11 @@ var collectionHelpers = [
     doc: {
       signature: "last(list)",
       description: "Last item.",
-      example: "{{ lines | last }}",
+      examples: {
+        jinja2: "{{ tags | last }}",
+        liquid: "{{ tags | last }}",
+        handlebars: "{{last tags}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value) => list(value).at(-1)
@@ -914,7 +1176,11 @@ var collectionHelpers = [
     doc: {
       signature: "length(value)",
       description: "Number of items in a list, keys in an object or characters in a string.",
-      example: "{{ lines | length }}",
+      examples: {
+        jinja2: "{{ lines | length }}",
+        liquid: "{{ lines | length }}",
+        handlebars: "{{length lines}}"
+      },
       category: "collection"
     },
     fn: (_ctx, value) => Array.isArray(value) || typeof value === "string" ? value.length : value && typeof value === "object" ? Object.keys(value).length : 0
@@ -990,7 +1256,11 @@ var documentHelpers = [
     doc: {
       signature: "chart({ type, labels, values, label, color } | { type, labels, series } | { type, data, options }, { width, height })",
       description: "Draws a Chart.js chart (bar, line, pie, doughnut, radar, \u2026) from plain data, `labels` with `values` or several `series` of `{ label, values, color }`, or from a full Chart.js `data` and `options`; animations are disabled so PDF and preview match.",
-      example: "{{ chart({ type: 'line', labels: ['Q1', 'Q2', 'Q3'], values: sales.quarters, width: 480 }) }}",
+      examples: {
+        jinja2: "{{ chart({ type: 'line', labels: sales.labels, values: sales.quarters, width: 480 }) }}",
+        liquid: "{{ '' | chart: type: 'line', labels: sales.labels, values: sales.quarters, width: 480 }}",
+        handlebars: "{{chart type='line' labels=sales.labels values=sales.quarters width=480}}"
+      },
       category: "document"
     },
     fn: (ctx, spec, extra) => {
@@ -1004,7 +1274,11 @@ var documentHelpers = [
     doc: {
       signature: "image(url, { width, height, fit, alt })",
       description: "Places an image with fixed size and crop mode (`cover`, `contain`, `fill`); the render-worker fetches it through its cache and blocks private hosts.",
-      example: "{{ image(product.photo, { width: 120, height: 80, fit: 'cover' }) }}",
+      examples: {
+        jinja2: "{{ image(product.photo, { width: 120, height: 80, fit: 'cover' }) }}",
+        liquid: "{{ product.photo | image: width: 120, height: 80, fit: 'cover' }}",
+        handlebars: "{{image product.photo width=120 height=80 fit='cover'}}"
+      },
       category: "document"
     },
     fn: (ctx, url, options) => {
@@ -1030,7 +1304,12 @@ var comparison = (name, test, description) => ({
   doc: {
     signature: `${name}(a, b)`,
     description,
-    example: `{{#if (${name} invoice.total 1000)}}\u2026{{/if}}`,
+    examples: {
+      jinja2: `{% if ${name}(invoice.total, 1000) %}\u2026{% endif %}`,
+      // Liquid takes no filter in a condition, so the comparison is assigned first
+      liquid: `{% assign hit = invoice.total | ${name}: 1000 %}{% if hit %}\u2026{% endif %}`,
+      handlebars: `{{#if (${name} invoice.total 1000)}}\u2026{{/if}}`
+    },
     category: "logic"
   },
   fn: (_ctx, a, b) => test(a, b)
@@ -1047,7 +1326,12 @@ var logicHelpers = [
     doc: {
       signature: "and(a, b, \u2026)",
       description: "True when every value is true; an empty list counts as false.",
-      example: '{{#if (and customer.vatId (eq country "DE"))}}\u2026{{/if}}',
+      examples: {
+        jinja2: "{% if and(customer.vatId, eq(country, 'DE')) %}\u2026{% endif %}",
+        // nesting one comparison in another needs its own assignment in Liquid
+        liquid: "{% assign german = country | eq: 'DE' %}{% assign both = customer.vatId | and: german %}{% if both %}\u2026{% endif %}",
+        handlebars: "{{#if (and customer.vatId (eq country 'DE'))}}\u2026{{/if}}"
+      },
       category: "logic"
     },
     fn: (_ctx, ...values) => values.length > 0 && values.every(truthy)
@@ -1057,7 +1341,11 @@ var logicHelpers = [
     doc: {
       signature: "or(a, b, \u2026)",
       description: "True when any value is true.",
-      example: "{{#if (or invoice.paid invoice.credited)}}\u2026{{/if}}",
+      examples: {
+        jinja2: "{% if or(invoice.paid, invoice.credited) %}\u2026{% endif %}",
+        liquid: "{% assign any = invoice.paid | or: invoice.credited %}{% if any %}\u2026{% endif %}",
+        handlebars: "{{#if (or invoice.paid invoice.credited)}}\u2026{{/if}}"
+      },
       category: "logic"
     },
     fn: (_ctx, ...values) => values.some(truthy)
@@ -1067,7 +1355,11 @@ var logicHelpers = [
     doc: {
       signature: "not(value)",
       description: "The opposite truth value.",
-      example: "{{#if (not invoice.paid)}}\u2026{{/if}}",
+      examples: {
+        jinja2: "{% if invoice.paid | not %}\u2026{% endif %}",
+        liquid: "{% assign unpaid = invoice.paid | not %}{% if unpaid %}\u2026{% endif %}",
+        handlebars: "{{#if (not invoice.paid)}}\u2026{{/if}}"
+      },
       category: "logic"
     },
     fn: (_ctx, value) => !truthy(value)
@@ -1140,7 +1432,9 @@ function helperDocs(registry = defaultHelpers()) {
   return [...registry.definitions.values()].map((d) => ({
     name: d.name,
     aliases: d.aliases ?? [],
-    ...d.doc
+    ...d.doc,
+    // derived rather than authored, so the old field cannot drift from `examples`
+    example: d.doc.examples.jinja2
   }));
 }
 
@@ -3572,7 +3866,7 @@ ${loop(e, "line", "invoice.lines", `    <tr><td>${val(e, "line.description")}</t
       invoice: { due_date: "2026-10-13" },
       payment: {
         name: "Fennlor Studio GmbH",
-        iban: "DE00000000000000000000",
+        iban: "DE36000000000000000000",
         bic: "XXXXDEXXXXX",
         amount: 3760.4,
         reference: "2026-0042"
@@ -3759,7 +4053,7 @@ ${loop(e, "line", "invoice.lines", `    <tr><td>${val(e, "line.description")}</t
     sampleData: {
       payment: {
         name: "Fennlor Studio GmbH",
-        iban: "DE00000000000000000000",
+        iban: "DE36000000000000000000",
         bic: "XXXXDEXXXXX",
         amount: 3760.4,
         reference: "2026-0042"