@12-apps/payments-frontend 3.36.0 → 3.38.0

package/src/components/checkout/list/pt-BR.ts

@@ -0,0 +1,77 @@
+import type { PaymentListCopy } from "./types";
+
+/**
+ * The article a provider's name takes in a pt-BR sentence — "o PagBank", "a
+ * InfinitePay". The names are the chain's own `displayName`s; one this table
+ * has never seen reads as a company ("a empresa"), which is the safer default.
+ */
+const MASCULINE = new Set(["PagBank", "PagSeguro", "Stripe", "Itaú", "Mercado Pago"]);
+
+function the(provider: string): string {
+  return `${MASCULINE.has(provider) ? "o" : "a"} ${provider}`;
+}
+
+/** "da InfinitePay" / "do PagBank". */
+function of(provider: string): string {
+  return `${MASCULINE.has(provider) ? "do" : "da"} ${provider}`;
+}
+
+/** The one-list Pagamento step's words, pt-BR (FUT-3591, FUT-3592). */
+export const PT_BR_PAYMENT_LIST_COPY: PaymentListCopy = {
+  title: "Como você quer pagar?",
+  onlineHeading: "Pagar agora, pelo app",
+  doorHeading: "Pagar na entrega",
+  pix: { label: "Pix", hint: "Gera o código para copiar e colar" },
+  card: {
+    label: "Cartão de crédito",
+    hintSaved: (card) => `${card} ou outro cartão`,
+    hintNew: "Digite os dados do cartão",
+  },
+  googlePay: { label: "Google Pay", hint: "Com o cartão salvo no seu Google" },
+  handOff: {
+    label: "Pix ou cartão",
+    hint: (provider) =>
+      provider ? `Você paga na página ${of(provider)} e volta` : "Você paga na página de pagamento e volta",
+  },
+  savedCard: (brand, last4) => `${brand ?? "Cartão"} final ${last4}`,
+  otherCard: "Outro cartão",
+  buyer: {
+    cpf: "CPF",
+    phone: "Celular",
+    name: "Nome",
+    email: "E-mail",
+    why: (provider) => (provider ? `(${the(provider)} pede para pagar pelo app)` : "(pedido para pagar pelo app)"),
+    cpfIncomplete: "O CPF tem 11 dígitos.",
+    phoneIncomplete: "O celular precisa de DDD e 9 dígitos.",
+  },
+  reasons: {
+    choose: "Escolha como pagar.",
+    cpf: "Digite seu CPF para pagar pelo app.",
+    phone: "Digite seu celular para pagar pelo app.",
+    details: "Preencha seus dados para pagar pelo app.",
+    chooseCard: "Escolha o cartão.",
+    cardDetails: "Preencha os dados do cartão.",
+  },
+  actions: {
+    choose: "Escolha como pagar",
+    card: "Pagar",
+    pix: "Gerar Pix",
+    googlePay: "Pagar com Google Pay",
+    handOff: (provider) => (provider ? `Ir para ${the(provider)}` : "Ir para o pagamento"),
+  },
+  payer: (name) => `Pagando como ${name} · CPF ✓`,
+  payerChange: "Alterar",
+  charging: (total, card) => `Pagando ${total} no ${card ?? "cartão informado"}…`,
+  cancel: "Cancelar",
+  pixFace: {
+    title: (total) => `Pague ${total} com Pix`,
+    validUntil: (time) =>
+      `Válido até ${time}. Copie o código e cole no app do seu banco, em Pix copia e cola.`,
+    showQr: "Ver QR code (pagar de outro celular)",
+    hideQr: "Esconder QR code",
+    changeMethod: "Trocar a forma de pagamento",
+    copyCode: "Copiar código Pix",
+    waiting: "Aguardando o pagamento do Pix…",
+  },
+  handOffWaiting: (provider) => (provider ? `Aguardando ${the(provider)}…` : "Aguardando o pagamento…"),
+};

package/src/components/checkout/list/types.ts

