@12-apps/payments-frontend 3.21.3 → 3.22.0

package/src/components/checkout/dados-step.tsx

@@ -0,0 +1,141 @@
+import { Box } from "@mui/material";
+import type { JSX, ReactNode } from "react";
+
+import { BuyerInfoForm } from "./buyer-info-form";
+import { LockOutlinedIcon } from "./icons";
+import { displayTotals, PayBarTotal } from "./checkout-totals";
+import type { BuyerField, BuyerInfo, CheckoutCustomerField } from "./types";
+import { useCheckoutComponents } from "./ui";
+import type { DadosStepCopy } from "./view-copy";
+
+/**
+ * Step 1 of the buyer checkout, and its sticky bar.
+ *
+ * Split out of `./checkout-steps.tsx` when the Pagamento step grew a money line
+ * of its own (FUT-1179) and took that file past its size gate. The seam is the
+ * one the flow already renders on: one step per module, with the totals both of
+ * them show living in `./checkout-totals.tsx`.
+ */
+
+/**
+ * Step 1 "Dados" — the buyer's register info (CPF plus optional name/email/
+ * phone; contact pre-filled from the saved buyer profile). NO payment method
+ * here (that's step 2); nav lives in the slim checkout header. "Continuar"
+ * (sticky, with the live total) validates the CPF and advances to "Pagamento"
+ * — no charge yet.
+ */
+export function DadosStep({
+  copy,
+  buyer,
+  onBuyerChange,
+  saveProfile,
+  onSaveProfileChange,
+  createError,
+  errorField,
+  onContinue,
+  cartTotals,
+  buyerFields,
+  discountLines,
+  totalOverride,
+}: {
+  /** The step's own sentences — the HOST's words (see `./view-copy`). */
+  copy: DadosStepCopy;
+  buyer: BuyerInfo;
+  onBuyerChange: (buyer: BuyerInfo) => void;
+  saveProfile: boolean;
+  onSaveProfileChange: (value: boolean) => void;
+  createError: string | null;
+  errorField: BuyerField | null;
+  onContinue: () => void;
+  /** The host cart's own totals — what the pay bar shows in cart mode. */
+  cartTotals: { totalLabel: string; totalItems: number };
+  /** What the store's chain declares it needs (FUT-595); absent ⇒ CPF-required. */
+  buyerFields?: readonly CheckoutCustomerField[];
+  /**
+   * The saving, itemized under the total the buyer is about to authorize
+   * (FUT-246) — RENDERED BY THE HOST from its cart (the storefront passes its
+   * cart footer's money block), never re-implemented here, so the two surfaces
+   * can never word the same discount differently.
+ */
+  discountLines?: ReactNode;
+  /** Settling an open balance: totals come from the settlement, not the cart. */
+  totalOverride?: { label: string; items: number };
+}): JSX.Element {
+  const { Checkbox } = useCheckoutComponents();
+  const { label: totalLabel, items: totalItems } = displayTotals(totalOverride, cartTotals);
+
+  return (
+    <>
+      <Box sx={{ display: "flex", flexDirection: "column", gap: 3, pb: { xs: createError ? 22 : 14, sm: createError ? 20 : 12 } }}>
+        <BuyerInfoForm
+          value={buyer}
+          onChange={onBuyerChange}
+          fields={buyerFields}
+          fieldError={errorField && createError ? { field: errorField, message: createError } : null}
+        />
+        <Checkbox
+          checked={saveProfile}
+          onChange={(_event, checked) => onSaveProfileChange(checked)}
+          label={copy.saveProfile}
+          data-testid="buyer-save-profile"
+        />
+      </Box>
+
+      <DadosPayBar
+        copy={copy}
+        totalLabel={totalLabel}
+        totalItems={totalItems}
+        createError={createError}
+        onContinue={onContinue}
+      >
+        {/* Suppressed while settling a balance: those totals come from the
+            frozen ticket, not the cart. */}
+        {totalOverride ? null : discountLines}
+      </DadosPayBar>
+    </>
+  );
+}
+
+/** The sticky "Continuar" bar: the refusal, the money, and the one action. */
+function DadosPayBar({
+  copy,
+  totalLabel,
+  totalItems,
+  createError,
+  onContinue,
+  children,
+}: {
+  copy: DadosStepCopy;
+  totalLabel: string;
+  totalItems: number;
+  createError: string | null;
+  onContinue: () => void;
+  children?: ReactNode;
+}): JSX.Element {
+  const { ActionBar, Alert, Button, Text } = useCheckoutComponents();
+  return (
+    <ActionBar dataTestId="checkout-pay-bar">
+      <Box sx={{ width: "100%", display: "flex", flexDirection: "column", gap: 1.5 }}>
+        {createError ? (
+          <Alert variant="danger" title={copy.cannotContinueTitle} description={createError} showIcon data-testid="checkout-error" />
+        ) : null}
+        <Box sx={{ display: "flex", alignItems: "center", gap: 2 }}>
+          <PayBarTotal totalLabel={totalLabel} totalItems={totalItems}>{children}</PayBarTotal>
+          <Box sx={{ flex: 1, display: "flex", flexDirection: "column", alignItems: "flex-end", gap: 0.5, minWidth: 0 }}>
+            <Button variant="solid" color="primary" size="lg" fullWidth onClick={onContinue} dataTestId="checkout-continue">
+              {copy.continueAction}
+            </Button>
+            {copy.secureNotice ? (
+              <Box sx={{ display: "flex", alignItems: "center", gap: 0.5, color: "text.secondary" }}>
+                <LockOutlinedIcon sx={{ fontSize: 13 }} />
+                <Text variant="caption" size="xs" color="secondary" as="span">
+                  {copy.secureNotice}
+                </Text>
+              </Box>
+            ) : null}
+          </Box>
+        </Box>
+      </Box>
+    </ActionBar>
+  );
+}

