@12-apps/payments-frontend 3.37.0 → 3.38.0

package/src/components/checkout/payment-phase.tsx

@@ -0,0 +1,119 @@
+import type { JSX } from "react";
+
+import type { CheckoutCartView, CheckoutFlowProps } from "./checkout-flow";
+import { PaymentStep } from "./checkout-steps";
+import { PaymentListStep } from "./list/payment-list-step";
+import { OneClickProvider } from "./one-click";
+import type { CheckoutProviderConfig, SettlementCheckout } from "./types";
+import type { useCheckoutController } from "./use-checkout-controller";
+
+/**
+ * Step 2 of `<CheckoutFlow>`, moved out of `./checkout-flow.tsx` at its size
+ * gate when the Pagamento step gained a second shape (FUT-3591): the method
+ * tabs it always had, or the one list a host opts into.
+ */
+
+/** The pay-bar total override when settling a settlement (else the cart's own totals). */
+export function settlementTotalOverride(
+  settlement: SettlementCheckout | null | undefined,
+): { label: string; items: number } | undefined {
+  return settlement ? { label: settlement.totalLabel, items: settlement.totalItems } : undefined;
+}
+
+/** Step 2, with the controller's facts and the host's money mapped onto it. */
+function PagamentoStep({
+  c,
+  cart,
+  settlement,
+  providerConfig,
+  tenantSlug,
+  validateApplePayMerchant,
+}: {
+  c: ReturnType<typeof useCheckoutController>;
+  cart: CheckoutCartView;
+  settlement: SettlementCheckout | null | undefined;
+  providerConfig: CheckoutProviderConfig | null | undefined;
+  tenantSlug: string | undefined;
+  validateApplePayMerchant: ((validationURL: string) => Promise<unknown>) | undefined;
+}): JSX.Element {
+  return (
+    <PaymentStep
+      method={c.method}
+      onMethodChange={c.setMethod}
+      order={c.order}
+      buyer={c.buyer}
+      creating={c.creating}
+      createError={c.createError}
+      errorField={c.errorField}
+      errorCode={c.errorCode}
+      onGenerate={(chosen) => void c.startPayment(chosen)}
+      refresh={c.refresh}
+      onUseEmail={c.payWithEmail}
+      // Set only for a skipped-Dados flow (the controller decides); the payer
+      // block hides itself when it is absent.
+      onEditBuyer={c.editBuyer}
+      providerConfig={providerConfig}
+      tenantSlug={tenantSlug}
+      // The amount, on the step that asks for it (FUT-1179).
+      cartTotals={cart}
+      totalOverride={settlementTotalOverride(settlement)}
+      discountLines={cart.discountLines}
+      // The order around the payment, for the summary (FUT-3525).
+      lines={cart.lines}
+      delivery={cart.delivery}
+      orderNote={cart.orderNote}
+      // Retrying a refused card: the failed saved card is not chosen again (FUT-1145).
+      freshInstrument={c.freshInstrument}
+      // The card path parks an order of its own for a 3-D Secure challenge, so
+      // it needs the same basket the flow was mounted for (FUT-1213).
+      basket={cart.identity}
+      validateApplePayMerchant={validateApplePayMerchant}
+      onResolved={c.handleResolved}
+    />
+  );
+}
+
+/**
+ * Step 2, in whichever shape the host asked for: the one list, or the tabs.
+ * The list never arms one-click — it raises nothing on its own, which is the
+ * one-click request's ordinary degraded outcome anyway.
+ */
+export function PaymentPhase({
+  props,
+  c,
+  armed,
+}: {
+  props: Omit<CheckoutFlowProps, "components">;
+  c: ReturnType<typeof useCheckoutController>;
+  armed: boolean;
+}): JSX.Element {
+  const { cart, settlement, providerConfig, tenantSlug, validateApplePayMerchant, paymentList } = props;
+  if (paymentList) {
+    return (
+      <PaymentListStep
+        c={c}
+        list={paymentList}
+        cart={cart}
+        totalOverride={settlementTotalOverride(settlement)}
+        providerConfig={providerConfig}
+        tenantSlug={tenantSlug}
+        taxIdOnFile={props.taxIdOnFile ?? false}
+        defaultBuyer={props.defaultBuyer}
+        saveBuyerContact={props.saveBuyerContact}
+        consentLabel={props.copy.dados.saveProfile}
+      />
+    );
+  }
+  return (
+    <OneClickProvider armed={armed}>
+      <PagamentoStep
+        c={c}
+        cart={cart}
+        settlement={settlement}
+        providerConfig={providerConfig}
+        tenantSlug={tenantSlug}
+        validateApplePayMerchant={validateApplePayMerchant}
+      />
+    </OneClickProvider>
+  );
+}

