@12-apps/payments-frontend 1.0.0 → 1.2.0

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

@@ -0,0 +1,256 @@
+import { Box } from "@mui/material";
+import type { JSX, ReactNode } from "react";
+
+import { CheckCircleOutlineIcon, ErrorOutlineIcon, ScheduleIcon } from "./icons";
+import type { OrderStatus } from "./types";
+import { useCheckoutComponents } from "./ui";
+
+/**
+ * The last screen of checkout.
+ *
+ * It used to be a status page: the heading said "Pagamento" — the step the
+ * buyer had just finished — with a small success strip underneath and a chip
+ * repeating what the strip already said. Three things were wrong with that for
+ * somebody who has just handed over money:
+ *
+ *  - it never said the thing they came for. "Pedido confirmado" is the outcome;
+ *    "Pagamento" is a step, and reading it back after paying leaves the buyer
+ *    wondering whether anything happened.
+ *  - the confirmation carried no facts they could use later — no reference to
+ *    quote, no note of where the receipt went.
+ *  - success and failure looked the same shape, so the screen's most important
+ *    distinction was carried only by a small coloured strip.
+ *
+ * Each state now leads with its own outcome, and the paid one carries the
+ * amount, the order reference and the receipt's destination.
+ *
+ * The FLOW is untouched: same steps, same actions, same polling. Only what the
+ * screen says and how it is arranged has changed.
+ */
+
+/** Everything the hero block needs, per outcome. */
+interface Outcome {
+  heading: string;
+  support: string;
+  icon: JSX.Element;
+  /** Semantic theme token — never a raw colour. */
+  tone: "success" | "danger" | "warning" | "neutral";
+}
+
+const OUTCOME: Record<OrderStatus, Outcome> = {
+  PAID: {
+    heading: "Pedido confirmado",
+    support: "Recebemos seu pagamento e já registramos o pedido.",
+    icon: <CheckCircleOutlineIcon fontSize="large" />,
+    tone: "success",
+  },
+  AWAITING_PAYMENT: {
+    heading: "Confirmando seu pagamento",
+    support: "Isso costuma levar alguns segundos. Pode deixar esta tela aberta.",
+    icon: <ScheduleIcon fontSize="large" />,
+    tone: "neutral",
+  },
+  FAILED: {
+    heading: "Pagamento não concluído",
+    // Said plainly and first: the fear on this screen is having been charged
+    // for an order that failed.
+    support: "Nenhum valor foi cobrado. Você pode tentar novamente.",
+    icon: <ErrorOutlineIcon fontSize="large" />,
+    tone: "danger",
+  },
+  EXPIRED: {
+    heading: "O código expirou",
+    support: "Nenhum valor foi cobrado. Gere um novo código para continuar.",
+    icon: <ScheduleIcon fontSize="large" />,
+    tone: "warning",
+  },
+};
+
+const TONE_COLOR: Record<Outcome["tone"], string> = {
+  success: "success.main",
+  danger: "error.main",
+  warning: "warning.main",
+  neutral: "text.secondary",
+};
+
+/**
+ * The buyer's quotable reference.
+ *
+ * The order id is a uuid — unreadable over a phone call and impossible to copy
+ * by eye — so the screen shows its first block, uppercased. It is the real id's
+ * own prefix rather than a second number, so support can still find the order
+ * from what the buyer reads out.
+ */
+function orderReference(orderId: string): string {
+  return orderId.replace(/-/g, "").slice(0, 8).toUpperCase();
+}
+
+/** The headline block: icon, outcome, and one supporting line. */
+function OutcomeHero({ status }: { status: OrderStatus }): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const outcome = OUTCOME[status];
+  return (
+    <Box
+      // `payment-paid` is load-bearing for the storefront journeys — it is how
+      // they assert the buyer actually got there.
+      data-testid={status === "PAID" ? "payment-paid" : `payment-${status.toLowerCase()}`}
+      sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 1, textAlign: "center" }}
+    >
+      <Box sx={{ color: TONE_COLOR[outcome.tone], display: "flex" }}>{outcome.icon}</Box>
+      <Text variant="heading" size="md" weight="bold" as="h2">
+        {outcome.heading}
+      </Text>
+      <Text variant="body" size="sm" as="p" style={{ opacity: 0.75 }}>
+        {outcome.support}
+      </Text>
+    </Box>
+  );
+}
+
+/** One label/value row of the paid receipt block. */
+function Fact({ label, value, testId }: { label: string; value: string; testId?: string }): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  return (
+    <Box sx={{ display: "flex", justifyContent: "space-between", alignItems: "baseline", gap: 2 }}>
+      <Text variant="body" size="sm" as="span" style={{ opacity: 0.75 }}>
+        {label}
+      </Text>
+      <Text variant="body" size="sm" weight="bold" as="span" data-testid={testId}>
+        {value}
+      </Text>
+    </Box>
+  );
+}
+
+/**
+ * What a paid buyer will want later: how much left their account, which order
+ * it was, and where the receipt went. Rendered only for PAID — on any other
+ * outcome these facts are either untrue or not yet knowable.
+ */
+function PaidFacts({
+  totalLabel,
+  orderId,
+  buyerEmail,
+}: {
+  totalLabel: string;
+  orderId?: string;
+  buyerEmail?: string;
+}): JSX.Element {
+  return (
+    <Box
+      data-testid="payment-receipt"
+      sx={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 1,
+        p: 2,
+        borderRadius: 2,
+        bgcolor: "action.hover",
+      }}
+    >
+      <Fact label="Valor pago" value={totalLabel} testId="payment-amount" />
+      {orderId ? (
+        <Fact label="Pedido" value={`#${orderReference(orderId)}`} testId="payment-reference" />
+      ) : null}
+      {buyerEmail ? <Fact label="Comprovante enviado para" value={buyerEmail} /> : null}
+    </Box>
+  );
+}
+
+/** The next-action row: retry / regenerate for failures, always back-to-menu. */
+function StatusActions({
+  status,
+  onRetry,
+  onRegenerate,
+  onBackToMenu,
+}: {
+  status: OrderStatus;
+  onRetry?: () => void;
+  onRegenerate?: () => void;
+  onBackToMenu: () => void;
+}): JSX.Element {
+  const { Button } = useCheckoutComponents();
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
+      {status === "FAILED" && onRetry ? (
+        <Button variant="solid" color="primary" size="lg" onClick={onRetry} dataTestId="payment-retry">
+          Tentar novamente
+        </Button>
+      ) : null}
+      {status === "EXPIRED" && onRegenerate ? (
+        <Button variant="solid" color="primary" size="lg" onClick={onRegenerate} dataTestId="payment-regenerate">
+          Gerar novo código
+        </Button>
+      ) : null}
+      <Button
+        // Full width and last, so the thumb lands on the same place in every
+        // outcome instead of hunting a button that moves with the state.
+        variant={status === "PAID" ? "solid" : "outline"}
+        color={status === "PAID" ? "primary" : "neutral"}
+        size="lg"
+        onClick={onBackToMenu}
+        dataTestId="payment-back-to-menu"
+      >
+        Voltar ao cardápio
+      </Button>
+    </Box>
+  );
+}
+
+export function PaymentStatus({
+  status,
+  totalLabel,
+  orderId,
+  buyerEmail,
+  onRetry,
+  onRegenerate,
+  onBackToMenu,
+  paidExtra,
+}: {
+  status: OrderStatus | null;
+  totalLabel: string;
+  /** The created order, when there is one — absent before the charge is raised. */
+  orderId?: string;
+  /** Where the receipt was sent, when known. */
+  buyerEmail?: string;
+  onRetry?: () => void;
+  onRegenerate?: () => void;
+  onBackToMenu: () => void;
+  /**
+   * Host content rendered under the paid receipt, and ONLY on PAID — the
+   * storefront puts its PWA install invite here (FUT-640): a customer who has
+   * just completed an order knows exactly what they would be installing, which
+   * is the difference between an offer and an interruption.
+   */
+  paidExtra?: ReactNode;
+}): JSX.Element {
+  const { LoadingState } = useCheckoutComponents();
+  const effective: OrderStatus = status ?? "AWAITING_PAYMENT";
+
+  return (
+    <Box
+      data-testid="payment-status"
+      data-status={effective}
+      sx={{ display: "flex", flexDirection: "column", gap: 3, alignItems: "stretch", py: 2 }}
+    >
+      <OutcomeHero status={effective} />
+
+      {effective === "PAID" ? (
+        <PaidFacts totalLabel={totalLabel} orderId={orderId} buyerEmail={buyerEmail} />
+      ) : null}
+
+      {effective === "PAID" ? paidExtra : null}
+
+      {effective === "AWAITING_PAYMENT" ? (
+        <LoadingState variant="spinner" size="md" message="" dataTestId="payment-pending" />
+      ) : null}
+
+      <StatusActions
+        status={effective}
+        onRetry={onRetry}
+        onRegenerate={onRegenerate}
+        onBackToMenu={onBackToMenu}
+      />
+    </Box>
+  );
+}

