@12-apps/payments-frontend 3.17.0 → 3.18.1

package/src/activation/screens/copy-context.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { createContext, useContext, type JSX, type ReactNode } from 'react';
+
+import type { ActivationStepCopy } from './copy';
+
+/**
+ * Step 3's words, for the dozen panels that render them.
+ *
+ * A CONTEXT rather than a prop, for the same reason `PaymentsSettingsCopy` is
+ * one: this step is a tree of small pieces — six settled states, the waiting
+ * panel, the link actions, two flows and the form between them — and threading
+ * one object through all of them as props is how a copy port comes to exist,
+ * be required, and go unread. It stays a single REQUIRED field at the mount
+ * (`createActivationStep`), which is the only place a host has to answer.
+ */
+const ActivationCopyContext = createContext<ActivationStepCopy | null>(null);
+
+export function ActivationCopyProvider({
+  copy,
+  children,
+}: {
+  copy: ActivationStepCopy;
+  children: ReactNode;
+}): JSX.Element {
+  return <ActivationCopyContext.Provider value={copy}>{children}</ActivationCopyContext.Provider>;
+}
+
+/**
+ * The words this step renders — THROWS outside a provider rather than falling
+ * back.
+ *
+ * A fallback could only be the origin host's Portuguese, handed silently to the
+ * next adopter's store owner. Failing at the mount is the point: it is the one
+ * moment a host can still be told it forgot.
+ */
+export function useActivationCopy(): ActivationStepCopy {
+  const copy = useContext(ActivationCopyContext);
+  if (!copy) {
+    throw new Error('useActivationCopy must be rendered inside an <ActivationCopyProvider>');
+  }
+  return copy;
+}

package/src/activation/screens/copy.ts

