@12-apps/payments-frontend 1.7.0 → 1.8.0

package/src/flows/runtime.tsx

@@ -0,0 +1,149 @@
+/**
+ * The factory's shared runtime (FUT-741): the fetched store protocol, and the
+ * providers that stop every nested screen re-fetching it.
+ *
+ * Two layers, on purpose:
+ *
+ *   - {@link FlowsShell} supplies the things a screen cannot work WITHOUT —
+ *     the design-system slots, the bound transport, the navigate port. Every
+ *     returned screen wraps itself in one, which is what makes "every
+ *     `screens.*` member already works standalone" true rather than
+ *     aspirational. Re-supplying them under a `Provider` is a no-op.
+ *   - {@link FlowsProvider} adds the one thing that is worth NOT repeating: the
+ *     fetched `/config`. A screen under it reads that answer; a screen standing
+ *     alone fetches its own.
+ */
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type JSX,
+  type ReactNode,
+} from "react";
+
+import { CheckoutClientProvider } from "../components/checkout/client-context";
+import { CheckoutNavigateProvider } from "../components/checkout/navigate-context";
+import type { CheckoutClient } from "../components/checkout/transport";
+import type { CheckoutProviderConfig } from "../components/checkout/types";
+import { CheckoutComponentsProvider } from "../components/checkout/ui";
+
+import type { CheckoutCopyFE } from "./copy";
+import type { CheckoutAvailability, CheckoutConfigState, PaymentFlowsConfig } from "./types";
+
+/** Supplied by a `Provider`; `null` means "nobody above me fetched it". */
+const FetchedConfigContext = createContext<CheckoutConfigState | null>(null);
+
+/** Everything one factory hands the screens it built. */
+export interface FlowsRuntime {
+  config: PaymentFlowsConfig;
+  client: CheckoutClient;
+  copy: CheckoutCopyFE;
+  navigate: (url: string) => void;
+  /** The store slug for THIS render — read from the host's hook, never frozen. */
+  useTenantSlug(): string | undefined;
+  /** The host's availability vote for THIS render. Defaults to "payable". */
+  useAvailability(): CheckoutAvailability;
+}
+
+/**
+ * Fetch the store protocol for one slug.
+ *
+ * A failure is NOT retried into a loop and NOT surfaced as an error state: the
+ * config read fails OPEN for the UI (`null` renders both method tiles) and the
+ * server still fails the charge CLOSED. Nothing about a blip here may hide a
+ * working checkout, and nothing about it may invent permission to mock.
+ */
+function useFetchedConfig(
+  runtime: FlowsRuntime,
+  enabled: boolean,
+): CheckoutConfigState {
+  const { client } = runtime;
+  const onWarning = runtime.config.onWarning;
+  const tenantSlug = runtime.useTenantSlug();
+  const [state, setState] = useState<CheckoutConfigState>({ config: null, pending: enabled });
+
+  useEffect(() => {
+    if (!enabled || !tenantSlug) {
+      setState({ config: null, pending: false });
+      return undefined;
+    }
+    let active = true;
+    setState({ config: null, pending: true });
+    void client.getConfig(tenantSlug).then((result) => {
+      if (!active) return;
+      if (!result.ok) {
+        // Reported, never logged: a `console.error` in a buyer's browser tells
+        // nobody. Silent by default is the honest alternative.
+        onWarning?.("checkout config read failed", { tenantSlug, error: result.error });
+        setState({ config: null, pending: false });
+        return;
+      }
+      setState({ config: result.data, pending: false });
+    });
+    return () => {
+      active = false;
+    };
+  }, [client, tenantSlug, enabled, onWarning]);
+
+  return state;
+}
+
+/**
+ * The store protocol, from the nearest `Provider` or fetched here.
+ *
+ * Both branches always run their hooks; the self-fetch is merely disabled when
+ * somebody above already has the answer, which keeps the rule of hooks honest.
+ */
+export function useResolvedConfig(runtime: FlowsRuntime): CheckoutConfigState {
+  const provided = useContext(FetchedConfigContext);
+  const own = useFetchedConfig(runtime, provided === null);
+  return provided ?? own;
+}
+
+/** Slots, transport and the navigate port — what a screen cannot work without. */
+export function FlowsShell({
+  runtime,
+  children,
+}: {
+  runtime: FlowsRuntime;
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <CheckoutComponentsProvider components={runtime.config.components}>
+      <CheckoutClientProvider client={runtime.client}>
+        <CheckoutNavigateProvider navigate={runtime.navigate}>{children}</CheckoutNavigateProvider>
+      </CheckoutClientProvider>
+    </CheckoutComponentsProvider>
+  );
+}
+
+/**
+ * The shell plus the fetched `/config`, supplied once for a host that nests
+ * individual screens in its own layout.
+ *
+ * A host that passes its own `config` skips the fetch entirely — that is the
+ * seam a story, a harness page or a server-rendered host uses to STATE the
+ * protocol rather than round-trip for it.
+ */
+export function FlowsProvider({
+  runtime,
+  config,
+  children,
+}: {
+  runtime: FlowsRuntime;
+  config?: CheckoutProviderConfig | null;
+  children: ReactNode;
+}): JSX.Element {
+  const fetched = useFetchedConfig(runtime, config === undefined);
+  const value = useMemo<CheckoutConfigState>(
+    () => (config === undefined ? fetched : { config, pending: false }),
+    [config, fetched],
+  );
+  return (
+    <FlowsShell runtime={runtime}>
+      <FetchedConfigContext.Provider value={value}>{children}</FetchedConfigContext.Provider>
+    </FlowsShell>
+  );
+}