package/src/components/checkout/decline.ts

@@ -0,0 +1,48 @@
+/**
+ * HOW A REFUSED CARD IS DESCRIBED (FUT-1145).
+ *
+ * Its own module rather than another block in `./types.ts`, which is at its
+ * size ceiling — and because this is one idea with two halves that must travel
+ * together: what happened, and whether trying again could ever work.
+ */
+
+/**
+ * WHY a card was refused, in the cross-provider vocabulary the server
+ * normalizes every acquirer's own code into (FUT-1145).
+ *
+ * A MIRROR of `@12-apps/payments-backend`'s `DeclineReason`, restated rather
+ * than imported for the reason every other mirror in `./types.ts` is: the two
+ * packages version independently, so a server one release ahead can answer a
+ * reason this bundle has never heard of. Everything that reads it degrades to
+ * the generic refusal rather than rendering nothing — see
+ * `PaymentStatusCopy.declined`. `declines.test.ts` pins the mirror against the
+ * backend union, so a reason ADDED there fails a test here rather than going
+ * quietly unworded.
+ */
+export type CheckoutDeclineReason =
+  | "INSUFFICIENT_FUNDS"
+  | "CARD_DECLINED"
+  | "INVALID_CARD"
+  | "EXPIRED_CARD"
+  | "FRAUD_SUSPECTED"
+  | "PROVIDER_ERROR"
+  | "UNKNOWN";
+
+/**
+ * A refusal as the checkout has to present it (FUT-1145): what happened, and
+ * whether another attempt could ever work.
+ *
+ * The two answer different questions and neither can carry the other. "Attempts
+ * exhausted — do not retry" and "the standing authorization was cancelled at
+ * the bank" are both terminal for completely different causes, and a
+ * seven-value taxonomy has to flatten one of them into a lie; meanwhile a
+ * screen deciding whether to OFFER a retry needs the verdict and not the cause.
+ *
+ * `retriable` UNDEFINED means the provider offered no guidance, which is not
+ * the same as "no": the retry stays on offer, because withholding it on
+ * silence would strand a buyer whose card is fine.
+ */
+export interface CheckoutDecline {
+  reason?: CheckoutDeclineReason;
+  retriable?: boolean;
+}

package/src/components/checkout/en-US.ts

@@ -48,9 +48,42 @@ export const EN_US_PAYMENT_STATUS_COPY: PaymentStatusCopy = {
       "We are still trying. If you have already paid, do not pay again — " +
       "the order is confirmed as soon as the provider tells us.",
   },
+  /**
+   * One refusal at a time, in the cardholder's own terms (FUT-1145).
+   *
+   * `UNKNOWN` is deliberately absent: with no recognised reason there is
+   * nothing specific to say, and `failed` above is already that sentence.
+   */
+  declined: {
+    INSUFFICIENT_FUNDS: {
+      heading: "There were not enough funds",
+      support: "Nothing was charged. Try another card.",
+    },
+    CARD_DECLINED: {
+      heading: "Your bank did not authorise the payment",
+      support: "Nothing was charged. Try another card, or talk to your bank.",
+    },
+    INVALID_CARD: {
+      heading: "The card details were not accepted",
+      support: "Nothing was charged. Check the number, the expiry and the CVV, or use another card.",
+    },
+    EXPIRED_CARD: {
+      heading: "That card has expired",
+      support: "Nothing was charged. Use a card that is still in date.",
+    },
+    FRAUD_SUSPECTED: {
+      heading: "Your bank blocked this purchase for security",
+      support: "Nothing was charged. Talk to your bank, or use another card.",
+    },
+    PROVIDER_ERROR: {
+      heading: "We could not process the payment right now",
+      support: "Nothing was charged. Try again in a moment.",
+    },
+  },
   retryAction: "Try again",
   regenerateAction: "Generate a new code",
   checkAgainAction: "Check again",
+  notPaidAction: "I could not pay",
   backAction: "Back to the menu",
   amountLabel: "Amount paid",
   referenceLabel: "Order",