From 6929b06c66e5651de4ce02b6aa1fac7d17d66e7b Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Tue, 21 Jul 2026 21:36:58 +0000
Subject: [PATCH] =?UTF-8?q?feat(ui):=20=ED=85=8C=EC=9D=B4=EB=B8=94=20?=
 =?UTF-8?q?=EC=95=A1=EC=85=98=20=EB=B2=84=ED=8A=BC=EC=97=90=20=EC=BB=A8?=
 =?UTF-8?q?=ED=85=8D=EC=8A=A4=ED=8A=B8=20=EA=B8=B0=EB=B0=98=20ARIA=20?=
 =?UTF-8?q?=EB=A0=88=EC=9D=B4=EB=B8=94=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

반복되는 테이블 액션 버튼("Details", "Status JSON", "Open viewer")에 행(row) 컨텍스트(파일명)를 포함한 동적인 ARIA 레이블을 추가하여 스크린 리더 사용자의 접근성을 향상시켰습니다.
또한 로딩 상태 전환 시 기존 ARIA 레이블을 임시로 "Loading..."으로 덮어쓰고 복원하도록 개선하였습니다.
---
 .jules/palette.md                             |  4 ++++
 .../resources/static/assets/viewer/demo.js    | 20 ++++++++++++++-----
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/.jules/palette.md b/.jules/palette.md
index a34ea59b..b610cf08 100644
--- a/.jules/palette.md
+++ b/.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-21 - Context-specific ARIA labels for repetitive table actions
+**Learning:** Screen reader users struggle to understand repetitive action buttons or links (like "Details" or "Open viewer") in a data table because the label alone lacks row context.
+**Action:** Always provide dynamically generated, context-specific `aria-label` attributes (e.g., `aria-label="Details for example_document.pdf"`) that include row-specific identifiers when rendering table action buttons or links.
diff --git a/src/main/resources/static/assets/viewer/demo.js b/src/main/resources/static/assets/viewer/demo.js
index 51466a8b..678df06c 100644
--- a/src/main/resources/static/assets/viewer/demo.js
+++ b/src/main/resources/static/assets/viewer/demo.js
@@ -81,13 +81,16 @@ function updateJob(jobId, patch, { refreshKpisAfterUpdate = true } = {}) {
   }
 }
 
-function createLink(href, label) {
+function createLink(href, label, ariaLabel) {
   const link = document.createElement("a");
   link.href = href;
   link.textContent = label;
   link.className = "table-link";
   link.target = "_blank";
   link.rel = "noopener noreferrer";
+  if (ariaLabel) {
+    link.setAttribute("aria-label", ariaLabel);
+  }
   return link;
 }
 
@@ -110,12 +113,15 @@ async function openJsonDocument(url, title) {
     : "Unable to load JSON evidence with the current tenant claim.";
 }
 
-function createActionButton(label, onClick) {
+function createActionButton(label, onClick, ariaLabel) {
   const button = document.createElement("button");
   button.type = "button";
   button.textContent = label;
   button.className = "btn btn-secondary btn-compact";
   button.addEventListener("click", onClick);
+  if (ariaLabel) {
+    button.setAttribute("aria-label", ariaLabel);
+  }
   return button;
 }
 
@@ -143,23 +149,27 @@ function renderHistory(history = loadHistory()) {
     submittedCell.textContent = job.submittedAt || "";
     actionsCell.className = "table-actions";
 
+    const rowFileName = job.fileName || "Document";
     if (job.statusUrl) {
       actionsCell.appendChild(createActionButton("Details", (e) => {
         const btn = e.currentTarget;
         const initialChildren = Array.from(btn.childNodes);
+        const originalAriaLabel = btn.getAttribute("aria-label");
         btn.disabled = true;
         btn.textContent = "Loading...";
+        btn.setAttribute("aria-label", "Loading...");
         openJobDetail(job).finally(() => {
           btn.replaceChildren(...initialChildren);
           btn.disabled = false;
+          if (originalAriaLabel) btn.setAttribute("aria-label", originalAriaLabel);
         });
-      }));
+      }, `Details for ${rowFileName}`));
       actionsCell.appendChild(createActionButton("Status JSON", () => {
         void openJsonDocument(job.statusUrl, "Clearfolio status JSON");
-      }));
+      }, `Status JSON for ${rowFileName}`));
     }
     if (job.jobId) {
-      actionsCell.appendChild(createLink(`/viewer/${encodeURIComponent(job.jobId)}`, "Open viewer"));
+      actionsCell.appendChild(createLink(`/viewer/${encodeURIComponent(job.jobId)}`, "Open viewer", `Open viewer for ${rowFileName}`));
     }
 
     row.append(fileCell, statusCell, submittedCell, actionsCell);