package/src/flows/screens-buyer.tsx

@@ -0,0 +1,170 @@
+/**
+ * The buyer-facing screens the factory binds (FUT-741), part one: choosing a
+ * method, stating who is paying, reusing a card, and the empty cart.
+ *
+ * Every one of them is a THIN binding. The behaviour still lives in the
+ * components this package already shipped; what is new is that the config,
+ * the transport, the scope and the slots arrive from the factory instead of
+ * from six props the host had to thread itself.
+ */
+import { Box } from "@mui/material";
+import { useEffect, useMemo, useState, type JSX } from "react";
+
+import { SavedCardsPicker, type SavedCard } from "../card";
+import { buyerFieldsFor } from "../components/checkout/buyer-fields";
+import { BuyerInfoForm } from "../components/checkout/buyer-info-form";
+import { EmptyCart as EmptyCartView } from "../components/checkout/checkout-steps";
+import {
+  cardPathAvailable,
+  offeredMethods,
+  selectableMethods,
+  usePreselectSoleMethod,
+} from "../components/checkout/method-capability";
+import { MethodPicker } from "../components/checkout/method-picker";
+import { PayerSummary as PayerSummaryView } from "../components/checkout/payer-summary";
+import type { BuyerInfo, PaymentMethod } from "../components/checkout/types";
+import { useCheckoutComponents } from "../components/checkout/ui";
+
+import { FlowsShell, useResolvedConfig, type FlowsRuntime } from "./runtime";
+import type { BuyerDetailsProps, CheckoutScreens } from "./types";
+
+function buildMethodChoice(runtime: FlowsRuntime): CheckoutScreens["MethodChoice"] {
+  function MethodChoiceBody({
+    value,
+    onChange,
+  }: {
+    value: PaymentMethod | null;
+    onChange: (method: PaymentMethod) => void;
+  }): JSX.Element {
+    const { config } = useResolvedConfig(runtime);
+    const offered = offeredMethods(config);
+    const cardUnavailable = !cardPathAvailable(config);
+    usePreselectSoleMethod(selectableMethods(offered, cardUnavailable), value, onChange);
+    return (
+      <MethodPicker
+        value={value}
+        onChange={onChange}
+        cardUnavailable={cardUnavailable}
+        offered={offered}
+      />
+    );
+  }
+  return function MethodChoice(props) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <MethodChoiceBody {...props} />
+      </FlowsShell>
+    );
+  };
+}
+
+function buildBuyerDetails(runtime: FlowsRuntime): CheckoutScreens["BuyerDetails"] {
+  function BuyerDetailsBody({
+    value,
+    onChange,
+    method,
+    onContinue,
+    error,
+  }: BuyerDetailsProps): JSX.Element {
+    const { Button, Text } = useCheckoutComponents();
+    const { config } = useResolvedConfig(runtime);
+    // ∩ method (FUT-595). An absent declaration degrades to CPF-required —
+    // never to "ask nothing", which is a 400 the buyer only meets after
+    // finishing the form.
+    const fields = useMemo(() => buyerFieldsFor(config?.chain, method), [config, method]);
+    return (
+      <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
+        <BuyerInfoForm value={value} onChange={onChange} fields={fields} fieldError={error} />
+        <Box>
+          <Button
+            variant="solid"
+            color="primary"
+            size="lg"
+            fullWidth
+            onClick={onContinue}
+            dataTestId="checkout-continue"
+          >
+            {runtime.copy.continueAction}
+          </Button>
+        </Box>
+        <Text variant="caption" size="xs" color="secondary" as="p">
+          Pagamento seguro
+        </Text>
+      </Box>
+    );
+  }
+  return function BuyerDetails(props) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <BuyerDetailsBody {...props} />
+      </FlowsShell>
+    );
+  };
+}
+
+function buildPayerSummary(runtime: FlowsRuntime): CheckoutScreens["PayerSummary"] {
+  return function PayerSummary({ buyer, onEdit }: { buyer: BuyerInfo; onEdit?: () => void }) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <PayerSummaryView name={buyer.name} taxId={buyer.taxId} onEdit={onEdit} />
+      </FlowsShell>
+    );
+  };
+}
+
+/** The vaulted instruments this store can actually charge (FUT-697 scoping). */
+function useScopedInstruments(runtime: FlowsRuntime): SavedCard[] {
+  const tenantSlug = runtime.useTenantSlug();
+  const [cards, setCards] = useState<SavedCard[]>([]);
+  useEffect(() => {
+    let active = true;
+    void runtime.client.listInstruments(tenantSlug).then((list) => {
+      if (active) setCards(list);
+    });
+    return () => {
+      active = false;
+    };
+  }, [runtime, tenantSlug]);
+  return cards;
+}
+
+function buildSavedCards(runtime: FlowsRuntime): CheckoutScreens["SavedCards"] {
+  function SavedCardsBody({
+    selection,
+    onSelect,
+  }: {
+    selection: string;
+    onSelect: (id: string) => void;
+  }): JSX.Element | null {
+    const savedCards = useScopedInstruments(runtime);
+    // Nothing to reuse renders nothing at all — an empty picker is a heading
+    // over a void, and the new-card form below it already says what to do.
+    if (savedCards.length === 0) return null;
+    return <SavedCardsPicker savedCards={savedCards} selection={selection} onSelect={onSelect} />;
+  }
+  return function SavedCards(props) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <SavedCardsBody {...props} />
+      </FlowsShell>
+    );
+  };
+}
+
+function buildEmptyCart(runtime: FlowsRuntime): CheckoutScreens["EmptyCart"] {
+  return function EmptyCart() {
+    return (
+      <FlowsShell runtime={runtime}>
+        <EmptyCartView onBack={runtime.config.ports.exitToCatalog} />
+      </FlowsShell>
+    );
+  };
+}
+
+export const buyerScreens = {
+  buildMethodChoice,
+  buildBuyerDetails,
+  buildPayerSummary,
+  buildSavedCards,
+  buildEmptyCart,
+};

