@12-apps/payments-frontend 1.12.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.12.0",
+  "version": "1.13.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": "^1.12.0",
+    "@12-apps/payments-backend": "^1.13.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {
@@ -28,8 +28,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.13.0",
-    "@12-apps/typescript-config": "^1.13.0",
+    "@12-apps/eslint-config": "^1.15.0",
+    "@12-apps/typescript-config": "^1.15.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@mui/material": "^6.5.0",

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

@@ -2,12 +2,9 @@ import { Box } from "@mui/material";
 import { useEffect, useRef, type JSX, type ReactNode } from "react";
 
 import { BuyerInfoForm } from "./buyer-info-form";
-import { CardView } from "./card-view";
 import { LockOutlinedIcon } from "./icons";
 import {
-  cardChain,
   cardPathAvailable,
-  cardTokenization,
   offeredMethods,
   selectableMethods,
   usePreselectSoleMethod,
@@ -15,7 +12,7 @@ import {
 import { MethodPicker } from "./method-picker";
 import { PaymentErrorPanel } from "./payment-error-panel";
 import { PayerSummary } from "./payer-summary";
-import { PixView } from "./pix-view";
+import { resolveCheckoutScreen } from "./providers/registry";
 import type {
   BuyerField,
   BuyerInfo,
@@ -53,11 +50,24 @@ function useAutoRaiseOrder(
   }, [method, order, creating, createError, onGenerate]);
 }
 
-/** The per-method payment body — PIX QR, card form, or nothing until raised. */
+/**
+ * The payment body — whichever screen the store's provider declares (FUT-596).
+ *
+ * This used to switch on `order.method` and compose the PIX and card panes
+ * itself. It now resolves a screen from the id the adapter published on the
+ * chain's head and renders it; the panes moved to `providers/`, unchanged.
+ * The shell keeps everything shared — picker, payer, totals, errors, the
+ * polling cadence — so a provider's flow differs only where it genuinely does.
+ *
+ * `resolveCheckoutScreen` always returns a component, so there is no branch
+ * here for "no screen": an undeclared or unrecognised id lands on the
+ * capability default.
+ */
 function PaymentBody({
   order,
   buyer,
   providerConfig,
+  method,
   tenantSlug,
   onResolved,
   pollIntervalMs,
@@ -65,29 +75,23 @@ function PaymentBody({
   order: CheckoutOrder | null;
   buyer: BuyerInfo;
   providerConfig: CheckoutProviderConfig | null;
+  method: PaymentMethod | null;
   tenantSlug?: string;
   onResolved: (status: OrderStatus) => void;
   pollIntervalMs?: number;
 }): JSX.Element | null {
-  if (order?.method === "PIX") {
-    return <PixView order={order} onResolved={onResolved} pollIntervalMs={pollIntervalMs} />;
-  }
-  if (order?.method === "CARD") {
-    return (
-      <CardView
-        order={order}
-        buyer={buyer}
-        providerConfig={cardTokenization(providerConfig)}
-        // The whole chain (FUT-563): one instrument is minted per provider so
-        // the charge survives the first one failing, with nothing re-typed.
-        providerChain={cardChain(providerConfig)}
-        tenantSlug={tenantSlug}
-        onResolved={onResolved}
-        pollIntervalMs={pollIntervalMs}
-      />
-    );
-  }
-  return null;
+  const Screen = resolveCheckoutScreen(providerConfig?.chain?.[0]?.checkoutScreen);
+  return (
+    <Screen
+      order={order}
+      buyer={buyer}
+      config={providerConfig}
+      method={method}
+      tenantSlug={tenantSlug}
+      onResolved={onResolved}
+      pollIntervalMs={pollIntervalMs}
+    />
+  );
 }
 
 /** Empty-cart state shown when there's nothing to check out. */
@@ -334,6 +338,7 @@ export function PaymentStep({
         order={order}
         buyer={buyer}
         providerConfig={providerConfig ?? null}
+        method={method}
         tenantSlug={tenantSlug}
         onResolved={onResolved}
         pollIntervalMs={pollIntervalMs}

package/src/components/checkout/providers/capability-default.tsx

@@ -0,0 +1,67 @@
+/**
+ * The screen for a provider that declares none (FUT-596, AC3).
+ *
+ * This is the guarantee that adding a vendor never leaves a blank pane. It is
+ * reached three ways, and all three are normal rather than exceptional:
+ *
+ *   1. An adapter that has not declared `checkoutScreen` at all — Stone and
+ *      Stripe today. They check out on the day they are written.
+ *   2. A host serving an older `/checkout/config` with no chain, so there is
+ *      no id to read.
+ *   3. An id THIS bundle has never heard of. The backend and frontend packages
+ *      version independently, so a host running a newer server than bundle is
+ *      an ordinary deployment state — and the buyer must not pay for it.
+ *
+ * It does not reimplement a pane. It picks between the same two screens a
+ * declaration would have chosen, from the capabilities every adapter already
+ * publishes — so the default and the declared path cannot drift apart, and
+ * there is exactly one implementation of each shape.
+ */
+import type { JSX } from "react";
+
+import type { CheckoutProviderConfig } from "../types";
+
+import { HostedLinkScreen } from "./hosted-link";
+import { PixAndCardScreen } from "./pix-and-card";
+import type { ProviderCheckoutScreenProps } from "./types";
+
+/** Schemes that give the BROWSER a card form of its own. */
+const IN_BROWSER_TOKENIZATION: ReadonlySet<string> = new Set(["PUBLIC_KEY", "SDK"]);
+
+/**
+ * Whether this store hands the buyer over instead of collecting here — the
+ * frontend twin of the server's `usesHostedCheckout`, deliberately written to
+ * the same three rules so the pane and the walk cannot disagree.
+ *
+ * Note this is NOT `!cardPathAvailable(config)`. That helper answers a
+ * different question — "is a card offerable at all" — and it answers TRUE for
+ * a hand-off store, because typing the card on the provider's page is still a
+ * card path. Inverting it therefore sends the hosted store to the on-page
+ * screen and the on-page store to the hand-off, which is exactly backwards.
+ *
+ * The rules, in order:
+ *   - Only CARD can be answered in advance. TOKENIZATION IS A CARD FACT: it
+ *     says how the browser turns a PAN into an instrument, and a PIX charge
+ *     has no instrument to mint. A store with no card-capable entry is not
+ *     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.
+ *   - 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.
+ */
+function handsBuyerOver(config: CheckoutProviderConfig | null): boolean {
+  const chain = config?.chain;
+  if (!chain || chain.length === 0) return false;
+  const cardCapable = chain.filter((link) => link.methods.includes("CARD"));
+  if (cardCapable.length === 0) return false;
+  return !cardCapable.some((link) => IN_BROWSER_TOKENIZATION.has(link.tokenization));
+}
+
+export function CapabilityDefaultScreen(props: ProviderCheckoutScreenProps): JSX.Element | null {
+  return handsBuyerOver(props.config) ? (
+    <HostedLinkScreen {...props} />
+  ) : (
+    <PixAndCardScreen {...props} />
+  );
+}

package/src/components/checkout/providers/hosted-link.tsx

@@ -0,0 +1,52 @@
+/**
+ * The screen for a store whose buyer finishes on the PROVIDER's page (FUT-596).
+ *
+ * Declared as `hosted-link` by any adapter of that shape — today InfinitePay.
+ * There is no card form and no PIX pane here on purpose: this provider takes
+ * neither on our page, and rendering either would offer a buyer something the
+ * charge cannot honour.
+ *
+ * ## Why this screen renders no payable
+ *
+ * For a hand-off provider the pane never receives an `order`, and that is by
+ * design rather than an omission. The controller raises the charge, sees a
+ * `hostedCheckoutUrl` on the response and navigates — `handOverToProvider`
+ * returns before `setOrder` (`use-checkout-controller.ts`), because the buyer
+ * is leaving this page and parking the payable for the return leg matters more
+ * than painting a pane they will not see. `hosted-return.ts` picks it back up.
+ *
+ * So the whole job here is the moment BEFORE that: the buyer has chosen a
+ * method and the redirect is being prepared. Previously the pane rendered
+ * `null` through that moment, which reads as a checkout that has stalled — the
+ * screen tells them where they are going instead. Nothing here touches the
+ * money path; the navigation and the parking are unchanged.
+ */
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { useCheckoutComponents } from "../ui";
+
+import type { ProviderCheckoutScreenProps } from "./types";
+
+export function HostedLinkScreen({ method }: ProviderCheckoutScreenProps): JSX.Element | null {
+  const { Text, LoadingState } = useCheckoutComponents();
+
+  // Nothing chosen yet ⇒ the shell is still showing the picker. Same as every
+  // other screen: the pane stays out of the way until there is something to say.
+  if (!method) return null;
+
+  return (
+    <Box
+      data-testid="checkout-handoff-pending"
+      sx={{ display: "flex", flexDirection: "column", gap: 2, alignItems: "center", py: 4 }}
+    >
+      <LoadingState variant="spinner" message="Preparando o pagamento" size="md" />
+      <Text variant="body" size="md" as="p">
+        Você será levado à página segura do provedor para concluir o pagamento.
+      </Text>
+      <Text variant="caption" size="sm" as="p" color="secondary">
+        Assim que terminar, você volta para cá e nós confirmamos o pedido.
+      </Text>
+    </Box>
+  );
+}

package/src/components/checkout/providers/pix-and-card.tsx

@@ -0,0 +1,50 @@
+/**
+ * The screen for a store that collects payment ON OUR PAGE (FUT-596).
+ *
+ * A PIX charge renders the provider's code here; a card charge renders our own
+ * form and mints the instrument in this browser. Declared by any adapter whose
+ * flow is that shape — `pix-and-card` — which today is PagBank and tomorrow is
+ * Stone, from one declaration each and no second component.
+ *
+ * It carries NO hand-off branch. A provider that finishes on its own page
+ * declares `hosted-link` and renders `./hosted-link.tsx` instead; the two never
+ * test for each other, which is the property FUT-596 exists to buy.
+ */
+import type { JSX } from "react";
+
+import { CardView } from "../card-view";
+import { cardChain, cardTokenization } from "../method-capability";
+import { PixView } from "../pix-view";
+
+import type { ProviderCheckoutScreenProps } from "./types";
+
+export function PixAndCardScreen({
+  order,
+  buyer,
+  config,
+  tenantSlug,
+  onResolved,
+  pollIntervalMs,
+}: ProviderCheckoutScreenProps): JSX.Element | null {
+  if (order?.method === "PIX") {
+    return <PixView order={order} onResolved={onResolved} pollIntervalMs={pollIntervalMs} />;
+  }
+  if (order?.method === "CARD") {
+    return (
+      <CardView
+        order={order}
+        buyer={buyer}
+        providerConfig={cardTokenization(config)}
+        // The whole chain (FUT-563): one instrument is minted per provider so
+        // the charge survives the first one failing, with nothing re-typed.
+        providerChain={cardChain(config)}
+        tenantSlug={tenantSlug}
+        onResolved={onResolved}
+        pollIntervalMs={pollIntervalMs}
+      />
+    );
+  }
+  // No order yet — the shell is still showing the picker, and raises one as
+  // soon as a method is chosen.
+  return null;
+}

package/src/components/checkout/providers/registry.ts

@@ -0,0 +1,78 @@
+/**
+ * Screen id → screen (FUT-596).
+ *
+ * The one place the buyer's pane is chosen. An adapter declares
+ * `checkoutScreen` (see `PaymentProviderAdapter`), the gateway publishes it on
+ * every chain entry, and this table turns it into a component.
+ *
+ * ## Why the key is a screen id and not a provider name
+ *
+ * A provider-name switch is the shape this ticket exists to remove. It cannot
+ * express reuse — Stone's flow is PagBank's flow, and under a name key that is
+ * a duplicated entry rather than one declaration — and it puts vendor
+ * knowledge in the frontend, where nothing declares it and no adapter outside
+ * this package can extend it. A screen id inverts that: the adapter says what
+ * shape its flow is, and any number of providers share one screen by saying
+ * the same word. It is the contract `SetupStep.action` already uses one layer
+ * up, for the same reason.
+ *
+ * ## Unknown ids resolve, they do not fail
+ *
+ * {@link screenFor} returns `null` for an id it does not know, and the caller
+ * renders {@link CapabilityDefaultScreen}. This is load-bearing: the backend
+ * and frontend packages version independently, so a host running a newer
+ * server than bundle will publish ids this table has never seen. That is an
+ * ordinary deployment state and it must degrade to a working checkout, never
+ * to an empty pane.
+ */
+import { CapabilityDefaultScreen } from "./capability-default";
+import { HostedLinkScreen } from "./hosted-link";
+import { PixAndCardScreen } from "./pix-and-card";
+import type { ProviderCheckoutScreen } from "./types";
+
+/**
+ * Every screen this bundle can render, by the id an adapter declares.
+ *
+ * NULL-PROTOTYPE on purpose. The key is a string that arrives from the server,
+ * so a plain object literal would answer `SCREENS['constructor']` with
+ * `Object` and `SCREENS['toString']` with a function — both truthy, neither a
+ * component, and the pane would throw mid-render for a store whose declared id
+ * happened to collide with `Object.prototype`. `Object.create(null)` has no
+ * prototype to inherit from, so the only keys are the ones written here.
+ */
+const SCREENS: Readonly<Record<string, ProviderCheckoutScreen>> = Object.assign(
+  Object.create(null) as Record<string, ProviderCheckoutScreen>,
+  {
+    /** Collected on our page: a PIX code, or a card typed here. */
+    "pix-and-card": PixAndCardScreen,
+    /** Finished on the provider's own page. */
+    "hosted-link": HostedLinkScreen,
+  },
+);
+
+/**
+ * The screen for a declared id, or `null` when nothing is declared or the id
+ * is unknown to this bundle. A `null` answer is not an error — see the module
+ * comment.
+ */
+export function screenFor(id: string | null | undefined): ProviderCheckoutScreen | null {
+  if (!id) return null;
+  return SCREENS[id] ?? null;
+}
+
+/**
+ * THE resolution the pane uses: the declared screen, else the capability
+ * default. Always returns something renderable, which is AC3.
+ *
+ * The id is read from the chain's HEAD, because the head is the provider the
+ * walk tries first and therefore the flow the buyer is about to enter. A
+ * failover to a tail provider happens server-side, after the buyer has already
+ * given us everything the charge needs — the card is typed once and minted for
+ * every chain entry (FUT-563) — so the pane does not change under them
+ * mid-charge, and must not.
+ */
+export function resolveCheckoutScreen(
+  chainHeadScreen: string | null | undefined,
+): ProviderCheckoutScreen {
+  return screenFor(chainHeadScreen) ?? CapabilityDefaultScreen;
+}

package/src/components/checkout/providers/types.ts

@@ -0,0 +1,65 @@
+/**
+ * The buyer checkout SCREEN contract (FUT-596).
+ *
+ * A screen owns the pane where the buyer actually pays — the PIX code, the card
+ * form, the hand-off notice — and nothing else. Everything shared stays in the
+ * shell: the stepper, the payer summary, the method picker, the totals, the
+ * error surfaces, the polling cadence and the terminal `onResolved` hop to
+ * Confirmação. That split is what lets a vendor's flow differ in the one place
+ * it genuinely differs without forking a checkout.
+ *
+ * Which screen renders is resolved from an id the ADAPTER declares
+ * (`PaymentProviderAdapter.checkoutScreen`, published per chain entry), so
+ * neither the shell nor any host names a provider to get here. See
+ * `./registry.ts`.
+ */
+import type { JSX } from "react";
+
+import type {
+  BuyerInfo,
+  CheckoutOrder,
+  CheckoutProviderConfig,
+  OrderStatus,
+  PaymentMethod,
+} from "../types";
+
+/**
+ * What every screen is handed. Every field is already a prop of `PaymentStep`,
+ * so resolving a screen threads nothing new through the shell.
+ */
+export interface ProviderCheckoutScreenProps {
+  /**
+   * The raised payable, or `null` before the buyer has chosen a method.
+   *
+   * `null` is a real state a screen must render, not a loading artefact: it is
+   * the moment a hand-off screen says where the buyer is about to be sent.
+   */
+  order: CheckoutOrder | null;
+  buyer: BuyerInfo;
+  /**
+   * The store's protocol, RAW — not pre-narrowed to the card path's view.
+   *
+   * The shell used to hand the pane `cardTokenization(config)` and
+   * `cardChain(config)` directly. Both are card-shaped readings, and a screen
+   * whose provider takes no card here must not be given one: it would describe
+   * a store that mints instruments when this one does not. Screens that need
+   * those readings call the helpers themselves.
+   */
+  config: CheckoutProviderConfig | null;
+  /** What the shell's picker currently has selected; `null` before a choice. */
+  method: PaymentMethod | null;
+  /** Scopes the saved-card list to the store being paid. */
+  tenantSlug?: string;
+  /** The shell's polling cadence, passed through so tests can shorten it. */
+  pollIntervalMs?: number;
+  /** A terminal status — the shell moves to Confirmação. */
+  onResolved: (status: OrderStatus) => void;
+}
+
+/**
+ * A screen is a plain component. `null` is a legal render (nothing to show
+ * yet), which is what the pane did for every provider before FUT-596.
+ */
+export type ProviderCheckoutScreen = (
+  props: ProviderCheckoutScreenProps,
+) => JSX.Element | null;

package/src/components/checkout/types.ts

@@ -236,6 +236,22 @@ export interface CheckoutChainLink {
    * never shown a field for.
    */
   customerSchema?: CheckoutCustomerField[];
+  /**
+   * The buyer screen THIS provider's flow needs (FUT-596) — an opaque id the
+   * adapter declares and `providers/registry.ts` resolves to a component.
+   *
+   * Optional, and the DEGRADE DIRECTION IS THE OPPOSITE of `customerSchema`'s
+   * above — spelled out because a reader will otherwise assume symmetry from
+   * the neighbouring comment. Absent, `null`, or an id THIS bundle has never
+   * heard of all mean the CAPABILITY DEFAULT: the pane composed from
+   * `tokenization` + `methods`, exactly as it was before this field existed.
+   *
+   * That is the safe direction here. Treating an unknown id as "render
+   * nothing" would blank the pane for every buyer of a store whose backend is
+   * one release ahead of this bundle — and the two packages version
+   * independently, so that skew is normal, not exceptional.
+   */
+  checkoutScreen?: string | null;
 }
 
 /**