@@ -0,0 +1,187 @@
+/**
+ * The Pagamento step as ONE list (FUT-3591): every way to pay — the ones the
+ * store charges through this package AND the host's own ways to pay at the
+ * door — as one radio group under two headings, with one bar whose button is
+ * the only thing that creates the order and the charge.
+ *
+ * Opt-in, through `CheckoutFlowProps.paymentList`. A host that passes nothing
+ * keeps the method tabs, the order summary and the raise-on-pick it has today
+ * — this is additive, not a replacement.
+ *
+ * ## The door options are the HOST's
+ *
+ * Paying at the door raises no charge, so nothing about it belongs to a
+ * payments package: which tenders a store takes, the troco question, the
+ * minimum order and the request that places the pedido are all the host's.
+ * The list only DRAWS them — a radio row in the same group, the host's
+ * content opened inside it, and the host's verb, reason and send on the bar's
+ * button while it is the chosen one. That is the slot `CheckoutDoorOption`
+ * describes.
+ */
+import type { ReactNode } from "react";
+
+/**
+ * One of the host's ways to pay at the door — "Dinheiro", "Maquininha".
+ *
+ * Every field is a fact the host already holds; the list never computes one.
+ * Rebuild the array whenever any of them changes (a hook that returns it is the
+ * natural shape): the list renders what it is handed on every render.
+ */
+export interface CheckoutDoorOption {
+  /** Stable within the list; reported back through `onChoiceChange`. */
+  id: string;
+  /** The row's label — "Dinheiro". */
+  label: string;
+  /** The muted line under the label — "Crédito, débito, vale-refeição ou Pix". */
+  hint?: string;
+  /**
+   * Hide the hint while the option is chosen — for an option whose opened
+   * content says the same thing at length (the maquininha's brand lines).
+   */
+  hideHintWhileChosen?: boolean;
+  /**
+   * What opens INSIDE the row when it is chosen (the troco question, the
+   * tender chips, the brand lines). Rendered only while chosen, with no left
+   * indent: it starts where the row's own content starts.
+   */
+  content?: ReactNode;
+  /** The bar button's verb while this option is chosen — "Enviar pedido". */
+  action: string;
+  /** The amount beside the verb. Absent ⇒ the cart's own total. */
+  totalLabel?: string;
+  /**
+   * Why the button cannot send yet, in the host's words — or `null` when it
+   * can. Shown under the button, which stays disabled while it is set.
+   */
+  blocked: string | null;
+  /** The host's send is in flight: the button shows its busy state. */
+  pending?: boolean;
+  /** A refusal of the last send, in the host's words, shown under the button. */
+  error?: string | null;
+  /** Press of the bar's button while this option is chosen. Places the order. */
+  onSend: () => void;
+}
+
+/** The online ways to pay the list may offer, as the host is told about them. */
+export type CheckoutOnlineChoice = "PIX" | "CARD" | "GOOGLE_PAY" | "HAND_OFF";
+
+/** What the buyer has chosen in the list. */
+export type CheckoutListChoice =
+  | { kind: "online"; method: CheckoutOnlineChoice }
+  | { kind: "door"; id: string };
+
+/**
+ * A reason the HOST is holding the button, whatever is chosen — a step before
+ * this one is still open ("Escolha o horário no passo 2."). The button reads
+ * `action`, disabled, with `reason` under it.
+ */
+export interface CheckoutListHold {
+  action: string;
+  reason: string;
+}
+
+/** `CheckoutFlowProps.paymentList` — see the module comment. */
+export interface CheckoutPaymentList {
+  /** Every sentence the list draws. REQUIRED, with no default (FUT-760). */
+  copy: PaymentListCopy;
+  /**
+   * The first line of the bar, in the host's words — "2 itens · Taxa de
+   * entrega R$ 5,00". The list draws it as given.
+   */
+  summary?: ReactNode;
+  /**
+   * Host content drawn in the bar while an ONLINE option is chosen, under the
+   * summary — the storefront's "Usar meus R$ 5,00 de crédito na loja". A door
+   * option hides it: what it offers applies only to a payment made here.
+   */
+  onlineExtras?: ReactNode;
+  /** The "PAGAR NA ENTREGA" group. Absent or empty ⇒ no heading, no rows. */
+  door?: readonly CheckoutDoorOption[];
+  /** Held by the host — see {@link CheckoutListHold}. */
+  hold?: CheckoutListHold | null;
+  /** Told whenever the chosen option changes, including to nothing. */
+  onChoiceChange?: (choice: CheckoutListChoice | null) => void;
+  /**
+   * The amount the buyer is about to pay, in integer cents — what Google Pay's
+   * sheet is priced with, since that sheet must open INSIDE the tap, before any
+   * order exists to read a price from. Absent ⇒ no Google Pay row. The charge
+   * is refused if the order raised after the sheet does not cost the same.
+   */
+  totalCents?: number;
+}
+
+/** The list's words — a pack per locale ships at `@12-apps/payments-frontend/locales`. */
+export interface PaymentListCopy {
+  /** "Como você quer pagar?" */
+  title: string;
+  /** "Pagar agora, pelo app" — drawn in capitals by CSS. */
+  onlineHeading: string;
+  /** "Pagar na entrega" — drawn in capitals by CSS. */
+  doorHeading: string;
+  pix: { label: string; hint: string };
+  card: {
+    label: string;
+    /** "Visa final 4242 ou outro cartão" — the preselected saved card named. */
+    hintSaved: (card: string) => string;
+    /** "Digite os dados do cartão". */
+    hintNew: string;
+  };
+  googlePay: { label: string; hint: string };
+  handOff: {
+    label: string;
+    /** "Você paga na página da InfinitePay e volta" — `null` when the store published no name. */
+    hint: (provider: string | null) => string;
+  };
+  /** "Visa final 4242"; `brand` is `null` when the network is unknown ("Cartão final 4242"). */
+  savedCard: (brand: string | null, last4: string) => string;
+  /** "Outro cartão". */
+  otherCard: string;
+  /** The buyer's own details asked inside the option, when the store needs one the buyer has not given. */
+  buyer: {
+    cpf: string;
+    phone: string;
+    name: string;
+    email: string;
+    /** "(o PagBank pede para pagar pelo app)" — `null` when no name was published. */
+    why: (provider: string | null) => string;
+    cpfIncomplete: string;
+    phoneIncomplete: string;
+  };
+  /** Why the button is disabled — shown under it. */
+  reasons: {
+    choose: string;
+    cpf: string;
+    phone: string;
+    details: string;
+    chooseCard: string;
+    cardDetails: string;
+  };
+  /** The button's verb, beside the total. */
+  actions: {
+    choose: string;
+    card: string;
+    pix: string;
+    googlePay: string;
+    handOff: (provider: string | null) => string;
+  };
+  /** "Pagando como Ana Teste · CPF ✓". */
+  payer: (name: string) => string;
+  payerChange: string;
+  /** The 5-second bar: "Pagando R$ 27,00 no Visa final 4242…"; `card` is `null` for a card typed now. */
+  charging: (total: string, card: string | null) => string;
+  cancel: string;
+  pixFace: {
+    /** "Pague R$ 22,00 com Pix". */
+    title: (total: string) => string;
+    /** "Válido até 18:42. Copie o código e cole no app do seu banco, em Pix copia e cola." */
+    validUntil: (time: string) => string;
+    showQr: string;
+    hideQr: string;
+    changeMethod: string;
+    /** The bar's action, and the accessible name of the tappable code. */
+    copyCode: string;
+    waiting: string;
+  };
+  /** "Aguardando a InfinitePay…" */
+  handOffWaiting: (provider: string | null) => string;
+}

