@12-apps/payments-frontend 2.0.0 → 2.1.0

package/src/components/EnvironmentTabs.tsx

@@ -1,9 +1,11 @@
 'use client';
 
-import { Alert, Tab, Tabs } from '@mui/material';
+import { Alert, Box, Tab, Tabs, Typography } from '@mui/material';
 
 import type { PaymentEnvironment } from '@12-apps/payments-backend';
 
+import { T } from './panel-tokens';
+
 /** One environment's human name — the tabs and the probe result share it. */
 export const ENVIRONMENT_LABELS: Record<PaymentEnvironment, string> = {
   SANDBOX: 'Sandbox',
@@ -14,7 +16,22 @@ export const ENVIRONMENT_LABELS: Record<PaymentEnvironment, string> = {
  * Sentence case, because these are place names rather than shouted commands —
  * MUI upper-cases tab labels by default, which turns "Produção" into signage.
  */
-const TAB_SX = { textTransform: 'none' } as const;
+const TAB_SX = {
+  textTransform: 'none',
+  minHeight: 0,
+  minWidth: 0,
+  borderRadius: '6px',
+  px: '14px',
+  py: '6px',
+  fontSize: '12.5px',
+  fontWeight: 600,
+  color: T.ink3,
+  '&.Mui-selected': {
+    background: T.bg,
+    color: T.ink,
+    boxShadow: '0 1px 3px rgba(0,0,0,.09)',
+  },
+} as const;
 
 /**
  * The two environments as tabs, not a select: there are exactly two, and which
@@ -30,26 +47,45 @@ export function EnvironmentSelector({
   environment: PaymentEnvironment;
   onChange: (next: PaymentEnvironment) => void;
 }) {
+  // A segmented control, not underlined tabs. Two options that CHANGE WHAT
+  // EVERY FIELD BELOW MEANS should look like a switch being thrown, and the
+  // label above says which switch — "Ambiente" alone reads as a page section.
   return (
-    <Tabs
-      value={environment}
-      onChange={(_, next: PaymentEnvironment) => onChange(next)}
-      aria-label="Ambiente"
-      data-testid="payments-environment-tabs"
-    >
-      <Tab
-        label="Sandbox"
-        value="SANDBOX"
-        data-testid="payments-environment-SANDBOX"
-        sx={TAB_SX}
-      />
-      <Tab
-        label="Produção"
-        value="PRODUCTION"
-        data-testid="payments-environment-PRODUCTION"
-        sx={TAB_SX}
-      />
-    </Tabs>
+    <Box>
+      <Typography
+        sx={{ display: 'block', fontSize: '12px', fontWeight: 650, color: T.ink2, mb: '5px' }}
+      >
+        Ambiente desta conexão
+      </Typography>
+      <Tabs
+        value={environment}
+        onChange={(_, next: PaymentEnvironment) => onChange(next)}
+        aria-label="Ambiente desta conexão"
+        data-testid="payments-environment-tabs"
+        slotProps={{ indicator: { sx: { display: 'none' } } }}
+        sx={{
+          minHeight: 0,
+          width: 'fit-content',
+          background: T.bg2,
+          border: `1px solid ${T.line}`,
+          borderRadius: '9px',
+          p: '4px',
+        }}
+      >
+        <Tab
+          label="Sandbox"
+          value="SANDBOX"
+          data-testid="payments-environment-SANDBOX"
+          sx={TAB_SX}
+        />
+        <Tab
+          label="Produção"
+          value="PRODUCTION"
+          data-testid="payments-environment-PRODUCTION"
+          sx={TAB_SX}
+        />
+      </Tabs>
+    </Box>
   );
 }
 
@@ -72,10 +108,23 @@ export function EnvironmentSelector({
 export function EnvironmentNotice({
   environment,
   active,
+  band = true,
 }: {
   environment: PaymentEnvironment;
   /** The environment this store's real checkout uses, when it has one. */
   active: PaymentEnvironment | null;
+  /**
+   * Rendered as the card's full-bleed strip (the default), or as an ordinary
+   * inset alert.
+   *
+   * The band geometry — square corners, and `px: 3` matching the card's own
+   * padding so the text lines up with the content above and below — only reads
+   * correctly when the strip actually spans the card. Stacked INSIDE the manual
+   * disclosure, where it is already inset by the accordion, the same values
+   * indent the text a second time and square off a box that is visibly not
+   * touching either edge.
+   */
+  band?: boolean;
 }) {
   const elsewhere = active !== null && active !== environment ? ENVIRONMENT_LABELS[active] : null;
   const production = environment === 'PRODUCTION';
@@ -83,9 +132,9 @@ export function EnvironmentNotice({
     <Alert
       severity={production ? 'warning' : 'info'}
       variant="standard"
-      square
+      square={band}
       data-testid={`payments-environment-notice-${environment}`}
-      sx={{ borderRadius: 0, py: 0.5, px: 3 }}
+      sx={band ? { borderRadius: 0, py: 0.5, px: 3 } : { py: 0.5 }}
     >
       <strong>
         {production ? 'Produção — dinheiro real.' : 'Sandbox — ambiente de teste.'}

package/src/components/OAuthPanel.tsx

@@ -0,0 +1,166 @@
+'use client';
+
+import { Alert, Box, Button } from '@mui/material';
+import { useState, type ReactNode } from 'react';
+
+import { ConnectionProbe } from './ConnectionProbe';
+import { LINKISH_SX } from './panel-tokens';
+import { ProviderConnection } from './ProviderConnection';
+import type { ActivePanelProps } from './ProviderPanel';
+import { ProviderCard } from './ProviderPanel';
+
+/**
+ * The OAuth branch of a provider's screen, and the switch between its two
+ * connection paths.
+ *
+ * Split from `ProviderPanel` — which decides WHICH branch a provider gets —
+ * because this one is about what the connect branch looks like once chosen, and
+ * because the two together no longer fit the size gate.
+ */
+/**
+ * The collapsed row that moves the owner between the two connection paths.
+ *
+ * Both directions get one, and they are the same control: the row on screen
+ * always names the path you are NOT on. Only the manual leg carries content —
+ * the OAuth leg's "content" is the connect card, which belongs above the
+ * walkthrough rather than nested inside a disclosure — so `children` is
+ * optional and an empty one renders as a bare, clickable row.
+ */
+function PathSwitch({
+  label,
+  expanded,
+  onChange,
+  testId,
+  children,
+}: {
+  label: string;
+  expanded: boolean;
+  onChange: (expanded: boolean) => void;
+  testId: string;
+  children?: ReactNode;
+}) {
+  // Open, this is not a disclosure any more — it IS the path, and dressing a
+  // whole block (its own stepper, environment switch, fields and action bar) in
+  // a collapsible chrome adds a frame around a frame. So the content renders
+  // bare and only the CLOSED state is a control: one quiet line offering the
+  // other way in, which is all a path the owner is not on needs to be.
+  if (expanded) {
+    return (
+      <Box data-testid={testId} data-open="true">
+        {children}
+      </Box>
+    );
+  }
+  return (
+    <Box data-testid={testId} sx={{ px: '20px', pb: '20px' }}>
+      <Button onClick={() => onChange(true)} sx={{ ...LINKISH_SX, fontSize: '12.5px' }}>
+        {label}
+      </Button>
+    </Box>
+  );
+}
+
+/**
+ * The OAuth path: a connect button as the happy path, with the credential form
+ * kept behind a disclosure.
+ *
+ * ## One path on screen at a time
+ *
+ * Opening the manual disclosure is the owner SAYING which path they are on.
+ * While the connect card stayed above the open form the screen showed both at
+ * once — a card explaining that no key needs copying, directly over four boxes
+ * asking for keys, with the grant's own controls in between belonging to
+ * neither. Every control on that card acts on the OAuth grant; a store
+ * connecting by hand has no grant for them to act on.
+ *
+ * ## Order inside the card
+ *
+ * The activation step sits directly under the connect card and ABOVE the
+ * disclosure: it is what actually turns the store on, and an owner who just
+ * authorized has no reason to open a fallback to find it.
+ *
+ * The walkthrough renders OUTSIDE the disclosure for the same reason — it used
+ * to live inside the credential form, which on this branch is folded into the
+ * fallback, so the guide and the stepper answering "where am I" were buried
+ * behind a label the connect card says there is no reason to open (FUT-691).
+ * Its step LIST depends on the path: under authorization step 1 says to press
+ * the connect button above, and with pasted keys that button is not rendered.
+ * An adapter shipping a `credentialsPath` variant gets its own steps; one that
+ * does not keeps the single guide on both paths, unchanged.
+ *
+ * That fallback is not decoration — stores connected before Connect existed
+ * still hold a pasted token, and a deployment with no registered provider
+ * application has no working connect button at all. Hiding the form outright
+ * would strand both.
+ */
+export function OAuthPanel({
+  descriptor,
+  config,
+  client,
+  reload,
+  prepareConnect,
+  verification,
+  statusBar,
+  walkthrough,
+  form,
+}: ActivePanelProps & {
+  statusBar: ReactNode;
+  walkthrough: (path: 'oauth' | 'credentials') => ReactNode;
+  form: ReactNode;
+}) {
+  // Which path the owner is on. The disclosure is no longer just a container —
+  // opening it CHOOSES the credentials path, so the panel has to know.
+  const [manual, setManual] = useState(false);
+  // The connection probe, for a store whose connection is a grant: the form's
+  // own probe runs off Salvar, which an OAuth store never presses (FUT-691).
+  const probe = (
+    <ConnectionProbe descriptor={descriptor} config={config} client={client} reload={reload} />
+  );
+  if (!prepareConnect) {
+    return (
+      <ProviderCard header={statusBar}>
+        <Alert severity="info">
+          Este provedor conecta por autorização, mas o botão de conexão não está disponível nesta
+          instalação. Você ainda pode conectar informando as credenciais manualmente.
+        </Alert>
+        {form}
+        {probe}
+        {verification}
+      </ProviderCard>
+    );
+  }
+
+  return (
+    <ProviderCard header={statusBar}>
+      {manual ? (
+        <PathSwitch
+          label="Prefiro conectar por autorização"
+          expanded={false}
+          onChange={() => setManual(false)}
+          testId="payments-oauth-fallback"
+        />
+      ) : (
+        <ProviderConnection
+          descriptor={descriptor}
+          config={config}
+          client={client}
+          prepareConnect={prepareConnect}
+          onChanged={reload}
+        />
+      )}
+      {verification}
+      {manual ? null : walkthrough('oauth')}
+      {probe}
+      {descriptor.credentialSchema.length > 0 ? (
+        <PathSwitch
+          label="Prefiro informar as credenciais manualmente"
+          expanded={manual}
+          onChange={setManual}
+          testId="payments-manual-fallback"
+        >
+          {form}
+        </PathSwitch>
+      ) : null}
+    </ProviderCard>
+  );
+}

package/src/components/PaymentProviderSettings.tsx

@@ -3,7 +3,7 @@
 import { Alert, Box, Button, CircularProgress } from '@mui/material';
 import { useCallback, type ReactNode } from 'react';
 
-import type { MaskedProviderConfig } from '@12-apps/payments-backend';
+import type { MaskedProviderConfig, ProviderSetupGuide } from '@12-apps/payments-backend';
 
 import type { PaymentsSettingsClient } from '../client';
 import { canAttemptCharge } from './connection-state';
@@ -195,6 +195,23 @@ function verificationFor(io: VerificationInputs): ReactNode {
   });
 }
 
+/**
+ * The walkthrough for the connection path the panel currently has open.
+ *
+ * A provider that accepts both a grant and pasted keys ships one guide with a
+ * `credentialsPath` variant; everything else ships one guide, and both paths
+ * get it. Only the SECTIONS are swapped — the variant mirrors the base's stage
+ * count and confirmable index, which is what lets `blocked`/`hidden` above stay
+ * computed from the base guide alone.
+ */
+function guideForPath(
+  guide: ProviderSetupGuide | null,
+  path: 'oauth' | 'credentials',
+): ProviderSetupGuide | null {
+  if (!guide || path === 'oauth') return guide;
+  return guide.credentialsPath ? { ...guide.credentialsPath } : guide;
+}
+
 interface ProviderScreenProps extends ActivePanelProps {
   onBack: () => void;
 }
@@ -279,9 +296,12 @@ export function PaymentProviderSettings({
         onVerified: () => void reload(),
         onSetupIncomplete: ack.withdraw,
       })}
