@12-apps/payments-frontend 3.43.1 → 3.45.0

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

@@ -20,6 +20,22 @@
  */
 import type { ReactNode } from "react";
 
+/**
+ * What a door option's `content` function is handed (FUT-3715).
+ *
+ * `choose` is exactly what the row's radio does; calling it on the chosen row
+ * changes nothing. The list reports the choice through `onChoiceChange` as it
+ * does for the radio — from an effect, after the render — so a host that
+ * answers in the same tap keeps its answer across that render. The list never
+ * moves keyboard focus here: where focus goes is the host's call.
+ */
+export interface CheckoutDoorRowControls {
+  /** This option is the list's current choice. */
+  chosen: boolean;
+  /** Choose this option, as its radio would. */
+  choose: () => void;
+}
+
 /**
  * One of the host's ways to pay at the door — "Dinheiro", "Maquininha".
  *
@@ -41,10 +57,25 @@ export interface CheckoutDoorOption {
   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.
+   * tender chips, the brand lines). Rendered only while chosen — unless
+   * `showContentWhileIdle` — with no left indent: it starts where the row's own
+   * content starts.
+   *
+   * As a function it is handed the row's own controls, so a control inside the
+   * content can choose the row in the same tap that answers it (the troco
+   * chips, FUT-3715). A plain node behaves exactly as before. The function is
+   * called during the row's render, not mounted as a component: keep it one
+   * shape for the option's life, and return a component of your own if the
+   * content needs hooks.
+   */
+  content?: ReactNode | ((row: CheckoutDoorRowControls) => ReactNode);
+  /**
+   * Render `content` while the option is NOT chosen too — for an option whose
+   * answers are themselves the way to choose it (FUT-3715). The unchosen row
+   * keeps its unchosen frame; the content keeps its box and place in both
+   * states, so choosing the row moves nothing.
    */
-  content?: ReactNode;
+  showContentWhileIdle?: boolean;
   /** 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. */
@@ -62,7 +93,12 @@ export interface CheckoutDoorOption {
   onSend: () => void;
 }
 
-/** The online ways to pay the list may offer, as the host is told about them. */
+/**
+ * The online ways to pay the list may offer, as the host is told about them.
+ * `"GOOGLE_PAY"` is never reported any more: the wallets are buttons above the
+ * list, not rows (FUT-3685). It stays in the union so a host's exhaustive
+ * switch still compiles.
+ */
 export type CheckoutOnlineChoice = "PIX" | "CARD" | "GOOGLE_PAY" | "HAND_OFF";
 
 /** What the buyer has chosen in the list. */
@@ -104,15 +140,14 @@ export interface CheckoutPaymentList {
   /**
    * 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`.
+   * (store credit). It is what the wallets' sheets are priced with (FUT-3685),
+   * since a sheet must open INSIDE the tap, before any order exists to read a
+   * price from. Never given, or zero (a balance covers everything) ⇒ no wallet
+   * buttons. Once given, a moment without it (the host re-pricing) keeps their
+   * place, held — plainly, with `copy.reasons.repricing` — until it returns. A
+   * 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;
   /**
@@ -168,6 +203,17 @@ export interface CheckoutPaymentList {
   pixBank?: CheckoutPixBank;
   /** Says a short sentence in the host's own toast — "Código Pix copiado". */
   notify?: (message: string) => void;
+  /**
+   * The host lays out the computer's two columns itself (FUT-3685, L4): its
+   * step cards on the left, and this element on the right — the list portals
+   * the "Resumo do pedido" column into it (the lines, the money rows, "Total",
+   * `summary`, the extras and the pay button), so no bar is drawn at the
+   * bottom. `null` while the element is not mounted yet: the bar waits rather
+   * than flash. Leave it OUT (undefined) on a phone, or to keep the list's own
+   * layout — the step and the column side by side once the flow's frame is
+   * wide, the bar otherwise. The Pix screen and the hand-off keep their bar.
+   */
+  summaryTarget?: HTMLElement | null;
 }
 
 /** The six banks the Pix face offers to open, in the prototype's order. */
@@ -240,7 +286,26 @@ export interface PaymentListCopy {
     /** "Digite os dados do cartão". */
     hintNew: string;
   };
+  /**
+   * @deprecated Google Pay is no longer a row (FUT-3685): it is a button in
+   * the "PAGAMENTO RÁPIDO" block — see {@link PaymentListCopy.wallets}. Kept so
+   * a host's own pack still type-checks; nothing draws it.
+   */
   googlePay: { label: string; hint: string };