package/src/components/checkout/payments-unavailable.tsx

@@ -0,0 +1,79 @@
+/**
+ * What a shopper sees when the store cannot take money online.
+ *
+ * A store with no active payment provider used to render the full payment step
+ * — PIX and Cartão side by side — and only fail at order creation, with a
+ * "tente novamente em instantes" that no amount of retrying could fix. The
+ * store is not momentarily busy; it simply does not charge online.
+ *
+ * The remedy depends on how the store operates, so the two cases are answered
+ * differently rather than with one vague apology:
+ *
+ *   waiter reachable — someone is there to take payment: offer the waiter.
+ *   not reachable    — nobody is; say plainly that this store does not charge
+ *                      online, so the shopper stops waiting for a payment screen.
+ *
+ * "Reachable" is a property of THIS shopper, not of the store: a mesas
+ * restaurant also serves the balcão, and a shopper with no mesa has no comanda
+ * for a waiter to close. Offering them the waiter sent them to a comanda screen
+ * whose own mesa gate bounced them straight back to the menu — a dead end
+ * dressed up as the remedy. So the caller decides, from the shopper's mesa.
+ */
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { useCheckoutComponents } from "./ui";
+
+interface PaymentsUnavailableProps {
+  /**
+   * Whether THIS shopper can settle with a waiter — mesas on AND a mesa of
+   * their own. Decides which remedy is offered.
+   */
+  waiterAvailable: boolean;
+  /** Called when the shopper asks for a waiter. Omitted ⇒ no button. */
+  onCallWaiter?: () => void;
+  /** True while the waiter request is in flight. */
+  calling?: boolean;
+}
+
+export function PaymentsUnavailable({
+  waiterAvailable,
+  onCallWaiter,
+  calling = false,
+}: PaymentsUnavailableProps): JSX.Element {
+  const { Alert, Button } = useCheckoutComponents();
+  if (!waiterAvailable) {
+    return (
+      <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }} data-testid="checkout-payments-disabled">
+        <Alert
+          variant="info"
+          title="Pagamento online indisponível"
+          description="Esta loja não recebe pagamentos pelo site. Combine o pagamento diretamente com a loja para concluir seu pedido."
+          showIcon
+        />
+      </Box>
+    );
+  }
+
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }} data-testid="checkout-call-waiter">
+      <Alert
+        variant="info"
+        title="Pagamento com o garçom"
+        description="Esta loja não recebe pagamentos pelo site. Chame o garçom para fechar a conta na mesa."
+        showIcon
+      />
+      {onCallWaiter ? (
+        <Button
+          variant="solid"
+          size="lg"
+          disabled={calling}
+          onClick={onCallWaiter}
+          dataTestId="checkout-call-waiter-button"
+        >
+          {calling ? "Chamando..." : "Chamar garçom"}
+        </Button>
+      ) : null}
+    </Box>
+  );
+}

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