package/src/components/checkout/list/use-capability.ts

@@ -0,0 +1,53 @@
+import { useMemo, useState } from "react";
+
+import { useGooglePayClient, type GooglePayGatewayParams, type GooglePaymentsClient } from "../google-pay-button";
+import { cardPathAvailable, googlePayConfig, offeredMethods } from "../method-capability";
+import { methodChosenAtProvider } from "../providers/registry";
+import type { CheckoutProviderConfig } from "../types";
+
+import type { OnlineCapability } from "./choice";
+
+/** What the store's chain lets THIS browser offer in the list, Google Pay's client included. */
+export interface ListCapability extends OnlineCapability {
+  /** Google Pay, ready to open its sheet — `null` when there is no row, or while the host re-prices. */
+  googlePay: { client: GooglePaymentsClient; params: GooglePayGatewayParams } | null;
+}
+
+/**
+ * The capability reads the tabs layout already makes (`method-capability.ts`,
+ * `providers/registry.ts`), plus the one the list adds: Google Pay as its own
+ * row, offered only when the chain head declares it AND this browser's
+ * `isReadyToPay` said yes — the same two gates the Google Pay button has
+ * always had (FUT-471), so the list never offers a wallet that cannot work.
+ *
+ * The sheet must open inside the tap, before any order exists, so it is priced
+ * with the host's `totalCents`; without one there is no row.
+ *
+ * Apple Pay is not a row here: its sheet must open synchronously inside the
+ * tap, before any order could be raised for it. The tabs layout keeps it.
+ */
+export function useListCapability(
+  config: CheckoutProviderConfig | null,
+  /** The host's price for the sheet — no price, no Google Pay row. */
+  totalCents: number | undefined,
+): ListCapability {
+  const declared = googlePayConfig(config) !== null;
+  // `null` tells the client hook not to load pay.js at all.
+  const client = useGooglePayClient(declared ? undefined : null, "TEST");
+  // Once the host has priced the sheet, a moment without a price (it is
+  // re-pricing — the credit was toggled) keeps the row and holds its button;
+  // only a host that never priced it offers no row.
+  const [priced, setPriced] = useState(false);
+  if (totalCents !== undefined && !priced) setPriced(true);
+  return useMemo(() => {
+    const params = googlePayConfig(config);
+    const usable = params && client ? { client, params } : null;
+    return {
+      handOff: methodChosenAtProvider(config?.chain?.[0]?.checkoutScreen, config),
+      offered: offeredMethods(config),
+      cardUnavailable: !cardPathAvailable(config),
+      googlePayReady: usable !== null && (totalCents !== undefined || priced),
+      googlePay: totalCents === undefined ? null : usable,
+    };
+  }, [config, client, totalCents, priced]);
+}

