@12-apps/payments-frontend 1.0.0 → 1.2.0

package/src/components/checkout/__tests__/second-host.test.tsx

@@ -0,0 +1,86 @@
+// @vitest-environment jsdom
+/**
+ * The second-host proof (FUT-564 acceptance).
+ *
+ * This package's dependency graph contains NO `@12-apps/ui` — it is not even
+ * resolvable from here — so a green run of this suite IS the proof that a host
+ * without this repo's design system can mount the buyer checkout: every pixel
+ * below renders through the raw-MUI default slots (`mui-defaults.tsx`),
+ * because no `components` prop is passed and no provider sits above the flow.
+ *
+ * The walk is the buyer's own: Dados (CPF form, consent checkbox, pay bar) →
+ * Pagamento (method picker) → the card form, with the order raised through the
+ * host port. The load-bearing test ids must survive the default slots too —
+ * they are the same hooks the storefront journeys click.
+ */
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { CheckoutFlow } from "../checkout-flow";
+import type { CheckoutOrder, CreateOrderRequest, CreateOrderResult } from "../types";
+
+afterEach(cleanup);
+
+const CARD_ORDER: CheckoutOrder = {
+  orderId: "o-2nd-host",
+  status: "AWAITING_PAYMENT",
+  method: "CARD",
+  totalCents: 1000,
+  subtotalCents: 1000,
+  discountTotalCents: 0,
+  appliedDiscounts: [],
+  totalLabel: "R$ 10,00",
+};
+
+/** A valid CPF (passes the client-side check digits). */
+const VALID_CPF = "52998224725";
+
+describe("CheckoutFlow with no design system present (raw-MUI default slots)", () => {
+  it("walks Dados → Pagamento → card form through the default slots", async () => {
+    const createOrder = vi.fn<(input: CreateOrderRequest) => Promise<CreateOrderResult>>(
+      async () => ({ ok: true, data: CARD_ORDER }),
+    );
+
+    render(
+      <CheckoutFlow
+        cart={{ empty: false, totalLabel: "R$ 10,00", totalItems: 1 }}
+        createOrder={createOrder}
+        onExitToMenu={vi.fn()}
+      />,
+    );
+
+    // Dados renders through the defaults: stepper, CPF field, consent, pay bar.
+    expect(screen.getByTestId("checkout-stepper")).toBeTruthy();
+    expect(screen.getByTestId("buyer-save-profile")).toBeTruthy();
+    expect(screen.getByTestId("checkout-pay-bar")).toBeTruthy();
+
+    fireEvent.change(screen.getByTestId("buyer-cpf"), { target: { value: VALID_CPF } });
+    fireEvent.click(screen.getByTestId("checkout-continue"));
+
+    // Pagamento: the method picker, with both in-browser methods on offer.
+    await waitFor(() => expect(screen.getByTestId("checkout-method")).toBeTruthy());
+    expect(screen.getByTestId("checkout-method-PIX")).toBeTruthy();
+
+    // Choosing card auto-raises the order through the HOST port…
+    fireEvent.click(screen.getByTestId("checkout-method-CARD"));
+    await waitFor(() => expect(createOrder).toHaveBeenCalledTimes(1));
+    expect(createOrder.mock.calls[0]?.[0]).toMatchObject({ method: "CARD", saveProfile: true });
+
+    // …and the card form renders, again through the default slots.
+    await waitFor(() => expect(screen.getByTestId("card-number")).toBeTruthy());
+    expect(screen.getByTestId("card-holder")).toBeTruthy();
+    expect(screen.getByTestId("card-pay")).toBeTruthy();
+  });
+
+  it("shows the empty-cart state for a cart with nothing to pay", () => {
+    render(
+      <CheckoutFlow
+        cart={{ empty: true, totalLabel: "R$ 0,00", totalItems: 0 }}
+        createOrder={vi.fn()}
+        onExitToMenu={vi.fn()}
+      />,
+    );
+
+    expect(screen.getByTestId("checkout-empty")).toBeTruthy();
+  });
+});

package/src/components/checkout/buyer-info-form.tsx

