@12-apps/payments-frontend 3.37.0 → 3.39.0

package/src/components/checkout/list/pt-BR.ts

@@ -0,0 +1,79 @@
+import type { PaymentListCopy } from "./types";
+
+/**
+ * The article a provider's name takes in a pt-BR sentence — "o PagBank", "a
+ * InfinitePay". The names are the chain's own `displayName`s; one this table
+ * has never seen reads as a company ("a empresa"), which is the safer default.
+ */
+const MASCULINE = new Set(["PagBank", "PagSeguro", "Stripe", "Itaú", "Mercado Pago"]);
+
+function the(provider: string): string {
+  return `${MASCULINE.has(provider) ? "o" : "a"} ${provider}`;
+}
+
+/** "da InfinitePay" / "do PagBank". */
+function of(provider: string): string {
+  return `${MASCULINE.has(provider) ? "do" : "da"} ${provider}`;
+}
+
+/** The one-list Pagamento step's words, pt-BR (FUT-3591, FUT-3592). */
+export const PT_BR_PAYMENT_LIST_COPY: PaymentListCopy = {
+  title: "Como você quer pagar?",
+  onlineHeading: "Pagar agora, pelo app",
+  doorHeading: "Pagar na entrega",
+  pix: { label: "Pix", hint: "Gera o código para copiar e colar" },
+  card: {
+    label: "Cartão de crédito",
+    hintSaved: (card) => `${card} ou outro cartão`,
+    hintNew: "Digite os dados do cartão",
+  },
+  googlePay: { label: "Google Pay", hint: "Com o cartão salvo no seu Google" },
+  handOff: {
+    label: "Pix ou cartão",
+    hint: (provider) =>
+      provider ? `Você paga na página ${of(provider)} e volta` : "Você paga na página de pagamento e volta",
+  },
+  savedCard: (brand, last4) => `${brand ?? "Cartão"} final ${last4}`,
+  otherCard: "Outro cartão",
+  buyer: {
+    cpf: "CPF",
+    phone: "Celular",
+    name: "Nome",
+    email: "E-mail",
+    why: (provider) => (provider ? `(${the(provider)} pede para pagar pelo app)` : "(pedido para pagar pelo app)"),
+    cpfIncomplete: "O CPF tem 11 dígitos.",
+    phoneIncomplete: "O celular precisa de DDD e 9 dígitos.",
+  },
+  reasons: {
+    choose: "Escolha como pagar.",
+    cpf: "Digite seu CPF para pagar pelo app.",
+    phone: "Digite seu celular para pagar pelo app.",
+    details: "Preencha seus dados para pagar pelo app.",
+    chooseCard: "Escolha o cartão.",
+    cardDetails: "Preencha os dados do cartão.",
+    repricing: "Atualizando o valor…",
+  },
+  actions: {
+    choose: "Escolha como pagar",
+    card: "Pagar",
+    pix: "Gerar Pix",
+    googlePay: "Pagar com Google Pay",
+    handOff: (provider) => (provider ? `Ir para ${the(provider)}` : "Ir para o pagamento"),
+  },
+  payer: (name) => `Pagando como ${name} · CPF ✓`,
+  payerChange: "Alterar",
+  charging: (total, card) => `Pagando ${total} no ${card ?? "cartão informado"}…`,
+  chargingCovered: "Confirmando o pedido, pago com o seu saldo…",
+  cancel: "Cancelar",
+  pixFace: {
+    title: (total) => `Pague ${total} com Pix`,
+    validUntil: (time) =>
+      `Válido até ${time}. Copie o código e cole no app do seu banco, em Pix copia e cola.`,
+    showQr: "Ver QR code (pagar de outro celular)",
+    hideQr: "Esconder QR code",
+    changeMethod: "Trocar a forma de pagamento",
+    copyCode: "Copiar código Pix",
+    waiting: "Aguardando o pagamento do Pix…",
+  },
+  handOffWaiting: (provider) => (provider ? `Aguardando ${the(provider)}…` : "Aguardando o pagamento…"),
+};

package/src/components/checkout/list/types.ts

