@12-apps/payments-frontend 3.43.1 → 3.45.0

package/src/components/checkout/list/wallet-block.tsx

@@ -0,0 +1,235 @@
+import { Box, Divider } from "@mui/material";
+import { useTheme, type Theme } from "@mui/material/styles";
+import { useEffect, useId, useRef, type JSX } from "react";
+
+import { ChargeFailure } from "../card-view";
+import { useCheckoutCopy } from "../copy-context";
+import { UNRESOLVED_CODE } from "../failure-codes";
+import type { GooglePaymentsClient } from "../google-pay-button";
+import { useCheckoutComponents } from "../ui";
+
+import type { ListChargeFailure } from "./charge-runners";
+import { GroupHeading } from "./option-row";
+import type { PaymentListCopy } from "./types";
+import type { ListCapability, ListWallet } from "./use-capability";
+
+/** The prototype's 44px wallet button (L3), on the theme's spacing scale. */
+const WALLET_HEIGHT = 5.5;
+
+/** Why the buttons are held, as each button carries it: disabled, and described by the reason. */
+interface Held {
+  /** The reason's element id, or `null` when nothing holds them. */
+  describedBy: string | null;
+}
+
+/**
+ * The pill's edge: none on a light page (the black pill is its own edge); a
+ * hairline at night, where black on a dark surface has none; and a visible
+ * one while held, when the pill is dimmed (FUT-3685 review).
+ */
+const pillEdge = (held: boolean) => (t: Theme): string => {
+  if (held) return `1px solid ${t.palette.text.secondary}`;
+  return t.palette.mode === "dark" ? `1px solid ${t.palette.divider}` : "1px solid transparent";
+};
+
+/**
+ * The look every wallet pill shares — the prototype's 44px black pill (L3).
+ * The edge is an OUTLINE drawn just inside the pill: it paints over Google's
+ * own element and moves nothing, so both pills keep one size and their labels
+ * one baseline.
+ */
+const pill = (held: boolean) => ({
+  height: (t: Theme) => t.spacing(WALLET_HEIGHT),
+  width: "100%",
+  border: 0,
+  outline: pillEdge(held),
+  outlineOffset: "-1px",
+  borderRadius: (t: Theme) => t.spacing(WALLET_HEIGHT / 2),
+  overflow: "hidden",
+} as const);
+
+/**
+ * Google Pay's own button (FUT-471's brand rule: the buyer presses Google's
+ * button, drawn by `createButton`, never a look-alike) — black, "pay", a pill.
+ * Its press opens the sheet SYNCHRONOUSLY, inside the tap, through `onPress`.
+ * Held, Google's element is marked disabled and described by the reason —
+ * it stays in the accessibility tree — and a press does nothing.
+ */
+function GoogleWalletButton({ client, onPress, held }: { client: GooglePaymentsClient; onPress: () => void; held: Held }): JSX.Element {
+  const mount = useRef<HTMLDivElement | null>(null);
+  const latest = useRef(onPress);
+  latest.current = onPress;
+  const locale = useCheckoutCopy().screens.wallet.googlePay.buttonLocale;
+  const theme = useTheme();
+  // Google's own parameter, in CSS pixels: half the button's height is a pill.
+  const radius = Number.parseFloat(theme.spacing(WALLET_HEIGHT / 2));
+  useEffect(() => {
+    const element = mount.current;
+    if (!element) return undefined;
+    element.replaceChildren(
+      client.createButton({
+        onClick: () => latest.current(),
+        buttonSizeMode: "fill",
+        buttonLocale: locale,
+        buttonColor: "black",
+        buttonType: "pay",
+        buttonRadius: radius,
+      }),
+    );
+    return () => element.replaceChildren();
+  }, [client, locale, radius]);
+  useEffect(() => {
+    const button = mount.current?.querySelector("button");
+    if (!button) return;
+    if (held.describedBy) {
+      button.setAttribute("aria-disabled", "true");
+      button.setAttribute("aria-describedby", held.describedBy);
+    } else {
+      button.removeAttribute("aria-disabled");
+      button.removeAttribute("aria-describedby");
+    }
+  });
+  const isHeld = held.describedBy !== null;
+  return (
+    <Box
+      ref={mount}
+      data-testid="list-google-pay"
+      data-held={isHeld ? "true" : undefined}
+      sx={{ ...pill(isHeld), pointerEvents: isHeld ? "none" : undefined, "& > *": { width: "100%", height: "100%" } }}
+    />
+  );
+}
+
+/**
+ * Apple's button: the `-apple-pay-button` appearance Safari draws in the
+ * buyer's own language (Apple's Human Interface Guidelines), black, "pay".
+ * Only a browser that has an `ApplePaySession` ever renders it; one that does
+ * not know the appearance (a test browser with a stubbed session) gets the
+ * accessible name drawn as text on the same black pill instead.
+ */
+function AppleWalletButton({ label, onPress, held }: { label: string; onPress: () => void; held: Held }): JSX.Element {
+  const isHeld = held.describedBy !== null;
+  return (
+    <Box
+      component="button"
+      type="button"
+      aria-label={label}
+      disabled={isHeld}
+      aria-describedby={held.describedBy ?? undefined}
+      onClick={onPress}
+      data-testid="list-apple-pay"
+      sx={{
+        WebkitAppearance: "-apple-pay-button",
+        "-apple-pay-button-type": "pay",
+        "-apple-pay-button-style": "black",
+        ...pill(isHeld),
+        cursor: isHeld ? "default" : "pointer",
+        bgcolor: "common.black",
+        color: "common.white",
+        typography: "body1",
+        fontWeight: 600,
+        "&:focus-visible": { outline: (t) => `${t.spacing(0.25)} solid ${t.palette.primary.main}`, outlineOffset: (t) => t.spacing(0.25) },
+        "@supports (-webkit-appearance: -apple-pay-button)": { "& > span": { display: "none" } },
+      }}
+    >
+      <span aria-hidden>{label}</span>
+    </Box>
+  );
+}
+
+/** One wallet's button, or a held pill while the host re-prices it. */
+function WalletButton({ wallet, cap, copy, onGoogle, onApple, held }: {
+  wallet: ListWallet;
+  cap: ListCapability;
+  copy: PaymentListCopy;
+  onGoogle: () => void;
+  onApple: () => void;
+  held: Held;
+}): JSX.Element {
+  if (wallet === "GOOGLE_PAY" && cap.googlePay) return <GoogleWalletButton client={cap.googlePay.client} onPress={onGoogle} held={held} />;
+  if (wallet === "APPLE_PAY") return <AppleWalletButton label={copy.wallets.applePay} onPress={onApple} held={held} />;
+  // Google while the host re-prices: no sheet can open, so no Google button either — a plain held pill.
+  return <HeldWalletButton label={copy.wallets.googlePay} held={held} />;
+}
+
+/** A held wallet while the host re-prices: the pill, disabled, named, described by the reason. */
+function HeldWalletButton({ label, held }: { label: string; held: Held }): JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      disabled
+      aria-describedby={held.describedBy ?? undefined}
+      data-testid="list-wallet-held"
+      sx={{ ...pill(true), bgcolor: "common.black", color: "common.white", typography: "body1", fontWeight: 600 }}
+    >
+      {label}
+    </Box>
+  );
+}
+
+/**
+ * "PAGAMENTO RÁPIDO" (FUT-3685, C5, C6, E4, E5, L3, L5): the ready wallets'
+ * buttons above the list, then "ou escolha como pagar". Nothing at all — no
+ * heading, no buttons, no divider — when no wallet is ready (E4); one wallet
+ * takes the full width (E5); two sit side by side from the theme's `sm`
+ * (L5) and stack below it (L3).
+ *
+ * The buttons are not part of the list's radio group (R1): pressing one opens
+ * its sheet and never changes the chosen row. `held` is why they cannot act
+ * yet — the CPF the provider needs (E3), the host re-pricing — said under them.
+ */
+export function WalletBlock({ cap, copy, held, failure, onGoogle, onApple }: {
+  cap: ListCapability;
+  copy: PaymentListCopy;
+  held: string | null;
+  /** The last wallet charge's refusal; an UNRESOLVED one removes the buttons (FUT-563). */
+  failure: ListChargeFailure | null;
+  onGoogle: () => void;
+  onApple: () => void;
+}): JSX.Element | null {
+  const { Text } = useCheckoutComponents();
+  const id = useId();
+  const reasonId = `${id}-held`;
+  if (cap.wallets.length === 0) return null;
+  const two = cap.wallets.length > 1;
+  const unresolved = failure?.code === UNRESOLVED_CODE;
+  return (
+    <Box data-testid="list-wallets" sx={{ display: "flex", flexDirection: "column", gap: 1.25 }}>
+      <Box role="group" aria-labelledby={id} sx={{ display: "flex", flexDirection: "column", gap: 1.25 }}>
+        <GroupHeading id={id}>{copy.wallets.heading}</GroupHeading>
+        {unresolved ? null : (
+        <Box
+          data-testid="list-wallet-buttons"
+          data-held={held ? "true" : undefined}
+          sx={{
+            display: "grid",
+            gap: 1.25,
+            gridTemplateColumns: { xs: "minmax(0, 1fr)", sm: two ? "repeat(2, minmax(0, 1fr))" : "minmax(0, 1fr)" },
+            opacity: (t) => (held ? t.palette.action.disabledOpacity : 1),
+          }}
+        >
+          {cap.wallets.map((wallet) => (
+            <WalletButton key={wallet} wallet={wallet} cap={cap} copy={copy} onGoogle={onGoogle} onApple={onApple} held={{ describedBy: held ? reasonId : null }} />
+          ))}
+        </Box>
+        )}
+        {held ? (
+          // The Text slot takes no id; the reason's own box carries the one the buttons point at.
+          <Box id={reasonId} data-testid="list-wallets-held">
+            <Text variant="body" size="sm" color="secondary" as="p" style={{ margin: 0 }}>
+              {held}
+            </Text>
+          </Box>
+        ) : null}
+        {failure ? <ChargeFailure message={failure.message} unresolved={unresolved} /> : null}
+      </Box>
+      <Divider data-testid="list-wallets-or">
+        {/* The body style the hints use: a caption tone fell under 4.5:1 on the surface. */}
+        <Text variant="body" size="xs" color="secondary" as="span">
+          {copy.wallets.or}
+        </Text>
+      </Divider>
+    </Box>
+  );
+}

