From 84d46a7888bb72a7c477008401f026eeb597822d Mon Sep 17 00:00:00 2001
From: SundayEmmanualEkwe <emmalekwe0@gmail.com>
Date: Sat, 27 Jun 2026 13:29:34 +0100
Subject: [PATCH] feat(a11y): add opt-in backdrop-click cancel to ConfirmDialog

---
 TODO.md                                       | 17 ++++---
 src/components/ConfirmDialog.tsx              | 16 ++++++
 .../__tests__/ConfirmDialog.test.tsx          | 51 ++++++++++++++++++-
 3 files changed, 74 insertions(+), 10 deletions(-)

diff --git a/TODO.md b/TODO.md
index 289737e..20d1671 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,11 +1,12 @@
 # TODO
 
-- [x] Inspect existing numeric validation helper (`src/lib/validateNumber.ts`).
-- [x] Verify usage/edit/new pages already import and use the helper.
-- [ ] Update helper tests (`src/lib/__tests__/validateNumber.test.ts`) to cover required edge cases for both ranges.
-- [ ] Adjust `src/app/usage/page.test.tsx` to assert validation message is surfaced through `TextField` error UI for non-integer requests.
-- [ ] Update `README.md` with validation rule summary (price: >=0 int; requests: >=1 int).
-- [ ] Run `npm run lint`, `npm run typecheck`, `npm test`, `npm run test:coverage`.
-- [ ] Ensure coverage threshold (>=95%) for helper + changed pages.
-- [ ] Commit with message: `refactor(forms): extract shared numeric-field validation helper`.
+- [ ] Implement `dismissOnBackdrop?: boolean` prop and accessible backdrop click cancel in `src/components/ConfirmDialog.tsx` (guard clicks so only backdrop—not panel—cancels).
+- [ ] Update JSDoc documentation for the new prop.
+- [ ] Extend tests in `src/components/__tests__/ConfirmDialog.test.tsx`:
+  - [ ] backdrop click cancels only when enabled
+  - [ ] backdrop click does not cancel when prop is off
+  - [ ] clicks inside dialog panel do not cancel (when enabled)
+  - [ ] Escape handling remains unchanged
+- [ ] Run `npm test`, `npm run lint`, `npm run typecheck`, and `npm run build`.
+- [ ] Capture/record npm test output and add short a11y note in final summary.
 
diff --git a/src/components/ConfirmDialog.tsx b/src/components/ConfirmDialog.tsx
index 38ec955..c845d5c 100644
--- a/src/components/ConfirmDialog.tsx
+++ b/src/components/ConfirmDialog.tsx
@@ -14,6 +14,11 @@ type Props = {
   description?: ReactNode;
   confirmLabel?: string;
   cancelLabel?: string;
+  /**
+   * When true, clicking the backdrop (outside the dialog panel) calls `onCancel`.
+   * Escape and the Cancel button always dismiss the dialog.
+   */
+  dismissOnBackdrop?: boolean;
   onConfirm: () => void;
   onCancel: () => void;
 };
@@ -43,6 +48,7 @@ export function ConfirmDialog({
   description,
   confirmLabel = "Confirm",
   cancelLabel = "Cancel",
+  dismissOnBackdrop = false,
   onConfirm,
   onCancel,
 }: Props) {
@@ -122,6 +128,15 @@ export function ConfirmDialog({
     }
   };
 
+  const handleBackdropMouseDown = (event: React.MouseEvent<HTMLDivElement>) => {
+    if (!dismissOnBackdrop) return;
+
+    // Only dismiss when the user clicked directly on the backdrop, not on the dialog panel.
+    if (event.target !== event.currentTarget) return;
+
+    onCancel();
+  };
+
   if (!open) return null;
   return (
     <div
@@ -132,6 +147,7 @@ export function ConfirmDialog({
       aria-describedby={description ? descriptionId : undefined}
       tabIndex={-1}
       onKeyDown={handleKeyDown}
+      onMouseDown={handleBackdropMouseDown}
       className="fixed inset-0 z-40 flex items-center justify-center bg-black/40 p-4"
     >
       <div className="w-full max-w-sm rounded-lg bg-white p-6 shadow-xl dark:bg-zinc-900">
diff --git a/src/components/__tests__/ConfirmDialog.test.tsx b/src/components/__tests__/ConfirmDialog.test.tsx
index ffce313..e0aebc6 100644
--- a/src/components/__tests__/ConfirmDialog.test.tsx
+++ b/src/components/__tests__/ConfirmDialog.test.tsx
@@ -2,8 +2,14 @@ import { fireEvent, render, screen } from "@testing-library/react";
 import { useState } from "react";
 import { ConfirmDialog } from "../ConfirmDialog";
 
-function ConfirmDialogHarness() {
+function ConfirmDialogHarness({
+  dismissOnBackdrop = false,
+}: {
+  dismissOnBackdrop?: boolean;
+}) {
   const [open, setOpen] = useState(false);
+  const onCancel = () => setOpen(false);
+
   return (
     <>
       <button type="button" onClick={() => setOpen(true)}>
@@ -14,13 +20,15 @@ function ConfirmDialogHarness() {
         open={open}
         title="Delete project"
         description="This action cannot be undone."
+        dismissOnBackdrop={dismissOnBackdrop}
         onConfirm={jest.fn()}
-        onCancel={() => setOpen(false)}
+        onCancel={onCancel}
       />
     </>
   );
 }
 
+
 const openDialog = () => {
   const trigger = screen.getByRole("button", { name: /open dialog/i });
   trigger.focus();
@@ -217,4 +225,43 @@ describe("ConfirmDialog", () => {
     fireEvent.keyDown(dialog, { key: "Tab" });
     expect(cancelButton).toHaveFocus();
   });
+
+  it("does not cancel on backdrop click when dismissOnBackdrop is off", () => {
+    render(<ConfirmDialogHarness dismissOnBackdrop={false} />);
+
+    const { dialog, cancelButton } = openDialog();
+    const backdrop = dialog.parentElement as HTMLElement;
+
+    const onCancelSpy = jest.spyOn(cancelButton, "click");
+
+    fireEvent.mouseDown(backdrop);
+    expect(screen.getByRole("dialog", { name: /delete project/i })).toBeInTheDocument();
+
+    onCancelSpy.mockRestore();
+  });
+
+  it("cancels on backdrop click when dismissOnBackdrop is on", () => {
+    render(<ConfirmDialogHarness dismissOnBackdrop={true} />);
+
+    const { dialog } = openDialog();
+    const backdrop = dialog.parentElement as HTMLElement;
+
+    fireEvent.mouseDown(backdrop);
+
+    expect(screen.queryByRole("dialog", { name: /delete project/i })).not.toBeInTheDocument();
+  });
+
+  it("does not cancel when clicking inside the dialog panel", () => {
+    render(<ConfirmDialogHarness dismissOnBackdrop={true} />);
+
+    const { dialog, cancelButton } = openDialog();
+
+    fireEvent.mouseDown(cancelButton);
+
+    expect(screen.getByRole("dialog", { name: /delete project/i })).toBeInTheDocument();
+    // sanity: Cancel still works
+    fireEvent.click(cancelButton);
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
 });
+