package/src/flows/screens-hosted.tsx

@@ -0,0 +1,149 @@
+/**
+ * The hosted handover, as two SCREENS (FUT-741) — the leg of checkout that had
+ * none.
+ *
+ * Today a redirect provider's link (FUT-556) and a 3-DS challenge (FUT-698) are
+ * both a bare `window.location.assign` buried in a hook. When the navigation
+ * works, nobody notices. When it does not — a popup/redirect blocker, a slow
+ * DNS, an in-app webview that refuses cross-origin navigations, a buyer who
+ * taps back — the buyer is left looking at a page that says nothing, offers
+ * nothing, and has already raised a charge.
+ *
+ * So: an interstitial that PARKS the order first, then navigates, and renders
+ * an explicit link as the fallback the assign never had. And the return leg as
+ * a screen of its own, so "rehydrate the parked order and poll it to a terminal
+ * state" is something a host can mount at its return route rather than
+ * something that only happens if the buyer lands back on the exact component
+ * that left.
+ *
+ * ORDERING IS LOAD-BEARING: park, then navigate. The navigation may tear this
+ * SPA down at any point after it starts, and a return trip that finds nothing
+ * parked drops the buyer on a blank confirmation after they have paid.
+ */
+import { Box } from "@mui/material";
+import { useEffect, useState, type JSX } from "react";
+
+import { rememberHostedOrder, takeHostedOrder } from "../components/checkout/hosted-return";
+import type { CheckoutOrder, OrderStatus } from "../components/checkout/types";
+import { useCheckoutComponents } from "../components/checkout/ui";
+import { usePaymentPolling } from "../components/checkout/use-payment-polling";
+
+import { FlowsShell, type FlowsRuntime } from "./runtime";
+import type { CheckoutScreens } from "./types";
+
+/** Park the order, then navigate — exactly once, even under StrictMode. */
+function useHandover(payable: CheckoutOrder, url: string, navigate: (url: string) => void): void {
+  const [done, setDone] = useState(false);
+  useEffect(() => {
+    if (done) return;
+    setDone(true);
+    rememberHostedOrder(payable);
+    navigate(url);
+  }, [done, payable, url, navigate]);
+}
+
+function buildHostedHandoff(runtime: FlowsRuntime): CheckoutScreens["HostedHandoff"] {
+  function HostedHandoffBody({
+    url,
+    payable,
+    onCancel,
+  }: {
+    url: string;
+    payable: CheckoutOrder;
+    onCancel?: () => void;
+  }): JSX.Element {
+    const { Button, LoadingState, Text } = useCheckoutComponents();
+    const copy = runtime.copy;
+    useHandover(payable, url, runtime.navigate);
+    return (
+      <Box
+        data-testid="checkout-hosted-handoff"
+        sx={{ display: "flex", flexDirection: "column", gap: 2, alignItems: "center", py: 4 }}
+      >
+        <Text variant="heading" size="md" weight="bold" as="h2">
+          {copy.handoffTitle}
+        </Text>
+        <Text variant="body" size="sm" color="secondary" as="p">
+          {copy.handoffBody}
+        </Text>
+        <LoadingState variant="spinner" size="md" message="" dataTestId="checkout-hosted-waiting" />
+        {/* A real anchor, not a second scripted navigation: when the scripted
+            one was blocked, another one will be too. This is the affordance a
+            bare `location.assign` never had. */}
+        <a href={url} data-testid="checkout-hosted-link" rel="noreferrer">
+          {copy.handoffLink}
+        </a>
+        {onCancel ? (
+          <Button
+            variant="text"
+            color="neutral"
+            size="sm"
+            onClick={onCancel}
+            dataTestId="checkout-hosted-cancel"
+          >
+            {copy.handoffCancel}
+          </Button>
+        ) : null}
+      </Box>
+    );
+  }
+  return function HostedHandoff(props) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <HostedHandoffBody {...props} />
+      </FlowsShell>
+    );
+  };
+}
+
+function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn"] {
+  function HostedReturnBody({
+    onResolved,
+  }: {
+    onResolved: (status: OrderStatus) => void;
+  }): JSX.Element {
+    const { Alert, LoadingState } = useCheckoutComponents();
+    // Read-and-clear, once, on first render: the resumed view belongs to
+    // exactly one return trip.
+    const [parked] = useState(takeHostedOrder);
+    const { status } = usePaymentPolling(parked?.orderId ?? null, {
+      enabled: Boolean(parked),
+      intervalMs: runtime.config.polling?.intervalMs,
+    });
+
+    useEffect(() => {
+      if (status && status !== "AWAITING_PAYMENT") onResolved(status);
+    }, [status, onResolved]);
+
+    if (!parked) {
+      return (
+        <Alert
+          variant="info"
+          title={runtime.copy.returnPending}
+          description={runtime.copy.returnUnknown}
+          showIcon
+          data-testid="checkout-hosted-return-unknown"
+        />
+      );
+    }
+    return (
+      <Box data-testid="checkout-hosted-return" sx={{ py: 4 }}>
+        <LoadingState
+          variant="spinner"
+          size="md"
+          message={runtime.copy.returnPending}
+          dataTestId="checkout-hosted-return-waiting"
+        />
+      </Box>
+    );
+  }
+  return function HostedReturn(props) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <HostedReturnBody {...props} />
+      </FlowsShell>
+    );
+  };
+}
+
+export const hostedScreens = { buildHostedHandoff, buildHostedReturn };

