@12-apps/payments-frontend 3.34.4 → 3.36.0

package/src/components/checkout/payment-step-frame.tsx

@@ -0,0 +1,206 @@
+import { Box } from "@mui/material";
+import { useId, type JSX, type ReactNode } from "react";
+
+import { displayTotals } from "./checkout-totals";
+import { useCheckoutCopy } from "./copy-context";
+import { MethodTabs, methodPanelId, methodTabId } from "./method-tabs";
+import { PANEL_PAD_PHONE } from "./payment-step-layout";
+import {
+  OrderSummaryCard,
+  type CheckoutDeliverySummary,
+  type CheckoutSummaryLine,
+  type OrderSummaryParts,
+} from "./payment-summary";
+import { PhoneOrderSummary } from "./payment-summary-phone";
+import type { CheckoutOrder, PaymentMethod } from "./types";
+import { useCheckoutComponents } from "./ui";
+
+/**
+ * The Pagamento step's frame (FUT-3525): the computer's payment column with
+ * the order summary beside it, or the phone's single column with the total
+ * and chips on top — around ONE panel that holds the payment body.
+ */
+
+/** What the step knows about the amount: the charge's, the balance's, the cart's. */
+interface StepMoney {
+  order: CheckoutOrder | null;
+  cartTotals?: { totalLabel: string; totalItems: number };
+  totalOverride?: { label: string; items: number };
+  discountLines?: ReactNode;
+}
+
+/**
+ * The Pagamento step's own money line (FUT-1179), and everything the order
+ * summary shows beside it (FUT-3525).
+ *
+ * THE RAISED ORDER'S TOTAL WINS, exactly as the confirmation screen's does
+ * (`statusTotalLabel`). Once a charge exists, that charge's amount is what is
+ * being taken — a repriced cart, or an order resumed from a parked entry, makes
+ * the cart's total a different number from the one about to leave the buyer's
+ * account. Showing the cart's number above a QR for the order's would be this
+ * ticket's own defect in a new place: an amount on screen that is not the
+ * amount being charged.
+ *
+ * The item COUNT stays the cart's — an order carries no line count, and the
+ * caption is a description of the basket rather than of the charge.
+ *
+ * `null` when the host supplied no totals and no order — a step that would
+ * otherwise print "Total ·" with a blank beside it is worse than the silence
+ * FUT-1179 is about. Every host mounting `CheckoutFlow` gets them; only a
+ * hand-composed step can be missing them.
+ */
+export function summaryParts(
+  money: StepMoney,
+  extras: SummaryExtras,
+): OrderSummaryParts | null {
+  const { order, cartTotals, totalOverride, discountLines } = money;
+  if (!cartTotals && !totalOverride && !order) return null;
+  const { label, items } = displayTotals(
+    totalOverride,
+    cartTotals ?? { totalLabel: "", totalItems: 0 },
+  );
+  return {
+    totalLabel: order?.totalLabel ?? label,
+    totalItems: items,
+    // Suppressed while settling a balance: those totals come from the frozen
+    // ticket, not the cart — and so do its lines.
+    discountLines: totalOverride ? undefined : discountLines,
+    lines: totalOverride ? undefined : extras.lines,
+    payer: extras.payer,
+    delivery: extras.delivery,
+    orderNote: extras.orderNote,
+  };
+}
+
+/** The order facts a host may hand the summary, beyond the money (FUT-3525). */
+interface SummaryExtras {
+  lines?: CheckoutSummaryLine[];
+  payer?: OrderSummaryParts["payer"];
+  delivery?: CheckoutDeliverySummary;
+  orderNote?: ReactNode;
+}
+
+/**
+ * The panel under the method tabs: on a computer a card the chosen folder tab
+ * opens into (no top border, so the tab and the card are one shape); on a
+ * phone a rounded card under the pill. Empty — nothing chosen, nothing raised
+ * — it draws nothing, so an unanswered choice is not an empty box.
+ */
+function panelSx(wide: boolean, attached: boolean, filled: boolean) {
+  const base = {
+    display: "flex",
+    flexDirection: "column",
+    gap: 2,
+    minWidth: 0,
+    "&:empty": { display: "none" },
+  } as const;
+  if (!filled) return base;
+  if (wide) {
+    return {
+      ...base,
+      p: 3,
+      bgcolor: "background.paper",
+      border: "1px solid",
+      borderColor: "divider",
+      borderTop: attached ? 0 : "1px solid",
+      borderTopColor: "divider",
+      borderRadius: attached ? "0 0 10px 10px" : "10px",
+      // Flush under the folder tabs: the column's gap would open a seam
+      // between the chosen tab and the card it opens into.
+      mt: attached ? -2 : 0,
+    } as const;
+  }
+  return { ...base, p: `${PANEL_PAD_PHONE}px`, bgcolor: "background.paper", border: "1px solid", borderColor: "divider", borderRadius: 4 } as const;
+}
+
+/** What the frame needs to draw the method tabs. */
+interface FrameTabs {
+  show: boolean;
+  method: PaymentMethod | null;
+  onChange: (method: PaymentMethod) => void;
+  cardUnavailable: boolean;
+  offered: PaymentMethod[] | null;
+}
+
+/** The computer's heading over the tabs, at the prototype's 26px whatever the host's md is. */
+function PayHeading(): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens.layout;
+  return (
+    <Box sx={{ "&& > *": { fontSize: "1.625rem", lineHeight: 1.2, m: 0 } }}>
+      <Text variant="heading" size="md" weight="bold" as="h2">
+        {copy.payHeading}
+      </Text>
+    </Box>
+  );
+}
+
+const WIDE_GRID = { display: "grid", gridTemplateColumns: "minmax(0, 1fr) 380px", gap: 4, alignItems: "start" } as const;
+const NARROW_COLUMN = { display: "flex", flexDirection: "column", width: "100%", maxWidth: 560, mx: "auto" } as const;
+
+/**
+ * The panel's label: only a tab that is actually chosen — a card the store
+ * cannot charge stays disabled and unselected even while `method` names it.
+ */
+function panelLabel(tabs: FrameTabs, idBase: string): string | undefined {
+  if (!tabs.show || !tabs.method) return undefined;
+  if (tabs.method === "CARD" && tabs.cardUnavailable) return undefined;
+  return methodTabId(idBase, tabs.method);
+}
+
+/** Over the tabs: the computer's heading, or the phone's total and chips. */
+function StepHead({ wide, parts }: { wide: boolean; parts: OrderSummaryParts | null }): JSX.Element | null {
+  if (wide) return <PayHeading />;
+  return parts ? <PhoneOrderSummary parts={parts} /> : null;
+}
+
+/**
+ * The step's frame. The panel — and so the payment body inside it — keeps ONE
+ * place in the tree whichever layout is showing: a tablet turned on its side
+ * changes the frame, and remounting the card form there would throw away what
+ * the buyer typed.
+ */
+export function PaymentStepFrame({
+  wide,
+  parts,
+  tabs,
+  filled,
+  children,
+}: {
+  wide: boolean;
+  parts: OrderSummaryParts | null;
+  tabs: FrameTabs;
+  /** A method is chosen or an order raised — the panel has something to draw. */
+  filled: boolean;
+  children: ReactNode;
+}): JSX.Element {
+  const idBase = useId();
+  const labelledBy = panelLabel(tabs, idBase);
+  return (
+    <Box data-testid="payment-step" data-layout={wide ? "wide" : "narrow"} sx={wide ? WIDE_GRID : NARROW_COLUMN}>
+      <Box sx={{ display: "flex", flexDirection: "column", gap: wide ? 2 : 2.5, minWidth: 0 }}>
+        <StepHead wide={wide} parts={parts} />
+        {tabs.show ? (
+          <MethodTabs
+            idBase={idBase}
+            shape={wide ? "folder" : "pill"}
+            value={tabs.method}
+            onChange={tabs.onChange}
+            cardUnavailable={tabs.cardUnavailable}
+            offered={tabs.offered}
+          />
+        ) : null}
+        <Box
+          id={methodPanelId(idBase)}
+          role={labelledBy ? "tabpanel" : undefined}
+          aria-labelledby={labelledBy}
+          data-testid="checkout-method-panel"
+          sx={panelSx(wide, tabs.show, filled)}
+        >
+          {children}
+        </Box>
+      </Box>
+      {wide && parts ? <OrderSummaryCard parts={parts} /> : null}
+    </Box>
+  );
+}

