@12-apps/payments-frontend 1.0.0 → 1.2.0

package/src/components/checkout/method-capability.ts

@@ -0,0 +1,69 @@
+/**
+ * What the store's active provider lets THIS browser do (FUT-697/698) — the
+ * capability reads the Pagamento step derives its picker and card path from.
+ * Every rule here fails OPEN for the UI and CLOSED for the money: a missing
+ * config renders everything, and the tokenizer/server still refuse a charge
+ * they cannot honour.
+ */
+import { useEffect } from "react";
+
+import { tokenizerFor, type CardTokenizationConfig } from "../../card";
+
+import type { CheckoutProviderConfig, PaymentMethod } from "./types";
+
+/**
+ * Whether the ACTIVE provider gives this browser a card path (FUT-697):
+ * a scheme {@link tokenizerFor} knows, with a key (or PagBank's on-demand
+ * refresh); a hosted page (`REDIRECT` — the provider's own site takes the
+ * card); or server-granted stub mode. `null` config (still loading / fetch
+ * blip) fails OPEN for the UI — the tokenizer itself still fails CLOSED.
+ */
+export function cardPathAvailable(config: CheckoutProviderConfig | null): boolean {
+  if (!config) return true;
+  if (config.mockTokenization) return true;
+  if (config.tokenization === "REDIRECT") return true;
+  const scheme = config.provider ? tokenizerFor(config.provider) : null;
+  if (!scheme) return false;
+  return config.publicKey !== null || scheme === "pagbank-sdk";
+}
+
+/**
+ * The tokenization slice the card view consumes. A missing config degrades
+ * to the legacy PagBank path — per-order key refresh, NO mock permission — so
+ * a transient config failure never blocks a healthy PagBank store and never
+ * mints a fake token anywhere.
+ */
+export function cardTokenization(config: CheckoutProviderConfig | null): CardTokenizationConfig {
+  if (config) return config;
+  return { provider: "pagbank", publicKey: null, mockTokenization: false };
+}
+
+/**
+ * The methods the picker may offer, from the chain's declared capabilities
+ * (FUT-698). `null` config — still loading, or a fetch blip — fails OPEN like
+ * {@link cardPathAvailable}: the picker renders everything and the server
+ * still refuses the charge closed. Narrowed to the methods this checkout can
+ * actually drive (PIX and CARD; BOLETO is declared by some adapters but has
+ * no buyer UI yet), so a capability the UI cannot honour is never offered.
+ */
+export function offeredMethods(config: CheckoutProviderConfig | null): PaymentMethod[] | null {
+  if (!config?.methods) return null;
+  return config.methods.filter(
+    (method): method is PaymentMethod => method === "PIX" || method === "CARD",
+  );
+}
+
+/**
+ * When the card path is unavailable, PIX is the only choice left — choose it
+ * (FUT-697 review): a one-option radiogroup that still demands a tap is a
+ * click that buys the buyer nothing.
+ */
+export function usePreselectSoleMethod(
+  cardUnavailable: boolean,
+  method: PaymentMethod | null,
+  onMethodChange: (method: PaymentMethod) => void,
+): void {
+  useEffect(() => {
+    if (cardUnavailable && method === null) onMethodChange("PIX");
+  }, [cardUnavailable, method, onMethodChange]);
+}

package/src/components/checkout/method-picker.tsx

