@12-apps/payments-frontend 1.0.0 → 1.2.0

package/src/components/settings-state.ts

@@ -126,6 +126,11 @@ export function useSetupConfirmation(
  * BEFORE the loading and error returns — the guide hook depends on them — and
  * that is exactly the position where a component accumulates the branches that
  * make it unreadable.
+ *
+ * `selected` may be the provider's NAME or its `urlSlug` — a controlled host
+ * stores the selection in a path segment, and the segment is the adapter's URL
+ * spelling. The raw name stays a working alias so a link built before the
+ * adapter declared a slug does not 404.
  */
 export function useOpenProvider(
   view: MerchantSettingsView | null,
@@ -135,7 +140,7 @@ export function useOpenProvider(
   // providers, not one arbitrary provider's configuration.
   const active = useMemo(() => {
     if (!view || !selected) return null;
-    return view.providers.find((p) => p.name === selected) ?? null;
+    return view.providers.find((p) => p.name === selected || p.urlSlug === selected) ?? null;
   }, [view, selected]);
 
   // A stored connection is what makes the manual walkthrough steps redundant —
@@ -148,6 +153,44 @@ export function useOpenProvider(
   return { active, activeConfig };
 }
 
+/**
+ * How a host is asked to move its selection. `options.replace` marks a
+ * CORRECTION rather than a navigation: the host should rewrite its current
+ * history entry (react-router's `replace`), so Voltar never revisits the
+ * spelling being corrected.
+ */
+export type ProviderChangeHandler = (
+  provider: string | null,
+  options?: { replace?: boolean },
+) => void;
+
+/**
+ * Ask the HOST to respell its path segment once the catalog can (FUT-557).
+ *
+ * The OAuth callback hands the host a raw provider NAME (`?connected=`), and a
+ * controlled host writes it into the URL verbatim — it holds no slug map, on
+ * purpose. The alias already resolves, so the SCREEN is right either way; what
+ * stays wrong is the ADDRESS BAR, which is exactly what a reload or a shared
+ * link uses. Once the view knows the provider's declared spelling, hand the
+ * canonical slug back — with `replace`, so the alias spelling never becomes a
+ * history entry of its own.
+ *
+ * Controlled hosts only: with internal selection there is no URL to fix, and
+ * `controlled === undefined` is the one test for that (see
+ * {@link useSelectedProvider}).
+ */
+export function useCanonicalProviderSegment(
+  controlled: string | null | undefined,
+  active: ProviderDescriptor | null,
+  onProviderChange: ProviderChangeHandler | undefined,
+): void {
+  useEffect(() => {
+    if (controlled === undefined || controlled === null) return;
+    if (!active?.urlSlug || active.urlSlug === controlled) return;
+    onProviderChange?.(active.urlSlug, { replace: true });
+  }, [controlled, active, onProviderChange]);
+}
+
 export function useSettingsState(client: PaymentsSettingsClient) {
   const [view, setView] = useState<MerchantSettingsView | null>(null);
   const [error, setError] = useState<string | null>(null);
@@ -187,7 +230,7 @@ export function useSettingsState(client: PaymentsSettingsClient) {
 export function useSelectedProvider(
   initialProvider: string | null,
   controlled: string | null | undefined,
-  onProviderChange: ((provider: string | null) => void) | undefined,
+  onProviderChange: ProviderChangeHandler | undefined,
 ) {
   const isControlled = controlled !== undefined;
   const [internal, setInternal] = useState<string | null>(initialProvider);

package/src/index.ts

@@ -37,7 +37,80 @@ export {
   type CheckoutPaymentProps,
   type SavedCardOption,
 } from './components/CheckoutPayment';
-export { CheckoutFlow, type CheckoutFlowProps } from './components/CheckoutFlow';
+
+// ---------------------------------------------------------------------------
+// The buyer checkout surface (FUT-564) — the storefront's three-step flow,
+// mounted by a host in one line. See ADOPTING.md §3 for the ports and the
+// design-system slot contract.
+// ---------------------------------------------------------------------------
+export {
+  CheckoutFlow,
+  type CheckoutCartView,
+  type CheckoutFlowProps,
+} from './components/checkout/checkout-flow';
+export { type CheckoutHostPorts } from './components/checkout/use-checkout-controller';
+export { PaymentsUnavailable } from './components/checkout/payments-unavailable';
+export { fetchCheckoutConfig } from './components/checkout/client';
+export {
+  CheckoutComponentsProvider,
+  type CheckoutActionBarProps,
+  type CheckoutAlertProps,
+  type CheckoutButtonProps,
+  type CheckoutCheckboxProps,
+  type CheckoutComponents,
+  type CheckoutInputProps,
+  type CheckoutLoadingStateProps,
+  type CheckoutRadioGroupProps,
+  type CheckoutRadioOption,
+  type CheckoutStepperProps,
+  type CheckoutStepperStep,
+  type CheckoutTextProps,
+} from './components/checkout/ui';
+export {
+  type BuyerContact,
+  type BuyerField,
+  type BuyerInfo,
+  type CheckoutError,
+  type CheckoutOrder,
+  type CheckoutProviderConfig,
+  type ComandaCheckout,
+  type CreateOrderRequest,
+  type CreateOrderResult,
+  type OrderStatus,
+  type PaymentMethod,
+} from './components/checkout/types';
+
+// The shared card-entry surface (form + tokenizer), used by the checkout above
+// and by the admin's provider-activation charge (FUT-463) — same fields, same
+// validation, same tokenization, or the activation proves nothing.
+export {
+  CardPayBar,
+  NewCardForm,
+  SavedCardsPicker,
+  cvvLength,
+  detectBrand,
+  formatCardNumber,
+  formatCpf,
+  formatCvv,
+  formatExpiry,
+  onlyDigits,
+  tokenizeCard,
+  tokenizeForCheckout,
+  tokenizerFor,
+  validateCardNumber,
+  validateCpf,
+  validateCvv,
+  validateExpiry,
+  validateHolder,
+  NEW_CARD,
+  type CardBrand,
+  type CardDetails,
+  type CardFieldErrors,
+  type CardToken,
+  type CardTokenizationConfig,
+  type CardTokenizer,
+  type SavedCard,
+} from './card';
 export {
   ProviderConnection,
   type ProviderConnectionProps,

package/src/result.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal `Result` shape for the browser payment surfaces. Lives in this
+ * package (moved from `@12-apps/spa-shared` with the checkout, FUT-564) so the
+ * portable frontend never reaches back into a repo-specific package for a
+ * ten-line type.
+ */
+export type Result<T> = { ok: true; data: T } | { ok: false; error: string };
+
+export const ok = <T,>(data: T): Result<T> => ({ ok: true, data });
+
+export const err = <T,>(error: string): Result<T> => ({ ok: false, error });

package/src/components/CheckoutFlow.tsx

@@ -1,169 +0,0 @@
-'use client';
-
-import {
-  Alert,
-  Button,
-  Checkbox,
-  FormControlLabel,
-  Stack,
-  Step,
-  StepLabel,
-  Stepper,
-  TextField,
-  Typography,
-} from '@mui/material';
-import { useState } from 'react';
-
-import type { ClientChargeView, CustomerInfo, Money } from '@12-apps/payments-backend';
-
-import { CheckoutPayment, type CheckoutPaymentProps } from './CheckoutPayment';
-
-/**
- * The full plug-and-play checkout: the three-step flow of the buyer-facing
- * screens — Dados (CPF required; name/email/phone optional, "save my data")
- * → Pagamento (method cards, saved cards, pay button — `CheckoutPayment`)
- * → Confirmação. The host supplies cart totals, prefilled customer data,
- * saved cards, and reacts to `onCustomerConfirmed` / `onPaid`.
- */
-export interface CheckoutFlowProps
-  extends Omit<CheckoutPaymentProps, 'customer' | 'onPaid'> {
-  initialCustomer?: Partial<CustomerInfo>;
-  /** Default state of the "save my data for next time" checkbox. */
-  saveDataDefault?: boolean;
-  /** Fired when the buyer completes step 1 (persist profile if saveData). */
-  onCustomerConfirmed?: (customer: CustomerInfo, saveData: boolean) => void;
-  onPaid?: (charge: ClientChargeView) => void;
-  /** e.g. "1 item" — shown next to the total in the footer. */
-  itemsLabel?: string;
-}
-
-const STEPS = ['Dados', 'Pagamento', 'Confirmação'];
-
-/** CPF: 11 digits (checksum stays server/provider-side; this is UX-level). */
-function cpfDigits(value: string): string {
-  return value.replace(/\D/g, '');
-}
-
-interface CustomerStepProps {
-  amount: Money;
-  itemsLabel?: string;
-  initial: Partial<CustomerInfo>;
-  saveDataDefault: boolean;
-  onContinue: (customer: CustomerInfo, saveData: boolean) => void;
-}
-
-function CustomerStep({ amount, itemsLabel, initial, saveDataDefault, onContinue }: CustomerStepProps) {
-  const [taxId, setTaxId] = useState(initial.taxId ?? '');
-  const [name, setName] = useState(initial.name ?? '');
-  const [email, setEmail] = useState(initial.email ?? '');
-  const [phone, setPhone] = useState(initial.phone ?? '');
-  const [saveData, setSaveData] = useState(saveDataDefault);
-  const [touched, setTouched] = useState(false);
-  const cpfInvalid = cpfDigits(taxId).length !== 11;
-
-  return (
-    <Stack spacing={2}>
-      <Typography variant="body2" color="text.secondary">
-        Informe seu CPF (obrigatório para o pagamento). Nome, e-mail e telefone são opcionais —
-        usados apenas para o comprovante.
-      </Typography>
-      <TextField
-        size="small"
-        label="CPF"
-        required
-        value={taxId}
-        error={touched && cpfInvalid}
-        helperText={touched && cpfInvalid ? 'Informe um CPF com 11 dígitos.' : undefined}
-        onBlur={() => setTouched(true)}
-        onChange={(e) => setTaxId(e.target.value)}
-      />
-      <TextField size="small" label="Nome" value={name} onChange={(e) => setName(e.target.value)} />
-      <TextField size="small" label="E-mail" value={email} onChange={(e) => setEmail(e.target.value)} />
-      <TextField size="small" label="Telefone" value={phone} onChange={(e) => setPhone(e.target.value)} />
-      <FormControlLabel
-        control={<Checkbox checked={saveData} onChange={(_, v) => setSaveData(v)} />}
-        label="Salvar meus dados para a próxima compra"
-      />
-      <Stack direction="row" spacing={2} alignItems="center">
-        <Typography variant="body2" color="text.secondary">
-          {itemsLabel ? `Total · ${itemsLabel} — ` : 'Total: '}
-          {(amount.amountCents / 100).toLocaleString('pt-BR', { style: 'currency', currency: amount.currency })}
-        </Typography>
-        <Button
-          variant="contained"
-          fullWidth
-          disabled={cpfInvalid}
-          onClick={() => onContinue({ name, email, taxId: cpfDigits(taxId), phone }, saveData)}
-        >
-          Continuar
-        </Button>
-      </Stack>
-      <Typography variant="caption" color="text.secondary" textAlign="right">
-        🔒 Pagamento seguro
-      </Typography>
-    </Stack>
-  );
-}
-
-export function CheckoutFlow(props: CheckoutFlowProps) {
-  const {
-    initialCustomer = {},
-    saveDataDefault = true,
-    onCustomerConfirmed,
-    onPaid,
-    itemsLabel,
-    ...payment
-  } = props;
-  const [step, setStep] = useState(0);
-  const [customer, setCustomer] = useState<CustomerInfo | null>(null);
-  const [paid, setPaid] = useState<ClientChargeView | null>(null);
-
-  return (
-    <Stack spacing={3}>
-      <Stepper activeStep={step} alternativeLabel>
-        {STEPS.map((label) => (
-          <Step key={label}>
-            <StepLabel>{label}</StepLabel>
-          </Step>
-        ))}
-      </Stepper>
-
-      {step === 0 ? (
-        <CustomerStep
-          amount={payment.amount}
-          itemsLabel={itemsLabel}
-          initial={initialCustomer}
-          saveDataDefault={saveDataDefault}
-          onContinue={(confirmed, saveData) => {
-            setCustomer(confirmed);
-            onCustomerConfirmed?.(confirmed, saveData);
-            setStep(1);
-          }}
-        />
-      ) : null}
-
-      {step === 1 && customer ? (
-        <Stack spacing={1}>
-          <Button size="small" sx={{ alignSelf: 'flex-start' }} onClick={() => setStep(0)}>
-            ← Voltar
-          </Button>
-          <CheckoutPayment
-            {...payment}
-            customer={customer}
-            onPaid={(charge) => {
-              setPaid(charge);
-              setStep(2);
-              onPaid?.(charge);
-            }}
-          />
-        </Stack>
-      ) : null}
-
-      {step === 2 && paid ? (
-        <Alert severity="success">
-          Pagamento confirmado — {paid.provider} · {paid.providerChargeId}
-        </Alert>
-      ) : null}
-    </Stack>
-  );
-}