package/src/components/checkout/list/wallet-press.ts

@@ -0,0 +1,129 @@
+/**
+ * A wallet button's press (FUT-3685, C5, C6): the wallet's sheet opens HERE,
+ * synchronously, inside the buyer's tap — the browser opens Google's sheet and
+ * Safari starts an Apple Pay session only from inside one — priced at the
+ * host's amount DUE (`totalCents`, K3). The order is raised in parallel by the
+ * list's charge, and the runner charges the sheet's key only against an order
+ * that asks the provider for the same amount (R4).
+ */
+import { useEffect, type MutableRefObject } from "react";
+
+import { startApplePaySession } from "../apple-pay-button";
+import { useCheckoutCopy } from "../copy-context";
+import { paymentDataRequest, sheetDismissed } from "../google-pay-button";
+
+import type { ListChargeFailure, WalletSheet } from "./charge-runners";
+import type { ListCapability } from "./use-capability";
+import type { ListCharge } from "./use-list-charge";
+
+/** What a press needs from the list face. */
+export interface WalletPressInput {
+  cap: ListCapability;
+  charge: ListCharge;
+  /** The host's amount due, in cents — what the sheet shows. */
+  cents: number | undefined;
+  /** The amount the bar names for an online payment, frozen at the press. */
+  total: string;
+  /** Something stops a press: a reason the block shows, or a charge already under way. */
+  blocked: boolean;
+  /** Before the sheet opens: clear the last refusal, keep the asked details. */
+  before: () => void;
+  /** A sheet that could not open, in the wallet's own words. */
+  onFailed: (failure: ListChargeFailure) => void;
+  /**
+   * Set synchronously by a press, cleared when the charge is back to idle: a
+   * second tap before React re-renders (a double tap) opens no second sheet.
+   */
+  pressed: MutableRefObject<boolean>;
+}
+
+/**
+ * Open a wallet's sheet, synchronously. A sheet that throws instead — Safari's
+ * `InvalidAccessError` for a session it will not begin, a pay.js that throws
+ * outright — starts no charge, so nothing would ever clear the press guard:
+ * both buttons would be dead (FUT-3685 review). So the guard is released, and
+ * the buyer is told the wallet could not start; the next press tries again.
+ */
+function openSheet<T>(input: WalletPressInput, open: () => T, cannotStart: string): T | null {
+  try {
+    return open();
+  } catch {
+    input.pressed.current = false;
+    input.onFailed({ message: cannotStart, code: null });
+    return null;
+  }
+}
+
+/** Google Pay's press: `loadPaymentData` inside the tap, then the charge. */
+export function useGooglePayPress(input: WalletPressInput, sheet: MutableRefObject<WalletSheet | null>): () => void {
+  const cannotStart = useCheckoutCopy().screens.wallet.googlePay.cannotComplete;
+  return () => {
+    const google = input.cap.googlePay;
+    const cents = input.cents;
+    if (!google || cents === undefined || input.blocked || input.pressed.current) return;
+    input.pressed.current = true;
+    input.before();
+    const loading = openSheet(input, () => google.client.loadPaymentData(paymentDataRequest(google.params, { totalCents: cents })), cannotStart);
+    if (!loading) return;
+    // A sheet that rejects later reaches the runner, which says so and settles the charge.
+    const answer = loading.then(
+      (data) => data.paymentMethodData.tokenizationData.token,
+      (error: unknown) => {
+        if (sheetDismissed(error)) return null;
+        throw error;
+      },
+    );
+    sheet.current = { type: "GOOGLE_PAY", answer, cents };
+    input.charge.start("GOOGLE_PAY", input.total);
+  };
+}
+
+/**
+ * Apple Pay's press: the session is CREATED and BEGUN synchronously, in the
+ * tap — Safari's rule — and the order is raised while the buyer looks at the
+ * sheet. A merchant validation that cannot run says why, beside the list.
+ */
+export function useApplePayPress(input: WalletPressInput, sheet: MutableRefObject<WalletSheet | null>): () => void {
+  const copy = useCheckoutCopy().screens.wallet.applePay;
+  return () => {
+    const apple = input.cap.applePay;
+    const cents = input.cents;
+    if (!apple || cents === undefined || input.blocked || input.pressed.current) return;
+    input.pressed.current = true;
+    input.before();
+    const started = openSheet(
+      input,
+      () =>
+        startApplePaySession({
+          Session: apple.Session,
+          cents,
+          copy,
+          validateMerchant: apple.validateMerchant,
+          onError: (message) => input.onFailed({ message, code: null }),
+        }),
+      copy.cannotComplete,
+    );
+    if (!started) return;
+    sheet.current = { type: "APPLE_PAY", answer: started.answer, cents, complete: started.complete };
+    input.charge.start("APPLE_PAY", input.total);
+  };
+}
+
+/**
+ * A sheet left open with nobody to charge it: the raise behind it was refused,
+ * and the list is back to its rows. Apple's sheet waits for an outcome, so it
+ * is told this one failed; nothing is charged.
+ */
+export function useCloseOrphanSheet(phase: ListCharge["phase"], sheet: MutableRefObject<WalletSheet | null>, pressed: MutableRefObject<boolean>): void {
+  useEffect(() => {
+    if (phase !== "idle") return;
+    // Back to idle: a new press may open a sheet again.
+    pressed.current = false;
+    const open = sheet.current;
+    sheet.current = null;
+    if (!open || open.claimed) return;
+    void open.answer.then((key) => {
+      if (key !== null) open.complete?.(false);
+    }, () => undefined);
+  }, [phase, sheet, pressed]);
+}

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