@@ -0,0 +1,138 @@
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { formatCpf, validateCpf } from "../../card";
+
+import type { BuyerField, BuyerInfo } from "./types";
+import { useCheckoutComponents } from "./ui";
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** A server-flagged field error (which field + message), or null. */
+type FieldError = { field: BuyerField; message: string } | null;
+
+interface BuyerFieldErrors {
+  cpf?: string;
+  email?: string;
+  name?: string;
+  phone?: string;
+}
+
+/**
+ * Per-field error, overlaying any server-flagged error on top of the local format
+ * checks — so a failed "pay" attempt highlights the exact input.
+ */
+function deriveErrors(value: BuyerInfo, fieldError: FieldError): BuyerFieldErrors {
+  const override = (field: BuyerField): string | undefined =>
+    fieldError?.field === field ? fieldError.message : undefined;
+  const localEmail =
+    value.email && !EMAIL_PATTERN.test(value.email) ? "E-mail inválido." : undefined;
+  return {
+    cpf: override("cpf") ?? (value.taxId ? validateCpf(value.taxId) : undefined),
+    email: override("email") ?? localEmail,
+    name: override("name"),
+    phone: override("phone"),
+  };
+}
+
+/**
+ * Buyer contact at checkout. CPF is REQUIRED (PagBank needs it for the charge);
+ * name, e-mail and phone are optional and only used for the receipt. A provided
+ * e-mail is format-checked. Fully controlled by the parent checkout state.
+ */
+export function BuyerInfoForm({
+  value,
+  onChange,
+  fieldError,
+}: {
+  value: BuyerInfo;
+  onChange: (buyer: BuyerInfo) => void;
+  fieldError?: FieldError;
+}): JSX.Element {
+  const { Input, Text } = useCheckoutComponents();
+  const errors = deriveErrors(value, fieldError ?? null);
+
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <Text variant="caption" size="xs" color="secondary" as="p">
+        Informe seu CPF (obrigatório para o pagamento). Nome, e-mail e telefone são
+        opcionais — usados apenas para o comprovante.
+      </Text>
+
+      <Input
+        label="CPF"
+        type="text"
+        inputMode="numeric"
+        variant="outlined"
+        size="md"
+        fullWidth
+        required
+        autoComplete="off"
+        placeholder="000.000.000-00"
+        value={value.taxId ?? ""}
+        error={Boolean(errors.cpf)}
+        helperText={errors.cpf}
+        onChange={(event) => onChange({ ...value, taxId: formatCpf(event.target.value) })}
+        data-testid="buyer-cpf"
+      />
+
+      <OptionalContactFields value={value} onChange={onChange} errors={errors} />
+    </Box>
+  );
+}
+
+/** The optional receipt fields (name / e-mail / phone). */
+function OptionalContactFields({
+  value,
+  onChange,
+  errors,
+}: {
+  value: BuyerInfo;
+  onChange: (buyer: BuyerInfo) => void;
+  errors: BuyerFieldErrors;
+}): JSX.Element {
+  const { Input } = useCheckoutComponents();
+  return (
+    <>
+      <Input
+        label="Nome"
+        type="text"
+        variant="outlined"
+        size="md"
+        fullWidth
+        autoComplete="name"
+        value={value.name ?? ""}
+        error={Boolean(errors.name)}
+        helperText={errors.name}
+        onChange={(event) => onChange({ ...value, name: event.target.value })}
+        data-testid="buyer-name"
+      />
+      <Input
+        label="E-mail"
+        type="email"
+        variant="outlined"
+        size="md"
+        fullWidth
+        autoComplete="email"
+        value={value.email ?? ""}
+        error={Boolean(errors.email)}
+        helperText={errors.email}
+        onChange={(event) => onChange({ ...value, email: event.target.value })}
+        data-testid="buyer-email"
+      />
+      <Input
+        label="Telefone"
+        type="tel"
+        variant="outlined"
+        size="md"
+        fullWidth
+        autoComplete="tel"
+        value={value.phone ?? ""}
+        error={Boolean(errors.phone)}
+        helperText={errors.phone}
+        onChange={(event) => onChange({ ...value, phone: event.target.value })}
+        data-testid="buyer-phone"
+      />
+    </>
+  );
+}