@@ -0,0 +1,150 @@
+import type { ActivationChargeCopy } from '../charge-copy';
+import type { RedirectActivationCopy } from '../copy';
+
+/**
+ * Every sentence step 3 puts in front of a store owner (FUT-764 burn-down).
+ *
+ * Required, with no defaults — this package's doctrine, stated in
+ * `checkout/view-copy.ts` and again in `settings-copy.ts`: a default in the
+ * origin host's language reads as finished to the next host right up until an
+ * owner sees it.
+ *
+ * The split is the one the whole port draws. WHICH outcome the activation
+ * charge reached — refused at creation, refused on payment, unreachable,
+ * expired, outstanding, already proven — is knowledge of the activation
+ * lifecycle and it stays here. The words are the host's.
+ *
+ * ## What is NOT in here
+ *
+ * The provider's own display name: it arrives as `displayName` and is
+ * interpolated by the functions below, because "InfinitePay" is InfinitePay's
+ * name in every language.
+ *
+ * The AMOUNT. Every sentence that names one takes an already-formatted string,
+ * because how a host writes money is a decision it has made elsewhere — and
+ * because the figure is the provider's, not this package's to round.
+ */
+
+/** The step's heading and the two sentences under it, per flow. */
+export interface ActivationIntroCopy {
+  /** The heading both flows carry — "Passo 3 · …". */
+  readonly title: string;
+  /**
+   * The card flow's lead: a test charge on the owner's own card, refunded.
+   *
+   * Takes the formatted amount or `null` — the window before the endpoint has
+   * priced the charge. A package that guessed a cent there would have the
+   * screen promise one figure while the button charged another, which is the
+   * exact lie this step exists to remove.
+   */
+  cardBody(amountLabel: string | null): string;
+  /** The redirect flow's first line: what is about to be charged. */
+  realCharge(amountLabel: string): string;
+  /** Its second: whose money moves, and where it lands. */
+  payingYourself(amountLabel: string): string;
+}
+
+/** The buttons that start a charge, and the one that re-runs a settled test. */
+export interface ActivationActionCopy {
+  /** The card flow's submit — takes the formatted amount, or `null`. */
+  chargeAndActivate(amountLabel: string | null): string;
+  /** The redirect flow's submit, which always names an amount. */
+  payAndActivate(amountLabel: string): string;
+  /** Re-run the activation TEST — not "retry a failed read". */
+  readonly testAgain: string;
+  /** The retry button on the settled-and-refused state. */
+  readonly retry: string;
+  /** "Try again" for an outage, which is a different act from `retry`. */
+  readonly tryAgain: string;
+  /** Clear a refused creation and return the step to its start. */
+  readonly restart: string;
+  /** Mint a replacement for a link whose window elapsed. */
+  readonly generateNewCharge: string;
+  /** Ask the provider right now instead of waiting for the next tick. */
+  readonly checkNow: string;
+  /** The same, worded for someone who has just paid. */
+  readonly alreadyPaidCheckNow: string;
+  /** Where the owner goes next: the order providers are tried in. */
+  readonly setProviderOrder: string;
+  /** And the shop this connection now takes money for. */
+  readonly seePublishedStore: string;
+}
+
+/** The outstanding-payment panel, and the link it is waiting on. */
+export interface ActivationAwaitingCopy {
+  /** The return trip: the owner has paid and we are only confirming. */
+  readonly receivedTitle: string;
+  readonly receivedBody: string;
+  /** A refused attempt on a charge that is still payable. */
+  readonly declinedTitle: string;
+  /** The live link's own panel. */
+  readonly waitingTitle: string;
+  waitingBody(amountLabel: string): string;
+  /** How long ago the provider was last asked, in seconds. */
+  lastChecked(seconds: number): string;
+  readonly openPaymentPage: string;
+  readonly copyLink: string;
+  readonly linkCopied: string;
+  readonly showLink: string;
+  readonly hideLink: string;
+}
+
+/** The settled outcomes — where this screen earns its keep. */
+export interface ActivationOutcomeCopy {
+  /** Passed, with the refund already made. */
+  readonly approvedTitle: string;
+  refundedBody(amountLabel: string): string;
+  /** Passed, refund still in flight. */
+  refundPendingBody(amountLabel: string): string;
+  /** The fallback for a sentence that must name an amount before one is known. */
+  readonly someAmount: string;
+  /**
+   * Refused on PAYMENT. The owner IS connected, so a sentence about the
+   * connection failing would send them to reauthorize something that works.
+   */
+  readonly authenticatedNotActive: string;
+  /** Refused at CREATION — a provider-side switch, which is a step not an error. */
+  refusedTitle(displayName: string): string;
+  refusedBody(displayName: string): string;
+  /** The provider was never reached: it refused nothing, so blame nothing. */
+  readonly unreachableTitle: string;
+  /** The link's window elapsed unpaid. No blame, and the offer of another. */
+  readonly expiredTitle: string;
+  /** The redirect flow's own success, which settles without a refund leg. */
+  readonly settledTitle: string;
+  settledBody(amountLabel: string): string;
+  /** Already proven — the only honest thing the step can render on a reload. */
+  readonly provenTitle: string;
+  readonly provenBody: string;
+  /** The provider's raw refusal, above the verbatim block. */
+  readonly providerSaid: string;
+  /** An earlier step is unconfirmed, so no new charge is offered yet. */
+  readonly blockedTitle: string;
+  readonly blockedBody: string;
+}
+
+/** The CPF field the card flow asks for beside the card. */
+export interface ActivationTaxIdCopy {
+  readonly label: string;
+  readonly hint: string;
+  readonly placeholder: string;
+}
+
+/**
+ * Everything step 3 says.
+ *
+ * `charge` and `redirect` are the two protocol packs the hooks already
+ * required — carried here rather than beside them so a host answers the step
+ * in ONE object, which is what stops half of it going unread.
+ */
+export interface ActivationStepCopy {
+  readonly intro: ActivationIntroCopy;
+  readonly actions: ActivationActionCopy;
+  readonly awaiting: ActivationAwaitingCopy;
+  readonly outcome: ActivationOutcomeCopy;
+  readonly taxId: ActivationTaxIdCopy;
+  /** The card protocol's three sentences, plus the card form's own words. */
+  readonly charge: ActivationChargeCopy;
+  /** The redirect protocol's four. */
+  readonly redirect: RedirectActivationCopy;
+}

package/src/activation/screens/index.ts

@@ -0,0 +1,10 @@
+export { createActivationStep, type ActivationStepConfig, type ActivationStepProps } from './activation-step';
+export { type CardSurface } from './card-verification';
+export {
+  type ActivationActionCopy,
+  type ActivationAwaitingCopy,
+  type ActivationIntroCopy,
+  type ActivationOutcomeCopy,
+  type ActivationStepCopy,
+  type ActivationTaxIdCopy,
+} from './copy';

