@12-apps/payments-frontend 2.0.0 → 3.0.0

package/src/components/ProviderSetupGuide.tsx

@@ -6,11 +6,14 @@ import {
   Button,
   IconButton,
   Link,
-  Paper,
   Stack,
   Step,
+  StepConnector,
+  stepConnectorClasses,
   StepLabel,
   Stepper,
+  styled,
+  type StepIconProps,
   TextField,
   Typography,
 } from '@mui/material';
@@ -18,6 +21,15 @@ import { useState, type ReactNode } from 'react';
 
 import type { ProviderSetupGuide as Guide, SetupSection, SetupStep } from '@12-apps/payments-backend';
 
+import {
+  BAR_MSG_SX,
+  BAR_SX,
+  BTN_PRIMARY_SX,
+  BTN_SECONDARY_SX,
+  PANEL_SX,
+  T,
+} from './panel-tokens';
+
 import { richText } from './rich-text';
 
 /**
@@ -122,6 +134,39 @@ const BUTTON_SX = { textTransform: 'none' } as const;
 
 type StepActions = ProviderSetupGuideProps['actions'];
 
+/** A step's sentence, with the provider's own reference inline after it. */
+function StepText({ text, link }: { text?: string; link?: SetupStep['link'] }) {
+  if (!text) return null;
+  return (
+    <Typography sx={{ fontSize: '13px', color: T.ink2, lineHeight: 1.5 }}>
+      {richText(text)}{' '}
+      {link ? (
+        <Link href={link.url} target="_blank" rel="noreferrer">
+          {link.label}
+        </Link>
+      ) : null}
+    </Typography>
+  );
+}
+
+/**
+ * The panel's action bar: what this step is asking, and the button that answers.
+ *
+ * The sentence is not decoration. This is the one step no API can report, so
+ * the owner is being asked to vouch for work done somewhere else — and a bare
+ * button gives them nothing to weigh that against.
+ */
+function ConfirmBar({ action }: { action: { label: string; run: () => void } }) {
+  return (
+    <Box sx={BAR_SX} data-testid="payments-setup-confirm-bar">
+      <Typography sx={BAR_MSG_SX}>Confirme quando terminar do lado do provedor.</Typography>
+      <Button variant="contained" disableElevation sx={BTN_PRIMARY_SX} onClick={() => action.run()}>
+        {action.label}
+      </Button>
+    </Box>
+  );
+}
+
 interface StepRowProps {
   step: SetupStep;
   actions: StepActions;
@@ -153,37 +198,21 @@ function WarningRow({ text }: { text: string }) {
 function StepRow({ step, actions }: StepRowProps) {
   const action = step.action ? actions?.[step.action] : undefined;
   if (step.tone === 'warning') return <WarningRow text={step.text ?? ''} />;
+  // An action-only step IS the panel's action bar — see `SectionCard`.
+  if (action && !step.text) return <ConfirmBar action={action} />;
+  // A bordered row with the work on the left and the way to do it on the
+  // right, so a step reads as a thing to tick off rather than as a paragraph.
+  // The instructions on this screen are a CHECKLIST — each one is a piece of
+  // work the owner does somewhere else and comes back from.
   return (
-    <Stack spacing={1}>
-      {step.text ? (
-        <Typography variant="body2">
-          {richText(step.text)}{' '}
-          {step.link ? (
-            <Link href={step.link.url} target="_blank" rel="noreferrer">
-              {step.link.label}
-            </Link>
-          ) : null}
-        </Typography>
-      ) : null}
-      {step.button ? (
-        <Box>
-          <Button
-            variant="outlined"
-            size="small"
-            href={step.button.url}
-            target="_blank"
-            rel="noreferrer"
-            sx={BUTTON_SX}
-            // The mark is the promise: this leaves the store and opens the
-            // provider's site. A button that reads the same as the in-page ones
-            // and then navigates away is a small betrayal, and here it lands on
-            // a screen that can CHANGE the tag.
-            endIcon={<Box component="span" aria-hidden sx={{ fontSize: '0.9em' }}>↗</Box>}
-          >
-            {step.button.label}
-          </Button>
-        </Box>
-      ) : null}
+    <Stack
+      direction="row"
+      gap="12px"
+      alignItems="flex-start"
+      sx={{ border: `1px solid ${T.line}`, borderRadius: '9px', px: '14px', py: '12px' }}
+    >
+      <Stack spacing={1} sx={{ flex: 1, minWidth: 0 }}>
+        <StepText text={step.text} link={step.link} />
       {action ? (
         <Box>
           <Button variant="contained" size="small" sx={BUTTON_SX} onClick={() => void action.run()}>
@@ -191,17 +220,88 @@ function StepRow({ step, actions }: StepRowProps) {
           </Button>
         </Box>
       ) : null}
-      {step.copy ? (
-        <CopyField
-          label={step.copy.label}
-          text={step.copy.text}
-          collapsible={step.copy.collapsible}
-        />
+        {step.copy ? (
+          <CopyField
+            label={step.copy.label}
+            text={step.copy.text}
+            collapsible={step.copy.collapsible}
+          />
+        ) : null}
+      </Stack>
+      {step.button ? (
+        <Button
+          size="small"
+          href={step.button.url}
+          target="_blank"
+          rel="noreferrer"
+          sx={{ ...BTN_SECONDARY_SX, px: '12px', py: '7px', fontSize: '12px', flexShrink: 0 }}
+          // The mark is the promise: this leaves the store and opens the
+          // provider's site. A button that reads the same as the in-page ones
+          // and then navigates away is a small betrayal, and here it lands on
+          // a screen that can CHANGE where the money goes.
+          endIcon={
+            <Box component="span" aria-hidden sx={{ fontSize: '0.9em' }}>
+              ↗
+            </Box>
+          }
+        >
+          {step.button.label}
+        </Button>
       ) : null}
     </Stack>
   );
 }
 
+/**
+ * The numbered dot: 24px, filled once the store is ON or PAST the step.
+ *
+ * MUI's own icon is a 24px circle with the number inside and the same fill for
+ * active and completed, which is nearly the prototype — the differences are the
+ * exact greys and the ✓ on a finished step, and on a screen whose whole job is
+ * "where am I" those are the two things that carry the answer.
+ */
+function StageIcon({ active, completed, icon }: StepIconProps) {
+  const filled = active || completed;
+  return (
+    <Box
+      sx={{
+        width: 24,
+        height: 24,
+        borderRadius: '50%',
+        background: filled ? T.brand : '#d9dbe1',
+        color: '#fff',
+        fontSize: '12px',
+        fontWeight: 700,
+        display: 'grid',
+        placeItems: 'center',
+      }}
+    >
+      {completed ? '✓' : icon}
+    </Box>
+  );
+}
+
+/** A 2px rule that turns brand-coloured behind the steps already passed. */
+const StageConnector = styled(StepConnector)({
+  top: 11,
+  [`& .${stepConnectorClasses.line}`]: { borderTopWidth: 2, borderColor: T.line },
+  [`&.${stepConnectorClasses.active} .${stepConnectorClasses.line}`]: { borderColor: T.brandLine },
+  [`&.${stepConnectorClasses.completed} .${stepConnectorClasses.line}`]: {
+    borderColor: T.brandLine,
+  },
+});
+
+const STAGE_LABEL_SX = {
+  '& .MuiStepLabel-label': {
+    fontSize: '12px',
+    color: T.ink3,
+    lineHeight: 1.25,
+    mt: '7px !important',
+    '&.Mui-active': { color: T.ink, fontWeight: 650 },
+    '&.Mui-completed': { color: T.ink3, fontWeight: 400 },
+  },
+} as const;
+
 export function ProviderSetupGuide({
   guide,
   activeStage = 0,
@@ -210,11 +310,18 @@ export function ProviderSetupGuide({
   sectionFooter,
 }: ProviderSetupGuideProps) {
   return (
-    <Stack spacing={3} data-testid="payments-setup-guide">
-      <Stepper activeStep={activeStage} alternativeLabel>
-        {guide.stages.map((stage) => (
-          <Step key={stage.id}>
-            <StepLabel>{stage.label}</StepLabel>
+    <Stack spacing={0} data-testid="payments-setup-guide">
+      <Stepper
+        activeStep={activeStage}
+        alternativeLabel
+        connector={<StageConnector />}
+        sx={{ px: '20px', pt: '6px', pb: '18px' }}
+      >
+        {guide.stages.map((stage, index) => (
+          <Step key={stage.id} completed={index < activeStage}>
+            <StepLabel slots={{ stepIcon: StageIcon }} sx={STAGE_LABEL_SX}>
+              {stage.label}
+            </StepLabel>
           </Step>
         ))}
       </Stepper>
@@ -235,29 +342,42 @@ function SectionCard({
   actions: StepActions;
   footer?: ReactNode;
 }) {
+  // The step whose completion only the OWNER can report is not a row among the
+  // instructions — it is what this panel is FOR. It moves to the action bar, so
+  // the control the owner is working toward is the last thing in the block and
+  // stays on screen while they read the steps above it.
+  const asks = section.steps.filter((step) => step.action !== undefined);
+  const reads = section.steps.filter((step) => step.action === undefined);
+
   return (
-    <Paper
-      variant="outlined"
-      sx={{ p: 2 }}
+    <Box
+      sx={PANEL_SX}
       // Which section is showing is now a FACT about the store's progress, not
       // a constant, so it needs to be assertable by id rather than by matching
       // the prose inside it.
       data-testid={`payments-setup-section-${section.id}`}
     >
-      <Stack spacing={2}>
-        <Typography variant="subtitle1" fontWeight="bold">
+      <Box sx={{ px: '18px', pt: '15px' }}>
+        <Typography sx={{ fontSize: '14.5px', fontWeight: 700, color: T.ink }}>
           {section.title}
         </Typography>
         {section.intro ? (
-          <Typography variant="body2" color="text.secondary">
+          <Typography sx={{ fontSize: '12.5px', color: T.ink3, mt: '5px', lineHeight: 1.5 }}>
             {richText(section.intro)}
           </Typography>
         ) : null}
-        {section.steps.map((step, index) => (
-          <StepRow key={index} step={step} actions={actions} />
-        ))}
-        {footer}
-      </Stack>
-    </Paper>
+      </Box>
+      <Box sx={{ px: '18px', pt: '14px', pb: '18px' }}>
+        <Stack spacing={1.5}>
+          {reads.map((step, index) => (
+            <StepRow key={index} step={step} actions={actions} />
+          ))}
+          {footer}
+        </Stack>
+      </Box>
+      {asks.map((step, index) => (
+        <StepRow key={`ask-${index}`} step={step} actions={actions} />
+      ))}
+    </Box>
   );
 }

package/src/components/ProviderStatusBar.tsx

@@ -1,10 +1,11 @@
 'use client';
 
-import { Box, Chip, FormControlLabel, Stack, Switch, Tooltip, Typography } from '@mui/material';
+import { Box, Stack, Switch, Tooltip, Typography } from '@mui/material';
 
 import type { MaskedProviderConfig, ProviderDescriptor } from '@12-apps/payments-backend';
 
 import { isConnected } from './connection-state';
+import { T } from './panel-tokens';
 
 /**
  * The provider's headline: what state it is in, and the switch that decides
@@ -124,6 +125,36 @@ function toggleGate(
   };
 }
 
+/**
+ * The three sentences the header can be saying, chosen once.
+ *
+ * Proven-but-off is its OWN state. "Não está recebendo" is true of a store that
+ * never finished setup AND of one that finished and paused, and those are
+ * opposite situations: the first is a step outstanding, the second a decision
+ * the owner made and can undo in one click.
+ */
+function headline(io: { enabled: boolean; paused: boolean; lockedOff: boolean; hint: string }) {
+  if (io.enabled) {
+    return {
+      state: 'Recebendo vendas',
+      sub: 'Sua loja está recebendo por este provedor.',
+      tone: T.ok,
+    };
+  }
+  if (io.paused) {
+    return {
+      state: 'Pausado',
+      sub: 'Conexão pronta e pausada por você — nenhum pedido novo é cobrado aqui.',
+      tone: T.warn,
+    };
+  }
+  return {
+    state: 'Ainda não está recebendo',
+    sub: io.lockedOff ? io.hint : 'Tudo pronto — ligue a chave para começar a receber.',
+    tone: T.ink3,
+  };
+}
+
 /**
  * Status chip + the "recebendo vendas" switch, hoisted OUT of the credential
  * form.
@@ -142,6 +173,52 @@ function toggleGate(
  * you hover it. The reason is printed underneath instead of hidden in a
  * tooltip, since the owner who most needs it is the one who cannot click.
  */
+/**
+ * The provider's name and its status chip, side by side.
+ *
+ * The name is a REAL heading, not a div sized to look like one: it is what this
+ * screen is about, and it is how a screen reader — and the harness — identifies
+ * the page it landed on. The restyle set the size by hand and took the element
+ * with it, which no unit test could see and the harness caught at once.
+ */
+function ProviderName({
+  displayName,
+  label,
+  proven,
+}: {
+  displayName: string;
+  label: string;
+  proven: boolean;
+}) {
+  return (
+    <Stack direction="row" alignItems="center" gap="9px">
+      <Typography
+        component="h2"
+        sx={{ m: 0, fontSize: '19px', fontWeight: 700, letterSpacing: '-.01em', color: T.ink }}
+      >
+        {displayName}
+      </Typography>
+      <Box
+        component="span"
+        data-testid="payments-status"
+        sx={{
+          fontSize: '10px',
+          fontWeight: 800,
+          letterSpacing: '.06em',
+          textTransform: 'uppercase',
+          borderRadius: '5px',
+          px: '7px',
+          py: '3px',
+          background: proven ? T.okSoft : '#f0f1f4',
+          color: proven ? T.ok : T.ink3,
+        }}
+      >
+        {label}
+      </Box>
+    </Stack>
+  );
+}
+
 export function ProviderStatusBar({
   descriptor,
   config,
@@ -157,37 +234,40 @@ export function ProviderStatusBar({
   const { lockedOff, hint } = toggleGate(descriptor, config, enabled);
   const badge = statusBadge(config, descriptor);
 
+  const proven = Boolean(config?.chargeVerifiedAt);
+  const paused = proven && !enabled;
+  const { state, sub, tone } = headline({ enabled, paused, lockedOff, hint });
+
   return (
-    <Stack spacing={0.5}>
-      <Stack direction="row" spacing={1} alignItems="center">
-        <Typography variant="h6">{descriptor.displayName}</Typography>
-        <Chip size="small" data-testid="payments-status" label={badge.label} color={badge.color} />
-        {/* The switch belongs at the far edge: it is the one control here that
-            changes what buyers experience, and crowding it against the status
-            chip made the two read as one compound widget. */}
-        <Box sx={{ flexGrow: 1 }} />
+    <Stack direction="row" alignItems="flex-start" gap="14px" flexWrap="wrap">
+      <Box>
+        <ProviderName displayName={descriptor.displayName} label={badge.label} proven={proven} />
+        <Typography
+          sx={{ fontSize: '12.5px', color: T.ink3, mt: '5px', maxWidth: '52ch', lineHeight: 1.5 }}
+          data-testid="payments-enable-hint"
+        >
+          {sub}
+        </Typography>
+      </Box>
+      {/* The switch belongs at the far edge: it is the one control here that
+          changes what buyers experience, and crowding it against the status
+          chip made the two read as one compound widget. */}
+      <Stack direction="row" alignItems="center" gap="10px" sx={{ ml: 'auto' }}>
         <Tooltip title={hint}>
           {/* A disabled control fires no events, so the tooltip needs a live wrapper. */}
           <span>
-            <FormControlLabel
-              control={
-                <Switch
-                  data-testid="payments-enabled-toggle"
-                  checked={enabled}
-                  disabled={busy || lockedOff}
-                  onChange={(_, next) => onToggle(next)}
-                />
-              }
-              label={enabled ? 'Recebendo vendas' : 'Não está recebendo'}
+            <Switch
+              data-testid="payments-enabled-toggle"
+              checked={enabled}
+              disabled={busy || lockedOff}
+              onChange={(_, next) => onToggle(next)}
             />
           </span>
         </Tooltip>
-      </Stack>
-      {lockedOff ? (
-        <Typography variant="caption" color="text.secondary" data-testid="payments-enable-hint">
-          {hint}
+        <Typography sx={{ fontSize: '12.5px', fontWeight: tone === T.ink3 ? 400 : 600, color: tone }}>
+          {state}
         </Typography>
-      ) : null}
+      </Stack>
     </Stack>
   );
 }

package/src/components/checkout/hosted-return.ts

@@ -31,19 +31,6 @@ import type { CheckoutOrder } from "./types";
  */
 export const HOSTED_ORDER_STORAGE_KEY = "payments.checkout.hostedOrder";
 
-/**
- * The key before the rename, READ ONLY.
- *
- * A buyer who left for the provider's page on the old bundle comes back to the
- * new one with their order parked under the old name. Without this they land on
- * the plain return screen — the order still settles, because the webhook does
- * that and never depended on any of this, but the confirmation they were
- * promised is missing for a reason they could not possibly understand.
- *
- * Delete once no session can still be mid-redirect across that deploy.
- */
-const LEGACY_KEY = "futurepay.checkout.hostedOrder";
-
 /**
  * What a hosted provider appends to the return URL. InfinitePay sends the
  * first three; Stripe's redirect-based 3-D Secure appends `payment_intent`
@@ -87,25 +74,21 @@ export function rememberHostedOrder(order: CheckoutOrder): void {
  * resumed view belongs to exactly one return.
  */
 /**
- * The raw parked payload under either key, cleared as it is read.
+ * The raw parked payload, cleared as it is read.
  *
  * Split out from {@link takeHostedOrder} so the storage handling and the
- * parsing stay separately readable — reading two keys and clearing both put the
- * combined function over the complexity gate, and the two halves fail for
- * unrelated reasons anyway (storage disabled vs. a value that is not an order).
+ * parsing stay separately readable — the two halves fail for unrelated reasons
+ * anyway (storage disabled vs. a value that is not an order).
  *
- * BOTH keys are cleared whichever one answered: this is read-and-clear, and a
- * legacy entry left behind would let a later return trip resume an order that
- * was already consumed.
+ * (This once also read a pre-rename legacy key, kept only for sessions that
+ * were mid-redirect across the deploy that renamed the storage key. A hosted
+ * round trip lasts minutes, so that window is long closed and the shim is
+ * gone.)
  */
 function takeParkedPayload(): string | null {
   try {
-    const raw =
-      window.sessionStorage?.getItem(HOSTED_ORDER_STORAGE_KEY) ??
-      window.sessionStorage?.getItem(LEGACY_KEY) ??
-      null;
+    const raw = window.sessionStorage?.getItem(HOSTED_ORDER_STORAGE_KEY) ?? null;
     window.sessionStorage?.removeItem(HOSTED_ORDER_STORAGE_KEY);
-    window.sessionStorage?.removeItem(LEGACY_KEY);
     return raw;
   } catch {
     // Storage disabled or unavailable — the same "no parked order" as an empty

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*$/, '')}`;
 }