+  /**
+   * The "PAGAMENTO RÁPIDO" block above the list (FUT-3685, T5–T8): the wallet
+   * buttons' accessible names and the words around them.
+   */
+  wallets: {
+    /** "Pagamento rápido" — drawn in capitals by CSS. */
+    heading: string;
+    /** "Pagar com Google Pay". */
+    googlePay: string;
+    /** "Pagar com Apple Pay". */
+    applePay: string;
+    /** "ou escolha como pagar" — the divider between the wallets and the rows. */
+    or: string;
+  };
   handOff: {
     label: string;
     /** "Você paga na página da InfinitePay e volta" — `null` when the store published no name. */
@@ -258,6 +323,17 @@ export interface PaymentListCopy {
     email: string;
     /** "(o PagBank pede para pagar pelo app)" — `null` when no name was published. */
     why: (provider: string | null) => string;
+    /**
+     * The line under "CPF" at the top of Pagamento (FUT-3685, T3) — "o PagBank
+     * pede para pagar pelo app"; `null` when no name was published.
+     */
+    cpfHint: (provider: string | null) => string;
+    /**
+     * The link under the CPF opened by "Alterar" over a CPF on file, closing it
+     * again — "Manter o CPF salvo" (FUT-3685). Both packs carry it; absent ⇒ no
+     * link (an empty field keeps the saved CPF either way).
+     */
+    keepSavedCpf?: string;
     cpfIncomplete: string;
     phoneIncomplete: string;
   };

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

@@ -1,58 +1,136 @@
-import { useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 
+import { applePaySessionClass, applePaySupported, type ApplePaySessionClass } from "../apple-pay-button";
 import { useGooglePayClient, type GooglePayGatewayParams, type GooglePaymentsClient } from "../google-pay-button";
-import { cardPathAvailable, googlePayConfig, offeredMethods } from "../method-capability";
+import { applePayDeclared, cardPathAvailable, googlePayConfig, offeredMethods } from "../method-capability";
 import { methodChosenAtProvider } from "../providers/registry";
-import type { CheckoutProviderConfig } from "../types";
+import type { CheckoutProviderConfig, PaymentMethod } from "../types";
 
 import type { OnlineCapability } from "./choice";
 
-/** What the store's chain lets THIS browser offer in the list, Google Pay's client included. */
+/** Apple Pay, ready to start a session inside the tap. */
+export interface ListApplePay {
+  Session: ApplePaySessionClass;
+  /** The host's merchant-validation port (server-side). */
+  validateMerchant: (validationURL: string) => Promise<unknown>;
+}
+
+/** What the store's chain lets THIS browser offer in the list, the wallets 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. */
+  /** Google Pay, ready to open its sheet — `null` when it is not offered, or while the host re-prices. */
   googlePay: { client: GooglePaymentsClient; params: GooglePayGatewayParams } | null;
+  /** Apple Pay, ready to start its session — `null` when it is not offered, or while the host re-prices. */
+  applePay: ListApplePay | null;
+  /**
+   * The wallets the "PAGAMENTO RÁPIDO" block draws, in the prototype's order.
+   * A wallet drawn while the host re-prices has its button held
+   * (`googlePay`/`applePay` is `null` for that moment).
+   */
+  wallets: ListWallet[];
+}
+
+export type ListWallet = "GOOGLE_PAY" | "APPLE_PAY";
+
+/**
+ * The host priced the sheet once and, for a moment, has no price (re-pricing:
+ * the credit was toggled) — a wallet keeps its place, held, until the price
+ * returns. An explicit zero (a balance covers everything) withdraws it.
+ */
+function useRepricing(totalCents: number | undefined): { priced: boolean; repricing: boolean } {
+  const priced = totalCents !== undefined && totalCents > 0;
+  const [wasPriced, setWasPriced] = useState(false);
+  if (priced && !wasPriced) setWasPriced(true);
+  if (totalCents === 0 && wasPriced) setWasPriced(false);
+  return { priced, repricing: totalCents === undefined && wasPriced };
+}
+
+/** Apple Pay's session class, when the chain head declares the wallet and this device can pay (R5). */
+function appleSession(config: CheckoutProviderConfig | null, port: ListApplePay["validateMerchant"] | undefined): ListApplePay | null {
+  if (!port || !applePayDeclared(config) || !applePaySupported()) return null;
+  const Session = applePaySessionClass();
+  return Session ? { Session, validateMerchant: port } : null;
+}
+
+/** Whether the card is offered and available on THIS page — what a wallet is another way of producing. */
+function cardHere(handOff: boolean, offered: PaymentMethod[] | null, cardUnavailable: boolean): boolean {
+  return !handOff && !cardUnavailable && (offered === null || offered.includes("CARD"));
+}
+
+/** The wallets the block draws: each ready one, while the card is here and the sheet is (or was) priced. */
+function walletsShown(shown: boolean, google: unknown, apple: unknown): ListWallet[] {
+  if (!shown) return [];
+  const wallets: ListWallet[] = [];
+  if (google) wallets.push("GOOGLE_PAY");
+  if (apple) wallets.push("APPLE_PAY");
+  return wallets;
+}
+
+/** Google Pay's client and the head's gateway parameters, when both are there. */
+function googleSheet(config: CheckoutProviderConfig | null, client: GooglePaymentsClient | null): ListCapability["googlePay"] {
+  const params = googlePayConfig(config);
+  return params && client ? { client, params } : null;
+}
+
+/** {@link useListCapability}'s answer, from what it read. */
+function capabilityOf(
+  config: CheckoutProviderConfig | null,
+  client: GooglePaymentsClient | null,
+  price: { priced: boolean; repricing: boolean },
+  port: ListApplePay["validateMerchant"] | undefined,
+): ListCapability {
+  const offered = offeredMethods(config);
+  const cardUnavailable = !cardPathAvailable(config);
+  const handOff = methodChosenAtProvider(config?.chain?.[0]?.checkoutScreen, config);
+  const card = cardHere(handOff, offered, cardUnavailable);
+  const google = googleSheet(config, client);
+  const apple = appleSession(config, port);
+  const live = card && price.priced;
+  return {
+    handOff,
+    offered,
+    cardUnavailable,
+    wallets: walletsShown(card && (price.priced || price.repricing), google, apple),
+    googlePay: live ? google : null,
+    applePay: live ? apple : 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.
+ * `providers/registry.ts`), plus the two wallets of the "PAGAMENTO RÁPIDO"
+ * block (FUT-3685, R5). A wallet is ready when the chain head declares it AND
+ * this device can pay with it — Google's `isReadyToPay`, Apple's
+ * `canMakePayments` — AND the card is offered and available here, since a
+ * wallet is another way of producing the card (so a Pix-only store never shows
+ * the block). Apple also needs the host's merchant-validation port: without it
+ * the session could only abort.
  *
- * The sheet must open inside the tap, before any order exists, so it is priced
+ * Both sheets open inside the tap, before any order exists, so they are 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.
+ * or prices it at zero (a balance covers everything), offers no wallet.
  */
 export function useListCapability(
   config: CheckoutProviderConfig | null,
-  /** The host's price for the sheet — no price (or zero), no Google Pay row. */
+  /** The host's price for the sheets — no price (or zero), no wallet. */
   totalCents: number | undefined,
+  validateApplePayMerchant?: ListApplePay["validateMerchant"],
 ): 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]);
