@12-apps/payments-frontend 3.26.0 → 3.27.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.26.0",
+  "version": "3.27.1",
   "type": "module",
   "sideEffects": false,
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",
@@ -9,6 +9,7 @@
     "./locales": "./src/locales.ts",
     "./manifest": "./src/manifest/index.ts",
     "./manifest/web": "./src/manifest/web.ts",
+    "./tender-split": "./src/tender-split/index.ts",
     "./package.json": "./package.json"
   },
   "scripts": {

package/src/components/checkout/icons.tsx

@@ -59,3 +59,7 @@ export const ScheduleIcon = makeIcon([
 export const PersonOutlineIcon = makeIcon([
   'M12 5.9c1.16 0 2.1.94 2.1 2.1s-.94 2.1-2.1 2.1S9.9 9.16 9.9 8s.94-2.1 2.1-2.1m0 9c2.97 0 6.1 1.46 6.1 2.1v1.1H5.9V17c0-.64 3.13-2.1 6.1-2.1M12 4C9.79 4 8 5.79 8 8s1.79 4 4 4 4-1.79 4-4-1.79-4-4-4m0 9c-2.67 0-8 1.34-8 4v3h16v-3c0-2.66-5.33-4-8-4',
 ]);
+
+export const CloseIcon = makeIcon([
+  'M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z',
+]);

package/src/locales.ts

@@ -27,6 +27,9 @@ import { PT_BR_PLATFORM_HOMOLOGACAO_COPY } from './components/platform/pt-BR';
 import { EN_US_PAYMENTS_SETTINGS_COPY } from './components/settings-en-US';
 import type { PaymentsSettingsCopy } from './components/settings-copy';
 import { PT_BR_PAYMENTS_SETTINGS_COPY } from './components/settings-pt-BR';
+import type { TenderSplitCopy } from './tender-split/copy';
+import { EN_US_TENDER_SPLIT_COPY } from './tender-split/en-US';
+import { PT_BR_TENDER_SPLIT_COPY } from './tender-split/pt-BR';
 
 /**
  * Every surface this half renders, in both languages, keyed by tag.
@@ -54,6 +57,15 @@ export const ACTIVATION_STEP_COPY = {
   'en-US': EN_US_ACTIVATION_STEP_COPY,
 } as const satisfies LocalePack<ActivationStepCopy>;
 
+/**
+ * `TenderSplit`'s words (`./tender-split`) — read by the OPERATOR recording
+ * money taken in person, so they resolve from the operator's preference.
+ */
+export const TENDER_SPLIT_COPY = {
+  'pt-BR': PT_BR_TENDER_SPLIT_COPY,
+  'en-US': EN_US_TENDER_SPLIT_COPY,
+} as const satisfies LocalePack<TenderSplitCopy>;
+
 export const CARD_COPY = {
   'pt-BR': PT_BR_CARD_COPY,
   'en-US': EN_US_CARD_COPY,
@@ -113,3 +125,4 @@ export {
 export { EN_US_CHECKOUT_SCREENS_COPY } from './components/checkout/screens-en-US';
 export { EN_US_PAYMENTS_SETTINGS_COPY } from './components/settings-en-US';
 export { EN_US_PLATFORM_HOMOLOGACAO_COPY } from './components/platform/en-US';
+export { EN_US_TENDER_SPLIT_COPY } from './tender-split/en-US';

package/src/tender-split/copy.ts

@@ -0,0 +1,41 @@
+/**
+ * Every word `TenderSplit` puts in front of the operator.
+ *
+ * Required, with no defaults — this package's own doctrine (see
+ * `../card/copy.ts`): a default in one host's language reads as finished to
+ * the next host until somebody sees it. The tenders' own names are not here
+ * either; they arrive with each {@link TenderOption}, because which tenders a
+ * store takes, and what it calls them, is the host's catalogue.
+ *
+ * The functions receive amounts ALREADY formatted in the host's locale and
+ * currency, so no sentence here builds a number itself.
+ */
+export interface TenderSplitCopy {
+  /** Beside the amount already carried by the picks — "Lançado". */
+  readonly launchedLabel: string;
+  /** Beside the amount still unpaid — "Falta". */
+  readonly missingLabel: string;
+  /** Once the picks cover the bill — "Fechou". */
+  readonly coveredLabel: string;
+  /** The picks pass the bill with nothing to hand back — "Passou R$ 5,00". */
+  readonly over: (amount: string) => string;
+  /** Names the progress bar for a screen reader. */
+  readonly progressLabel: string;
+  /** Beside the currency sign of a tender that takes an equal share — "dividido". */
+  readonly sharedHint: string;
+  /** Names a tender's amount field for a screen reader — "Valor em Dinheiro". */
+  readonly amountLabel: (tender: string) => string;
+  /** Names the control that drops a tender — "Tirar Dinheiro". */
+  readonly remove: (tender: string) => string;
+  /** The line naming the change handed back — "Troco". */
+  readonly changeLabel: string;
+  /** The confirm, before any tender is picked — "Escolha a forma". */
+  readonly pickFirst: string;
+  /** The confirm, while part of the bill is unpaid — "Falta R$ 5,00". */
+  readonly missing: (amount: string) => string;
+  /** The confirm, while a typed amount is not an amount. */
+  readonly invalid: string;
+  /** The confirm, once the bill is covered — "Confirmar R$ 82,00". */
+  readonly confirm: (amount: string) => string;
+  readonly cancel: string;
+}

package/src/tender-split/en-US.ts

@@ -0,0 +1,19 @@
+import type { TenderSplitCopy } from './copy';
+
+/** `TenderSplit` in en-US — a named pack, never a default (see `./copy`). */
+export const EN_US_TENDER_SPLIT_COPY: TenderSplitCopy = {
+  launchedLabel: 'Recorded',
+  missingLabel: 'Left',
+  coveredLabel: 'Covered',
+  over: (amount) => `Over by ${amount}`,
+  progressLabel: 'How much of the bill is recorded',
+  sharedHint: 'split',
+  amountLabel: (tender) => `Amount in ${tender}`,
+  remove: (tender) => `Remove ${tender}`,
+  changeLabel: 'Change',
+  pickFirst: 'Pick a method',
+  missing: (amount) => `${amount} left`,
+  invalid: 'Invalid amount',
+  confirm: (amount) => `Confirm ${amount}`,
+  cancel: 'Cancel',
+};

package/src/tender-split/index.ts

@@ -0,0 +1,26 @@
+/**
+ * `@12-apps/payments-frontend/tender-split` — "how was it paid?" for money
+ * taken in person: the tenders as cards, an equal split as they are tapped,
+ * typed amounts that stay put, change for the tender that gives it.
+ *
+ * Its own entry rather than the root barrel's: it needs none of the online
+ * payments client, and a host asking only this question should not pull it.
+ */
+export { TenderSplit, type TenderSplitProps } from './tender-split';
+export type { TenderOption } from './tender-card';
+export type { TenderSplitCopy } from './copy';
+export {
+  parseAmount,
+  readTenderSplit,
+  shareEqually,
+  withPicked,
+  withTyped,
+  withoutPicked,
+  type TenderPick,
+  type TenderSplitAnswer,
+  type TenderSplitLeg,
+  type TenderSplitOutcome,
+  type TenderSplitState,
+} from './math';
+export { PT_BR_TENDER_SPLIT_COPY } from './pt-BR';
+export { EN_US_TENDER_SPLIT_COPY } from './en-US';

package/src/tender-split/math.ts

@@ -0,0 +1,242 @@
+/**
+ * The arithmetic behind `TenderSplit` — which part of a bill each picked
+ * tender carries, and what the host is sent — kept free of React so it is
+ * tested on its own.
+ *
+ * ## Two kinds of pick
+ *
+ * A tender the operator only TAPPED is automatic: every automatic pick takes
+ * an equal share of what the typed picks leave, and the cent a division cannot
+ * place goes to the one tapped last (100 → 50/50 → 33,33/33,33/33,34). A
+ * tender whose amount the operator TYPED is fixed: it is never recalculated,
+ * not even when it is emptied (an empty field is a typed zero), until the pick
+ * is removed. That is the whole rule, and it is how an amount is said out
+ * loud: "cinquenta no dinheiro, o resto no cartão".
+ *
+ * ## What the host is sent
+ *
+ * One leg per tender carrying money, in the order they were picked. The LAST
+ * automatic leg goes without an amount — it is "the rest", divided by the
+ * server against the total it composes, so a total that moved between this
+ * screen and the write lands on that leg instead of being refused. With no
+ * automatic leg every amount is named and they add up to the total exactly.
+ *
+ * A tender flagged `givesChange` (cash) may be typed above what the bill
+ * leaves: the excess is change handed back, reported beside the legs and
+ * taken off that leg, never sent as money received.
+ */
+
+/** One picked tender: `typed` is what was typed, `null` while automatic. */
+export interface TenderPick<T extends string> {
+  readonly tender: T;
+  readonly typed: string | null;
+}
+
+/** One part of the payment. No `amountCents` means "whatever is left". */
+export interface TenderSplitLeg<T extends string> {
+  readonly tender: T;
+  readonly amountCents?: number;
+}
+
+/** What `TenderSplit` answers with. */
+export interface TenderSplitAnswer<T extends string> {
+  readonly legs: readonly TenderSplitLeg<T>[];
+  /** Handed back to the payer; already taken off the leg that received it. */
+  readonly changeCents: number;
+}
+
+/**
+ * Where the picks stand against the bill.
+ *
+ * - `EMPTY`: nothing picked yet.
+ * - `INVALID`: a typed amount is not an amount.
+ * - `SHORT`: the picks leave part of the bill unpaid.
+ * - `OVER`: the picks pass the bill and no change-giving tender explains it.
+ * - `READY`: the bill is covered; `answer` is set.
+ */
+export type TenderSplitOutcome = 'EMPTY' | 'INVALID' | 'SHORT' | 'OVER' | 'READY';
+
+export interface TenderSplitState<T extends string> {
+  /** Cents each pick carries: its typed amount, or its automatic share. */
+  readonly amounts: ReadonlyMap<T, number>;
+  readonly launchedCents: number;
+  /** The bill minus what the picks carry — negative when they pass it. */
+  readonly restCents: number;
+  readonly changeCents: number;
+  readonly outcome: TenderSplitOutcome;
+  readonly answer: TenderSplitAnswer<T> | null;
+}
+
+/** Tap a tender: it joins as automatic. A tender already picked is kept. */
+export function withPicked<T extends string>(
+  picks: readonly TenderPick<T>[],
+  tender: T,
+): TenderPick<T>[] {
+  if (picks.some((pick) => pick.tender === tender)) return [...picks];
+  return [...picks, { tender, typed: null }];
+}
+
+/** Remove a tender — the one way a typed amount stops being fixed. */
+export function withoutPicked<T extends string>(
+  picks: readonly TenderPick<T>[],
+  tender: T,
+): TenderPick<T>[] {
+  return picks.filter((pick) => pick.tender !== tender);
+}
+
+/** Type into a tender's field: from here on its amount is fixed. */
+export function withTyped<T extends string>(
+  picks: readonly TenderPick<T>[],
+  tender: T,
+  typed: string,
+  shown = '',
+): TenderPick<T>[] {
+  return picks.map((pick) =>
+    pick.tender === tender ? { tender, typed: firstTyping(pick, typed, shown) } : pick,
+  );
+}
+
+/**
+ * What an automatic card's field holds once the operator types into it.
+ *
+ * The field shows the card's share and selects it on focus, so a keystroke
+ * replaces it. Where the selection does not take (iOS Safari), the keystroke
+ * lands after the share instead — "41,00" + "5" → "41,005" — so on that FIRST
+ * edit the share still sitting in front of the new characters is dropped.
+ * `shown` is the share as the field displayed it.
+ */
+function firstTyping<T extends string>(pick: TenderPick<T>, typed: string, shown: string): string {
+  if (pick.typed !== null || shown === '' || typed === shown) return typed;
+  return typed.startsWith(shown) ? typed.slice(shown.length) : typed;
+}
+
+/**
+ * Typed money → whole cents; `0` for an empty field, `null` for text that is
+ * not an amount.
+ *
+ * Reads either separator, whatever the locale: a separator followed by one or
+ * two final digits is the decimal one and every other is grouping, so
+ * "50", "50,5", "50.50", "1.234,56" and "1,234.56" all read as written. A
+ * currency sign in front ("R$ 12,00", "$12") is ignored; a minus is refused.
+ */
+export function parseAmount(typed: string): number | null {
+  if (typed.includes('-')) return null;
+  const bare = typed.trim().replace(/^[^\d.,]+/u, '').replace(/\s/gu, '');
+  if (bare === '') return typed.trim() === '' ? 0 : null;
+  return /^[\d.,]+$/u.test(bare) ? centsOf(bare) : null;
+}
+
+/** Digits and separators → cents, or `null` when they are not an amount. */
+function centsOf(typed: string): number | null {
+  // A separator typed last is a decimal on its way ("50," while typing "50,50").
+  const bare = typed.replace(/[.,]$/u, '');
+  const decimal = /[.,](\d{1,2})$/u.exec(bare);
+  const whole = wholeUnits(decimal === null ? bare : bare.slice(0, decimal.index));
+  if (whole === null || (whole === '' && decimal === null)) return null;
+  const fraction = decimal === null ? '00' : decimal[1]!.padEnd(2, '0');
+  return Number(whole || '0') * 100 + Number(fraction);
+}
+
+/** The digits before the decimal separator; grouping only in threes, so "1,2,3" is refused. */
+function wholeUnits(grouped: string): string | null {
+  if (!/^(\d+|\d{1,3}([.,]\d{3})+)?$/u.test(grouped)) return null;
+  return grouped.replace(/[.,]/gu, '');
+}
+
+/** `pool` cents in `parts` equal shares; the leftover cents go to the last. */
+export function shareEqually(pool: number, parts: number): number[] {
+  if (parts <= 0) return [];
+  const base = Math.floor(Math.max(0, pool) / parts);
+  const shares = Array.from({ length: parts }, () => base);
+  shares[parts - 1] = Math.max(0, pool) - base * (parts - 1);
+  return shares;
+}
+
+/** Where the picks stand against a bill of `totalCents`. */
+export function readTenderSplit<T extends string>(
+  picks: readonly TenderPick<T>[],
+  totalCents: number,
+  givesChange: (tender: T) => boolean,
+): TenderSplitState<T> {
+  const amounts = amountsOf(picks, totalCents);
+  const sum = [...amounts.values()].reduce((total, cents) => total + cents, 0);
+  const restCents = totalCents - sum;
+  const base = { amounts, launchedCents: Math.min(sum, totalCents), restCents };
+  const outcome = outcomeOf(picks, restCents);
+  if (outcome === 'SHORT' || outcome === 'EMPTY' || outcome === 'INVALID') {
+    return { ...base, changeCents: 0, outcome, answer: null };
+  }
+  const changeFrom = outcome === 'OVER' ? changeTaker(picks, amounts, -restCents, givesChange) : null;
+  if (outcome === 'OVER' && changeFrom === null) {
+    return { ...base, changeCents: 0, outcome, answer: null };
+  }
+  const changeCents = changeFrom === null ? 0 : -restCents;
+  const legs = legsOf(picks, amounts, changeFrom, changeCents);
+  return { ...base, changeCents, outcome: 'READY', answer: { legs, changeCents } };
+}
+
+function amountsOf<T extends string>(
+  picks: readonly TenderPick<T>[],
+  totalCents: number,
+): Map<T, number> {
+  const typed = picks.filter((pick) => pick.typed !== null);
+  const typedSum = typed.reduce((sum, pick) => sum + (parseAmount(pick.typed!) ?? 0), 0);
+  const automatic = picks.filter((pick) => pick.typed === null);
+  const shares = shareEqually(totalCents - typedSum, automatic.length);
+  const amounts = new Map<T, number>();
+  for (const pick of picks) {
+    amounts.set(
+      pick.tender,
+      pick.typed === null ? shares[automatic.indexOf(pick)]! : parseAmount(pick.typed) ?? 0,
+    );
+  }
+  return amounts;
+}
+
+function outcomeOf<T extends string>(
+  picks: readonly TenderPick<T>[],
+  restCents: number,
+): TenderSplitOutcome {
+  if (picks.length === 0) return 'EMPTY';
+  if (picks.some((pick) => pick.typed !== null && parseAmount(pick.typed) === null)) {
+    return 'INVALID';
+  }
+  if (restCents > 0) return 'SHORT';
+  return restCents < 0 ? 'OVER' : 'READY';
+}
+
+/** The typed change-giving tender that received more than the excess. */
+function changeTaker<T extends string>(
+  picks: readonly TenderPick<T>[],
+  amounts: ReadonlyMap<T, number>,
+  excess: number,
+  givesChange: (tender: T) => boolean,
+): T | null {
+  const taker = picks.find(
+    (pick) => pick.typed !== null && givesChange(pick.tender) && amounts.get(pick.tender)! > excess,
+  );
+  return taker?.tender ?? null;
+}
+
+function legsOf<T extends string>(
+  picks: readonly TenderPick<T>[],
+  amounts: ReadonlyMap<T, number>,
+  changeFrom: T | null,
+  changeCents: number,
+): TenderSplitLeg<T>[] {
+  const carrying = picks
+    .map((pick) => ({
+      pick,
+      cents: amounts.get(pick.tender)! - (pick.tender === changeFrom ? changeCents : 0),
+    }))
+    .filter((entry) => entry.cents > 0);
+  // A bill of zero leaves every tender carrying nothing; the last one tapped
+  // still answers, as "the rest" of nothing, which a server accepts.
+  if (carrying.length === 0) return [{ tender: picks[picks.length - 1]!.tender }];
+  const open = [...carrying].reverse().find((entry) => entry.pick.typed === null);
+  return carrying.map((entry) =>
+    entry === open
+      ? { tender: entry.pick.tender }
+      : { tender: entry.pick.tender, amountCents: entry.cents },
+  );
+}

package/src/tender-split/pt-BR.ts

@@ -0,0 +1,19 @@
+import type { TenderSplitCopy } from './copy';
+
+/** `TenderSplit` in pt-BR — a named pack, never a default (see `./copy`). */
+export const PT_BR_TENDER_SPLIT_COPY: TenderSplitCopy = {
+  launchedLabel: 'Lançado',
+  missingLabel: 'Falta',
+  coveredLabel: 'Fechou',
+  over: (amount) => `Passou ${amount}`,
+  progressLabel: 'Quanto da conta já foi lançado',
+  sharedHint: 'dividido',
+  amountLabel: (tender) => `Valor em ${tender}`,
+  remove: (tender) => `Tirar ${tender}`,
+  changeLabel: 'Troco',
+  pickFirst: 'Escolha a forma',
+  missing: (amount) => `Falta ${amount}`,
+  invalid: 'Valor inválido',
+  confirm: (amount) => `Confirmar ${amount}`,
+  cancel: 'Cancelar',
+};

package/src/tender-split/tender-card.tsx

@@ -0,0 +1,198 @@
+'use client';
+
+import { Box, ButtonBase, IconButton, InputBase, Typography } from '@mui/material';
+import { alpha } from '@mui/material/styles';
+import type { FocusEvent, ReactNode } from 'react';
+
+import { CloseIcon } from '../components/checkout/icons';
+import type { TenderSplitCopy } from './copy';
+
+/**
+ * One tender the host takes in person.
+ *
+ * `label` and `icon` are the host's own words and glyph: which tenders a store
+ * takes and what it calls them is its catalogue, never this package's.
+ * `givesChange` marks the tender that may be typed above the bill, the excess
+ * being change handed back — cash, in every host so far.
+ */
+export interface TenderOption<T extends string> {
+  readonly id: T;
+  readonly label: string;
+  /** The glyph on the card; `null` for a host that draws none. */
+  readonly icon: ReactNode;
+  readonly givesChange: boolean;
+}
+
+const CARD_RADIUS = 1.5;
+
+/** A tender nobody picked yet: one tap picks it. */
+export function TenderChoice<T extends string>({
+  tender,
+  testId,
+  autoFocus,
+  onPick,
+}: {
+  tender: TenderOption<T>;
+  testId: string;
+  /** The card just removed comes back as a choice and keeps the focus. */
+  autoFocus: boolean;
+  onPick: () => void;
+}) {
+  return (
+    <ButtonBase
+      onClick={onPick}
+      autoFocus={autoFocus}
+      data-testid={testId}
+      sx={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'flex-start',
+        justifyContent: 'flex-start',
+        gap: 0.75,
+        p: 1.5,
+        minHeight: 74,
+        textAlign: 'left',
+        borderRadius: CARD_RADIUS,
+        border: 1.5,
+        borderColor: 'divider',
+        color: 'text.primary',
+        transition: 'border-color .12s, background-color .12s',
+        '&:hover': { borderColor: 'primary.main' },
+        '&.Mui-focusVisible': { outline: 2, outlineColor: 'primary.main', outlineOffset: 2 },
+      }}
+    >
+      <TenderHeading tender={tender} />
+    </ButtonBase>
+  );
+}
+
+/**
+ * A picked tender: its amount, typed or shared, and the one control that
+ * lets a typed amount go.
+ */
+export function PickedTender<T extends string>({
+  tender,
+  value,
+  shared,
+  currencySign,
+  copy,
+  testId,
+  autoFocus,
+  onType,
+  onRemove,
+}: {
+  tender: TenderOption<T>;
+  value: string;
+  shared: boolean;
+  currencySign: string;
+  copy: TenderSplitCopy;
+  testId: string;
+  /** The card just picked takes the focus, so its amount can be typed at once. */
+  autoFocus: boolean;
+  onType: (typed: string) => void;
+  onRemove: () => void;
+}) {
+  return (
+    <Box
+      data-testid={testId}
+      sx={(theme) => ({
+        position: 'relative',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 1,
+        p: 1.5,
+        minWidth: 0,
+        borderRadius: CARD_RADIUS,
+        border: 1.5,
+        borderColor: 'primary.main',
+        bgcolor: alpha(theme.palette.primary.main, 0.08),
+      })}
+    >
+      <TenderHeading tender={tender} />
+      <IconButton
+        size="small"
+        aria-label={copy.remove(tender.label)}
+        onClick={onRemove}
+        data-testid={`${testId}-remove`}
+        sx={{ position: 'absolute', top: (t) => t.spacing(0.5), right: (t) => t.spacing(0.5), color: 'text.secondary' }}
+      >
+        <CloseIcon fontSize="small" />
+      </IconButton>
+      <AmountField
+        label={copy.amountLabel(tender.label)}
+        value={value}
+        currencySign={currencySign}
+        autoFocus={autoFocus}
+        testId={`${testId}-amount`}
+        onType={onType}
+      />
+      {/* Under the field rather than beside it, where a narrow card had no room
+          for it and the amount both. */}
+      {shared ? (
+        <Typography variant="caption" color="text.secondary" sx={{ mt: -0.5 }}>
+          {copy.sharedHint}
+        </Typography>
+      ) : null}
+    </Box>
+  );
+}
+
+/** A picked card's amount: the currency sign in front, never squeezed. */
+function AmountField({
+  label,
+  value,
+  currencySign,
+  autoFocus,
+  testId,
+  onType,
+}: {
+  label: string;
+  value: string;
+  currencySign: string;
+  autoFocus: boolean;
+  testId: string;
+  onType: (typed: string) => void;
+}) {
+  return (
+    <InputBase
+      value={value}
+      onChange={(event) => onType(event.target.value)}
+      onFocus={(event: FocusEvent<HTMLInputElement>) => event.target.select()}
+      autoFocus={autoFocus}
+      inputProps={{
+        inputMode: 'decimal',
+        'aria-label': label,
+        'data-testid': testId,
+      }}
+      startAdornment={
+        // Never shrunk: squeezed by the amount beside it, the sign read "R."
+        <Typography variant="caption" color="text.secondary" sx={{ mr: 0.5, flexShrink: 0 }}>
+          {currencySign}
+        </Typography>
+      }
+      sx={{
+        borderBottom: 1.5,
+        borderColor: 'divider',
+        fontWeight: 500,
+        fontVariantNumeric: 'tabular-nums',
+        '&.Mui-focused': { borderColor: 'primary.main' },
+        '& input': { textAlign: 'right', py: 0.375, minWidth: 0 },
+      }}
+    />
+  );
+}
+
+function TenderHeading<T extends string>({ tender }: { tender: TenderOption<T> }) {
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1, pr: 3, minWidth: 0 }}>
+      {tender.icon === null ? null : (
+        <Box component="span" aria-hidden sx={{ display: 'flex', color: 'primary.main' }}>
+          {tender.icon}
+        </Box>
+      )}
+      <Typography component="span" sx={{ fontWeight: 500, overflowWrap: 'anywhere' }}>
+        {tender.label}
+      </Typography>
+    </Box>
+  );
+}

package/src/tender-split/tender-split.tsx

@@ -0,0 +1,302 @@
+'use client';
+
+import { Box, Button, LinearProgress, Stack, Typography } from '@mui/material';
+import { alpha } from '@mui/material/styles';
+import { useMemo, useState } from 'react';
+
+import type { TenderSplitCopy } from './copy';
+import {
+  readTenderSplit,
+  withPicked,
+  withTyped,
+  withoutPicked,
+  type TenderPick,
+  type TenderSplitAnswer,
+  type TenderSplitState,
+} from './math';
+import { PickedTender, TenderChoice, type TenderOption } from './tender-card';
+
+/**
+ * "How was it paid?" for money taken in person — one screen whatever the mix.
+ *
+ * The tenders are cards. Tapping one picks it and it takes the bill; tapping a
+ * second splits the bill between the two, a third in three, the leftover cent
+ * going to the last one tapped. Typing into a card fixes that amount, and the
+ * cards still automatic share what it leaves; only removing the card lets a
+ * typed amount go (the rule, and what is sent, are in `./math`). A bar above
+ * says how much is recorded and how much is missing, and the confirm names the
+ * same figure, so it is never a disabled button with no reason on it.
+ *
+ * The component knows no store and no language: the host passes its tenders
+ * (names, glyphs, which one gives change), the words, and the locale and
+ * currency every amount is formatted in. It renders no dialog chrome either —
+ * a host puts it inside its own dialog, sheet or page.
+ */
+export interface TenderSplitProps<T extends string> {
+  readonly tenders: readonly TenderOption<T>[];
+  /** The bill, in whole cents of `currency`. */
+  readonly totalCents: number;
+  readonly copy: TenderSplitCopy;
+  /** BCP 47 tag every amount is formatted in, e.g. `pt-BR`. */
+  readonly locale: string;
+  /** ISO 4217 code, e.g. `BRL`. */
+  readonly currency: string;
+  readonly onConfirm: (answer: TenderSplitAnswer<T>) => void;
+  /** Omit to render no cancel control. */
+  readonly onCancel?: () => void;
+  /** Prefix of every test id — `<id>-option-<tender>`, `<id>-confirm`, … */
+  readonly dataTestId?: string;
+}
+
+export function TenderSplit<T extends string>({
+  tenders,
+  totalCents,
+  copy,
+  locale,
+  currency,
+  onConfirm,
+  onCancel,
+  dataTestId = 'tender-split',
+}: TenderSplitProps<T>) {
+  const [picks, setPicks] = useState<TenderPick<T>[]>([]);
+  // The tender whose card was just removed: its choice takes the focus back,
+  // so a keyboard never falls to the top of the dialog.
+  const [removed, setRemoved] = useState<T | null>(null);
+  const money = useMemo(() => moneyFormats(locale, currency), [locale, currency]);
+  const changing = useMemo(
+    () => new Set(tenders.filter((tender) => tender.givesChange).map((t) => t.id)),
+    [tenders],
+  );
+  // A pick the host no longer offers (its list refetched mid-question) is not
+  // on screen, so it is not sent either.
+  const offered = picks.filter((pick) => tenders.some((tender) => tender.id === pick.tender));
+  const state = readTenderSplit(offered, totalCents, (tender) => changing.has(tender));
+  const lastPicked = offered[offered.length - 1]?.tender;
+  return (
+    <Stack spacing={2} data-testid={dataTestId}>
+      <Progress state={state} totalCents={totalCents} copy={copy} money={money} testId={dataTestId} />
+      <Box sx={{ display: 'grid', gridTemplateColumns: 'repeat(2, minmax(0, 1fr))', gap: 1.25 }}>
+        {tenders.map((tender) => {
+          const pick = offered.find((candidate) => candidate.tender === tender.id);
+          const shown = money.amount(state.amounts.get(tender.id) ?? 0);
+          return pick === undefined ? (
+            <TenderChoice
+              key={tender.id}
+              tender={tender}
+              testId={`${dataTestId}-option-${tender.id}`}
+              autoFocus={tender.id === removed}
+              onPick={() => setPicks((current) => withPicked(current, tender.id))}
+            />
+          ) : (
+            <PickedTender
+              key={tender.id}
+              tender={tender}
+              value={pick.typed ?? shown}
+              shared={pick.typed === null}
+              currencySign={money.sign}
+              copy={copy}
+              testId={`${dataTestId}-picked-${tender.id}`}
+              autoFocus={tender.id === lastPicked}
+              onType={(typed) => setPicks((current) => withTyped(current, tender.id, typed, shown))}
+              onRemove={() => {
+                setRemoved(tender.id);
+                setPicks((current) => withoutPicked(current, tender.id));
+              }}
+            />
+          );
+        })}
+      </Box>
+      {state.changeCents > 0 ? (
+        <ChangeLine cents={state.changeCents} copy={copy} money={money} testId={dataTestId} />
+      ) : null}
+      <Actions
+        label={confirmText(state, totalCents, copy, money)}
+        onConfirm={state.answer === null ? null : () => onConfirm(state.answer!)}
+        onCancel={onCancel}
+        copy={copy}
+        testId={dataTestId}
+      />
+    </Stack>
+  );
+}
+
+function ChangeLine({
+  cents,
+  copy,
+  money,
+  testId,
+}: {
+  cents: number;
+  copy: TenderSplitCopy;
+  money: MoneyFormats;
+  testId: string;
+}) {
+  return (
+    <Box
+      data-testid={`${testId}-change`}
+      sx={(theme) => ({
+        display: 'flex',
+        justifyContent: 'space-between',
+        px: 1.5,
+        py: 1,
+        borderRadius: 1,
+        bgcolor: alpha(theme.palette.success.main, 0.12),
+        color: 'success.main',
+        fontWeight: 500,
+        fontVariantNumeric: 'tabular-nums',
+      })}
+    >
+      <span>{copy.changeLabel}</span>
+      <span>{money.full(cents)}</span>
+    </Box>
+  );
+}
+
+/** Cancel (when the host handles it) and the confirm that names the figure. */
+function Actions({
+  label,
+  onConfirm,
+  onCancel,
+  copy,
+  testId,
+}: {
+  label: string;
+  onConfirm: (() => void) | null;
+  onCancel: (() => void) | undefined;
+  copy: TenderSplitCopy;
+  testId: string;
+}) {
+  return (
+    <Box sx={{ display: 'flex', justifyContent: onCancel ? 'space-between' : 'flex-end', gap: 1 }}>
+      {onCancel ? (
+        <Button
+          variant="text"
+          color="inherit"
+          onClick={onCancel}
+          data-testid={`${testId}-cancel`}
+          sx={{ textTransform: 'none' }}
+        >
+          {copy.cancel}
+        </Button>
+      ) : null}
+      <Button
+        variant="contained"
+        disabled={onConfirm === null}
+        onClick={onConfirm ?? undefined}
+        data-testid={`${testId}-confirm`}
+        // The confirm reads a sentence with a figure in it — "Falta R$ 2,00" —
+        // which MUI's default capitals would shout.
+        sx={{ textTransform: 'none' }}
+      >
+        {label}
+      </Button>
+    </Box>
+  );
+}
+
+interface MoneyFormats {
+  /** An amount with its currency sign — "R$ 82,00". */
+  full: (cents: number) => string;
+  /** An amount as it sits in a field — "82,00". */
+  amount: (cents: number) => string;
+  /** The currency sign alone — "R$". */
+  sign: string;
+}
+
+function moneyFormats(locale: string, currency: string): MoneyFormats {
+  const full = new Intl.NumberFormat(locale, { style: 'currency', currency });
+  const amount = new Intl.NumberFormat(locale, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+  const sign = full.formatToParts(0).find((part) => part.type === 'currency')?.value ?? currency;
+  return {
+    full: (cents) => full.format(cents / 100),
+    amount: (cents) => amount.format(cents / 100),
+    sign,
+  };
+}
+
+function Progress<T extends string>({
+  state,
+  totalCents,
+  copy,
+  money,
+  testId,
+}: {
+  state: TenderSplitState<T>;
+  totalCents: number;
+  copy: TenderSplitCopy;
+  money: MoneyFormats;
+  testId: string;
+}) {
+  const covered = state.outcome === 'READY';
+  const percent = totalCents > 0 ? Math.min(100, (state.launchedCents / totalCents) * 100) : 0;
+  return (
+    <Stack spacing={0.75}>
+      <LinearProgress
+        variant="determinate"
+        value={percent}
+        color={covered ? 'success' : 'primary'}
+        aria-label={copy.progressLabel}
+        sx={{ height: 8, borderRadius: 1 }}
+      />
+      <Box sx={{ display: 'flex', justifyContent: 'space-between', gap: 1 }}>
+        <Typography variant="caption" color="text.secondary" data-testid={`${testId}-launched`}>
+          {copy.launchedLabel} <b>{money.full(state.launchedCents)}</b>
+        </Typography>
+        <RestLabel state={state} copy={copy} money={money} testId={testId} />
+      </Box>
+    </Stack>
+  );
+}
+
+function RestLabel<T extends string>({
+  state,
+  copy,
+  money,
+  testId,
+}: {
+  state: TenderSplitState<T>;
+  copy: TenderSplitCopy;
+  money: MoneyFormats;
+  testId: string;
+}) {
+  const id = `${testId}-rest`;
+  if (state.outcome === 'READY') {
+    return (
+      <Typography variant="caption" color="success.main" fontWeight={500} data-testid={id}>
+        {copy.coveredLabel}
+      </Typography>
+    );
+  }
+  if (state.restCents < 0) {
+    return (
+      <Typography variant="caption" color="error" data-testid={id}>
+        {copy.over(money.full(-state.restCents))}
+      </Typography>
+    );
+  }
+  return (
+    <Typography variant="caption" color="text.secondary" data-testid={id}>
+      {copy.missingLabel} <b>{money.full(state.restCents)}</b>
+    </Typography>
+  );
+}
+
+function confirmText<T extends string>(
+  state: TenderSplitState<T>,
+  totalCents: number,
+  copy: TenderSplitCopy,
+  money: MoneyFormats,
+): string {
+  switch (state.outcome) {
+    case 'EMPTY':
+      return copy.pickFirst;
+    case 'INVALID':
+      return copy.invalid;
+    case 'SHORT':
+      return copy.missing(money.full(state.restCents));
+    case 'OVER':
+      return copy.over(money.full(-state.restCents));
+    case 'READY':
+      return copy.confirm(money.full(totalCents));
+  }
+}