@spaceinvoices/react-ui 0.4.11 → 0.4.31

package/src/components/documents/create/payment-rows.ts

@@ -0,0 +1,321 @@
+import type { PriceModesMap } from "./document-items-section";
+
+export const REGULAR_PAYMENT_TYPES = ["cash", "bank_transfer", "card", "check", "other"] as const;
+
+export type RegularPaymentType = (typeof REGULAR_PAYMENT_TYPES)[number];
+
+export type DraftPaymentRow = {
+  id?: string;
+  type: RegularPaymentType | null;
+  amount: string;
+  amountTouched: boolean;
+};
+
+export type SerializedPaymentRow = {
+  type: RegularPaymentType;
+  amount: number;
+};
+
+export type ApiSerializedPaymentRow = {
+  type: RegularPaymentType;
+  amount?: number;
+};
+
+export type PaymentRowsEvaluation = {
+  payments: SerializedPaymentRow[];
+  totalAmount: number;
+  hasTypeError: boolean;
+  hasAmountError: boolean;
+  exceedsTotal: boolean;
+  requiresFullAmount: boolean;
+  totalMatchesExactly: boolean;
+};
+
+export type PaymentRowsValidationMode = "partial_allowed" | "full_required";
+
+export type PaymentRowsValidation = {
+  typeError?: string;
+  amountError?: string;
+  totalError?: string;
+  payments: SerializedPaymentRow[];
+  totalAmount: number;
+};
+
+export function getPaymentValidationMessage(
+  evaluation: PaymentRowsEvaluation,
+  options?: { requireFullAmount?: boolean },
+): string | undefined {
+  if (evaluation.hasTypeError) {
+    return "Please select a payment type";
+  }
+
+  if (evaluation.exceedsTotal) {
+    return "Payment amounts cannot exceed the document total";
+  }
+
+  if (options?.requireFullAmount && !evaluation.totalMatchesExactly) {
+    return "Advance invoices must be fully paid";
+  }
+
+  if (evaluation.hasAmountError) {
+    return "Payment amount must be greater than 0";
+  }
+
+  return undefined;
+}
+
+export function getFirstValidPaymentType(paymentRows: DraftPaymentRow[]): RegularPaymentType | undefined {
+  return paymentRows.find((row) => isValidPaymentTypeSelection(row.type))?.type ?? undefined;
+}
+
+export function createEmptyPaymentRow(): DraftPaymentRow {
+  return { id: crypto.randomUUID(), type: null, amount: "", amountTouched: false };
+}
+
+export function coercePaymentRowsToType(paymentRows: DraftPaymentRow[], type: RegularPaymentType): DraftPaymentRow[] {
+  if (paymentRows.length === 0) {
+    return [{ ...createEmptyPaymentRow(), type }];
+  }
+
+  return paymentRows.map((row) => ({
+    ...row,
+    type,
+  }));
+}
+
+export function isValidPaymentTypeSelection(value: string | null | undefined): value is RegularPaymentType {
+  return REGULAR_PAYMENT_TYPES.includes(value as RegularPaymentType);
+}
+
+export function roundCurrency(amount: number): number {
+  return Math.round((amount + Number.EPSILON) * 100) / 100;
+}
+
+export function formatAmountInput(amount: number | null): string {
+  if (amount == null || !Number.isFinite(amount)) return "";
+  return amount.toFixed(2);
+}
+
+export function parsePaymentAmount(value: string): number | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+
+  const normalized = trimmed.replace(",", ".");
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed)) return null;
+
+  return roundCurrency(parsed);
+}
+
+export function calculateDocumentTotal(items: any[] | undefined, priceModes: PriceModesMap = {}): number {
+  if (!items?.length) return 0;
+
+  const total = items.reduce((sum, item, index) => {
+    if (!item || item.type === "separator") return sum;
+
+    const quantity = Number(item.quantity ?? 0);
+    const price = Number(item.price ?? 0);
+    if (!Number.isFinite(quantity) || !Number.isFinite(price) || quantity <= 0 || price <= 0) {
+      return sum;
+    }
+
+    const lineBase = quantity * price;
+    const isGrossPrice = priceModes[index] ?? false;
+    const taxMultiplier =
+      1 +
+      (Array.isArray(item.taxes)
+        ? item.taxes.reduce((taxSum: number, tax: any) => taxSum + Number(tax?.rate ?? 0), 0) / 100
+        : 0);
+
+    return sum + (isGrossPrice ? lineBase : lineBase * taxMultiplier);
+  }, 0);
+
+  return roundCurrency(total);
+}
+
+export function derivePaymentAmounts(paymentRows: DraftPaymentRow[], documentTotal: number): Array<number | null> {
+  const resolved = Array<number | null>(paymentRows.length).fill(null);
+  const untouchedIndexes: number[] = [];
+  let touchedTotal = 0;
+
+  paymentRows.forEach((row, index) => {
+    if (!row.amountTouched) {
+      untouchedIndexes.push(index);
+      return;
+    }
+
+    const parsed = parsePaymentAmount(row.amount);
+    resolved[index] = parsed;
+    if (parsed != null) {
+      touchedTotal += parsed;
+    }
+  });
+
+  const roundedTotal = roundCurrency(documentTotal);
+  const remaining = roundCurrency(roundedTotal - touchedTotal);
+
+  if (untouchedIndexes.length === 0) {
+    return resolved;
+  }
+
+  if (remaining <= 0) {
+    untouchedIndexes.forEach((index) => {
+      resolved[index] = 0;
+    });
+    return resolved;
+  }
+
+  const equalShare = roundCurrency(remaining / untouchedIndexes.length);
+  let allocated = 0;
+
+  untouchedIndexes.forEach((index, arrayIndex) => {
+    if (arrayIndex === untouchedIndexes.length - 1) {
+      resolved[index] = roundCurrency(remaining - allocated);
+      return;
+    }
+
+    resolved[index] = equalShare;
+    allocated = roundCurrency(allocated + equalShare);
+  });
+
+  return resolved;
+}
+
+export const derivePaymentRowAmounts = derivePaymentAmounts;
+
+export function getDisplayPaymentAmount(row: DraftPaymentRow, derivedAmount: number | null): string {
+  return row.amountTouched ? row.amount : formatAmountInput(derivedAmount);
+}
+
+export function getRecordedPaymentTotal(paymentRows: DraftPaymentRow[], documentTotal: number): number {
+  const resolvedAmounts = derivePaymentAmounts(paymentRows, documentTotal);
+  return roundCurrency(
+    resolvedAmounts.reduce<number>((sum, amount) => sum + (amount != null && amount > 0 ? amount : 0), 0),
+  );
+}
+
+export function evaluatePaymentRows(
+  paymentRows: DraftPaymentRow[],
+  documentTotal: number,
+  options?: { requireFullAmount?: boolean },
+): PaymentRowsEvaluation {
+  const resolvedAmounts = derivePaymentAmounts(paymentRows, documentTotal);
+  const payments: SerializedPaymentRow[] = [];
+  let hasTypeError = false;
+  let hasAmountError = false;
+
+  paymentRows.forEach((row, index) => {
+    if (!isValidPaymentTypeSelection(row.type)) {
+      hasTypeError = true;
+      return;
+    }
+
+    const amount = resolvedAmounts[index];
+    if (amount == null || amount <= 0) {
+      hasAmountError = true;
+      return;
+    }
+
+    payments.push({ type: row.type, amount });
+  });
+
+  const totalAmount = roundCurrency(payments.reduce((sum, payment) => sum + payment.amount, 0));
+  const roundedTotal = roundCurrency(documentTotal);
+  const exceedsTotal = totalAmount > roundedTotal;
+  const requireFullAmount = options?.requireFullAmount === true;
+  const totalMatchesExactly = totalAmount === roundedTotal;
+
+  if (exceedsTotal) {
+    hasAmountError = true;
+  }
+
+  if (requireFullAmount && !totalMatchesExactly) {
+    hasAmountError = true;
+  }
+
+  return {
+    payments,
+    totalAmount,
+    hasTypeError,
+    hasAmountError,
+    exceedsTotal,
+    requiresFullAmount: requireFullAmount,
+    totalMatchesExactly,
+  };
+}
+
+export function validatePaymentRows(
+  paymentRows: DraftPaymentRow[],
+  documentTotal: number,
+  mode: PaymentRowsValidationMode,
+): PaymentRowsValidation {
+  const evaluation = evaluatePaymentRows(paymentRows, documentTotal, {
+    requireFullAmount: mode === "full_required",
+  });
+
+  if (evaluation.hasTypeError) {
+    return {
+      payments: evaluation.payments,
+      totalAmount: evaluation.totalAmount,
+      typeError: "Please select a payment type",
+    };
+  }
+
+  if (evaluation.exceedsTotal) {
+    return {
+      payments: evaluation.payments,
+      totalAmount: evaluation.totalAmount,
+      totalError: "Payment amounts cannot exceed the document total",
+    };
+  }
+
+  if (mode === "full_required" && !evaluation.totalMatchesExactly) {
+    return {
+      payments: evaluation.payments,
+      totalAmount: evaluation.totalAmount,
+      totalError: "Advance invoices must be fully paid",
+    };
+  }
+
+  if (evaluation.hasAmountError) {
+    return {
+      payments: evaluation.payments,
+      totalAmount: evaluation.totalAmount,
+      amountError: "Payment amount must be greater than 0",
+    };
+  }
+
+  return {
+    payments: evaluation.payments,
+    totalAmount: evaluation.totalAmount,
+  };
+}
+
+export function serializePaymentRows(paymentRows: DraftPaymentRow[], documentTotal: number): SerializedPaymentRow[] {
+  return evaluatePaymentRows(paymentRows, documentTotal).payments;
+}
+
+export function serializePaymentRowsForApi(
+  paymentRows: DraftPaymentRow[],
+  documentTotal: number,
+  options?: { preserveUntouchedAmounts?: boolean },
+): ApiSerializedPaymentRow[] {
+  const resolvedPayments = evaluatePaymentRows(paymentRows, documentTotal).payments;
+
+  if (!options?.preserveUntouchedAmounts) {
+    return resolvedPayments;
+  }
+
+  return paymentRows.flatMap((row, index) => {
+    if (!isValidPaymentTypeSelection(row.type)) {
+      return [];
+    }
+
+    const resolvedPayment = resolvedPayments[index];
+    if (!resolvedPayment) {
+      return [];
+    }
+
+    return row.amountTouched ? [resolvedPayment] : [{ type: resolvedPayment.type }];
+  });
+}