+  const { priced, repricing } = useRepricing(totalCents);
+  // The port is read at the press, through a ref: a host passing a new
+  // function each render must not rebuild the capability (and the wallets'
+  // buttons) every time. Only whether there IS one changes what is offered.
+  const port = useRef(validateApplePayMerchant);
+  port.current = validateApplePayMerchant;
+  const hasPort = validateApplePayMerchant !== undefined;
+  const stablePort = useCallback((validationURL: string): Promise<unknown> => {
+    const current = port.current;
+    return current ? current(validationURL) : Promise.reject(new Error("no merchant validation port"));
+  }, []);
+  return useMemo(
+    () => capabilityOf(config, client, { priced, repricing }, hasPort ? stablePort : undefined),
+    [config, client, priced, repricing, hasPort, stablePort],
+  );
 }

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

@@ -20,8 +20,8 @@ export const CHARGE_WINDOW_MS = 5_000;
  */
 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";
+/** What a charge runs against: the card the buyer chose, or a wallet's sheet. */
+export type ListChargeKind = "CARD" | "GOOGLE_PAY" | "APPLE_PAY";
 
 /** The controller's slice this needs. */
 interface RaisePorts {
@@ -41,7 +41,7 @@ export interface ListCharge {
   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 a card charge (with its 5-second bar) or a wallet one (straight away: its sheet is the confirmation). Only from idle. */
   start: (kind: ListChargeKind, total: string) => void;
   /** Cancelar, during the bar: nothing has been sent, and nothing will be. */
   cancel: () => void;
@@ -131,11 +131,12 @@ export function useListCharge(ports: RaisePorts): ListCharge {
     setPressedTotal(null);
   }, []);
 
-  const send = useCallback(() => {
+  const send = useCallback((wallet: boolean) => {
     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();
+    // must not let the bar's own timer charge past it. A wallet's press is not
+    // the bar's: its sheet is already open, and the block held it itself.
+    if (!wallet && !allowed.current) return cancel();
     setPhase("sending");
     const { order, cartTotal, dueCents } = latest.current;
     if (reusable(order, cartTotal, dueCents) && order) {
@@ -152,12 +153,13 @@ export function useListCharge(ports: RaisePorts): ListCharge {
   const start = useCallback(
     (next: ListChargeKind, total: string) => {
       if (phaseRef.current !== "idle") return;
-      phaseRef.current = next === "GOOGLE_PAY" ? "sending" : "counting";
+      const wallet = next !== "CARD";
+      phaseRef.current = wallet ? "sending" : "counting";
       setKind(next);
       setPressedTotal(total);
-      if (next === "GOOGLE_PAY") return send();
+      if (wallet) return send(true);
       setPhase("counting");
-      timer.current = setTimeout(send, CHARGE_WINDOW_MS);
+      timer.current = setTimeout(() => send(false), CHARGE_WINDOW_MS);
     },
     [send],
   );

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

@@ -3,10 +3,12 @@ import { useCallback, useEffect, useMemo, useRef, useState, type Dispatch, type
 import { NEW_CARD, type CardDetails, type CardFieldErrors, type SavedCard } from "../../../card";
 import { useSavedCardList } from "../card-sources";
 import { useCheckoutCopy } from "../copy-context";
-import type { BuyerInfo, CheckoutCustomerField, CheckoutProviderConfig } from "../types";
+import type { BuyerInfo, CheckoutCustomerField, CheckoutProviderConfig, PaymentMethod } from "../types";
 
 import { askedFields, cardComplete, lastUsedCard, onlineRows, preselection, raisedMethod, type OnlineCapability, type OnlineRow } from "./choice";
+import { isTaxId, topCpfField } from "./top-cpf";
 import type { CheckoutListChoice } from "./types";
+import type { ListWallet } from "./use-capability";
 
 const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
 
@@ -31,8 +33,15 @@ export interface ListState {
   choice: CheckoutListChoice | null;
   choose: (next: CheckoutListChoice) => void;
   card: ListCard;
-  /** The buyer's own details the chosen online option must ask for (M11). */
+  /**
+   * The buyer's own details the chosen online option asks for INSIDE its row
+   * (M11) — the hand-off provider's mobile (K4). Never the CPF: that is `top`.
+   */
   asked: CheckoutCustomerField[];
+  /** The CPF asked at the top of Pagamento, or `null` (FUT-3685, E1/E2). */
+  top: CheckoutCustomerField | null;
+  /** Every online method the list offers, wallets included — what the top CPF is decided over (R2). */
+  methods: PaymentMethod[];
 }
 
 /**
@@ -100,6 +109,10 @@ export function useListState(input: {
   /** The buyer's last online method, from the host (FUT-3611). */
   lastMethod?: "PIX" | "CARD" | null;
   onChoiceChange?: (choice: CheckoutListChoice | null) => void;
+  /** The wallets the block above the list draws — each raises a CARD order. */
+  wallets?: readonly ListWallet[];
+  /** "Alterar" on the payer line revealed the CPF at the top (E2 → E1). */
+  revealed?: boolean;
 }): ListState {
   const { capability } = input;
   const rows = useMemo(() => onlineRows(capability), [capability]);
@@ -147,9 +160,29 @@ export function useListState(input: {
             method: raisedMethod(choice.method, capability.offered),
             arrivedWith: input.arrivedWith,
             taxIdOnFile: input.taxIdOnFile,
-          })
+          }).filter((field) => !isTaxId(field))
         : [],
     [choice, input.config, capability.offered, input.arrivedWith, input.taxIdOnFile],
   );
-  return { rows, choice, choose, card, asked };
+  const methods = useMemo(() => offeredOnline(rows, capability.offered, input.wallets ?? []), [rows, capability.offered, input.wallets]);
+  const top = useMemo(
+    () =>
+      topCpfField({
+        chain: input.config?.chain,
+        methods,
+        arrivedWith: input.arrivedWith,
+        taxIdOnFile: input.taxIdOnFile,
+        revealed: input.revealed ?? false,
+      }),
+    [input.config, methods, input.arrivedWith, input.taxIdOnFile, input.revealed],
+  );
+  return { rows, choice, choose, card, asked, top, methods };
+}
+
+/** The chain methods the list's rows and wallets would raise, each once. */
+function offeredOnline(rows: readonly OnlineRow[], offered: PaymentMethod[] | null, wallets: readonly ListWallet[]): PaymentMethod[] {
+  const methods = new Set<PaymentMethod>();
+  for (const row of rows) if (!row.disabled) methods.add(raisedMethod(row.method, offered));
+  if (wallets.length > 0) methods.add("CARD");
+  return [...methods];
 }