@@ -0,0 +1,153 @@
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { CreditCardIcon, PixIcon } from "./icons";
+import type { PaymentMethod } from "./types";
+import { useCheckoutComponents } from "./ui";
+
+interface MethodOption {
+  value: PaymentMethod;
+  label: string;
+  description: string;
+  icon: JSX.Element;
+}
+
+const OPTIONS: MethodOption[] = [
+  { value: "PIX", label: "PIX", description: "Aprovação imediata", icon: <PixIcon /> },
+  { value: "CARD", label: "Cartão", description: "Crédito à vista", icon: <CreditCardIcon /> },
+];
+
+/** Text/icon color for a tile's state — one place, so the ternaries stay flat. */
+function tileColor(unavailable: boolean, selected: boolean, muted: string): string {
+  if (unavailable) return "text.disabled";
+  return selected ? "primary.main" : muted;
+}
+
+/** One selectable (or disabled) payment-method tile of the segmented control. */
+function MethodTile({
+  option,
+  selected,
+  unavailable,
+  onSelect,
+}: {
+  option: MethodOption;
+  selected: boolean;
+  unavailable: boolean;
+  onSelect: () => void;
+}): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const cursor = unavailable ? "not-allowed" : "pointer";
+  return (
+    <Box
+      component="button"
+      type="button"
+      role="radio"
+      aria-checked={selected}
+      disabled={unavailable}
+      onClick={unavailable ? undefined : onSelect}
+      data-testid={`checkout-method-${option.value}`}
+      sx={{
+        flex: 1,
+        minWidth: 0,
+        display: "flex",
+        alignItems: "center",
+        gap: 1,
+        p: 1.25,
+        cursor,
+        borderRadius: 2,
+        border: "2px solid",
+        borderColor: selected ? "primary.main" : "divider",
+        bgcolor: selected ? "action.selected" : "background.paper",
+        color: tileColor(unavailable, selected, "text.primary"),
+        opacity: unavailable ? 0.6 : 1,
+        textAlign: "left",
+        transition: "border-color 0.15s, background-color 0.15s",
+        "& *": { cursor },
+        "&:hover": { borderColor: unavailable ? "divider" : "primary.main" },
+        "&:focus-visible": {
+          outline: "2px solid",
+          outlineColor: "primary.main",
+          outlineOffset: 2,
+        },
+      }}
+    >
+      <Box sx={{ display: "flex", color: tileColor(unavailable, selected, "text.secondary") }}>
+        {option.icon}
+      </Box>
+      <Box sx={{ minWidth: 0 }}>
+        <Text variant="body" size="sm" weight="semibold" as="span">
+          {option.label}
+        </Text>
+        <Text variant="caption" size="xs" color="secondary" as="p">
+          {unavailable ? "Indisponível nesta loja" : option.description}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * PIX / Card payment-method picker as a compact two-button segmented control.
+ * Each option is a real focusable `<button role="radio">` (keyboard + AT
+ * operable), selected-state shown by the button fill itself — so there's no radio
+ * dot taking space and the two always sit side by side.
+ *
+ * `offered` derives the options from the chain's declared capabilities
+ * (FUT-698): a provider that cannot PIX must not offer PIX — the charge walk
+ * would refuse the method after the buyer already chose it. `null` (config
+ * still loading / fetch blip) fails OPEN and offers everything: the server
+ * still fails the charge closed.
+ *
+ * `cardUnavailable` DISABLES the card option with a caption saying so
+ * (FUT-697): a provider with no browser card path must not take the buyer to a
+ * form that fails at the last click — and a tile that silently vanished would
+ * leave an unexplained one-option "choice". The caller preselects the sole
+ * remaining method, so no extra tap is demanded either.
+ */
+function visibleOptions(offered: PaymentMethod[] | null): MethodOption[] {
+  return OPTIONS.filter((option) => offered === null || offered.includes(option.value));
+}
+
+export function MethodPicker({
+  value,
+  onChange,
+  cardUnavailable = false,
+  offered = null,
+}: {
+  /** The chosen method, or `null` before the buyer has picked one. */
+  value: PaymentMethod | null;
+  onChange: (method: PaymentMethod) => void;
+  /** True ⇒ the store's active provider has no card path here; disable the tile. */
+  cardUnavailable?: boolean;
+  /** Methods the store's chain can charge, or `null` while unknown (fail open). */
+  offered?: PaymentMethod[] | null;
+}): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const options = visibleOptions(offered);
+  return (
+    <Box>
+      <Text variant="body" size="sm" weight="bold" as="p" style={{ marginBottom: 8 }}>
+        Forma de pagamento
+      </Text>
+      <Box
+        role="radiogroup"
+        aria-label="Forma de pagamento"
+        data-testid="checkout-method"
+        sx={{ display: "flex", gap: 1 }}
+      >
+        {options.map((option) => {
+          const unavailable = option.value === "CARD" && cardUnavailable;
+          return (
+            <MethodTile
+              key={option.value}
+              option={option}
+              selected={option.value === value && !unavailable}
+              unavailable={unavailable}
+              onSelect={() => onChange(option.value)}
+            />
+          );
+        })}
+      </Box>
+    </Box>
+  );
+}