package/src/components/documents/create/prepare-document-submission.ts

@@ -1,3 +1,5 @@
+import { normalizeDateOnlyInput } from "../../../lib/date-only";
+
 type CustomerData = {
   name?: string | null;
   address?: string | null;
@@ -8,7 +10,7 @@ type CustomerData = {
   country?: string | null;
   tax_number?: string | null;
   is_end_consumer?: boolean | null;
-  save_customer?: boolean;
+  save_customer?: boolean | null;
 };
 
 type BaseDocumentValues = {
@@ -33,6 +35,8 @@ type PrepareDocumentOptions = {
   markAsPaid?: boolean;
   /** For invoices/credit notes: payment types when markAsPaid is true */
   paymentTypes?: string[];
+  /** Structured payments when amounts were already normalized by the form layer */
+  payments?: Array<{ type: string; amount?: number }>;
   /** Document type for specific date handling */
   documentType: "invoice" | "estimate" | "credit_note" | "advance_invoice" | "delivery_note";
   /** Secondary date field value (date_due for invoices, date_valid_till for estimates) */
@@ -43,62 +47,31 @@ type PrepareDocumentOptions = {
   isDraft?: boolean;
 };
 
-/**
- * Prepares document form data for API submission.
- * Handles customer data transformation and payment data for all document types.
- *
- * This is a shared utility for invoices, estimates, and credit notes.
- *
- * @example
- * ```ts
- * // For invoice
- * const payload = prepareDocumentSubmission(values, {
- *   originalCustomer,
- *   wasCustomerFormShown: showCustomerForm,
- *   markAsPaid: values.markAsPaid,
- *   paymentType: values.paymentType,
- *   documentType: "invoice",
- *   secondaryDate: values.date_due,
- * });
- *
- * // For estimate
- * const payload = prepareDocumentSubmission(values, {
- *   originalCustomer,
- *   documentType: "estimate",
- *   secondaryDate: values.date_valid_till,
- * });
- * ```
- */
-export function prepareDocumentSubmission<T extends BaseDocumentValues>(
-  values: T,
-  options: PrepareDocumentOptions,
-): any {
-  const nextValues: any = {
-    ...values,
-    customer: values.customer ? { ...values.customer } : values.customer,
-    items: values.items
-      ? values.items.map((item: any) => ({ ...item, taxes: item?.taxes ? [...item.taxes] : item?.taxes }))
-      : values.items,
-  };
+const CLEARABLE_TEXT_FIELDS = ["note", "payment_terms", "reference", "signature", "tax_clause", "footer"] as const;
 
-  // Document numbers are always auto-generated by the server
-  // Remove number from payload (even if form provides a preview value)
+export function normalizeClearableFormTextField(value: unknown): string | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (typeof value !== "string") return undefined;
 
-  // Handle customer logic
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+export function prepareDocumentCustomerData<T extends BaseDocumentValues>(
+  nextValues: T & { customer?: CustomerData | null; customer_id?: string | null },
+  options: Pick<PrepareDocumentOptions, "originalCustomer" | "wasCustomerFormShown">,
+): void {
   if (nextValues.customer_id && nextValues.customer) {
-    // If customer form was not shown, remove customer data (keep only customer_id)
     if (options.wasCustomerFormShown === false) {
       delete nextValues.customer;
     } else {
-      // Existing customer loaded - check if data was actually modified
       const customerChanged =
         options.originalCustomer && JSON.stringify(nextValues.customer) !== JSON.stringify(options.originalCustomer);
 
       if (!customerChanged) {
-        // No changes - send only customer_id
         delete nextValues.customer;
       } else {
-        // Changes detected - clean null/empty values and send with save_customer flag
         const cleanedCustomer: any = { save_customer: true };
         for (const [key, value] of Object.entries(nextValues.customer)) {
           if (key !== "save_customer" && value !== "" && value !== null && value !== undefined) {
@@ -109,7 +82,6 @@ export function prepareDocumentSubmission<T extends BaseDocumentValues>(
       }
     }
   } else if (nextValues.customer) {
-    // New inline customer - clean null/empty values and add save flag
     const cleanedCustomer: any = { save_customer: true };
     let hasAnyValue = false;
 
@@ -126,91 +98,164 @@ export function prepareDocumentSubmission<T extends BaseDocumentValues>(
       nextValues.customer = cleanedCustomer;
     }
   }
+}
 
-  // Clean up customer_id if empty
+export function cleanupEmptyCustomerId<T extends BaseDocumentValues>(nextValues: T & { customer_id?: string | null }): void {
   if (!nextValues.customer_id) {
     delete nextValues.customer_id;
   }
+}
 
-  // Clean up taxes and handle gross price transformation
-  if (nextValues.items) {
-    const priceModes = options.priceModes ?? {};
-    nextValues.items = nextValues.items.map((item: any, index: number) => {
-      // Separator items — pass through with only type, name, description
-      if (item.type === "separator") {
-        return {
-          type: "separator",
-          name: item.name,
-          description: item.description || undefined,
-        };
-      }
-
-      const { price, ...rest } = item;
-
-      // Transform price based on price mode (from component state, not form)
-      const isGrossPrice = priceModes[index] ?? false;
-      const priceFields = isGrossPrice ? { gross_price: price } : { price };
+export function prepareDocumentItems(items: any[] | undefined, priceModes: PriceModesMap = {}): any[] | undefined {
+  if (!items) {
+    return items;
+  }
 
+  return items.map((item: any, index: number) => {
+    if (item.type === "separator") {
       return {
-        ...rest,
-        ...priceFields,
-        taxes: item.taxes
-          ?.map((tax: any) => {
-            if (tax.tax_id) {
-              // Only send tax_id, API will resolve the rate
-              return { tax_id: tax.tax_id };
-            }
-            return tax;
-          })
-          // Filter out empty placeholder taxes (UI adds { tax_id: undefined } for the dropdown)
-          .filter((tax: any) => tax.tax_id || tax.rate !== undefined || tax.classification),
+        type: "separator",
+        name: item.name,
+        description: item.description || undefined,
       };
-    });
-  }
+    }
+
+    const { price, gross_price, ...rest } = item;
+    const isGrossPrice = priceModes[index] ?? false;
+    const effectivePrice = price ?? gross_price;
+    const priceFields =
+      effectivePrice === undefined ? {} : isGrossPrice ? { gross_price: effectivePrice } : { price: effectivePrice };
+
+    return {
+      ...rest,
+      ...priceFields,
+      taxes: item.taxes
+        ?.map((tax: any) => {
+          if (tax.tax_id) {
+            return {
+              tax_id: tax.tax_id,
+              ...(tax.pt_exemption_code ? { pt_exemption_code: tax.pt_exemption_code } : {}),
+              ...(tax.pt_exemption_reason ? { pt_exemption_reason: tax.pt_exemption_reason } : {}),
+            };
+          }
+          return tax;
+        })
+        .filter((tax: any) => tax.tax_id || tax.rate !== undefined || tax.classification),
+    };
+  });
+}
+
+export function buildDocumentBasePayload(
+  nextValues: Record<string, any>,
+  options: Pick<PrepareDocumentOptions, "documentType" | "secondaryDate">,
+): Record<string, any> {
+  const {
+    number: _number,
+    note,
+    payment_terms,
+    reference,
+    signature,
+    tax_clause,
+    footer,
+    pt: _pt,
+    ...restValues
+  } = nextValues;
 
-  // Build payload with date conversions
-  // Destructure to exclude fields we handle explicitly (number is always server-generated)
-  const { number: _number, note, payment_terms, reference, signature, ...restValues } = nextValues as any;
-  const payload: any = {
+  const payload: Record<string, any> = {
     ...restValues,
-    ...(note?.trim() && { note: note.trim() }),
-    ...(reference?.trim() && { reference: reference.trim() }),
-    // Advance invoices don't have payment terms - they are documents requesting payment
-    ...(options.documentType !== "advance_invoice" && payment_terms?.trim() && { payment_terms: payment_terms.trim() }),
-    ...(signature?.trim() && { signature: signature.trim() }),
-    date: nextValues.date ? new Date(nextValues.date) : undefined,
+    date: normalizeDateOnlyInput(nextValues.date),
   };
 
-  // Add secondary date field based on document type
+  for (const [key, value] of Object.entries({
+    note,
+    payment_terms: options.documentType !== "advance_invoice" ? payment_terms : undefined,
+    reference,
+    signature,
+    tax_clause,
+    footer,
+  })) {
+    const normalized = normalizeClearableFormTextField(value);
+    if (normalized !== undefined) {
+      payload[key] = normalized;
+    }
+  }
+
   if ((options.documentType === "invoice" || options.documentType === "advance_invoice") && options.secondaryDate) {
-    payload.date_due = new Date(options.secondaryDate);
+    payload.date_due = normalizeDateOnlyInput(options.secondaryDate);
   } else if (options.documentType === "estimate" && options.secondaryDate) {
-    payload.date_valid_till = new Date(options.secondaryDate);
+    payload.date_valid_till = normalizeDateOnlyInput(options.secondaryDate);
   }
-  // Credit notes don't have a secondary date field
 
-  // Add service date fields for invoices and credit notes
   if (options.documentType === "invoice" || options.documentType === "credit_note") {
-    const v = nextValues as any;
-    if (v.date_service) {
-      payload.date_service = new Date(v.date_service);
+    if (nextValues.date_service) {
+      payload.date_service = normalizeDateOnlyInput(nextValues.date_service);
     }
-    if (v.date_service_to) {
-      payload.date_service_to = new Date(v.date_service_to);
+    if (nextValues.date_service_to) {
+      payload.date_service_to = normalizeDateOnlyInput(nextValues.date_service_to);
     }
   }
 
+  return payload;
+}
+
+/**
+ * Prepares document form data for API submission.
+ * Handles customer data transformation and payment data for all document types.
+ *
+ * This is a shared utility for invoices, estimates, and credit notes.
+ *
+ * @example
+ * ```ts
+ * // For invoice
+ * const payload = prepareDocumentSubmission(values, {
+ *   originalCustomer,
+ *   wasCustomerFormShown: showCustomerForm,
+ *   markAsPaid: values.markAsPaid,
+ *   paymentType: values.paymentType,
+ *   documentType: "invoice",
+ *   secondaryDate: values.date_due,
+ * });
+ *
+ * // For estimate
+ * const payload = prepareDocumentSubmission(values, {
+ *   originalCustomer,
+ *   documentType: "estimate",
+ *   secondaryDate: values.date_valid_till,
+ * });
+ * ```
+ */
+export function prepareDocumentSubmission<T extends BaseDocumentValues>(
+  values: T,
+  options: PrepareDocumentOptions,
+): any {
+  const nextValues: any = {
+    ...values,
+    customer: values.customer ? { ...values.customer } : values.customer,
+    items: values.items
+      ? values.items.map((item: any) => ({ ...item, taxes: item?.taxes ? [...item.taxes] : item?.taxes }))
+      : values.items,
+  };
+  prepareDocumentCustomerData(nextValues, options);
+  cleanupEmptyCustomerId(nextValues);
+  nextValues.items = prepareDocumentItems(nextValues.items, options.priceModes ?? {});
+  const payload: any = buildDocumentBasePayload(nextValues, options);
+
   // Handle markAsPaid for invoices and credit notes
-  if (
-    options.documentType !== "estimate" &&
-    options.markAsPaid &&
-    options.paymentTypes &&
-    options.paymentTypes.length > 0
-  ) {
-    payload.payments = options.paymentTypes.map((type: string) => ({
-      type,
-      date: payload.date ?? undefined,
-    }));
+  if (options.documentType !== "estimate" && options.markAsPaid) {
+    const serializedPayments =
+      options.payments?.map((payment) => ({
+        ...payment,
+        date: payload.date ?? undefined,
+      })) ??
+      options.paymentTypes?.map((type: string) => ({
+        type,
+        date: payload.date ?? undefined,
+      })) ??
+      [];
+
+    if (serializedPayments.length > 0) {
+      payload.payments = serializedPayments;
+    }
   }
 
   // Remove UI-only fields from payload
@@ -222,5 +267,11 @@ export function prepareDocumentSubmission<T extends BaseDocumentValues>(
     payload.is_draft = true;
   }
 
+  for (const field of CLEARABLE_TEXT_FIELDS) {
+    if (payload[field] === undefined || payload[field] === null) {
+      delete payload[field];
+    }
+  }
+
   return payload;
 }

package/src/components/documents/create/prepare-preview-data.ts

@@ -1,4 +1,5 @@
 import type { CreateInvoiceRequest } from "@spaceinvoices/js-sdk";
+import { normalizeDateOnlyInput } from "../../../lib/date-only";
 
 type ItemWithTaxes = NonNullable<CreateInvoiceRequest["items"]>[number];
 
@@ -14,3 +15,14 @@ export function filterUnresolvedTaxes(items: ItemWithTaxes[] | undefined): ItemW
     taxes: (item.taxes || []).filter((tax) => tax.tax_id != null),
   }));
 }
+
+export function normalizeDocumentPreviewDates<T extends Record<string, any>>(document: T): T {
+  return {
+    ...document,
+    ...(document.date ? { date: normalizeDateOnlyInput(document.date) } : {}),
+    ...(document.date_due ? { date_due: normalizeDateOnlyInput(document.date_due) } : {}),
+    ...(document.date_valid_till ? { date_valid_till: normalizeDateOnlyInput(document.date_valid_till) } : {}),
+    ...(document.date_service ? { date_service: normalizeDateOnlyInput(document.date_service) } : {}),
+    ...(document.date_service_to ? { date_service_to: normalizeDateOnlyInput(document.date_service_to) } : {}),
+  };
+}