@@ -0,0 +1,179 @@
+import { Box } from "@mui/material";
+import { useEffect, useState, type JSX } from "react";
+import QRCode from "react-qr-code";
+
+import { ContentCopyIcon } from "./icons";
+import type { CheckoutOrder, OrderStatus, PixCharge } from "./types";
+import { useCheckoutComponents } from "./ui";
+import { usePaymentPolling } from "./use-payment-polling";
+
+/**
+ * PIX payment view: a scannable QR (rendered client-side from the "copia e cola"
+ * payload), the copyable code, and a live pending indicator. Polls the order in
+ * the background and hands a terminal status up to the parent, which then shows
+ * the payment-status screen.
+ */
+
+/** The copyable "copia e cola" strip with its copy button. */
+function PixCodeBox({ pix }: { pix: PixCharge }): JSX.Element {
+  const { Button, Text } = useCheckoutComponents();
+  const [copied, setCopied] = useState(false);
+
+  const copyCode = async (): Promise<void> => {
+    try {
+      await navigator.clipboard?.writeText(pix.copyPaste);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      /* clipboard unavailable — the code is still visible to copy manually */
+    }
+  };
+
+  return (
+    <Box
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        gap: 1,
+        width: "100%",
+        maxWidth: 420,
+        p: 1,
+        borderRadius: 1,
+        border: "1px solid",
+        borderColor: "divider",
+        bgcolor: "background.default",
+      }}
+    >
+      <Text
+        variant="code"
+        size="xs"
+        as="span"
+        data-testid="pix-code"
+        style={{ flex: 1, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}
+      >
+        {pix.copyPaste}
+      </Text>
+      <Button
+        variant="outline"
+        color="neutral"
+        size="sm"
+        icon={<ContentCopyIcon fontSize="small" />}
+        onClick={() => {
+          void copyCode();
+        }}
+        dataTestId="pix-copy"
+      >
+        {copied ? "Copiado!" : "Copiar"}
+      </Button>
+    </Box>
+  );
+}
+
+/** The live footer: poll error, or the pulsing "awaiting payment" indicator. */
+function PixPollFooter({ error }: { error: string | null }): JSX.Element {
+  const { Alert, Text } = useCheckoutComponents();
+  if (error) {
+    return (
+      <Alert
+        variant="danger"
+        title="Não foi possível confirmar o pagamento"
+        description={error}
+        showIcon
+        data-testid="pix-poll-error"
+      />
+    );
+  }
+  return (
+    <Box sx={{ display: "flex", alignItems: "center", gap: 1, color: "text.secondary" }}>
+      <LoadingDot />
+      <Text variant="caption" size="xs" color="secondary" as="span" data-testid="pix-awaiting">
+        Aguardando pagamento…
+      </Text>
+    </Box>
+  );
+}
+
+export function PixView({
+  order,
+  onResolved,
+  pollIntervalMs = 2500,
+}: {
+  order: CheckoutOrder;
+  onResolved: (status: OrderStatus) => void;
+  pollIntervalMs?: number;
+}): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const { status, error } = usePaymentPolling(order.orderId, { intervalMs: pollIntervalMs });
+
+  // Bubble a terminal status up once, so the parent can advance to the status step.
+  useEffect(() => {
+    if (status && status !== "AWAITING_PAYMENT") {
+      onResolved(status);
+    }
+  }, [status, onResolved]);
+
+  const pix = order.pix;
+  if (!pix) {
+    return (
+      <Text variant="body" size="sm" color="danger" as="p" data-testid="pix-missing">
+        Não foi possível gerar o código PIX.
+      </Text>
+    );
+  }
+
+  const validUntil = new Date(pix.expiresAt).toLocaleTimeString("pt-BR", {
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+
+  return (
+    <Box
+      data-testid="pix-view"
+      sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 2, textAlign: "center" }}
+    >
+      <Text variant="heading" size="md" weight="bold" as="h2">
+        Pague com PIX
+      </Text>
+      <Text variant="body" size="sm" color="secondary" as="p">
+        Escaneie o QR code no app do seu banco ou copie o código. Total {order.totalLabel}.
+      </Text>
+
+      <Box
+        data-testid="pix-qr"
+        role="img"
+        aria-label="QR Code PIX para pagamento"
+        sx={{ bgcolor: "background.paper", p: 2, borderRadius: 2, border: "1px solid", borderColor: "divider" }}
+      >
+        <QRCode value={pix.copyPaste} size={200} />
+      </Box>
+
+      <PixCodeBox pix={pix} />
+
+      <Text variant="caption" size="xs" color="secondary" as="p" data-testid="pix-expiry">
+        Válido até {validUntil}. A confirmação é automática.
+      </Text>
+
+      <PixPollFooter error={error} />
+    </Box>
+  );
+}
+
+/** Small pulsing dot indicating the background poll is live. */
+function LoadingDot(): JSX.Element {
+  return (
+    <Box
+      aria-hidden
+      sx={{
+        width: 8,
+        height: 8,
+        borderRadius: "50%",
+        bgcolor: "primary.main",
+        animation: "pixPulse 1.2s ease-in-out infinite",
+        "@keyframes pixPulse": {
+          "0%, 100%": { opacity: 0.3 },
+          "50%": { opacity: 1 },
+        },
+      }}
+    />
+  );
+}