@spaceinvoices/react-ui 0.4.10 → 0.4.12

package/src/hooks/use-transaction-type-check.ts

@@ -1,7 +1,7 @@
 import type { TransactionTypeCheckRequest, TransactionTypeCheckResponse } from "@spaceinvoices/js-sdk";
 import { useQuery } from "@tanstack/react-query";
 import { useMemo } from "react";
-import { useSDK } from "../providers/sdk-provider";
+import { transactionType } from "../../../js-sdk/src/sdk/transaction-type";
 import { useDebounce } from "./use-debounce";
 
 export const TRANSACTION_TYPE_CHECK_CACHE_KEY = "transaction-type-check";
@@ -77,8 +77,6 @@ export function useTransactionTypeCheck({
   customerIsEndConsumer,
   enabled = true,
 }: UseTransactionTypeCheckParams): UseTransactionTypeCheckResult {
-  const { sdk } = useSDK();
-
   // Build the request object
   const requestData = useMemo((): TransactionTypeCheckRequest | null => {
     // Need at least issuer info to make a check
@@ -120,12 +118,9 @@ export function useTransactionTypeCheck({
     queryKey,
     queryFn: async () => {
       if (!debouncedRequest) throw new Error("No request data");
-      // Use sdk.vies.checkVies which hits the same endpoint types
-      // (sdk.transactionType is not reliably available in Vite pre-bundled builds)
-      const checkFn = sdk.transactionType?.checkTransactionType ?? sdk.vies.checkVies;
-      return checkFn(debouncedRequest);
+      return transactionType.checkTransactionType(debouncedRequest);
     },
-    enabled: enabled && !!sdk && !!debouncedRequest,
+    enabled: enabled && !!debouncedRequest,
     staleTime: CHECK_STALE_TIME,
     refetchOnWindowFocus: false,
   });

package/src/lib/browser-cookies.ts

@@ -64,7 +64,7 @@ export function deleteCookie(name: string, path = "/") {
   });
 
   // Also delete domain cookie (e.g. .spaceinvoices.com) if on spaceinvoices.com
-  const hostname = typeof window !== "undefined" ? window.location.hostname : globalThis.location?.hostname ?? "";
+  const hostname = typeof window !== "undefined" ? window.location.hostname : (globalThis.location?.hostname ?? "");
   if (hostname === "spaceinvoices.com" || hostname.endsWith(".spaceinvoices.com")) {
     setCookie(name, "", {
       path,

package/src/lib/country-capabilities.ts

@@ -0,0 +1,114 @@
+import type { AdvanceInvoice, CreditNote, DeliveryNote, Estimate, Invoice } from "@spaceinvoices/js-sdk";
+
+import type { PdfTemplateId } from "@/ui/components/documents/create/live-preview";
+import type { Entity } from "@/ui/providers/entities-context";
+
+export const PORTUGAL_COUNTRY_CODE = "PT";
+export const PORTUGAL_PDF_LOCALE = "pt-PT";
+export const PORTUGAL_CANONICAL_PDF_TEMPLATE: PdfTemplateId = "classic";
+const ACTIVE_ACCOUNT_COOKIE = "l.account";
+const SUPPORT_ACCOUNT_ID = import.meta.env.VITE_SUPPORT_ACCOUNT_ID || "acc_000000000000000000000001";
+
+export type CountryAwareDocument = Invoice | Estimate | CreditNote | AdvanceInvoice | DeliveryNote;
+export type CountryAwareDocumentType = "invoice" | "estimate" | "credit_note" | "advance_invoice" | "delivery_note";
+
+type CountryEntity = Pick<Entity, "country_code" | "settings"> | null | undefined;
+
+export function isPortugalEntity(entity: CountryEntity): boolean {
+  return entity?.country_code === PORTUGAL_COUNTRY_CODE;
+}
+
+function getCookieValue(name: string) {
+  if (typeof document === "undefined") {
+    return null;
+  }
+
+  const cookiePrefix = `${name}=`;
+  const rawCookie = document.cookie
+    .split(";")
+    .map((cookie) => cookie.trim())
+    .find((cookie) => cookie.startsWith(cookiePrefix));
+
+  if (!rawCookie) {
+    return null;
+  }
+  return decodeURIComponent(rawCookie.slice(cookiePrefix.length));
+}
+
+export function hasPortugalUiAccess() {
+  if (typeof document === "undefined") {
+    return true;
+  }
+
+  const activeAccountId = getCookieValue(ACTIVE_ACCOUNT_COOKIE);
+  return !!SUPPORT_ACCOUNT_ID && activeAccountId === SUPPORT_ACCOUNT_ID;
+}
+
+export function resolveDocumentPdfTemplate(entity: CountryEntity): PdfTemplateId {
+  if (isPortugalEntity(entity) && hasPortugalUiAccess()) {
+    return PORTUGAL_CANONICAL_PDF_TEMPLATE;
+  }
+
+  const settings = (entity?.settings as Record<string, unknown> | undefined) ?? {};
+  return (settings.pdf_template as PdfTemplateId) || "modern";
+}
+
+export function getPortugalEditBlockedReason(entity: CountryEntity): string | undefined {
+  if (!isPortugalEntity(entity) || !hasPortugalUiAccess()) {
+    return undefined;
+  }
+
+  return "Issued Portugal documents cannot be edited. Void the document instead.";
+}
+
+export function getEntityCountryCapabilities(entity: CountryEntity) {
+  const isPortugal = isPortugalEntity(entity) && hasPortugalUiAccess();
+  const isSlovenia = entity?.country_code === "SI";
+
+  return {
+    isPortugal,
+    isSlovenia,
+    usesFixedPdfTemplate: isPortugal,
+    showPtSaftExport: isPortugal,
+    showSloveniaVodExport: isSlovenia,
+    showPtAtcudSettings: isPortugal,
+    allowTemplateSettings: !isPortugal,
+    allowEmailSettings: !isPortugal,
+    showTemplatesSettings: !isPortugal,
+    showEmailSettings: !isPortugal,
+    allowPdfTemplateSelection: !isPortugal,
+    allowPdfLanguageSelection: !isPortugal,
+    allowDocumentDrafts: !isPortugal,
+    allowSavedItemFullEdit: !isPortugal,
+    resolvedPdfTemplate: resolveDocumentPdfTemplate(entity),
+    forcePdfLocale: isPortugal ? PORTUGAL_PDF_LOCALE : undefined,
+  };
+}
+
+export function getDocumentCountryCapabilities(
+  entity: CountryEntity,
+  documentType: CountryAwareDocumentType,
+  document?: Partial<CountryAwareDocument> | null,
+) {
+  const entityCapabilities = getEntityCountryCapabilities(entity);
+  const isDraft = document?.is_draft === true;
+
+  return {
+    ...entityCapabilities,
+    allowEmailSend: !entityCapabilities.isPortugal,
+    allowSendEmail: !entityCapabilities.isPortugal,
+    allowEditIssuedDocument: !entityCapabilities.isPortugal || isDraft,
+    allowEditDocument: !entityCapabilities.isPortugal || isDraft,
+    allowPaymentAction:
+      (documentType === "invoice" || documentType === "advance_invoice" || documentType === "credit_note") &&
+      !(entityCapabilities.isPortugal && documentType === "credit_note"),
+    allowPaymentActions:
+      (documentType === "invoice" || documentType === "advance_invoice" || documentType === "credit_note") &&
+      !(entityCapabilities.isPortugal && documentType === "credit_note"),
+    forceDocumentPdfLocale: entityCapabilities.forcePdfLocale,
+    isDraft,
+  };
+}
+
+export const getCountryUiCapabilities = getEntityCountryCapabilities;
+export const getDocumentUiCapabilities = getDocumentCountryCapabilities;

package/src/lib/date-fns-locale.ts

@@ -1,24 +1,5 @@
 import type { Locale } from "date-fns";
-import {
-  bg,
-  cs,
-  de,
-  enUS,
-  es,
-  et,
-  fi,
-  fr,
-  hr,
-  is,
-  it,
-  nb,
-  nl,
-  pl,
-  pt,
-  sk,
-  sl,
-  sv,
-} from "date-fns/locale";
+import { bg, cs, de, enUS, es, et, fi, fr, hr, is, it, nb, nl, pl, pt, sk, sl, sv } from "date-fns/locale";
 import { getLocaleLanguage } from "./locale";
 
 const DATE_FNS_LOCALES: Record<string, Locale> = {

package/src/lib/eslog-export.ts

@@ -0,0 +1,32 @@
+type EslogDocumentLike = {
+  eslog?: {
+    validation_status?: string | null;
+  } | null;
+};
+
+export type EslogSelectionState = {
+  selectedCount: number;
+  eligibleCount: number;
+  hasEligibleDocuments: boolean;
+  hasIneligibleDocuments: boolean;
+  allEligible: boolean;
+  noneEligible: boolean;
+  partiallyEligible: boolean;
+};
+
+export function getEslogSelectionState(documents: EslogDocumentLike[]): EslogSelectionState {
+  const selectedCount = documents.length;
+  const eligibleCount = documents.filter((document) => document.eslog?.validation_status === "valid").length;
+  const hasEligibleDocuments = eligibleCount > 0;
+  const hasIneligibleDocuments = eligibleCount < selectedCount;
+
+  return {
+    selectedCount,
+    eligibleCount,
+    hasEligibleDocuments,
+    hasIneligibleDocuments,
+    allEligible: selectedCount > 0 && eligibleCount === selectedCount,
+    noneEligible: selectedCount > 0 && eligibleCount === 0,
+    partiallyEligible: eligibleCount > 0 && eligibleCount < selectedCount,
+  };
+}

package/src/lib/fiscalization-options.ts

@@ -5,12 +5,26 @@
  * and advance invoice forms where this logic was duplicated.
  */
 
-export type FursSubmitOptions = { skip: true } | { business_premise_name: string; electronic_device_name: string };
+export type FiscalizationOperatorOverride = {
+  label?: string;
+  tax_number?: string;
+};
+
+export type FursSubmitOptions =
+  | { skip: true }
+  | {
+      business_premise_name: string;
+      electronic_device_name: string;
+      operator_tax_number?: string;
+      operator_label?: string;
+    };
 
 export type FinaSubmitOptions = {
   business_premise_name: string;
   electronic_device_name: string;
   payment_type: string;
+  operator_oib?: string;
+  operator_label?: string;
 };
 
 export type EslogSubmitOptions = {
@@ -29,6 +43,7 @@ export function buildFursOptions(opts: {
   skipFiscalization?: boolean;
   premiseName?: string;
   deviceName?: string;
+  operator?: FiscalizationOperatorOverride;
 }): FursSubmitOptions | undefined {
   if (opts.isDraft || opts.isEditMode || !opts.isEnabled) return undefined;
   if (opts.skipFiscalization) return { skip: true };
@@ -36,6 +51,8 @@ export function buildFursOptions(opts: {
     return {
       business_premise_name: opts.premiseName,
       electronic_device_name: opts.deviceName,
+      ...(opts.operator?.tax_number ? { operator_tax_number: opts.operator.tax_number } : {}),
+      ...(opts.operator?.label ? { operator_label: opts.operator.label } : {}),
     };
   }
   return undefined;
@@ -53,6 +70,7 @@ export function buildFinaOptions(opts: {
   premiseName?: string;
   deviceName?: string;
   paymentType?: string;
+  operator?: FiscalizationOperatorOverride;
 }): FinaSubmitOptions | undefined {
   if (opts.isDraft || opts.isEditMode || !opts.useFinaNumbering) return undefined;
   if (opts.premiseName && opts.deviceName) {
@@ -60,6 +78,8 @@ export function buildFinaOptions(opts: {
       business_premise_name: opts.premiseName,
       electronic_device_name: opts.deviceName,
       payment_type: opts.paymentType || "bank_transfer",
+      ...(opts.operator?.tax_number ? { operator_oib: opts.operator.tax_number } : {}),
+      ...(opts.operator?.label ? { operator_label: opts.operator.label } : {}),
     };
   }
   return undefined;

package/src/lib/formatting.ts

@@ -0,0 +1,27 @@
+export function formatCurrencyValue(amount: number, currencyCode: string, locale?: string): string {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: currencyCode || "USD",
+  }).format(amount);
+}
+
+export function formatDateValue(
+  date: string | number | Date | null | undefined,
+  locale?: string,
+  format: Intl.DateTimeFormatOptions = {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  },
+): string {
+  if (!date) {
+    return "—";
+  }
+
+  const dateObj = new Date(date);
+  if (Number.isNaN(dateObj.getTime())) {
+    return String(date);
+  }
+
+  return new Intl.DateTimeFormat(locale, format).format(dateObj);
+}

package/src/lib/furs-error-utils.ts

@@ -34,3 +34,32 @@ export function isFinaOperatorError(error: unknown): boolean {
   }
   return false;
 }
+
+/**
+ * Detect if an error is a PT operator snapshot validation error.
+ * PT document creation requires the operator first name, last name, and tax number.
+ */
+export function isPtOperatorError(error: unknown): boolean {
+  const data = (error as any)?.data;
+  if (data?.cause?.issues) {
+    return data.cause.issues.some(
+      (issue: any) =>
+        issue.path?.[0] === "pt" &&
+        (issue.path?.[1] === "account_first_name" ||
+          issue.path?.[1] === "operator_first_name" ||
+          issue.path?.[1] === "account_last_name" ||
+          issue.path?.[1] === "operator_last_name" ||
+          issue.path?.[1] === "account_tax_number" ||
+          issue.path?.[1] === "operator_tax_number"),
+    );
+  }
+
+  const message = data?.message || (error as any)?.message || "";
+  if (typeof message !== "string") return false;
+
+  return (
+    message.includes("PT operator first name is required") ||
+    message.includes("PT operator last name is required") ||
+    message.includes("PT operator tax number is required")
+  );
+}

package/src/lib/locale.ts

@@ -6,6 +6,10 @@ export function getLocaleLanguage(locale?: string, fallback = "en"): string {
   return normalizeLocale(locale, fallback).split("-")[0] || fallback;
 }
 
+export function resolveTranslationLocale(translationLocale?: string, locale?: string, fallback = "en"): string {
+  return normalizeLocale(translationLocale ?? locale, fallback);
+}
+
 const LANGUAGE_TO_LOCALE: Record<string, string> = {
   en: "en-US",
   de: "de-DE",

package/src/lib/payment-display.ts

@@ -0,0 +1,95 @@
+type TranslateFn = (key: string) => string;
+
+const AUTO_APPLIED_CREDIT_NOTE_TEMPLATE = "Auto-applied credit note for voided invoice {number}";
+const AUTO_BILLING_STRIPE_NOTE = "Automatic billing payment via Stripe";
+const AUTO_APPLIED_CREDIT_NOTE_REGEX = /^Auto-applied credit note for voided invoice (.+)$/;
+
+type PaymentDocumentLike = {
+  Invoice?: { id: string; number: string } | null;
+  CreditNote?: { id: string; number: string } | null;
+  AdvanceInvoice?: { id: string; number: string } | null;
+  IncomingPurchaseDocument?: {
+    id: string;
+    supplier_document_number?: string | null;
+  } | null;
+};
+
+export type PaymentDocumentDisplay = {
+  id: string;
+  label: string;
+  isNavigable: boolean;
+};
+
+export function getPaymentTypeLabel(type: string, t: TranslateFn): string {
+  switch (type) {
+    case "cash":
+      return t("cash");
+    case "bank_transfer":
+      return t("bank_transfer");
+    case "card":
+      return t("card");
+    case "check":
+      return t("check");
+    case "credit_note":
+      return t("credit_note");
+    case "advance":
+      return t("advance_payment");
+    case "other":
+      return t("other");
+    default:
+      return type;
+  }
+}
+
+export function localizePaymentNote(note: string | null | undefined, t: TranslateFn): string | null | undefined {
+  if (!note) {
+    return note;
+  }
+
+  if (note === AUTO_BILLING_STRIPE_NOTE) {
+    return t(AUTO_BILLING_STRIPE_NOTE);
+  }
+
+  const autoAppliedMatch = note.match(AUTO_APPLIED_CREDIT_NOTE_REGEX);
+  if (autoAppliedMatch) {
+    return t(AUTO_APPLIED_CREDIT_NOTE_TEMPLATE).replace("{number}", autoAppliedMatch[1] ?? "");
+  }
+
+  return note;
+}
+
+export function getPaymentDocumentDisplay(payment: PaymentDocumentLike): PaymentDocumentDisplay | null {
+  if (payment.Invoice) {
+    return {
+      id: payment.Invoice.id,
+      label: payment.Invoice.number,
+      isNavigable: true,
+    };
+  }
+
+  if (payment.CreditNote) {
+    return {
+      id: payment.CreditNote.id,
+      label: payment.CreditNote.number,
+      isNavigable: true,
+    };
+  }
+
+  if (payment.AdvanceInvoice) {
+    return {
+      id: payment.AdvanceInvoice.id,
+      label: payment.AdvanceInvoice.number,
+      isNavigable: true,
+    };
+  }
+
+  if (payment.IncomingPurchaseDocument) {
+    return {
+      id: payment.IncomingPurchaseDocument.id,
+      label: payment.IncomingPurchaseDocument.supplier_document_number || payment.IncomingPurchaseDocument.id,
+      isNavigable: false,
+    };
+  }
+
+  return null;
+}

package/src/lib/pt-document-input.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+export const ptDocumentInputFormSchema = z
+  .object({
+    series_id: z.string().optional(),
+    manual: z.boolean().optional(),
+    manual_sequential_number: z.number().int().gte(1).optional(),
+    manual_series_code: z.string().min(1).max(35).optional(),
+    operator_first_name: z.string().optional(),
+    operator_last_name: z.string().optional(),
+    operator_tax_number: z.string().optional(),
+    account_first_name: z.string().optional(),
+    account_last_name: z.string().optional(),
+    account_tax_number: z.string().optional(),
+  })
+  .partial();
+
+export type PtDocumentInputForm = z.infer<typeof ptDocumentInputFormSchema>;
+
+export type PtDocumentNumberingType = "invoice" | "advance_invoice" | "credit_note" | "estimate";
+
+export function formatPtManualDocumentNumber(
+  documentType: PtDocumentNumberingType,
+  manualSeriesCode: string,
+  sequence: number,
+) {
+  const prefix = documentType === "credit_note" ? "NC" : documentType === "estimate" ? "OR" : "FT";
+  return `${prefix}M ${manualSeriesCode}/${String(sequence)}`;
+}
+
+export function normalizePtDocumentInput(
+  input: PtDocumentInputForm | null | undefined,
+): PtDocumentInputForm | undefined {
+  if (!input) return undefined;
+
+  const normalized: PtDocumentInputForm = {};
+
+  if (input.series_id?.trim()) normalized.series_id = input.series_id.trim();
+  if (input.manual === true) normalized.manual = true;
+
+  if (input.manual_series_code?.trim()) {
+    normalized.manual_series_code = input.manual_series_code.trim();
+  }
+
+  if (typeof input.manual_sequential_number === "number" && Number.isFinite(input.manual_sequential_number)) {
+    normalized.manual_sequential_number = input.manual_sequential_number;
+  }
+
+  const operatorFirstName = input.operator_first_name?.trim() || input.account_first_name?.trim();
+  const operatorLastName = input.operator_last_name?.trim() || input.account_last_name?.trim();
+  const operatorTaxNumber = input.operator_tax_number?.trim() || input.account_tax_number?.trim();
+
+  if (operatorFirstName) {
+    normalized.operator_first_name = operatorFirstName;
+    normalized.account_first_name = operatorFirstName;
+  }
+  if (operatorLastName) {
+    normalized.operator_last_name = operatorLastName;
+    normalized.account_last_name = operatorLastName;
+  }
+  if (operatorTaxNumber) {
+    normalized.operator_tax_number = operatorTaxNumber;
+    normalized.account_tax_number = operatorTaxNumber;
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}

package/src/lib/schemas/shared.ts

@@ -54,6 +54,7 @@ export type DiscountFormData = z.infer<typeof discountSchema>;
 export const lineItemSchema = z.object({
   name: z.string().min(1),
   description: z.string().nullish(),
+  classification: z.enum(["product", "service", "advance"]).nullish(),
   price: z.number().optional(),
   gross_price: z.number().optional(),
   quantity: z.number(),

package/src/lib/template-variables.tsx

@@ -1,6 +1,62 @@
-import type { Entity, Estimate, Invoice } from "@spaceinvoices/js-sdk";
+import type { Entity } from "@spaceinvoices/js-sdk";
 import { cn } from "@/ui/lib/utils";
 
+type PreviewDocument = {
+  number?: string | null;
+  date?: string | Date | null;
+  date_due?: string | Date | null;
+  date_valid_till?: string | Date | null;
+  total_with_tax?: number | null;
+  currency_code?: string | null;
+  customer?: { name?: string | null; email?: string | null } | null;
+  customer_id?: string | null;
+};
+
+type TemplateVariableDefinition = {
+  name: string;
+  label: string;
+  category: string;
+  translationAliases?: string[];
+};
+
+const TEMPLATE_VARIABLE_DEFINITIONS: TemplateVariableDefinition[] = [
+  { name: "entity_name", label: "Company name", category: "Entity" },
+  { name: "entity_email", label: "Email address", category: "Entity" },
+  { name: "entity_address", label: "Address", category: "Entity" },
+  { name: "entity_post_code", label: "Post code", category: "Entity", translationAliases: ["Postal Code"] },
+  { name: "entity_city", label: "City", category: "Entity" },
+  { name: "entity_country", label: "Country", category: "Entity" },
+  { name: "entity_tax_number", label: "Tax number", category: "Entity", translationAliases: ["tax-number"] },
+  {
+    name: "entity_company_number",
+    label: "Company number",
+    category: "Entity",
+    translationAliases: ["company-number"],
+  },
+  { name: "entity_starting_capital", label: "Starting capital", category: "Entity" },
+  { name: "document_number", label: "Invoice number", category: "Document" },
+  { name: "document_date", label: "Invoice date", category: "Document" },
+  { name: "document_due_date", label: "Due date", category: "Document" },
+  { name: "document_valid_until", label: "Valid until", category: "Document" },
+  { name: "document_total", label: "Total amount", category: "Document" },
+  { name: "document_currency", label: "Currency", category: "Document" },
+  { name: "customer_name", label: "Customer name", category: "Customer" },
+  { name: "customer_email", label: "Customer email", category: "Customer" },
+  { name: "bank_account", label: "Bank Account", category: "Bank Account" },
+  { name: "bank_account.iban", label: "IBAN", category: "Bank Account" },
+  { name: "bank_account.bank_name", label: "Bank Name", category: "Bank Account" },
+  { name: "bank_account.bic", label: "BIC/SWIFT", category: "Bank Account" },
+  { name: "bank_account.account_number", label: "Account number", category: "Bank Account" },
+  { name: "current_date", label: "Today's date", category: "Other" },
+  { name: "current_year", label: "Current year", category: "Other" },
+];
+
+const TEMPLATE_VARIABLE_LOOKUP = new Map(
+  TEMPLATE_VARIABLE_DEFINITIONS.map((definition) => [definition.name, definition] as const),
+);
+
+type TranslationFunction = (key: string) => string;
+
 /**
  * Convert snake_case variable name to Title Case for display
  * e.g., "document_number" -> "Document Number", "bank_account.iban" -> "Bank Account Iban"
@@ -20,7 +76,7 @@ export function formatVariableName(varName: string): string {
 export function getVariableValue(
   varName: string,
   entity?: Entity | null,
-  document?: Partial<Invoice | Estimate> | null,
+  document?: PreviewDocument | null,
 ): string | null {
   if (!entity) return null;
 
@@ -33,6 +89,9 @@ export function getVariableValue(
   if (varName === "entity_country") return entity.country || null;
   if (varName === "entity_tax_number") return entity.tax_number || null;
   if (varName === "entity_company_number") return entity.company_number || null;
+  if (varName === "entity_starting_capital") {
+    return entity.starting_capital != null ? String(entity.starting_capital) : null;
+  }
 
   // Date variables
   if (varName === "current_date") {
@@ -117,6 +176,44 @@ export function getVariableValue(
   return null;
 }
 
+function translateLabel(label: string, aliases: string[] | undefined, translate?: TranslationFunction): string {
+  if (!translate) return label;
+
+  const translatedLabel = translate(label);
+  if (translatedLabel !== label) return translatedLabel;
+
+  for (const alias of aliases ?? []) {
+    const translatedAlias = translate(alias);
+    if (translatedAlias !== alias) return translatedAlias;
+  }
+
+  return label;
+}
+
+export function getTemplateVariableLabel(varName: string, translate?: TranslationFunction): string {
+  const definition = TEMPLATE_VARIABLE_LOOKUP.get(varName);
+  if (!definition) return formatVariableName(varName);
+  return translateLabel(definition.label, definition.translationAliases, translate);
+}
+
+export function getTemplateVariableGroups(translate?: TranslationFunction) {
+  const groupedVariables = new Map<string, Array<{ code: string; label: string }>>();
+
+  for (const definition of TEMPLATE_VARIABLE_DEFINITIONS) {
+    const group = groupedVariables.get(definition.category) ?? [];
+    group.push({
+      code: `{${definition.name}}`,
+      label: getTemplateVariableLabel(definition.name, translate),
+    });
+    groupedVariables.set(definition.category, group);
+  }
+
+  return Array.from(groupedVariables.entries()).map(([category, variables]) => ({
+    category: translate ? translate(category) : category,
+    variables,
+  }));
+}
+
 /**
  * Replace template variables in a string with styled React nodes for preview.
  * Resolved values get a secondary bg, unresolved show as primary-colored placeholders.
@@ -124,7 +221,8 @@ export function getVariableValue(
 export function replaceTemplateVariablesForPreview(
   template: string,
   entity?: Entity | null,
-  document?: Partial<Invoice | Estimate> | null,
+  document?: PreviewDocument | null,
+  translate?: TranslationFunction,
 ): React.ReactNode[] {
   if (!template) return [];
 
@@ -141,7 +239,7 @@ export function replaceTemplateVariablesForPreview(
 
     const varName = match[1];
     const actualValue = getVariableValue(varName, entity, document);
-    const displayValue = actualValue || formatVariableName(varName);
+    const displayValue = actualValue || getTemplateVariableLabel(varName, translate);
 
     parts.push(
       <span