@spaceinvoices/react-ui 0.4.11 → 0.4.12

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

package/src/lib/translation.ts

@@ -1,5 +1,4 @@
-import { useCallback } from "react";
-import { getLocaleLanguage, normalizeLocale } from "./locale";
+import { getLocaleLanguage, resolveTranslationLocale } from "./locale";
 
 type TranslationFunction = (key: string) => string;
 
@@ -7,43 +6,62 @@ export type ComponentTranslationProps = {
   t?: TranslationFunction;
   namespace?: string;
   locale?: string;
+  translationLocale?: string;
   translations?: Record<string, Record<string, string>>;
 };
 
-export function createTranslation({ t, namespace, locale = "en", translations = {} }: ComponentTranslationProps = {}) {
-  return useCallback(
-    (key: string): string => {
-      // 1. If external translation function provided, use it
-      if (t) {
-        const fullKey = namespace ? `${namespace}.${key}` : key;
-        const result = t(fullKey);
-
-        // If translation found (result is not the key), return it.
-        // We check against both fullKey (standard i18next behavior) and key (in case namespace was stripped)
-        if (result !== fullKey && result !== key) {
-          return result;
-        }
-      }
+function humanizeFallbackKey(key: string): string {
+  if (!/[_-]/.test(key)) return key;
 
-      const normalizedLocale = normalizeLocale(locale);
-      const baseLocale = getLocaleLanguage(normalizedLocale);
+  const words = key.split(/[_-]+/).filter(Boolean);
+  if (words.length === 0) return key;
 
-      // 2. Look up in local translations for current locale, then base language
-      const localeTranslations = translations[normalizedLocale] ?? translations[baseLocale];
-      if (localeTranslations) {
-        const translation = localeTranslations[key];
-        if (translation) return translation;
-      }
+  return words
+    .map((word, index) => {
+      if (word.toUpperCase() === word && word.length > 1) return word;
+      if (index === 0) return `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+      return word;
+    })
+    .join(" ");
+}
+
+export function createTranslation({
+  t,
+  namespace,
+  locale = "en",
+  translationLocale,
+  translations = {},
+}: ComponentTranslationProps = {}) {
+  return (key: string): string => {
+    // 1. If external translation function provided, use it
+    if (t) {
+      const fullKey = namespace ? `${namespace}.${key}` : key;
+      const result = t(fullKey);
 
-      const englishTranslations = translations.en;
-      if (englishTranslations) {
-        const translation = englishTranslations[key];
-        if (translation) return translation;
+      // If translation found (result is not the key), return it.
+      // We check against both fullKey (standard i18next behavior) and key (in case namespace was stripped)
+      if (result !== fullKey && result !== key) {
+        return result;
       }
+    }
+
+    const normalizedLocale = resolveTranslationLocale(translationLocale, locale);
+    const baseLocale = getLocaleLanguage(normalizedLocale);
+
+    // 2. Look up in local translations for current locale, then base language
+    const localeTranslations = translations[normalizedLocale] ?? translations[baseLocale];
+    if (localeTranslations) {
+      const translation = localeTranslations[key];
+      if (translation) return translation;
+    }
+
+    const englishTranslations = translations.en;
+    if (englishTranslations) {
+      const translation = englishTranslations[key];
+      if (translation) return translation;
+    }
 
-      // 3. Fall back to key itself (which is the English text)
-      return key;
-    },
-    [t, namespace, locale, translations],
-  );
+    // 3. Humanize raw lookup keys like "credit_note" before falling back fully
+    return humanizeFallbackKey(key);
+  };
 }