-      guide={(slots) => (
+      guide={({ path, ...slots }) => (
         <SetupGuideSection
-          guide={guide}
+          // Which walkthrough, per the path the panel has open. Only the
+          // SECTIONS differ; `blocked`/`hidden` above stay computed from the
+          // base guide, which `credentialsPath` is required to mirror.
+          guide={guideForPath(guide, path)}
           confirmed={ack.confirmed}
           onConfirm={ack.confirm}
           onReopen={ack.withdraw}

package/src/components/ProviderConnection.tsx

@@ -2,14 +2,10 @@
 
 import {
   Alert,
+  Box,
   Button,
   Chip,
   CircularProgress,
-  Dialog,
-  DialogActions,
-  DialogContent,
-  DialogContentText,
-  DialogTitle,
   Stack,
   Typography,
 } from '@mui/material';
@@ -23,7 +19,9 @@ import type {
 } from '@12-apps/payments-backend';
 
 import type { PaymentsSettingsClient } from '../client';
+import { ConnectionFacts, ConnectSteps, DisconnectDialog } from './ConnectionCard';
 import { expiryProximity, isConnected } from './connection-state';
+import { BAR_MSG_SX, BAR_SX, BTN_PRIMARY_SX, BTN_QUIET_DANGER_SX, T } from './panel-tokens';
 
 /**
  * The `authMode: 'oauth'` half of the settings page: a provider whose
@@ -81,6 +79,47 @@ function ExpiryNote(props: { expiresAt: string }) {
   );
 }
 
+/**
+ * A failed connect, in the owner's terms.
+ *
+ * The one case worth naming is the deployment that has registered no OAuth
+ * application for this provider. It surfaced as
+ * `{"error":"CredentialsError","message":"No platform OAuth application
+ * credentials configured for stripe/SANDBOX"}` in a red box under the connect
+ * button — an error class, a slash-joined pair of internal identifiers, and not
+ * one word about what to do. It is not a failure the owner caused or can fix,
+ * and it is not a dead end either: the credentials path works, and it is right
+ * there on the same screen. So it reads as a warning that names the way round.
+ *
+ * Anything else is passed through. The adapter's own sentence beats a generic
+ * one, and inventing copy for a failure we have not seen is how a screen ends
+ * up confidently misdescribing an outage.
+ */
+function connectFailure(
+  message: string,
+  displayName: string,
+): { severity: 'error' | 'warning'; text: string } {
+  if (/no platform oauth application credentials/i.test(message)) {
+    return {
+      severity: 'warning',
+      text:
+        `A conexão automática com ${displayName} não está disponível nesta instalação — ` +
+        'o aplicativo de autorização não foi cadastrado. Para conectar agora, abra ' +
+        '“Prefiro informar as credenciais manualmente” abaixo e cole as suas próprias chaves.',
+    };
+  }
+  return { severity: 'error', text: message };
+}
+
+function ConnectError({ message, displayName }: { message: string; displayName: string }) {
+  const { severity, text } = connectFailure(message, displayName);
+  return (
+    <Alert severity={severity} data-testid="payments-connect-failure">
+      {text}
+    </Alert>
+  );
+}
+
 function connectLabel(displayName: string, connected: boolean, busy: string | null) {
   if (busy === 'connect') return <CircularProgress size={18} />;
   return connected ? 'Reconectar' : `Conectar com ${displayName}`;
@@ -134,6 +173,8 @@ function ConnectedAccountDetails(props: { account: ConnectedOAuthAccount }) {
   );
 }
 
+
+
 /** Header + explanatory copy + any warning banner for the connection. */
 function ConnectionSummary(props: {
   displayName: string;
@@ -153,15 +194,11 @@ function ConnectionSummary(props: {
         once connected, since the provider sealed it into the grant.
       */}
       {props.connected ? (
-        <Stack direction="row" spacing={1} alignItems="center">
-          <Chip
-            size="small"
-            variant="outlined"
-            data-testid="payments-connected-environment"
-            label={props.environment === 'PRODUCTION' ? 'Produção' : 'Sandbox (testes)'}
-            color={props.environment === 'PRODUCTION' ? 'default' : 'warning'}
-          />
-        </Stack>
+        <ConnectionFacts
+          environment={props.environment}
+          account={props.connectedAccount}
+          displayName={props.displayName}
+        />
       ) : null}
       {/*
         The connected sentence names NO platform. It used to open with one
@@ -176,11 +213,12 @@ function ConnectionSummary(props: {
         grant, not whose logo is on the page. The subject is the connection
         itself, which is true for every host and needs no new configuration.
       */}
-      <Typography variant="body2" color="text.secondary">
+      <Typography sx={{ fontSize: '13px', color: T.ink2, lineHeight: 1.6 }}>
         {props.connected
           ? 'Sua conta está conectada. As cobranças são criadas em seu nome — nenhuma chave precisa ser copiada.'
           : `Conecte sua conta ${props.displayName} autorizando o acesso no site do provedor. Nenhuma chave precisa ser copiada.`}
       </Typography>
+      {props.connected ? null : <ConnectSteps displayName={props.displayName} />}
       {props.connected && props.connectedAccount ? (
         <ConnectedAccountDetails account={props.connectedAccount} />
       ) : null}
@@ -194,47 +232,16 @@ function ConnectionSummary(props: {
   );
 }
 
+
+
 /**
- * Confirmation for Desconectar, which is destructive and irreversible from
- * here: it revokes the grant at the provider, so the store stops being able to
- * charge immediately and getting back requires the owner to authorize again on
- * the provider's site. It also sat one careless click from "Reconectar".
+ * The connect card's action bar.
+ *
+ * Removing the connection is stated QUIETLY beside the step's own button rather
+ * than as a second filled control: an owner reaches it deliberately or not at
+ * all, and a red button of equal weight on every visit is an invitation to
+ * misclick the one action here that cannot be undone from this screen.
  */
-function DisconnectDialog(props: {
-  open: boolean;
-  displayName: string;
-  busy: boolean;
-  onCancel: () => void;
-  onConfirm: () => void;
-}) {
-  return (
-    <Dialog open={props.open} onClose={props.onCancel} data-testid="payments-disconnect-confirm">
-      <DialogTitle>Desconectar {props.displayName}?</DialogTitle>
-      <DialogContent>
-        <DialogContentText>
-          A autorização será revogada no {props.displayName} e sua loja deixa de conseguir cobrar
-          imediatamente. Para voltar a receber, será necessário conectar a conta novamente
-          autorizando o acesso no site do provedor.
-        </DialogContentText>
-      </DialogContent>
-      <DialogActions>
-        <Button onClick={props.onCancel} disabled={props.busy}>
-          Cancelar
-        </Button>
-        <Button
-          color="error"
-          variant="contained"
-          onClick={props.onConfirm}
-          disabled={props.busy}
-          data-testid="payments-disconnect-confirm-action"
-        >
-          {props.busy ? <CircularProgress size={18} /> : 'Desconectar'}
-        </Button>
-      </DialogActions>
-    </Dialog>
-  );
-}
-
 function ConnectionActions(props: {
   displayName: string;
   connected: boolean;
@@ -244,16 +251,32 @@ function ConnectionActions(props: {
 }) {
   const { displayName, connected, busy, onConnect, onDisconnect } = props;
   return (
-    <Stack direction="row" spacing={1}>
-      <Button variant="contained" disabled={busy !== null} onClick={onConnect}>
-        {connectLabel(displayName, connected, busy)}
-      </Button>
+    <Box sx={BAR_SX} data-testid="payments-connection-bar">
+      <Typography sx={BAR_MSG_SX}>
+        {connected
+          ? `Conta ${displayName} conectada. Revogue quando quiser, aqui ou no painel do provedor.`
+          : 'Você sai para o provedor e volta para cá — leva menos de um minuto.'}
+      </Typography>
       {connected ? (
-        <Button variant="outlined" color="error" disabled={busy !== null} onClick={onDisconnect}>
-          {busy === 'disconnect' ? <CircularProgress size={18} /> : 'Desconectar'}
+        <Button
+          disabled={busy !== null}
+          onClick={onDisconnect}
+          sx={BTN_QUIET_DANGER_SX}
+          data-testid="payments-disconnect"
+        >
+          {busy === 'disconnect' ? <CircularProgress size={18} /> : 'Remover conexão'}
         </Button>
       ) : null}
-    </Stack>
+      <Button
+        variant="contained"
+        disableElevation
+        disabled={busy !== null}
+        onClick={onConnect}
+        sx={BTN_PRIMARY_SX}
+      >
+        {connectLabel(displayName, connected, busy)}
+      </Button>
+    </Box>
   );
 }
 
@@ -278,17 +301,37 @@ function useConnectionAction(onChanged: () => void) {
   return { busy, error, run };
 }
 
+/**
+ * The connection as this card reads it, with every default applied once.
+ *
+ * `environment` follows whatever the provider is already configured for and
+ * falls back to SANDBOX, so a live grant is never the accident — changing it is
+ * an ADVANCED action that lives with the manual credentials, not on the
+ * one-button connect card.
+ */
+function readConnection(config: MaskedProviderConfig | null) {
+  return {
+    environment: (config?.environment ?? 'SANDBOX') as PaymentEnvironment,
+    status: config?.status ?? 'UNVERIFIED',
+    connected: isConnected(config),
+    expiresAt: config?.expiresAt ?? null,
+    account: config?.connectedAccount ?? null,
+    receiving: config?.enabled === true,
+  };
+}
+
 export function ProviderConnection(props: ProviderConnectionProps) {
   const { descriptor, config, client, prepareConnect, onChanged } = props;
   const { busy, error, run } = useConnectionAction(onChanged);
   const [confirmingDisconnect, setConfirmingDisconnect] = useState(false);
-  // Which account the owner is connecting. Follows whatever this provider is
-  // already configured for, defaulting to SANDBOX so a live grant is never the
-  // accident. Changing it is an ADVANCED action and lives with the manual
-  // credentials, not on the one-button connect card.
-  const environment: PaymentEnvironment = config?.environment ?? 'SANDBOX';
-  const status = config?.status ?? 'UNVERIFIED';
-  const connected = isConnected(config);
+  const { environment, status, connected, expiresAt, account, receiving } = readConnection(config);
+
+  /** Run a dialog action and shut the dialog once it has actually landed. */
+  const close = (kind: string, action: () => Promise<unknown>) =>
+    void run(kind, async () => {
+      await action();
+      setConfirmingDisconnect(false);
+    });
 
   const connect = () =>
     void run('connect', async () => {
@@ -307,12 +350,12 @@ export function ProviderConnection(props: ProviderConnectionProps) {
         displayName={descriptor.displayName}
         status={status}
         connected={connected}
-        expiresAt={config?.expiresAt ?? null}
+        expiresAt={expiresAt}
         environment={environment}
-        connectedAccount={config?.connectedAccount ?? null}
+        connectedAccount={account}
       />
 
-      {error ? <Alert severity="error">{error}</Alert> : null}
+      {error ? <ConnectError message={error} displayName={descriptor.displayName} /> : null}
 
       <ConnectionActions
         displayName={descriptor.displayName}
@@ -326,13 +369,12 @@ export function ProviderConnection(props: ProviderConnectionProps) {
         open={confirmingDisconnect}
         displayName={descriptor.displayName}
         busy={busy === 'disconnect'}
+        // Live on this provider: removing it stops checkout, and pausing is a
+        // real alternative rather than a lesser version of the same thing.
+        receiving={receiving}
+        onPauseInstead={() => close('pause', () => client.setEnabled(descriptor.name, false))}
         onCancel={() => setConfirmingDisconnect(false)}
-        onConfirm={() =>
-          void run('disconnect', async () => {
-            await client.disconnectOAuth(descriptor.name);
-            setConfirmingDisconnect(false);
-          })
-        }
+        onConfirm={() => close('disconnect', () => client.disconnectOAuth(descriptor.name))}
       />
     </Stack>
   );