@@ -0,0 +1,218 @@
+/**
+ * The Pagamento step as ONE list (FUT-3591): every way to pay — the ones the
+ * store charges through this package AND the host's own ways to pay at the
+ * door — as one radio group under two headings, with one bar whose button is
+ * the only thing that creates the order and the charge.
+ *
+ * Opt-in, through `CheckoutFlowProps.paymentList`. A host that passes nothing
+ * keeps the method tabs, the order summary and the raise-on-pick it has today
+ * — this is additive, not a replacement.
+ *
+ * ## The door options are the HOST's
+ *
+ * Paying at the door raises no charge, so nothing about it belongs to a
+ * payments package: which tenders a store takes, the troco question, the
+ * minimum order and the request that places the pedido are all the host's.
+ * The list only DRAWS them — a radio row in the same group, the host's
+ * content opened inside it, and the host's verb, reason and send on the bar's
+ * button while it is the chosen one. That is the slot `CheckoutDoorOption`
+ * describes.
+ */
+import type { ReactNode } from "react";
+
+/**
+ * One of the host's ways to pay at the door — "Dinheiro", "Maquininha".
+ *
+ * Every field is a fact the host already holds; the list never computes one.
+ * Rebuild the array whenever any of them changes (a hook that returns it is the
+ * natural shape): the list renders what it is handed on every render.
+ */
+export interface CheckoutDoorOption {
+  /** Stable within the list; reported back through `onChoiceChange`. */
+  id: string;
+  /** The row's label — "Dinheiro". */
+  label: string;
+  /** The muted line under the label — "Crédito, débito, vale-refeição ou Pix". */
+  hint?: string;
+  /**
+   * Hide the hint while the option is chosen — for an option whose opened
+   * content says the same thing at length (the maquininha's brand lines).
+   */
+  hideHintWhileChosen?: boolean;
+  /**
+   * What opens INSIDE the row when it is chosen (the troco question, the
+   * tender chips, the brand lines). Rendered only while chosen, with no left
+   * indent: it starts where the row's own content starts.
+   */
+  content?: ReactNode;
+  /** The bar button's verb while this option is chosen — "Enviar pedido". */
+  action: string;
+  /** The amount beside the verb. Absent ⇒ the cart's own total. */
+  totalLabel?: string;
+  /**
+   * Why the button cannot send yet, in the host's words — or `null` when it
+   * can. Shown under the button, which stays disabled while it is set.
+   */
+  blocked: string | null;
+  /** The host's send is in flight: the button shows its busy state. */
+  pending?: boolean;
+  /** A refusal of the last send, in the host's words, shown under the button. */
+  error?: string | null;
+  /** Press of the bar's button while this option is chosen. Places the order. */
+  onSend: () => void;
+}
+
+/** The online ways to pay the list may offer, as the host is told about them. */
+export type CheckoutOnlineChoice = "PIX" | "CARD" | "GOOGLE_PAY" | "HAND_OFF";
+
+/** What the buyer has chosen in the list. */
+export type CheckoutListChoice =
+  | { kind: "online"; method: CheckoutOnlineChoice }
+  | { kind: "door"; id: string };
+
+/**
+ * A reason the HOST is holding the button, whatever is chosen — a step before
+ * this one is still open ("Escolha o horário no passo 2."). The button reads
+ * `action`, disabled, with `reason` under it.
+ */
+export interface CheckoutListHold {
+  action: string;
+  reason: string;
+}
+
+/** `CheckoutFlowProps.paymentList` — see the module comment. */
+export interface CheckoutPaymentList {
+  /** Every sentence the list draws. REQUIRED, with no default (FUT-760). */
+  copy: PaymentListCopy;
+  /**
+   * The first line of the bar, in the host's words — "2 itens · Taxa de
+   * entrega R$ 5,00". The list draws it as given.
+   */
+  summary?: ReactNode;
+  /**
+   * Host content drawn in the bar while an ONLINE option is chosen, under the
+   * summary — the storefront's "Usar meus R$ 5,00 de crédito na loja". A door
+   * option hides it: what it offers applies only to a payment made here.
+   */
+  onlineExtras?: ReactNode;
+  /** The "PAGAR NA ENTREGA" group. Absent or empty ⇒ no heading, no rows. */
+  door?: readonly CheckoutDoorOption[];
+  /** Held by the host — see {@link CheckoutListHold}. */
+  hold?: CheckoutListHold | null;
+  /** Told whenever the chosen option changes, including to nothing. */
+  onChoiceChange?: (choice: CheckoutListChoice | null) => void;
+  /**
+   * The amount an ONLINE payment will ask the provider for, in integer cents —
+   * the cart's total, or what is left of it after a balance the host holds
+   * (store credit). It is what Google Pay's sheet is priced with, since that
+   * sheet must open INSIDE the tap, before any order exists to read a price
+   * from. Never given, or zero (a balance covers everything) ⇒ no Google Pay
+   * row, and a Google Pay choice is dropped. Once given, a moment without it
+   * (the host re-pricing) keeps a chosen Google Pay with its button held —
+   * plainly, with `copy.reasons.repricing` — until it returns. The key is
+   * refused if the order raised behind the sheet asks the provider for another
+   * amount (`CheckoutOrder.amountDueCents`, else its total) — so a host that
+   * takes a balance off the charge MUST answer `amountDueCents`.
+   */
+  totalCents?: number;
+  /**
+   * The same amount, pre-formatted by the host ("R$ 22,00"), when it is not
+   * the cart's total — a balance the host holds pays part of it. The card's
+   * button, the 5-second bar and Google Pay's press name THIS while an online
+   * option is chosen; a door option and an empty choice keep the cart's total,
+   * since no balance pays at the door. Absent ⇒ the cart's total. It is also
+   * the amount the Pix face asks for.
+   *
+   * **A balance that covers everything** (`totalCents: 0`): the card option
+   * asks for no card, the bar says `copy.chargingCovered`, and the order the
+   * button raises must come back SETTLED by the host — paid from the balance,
+   * with no provider call — so the list goes to its paid screen. An order that
+   * comes back `AWAITING_PAYMENT` with `amountDueCents: 0` is never charged:
+   * the list returns to its rows.
+   */
+  amountDueLabel?: string;
+}
+
+/** The list's words — a pack per locale ships at `@12-apps/payments-frontend/locales`. */
+export interface PaymentListCopy {
+  /** "Como você quer pagar?" */
+  title: string;
+  /** "Pagar agora, pelo app" — drawn in capitals by CSS. */
+  onlineHeading: string;
+  /** "Pagar na entrega" — drawn in capitals by CSS. */
+  doorHeading: string;
+  pix: { label: string; hint: string };
+  card: {
+    label: string;
+    /** "Visa final 4242 ou outro cartão" — the preselected saved card named. */
+    hintSaved: (card: string) => string;
+    /** "Digite os dados do cartão". */
+    hintNew: string;
+  };
+  googlePay: { label: string; hint: string };
+  handOff: {
+    label: string;
+    /** "Você paga na página da InfinitePay e volta" — `null` when the store published no name. */
+    hint: (provider: string | null) => string;
+  };
+  /** "Visa final 4242"; `brand` is `null` when the network is unknown ("Cartão final 4242"). */
+  savedCard: (brand: string | null, last4: string) => string;
+  /** "Outro cartão". */
+  otherCard: string;
+  /** The buyer's own details asked inside the option, when the store needs one the buyer has not given. */
+  buyer: {
+    cpf: string;
+    phone: string;
+    name: string;
+    email: string;
+    /** "(o PagBank pede para pagar pelo app)" — `null` when no name was published. */
+    why: (provider: string | null) => string;
+    cpfIncomplete: string;
+    phoneIncomplete: string;
+  };
+  /** Why the button is disabled — shown under it. */
+  reasons: {
+    choose: string;
+    cpf: string;
+    phone: string;
+    details: string;
+    chooseCard: string;
+    cardDetails: string;
+    /** Google Pay is chosen while the host re-prices (`totalCents` briefly absent). Absent ⇒ no sentence. */
+    repricing?: string;
+  };
+  /** The button's verb, beside the total. */
+  actions: {
+    choose: string;
+    card: string;
+    pix: string;
+    googlePay: string;
+    handOff: (provider: string | null) => string;
+  };
+  /** "Pagando como Ana Teste · CPF ✓". */
+  payer: (name: string) => string;
+  payerChange: string;
+  /** The 5-second bar: "Pagando R$ 27,00 no Visa final 4242…"; `card` is `null` for a card typed now. */
+  charging: (total: string, card: string | null) => string;
+  /**
+   * The 5-second bar when the host's balance pays the WHOLE amount
+   * (`totalCents` 0), so no card is charged and none is named — "Confirmando
+   * o pedido, pago com o seu saldo…". Absent ⇒ `charging` as usual.
+   */
+  chargingCovered?: string;
+  cancel: string;
+  pixFace: {
+    /** "Pague R$ 22,00 com Pix". */
+    title: (total: string) => string;
+    /** "Válido até 18:42. Copie o código e cole no app do seu banco, em Pix copia e cola." */
+    validUntil: (time: string) => string;
+    showQr: string;
+    hideQr: string;
+    changeMethod: string;
+    /** The bar's action, and the accessible name of the tappable code. */
+    copyCode: string;
+    waiting: string;
+  };
+  /** "Aguardando a InfinitePay…" */
+  handOffWaiting: (provider: string | null) => string;
+}

