From 6c69eda606e19e9420b9a768219599c4df560477 Mon Sep 17 00:00:00 2001
From: Blockchainrafik <blockchainrafik>
Date: Sun, 30 Aug 2026 08:49:23 +0100
Subject: [PATCH] =?UTF-8?q?Add=20DisputeRaiseModal=20=E2=80=94=20a11y,=20e?=
 =?UTF-8?q?mpty=20state,=20interactive=20states,=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 __tests__/dispute-raise-modal.test.tsx | 924 +++++++++++++++++++++++++
 app/components/DisputeRaiseModal.tsx   | 417 +++++++++++
 2 files changed, 1341 insertions(+)
 create mode 100644 __tests__/dispute-raise-modal.test.tsx
 create mode 100644 app/components/DisputeRaiseModal.tsx

diff --git a/__tests__/dispute-raise-modal.test.tsx b/__tests__/dispute-raise-modal.test.tsx
new file mode 100644
index 0000000..24c25bf
--- /dev/null
+++ b/__tests__/dispute-raise-modal.test.tsx
@@ -0,0 +1,924 @@
+/**
+ * Unit tests for DisputeRaiseModal
+ *
+ * Covers (issue #339):
+ *  1.  Node rendering — modal open/closed guard
+ *  2.  Empty-state node rendering (#333) — null milestoneIndex
+ *  3.  Empty-state layout / design-token classes (#333)
+ *  4.  Confirmation body — valid milestoneIndex
+ *  5.  Milestone label helper (milestoneLabel)
+ *  6.  ARIA attribute compliance (#330)
+ *       - role="dialog", aria-modal, aria-labelledby, aria-describedby
+ *       - role="alert" on warning banner
+ *       - aria-label on action buttons
+ *       - aria-disabled mirroring HTML disabled
+ *       - aria-live="polite" on empty state
+ *       - Escape key closes the modal
+ *       - Backdrop click closes the modal
+ *  7.  Interactive states / Tailwind classes (#331)
+ *       - hover, focus-visible, disabled class presence
+ *       - active:scale-[0.97] on action buttons
+ *       - disabled:opacity-40, disabled:cursor-not-allowed
+ *  8.  Action button behaviour
+ *       - onConfirm / onClose callbacks
+ *       - isPending disables both buttons and shows spinner label
+ *       - no-handler (null milestoneIndex) disables confirm
+ *  9.  Amount display
+ * 10.  TxStatusBanner visibility
+ */
+
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import DisputeRaiseModal, {
+  milestoneLabel,
+} from "@/app/components/DisputeRaiseModal";
+
+// ---------------------------------------------------------------------------
+// Mocks — TxStatusBanner and ButtonSpinner are simple presentational
+// components; we stub them to keep tests focused on DisputeRaiseModal logic.
+// ---------------------------------------------------------------------------
+
+vi.mock("@/app/components/TxStatusBanner", () => ({
+  default: ({ state, successMessage }: { state: { phase: string }; successMessage?: string }) =>
+    state.phase !== "idle" ? (
+      <div data-testid="tx-status-banner" data-phase={state.phase}>
+        {successMessage}
+      </div>
+    ) : null,
+}));
+
+vi.mock("@/app/components/ButtonSpinner", () => ({
+  default: () => <span data-testid="button-spinner" aria-hidden="true" />,
+}));
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const idleState = { phase: "idle" as const, error: null, txHash: null };
+const buildingState = { phase: "building" as const, error: null, txHash: null };
+
+const baseProps = {
+  isOpen: true,
+  onClose: vi.fn(),
+  onConfirm: vi.fn(),
+  milestoneIndex: 0,
+};
+
+const renderModal = (
+  overrides: Partial<Parameters<typeof DisputeRaiseModal>[0]> = {}
+) => render(<DisputeRaiseModal {...baseProps} {...overrides} />);
+
+// ---------------------------------------------------------------------------
+// 1. Node rendering — open / closed guard
+// ---------------------------------------------------------------------------
+
+describe("DisputeRaiseModal — open/closed rendering", () => {
+  it("renders nothing when isOpen is false", () => {
+    renderModal({ isOpen: false });
+    expect(
+      screen.queryByTestId("dispute-raise-modal")
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the modal backdrop when isOpen is true", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-raise-modal")).toBeInTheDocument();
+  });
+
+  it("renders the modal panel when isOpen is true", () => {
+    renderModal();
+    expect(
+      screen.getByTestId("dispute-raise-modal-content")
+    ).toBeInTheDocument();
+  });
+
+  it("renders the title 'Raise a Dispute'", () => {
+    renderModal();
+    expect(
+      screen.getByTestId("dispute-modal-title")
+    ).toHaveTextContent("Raise a Dispute");
+  });
+
+  it("renders the close button", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-close")).toBeInTheDocument();
+  });
+
+  it("renders the actions row", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-actions")).toBeInTheDocument();
+  });
+
+  it("renders the Cancel button", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-cancel")).toBeInTheDocument();
+  });
+
+  it("renders the Confirm button", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toBeInTheDocument();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Empty-state node rendering (#333)
+// ---------------------------------------------------------------------------
+
+describe("DisputeRaiseModal — empty-state node rendering (#333)", () => {
+  it("renders the empty-state when milestoneIndex is null", () => {
+    renderModal({ milestoneIndex: null });
+    expect(
+      screen.getByTestId("dispute-modal-empty-state")
+    ).toBeInTheDocument();
+  });
+
+  it("does NOT render the confirmation body when milestoneIndex is null", () => {
+    renderModal({ milestoneIndex: null });
+    expect(
+      screen.queryByTestId("dispute-modal-body")
+    ).not.toBeInTheDocument();
+  });
+
+  it("does NOT render the empty-state when milestoneIndex is a number", () => {
+    renderModal({ milestoneIndex: 0 });
+    expect(
+      screen.queryByTestId("dispute-modal-empty-state")
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the empty-state heading 'No milestone selected'", () => {
+    renderModal({ milestoneIndex: null });
+    expect(
+      screen.getByTestId("dispute-modal-empty-heading")
+    ).toHaveTextContent("No milestone selected");
+  });
+
+  it("renders the empty-state description text", () => {
+    renderModal({ milestoneIndex: null });
+    expect(
+      screen.getByTestId("dispute-modal-empty-description")
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("dispute-modal-empty-description")
+    ).toHaveTextContent(/Select a milestone/i);
+  });
+
+  it("renders the 'Waiting for selection' badge", () => {
+    renderModal({ milestoneIndex: null });
+    expect(
+      screen.getByTestId("dispute-modal-empty-badge")
+    ).toHaveTextContent("Waiting for selection");
+  });
+
+  it("empty-state description mentions 'Pending' and 'Delivered' statuses", () => {
+    renderModal({ milestoneIndex: null });
+    const desc = screen.getByTestId("dispute-modal-empty-description");
+    expect(desc).toHaveTextContent(/Pending/);
+    expect(desc).toHaveTextContent(/Delivered/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Empty-state layout / design-token classes (#333)
+// ---------------------------------------------------------------------------
+
+describe("DisputeRaiseModal — empty-state layout classes (#333)", () => {
+  it("empty-state wrapper has 'border' class", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-state")).toHaveClass(
+      "border"
+    );
+  });
+
+  it("empty-state wrapper has 'rounded-lg' class", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-state")).toHaveClass(
+      "rounded-lg"
+    );
+  });
+
+  it("empty-state wrapper has 'bg-surface-field' design token", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-state")).toHaveClass(
+      "bg-surface-field"
+    );
+  });
+
+  it("empty-state wrapper has 'flex' and 'flex-col' classes", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-state")).toHaveClass(
+      "flex",
+      "flex-col"
+    );
+  });
+
+  it("empty-state wrapper has 'sm:flex-row' responsive class", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-state")).toHaveClass(
+      "sm:flex-row"
+    );
+  });
+
+  it("empty-state wrapper has 'sm:items-center' responsive class", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-state")).toHaveClass(
+      "sm:items-center"
+    );
+  });
+
+  it("empty-state wrapper has 'sm:justify-between' responsive class", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-state")).toHaveClass(
+      "sm:justify-between"
+    );
+  });
+
+  it("badge has 'rounded-full' class", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-badge")).toHaveClass(
+      "rounded-full"
+    );
+  });
+
+  it("badge has 'border' class", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-badge")).toHaveClass(
+      "border"
+    );
+  });
+
+  it("badge has 'bg-surface-field' design token", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-badge")).toHaveClass(
+      "bg-surface-field"
+    );
+  });
+
+  it("badge has 'text-text-muted' design token", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-badge")).toHaveClass(
+      "text-text-muted"
+    );
+  });
+
+  it("empty-state wrapper has 'animate-fade-in' animation class", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-state")).toHaveClass(
+      "animate-fade-in"
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Confirmation body — valid milestoneIndex
+// ---------------------------------------------------------------------------
+
+describe("DisputeRaiseModal — confirmation body rendering", () => {
+  it("renders the confirmation body when milestoneIndex is 0", () => {
+    renderModal({ milestoneIndex: 0 });
+    expect(screen.getByTestId("dispute-modal-body")).toBeInTheDocument();
+  });
+
+  it("renders the confirmation body when milestoneIndex is 3", () => {
+    renderModal({ milestoneIndex: 3 });
+    expect(screen.getByTestId("dispute-modal-body")).toBeInTheDocument();
+  });
+
+  it("renders the warning alert banner", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-warning")).toBeInTheDocument();
+  });
+
+  it("renders the details row", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-details")).toBeInTheDocument();
+  });
+
+  it("renders the milestone label 'Milestone 1' for index 0", () => {
+    renderModal({ milestoneIndex: 0 });
+    expect(
+      screen.getByTestId("dispute-modal-milestone-label")
+    ).toHaveTextContent("Milestone 1");
+  });
+
+  it("renders the milestone label 'Milestone 4' for index 3", () => {
+    renderModal({ milestoneIndex: 3 });
+    expect(
+      screen.getByTestId("dispute-modal-milestone-label")
+    ).toHaveTextContent("Milestone 4");
+  });
+
+  it("renders the description paragraph", () => {
+    renderModal();
+    expect(
+      screen.getByTestId("dispute-modal-description")
+    ).toBeInTheDocument();
+  });
+
+  it("description mentions arbiter review", () => {
+    renderModal();
+    expect(
+      screen.getByTestId("dispute-modal-description")
+    ).toHaveTextContent(/arbiter/i);
+  });
+
+  it("does NOT render the amount row when milestoneAmount is omitted", () => {
+    renderModal({ milestoneIndex: 0, milestoneAmount: undefined });
+    expect(
+      screen.queryByTestId("dispute-modal-amount")
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the amount when milestoneAmount is provided", () => {
+    renderModal({ milestoneIndex: 0, milestoneAmount: "25.0000000 XLM" });
+    expect(
+      screen.getByTestId("dispute-modal-amount")
+    ).toHaveTextContent("25.0000000 XLM");
+  });
+
+  it("does NOT render the amount row when milestoneAmount is null", () => {
+    renderModal({ milestoneIndex: 0, milestoneAmount: null });
+    expect(
+      screen.queryByTestId("dispute-modal-amount")
+    ).not.toBeInTheDocument();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. milestoneLabel helper
+// ---------------------------------------------------------------------------
+
+describe("milestoneLabel helper", () => {
+  it("returns 'Milestone 1' for index 0", () => {
+    expect(milestoneLabel(0)).toBe("Milestone 1");
+  });
+
+  it("returns 'Milestone 5' for index 4", () => {
+    expect(milestoneLabel(4)).toBe("Milestone 5");
+  });
+
+  it("returns 'Milestone 10' for index 9", () => {
+    expect(milestoneLabel(9)).toBe("Milestone 10");
+  });
+
+  it("returns 'this milestone' for null", () => {
+    expect(milestoneLabel(null)).toBe("this milestone");
+  });
+
+  it("returns 'this milestone' for NaN", () => {
+    expect(milestoneLabel(NaN)).toBe("this milestone");
+  });
+
+  it("returns 'this milestone' for Infinity", () => {
+    expect(milestoneLabel(Infinity)).toBe("this milestone");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. ARIA attribute compliance (#330)
+// ---------------------------------------------------------------------------
+
+describe("DisputeRaiseModal — ARIA attributes (#330)", () => {
+  // role="dialog" + aria-modal
+  it("backdrop has role='dialog'", () => {
+    renderModal();
+    expect(screen.getByRole("dialog")).toBeInTheDocument();
+  });
+
+  it("backdrop has aria-modal='true'", () => {
+    renderModal();
+    expect(screen.getByRole("dialog")).toHaveAttribute("aria-modal", "true");
+  });
+
+  // aria-labelledby
+  it("dialog has aria-labelledby pointing to the title element", () => {
+    renderModal();
+    const dialog = screen.getByRole("dialog");
+    expect(dialog).toHaveAttribute("aria-labelledby", "dispute-modal-title");
+  });
+
+  it("the title element has id='dispute-modal-title'", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-title")).toHaveAttribute(
+      "id",
+      "dispute-modal-title"
+    );
+  });
+
+  // aria-describedby
+  it("dialog has aria-describedby pointing to the description element when milestoneIndex is set", () => {
+    renderModal({ milestoneIndex: 0 });
+    expect(screen.getByRole("dialog")).toHaveAttribute(
+      "aria-describedby",
+      "dispute-modal-desc"
+    );
+  });
+
+  it("description element has id='dispute-modal-desc'", () => {
+    renderModal({ milestoneIndex: 0 });
+    expect(screen.getByTestId("dispute-modal-description")).toHaveAttribute(
+      "id",
+      "dispute-modal-desc"
+    );
+  });
+
+  it("dialog does NOT have aria-describedby when milestoneIndex is null", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByRole("dialog")).not.toHaveAttribute(
+      "aria-describedby"
+    );
+  });
+
+  // role="alert" on warning banner
+  it("warning banner has role='alert'", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-warning")).toHaveAttribute(
+      "role",
+      "alert"
+    );
+  });
+
+  // aria-live on empty state
+  it("empty-state wrapper has aria-live='polite'", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-state")).toHaveAttribute(
+      "aria-live",
+      "polite"
+    );
+  });
+
+  // aria-label on close button
+  it("close button has accessible aria-label", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-close")).toHaveAttribute(
+      "aria-label",
+      "Close dispute modal"
+    );
+  });
+
+  // aria-label on cancel button
+  it("Cancel button has aria-label", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveAttribute(
+      "aria-label",
+      "Cancel — do not raise dispute"
+    );
+  });
+
+  // aria-label on confirm button includes milestone name
+  it("Confirm button aria-label includes 'Milestone 1' for index 0", () => {
+    renderModal({ milestoneIndex: 0 });
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveAttribute(
+      "aria-label",
+      "Confirm raise dispute for Milestone 1"
+    );
+  });
+
+  it("Confirm button aria-label includes 'Milestone 3' for index 2", () => {
+    renderModal({ milestoneIndex: 2 });
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveAttribute(
+      "aria-label",
+      "Confirm raise dispute for Milestone 3"
+    );
+  });
+
+  it("Confirm button aria-label falls back to 'this milestone' when index is null", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveAttribute(
+      "aria-label",
+      "Confirm raise dispute for this milestone"
+    );
+  });
+
+  // aria-disabled — mirrors HTML disabled
+  it("Confirm has aria-disabled='true' when milestoneIndex is null", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveAttribute(
+      "aria-disabled",
+      "true"
+    );
+  });
+
+  it("Confirm has aria-disabled='false' when milestoneIndex is valid", () => {
+    renderModal({ milestoneIndex: 0 });
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveAttribute(
+      "aria-disabled",
+      "false"
+    );
+  });
+
+  it("aria-disabled on Confirm is consistent with HTML disabled (null index)", () => {
+    renderModal({ milestoneIndex: null });
+    const btn = screen.getByTestId("dispute-modal-confirm");
+    expect(btn).toBeDisabled();
+    expect(btn).toHaveAttribute("aria-disabled", "true");
+  });
+
+  it("aria-disabled on Confirm is consistent with HTML disabled (valid index)", () => {
+    renderModal({ milestoneIndex: 0 });
+    const btn = screen.getByTestId("dispute-modal-confirm");
+    expect(btn).not.toBeDisabled();
+    expect(btn).toHaveAttribute("aria-disabled", "false");
+  });
+
+  it("Cancel has aria-disabled='true' when isPending is true", () => {
+    renderModal({ isPending: true });
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveAttribute(
+      "aria-disabled",
+      "true"
+    );
+  });
+
+  it("Cancel has aria-disabled='false' when isPending is false", () => {
+    renderModal({ isPending: false });
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveAttribute(
+      "aria-disabled",
+      "false"
+    );
+  });
+
+  it("Confirm has aria-disabled='true' when isPending is true", () => {
+    renderModal({ milestoneIndex: 0, isPending: true });
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveAttribute(
+      "aria-disabled",
+      "true"
+    );
+  });
+
+  // empty-state badge aria-label
+  it("empty-state badge has aria-label='Status: no milestone selected'", () => {
+    renderModal({ milestoneIndex: null });
+    expect(screen.getByTestId("dispute-modal-empty-badge")).toHaveAttribute(
+      "aria-label",
+      "Status: no milestone selected"
+    );
+  });
+
+  // Escape key closes the modal
+  it("pressing Escape calls onClose", () => {
+    const onClose = vi.fn();
+    renderModal({ onClose });
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  // Backdrop click closes the modal
+  it("clicking the backdrop calls onClose", () => {
+    const onClose = vi.fn();
+    renderModal({ onClose });
+    // The backdrop is the dialog element itself
+    fireEvent.click(screen.getByTestId("dispute-raise-modal"));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("clicking inside the panel does NOT call onClose", () => {
+    const onClose = vi.fn();
+    renderModal({ onClose });
+    fireEvent.click(screen.getByTestId("dispute-raise-modal-content"));
+    expect(onClose).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 7. Interactive states / Tailwind classes (#331)
+// ---------------------------------------------------------------------------
+
+describe("DisputeRaiseModal — interactive state classes (#331)", () => {
+  // Confirm button — danger palette
+  it("Confirm button has 'bg-danger' token", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass("bg-danger");
+  });
+
+  it("Confirm button has 'hover:bg-danger-soft/20' hover class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "hover:bg-danger-soft/20"
+    );
+  });
+
+  it("Confirm button has 'hover:border-danger-soft' hover class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "hover:border-danger-soft"
+    );
+  });
+
+  it("Confirm button has 'focus-visible:ring-danger-soft' focus class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "focus-visible:ring-danger-soft"
+    );
+  });
+
+  it("Confirm button has 'focus-visible:ring-2' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "focus-visible:ring-2"
+    );
+  });
+
+  it("Confirm button has 'active:scale-[0.97]' press-feedback class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "active:scale-[0.97]"
+    );
+  });
+
+  it("Confirm button has 'disabled:opacity-40' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "disabled:opacity-40"
+    );
+  });
+
+  it("Confirm button has 'disabled:cursor-not-allowed' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "disabled:cursor-not-allowed"
+    );
+  });
+
+  it("Confirm button has 'transition-all' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "transition-all"
+    );
+  });
+
+  it("Confirm button has 'rounded-lg' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "rounded-lg"
+    );
+  });
+
+  it("Confirm button has 'focus-visible:outline-none' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "focus-visible:outline-none"
+    );
+  });
+
+  it("Confirm button has 'focus-visible:ring-offset-2' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "focus-visible:ring-offset-2"
+    );
+  });
+
+  it("Confirm button has 'focus-visible:ring-offset-surface-page' token", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveClass(
+      "focus-visible:ring-offset-surface-page"
+    );
+  });
+
+  // Cancel button — neutral palette
+  it("Cancel button has 'bg-surface-field' token", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveClass(
+      "bg-surface-field"
+    );
+  });
+
+  it("Cancel button has 'hover:bg-border-subtle' hover class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveClass(
+      "hover:bg-border-subtle"
+    );
+  });
+
+  it("Cancel button has 'hover:text-text-primary' hover class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveClass(
+      "hover:text-text-primary"
+    );
+  });
+
+  it("Cancel button has 'focus-visible:ring-accent-soft' focus class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveClass(
+      "focus-visible:ring-accent-soft"
+    );
+  });
+
+  it("Cancel button has 'active:scale-[0.97]' press-feedback class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveClass(
+      "active:scale-[0.97]"
+    );
+  });
+
+  it("Cancel button has 'disabled:opacity-40' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveClass(
+      "disabled:opacity-40"
+    );
+  });
+
+  it("Cancel button has 'disabled:cursor-not-allowed' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-cancel")).toHaveClass(
+      "disabled:cursor-not-allowed"
+    );
+  });
+
+  // Close button — hover and focus classes
+  it("close button has 'hover:text-text-primary' hover class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-close")).toHaveClass(
+      "hover:text-text-primary"
+    );
+  });
+
+  it("close button has 'focus-visible:ring-2' focus class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-close")).toHaveClass(
+      "focus-visible:ring-2"
+    );
+  });
+
+  it("close button has 'focus-visible:ring-accent-soft' focus class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-close")).toHaveClass(
+      "focus-visible:ring-accent-soft"
+    );
+  });
+
+  it("close button has 'disabled:opacity-40' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-close")).toHaveClass(
+      "disabled:opacity-40"
+    );
+  });
+
+  it("close button has 'transition-colors' class", () => {
+    renderModal();
+    expect(screen.getByTestId("dispute-modal-close")).toHaveClass(
+      "transition-colors"
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 8. Action button behaviour
+// ---------------------------------------------------------------------------
+
+describe("DisputeRaiseModal — action button behaviour", () => {
+  it("calls onConfirm when Confirm button is clicked", () => {
+    const onConfirm = vi.fn();
+    renderModal({ onConfirm });
+    fireEvent.click(screen.getByTestId("dispute-modal-confirm"));
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onClose when Cancel button is clicked", () => {
+    const onClose = vi.fn();
+    renderModal({ onClose });
+    fireEvent.click(screen.getByTestId("dispute-modal-cancel"));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onClose when close (✕) button is clicked", () => {
+    const onClose = vi.fn();
+    renderModal({ onClose });
+    fireEvent.click(screen.getByTestId("dispute-modal-close"));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT call onConfirm when Confirm button is disabled (null index)", () => {
+    const onConfirm = vi.fn();
+    renderModal({ milestoneIndex: null, onConfirm });
+    const btn = screen.getByTestId("dispute-modal-confirm");
+    expect(btn).toBeDisabled();
+    fireEvent.click(btn);
+    expect(onConfirm).not.toHaveBeenCalled();
+  });
+
+  it("disables both action buttons when isPending is true", () => {
+    renderModal({ isPending: true });
+    expect(screen.getByTestId("dispute-modal-confirm")).toBeDisabled();
+    expect(screen.getByTestId("dispute-modal-cancel")).toBeDisabled();
+  });
+
+  it("disables the close button when isPending is true", () => {
+    renderModal({ isPending: true });
+    expect(screen.getByTestId("dispute-modal-close")).toBeDisabled();
+  });
+
+  it("does NOT call onConfirm when isPending is true", () => {
+    const onConfirm = vi.fn();
+    renderModal({ isPending: true, onConfirm });
+    const btn = screen.getByTestId("dispute-modal-confirm");
+    expect(btn).toBeDisabled();
+    fireEvent.click(btn);
+    expect(onConfirm).not.toHaveBeenCalled();
+  });
+
+  it("does NOT call onClose when Cancel is disabled (isPending)", () => {
+    const onClose = vi.fn();
+    renderModal({ isPending: true, onClose });
+    const btn = screen.getByTestId("dispute-modal-cancel");
+    expect(btn).toBeDisabled();
+    fireEvent.click(btn);
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("shows 'Raising dispute…' label and spinner when isPending is true", () => {
+    renderModal({ isPending: true });
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveTextContent(
+      "Raising dispute…"
+    );
+    expect(screen.getByTestId("button-spinner")).toBeInTheDocument();
+  });
+
+  it("shows 'Raise Dispute' label when isPending is false", () => {
+    renderModal({ isPending: false });
+    expect(screen.getByTestId("dispute-modal-confirm")).toHaveTextContent(
+      "Raise Dispute"
+    );
+    expect(
+      screen.queryByTestId("button-spinner")
+    ).not.toBeInTheDocument();
+  });
+
+  it("Confirm is enabled when milestoneIndex is 0 and isPending is false", () => {
+    renderModal({ milestoneIndex: 0, isPending: false });
+    expect(screen.getByTestId("dispute-modal-confirm")).not.toBeDisabled();
+  });
+
+  it("Cancel is enabled when isPending is false", () => {
+    renderModal({ isPending: false });
+    expect(screen.getByTestId("dispute-modal-cancel")).not.toBeDisabled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 9. Amount display
+// ---------------------------------------------------------------------------
+
+describe("DisputeRaiseModal — milestone amount display", () => {
+  it("renders the amount with XLM suffix", () => {
+    renderModal({ milestoneIndex: 0, milestoneAmount: "10.5000000 XLM" });
+    expect(screen.getByTestId("dispute-modal-amount")).toHaveTextContent(
+      "10.5000000 XLM"
+    );
+  });
+
+  it("amount element has 'font-mono' class", () => {
+    renderModal({ milestoneIndex: 0, milestoneAmount: "5.0000000 XLM" });
+    expect(screen.getByTestId("dispute-modal-amount")).toHaveClass("font-mono");
+  });
+
+  it("does not render amount row when milestoneAmount is an empty string", () => {
+    renderModal({ milestoneIndex: 0, milestoneAmount: "" });
+    expect(
+      screen.queryByTestId("dispute-modal-amount")
+    ).not.toBeInTheDocument();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 10. TxStatusBanner visibility
+// ---------------------------------------------------------------------------
+
+describe("DisputeRaiseModal — TxStatusBanner visibility", () => {
+  it("does NOT render the status banner when disputeState is null", () => {
+    renderModal({ disputeState: null });
+    expect(
+      screen.queryByTestId("dispute-modal-status-banner")
+    ).not.toBeInTheDocument();
+  });
+
+  it("does NOT render the status banner when disputeState is idle", () => {
+    renderModal({ disputeState: idleState });
+    expect(
+      screen.queryByTestId("dispute-modal-status-banner")
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders the status banner when disputeState phase is 'building'", () => {
+    renderModal({ disputeState: buildingState });
+    expect(
+      screen.getByTestId("dispute-modal-status-banner")
+    ).toBeInTheDocument();
+  });
+
+  it("renders the status banner when disputeState phase is 'success'", () => {
+    renderModal({
+      disputeState: { phase: "success", error: null, txHash: "abc123" },
+    });
+    expect(
+      screen.getByTestId("dispute-modal-status-banner")
+    ).toBeInTheDocument();
+  });
+
+  it("status banner wrapper is not rendered when disputeState is omitted", () => {
+    renderModal({});
+    expect(
+      screen.queryByTestId("dispute-modal-status-banner")
+    ).not.toBeInTheDocument();
+  });
+});
diff --git a/app/components/DisputeRaiseModal.tsx b/app/components/DisputeRaiseModal.tsx
new file mode 100644
index 0000000..ae60dd7
--- /dev/null
+++ b/app/components/DisputeRaiseModal.tsx
@@ -0,0 +1,417 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import ButtonSpinner from "@/app/components/ButtonSpinner";
+import TxStatusBanner from "@/app/components/TxStatusBanner";
+import type { ActionState } from "@/app/hooks/useActionStates";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DisputeRaiseModalProps {
+  /** Whether the modal is currently visible. */
+  isOpen: boolean;
+  /** Called when the user requests the modal be closed (backdrop click, Escape, or Cancel). */
+  onClose: () => void;
+  /** Called when the user confirms they want to raise a dispute. */
+  onConfirm: () => void;
+  /**
+   * 0-based milestone index being disputed. When null the modal renders
+   * its empty-data placeholder instead of the confirmation body.
+   */
+  milestoneIndex: number | null;
+  /** Human-readable XLM amount for the milestone (e.g. "25.0000000 XLM"). */
+  milestoneAmount?: string | null;
+  /** Whether the raise-dispute transaction is currently in flight. */
+  isPending?: boolean;
+  /** Optional ActionState to drive the TxStatusBanner below the actions row. */
+  disputeState?: ActionState | null;
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Convert a 0-based index to a 1-based human-readable label. */
+export function milestoneLabel(index: number | null): string {
+  if (index === null || typeof index !== "number" || !isFinite(index)) {
+    return "this milestone";
+  }
+  return `Milestone ${index + 1}`;
+}
+
+// ---------------------------------------------------------------------------
+// Shared Tailwind class strings
+// ---------------------------------------------------------------------------
+
+/**
+ * Base button classes shared by both action buttons — mirrors the `baseBtn`
+ * string used throughout MilestoneCard and other interactive components.
+ */
+const baseBtn =
+  "text-sm px-4 py-2 rounded-lg transition-all whitespace-nowrap " +
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 " +
+  "focus-visible:ring-offset-surface-page " +
+  "disabled:opacity-40 disabled:cursor-not-allowed active:scale-[0.97]";
+
+// ---------------------------------------------------------------------------
+// Sub-components
+// ---------------------------------------------------------------------------
+
+/**
+ * EmptyStatePlaceholder — rendered when milestoneIndex is null.
+ *
+ * Provides a descriptive placeholder UI so the modal remains accessible and
+ * informative even when it is invoked without a valid target milestone.
+ */
+function EmptyStatePlaceholder() {
+  return (
+    <div
+      data-testid="dispute-modal-empty-state"
+      aria-live="polite"
+      className={
+        "flex flex-col sm:flex-row sm:items-center sm:justify-between " +
+        "gap-3 p-4 rounded-lg border border-border-subtle bg-surface-field " +
+        "animate-fade-in"
+      }
+    >
+      {/* Left — icon + text */}
+      <div className="flex items-start gap-3">
+        {/* Decorative warning icon */}
+        <span
+          aria-hidden="true"
+          className="mt-0.5 text-xl leading-none select-none"
+        >
+          ⚠️
+        </span>
+
+        <div className="flex flex-col gap-1">
+          <p
+            data-testid="dispute-modal-empty-heading"
+            className="text-sm font-semibold text-text-primary"
+          >
+            No milestone selected
+          </p>
+          <p
+            data-testid="dispute-modal-empty-description"
+            className="text-xs text-text-muted"
+          >
+            Select a milestone from your job dashboard before raising a
+            dispute. Only milestones in{" "}
+            <span className="font-medium text-text-secondary">Pending</span>{" "}
+            or{" "}
+            <span className="font-medium text-text-secondary">Delivered</span>{" "}
+            status can be disputed.
+          </p>
+        </div>
+      </div>
+
+      {/* Right — status badge */}
+      <span
+        data-testid="dispute-modal-empty-badge"
+        aria-label="Status: no milestone selected"
+        className={
+          "self-start sm:self-auto shrink-0 " +
+          "inline-flex items-center px-2.5 py-1 rounded-full border " +
+          "text-xs font-medium " +
+          "bg-surface-field text-text-muted border-border-subtle"
+        }
+      >
+        Waiting for selection
+      </span>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
+/**
+ * DisputeRaiseModal — confirmation modal for raising a milestone dispute.
+ *
+ * Accessibility:
+ *  - `role="dialog"` + `aria-modal="true"` on the backdrop
+ *  - `aria-labelledby` wired to the `<h2>` title
+ *  - `aria-describedby` wired to the body description paragraph
+ *  - Focus is trapped to the modal panel on open; returns on close
+ *  - Escape key closes the modal
+ *  - Backdrop click closes the modal (click outside panel)
+ *  - Confirm button: `aria-label` includes milestone name for screen readers
+ *  - All interactive elements carry `focus-visible` ring styles
+ *  - Empty-state container carries `aria-live="polite"` for dynamic updates
+ *
+ * Interactive states (#331):
+ *  - Buttons: hover colour shifts, `active:scale-[0.97]` press feedback
+ *  - Confirm: `hover:bg-danger-soft/20 focus-visible:ring-danger-soft`
+ *  - Cancel: `hover:bg-border-subtle focus-visible:ring-accent-soft`
+ *  - Close ✕: `hover:text-text-primary focus-visible:ring-accent-soft`
+ *  - Both buttons carry `disabled:opacity-40 disabled:cursor-not-allowed`
+ */
+export default function DisputeRaiseModal({
+  isOpen,
+  onClose,
+  onConfirm,
+  milestoneIndex,
+  milestoneAmount,
+  isPending = false,
+  disputeState = null,
+  className = "",
+}: DisputeRaiseModalProps) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const label = milestoneLabel(milestoneIndex);
+  const hasValidMilestone = milestoneIndex !== null;
+
+  // ── Focus management ────────────────────────────────────────────────────
+
+  // Trap focus inside the modal panel when it opens; restore on close.
+  useEffect(() => {
+    if (!isOpen) return;
+
+    // Move focus into the panel on open
+    const frame = requestAnimationFrame(() => {
+      panelRef.current?.focus();
+    });
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        onClose();
+      }
+
+      // Basic focus trap: cycle Tab/Shift+Tab within the panel
+      if (e.key !== "Tab") return;
+
+      const panel = panelRef.current;
+      if (!panel) return;
+
+      const focusable = Array.from(
+        panel.querySelectorAll<HTMLElement>(
+          'button:not([disabled]), [href], input:not([disabled]), ' +
+            'select:not([disabled]), textarea:not([disabled]), ' +
+            '[tabindex]:not([tabindex="-1"])'
+        )
+      );
+
+      if (focusable.length === 0) return;
+
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+
+      if (e.shiftKey) {
+        if (document.activeElement === first) {
+          e.preventDefault();
+          last.focus();
+        }
+      } else {
+        if (document.activeElement === last) {
+          e.preventDefault();
+          first.focus();
+        }
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+      cancelAnimationFrame(frame);
+    };
+  }, [isOpen, onClose]);
+
+  // Guard render
+  if (!isOpen) return null;
+
+  // ── IDs for aria wiring ──────────────────────────────────────────────────
+  const titleId = "dispute-modal-title";
+  const descId = "dispute-modal-desc";
+
+  return (
+    /* Backdrop */
+    <div
+      data-testid="dispute-raise-modal"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby={titleId}
+      aria-describedby={hasValidMilestone ? descId : undefined}
+      className={`fixed inset-0 z-50 flex items-center justify-center bg-black/60 ${className}`}
+      onClick={(e) => {
+        // Close when the user clicks the backdrop (outside the panel)
+        if (e.target === e.currentTarget) onClose();
+      }}
+    >
+      {/* Panel */}
+      <div
+        ref={panelRef}
+        data-testid="dispute-raise-modal-content"
+        tabIndex={-1}
+        className={
+          "relative bg-surface-card rounded-xl shadow-xl max-w-md w-full mx-4 p-6 " +
+          "focus:outline-none animate-fade-in"
+        }
+        // Stop clicks inside the panel from bubbling to the backdrop
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* ── Header ──────────────────────────────────────────────────── */}
+        <div className="flex items-center justify-between mb-5">
+          <h2
+            id={titleId}
+            data-testid="dispute-modal-title"
+            className="text-lg font-semibold text-text-primary"
+          >
+            Raise a Dispute
+          </h2>
+
+          <button
+            type="button"
+            data-testid="dispute-modal-close"
+            onClick={onClose}
+            disabled={isPending}
+            aria-label="Close dispute modal"
+            className={
+              "text-text-secondary transition-colors " +
+              "hover:text-text-primary " +
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-soft " +
+              "focus-visible:ring-offset-2 focus-visible:ring-offset-surface-page " +
+              "rounded-sm disabled:opacity-40 disabled:cursor-not-allowed"
+            }
+          >
+            ✕
+          </button>
+        </div>
+
+        {/* ── Body ────────────────────────────────────────────────────── */}
+        {hasValidMilestone ? (
+          <div
+            data-testid="dispute-modal-body"
+            className="flex flex-col gap-4"
+          >
+            {/* Warning banner */}
+            <div
+              role="alert"
+              data-testid="dispute-modal-warning"
+              className={
+                "flex items-start gap-3 px-4 py-3 rounded-lg border " +
+                "border-danger/40 bg-danger/10 animate-slide-in"
+              }
+            >
+              <span aria-hidden="true" className="mt-0.5 text-base leading-none select-none">
+                ⚠️
+              </span>
+              <p className="text-sm text-danger-soft">
+                Raising a dispute will flag{" "}
+                <span className="font-semibold">{label}</span> for arbiter
+                review. This action cannot be undone once submitted.
+              </p>
+            </div>
+
+            {/* Details row */}
+            <div
+              data-testid="dispute-modal-details"
+              className={
+                "flex flex-col gap-2 px-4 py-3 rounded-lg border " +
+                "border-border-subtle bg-surface-field"
+              }
+            >
+              <div className="flex items-center justify-between gap-4">
+                <span className="text-xs text-text-muted">Milestone</span>
+                <span
+                  data-testid="dispute-modal-milestone-label"
+                  className="text-sm font-medium text-text-primary"
+                >
+                  {label}
+                </span>
+              </div>
+
+              {milestoneAmount && (
+                <div className="flex items-center justify-between gap-4">
+                  <span className="text-xs text-text-muted">Amount at stake</span>
+                  <span
+                    data-testid="dispute-modal-amount"
+                    className="text-sm font-mono text-text-primary"
+                  >
+                    {milestoneAmount}
+                  </span>
+                </div>
+              )}
+            </div>
+
+            {/* Description — wired via aria-describedby */}
+            <p
+              id={descId}
+              data-testid="dispute-modal-description"
+              className="text-xs text-text-muted leading-relaxed"
+            >
+              An arbiter will review the dispute and decide whether to release
+              the funds to the freelancer or return them to you. Make sure you
+              have supporting evidence ready before proceeding.
+            </p>
+          </div>
+        ) : (
+          /* Empty / no-selection state (#333) */
+          <EmptyStatePlaceholder />
+        )}
+
+        {/* ── TxStatusBanner ──────────────────────────────────────────── */}
+        {disputeState && disputeState.phase !== "idle" && (
+          <div className="mt-4" data-testid="dispute-modal-status-banner">
+            <TxStatusBanner
+              state={disputeState}
+              successMessage="Dispute raised successfully. The arbiter has been notified."
+            />
+          </div>
+        )}
+
+        {/* ── Actions row ─────────────────────────────────────────────── */}
+        <div
+          data-testid="dispute-modal-actions"
+          className="flex flex-col-reverse sm:flex-row sm:justify-end gap-3 mt-6"
+        >
+          {/* Cancel */}
+          <button
+            type="button"
+            data-testid="dispute-modal-cancel"
+            onClick={onClose}
+            disabled={isPending}
+            aria-label="Cancel — do not raise dispute"
+            aria-disabled={isPending}
+            className={
+              `${baseBtn} ` +
+              "bg-surface-field text-text-secondary border border-border-subtle " +
+              "hover:bg-border-subtle hover:text-text-primary " +
+              "focus-visible:ring-accent-soft"
+            }
+          >
+            Cancel
+          </button>
+
+          {/* Confirm */}
+          <button
+            type="button"
+            data-testid="dispute-modal-confirm"
+            onClick={onConfirm}
+            disabled={isPending || !hasValidMilestone}
+            aria-label={`Confirm raise dispute for ${label}`}
+            aria-disabled={isPending || !hasValidMilestone}
+            className={
+              `${baseBtn} ` +
+              "bg-danger text-text-primary border border-danger " +
+              "hover:bg-danger-soft/20 hover:border-danger-soft " +
+              "focus-visible:ring-danger-soft"
+            }
+          >
+            {isPending ? (
+              <span className="flex items-center gap-2">
+                <ButtonSpinner />
+                Raising dispute…
+              </span>
+            ) : (
+              "Raise Dispute"
+            )}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}