package/src/components/checkout/payment-step-layout.tsx

@@ -1,8 +1,20 @@
 import { Box } from "@mui/material";
-import { useCallback, useMemo, useState, type JSX, type ReactNode } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useState,
+  type JSX,
+  type ReactNode,
+} from "react";
+
+import { useCheckoutCopy } from "./copy-context";
 
 import type { PixStage } from "./pix-stage";
 import type { PaymentMethod } from "./types";
+import { useCheckoutComponents } from "./ui";
 
 /**
  * The width of the Dados and confirmation steps, and of every non-PIX pane:
@@ -12,19 +24,6 @@ import type { PaymentMethod } from "./types";
  */
 export const STEP_COLUMN_MAX = 672;
 
-/**
- * The payment step's form column. The host may give this step more room than
- * the others (the 2026-10-06 Pix redesign lets the PIX pane put its QR and code
- * side by side), and only that pane uses it: the card form, wallets, hand-off,
- * the payer line and the raising and error panels keep the 672px they
- * always had. `full` lets the PIX pane through.
- */
-export function StepColumn({ full = false, children }: { full?: boolean; children: ReactNode }): JSX.Element {
-  // `:empty` keeps a self-hiding child (the payer line, the raising state)
-  // from leaving a gap in the step's flex column.
-  return <Box sx={{ width: "100%", mx: "auto", maxWidth: full ? "none" : STEP_COLUMN_MAX, "&:empty": { display: "none" } }}>{children}</Box>;
-}
-
 /**
  * The payment step's half of the PIX pane's after-copy face (the 2026-10-06
  * Pix redesign): the flag that hides the method picker, and the way to the
@@ -63,3 +62,159 @@ export function usePaymentPixStage(
  * buys them nothing, but here the tap is the buyer's consent to LEAVE, and
  * taking it for them would redirect a checkout the moment it rendered.
  */
