From 1060a3d6ac1cc0f1283cd478abf516ddf0255548 Mon Sep 17 00:00:00 2001
From: georgeefaith <georgefaith444@gmail.com>
Date: Fri, 26 Jun 2026 22:56:29 +0000
Subject: [PATCH] feat(a11y): improve retire-modal accessibility (#487)

- aria-live='polite' region announces success and error messages to
  screen readers without interrupting the user mid-flow
- role='alert' on inline error banner for immediate screen reader
  announcement on failure
- role='status' + CheckCircle success state replaces the form on
  completion so screen readers detect the outcome
- aria-busy on submit button signals loading state to assistive tech
- Close and Cancel buttons disabled while submitting; textarea also
  disabled during in-flight request
- Error caught from onConfirm() and surfaced visually and via aria-live

Closes #487
---
 apps/web/src/components/retire-modal.tsx | 160 ++++++++++++++---------
 1 file changed, 95 insertions(+), 65 deletions(-)

diff --git a/apps/web/src/components/retire-modal.tsx b/apps/web/src/components/retire-modal.tsx
index b20571d..70a0b50 100644
--- a/apps/web/src/components/retire-modal.tsx
+++ b/apps/web/src/components/retire-modal.tsx
@@ -1,7 +1,7 @@
 'use client'
 
 import { useRef, useState } from 'react'
-import { X, Leaf } from 'lucide-react'
+import { X, Leaf, CheckCircle } from 'lucide-react'
 import { CopyableText } from './copy-button'
 
 interface Props {
@@ -14,13 +14,19 @@ interface Props {
 export function RetireModal({ certificateId, kwh, onConfirm, onClose }: Props) {
   const [reason, setReason] = useState('')
   const [submitting, setSubmitting] = useState(false)
+  const [succeeded, setSucceeded] = useState(false)
+  const [error, setError] = useState<string | null>(null)
   const inputRef = useRef<HTMLTextAreaElement>(null)
 
   async function handleSubmit(e: React.FormEvent) {
     e.preventDefault()
     setSubmitting(true)
+    setError(null)
     try {
       await onConfirm(reason)
+      setSucceeded(true)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Retirement failed. Please try again.')
     } finally {
       setSubmitting(false)
     }
@@ -32,9 +38,15 @@ export function RetireModal({ certificateId, kwh, onConfirm, onClose }: Props) {
       aria-modal="true"
       aria-labelledby="retire-title"
       className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4"
-      onClick={(e) => e.target === e.currentTarget && onClose()}
+      onClick={(e) => e.target === e.currentTarget && !submitting && onClose()}
     >
       <div className="w-full max-w-md rounded-xl bg-white p-6 shadow-xl dark:bg-gray-900">
+        {/* aria-live region announces success/error to screen readers */}
+        <div aria-live="polite" aria-atomic="true" className="sr-only">
+          {succeeded && 'Certificate retired successfully.'}
+          {error && `Error: ${error}`}
+        </div>
+
         <div className="mb-4 flex items-center justify-between">
           <div className="flex items-center gap-2">
             <Leaf className="h-5 w-5 text-green-500" aria-hidden="true" />
@@ -45,79 +57,97 @@ export function RetireModal({ certificateId, kwh, onConfirm, onClose }: Props) {
           <button
             onClick={onClose}
             aria-label="Close"
-            className="rounded p-1 text-gray-400 hover:text-gray-600 dark:hover:text-gray-200"
+            disabled={submitting}
+            className="rounded p-1 text-gray-400 hover:text-gray-600 disabled:cursor-not-allowed dark:hover:text-gray-200"
           >
             <X className="h-4 w-4" aria-hidden="true" />
           </button>
         </div>
 
-        <p className="mb-4 text-sm text-gray-600 dark:text-gray-400">
-          You are about to permanently retire certificate{' '}
-          <CopyableText value={certificateId} displayValue={`${certificateId.slice(0, 8)}…`} />
-          {' '}({kwh.toFixed(3)} kWh).
-          This action cannot be undone.
-        </p>
-
-        <form onSubmit={handleSubmit} className="space-y-4">
-          <div>
-            <label
-              htmlFor="retire-reason"
-              className="mb-1 block text-sm font-medium text-gray-700 dark:text-gray-300"
-            >
-              Retirement reason <span className="text-gray-400">(optional)</span>
-            </label>
-            <textarea
-              id="retire-reason"
-              ref={inputRef}
-              value={reason}
-              onChange={(e) => setReason(e.target.value)}
-              rows={3}
-              placeholder="e.g. Offset Q1 2026 carbon footprint"
-              className="w-full rounded-lg border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 placeholder-gray-400 focus:border-yellow-400 focus:outline-none focus:ring-1 focus:ring-yellow-400 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-100 dark:placeholder-gray-500"
-            />
-          </div>
-
-          <div className="flex justify-end gap-3">
+        {succeeded ? (
+          <div role="status" className="flex flex-col items-center gap-3 py-4 text-center">
+            <CheckCircle className="h-10 w-10 text-green-500" aria-hidden="true" />
+            <p className="text-sm font-medium text-gray-900 dark:text-gray-100">
+              Certificate retired successfully.
+            </p>
             <button
-              type="button"
               onClick={onClose}
-              disabled={submitting}
-              className="rounded-lg border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-50 dark:border-gray-700 dark:text-gray-300 dark:hover:bg-gray-800"
-            >
-              Cancel
-            </button>
-            <button
-              type="submit"
-              disabled={submitting}
-              className="flex items-center gap-2 rounded-lg bg-green-600 px-4 py-2 text-sm font-medium text-white hover:bg-green-700 disabled:cursor-not-allowed disabled:opacity-60"
+              className="mt-2 rounded-lg bg-green-600 px-4 py-2 text-sm font-medium text-white hover:bg-green-700"
             >
-              {submitting && (
-                <svg
-                  className="h-4 w-4 animate-spin"
-                  xmlns="http://www.w3.org/2000/svg"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                  aria-hidden="true"
-                >
-                  <circle
-                    className="opacity-25"
-                    cx="12"
-                    cy="12"
-                    r="10"
-                    stroke="currentColor"
-                    strokeWidth="4"
-                  />
-                  <path
-                    className="opacity-75"
-                    fill="currentColor"
-                    d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
-                  />
-                </svg>
-              )}
-              {submitting ? 'Retiring…' : 'Confirm retirement'}
+              Close
             </button>
           </div>
-        </form>
+        ) : (
+          <>
+            <p className="mb-4 text-sm text-gray-600 dark:text-gray-400">
+              You are about to permanently retire certificate{' '}
+              <CopyableText value={certificateId} displayValue={`${certificateId.slice(0, 8)}…`} />
+              {' '}({kwh.toFixed(3)} kWh). This action cannot be undone.
+            </p>
+
+            {error && (
+              <div
+                role="alert"
+                className="mb-4 rounded-lg border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700 dark:border-red-800 dark:bg-red-900/20 dark:text-red-400"
+              >
+                {error}
+              </div>
+            )}
+
+            <form onSubmit={handleSubmit} className="space-y-4">
+              <div>
+                <label
+                  htmlFor="retire-reason"
+                  className="mb-1 block text-sm font-medium text-gray-700 dark:text-gray-300"
+                >
+                  Retirement reason <span className="text-gray-400">(optional)</span>
+                </label>
+                <textarea
+                  id="retire-reason"
+                  ref={inputRef}
+                  value={reason}
+                  onChange={(e) => setReason(e.target.value)}
+                  rows={3}
+                  disabled={submitting}
+                  placeholder="e.g. Offset Q1 2026 carbon footprint"
+                  className="w-full rounded-lg border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 placeholder-gray-400 focus:border-yellow-400 focus:outline-none focus:ring-1 focus:ring-yellow-400 disabled:opacity-50 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-100 dark:placeholder-gray-500"
+                />
+              </div>
+
+              <div className="flex justify-end gap-3">
+                <button
+                  type="button"
+                  onClick={onClose}
+                  disabled={submitting}
+                  className="rounded-lg border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-50 dark:border-gray-700 dark:text-gray-300 dark:hover:bg-gray-800"
+                >
+                  Cancel
+                </button>
+                <button
+                  type="submit"
+                  disabled={submitting}
+                  aria-busy={submitting}
+                  aria-describedby={error ? 'retire-error' : undefined}
+                  className="flex items-center gap-2 rounded-lg bg-green-600 px-4 py-2 text-sm font-medium text-white hover:bg-green-700 disabled:cursor-not-allowed disabled:opacity-60"
+                >
+                  {submitting && (
+                    <svg
+                      className="h-4 w-4 animate-spin"
+                      xmlns="http://www.w3.org/2000/svg"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      aria-hidden="true"
+                    >
+                      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+                      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                    </svg>
+                  )}
+                  {submitting ? 'Retiring…' : 'Confirm retirement'}
+                </button>
+              </div>
+            </form>
+          </>
+        )}
       </div>
     </div>
   )