package/src/components/checkout/list/use-capability.ts

@@ -0,0 +1,58 @@
+import { useMemo, useState } from "react";
+
+import { useGooglePayClient, type GooglePayGatewayParams, type GooglePaymentsClient } from "../google-pay-button";
+import { cardPathAvailable, googlePayConfig, offeredMethods } from "../method-capability";
+import { methodChosenAtProvider } from "../providers/registry";
+import type { CheckoutProviderConfig } from "../types";
+
+import type { OnlineCapability } from "./choice";
+
+/** What the store's chain lets THIS browser offer in the list, Google Pay's client included. */
+export interface ListCapability extends OnlineCapability {
+  /** Google Pay, ready to open its sheet — `null` when there is no row, or while the host re-prices. */
+  googlePay: { client: GooglePaymentsClient; params: GooglePayGatewayParams } | null;
+}
+
+/**
+ * The capability reads the tabs layout already makes (`method-capability.ts`,
+ * `providers/registry.ts`), plus the one the list adds: Google Pay as its own
+ * row, offered only when the chain head declares it AND this browser's
+ * `isReadyToPay` said yes — the same two gates the Google Pay button has
+ * always had (FUT-471), so the list never offers a wallet that cannot work.
+ *
+ * The sheet must open inside the tap, before any order exists, so it is priced
+ * with the host's `totalCents` — the amount DUE. A host that never priced it,
+ * or prices it at zero (a balance it holds covers everything), offers no row.
+ * Once priced, a moment without a price (the host re-pricing — the credit was
+ * toggled) keeps the row, and the list holds a chosen Google Pay's button,
+ * plainly, until the price returns.
+ *
+ * Apple Pay is not a row here: its sheet must open synchronously inside the
+ * tap, before any order could be raised for it. The tabs layout keeps it.
+ */
+export function useListCapability(
+  config: CheckoutProviderConfig | null,
+  /** The host's price for the sheet — no price (or zero), no Google Pay row. */
+  totalCents: number | undefined,
+): ListCapability {
+  const declared = googlePayConfig(config) !== null;
+  // `null` tells the client hook not to load pay.js at all.
+  const client = useGooglePayClient(declared ? undefined : null, "TEST");
+  const priced = totalCents !== undefined && totalCents > 0;
+  // Priced once, and not since withdrawn by an explicit zero.
+  const [wasPriced, setWasPriced] = useState(false);
+  if (priced && !wasPriced) setWasPriced(true);
+  if (totalCents === 0 && wasPriced) setWasPriced(false);
+  const repricing = totalCents === undefined && wasPriced;
+  return useMemo(() => {
+    const params = googlePayConfig(config);
+    const usable = params && client ? { client, params } : null;
+    return {
+      handOff: methodChosenAtProvider(config?.chain?.[0]?.checkoutScreen, config),
+      offered: offeredMethods(config),
+      cardUnavailable: !cardPathAvailable(config),
+      googlePayReady: usable !== null && (priced || repricing),
+      googlePay: priced ? usable : null,
+    };
+  }, [config, client, priced, repricing]);
+}