package/src/components/checkout/list/use-list-charge.ts

@@ -0,0 +1,161 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { CheckoutOrder, PaymentMethod } from "../types";
+
+/**
+ * How long the card's "Pagando R$ X no Visa final 4242…" bar takes to fill —
+ * the window in which "Cancelar" still sends nothing (FUT-3592, M10). The
+ * owner's own number: the bar replaces the confirmation dialog, so it is the
+ * buyer's whole chance to change their mind.
+ */
+export const CHARGE_WINDOW_MS = 5_000;
+
+/**
+ * Where a charge the bar's button started stands.
+ *
+ *  - `idle` — the list, with the button.
+ *  - `counting` — the card's 5-second bar; Cancelar still sends nothing.
+ *  - `sending` — the order is being raised, then the instrument charged.
+ *  - `waiting` — the charge was accepted and its confirmation is awaited.
+ */
+export type ListChargePhase = "idle" | "counting" | "sending" | "waiting";
+
+/** What a charge runs against: the card the buyer chose, or Google Pay's sheet. */
+export type ListChargeKind = "CARD" | "GOOGLE_PAY";
+
+/** The controller's slice this needs. */
+interface RaisePorts {
+  order: CheckoutOrder | null;
+  creating: boolean;
+  createError: string | null;
+  setMethod: (method: PaymentMethod) => void;
+  startPayment: (method: PaymentMethod) => Promise<void>;
+  /** The amount the buyer is shown now (the cart's, or the balance's). */
+  cartTotal: string;
+}
+
+export interface ListCharge {
+  phase: ListChargePhase;
+  kind: ListChargeKind | null;
+  /** The amount named when the button was pressed — the bar shows THIS, never a later one. */
+  pressedTotal: string | null;
+  /** Start a card charge (with its 5-second bar) or a Google Pay one (straight away). Only from idle. */
+  start: (kind: ListChargeKind, total: string) => void;
+  /** Cancelar, during the bar: nothing has been sent, and nothing will be. */
+  cancel: () => void;
+  /**
+   * Whether the charge may still go out — set by the list on every render. A
+   * hold the host raised, a reason the button would show, or a total that
+   * moved since the press stops the bar, and `send` checks it again.
+   */
+  setAllowed: (allowed: boolean) => void;
+  /** The runner reports the charge was accepted and is now awaited. */
+  accepted: () => void;
+  /** The runner, or the raise, gave up: back to the list as it was. */
+  settle: () => void;
+  /** The CARD order the runner charges — set once one is held for this charge. */
+  chargeable: CheckoutOrder | null;
+}
+
+/** A held CARD order still awaiting payment AND priced as the buyer now sees — reusable for the charge. */
+function reusable(order: CheckoutOrder | null, cartTotal: string): boolean {
+  return order?.method === "CARD" && order.status === "AWAITING_PAYMENT" && order.totalLabel === cartTotal;
+}
+
+/** The order `send` meant: the one it reused, or the CARD order raised to replace a stale one. */
+function chargeTarget(
+  order: CheckoutOrder | null,
+  target: { reuse: CheckoutOrder } | { replace: CheckoutOrder | null } | null,
+): CheckoutOrder | null {
+  if (!order || !target || order.method !== "CARD" || order.status !== "AWAITING_PAYMENT") return null;
+  if ("reuse" in target) return target.reuse === order ? order : null;
+  return order !== target.replace ? order : null;
+}
+
+/**
+ * The bar's charge, after the button (FUT-3592): count down for a card, then
+ * raise the order — or reuse the CARD order already held, after a refusal the
+ * buyer is retrying, but only while it is priced as the cart now is (a credit
+ * toggled, an address changed: re-raise, never charge the old amount) — and
+ * hand it to the runner that charges it.
+ *
+ * Nothing is sent before `sending`: the timer is the only thing running while
+ * the bar fills, so Cancelar has nothing to undo.
+ */
+export function useListCharge(ports: RaisePorts): ListCharge {
+  const [phase, setPhase] = useState<ListChargePhase>("idle");
+  const [kind, setKind] = useState<ListChargeKind | null>(null);
+  const [pressedTotal, setPressedTotal] = useState<string | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const allowed = useRef(true);
+  // What `send` decided to charge: the held order it reused, or "a fresh one"
+  // — any CARD order other than the stale one it replaced.
+  const target = useRef<{ reuse: CheckoutOrder } | { replace: CheckoutOrder | null } | null>(null);
+  const latest = useRef(ports);
+  latest.current = ports;
+
+  const cancel = useCallback(() => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+    setPhase("idle");
+    setKind(null);
+    setPressedTotal(null);
+  }, []);
+
+  const send = useCallback(() => {
+    timer.current = null;
+    // Checked again at the last moment: a hold raised between two renders
+    // must not let the bar's own timer charge past it.
+    if (!allowed.current) return cancel();
+    setPhase("sending");
+    const { order, cartTotal } = latest.current;
+    if (reusable(order, cartTotal) && order) {
+      target.current = { reuse: order };
+      return;
+    }
+    target.current = { replace: order };
+    latest.current.setMethod("CARD");
+    void latest.current.startPayment("CARD");
+  }, [cancel]);
+
+  const phaseRef = useRef(phase);
+  phaseRef.current = phase;
+  const start = useCallback(
+    (next: ListChargeKind, total: string) => {
+      if (phaseRef.current !== "idle") return;
+      phaseRef.current = next === "GOOGLE_PAY" ? "sending" : "counting";
+      setKind(next);
+      setPressedTotal(total);
+      if (next === "GOOGLE_PAY") return send();
+      setPhase("counting");
+      timer.current = setTimeout(send, CHARGE_WINDOW_MS);
+    },
+    [send],
+  );
+
+  const setAllowed = useCallback(
+    (next: boolean) => {
+      allowed.current = next;
+      if (!next && phaseRef.current === "counting") cancel();
+    },
+    [cancel],
+  );
+
+  const settle = cancel;
+  const accepted = useCallback(() => setPhase("waiting"), []);
+
+  useEffect(() => () => {
+    if (timer.current) clearTimeout(timer.current);
+  }, []);
+
+  // A raise that failed leaves nothing to charge: back to the list, where the
+  // step's error panel says why.
+  const { order, creating, createError } = ports;
+  useEffect(() => {
+    if (phase === "sending" && !creating && !order && createError) settle();
+  }, [phase, creating, order, createError, settle]);
+
+  const sending = phase === "sending" || phase === "waiting";
+  const chargeable = sending && !creating ? chargeTarget(order, target.current) : null;
+  return { phase, kind, pressedTotal, start, cancel, setAllowed, accepted, settle, chargeable };
+}