package/src/activation/screens/notice.tsx

@@ -0,0 +1,111 @@
+'use client';
+
+import { Box, Stack, Typography } from '@mui/material';
+import type { JSX, ReactNode } from 'react';
+
+import { T } from '../../components/panel-tokens';
+
+/**
+ * The tinted panel every settled state is made of.
+ *
+ * Local to this step rather than a design-system Alert, and that is the whole
+ * point of the move: the origin host rendered these through its own Alert and
+ * then had to correct it twice in place — a 12px radius against the 4px cards
+ * it sat under, and a hover lift on a standing panel that moved under the
+ * cursor as you reached for the buttons inside it. Both corrections were
+ * written as `sx` overrides in a page file, which is where a design decision
+ * goes to be invisible. Here it is one shape, matching the cards it sits with,
+ * for every host.
+ */
+type NoticeTone = 'ok' | 'warn' | 'bad' | 'info';
+
+const TONES = {
+  ok: { bg: T.okSoft, line: T.okLine, ink: T.okInk },
+  warn: { bg: T.warnSoft, line: T.warnLine, ink: T.warnInk },
+  bad: { bg: T.badSoft, line: T.badLine, ink: T.badInk },
+  info: { bg: T.infoSoft, line: T.infoLine, ink: T.infoInk },
+} as const;
+
+export function Notice({
+  tone,
+  title,
+  description,
+  children,
+  dataTestId,
+}: {
+  tone: NoticeTone;
+  title: string;
+  /** The body, when there is one — a state may be its title alone. */
+  description?: string;
+  /** What this outcome OFFERS, inside the panel rather than under it. */
+  children?: ReactNode;
+  dataTestId?: string;
+}): JSX.Element {
+  const tint = TONES[tone];
+  return (
+    <Box
+      data-testid={dataTestId}
+      sx={{
+        background: tint.bg,
+        border: `1px solid ${tint.line}`,
+        borderRadius: '8px',
+        p: '12px 14px',
+      }}
+    >
+      <Typography sx={{ fontSize: '13.5px', fontWeight: 650, color: tint.ink }}>{title}</Typography>
+      {description ? (
+        <Typography sx={{ fontSize: '12.5px', color: T.ink2, mt: '4px', lineHeight: 1.5 }}>
+          {description}
+        </Typography>
+      ) : null}
+      {children ? <Box sx={{ mt: '12px' }}>{children}</Box> : null}
+    </Box>
+  );
+}
+
+/**
+ * The provider's own refusal, verbatim — what support asks for on the phone.
+ *
+ * Selectable and monospaced on purpose: it is a string to be copied into a
+ * ticket, not prose. Rendered UNDER the notice rather than inside it, because
+ * it is evidence for the sentence above rather than part of it.
+ */
+export function ProviderMessage({ message, label }: { message: string; label: string }): JSX.Element {
+  return (
+    <Box
+      data-testid="verify-charge-provider-message"
+      sx={{
+        fontFamily: T.mono,
+        fontSize: '12px',
+        whiteSpace: 'pre-wrap',
+        wordBreak: 'break-word',
+        userSelect: 'text',
+        p: '10px 12px',
+        borderRadius: '8px',
+        background: T.bg2,
+        border: `1px solid ${T.line2}`,
+      }}
+    >
+      <Typography sx={{ fontSize: '11px', color: T.ink3, mb: '4px' }}>{label}</Typography>
+      {message}
+    </Box>
+  );
+}
+
+/** The panel that frames a whole flow — the same card the steps above use. */
+export function StepPanel({
+  children,
+  dataTestId,
+}: {
+  children: ReactNode;
+  dataTestId: string;
+}): JSX.Element {
+  return (
+    <Box
+      data-testid={dataTestId}
+      sx={{ border: `1px solid ${T.line}`, borderRadius: '11px', p: '16px', background: T.bg }}
+    >
+      <Stack spacing={2}>{children}</Stack>
+    </Box>
+  );
+}

package/src/activation/screens/redirect-verification.tsx