+
+/**
+ * The checkout container's width class, from the 2026-10-11 Pagamento
+ * redesign (FUT-3525): `wide` is the computer layout (the payment column with
+ * the order summary beside it), `narrow` the phone layout (one column, chips,
+ * a sticky pay bar).
+ *
+ * Read off the flow's own full-width root rather than the viewport, so a host
+ * that renders the checkout inside a narrow panel gets the phone layout, and
+ * picked ONCE for the whole flow so the header does not change shape between
+ * steps.
+ */
+export const WIDE_CHECKOUT_MIN = 900;
+
+/** The phone panel's padding, in px — the sticky pay bar reaches past it. */
+export const PANEL_PAD_PHONE = 16;
+
+interface CheckoutLayout {
+  wide: boolean;
+}
+
+const CheckoutLayoutContext = createContext<CheckoutLayout | null>(null);
+
+/** `null` outside a measured flow: a component composed by hand keeps its old look. */
+export function useCheckoutLayout(): CheckoutLayout | null {
+  return useContext(CheckoutLayoutContext);
+}
+
+export const CheckoutLayoutProvider = CheckoutLayoutContext.Provider;
+
+/**
+ * Measure an element's width and say whether it is the wide layout.
+ *
+ * A CALLBACK ref, so the measuring starts whenever the element mounts — the
+ * flow renders its empty-cart screen first while the host's cart is still
+ * loading, and a ref object read once in an effect would never see the frame
+ * that mounts after it. Measured in a layout effect so the first PAINT is
+ * already right; a width of zero (jsdom, a hidden tab) reads as narrow, which
+ * is the layout that fits anything.
+ */
+export function useWideLayout(): [boolean, (element: HTMLElement | null) => void] {
+  const [element, setElement] = useState<HTMLElement | null>(null);
+  const [wide, setWide] = useState(false);
+  useLayoutEffect(() => {
+    if (!element) return;
+    const measure = (): void => setWide(element.getBoundingClientRect().width >= WIDE_CHECKOUT_MIN);
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [element]);
+  return [wide, setElement];
+}
+
+/** The amount the phone's pay bar shows beside its button; set by the Pagamento step. */
+const PayBarTotalContext = createContext<string | null>(null);
+
+export const PayBarTotalProvider = PayBarTotalContext.Provider;
+
+/**
+ * The phone's sticky pay bar (FUT-3525): "Total" over the amount at its left,
+ * the step's ONE primary action filling the rest, pinned to the bottom of the
+ * viewport while the page scrolls. On the computer — or outside a measured
+ * flow — it is just the action, where the pane put it.
+ */
+/**
+ * The colour the page itself is painted, for a bar that must read as part of
+ * the page. A host may paint its ground outside the theme (the storefront's
+ * is the body's, while its `background.default` is white), so the theme role
+ * is only the fallback until the first layout reads the real one.
+ */
+function usePageGround(): string | undefined {
+  const [ground, setGround] = useState<string>();
+  useLayoutEffect(() => {
+    const painted = getComputedStyle(document.body).backgroundColor;
+    if (painted && painted !== "rgba(0, 0, 0, 0)" && painted !== "transparent") setGround(painted);
+  }, []);
+  return ground;
+}
+
+export function StickyPayBar({
+  children,
+  dataTestId,
+}: {
+  children: ReactNode;
+  dataTestId?: string;
+}): JSX.Element {
+  const layout = useCheckoutLayout();
+  const totalLabel = useContext(PayBarTotalContext);
+  const { Text } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens.layout;
+  const ground = usePageGround();
+  if (!layout) return <Box data-testid={dataTestId}>{children}</Box>;
+  if (layout.wide) {
+    // The computer's action, in the panel: the prototype's 52px bold bar.
+    return (
+      <Box data-testid={dataTestId} sx={{ "& button": { minHeight: 52 }, "& button, & button *": { fontWeight: 700 } }}>
+        {children}
+      </Box>
+    );
+  }
+  // The bar sits on the PAGE, not in the card around the pane (the
+  // prototype's layout C): it reaches past the panel's padding and border on
+  // three sides, so the card reads as ending above it.
+  const breakout = `calc(-1 * (${PANEL_PAD_PHONE}px + 1px))`;
+  return (
+    <Box
+      data-testid={dataTestId}
+      sx={{
+        position: "sticky",
+        bottom: 0,
+        zIndex: 2,
+        mx: breakout,
+        mb: breakout,
+        mt: 1,
+        // Its content on the column's edge, where the card's border was.
+        px: "1px",
+        pt: 1.5,
+        // Clear of a phone's home indicator.
+        pb: "calc(16px + env(safe-area-inset-bottom, 0px))",
+        display: "flex",
+        flexWrap: "wrap",
+        alignItems: "center",
+        columnGap: 2,
+        rowGap: 1,
+        bgcolor: ground ?? "background.default",
+      }}
+    >
+      {totalLabel ? (
+        <Box sx={{ flex: "none", display: "flex", flexDirection: "column" }}>
+          <Text variant="body" size="xs" as="span">
+            {copy.total}
+          </Text>
+          <Box sx={{ "&& > *": { fontSize: "1.125rem", lineHeight: 1.2 } }}>
+            <Text variant="body" size="md" weight="bold" as="span" data-testid="pay-bar-sticky-total">
+              {totalLabel}
+            </Text>
+          </Box>
+        </Box>
+      ) : null}
+      {/* The prototype's 56px pill with a bold label, never squeezed to two
+          lines: under ~200px beside the total it wraps under it instead. */}
+      <Box
+        sx={{
+          flex: "1 1 200px",
+          minWidth: 0,
+          "& button": { borderRadius: 999, minHeight: 56, whiteSpace: "nowrap" },
+          "& button, & button *": { fontWeight: 700 },
+        }}
+      >
+        {children}
+      </Box>
+    </Box>
+  );
+}

package/src/components/checkout/payment-summary-phone.tsx

@@ -0,0 +1,158 @@
+import { Box } from "@mui/material";
+import type { JSX, ReactNode } from "react";
+
+import { formatCpf } from "../../card";
+
+import { useCheckoutCopy } from "./copy-context";
+import { PersonOutlineIcon, PlaceOutlinedIcon } from "./icons";
+import { NoteIcon, TotalAmount, type CheckoutDeliverySummary, type OrderSummaryParts } from "./payment-summary";
+import { useCheckoutComponents } from "./ui";
+
+/**
+ * The phone's head of the Pagamento step (FUT-3525, layout C): the amount big
+ * at the top, then who pays, where it goes and the note as chips that wrap.
+ */
+
+const CHIP_ICON = { fontSize: 18, color: "text.secondary" } as const;
+
+const CHIP_SX = {
+  display: "inline-flex",
+  alignItems: "center",
+  gap: 1,
+  minHeight: 44,
+  maxWidth: "100%",
+  px: 1.75,
+  border: "1px solid",
+  borderColor: "divider",
+  borderRadius: 999,
+  bgcolor: "background.paper",
+  color: "text.primary",
+  font: "inherit",
+  fontSize: "0.8125rem",
+  cursor: "pointer",
+  "&:focus-visible": { outline: "2px solid", outlineColor: "primary.main", outlineOffset: 2 },
+} as const;
+
+/** One chip: an icon, a fact, and the word that changes it. */
+function Chip({
+  icon,
+  text,
+  action,
+  onClick,
+  label,
+  testId,
+}: {
+  icon: JSX.Element;
+  text: ReactNode;
+  action: string;
+  onClick: () => void;
+  label: string;
+  testId: string;
+}): JSX.Element {
+  return (
+    <Box component="button" type="button" onClick={onClick} aria-label={label} data-testid={testId} sx={CHIP_SX}>
+      {icon}
+      <Box component="span" sx={{ overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", minWidth: 0 }}>
+        {text}
+      </Box>
+      <Box component="span" sx={{ color: "primary.main", fontWeight: 600, flex: "none" }}>
+        {action}
+      </Box>
+    </Box>
+  );
+}
+
+/** Who pays: the name and "CPF ✓", or the CPF typed this time, masked. */
+function PayerChip({ payer }: { payer: NonNullable<OrderSummaryParts["payer"]> }): JSX.Element {
+  const screens = useCheckoutCopy().screens;
+  const cpf = payer.taxId?.trim() ? screens.payer.taxId(formatCpf(payer.taxId)) : screens.layout.taxIdOnFileShort;
+  const who = payer.name ? screens.payer.payingAs(payer.name) : screens.payer.payingWithSavedDetails;
+  return (
+    <Box data-testid="checkout-payer" sx={{ display: "contents" }}>
+      <Chip
+        icon={<PersonOutlineIcon sx={CHIP_ICON} />}
+        text={
+          <>
+            {payer.name ? `${payer.name} · ` : null}
+            <span data-testid="checkout-payer-cpf">{cpf}</span>
+          </>
+        }
+        action={screens.payer.changeAction}
+        onClick={payer.onEdit}
+        label={`${who} — ${screens.payer.changeAction}`}
+        testId="checkout-payer-edit"
+      />
+    </Box>
+  );
+}
+
+/** Where it goes: the street line only, and the way back to the address step. */
+function AddressChip({ delivery }: { delivery: CheckoutDeliverySummary }): JSX.Element {
+  const screens = useCheckoutCopy().screens;
+  return (
+    <Box data-testid="checkout-address" sx={{ display: "contents" }}>
+      <Chip
+        icon={<PlaceOutlinedIcon sx={CHIP_ICON} />}
+        text={delivery.line1}
+        action={screens.payer.changeAction}
+        onClick={delivery.onEdit}
+        label={`${delivery.line1} — ${screens.layout.changeAddress}`}
+        testId="checkout-address-edit"
+      />
+    </Box>
+  );
+}
+
+/**
+ * The host's note control, drawn as the third chip while it is closed; once it
+ * opens into a field, that field takes the whole row.
+ */
+function NoteChip({ note }: { note: ReactNode }): JSX.Element {
+  return (
+    <Box
+      data-testid="checkout-note-slot"
+      sx={{
+        ...CHIP_SX,
+        gap: 0.5,
+        pr: 0.5,
+        cursor: "auto",
+        "&:has(textarea)": { flexBasis: "100%", display: "block", p: 0, border: 0, bgcolor: "transparent" },
+        "&:has(textarea) > svg": { display: "none" },
+      }}
+    >
+      <NoteIcon size={18} />
+      {note}
+    </Box>
+  );
+}
+
+/** The amount, big, under "Total a pagar · N itens", the host's money rows under it. */
+function PhoneTotal({ parts }: { parts: OrderSummaryParts }): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens.layout;
+  return (
+    <Box data-testid="payment-step-total" sx={{ display: "flex", flexDirection: "column", gap: 0.5, py: 1 }}>
+      <Text variant="body" size="sm" color="secondary" as="span">
+        {copy.totalDueCaption(parts.totalItems)}
+      </Text>
+      <TotalAmount totalLabel={parts.totalLabel} big />
+      {parts.discountLines}
+    </Box>
+  );
+}
+
+export function PhoneOrderSummary({ parts }: { parts: OrderSummaryParts }): JSX.Element {
+  const hasChips = Boolean(parts.payer || parts.delivery || parts.orderNote);
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 2.5 }}>
+      <PhoneTotal parts={parts} />
+      {hasChips ? (
+        <Box data-testid="checkout-chips" sx={{ display: "flex", flexWrap: "wrap", gap: 1, alignItems: "center" }}>
+          {parts.payer ? <PayerChip payer={parts.payer} /> : null}
+          {parts.delivery ? <AddressChip delivery={parts.delivery} /> : null}
+          {parts.orderNote ? <NoteChip note={parts.orderNote} /> : null}
+        </Box>
+      ) : null}
+    </Box>
+  );
+}