@12-apps/payments-frontend 3.25.0 → 3.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.25.0",
+  "version": "3.26.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

@@ -95,6 +95,11 @@ 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 illustration that replaces the paid confirmation's icon —
+   * `PaymentStatusProps.paidHero`: pass it only when there is one, and mark it `aria-hidden`.
+   */
+  confirmationHero?: ReactNode;
   /** Host content shown AFTER the confirmation's actions — `PaymentStatusProps.paidFooter`. */
   confirmationFooter?: ReactNode;
   /** Whether the way out leads the paid screen — see {@link BackActionEmphasis}. */
@@ -185,6 +190,7 @@ function StatusStep({
   settlement,
   cart,
   confirmationExtra,
+  confirmationHero,
   confirmationFooter,
   backActionEmphasis,
 }: {
@@ -193,6 +199,7 @@ function StatusStep({
   settlement: SettlementCheckout | null | undefined;
   cart: CheckoutCartView;
   confirmationExtra: ReactNode;
+  confirmationHero: ReactNode;
   confirmationFooter: ReactNode;
   backActionEmphasis: BackActionEmphasis | undefined;
 }): JSX.Element {
@@ -206,6 +213,7 @@ function StatusStep({
       onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
       onBackToMenu={c.goToMenu}
       paidExtra={confirmationExtra}
+      paidHero={confirmationHero}
       paidFooter={confirmationFooter}
       backActionEmphasis={backActionEmphasis}
       awaitingTimedOut={c.awaitingTimedOut}
@@ -308,7 +316,7 @@ function PagamentoStep({
 }
 
 function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
-  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, confirmationFooter, backActionEmphasis, validateApplePayMerchant, oneClick = false, ...ports } = props;
+  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, confirmationHero, 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
@@ -365,7 +373,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
       ) : null}
 
       {c.step === "status" ? (
-        <StatusStep copy={copy} c={c} settlement={settlement} cart={cart} confirmationExtra={confirmationExtra} confirmationFooter={confirmationFooter} backActionEmphasis={backActionEmphasis} />
+        <StatusStep copy={copy} c={c} settlement={settlement} cart={cart} confirmationExtra={confirmationExtra} confirmationHero={confirmationHero} confirmationFooter={confirmationFooter} backActionEmphasis={backActionEmphasis} />
       ) : null}
     </Box>
   );

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

@@ -1,5 +1,5 @@
 import { Box } from "@mui/material";
-import type { JSX } from "react";
+import type { JSX, ReactNode } from "react";
 
 import { CheckCircleOutlineIcon, ErrorOutlineIcon, ScheduleIcon } from "./icons";
 import type { CheckoutDecline } from "./decline";
@@ -120,17 +120,27 @@ function failedOutcome(copy: PaymentStatusCopy, decline: CheckoutDecline | null)
   return (reason ? copy.declined?.[reason] : undefined) ?? copy.failed;
 }
 
-/** The headline block: icon, outcome, and one supporting line. */
+/**
+ * The headline block: icon, outcome, and one supporting line.
+ *
+ * `hero` replaces the PAID icon with the host's own illustration — a store's
+ * mascot celebrating the order, say — and only the icon: the heading and the
+ * support line stay the package's. Every other status keeps its icon, because
+ * a host celebrating a payment that failed would be telling the buyer the
+ * opposite of what happened.
+ */
 export function OutcomeHero({
   copy,
   status,
   wait,
   decline,
+  hero,
 }: {
   copy: PaymentStatusCopy;
   status: OrderStatus;
   wait: WaitState;
   decline: CheckoutDecline | null;
+  hero?: ReactNode;
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const face = status === "AWAITING_PAYMENT" ? awaitingFace(copy, wait) : null;
@@ -154,7 +164,13 @@ export function OutcomeHero({
       }
       sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 1, textAlign: "center" }}
     >
-      <Box sx={{ color: TONE_COLOR[visual.tone], display: "flex" }}>{visual.icon}</Box>
+      {status === "PAID" && hero ? (
+        <Box data-testid="payment-paid-hero" sx={{ display: "flex" }}>
+          {hero}
+        </Box>
+      ) : (
+        <Box sx={{ color: TONE_COLOR[visual.tone], display: "flex" }}>{visual.icon}</Box>
+      )}
       <Text variant="heading" size="md" weight="bold" as="h2">
         {outcome.heading}
       </Text>

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

@@ -56,6 +56,16 @@ interface PaymentStatusProps {
    * is the difference between an offer and an interruption.
    */
   paidExtra?: ReactNode;
+  /**
+   * Host content that REPLACES the PAID icon at the top of the screen — the
+   * storefront's mascot celebrating a buyer's first order or birthday. Absent,
+   * the screen is exactly what it was. Never shown on any other status.
+   *
+   * Pass it only when there is something to show (`cond ? <Mascot /> : undefined`):
+   * an element that renders nothing still replaces the icon. It is decorative —
+   * the heading beside it says what happened — so mark it `aria-hidden`.
+   */
+  paidHero?: ReactNode;
   /**
    * Host content rendered AFTER the action row, and ONLY on PAID.
    *
@@ -182,7 +192,13 @@ export function PaymentStatus(props: PaymentStatusProps): JSX.Element {
       data-timed-out={view.wait.timedOut ? "true" : undefined}
       sx={{ display: "flex", flexDirection: "column", gap: 3, alignItems: "stretch", py: 2 }}
     >
-      <OutcomeHero copy={copy} status={view.effective} wait={view.wait} decline={view.decline} />
+      <OutcomeHero
+        copy={copy}
+        status={view.effective}
+        wait={view.wait}
+        decline={view.decline}
+        hero={props.paidHero}
+      />
 
       {view.paid ? (
         <PaidFacts copy={copy} totalLabel={totalLabel} orderId={orderId} buyerEmail={buyerEmail} />

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

@@ -106,6 +106,7 @@ function buildCheckout(
         providerConfig={config}
         tenantSlug={tenantSlug}
         confirmationExtra={runtime.config.confirmation?.extra}
+        confirmationHero={runtime.config.confirmation?.hero}
         validateApplePayMerchant={ports.validateApplePayMerchant}
       />
     );

package/src/flows/screens-pay.tsx

@@ -93,6 +93,7 @@ function buildPaymentStatus(runtime: FlowsRuntime): CheckoutScreens["PaymentStat
           orderId={payable?.orderId}
           onBackToMenu={backToMenu}
           paidExtra={runtime.config.confirmation?.extra}
+          paidHero={runtime.config.confirmation?.hero}
         />
       </FlowsShell>
     );

package/src/flows/types.ts

@@ -144,8 +144,11 @@ export interface PaymentFlowsConfig extends CheckoutPipelineConfig {
    * makes a new host answer once, at the one call site that knows the answer.
    */
   copy: CheckoutCopyFE;
-  /** Host content under the paid receipt (the storefront's PWA install invite). */
-  confirmation?: { extra?: ReactNode };
+  /**
+   * 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`).
+   */
+  confirmation?: { extra?: ReactNode; hero?: ReactNode };
   /**
    * Warnings the host reports (Sentry). Default SILENT — never `console`: a
    * library that writes to a buyer's console tells them nothing and tells the