@@ -0,0 +1,249 @@
+'use client';
+
+import { Button, Stack, Typography } from '@mui/material';
+import { useCallback, type JSX } from 'react';
+
+import { BTN_PRIMARY_SX, T } from '../../components/panel-tokens';
+import { useRedirectActivation } from '../use-redirect-activation';
+import type { RedirectActivationState } from '../redirect-state';
+
+import { AwaitingPayment } from './awaiting-payment';
+import { useActivationCopy } from './copy-context';
+import { Notice, StepPanel } from './notice';
+import { useVerificationAmount } from './use-verification-amount';
+import { ExpiredState, FailedState, SetupIncompleteState, UnreachableState } from './states';
+
+/**
+ * Step 3 for a provider whose buyer pays on ITS page.
+ *
+ * Same proof as the card form, different protocol: a REAL link through this
+ * store's own connection, paid by the owner on the provider's site, then
+ * confirmed by asking the provider. Telling an owner to "make a real low-value
+ * order and check" instead was the dead-end instruction this screen exists to
+ * abolish — if the check can be run for them, it must be.
+ *
+ * One button, one outcome: pressing it mints the charge AND lands them on the
+ * payment page (`useRedirectActivation` claims the tab inside the click, so no
+ * popup blocker can eat it). Generating a charge and then asking them to find a
+ * second button was the same extra step in a smaller costume.
+ */
+
+/**
+ * The pay button, or the reason it is not there yet.
+ *
+ * `blocked` withholds the button ONLY. Everything else this panel can render —
+ * an outstanding charge, a return trip being confirmed, a settled result — goes
+ * on rendering regardless, because those states describe money that has already
+ * moved. Hiding them behind a setup step is how a payment stops being
+ * confirmable, which is a far worse failure than an early click.
+ */
+function StartCharge({
+  amountLabel,
+  blocked,
+  creating,
+  onStart,
+}: {
+  amountLabel: string;
+  blocked: boolean;
+  creating: boolean;
+  onStart: () => void;
+}): JSX.Element {
+  const { outcome, actions } = useActivationCopy();
+  if (blocked) {
+    return (
+      <Notice
+        tone="info"
+        title={outcome.blockedTitle}
+        description={outcome.blockedBody}
+        dataTestId="verify-charge-blocked"
+      />
+    );
+  }
+  return (
+    <Button
+      sx={{ ...BTN_PRIMARY_SX, width: '100%' }}
+      disabled={creating}
+      onClick={onStart}
+      data-testid="verify-charge-start-redirect"
+    >
+      {actions.payAndActivate(amountLabel)}
+    </Button>
+  );
+}
+
+/**
+ * What is about to happen, said BEFORE it happens.
+ *
+ * FUT-463 asks that whatever is taken be reversed or explained beforehand, and
+ * this is the explanation: whose money moves, and where to. Both sentences are
+ * the host's, because the first attempt at them was true and still misread —
+ * an owner asked what it meant. Nothing is lost: the charge goes through the
+ * store's OWN connection, so it lands in the account that receives its sales,
+ * and there is no refund because it never left.
+ */
+function Intro({ amountLabel }: { amountLabel: string }): JSX.Element {
+  const { intro } = useActivationCopy();
+  return (
+    <Stack spacing={1}>
+      <Typography sx={{ fontSize: '14px', fontWeight: 650, color: T.ink }} component="h2">
+        {intro.title}
+      </Typography>
+      <Typography sx={{ fontSize: '12.5px', color: T.ink3, lineHeight: 1.5 }}>
+        {intro.realCharge(amountLabel)}
+      </Typography>
+      <Typography sx={{ fontSize: '12.5px', color: T.ink3, lineHeight: 1.5 }}>
+        {intro.payingYourself(amountLabel)}
+      </Typography>
+    </Stack>
+  );
+}
+
+/**
+ * Everything this step can be, once it has done something.
+ *
+ * Six states, each with its own sentence and its own next action. Three of the
+ * six are ways the link never got minted, and they are three screens rather
+ * than one because they are three different instructions: fix a setting
+ * (refused), wait it out (unreachable), read the provider's own words (anything
+ * else). One panel served all three and could only ever give the first one's
+ * advice.
+ */
+function Outcome({
+  state,
+  displayName,
+  amountLabel,
+  lastCheckedAt,
+  onCheckNow,
+  onReset,
+}: {
+  state: RedirectActivationState;
+  displayName: string;
+  amountLabel: string;
+  lastCheckedAt: number;
+  onCheckNow: () => Promise<void>;
+  onReset: () => void;
+}): JSX.Element | null {
+  const { outcome } = useActivationCopy();
+  if (state.kind === 'passed') {
+    return (
+      <Notice
+        tone="ok"
+        title={outcome.settledTitle}
+        description={outcome.settledBody(amountLabel)}
+      />
+    );
+  }
+  if (state.kind === 'expired') {
+    return <ExpiredState reason={state.reason} onRegenerate={onReset} />;
+  }
+  if (state.kind === 'awaiting') {
+    return (
+      <AwaitingPayment
+        checkoutUrl={state.checkoutUrl}
+        amountLabel={amountLabel}
+        declined={state.declined}
+        lastCheckedAt={lastCheckedAt}
+        onCheckNow={onCheckNow}
+      />
+    );
+  }
+  if (state.kind !== 'failed') return null;
+  if (!state.atCreation) {
+    return (
+      <FailedState reason={state.reason} providerMessage={state.providerMessage} onRetry={onReset} />
+    );
+  }
+  if (state.transport) {
+    return (
+      <UnreachableState
+        reason={state.reason}
+        providerMessage={state.providerMessage}
+        onRetry={onReset}
+      />
+    );
+  }
+  return (
+    <SetupIncompleteState
+      displayName={displayName}
+      reason={state.reason}
+      providerMessage={state.providerMessage}
+      onDismiss={onReset}
+    />
+  );
+}
+
+export function RedirectVerification({
+  verifyChargeUrl,
+  displayName,
+  blocked,
+  hidden,
+  storageKey,
+  formatAmount,
+  onVerified,
+  onSetupIncomplete,
+}: {
+  verifyChargeUrl: string;
+  /** The provider's human name, for the sentences that must say who refused. */
+  displayName: string;
+  blocked: boolean;
+  /** The walkthrough is on an earlier step — see `renderVerification`'s `hidden`. */
+  hidden: boolean;
+  storageKey?: string;
+  formatAmount: (cents: number) => string;
+  onVerified: () => void;
+  onSetupIncomplete: () => void;
+}): JSX.Element | null {
+  const copy = useActivationCopy();
+  // Still memoized: the hook reads its callbacks through a ref inside the
+  // effects, but `onCreateFailed` remains a dependency of `start`, so a fresh
+  // identity every render would rebuild it on every unrelated keystroke.
+  const onCreateFailed = useCallback(() => onSetupIncomplete(), [onSetupIncomplete]);
+  const { state, lastCheckedAt, start, checkNow, reset } = useRedirectActivation({
+    verifyChargeUrl,
+    onVerified,
+    onCreateFailed,
+    copy: copy.redirect,
+    storageKey,
+  });
+  // Named from the server, because it is not always a cent — see
+  // `useVerificationAmount`. A button promising one figure while charging
+  // another is the kind of lie this whole flow exists to remove, and an
+  // unpriced charge says so rather than guessing.
+  const cents = useVerificationAmount(verifyChargeUrl);
+  const amountLabel = cents === null ? copy.outcome.someAmount : formatAmount(cents);
+
+  // Off the current step and with nothing outstanding: the walkthrough is
+  // showing something earlier and this panel has nothing to add.
+  //
+  // NOT unmounted whenever `hidden` is true. The provider refusing to mint a
+  // link is exactly the evidence that withdraws the owner's step-2
+  // confirmation — so the guide goes back a step in the same render that
+  // produced the explanation, and unmounting took the explanation with it. The
+  // owner landed back on a step they thought was finished with nothing on
+  // screen saying why.
+  if (hidden && (state.kind === 'idle' || state.kind === 'creating')) return null;
+
+  return (
+    <StepPanel dataTestId="verify-charge-redirect">
+      {hidden ? null : <Intro amountLabel={amountLabel} />}
+
+      <Outcome
+        state={state}
+        displayName={displayName}
+        amountLabel={amountLabel}
+        lastCheckedAt={lastCheckedAt}
+        onCheckNow={checkNow}
+        onReset={reset}
+      />
+
+      {state.kind === 'idle' || state.kind === 'creating' ? (
+        <StartCharge
+          amountLabel={amountLabel}
+          blocked={blocked}
+          creating={state.kind === 'creating'}
+          onStart={() => void start()}
+        />
+      ) : null}
+    </StepPanel>
+  );
+}