@12-apps/payments-frontend 1.0.0

package/src/components/ProviderPriorityList.tsx

@@ -0,0 +1,293 @@
+'use client';
+
+import {
+  Alert,
+  Box,
+  FormControlLabel,
+  IconButton,
+  Paper,
+  Stack,
+  Switch,
+  Typography,
+} from '@mui/material';
+import { useCallback, useState } from 'react';
+
+import type { MerchantSettingsView, ProviderDescriptor } from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+
+/**
+ * The store's failover chain, ordered.
+ *
+ * Checkout walks this list top-down, moving on only when it can PROVE the
+ * provider above created no charge — so the order is real routing
+ * configuration, not a display preference. That is why the copy names the
+ * first entry explicitly rather than leaving the merchant to infer it from
+ * position.
+ *
+ * Reordering is offered two ways on purpose. Dragging is what the design asks
+ * for; the arrow buttons are what makes it usable with a keyboard or a screen
+ * reader, and what an automated test can drive. Neither is a fallback for the
+ * other — they write the same whole-chain update.
+ */
+export interface ProviderPriorityListProps {
+  view: MerchantSettingsView;
+  client: PaymentsSettingsClient;
+  /** Called with the refreshed view after a successful reorder. */
+  onReordered?: (view: MerchantSettingsView) => void;
+}
+
+/** Move `from` to `to`, returning a new array. */
+function reorder(chain: readonly string[], from: number, to: number): string[] {
+  if (to < 0 || to >= chain.length || from === to) return [...chain];
+  const next = [...chain];
+  const [moved] = next.splice(from, 1);
+  if (moved === undefined) return [...chain];
+  next.splice(to, 0, moved);
+  return next;
+}
+
+function labelOf(providers: readonly ProviderDescriptor[], name: string): string {
+  return providers.find((p) => p.name === name)?.displayName ?? name;
+}
+
+/**
+ * The chain, derived from `configs` rather than read from `view.providerChain`.
+ *
+ * Both carry the same fact, and deriving keeps ONE source of truth in the UI:
+ * a payload where the two disagree — a client bundle talking to an older
+ * server mid-deploy, say — renders the enable flags the rest of this page
+ * shows, instead of white-screening on a field that is not there.
+ */
+export function chainOf(view: MerchantSettingsView): string[] {
+  return view.configs
+    .filter((c) => c.enabled)
+    .slice()
+    .sort((a, b) => a.priority - b.priority || a.provider.localeCompare(b.provider))
+    .map((c) => c.provider);
+}
+
+interface PriorityRowProps {
+  label: string;
+  provider: string;
+  index: number;
+  total: number;
+  saving: boolean;
+  dragging: boolean;
+  onDragStart: () => void;
+  onDropOn: () => void;
+  onDragEnd: () => void;
+  onMove: (from: number, to: number) => void;
+}
+
+function PriorityRow({
+  label,
+  provider,
+  index,
+  total,
+  saving,
+  dragging,
+  onDragStart,
+  onDropOn,
+  onDragEnd,
+  onMove,
+}: PriorityRowProps) {
+  return (
+    <Paper
+      component="li"
+      variant="outlined"
+      data-testid={`payments-priority-item-${provider}`}
+      draggable={!saving}
+      onDragStart={onDragStart}
+      onDragOver={(e: React.DragEvent) => e.preventDefault()}
+      onDrop={(e: React.DragEvent) => {
+        e.preventDefault();
+        onDropOn();
+      }}
+      onDragEnd={onDragEnd}
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 1,
+        p: 1,
+        cursor: saving ? 'progress' : 'grab',
+        opacity: dragging ? 0.5 : 1,
+      }}
+    >
+      <Typography variant="body2" color="text.secondary" sx={{ minWidth: 24, textAlign: 'center' }}>
+        {index + 1}
+      </Typography>
+      <Typography sx={{ flexGrow: 1 }}>{label}</Typography>
+      {index === 0 ? (
+        <Typography variant="caption" color="primary" data-testid="payments-priority-first">
+          primeiro
+        </Typography>
+      ) : null}
+      <IconButton
+        size="small"
+        aria-label={`Mover ${label} para cima`}
+        disabled={index === 0 || saving}
+        onClick={() => onMove(index, index - 1)}
+      >
+        ↑
+      </IconButton>
+      <IconButton
+        size="small"
+        aria-label={`Mover ${label} para baixo`}
+        disabled={index === total - 1 || saving}
+        onClick={() => onMove(index, index + 1)}
+      >
+        ↓
+      </IconButton>
+    </Paper>
+  );
+}
+
+/**
+ * The optimistic-reorder state machine, kept out of the component so the
+ * render stays readable. The SERVER's response — not the local guess — sets
+ * the final order, so a concurrent change elsewhere is not papered over; a
+ * failure rolls the list back to where it was.
+ */
+function useChainReorder(
+  view: MerchantSettingsView,
+  client: PaymentsSettingsClient,
+  onReordered?: (next: MerchantSettingsView) => void,
+) {
+  const [chain, setChain] = useState<string[]>(() => chainOf(view));
+  const [error, setError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+
+  const move = useCallback(
+    (from: number, to: number) => {
+      const next = reorder(chain, from, to);
+      if (next.join(' ') === chain.join(' ')) return;
+      const previous = chain;
+      setChain(next);
+      setSaving(true);
+      setError(null);
+      void client
+        .setPriorities(next)
+        .then((updated) => {
+          setChain(chainOf(updated));
+          onReordered?.(updated);
+        })
+        .catch((err: unknown) => {
+          setChain(previous);
+          setError(err instanceof Error ? err.message : 'Não foi possível salvar a ordem.');
+        })
+        .finally(() => setSaving(false));
+    },
+    [chain, client, onReordered],
+  );
+
+  return { chain, error, saving, move };
+}
+
+/**
+ * Decline cascading — retrying a REFUSED card on the next acquirer.
+ *
+ * Deliberately a separate, explicit control rather than something the reorder
+ * list implies. Ordering is a technical preference; this is a business
+ * decision with fraud and interchange-fee consequences, and the copy says so
+ * instead of leaving the merchant to discover it from their statement.
+ */
+function DeclinePolicyControl({
+  view,
+  client,
+  onChanged,
+}: {
+  view: MerchantSettingsView;
+  client: PaymentsSettingsClient;
+  onChanged?: (next: MerchantSettingsView) => void;
+}) {
+  const [saving, setSaving] = useState(false);
+  const cascades = view.failoverPolicy === 'TECHNICAL_AND_DECLINE';
+
+  return (
+    <Box sx={{ mb: 2 }} data-testid="payments-decline-policy">
+      <FormControlLabel
+        control={
+          <Switch
+            size="small"
+            checked={cascades}
+            disabled={saving}
+            inputProps={{ 'aria-label': 'Tentar cartão recusado no próximo provedor' }}
+            onChange={(e) => {
+              setSaving(true);
+              void client
+                .setFailoverPolicy(e.target.checked ? 'TECHNICAL_AND_DECLINE' : 'TECHNICAL')
+                .then((updated) => onChanged?.(updated))
+                .finally(() => setSaving(false));
+            }}
+          />
+        }
+        label={
+          <Typography variant="body2">
+            Tentar cartão <strong>recusado</strong> no próximo provedor
+          </Typography>
+        }
+      />
+      <Typography variant="caption" color="text.secondary" display="block">
+        {cascades
+          ? 'Uma recusa passa para o próximo da lista. Isso pode aumentar custos de transação e sinais de fraude.'
+          : 'Padrão: uma recusa encerra a cobrança. Só falhas técnicas passam para o próximo.'}
+      </Typography>
+    </Box>
+  );
+}
+
+export function ProviderPriorityList({ view, client, onReordered }: ProviderPriorityListProps) {
+  const { chain, error, saving, move } = useChainReorder(view, client, onReordered);
+  const [dragging, setDragging] = useState<number | null>(null);
+
+  if (chain.length === 0) {
+    return (
+      <Alert severity="warning" data-testid="payments-priority-empty">
+        Nenhum provedor está ativo. O checkout não conseguirá cobrar até que você ative ao menos um.
+      </Alert>
+    );
+  }
+
+  return (
+    <Box data-testid="payments-priority-list">
+      <Typography variant="subtitle2" gutterBottom>
+        Ordem de tentativa
+      </Typography>
+      <Typography variant="body2" color="text.secondary" sx={{ mb: 1.5 }}>
+        O checkout tenta <strong>{labelOf(view.providers, chain[0] ?? '')}</strong> primeiro. Se uma
+        cobrança falhar por motivo técnico, ele tenta o próximo da lista — mas só quando é possível
+        comprovar que a tentativa anterior não gerou cobrança.
+      </Typography>
+
+      {error ? (
+        <Alert severity="error" sx={{ mb: 1.5 }} data-testid="payments-priority-error">
+          {error}
+        </Alert>
+      ) : null}
+
+      <DeclinePolicyControl view={view} client={client} onChanged={onReordered} />
+
+      <Stack spacing={1} component="ol" sx={{ listStyle: 'none', p: 0, m: 0 }}>
+        {chain.map((provider, index) => (
+          <PriorityRow
+            key={provider}
+            label={labelOf(view.providers, provider)}
+            provider={provider}
+            index={index}
+            total={chain.length}
+            saving={saving}
+            dragging={dragging === index}
+            onDragStart={() => setDragging(index)}
+            onDropOn={() => {
+              if (dragging !== null) move(dragging, index);
+              setDragging(null);
+            }}
+            onDragEnd={() => setDragging(null)}
+            onMove={move}
+          />
+        ))}
+      </Stack>
+    </Box>
+  );
+}

package/src/components/ProviderSetupGuide.tsx

@@ -0,0 +1,263 @@
+'use client';
+
+import {
+  Alert,
+  Box,
+  Button,
+  IconButton,
+  Link,
+  Paper,
+  Stack,
+  Step,
+  StepLabel,
+  Stepper,
+  TextField,
+  Typography,
+} from '@mui/material';
+import { useState, type ReactNode } from 'react';
+
+import type { ProviderSetupGuide as Guide, SetupSection, SetupStep } from '@12-apps/payments-backend';
+
+import { richText } from './rich-text';
+
+/**
+ * Renders a provider's step-by-step onboarding walkthrough — the reusable
+ * equivalent of the PagBank "Como gerar o token e cadastrar as URLs"
+ * screen: an onboarding stepper (Conectar conta → Homologar → Ativar
+ * vendas) plus numbered instruction sections with dashboard links and
+ * copy-paste URL fields. Content comes from the backend adapter's
+ * `setupGuide`; this component owns only presentation.
+ */
+export interface ProviderSetupGuideProps {
+  guide: Guide;
+  /** Index into `guide.stages` of the merchant's current stage. */
+  activeStage?: number;
+  /**
+   * Handlers for the in-app actions an adapter's steps can request, keyed by
+   * the adapter's opaque action id (PagBank asks for `homologacao-anexo`).
+   * An action with no handler renders NO button — the step's text still reads
+   * correctly on its own, so a host can adopt a provider before implementing
+   * its optional conveniences.
+   */
+  actions?: Record<string, { label: string; run: () => void | Promise<void> }>;
+  /**
+   * Rendered between the stepper and the current section — where the steps
+   * ALREADY finished go, as one-line rows.
+   *
+   * Above the open card rather than below it, because that is the reading
+   * order the stepper promises: done, doing, still to do. Below, a completed
+   * step looked like a consequence of the one in progress.
+   */
+  beforeSections?: ReactNode;
+  /**
+   * Rendered INSIDE the current section's card, after its steps.
+   *
+   * This is where the walkthrough stops being prose and becomes the thing
+   * itself: the instruction "informe sua InfiniteTag" and the field you type it
+   * into are one step, and separating them put a card of advice above a
+   * detached input, leaving the owner to work out that the two were related.
+   */
+  sectionFooter?: ReactNode;
+}
+
+function CopyField({
+  label,
+  text,
+  collapsible,
+}: {
+  label: string;
+  text: string;
+  collapsible?: boolean;
+}) {
+  const [open, setOpen] = useState(!collapsible);
+  if (!collapsible) return <CopyRow label={label} text={text} />;
+  return (
+    // Stretch, not flex-start: the revealed field is a full-width address and
+    // shrinking it to its own content clipped the URL mid-domain. The toggle
+    // keeps its intrinsic width by sitting in a Box of its own.
+    <Stack spacing={1}>
+      <Box>
+        <Button
+          size="small"
+          sx={{ ...BUTTON_SX, px: 0 }}
+          onClick={() => setOpen((shown) => !shown)}
+          data-testid="payments-setup-copy-reveal"
+        >
+          {label} {open ? '▴' : '▾'}
+        </Button>
+      </Box>
+      {open ? <CopyRow label={label} text={text} /> : null}
+    </Stack>
+  );
+}
+
+function CopyRow({ label, text }: { label: string; text: string }) {
+  const [copied, setCopied] = useState(false);
+  return (
+    <Stack direction="row" spacing={1} alignItems="center" sx={{ width: '100%' }}>
+      {/*
+        Disabled, not merely read-only: nothing here is to be edited, and a
+        live-looking field invited owners to type into the one value on the step
+        that is pure reference.
+      */}
+      <TextField fullWidth size="small" disabled value={text} />
+      <IconButton
+        aria-label={copied ? 'Copiado' : `Copiar ${label}`}
+        onClick={() => {
+          void navigator.clipboard.writeText(text).then(() => setCopied(true));
+        }}
+      >
+        {copied ? '✓' : '⧉'}
+      </IconButton>
+    </Stack>
+  );
+}
+
+/**
+ * Sentence case. MUI upper-cases button labels by default, which turns copy
+ * written to be read into copy that is shouted — "VER A MINHA INFINITETAG"
+ * also loses the capitalisation that made "InfiniteTag" one word.
+ */
+const BUTTON_SX = { textTransform: 'none' } as const;
+
+type StepActions = ProviderSetupGuideProps['actions'];
+
+interface StepRowProps {
+  step: SetupStep;
+  actions: StepActions;
+}
+
+/**
+ * The numbers an owner reads, which are not the array indices.
+ *
+ * Warnings sit between instructions and carry no number of their own, so
+ * numbering by position would print "1, 3" and skip a step that was never
+ * there. Counted rather than indexed.
+ */
+/**
+ * A step that warns rather than instructs.
+ *
+ * Un-numbered on purpose: it is not a thing to DO, and numbering it made the
+ * two most important sentences in InfinitePay's walkthrough — the tag decides
+ * who gets paid, and the page we link to can also change it — read as further
+ * instructions BELOW the button that had already taken the owner there.
+ */
+function WarningRow({ text }: { text: string }) {
+  return (
+    <Alert severity="warning" data-testid="payments-setup-warning">
+      <Typography variant="body2">{richText(text)}</Typography>
+    </Alert>
+  );
+}
+
+function StepRow({ step, actions }: StepRowProps) {
+  const action = step.action ? actions?.[step.action] : undefined;
+  if (step.tone === 'warning') return <WarningRow text={step.text ?? ''} />;
+  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}
+      {action ? (
+        <Box>
+          <Button variant="contained" size="small" sx={BUTTON_SX} onClick={() => void action.run()}>
+            {action.label}
+          </Button>
+        </Box>
+      ) : null}
+      {step.copy ? (
+        <CopyField
+          label={step.copy.label}
+          text={step.copy.text}
+          collapsible={step.copy.collapsible}
+        />
+      ) : null}
+    </Stack>
+  );
+}
+
+export function ProviderSetupGuide({
+  guide,
+  activeStage = 0,
+  actions,
+  beforeSections,
+  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>
+          </Step>
+        ))}
+      </Stepper>
+      {beforeSections}
+      {guide.sections.map((section) => (
+        <SectionCard key={section.id} section={section} actions={actions} footer={sectionFooter} />
+      ))}
+    </Stack>
+  );
+}
+
+function SectionCard({
+  section,
+  actions,
+  footer,
+}: {
+  section: SetupSection;
+  actions: StepActions;
+  footer?: ReactNode;
+}) {
+  return (
+    <Paper
+      variant="outlined"
+      sx={{ p: 2 }}
+      // 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">
+          {section.title}
+        </Typography>
+        {section.intro ? (
+          <Typography variant="body2" color="text.secondary">
+            {richText(section.intro)}
+          </Typography>
+        ) : null}
+        {section.steps.map((step, index) => (
+          <StepRow key={index} step={step} actions={actions} />
+        ))}
+        {footer}
+      </Stack>
+    </Paper>
+  );
+}