@12-apps/payments-frontend 1.21.1 → 2.1.0

package/src/components/checkout/types.ts

@@ -92,7 +92,7 @@ export interface CheckoutOrder {
   totalCents: number;
   /**
    * GROSS total before discounts, or null when the discount engine never ran
-   * for this order (every order predating FUT-235, and the comanda path): the
+   * for this order (every order predating FUT-235, and the settlement path): the
    * subtotal then simply IS {@link totalCents}.
    */
   subtotalCents: number | null;
@@ -117,13 +117,25 @@ export interface CheckoutOrder {
 }
 
 /**
- * Comanda settlement context for the checkout (FUT-comandas): the scope plus
- * the host-resolved totals shown in place of the cart total when settling a
- * comanda. HOW a comanda is resolved is the host's business; the flow only
- * renders the answer.
+ * SETTLEMENT context: this checkout pays an already-open balance rather than
+ * the cart.
+ *
+ * Named for what it does, not for the one product it came from. It was
+ * `SettlementCheckout` with `scope: "MINE" | "TABLE"` — a restaurant tab and its
+ * two ways of splitting one — which is a real concept but that host's, and it
+ * arrived in every adopter's type surface. The shape underneath is general: a
+ * host has resolved SOME balance, by whatever rule it likes, and the flow shows
+ * that total in place of the cart's.
+ *
+ * `scope` is an opaque string the library only echoes back. It exists so a host
+ * can tell its own two settlement modes apart in the events it receives; this
+ * package neither reads it nor enumerates it, which is exactly why it must not
+ * publish a closed set of somebody else's words.
+ *
+ * HOW a balance is resolved is the host's business; the flow renders the answer.
  */
-export interface ComandaCheckout {
-  scope: "MINE" | "TABLE";
+export interface SettlementCheckout {
+  scope: string;
   totalLabel: string;
   totalItems: number;
 }
@@ -153,7 +165,7 @@ export type CreateOrderResult =
 
 /**
  * What the flow hands the host's `createOrder` port. Everything else an order
- * needs — WHICH cart, WHICH comanda scope, WHICH tenant — is the host's own
+ * needs — WHICH cart, WHICH settlement scope, WHICH tenant — is the host's own
  * context, closed over by its port implementation.
  */
 export interface CreateOrderRequest {

package/src/components/checkout/use-checkout-controller.ts

@@ -35,15 +35,15 @@ const CPF_ONLY: readonly CheckoutCustomerField[] = [
 export interface CheckoutHostPorts {
   /**
    * Raise the order (and its first charge). The host closes over everything
-   * the flow must not know: WHICH cart, WHICH tenant, WHICH comanda scope.
-   */
+   * the flow must not know: WHICH cart, WHICH tenant, WHICH settlement scope.
+ */
   createOrder: (input: CreateOrderRequest) => Promise<CreateOrderResult>;
   /**
    * Persist the buyer's contact when they press "Continuar" on Dados — the
    * host's account surface owns the write (and the blank-CPF-never-clears
    * rule). Fire-and-forget by contract: the flow advances regardless of the
    * outcome, and only calls this under the "salvar meus dados" consent.
-   */
+ */
   saveBuyerContact?: (contact: BuyerContact) => void;
   /** Leave checkout for the host's menu/catalog. */
   onExitToMenu: () => void;
@@ -52,7 +52,7 @@ export interface CheckoutHostPorts {
    * server emptied it inside the confirmation transaction (FUT-601) and
    * nothing else tells the SPA. Never fired for FAILED/EXPIRED: that shopper
    * still has a basket to retry with.
-   */
+ */
   onPaid?: () => void;
 }
 

package/src/components/credential-rules.ts

@@ -18,21 +18,36 @@ import type { PendingSave } from './ConfirmCredentialSave';
  */
 
 /**
- * Is there actually something stored to probe?
+ * Is there enough on record to make the probe WORTH RUNNING?
  *
- * Read from the SERVER's answer to the save rather than from the form: blank
- * fields are preserved rather than cleared, so what the browser just typed does
- * not describe what is now on record.
+ * A required-field test cannot answer this, and Stripe is why: every field in its
+ * schema is `required: false`, because under authorization the access token
+ * fulfils the secret key and nothing needs typing at all. On the credentials
+ * path that makes the required-field test vacuously true, so a save with one
+ * key pasted and three boxes empty went straight to the probe and came back
+ * "Credenciais recusadas pela Stripe." — a rejection reported for a request
+ * that was never worth making, blaming the owner mid-way through typing.
+ *
+ * So completeness is measured over the schema MINUS its `advanced` fields.
+ * Not the whole schema: that asked for Stripe's `connectedAccountId`, which
+ * ordinary stores must leave empty, and owners filled it with their own account
+ * id to satisfy the button — producing exactly the refusal this was meant to
+ * prevent. A partial save is still a perfectly good save (blank fields preserve
+ * what is stored); it simply is not yet a connection worth testing.
  */
-export function allRequiredStored(
+export function credentialsComplete(
   descriptor: ProviderDescriptor,
-  config: MaskedProviderConfig,
+  config: MaskedProviderConfig | null,
   environment: PaymentEnvironment,
+  values: Record<string, string>,
 ): boolean {
-  const stored = config.environments[environment] ?? {};
-  return descriptor.credentialSchema
-    .filter((spec) => spec.required)
-    .every((spec) => stored[spec.key]?.configured === true);
+  const stored = config?.environments[environment] ?? {};
+  return descriptor.credentialSchema.every((spec) => {
+    if (spec.advanced) return true;
+    const typed = values[spec.key];
+    if (typed !== undefined && typed.trim() !== '') return true;
+    return stored[spec.key]?.configured === true;
+  });
 }
 
 /**
@@ -55,10 +70,31 @@ export function fieldsWellFormed(
   });
 }
 
-export function saveLabel(descriptor: ProviderDescriptor): string {
+/**
+ * What the one button says it will do — and it does BOTH halves.
+ *
+ * Saving IS testing (see `FormActions`): the write is followed straight away by
+ * the probe, which is what reaches the provider with the pasted keys and, on a
+ * pass, is the only thing that makes the activation charge appear. A button
+ * reading "Salvar" claims half of that. On the credentials path the owner has
+ * no other control, so they were left looking for the one that sends the keys
+ * to the provider — there isn't one, because this is it.
+ *
+ * …but only once there is a connection to test. Half a credential set cannot
+ * be, so a partly-filled form says plain "Salvar" and the save skips the probe:
+ * promising a test that is then reported as "Credenciais recusadas" is worse
+ * than promising nothing, because it reads as a verdict on what was typed.
+ *
+ * A provider whose whole connection is ONE field keeps naming that field
+ * instead. The label then says what is about to be committed rather than merely
+ * that something is, and on a step whose entire content is that single box that
+ * is the more useful of the two truths. Naming one of Stripe's four would be a
+ * lie about what the button writes, which is why only the fallback changes.
+ */
+export function saveLabel(descriptor: ProviderDescriptor, complete: boolean): string {
   const required = descriptor.credentialSchema.filter((field) => field.required);
   const only = required.length === 1 ? required[0] : undefined;
-  if (!only) return 'Salvar';
+  if (!only) return complete ? 'Salvar e testar conexão' : 'Salvar';
   return `Salvar ${only.label.replace(/\s*\([^)]*\)\s*$/, '')}`;
 }
 

package/src/components/panel-tokens.ts

@@ -0,0 +1,166 @@
+/**
+ * The payments screen's own palette and geometry, taken verbatim from the
+ * design prototype.
+ *
+ * Local rather than theme-level on purpose. `@repo/spa-shared/theme` says it in
+ * as many words — "re-deriving them here would quietly restyle every admin
+ * screen from a function nobody thinks of as owning that" — and the platform
+ * primary (`#6366F1`) is a decision already made for the rest of the app. This
+ * screen is a designed surface with its own greens, ambers and hairlines, and
+ * matching it must not move a single pixel anywhere else.
+ *
+ * Every value here is a hex the prototype states, not an approximation: a
+ * "pixel perfect" screen that rounds its own line colour to `divider` is a
+ * screen that looks nearly right and reviews as wrong.
+ */
+export const T = {
+  ink: '#111318',
+  ink2: '#3d4350',
+  ink3: '#6b7280',
+  ink4: '#9aa1ad',
+  line: '#e4e7ec',
+  line2: '#eef0f4',
+  bg: '#ffffff',
+  bg2: '#f7f8fa',
+
+  brand: '#5b5bd6',
+  brandInk: '#4a4ac4',
+  brandSoft: '#eeeefc',
+  brandLine: '#c9c9f2',
+
+  ok: '#0f7a4d',
+  okSoft: '#e8f6ef',
+  okLine: '#bfe5d3',
+  okInk: '#0b5c3a',
+
+  warn: '#b45309',
+  warnSoft: '#fdf1e3',
+  warnLine: '#f3d9b5',
+  warnInk: '#7c3d06',
+
+  bad: '#c02626',
+  badSoft: '#fdeceb',
+  badLine: '#f5c6c2',
+  badInk: '#8f1d1d',
+
+  info: '#1d6fa5',
+  infoSoft: '#e8f3fb',
+  infoLine: '#bfdcf0',
+  infoInk: '#14496b',
+
+  mono: '"SFMono-Regular",ui-monospace,Menlo,Consolas,monospace',
+} as const;
+
+/** The card that bounds one provider: hairline, 12px, nothing clipped. */
+export const CARD_SX = {
+  border: `1px solid ${T.line}`,
+  borderRadius: '12px',
+  background: T.bg,
+  overflow: 'hidden',
+} as const;
+
+/**
+ * A step's panel — the bordered block a single step lives in.
+ *
+ * `overflow: hidden` matters: the action bar below sticks to its bottom edge
+ * and would otherwise paint over the rounded corner.
+ */
+export const PANEL_SX = {
+  border: `1px solid ${T.line}`,
+  borderRadius: '11px',
+  overflow: 'hidden',
+  mx: '20px',
+  mb: '20px',
+} as const;
+
+/**
+ * The action bar: the primary control, always the last thing in the block the
+ * owner just filled.
+ *
+ * Sticky rather than merely last, so on a long step (the four credential boxes,
+ * the card form) the button the owner is working toward stays on screen instead
+ * of being something they have to go and find.
+ */
+export const BAR_SX = {
+  position: 'sticky',
+  bottom: 0,
+  background: 'rgba(255,255,255,.94)',
+  backdropFilter: 'blur(6px)',
+  borderTop: `1px solid ${T.line}`,
+  px: '18px',
+  py: '12px',
+  display: 'flex',
+  alignItems: 'center',
+  gap: '12px',
+  flexWrap: 'wrap',
+} as const;
+
+/** The sentence beside the button — why it is enabled, or what just happened. */
+export const BAR_MSG_SX = {
+  fontSize: '12.5px',
+  color: T.ink3,
+  flex: 1,
+  minWidth: '140px',
+  lineHeight: 1.4,
+} as const;
+
+/** Primary: the one thing this step is for. */
+export const BTN_PRIMARY_SX = {
+  borderRadius: '8px',
+  px: '18px',
+  py: '10px',
+  fontSize: '13.5px',
+  fontWeight: 650,
+  textTransform: 'none',
+  boxShadow: 'none',
+  background: T.brand,
+  color: '#fff',
+  '&:hover': { background: T.brandInk, boxShadow: 'none' },
+  '&.Mui-disabled': { background: '#c9cad6', color: '#fff' },
+} as const;
+
+/** Secondary: a real alternative, not a lesser primary. */
+export const BTN_SECONDARY_SX = {
+  borderRadius: '8px',
+  px: '18px',
+  py: '10px',
+  fontSize: '13.5px',
+  fontWeight: 650,
+  textTransform: 'none',
+  background: T.bg,
+  border: `1px solid ${T.line}`,
+  color: T.ink2,
+  '&:hover': { borderColor: T.ink4, background: T.bg },
+} as const;
+
+/**
+ * Destructive, stated quietly.
+ *
+ * "Remover conexão" sits beside the step's own button and must not compete with
+ * it — an owner reaches this deliberately or not at all, and a red filled button
+ * on every step is an invitation to misclick.
+ */
+export const BTN_QUIET_DANGER_SX = {
+  background: 'none',
+  border: 0,
+  color: T.bad,
+  px: '6px',
+  py: '10px',
+  fontSize: '13.5px',
+  fontWeight: 600,
+  textTransform: 'none',
+  '&:hover': { background: 'none', textDecoration: 'underline' },
+} as const;
+
+/** An inline text control — the way between the two connection paths. */
+export const LINKISH_SX = {
+  background: 'none',
+  border: 0,
+  color: T.brand,
+  fontSize: '12.5px',
+  p: 0,
+  minWidth: 0,
+  textTransform: 'none',
+  verticalAlign: 'baseline',
+  '&:hover': { background: 'none', textDecoration: 'underline' },
+} as const;

package/src/flows/copy.ts

@@ -9,8 +9,13 @@
  * keep it; moving all of it here in the same change that introduces the factory
  * would be a copy rewrite disguised as an API.
  *
- * Every default below is today's pt-BR, verbatim — a host that passes no `copy`
- * reads exactly what a buyer reads now.
+ * THE DEFAULTS ARE GONE (FUT-760). `DEFAULT_CHECKOUT_COPY_FE` held one
+ * product's RESTAURANT vocabulary — "Pagamento com o garçom", "Chame o garçom
+ * para fechar a conta na mesa", "Ver cardápio" — and was spread into every
+ * adopter that passed no `copy`. A host selling insurance got a waiter, and
+ * nothing failed, because saying nothing is exactly how a host silently adopts
+ * another product's voice. `copy` is required on the config now; this file is
+ * the port and nothing else.
  */
 
 /** Every buyer-facing string the factory's own screens render. */
@@ -49,33 +54,3 @@ export interface CheckoutCopyFE {
   manageCardsEmpty: string;
   manageCardsAdd: string;
 }
-
-export const DEFAULT_CHECKOUT_COPY_FE: CheckoutCopyFE = {
-  unavailableTitle: "Pagamento online indisponível",
-  unavailableBody:
-    "Esta loja não recebe pagamentos pelo site. Combine o pagamento diretamente com a loja para concluir seu pedido.",
-  unavailableWithRemedyTitle: "Pagamento com o garçom",
-  unavailableWithRemedyBody:
-    "Esta loja não recebe pagamentos pelo site. Chame o garçom para fechar a conta na mesa.",
-  handoffTitle: "Você será levado ao pagamento",
-  handoffBody:
-    "Estamos abrindo a página segura do meio de pagamento. Se ela não abrir sozinha, use o link abaixo.",
-  handoffLink: "Abrir a página de pagamento",
-  handoffCancel: "Voltar",
-  returnPending: "Confirmando seu pagamento…",
-  returnUnknown:
-    "Não encontramos um pagamento em andamento nesta sessão. Verifique seus pedidos em instantes.",
-  emptyCartTitle: "Seu carrinho está vazio.",
-  emptyCartAction: "Ver cardápio",
-  continueAction: "Continuar",
-  addCardTitle: "Adicionar cartão",
-  addCardAction: "Salvar cartão",
-  addCardPreparing: "Preparando o formulário…",
-  addCardSavedTitle: "Cartão salvo",
-  addCardSavedBody: "Você poderá usá-lo nas próximas compras.",
-  addCardFailedTitle: "Não foi possível salvar o cartão",
-  addCardUnavailable: "Esta loja não aceita salvar cartões no momento.",
-  manageCardsTitle: "Meus cartões",
-  manageCardsEmpty: "Você ainda não tem cartões salvos.",
-  manageCardsAdd: "Adicionar cartão",
-};

package/src/flows/create-payment-flows.tsx

@@ -7,7 +7,7 @@
  *
  * ## Why the scope arrives as HOOKS
  *
- * `useScope`, `useCart`, `useBuyerDefaults`, `useComanda` and
+ * `useScope`, `useCart`, `useBuyerDefaults`, `useSettlement` and
  * `ports.useAvailability` are hooks, not values, and they are invoked in a
  * component BODY — never read at factory time. The factory runs once, at module
  * evaluation, so a value-shaped config would freeze the first store's slug and
@@ -19,10 +19,9 @@ import { useCallback, type JSX, type ReactNode } from "react";
 import { buyerFieldsFor } from "../components/checkout/buyer-fields";
 import { CheckoutFlow } from "../components/checkout/checkout-flow";
 import { createCheckoutClient } from "../components/checkout/transport";
-import type { CheckoutProviderConfig, ComandaCheckout } from "../components/checkout/types";
+import type { CheckoutProviderConfig, SettlementCheckout } from "../components/checkout/types";
 import { useCheckoutController } from "../components/checkout/use-checkout-controller";
 
-import { DEFAULT_CHECKOUT_COPY_FE } from "./copy";
 import { FlowsProvider, useResolvedConfig, type FlowsRuntime } from "./runtime";
 import { buyerScreens } from "./screens-buyer";
 import { hostedScreens } from "./screens-hosted";
@@ -50,7 +49,7 @@ function buildRuntime(config: PaymentFlowsConfig): FlowsRuntime {
   return {
     config,
     client,
-    copy: { ...DEFAULT_CHECKOUT_COPY_FE, ...config.copy },
+    copy: config.copy,
     navigate,
     // Both of these are HOOKS. They are called from a component body on every
     // render, so the slug follows the host's router and the availability vote
@@ -68,10 +67,10 @@ function buildCheckout(
   const { ports } = runtime.config;
   const Unavailable = screens.PaymentsUnavailable;
 
-  function CheckoutBody({ comanda }: { comanda?: ComandaCheckout | null }): JSX.Element {
+  function CheckoutBody({ settlement }: { settlement?: SettlementCheckout | null }): JSX.Element {
     const cart = runtime.config.useCart();
     const defaults = runtime.config.useBuyerDefaults?.() ?? {};
-    const hostComanda = runtime.config.useComanda?.() ?? null;
+    const hostSettlement = runtime.config.useSettlement?.() ?? null;
     const { config, pending } = useResolvedConfig(runtime);
     const availability = runtime.useAvailability();
     const tenantSlug = runtime.useTenantSlug();
@@ -93,7 +92,7 @@ function buildCheckout(
         onPaid={ports.onPaid}
         defaultBuyer={defaults.buyer}
         taxIdOnFile={defaults.taxIdOnFile ?? false}
-        comanda={comanda ?? hostComanda}
+        settlement={settlement ?? hostSettlement}
         providerConfig={config}
         tenantSlug={tenantSlug}
         confirmationExtra={runtime.config.confirmation?.extra}

package/src/flows/types.ts

@@ -31,7 +31,7 @@ import type {
   ChargeOutcome,
   CheckoutOrder,
   CheckoutProviderConfig,
-  ComandaCheckout,
+  SettlementCheckout,
   CreateOrderRequest,
   CreateOrderResult,
   OrderStatus,
@@ -100,8 +100,8 @@ export interface PaymentFlowsConfig {
   useCart(): CheckoutCartView;
   /** The buyer's saved details, and whether a CPF is already on file. */
   useBuyerDefaults?(): { buyer?: BuyerInfo; taxIdOnFile?: boolean; pending?: boolean };
-  /** Present ⇒ this checkout settles a comanda rather than the cart. */
-  useComanda?(): ComandaCheckout | null;
+  /** Present ⇒ this checkout settles a settlement rather than the cart. */
+  useSettlement?(): SettlementCheckout | null;
 
   /** Design-system slots, filled ONCE instead of per screen. */
   components?: Partial<CheckoutComponents>;
@@ -117,7 +117,20 @@ export interface PaymentFlowsConfig {
   // "what happens WHEN it fires": a timed-out mint must decide whether the walk
   // advances to the next entry or the whole charge refuses, and that is a money
   // rule (FUT-563), not a wire-up.
-  copy?: Partial<CheckoutCopyFE>;
+  /**
+   * Every buyer-facing sentence the factory's own screens render.
+   *
+   * REQUIRED, and not partial. It used to be `Partial<…>` over a pt-BR default
+   * spread in at `create-payment-flows.tsx`, and that default was one product's
+   * RESTAURANT vocabulary — "Pagamento com o garçom", "Chame o garçom para
+   * fechar a conta na mesa", "Ver cardápio" — reaching every adopter that said
+   * nothing. A host selling insurance got a waiter.
+   *
+   * That is the failure a default cannot warn about: saying nothing is exactly
+   * how a host adopts another product's voice, and nothing fails. Required
+   * makes a new host answer once, at the one call site that knows the answer.
+   */
+  copy: CheckoutCopyFE;
   /** Host content under the paid receipt (the storefront's PWA install invite). */
   confirmation?: { extra?: ReactNode };
   /**
@@ -187,7 +200,7 @@ export interface CheckoutConfigState {
 /** What `createPaymentFlows` returns. */
 export interface PaymentFlows {
   /** THE mount: a complete buyer checkout in one line. */
-  Checkout: ComponentType<{ comanda?: ComandaCheckout | null }>;
+  Checkout: ComponentType<{ settlement?: SettlementCheckout | null }>;
   /** Slots + transport + scope + the fetched config, for a nesting host. */
   Provider: ComponentType<{ children: ReactNode; config?: CheckoutProviderConfig | null }>;
   screens: CheckoutScreens;

package/src/index.ts

@@ -56,10 +56,9 @@ export {
 // hand-composing path is unchanged.
 // ---------------------------------------------------------------------------
 export { createPaymentFlows } from './flows/create-payment-flows';
-export {
-  DEFAULT_CHECKOUT_COPY_FE,
-  type CheckoutCopyFE,
-} from './flows/copy';
+// A type and nothing else now: `DEFAULT_CHECKOUT_COPY_FE` used to sit beside it
+// and was the only value this module ever published (FUT-760).
+export type { CheckoutCopyFE } from './flows/copy';
 export {
   type BoundCheckoutClient,
   type BuyerDetailsProps,
@@ -143,7 +142,7 @@ export {
   type CheckoutOrder,
   type CheckoutProviderConfig,
   type CheckoutWalletType,
-  type ComandaCheckout,
+  type SettlementCheckout,
   type CreateOrderRequest,
   type CreateOrderResult,
   type OrderStatus,