@@ -101,6 +101,7 @@ export function PaymentPhase({
         defaultBuyer={props.defaultBuyer}
         saveBuyerContact={props.saveBuyerContact}
         consentLabel={props.copy.dados.saveProfile}
+        validateApplePayMerchant={validateApplePayMerchant}
       />
     );
   }

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

@@ -212,7 +212,7 @@ function AddressRow({
 const DIVIDER = <Box sx={{ height: "1px", bgcolor: "divider" }} />;
 
 /** The cart's lines, "2× X-Burger … R$ 36,00", when the host passed them. */
-function SummaryLines({ lines }: { lines: CheckoutSummaryLine[] }): JSX.Element {
+export function SummaryLines({ lines }: { lines: CheckoutSummaryLine[] }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.layout;
   return (
@@ -232,7 +232,7 @@ function SummaryLines({ lines }: { lines: CheckoutSummaryLine[] }): JSX.Element
 }
 
 /** "Total" and the amount on one line, the host's money rows under it. */
-function SummaryTotal({ totalLabel, discountLines }: { totalLabel: string; discountLines?: ReactNode }): JSX.Element {
+export function SummaryTotal({ totalLabel, discountLines }: { totalLabel: string; discountLines?: ReactNode }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.layout;
   return (

package/src/components/checkout/screens-copy.ts

@@ -234,6 +234,12 @@ export interface WalletCopy {
     cannotStart: string;
     /** It started and failed. */
     cannotComplete: string;
+    /**
+     * The sheet was authorized and the payment did not go through — the
+     * amount moved, or the charge was refused (FUT-3685). Absent ⇒
+     * `cannotComplete`. Both packs carry it.
+     */
+    paymentFailed?: string;
     payAction: string;
   };
   googlePay: {

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

@@ -124,6 +124,7 @@ export const EN_US_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
       orderTotal: 'Order total',
       cannotStart: 'Could not start Apple Pay in this store. Pay by card instead.',
       cannotComplete: 'Could not start Apple Pay. Try again, or pay by card.',
+      paymentFailed: 'Could not complete the payment with Apple Pay. Try again, or pay by card.',
       payAction: 'Pay with Apple Pay',
     },
     googlePay: {

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

@@ -113,6 +113,8 @@ export const PT_BR_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
       cannotStart: 'Não foi possível iniciar o Apple Pay nesta loja. Pague com cartão.',
       cannotComplete:
         'Não foi possível iniciar o Apple Pay. Tente novamente ou pague com cartão.',
+      paymentFailed:
+        'Não foi possível concluir o pagamento com o Apple Pay. Tente novamente ou pague com cartão.',
       payAction: 'Pagar com Apple Pay',
     },
     googlePay: {

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

@@ -68,6 +68,16 @@ function buildRuntime(config: PaymentFlowsConfig): FlowsRuntime {
   };
 }
 
+/** The host's confirmation slots, as `CheckoutFlow` takes them. */
+function confirmationProps(confirmation: PaymentFlowsConfig["confirmation"]) {
+  return {
+    confirmationExtra: confirmation?.extra,
+    confirmationHero: confirmation?.hero,
+    confirmationFooter: confirmation?.footer,
+    backActionEmphasis: confirmation?.backActionEmphasis,
+  };
+}
+
 /** 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?.();
@@ -111,8 +121,7 @@ function buildCheckout(
         settlement={settlement ?? hostSettlement}
         providerConfig={config}
         tenantSlug={tenantSlug}
-        confirmationExtra={runtime.config.confirmation?.extra}
-        confirmationHero={runtime.config.confirmation?.hero}
+        {...confirmationProps(runtime.config.confirmation)}
         validateApplePayMerchant={ports.validateApplePayMerchant}
         paymentList={paymentList}
       />

package/src/flows/types.ts

@@ -20,6 +20,7 @@
  * a `tokensByProvider` key. A host never types one.
  */
 import type { CheckoutPaymentList } from "../components/checkout/list/types";
+import type { BackActionEmphasis } from "../components/checkout/payment-status-parts";
 import type { ComponentType, ReactNode } from "react";
 
 import type { SavedCard } from "../card";
@@ -153,9 +154,13 @@ export interface PaymentFlowsConfig extends CheckoutPipelineConfig {
   copy: CheckoutCopyFE;
   /**
    * Host content under the paid receipt (the storefront's PWA install invite),
-   * and the host's own illustration in place of the paid icon (`hero`).
+   * the host's own illustration in place of the paid icon (`hero`), content
+   * AFTER the confirmation's actions (`footer`), and whether the way out leads
+   * the paid screen (`backActionEmphasis`) — `CheckoutFlowProps`'
+   * `confirmationExtra`/`Hero`/`Footer` and `backActionEmphasis`, so a host on
+   * the factory composes the same confirmation as one mounting the flow.
    */
-  confirmation?: { extra?: ReactNode; hero?: ReactNode };
+  confirmation?: { extra?: ReactNode; hero?: ReactNode; footer?: ReactNode; backActionEmphasis?: BackActionEmphasis };
   /**
    * Warnings the host reports (Sentry). Default SILENT — never `console`: a
    * library that writes to a buyer's console tells them nothing and tells the

package/src/index.ts

@@ -56,7 +56,7 @@ export { PT_BR_CHECKOUT_PAYMENT_COPY } from './components/checkout-payment-pt-BR
 // ---------------------------------------------------------------------------
 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, CheckoutPixBank, PaymentListCopy, PixBankCopy, PixBankId, PixBankName } from './components/checkout/list/types';
+export type { CheckoutDoorOption, CheckoutDoorRowControls, CheckoutListChoice, CheckoutListHold, CheckoutOnlineChoice, CheckoutPaymentList, CheckoutPixBank, PaymentListCopy, PixBankCopy, PixBankId, PixBankName } 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';