package/src/flows/screens-pay.tsx

@@ -0,0 +1,178 @@
+/**
+ * The factory's payment screens (FUT-741), part two: taking the money, saying
+ * how it went, and saying plainly when the store cannot take it at all.
+ */
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { CardView } from "../components/checkout/card-view";
+import {
+  cardChain,
+  cardTokenization,
+} from "../components/checkout/method-capability";
+import { PaymentStatus as PaymentStatusView } from "../components/checkout/payment-status";
+import { PixView } from "../components/checkout/pix-view";
+import type { CheckoutOrder, OrderStatus } from "../components/checkout/types";
+import { useCheckoutComponents } from "../components/checkout/ui";
+
+import { FlowsShell, useResolvedConfig, type FlowsRuntime } from "./runtime";
+import type { CheckoutScreens } from "./types";
+
+function buildCardEntry(runtime: FlowsRuntime): CheckoutScreens["CardEntry"] {
+  function CardEntryBody({
+    payable,
+    onResolved,
+  }: {
+    payable: CheckoutOrder;
+    onResolved: (status: OrderStatus) => void;
+  }): JSX.Element {
+    const { config } = useResolvedConfig(runtime);
+    return (
+      <CardView
+        order={payable}
+        providerConfig={cardTokenization(config)}
+        // The chain VERBATIM (FUT-563). Nothing here filters, sorts or
+        // de-duplicates it: `tokensByProvider` is sent iff the SERVER-published
+        // chain has more than one entry, so any tidying done at this layer
+        // silently disables failover for the store it exists for.
+        providerChain={cardChain(config)}
+        tenantSlug={runtime.useTenantSlug()}
+        onResolved={onResolved}
+        pollIntervalMs={runtime.config.polling?.intervalMs}
+      />
+    );
+  }
+  return function CardEntry(props) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <CardEntryBody {...props} />
+      </FlowsShell>
+    );
+  };
+}
+
+function buildPixPayment(runtime: FlowsRuntime): CheckoutScreens["PixPayment"] {
+  return function PixPayment({
+    payable,
+    onResolved,
+  }: {
+    payable: CheckoutOrder;
+    onResolved: (status: OrderStatus) => void;
+  }) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <PixView
+          order={payable}
+          onResolved={onResolved}
+          pollIntervalMs={runtime.config.polling?.intervalMs}
+        />
+      </FlowsShell>
+    );
+  };
+}
+
+function buildPaymentStatus(runtime: FlowsRuntime): CheckoutScreens["PaymentStatus"] {
+  return function PaymentStatus({
+    status,
+    payable,
+  }: {
+    status: OrderStatus | null;
+    payable?: CheckoutOrder | null;
+  }) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <PaymentStatusView
+          status={status}
+          totalLabel={payable?.totalLabel ?? ""}
+          orderId={payable?.orderId}
+          onBackToMenu={runtime.config.ports.exitToCatalog}
+          paidExtra={runtime.config.confirmation?.extra}
+        />
+      </FlowsShell>
+    );
+  };
+}
+
+/**
+ * Whether this store can take money at all.
+ *
+ * An OR, never a swap. `chain.length === 0` is the library's own fact — the
+ * server published no enabled provider. The host's veto is a DIFFERENT fact: a
+ * store with a perfectly good chain that has switched online payments off. Move
+ * the decision entirely to the chain and that store starts offering a checkout
+ * it will not honour; move it entirely to the host and a store that simply
+ * never connected a provider gets the payment step it cannot serve.
+ *
+ * While the config is still in flight, neither fact is known — so nothing is
+ * refused. The unavailable screen is a statement about the store, and stating
+ * it early would be a lie a spinner never tells.
+ */
+export function storeCannotCharge(
+  config: { chain?: unknown[] } | null,
+  pending: boolean,
+  hostSaysPayable: boolean,
+): boolean {
+  if (pending) return false;
+  if (!hostSaysPayable) return true;
+  return config !== null && (config.chain?.length ?? 0) === 0;
+}
+
+function buildPaymentsUnavailable(
+  runtime: FlowsRuntime,
+): CheckoutScreens["PaymentsUnavailable"] {
+  function PaymentsUnavailableBody(): JSX.Element {
+    const { Alert, Button } = useCheckoutComponents();
+    const { remedy } = runtime.useAvailability();
+    const copy = runtime.copy;
+    if (!remedy) {
+      return (
+        <Box
+          sx={{ display: "flex", flexDirection: "column", gap: 2 }}
+          data-testid="checkout-payments-disabled"
+        >
+          <Alert
+            variant="info"
+            title={copy.unavailableTitle}
+            description={copy.unavailableBody}
+            showIcon
+          />
+        </Box>
+      );
+    }
+    return (
+      <Box
+        sx={{ display: "flex", flexDirection: "column", gap: 2 }}
+        data-testid="checkout-payments-remedy"
+      >
+        <Alert
+          variant="info"
+          title={copy.unavailableWithRemedyTitle}
+          description={copy.unavailableWithRemedyBody}
+          showIcon
+        />
+        <Button
+          variant="solid"
+          size="lg"
+          onClick={remedy.onSelect}
+          dataTestId="checkout-payments-remedy-action"
+        >
+          {remedy.label}
+        </Button>
+      </Box>
+    );
+  }
+  return function PaymentsUnavailable() {
+    return (
+      <FlowsShell runtime={runtime}>
+        <PaymentsUnavailableBody />
+      </FlowsShell>
+    );
+  };
+}
+
+export const payScreens = {
+  buildCardEntry,
+  buildPixPayment,
+  buildPaymentStatus,
+  buildPaymentsUnavailable,
+};