@12-apps/payments-frontend 3.21.4 → 3.23.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",
@@ -101,4 +134,12 @@ export const EN_US_CHECKOUT_VIEW_COPY: CheckoutViewCopy = {
     action: "See the menu",
   },
   status: EN_US_PAYMENT_STATUS_COPY,
+  pipeline: {
+    loading: "Loading…",
+    // The KEYS are the package's own settlement-method ids, never words.
+    awaitingHandover: {
+      PIX: "Opening Pix…",
+      CARD: "Opening the card payment…",
+    },
+  },
 };

package/src/components/checkout/failure-codes.ts

@@ -15,3 +15,85 @@
  * one and must not word it as a failure.
  */
 export const UNRESOLVED_CODE = "PAYMENT_UNRESOLVED";
+
+/**
+ * REFUSALS RE-SENDING THE SAME REQUEST CANNOT CLEAR (FUT-1182).
+ *
+ * A different exception from {@link UNRESOLVED_CODE}, and the difference is
+ * worth keeping: an unresolved charge withholds the retry because pressing it
+ * could take the buyer's money twice. These withhold it because pressing it
+ * cannot do anything at all. The order was refused for a fact about the world —
+ * the shop is shut, the mode is off, the booked slot is gone, the basket has
+ * already been paid for, the merchant has connected no provider — and the
+ * identical POST meets the identical fact. So the button was the screen's most
+ * prominent control and it was guaranteed to fail, phrased as though the buyer
+ * had got something wrong.
+ *
+ * ## Why a package names a host's vocabulary here
+ *
+ * Because the alternative is worse in both directions. A prop the host fills
+ * would leave every host that has not filled it with the defect this exists to
+ * remove; and a rule inferred from the STATUS code cannot separate these from
+ * the 400s and 409s that a retry genuinely clears (`CHARGE_MISMATCH` is a 409
+ * and re-raising is exactly what fixes it).
+ *
+ * What makes it safe is that the list is CLOSED and its members are wire
+ * constants: this file already names `PAYMENT_UNRESOLVED` for the same reason,
+ * and the transport beside it already speaks the routes those codes arrive on.
+ * A host that answers none of these loses nothing — an unknown code keeps the
+ * retry, which is the pre-1182 behaviour for every code.
+ *
+ * ## It never SUPPRESSES the message, only the button
+ *
+ * The host half of this ticket (FUT-1166) acts on the same codes: it refetches
+ * whatever was stale, so the screen behind the refusal corrects itself into the
+ * gate that says what the buyer can actually do. The refusal's own sentence has
+ * to stay on screen while that happens, or a shopper watches a checkout
+ * rearrange itself for no stated reason.
+ *
+ * ## What is deliberately NOT here
+ *
+ * `BASKET_NOT_FOUND` and `MODE_CATALOG_SCOPE`, because this list is the
+ * GUARANTEED half. Both name states a fresh read can legitimately answer
+ * differently, and withholding the retry on a maybe is how a buyer with a
+ * recoverable problem ends up with no control at all — the same asymmetry
+ * `CheckoutDecline.retriable` settles by treating silence as yes.
+ */
+const NO_RETRY_CODES: readonly string[] = [
+  // The shop is shut, or shut by the time the slot came round.
+  "STORE_CLOSED",
+  "SCHEDULE_UNAVAILABLE",
+  // The store does not sell this way — a bookmarked URL, or a mode cookie that
+  // outlived the config allowing it.
+  "MODE_UNAVAILABLE",
+  // No provider connected. TWO spellings on purpose: the package's own routes
+  // answer `PAYMENT_NOT_CONFIGURED`, and a host that guards its order route
+  // before delegating answers its own. A client meets both.
+  "PAYMENT_NOT_CONFIGURED",
+  "PAYMENTS_NOT_CONFIGURED",
+  // Already bought — in another tab, or by whoever was settling alongside them.
+  // Retrying cannot un-pay it; the buyer wants their purchases, not this step.
+  "CART_ALREADY_PAID",
+  "BASKET_ALREADY_BOUGHT",
+  // Nothing left to charge for, and this step cannot put anything back.
+  "EMPTY_CART",
+  "COMANDA_CLOSED",
+  // The order cannot be delivered as asked. Fixed where the address is, which
+  // is not here.
+  "DELIVERY_UNAVAILABLE",
+  "DELIVERY_ADDRESS_REQUIRED",
+];
+
+/**
+ * Whether the surface may offer to send this refused order again.
+ *
+ * SILENCE MEANS YES, and so does anything unrecognised: a refusal with no code,
+ * or one from a server this bundle is a release behind, keeps the retry. The
+ * two packages version independently and a host may answer a vocabulary of its
+ * own, so "never heard of it" has to degrade to the old behaviour rather than
+ * to a screen with nothing on it.
+ */
+export function retryMayHelp(code: string | null | undefined): boolean {
+  if (code === undefined || code === null) return true;
+  return !NO_RETRY_CODES.includes(code);
+}