@12-apps/payments-frontend 3.5.0 → 3.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "type": "module",
   "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.",
   "exports": {
@@ -17,7 +17,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.13.0",
+    "@12-apps/payments-backend": "^4.15.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {
@@ -28,8 +28,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.21.0",
-    "@12-apps/typescript-config": "^1.20.0",
+    "@12-apps/eslint-config": "^1.21.1",
+    "@12-apps/typescript-config": "^1.20.1",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@mui/material": "^6.5.0",

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

@@ -7,13 +7,17 @@ import { ArrowBackIcon } from "./icons";
 import { PaymentStatus } from "./payment-status";
 import type { BuyerInfo, CheckoutProviderConfig, SettlementCheckout } from "./types";
 import { CheckoutComponentsProvider, useCheckoutComponents, type CheckoutComponents } from "./ui";
+import type { CheckoutViewCopy } from "./view-copy";
 import { useCheckoutController, type CheckoutHostPorts } from "./use-checkout-controller";
 
-const STEPPER_STEPS = [
-  { id: "dados", label: "Dados" },
-  { id: "payment", label: "Pagamento" },
-  { id: "status", label: "Confirmação" },
-];
+/** Step ids are the flow's own contract; the labels beside them are host copy. */
+function stepperSteps(copy: CheckoutViewCopy): { id: string; label: string }[] {
+  return [
+    { id: "dados", label: copy.steps.dados },
+    { id: "payment", label: copy.steps.payment },
+    { id: "status", label: copy.steps.status },
+  ];
+}
 
 /** What the flow reads off the host's cart — display facts, never money math. */
 export interface CheckoutCartView {
@@ -35,6 +39,14 @@ export interface CheckoutCartView {
  * pixels render through the slot contract (`components`, see `ui.tsx`).
  */
 export interface CheckoutFlowProps extends CheckoutHostPorts {
+  /**
+   * Every sentence the flow's own chrome renders — stepper labels, the Dados
+   * step, the empty cart, the confirmation screen. REQUIRED, with no default:
+   * a pt-BR host passes `PT_BR_CHECKOUT_VIEW_COPY` from the package root by
+   * hand, so choosing Portuguese is a line in the host's diff, never a
+   * silence (FUT-760's doctrine, finally applied to the legacy flow too).
+   */
+  copy: CheckoutViewCopy;
   /** The host's cart, reduced to what the flow displays. */
   cart: CheckoutCartView;
   defaultBuyer?: BuyerInfo;
@@ -97,23 +109,23 @@ function statusTotalLabel(
  * per-line remove. Offering it here put a destructive control next to the form
  * a buyer is filling in, one tap away from the field they are typing into.
  */
-function CheckoutHeader({ step, onBack }: { step: string; onBack: () => void }): JSX.Element {
+function CheckoutHeader({ copy, step, onBack }: { copy: CheckoutViewCopy; step: string; onBack: () => void }): JSX.Element {
   const { Button } = useCheckoutComponents();
   return (
     <Box sx={{ minHeight: 36, display: "flex", alignItems: "center", gap: 1 }}>
       <Button variant="text" color="neutral" size="sm" icon={<ArrowBackIcon fontSize="small" />} iconPosition="left" onClick={onBack} dataTestId="checkout-back">
-        {step === "dados" ? "Continuar comprando" : "Voltar"}
+        {step === "dados" ? copy.dados.keepShopping : copy.dados.back}
       </Button>
     </Box>
   );
 }
 
 /** Compact 50px progress header so the form stays above the fold on mobile. */
-function ProgressHeader({ step, completed }: { step: string; completed: Set<string> }): JSX.Element {
+function ProgressHeader({ copy, step, completed }: { copy: CheckoutViewCopy; step: string; completed: Set<string> }): JSX.Element {
   const { Stepper } = useCheckoutComponents();
   return (
     <Box sx={{ height: 50, display: "flex", flexDirection: "column", justifyContent: "center" }}>
-      <Stepper steps={STEPPER_STEPS} activeId={step} completed={completed} orientation="horizontal" size="sm" data-testid="checkout-stepper" />
+      <Stepper steps={stepperSteps(copy)} activeId={step} completed={completed} orientation="horizontal" size="sm" data-testid="checkout-stepper" />
     </Box>
   );
 }
@@ -124,8 +136,37 @@ function ProgressHeader({ step, completed }: { step: string; completed: Set<stri
  * chrome (reduced to {@link CheckoutCartView} here), and the provider SDK +
  * card public key are loaded lazily by the card path (order-scoped REST).
  */
+/** Step 3, with the controller's facts mapped onto the status screen. */
+function StatusStep({
+  copy,
+  c,
+  settlement,
+  cart,
+  confirmationExtra,
+}: {
+  copy: CheckoutViewCopy;
+  c: ReturnType<typeof useCheckoutController>;
+  settlement: SettlementCheckout | null | undefined;
+  cart: CheckoutCartView;
+  confirmationExtra: ReactNode;
+}): JSX.Element {
+  return (
+    <PaymentStatus
+      copy={copy.status}
+      status={c.finalStatus}
+      totalLabel={statusTotalLabel(c.order, settlement, cart)}
+      {...confirmationFacts(c.order, c.buyer)}
+      onRetry={c.retry}
+      onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
+      onBackToMenu={c.goToMenu}
+      paidExtra={confirmationExtra}
+      awaitingTimedOut={c.resumeTimedOut}
+    />
+  );
+}
+
 function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
-  const { cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, validateApplePayMerchant, ...ports } = props;
+  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, validateApplePayMerchant, ...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
@@ -141,17 +182,18 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
   // method picker. It holds until an order exists — once one does, its lines are
   // snapshotted server-side and the cart no longer speaks for it.
   if (!settlement && cart.empty && !c.order && c.step !== "status") {
-    return <EmptyCart onBack={c.goToMenu} />;
+    return <EmptyCart copy={copy.emptyCart} onBack={c.goToMenu} />;
   }
 
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: { xs: 2, sm: 3 } }}>
-      <CheckoutHeader step={c.step} onBack={c.back} />
+      <CheckoutHeader copy={copy} step={c.step} onBack={c.back} />
 
-      <ProgressHeader step={c.step} completed={c.completed} />
+      <ProgressHeader copy={copy} step={c.step} completed={c.completed} />
 
       {c.step === "dados" ? (
         <DadosStep
+          copy={copy.dados}
           buyer={c.buyer}
           onBuyerChange={c.setBuyer}
           saveProfile={c.saveProfile}
@@ -189,16 +231,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
       ) : null}
 
       {c.step === "status" ? (
-        <PaymentStatus
-          status={c.finalStatus}
-          totalLabel={statusTotalLabel(c.order, settlement, cart)}
-          {...confirmationFacts(c.order, c.buyer)}
-          onRetry={c.retry}
-          onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
-          onBackToMenu={c.goToMenu}
-          paidExtra={confirmationExtra}
-          awaitingTimedOut={c.resumeTimedOut}
-        />
+        <StatusStep copy={copy} c={c} settlement={settlement} cart={cart} confirmationExtra={confirmationExtra} />
       ) : null}
     </Box>
   );

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

@@ -3,12 +3,7 @@ import { useEffect, useRef, type JSX, type ReactNode } from "react";
 
 import { BuyerInfoForm } from "./buyer-info-form";
 import { LockOutlinedIcon } from "./icons";
-import {
-  cardPathAvailable,
-  offeredMethods,
-  selectableMethods,
-  usePreselectSoleMethod,
-} from "./method-capability";
+import { useMethodChoice } from "./method-choice";
 import { MethodPicker } from "./method-picker";
 import { PaymentErrorPanel } from "./payment-error-panel";
 import { PayerSummary } from "./payer-summary";
@@ -22,6 +17,7 @@ import type {
   OrderStatus,
   PaymentMethod,
 } from "./types";
+import type { DadosStepCopy, EmptyCartCopy } from "./view-copy";
 import { useCheckoutComponents } from "./ui";
 
 /**
@@ -42,8 +38,8 @@ function useAutoRaiseOrder(
       requestedFor.current = null;
       return;
     }
-    // No method chosen yet ⇒ show only the picker; raise the order once the
-    // buyer selects PIX or card.
+    // No method chosen yet ⇒ show only the picker (or, for a hand-off store,
+    // its "Seguir para o pagamento"); raise the order once the buyer commits.
     if (!method || creating || createError || requestedFor.current === method) return;
     requestedFor.current = method;
     onGenerate(method);
@@ -70,6 +66,8 @@ function PaymentBody({
   method,
   tenantSlug,
   onResolved,
+  onStart,
+  creating,
   pollIntervalMs,
   validateApplePayMerchant,
 }: {
@@ -79,6 +77,9 @@ function PaymentBody({
   method: PaymentMethod | null;
   tenantSlug?: string;
   onResolved: (status: OrderStatus) => void;
+  /** Set only when the shell hid its picker — see {@link PaymentStep}. */
+  onStart?: () => void;
+  creating: boolean;
   pollIntervalMs?: number;
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
 }): JSX.Element | null {
@@ -91,6 +92,8 @@ function PaymentBody({
       method={method}
       tenantSlug={tenantSlug}
       onResolved={onResolved}
+      onStart={onStart}
+      creating={creating}
       pollIntervalMs={pollIntervalMs}
       validateApplePayMerchant={validateApplePayMerchant}
     />
@@ -98,15 +101,15 @@ function PaymentBody({
 }
 
 /** Empty-cart state shown when there's nothing to check out. */
-export function EmptyCart({ onBack }: { onBack: () => void }): JSX.Element {
+export function EmptyCart({ copy, onBack }: { copy: EmptyCartCopy; onBack: () => void }): JSX.Element {
   const { Button, Text } = useCheckoutComponents();
   return (
     <Box data-testid="checkout-empty" sx={{ py: 8, textAlign: "center", display: "flex", flexDirection: "column", gap: 2, alignItems: "center" }}>
       <Text variant="heading" size="md" as="p">
-        Seu carrinho está vazio.
+        {copy.title}
       </Text>
       <Button variant="solid" color="primary" size="md" onClick={onBack} dataTestId="checkout-empty-back">
-        Ver cardápio
+        {copy.action}
       </Button>
     </Box>
   );
@@ -156,6 +159,7 @@ function PayBarTotal({
  * — no charge yet.
  */
 export function DadosStep({
+  copy,
   buyer,
   onBuyerChange,
   saveProfile,
@@ -168,6 +172,8 @@ export function DadosStep({
   discountLines,
   totalOverride,
 }: {
+  /** The step's own sentences — the HOST's words (see `./view-copy`). */
+  copy: DadosStepCopy;
   buyer: BuyerInfo;
   onBuyerChange: (buyer: BuyerInfo) => void;
   saveProfile: boolean;
@@ -204,12 +210,13 @@ export function DadosStep({
         <Checkbox
           checked={saveProfile}
           onChange={(_event, checked) => onSaveProfileChange(checked)}
-          label="Salvar meus dados para a próxima compra"
+          label={copy.saveProfile}
           data-testid="buyer-save-profile"
         />
       </Box>
 
       <DadosPayBar
+        copy={copy}
         totalLabel={totalLabel}
         totalItems={totalItems}
         createError={createError}
@@ -225,12 +232,14 @@ export function DadosStep({
 
 /** The sticky "Continuar" bar: the refusal, the money, and the one action. */
 function DadosPayBar({
+  copy,
   totalLabel,
   totalItems,
   createError,
   onContinue,
   children,
 }: {
+  copy: DadosStepCopy;
   totalLabel: string;
   totalItems: number;
   createError: string | null;
@@ -242,20 +251,22 @@ function DadosPayBar({
     <ActionBar dataTestId="checkout-pay-bar">
       <Box sx={{ width: "100%", display: "flex", flexDirection: "column", gap: 1.5 }}>
         {createError ? (
-          <Alert variant="danger" title="Não foi possível continuar" description={createError} showIcon data-testid="checkout-error" />
+          <Alert variant="danger" title={copy.cannotContinueTitle} description={createError} showIcon data-testid="checkout-error" />
         ) : null}
         <Box sx={{ display: "flex", alignItems: "center", gap: 2 }}>
           <PayBarTotal totalLabel={totalLabel} totalItems={totalItems}>{children}</PayBarTotal>
           <Box sx={{ flex: 1, display: "flex", flexDirection: "column", alignItems: "flex-end", gap: 0.5, minWidth: 0 }}>
             <Button variant="solid" color="primary" size="lg" fullWidth onClick={onContinue} dataTestId="checkout-continue">
-              Continuar
+              {copy.continueAction}
             </Button>
-            <Box sx={{ display: "flex", alignItems: "center", gap: 0.5, color: "text.secondary" }}>
-              <LockOutlinedIcon sx={{ fontSize: 13 }} />
-              <Text variant="caption" size="xs" color="secondary" as="span">
-                Pagamento seguro
-              </Text>
-            </Box>
+            {copy.secureNotice ? (
+              <Box sx={{ display: "flex", alignItems: "center", gap: 0.5, color: "text.secondary" }}>
+                <LockOutlinedIcon sx={{ fontSize: 13 }} />
+                <Text variant="caption" size="xs" color="secondary" as="span">
+                  {copy.secureNotice}
+                </Text>
+              </Box>
+            ) : null}
           </Box>
         </Box>
       </Box>
@@ -303,6 +314,17 @@ interface PaymentStepProps {
  * Step 2 "Pagamento" — pick PIX or card and pay on the SAME page. Selecting a
  * method auto-raises its order and reveals its UI (PIX QR / card form) with no
  * intermediate tap; switching method clears the previous order (controller).
+ *
+ * ## Unless the choice is not ours to ask
+ *
+ * A store that finishes checkout on the provider's own page gets NO picker
+ * here (`methodChosenAtProvider`). Its screen renders a single "Seguir para o
+ * pagamento" instead, and pressing it selects the store's hand-off method —
+ * which is the same event a tile press is, so the auto-raise, the error panel
+ * and the retry below all keep working unchanged. Preselection is suppressed
+ * for the same flow, and deliberately: it exists to spare a buyer a tap that
+ * buys them nothing, but here the tap is the buyer's consent to LEAVE, and
+ * taking it for them would redirect a checkout the moment it rendered.
  */
 export function PaymentStep({
   method,
@@ -323,35 +345,42 @@ export function PaymentStep({
   onResolved,
 }: PaymentStepProps): JSX.Element {
   const { LoadingState } = useCheckoutComponents();
-  const cardUnavailable = !cardPathAvailable(providerConfig ?? null);
-  const offered = offeredMethods(providerConfig ?? null);
+  const config = providerConfig ?? null;
+  const choice = useMethodChoice(config, method, onMethodChange);
   useAutoRaiseOrder(order, method, creating, createError, onGenerate);
-  usePreselectSoleMethod(selectableMethods(offered, cardUnavailable), method, onMethodChange);
 
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
       {/* Self-hiding: renders only for a flow whose Dados step was skipped. */}
       <PayerSummary name={buyer.name} taxId={buyer.taxId} onEdit={onEditBuyer} />
 
-      <MethodPicker
-        value={method}
-        onChange={onMethodChange}
-        cardUnavailable={cardUnavailable}
-        offered={offered}
-      />
+      {choice.atProvider ? null : (
+        <MethodPicker
+          value={method}
+          onChange={onMethodChange}
+          cardUnavailable={choice.cardUnavailable}
+          offered={choice.offered}
+        />
+      )}
 
       <PaymentBody
         order={order}
         buyer={buyer}
-        providerConfig={providerConfig ?? null}
+        providerConfig={config}
         method={method}
         tenantSlug={tenantSlug}
         onResolved={onResolved}
+        onStart={choice.onStart}
+        creating={creating}
         pollIntervalMs={pollIntervalMs}
         validateApplePayMerchant={validateApplePayMerchant}
       />
 
-      {!order && creating ? (
+      {/* The shell's own busy spinner, SUPPRESSED for a hand-off screen: that
+          screen renders its own "Preparando o pagamento" while the charge is
+          raised, and two stacked spinners saying the same thing is what the
+          buyer actually saw. */}
+      {!order && creating && !choice.atProvider ? (
         <LoadingState variant="spinner" size="md" message="Gerando pagamento…" dataTestId="payment-generating" />
       ) : null}
 

package/src/components/checkout/method-capability.ts

@@ -216,6 +216,33 @@ export function selectableMethods(
   );
 }
 
+/**
+ * The method a HAND-OFF checkout raises on the buyer's behalf, when the buyer
+ * was never asked (see `providers/registry.ts`'s `methodChosenAtProvider`).
+ *
+ * A charge still has to be raised with SOME method — that is the wire's shape,
+ * and the link is minted by raising it — but for a hand-off store the value is
+ * provisional by construction: the buyer picks for real on the provider's page,
+ * and the settlement reports back which one they actually used. So the choice
+ * here is about which request the SERVER will honour, not about what the buyer
+ * gets.
+ *
+ * PIX when the chain offers it, because PIX is the one method whose first
+ * charge is always raised immediately: a CARD request at a store that can
+ * tokenize somewhere in its chain is answered with the bare order instead, and
+ * there is no hand-off link on that answer to send anyone anywhere. Otherwise
+ * the chain's first declared method, since a store that cannot PIX would have
+ * the walk refuse a PIX charge outright.
+ *
+ * `null` offered — still loading, or a fetch blip — cannot reach here: the
+ * picker is only hidden for a store whose config already said it hands over.
+ * PIX is the safe reading of it anyway, for the reason above.
+ */
+export function handOffMethod(offered: PaymentMethod[] | null): PaymentMethod {
+  if (!offered || offered.includes("PIX")) return "PIX";
+  return offered[0] ?? "PIX";
+}
+
 /**
  * A SOLE remaining method is not a choice — take it (FUT-697 review, widened by
  * FUT-741).

package/src/components/checkout/method-choice.ts

@@ -0,0 +1,64 @@
+/**
+ * WHO asks the buyer PIX-or-card, and what the Pagamento step does about it.
+ *
+ * Its own module because the answer is a set of derived facts that must move
+ * together: a picker rendered for a store that hands the buyer over, or a
+ * hand-off CTA rendered beside a picker, are both a checkout asking one
+ * question twice — which is the defect this seam exists to make impossible.
+ */
+import {
+  cardPathAvailable,
+  handOffMethod,
+  offeredMethods,
+  selectableMethods,
+  usePreselectSoleMethod,
+} from "./method-capability";
+import { methodChosenAtProvider } from "./providers/registry";
+import type { CheckoutProviderConfig, PaymentMethod } from "./types";
+
+/** What the Pagamento step needs to know about WHO asks the buyer for a method. */
+interface MethodChoice {
+  /** The store's active provider has no card path in this browser. */
+  cardUnavailable: boolean;
+  /** The methods the chain declares it can charge, or `null` while unknown. */
+  offered: PaymentMethod[] | null;
+  /** The choice is made on the provider's page ⇒ render no picker here. */
+  atProvider: boolean;
+  /**
+   * The hand-off screen's "start paying" port, or `undefined` when the picker
+   * is on the page and owns that job instead. It SELECTS the store's hand-off
+   * method, which is the same event a tile press is — so the auto-raise, the
+   * error panel and its retry all keep working with no second code path.
+   */
+  onStart?: () => void;
+}
+
+/**
+ * Resolve who asks the buyer PIX-or-card, and preselect a sole method when the
+ * question is ours to ask.
+ */
+export function useMethodChoice(
+  config: CheckoutProviderConfig | null,
+  method: PaymentMethod | null,
+  onMethodChange: (method: PaymentMethod) => void,
+): MethodChoice {
+  const cardUnavailable = !cardPathAvailable(config);
+  const offered = offeredMethods(config);
+  const atProvider = methodChosenAtProvider(config?.chain?.[0]?.checkoutScreen, config);
+  // Nothing to preselect when the screen owns the choice: the whole point of
+  // its button is that the buyer presses it. Preselection exists to spare them
+  // a tap that buys them nothing, and here the tap is their consent to LEAVE —
+  // taking it for them would redirect a checkout the moment it rendered.
+  usePreselectSoleMethod(
+    atProvider ? [] : selectableMethods(offered, cardUnavailable),
+    method,
+    onMethodChange,
+  );
+  if (!atProvider) return { cardUnavailable, offered, atProvider };
+  return {
+    cardUnavailable,
+    offered,
+    atProvider,
+    onStart: () => onMethodChange(handOffMethod(offered)),
+  };
+}