package/src/components/checkout/list/use-list-charge.ts

@@ -0,0 +1,186 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { CheckoutOrder, PaymentMethod } from "../types";
+
+/**
+ * How long the card's "Pagando R$ X no Visa final 4242…" bar takes to fill —
+ * the window in which "Cancelar" still sends nothing (FUT-3592, M10). The
+ * owner's own number: the bar replaces the confirmation dialog, so it is the
+ * buyer's whole chance to change their mind.
+ */
+export const CHARGE_WINDOW_MS = 5_000;
+
+/**
+ * Where a charge the bar's button started stands.
+ *
+ *  - `idle` — the list, with the button.
+ *  - `counting` — the card's 5-second bar; Cancelar still sends nothing.
+ *  - `sending` — the order is being raised, then the instrument charged.
+ *  - `waiting` — the charge was accepted and its confirmation is awaited.
+ */
+export type ListChargePhase = "idle" | "counting" | "sending" | "waiting";
+
+/** What a charge runs against: the card the buyer chose, or Google Pay's sheet. */
+export type ListChargeKind = "CARD" | "GOOGLE_PAY";
+
+/** The controller's slice this needs. */
+interface RaisePorts {
+  order: CheckoutOrder | null;
+  creating: boolean;
+  createError: string | null;
+  setMethod: (method: PaymentMethod) => void;
+  startPayment: (method: PaymentMethod) => Promise<void>;
+  /** The amount the buyer is shown now (the cart's, or the balance's). */
+  cartTotal: string;
+  /** What an online payment asks the provider for now, when the host prices it (`paymentList.totalCents`). */
+  dueCents?: number;
+}
+
+export interface ListCharge {
+  phase: ListChargePhase;
+  kind: ListChargeKind | null;
+  /** The amount named when the button was pressed — the bar shows THIS, never a later one. */
+  pressedTotal: string | null;
+  /** Start a card charge (with its 5-second bar) or a Google Pay one (straight away). Only from idle. */
+  start: (kind: ListChargeKind, total: string) => void;
+  /** Cancelar, during the bar: nothing has been sent, and nothing will be. */
+  cancel: () => void;
+  /**
+   * Whether the charge may still go out — set by the list on every render. A
+   * hold the host raised, a reason the button would show, or a total that
+   * moved since the press stops the bar, and `send` checks it again.
+   */
+  setAllowed: (allowed: boolean) => void;
+  /** The runner reports the charge was accepted and is now awaited. */
+  accepted: () => void;
+  /** The runner, or the raise, gave up: back to the list as it was. */
+  settle: () => void;
+  /** The CARD order the runner charges — set once one is held for this charge. */
+  chargeable: CheckoutOrder | null;
+}
+
+/**
+ * A held CARD order still awaiting payment AND priced as the buyer now sees —
+ * reusable for the charge. A balance ticked or unticked moves what the charge
+ * asks for and not the order's total, so the amount due is compared too.
+ */
+function reusable(order: CheckoutOrder | null, cartTotal: string, dueCents: number | undefined): boolean {
+  if (order?.method !== "CARD" || order.status !== "AWAITING_PAYMENT" || order.totalLabel !== cartTotal) return false;
+  return dueCents === undefined || (order.amountDueCents ?? order.totalCents) === dueCents;
+}
+
+/**
+ * An awaiting CARD order that asks the provider for nothing: a balance the host
+ * holds covers it, and the host should have settled it (see `amountDueLabel`).
+ * It is never charged.
+ */
+function owesNothing(order: CheckoutOrder | null): boolean {
+  return order?.method === "CARD" && order.status === "AWAITING_PAYMENT" && order.amountDueCents === 0;
+}
+
+/** The order `send` meant: the one it reused, or the CARD order raised to replace a stale one. */
+function chargeTarget(
+  order: CheckoutOrder | null,
+  target: { reuse: CheckoutOrder } | { replace: CheckoutOrder | null } | null,
+): CheckoutOrder | null {
+  if (!order || !target || order.method !== "CARD" || order.status !== "AWAITING_PAYMENT" || owesNothing(order)) return null;
+  if ("reuse" in target) return target.reuse === order ? order : null;
+  return order !== target.replace ? order : null;
+}
+
+/**
+ * Back to the list when the press left nothing to charge: a raise that failed
+ * (the step's error panel says why), or a held order that owes the provider
+ * nothing — never charged, rather than waited on forever.
+ */
+function useSettleWhenNothingToCharge(phase: ListChargePhase, kind: ListChargeKind | null, ports: RaisePorts, settle: () => void): void {
+  const { order, creating, createError } = ports;
+  useEffect(() => {
+    if (phase !== "sending" || creating) return;
+    if ((!order && createError) || (kind === "CARD" && owesNothing(order))) settle();
+  }, [phase, kind, creating, order, createError, settle]);
+}
+
+/**
+ * The bar's charge, after the button (FUT-3592): count down for a card, then
+ * raise the order — or reuse the CARD order already held, after a refusal the
+ * buyer is retrying, but only while it is priced as the cart now is (a credit
+ * toggled, an address changed: re-raise, never charge the old amount) — and
+ * hand it to the runner that charges it.
+ *
+ * Nothing is sent before `sending`: the timer is the only thing running while
+ * the bar fills, so Cancelar has nothing to undo.
+ */
+export function useListCharge(ports: RaisePorts): ListCharge {
+  const [phase, setPhase] = useState<ListChargePhase>("idle");
+  const [kind, setKind] = useState<ListChargeKind | null>(null);
+  const [pressedTotal, setPressedTotal] = useState<string | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const allowed = useRef(true);
+  // What `send` decided to charge: the held order it reused, or "a fresh one"
+  // — any CARD order other than the stale one it replaced.
+  const target = useRef<{ reuse: CheckoutOrder } | { replace: CheckoutOrder | null } | null>(null);
+  const latest = useRef(ports);
+  latest.current = ports;
+
+  const cancel = useCallback(() => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+    setPhase("idle");
+    setKind(null);
+    setPressedTotal(null);
+  }, []);
+
+  const send = useCallback(() => {
+    timer.current = null;
+    // Checked again at the last moment: a hold raised between two renders
+    // must not let the bar's own timer charge past it.
+    if (!allowed.current) return cancel();
+    setPhase("sending");
+    const { order, cartTotal, dueCents } = latest.current;
+    if (reusable(order, cartTotal, dueCents) && order) {
+      target.current = { reuse: order };
+      return;
+    }
+    target.current = { replace: order };
+    latest.current.setMethod("CARD");
+    void latest.current.startPayment("CARD");
+  }, [cancel]);
+
+  const phaseRef = useRef(phase);
+  phaseRef.current = phase;
+  const start = useCallback(
+    (next: ListChargeKind, total: string) => {
+      if (phaseRef.current !== "idle") return;
+      phaseRef.current = next === "GOOGLE_PAY" ? "sending" : "counting";
+      setKind(next);
+      setPressedTotal(total);
+      if (next === "GOOGLE_PAY") return send();
+      setPhase("counting");
+      timer.current = setTimeout(send, CHARGE_WINDOW_MS);
+    },
+    [send],
+  );
+
+  const setAllowed = useCallback(
+    (next: boolean) => {
+      allowed.current = next;
+      if (!next && phaseRef.current === "counting") cancel();
+    },
+    [cancel],
+  );
+
+  const settle = cancel;
+  const accepted = useCallback(() => setPhase("waiting"), []);
+
+  useEffect(() => () => {
+    if (timer.current) clearTimeout(timer.current);
+  }, []);
+
+  const { order, creating } = ports;
+  useSettleWhenNothingToCharge(phase, kind, ports, settle);
+
+  const sending = phase === "sending" || phase === "waiting";
+  const chargeable = sending && !creating ? chargeTarget(order, target.current) : null;
+  return { phase, kind, pressedTotal, start, cancel, setAllowed, accepted, settle, chargeable };
+}