package/src/components/checkout/mui-defaults.tsx

@@ -0,0 +1,218 @@
+/**
+ * The raw-MUI fallback for every checkout slot (FUT-564, option 3).
+ *
+ * These are what a host gets when it fills nothing: functional, plain,
+ * accessible — built only on `@mui/material`, which is already a peer. They
+ * exist so the package works in a host with NO component library (the
+ * second-host proof renders the whole flow through these), not to imitate any
+ * particular design system's pixels.
+ *
+ * Test ids are preserved exactly — behavior tests and e2e selectors must find
+ * the same hooks whichever side of the seam renders the pixels.
+ */
+import {
+  Alert as MuiAlert,
+  AlertTitle,
+  Box,
+  Button as MuiButton,
+  Checkbox as MuiCheckbox,
+  CircularProgress,
+  FormControl,
+  FormControlLabel,
+  FormLabel,
+  Radio,
+  RadioGroup as MuiRadioGroup,
+  Step,
+  StepLabel,
+  Stepper as MuiStepper,
+  TextField,
+  Typography,
+} from '@mui/material';
+import type { JSX } from 'react';
+
+import type {
+  CheckoutActionBarProps,
+  CheckoutAlertProps,
+  CheckoutButtonProps,
+  CheckoutCheckboxProps,
+  CheckoutComponents,
+  CheckoutInputProps,
+  CheckoutLoadingStateProps,
+  CheckoutRadioGroupProps,
+  CheckoutStepperProps,
+  CheckoutTextProps,
+} from './ui';
+
+const TEXT_SIZE = { xs: '0.75rem', sm: '0.875rem', md: '1rem' } as const;
+const TEXT_COLOR = {
+  primary: 'primary.main',
+  secondary: 'text.secondary',
+  success: 'success.main',
+  danger: 'error.main',
+} as const;
+
+function DefaultText({ variant, size = 'md', weight, color, as, style, children, ...rest }: CheckoutTextProps): JSX.Element {
+  return (
+    <Typography
+      component={as ?? 'span'}
+      data-testid={rest['data-testid']}
+      style={style}
+      sx={{
+        fontSize: TEXT_SIZE[size],
+        fontWeight: weight === 'bold' ? 700 : weight === 'semibold' ? 600 : variant === 'heading' ? 600 : 400,
+        color: color ? TEXT_COLOR[color] : 'text.primary',
+        fontFamily: variant === 'code' ? 'monospace' : undefined,
+        opacity: variant === 'caption' ? 0.8 : undefined,
+      }}
+    >
+      {children}
+    </Typography>
+  );
+}
+
+const BUTTON_VARIANT = { solid: 'contained', outline: 'outlined', text: 'text' } as const;
+const BUTTON_SIZE = { sm: 'small', md: 'medium', lg: 'large' } as const;
+
+function DefaultButton({ variant = 'solid', color = 'primary', size = 'md', fullWidth, disabled, loading, icon, iconPosition = 'left', onClick, dataTestId, children }: CheckoutButtonProps): JSX.Element {
+  const adornment = loading ? <CircularProgress size={16} color="inherit" /> : icon;
+  return (
+    <MuiButton
+      variant={BUTTON_VARIANT[variant]}
+      color={color === 'neutral' ? 'inherit' : 'primary'}
+      size={BUTTON_SIZE[size]}
+      fullWidth={fullWidth}
+      disabled={disabled || loading}
+      startIcon={iconPosition === 'left' ? adornment : undefined}
+      endIcon={iconPosition === 'right' ? adornment : undefined}
+      onClick={onClick}
+      data-testid={dataTestId}
+      sx={{ textTransform: 'none' }}
+    >
+      {children}
+    </MuiButton>
+  );
+}
+
+function DefaultInput({ label, type = 'text', inputMode, fullWidth, required, autoComplete, placeholder, maxLength, value, error, helperText, endAdornment, onChange, onBlur, ...rest }: CheckoutInputProps): JSX.Element {
+  return (
+    <TextField
+      label={label}
+      type={type}
+      size="small"
+      fullWidth={fullWidth}
+      required={required}
+      placeholder={placeholder}
+      value={value}
+      error={error}
+      helperText={helperText}
+      onChange={onChange}
+      onBlur={onBlur}
+      slotProps={{
+        htmlInput: { inputMode, maxLength, autoComplete, 'data-testid': rest['data-testid'] },
+        input: { endAdornment },
+      }}
+    />
+  );
+}
+
+function DefaultCheckbox({ checked, onChange, label, ...rest }: CheckoutCheckboxProps): JSX.Element {
+  return (
+    <FormControlLabel
+      control={<MuiCheckbox checked={checked} onChange={onChange} data-testid={rest['data-testid']} />}
+      label={label}
+    />
+  );
+}
+
+const ALERT_SEVERITY = { info: 'info', warning: 'warning', danger: 'error' } as const;
+
+function DefaultAlert({ variant = 'info', title, description, showIcon, ...rest }: CheckoutAlertProps): JSX.Element {
+  return (
+    <MuiAlert severity={ALERT_SEVERITY[variant]} icon={showIcon ? undefined : false} data-testid={rest['data-testid']}>
+      {title ? <AlertTitle>{title}</AlertTitle> : null}
+      {description}
+    </MuiAlert>
+  );
+}
+
+function DefaultLoadingState({ message, dataTestId }: CheckoutLoadingStateProps): JSX.Element {
+  return (
+    <Box data-testid={dataTestId} sx={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 1, py: 2 }}>
+      <CircularProgress size={28} />
+      {message ? <Typography variant="body2" color="text.secondary">{message}</Typography> : null}
+    </Box>
+  );
+}
+
+function DefaultStepper({ steps, activeId, completed, ...rest }: CheckoutStepperProps): JSX.Element {
+  const activeStep = steps.findIndex((step) => step.id === activeId);
+  return (
+    <MuiStepper activeStep={activeStep} alternativeLabel data-testid={rest['data-testid']}>
+      {steps.map((step) => (
+        <Step key={step.id} completed={completed?.has(step.id)}>
+          <StepLabel>{step.label}</StepLabel>
+        </Step>
+      ))}
+    </MuiStepper>
+  );
+}
+
+function DefaultRadioGroup({ label, value, onChange, options, dataTestId }: CheckoutRadioGroupProps): JSX.Element {
+  return (
+    <FormControl data-testid={dataTestId}>
+      {label ? <FormLabel>{label}</FormLabel> : null}
+      <MuiRadioGroup value={value} onChange={onChange}>
+        {options.map((option) => (
+          <FormControlLabel
+            key={option.value}
+            value={option.value}
+            control={<Radio />}
+            label={
+              <Box>
+                <Typography variant="body2">{option.label}</Typography>
+                {option.description ? (
+                  <Typography variant="caption" color="text.secondary">{option.description}</Typography>
+                ) : null}
+              </Box>
+            }
+          />
+        ))}
+      </MuiRadioGroup>
+    </FormControl>
+  );
+}
+
+function DefaultActionBar({ children, dataTestId }: CheckoutActionBarProps): JSX.Element {
+  return (
+    <Box
+      data-testid={dataTestId}
+      sx={{
+        position: 'sticky',
+        bottom: 0,
+        zIndex: 2,
+        bgcolor: 'background.paper',
+        borderTop: '1px solid',
+        borderColor: 'divider',
+        py: 1.5,
+        display: 'flex',
+        alignItems: 'center',
+        gap: 2,
+      }}
+    >
+      {children}
+    </Box>
+  );
+}
+
+/** The complete raw-MUI slot set — what an empty `components` prop means. */
+export const defaultCheckoutComponents: CheckoutComponents = {
+  Text: DefaultText,
+  Button: DefaultButton,
+  Input: DefaultInput,
+  Checkbox: DefaultCheckbox,
+  Alert: DefaultAlert,
+  LoadingState: DefaultLoadingState,
+  Stepper: DefaultStepper,
+  RadioGroup: DefaultRadioGroup,
+  ActionBar: DefaultActionBar,
+};

