@12-apps/payments-frontend 3.23.0 → 3.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.23.0",
+  "version": "3.24.0",
   "type": "module",
   "sideEffects": false,
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",

package/src/components/checkout/checkout-flow.tsx

@@ -7,6 +7,7 @@ import { EmptyCart, PaymentStep } from "./checkout-steps";
 import { DadosStep } from "./dados-step";
 import { ArrowBackIcon } from "./icons";
 import { PaymentStatus } from "./payment-status";
+import type { BackActionEmphasis } from "./payment-status-parts";
 import type { BuyerInfo, CheckoutProviderConfig, SettlementCheckout } from "./types";
 import { CheckoutCopyProvider } from "./copy-context";
 import { OneClickProvider, useOneClick } from "./one-click";
@@ -94,6 +95,10 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
   /** Host content shown on the paid confirmation (the storefront's install invite). */
   confirmationExtra?: ReactNode;
+  /** Host content shown AFTER the confirmation's actions — `PaymentStatusProps.paidFooter`. */
+  confirmationFooter?: ReactNode;
+  /** Whether the way out leads the paid screen — see {@link BackActionEmphasis}. */
+  backActionEmphasis?: BackActionEmphasis;
   /** Design-system slots; unfilled slots render the raw-MUI defaults. */
   components?: Partial<CheckoutComponents>;
 }
@@ -180,12 +185,16 @@ function StatusStep({
   settlement,
   cart,
   confirmationExtra,
+  confirmationFooter,
+  backActionEmphasis,
 }: {
   copy: CheckoutViewCopy;
   c: ReturnType<typeof useCheckoutController>;
   settlement: SettlementCheckout | null | undefined;
   cart: CheckoutCartView;
   confirmationExtra: ReactNode;
+  confirmationFooter: ReactNode;
+  backActionEmphasis: BackActionEmphasis | undefined;
 }): JSX.Element {
   return (
     <PaymentStatus
@@ -197,6 +206,8 @@ function StatusStep({
       onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
       onBackToMenu={c.goToMenu}
       paidExtra={confirmationExtra}
+      paidFooter={confirmationFooter}
+      backActionEmphasis={backActionEmphasis}
       awaitingTimedOut={c.awaitingTimedOut}
       // How the wait behind this screen is going, and the way out of it
       // (FUT-1144). It is the resumed leg's wait for a checkout that came back
@@ -297,7 +308,7 @@ function PagamentoStep({
 }
 
 function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
-  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, validateApplePayMerchant, oneClick = false, ...ports } = props;
+  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, confirmationFooter, backActionEmphasis, validateApplePayMerchant, oneClick = false, ...ports } = props;
   // Resolved for NO method on purpose (FUT-595): the Dados step opens before
   // the picker, and the form is filled once — so it asks for the union of what
   // any chain member may need rather than re-opening after the choice. A chain
@@ -354,7 +365,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
       ) : null}
 
       {c.step === "status" ? (
-        <StatusStep copy={copy} c={c} settlement={settlement} cart={cart} confirmationExtra={confirmationExtra} />
+        <StatusStep copy={copy} c={c} settlement={settlement} cart={cart} confirmationExtra={confirmationExtra} confirmationFooter={confirmationFooter} backActionEmphasis={backActionEmphasis} />
       ) : null}
     </Box>
   );

package/src/components/checkout/payment-status-parts.tsx

@@ -234,6 +234,38 @@ function retryable(decline: CheckoutDecline | null): boolean {
   return decline?.retriable !== false;
 }
 