package/src/components/checkout/card-view.tsx

@@ -0,0 +1,128 @@
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import {
+  CardPayBar,
+  NewCardForm,
+  SavedCardsPicker,
+  type CardTokenizationConfig,
+} from "../../card";
+
+import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
+import { useCheckoutComponents } from "./ui";
+import { useCardCheckout } from "./use-card-checkout";
+
+/**
+ * Post-submit confirmation state, error > timeout > spinner (FUT-191): a poll
+ * failure is a danger Alert, the healthy-poll cap elapsing is a warning (the
+ * order stays AWAITING server-side and is recoverable by webhook/reconcile/
+ * backfill), and otherwise the — now bounded — confirmation spinner shows.
+ */
+function SubmittedState({
+  pollError,
+  pollTimedOut,
+}: {
+  pollError: string | null;
+  pollTimedOut: boolean;
+}): JSX.Element {
+  const { Alert, LoadingState } = useCheckoutComponents();
+  if (pollError) {
+    return (
+      <Alert
+        variant="danger"
+        title="Não foi possível confirmar o pagamento"
+        description={pollError}
+        showIcon
+        data-testid="card-poll-error"
+      />
+    );
+  }
+  if (pollTimedOut) {
+    return (
+      <Alert
+        variant="warning"
+        title="O pagamento está demorando mais que o esperado"
+        description="Você pode aguardar ou verificar seu pedido em instantes — não realize um novo pagamento."
+        showIcon
+        data-testid="card-poll-timeout"
+      />
+    );
+  }
+  return (
+    <LoadingState
+      variant="spinner"
+      size="md"
+      message="Processando pagamento…"
+      dataTestId="card-processing"
+    />
+  );
+}
+
+/**
+ * Card payment view (FUT-58). Card data is validated + formatted client-side, then
+ * tokenized (mock PagBank JS SDK) so the PAN never reaches our server; only the
+ * token is charged. Supports reusing a saved card and opting to save a new one for
+ * future purchases. On an accepted charge it polls for the async confirmation,
+ * then bubbles the terminal status up to the parent. All state + the submit
+ * handler live in {@link useCardCheckout}; this component is presentational.
+ *
+ * Tip: the `4000 0000 0000 0002` test card always declines.
+ */
+export function CardView({
+  order,
+  buyer = {},
+  providerConfig,
+  tenantSlug,
+  onResolved,
+  pollIntervalMs = 2500,
+}: {
+  order: CheckoutOrder;
+  buyer?: BuyerInfo;
+  /** The active provider's tokenization protocol + key (FUT-697). */
+  providerConfig: CardTokenizationConfig;
+  /** Scopes the saved-card list to cards the store's provider can charge. */
+  tenantSlug?: string;
+  onResolved: (status: OrderStatus) => void;
+  pollIntervalMs?: number;
+}): JSX.Element {
+  const { Alert, Text } = useCheckoutComponents();
+  const cc = useCardCheckout(order, buyer, providerConfig, onResolved, pollIntervalMs, tenantSlug);
+
+  if (cc.submitted) {
+    return <SubmittedState pollError={cc.pollError} pollTimedOut={cc.pollTimedOut} />;
+  }
+
+  return (
+    <Box data-testid="card-view" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <Text variant="heading" size="md" weight="bold" as="h2">
+        Pague com cartão
+      </Text>
+
+      {cc.savedCards.length > 0 ? (
+        <SavedCardsPicker
+          savedCards={cc.savedCards}
+          selection={cc.selection}
+          onSelect={cc.setSelection}
+        />
+      ) : null}
+
+      {cc.usingNewCard ? (
+        <NewCardForm
+          card={cc.card}
+          fieldErrors={cc.fieldErrors}
+          brand={cc.brand}
+          saveCard={cc.saveCard}
+          setCard={cc.setCard}
+          setFieldErrors={cc.setFieldErrors}
+          onSaveCardChange={cc.setSaveCard}
+        />
+      ) : null}
+
+      {cc.error ? (
+        <Alert variant="danger" title="Não foi possível pagar" description={cc.error} showIcon data-testid="card-error" />
+      ) : null}
+
+      <CardPayBar totalLabel={order.totalLabel} submitting={cc.submitting} onPay={() => void cc.handlePay()} />
+    </Box>
+  );
+}

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

