🎨 Palette: 비동기 작업 버튼에 aria-busy 속성 추가를 통한 접근성 개선

.jules/palette.md

@@ -13,3 +13,7 @@
 ## 2026-07-13 - Async Table Actions UX
 **Learning:** Adding explicit loading and disabled states to table action buttons that invoke asynchronous processes helps prevent redundant API calls and visually assures the user that their request is being handled.
 **Action:** Consistently apply `disabled` state and `Loading...` text changes to inline table action buttons linked to async workflows, and carefully preserve underlying DOM structures with `Array.from(btn.childNodes)` during the loading cycle to avoid rendering regressions.
+
+## 2026-07-18 - Async Loading States with aria-busy
+**Learning:** 비동기 작업 중 사용자에게 명확한 로딩 피드백을 제공하려면 버튼의 텍스트와 disabled 속성만 변경하는 것보다 \`aria-busy="true"\` 속성을 동적으로 추가 및 제거하는 것이 스크린 리더와 같은 보조 기술에 더 효과적입니다.
+**Action:** 항상 비동기 액션 실행 전 \`aria-busy\`를 설정하고 \`finally\` 블록에서 이를 제거하는 패턴을 적용해야 합니다.

src/main/resources/static/assets/viewer/demo.js

@@ -148,9 +148,11 @@ function renderHistory(history = loadHistory()) {
         const btn = e.currentTarget;
         const initialChildren = Array.from(btn.childNodes);
         btn.disabled = true;
+        btn.setAttribute("aria-busy", "true");
         btn.textContent = "Loading...";
         openJobDetail(job).finally(() => {
           btn.replaceChildren(...initialChildren);
+          btn.removeAttribute("aria-busy");
           btn.disabled = false;
         });
       }));
@@ -299,6 +301,7 @@ async function retryActiveJob() {
   const jobId = activeJobDetail.jobId;
   const initialChildren = Array.from(el.retryJobBtn.childNodes);
   el.retryJobBtn.disabled = true;
+  el.retryJobBtn.setAttribute("aria-busy", "true");
   el.retryJobBtn.textContent = "Retrying...";
   setStatus("Requesting operator retry...");
 
@@ -339,6 +342,7 @@ async function retryActiveJob() {
     setError("Network error while requesting retry. Retry when the service is reachable.");
   } finally {
     el.retryJobBtn.replaceChildren(...initialChildren);
+    el.retryJobBtn.removeAttribute("aria-busy");
     el.retryJobBtn.disabled = false;
   }
 }
@@ -414,6 +418,7 @@ async function refreshKpis() {
 async function refreshKpiEvidence() {
   const initialChildren = Array.from(el.refreshEvidenceBtn.childNodes);
   el.refreshEvidenceBtn.disabled = true;
+  el.refreshEvidenceBtn.setAttribute("aria-busy", "true");
   el.refreshEvidenceBtn.textContent = "Refreshing...";
 
   try {
@@ -428,13 +433,15 @@ async function refreshKpiEvidence() {
     el.kpiExportStatus.textContent = "Snapshot evidence is unavailable while the service is unreachable.";
   } finally {
     el.refreshEvidenceBtn.replaceChildren(...initialChildren);
+    el.refreshEvidenceBtn.removeAttribute("aria-busy");
     el.refreshEvidenceBtn.disabled = false;
   }
 }
 
 async function loadDemoData() {
   const initialChildren = Array.from(el.loadDemoDataBtn.childNodes);
   el.loadDemoDataBtn.disabled = true;
+  el.loadDemoDataBtn.setAttribute("aria-busy", "true");
   el.loadDemoDataBtn.textContent = "Loading...";
   setStatus("Loading seeded buyer-demo story...");
 
@@ -459,6 +466,7 @@ async function loadDemoData() {
     setError("Unable to load seeded demo story.");
   } finally {
     el.loadDemoDataBtn.replaceChildren(...initialChildren);
+    el.loadDemoDataBtn.removeAttribute("aria-busy");
     el.loadDemoDataBtn.disabled = false;
   }
 }
@@ -507,6 +515,7 @@ async function submitDocument(event) {
 
   const initialChildren = Array.from(el.submitBtn.childNodes);
   el.submitBtn.disabled = true;
+  el.submitBtn.setAttribute("aria-busy", "true");
   el.submitBtn.textContent = "Submitting...";
   setStatus("Submitting document...");
 
@@ -551,6 +560,7 @@ async function submitDocument(event) {
     setError("Network error while submitting. Retry when the service is reachable.");
   } finally {
     el.submitBtn.replaceChildren(...initialChildren);
+    el.submitBtn.removeAttribute("aria-busy");
     el.submitBtn.disabled = false;
   }
 }

src/test/java/com/clearfolio/viewer/controller/ViewerUiControllerTest.java

@@ -135,6 +135,7 @@ void demoScriptUsesExistingApiAndSessionHistory() throws Exception {
             assertTrue(script.contains("X-Clearfolio-Tenant-Id"));
             assertTrue(script.contains("X-Clearfolio-Permissions"));
             assertTrue(script.contains("deadLettered"));
+            assertTrue(script.contains("aria-busy"));
         }
     }