package/src/components/checkout/list/use-list-state.ts

@@ -0,0 +1,152 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type Dispatch, type SetStateAction } from "react";
+
+import { NEW_CARD, type CardDetails, type CardFieldErrors, type SavedCard } from "../../../card";
+import { useSavedCardList } from "../card-sources";
+import { useCheckoutCopy } from "../copy-context";
+import type { BuyerInfo, CheckoutCustomerField, CheckoutProviderConfig } from "../types";
+
+import { askedFields, cardComplete, onlineRows, preselection, raisedMethod, type OnlineCapability, type OnlineRow } from "./choice";
+import type { CheckoutListChoice } from "./types";
+
+const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
+
+/** The card the buyer pays with, as the list holds it before any order exists. */
+export interface ListCard {
+  saved: SavedCard[];
+  /** A saved card's id, `NEW_CARD` for the fields, or `null` when none is chosen. */
+  selection: string | null;
+  setSelection: (selection: string | null) => void;
+  card: CardDetails;
+  setCard: Dispatch<SetStateAction<CardDetails>>;
+  fieldErrors: CardFieldErrors;
+  setFieldErrors: Dispatch<SetStateAction<CardFieldErrors>>;
+  saveCard: boolean;
+  setSaveCard: (save: boolean) => void;
+  complete: boolean;
+}
+
+/** Everything the one list holds, and nothing it raises. */
+export interface ListState {
+  rows: OnlineRow[];
+  choice: CheckoutListChoice | null;
+  choose: (next: CheckoutListChoice) => void;
+  card: ListCard;
+  /** The buyer's own details the chosen online option must ask for (M11). */
+  asked: CheckoutCustomerField[];
+}
+
+/**
+ * The card the buyer is typing or has picked. It outlives every order raised
+ * under it: the charge reads it when the 5-second bar fills, and a refusal
+ * brings the buyer back to it as they left it.
+ */
+function useListCard(saved: SavedCard[]): ListCard {
+  const fieldCopy = useCheckoutCopy().card.fields;
+  const [selection, setSelection] = useState<string | null>(null);
+  const [card, setCard] = useState<CardDetails>(EMPTY_CARD);
+  const [fieldErrors, setFieldErrors] = useState<CardFieldErrors>({});
+  const [saveCard, setSaveCard] = useState(false);
+  const complete = useMemo(() => cardComplete(card, fieldCopy), [card, fieldCopy]);
+  return { saved, selection, setSelection, card, setCard, fieldErrors, setFieldErrors, saveCard, setSaveCard, complete };
+}
+
+/**
+ * Preselect ONCE, when the saved cards answer — never over a choice the buyer
+ * already made, and never again after they made one (M7).
+ */
+function usePreselect(
+  loaded: boolean,
+  rows: readonly OnlineRow[],
+  saved: readonly SavedCard[],
+  fresh: boolean,
+  apply: (choice: CheckoutListChoice, selection: string | null) => void,
+  touched: { current: boolean },
+): void {
+  const done = useRef(false);
+  useEffect(() => {
+    if (done.current || touched.current || !loaded) return;
+    done.current = true;
+    const pick = preselection(rows, saved, fresh);
+    if (pick) apply(pick.choice, pick.selection);
+  }, [loaded, rows, saved, fresh, apply, touched]);
+}
+
+/**
+ * The card chosen again: the head of the saved list — or, for a buyer back from
+ * a refused card (FUT-1145), no saved card at all (the head may be the one that
+ * failed), or the fields when nothing is saved.
+ */
+function reopenedSelection(cards: readonly SavedCard[], fresh: boolean): string | null {
+  const head = cards[0];
+  if (!head) return NEW_CARD;
+  return fresh ? null : head.id;
+}
+
+/**
+ * The one list's state (FUT-3591). Picking an option changes THIS and nothing
+ * else: no order, no charge, no request — the bar's button is the only thing
+ * that raises (M7). The host hears about every change through
+ * `onChoiceChange`, which is how its door options learn they are chosen.
+ */
+export function useListState(input: {
+  config: CheckoutProviderConfig | null;
+  capability: OnlineCapability;
+  tenantSlug: string | undefined;
+  /** Back here after a refused card (FUT-1145): no saved card is selected for them. */
+  fresh: boolean;
+  arrivedWith: BuyerInfo | undefined;
+  taxIdOnFile: boolean;
+  onChoiceChange?: (choice: CheckoutListChoice | null) => void;
+}): ListState {
+  const { capability } = input;
+  const rows = useMemo(() => onlineRows(capability), [capability]);
+  const { cards, loaded } = useSavedCardList(input.tenantSlug);
+  const card = useListCard(cards);
+  const [choice, setChoice] = useState<CheckoutListChoice | null>(null);
+  const touched = useRef(false);
+  const { setSelection } = card;
+  const apply = useCallback(
+    (next: CheckoutListChoice, selection: string | null) => {
+      setChoice(next);
+      if (selection !== null) setSelection(selection);
+    },
+    [setSelection],
+  );
+  usePreselect(loaded, rows, cards, input.fresh, apply, touched);
+  const choose = useCallback(
+    (next: CheckoutListChoice) => {
+      touched.current = true;
+      setChoice((previous) => {
+        // Coming back to the card from another option starts on the head of
+        // the saved list again (FN:420), or on the fields when there is none;
+        // what was typed in them is kept.
+        const reopensCard = next.kind === "online" && next.method === "CARD" && !(previous?.kind === "online" && previous.method === "CARD");
+        if (reopensCard) setSelection(reopenedSelection(cards, input.fresh));
+        return next;
+      });
+    },
+    [cards, setSelection, input.fresh],
+  );
+  // A choice the chain no longer offers (a config that resolved to a hand-off
+  // store after the card was preselected) is no choice at all.
+  useEffect(() => {
+    if (choice?.kind === "online" && !rows.some((row) => row.method === choice.method && !row.disabled)) setChoice(null);
+  }, [choice, rows]);
+  const { onChoiceChange } = input;
+  useEffect(() => {
+    onChoiceChange?.(choice);
+  }, [choice, onChoiceChange]);
+  const asked = useMemo(
+    () =>
+      choice?.kind === "online"
+        ? askedFields({
+            chain: input.config?.chain,
+            method: raisedMethod(choice.method, capability.offered),
+            arrivedWith: input.arrivedWith,
+            taxIdOnFile: input.taxIdOnFile,
+          })
+        : [],
+    [choice, input.config, capability.offered, input.arrivedWith, input.taxIdOnFile],
+  );
+  return { rows, choice, choose, card, asked };
+}