Frontend Transaction UX: Status, Errors, Recovery

// Keep status values small and explicit so the UI cannot drift.
export type TxStatus =
  | "idle"
  | "preparing"
  | "awaiting-signature"
  | "broadcasting"
  | "confirming"
  | "confirmed"
  | "failed";

// Error kinds are user-facing categories. The raw error stays in logs.
export type TxErrorKind = "user-rejected" | "network" | "expired" | "program" | "unknown";

export function classifyTxError(err: string): TxErrorKind {
  const e = err.toLowerCase();
  // The goal is not perfect parsing. The goal is actionable UX.
  if (e.includes("reject")) return "user-rejected";
  if (e.includes("blockhash")) return "expired";
  if (e.includes("timeout") || e.includes("network")) return "network";
  if (e.includes("instruction") || e.includes("program")) return "program";
  return "unknown";
}

"use client";

import React, { useState } from "react";
import { classifyTxError, type TxStatus } from "@/lib/solana/uiTxState";

export function TxActionCard() {
  // Keep tx UI state in a single place so it is impossible to show conflicting statuses.
  const [status, setStatus] = useState<TxStatus>("idle");
  const [signature, setSignature] = useState("");
  const [error, setError] = useState("");

  const run = async () => {
    // Clear previous attempt output.
    setError("");
    setSignature("");

    try {
      // These status transitions are the UX contract.
      setStatus("preparing");
      setStatus("awaiting-signature");
      setStatus("broadcasting");
      setStatus("confirming");
      // Replace with real service call:
      const fakeSig = "3Ab...demo-signature";
      setSignature(fakeSig);
      setStatus("confirmed");
    } catch (e: any) {
      const kind = classifyTxError(String(e?.message ?? e));
      // Always show a next action to the user.
      setError(`Failed (${kind}). Suggested action: retry or rebuild.`);
      setStatus("failed");
    }
  };

  return (
    <div className="rounded-xl border border-zinc-700 p-4 space-y-2">
      <div className="text-sm">Status: {status}</div>
      <button onClick={run} disabled={status !== "idle" && status !== "failed" && status !== "confirmed"} className="px-3 py-2 rounded bg-cyan-700 text-white">
        Run Transaction
      </button>
      {signature && <div className="text-xs">Signature: {signature}</div>}
      {error && <div className="text-xs text-red-300">{error}</div>}
    </div>
  );
}