@12-apps/payments-frontend 3.27.2 → 3.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.27.2",
+  "version": "3.28.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.27.1",
+    "@12-apps/payments-backend": "^4.28.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/CredentialFieldStack.tsx

@@ -2,10 +2,10 @@
 
 import { Stack } from '@mui/material';
 
-import type { ProviderDescriptor } from '@12-apps/payments-backend';
+import type { PaymentEnvironment, ProviderDescriptor } from '@12-apps/payments-backend';
 
 import { CredentialField } from './CredentialFields';
-import { saveLabel } from './credential-rules';
+import { appliesIn, saveLabel } from './credential-rules';
 import { FormActions, ReverifyWarning } from './CredentialFormAlerts';
 import type { CredentialFormState } from './ProviderCredentialForm';
 import { usePaymentsSettingsCopy } from './settings-copy-context';
@@ -20,10 +20,13 @@ import { usePaymentsSettingsCopy } from './settings-copy-context';
  */
 export function CredentialFields({
   descriptor,
+  environment,
   form,
   proven,
 }: {
   descriptor: ProviderDescriptor;
+  /** The tab on screen: a field declared for other environments is not drawn. */
+  environment: PaymentEnvironment;
   form: CredentialFormState;
   /** A real charge has landed through this connection — see `ReverifyWarning`. */
   proven: boolean;
@@ -32,7 +35,7 @@ export function CredentialFields({
   return (
     <Stack spacing={2}>
       {proven ? <ReverifyWarning displayName={descriptor.displayName} /> : null}
-      {descriptor.credentialSchema.map((spec) => (
+      {descriptor.credentialSchema.filter((spec) => appliesIn(spec, environment)).map((spec) => (
         <CredentialField
           key={spec.key}
           spec={spec}

package/src/components/CredentialFields.tsx

@@ -68,6 +68,16 @@ const MONO_INPUT = {
   letterSpacing: '0.08em',
 } as const;
 
+/**
+ * A pasted PEM keeps its lines: a single-line input folds them away and the
+ * owner cannot see what they pasted. A textarea cannot be `type="password"`,
+ * so a multiline secret is shown while typed — it is still write-only, never
+ * echoed back after saving (the placeholder carries the masked hint).
+ */
+function multilineProps(spec: CredentialFieldSpec) {
+  return spec.multiline ? { multiline: true, minRows: 4, maxRows: 10, type: undefined } : {};
+}
+
 interface CredentialFieldProps {
   spec: CredentialFieldSpec;
   state: MaskedFieldState | undefined;
@@ -117,9 +127,12 @@ export function CredentialField({ spec, state, value, onChange, check }: Credent
         fullWidth
         id={inputId}
         {...presentation}
+        {...multilineProps(spec)}
         helperText={undefined}
         slotProps={
-          spec.mono ? { htmlInput: { sx: MONO_INPUT, spellCheck: false } } : { htmlInput: {} }
+          spec.mono || spec.multiline
+            ? { htmlInput: { sx: MONO_INPUT, spellCheck: false } }
+            : { htmlInput: {} }
         }
         sx={fieldSx(check?.status)}
         onChange={(e) => onChange(e.target.value)}
@@ -151,6 +164,9 @@ function fieldSx(status?: 'PASS' | 'FAIL' | 'UNCHECKED') {
       '&.Mui-focused fieldset': { borderColor: T.brand, borderWidth: '2px' },
     },
     '& .MuiOutlinedInput-input': { padding: '10px 12px' },
+    // A multiline root pads itself too; the textarea's own padding above is
+    // the one that lines it up with the single-line boxes around it.
+    '& .MuiInputBase-multiline': { padding: 0 },
   } as const;
 }
 

package/src/components/PaymentProviderSettings.tsx

@@ -177,6 +177,11 @@ interface VerificationInputs {
   provider: string;
   displayName: string;
   config: MaskedProviderConfig | null;
+  /**
+   * Some activation flow can run for this provider at all — see
+   * {@link activationRunnable}. When none can, there is no step to show.
+   */
+  provable: boolean;
   /** An earlier step is unfinished: withhold the pay button, render the rest. */
   blocked: boolean;
   /** The walkthrough is on an earlier step; this one is not on screen at all. */
@@ -185,8 +190,24 @@ interface VerificationInputs {
   onSetupIncomplete: () => void;
 }
 
+/**
+ * Whether ANY activation flow can run for this provider: the card flow needs a
+ * card to charge, the redirect flow a hosted page to send the owner to. A
+ * PIX-only provider that answers with a code on this page (Itau) has neither,
+ * so the step could only ever fail with "the provider returned no payment
+ * link" — it is switched on once its credential probe passes instead, the rule
+ * `ProviderStatusBar`'s toggle already applies to a provider that declares no
+ * `activationCharge`. Every other provider keeps the step exactly as before.
+ */
+function activationRunnable(descriptor: { capabilities?: { methods?: readonly string[]; tokenization?: string } }): boolean {
+  const capabilities = descriptor.capabilities;
+  if (!capabilities?.methods) return true;
+  return capabilities.tokenization === 'REDIRECT' || capabilities.methods.includes('CARD');
+}
+
 /** The activation step's context, built from what this screen already knows. */
 function verificationFor(io: VerificationInputs): ReactNode {
+  if (!io.provable) return null;
   // `enabled` is deliberately NOT passed: the step used it to show a standing
   // "provider is active" banner, which kept reassuring a store whose every
   // charge was being refused. `proven` is a different kind of fact — it is
@@ -331,6 +352,7 @@ export function PaymentProviderSettings({
         render: renderVerification,
         provider: active.name,
         displayName: active.displayName,
+        provable: activationRunnable(active),
         config: activeConfig,
         blocked: guideAwaitsConfirmation(guide, ack.confirmed, loaded),
         // The walkthrough still has a step to show ⇒ this is not that step.

package/src/components/ProviderCredentialForm.tsx

@@ -338,7 +338,7 @@ export function ProviderForm(props: ProviderFormProps) {
     />
   ) : null;
 
-  const fields = summary ? null : <CredentialFields descriptor={descriptor} form={form} proven={Boolean(config?.chargeVerifiedAt)} />;
+  const fields = summary ? null : <CredentialFields descriptor={descriptor} environment={props.environment} form={form} proven={Boolean(config?.chargeVerifiedAt)} />;
 
   return (
     <Stack spacing={2}>

package/src/components/ProviderSetupGuide.tsx

@@ -206,15 +206,18 @@ function StepRow({ step, actions }: StepRowProps) {
   // A bordered row with the work on the left and the way to do it on the
   // right, so a step reads as a thing to tick off rather than as a paragraph.
   // The instructions on this screen are a CHECKLIST — each one is a piece of
-  // work the owner does somewhere else and comes back from.
+  // work the owner does somewhere else and comes back from. On a phone the
+  // row wraps: the text keeps a readable measure and the button drops under
+  // it, rather than squeezing the text to a word per line beside it.
   return (
     <Stack
       direction="row"
       gap="12px"
       alignItems="flex-start"
+      flexWrap="wrap"
       sx={{ border: `1px solid ${T.line}`, borderRadius: '9px', px: '14px', py: '12px' }}
     >
-      <Stack spacing={1} sx={{ flex: 1, minWidth: 0 }}>
+      <Stack spacing={1} sx={{ flex: '1 1 240px', minWidth: 0 }}>
         <StepText text={step.text} link={step.link} />
       {action ? (
         <Box>

package/src/components/checkout/providers/hands-over.ts

@@ -7,7 +7,7 @@
  * which decides whether the buyer is asked PIX-or-card here at all. It lived
  * inside `capability-default.tsx` while there was one caller.
  */
-import type { CheckoutProviderConfig } from "../types";
+import type { CheckoutChainLink, CheckoutProviderConfig } from "../types";
 
 /** Schemes that give the BROWSER a card form of its own. */
 const IN_BROWSER_TOKENIZATION: ReadonlySet<string> = new Set(["PUBLIC_KEY", "SDK"]);
@@ -30,7 +30,8 @@ const IN_BROWSER_TOKENIZATION: ReadonlySet<string> = new Set(["PUBLIC_KEY", "SDK
  *     hosted — this is the FUT-747 correction, and getting it wrong routed the
  *     simplest store there is (one PIX-only provider honestly declaring
  *     `NONE`) into a hand-off it had no link for.
- *   - Hosted only when NOBODY who takes a card takes it here.
+ *   - Hosted only when NOBODY who takes a card takes it here — and nobody
+ *     takes PIX here either (see {@link takesPixOnThisPage}).
  *   - No chain served (an older host, a still-loading config) ⇒ not hosted,
  *     which is what this checkout did before there was a chain to read.
  */
@@ -39,5 +40,24 @@ export function handsBuyerOver(config: CheckoutProviderConfig | null): boolean {
   if (!chain || chain.length === 0) return false;
   const cardCapable = chain.filter((link) => link.methods.includes("CARD"));
   if (cardCapable.length === 0) return false;
+  if (chain.some(takesPixOnThisPage)) return false;
   return !cardCapable.some((link) => IN_BROWSER_TOKENIZATION.has(link.tokenization));
 }
+
+/**
+ * A provider that answers PIX with a code for THIS page rather than a link to
+ * its own. Whenever the chain holds one, the store is not a hand-off: PIX is
+ * paid here, so the picker is ours to show, and a card that only a hosted
+ * provider takes still leaves through `handOverToProvider` the moment its
+ * order comes back with a link. Without this rule a PIX-only on-page provider
+ * ahead of a hosted card provider (Itau, then InfinitePay) was routed whole to
+ * the hand-off screen, which never paints the QR and never offers the card.
+ *
+ * `NONE` is read as "no browser step" here. An adapter that declares `NONE`
+ * for a HOSTED checkout that also takes PIX (legal, though none ships) must
+ * declare `checkoutScreen: 'hosted-link'`, which `methodChosenAtProvider`
+ * honours before this rule is ever consulted.
+ */
+function takesPixOnThisPage(link: CheckoutChainLink): boolean {
+  return link.methods.includes("PIX") && link.tokenization !== "REDIRECT";
+}

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

@@ -22,6 +22,7 @@ import {
   Typography,
 } from '@mui/material';
 import { useState } from 'react';
+import QRCode from 'react-qr-code';
 
 import type { ClientChargeView, Money } from '@12-apps/payments-backend';
 
@@ -55,9 +56,22 @@ export function PixPanel({ charge, copy }: { charge: ClientChargeView; copy: Leg
   if (!charge.pix) return null;
   return (
     <Stack spacing={1} alignItems="flex-start">
+      {/* The provider's own image when it sent one (Stone, Stripe); otherwise
+          drawn here from the BR Code, as `PixView` does — a provider that
+          returns only the code (PagBank, Itau) must still give the buyer
+          something to scan. */}
       {charge.pix.qrImageUrl ? (
         <Box component="img" src={charge.pix.qrImageUrl} alt={copy.qrAlt} sx={{ width: 220 }} />
-      ) : null}
+      ) : (
+        <Box
+          role="img"
+          aria-label={copy.qrAlt}
+          data-testid="payments-pix-qr-local"
+          sx={{ bgcolor: 'background.paper', p: 2, borderRadius: 2, border: '1px solid', borderColor: 'divider' }}
+        >
+          <QRCode value={charge.pix.qrText} size={200} />
+        </Box>
+      )}
       <TextField fullWidth multiline size="small" label={copy.copyPasteLabel} value={charge.pix.qrText} />
       <Button
         size="small"

package/src/components/credential-rules.ts

@@ -18,6 +18,11 @@ import type { CredentialFormCopy } from './settings-copy';
  * they can be read as the set of rules they are.
  */
 
+/** Whether a field exists in `environment` — see `CredentialFieldSpec.environments`. */
+export function appliesIn(spec: CredentialFieldSpec, environment: PaymentEnvironment): boolean {
+  return !spec.environments || spec.environments.includes(environment);
+}
+
 /**
  * Is there enough on record to make the probe WORTH RUNNING?
  *
@@ -44,7 +49,7 @@ export function credentialsComplete(
 ): boolean {
   const stored = config?.environments[environment] ?? {};
   return descriptor.credentialSchema.every((spec) => {
-    if (spec.advanced) return true;
+    if (spec.advanced || !appliesIn(spec, environment)) return true;
     const typed = values[spec.key];
     if (typed !== undefined && typed.trim() !== '') return true;
     return stored[spec.key]?.configured === true;