+/**
+ * How much of the eye the way out asks for on a PAID confirmation.
+ *
+ * `"primary"` is the default and the historical look: back-to-menu is the only
+ * control a settled screen carries, so it wears the solid fill. A host that
+ * renders an action of its OWN in {@link PaymentStatusProps.paidExtra} — a
+ * route to the order it just raised, say — has two controls on one screen, and
+ * only one of them may lead. `"secondary"` is how such a host says which.
+ *
+ * A prop rather than a guess, because the package cannot make it: whether the
+ * buyer's next move is "look at the pedido" or "buy something else" is a fact
+ * about the way this shop serves people, and nothing in a payment knows it.
+ * Every other status is unaffected — an unsettled screen already paints this
+ * button as the quiet way out, and the retry beside it is the lead.
+ */
+export type BackActionEmphasis = "primary" | "secondary";
+
+/**
+ * The back-to-menu button's look, from the outcome and the host's emphasis.
+ *
+ * Its own function so the two attributes cannot disagree: they moved together
+ * as a pair of inline ternaries, and a third condition would have made that
+ * four places to keep in step.
+ */
+function backLook(
+  status: OrderStatus,
+  emphasis: BackActionEmphasis,
+): { variant: "solid" | "outline"; color: "primary" | "neutral" } {
+  const leads = status === "PAID" && emphasis === "primary";
+  return leads ? { variant: "solid", color: "primary" } : { variant: "outline", color: "neutral" };
+}
+
 /** The next-action row: retry / regenerate / check-again, always back-to-menu. */
 export function StatusActions({
   copy,
@@ -244,6 +276,7 @@ export function StatusActions({
   onCheckAgain,
   onNotPaid,
   onBackToMenu,
+  backActionEmphasis = "primary",
 }: {
   copy: PaymentStatusCopy;
   status: OrderStatus;
@@ -259,8 +292,11 @@ export function StatusActions({
   /** The buyer's "I did not pay" (FUT-1146) — present only while it applies. */
   onNotPaid?: () => void;
   onBackToMenu: () => void;
+  /** Whether back-to-menu leads a PAID screen. See {@link BackActionEmphasis}. */
+  backActionEmphasis?: BackActionEmphasis;
 }): JSX.Element {
   const { Button } = useCheckoutComponents();
+  const back = backLook(status, backActionEmphasis);
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
       {onCheckAgain ? (
@@ -298,8 +334,8 @@ export function StatusActions({
       <Button
         // Full width and last, so the thumb lands on the same place in every
         // outcome instead of hunting a button that moves with the state.
-        variant={status === "PAID" ? "solid" : "outline"}
-        color={status === "PAID" ? "primary" : "neutral"}
+        variant={back.variant}
+        color={back.color}
         size="lg"
         onClick={onBackToMenu}
         dataTestId="payment-back-to-menu"

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

@@ -2,7 +2,13 @@ import { Box } from "@mui/material";
 import type { JSX, ReactNode } from "react";
 
 import type { CheckoutDecline } from "./decline";
-import { OutcomeHero, PaidFacts, StatusActions, type WaitState } from "./payment-status-parts";
+import {
+  OutcomeHero,
+  PaidFacts,
+  StatusActions,
+  type BackActionEmphasis,
+  type WaitState,
+} from "./payment-status-parts";
 import type { OrderStatus } from "./types";
 import { useCheckoutComponents } from "./ui";
 import type { PaymentStatusCopy } from "./view-copy";
@@ -50,6 +56,23 @@ interface PaymentStatusProps {
    * is the difference between an offer and an interruption.
    */
   paidExtra?: ReactNode;
+  /**
+   * Host content rendered AFTER the action row, and ONLY on PAID.
+   *
+   * The other half of {@link paidExtra}, and the difference between them is the
+   * actions. What a buyer has to DO next belongs beside the way out, in one
+   * block: a panel dropped between two controls splits the only decision on the
+   * screen in half. What is merely OFFERED — an install invite, an ask to turn
+   * on alerts — belongs after that block, because it is about everything that
+   * happens once this screen is closed and must not come between a shopper and
+   * the order they just paid for.
+   */
+  paidFooter?: ReactNode;
+  /**
+   * Whether back-to-menu leads a PAID screen (default) or stands down for an
+   * action the host renders in {@link paidExtra}. See {@link BackActionEmphasis}.
+   */
+  backActionEmphasis?: BackActionEmphasis;
   /**
    * The wait has been given up on. Only meaningful while AWAITING_PAYMENT;
    * every other status has already resolved, so a stale flag cannot change what
@@ -180,7 +203,10 @@ export function PaymentStatus(props: PaymentStatusProps): JSX.Element {
         onCheckAgain={view.checkAgain}
         onNotPaid={view.notPaid}
         onBackToMenu={onBackToMenu}
+        backActionEmphasis={props.backActionEmphasis}
       />
+
+      {view.paid ? props.paidFooter : null}
     </Box>
   );
 }

package/src/components/checkout/resolution-actions.ts

@@ -0,0 +1,43 @@
+import { useCallback, type Dispatch, type SetStateAction } from "react";
+
+import type { Step } from "./checkout-actions";
+import type { CheckoutDecline } from "./decline";
+import type { BuyerInfo, OrderStatus, PaymentMethod } from "./types";
+
+/**
+ * The two actions the payment step raises on its own: paying once an e-mail
+ * has been typed, and reporting the result the provider's screen reached.
+ *
+ * Extracted from `useCheckoutController` for the same reason `useRetryAction`
+ * and `useGoToPayment` were: the controller is the one function that has to
+ * hold every piece of checkout state at once, and each action it also spells
+ * out inline is a line it cannot spend on the state. FUT-1170 and FUT-1240
+ * together pushed it past the size gate; these two callbacks are the part that
+ * reads the same wherever it lives.
+ */
+export function useResolutionActions(input: {
+  buyer: BuyerInfo;
+  method: PaymentMethod | null;
+  startPayment: (method: PaymentMethod, buyer: BuyerInfo) => Promise<void>;
+  setBuyerState: Dispatch<SetStateAction<BuyerInfo>>;
+  setDecline: Dispatch<SetStateAction<CheckoutDecline | null>>;
+  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>;
+  setStep: Dispatch<SetStateAction<Step>>;
+}): {
+  payWithEmail: (email: string) => void;
+  handleResolved: (status: OrderStatus, refusal?: CheckoutDecline | null) => void;
+} {
+  const { buyer, method, startPayment, setBuyerState, setDecline, setFinalStatus, setStep } = input;
+  const payWithEmail = useCallback((email: string) => {
+    if (!method) return;
+    const next = { ...buyer, email };
+    setBuyerState(next);
+    void startPayment(method, next);
+  }, [buyer, method, setBuyerState, startPayment]);
+  const handleResolved = useCallback((status: OrderStatus, refusal?: CheckoutDecline | null) => {
+    setDecline(refusal ?? null);
+    setFinalStatus(status);
+    setStep("status");
+  }, [setDecline, setFinalStatus, setStep]);
+  return { payWithEmail, handleResolved };
+}

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

@@ -28,6 +28,7 @@ import type {
   OrderStatus,
   PaymentMethod,
 } from "./types";
+import { useResolutionActions } from "./resolution-actions";
 import { useHostedResume } from "./use-hosted-resume";
 
 const STEP_ORDER: Step[] = ["dados", "payment", "status"];
@@ -140,17 +141,9 @@ export function useCheckoutController(
     buyer, saveProfile, createOrder, navigate, tenantSlug, basket, failure,
     setCreating, setDecline, setOrder, setFinalStatus,
   });
-  const payWithEmail = useCallback((email: string) => {
-    if (!method) return;
-    const next = { ...buyer, email };
-    setBuyerState(next);
-    void startPayment(method, next);
-  }, [buyer, method, startPayment]);
-  const handleResolved = useCallback((s: OrderStatus, refusal?: CheckoutDecline | null) => {
-    setDecline(refusal ?? null);
-    setFinalStatus(s);
-    setStep("status");
-  }, []);
+  const { payWithEmail, handleResolved } = useResolutionActions({
+    buyer, method, startPayment, setBuyerState, setDecline, setFinalStatus, setStep,
+  });
   const retry = useRetryAction({
     decline, order, clearError, setOrder, setDecline, setFinalStatus, setStep, setFreshInstrument,
   });

package/src/index.ts

@@ -59,6 +59,7 @@ export {
   type CheckoutCartView,
   type CheckoutFlowProps,
 } from './components/checkout/checkout-flow';
+export type { BackActionEmphasis } from './components/checkout/payment-status-parts';
 
 // ---------------------------------------------------------------------------
 // The MOUNTED buyer checkout (FUT-741) and the checkout PIPELINE (FUT-1240).