package/src/components/checkout/pix-parts.tsx

@@ -105,6 +105,9 @@ export function StaleVeil({ stale, children }: { stale: boolean; children: React
         >
           <Box
             component="p"
+            // An opaque overlay over the blurred code (ADR 0121): it covers
+            // what is under it on purpose, so the review probe reads it so.
+            data-ui-overlay=""
             sx={{
               m: 0,
               px: 1.5,

package/src/components/checkout/pix-view.tsx

@@ -2,6 +2,8 @@ import { Box } from "@mui/material";
 import { useEffect, useMemo, useRef, type JSX } from "react";
 
 import { useCheckoutCopy } from "./copy-context";
+import { usePaymentListMode } from "./list/context";
+import { ListPixFace } from "./list/list-pix";
 import { PixAfterCopy } from "./pix-after-copy";
 import { PixPane } from "./pix-pane";
 import { useCheckoutLayout } from "./payment-step-layout";
@@ -221,15 +223,19 @@ function PixTitle(): JSX.Element | null {
   );
 }
 
-function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; poll: ReturnType<typeof usePixPolling> }): JSX.Element {
-  const copy = useCheckoutCopy().screens.pix;
-  const stage = usePixStage();
-  const { copy: writeClipboard, justCopied } = useClipboardCopy(pix.copyPaste);
-  // Leaving the payment step (a method switch, a terminal status) ends the
-  // after-copy face with it: the next pane starts on the code.
-  const { setAfterCopy } = stage;
-  // A clipboard write that settles after the pane is gone must not reopen the
-  // after-copy face over whatever replaced it (it would hide the picker).
+/**
+ * The clipboard, and the copy that moves the pane on to its after-copy face.
+ *
+ * Leaving the payment step (a method switch, a terminal status) ends the
+ * after-copy face with it: the next pane starts on the code. And a clipboard
+ * write that settles after the pane is gone must not reopen the after-copy
+ * face over whatever replaced it (it would hide the picker).
+ */
+function useCopyThenWait(
+  payload: string,
+  setAfterCopy: (afterCopy: boolean) => void,
+): { writeClipboard: () => Promise<boolean>; justCopied: boolean; copyThenWait: () => void } {
+  const { copy: writeClipboard, justCopied } = useClipboardCopy(payload);
   const mounted = useRef(true);
   useEffect(() => {
     mounted.current = true;
@@ -238,6 +244,22 @@ function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; p
       setAfterCopy(false);
     };
   }, [setAfterCopy]);
+  // Only a copy the clipboard TOOK moves on: the next face opens on "Código
+  // Pix copiado", and a failed write leaves the code on screen to select by hand.
+  const copyThenWait = (): void => {
+    void writeClipboard().then((ok) => {
+      if (ok && mounted.current) setAfterCopy(true);
+    });
+  };
+  return { writeClipboard, justCopied, copyThenWait };
+}
+
+function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; poll: ReturnType<typeof usePixPolling> }): JSX.Element {
+  const copy = useCheckoutCopy().screens.pix;
+  const stage = usePixStage();
+  const listMode = usePaymentListMode();
+  const { writeClipboard, justCopied, copyThenWait } = useCopyThenWait(pix.copyPaste, stage.setAfterCopy);
+  const { setAfterCopy } = stage;
 
   // The locale is the HOST's (FUT-760): it decides what a buyer reads off the
   // clock, so it travels with the sentence it feeds rather than being frozen
@@ -247,6 +269,27 @@ function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; p
   const footerLine = (awaiting: string): JSX.Element => (
     <PixPollFooter error={poll.error} timedOut={poll.timedOut} onCheckAgain={poll.checkAgain} awaiting={awaiting} />
   );
+  // Inside the one list (FUT-3592), the code itself is the pane and the bar
+  // carries the copy; the wait is said by the bar, so only a STALLED poll
+  // draws here.
+  if (listMode) {
+    return (
+      <ListPixFace
+        mode={listMode}
+        order={order}
+        pix={pix}
+        time={time}
+        afterCopy={stage.afterCopy}
+        words={sentences.afterCopy}
+        justCopied={justCopied}
+        onCopy={copyThenWait}
+        onCopyAgain={() => void writeClipboard()}
+        onShowQr={() => setAfterCopy(false)}
+        onPreferCard={stage.preferCard}
+        footer={poll.error || poll.timedOut ? footerLine(copy.verifying) : null}
+      />
+    );
+  }
 
   if (stage.afterCopy) {
     return (
@@ -267,17 +310,7 @@ function PixBody({ order, pix, poll }: { order: CheckoutOrder; pix: PixCharge; p
   return (
     <>
       <PixTitle />
-      <PixPane
-        pix={pix}
-        onCopy={() => {
-          // Only a copy the clipboard TOOK moves on: the next face opens on
-          // "Código Pix copiado", and a failed write leaves the code on screen
-          // to select by hand.
-          void writeClipboard().then((ok) => {
-            if (ok && mounted.current) setAfterCopy(true);
-          });
-        }}
-      />
+      <PixPane pix={pix} onCopy={copyThenWait} />
       <PixFooter deadline={sentences.validUntil(time)}>{footerLine(sentences.awaiting)}</PixFooter>
     </>
   );

package/src/components/checkout/use-card-checkout.ts

@@ -4,7 +4,6 @@ import {
   NEW_CARD,
   detectBrand,
   onlyDigits,
-  tokenizerFor,
   validateCardNumber,
   validateCvv,
   validateExpiry,
@@ -23,6 +22,7 @@ import {
   type RefreshBrowserKey,
 } from "./card-instruments";
 import { handOverToChallenge, reportResolved, type ChallengeScope } from "./card-outcome";
+import { useCardPublicKey, useSavedCards } from "./card-sources";
 import { useCheckoutClientApi } from "./client-context";
 import { useCheckoutNavigate } from "./navigate-context";
 import type { CardChainLink } from "./method-capability";
@@ -34,80 +34,6 @@ import { useCheckoutCopy } from "./copy-context";
 
 const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
 
-/**
- * Saved-card list + current selection, loaded once on mount — scoped to the
- * current store (FUT-697), so only cards the store's active provider can
- * actually charge are offered. The slug arrives as an argument (the host's
- * routing owns it); absent, the list is unscoped, exactly as before FUT-697.
- */
-function useSavedCards(
-  tenantSlug: string | undefined,
-  /**
-   * The buyer is here because a card was REFUSED (FUT-1145), so the saved card
-   * this would otherwise preselect is the one that just failed. The list is
-   * still offered — another saved card may well work — but nothing is chosen
-   * for them, which puts the form in front of a buyer whose only untried
-   * instrument is a new one.
-   */
-  freshInstrument: boolean,
-): {
-  savedCards: SavedCard[];
-  selection: string;
-  setSelection: (id: string) => void;
-} {
-  const [savedCards, setSavedCards] = useState<SavedCard[]>([]);
-  const [selection, setSelection] = useState<string>(NEW_CARD);
-  const client = useCheckoutClientApi();
-
-  useEffect(() => {
-    let active = true;
-    void client.listInstruments(tenantSlug).then((cards) => {
-      if (!active) return;
-      setSavedCards(cards);
-      const first = cards[0];
-      if (first && !freshInstrument) setSelection(first.id);
-    });
-    return () => {
-      active = false;
-    };
-  }, [tenantSlug, client, freshInstrument]);
-
-  return { savedCards, selection, setSelection };
-}
-
-/**
- * The store's card public key for this order. The checkout config resolved the
- * initial key server-side (`GET /api/checkout/config`, FUT-697); the SPA
- * fetches through the order-scoped refresh route only when the ACTIVE provider
- * is PagBank — the sole provider that can mint a key on demand — and the
- * config arrived without one. A `null` key never means "mock": stub permission
- * travels separately as `mockTokenization`.
- */
-function useCardPublicKey(
-  orderId: string,
-  config: CardTokenizationConfig,
-): {
-  publicKey: string | null;
-  setPublicKey: (key: string) => void;
-} {
-  const [publicKey, setPublicKey] = useState<string | null>(config.publicKey);
-  const client = useCheckoutClientApi();
-  const refreshable =
-    config.provider !== null && tokenizerFor(config.provider) === "pagbank-sdk";
-
-  useEffect(() => {
-    if (config.publicKey !== null || !refreshable) return undefined;
-    let active = true;
-    void client.refreshBrowserKey({ orderId }).then((result) => {
-      if (active && result.ok && result.data.publicKey) setPublicKey(result.data.publicKey);
-    });
-    return () => {
-      active = false;
-    };
-  }, [orderId, config.publicKey, refreshable, client]);
-
-  return { publicKey, setPublicKey };
-}
 
 /** Everything the card view renders — all checkout state + the submit handler. */
 export interface CardCheckout {
@@ -137,6 +63,12 @@ export interface CardCheckout {
   pollTimedOut: boolean;
   /** Ask now and restart the wait — the buyer's "verificar de novo". */
   pollCheckAgain: () => void;
+  /**
+   * The order-scoped key refresh has not answered yet (`./card-sources.ts`): a
+   * charge started now would tokenize a new card with no key. A screen that
+   * starts the charge itself waits for this to clear.
+   */
+  keyPending: boolean;
   handlePay: () => Promise<void>;
 }
 
@@ -160,6 +92,7 @@ type CardSubmit = Pick<
   | "pollError"
   | "pollTimedOut"
   | "pollCheckAgain"
+  | "keyPending"
   | "handlePay"
 >;
 
@@ -246,7 +179,7 @@ function useCardWait(
  * poll for the async confirmation, bubbling the terminal status up via
  * {@link onResolved}.
  */
-function useCardSubmit(
+export function useCardSubmit(
   order: CheckoutOrder,
   buyer: BuyerInfo,
   providerConfig: CardTokenizationConfig,
@@ -264,7 +197,7 @@ function useCardSubmit(
   const [errorCode, setErrorCode] = useState<string | null>(null);
   // The active key: resolved by the checkout config, overridden by the
   // rotated-key self-heal for the rest of the session.
-  const { publicKey, setPublicKey } = useCardPublicKey(order.orderId, providerConfig);
+  const { publicKey, setPublicKey, keyPending } = useCardPublicKey(order.orderId, providerConfig);
   const client = useCheckoutClientApi();
   const navigate = useCheckoutNavigate();
   const cardCopy = useCheckoutCopy().card;
@@ -323,7 +256,7 @@ function useCardSubmit(
     else setSubmitted(true);
   };
 
-  return { submitting, submitted, error, errorCode, ...wait, handlePay };
+  return { submitting, submitted, error, errorCode, ...wait, keyPending, handlePay };
 }
 
 /**

package/src/components/checkout/use-checkout-controller.ts

@@ -5,6 +5,7 @@ import {
   resumeSurface,
   useCheckoutNav,
   useCreateFailure,
+  useDropOrder,
   useGoToPayment,
   useResumedCheckout,
   useRetryAction,
@@ -135,6 +136,7 @@ export function useCheckoutController(
       return next;
     });
   }, [clearError, tenantSlug]);
+  const dropOrder = useDropOrder(setOrder, tenantSlug, clearError);
   const goToPayment = useGoToPayment({
     buyer, buyerFields, taxIdOnFile, saveProfile, saveBuyerContact, validation, failure, setStep,
   });
@@ -170,6 +172,6 @@ export function useCheckoutController(
     ...resumeSurface(resume, confirming),
     createError: failure.message, errorField: failure.field, errorCode: failure.code,
     goToMenu: onExitToMenu, back, editBuyer,
-    goToPayment, startPayment, refresh, payWithEmail, handleResolved, retry, completed,
+    goToPayment, startPayment, refresh, payWithEmail, handleResolved, retry, completed, dropOrder,
   };
 }

package/src/flows/create-payment-flows.tsx

@@ -68,6 +68,11 @@ function buildRuntime(config: PaymentFlowsConfig): FlowsRuntime {
   };
 }
 
+/** The host's one-list Pagamento (FUT-3591), when it opted in — a hook, read every render. */
+function useHostPaymentList(runtime: FlowsRuntime) {
+  return runtime.config.usePaymentList?.();
+}
+
 /** The whole three-step flow, with the config fetched and availability decided. */
 function buildCheckout(
   runtime: FlowsRuntime,
@@ -80,6 +85,7 @@ function buildCheckout(
     const cart = runtime.config.useCart();
     const defaults = runtime.config.useBuyerDefaults?.() ?? {};
     const hostSettlement = runtime.config.useSettlement?.() ?? null;
+    const paymentList = useHostPaymentList(runtime);
     const { config, pending } = useResolvedConfig(runtime);
     const availability = runtime.useAvailability();
     const tenantSlug = runtime.useTenantSlug();
@@ -108,6 +114,7 @@ function buildCheckout(
         confirmationExtra={runtime.config.confirmation?.extra}
         confirmationHero={runtime.config.confirmation?.hero}
         validateApplePayMerchant={ports.validateApplePayMerchant}
+        paymentList={paymentList}
       />
     );
   }

package/src/flows/types.ts

@@ -19,6 +19,7 @@
  * `chain[].provider`, looked up in the tokenizer registry and used verbatim as
  * a `tokensByProvider` key. A host never types one.
  */
+import type { CheckoutPaymentList } from "../components/checkout/list/types";
 import type { ComponentType, ReactNode } from "react";
 
 import type { SavedCard } from "../card";
@@ -115,6 +116,12 @@ export interface PaymentFlowsConfig extends CheckoutPipelineConfig {
   useBuyerDefaults?(): { buyer?: BuyerInfo; taxIdOnFile?: boolean; pending?: boolean };
   /** Present ⇒ this checkout settles a settlement rather than the cart. */
   useSettlement?(): SettlementCheckout | null;
+  /**
+   * The Pagamento step as ONE list (FUT-3591) — `CheckoutFlowProps.paymentList`,
+   * read through a HOOK because the host's door options follow its own state.
+   * Absent, or answering `undefined`, keeps the method tabs.
+   */
+  usePaymentList?(): CheckoutPaymentList | undefined;
 
   /** Design-system slots, filled ONCE instead of per screen. */
   components?: Partial<CheckoutComponents>;

package/src/index.ts

@@ -54,11 +54,10 @@ export { PT_BR_CHECKOUT_PAYMENT_COPY } from './components/checkout-payment-pt-BR
 // mounted by a host in one line. See ADOPTING.md §3 for the ports and the
 // design-system slot contract.
 // ---------------------------------------------------------------------------
-export {
-  CheckoutFlow,
-  type CheckoutCartView,
-  type CheckoutFlowProps,
-} from './components/checkout/checkout-flow';
+export { CheckoutFlow, type CheckoutCartView, type CheckoutFlowProps } from './components/checkout/checkout-flow';
+// The Pagamento step as ONE list (FUT-3591/3592) — opt-in via `CheckoutFlowProps.paymentList`.
+export type { CheckoutDoorOption, CheckoutListChoice, CheckoutListHold, CheckoutOnlineChoice, CheckoutPaymentList, PaymentListCopy } from './components/checkout/list/types';
+export { PT_BR_PAYMENT_LIST_COPY } from './components/checkout/list/pt-BR';
 export type { BackActionEmphasis } from './components/checkout/payment-status-parts';
 export type { CheckoutDeliverySummary, CheckoutSummaryLine } from './components/checkout/payment-summary';
 

package/src/locales.ts

@@ -20,6 +20,9 @@ import {
 import { EN_US_CHECKOUT_SCREENS_COPY } from './components/checkout/screens-en-US';
 import type { CheckoutScreensCopy } from './components/checkout/screens-copy';
 import { PT_BR_CHECKOUT_SCREENS_COPY } from './components/checkout/screens-pt-BR';
+import { EN_US_PAYMENT_LIST_COPY } from './components/checkout/list/en-US';
+import { PT_BR_PAYMENT_LIST_COPY } from './components/checkout/list/pt-BR';
+import type { PaymentListCopy } from './components/checkout/list/types';
 import type { CheckoutViewCopy, PaymentStatusCopy } from './components/checkout/view-copy';
 import type { PlatformHomologacaoCopy } from './components/platform/copy';
 import { EN_US_PLATFORM_HOMOLOGACAO_COPY } from './components/platform/en-US';
@@ -76,6 +79,15 @@ export const CHECKOUT_SCREENS_COPY = {
   'en-US': EN_US_CHECKOUT_SCREENS_COPY,
 } as const satisfies LocalePack<CheckoutScreensCopy>;
 
+/**
+ * The one-list Pagamento step's words (FUT-3591) — `CheckoutFlowProps.paymentList.copy`.
+ * Read by the SHOPPER, like every checkout pack.
+ */
+export const PAYMENT_LIST_COPY = {
+  'pt-BR': PT_BR_PAYMENT_LIST_COPY,
+  'en-US': EN_US_PAYMENT_LIST_COPY,
+} as const satisfies LocalePack<PaymentListCopy>;
+
 export const CHECKOUT_COPY = {
   'pt-BR': PT_BR_CHECKOUT_COPY,
   'en-US': EN_US_CHECKOUT_COPY,
@@ -123,6 +135,7 @@ export {
   EN_US_PAYMENT_STATUS_COPY,
 } from './components/checkout/en-US';
 export { EN_US_CHECKOUT_SCREENS_COPY } from './components/checkout/screens-en-US';
+export { EN_US_PAYMENT_LIST_COPY } from './components/checkout/list/en-US';
 export { EN_US_PAYMENTS_SETTINGS_COPY } from './components/settings-en-US';
 export { EN_US_PLATFORM_HOMOLOGACAO_COPY } from './components/platform/en-US';
 export { EN_US_TENDER_SPLIT_COPY } from './tender-split/en-US';