@@ -0,0 +1,201 @@
+import { Box } from "@mui/material";
+import type { JSX, ReactNode } from "react";
+
+import { DadosStep, EmptyCart, PaymentStep } from "./checkout-steps";
+import { ArrowBackIcon } from "./icons";
+import { PaymentStatus } from "./payment-status";
+import type { BuyerInfo, CheckoutProviderConfig, ComandaCheckout } from "./types";
+import { CheckoutComponentsProvider, useCheckoutComponents, type CheckoutComponents } from "./ui";
+import { useCheckoutController, type CheckoutHostPorts } from "./use-checkout-controller";
+
+const STEPPER_STEPS = [
+  { id: "dados", label: "Dados" },
+  { id: "payment", label: "Pagamento" },
+  { id: "status", label: "Confirmação" },
+];
+
+/** What the flow reads off the host's cart — display facts, never money math. */
+export interface CheckoutCartView {
+  /** Nothing to check out (cart mode only; a comanda settlement ignores it). */
+  empty: boolean;
+  totalLabel: string;
+  totalItems: number;
+  /** Host-rendered discount itemization under the pay-bar total (FUT-246). */
+  discountLines?: ReactNode;
+}
+
+/**
+ * The full buyer checkout, mounted by a host in one line (FUT-564): the
+ * three-step flow — Dados → Pagamento → Confirmação — with the payment step
+ * speaking the store's ACTIVE provider protocol (PagBank PIX + card, Stone
+ * card, InfinitePay hosted redirect) against the host-mounted `/api/checkout*`
+ * surface. Cart, catalog, comanda and order CREATION stay in the host and
+ * arrive through {@link CheckoutHostPorts} + {@link CheckoutCartView};
+ * pixels render through the slot contract (`components`, see `ui.tsx`).
+ */
+export interface CheckoutFlowProps extends CheckoutHostPorts {
+  /** The host's cart, reduced to what the flow displays. */
+  cart: CheckoutCartView;
+  defaultBuyer?: BuyerInfo;
+  /** Present ⇒ this checkout settles a comanda, not the cart (FUT-comandas). */
+  comanda?: ComandaCheckout | null;
+  /** The buyer has a CPF saved ⇒ open on Pagamento, skipping Dados (FUT-465). */
+  taxIdOnFile?: boolean;
+  /** The store's active payment protocol (FUT-697); absent while loading. */
+  providerConfig?: CheckoutProviderConfig | null;
+  /** Scopes the saved-card list to the store being paid. */
+  tenantSlug?: string;
+  /** Host content shown on the paid confirmation (the storefront's install invite). */
+  confirmationExtra?: ReactNode;
+  /** Design-system slots; unfilled slots render the raw-MUI defaults. */
+  components?: Partial<CheckoutComponents>;
+}
+
+/** The pay-bar total override when settling a comanda (else the cart's own totals). */
+function comandaTotalOverride(
+  comanda: ComandaCheckout | null | undefined,
+): { label: string; items: number } | undefined {
+  return comanda ? { label: comanda.totalLabel, items: comanda.totalItems } : undefined;
+}
+
+/**
+ * The facts the confirmation screen shows beside the total (FUT-593): which
+ * order this was, and where its receipt went. Its own function so the optional
+ * order stays out of the flow body, which sits at its complexity ceiling.
+ */
+function confirmationFacts(
+  order: { orderId: string } | null,
+  buyer: BuyerInfo,
+): { orderId?: string; buyerEmail?: string } {
+  return { orderId: order?.orderId, buyerEmail: buyer.email };
+}
+
+/** The confirmation total: the created order's, else the comanda scope's, else the cart's. */
+function statusTotalLabel(
+  order: { totalLabel: string } | null,
+  comanda: ComandaCheckout | null | undefined,
+  cart: { totalLabel: string },
+): string {
+  return order?.totalLabel ?? comanda?.totalLabel ?? cart.totalLabel;
+}
+
+/**
+ * The slim checkout header — the flow's only nav: a step-aware back link
+ * (Pagamento → Dados, else the menu).
+ *
+ * Deliberately nothing else. A "limpar carrinho" trash used to sit on the right
+ * of the Dados step; it was removed because emptying the cart is a CART action
+ * and belongs where the cart is edited — the drawer, which already offers a
+ * 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 {
+  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"}
+      </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 {
+  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" />
+    </Box>
+  );
+}
+
+/**
+ * The 3-step flow body, below the slot provider. Ported from the storefront's
+ * app-local checkout (FUT-564): the tenant cart provider lives in the HOST's
+ * chrome (reduced to {@link CheckoutCartView} here), and the provider SDK +
+ * card public key are loaded lazily by the card path (order-scoped REST).
+ */
+function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
+  const { cart, defaultBuyer, comanda, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, ...ports } = props;
+  const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile);
+
+  // A comanda settlement pays already-sent kitchen items — the cart is
+  // legitimately empty here, so the empty-cart guard only applies to cart mode.
+  //
+  // The guard cannot key on the Dados step any more: skipping it (FUT-465) makes
+  // Pagamento the first screen, so an empty cart would otherwise reach the
+  // 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 (!comanda && cart.empty && !c.order && c.step !== "status") {
+    return <EmptyCart onBack={c.goToMenu} />;
+  }
+
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: { xs: 2, sm: 3 } }}>
+      <CheckoutHeader step={c.step} onBack={c.back} />
+
+      <ProgressHeader step={c.step} completed={c.completed} />
+
+      {c.step === "dados" ? (
+        <DadosStep
+          buyer={c.buyer}
+          onBuyerChange={c.setBuyer}
+          saveProfile={c.saveProfile}
+          onSaveProfileChange={c.setSaveProfile}
+          createError={c.createError}
+          errorField={c.errorField}
+          onContinue={c.goToPayment}
+          cartTotals={cart}
+          discountLines={cart.discountLines}
+          totalOverride={comandaTotalOverride(comanda)}
+        />
+      ) : null}
+
+      {c.step === "payment" ? (
+        <PaymentStep
+          method={c.method}
+          onMethodChange={c.setMethod}
+          order={c.order}
+          buyer={c.buyer}
+          creating={c.creating}
+          createError={c.createError}
+          errorField={c.errorField}
+          onGenerate={(chosen) => void c.startPayment(chosen)}
+          onUseEmail={c.payWithEmail}
+          // Set only for a skipped-Dados flow (the controller decides); the
+          // payer block hides itself when it is absent.
+          onEditBuyer={c.editBuyer}
+          providerConfig={providerConfig}
+          tenantSlug={tenantSlug}
+          onResolved={c.handleResolved}
+        />
+      ) : null}
+
+      {c.step === "status" ? (
+        <PaymentStatus
+          status={c.finalStatus}
+          totalLabel={statusTotalLabel(c.order, comanda, cart)}
+          {...confirmationFacts(c.order, c.buyer)}
+          onRetry={c.retry}
+          onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
+          onBackToMenu={c.goToMenu}
+          paidExtra={confirmationExtra}
+        />
+      ) : null}
+    </Box>
+  );
+}
+
+/**
+ * The one-line mount: fills the design-system slots, then renders the flow.
+ * `<CheckoutFlow cart={...} createOrder={...} onExitToMenu={...} />` is a
+ * complete buyer checkout; everything else is optional.
+ */
+export function CheckoutFlow({ components, ...props }: CheckoutFlowProps): JSX.Element {
+  return (
+    <CheckoutComponentsProvider components={components}>
+      <CheckoutFlowBody {...props} />
+    </CheckoutComponentsProvider>
+  );
+}