package/src/components/checkout/payer-summary.tsx

@@ -0,0 +1,81 @@
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { formatCpf } from "../../card";
+
+import { PersonOutlineIcon } from "./icons";
+import { useCheckoutComponents } from "./ui";
+
+
+/** What the CPF line reads, given whether the buyer typed one this time. */
+function cpfLabel(taxId: string | undefined): string {
+  return taxId?.trim() ? `CPF ${formatCpf(taxId)}` : "CPF já cadastrado";
+}
+
+/**
+ * "Pagando como … " — who the charge will name, shown at the top of Pagamento
+ * for a buyer whose Dados step was skipped (FUT-465).
+ *
+ * Skipping that step is right (it existed to collect a CPF the store already
+ * has) but it silently removed the last place a buyer could see WHICH identity
+ * is about to be charged, or use a different CPF for one purchase. This states
+ * both, and "Alterar" reopens Dados so they can type another — the server
+ * prefers a CPF that was sent over the saved one, so a typed CPF simply wins.
+ *
+ * The saved CPF is never shown, because the client never receives it: the
+ * profile API answers `hasTaxId` only. A CPF the buyer typed HERE is theirs and
+ * already on screen, so that one is echoed back masked.
+ *
+ * Renders nothing without `onEdit`, which is the flow's way of saying the buyer
+ * filled the Dados step in themselves: they have already seen these details on
+ * the previous screen, and the header's back link returns them to it.
+ */
+export function PayerSummary({
+  name,
+  taxId,
+  onEdit,
+}: {
+  name?: string;
+  /** A CPF typed in this checkout, if any — else the saved one is in play. */
+  taxId?: string;
+  /** Absent ⇒ Dados was NOT skipped, so there is nothing to restate. */
+  onEdit?: () => void;
+}): JSX.Element | null {
+  const { Button, Text } = useCheckoutComponents();
+  if (!onEdit) return null;
+
+  return (
+    <Box
+      data-testid="checkout-payer"
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        gap: 1.5,
+        p: 1.5,
+        border: "1px solid",
+        borderColor: "divider",
+        borderRadius: 1,
+        bgcolor: "background.paper",
+      }}
+    >
+      <PersonOutlineIcon sx={{ fontSize: 20, color: "text.secondary", flex: "0 0 auto" }} />
+      <Box sx={{ flex: 1, minWidth: 0 }}>
+        <Text variant="body" size="sm" as="p" data-testid="checkout-payer-name">
+          {name ? `Pagando como ${name}` : "Pagando com os seus dados salvos"}
+        </Text>
+        <Text variant="caption" size="xs" color="secondary" as="p" data-testid="checkout-payer-cpf">
+          {cpfLabel(taxId)}
+        </Text>
+      </Box>
+      <Button
+        variant="text"
+        color="primary"
+        size="sm"
+        onClick={onEdit}
+        dataTestId="checkout-payer-edit"
+      >
+        Alterar
+      </Button>
+    </Box>
+  );
+}