@12-apps/payments-frontend 3.47.1 → 3.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.47.1",
+  "version": "3.48.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.",
@@ -23,7 +23,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.38.0",
+    "@12-apps/payments-backend": "^4.39.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/platform/HomologacaoEvidenceCard.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { Alert, Box, Button, LinearProgress, Stack, Typography } from '@mui/material';
+import { Alert, Box, Button, Stack, Typography } from '@mui/material';
 import { useState, type ReactNode } from 'react';
 
 import type {
@@ -8,6 +8,7 @@ import type {
   BrowserCardResult,
   BrowserWalletResult,
   DebitTestData,
+  EvidenceRunSection,
   EvidenceSummary,
   EvidenceWalletsConfig,
   PaymentEnvironment,
@@ -21,6 +22,7 @@ import type { GooglePayApi } from '../checkout/google-pay-button';
 import { CARD_SX, TAP_SX } from './ConnectEnvironmentCard';
 import type { PlatformHomologacaoCopy } from './copy';
 import { PlatformCopyProvider, usePlatformCopy } from './copy-context';
+import { EvidenceProgress, type EvidencePhase } from './HomologacaoEvidenceProgress';
 import { EvidenceWalletBlock, useEvidenceWallets, type EvidenceWallets } from './HomologacaoEvidenceWallets';
 
 /**
@@ -78,9 +80,15 @@ export interface HomologacaoEvidenceCardProps {
   }>;
   /**
    * Phase 2 — raise the orders with the encrypted cards and, for each wallet,
-   * the token its sheet gave (or the code saying why there is none).
+   * the token its sheet gave (or the code saying why there is none). The host
+   * calls `onSection` as the server starts each section, for the step list.
    */
-  onRun: (runId: string, cards: BrowserCardResult[], wallets: BrowserWalletResult[]) => Promise<void>;
+  onRun: (
+    runId: string,
+    cards: BrowserCardResult[],
+    wallets: BrowserWalletResult[],
+    onSection: (section: EvidenceRunSection) => void,
+  ) => Promise<void>;
   /**
    * The host's Apple Pay merchant validation (FUT-3755): exchange Apple's
    * `validationURL` for a merchant session, server-side. Absent, the Apple Pay
@@ -93,8 +101,8 @@ export interface HomologacaoEvidenceCardProps {
   onDownload: () => Promise<EvidenceSummary>;
 }
 
-type Phase = 'idle' | 'preparing' | 'encrypting' | 'running' | 'downloading';
-type ActivePhase = Exclude<Phase, 'idle'>;
+type Phase = 'idle' | EvidencePhase;
+type ActivePhase = EvidencePhase;
 
 type TestCard = typeof PAGBANK_3DS_TEST_CARD;
 
@@ -236,9 +244,17 @@ function useEvidenceRun(
   const [phase, setPhase] = useState<Phase>('idle');
   const [summary, setSummary] = useState<EvidenceSummary | null>(null);
   const [failed, setFailed] = useState<ActivePhase | null>(null);
+  // What the step list draws: the server's section, and the tokens this run took.
+  const [section, setSection] = useState<EvidenceRunSection | null>(null);
+  const [scope, setScope] = useState<{ full: boolean; walletResults: BrowserWalletResult[] | null }>({
+    full: false,
+    walletResults: null,
+  });
   const run = async (full: boolean): Promise<void> => {
     setFailed(null);
     setSummary(null);
+    setSection(null);
+    setScope({ full, walletResults: null });
     // The phase that throws is the one the operator is told about.
     let current: ActivePhase = full ? 'preparing' : 'downloading';
     const enter = (next: ActivePhase): void => {
@@ -251,11 +267,12 @@ function useEvidenceRun(
         // The sheets ran before this chain: what they answered, taken once.
         const walletResults = wallets.collect();
         wallets.reset();
+        setScope({ full, walletResults });
         const prepared = await onPrepare();
         enter('encrypting');
         const cards = await prepareTestCards(prepared);
         enter('running');
-        await onRun(prepared.runId, cards, walletResults);
+        await onRun(prepared.runId, cards, walletResults, setSection);
       }
       enter('downloading');
       setSummary(await onDownload());
@@ -265,7 +282,7 @@ function useEvidenceRun(
       setPhase('idle');
     }
   };
-  return { phase, busy: phase !== 'idle', summary, failed, run };
+  return { phase, section, scope, busy: phase !== 'idle', summary, failed, run };
 }
 
 /** How the last return from PagBank ended — with the recorded reason when it failed. */
@@ -290,7 +307,7 @@ function EvidenceBody(props: HomologacaoEvidenceCardProps): ReactNode {
     validateApplePayMerchant: props.onValidateApplePayMerchant,
     googlePayApi: props.googlePayApi,
   });
-  const { phase, busy, summary, failed, run } = useEvidenceRun(props, wallets);
+  const { phase, section, scope, busy, summary, failed, run } = useEvidenceRun(props, wallets);
   return (
     <Stack spacing={1.5} data-testid="homologacao-evidence-card" sx={CARD_SX}>
       <Typography variant="body2" fontWeight={600}>
@@ -324,11 +341,8 @@ function EvidenceBody(props: HomologacaoEvidenceCardProps): ReactNode {
           {copy.downloadLatest}
         </Button>
       </Stack>
-      {busy ? (
-        <Stack spacing={0.5} role="status" aria-busy="true" data-testid="evidence-phase">
-          <Typography variant="body2">{copy.phases[phase as ActivePhase]}</Typography>
-          <LinearProgress />
-        </Stack>
+      {phase !== 'idle' ? (
+        <EvidenceProgress phase={phase} section={section} full={scope.full} walletResults={scope.walletResults} />
       ) : null}
       <EvidenceResult summary={summary} failed={failed} />
     </Stack>

package/src/components/platform/HomologacaoEvidenceProgress.tsx

@@ -0,0 +1,120 @@
+'use client';
+
+import { Box, CircularProgress, LinearProgress, Stack, SvgIcon, Typography } from '@mui/material';
+import type { ReactNode } from 'react';
+
+import type { BrowserWalletResult, EvidenceRunSection } from '@12-apps/payments-backend';
+
+import { usePlatformCopy } from './copy-context';
+
+/**
+ * The evidence run's progress, one line per step (FUT-3755): a run takes
+ * minutes — every cancel is retried while the sandbox answers 40008 — so the
+ * operator sees which step is done, which one is going, and which wallets this
+ * generation carries (their sheets were tapped BEFORE "generate", and the
+ * buttons reset once the tokens are taken).
+ *
+ * The sections come from the host as the server starts each one; the card
+ * never guesses one. A download-only press shows the file step alone.
+ */
+
+export type EvidencePhase = 'preparing' | 'encrypting' | 'running' | 'downloading';
+type EvidenceRunStep = 'prepare' | 'encrypt' | EvidenceRunSection | 'file';
+
+// The server's section order (`EVIDENCE_RUN_SECTIONS`), spelled here: this
+// package may import only types from the backend (ADOPTING.md §6).
+const SECTIONS: readonly EvidenceRunSection[] = ['PIX', 'CARD', 'DEBIT', 'GOOGLE_PAY', 'APPLE_PAY'];
+const FULL_RUN: readonly EvidenceRunStep[] = ['prepare', 'encrypt', ...SECTIONS, 'file'];
+const DOWNLOAD_ONLY: readonly EvidenceRunStep[] = ['file'];
+
+/** The step a phase — and, while running, the server's section — is on. */
+function currentEvidenceStep(phase: EvidencePhase, section: EvidenceRunSection | null): EvidenceRunStep {
+  if (phase === 'preparing') return 'prepare';
+  if (phase === 'encrypting') return 'encrypt';
+  if (phase === 'running') return section ?? 'PIX';
+  return 'file';
+}
+
+interface EvidenceProgressProps {
+  phase: EvidencePhase;
+  section: EvidenceRunSection | null;
+  /** False for "download the latest recorded": nothing is run. */
+  full: boolean;
+  /** What the wallet sheets answered for this run; null on a download-only press. */
+  walletResults: BrowserWalletResult[] | null;
+}
+
+// Material Symbols' check_circle and radio_button_unchecked, inline: the
+// package takes no icons dependency (see `../checkout/icons.tsx`).
+const DONE_PATH = 'M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m-2 15-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8z';
+const PENDING_PATH =
+  'M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m0 18c-4.42 0-8-3.58-8-8s3.58-8 8-8 8 3.58 8 8-3.58 8-8 8';
+
+/** Shape, not only colour, tells the three states apart. */
+function StepMark({ state }: { state: 'done' | 'current' | 'pending' }): ReactNode {
+  if (state === 'current') return <CircularProgress size={18} thickness={5} />;
+  return (
+    <SvgIcon fontSize="small" color={state === 'done' ? 'success' : 'disabled'}>
+      <path d={state === 'done' ? DONE_PATH : PENDING_PATH} />
+    </SvgIcon>
+  );
+}
+
+/** Which wallets this run carries a token for, and which stay pending. */
+function WalletsLine({ results }: { results: BrowserWalletResult[] }): ReactNode {
+  const copy = usePlatformCopy().evidence;
+  const names = copy.wallets.names;
+  const included = (['GOOGLE_PAY', 'APPLE_PAY'] as const).filter((type) =>
+    results.some((result) => result.type === type && result.token),
+  );
+  const left = (['GOOGLE_PAY', 'APPLE_PAY'] as const).filter((type) => !included.includes(type));
+  return (
+    <Typography variant="caption" component="p" data-testid="evidence-run-wallets">
+      {copy.steps.walletsInRun(
+        included.map((type) => names[type]),
+        left.map((type) => names[type]),
+      )}
+    </Typography>
+  );
+}
+
+export function EvidenceProgress({ phase, section, full, walletResults }: EvidenceProgressProps): ReactNode {
+  const copy = usePlatformCopy().evidence;
+  const steps = full ? FULL_RUN : DOWNLOAD_ONLY;
+  const at = steps.indexOf(currentEvidenceStep(phase, section));
+  return (
+    <Stack spacing={1} role="status" aria-busy="true" data-testid="evidence-phase">
+      <Typography variant="body2">{copy.phases[phase]}</Typography>
+      <LinearProgress variant="determinate" value={(at / steps.length) * 100} aria-label={copy.steps.label} />
+      {full ? (
+        <Box component="ol" sx={{ m: 0, p: 0, listStyle: 'none', display: 'grid', gap: 0.5 }} data-testid="evidence-steps">
+          {steps.map((step, index) => {
+            const state = index < at ? 'done' : index === at ? 'current' : 'pending';
+            return (
+              <Stack
+                key={step}
+                component="li"
+                direction="row"
+                spacing={1}
+                sx={{ alignItems: 'center', minHeight: 24 }}
+                data-testid={`evidence-step-${step}`}
+                data-state={state}
+                aria-current={state === 'current' ? 'step' : undefined}
+              >
+                <StepMark state={state} />
+                <Typography
+                  variant="body2"
+                  fontWeight={state === 'current' ? 600 : 400}
+                  color={state === 'pending' ? 'text.secondary' : 'text.primary'}
+                >
+                  {copy.steps.names[step]}
+                </Typography>
+              </Stack>
+            );
+          })}
+        </Box>
+      ) : null}
+      {walletResults ? <WalletsLine results={walletResults} /> : null}
+    </Stack>
+  );
+}

package/src/components/platform/HomologacaoEvidenceWallets.tsx

@@ -25,7 +25,7 @@ import {
   type GooglePaymentData,
   type GooglePaymentsClient,
 } from '../checkout/google-pay-button';
-import type { HomologacaoEvidenceWalletsCopy } from './copy';
+import type { AppleAbsence, HomologacaoEvidenceWalletsCopy } from './copy';
 import { usePlatformCopy } from './copy-context';
 
 /**
@@ -171,9 +171,10 @@ function notOffered(wallet: EvidenceWallet, input: EvidenceWalletsInput, googleR
 }
 
 /** Why Apple Pay has no button on a screen whose host carries wallets — null when it has one, or no wallets at all. */
-function appleAbsence(input: EvidenceWalletsInput, offered: boolean): BrowserWalletFailure | null {
+function appleAbsence(input: EvidenceWalletsInput, offered: boolean): AppleAbsence | null {
   if (offered || !input.config) return null;
-  return notOffered('APPLE_PAY', input, false)?.failure ?? null;
+  const failure = notOffered('APPLE_PAY', input, false)?.failure;
+  return failure === 'NOT_CONFIGURED' || failure === 'NOT_AVAILABLE' || failure === 'MERCHANT_VALIDATION_FAILED' ? failure : null;
 }
 
 /** The wallet step's state: the sheets' answers, the presses that open them, and what phase 2 gets. */
@@ -216,7 +217,7 @@ function GooglePayMount({ client, onPress, locale }: { client: GooglePaymentsCli
     element.replaceChildren(client.createButton({ onClick: () => latest.current(), buttonSizeMode: 'fill', buttonLocale: locale }));
     return () => element.replaceChildren();
   }, [client, locale]);
-  return <Box ref={mount} data-testid="evidence-google-pay" sx={{ minHeight: 40, width: 240, '& > *': { width: '100%' } }} />;
+  return <Box ref={mount} data-testid="evidence-google-pay" sx={{ minHeight: 40, width: { xs: '100%', sm: 240 }, '& > *': { width: '100%' } }} />;
 }
 
 /** Apple's button: Safari draws it (`-apple-pay-button`); elsewhere the name on a black pill. */
@@ -231,7 +232,7 @@ function ApplePayPress({ label, onPress }: { label: string; onPress: () => void
       sx={{
         WebkitAppearance: '-apple-pay-button',
         height: 40,
-        width: 240,
+        width: { xs: '100%', sm: 240 },
         border: 0,
         borderRadius: 1,
         cursor: 'pointer',
@@ -270,20 +271,22 @@ export function EvidenceWalletBlock({ wallets }: { wallets: EvidenceWallets }):
     return result ? [result] : [];
   });
   return (
-    <Stack spacing={1} data-testid="evidence-wallets">
+    <Stack spacing={1} data-testid="evidence-wallets" sx={{ maxWidth: '72ch' }}>
       <Typography variant="body2" fontWeight={600}>
         {copy.heading}
       </Typography>
-      <Typography variant="caption" component="p" color="text.secondary">
-        {copy.hint}
-      </Typography>
+      {wallets.google || wallets.apple ? (
+        <Typography variant="caption" component="p" color="text.secondary">
+          {copy.hint}
+        </Typography>
+      ) : null}
       <Stack direction={{ xs: 'column', sm: 'row' }} spacing={1}>
         {wallets.google ? (
           <GooglePayMount client={wallets.google.client} onPress={wallets.google.press} locale={copy.googlePayButtonLocale} />
         ) : null}
         {wallets.apple ? <ApplePayPress label={copy.applePayButton} onPress={wallets.apple.press} /> : null}
       </Stack>
-      {wallets.appleAbsent === 'NOT_CONFIGURED' || wallets.appleAbsent === 'NOT_AVAILABLE' ? (
+      {wallets.appleAbsent ? (
         <Typography variant="caption" component="p" color="text.secondary" data-testid="evidence-apple-pay-absent">
           {copy.applePayAbsent[wallets.appleAbsent]}
         </Typography>

package/src/components/platform/copy.ts

@@ -148,6 +148,14 @@ export interface HomologacaoEvidenceCardCopy {
   generate: string;
   downloadLatest: string;
   phases: { preparing: string; encrypting: string; running: string; downloading: string };
+  /** The run's step list (FUT-3755): which step is done, which one is going. */
+  steps: {
+    /** The bar's accessible name. */
+    label: string;
+    names: Record<'prepare' | 'encrypt' | 'PIX' | 'CARD' | 'DEBIT' | 'GOOGLE_PAY' | 'APPLE_PAY' | 'file', string>;
+    /** Which wallets this generation carries a token for, and which stay pending. */
+    walletsInRun: (included: string[], pending: string[]) => string;
+  };
   summary: (counts: { executed: number; failed: number; pending: number }) => string;
   incomplete: string;
   /** Which phase failed — and that the latest recorded file can still be downloaded. */
@@ -156,6 +164,9 @@ export interface HomologacaoEvidenceCardCopy {
   wallets: HomologacaoEvidenceWalletsCopy;
 }
 
+/** Why Apple Pay has no button on the evidence card (FUT-3755). */
+export type AppleAbsence = 'NOT_CONFIGURED' | 'NOT_AVAILABLE' | 'MERCHANT_VALIDATION_FAILED';
+
 /** The Google Pay / Apple Pay step of the evidence card (FUT-3755). */
 export interface HomologacaoEvidenceWalletsCopy {
   heading: string;
@@ -174,7 +185,7 @@ export interface HomologacaoEvidenceWalletsCopy {
   /** Apple Pay started and failed. */
   applePayCannotComplete: string;
   /** Why Apple Pay has no button here: the platform has no Apple Pay identity yet, or this browser has no sheet. */
-  applePayAbsent: { NOT_CONFIGURED: string; NOT_AVAILABLE: string };
+  applePayAbsent: Record<AppleAbsence, string>;
   /** A wallet holds its token: `card` is the network and last four the wallet showed — never the token. */
   ready: (wallet: string, card: string) => string;
   /** The sheet answered no token; pressing again retries. */

package/src/components/platform/en-US.ts

@@ -131,6 +131,26 @@ export const EN_US_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
       running: 'Creating the Pix, credit, debit and wallet orders in the sandbox — this can take a few minutes…',
       downloading: 'Building the file…',
     },
+    steps: {
+      label: 'Generation progress',
+      names: {
+        prepare: 'Prepare (application, token, public key and 3DS session)',
+        encrypt: 'Encrypt the cards and authenticate the debit (3DS)',
+        PIX: 'Pix',
+        CARD: 'Credit card',
+        DEBIT: 'Debit with 3DS',
+        GOOGLE_PAY: 'Google Pay',
+        APPLE_PAY: 'Apple Pay',
+        file: 'Build the file',
+      },
+      walletsInRun: (included, pending) =>
+        [
+          included.length > 0 ? `In this generation: ${included.join(' and ')}.` : 'No wallet in this generation.',
+          pending.length > 0 ? `${pending.join(' and ')} ${pending.length === 1 ? 'stays' : 'stay'} pending.` : '',
+        ]
+          .filter(Boolean)
+          .join(' '),
+    },
     summary: ({ executed, failed, pending }) =>
       `✓\u00a0${executed}\u00a0executed · ✗\u00a0${failed}\u00a0failed · ⧗\u00a0${pending}\u00a0pending`,
     incomplete:
@@ -147,9 +167,7 @@ export const EN_US_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
     wallets: {
       heading: 'Digital wallets (before generating)',
       names: { GOOGLE_PAY: 'Google Pay', APPLE_PAY: 'Apple Pay' },
-      hint:
-        'Google Pay and Apple Pay open their own sheet, and only on your tap. Tap each one before generating the file; ' +
-        "without it, the wallets' sections stay pending. Test only: nothing is charged.",
+      hint: "Tap each wallet before generating; without it, that wallet's section stays pending.",
       googlePayButtonLocale: 'en',
       applePayButton: 'Pay with Apple Pay',
       applePaySheetTotal: 'Homologation test',
@@ -158,6 +176,7 @@ export const EN_US_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
       applePayAbsent: {
         NOT_CONFIGURED: 'Apple Pay: waiting for the Apple Developer account. Its section stays pending.',
         NOT_AVAILABLE: 'Apple Pay: open this screen in Safari on an iPhone or Mac to test it.',
+        MERCHANT_VALIDATION_FAILED: "Apple Pay: the merchant validation is not set up. Its section stays pending.",
       },
       ready: (wallet, card) => `${wallet} ready${card ? ` — ${card}` : ''}. It will be used when the file is generated.`,
       failed: (wallet) => `${wallet} returned no token. Tap again to retry.`,

package/src/components/platform/pt-BR.ts

@@ -112,6 +112,26 @@ export const PT_BR_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
       running: 'Criando os pedidos Pix, crédito, débito e carteiras no sandbox — pode levar alguns minutos…',
       downloading: 'Montando o arquivo…',
     },
+    steps: {
+      label: 'Progresso da geração',
+      names: {
+        prepare: 'Preparar (aplicação, token, chave pública e sessão 3DS)',
+        encrypt: 'Criptografar os cartões e autenticar o débito (3DS)',
+        PIX: 'Pix',
+        CARD: 'Cartão de crédito',
+        DEBIT: 'Débito com 3DS',
+        GOOGLE_PAY: 'Google Pay',
+        APPLE_PAY: 'Apple Pay',
+        file: 'Montar o arquivo',
+      },
+      walletsInRun: (included, pending) =>
+        [
+          included.length > 0 ? `Nesta geração: ${included.join(' e ')}.` : 'Nenhuma carteira nesta geração.',
+          pending.length > 0 ? `${pending.join(' e ')} ${pending.length === 1 ? 'fica pendente' : 'ficam pendentes'}.` : '',
+        ]
+          .filter(Boolean)
+          .join(' '),
+    },
     summary: ({ executed, failed, pending }) =>
       // Non-breaking inside each count, so only the separators may wrap.
       `✓\u00a0${executed}\u00a0${executed === 1 ? 'executado' : 'executados'} · ` +
@@ -131,9 +151,7 @@ export const PT_BR_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
     wallets: {
       heading: 'Carteiras digitais (antes de gerar)',
       names: { GOOGLE_PAY: 'Google Pay', APPLE_PAY: 'Apple Pay' },
-      hint:
-        'O Google Pay e o Apple Pay abrem a própria folha e só com o seu toque. Toque em cada um antes de gerar o arquivo; ' +
-        'sem isso, as seções das carteiras ficam pendentes. Somente teste: nada é cobrado.',
+      hint: 'Toque em cada carteira antes de gerar; sem isso, a seção dela fica pendente.',
       googlePayButtonLocale: 'pt',
       applePayButton: 'Pagar com Apple Pay',
       applePaySheetTotal: 'Teste de homologação',
@@ -142,6 +160,7 @@ export const PT_BR_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
       applePayAbsent: {
         NOT_CONFIGURED: 'Apple Pay: aguardando a conta Apple Developer. A seção fica pendente.',
         NOT_AVAILABLE: 'Apple Pay: abra esta tela no Safari de um iPhone ou Mac para testar.',
+        MERCHANT_VALIDATION_FAILED: 'Apple Pay: a validação do comerciante não está configurada. A seção fica pendente.',
       },
       ready: (wallet, card) => `${wallet} pronto${card ? ` — ${card}` : ''}. Será usado ao gerar o arquivo.`,
       failed: (wallet) => `O ${wallet} não devolveu o token. Toque de novo para tentar.`,